ratatui_ruby 0.4.0 → 0.5.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(state, 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.
+  #
+  # [state] ViewState containing all application data.
+  # [tui] RatatuiRuby instance.
+  # [frame] RatatuiRuby::Frame being rendered.
+  # [area] RatatuiRuby::Rect defining the total available space.
+  #
+  # === Example
+  #
+  #   app_view.call(state, tui, frame, area)
+  def call(state, 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(state, tui, frame, counts_area)
+    @live_view.call(state, tui, frame, live_area)
+    @log_view.call(state, tui, frame, log_area)
+    @controls_view.call(state, tui, frame, control_area)
+  end
+end

data/examples/app_all_events/view/controls_view.rb

@@ -0,0 +1,50 @@
+# 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(state, tui, frame, area)
+class View::Controls
+  # Renders the controls widget to the given area.
+  #
+  # [state] ViewState containing style information.
+  # [tui] RatatuiRuby instance.
+  # [frame] RatatuiRuby::Frame being rendered.
+  # [area] RatatuiRuby::Rect defining the widget's bounds.
+  #
+  # === Example
+  #
+  #   controls.call(state, tui, frame, area)
+  def call(state, tui, frame, area)
+    widget = tui.paragraph(
+      text: [
+        tui.text_line(spans: [
+          tui.text_span(content: "q", style: state.hotkey_style),
+          tui.text_span(content: ": Quit  "),
+          tui.text_span(content: "Ctrl+C", style: state.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,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 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.
+  #
+  # [state] ViewState containing event data and styles.
+  # [tui] RatatuiRuby instance.
+  # [frame] RatatuiRuby::Frame being rendered.
+  # [area] RatatuiRuby::Rect defining the widget's bounds.
+  def call(state, tui, frame, area)
+    count_lines = []
+
+    AppAllEvents::EVENT_TYPES.each do |type|
+      count = state.events.count(type)
+      label = type.to_s.capitalize
+      style = state.events.lit?(type) ? state.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)),
+      ])
+
+      state.events.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: state.dimmed_style),
+          tui.text_span(content: sub_count.to_s, style: state.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: state.border_color)
+      )
+    )
+    frame.render_widget(widget, area)
+  end
+end

data/examples/app_all_events/view/live_view.rb

@@ -0,0 +1,69 @@
+# 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(state, tui, frame, area)
+class View::Live
+  # Renders the live event table to the given area.
+  #
+  # [state] ViewState containing event data and styles.
+  # [tui] RatatuiRuby instance.
+  # [frame] RatatuiRuby::Frame being rendered.
+  # [area] RatatuiRuby::Rect defining the widget's bounds.
+  #
+  # === Example
+  #
+  #   live_view.call(state, tui, frame, area)
+  def call(state, tui, frame, area)
+    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 = state.events.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 = state.events.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: state.border_color)
+      )
+    )
+    frame.render_widget(widget, area)
+  end
+end

data/examples/app_all_events/view/log_view.rb

