ratatui_ruby 0.4.0 → 0.6.0

data/examples/app_all_events/view/app_view.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "../view"
+require_relative "counts_view"
+require_relative "live_view"
+require_relative "log_view"
+require_relative "controls_view"
+
+# Orchestrates the complete UI layout and sub-view composition.
+#
+# Complex applications need a structured way to divide the screen and delegate rendering.
+# Placing all layout logic in one monolithic method makes the code difficult to maintain.
+#
+# This class defines the screen layout using a series of split constraints and delegates to sub-views.
+#
+# Use it as the root view for the All Events example application.
+#
+# === Examples
+#
+#   app_view = View::App.new
+#   app_view.call(model, tui, frame, area)
+class View::App
+  # Creates a new View::App and initializes sub-views.
+  def initialize
+    @counts_view = View::Counts.new
+    @live_view = View::Live.new
+    @log_view = View::Log.new
+    @controls_view = View::Controls.new
+  end
+
+  # Renders the entire application UI to the given area.
+  #
+  # [model] AppModel containing all application data.
+  # [tui] RatatuiRuby instance.
+  # [frame] RatatuiRuby::Frame being rendered.
+  # [area] RatatuiRuby::Rect defining the total available space.
+  #
+  # === Example
+  #
+  #   app_view.call(model, tui, frame, area)
+  def call(model, tui, frame, area)
+    main_area, control_area = tui.layout_split(
+      area,
+      direction: :vertical,
+      constraints: [
+        tui.constraint_fill(1),
+        tui.constraint_length(3),
+      ]
+    )
+
+    counts_area, _margin_area, right_area = tui.layout_split(
+      main_area,
+      direction: :horizontal,
+      constraints: [
+        tui.constraint_length(20),
+        tui.constraint_length(1),
+        tui.constraint_fill(1),
+      ]
+    )
+
+    live_area, log_area = tui.layout_split(
+      right_area,
+      direction: :vertical,
+      constraints: [
+        tui.constraint_length(9),
+        tui.constraint_fill(1),
+      ]
+    )
+
+    @counts_view.call(model, tui, frame, counts_area)
+    @live_view.call(model, tui, frame, live_area)
+    @log_view.call(model, tui, frame, log_area)
+    @controls_view.call(model, tui, frame, control_area)
+  end
+end

data/examples/app_all_events/view/controls_view.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "../view"
+
+# Renders the keyboard controls and shortcuts panel.
+#
+# Users need to know how to interact with the application and exit.
+# Hardcoding control descriptions into the main layout makes the code hard to read.
+#
+# This component renders a formatted paragraph listing available global shortcuts.
+#
+# Use it to display help information in a sidebar or dedicated panel.
+#
+# === Examples
+#
+#   controls = View::Controls.new
+#   controls.call(model, tui, frame, area)
+class View::Controls
+  # Renders the controls widget to the given area.
+  #
+  # [model] AppModel (unused, included for consistent interface).
+  # [tui] RatatuiRuby instance.
+  # [frame] RatatuiRuby::Frame being rendered.
+  # [area] RatatuiRuby::Rect defining the widget's bounds.
+  #
+  # === Example
+  #
+  #   controls.call(model, tui, frame, area)
+  def call(_model, tui, frame, area)
+    hotkey_style = tui.style(modifiers: [:bold, :underlined])
+
+    widget = tui.paragraph(
+      text: [
+        tui.text_line(spans: [
+          tui.text_span(content: "q", style: hotkey_style),
+          tui.text_span(content: ": Quit  "),
+          tui.text_span(content: "Ctrl+C", style: hotkey_style),
+          tui.text_span(content: ": Quit"),
+        ]),
+      ],
+      block: tui.block(
+        title: "Controls",
+        borders: [:all],
+        border_style: tui.style(fg: :white)
+      )
+    )
+    frame.render_widget(widget, area)
+  end
+end

