ratatui_ruby 0.3.1 → 0.5.0

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

data/examples/app_color_picker/scene.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "input"
+require_relative "palette"
+require_relative "clipboard"
+require_relative "copy_dialog"
+
+# Orchestrates layout and rendering of the color picker UI.
+#
+# Building a complete color picker UI involves layout calculation, widget
+# composition, and coordinate tracking for hit testing. Keeping this logic
+# scattered across the main app makes the app harder to read and test.
+#
+# This object owns the layout logic. It orchestrates all sections. It calculates
+# and caches rects for hit testing.
+#
+# Use it to encapsulate complex UI composition.
+#
+# === Example
+#
+#   scene = Scene.new(tui)
+#   scene.render(frame, input:, palette:, clipboard:, dialog:)
+#
+#   # For hit testing:
+#   rect = scene.export_rect
+#   if rect.contains?(x, y)
+#     # Handle click
+#   end
+class Scene
+  def initialize(tui)
+    @tui = tui
+    @export_area_rect = nil
+    @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+  end
+
+  # Renders the complete UI given all model objects.
+  #
+  # Calculates layout once per frame. Renders input, palette, export, controls,
+  # and dialog sections. Caches the export area rect for hit testing.
+  #
+  # [frame] Frame object from RatatuiRuby.draw block
+  # [input] Input object for text input display
+  # [palette] Palette object for color display
+  # [clipboard] Clipboard object for feedback message
+  # [dialog] CopyDialog object for confirmation dialog
+  #
+  # === Example
+  #
+  #   scene.render(frame, input: @input, palette: @palette, clipboard: @clipboard, dialog: @dialog)
+  def render(frame, input:, palette:, clipboard:, dialog:)
+    input_area, rest = @tui.layout_split(
+      frame.area,
+      direction: :vertical,
+      constraints: [
+        @tui.constraint_length(3),
+        @tui.constraint_fill(1),
+      ]
+    )
+
+    color_area, control_area = @tui.layout_split(
+      rest,
+      direction: :vertical,
+      constraints: [
+        @tui.constraint_length(14),
+        @tui.constraint_fill(1),
+      ]
+    )
+
+    harmony_area, @export_area_rect = @tui.layout_split(
+      color_area,
+      direction: :vertical,
+      constraints: [
+        @tui.constraint_length(7),
+        @tui.constraint_fill(1),
+      ]
+    )
+
+    frame.render_widget(input.render(@tui), input_area)
+    frame.render_widget(build_palette_section(palette, harmony_area), harmony_area)
+    frame.render_widget(build_export_section(palette), @export_area_rect)
+    frame.render_widget(build_controls_section(clipboard), control_area)
+
+    if dialog.active?
+      dialog_center = calculate_center_area(frame.area, 40, 8)
+      frame.render_widget(@tui.clear, frame.area)
+      frame.render_widget(dialog.render(@tui, dialog_center), dialog_center)
+    end
+  end
+
+  # The cached rectangle of the export formats section, used for hit testing.
+  #
+  # Populated during #render. Use this to detect clicks on the export section.
+  #
+  # === Example
+  #
+  #   scene.render(frame, ...)
+  #   if scene.export_rect.contains?(x, y)
+  #     # Click on export section
+  #   end
+  def export_rect
+    @export_area_rect
+  end
+
+  private def build_palette_section(palette, _harmony_area)
+    if palette.main.nil?
+      @tui.paragraph(text: "No color selected")
+    else
+      blocks = palette.as_blocks(@tui)
+      @tui.layout(
+        direction: :horizontal,
+        constraints: Array.new(blocks.size) { @tui.constraint_fill(1) },
+        children: blocks
+      )
+    end
+  end
+
+  private def build_export_section(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
+      color = palette.main
+      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
+
+  private def build_controls_section(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
+
+  private def calculate_center_area(parent_area, width, height)
+    x = (parent_area.width - width) / 2
+    y = (parent_area.height - height) / 2
+    @tui.rect(x:, y:, width:, height:)
+  end
+end

data/examples/app_login_form/app.rb

@@ -0,0 +1,108 @@
+# 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__)
+require "ratatui_ruby"
+
+class AppLoginForm
+  PREFIX = "Enter Username: [ "
+  SUFFIX = " ]"
+
+  def initialize
+    @username = ""
+    @show_popup = false
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def render
+    # 1. Base Layer Construction
+    # We want a cursor relative to the paragraph.
+    # So we wrap Paragraph and Cursor in an Overlay, and put that Overlay in a Center.
+
+    # Calculate cursor position
+    # Border takes 1 cell.
+    # Cursor X = 1 (border) + PREFIX.length + username.length
+    # Cursor Y = 1 (border + line 0)
+    cursor_x = 1 + PREFIX.length + @username.length
+    cursor_y = 1
+
+    # The content of the base form
+    form_content = @tui.overlay(layers: [
+      @tui.paragraph(
+        text: "#{PREFIX}#{@username}#{SUFFIX}",
+        block: @tui.block(borders: :all, title: "Login Form"),
+        alignment: :left
+      ),
+      @tui.cursor(x: cursor_x, y: cursor_y),
+    ])
+
+    # Center the form on screen
+    base_layer = @tui.center(
+      child: form_content,
+      width_percent: 50,
+      height_percent: 20
+    )
+
+    # 2. Popup Layer Construction
+    final_view = if @show_popup
+      popup_message = @tui.center(
+        child: @tui.paragraph(
+          text: "Login Successful!\nPress 'q' to quit.",
+          style: @tui.style(fg: :green, bg: :black),
+          block: @tui.block(borders: :all),
+          alignment: :center,
+          wrap: true
+        ),
+        width_percent: 30,
+        height_percent: 20
+      )
+
+      # Render Base Layer (background) THEN Popup Layer
+      @tui.overlay(layers: [base_layer, popup_message])
+    else
+      base_layer
+    end
+
+    # 3. Draw
+    @tui.draw do |frame|
+      frame.render_widget(final_view, frame.area)
+    end
+  end
+
+  private def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      return :quit if @show_popup
+      nil
+    in { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in { type: :key, code: "enter" }
+      @show_popup ||= true
+      nil
+    in { type: :key, code: "backspace" }
+      @username.chop! unless @show_popup
+      nil
+    in { type: :key, code: "esc" }
+      :quit unless @show_popup
+    in { type: :key, code:, modifiers: [] }
+      # Simple text input (single character, no modifiers)
+      @username += code if !@show_popup && code.length == 1
+      nil
+    else
+      nil
+    end
+  end
+end
+
+AppLoginForm.new.run if __FILE__ == $0

data/examples/app_map_demo/app.rb

@@ -0,0 +1,93 @@
+# 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__)
+require "ratatui_ruby"
+
+# An example of the Canvas widget showing a world map and animated shapes.
+class AppMapDemo
+  include RatatuiRuby
+
+  COLORS = [:black, :blue, :white, nil].freeze
+  MARKERS = [:braille, :half_block, :dot, :block, :bar, :quadrant, :sextant, :octant].freeze
+
+  # Returns a Canvas view for the map demo with the given circle radius.
+  #
+  # +tui+:: The RatatuiRuby::Session instance.
+  # +radius+:: The radius of the animated circle.
+  # +marker+:: The marker type.
+  # +background_color+:: The background color of the canvas.
+  # +show_labels+:: Whether to show city labels.
+  def view(tui, radius, marker = :braille, background_color = nil, show_labels: true)
+    shapes = [
+      tui.shape_map(color: :green, resolution: :high),
+      tui.shape_circle(x: 0.0, y: 0.0, radius:, color: :red),
+      tui.shape_line(x1: 0.0, y1: 0.0, x2: 50.0, y2: 25.0, color: :yellow),
+    ]
+
+    if show_labels
+      shapes += [
+        tui.shape_label(x: -0.1, y: 51.5, text: "London", style: tui.style(fg: :cyan)),
+        tui.shape_label(x: 139.7, y: 35.7, text: "Tokyo", style: tui.style(fg: :magenta)),
+        tui.shape_label(x: -74.0, y: 40.7, text: "New York", style: tui.style(fg: :yellow)),
+        tui.shape_label(x: -122.4, y: 37.8, text: "San Francisco", style: tui.style(fg: :blue)),
+        tui.shape_label(x: 151.2, y: -33.9, text: "Sydney", style: tui.style(fg: :green)),
+      ]
+    end
+
+    tui.canvas(
+      shapes:,
+      x_bounds: [-180.0, 180.0],
+      y_bounds: [-90.0, 90.0],
+      marker:,
+      block: tui.block(title: "World Map ['b' bg, 'm' marker: #{marker}, 'l' labels: #{show_labels ? 'on' : 'off'}]", borders: :all),
+      background_color:
+    )
+  end
+
+  # Runs the map demo loop.
+  def run
+    RatatuiRuby.run do |tui|
+      radius = 0.0
+      direction = 1
+      bg_index = 0
+      marker_index = 0
+      show_labels = true
+
+      loop do
+        # Animate the circle radius
+        radius += 0.5 * direction
+        if radius > 10.0 || radius < 0.0
+          direction *= -1
+        end
+
+        # Define the view
+        canvas = view(tui, radius, MARKERS[marker_index], COLORS[bg_index], show_labels:)
+
+        tui.draw do |frame|
+          frame.render_widget(canvas, frame.area)
+        end
+
+        event = tui.poll_event
+        case event
+        in { type: :key, code: "q" } | { type: :key, code: :ctrl_c }
+          break
+        in type: :key, code: "b"
+          bg_index = (bg_index + 1) % COLORS.size
+        in type: :key, code: "m"
+          marker_index = (marker_index + 1) % MARKERS.size
+        in type: :key, code: "l"
+          show_labels = !show_labels
+        else
+          # Ignore other events
+        end
+
+        sleep 0.05
+      end
+    end
+  end
+end
+
+AppMapDemo.new.run if __FILE__ == $PROGRAM_NAME