ratatui_ruby 1.0.0 → 1.0.1

data/examples/app_color_picker/controls.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-# A display-only component showing keyboard shortcuts and clipboard feedback.
-#
-# Users need to know what keys are available. They also need feedback when
-# they copy a color. This component renders the controls section.
-#
-# === Component Contract
-#
-# - `render(tui, frame, area, clipboard:)`: Draws the controls; stores `area`
-# - `handle_event(event) -> nil`: Display-only, always returns nil
-# - `tick`: Delegates to clipboard for time-based feedback updates
-#
-# === Example
-#
-#   controls = Controls.new
-#   controls.render(tui, frame, area, clipboard: clipboard)
-#   controls.tick(clipboard)
-class Controls
-  def initialize
-    @area = nil
-    @hotkey_style = nil
-  end
-
-  # The cached render area.
-  attr_reader :area
-
-  # Renders the controls section into the given area.
-  #
-  # Shows keyboard shortcuts and clipboard feedback message if one is active.
-  #
-  # [tui] Session or TUI factory object
-  # [frame] Frame object from RatatuiRuby.draw block
-  # [area] Rect area to draw into
-  # [clipboard] Clipboard object for feedback message
-  #
-  # === Example
-  #
-  #   controls.render(tui, frame, control_area, clipboard: clipboard)
-  def render(tui, frame, area, clipboard:)
-    @area = area
-    @hotkey_style ||= tui.style(modifiers: [:bold, :underlined])
-    widget = build_widget(tui, clipboard)
-    frame.render_widget(widget, area)
-  end
-
-  # Display-only component; always returns nil.
-  def handle_event(_event)
-    nil
-  end
-
-  # Delegates tick to the clipboard for time-based updates.
-  #
-  # [clipboard] Clipboard object to tick
-  def tick(clipboard)
-    clipboard.tick
-  end
-
-  private def build_widget(tui, clipboard)
-    control_lines = [
-      tui.text_line(spans: [
-        tui.text_span(content: "a-z/0-9", style: @hotkey_style),
-        tui.text_span(content: ": Type  "),
-        tui.text_span(content: "enter", style: @hotkey_style),
-        tui.text_span(content: ": Parse  "),
-        tui.text_span(content: "bksp", style: @hotkey_style),
-        tui.text_span(content: ": Erase  "),
-        tui.text_span(content: "esc", style: @hotkey_style),
-        tui.text_span(content: ": Quit"),
-      ]),
-    ]
-
-    unless clipboard.message.empty?
-      control_lines << tui.text_line(spans: [
-        tui.text_span(content: clipboard.message, style: tui.style(fg: :green, modifiers: [:bold])),
-      ])
-    end
-
-    tui.block(
-      title: "Controls",
-      borders: [:all],
-      children: [
-        tui.paragraph(text: control_lines),
-      ]
-    )
-  end
-end

data/examples/app_color_picker/copy_dialog.rb

@@ -1,168 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require_relative "clipboard"
-
-# A self-contained modal dialog component for copying text to the clipboard.
-#
-# Users click on content they want to copy. The app needs to confirm: "Are you
-# sure?" This component owns dialog state, renders itself, and handles keyboard
-# input.
-#
-# === Component Contract
-#
-# - `render(tui, frame, area)`: Draws the dialog; stores `area`
-# - `handle_event(event) -> Symbol | nil`: Returns `:consumed` when handled
-# - `open(text)`: Opens the dialog with the text to copy
-# - `close`: Closes the dialog
-# - `active?`: True if the dialog is visible
-#
-# === Example
-#
-#   dialog = CopyDialog.new(clipboard)
-#   dialog.open("#FF0000")
-#
-#   result = dialog.handle_event(event)
-#   # result == :consumed when dialog handled the event
-#
-#   dialog.render(tui, frame, center_area)
-class CopyDialog
-  def initialize(clipboard)
-    @clipboard = clipboard
-    @text = ""
-    @selected = :yes
-    @active = false
-    @area = nil
-  end
-
-  # The cached render area.
-  attr_reader :area
-
-  # Opens the dialog with text to copy.
-  #
-  # Initializes selection to <tt>:yes</tt> and sets active to true.
-  #
-  # [text] String text to show and copy
-  #
-  # === Example
-  #
-  #   dialog.open("#FF0000")
-  #   dialog.active?  # => true
-  def open(text)
-    @text = text
-    @selected = :yes
-    @active = true
-  end
-
-  # Closes the dialog and deactivates it.
-  def close
-    @active = false
-  end
-
-  # True if the dialog is currently open and visible.
-  def active?
-    @active
-  end
-
-  # Renders the dialog into the given area.
-  #
-  # Shows the text to copy, Yes/No buttons with current selection highlighted,
-  # and keyboard instructions.
-  #
-  # [tui] Session or TUI factory object
-  # [frame] Frame object from RatatuiRuby.draw block
-  # [area] Rect area to draw into
-  #
-  # === Example
-  #
-  #   dialog.render(tui, frame, center_area)
-  def render(tui, frame, area)
-    @area = area
-    widget = build_widget(tui)
-    frame.render_widget(widget, area)
-  end
-
-  # Processes a keyboard event and updates selection or closes the dialog.
-  #
-  # Returns:
-  # - `:consumed` when the event was handled
-  # - `nil` when the event was ignored or dialog is inactive
-  #
-  # [event] Event from RatatuiRuby.poll_event
-  #
-  # === Example
-  #
-  #   result = dialog.handle_event(event)
-  def handle_event(event)
-    return nil unless @active
-
-    case event
-    in { type: :key, code: "left" } | { type: :key, code: "h" }
-      @selected = :yes
-      :consumed
-    in { type: :key, code: "right" } | { type: :key, code: "l" }
-      @selected = :no
-      :consumed
-    in { type: :key, code: "enter" }
-      if @selected == :yes
-        @clipboard.copy(@text)
-      end
-      @active = false
-      :consumed
-    in { type: :key, code: "y" }
-      @clipboard.copy(@text)
-      @active = false
-      :consumed
-    in { type: :key, code: "n" }
-      @active = false
-      :consumed
-    else
-      nil
-    end
-  end
-
-  private def build_widget(tui)
-    yes_style = if @selected == :yes
-      tui.style(bg: :cyan, fg: :black, modifiers: [:bold])
-    else
-      tui.style(fg: :gray)
-    end
-
-    no_style = if @selected == :no
-      tui.style(bg: :cyan, fg: :black, modifiers: [:bold])
-    else
-      tui.style(fg: :gray)
-    end
-
-    tui.block(
-      title: "Copy to Clipboard",
-      borders: [:all],
-      border_type: :rounded,
-      style: tui.style(bg: :black, fg: :white),
-      children: [
-        tui.paragraph(
-          text: [
-            tui.text_line(spans: [
-              tui.text_span(content: "Copy #{@text}?", style: tui.style(fg: :white)),
-            ]),
-            tui.text_line(spans: []),
-            tui.text_line(spans: [
-              tui.text_span(content: "[", style: tui.style(fg: :white)),
-              tui.text_span(content: "Yes", style: yes_style),
-              tui.text_span(content: "]  [", style: tui.style(fg: :white)),
-              tui.text_span(content: "No", style: no_style),
-              tui.text_span(content: "]", style: tui.style(fg: :white)),
-            ]),
-            tui.text_line(spans: [
-              tui.text_span(content: "Use ←/→ or h/l to select, Enter to confirm", style: tui.style(fg: :gray, modifiers: [:italic])),
-            ]),
-          ]
-        ),
-      ]
-    )
-  end
-end

