Update coverage badges [skip ci]

2026-08-08 20:35:15 +00:00
commit 735face593
312 changed files with 91102 additions and 0 deletions
@@ -0,0 +1,310 @@
+# PyWebLayout Examples
+
+This directory contains example scripts demonstrating the pyWebLayout library.
+
+## Getting Started Examples
+
+These examples demonstrate the core rendering capabilities of pyWebLayout:
+
+### 01. Simple Page Rendering
+**`01_simple_page_rendering.py`** - Introduction to the Page system
+
+```bash
+python 01_simple_page_rendering.py
+```
+
+Demonstrates:
+- Creating pages with different styles
+- Setting borders, padding, and backgrounds
+- Understanding page layout structure
+- Basic rendering to images
+
+![Page Rendering Example](../docs/images/example_01_page_rendering.png)
+
+### 02. Text and Layout
+**`02_text_and_layout.py`** - HTML parsing and text rendering
+
+```bash
+python 02_text_and_layout.py
+```
+
+Demonstrates:
+- Parsing HTML content
+- Text alignment options
+- Font sizes and styles
+- Document structure
+
+![Text and Layout Example](../docs/images/example_02_text_and_layout.png)
+
+### 03. Page Layouts
+**`03_page_layouts.py`** - Different page configurations
+
+```bash
+python 03_page_layouts.py
+```
+
+Demonstrates:
+- Various page sizes (portrait, landscape, square)
+- Different aspect ratios
+- Border and padding variations
+- Color schemes
+
+![Page Layouts Example](../docs/images/example_03_page_layouts.png)
+
+### 04. Table Rendering
+**`04_table_rendering.py`** - HTML table rendering with styling
+
+```bash
+python 04_table_rendering.py
+```
+
+Demonstrates:
+- Rendering HTML tables
+- Table headers and body rows
+- Cell borders and padding
+- Caption support
+- Custom table styling
+
+![Table Rendering Example](../docs/images/example_04_table_rendering.png)
+
+### 05. Tables with Images
+**`05_html_table_with_images.py`** - Tables containing images and mixed content
+
+```bash
+python 05_html_table_with_images.py
+```
+
+Demonstrates:
+- Creating tables programmatically
+- Adding images to table cells
+- Book catalog and product showcase tables
+- Mixed content (images and text) in cells
+- Using cover images from test data
+- HTML table parsing with `<img>` tags
+
+![Table with Images Example](../docs/images/example_05_html_table_with_images.png)
+
+### 06. Functional Elements (Interactive)
+**`06_functional_elements_demo.py`** - Interactive buttons and forms with callbacks
+
+```bash
+python 06_functional_elements_demo.py
+```
+
+Demonstrates:
+- Creating interactive buttons
+- Building forms with multiple field types
+- Post-layout callback binding
+- CallbackRegistry system for managing interactables
+- Accessing application state from callbacks
+- Batch callback operations
+- Simulating user interactions
+
+![Functional Elements Example](../docs/images/example_06_functional_elements.png)
+
+### 07. Button Pressed States (Interactive)
+**`07_pressed_state_demo.py`** - Visual feedback for button interactions
+
+```bash
+python 07_pressed_state_demo.py
+```
+
+Demonstrates:
+- Button pressed/released state management
+- Visual feedback timing (150ms press duration)
+- Automatic interaction handling with `InteractionHandler`
+- Manual state management for custom event loops
+- Dirty flag system for optimized re-rendering
+- State tracking with `InteractionStateManager`
+
+![Button Pressed State Animation](../docs/images/example_07_button_animation.gif)
+
+*Animated GIF showing button press sequence: initial → pressed → released*
+
+---
+
+## 🆕 New Examples (2024-11)
+
+These examples address critical coverage gaps and demonstrate advanced features:
+
+### 08. Bundled Fonts Showcase
+**`08_bundled_fonts_demo.py`** - Demonstration of all bundled fonts
+
+```bash
+python 08_bundled_fonts_demo.py
+```
+
+Demonstrates:
+- DejaVu Sans (Sans-serif)
+- DejaVu Serif (Serif)
+- DejaVu Sans Mono (Monospace)
+- All font variants: Regular, Bold, Italic, Bold Italic
+
+![Bundled Fonts Example](../docs/images/demo_08_bundled_fonts.png)
+
+### 08. Pagination with PageBreak ✅
+**`08_pagination_demo.py`** - Multi-page documents with explicit and automatic pagination
+
+```bash
+python 08_pagination_demo.py
+```
+
+**Test Coverage:** [tests/examples/test_08_pagination_demo.py](../tests/examples/test_08_pagination_demo.py) - 11 tests
+
+Demonstrates:
+- Using `PageBreak` to force content onto new pages
+- Multi-page document layout with explicit breaks
+- Automatic pagination when content overflows
+- Page numbering functionality
+- Document flow control
+- Combining pages into vertical strips
+
+**Coverage Impact:** Fills critical gap - PageBreak layouter had NO examples before this!
+
+![Pagination Example](../docs/images/example_08_pagination_explicit.png)
+
+### 09. Link Navigation (NEW) ✅
+**`09_link_navigation_demo.py`** - All link types and interactive navigation
+
+```bash
+python 09_link_navigation_demo.py
+```
+
+**Test Coverage:** [tests/examples/test_09_link_navigation_demo.py](../tests/examples/test_09_link_navigation_demo.py) - 10 tests
+
+Demonstrates:
+- **Internal links** - Document navigation (`#section1`, `#section2`)
+- **External links** - Web URLs (`https://example.com`)
+- **API links** - API endpoints (`/api/settings`, `/api/save`)
+- **Function links** - Direct function calls (`calculate()`, `process()`)
+- Link styling (underlined, color-coded by type)
+- Link callbacks and interactivity
+- Mixed text and link paragraphs
+
+**Coverage Impact:** Comprehensive - All 4 LinkType variations demonstrated!
+
+![Link Navigation Example](../docs/images/example_09_link_navigation.png)
+
+### 10. Comprehensive Forms (NEW) ✅
+**`10_forms_demo.py`** - All 14 form field types with validation
+
+```bash
+python 10_forms_demo.py
+```
+
+**Test Coverage:** [tests/examples/test_10_forms_demo.py](../tests/examples/test_10_forms_demo.py) - 9 tests
+
+Demonstrates all 14 FormFieldType variations:
+
+**Text-Based Fields:**
+- TEXT, EMAIL, PASSWORD, URL, TEXTAREA
+
+**Number/Date/Time Fields:**
+- NUMBER, DATE, TIME, RANGE, COLOR
+
+**Selection Fields:**
+- CHECKBOX, RADIO, SELECT, HIDDEN
+
+**Coverage Impact:** Complete - All 14 field types across 4 practical form examples!
+
+![Comprehensive Forms Example](../docs/images/example_10_forms.png)
+
+### 11. Table Text Wrapping (NEW) ✅
+**`11_table_text_wrapping_demo.py`** - Automatic line wrapping in table cells
+
+```bash
+python 11_table_text_wrapping_demo.py
+```
+
+**Simple Version:** `11b_simple_table_wrapping.py` - Quick demonstration
+
+Demonstrates:
+- **Automatic line wrapping** - Text wraps across multiple lines within cells
+- **Word hyphenation** - Long words are intelligently hyphenated
+- **Narrow columns** - Aggressive wrapping for tight spaces
+- **Mixed content** - Both short and long text in the same table
+- **Technical documentation** - API reference style tables
+- **News layouts** - Article-style table content
+
+**Implementation:** Uses the Line class from `pyWebLayout.concrete.text` with:
+- Word-by-word fitting with intelligent spacing
+- Pyphen-based dictionary hyphenation
+- Brute-force splitting for edge cases
+- Proper baseline alignment and metrics
+
+![Table Text Wrapping Example](../docs/images/example_11_table_text_wrapping.png)
+
+---
+
+## Running the Examples
+
+All examples can be run directly from the examples directory:
+
+```bash
+cd examples
+
+# Getting Started (01-07)
+python 01_simple_page_rendering.py    # Page layouts
+python 02_text_and_layout.py          # Text alignment with justified text
+python 03_page_layouts.py             # Various page sizes
+python 04_table_rendering.py          # Table styles
+python 05_html_table_with_images.py   # HTML tables with images
+python 06_functional_elements_demo.py # Interactive buttons and forms
+python 07_pressed_state_demo.py       # Button pressed states (generates GIF)
+
+# Advanced Features (08-11)
+python 08_bundled_fonts_demo.py       # Bundled font showcase
+python 08_pagination_demo.py          # Multi-page documents
+python 09_link_navigation_demo.py     # All link types
+python 10_forms_demo.py               # All form field types
+python 11_table_text_wrapping_demo.py # Table text wrapping
+python 11b_simple_table_wrapping.py   # Simple wrapping demo
+```
+
+Output images are saved to the `docs/images/` directory.
+
+## Recent Improvements
+
+### ✅ Justified Text Fix (2024-11-10)
+Lines using justified alignment now properly fill the entire width by:
+- Calculating base spacing and remainder pixels
+- Distributing remainder across word gaps to eliminate short lines
+- Removing max_spacing constraint for true justification
+
+**Affected examples:** 02, 11, 11b - All text now perfectly justified!
+
+### ✅ Animated Button States (2024-11-10)
+Example 07 now automatically generates an animated GIF showing button interactions:
+- Initial state (1000ms)
+- Pressed state (200ms)
+- Released state (500ms)
+- Loops continuously
+
+**Output:** `docs/images/example_07_button_animation.gif`
+
+### Running Tests
+
+All new examples (08, 09, 10) include comprehensive test coverage:
+
+```bash
+# Run all example tests
+python -m pytest tests/examples/ -v
+
+# Run specific test file
+python -m pytest tests/examples/test_08_pagination_demo.py -v
+python -m pytest tests/examples/test_09_link_navigation_demo.py -v
+python -m pytest tests/examples/test_10_forms_demo.py -v
+```
+
+**Total Test Coverage:** 30 tests (11 + 10 + 9), all passing ✅
+
+## Additional Documentation
+
+- `README_HTML_MULTIPAGE.md` - HTML multi-page rendering guide
+- `../ARCHITECTURE.md` - Detailed explanation of the Abstract/Concrete architecture
+- `../docs/images/README.md` - Visual documentation index with all examples
+- `../pyWebLayout/layout/README_EREADER_API.md` - EbookReader API reference
+
+## Debug/Development Scripts
+
+Low-level debug and rendering scripts have been moved to the `scripts/` directory.