ratatui_ruby 0.5.0 → 0.6.0

data/examples/app_color_picker/README.md

@@ -8,62 +8,102 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 This example demonstrates how to build a **Feature-Rich Interactive Application** using `ratatui_ruby`.
 
 It goes beyond simple widgets to show a complete, real-world architecture for handling:
--   **Complex State Management** (Input validation, undo/redo prep, clipboard interaction)
+-   **Complex State Management** (Input validation, clipboard interaction)
 -   **Mouse Interaction & Hit Testing**
 -   **Dynamic Layouts**
 -   **Modal Dialogs**
 
-## Architecture: The "Scene-Orchestrated" Pattern
+## Architecture: The "Proto-Kit" Pattern (Component-Based)
 
-This app uses a pattern we call **"Scene-Orchestrated MVC"**.
+This app uses a **Strict Component-Based Architecture** where every UI element encapsulates its own **Rendering**, **State**, and **Event Handling**.
 
-### 1. The App (Controller)
-The main `App` class (`app.rb`) acts as the Controller. It:
--   Holds the source of truth (the State).
--   Runs the Event Loop.
--   Routes input events to the appropriate handler.
--   Initializes the `Scene`.
+### The Component Contract
 
-### 2. The Scene (View / Layout Engine)
-The `Scene` class (`scene.rb`) acts as the primary View. Unlike simple examples where the render logic is in the `App` class, here the **Scene owns the Layout**.
--   **Composition**: It takes purely logical objects (`Palette`, `Input`) and decides how to present them.
--   **Hit Testing**: Crucially, the Scene **caches layout rectangles** (like `@export_area_rect`) during the render pass so the Controller knows *where* things are to handle clicks later.
+Every component implements this duck-type interface:
 
-### 3. The Logical Models
-The application logic is broken down into small, testable Plain Old Ruby Objects (POROs) that know nothing about the TUI:
--   **`Color`**: Handles hex parsing, contrast calculation, and transformations.
--   **`Palette`**: Generates color harmonies.
--   **`Input`**: Manages the text buffer and validation state.
--   **`Clipboard`**: Wraps system commands.
+```ruby
+# Renders the component into the given area
+# Caches `area` for hit testing
+def render(tui, frame, area)
+  @area = area
+  # ... render using frame.render_widget
+end
 
-This separation means your **business logic remains pure Ruby**, while the TUI layer focuses solely on presentation.
+# Processes events; returns a symbolic signal or nil
+def handle_event(event) -> Symbol | nil
+  # Returns :consumed, :submitted, :copy_requested, etc.
+end
+
+# Optional: time-based updates
+def tick
+end
+```
+
+### 1. The MainContainer (Orchestrator)
+
+The `MainContainer` class (`main_container.rb`) owns all child components and orchestrates the UI:
+
+-   **Layout Phase:** Calculates `Rect`s using `tui.layout_split`.
+-   **Delegation Phase:** Calls `child.render(tui, frame, child_area)` for each component.
+-   **Event Routing (Chain of Responsibility):** Delegates events front-to-back. The modal dialog gets priority when active.
+-   **Mediator Pattern:** Interprets symbolic signals (`:submitted`, `:copy_requested`) to coordinate cross-component effects.
+
+### 2. Self-Contained Components
+
+Each UI element is a self-contained component:
+
+-   **`Input`**: Text entry with validation. Returns `:submitted` when Enter is pressed.
+-   **`Palette`**: Displays color harmonies. Accepts `update_color` from the container.
+-   **`ExportPane`**: Shows HEX/RGB/HSL formats. Returns `:copy_requested` when clicked.
+-   **`Controls`**: Displays keyboard shortcuts. Has a `tick` lifecycle for clipboard feedback.
+-   **`CopyDialog`**: Modal confirmation dialog. Returns `:consumed` when handling events.
+
+### 3. The App (Minimal Runner)
+
+The `App` class (`app.rb`) is a thin runner:
+-   Creates the `MainContainer`.
+-   Runs the main loop: `tick` → `render` → `poll` → `handle_event`.
+-   Checks for quit events.
 
 ## Key Features Showcased
 
