ratatui_ruby 1.3.0 → 1.4.0

data/examples/app_color_picker/harmony.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-# A single color variant with label and styling information.
-#
-# Color palettes need to show individual colors with labels (Main, Shade, Tint,
-# Complement). Bundling a color's hex code, text color, and frame color together
-# is natural—they're always used as a set.
-#
-# This value object pairs a color with its metadata and rendering styles.
-#
-# Use it to represent colors in a palette or harmony.
-#
-# === Attributes
-#
-# [label] String label for this color variant
-# [hex] String hex color code
-# [text_color] Symbol (:white or :black) for readable text
-# [frame_color] String background color for the swatch frame
-#
-# === Example
-#
-#   harmony = Harmony.new(
-#     label: "Main",
-#     hex: "#FF0000",
-#     text_color: :white,
-#     frame_color: "#000000"
-#   )
-Harmony = Data.define(:label, :hex, :text_color, :frame_color) do
-  # Renders a 4-line color swatch for display in a TUI Block.
-  #
-  # Produces a visual representation: a 7-character-wide box with the color
-  # centered and the hex code below.
-  #
-  # [tui] Session or TUI factory object
-  #
-  # === Example
-  #
-  #   harmony = Harmony.new(...)
-  #   lines = harmony.color_swatch_lines(tui)
-  #   # => [TextLine, TextLine, TextLine, TextLine]
-  def color_swatch_lines(tui)
-    [
-      tui.text_line(spans: Array.new(7) { tui.text_span(content: " ", style: tui.style(bg: frame_color)) }),
-      tui.text_line(spans: [
-        *Array.new(3) { tui.text_span(content: " ", style: tui.style(bg: frame_color)) },
-        tui.text_span(content: " ", style: tui.style(bg: hex, fg: text_color)),
-        *Array.new(3) { tui.text_span(content: " ", style: tui.style(bg: frame_color)) },
-      ]),
-      tui.text_line(spans: Array.new(7) { tui.text_span(content: " ", style: tui.style(bg: frame_color)) }),
-      tui.text_line(spans: [tui.text_span(content: hex, style: tui.style(fg: :white))]),
-    ]
-  end
-end

data/examples/app_color_picker/input.rb

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

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

@@ -1,111 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 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_debugging_showcase/README.md

@@ -1,119 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Debugging Showcase
-
-[![Debugging Showcase](../../doc/images/app_debugging_showcase.gif)](app.rb)
-
-Interactive demonstration of RatatuiRuby's debugging features.
-
-For comprehensive documentation, see the [Debugging Guide](../../doc/concepts/debugging.md).
-
-## What This Example Does
-
-This app lets you trigger each debugging feature with a hotkey. Test your setup before encountering a real bug.
-
-| Key | Action |
-|-----|--------|
-| `d` | Enable `debug_mode!` programmatically |
-| `p` | Trigger a Rust panic |
-| `t` | Trigger a Rust `TypeError` |
-| `b` | Refresh debug status |
-| `q` | Quit |
-
-## Library Features Showcased
-
-Reading this code will teach you how to:
-
-*   **Enable Remote Debugging**: Call `RatatuiRuby.debug_mode!` and receive the socket path
-*   **Detect Debug State**: Query `Debug.enabled?`, `Debug.rust_backtrace_enabled?`, and `Debug.remote_debugging_mode`
-*   **Trigger Test Panics**: Use `Debug.test_panic!` to verify Rust backtrace visibility
-*   **See Improved Error Messages**: Bypass DWIM coercion to see `TypeError` messages with value context
-
-**Note:** Rust backtraces only appear for panics (`[p]`). Exceptions (`[t]`) show Ruby backtraces with improved error messages from Rust.
-
-## Environment Variables
-
-The example behaves differently depending on which environment variables you set.
-
-### No Environment Variables
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/app_debugging_showcase/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-The TUI starts normally. Rust backtraces are disabled. Press `[d]` to enable remote debugging mid-session.
-
-### `RUST_BACKTRACE=1`
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-RUST_BACKTRACE=1 ruby examples/app_debugging_showcase/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-Enables Rust backtraces. Press `[p]` to see the full Rust stack trace with file names and line numbers.
-
-### `RR_DEBUG=1`
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-RR_DEBUG=1 ruby examples/app_debugging_showcase/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-Full debug mode at startup. The debugger opens a socket and **waits for a connection** before the TUI starts. You'll see the socket path printed before the app runs.
-
-In another terminal:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-rdbg --attach
-```
-<!-- SPDX-SnippetEnd -->
-
-When you attach, you'll see "Stop by SIGURG" — that's normal! SIGURG is how the debug gem signals the app to pause. Type `continue` to resume.
-
-This uses the [ruby/debug](https://github.com/ruby/debug?tab=readme-ov-file#readme) gem for remote debugging.
-
-### When to Use Which
-
-`RR_DEBUG=1` includes Rust backtraces automatically (it calls `enable_rust_backtrace!` internally).
-
-Use `RUST_BACKTRACE=1` alone when you want backtraces but **don't** want the debugger to stop and wait for a connection at startup.
-
-## What Problems Does This Solve?
-
-### "Is my Rust backtrace setup working?"
-
-Press `[p]`. If you see a stack trace with file names and line numbers, you're good. If not, you need `RUST_BACKTRACE=1`.
-
-### "How do I attach a debugger to a TUI?"
-
-TUIs run in raw mode — you can't type into a REPL. Press `[d]` to enable remote debugging. The socket path appears in the UI. Run `rdbg --attach` from another terminal.
-
-### "What does a Rust TypeError look like?"
-
-Press `[t]`. The error message shows the expected type and the actual value you passed (e.g., `expected array for rows, got 42`). Note: This shows Ruby's backtrace — only panics (`[p]`) show Rust backtraces.
-
-[Read the source code →](app.rb)