data/examples/app_color_picker/export_pane.rb

@@ -1,128 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-# A self-contained component displaying export formats for a color.
-#
-# Users need to copy color values in different formats (HEX, RGB, HSL).
-# This component renders the export section and detects clicks on itself.
-#
-# === Component Contract
-#
-# - `render(tui, frame, area, palette:)`: Draws the export formats; stores `area` for hit testing
-# - `handle_event(event) -> Symbol | nil`: Returns `:copy_requested` when clicked
-#
-# === Example
-#
-#   export_pane = ExportPane.new
-#   export_pane.render(tui, frame, area, palette: palette)
-#
-#   result = export_pane.handle_event(event)
-#   if result == :copy_requested && palette.main
-#     dialog.open(palette.main.hex)
-#   end
-class ExportPane
-  def initialize
-    @area = nil
-  end
-
-  # The cached render area, for hit testing.
-  attr_reader :area
-
-  # Renders the export formats section into the given area.
-  #
-  # Shows HEX, RGB, and HSL values for the current color. 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
-  # [palette] Palette object containing the color to display
-  #
-  # === Example
-  #
-  #   export_pane.render(tui, frame, export_area, palette: palette)
-  def render(tui, frame, area, palette:)
-    @area = area
-    widget = build_widget(tui, palette)
-    frame.render_widget(widget, area)
-  end
-
-  # Processes a mouse event and returns a signal if clicked.
-  #
-  # Returns:
-  # - `:copy_requested` when the pane is clicked (caller should open copy dialog)
-  # - `nil` when the event was ignored or outside the area
-  #
-  # [event] Event from RatatuiRuby.poll_event
-  #
-  # === Example
-  #
-  #   result = export_pane.handle_event(event)
-  #   if result == :copy_requested
-  #     dialog.open(palette.main.hex)
-  #   end
-  def handle_event(event)
-    case event
-    in { type: :mouse, kind: "down", button: "left", x:, y: }
-      if @area&.contains?(x, y)
-        :copy_requested
-      end
-    else
-      nil
-    end
-  end
-
-  private def build_widget(tui, palette)
-    if palette.main.nil?
-      tui.block(
-        title: "Export Formats",
-        borders: [:all],
-        children: [
-          tui.paragraph(
-            text: tui.text_line(spans: [
-              tui.text_span(content: "Enter a color to see formats"),
-            ])
-          ),
-        ]
-      )
-    else
-      build_color_widget(tui, palette.main)
-    end
-  end
-
-  private def build_color_widget(tui, color)
-    hex = color.hex
-    rgb = color.rgb
-    hsl = color.hsl_string
-    text_color = color.contrasting_text_color
-    bg_style = tui.style(bg: hex, fg: text_color)
-
-    tui.block(
-      title: "Export Formats",
-      borders: [:all],
-      style: bg_style,
-      children: [
-        tui.paragraph(
-          text: [
-            tui.text_line(spans: [
-              tui.text_span(content: "HEX: ", style: bg_style),
-              tui.text_span(content: hex, style: tui.style(bg: hex, fg: text_color, modifiers: [:underlined])),
-            ]),
-            tui.text_line(spans: [
-              tui.text_span(content: "RGB: ", style: bg_style),
-              tui.text_span(content: rgb, style: tui.style(bg: hex, fg: text_color, modifiers: [:underlined])),
-            ]),
-            tui.text_line(spans: [
-              tui.text_span(content: "HSL: ", style: bg_style),
-              tui.text_span(content: hsl, style: tui.style(bg: hex, fg: text_color, modifiers: [:underlined])),
-            ]),
-          ]
-        ),
-      ]
-    )
-  end
-end

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