-### 🖱️ Mouse Support & Hit Testing
-See `Scene#export_rect` and `App#handle_main_input`.
-The app detects clicks on specific UI elements. This handles the problem: *"How do I know which button the user clicked?"*
--   **Solution**: The rendering layer (Scene) exposes the `Rect` of interactive areas. The event loop checks `rect.contains?(mouse_x, mouse_y)`.
+### 🖱️ Encapsulated Hit Testing
+
+Components cache their render area (`@area`) during `render`. In `handle_event`, they check `@area&.contains?(x, y)` to detect clicks. The container never calculates coordinates—hit testing is fully encapsulated.
+
+### 🔲 Modal Dialogs via Chain of Responsibility
+
+When `CopyDialog` is active, the `MainContainer` offers it events first. If it returns `:consumed`, event propagation stops. This creates modal behavior without explicit flags in the app.
+
+### 📡 Symbolic Signals (Mediator Pattern)
+
+Components return semantic symbols instead of just `:consumed`:
+-   `Input` returns `:submitted` when the user presses Enter.
+-   `ExportPane` returns `:copy_requested` when clicked.
+
+The `MainContainer` interprets these signals to coordinate cross-component communication:
+
+```ruby
+result = @input.handle_event(event)
+case result
+when :submitted
+  @palette.update_color(@input.parsed_color)
+  return :consumed
+end
+```
 
-### 🔲 Modal Dialogs
-See `CopyDialog`.
-The app implements a modal overlay that intercepts input.
--   **Pattern**: The `App` checks `if dialog.active?`. If true, it routes events *only* to the dialog, effectively "blocking" the main UI.
+### ⏱️ Lifecycle Hooks (`tick`)
 
-### 🎨 Advanced Styling & Layout
--   **Dynamic Constraints**: Layouts that adapt to content.
--   **Visual Feedback**:
-    -   Input fields turn red on error.
-    -   Clipboard messages fade out over time (`Clipboard#tick`).
-    -   Text colors automatically adjust for contrast (Black text on light backgrounds, White on dark).
+Components can have time-based updates. `Controls#tick` delegates to `Clipboard#tick` to decrement the feedback timer.
 
-## Problem Solving: What you can learn
+## Problem Solving: What You Can Learn
 
 Read this example if you are trying to solve:
-1.  **"How do I structure a larger app?"** -> Move render logic out of `App` and into a `Scene` or `View` class.
-2.  **"How do I handle mouse clicks?"** -> Cache the `Rect` during render.
-3.  **"How do I make a popup?"** -> Use a state flag (`active?`) to conditional render on top of everything else (z-ordering) and hijack the input loop.
-4.  **"How do I validate input?"** -> Wrap strings in an `Input` object that tracks both keypresses and validation errors.
+1.  **"How do I structure a larger app?"** → Use the Component Contract and a Container for orchestration.
+2.  **"How do I handle mouse clicks?"** → Cache `@area` during render; check `contains?` in `handle_event`.
+3.  **"How do I make a popup?"** → Use Chain of Responsibility: the active modal gets events first.
+4.  **"How do I coordinate between components?"** → Use symbolic signals and the Mediator pattern.
+5.  **"How do I validate input?"** → Encapsulate validation inside the `Input` component.
 
 ## Usage
 
@@ -79,16 +119,16 @@ ruby examples/app_color_picker/app.rb
 
 Complex applications require structured state habits. This Color Picker and the [App All Events](../app_all_events/README.md) example demonstrate two different approaches.
 
-### The Tool Approach (Color Picker)
+### The Tool Approach (Color Picker - Proto-Kit)
 
-Tools require interaction. Users click buttons and drag sliders. The Controller needs to know where components exist on screen. MVVM hides this layout data.
+Tools require interaction. Users click buttons and drag sliders. Components need to know where they exist on screen for hit testing. The Container orchestrates cross-component effects.
 
-This example uses a "Scene" pattern. The View exposes layout rectangles. The Controller uses these rectangles to handle mouse clicks.
+This example uses the **Proto-Kit (Component-Based)** pattern. Each component owns its own state, rendering, and event handling. The Container routes events and mediates communication.
 
 Use this pattern for forms, editors, and mouse-driven tools.
 
