ratatui_ruby 0.5.0 → 0.6.0

data/doc/contributors/developing_examples.md

@@ -84,9 +84,11 @@ All interactive examples must fit within an **80×24 terminal** (standard VT100
 - **Style hotkeys visually:** Use `modifiers: [:bold, :underlined]` on hotkey letters to make them stand out from descriptions. Example: `i` (bold, underlined) followed by `Items`.
 - Test early by running the example at 80×24 and verifying all content is visible without wrapping, scrolling, or clipping.
 
-Every example must also have an RBS file documenting its public methods:
+## Type Signatures
 
-`examples/my_example/app.rbs`:
+Every example must also have an RBS file documenting its public methods. Type signatures live in a centralized location:
+
+`sig/examples/my_example/app.rbs`:
 ```rbs
 class MyExampleApp
   # @public
@@ -97,6 +99,27 @@ class MyExampleApp
 end
 ```
 
+## Directory Structure
+
+Examples are organized across three locations:
+
+```
+examples/
+  my_example/
+    app.rb              ← REQUIRED: The runnable example code
+    README.md           ← REQUIRED: Purpose, architecture, hotkeys, usage
+
+test/examples/
+  my_example/
+    test_app.rb         ← REQUIRED: Tests (centralized, not local to example)
+    snapshots/          ← Auto-created by assert_snapshot
+      initial_render.txt
+
+sig/examples/
+  my_example/
+    app.rbs             ← REQUIRED: Type signatures (centralized, not local to example)
+```
+
 ### Key Requirements
 
 1. **Only `run` should be public.** All other methods (`render`, `handle_input`, helper methods) must be private. This prevents tests from calling internal methods directly.
@@ -127,7 +150,6 @@ end
        # Ignore other events
      end
    end
-   ```
 
 5. **Use keyboard keys to cycle through widget attributes.** Users should be able to interactively explore all widget options. Common patterns:
     - Arrow keys: Navigate or adjust values
@@ -135,7 +157,17 @@ end
     - Space: Toggle or select
     - `q` or Ctrl+C: Quit
 
-5. **Naming Conventions for Controls**
+6. **All examples must include a README.md** explaining:
+   - What problem the example solves
+   - Architecture (if applicable)
+   - Hotkeys (if interactive): Document all keyboard/mouse controls
+   - Key concepts demonstrated
+   - Usage instructions
+   - Learning outcomes
+
+   See examples/app_color_picker/README.md and examples/app_all_events/README.md for patterns. Adhere to docs/contributors/documentation_style.md.
+
+7. **Naming Conventions for Controls**
 
 When documenting hotkeys and cycling options in the UI, use consistent naming:
 
@@ -158,7 +190,7 @@ When documenting hotkeys and cycling options in the UI, use consistent naming:
 
 This keeps the UI self-documenting and users can see exact parameter names when they read the hotkey help.
 
-7. **Hit Testing**
+8. **Hit Testing**
 
 Examples with mouse interaction should use the **Frame API**. By calling `@tui.layout_split` inside `@tui.draw`, you obtain the exact `Rect`s used for rendering. Store these rects in instance variables (e.g., `@sidebar_rect`) to use them in your `handle_input` method for hit testing:
 
@@ -170,11 +202,9 @@ end
 
 ## Testing Examples
 
-Example tests live alongside examples as `test_app.rb` files in the same directory.
-
-### Testing Pattern
+Example tests live in a centralized test tree:
 
-`examples/my_example/test_app.rb`:
+`test/examples/my_example/test_app.rb`:
 ```ruby
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
@@ -191,56 +221,75 @@ class TestMyExampleApp < Minitest::Test
 
   def test_initial_render
     with_test_terminal do
-      inject_key(:q)  # Queue quit event
-      @app.run        # Run the app loop
-      
-      content = buffer_content.join("\n")
-      assert_includes content, "Expected Text"
+      inject_key(:q)
+      @app.run
+      assert_snapshot("initial_render")
     end
   end
+end
+```
 
-  def test_keyboard_interaction
-    with_test_terminal do
-      inject_key("s")  # Press 's' to cycle something
-      inject_key(:q)   # Then quit
-      @app.run
+## Snapshot Testing Pattern (REQUIRED)
 
-      content = buffer_content.join("\n")
-      assert_includes content, "Changed State"
-    end
-  end
+All example tests MUST use snapshot testing via the `assert_snapshot` API, not manual content assertions.
 
-  def test_mouse_interaction
-    with_test_terminal do
-      # Click at (10, 5)
-      inject_click(x: 10, y: 5)
-      inject_key(:q)
-      @app.run
+### Why Snapshots
 
-      content = buffer_content.join("\n")
-      assert_includes content, "Clicked at (10, 5)"
-    end
+- **Exact verification:** Captures complete screen state, character-by-character
+- **Auto-update:** `UPDATE_SNAPSHOTS=1 bin/agent_rake test` regenerates all snapshots
+- **Auto-managed:** Snapshots live in `test/examples/{name}/snapshots/{test_name}.txt`
+- **Maintainable:** No tedious manual string checks
+- **Self-documenting:** Snapshots show exactly what output is expected
+
+### Basic Pattern
+
+```ruby
+def test_initial_render
+  with_test_terminal do
+    inject_key(:q)
+    @app.run
+    
+    assert_snapshot("initial_render")
   end
 end
 ```
 
-### Testing Guidelines
+Snapshot auto-saved to: `test/examples/widget_foo_demo/snapshots/initial_render.txt`
 
-1. **Inject events, observe buffer.** Tests should only interact through:
-   - `inject_key`, `inject_click`, `inject_event`, etc. for input
-   - `buffer_content` for output verification
+### With Normalization (for dynamic content)
 
-2. **Never call internal methods.** Don't call `render`, `handle_input`, `__send__`, or access instance variables with `instance_variable_get`. Tests verify behavior through the public `run` method.
+For examples with timestamps, random data, or other non-deterministic output:
 
-3. **Use `inject_key(:q)` to exit.** All examples should support quitting with `q`, so inject this as the final event to terminate the loop.
+```ruby
+private def assert_normalized_snapshot(snapshot_name)
+  assert_snapshot(snapshot_name) do |actual|
+    actual.map do |line|
+      line.gsub(/\d{2}:\d{2}:\d{2}/, "XX:XX:XX")  # Mask timestamps
+           .gsub(/Random ID: \d+/, "Random ID: XXX")  # Mask random values
+    end
+  end
+end
 
-4. **Assert and refute.** When testing which item was clicked/selected, also verify the opposite didn't happen:
-   ```ruby
-   assert_includes content, "Left Panel clicked"
-   refute_includes content, "Right Panel clicked"
-   ```
+def test_after_event
+  with_test_terminal do
+    inject_key("a")
+    inject_key(:q)
+    @app.run
+    
+    assert_normalized_snapshot("after_event")
+  end
+end
+```
+
+See `test/examples/app_all_events/test_app.rb` for a complete example.
 
-5. **Test state cycling.** If an example cycles through options (styles, modes, etc.), test that pressing the key actually changes the rendered output.
+### Regenerating Snapshots
+
+When UI changes are intentional, regenerate all snapshots:
+
+```bash
+UPDATE_SNAPSHOTS=1 bin/agent_rake test
+```
 
 ## Widget Attribute Cycling
 
@@ -259,3 +308,39 @@ Examples should demonstrate widget configurability by allowing interactive cycli
 | Scrollbar | theme | s |
 
 Display the current state in the UI (e.g., in a title or status bar or paragraph) so users can see what changed. Display the hotkey in the UI as well, so users can see how to change it; the hotkey should not disappear as app state changes.
+
+## Data Quality
+
+Examples must use **realistic, meaningful data**—not dummy placeholder text. This ensures examples:
+- Demonstrate the widget's real-world usage
+- Provide educational value to users reading the code
+- Look professional and polished
+
+### Guidelines
+
+**For small datasets (< 10 items):**
+Use hardcoded realistic data. Examples:
+- Geographic coordinates with city names (see `widget_map_demo/app.rb`)
+- Real product names or person names
+- Meaningful status values ("Completed", "Pending", "Failed")
+
+**For large datasets (≥ 10 items):**
+Use the [Faker](https://github.com/faker-ruby/faker) gem with **deterministic seeding** so data is consistent across runs:
+
+```ruby
+require "faker"
+
+# Seed Faker for reproducible output
+Faker::Config.random = Random.new(12345)
+
+# Generate realistic data
+users = Array.new(50) { Faker::Name.name }
+emails = Array.new(50) { Faker::Internet.email }
+```
+
+In tests, set the same seed before each test to ensure snapshot consistency.
+
+**Avoid:**
+- Repeated placeholder text like "Lorem ipsum" or "Background Layer" × 20
+- Generic numbered items like "Item 1", "Item 2" (unless the context demands it)
+- Nonsensical or visually jarring content

data/doc/contributors/examples_audit/p1_high.md

@@ -0,0 +1,21 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Priority 1: High (Polish & Ecosystem)
+
+Important for v1.0.0 quality and ecosystem goals. Not blocking release, but recommended before ship.
+
+---
+
+## 1. Ensure All Widgets Have Examples
+
+**Status:** Done
+
+Verified that all widget types shipped with ratatui_ruby have at least one example showing how to use them.
+
+**Action:**
+- [x] Check widget manifest against example inventory
+- [x] Create `widget_canvas_demo`, `widget_center_demo`, and `widget_overlay_demo`
+

data/doc/contributors/examples_audit/p2_moderate.md

@@ -0,0 +1,81 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Priority 2: Moderate (Quality Gates)
+
+These are v1.0.0 quality improvements that refine the example suite after P0 is complete. Not blocking, but recommended for maintainability and API consistency.
+
+---
+
+## 1. Add RDoc Cross-Links (Examples & Aliases)
+
+**Status:** Important for API discoverability — Documentation should link library and examples
+
+RDoc should cross-link between:
+- **Library classes/methods** ↔ **Examples that use them** (See also: examples/widget_foo_demo)
+- **Primary methods** ↔ **DWIM/TIMTOWTDI aliases** (See also: tui.foo_bar as alias for tui.foo(:bar))
+
+### Current Practice
+
+Done for:
+- `RatatuiRuby::Frame#set_cursor_position` ↔ `RatatuiRuby::Cursor` (cross-linking)
+- Limited elsewhere
+
+### Gaps
+
+- Most widget classes have no "See also: example_foo_demo" links
+- Aliases/TIMTOWTDI variants are not documented as such
+- Users can't easily find examples for a given class/method
+
+### Action
+
+1. Add `# See also: examples/widget_foo_demo/app.rb` to class/method RDoc
+2. Link DWIM methods to TIMTOWTDI variants: `# Also available as: tui.constraint_length (DWIM) vs tui.constraint(:length) (TIMTOWTDI)`
+3. Create consistent pattern across all public APIs in `lib/ratatui_ruby/`
+
+### Example Pattern
+
+```ruby
+# Renders text with styling.
+#
+# See also: examples/widget_paragraph_demo/app.rb (basic paragraph rendering)
+class Paragraph < Data.define(...)
+  # ...
+end
+
+# DWIM version of constraint creation
+# Also available as: constraint(type, value) for explicit control
+def constraint_length(length)
+  constraint(:length, length)
+end
+```
+
+---
+
+## Dependencies
+
+- P0 (developing_examples.md, README.md, tests) should be complete before consolidation
+
+---
+
+## 4. Enhance Widget Examples with Functional Context
+
+**Status:** Recommended — Move beyond "parameter playgrounds" to "real-world patterns"
+
+Current `widget_*` examples mostly focus on interactive parameter turning (changing colors, borders, etc.). While useful for API discovery, they don't show *how* to use the widget in a real application logic flow.
+
+### The Standard: widget_tabs_demo
+
+The `widget_tabs_demo` was enhanced to show **conditional rendering** of content based on the selected tab in git commit `38ceed39a011d557cc66e11a4598d3341dc7a0cc`. It doesn't just highlight the tab; it changes the screen content. This connects the widget (the tabs) to the problem it solves (view segregation).
+
+### Action
+
+Identify other widget examples that could benefit from this "functional context" treatment:
+
+-   **widget_popup_demo:** Show a multi-step modal flow (e.g., Confirm -> Success) rather than just a static overlay.
+-   **widget_list_demo:** Show a master-detail view where selecting a list item updates a detail pane.
+-   **widget_input_demo:** (If created) Show specific validation logic (email vs number).
+
+**Goal:** Every widget example should answer "How do I build a feature with this?" not just "What does this parameter do?"

data/doc/contributors/examples_audit.md

@@ -0,0 +1,41 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Examples Audit Report
+
+Audit of ratatui_ruby `examples/` directory for v1.0.0 readiness.
+
+## P0: Critical (Completed ✓)
+
+All P0 critical items have been completed:
+
+1. **Migrate Example Tests to Snapshot API** ✓
+   - Migrated 31 test files from manual `buffer_content` assertions to `assert_snapshot` and `assert_rich_snapshot`
+   - Added deterministic seeding for tests with random content (Faker, RATA_SEED)
+   - Generates `.txt` (plain) and `.ansi` (styled) snapshots for mutation-testing capability
+
+---
+
+## [P1: High (Polish)](./examples_audit/p1_high.md)
+
+1. **[Ensure All Widgets Have Examples](./examples_audit/p1_high.md#1-ensure-all-widgets-have-examples)** (Completeness)
+   - Check widget manifest against example inventory
+   - Create examples for any missing widgets
+
+---
+
+## [P2: Moderate (Quality)](./examples_audit/p2_moderate.md)
+
+1. **[Add RDoc Cross-Links](./examples_audit/p2_moderate.md#1-add-rdoc-cross-links-examples--aliases)** (Documentation discoverability)
+   - Link library classes/methods to examples
+   - Link DWIM/TIMTOWTDI aliases
+   - Create consistent pattern across public APIs
+
+---
+
+## Success Criteria for v1.0.0
+
+- ✓ All P0 items are fixed
+- ✓ All P1 items are mitigated (or time has run out)

data/doc/event_handling.md

@@ -10,7 +10,15 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 Events are retrieved using `RatatuiRuby.poll_event`. This method returns an instance of a subclass of `RatatuiRuby::Event` (e.g., `RatatuiRuby::Event::Key`, `RatatuiRuby::Event::Mouse`). When no event is available, it returns `RatatuiRuby::Event::None`—a [null object](https://martinfowler.com/eaaCatalog/specialCase.html) that safely responds to all event predicates with `false`.
 
-## 1. Symbol and String Comparison (Simplest)
+## 1. Blocking vs. Polling
+
+Most applications run in a loop (e.g., a game loop or UI loop). To prevent high CPU usage, the loop should wait briefly for input.
+
+*   **Default (Polling):** `RatatuiRuby.poll_event` (no args) waits for **0.016s** (approx 60 FPS). If no event occurs, it returns `RatatuiRuby::Event::None`. This keeps the application responsive.
+*   **Blocking:** `RatatuiRuby.poll_event(timeout: nil)` waits **forever** until an event occurs. Use this for scripts that only react to input and do not need to update the UI on a timer.
+*   **Non-Blocking:** `RatatuiRuby.poll_event(timeout: 0.0)` returns immediately.
+
+## 2. Symbol and String Comparison (Simplest)
 
 For simple key events, `RatatuiRuby::Event::Key` objects can be compared directly to Symbols or Strings. This is often the quickest way to get started.
 
@@ -36,7 +44,7 @@ if event == :enter
 end
 ```
 
-## 2. Predicate Methods (Intermediate)
+## 3. Predicate Methods (Intermediate)
 
 If you need more control or logic (e.g. `if/elsif`), or need to handle non-key events like Resize or Mouse, use the predicate methods.
 
@@ -82,7 +90,7 @@ if event.mouse? && event.scroll_up?
 end
 ```
 
-## 3. Pattern Matching (Powerful)
+## 4. Pattern Matching (Powerful)
 
 For complex applications, Ruby 3.0+ Pattern Matching with the `type:` discriminator is the most idiomatic and concise approach.