@@ -0,0 +1,60 @@
+# 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.
+  #
+  # [state] ViewState containing event data and styles.
+  # [tui] RatatuiRuby instance.
+  # [frame] RatatuiRuby::Frame being rendered.
+  # [area] RatatuiRuby::Rect defining the widget's bounds.
+  def call(state, tui, frame, area)
+    visible_entries_count = (area.height - 2) / 2
+    display_entries = state.events.visible(visible_entries_count)
+
+    log_lines = []
+    if state.events.empty?
+      log_lines << tui.text_line(spans: [tui.text_span(content: "No events yet...", style: state.dimmed_style)])
+    else
+      display_entries.each do |entry|
+        entry_style = tui.style(fg: entry.color)
+
+        # Split description into lines if it's too long, or just let it wrap conceptually (though paragraph wraps by character by default)
+        # Using simple inspect output as requested.
+        description = entry.description
+
+        # We want to display it over potentially multiple lines if needed, but the original code did manual 2-line formatting.
+        # Let's try to just dump the inspect string. If it's very long, it might be cut off.
+        # But the User asked specifically to use inspect.
+
+        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)]) # Spacer line to match previous 2-line rhythm? Or just compact?
+        # Previous view had 2 lines per entry. Let's keep a spacer to make it readable.
+      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: state.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_all_events/view_state.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Encapsulates all data required to render the application view.
+#
+# Views need access to models, global settings, and calculated styles.
+# Passing dozens of individual parameters to view components is messy and unmaintainable.
+#
+# This class provides a single, structured object containing all state necessary for rendering.
+#
+# Use it to shuttle data from the main application to the various view components.
+#
+# === Examples
+#
+#   state = ViewState.build(events, true, tui, nil)
+#   puts state.focused #=> true
+#   app_view.call(state, tui, frame, area)
+class ViewState < Data.define(:events, :focused, :hotkey_style, :dimmed_style, :lit_style, :border_color, :area)
+  # Builds a new ViewState with calculated styles.
+  #
+  # [events] Events model instance.
+  # [focused] Boolean indicating if the app has focus.
+  # [tui] RatatuiRuby instance for style creation.
+  # [_resize_sub_counter] Unused parameter (reserved for future use).
+  #
+  # === Example
+  #
+  #   ViewState.build(events, true, tui, nil) #=> #<ViewState ...>
+  def self.build(events, focused, tui, _resize_sub_counter)
+    new(
+      events:,
+      focused:,
+      hotkey_style: tui.style(modifiers: [:bold, :underlined]),
+      dimmed_style: tui.style(fg: :dark_gray),
+      lit_style: tui.style(fg: :green, modifiers: [:bold]),
+      border_color: focused ? :green : :gray,
+      area: nil
+    )
+  end
+end

data/examples/app_color_picker/README.md

@@ -0,0 +1,94 @@
+<!--
+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, undo/redo prep, clipboard interaction)
+-   **Mouse Interaction & Hit Testing**
+-   **Dynamic Layouts**
+-   **Modal Dialogs**
+
+## Architecture: The "Scene-Orchestrated" Pattern
+
+This app uses a pattern we call **"Scene-Orchestrated MVC"**.
+
+### 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`.
+
+### 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.
+
+### 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.
+
+This separation means your **business logic remains pure Ruby**, while the TUI layer focuses solely on presentation.
+
+## 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)`.
+
+### 🔲 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.
+
+### 🎨 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).
+
+## 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.
+
+## 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)
+
+Tools require interaction. Users click buttons and drag sliders. The Controller needs to know where components exist on screen. MVVM hides this layout data.
+
+This example uses a "Scene" pattern. The View exposes layout rectangles. The Controller uses these rectangles to handle mouse clicks.
+
+Use this pattern for forms, editors, and mouse-driven tools.
+
+### The Dashboard Approach (AppAllEvents)
+
+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.
+
+Use that pattern for logs, monitors, and data viewers.

data/examples/app_color_picker/app.rb

@@ -0,0 +1,112 @@
+# 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 "input"
+require_relative "palette"
+require_relative "clipboard"
+require_relative "copy_dialog"
+require_relative "scene"
+
+# 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.
+#
+# Use it to experiment with color combinations and quickly find the right hex codes.
+#
+# === Examples
+#
+#   AppColorPicker.new.run
+#
+class AppColorPicker
+  # Creates a new <tt>AppColorPicker</tt> instance with a default palette and clipboard.
+  def initialize
+    @input = Input.new
+    @palette = Palette.new(@input.parse)
+    @clipboard = Clipboard.new
+    @dialog = CopyDialog.new(@clipboard)
+    @scene = 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.
+  #
+  # === Example
+  #
+  #   app = AppColorPicker.new
+  #   app.run
+  #
+  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
+
+  private def handle_input(tui)
+    event = tui.poll_event
+    @input.clear_error unless @dialog.active?
+
+    if @dialog.active?
+      handle_dialog_input(event)
+    else
+      handle_main_input(event)
+    end
+  end
+
+  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
+    end
+  end
+
+  private def handle_main_input(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
+    else
+      nil
+    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