-### The Dashboard Approach (AppAllEvents)
+### The Dashboard Approach (AppAllEvents - Proto-TEA)
 
-Dashboards display data. They rarely require complex mouse interaction. Strict MVVM works best there. The View is a pure function. It accepts a `ViewState` and draws it. It ignores input. This simplifies testing.
+Dashboards display data. They rarely require complex mouse interaction. Proto-TEA (Model-View-Update) works best there. State is immutable. Logic is pure. Updates are predictable. This simplifies testing.
 
 Use that pattern for logs, monitors, and data viewers.

data/examples/app_color_picker/app.rb

@@ -7,11 +7,7 @@ $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 $LOAD_PATH.unshift File.expand_path(__dir__)
 
 require "ratatui_ruby"
-require_relative "input"
-require_relative "palette"
-require_relative "clipboard"
-require_relative "copy_dialog"
-require_relative "scene"
+require_relative "main_container"
 
 # A terminal-based color picker application.
 #
@@ -21,26 +17,27 @@ require_relative "scene"
 # This application solves the problem by providing an interactive interface. It parses hex strings,
 # generates palettes, and displays them visually in the terminal.
 #
-# Use it to experiment with color combinations and quickly find the right hex codes.
+# === Architecture
+#
+# This example uses the Proto-Kit (Component-Based) pattern:
+# - **Components**: Self-contained UI elements with `render`, `handle_event`, and optional `tick`
+# - **Container**: Owns layout, delegates to children, routes events via Chain of Responsibility
+# - **Mediator**: Container interprets symbolic signals (`:consumed`, `:submitted`) for cross-component effects
 #
 # === Examples
 #
 #   AppColorPicker.new.run
 #
 class AppColorPicker
-  # Creates a new <tt>AppColorPicker</tt> instance with a default palette and clipboard.
+  # Creates a new <tt>AppColorPicker</tt> instance.
   def initialize
-    @input = Input.new
-    @palette = Palette.new(@input.parse)
-    @clipboard = Clipboard.new
-    @dialog = CopyDialog.new(@clipboard)
-    @scene = nil
+    @container = nil
   end
 
   # Starts the terminal session and enters the main event loop.
   #
-  # This method initializes the terminal, renders the initial scene, and polls for
-  # input until the user quits.
+  # This method initializes the terminal, creates the MainContainer, and runs
+  # the event loop until the user quits.
   #
   # === Example
   #
@@ -49,62 +46,27 @@ class AppColorPicker
   #
   def run
     RatatuiRuby.run do |tui|
-      @scene = Scene.new(tui)
-      loop do
-        render(tui)
-        result = handle_input(tui)
-        break if result == :quit
-      end
-    end
-  end
-
-  private def render(tui)
-    @clipboard.tick
-    tui.draw do |frame|
-      @scene.render(frame, input: @input, palette: @palette, clipboard: @clipboard, dialog: @dialog)
-    end
-  end
+      @container = MainContainer.new(tui)
 
-  private def handle_input(tui)
-    event = tui.poll_event
-    @input.clear_error unless @dialog.active?
+      loop do
+        @container.tick
+        tui.draw { |frame| @container.render(tui, frame, frame.area) }
 
-    if @dialog.active?
-      handle_dialog_input(event)
-    else
-      handle_main_input(event)
-    end
-  end
+        event = tui.poll_event
+        break if quit_event?(event)
 
