ratatui_ruby 0.5.0 → 0.6.0

data/examples/app_color_picker/input.rb

@@ -5,27 +5,30 @@
 
 require_relative "color"
 
-# Manages text input and color parsing with error feedback.
+# A self-contained text input component for color entry.
 #
 # Users type color values. They make mistakes—typos, invalid formats. The app
-# needs to validate their input and show helpful error messages. Manually
-# tracking input state, validation, and error messages across renders is
-# cumbersome and error-prone.
+# needs to validate their input and show helpful error messages.
 #
-# This object holds the current input string. It validates by parsing. It stores
-# errors and clears them when appropriate. It provides methods to manipulate
-# the input (append, delete).
+# This component encapsulates rendering, state, and event handling. It draws
+# itself into the provided area, caches that area for hit testing, and handles
+# keyboard events internally.
 #
-# Use it to build text input forms where validation feedback matters.
+# === Component Contract
+#
+# - `render(tui, frame, area)`: Draws the input field; stores `area` for hit testing
+# - `handle_event(event) -> Symbol | nil`: Returns `:consumed`, `:submitted`, or `nil`
 #
 # === Example
 #
 #   input = Input.new
-#   input.append_char("#")
-#   input.append_char("f")
-#   input.append_char("f")
-#   color = input.parse  # => Color or nil
-#   puts input.error     # => error message if parse failed
+#   input.render(tui, frame, area)
+#
+#   result = input.handle_event(event)
+#   case result
+#   when :submitted
+#     palette.update_color(input.parsed_color)
+#   end
 class Input
   PRINTABLE_PATTERN = /[\w#,().\s%]/
 
@@ -35,93 +38,112 @@ class Input
   def initialize(initial_value = "#F96302")
     @value = initial_value
     @error = ""
+    @parsed_color = nil
+    @area = nil
   end
 
   # Current input string.
-  #
-  # === Example
-  #
-  #   input = Input.new
-  #   input.value  # => "#F96302"
-  def value
-    @value
-  end
+  attr_reader :value
 
   # Error message from the last failed parse, or empty string.
-  #
-  # === Example
-  #
-  #   input.parse  # => nil (invalid)
-  #   input.error  # => "Invalid color format. Try: #ff0000, rgb(255,0,0), red"
-  def error
-    @error
-  end
+  attr_reader :error
+
+  # The last successfully parsed Color, or nil.
+  attr_reader :parsed_color
+
+  # The cached render area, for hit testing.
+  attr_reader :area
 
   # Clears the current error message.
   def clear_error
     @error = ""
   end
 
-  # Appends a character to the input if it matches the printable pattern.
+  # Renders the input widget into the given area.
+  #
+  # Caches `area` for hit testing. Shows the current input value and positions
+  # the terminal's blinking cursor at the end of the text using
+  # `frame.set_cursor_position`. Displays the error message in red if set.
+  #
+  # [tui] Session or TUI factory object
+  # [frame] Frame object from RatatuiRuby.draw block
+  # [area] Rect area to draw into
+  #
+  # === Example
+  #
+  #   input.render(tui, frame, input_area)
+  def render(tui, frame, area)
+    @area = area
+    widget = build_widget(tui)
+    frame.render_widget(widget, area)
+
+    # Position real blinking cursor at end of input text
+    cursor_x, cursor_y = cursor_position_in(area)
+    frame.set_cursor_position(cursor_x, cursor_y)
+  end
+
+  # Processes a keyboard event and updates internal state.
+  #
+  # Returns:
+  # - `:submitted` when Enter is pressed (caller should read `parsed_color`)
+  # - `:consumed` when the event was handled (typing, backspace)
+  # - `nil` when the event was ignored
   #
-  # Silently ignores non-printable characters. Valid characters include
-  # letters, digits, hash, comma, parentheses, dot, space, and percent.
+  # [event] Event from RatatuiRuby.poll_event
   #
-  # [char] String single character
-  def append_char(char)
+  # === Example
+  #
+  #   result = input.handle_event(event)
+  #   if result == :submitted
+  #     palette.update_color(input.parsed_color)
+  #   end
+  def handle_event(event)
+    case event
+    in { type: :key, code: "enter" }
+      parse
+      :submitted
+    in { type: :key, code: "backspace" }
+      delete_char
+      :consumed
+    in { type: :paste, content: }
+      set(content)
+      parse
+      :submitted
+    in { type: :key, code: code }
+      append_char(code)
+      :consumed
+    else
+      nil
+    end
+  end
+
+  private def append_char(char)
     @value += char if char.length == 1 && char.match?(PRINTABLE_PATTERN)
   end
 
-  # Removes the last character from the input.
-  def delete_char
+  private def delete_char
     @value = @value[0...-1]
   end
 
-  # Replaces the entire input string.
-  #
-  # [text] String new input value
-  def set(text)
+  private def set(text)
     @value = text
   end
 
-  # Parses the current input as a Color.
-  #
-  # Returns a Color if valid; nil otherwise. Sets the error message on failure.
-  # Clears the error message on success.
-  #
-  # === Example
-  #
-  #   input = Input.new("#FF0000")
-  #   color = input.parse  # => Color
-  #   input.error          # => ""
-  def parse
+  private def parse
     color = Color.parse(@value)
     if color
       clear_error
-      color
+      @parsed_color = color
     else
       @error = "Invalid color format. Try: #ff0000, rgb(255,0,0), red"
-      nil
+      @parsed_color = nil
     end
   end
 
-  # Renders the input widget for display in a TUI frame.
-  #
-  # Shows the current input value with a cursor. Displays the error message
-  # in red if one is set.
-  #
-  # [tui] Session or TUI factory object
-  #
-  # === Example
-  #
-  #   input = Input.new
-  #   widget = input.render(tui)
-  #   frame.render_widget(widget, area)
-  def render(tui)
+  private def build_widget(tui)
     input_lines = [
       tui.text_line(spans: [
         tui.text_span(content: @value),
-        tui.text_span(content: "_", style: tui.style(modifiers: [:reversed])),
       ]),
     ]
 
@@ -139,4 +161,14 @@ class Input
       ]
     )
   end
