ratatui_ruby 0.4.0 → 0.5.0

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

data/examples/app_color_picker/input.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "color"
+
+# Manages text input and color parsing with error feedback.
+#
+# Users type color values. They make mistakes—typos, invalid formats. The app
+# needs to validate their input and show helpful error messages. Manually
+# tracking input state, validation, and error messages across renders is
+# cumbersome and error-prone.
+#
+# This object holds the current input string. It validates by parsing. It stores
+# errors and clears them when appropriate. It provides methods to manipulate
+# the input (append, delete).
+#
+# Use it to build text input forms where validation feedback matters.
+#
+# === Example
+#
+#   input = Input.new
+#   input.append_char("#")
+#   input.append_char("f")
+#   input.append_char("f")
+#   color = input.parse  # => Color or nil
+#   puts input.error     # => error message if parse failed
+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 = ""
+  end
+
+  # Current input string.
+  #
+  # === Example
+  #
+  #   input = Input.new
+  #   input.value  # => "#F96302"
+  def value
+    @value
+  end
+
+  # Error message from the last failed parse, or empty string.
+  #
+  # === Example
+  #
+  #   input.parse  # => nil (invalid)
+  #   input.error  # => "Invalid color format. Try: #ff0000, rgb(255,0,0), red"
+  def error
+    @error
+  end
+
+  # Clears the current error message.
+  def clear_error
+    @error = ""
+  end
+
+  # Appends a character to the input if it matches the printable pattern.
+  #
+  # Silently ignores non-printable characters. Valid characters include
+  # letters, digits, hash, comma, parentheses, dot, space, and percent.
+  #
+  # [char] String single character
+  def append_char(char)
+    @value += char if char.length == 1 && char.match?(PRINTABLE_PATTERN)
+  end
+
+  # Removes the last character from the input.
+  def delete_char
+    @value = @value[0...-1]
+  end
+
+  # Replaces the entire input string.
+  #
+  # [text] String new input value
+  def set(text)
+    @value = text
+  end
+
+  # Parses the current input as a Color.
+  #
+  # Returns a Color if valid; nil otherwise. Sets the error message on failure.
+  # Clears the error message on success.
+  #
+  # === Example
+  #
+  #   input = Input.new("#FF0000")
+  #   color = input.parse  # => Color
+  #   input.error          # => ""
+  def parse
+    color = Color.parse(@value)
+    if color
+      clear_error
+      color
+    else
+      @error = "Invalid color format. Try: #ff0000, rgb(255,0,0), red"
+      nil
+    end
+  end
+
+  # Renders the input widget for display in a TUI frame.
+  #
+  # Shows the current input value with a cursor. Displays the error message
+  # in red if one is set.
+  #
+  # [tui] Session or TUI factory object
+  #
+  # === Example
+  #
+  #   input = Input.new
+  #   widget = input.render(tui)
+  #   frame.render_widget(widget, area)
+  def render(tui)
+    input_lines = [
+      tui.text_line(spans: [
+        tui.text_span(content: @value),
+        tui.text_span(content: "_", style: tui.style(modifiers: [:reversed])),
+      ]),
+    ]
+
+    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
+end

data/examples/app_color_picker/palette.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "color"
+
+# Holds a primary color and its harmonies.
+#
+# Color pickers need to show related colors: shades, tints, complements. Building
+# these relationships repeatedly is redundant. Passing them individually through
+# rendering pipelines is awkward.
+#
+# This object owns a primary color and generates its harmonies on demand. It
+# provides accessor methods and rendering helpers.
+#
+# Use it to organize color data for palette displays.
+#
+# === Example
+#
+#   color = Color.parse("#FF0000")
+#   palette = Palette.new(color)
+#   palette.main           # => Color
+#   palette.all            # => [Harmony, Harmony, ...]
+#   blocks = palette.as_blocks(tui)  # => [Block, Block, ...]
+class Palette
+  def initialize(primary_color)
+    @primary = primary_color
+  end
+
+  # The primary (main) color, or nil if no color is set.
+  #
+  # === Example
+  #
+  #   palette = Palette.new(color)
+  #   palette.main.hex  # => "#FF0000"
+  def main
+    @primary
+  end
+
+  # All harmonies: main, shade, tint, complement, split 1, split 2, split-complement.
+  #
+  # Returns an empty array if no primary color is set.
+  #
+  # === Example
+  #
+  #   palette = Palette.new(color)
+  #   palette.all.size  # => 7
+  def all
+    return [] if @primary.nil?
+
+    @primary.harmonies
+  end
+
+  # Renders all harmonies as TUI Block widgets.
+  #
+  # Each harmony becomes a titled block showing its color swatch. Returns an empty
+  # array if no primary color is set.
+  #
+  # [tui] Session or TUI factory object
+  #
+  # === Example
+  #
+  #   palette = Palette.new(color)
+  #   blocks = palette.as_blocks(tui)
+  #   # blocks[0] => Block titled "Main" with color swatch
+  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