ratatui_ruby 0.4.0 → 0.6.0

data/examples/app_color_picker/input.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "color"
+
+# 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.
+#
+# 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.
+#
+# === 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.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%]/
+
+  # Creates a new Input with an optional initial value.
+  #
+  # [initial_value] String initial color input (default: <tt>"#F96302"</tt>)
+  def initialize(initial_value = "#F96302")
+    @value = initial_value
+    @error = ""
+    @parsed_color = nil
+    @area = nil
+  end
+
+  # Current input string.
+  attr_reader :value
+
+  # Error message from the last failed parse, or empty string.
+  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
+
+  # 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
+  #
+  # [event] Event from RatatuiRuby.poll_event
+  #
+  # === 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
+
+  private def delete_char
+    @value = @value[0...-1]
+  end
+
+  private def set(text)
+    @value = text
+  end
+
+  private def parse
+    color = Color.parse(@value)
+    if color
+      clear_error
+      @parsed_color = color
+    else
+      @error = "Invalid color format. Try: #ff0000, rgb(255,0,0), red"
+      @parsed_color = nil
+    end
+  end
+
+  private def build_widget(tui)
+    input_lines = [
+      tui.text_line(spans: [
+        tui.text_span(content: @value),
+      ]),
+    ]
+
+    unless @error.empty?
+      input_lines << tui.text_line(spans: [
+        tui.text_span(content: @error, style: tui.style(fg: :red)),
+      ])
+    end
+
+    tui.block(
+      title: "Color Input",
+      borders: [:all],
+      children: [
+        tui.paragraph(text: input_lines),
+      ]
+    )
+  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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "color"
+
+# A self-contained component displaying a color palette with harmonies.
+#
+# Color pickers need to show related colors: shades, tints, complements. This
+# component owns a primary color and renders its harmonies.
+#
+# === Component Contract
+#
+# - `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
+#
+#   palette = Palette.new
+#   palette.update_color(Color.parse("#FF0000"))
+#   palette.render(tui, frame, palette_area)
+class Palette
+  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.main.hex  # => "#FF0000"
+  def main
+    @primary
+  end
+
+  # Updates the primary color.
+  #
+  # Called by the MainContainer when Input submits a new color.
+  #
+  # [color] Color object or nil
+  def update_color(color)
+    @primary = color
+  end
+
+  # All harmonies: main, shade, tint, complement, split 1, split 2, split-complement.
+  #
+  # Returns an empty array if no primary color is set.
+  def all
+    return [] if @primary.nil?
+
+    @primary.harmonies
+  end
+
+  # Renders the palette into the given area.
+  #
+  # 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.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|
+      tui.block(
+        title: harmony.label,
+        borders: [:all],
+        children: [
+          tui.paragraph(text: harmony.color_swatch_lines(tui)),
+        ]
+      )
+    end
+  end
+end

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/{login_form → app_login_form}/app.rb

@@ -6,7 +6,7 @@
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
 
-class LoginFormApp
+class AppLoginForm
   PREFIX = "Enter Username: [ "
   SUFFIX = " ]"
 
@@ -16,7 +16,8 @@ class LoginFormApp
   end
 
   def run
-    RatatuiRuby.run do
+    RatatuiRuby.run do |tui|
+      @tui = tui
       loop do
         render
         break if handle_input == :quit
@@ -24,9 +25,7 @@ class LoginFormApp
     end
   end
 
-  private
-
-  def render
+  private def render
     # 1. Base Layer Construction
     # We want a cursor relative to the paragraph.
     # So we wrap Paragraph and Cursor in an Overlay, and put that Overlay in a Center.
@@ -39,17 +38,17 @@ class LoginFormApp
     cursor_y = 1
 
     # The content of the base form
-    form_content = RatatuiRuby::Overlay.new(layers: [
-      RatatuiRuby::Paragraph.new(
+    form_content = @tui.overlay(layers: [
+      @tui.paragraph(
         text: "#{PREFIX}#{@username}#{SUFFIX}",
-        block: RatatuiRuby::Block.new(borders: :all, title: "Login Form"),
+        block: @tui.block(borders: :all, title: "Login Form"),
         alignment: :left
       ),
-      RatatuiRuby::Cursor.new(x: cursor_x, y: cursor_y),
+      @tui.cursor(x: cursor_x, y: cursor_y),
     ])
 
     # Center the form on screen
-    base_layer = RatatuiRuby::Center.new(
+    base_layer = @tui.center(
       child: form_content,
       width_percent: 50,
       height_percent: 20
@@ -57,11 +56,11 @@ class LoginFormApp
 
     # 2. Popup Layer Construction
     final_view = if @show_popup
-      popup_message = RatatuiRuby::Center.new(
-        child: RatatuiRuby::Paragraph.new(
+      popup_message = @tui.center(
+        child: @tui.paragraph(
           text: "Login Successful!\nPress 'q' to quit.",
-          style: RatatuiRuby::Style.new(fg: :green, bg: :black),
-          block: RatatuiRuby::Block.new(borders: :all),
+          style: @tui.style(fg: :green, bg: :black),
+          block: @tui.block(borders: :all),
           alignment: :center,
           wrap: true
         ),
@@ -70,42 +69,39 @@ class LoginFormApp
       )
 
       # Render Base Layer (background) THEN Popup Layer
-      RatatuiRuby::Overlay.new(layers: [base_layer, popup_message])
+      @tui.overlay(layers: [base_layer, popup_message])
     else
       base_layer
     end
 
     # 3. Draw
-    RatatuiRuby.draw(final_view)
+    @tui.draw do |frame|
+      frame.render_widget(final_view, frame.area)
+    end
   end
 
-  def handle_input
-    # 4. Event Handling
-    event = RatatuiRuby.poll_event
-    return unless event
-
-    if event.key?
-      if @show_popup
-        return :quit if event == "q" || event == :ctrl_c
-      else
-        # Login Form Input
-        return :quit if event == :ctrl_c
-        case event.code
-        when "enter"
-          @show_popup = true
-        when "backspace"
-          @username.chop!
-        when "esc"
-          :quit
-        else
-          # Simple text input
-          if event.text? && !event.ctrl? && !event.alt?
-            @username += event.code
-          end
-        end
-      end
+  private def handle_input
+    case @tui.poll_event
+    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
+    in { type: :key, code: "backspace" }
+      @username.chop! unless @show_popup
+      nil
+    in { type: :key, code: "esc" }
+      :quit unless @show_popup
+    in { type: :key, code:, modifiers: [] }
+      # Simple text input (single character, no modifiers)
+      @username += code if !@show_popup && code.length == 1
+      nil
+    else
+      nil
     end
   end
 end
 
-LoginFormApp.new.run if __FILE__ == $0
+AppLoginForm.new.run if __FILE__ == $0

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 |