ratatui_ruby 0.3.1 → 0.4.0

data/examples/gauge_demo/app.rb

@@ -0,0 +1,182 @@
+# 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"
+
+# Demonstrates Gauge widget with interactive attribute cycling.
+class GaugeDemoApp
+  def initialize
+    @ratio = 0.65
+    @ratios = [0.0, 0.25, 0.5, 0.65, 0.8, 0.95, 1.0]
+    @ratio_index = 3
+
+    @gauge_colors = [
+      { name: "Green", color: :green },
+      { name: "Yellow", color: :yellow },
+      { name: "Red", color: :red },
+      { name: "Cyan", color: :cyan },
+      { name: "Blue", color: :blue }
+    ]
+    @gauge_color_index = 0
+
+    @bg_styles = [
+      { name: "None", style: nil },
+      { name: "Dark Gray BG", style: RatatuiRuby::Style.new(fg: :dark_gray) },
+      { name: "White on Black", style: RatatuiRuby::Style.new(fg: :white, bg: :black) },
+      { name: "Bold White", style: RatatuiRuby::Style.new(fg: :white, modifiers: [:bold]) }
+    ]
+    @bg_style_index = 1
+
+    @use_unicode_options = [true, false]
+    @use_unicode_index = 0
+
+    @label_modes = [
+      { name: "Percentage", template: ->(ratio) { "#{(ratio * 100).to_i}%" } },
+      { name: "Ratio (decimal)", template: ->(ratio) { format("%.2f", ratio) } },
+      { name: "Progress", template: ->(ratio) { "Progress: #{(ratio * 100).to_i}%" } },
+      { name: "None", template: ->(ratio) { nil } }
+    ]
+    @label_mode_index = 0
+  end
+
+  def run
+    RatatuiRuby.run do
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private
+
+  def render
+    @ratio = @ratios[@ratio_index]
+    gauge_color = @gauge_colors[@gauge_color_index][:color]
+    bg_style = @bg_styles[@bg_style_index][:style]
+    use_unicode = @use_unicode_options[@use_unicode_index]
+    label_template = @label_modes[@label_mode_index][:template]
+
+    gauge_style = RatatuiRuby::Style.new(fg: gauge_color)
+    label = label_template.call(@ratio)
+
+    layout = RatatuiRuby::Layout.new(
+      direction: :vertical,
+      constraints: [
+        RatatuiRuby::Constraint.fill(1),
+        RatatuiRuby::Constraint.length(6)
+      ],
+      children: [
+        # Main content area with multiple gauge examples
+        RatatuiRuby::Layout.new(
+          direction: :vertical,
+          constraints: [
+            RatatuiRuby::Constraint.length(1),
+            RatatuiRuby::Constraint.fill(1),
+            RatatuiRuby::Constraint.fill(1),
+            RatatuiRuby::Constraint.fill(1),
+            RatatuiRuby::Constraint.length(1)
+          ],
+          children: [
+            RatatuiRuby::Paragraph.new(
+              text: "Gauge Widget Demo",
+              style: RatatuiRuby::Style.new(modifiers: [:bold])
+            ),
+            # Gauge 1: Main interactive gauge
+            RatatuiRuby::Gauge.new(
+              ratio: @ratio,
+              label:,
+              style: bg_style,
+              gauge_style:,
+              use_unicode:,
+              block: RatatuiRuby::Block.new(title: "Interactive Gauge")
+            ),
+            # Gauge 2: Inverse ratio for comparison
+            RatatuiRuby::Gauge.new(
+              ratio: 1.0 - @ratio,
+              label: label_template.call(1.0 - @ratio),
+              style: bg_style,
+              gauge_style:,
+              use_unicode:,
+              block: RatatuiRuby::Block.new(title: "Inverse (1.0 - ratio)")
+            ),
+            # Gauge 3: Fixed at different stages
+            RatatuiRuby::Gauge.new(
+              ratio: [@ratio, 0.5].max,
+              label: "Min 50%",
+              style: RatatuiRuby::Style.new(fg: :dark_gray),
+              gauge_style: RatatuiRuby::Style.new(fg: :magenta),
+              use_unicode:,
+              block: RatatuiRuby::Block.new(title: "Min Threshold (Magenta)")
+            ),
+            RatatuiRuby::Paragraph.new(text: "")
+          ]
+        ),
+        # Bottom controls panel
+        RatatuiRuby::Block.new(
+          title: "Controls",
+          borders: [:all],
+          children: [
+            RatatuiRuby::Paragraph.new(
+              text: [
+                # Navigation & General
+                RatatuiRuby::Text::Line.new(spans: [
+                  RatatuiRuby::Text::Span.new(content: "←/→", style: RatatuiRuby::Style.new(modifiers: [:bold, :underlined])),
+                  RatatuiRuby::Text::Span.new(content: ": Adjust Ratio (#{format('%.2f', @ratio)})  "),
+                  RatatuiRuby::Text::Span.new(content: "q", style: RatatuiRuby::Style.new(modifiers: [:bold, :underlined])),
+                  RatatuiRuby::Text::Span.new(content: ": Quit")
+                ]),
+                # Styling
+                RatatuiRuby::Text::Line.new(spans: [
+                  RatatuiRuby::Text::Span.new(content: "g", style: RatatuiRuby::Style.new(modifiers: [:bold, :underlined])),
+                  RatatuiRuby::Text::Span.new(content: ": Color (#{@gauge_colors[@gauge_color_index][:name]})  "),
+                  RatatuiRuby::Text::Span.new(content: "b", style: RatatuiRuby::Style.new(modifiers: [:bold, :underlined])),
+                  RatatuiRuby::Text::Span.new(content: ": Background (#{@bg_styles[@bg_style_index][:name]})")
+                ]),
+                # Options
+                RatatuiRuby::Text::Line.new(spans: [
+                  RatatuiRuby::Text::Span.new(content: "u", style: RatatuiRuby::Style.new(modifiers: [:bold, :underlined])),
+                  RatatuiRuby::Text::Span.new(content: ": Unicode (#{use_unicode ? 'On' : 'Off'})  "),
+                  RatatuiRuby::Text::Span.new(content: "l", style: RatatuiRuby::Style.new(modifiers: [:bold, :underlined])),
+                  RatatuiRuby::Text::Span.new(content: ": Label (#{@label_modes[@label_mode_index][:name]})")
+                ])
+              ]
+            )
+          ]
+        )
+      ]
+    )
+
+    RatatuiRuby.draw(layout)
+  end
+
+  def handle_input
+    event = RatatuiRuby.poll_event
+    return unless event
+
+    case event
+    in {type: :key, code: "q"} | {type: :key, code: "c", modifiers: ["ctrl"]}
+      :quit
+    in type: :key, code: "right"
+      @ratio_index = (@ratio_index + 1) % @ratios.length
+    in type: :key, code: "left"
+      @ratio_index = (@ratio_index - 1) % @ratios.length
+    in type: :key, code: "g"
+      @gauge_color_index = (@gauge_color_index + 1) % @gauge_colors.length
+    in type: :key, code: "b"
+      @bg_style_index = (@bg_style_index + 1) % @bg_styles.length
+    in type: :key, code: "u"
+      @use_unicode_index = (@use_unicode_index + 1) % @use_unicode_options.length
+    in type: :key, code: "l"
+      @label_mode_index = (@label_mode_index + 1) % @label_modes.length
+    else
+      # Ignore other events
+      nil
+    end
+  end
+end
+
+GaugeDemoApp.new.run if __FILE__ == $PROGRAM_NAME

