ratatui_ruby 0.3.1 → 0.5.0

data/examples/app_color_picker/app.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 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 "input"
+require_relative "palette"
+require_relative "clipboard"
+require_relative "copy_dialog"
+require_relative "scene"
+
+# 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.
+#
+# Use it to experiment with color combinations and quickly find the right hex codes.
+#
+# === Examples
+#
+#   AppColorPicker.new.run
+#
+class AppColorPicker
+  # Creates a new <tt>AppColorPicker</tt> instance with a default palette and clipboard.
+  def initialize
+    @input = Input.new
+    @palette = Palette.new(@input.parse)
+    @clipboard = Clipboard.new
+    @dialog = CopyDialog.new(@clipboard)
+    @scene = nil
+  end
+
+  # Starts the terminal session and enters the main event loop.
+  #
+  # This method initializes the terminal, renders the initial scene, and polls for
+  # input until the user quits.
+  #
+  # === Example
+  #
+  #   app = AppColorPicker.new
+  #   app.run
+  #
+  def run
+    RatatuiRuby.run do |tui|
+      @scene = Scene.new(tui)
+      loop do
+        render(tui)
+        result = handle_input(tui)
+        break if result == :quit
+      end
+    end
+  end
+
+  private def render(tui)
+    @clipboard.tick
+    tui.draw do |frame|
+      @scene.render(frame, input: @input, palette: @palette, clipboard: @clipboard, dialog: @dialog)
+    end
+  end
+
+  private def handle_input(tui)
+    event = tui.poll_event
+    @input.clear_error unless @dialog.active?
+
+    if @dialog.active?
+      handle_dialog_input(event)
+    else
+      handle_main_input(event)
+    end
+  end
+
+  private def handle_dialog_input(event)
+    result = @dialog.handle_input(event)
+    case event
+    in { type: :key, code: "q" } | { type: :key, code: "esc" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    else
+      result
+    end
+  end
+
+  private def handle_main_input(event)
+    case event
+    in { type: :key, code: "q" } | { type: :key, code: "esc" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in { type: :key, code: "enter" }
+      @palette = Palette.new(@input.parse)
+    in { type: :key, code: "backspace" }
+      @input.delete_char
+    in { type: :paste, content: }
+      @input.set(content)
+      @palette = Palette.new(@input.parse)
+    in { type: :key, code: code }
+      @input.append_char(code)
+    in { type: :mouse, kind: "down", button: "left", x:, y: }
+      if @scene && @scene.export_rect&.contains?(x, y) && @palette.main
+        @dialog.open(@palette.main.hex)
+      end
+    else
+      nil
+    end
+  end
+end
+
+AppColorPicker.new.run if __FILE__ == $PROGRAM_NAME

data/examples/app_color_picker/clipboard.rb

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

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 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/copy_dialog.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "clipboard"
+
+# A confirmation dialog for copying text to the clipboard.
+#
+# Users click on content they want to copy. The app needs to confirm: "Are you
+# sure?" Managing dialog state (visible, selection, active), rendering the
+# dialog, and dispatching keyboard events manually is tedious.
+#
+# This object owns dialog state and lifecycle. It renders itself. It responds
+# to keyboard input. It delegates clipboard operations to a Clipboard.
+#
+# Use it to build copy-on-click interactions with user confirmation.
+#
+# === Example
+#
+#   clipboard = Clipboard.new
+#   dialog = CopyDialog.new(clipboard)
+#
+#   # Open the dialog
+#   dialog.open("#FF0000")
+#   dialog.active?  # => true
+#
+#   # Handle input
+#   result = dialog.handle_input(event)  # Routes to :copied or :cancelled
+#
+#   # Render
+#   widget = dialog.render(tui, area)
+class CopyDialog
+  def initialize(clipboard)
+    @clipboard = clipboard
+    @text = ""
+    @selected = :yes
+    @active = false
+  end
+
+  # 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
+  #   dialog.text     # => "#FF0000"
+  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.
+  #
+  # === Example
+  #
+  #   dialog.open("text")
+  #   dialog.active?  # => true
+  #   dialog.close
+  #   dialog.active?  # => false
+  def active?
+    @active
+  end
+
+  # Processes a keyboard event and updates selection or closes the dialog.
+  #
+  # Left/h moves selection to :yes. Right/l moves to :no. Enter confirms.
+  # Y/N hotkeys also work (Y copies immediately, N cancels). Returns nil for
+  # all handled events; does nothing if the dialog is inactive.
+  #
+  # [event] Hash event from RatatuiRuby.poll_event
+  #
+  # === Example
+  #
+  #   dialog.open("text")
+  #   dialog.handle_input({ type: :key, code: "left" })
+  #   dialog.handle_input({ type: :key, code: "enter" })
+  #   dialog.active?  # => false
+  def handle_input(event)
+    return nil unless @active
+
+    case event
+    in { type: :key, code: "left" } | { type: :key, code: "h" }
+      @selected = :yes
+      nil
+    in { type: :key, code: "right" } | { type: :key, code: "l" }
+      @selected = :no
+      nil
+    in { type: :key, code: "enter" }
+      if @selected == :yes
+        @clipboard.copy(@text)
+      end
+      @active = false
+      nil
+    in { type: :key, code: "y" }
+      @clipboard.copy(@text)
+      @active = false
+      nil
+    in { type: :key, code: "n" }
+      @active = false
+      nil
+    else
+      nil
+    end
+  end
+
+  # Renders the dialog widget for display in a TUI frame.
+  #
+  # Shows the text to copy, Yes/No buttons with current selection highlighted,
+  # and keyboard instructions. Renders only when active.
+  #
+  # [tui] Session or TUI factory object
+  # [area] Rect area for the dialog
+  #
+  # === Example
+  #
+  #   dialog.open("#FF0000")
+  #   widget = dialog.render(tui, center_area)
+  #   frame.render_widget(widget, center_area)
+  def render(tui, area)
+    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/harmony.rb

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