ratatui_ruby 0.3.1 → 0.5.0

data/doc/contributors/developing_examples.md

@@ -0,0 +1,261 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Developing Examples
+
+Guidelines for creating and testing examples in the `examples/` directory.
+
+## Example Structure
+
+Every interactive example should follow this pattern, living in its own directory:
+
+`examples/my_example/app.rb`:
+```ruby
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+
+class MyExampleApp
+  def initialize
+    # Initialize state (styles must be initialized in run when @tui is available)
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui  # Store for use in private methods
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private
+
+  def render
+    @tui.draw do |frame|
+      # 1. Split layout using Session helpers
+      areas = @tui.layout_split(frame.area, constraints: [@tui.constraint_fill(1)])
+      # 2. Create and render widgets
+      widget = @tui.paragraph(text: "Hello", block: @tui.block(borders: [:all]))
+      frame.render_widget(widget, areas[0])
+    end
+  end
+
+  def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" }
+      :quit
+    in { type: :key, code: code }
+      # Handle other keys
+    else
+      # Ignore unhandled events
+    end
+  end
+end
+
+MyExampleApp.new.run if __FILE__ == $PROGRAM_NAME
+```
+
+### Naming Convention (Required)
+
+Example directories **must** follow a prefixing convention to categorize them alphabetically:
+- `app_`: Application showcases (e.g., `app_analytics`). Class name: `AppAnalytics`.
+- `widget_`: Widget-focused demonstrations (e.g., `widget_gauge_demo`). Class name: `WidgetGaugeDemo`.
+- `verify_`: Documentation verification examples (e.g., `verify_readme_usage`). Class name: `VerifyReadmeUsage`.
+
+The directory and class names must match (snake_case directory maps to PascalCase class).
+
+This convention enables the `terminal_preview:update` rake task to automatically capture terminal output for all examples without maintaining a manual registry.
+
+### Terminal Size Constraint
+
+All interactive examples must fit within an **80×24 terminal** (standard VT100 dimensions). This ensures:
+- Examples work on minimal terminal configurations
+- Tests can use the default `with_test_terminal` size (80x24)
+- Examples remain discoverable and self-documenting through visible hotkey help
+
+**Layout pattern for 80×24:**
+- **Bottom control panel:** Allocate ~5-7 lines at bottom for a full-width control block with hotkey documentation. Style hotkeys with **bold and underline** to make them discoverable. Use double-space or pipe separators to compress multiple controls per line. This keeps all UI text at full readability while maximizing space for the main content area.
+
+**Best practices:**
+- Use descriptive names (e.g., "Yellow on Black" not "Yellow") so controls are self-documenting and discoverable.
+- **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:
+
+`examples/my_example/app.rbs`:
+```rbs
+class MyExampleApp
+  # @public
+  def self.new: () -> MyExampleApp
+
+  # @public
+  def run: () -> void
+end
+```
+
+### 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.
+
+2. **Use `RatatuiRuby.run` for terminal management.** Never call `init_terminal` or `restore_terminal` directly. The `run` block handles terminal setup/teardown automatically and safely, even if an exception occurs.
+
+3. **Use the Session API (`tui`) for cleaner code.** Accept the `tui` block parameter from `RatatuiRuby.run` and use it throughout your app:
+   - `@tui.draw { |frame| ... }` instead of `RatatuiRuby.draw`
+   - `@tui.poll_event` instead of `RatatuiRuby.poll_event`
+   - `@tui.style(...)` instead of `RatatuiRuby::Style.new(...)`
+   - `@tui.paragraph(...)` instead of `RatatuiRuby::Paragraph.new(...)`
+   - `@tui.block(...)` instead of `RatatuiRuby::Block.new(...)`
+   - `@tui.layout_split(...)` instead of `RatatuiRuby::Layout.split(...)`
+   - `@tui.constraint_fill(...)` instead of `RatatuiRuby::Constraint.fill(...)`
+   - `@tui.text_line(...)` instead of `RatatuiRuby::Text::Line.new(...)`
+   - `@tui.text_span(...)` instead of `RatatuiRuby::Text::Span.new(...)`
+
+4. **Event handling must include a catch-all pattern.** When using pattern matching in `handle_input`, always include an `else` clause at the end to catch unmatched events (mouse events, resize events, focus events, etc.). Without it, unmatched events will raise `NoMatchingPatternError`:
+
+   ```ruby
+   def handle_input
+     case @tui.poll_event
+     in { type: :key, code: "q" }
+       :quit
+     in { type: :mouse, kind: "down", x:, y: }
+       handle_click(x, y)
+     else
+       # 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
+    - Letter keys: Cycle through styles, modes, or variants. Prefer all lowercase keys to avoid confusion and simplify the UI description.
+    - Space: Toggle or select
+    - `q` or Ctrl+C: Quit
+
+5. **Naming Conventions for Controls**
+
+When documenting hotkeys and cycling options in the UI, use consistent naming:
+
+- **Parameter names:** Always match the actual Ruby parameter name. For example:
+  - Use "Scroll Padding" (not "Scroll Pad") for the `scroll_padding:` parameter
+  - Use "Highlight Style" (not "Highlight") for the `highlight_style:` parameter
+  - Use "Repeat Symbol" (not "Repeat") for the `repeat_highlight_symbol:` parameter
+  
+- **Display names for cycled values:** Create a `name` field in your options hash to keep display names paired with values. Initialize style arrays inside `run` when `@tui` is available:
+  ```ruby
+  # In run method, after @tui = tui:
+  @styles = [
+    { name: "Yellow Bold", style: @tui.style(fg: :yellow, modifiers: [:bold]) },
+    { name: "Blue on White", style: @tui.style(fg: :blue, bg: :white) }
+  ]
+  
+  # In controls: "h: Highlight Style (#{@styles[@style_index][:name]})"
+  # Outputs: "h: Highlight Style (Yellow Bold)"
+  ```
+
+This keeps the UI self-documenting and users can see exact parameter names when they read the hotkey help.
+
+7. **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:
+
+```ruby
+if @sidebar_rect&.contains?(event.x, event.y)
+  # Handle click
+end
+```
+
+## Testing Examples
+
+Example tests live alongside examples as `test_app.rb` files in the same directory.
+
+### Testing Pattern
+
+`examples/my_example/test_app.rb`:
+```ruby
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+require "ratatui_ruby/test_helper"
+require "minitest/autorun"
+require_relative "app"
+
+class TestMyExampleApp < Minitest::Test
+  include RatatuiRuby::TestHelper
+
+  def setup
+    @app = MyExampleApp.new
+  end
+
+  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"
+    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
+
+      content = buffer_content.join("\n")
+      assert_includes content, "Changed State"
+    end
+  end
+
+  def test_mouse_interaction
+    with_test_terminal do
+      # Click at (10, 5)
+      inject_click(x: 10, y: 5)
+      inject_key(:q)
+      @app.run
+
+      content = buffer_content.join("\n")
+      assert_includes content, "Clicked at (10, 5)"
+    end
+  end
+end
+```
+
+### Testing Guidelines
+
+1. **Inject events, observe buffer.** Tests should only interact through:
+   - `inject_key`, `inject_click`, `inject_event`, etc. for input
+   - `buffer_content` for output verification
+
+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.
+
+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.
+
+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"
+   ```
+
+5. **Test state cycling.** If an example cycles through options (styles, modes, etc.), test that pressing the key actually changes the rendered output.
+
+## Widget Attribute Cycling
+
+Examples should demonstrate widget configurability by allowing interactive cycling:
+
+| Widget | Attribute | Key Suggestion |
+|--------|-----------|----------------|
+| Tabs | highlight_style | Space |
+| Tabs | divider | d |
+| Tabs | style | s |
+| Block | border_type | Space |
+| Block | border_color | c |
+| List | highlight_style | Space |
+| Sparkline | direction | d |
+| Scrollbar | orientation | o |
+| 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/doc/contributors/documentation_style.md