data/examples/gauge_demo/app.rbs

@@ -0,0 +1,7 @@
+class SystemMonitorApp
+  # @public
+  def self.new: () -> SystemMonitorApp
+
+  # @public
+  def run: () -> void
+end

data/examples/gauge_demo/test_app.rb

@@ -0,0 +1,120 @@
+# 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"
+require "ratatui_ruby/test_helper"
+require "minitest/autorun"
+require_relative "app"
+
+class TestGaugeDemo < Minitest::Test
+  include RatatuiRuby::TestHelper
+
+  def setup
+    @app = GaugeDemoApp.new
+  end
+
+  def test_initial_render
+    with_test_terminal do
+      inject_key(:q)
+      @app.run
+
+      content = buffer_content.join("\n")
+      assert_includes content, "Interactive Gauge"
+      assert_includes content, "Inverse"
+      assert_includes content, "Min Threshold"
+    end
+  end
+
+  def test_ratio_increment
+    with_test_terminal do
+      inject_key(:right)
+      inject_key(:q)
+      @app.run
+
+      content = buffer_content.join("\n")
+      # After pressing right from index 3 (0.65), should be at index 4 (0.80)
+      assert_includes content, "0.80"
+    end
+  end
+
+  def test_ratio_decrement
+    with_test_terminal do
+      inject_key(:left)
+      inject_key(:q)
+      @app.run
+
+      content = buffer_content.join("\n")
+      # After pressing left from index 3 (0.65), should be at index 2 (0.50)
+      assert_includes content, "0.50"
+    end
+  end
+
+  def test_gauge_color_cycling
+    with_test_terminal do
+      inject_key(:g)
+      inject_key(:q)
+      @app.run
+
+      content = buffer_content.join("\n")
+      # After pressing g from index 0 (Green), should be at index 1 (Yellow)
+      assert_includes content, "Yellow"
+      refute_includes content, "Green"
+    end
+  end
+
+  def test_background_style_cycling
+    with_test_terminal do
+      inject_key(:b)
+      inject_key(:q)
+      @app.run
+
+      content = buffer_content.join("\n")
+      # After pressing b from index 1 (Dark Gray BG), should be at index 2 (White on Black)
+      assert_includes content, "White on Black"
+      refute_includes content, "Dark Gray BG"
+    end
+  end
+
+  def test_unicode_toggle
+    with_test_terminal do
+      inject_key(:u)
+      inject_key(:q)
+      @app.run
+
+      content = buffer_content.join("\n")
+      # After toggling unicode, should still show gauge controls
+      assert_includes content, "Off"
+    end
+  end
+
+  def test_label_mode_cycling
+    with_test_terminal do
+      inject_key(:l)
+      inject_key(:q)
+      @app.run
+
+      content = buffer_content.join("\n")
+      # After pressing l from index 0 (Percentage), should be at index 1 (Ratio decimal)
+      # The gauge should show decimal format instead of percentage
+      assert_includes content, "0.65"
+    end
+  end
+
+  def test_multiple_interactions
+    with_test_terminal do
+      inject_keys(:right, :g, :b, :u, :l, :q)
+      @app.run
+
+      content = buffer_content.join("\n")
+      # Verify all controls are visible
+      assert_includes content, "Adjust Ratio"
+      assert_includes content, "Color"
+      assert_includes content, "Background"
+      assert_includes content, "Unicode"
+      assert_includes content, "Label"
+    end
+  end
+end