+
+  # Calculates cursor position within the input area.
+  #
+  # Accounts for block border (1 cell) and current text length.
+  private def cursor_position_in(area)
+    # Border takes 1 cell on left, cursor goes after last character
+    x = area.x + 1 + @value.length
+    y = area.y + 1 # First line inside border
+    [x, y]
+  end
 end

data/examples/app_color_picker/main_container.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "input"
+require_relative "palette"
+require_relative "export_pane"
+require_relative "controls"
+require_relative "clipboard"
+require_relative "copy_dialog"
+
+# The root container that owns all child components and orchestrates the UI.
+#
+# Building a complete color picker UI involves layout calculation, widget
+# composition, event routing, and cross-component communication. The Container
+# pattern centralizes this orchestration while keeping components decoupled.
+#
+# This container:
+# - **Layout Phase**: Calculates Rects using tui.layout_split
+# - **Delegation Phase**: Calls child.render(tui, frame, area) for each component
+# - **Event Routing (Chain of Responsibility)**: Delegates events front-to-back
+# - **Mediator Pattern**: Manages cross-component communication via symbolic signals
+#
+# === Component Contract
+#
+# - `render(tui, frame, area)`: Lays out and renders all children
+# - `handle_event(event) -> Symbol | nil`: Routes events to children
+# - `tick`: Delegates lifecycle updates (clipboard timer)
+#
+# === Example
+#
+#   container = MainContainer.new(tui)
+#   container.render(tui, frame, frame.area)
+#   result = container.handle_event(event)
+#   container.tick
+class MainContainer
+  def initialize(tui)
+    @tui = tui
+    @input = Input.new
+    @palette = Palette.new(@input.parsed_color)
+    @export_pane = ExportPane.new
+    @controls = Controls.new
+    @clipboard = Clipboard.new
+    @dialog = CopyDialog.new(@clipboard)
+
+    # Parse initial color
+    initial_result = simulate_initial_parse
+    @palette.update_color(initial_result) if initial_result
+  end
+
+  # Renders all child components into the given area.
+  #
+  # Calculates layout once per frame. Delegates rendering to each component.
+  # Renders the dialog overlay last for z-ordering.
+  #
+  # [tui] Session or TUI factory object
+  # [frame] Frame object from RatatuiRuby.draw block
+  # [area] Rect area to draw into
+  #
+  # === Example
+  #
+  #   tui.draw { |frame| container.render(tui, frame, frame.area) }
+  def render(tui, frame, area)
+    # Layout Phase: calculate all areas
+    input_area, rest = tui.layout_split(
+      area,
+      direction: :vertical,
+      constraints: [
+        tui.constraint_length(3),
+        tui.constraint_fill(1),
+      ]
+    )
+
+    color_area, control_area = tui.layout_split(
+      rest,
+      direction: :vertical,
+      constraints: [
+        tui.constraint_length(14),
+        tui.constraint_fill(1),
+      ]
+    )
+
+    harmony_area, export_area = tui.layout_split(
+      color_area,
+      direction: :vertical,
+      constraints: [
+        tui.constraint_length(7),
+        tui.constraint_fill(1),
+      ]
+    )
+
+    # Delegation Phase: render each component
+    @input.render(tui, frame, input_area)
+    @palette.render(tui, frame, harmony_area)
+    @export_pane.render(tui, frame, export_area, palette: @palette)
+    @controls.render(tui, frame, control_area, clipboard: @clipboard)
+
+    # Overlay Logic: dialog rendered last for z-ordering
+    if @dialog.active?
+      dialog_area = calculate_center_area(area, 40, 8)
+      frame.render_widget(tui.clear, area)
+      @dialog.render(tui, frame, dialog_area)
+    end
+  end
+
+  # Routes events to child components in visual order (front-to-back).
+  #
+  # Implements Chain of Responsibility:
+  # 1. If dialog is active, offer it the event first
+  # 2. Then Input, ExportPane (which may trigger dialog)
+  # 3. Mediator pattern: interprets symbolic signals for cross-component effects
+  #
+  # Returns:
+  # - `:consumed` when any component handled the event
+  # - `nil` when no component handled the event
+  #
+  # [event] Event from RatatuiRuby.poll_event
+  #
+  # === Example
+  #
+  #   result = container.handle_event(event)
+  def handle_event(event)
+    # Clear input error when not in dialog mode
+    @input.clear_error unless @dialog.active?
+
+    # Front-to-back: dialog has priority when active
+    if @dialog.active?
+      result = @dialog.handle_event(event)
+      return :consumed if result == :consumed
+    end
+
+    # Input component
+    result = @input.handle_event(event)
+    case result
+    when :submitted
+      # Mediator: sync Input -> Palette
+      @palette.update_color(@input.parsed_color)
+      return :consumed
+    when :consumed
+      return :consumed
+    end
+
+    # ExportPane: may request copy dialog
+    result = @export_pane.handle_event(event)
+    if result == :copy_requested && @palette.main
+      @dialog.open(@palette.main.hex)
+      return :consumed
+    end
+
+    # Palette and Controls are display-only
+    nil
+  end
+
+  # Delegates lifecycle tick to time-sensitive components.
+  #
+  # Currently handles clipboard feedback timer.
+  #
+  # === Example
+  #
+  #   container.tick
+  def tick
+    @controls.tick(@clipboard)
+  end
+
+  private def calculate_center_area(parent_area, width, height)
+    x = (parent_area.width - width) / 2
+    y = (parent_area.height - height) / 2
+    @tui.rect(x:, y:, width:, height:)
+  end
+
+  # Simulates the initial parse that happens when the app starts.
+  # Input is initialized with a default color, so we need to parse it.
+  private def simulate_initial_parse
+    require_relative "color"
+    Color.parse(@input.value)
+  end
+end

