ratatui_ruby 1.0.0 → 1.0.1

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)