data/examples/hit_test/app.rb

@@ -0,0 +1,175 @@
+# 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"
+
+# Demonstrates hit testing using Layout.split with the Cached Layout Pattern.
+#
+# This example shows how to calculate layout regions *once per frame* and reuse
+# those regions for both rendering and hit testing. This is essential for
+# immediate-mode UI development where the same layout is used by multiple
+# subsystems (render, event handling, etc.).
+#
+# Controls:
+#   - Left/Right arrows: Adjust split ratio
+#   - Click: Detect which panel was clicked
+#   - q: Quit
+class HitTestApp
+  def initialize
+    @left_ratio = 50
+    @message = "Click a panel or adjust ratio"
+    @last_click = nil
+    @hotkey_style = RatatuiRuby::Style.new(modifiers: [:bold, :underlined])
+  end
+
+  def run
+    RatatuiRuby.run do
+      loop do
+        calculate_layout  # Phase 1: Layout calculation (once per frame)
+        render            # Phase 2: Draw to terminal
+        break if handle_input == :quit  # Phase 3: Consume input using cached rects
+      end
+    end
+  end
+
+  private
+
+  def calculate_layout
+    # Single source of truth for layout geometry.
+    # Calculated once per frame, then reused by render() and handle_input().
+    full_area = RatatuiRuby::Rect.new(x: 0, y: 0, width: 80, height: 24)
+
+    # First split: main content vs bottom controls.
+    @main_area, @control_area = RatatuiRuby::Layout.split(
+      full_area,
+      direction: :vertical,
+      constraints: [
+        RatatuiRuby::Constraint.fill(1),
+        RatatuiRuby::Constraint.length(7),
+      ]
+    )
+
+    # Second split: within main content, left vs right panels.
+    @left_rect, @right_rect = RatatuiRuby::Layout.split(
+      @main_area,
+      direction: :horizontal,
+      constraints: [
+        RatatuiRuby::Constraint.percentage(@left_ratio),
+        RatatuiRuby::Constraint.percentage(100 - @left_ratio)
+      ]
+    )
+  end
+
+  def render
+    # Build UI with the pre-calculated regions
+    left_panel = build_panel("Left Panel", @left_rect, @last_click == :left)
+    right_panel = build_panel("Right Panel", @right_rect, @last_click == :right)
+
+    layout = RatatuiRuby::Layout.new(
+      direction: :horizontal,
+      constraints: [
+        RatatuiRuby::Constraint.percentage(@left_ratio),
+        RatatuiRuby::Constraint.percentage(100 - @left_ratio)
+      ],
+      children: [left_panel, right_panel]
+    )
+
+    # Bottom control panel
+    control_panel = RatatuiRuby::Block.new(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        RatatuiRuby::Paragraph.new(
+          text: [
+            RatatuiRuby::Text::Line.new(spans: [
+              RatatuiRuby::Text::Span.new(content: "RATIO", style: RatatuiRuby::Style.new(modifiers: [:bold]))
+            ]),
+            RatatuiRuby::Text::Line.new(spans: [
+              RatatuiRuby::Text::Span.new(content: "←", style: @hotkey_style),
+              RatatuiRuby::Text::Span.new(content: ": Decrease (#{@left_ratio}%)  "),
+              RatatuiRuby::Text::Span.new(content: "→", style: @hotkey_style),
+              RatatuiRuby::Text::Span.new(content: ": Increase (#{@left_ratio}%)  "),
+              RatatuiRuby::Text::Span.new(content: "q", style: @hotkey_style),
+              RatatuiRuby::Text::Span.new(content: ": Quit")
+            ]),
+            RatatuiRuby::Text::Line.new(spans: [
+              RatatuiRuby::Text::Span.new(content: "HIT TESTING", style: RatatuiRuby::Style.new(modifiers: [:bold]))
+            ]),
+            "Click panels above to detect hits.",
+            "Last Click: #{@last_click || 'None'} - #{@message}"
+          ]
+        )
+      ]
+    )
+
+    # Full layout with bottom controls
+    full_layout = RatatuiRuby::Layout.new(
+      direction: :vertical,
+      constraints: [
+        RatatuiRuby::Constraint.fill(1),
+        RatatuiRuby::Constraint.length(7),
+      ],
+      children: [layout, control_panel]
+    )
+
+    RatatuiRuby.draw(full_layout)
+  end
+
+  def build_panel(title, rect, active)
+    content = "#{title}\n\n" \
+              "Width: #{rect.width}, Height: #{rect.height}\n" \
+              "Position: (#{rect.x}, #{rect.y})"
+
+    RatatuiRuby::Paragraph.new(
+      text: content,
+      alignment: :center,
+      block: RatatuiRuby::Block.new(
+        title: "#{title} (#{active ? 'CLICKED' : 'idle'})",
+        borders: [:all],
+        border_color: active ? "green" : "white"
+      )
+    )
+  end
+
+  def handle_input
+    event = RatatuiRuby.poll_event
+    return unless event
+
+    case event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      return :quit
+    in type: :key, code: "left"
+      @left_ratio = [@left_ratio - 10, 10].max
+      @message = "Ratio: #{@left_ratio}% / #{100 - @left_ratio}%"
+      @last_click = nil
+    in type: :key, code: "right"
+      @left_ratio = [@left_ratio + 10, 90].min
+      @message = "Ratio: #{@left_ratio}% / #{100 - @left_ratio}%"
+      @last_click = nil
+    in type: :mouse, kind: "down", x: click_x, y: click_y
+      handle_click(click_x, click_y)
+    else
+      @message = "Unhandled: #{event.class} #{event.inspect}"
+      nil
+    end
+    nil
+  end
+
+  def handle_click(x, y)
+    if @left_rect.contains?(x, y)
+      @last_click = :left
+      @message = "Left Panel clicked at (#{x}, #{y})"
+    elsif @right_rect.contains?(x, y)
+      @last_click = :right
+      @message = "Right Panel clicked at (#{x}, #{y})"
+    else
+      @last_click = nil
+      @message = "Clicked outside panels at (#{x}, #{y})"
+    end
+  end
+end
+
+HitTestApp.new.run if __FILE__ == $0