data/examples/app_color_picker/palette.rb

@@ -5,66 +5,95 @@
 
 require_relative "color"
 
-# Holds a primary color and its harmonies.
+# A self-contained component displaying a color palette with harmonies.
 #
-# Color pickers need to show related colors: shades, tints, complements. Building
-# these relationships repeatedly is redundant. Passing them individually through
-# rendering pipelines is awkward.
+# Color pickers need to show related colors: shades, tints, complements. This
+# component owns a primary color and renders its harmonies.
 #
-# This object owns a primary color and generates its harmonies on demand. It
-# provides accessor methods and rendering helpers.
+# === Component Contract
 #
-# Use it to organize color data for palette displays.
+# - `render(tui, frame, area)`: Draws the harmony blocks; stores `area`
+# - `handle_event(event) -> nil`: Display-only, always returns nil
+# - `update_color(color)`: Updates the primary color (called by MainContainer)
 #
 # === Example
 #
-#   color = Color.parse("#FF0000")
-#   palette = Palette.new(color)
-#   palette.main           # => Color
-#   palette.all            # => [Harmony, Harmony, ...]
-#   blocks = palette.as_blocks(tui)  # => [Block, Block, ...]
+#   palette = Palette.new
+#   palette.update_color(Color.parse("#FF0000"))
+#   palette.render(tui, frame, palette_area)
 class Palette
-  def initialize(primary_color)
+  def initialize(primary_color = nil)
     @primary = primary_color
+    @area = nil
   end
 
+  # The cached render area.
+  attr_reader :area
+
   # The primary (main) color, or nil if no color is set.
   #
   # === Example
   #
-  #   palette = Palette.new(color)
   #   palette.main.hex  # => "#FF0000"
   def main
     @primary
   end
 
-  # All harmonies: main, shade, tint, complement, split 1, split 2, split-complement.
+  # Updates the primary color.
   #
-  # Returns an empty array if no primary color is set.
+  # Called by the MainContainer when Input submits a new color.
   #
-  # === Example
+  # [color] Color object or nil
+  def update_color(color)
+    @primary = color
+  end
+
+  # All harmonies: main, shade, tint, complement, split 1, split 2, split-complement.
   #
-  #   palette = Palette.new(color)
-  #   palette.all.size  # => 7
+  # Returns an empty array if no primary color is set.
   def all
     return [] if @primary.nil?
 
     @primary.harmonies
   end
 
