ratatui_ruby 1.1.0 → 1.1.1

data/examples/app_all_events/view/live_view.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 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::Layout::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: :green, modifiers: [:reversed]) : 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

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 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::Layout::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

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

data/examples/app_cli_rich_moments/README.md

@@ -1,81 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# CLI Rich Moments Example
-
-[![CLI Rich Moments](../../doc/images/app_cli_rich_moments.gif)](app.rb)
-
-Demonstrates inline viewport usage for CLI tools that need brief moments of rich interactivity without full-screen commitment.
-
-## Context
-
-CLI applications often need moments of richness—a spinner while connecting, a quick menu selection, or a brief editor. But committing to a full-screen TUI feels wrong when 90% of the app is traditional CLI output.
-
-## Problem
-
-Standard full-screen TUIs (alternate screen) erase themselves on exit. Your carefully formatted CLI output disappears. Users lose their history. The terminal scrollback becomes useless.
-
-## Solution
-
-This example shows how **inline viewports** solve this problem. Inline regions persist in terminal scrollback after exit. You can mix inline and fullscreen viewports across multiple `RatatuiRuby.run` calls in a single application flow.
-
-## Flow
-
-The application demonstrates four distinct phases:
-
-1. **1-line inline**: Braille spinner (⠋ ⠙ ⠹ etc.) + "Connecting..." status
-2. **5-line inline**: Radio button menu with up/down/enter navigation  
-3. **Fullscreen**: Configuration editor showing legitimate use of alternate screen
-4. **1-line inline**: Braille spinner + "Saving..." confirmation
-
-After exit, all inline outputs remain visible in terminal history. The fullscreen portion disappears cleanly.
-
-## Running
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-cd examples/app_cli_rich_moments
-ruby app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## Architecture
-
-Each phase is a separate `RatatuiRuby.run` block with its own viewport configuration. State (like menu selection) must be passed between phases via instance variables.
-
-**Spinner phases**:
-- Use `viewport: :inline, height: 1`
-- Animate Braille frames with short delays
-- No input handling needed
-
-**Menu phase**:
-- Uses `viewport: :inline, height: 5`  
-- Handles up/down arrow keys for selection
-- Returns selected choice for next phase
-
-**Editor phase**:
-- Uses default fullscreen viewport
-- Demonstrates when alternate screen is appropriate
-- Full 80×24 available
-
-## Key Concepts
-
-- **Viewport independence**: Each `run` block can use different viewport modes
-- **Scrollback persistence**: Inline content remains after exit
-- **State management**: Pass data between phases via instance variables
-- **Appropriate contexts**: Inline for brief moments, fullscreen for sustained interaction
-
-## Learning Outcomes
-
-After studying this example, you'll understand:
-
-- When to use inline vs fullscreen viewports
-- How to mix viewport modes in a single application
-- Why inline viewports improve CLI UX for transient interactions
-- How to manage state across multiple `run` blocks

data/examples/app_cli_rich_moments/app.rb