data/examples/app_all_events/view/counts_view.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "../view"
+
+# Renders the event statistics dashboard.
+#
+# Developers auditing input need to see real-time counts of various event types.
+#
+# This component displays a list of event types with their total counts.
+#
+# Use it to build an interactive dashboard of application activity.
+class View::Counts
+  # Renders the event counts widget to the given area.
+  #
+  # [model] AppModel containing event data.
+  # [tui] RatatuiRuby instance.
+  # [frame] RatatuiRuby::Frame being rendered.
+  # [area] RatatuiRuby::Rect defining the widget's bounds.
+  def call(model, tui, frame, area)
+    dimmed_style = tui.style(fg: :dark_gray)
+    lit_style = tui.style(fg: :green, modifiers: [:bold])
+    border_color = model.focused ? :green : :gray
+
+    count_lines = []
+
+    AppAllEvents::EVENT_TYPES.each do |type|
+      count = model.count(type)
+      label = type.to_s.capitalize
+      style = model.lit?(type) ? lit_style : nil
+
+      count_lines << tui.text_line(spans: [
+        tui.text_span(content: "#{label}: ", style:),
+        tui.text_span(content: count.to_s, style: style || tui.style(fg: :yellow)),
+      ])
+
+      model.sub_counts(type).each do |sub_type, sub_count|
+        sub_label = sub_type.to_s.capitalize
+        count_lines << tui.text_line(spans: [
+          tui.text_span(content: "  #{sub_label}: ", style: dimmed_style),
+          tui.text_span(content: sub_count.to_s, style: dimmed_style),
+        ])
+      end
+    end
+
+    widget = tui.paragraph(
+      text: count_lines,
+      scroll: [0, 0],
+      block: tui.block(
+        title: "Event Counts",
+        borders: [:all],
+        border_style: tui.style(fg: border_color)
+      )
+    )
+    frame.render_widget(widget, area)
+  end
+end

data/examples/app_all_events/view/live_view.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "../view"
+
+# Renders a real-time summary of the most recent events.
+#
+# Users need to see the immediate result of their actions without digging through a log.
+# Identifying the specific details of the last key press or mouse move at a glance is difficult.
+#
+# This component displays a table showing the latest event of each type with its timestamp and description.
+#
+# Use it to provide instant feedback for user interactions.
+#
+# === Examples
+#
+#   live_view = View::Live.new
+#   live_view.call(model, tui, frame, area)
+class View::Live
+  # Renders the live event table to the given area.
+  #
+  # [model] AppModel containing event data.
+  # [tui] RatatuiRuby instance.
+  # [frame] RatatuiRuby::Frame being rendered.
+  # [area] RatatuiRuby::Rect defining the widget's bounds.
+  #
+  # === Example
+  #
+  #   live_view.call(model, tui, frame, area)
+  def call(model, tui, frame, area)
+    border_color = model.focused ? :green : :gray
+    rows = []
+
+    rows << tui.text_line(spans: [
+      tui.text_span(content: "Type".ljust(9), style: tui.style(fg: :gray, modifiers: [:bold])),
+      tui.text_span(content: "Time".ljust(10), style: tui.style(fg: :gray, modifiers: [:bold])),
+      tui.text_span(content: "Description", style: tui.style(fg: :gray, modifiers: [:bold])),
+    ])
+
+    (AppAllEvents::EVENT_TYPES - [:none]).each do |type|
+      event_data = model.live_event(type)
+
+      class_str = type.to_s.capitalize
+      time_str = event_data ? event_data[:time].strftime("%H:%M:%S") : "—"
+      desc_str = event_data ? event_data[:description] : "—"
+
+      is_lit = model.lit?(type)
+      row_style = is_lit ? tui.style(fg: :black, bg: :green) : nil
+
+      rows << tui.text_line(spans: [
+        tui.text_span(content: class_str.ljust(9), style: row_style || tui.style(fg: :cyan)),
+        tui.text_span(content: time_str.ljust(10), style: row_style || tui.style(fg: :white)),
+        tui.text_span(content: desc_str, style: row_style),
+      ])
+    end
+
+    widget = tui.paragraph(
+      text: rows,
+      scroll: [0, 0],
+      block: tui.block(
+        title: "Live Display",
+        borders: [:all],
+        border_style: tui.style(fg: border_color)
+      )
+    )
+    frame.render_widget(widget, area)
+  end
+end