@@ -0,0 +1,104 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Documentation Style Guide
+
+This project follows a strict and specific documentation style designed to be helpful, readable, and consistent. It combines the structural clarity of Christopher Alexander's Pattern Language with the prose style of William Zinsser's *On Writing Well* and the usability of the U.S. Federal Plain Language Guidelines.
+
+**All agents and contributors must adhere to these standards.**
+
+## 1. Core Philosophy
+
+*   **Context, Problem, Solution (Alexandrian Form):** Do not just say *what* a class does. Explain *why* it exists. Start with the context, state the problem (the pain point without this tool), and then present the class as the solution.
+*   **Prose Style (Zinsser/Klinkenborg):** Use short, punchy sentences. Use active voice. Cut unnecessary words. Avoid "allow," "enable," "provide," "support," "functionality," and "capability" where possible. Weak verbs hide the action. Strong verbs drive the sentence.
+*   **User-Centric (Plain Language):** Speak directly to the user ("You"). Don't abstract them away ("The developer"). Focus on their goals and how this tool helps them achieve those goals.
+*   **Tone (Supportive and Authoritative, not Hostile or Prescriptive):** Avoid "must," "requires," "need to," or "mandatory." These words sound bossy. Treat the user as a capable peer. Instead of "You must do X," use imperative "Do X" or cause-and-effect "X ensures Y."
+
+## 2. Class Documentation
+
+Every public class must begin with a **Context-Problem-Solution** narrative.
+
+### Structure
+
+1.  **Summary Line:** A single line explaining the class's role.
+2.  **Context (Narrative):** A short paragraph establishing the domain or situation.
+3.  **Problem (Narrative):** A sentence or two identifying the specific difficulty, complexity, or "pain" the user faces in this context without the widget.
+4.  **Solution (Narrative):** A sentence explaining how this widget solves that problem, often starting with "This widget..." or "Use it to...".
+5.  **Usage (Narrative):** A concrete "Use it to..." sentence listing common applications.
+6.  **Example:** A comprehensive, copy-pasteable code example using `=== Examples`. Provide **multiple** examples to cover different use cases (e.g., basic usage vs. advanced configuration).
+
+### Example
+
+**Bad (Generic/Descriptive):**
+```ruby
+# A widget for displaying list items.
+# It allows the user to select an item from an array of strings.
+# Supports scrolling and custom styling.
+```
+
+**Good (Alexandrian/Zinsser/Plain Language):**
+```ruby
+# Displays a selectable list of items.
+#
+# Users need to choose from options. Menus, file explorers, and selectors are everywhere.
+# Implementing navigation, highlighting, and scrolling state from scratch is tedious.
+#
+# This widget manages the list. It renders the items. It highlights the selection. It handles the scrolling window.
+#
+# Use it to build main menus, navigation sidebars, or logs.
+```
+
+## 3. Method and Attribute Documentation
+
+### Prose Style
+
+*   **Attributes:** Use concise noun phrases. Avoid "This attribute returns..." or "Getter for...".
+    *   *Bad:* "This is the width of the widget."
+    *   *Good:* "Width of the widget in cells."
+*   **Methods:** Use active, third-person present tense verbs.
+    *   *Bad:* "Will calculate the total."
+    *   *Good:* "Calculates the total."
+*   **Context:** For complex methods, you may use a condensed version of the Context-Problem-Solution pattern, but keep it brief.
+
+### Syntax Standards
+
+*   **Examples:** All public methods must include at least one usage example. Use `=== Example`.
+*   **Attributes:** Use `attr_reader` with documentation comments immediately preceding them.
+*   **Parameters:** Use strict RDoc definition lists `[name] description` for parameters in the `initialize` method.
+*   **Formatting:** Use `<tt>` tags for code literals, symbols, and values (e.g., `<tt>:vertical</tt>`).
+    *   Do **not** use backticks (\`) or markdown-style links `[text](url)`. RDoc does not render them correctly in all contexts.
+    *   Do **not** use smart quotes.
+
+### Example
+
+```ruby
+  # The styling to apply to the content.
+  attr_reader :style
+
+  # Creates a new List.
+  #
+  # [items] Array of Strings.
+  # [selected_index] Integer (nullable).
+  def initialize(items: [], selected_index: nil)
+    super
+  end
+```
+
+## 4. RDoc Specifics
+
+*   **No Endless Methods:** Do **not** use Ruby 3.0+ endless method definitions (`def foo = bar`). RDoc currently has a bug where it fails to correctly parse the end of the method, causing subsequent methods to be nested incorrectly in the documentation tree. Always use standard `def ... end` blocks.
+*   **No YARD:** Do not use `@param`, `@return`, or other YARD tags. Use standard RDoc formats.
+*   **Directives:** Use `:nodoc:` for private or internal methods that should not appear in the API docs.
+*   **Headings:** Use `===` for section headers like `=== Examples`.
+
+## 5. Checklist for Agents
+
+Before finalizing documentation, ask:
+1.  Did I explain the *problem* this code solves?
+2.  Are my sentences short and active? (Did I remove "allows the user to"?)
+3.  Is the code example valid and copy-pasteable?
+4.  Did I use `<tt>` for symbols and code values?
+5.  Did I document every attribute and parameter?