@@ -1,189 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
-require "ratatui_ruby"
-
-class AppCliRichMoments
-  SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"].freeze
-  MENU_OPTIONS = [
-    "Development Environment",
-    "Staging Environment",
-    "Production Environment",
-  ].freeze
-
-  def initialize
-    @selected_index = 0
-    @choice = nil
-    @tui = RatatuiRuby::TUI.new
-  end
-
-  def run
-    phase_connecting
-    @choice = phase_menu
-    phase_editor
-    phase_saving
-  end
-
-  private def phase_connecting
-    RatatuiRuby.run(viewport: :inline, height: 1) do
-      10.times do |i|
-        render_spinner(SPINNER_FRAMES[i % SPINNER_FRAMES.length], "Connecting to server...")
-        sleep 0.1
-      end
-
-      # Insert success message above viewport into scrollback
-      status = "✓ Connected to server"
-      @tui.insert_before(1, @tui.paragraph(text: status, style: @tui.style(fg: :green)))
-    end
-  end
-
-  private def phase_menu
-    RatatuiRuby.run(viewport: :inline, height: 5) do
-      loop do
-        render_menu
-        case handle_menu_input
-        when :quit, :select
-          # Position cursor after viewport for next phase
-          area = @tui.viewport_area
-
-          # # If you wanted to remove the menu from scrollback, you could do:
-          # @tui.draw { |frame| frame.render_widget(@tui.clear, frame.area) }
-          # # And move the cursor to avoid extra blank space.
-          # RatatuiRuby.cursor_position = [0, area.y]
-
-          # But instead, we'll leave it in scrollback for reference.
-          # Move the cursor to avoid overwriting it.
-          RatatuiRuby.cursor_position = [0, area.y + area.height]
-
-          return MENU_OPTIONS[@selected_index]
-        end
-      end
-    end
-  end
-
-  private def phase_editor
-    RatatuiRuby.run do # Fullscreen by default
-      loop do
-        render_editor
-        break if handle_editor_input == :quit
-      end
-    end
-  end
-
-  private def phase_saving
-    RatatuiRuby.run(viewport: :inline, height: 1) do
-      10.times do |i|
-        render_spinner(SPINNER_FRAMES[i % SPINNER_FRAMES.length], "Saving configuration...")
-        sleep 0.1
-      end
-
-      status = "✓ Configuration saved to #{@choice.downcase.gsub(' ', '_')}.yml"
-      @tui.insert_before(1, @tui.paragraph(text: status, style: @tui.style(fg: :green)))
-    end
-  end
-
-  private def render_spinner(frame, message)
-    @tui.draw do |f|
-      text = "#{frame} #{message}"
-      widget = @tui.paragraph(text:, style: @tui.style(fg: :cyan))
-      f.render_widget(widget, f.area)
-    end
-  end
-
-  private def render_menu
-    @tui.draw do |f|
-      lines = MENU_OPTIONS.map.with_index do |option, idx|
-        prefix = (idx == @selected_index) ? "→ " : "  "
-        style = (idx == @selected_index) ? @tui.style(fg: :cyan, modifiers: [:bold]) : @tui.style(fg: :white)
-        @tui.text_line(spans: [@tui.text_span(content: "#{prefix}#{option}", style:)])
-      end
-
-      widget = @tui.paragraph(
-        text: lines,
-        block: @tui.block(borders: :all, title: "Select Environment")
-      )
-      f.render_widget(widget, f.area)
-    end
-  end
-
-  private def render_editor
-    @tui.draw do |f|
-      areas = @tui.layout_split(
-        f.area,
-        direction: :vertical,
-        constraints: [
-          @tui.constraint_fill(1),
-          @tui.constraint_length(3),
-        ]
-      )
-
-      # Main content area
-      content_text = [
-        "Editing: #{@choice}",
-        "",
-        "# Database Configuration",
-        "database:",
-        "  adapter: postgresql",
-        "  host: db.example.com",
-        "  port: 5432",
-        "",
-        "# Cache Configuration",
-        "cache:",
-        "  provider: redis",
-        "  ttl: 3600",
-      ].join("\n")
-
-      content = @tui.paragraph(
-        text: content_text,
-        block: @tui.block(borders: :all, title: "Configuration Editor"),
-        style: @tui.style(fg: :yellow)
-      )
-      f.render_widget(content, areas[0])
-
-      # Help panel
-      help_text = "q: Save and Exit  |  Ctrl+C: Cancel"
-      help = @tui.paragraph(
-        text: help_text,
-        block: @tui.block(borders: :all),
-        style: @tui.style(fg: :dark_gray),
-        alignment: :center
-      )
-      f.render_widget(help, areas[1])
-    end
-  end
-
-  private def handle_menu_input
-    case @tui.poll_event
-    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      :quit
-    in { type: :key, code: "enter" }
-      :select
-    in { type: :key, code: "up" }
-      @selected_index = (@selected_index - 1) % MENU_OPTIONS.length
-      nil
-    in { type: :key, code: "down" }
-      @selected_index = (@selected_index + 1) % MENU_OPTIONS.length
-      nil
-    else
-      nil
-    end
-  end
-
-  private def handle_editor_input
-    case @tui.poll_event
-    in { type: :key, code: "q" }
-      :quit # "and save," presumably
-    in { type: :key, code: "c", modifiers: ["ctrl"] }
-      :quit
-    else
-      nil
-    end
-  end
-end
-
-AppCliRichMoments.new.run if __FILE__ == $PROGRAM_NAME

data/examples/app_color_picker/README.md

@@ -1,156 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Color Picker Example
-
-[![Color Picker](../../doc/images/app_color_picker.png)](app.rb)
-
-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: 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:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```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
-```
-<!-- SPDX-SnippetEnd -->
-
-### 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:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-result = @input.handle_event(event)
-case result
-when :submitted
-  @palette.update_color(@input.parsed_color)
-  return :consumed
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-### ⏱️ 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
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/app_color_picker/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
--   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. Components need to know where they exist on screen for hit testing. The Container orchestrates cross-component effects.
-
-This example uses a **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)
-
-Dashboards display data. They rarely require complex mouse interaction. 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.
-
-[Read the source code →](app.rb)

data/examples/app_color_picker/app.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 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 a 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