data/examples/app_all_events/view/log_view.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "../view"
+
+# Renders a detailed, scrollable history of application events.
+#
+# Debugging complex event flows requires a chronological record of raw data.
+# Interpreting raw event objects without formatting is difficult and slow.
+#
+# This component renders event history as a series of formatted, color-coded entries showing raw data.
+#
+# Use it to provide a detailed audit trail of all terminal interactions.
+class View::Log
+  # Renders the event log widget to the given area.
+  #
+  # [model] AppModel containing event data.
+  # [tui] RatatuiRuby instance.
+  # [frame] RatatuiRuby::Frame being rendered.
+  # [area] RatatuiRuby::Rect defining the widget's bounds.
+  def call(model, tui, frame, area)
+    dimmed_style = tui.style(fg: :dark_gray)
+    border_color = model.focused ? :green : :gray
+
+    visible_entries_count = (area.height - 2) / 2
+    display_entries = model.visible(visible_entries_count)
+
+    log_lines = []
+    if model.empty?
+      log_lines << tui.text_line(spans: [tui.text_span(content: "No events yet...", style: dimmed_style)])
+    else
+      display_entries.each do |entry|
+        entry_style = tui.style(fg: entry.color)
+        description = entry.description
+
+        log_lines << tui.text_line(spans: [tui.text_span(content: description, style: entry_style)])
+        log_lines << tui.text_line(spans: [tui.text_span(content: "", style: entry_style)])
+      end
+    end
+
+    widget = tui.paragraph(
+      text: log_lines,
+      scroll: [0, 0],
+      wrap: { trim: true },
+      block: tui.block(
+        title: "Event Log",
+        borders: [:all],
+        border_style: tui.style(fg: border_color)
+      )
+    )
+    frame.render_widget(widget, area)
+  end
+end

data/examples/app_all_events/view.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module View
+end

data/examples/app_color_picker/README.md

@@ -0,0 +1,134 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Color Picker Example
+
+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, clipboard interaction)
+-   **Mouse Interaction & Hit Testing**
+-   **Dynamic Layouts**
+-   **Modal Dialogs**
+
+## Architecture: The "Proto-Kit" Pattern (Component-Based)
+
+This app uses a **Strict Component-Based Architecture** where every UI element encapsulates its own **Rendering**, **State**, and **Event Handling**.
+
+### The Component Contract
+
+Every component implements this duck-type interface:
+
+```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
+
+# 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
+
+### 🖱️ 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
+```
+
+### ⏱️ Lifecycle Hooks (`tick`)
+
+Components can have time-based updates. `Controls#tick` delegates to `Clipboard#tick` to decrement the feedback timer.
+
+## Problem Solving: What You Can Learn
+
+Read this example if you are trying to solve:
+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
+
+```bash
+ruby examples/app_color_picker/app.rb
+```
+
+-   Type a hex code (e.g., `#FF0055`) or color name (`cyan`).
+-   Press `Enter` to generate the palette.
+-   Click on the **Export Formats** box to copy the hex code.
+
+## Comparison: Choosing an Architecture
+
+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 - Proto-Kit)
+
+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 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 - Proto-TEA)
+
+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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+$LOAD_PATH.unshift File.expand_path(__dir__)
+
+require "ratatui_ruby"
+require_relative "main_container"
+
+# A terminal-based color picker application.
+#
+# Terminal users often need to select colors for themes or UI components.
+# Manually typing hex codes and guessing how they will look is slow and error-prone.
+#
+# This application solves the problem by providing an interactive interface. It parses hex strings,
+# generates palettes, and displays them visually in the terminal.
+#
+# === 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.
+  def initialize
+    @container = nil
+  end
+
+  # Starts the terminal session and enters the main event loop.
+  #
+  # This method initializes the terminal, creates the MainContainer, and runs
+  # the event loop until the user quits.
+  #
+  # === Example
+  #
+  #   app = AppColorPicker.new
+  #   app.run
+  #
+  def run
+    RatatuiRuby.run do |tui|
+      @container = MainContainer.new(tui)
+
+      loop do
+        @container.tick
+        tui.draw { |frame| @container.render(tui, frame, frame.area) }
+
+        event = tui.poll_event
+        break if quit_event?(event)
+
+        @container.handle_event(event)
+      end
+    end
+  end
+
+  private def quit_event?(event)
+    case event
+    in { type: :key, code: "q" } | { type: :key, code: "esc" } |
+       { type: :key, code: "c", modifiers: [/ctrl/] }
+      true
+    else
+      false
+    end
+  end
+end
+
+AppColorPicker.new.run if __FILE__ == $PROGRAM_NAME

