ratatui_ruby 0.4.0 → 0.6.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/controls.rb

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

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

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

@@ -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