ratatui_ruby 1.1.0 → 1.1.1

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

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