-  private def handle_dialog_input(event)
-    result = @dialog.handle_input(event)
-    case event
-    in { type: :key, code: "q" } | { type: :key, code: "esc" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      :quit
-    else
-      result
+        @container.handle_event(event)
+      end
     end
   end
 
-  private def handle_main_input(event)
+  private def quit_event?(event)
     case event
-    in { type: :key, code: "q" } | { type: :key, code: "esc" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      :quit
-    in { type: :key, code: "enter" }
-      @palette = Palette.new(@input.parse)
-    in { type: :key, code: "backspace" }
-      @input.delete_char
-    in { type: :paste, content: }
-      @input.set(content)
-      @palette = Palette.new(@input.parse)
-    in { type: :key, code: code }
-      @input.append_char(code)
-    in { type: :mouse, kind: "down", button: "left", x:, y: }
-      if @scene && @scene.export_rect&.contains?(x, y) && @palette.main
-        @dialog.open(@palette.main.hex)
-      end
+    in { type: :key, code: "q" } | { type: :key, code: "esc" } |
+       { type: :key, code: "c", modifiers: [/ctrl/] }
+      true
     else
-      nil
+      false
     end
   end
 end

data/examples/app_color_picker/controls.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# A display-only component showing keyboard shortcuts and clipboard feedback.
+#
+# Users need to know what keys are available. They also need feedback when
+# they copy a color. This component renders the controls section.
+#
+# === Component Contract
+#
+# - `render(tui, frame, area, clipboard:)`: Draws the controls; stores `area`
+# - `handle_event(event) -> nil`: Display-only, always returns nil
+# - `tick`: Delegates to clipboard for time-based feedback updates
+#
+# === Example
+#
+#   controls = Controls.new
+#   controls.render(tui, frame, area, clipboard: clipboard)
+#   controls.tick(clipboard)
+class Controls
+  def initialize
+    @area = nil
+    @hotkey_style = nil
+  end
+
+  # The cached render area.
+  attr_reader :area
+
+  # Renders the controls section into the given area.
+  #
+  # Shows keyboard shortcuts and clipboard feedback message if one is active.
+  #
+  # [tui] Session or TUI factory object
+  # [frame] Frame object from RatatuiRuby.draw block
+  # [area] Rect area to draw into
+  # [clipboard] Clipboard object for feedback message
+  #
+  # === Example
+  #
+  #   controls.render(tui, frame, control_area, clipboard: clipboard)
+  def render(tui, frame, area, clipboard:)
+    @area = area
+    @hotkey_style ||= tui.style(modifiers: [:bold, :underlined])
+    widget = build_widget(tui, clipboard)
+    frame.render_widget(widget, area)
+  end
+
+  # Display-only component; always returns nil.
+  def handle_event(_event)
+    nil
+  end
+
+  # Delegates tick to the clipboard for time-based updates.
+  #
+  # [clipboard] Clipboard object to tick
+  def tick(clipboard)
+    clipboard.tick
+  end
+
+  private def build_widget(tui, clipboard)
+    control_lines = [
+      tui.text_line(spans: [
+        tui.text_span(content: "a-z/0-9", style: @hotkey_style),
+        tui.text_span(content: ": Type  "),
+        tui.text_span(content: "enter", style: @hotkey_style),
+        tui.text_span(content: ": Parse  "),
+        tui.text_span(content: "bksp", style: @hotkey_style),
+        tui.text_span(content: ": Erase  "),
+        tui.text_span(content: "esc", style: @hotkey_style),
+        tui.text_span(content: ": Quit"),
+      ]),
+    ]
+
+    unless clipboard.message.empty?
+      control_lines << tui.text_line(spans: [
+        tui.text_span(content: clipboard.message, style: tui.style(fg: :green, modifiers: [:bold])),
+      ])
+    end
+
+    tui.block(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        tui.paragraph(text: control_lines),
+      ]
+    )
+  end
+end

data/examples/app_color_picker/copy_dialog.rb

@@ -5,39 +5,41 @@
 
 require_relative "clipboard"
 
-# A confirmation dialog for copying text to the clipboard.
+# A self-contained modal dialog component for copying text to the clipboard.
 #
 # Users click on content they want to copy. The app needs to confirm: "Are you
-# sure?" Managing dialog state (visible, selection, active), rendering the
-# dialog, and dispatching keyboard events manually is tedious.
+# sure?" This component owns dialog state, renders itself, and handles keyboard
+# input.
 #
-# This object owns dialog state and lifecycle. It renders itself. It responds
-# to keyboard input. It delegates clipboard operations to a Clipboard.
+# === Component Contract
 #
-# Use it to build copy-on-click interactions with user confirmation.
+# - `render(tui, frame, area)`: Draws the dialog; stores `area`
+# - `handle_event(event) -> Symbol | nil`: Returns `:consumed` when handled
+# - `open(text)`: Opens the dialog with the text to copy
+# - `close`: Closes the dialog
+# - `active?`: True if the dialog is visible
 #
 # === Example
 #
-#   clipboard = Clipboard.new
 #   dialog = CopyDialog.new(clipboard)
-#
-#   # Open the dialog
 #   dialog.open("#FF0000")
-#   dialog.active?  # => true
 #
-#   # Handle input
-#   result = dialog.handle_input(event)  # Routes to :copied or :cancelled
+#   result = dialog.handle_event(event)
+#   # result == :consumed when dialog handled the event
 #
-#   # Render
-#   widget = dialog.render(tui, area)
+#   dialog.render(tui, frame, center_area)
 class CopyDialog
   def initialize(clipboard)
     @clipboard = clipboard
     @text = ""
     @selected = :yes
     @active = false
+    @area = nil
   end
 
+  # The cached render area.
+  attr_reader :area
+
   # Opens the dialog with text to copy.
   #
   # Initializes selection to <tt>:yes</tt> and sets active to true.
@@ -48,7 +50,6 @@ class CopyDialog
   #
   #   dialog.open("#FF0000")
   #   dialog.active?  # => true
-  #   dialog.text     # => "#FF0000"
   def open(text)
     @text = text
     @selected = :yes
@@ -61,73 +62,68 @@ class CopyDialog
   end
 
   # True if the dialog is currently open and visible.
+  def active?
+    @active
+  end
+
+  # Renders the dialog into the given area.
+  #
+  # Shows the text to copy, Yes/No buttons with current selection highlighted,
+  # and keyboard instructions.
+  #
+  # [tui] Session or TUI factory object
+  # [frame] Frame object from RatatuiRuby.draw block
+  # [area] Rect area to draw into
   #
   # === Example
   #
-  #   dialog.open("text")
-  #   dialog.active?  # => true
-  #   dialog.close
-  #   dialog.active?  # => false
-  def active?
-    @active
+  #   dialog.render(tui, frame, center_area)
+  def render(tui, frame, area)
+    @area = area
+    widget = build_widget(tui)
+    frame.render_widget(widget, area)
   end
 
   # Processes a keyboard event and updates selection or closes the dialog.
   #
-  # Left/h moves selection to :yes. Right/l moves to :no. Enter confirms.
-  # Y/N hotkeys also work (Y copies immediately, N cancels). Returns nil for
-  # all handled events; does nothing if the dialog is inactive.
+  # Returns:
+  # - `:consumed` when the event was handled
+  # - `nil` when the event was ignored or dialog is inactive
   #
-  # [event] Hash event from RatatuiRuby.poll_event
+  # [event] Event from RatatuiRuby.poll_event
   #
   # === Example
   #
-  #   dialog.open("text")
-  #   dialog.handle_input({ type: :key, code: "left" })
-  #   dialog.handle_input({ type: :key, code: "enter" })
-  #   dialog.active?  # => false
-  def handle_input(event)
+  #   result = dialog.handle_event(event)
+  def handle_event(event)
     return nil unless @active
 
     case event
     in { type: :key, code: "left" } | { type: :key, code: "h" }
       @selected = :yes
-      nil
+      :consumed
     in { type: :key, code: "right" } | { type: :key, code: "l" }
       @selected = :no
-      nil
+      :consumed
     in { type: :key, code: "enter" }
       if @selected == :yes
         @clipboard.copy(@text)
       end
       @active = false
-      nil
+      :consumed
     in { type: :key, code: "y" }
       @clipboard.copy(@text)
       @active = false
-      nil
+      :consumed
     in { type: :key, code: "n" }
       @active = false
-      nil
+      :consumed
     else
       nil
     end
   end
 
-  # Renders the dialog widget for display in a TUI frame.
-  #
-  # Shows the text to copy, Yes/No buttons with current selection highlighted,
-  # and keyboard instructions. Renders only when active.
-  #
-  # [tui] Session or TUI factory object
-  # [area] Rect area for the dialog
-  #
-  # === Example
-  #
-  #   dialog.open("#FF0000")
-  #   widget = dialog.render(tui, center_area)
-  #   frame.render_widget(widget, center_area)
-  def render(tui, area)
+  private def build_widget(tui)
     yes_style = if @selected == :yes
       tui.style(bg: :cyan, fg: :black, modifiers: [:bold])
     else

data/examples/app_color_picker/export_pane.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# A self-contained component displaying export formats for a color.
+#
+# Users need to copy color values in different formats (HEX, RGB, HSL).
+# This component renders the export section and detects clicks on itself.
+#
+# === Component Contract
+#
+# - `render(tui, frame, area, palette:)`: Draws the export formats; stores `area` for hit testing
+# - `handle_event(event) -> Symbol | nil`: Returns `:copy_requested` when clicked
+#
+# === Example
+#
+#   export_pane = ExportPane.new
+#   export_pane.render(tui, frame, area, palette: palette)
+#
+#   result = export_pane.handle_event(event)
+#   if result == :copy_requested && palette.main
+#     dialog.open(palette.main.hex)
+#   end
+class ExportPane
+  def initialize
+    @area = nil
+  end
+
+  # The cached render area, for hit testing.
+  attr_reader :area
+
+  # Renders the export formats section into the given area.
+  #
+  # Shows HEX, RGB, and HSL values for the current color. If no color is set,
+  # displays a placeholder message.
+  #
+  # [tui] Session or TUI factory object
+  # [frame] Frame object from RatatuiRuby.draw block
+  # [area] Rect area to draw into
+  # [palette] Palette object containing the color to display
+  #
+  # === Example
+  #
+  #   export_pane.render(tui, frame, export_area, palette: palette)
+  def render(tui, frame, area, palette:)
+    @area = area
+    widget = build_widget(tui, palette)
+    frame.render_widget(widget, area)
+  end
+
+  # Processes a mouse event and returns a signal if clicked.
+  #
+  # Returns:
+  # - `:copy_requested` when the pane is clicked (caller should open copy dialog)
+  # - `nil` when the event was ignored or outside the area
+  #
+  # [event] Event from RatatuiRuby.poll_event
+  #
+  # === Example
+  #
+  #   result = export_pane.handle_event(event)
+  #   if result == :copy_requested
+  #     dialog.open(palette.main.hex)
+  #   end
+  def handle_event(event)
+    case event
+    in { type: :mouse, kind: "down", button: "left", x:, y: }
+      if @area&.contains?(x, y)
+        :copy_requested
+      end
+    else
+      nil
+    end
+  end
+
+  private def build_widget(tui, palette)
+    if palette.main.nil?
+      tui.block(
+        title: "Export Formats",
+        borders: [:all],
+        children: [
+          tui.paragraph(
+            text: tui.text_line(spans: [
+              tui.text_span(content: "Enter a color to see formats"),
+            ])
+          ),
+        ]
+      )
+    else
+      build_color_widget(tui, palette.main)
+    end
+  end
+
+  private def build_color_widget(tui, color)
+    hex = color.hex
+    rgb = color.rgb
+    hsl = color.hsl_string
+    text_color = color.contrasting_text_color
+    bg_style = tui.style(bg: hex, fg: text_color)
+
+    tui.block(
+      title: "Export Formats",
+      borders: [:all],
+      style: bg_style,
+      children: [
+        tui.paragraph(
+          text: [
+            tui.text_line(spans: [
+              tui.text_span(content: "HEX: ", style: bg_style),
+              tui.text_span(content: hex, style: tui.style(bg: hex, fg: text_color, modifiers: [:underlined])),
+            ]),
+            tui.text_line(spans: [
+              tui.text_span(content: "RGB: ", style: bg_style),
+              tui.text_span(content: rgb, style: tui.style(bg: hex, fg: text_color, modifiers: [:underlined])),
+            ]),
+            tui.text_line(spans: [
+              tui.text_span(content: "HSL: ", style: bg_style),
+              tui.text_span(content: hsl, style: tui.style(bg: hex, fg: text_color, modifiers: [:underlined])),
+            ]),
+          ]
+        ),
+      ]
+    )
+  end
+end