-  # Renders all harmonies as TUI Block widgets.
+  # Renders the palette into the given area.
   #
-  # Each harmony becomes a titled block showing its color swatch. Returns an empty
-  # array if no primary color is set.
+  # Shows all harmony blocks in a horizontal layout. 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
   #
   # === Example
   #
-  #   palette = Palette.new(color)
-  #   blocks = palette.as_blocks(tui)
-  #   # blocks[0] => Block titled "Main" with color swatch
-  def as_blocks(tui)
+  #   palette.render(tui, frame, palette_area)
+  def render(tui, frame, area)
+    @area = area
+    widget = build_widget(tui)
+    frame.render_widget(widget, area)
+  end
+
+  # Display-only component; always returns nil.
+  def handle_event(_event)
+    nil
+  end
+
+  private def build_widget(tui)
+    if @primary.nil?
+      tui.paragraph(text: "No color selected")
+    else
+      blocks = as_blocks(tui)
+      tui.layout(
+        direction: :horizontal,
+        constraints: Array.new(blocks.size) { tui.constraint_fill(1) },
+        children: blocks
+      )
+    end
+  end
+
+  private def as_blocks(tui)
     return [] if @primary.nil?
 
     all.map do |harmony|

data/examples/app_login_form/README.md

@@ -0,0 +1,47 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Login Form Example
+
+Demonstrates how to create a modal overlay for user input.
+
+Many applications need to block interaction with the main UI while collecting specific information, like a login prompt or confirmation dialog. Managing the z-index and input focus for these overlays can be tricky.
+
+This example solves this by using the `Overlay` widget to stack a centered popup on top of a base layer, conditionally rendering the popup based on state.
+
+## Features Demonstrated
+
+- **Overlays:** Stacking widgets on top of each other using `tui.overlay`.
+- **Centering:** Positioning a widget in the center of the screen using `tui.center`.
+- **State Management:** Switching between "Base" and "Popup" views.
+- **Input Handling:** Capturing text input and handling specific keys (Enter, Esc) to trigger state changes.
+- **Cursor Positioning:** Manually calculating cursor position within a `Paragraph`.
+
+## Hotkeys
+
+### Form Mode
+- **Text Input**: Type to enter username (supports all characters including 'q').
+- **Backspace**: Deletes the last character.
+- **Enter**: Submits the form and opens the success popup.
+- **Esc**: Quits the application.
+- **Ctrl+C**: Quits the application.
+
+### Popup Mode
+- **q**: Closes the popup and quits the application.
+- **Ctrl+C**: Quits the application.
+
+## Usage
+
+```bash
+ruby examples/app_login_form/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Create a modal dialog or popup.
+- Center a widget on the screen (vertically and horizontally).
+- Implement a simple text input field with cursor management.
+- layer widgets using the `Overlay` widget.

data/examples/app_login_form/app.rb

@@ -82,11 +82,10 @@ class AppLoginForm
 
   private def handle_input
     case @tui.poll_event
-    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      return :quit if @show_popup
-      nil
     in { type: :key, code: "c", modifiers: ["ctrl"] }
       :quit
+    in { type: :key, code: "q" } if @show_popup
+      :quit
     in { type: :key, code: "enter" }
       @show_popup ||= true
       nil

data/examples/app_stateful_interaction/README.md

@@ -0,0 +1,31 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Stateful Interaction Example
+
+This example demonstrates High-Fidelity Interaction using **Stateful Widget Rendering**.
+
+It showcases a "Database Viewer" layout where:
+1.  **Selection Persistence:** `ListState` and `TableState` objects persist across frames, maintaining selection without manual index tracking variables.
+2.  **Offset Read-back:** The application reads `state.offset` *after* rendering to know exactly which items were visible on screen.
+3.  **Mouse Interaction:** Using the read-back offset, we can calculate exactly which row was clicked, even when the specific item wasn't drawn at that absolute Y position due to scrolling.
+
+## Key Concept: The "Read-back" Loop
+
+Standard immediate-mode interaction often requires you to re-calculate layout logic to determine what was clicked.
+
+In `ratatui_ruby`'s Stateful Rendering:
+1.  **Update**: You modify `state` (e.g., `state.select(1)`).
+2.  **Render**: You pass `state` to `render_stateful_widget`. Ratatui's Rust backend calculates layout and **updates** `state.offset` in-place if scrolling happened.
+3.  **Interact**: On the next event loop, you use `state.offset` to correctly map mouse coordinates to data indices.
+
+## Hotkeys
+
+| Key | Action |
+| --- | --- |
+| `↑` / `↓` | Scroll the active pane |
+| `Tab` / `←` / `→` | Switch active pane (List vs Table) |
+| `Mouse Click` | Select the clicked row (Works with scrolling!) |
+| `q` | Quit |