ratatui_ruby 1.0.0 → 1.0.1

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

data/examples/app_color_picker/clipboard.rb

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

data/examples/app_color_picker/color.rb

@@ -1,193 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require "chroma"
-require "wcag_color_contrast"
-require_relative "harmony"
-
-# Represents a single color with format conversion and harmony generation.
-#
-# Colors are central to visual design. Users need to work with colors in multiple
-# formats: hex, RGB, HSL. They also need to generate color schemes: shades, tints,
-# and complementary colors. Managing these conversions and relationships manually
-# is tedious and error-prone.
-#
-# This object wraps a Chroma color. It exposes format conversions. It generates
-# color harmonies. It calculates contrast ratios to choose readable text colors.
-#
-# Use it to parse user input, transform colors, and build color palettes.
-#
-# === Example
-#
-#   color = Color.parse("#FF0000")
-#   puts color.hex     # => "#FF0000"
-#   puts color.rgb     # => "rgb(255, 0, 0)"
-#   puts color.hsl_string  # => "hsl(0, 100%, 50%)"
-#
-#   # Generate harmonies
-#   harmonies = color.harmonies  # => [main, shade, tint, complement, ...]
-#
-#   # Transform colors
-#   lighter = color.tint(5)
-#   darker = color.shade(3)
-#   rotated = color.spin(180)
-class Color
-  def initialize(chroma_color)
-    @chroma = chroma_color
-  end
-
-  # Parses a color string and returns a Color, or nil if the string is invalid.
-  #
-  # Accepts hex, RGB, HSL, and named colors. Trims whitespace and handles
-  # empty strings gracefully.
-  #
-  # [input_str] String in any format Chroma supports (e.g., <tt>"#FF0000"</tt>, <tt>"red"</tt>, <tt>"rgb(255,0,0)"</tt>)
-  #
-  # === Example
-  #
-  #   Color.parse("#FF0000")       # => Color
-  #   Color.parse("red")            # => Color
-  #   Color.parse("invalid")        # => nil
-  #   Color.parse("")               # => nil
-  def self.parse(input_str)
-    input_str = input_str.to_s.strip
-    return nil if input_str.empty?
-
-    new(Chroma.paint(input_str.dup))
-  rescue
-    nil
-  end
-
-  # Hex color code (uppercase).
-  #
-  # === Example
-  #
-  #   color = Color.parse("red")
-  #   color.hex  # => "#FF0000"
-  def hex
-    @chroma.to_hex.upcase
-  end
-
-  # RGB color code.
-  #
-  # === Example
-  #
-  #   color = Color.parse("red")
-  #   color.rgb  # => "rgb(255, 0, 0)"
-  def rgb
-    @chroma.to_rgb
-  end
-
-  # HSL color string with percentage formatting.
-  #
-  # === Example
-  #
-  #   color = Color.parse("red")
-  #   color.hsl_string  # => "hsl(0, 100%, 50%)"
-  def hsl_string
-    hsl_obj = @chroma.hsl
-    h = hsl_obj.h
-    s = hsl_obj.s
-    l = hsl_obj.l
-    format("hsl(%.0f, %.1f%%, %.1f%%)", h, s * 100, l * 100)
-  end
-
-  # Darkens the color. Returns a new Color.
-  #
-  # [amount] Integer amount to darken (default: 3)
-  #
-  # === Example
-  #
-  #   color = Color.parse("red")
-  #   color.shade(5).hex  # => darker red
-  def shade(amount = 3)
-    Color.new(@chroma.darken(amount))
-  end
-
-  # Lightens the color. Returns a new Color.
-  #
-  # [amount] Integer amount to lighten (default: 3)
-  #
-  # === Example
-  #
-  #   color = Color.parse("red")
-  #   color.tint(5).hex  # => lighter red
-  def tint(amount = 3)
-    Color.new(@chroma.lighten(amount))
-  end
-
-  # Rotates the hue. Returns a new Color.
-  #
-  # [degrees] Integer degrees to rotate (0-360)
-  #
-  # === Example
-  #
-  #   color = Color.parse("red")
-  #   color.spin(180).hex  # => cyan
-  def spin(degrees)
-    Color.new(@chroma.spin(degrees))
-  end
-
-  # Determines optimal text color (:white or :black) for maximum contrast.
-  #
-  # Uses WCAG contrast ratio calculation. Returns <tt>:white</tt> if white has
-  # higher contrast; <tt>:black</tt> otherwise.
-  #
-  # === Example
-  #
-  #   Color.parse("yellow").contrasting_text_color  # => :black
-  #   Color.parse("navy").contrasting_text_color    # => :white
-  def contrasting_text_color
-    white_contrast = WCAGColorContrast.ratio(hex.sub(/^#/, ""), "ffffff")
-    black_contrast = WCAGColorContrast.ratio(hex.sub(/^#/, ""), "000000")
-    (white_contrast > black_contrast) ? :white : :black
-  end
-
-  # Background color for rendering this color as a swatch.
-  #
-  # Returns <tt>"#000000"</tt> if text should be white; <tt>"#ffffff"</tt> if black.
-  # Used to frame color swatches with contrasting borders.
-  #
-  # === Example
-  #
-  #   Color.parse("yellow").frame_color  # => "#000000"
-  def frame_color
-    (contrasting_text_color == :white) ? "#000000" : "#ffffff"
-  end
-
-  # Seven-color harmony: main, shade, tint, complement, split 1, split 2, split-complement.
-  #
-  # Generates a complete color scheme for UI design. Each harmony is a Harmony
-  # value object with label, hex, and styling information.
-  #
-  # === Example
-  #
-  #   color = Color.parse("red")
-  #   harmonies = color.harmonies
-  #   harmonies.first.label  # => "Main"
-  #   harmonies.size         # => 7
-  def harmonies
-    [
-      harmony_with_label("Main"),
-      shade.harmony_with_label("Shade"),
-      tint.harmony_with_label("Tint"),
-      spin(180).harmony_with_label("Comp"),
-      spin(150).harmony_with_label("Split 1"),
-      spin(210).harmony_with_label("Split 2"),
-      spin(30).harmony_with_label("S.Comp"),
-    ]
-  end
-
-  def harmony_with_label(label)
-    Harmony.new(
-      label:,
-      hex:,
-      text_color: contrasting_text_color,
-      frame_color:,
-    )
-  end
-end