data/examples/app_color_picker/clipboard.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Manages system clipboard interaction with transient feedback.
+#
+# Apps need to copy data to the clipboard. Users need feedback: "Did it work?"
+# Manual clipboard handling and feedback timers scattered through app logic is
+# messy.
+#
+# This object handles clipboard writes to all platforms (pbcopy, xclip, xsel).
+# It manages a feedback message and countdown timer.
+#
+# Use it to provide copy-to-clipboard functionality with user feedback.
+#
+# === Example
+#
+#   clipboard = Clipboard.new
+#   clipboard.copy("#FF0000")
+#   puts clipboard.message  # => "Copied!"
+#
+#   # In render loop:
+#   clipboard.tick  # Decrement timer
+#   puts clipboard.message  # => "" (after 60 frames)
+class Clipboard
+  def initialize
+    @message = ""
+    @timer = 0
+  end
+
+  # Writes text to the system clipboard.
+  #
+  # Tries pbcopy (macOS), xclip (Linux), then xsel (Linux fallback). Sets the
+  # feedback message to <tt>"Copied!"</tt> and starts a 60-frame timer.
+  #
+  # [text] String to copy
+  #
+  # === Example
+  #
+  #   clipboard = Clipboard.new
+  #   clipboard.copy("#FF0000")
+  #   clipboard.message  # => "Copied!"
+  def copy(text)
+    if `which pbcopy 2>/dev/null`.strip.length > 0
+      IO.popen("pbcopy", "w") { |io| io.write(text) }
+    elsif `which xclip 2>/dev/null`.strip.length > 0
+      IO.popen("xclip -selection clipboard", "w") { |io| io.write(text) }
+    elsif `which xsel 2>/dev/null`.strip.length > 0
+      IO.popen("xsel --clipboard --input", "w") { |io| io.write(text) }
+    end
+    @message = "Copied!"
+    @timer = 60
+  end
+
+  # Decrements the feedback timer by one frame.
+  #
+  # Call this once per render cycle. The message disappears when the timer
+  # reaches zero.
+  #
+  # === Example
+  #
+  #   clipboard.copy("text")  # timer = 60
+  #   clipboard.tick          # timer = 59
+  #   60.times { clipboard.tick }  # message becomes ""
+  def tick
+    @timer -= 1 if @timer > 0
+    @message = "" if @timer <= 0
+  end
+
+  # Current feedback message.
+  #
+  # Empty string when no active message. <tt>"Copied!"</tt> after a successful
+  # copy, fading after 60 frames.
+  #
+  # === Example
+  #
+  #   clipboard.message  # => ""
+  #   clipboard.copy("x")
+  #   clipboard.message  # => "Copied!"
+  def message
+    @message
+  end
+end