data/examples/hit_test/app.rbs

@@ -0,0 +1,7 @@
+class HitTestApp
+  # @public
+  def self.new: () -> HitTestApp
+
+  # @public
+  def run: () -> void
+end

data/examples/hit_test/test_app.rb

@@ -0,0 +1,102 @@
+# 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"
+require "ratatui_ruby/test_helper"
+require "minitest/autorun"
+require_relative "app"
+
+class TestHitTestExample < Minitest::Test
+  include RatatuiRuby::TestHelper
+
+  def setup
+    @app = HitTestApp.new
+  end
+
+  def test_initial_render_shows_both_panels
+    with_test_terminal do
+      inject_key(:q)
+      @app.run
+
+      content = buffer_content
+      assert content.any? { |line| line.include?("Left Panel") }
+      assert content.any? { |line| line.include?("Right Panel") }
+    end
+  end
+
+  def test_left_panel_click
+    with_test_terminal do
+      # Click in left half at x=10, then quit
+      inject_event(RatatuiRuby::Event::Mouse.new(kind: "down", button: "left", x: 10, y: 12))
+      inject_key(:q)
+
+      @app.run
+
+      content = buffer_content
+      # Check both status line and debug message
+      assert content.any? { |line| line.include?("Last Click: left") }
+      assert content.any? { |line| line.include?("Left Panel clicked") }
+    end
+  end
+
+  def test_right_panel_click
+    with_test_terminal do
+      # Click in right half at x=50, then quit
+      inject_event(RatatuiRuby::Event::Mouse.new(kind: "down", button: "left", x: 50, y: 12))
+      inject_key(:q)
+
+      @app.run
+
+      content = buffer_content
+      assert content.any? { |line| line.include?("Last Click: right") }
+      assert content.any? { |line| line.include?("Right Panel clicked") }
+    end
+  end
+
+  def test_ratio_change_decreases_left
+    with_test_terminal do
+      # Shrink left panel using left arrow
+      inject_keys("left", :q)
+      @app.run
+
+      content = buffer_content
+      assert content.any? { |line| line.include?("40%") }
+    end
+  end
+
+  def test_ratio_change_increases_left
+    with_test_terminal do
+      # Expand left panel using right arrow
+      inject_keys("right", :q)
+      @app.run
+
+      content = buffer_content
+      assert content.any? { |line| line.include?("60%") }
+    end
+  end
+
+  def test_ratio_minimum_boundary
+    with_test_terminal do
+      # Try to go below 10%
+      inject_keys("left", "left", "left", "left", "left", :q)
+      @app.run
+
+      content = buffer_content
+      assert content.any? { |line| line.include?("10%") }
+    end
+  end
+
+  def test_ratio_maximum_boundary
+    with_test_terminal do
+      # Try to go above 90%
+      inject_keys("right", "right", "right", "right", "right", "right", "right", "right", "right", :q)
+      @app.run
+
+      content = buffer_content
+      assert content.any? { |line| line.include?("90%") }
+    end
+  end
+end