ratatui_ruby 0.4.0 → 0.6.0

data/examples/widget_gauge_demo/app.rb

@@ -0,0 +1,212 @@
+# 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 completion visualization with interactive attribute cycling.
+#
+# Long-running tasks create anxiety. Users need to know that the system is working and how much is left to do.
+#
+# This demo showcases the <tt>Gauge</tt> widget. It provides an interactive playground where you can cycle through different ratios, colors, and label templates in real-time.
+#
+# Use it to understand how to communicate progress and task status in your terminal interface.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_gauge_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_gauge_demo.png
+class WidgetGaugeDemo
+  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 = nil # Initialized in run when @tui is available
+    @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
+    @hotkey_style = nil # Initialized in run when @tui is available
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+
+      # Initialize styles using tui helpers
+      @bg_styles = [
+        { name: "None", style: nil },
+        { name: "Dark Gray BG", style: tui.style(fg: :dark_gray) },
+        { name: "White on Black", style: tui.style(fg: :white, bg: :black) },
+        { name: "Bold White", style: tui.style(fg: :white, modifiers: [:bold]) },
+      ]
+      @hotkey_style = tui.style(modifiers: [:bold, :underlined])
+
+      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 = @tui.style(fg: gauge_color)
+    label = label_template.call(@ratio)
+
+    @tui.draw do |frame|
+      # Split into main content and control panel
+      main_area, controls_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(6),
+        ]
+      )
+
+      # Split main area into title, gauges, and spacer
+      title_area, gauge1_area, gauge2_area, gauge3_area, spacer_area = @tui.layout_split(
+        main_area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_length(1),
+          @tui.constraint_fill(1),
+          @tui.constraint_fill(1),
+          @tui.constraint_fill(1),
+          @tui.constraint_length(1),
+        ]
+      )
+
+      # Render title
+      title = @tui.paragraph(
+        text: "Gauge Widget Demo",
+        style: @tui.style(modifiers: [:bold])
+      )
+      frame.render_widget(title, title_area)
+
+      # Gauge 1: Main interactive gauge
+      gauge1 = @tui.gauge(
+        ratio: @ratio,
+        label:,
+        style: bg_style,
+        gauge_style:,
+        use_unicode:,
+        block: @tui.block(title: "Interactive Gauge")
+      )
+      frame.render_widget(gauge1, gauge1_area)
+
+      # Gauge 2: Inverse ratio for comparison
+      gauge2 = @tui.gauge(
+        ratio: 1.0 - @ratio,
+        label: label_template.call(1.0 - @ratio),
+        style: bg_style,
+        gauge_style:,
+        use_unicode:,
+        block: @tui.block(title: "Inverse (1.0 - ratio)")
+      )
+      frame.render_widget(gauge2, gauge2_area)
+
+      # Gauge 3: Fixed at different stages
+      gauge3 = @tui.gauge(
+        ratio: [@ratio, 0.5].max,
+        label: "Min 50%",
+        style: @tui.style(fg: :dark_gray),
+        gauge_style: @tui.style(fg: :magenta),
+        use_unicode:,
+        block: @tui.block(title: "Min Threshold (Magenta)")
+      )
+      frame.render_widget(gauge3, gauge3_area)
+
+      # Render empty spacer
+      spacer = @tui.paragraph(text: "")
+      frame.render_widget(spacer, spacer_area)
+
+      # Bottom controls panel
+      controls = @tui.block(
+        title: "Controls",
+        borders: [:all],
+        children: [
+          @tui.paragraph(
+            text: [
+              # Navigation & General
+              @tui.text_line(spans: [
+                @tui.text_span(content: "←/→", style: @hotkey_style),
+                @tui.text_span(content: ": Adjust Ratio (#{format('%.2f', @ratio)})  "),
+                @tui.text_span(content: "q", style: @hotkey_style),
+                @tui.text_span(content: ": Quit"),
+              ]),
+              # Styling
+              @tui.text_line(spans: [
+                @tui.text_span(content: "g", style: @hotkey_style),
+                @tui.text_span(content: ": Color (#{@gauge_colors[@gauge_color_index][:name]})  "),
+                @tui.text_span(content: "b", style: @hotkey_style),
+                @tui.text_span(content: ": Background (#{@bg_styles[@bg_style_index][:name]})"),
+              ]),
+              # Options
+              @tui.text_line(spans: [
+                @tui.text_span(content: "u", style: @hotkey_style),
+                @tui.text_span(content: ": Unicode (#{use_unicode ? 'On' : 'Off'})  "),
+                @tui.text_span(content: "l", style: @hotkey_style),
+                @tui.text_span(content: ": Label (#{@label_modes[@label_mode_index][:name]})"),
+              ]),
+            ]
+          ),
+        ]
+      )
+      frame.render_widget(controls, controls_area)
+    end
+  end
+
+  private def handle_input
+    case @tui.poll_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
+
+WidgetGaugeDemo.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_layout_split/README.md

@@ -0,0 +1,44 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Layout Split Example
+
+Demonstrates dynamic geometry management with constraints and flex modes.
+
+Terminal screens vary in size. Hardcoded layouts break. `Layout.split` manages space dynamically, ensuring your interface adapts to any window dimension.
+
+## Features Demonstrated
+
+- **Constraints**:
+    - `Fill(n)`: Takes available space proportional to `n`.
+    - `Length(n)`: Fixed number of cells.
+    - `Percentage(n)`: Percentage of the parent area.
+    - `Min(n)`: At least `n` cells.
+    - `Ratio(x, y)`: `x/y` of the parent area.
+- **Flex Modes**: Controlling how extra space is distributed (`Start`, `End`, `Center`, `SpaceBetween`, etc.).
+- **Direction**: Splitting Vertically vs Horizontally.
+
+## Hotkeys
+
+- **d**: Toggle Direction (`direction`)
+- **f**: Cycle Flex Mode (`flex`)
+- **c**: Cycle Constraint Set (`constraints`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_layout_split/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Build responsive dashboards.
+- Create 3-column layouts where the middle content fills remaining space.
+- Center a modal dialog on the screen.
+- Distribute buttons evenly across a control bar.
+
+![Demo](/doc/images/widget_layout_split.png)

data/examples/widget_layout_split/app.rb

@@ -0,0 +1,246 @@
+# 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 dynamic geometry management with interactive cycling.
+#
+# Terminal screens vary in size. Hardcoded positions break when the window resizes. You need a way to organize space dynamically.
+#
+# This demo showcases the <tt>Layout.split</tt> mechanism. It provides an interactive playground where you can toggle directions, all seven flex modes, and various constraint types (Fill, Length, Percentage, Min, Ratio) in real-time.
+#
+# Use it to understand how to build responsive, fluid terminal interfaces that adapt to any window dimensions.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_layout_split/app.rb
+#
+# rdoc-image:/doc/images/widget_layout_split.png
+class WidgetLayoutSplit
+  DIRECTIONS = [
+    { name: "Vertical", value: :vertical },
+    { name: "Horizontal", value: :horizontal },
+  ].freeze
+
+  FLEX_MODES = [
+    { name: "Legacy", value: :legacy },
+    { name: "Start", value: :start },
+    { name: "Center", value: :center },
+    { name: "End", value: :end },
+    { name: "Space Between", value: :space_between },
+    { name: "Space Around", value: :space_around },
+    { name: "Space Evenly", value: :space_evenly },
+  ].freeze
+
+  BLOCK_COLORS = %i[red green blue].freeze
+
+  def initialize
+    @direction_index = 0
+    @flex_index = 0
+    @constraint_index = 0
+    @hotkey_style = nil
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      @hotkey_style = tui.style(modifiers: [:bold, :underlined])
+      @constraint_demos = build_constraint_demos
+
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def build_constraint_demos
+    [
+      {
+        name: "Fill (1:2:1)",
+        constraints: -> (dir) {
+          [
+            @tui.constraint_fill(1),
+            @tui.constraint_fill(2),
+            @tui.constraint_fill(1),
+          ]
+        },
+      },
+      {
+        name: "Length (10/15/10)",
+        constraints: -> (dir) {
+          [
+            @tui.constraint_length(10),
+            @tui.constraint_length(15),
+            @tui.constraint_length(10),
+          ]
+        },
+      },
+      {
+        name: "Percentage (25/50/25)",
+        constraints: -> (dir) {
+          [
+            @tui.constraint_percentage(25),
+            @tui.constraint_percentage(50),
+            @tui.constraint_percentage(25),
+          ]
+        },
+      },
+      {
+        name: "Min (5/10/5)",
+        constraints: -> (dir) {
+          [
+            @tui.constraint_min(5),
+            @tui.constraint_min(10),
+            @tui.constraint_min(5),
+          ]
+        },
+      },
+      {
+        name: "Ratio (1:4, 2:4, 1:4)",
+        constraints: -> (dir) {
+          [
+            @tui.constraint_ratio(1, 4),
+            @tui.constraint_ratio(2, 4),
+            @tui.constraint_ratio(1, 4),
+          ]
+        },
+      },
+      {
+        name: -> (dir) { (dir == :vertical) ? "Mixed (Len 3, Fill, Pct 25)" : "Mixed (Len 20, Fill, Pct 25)" },
+        constraints: -> (dir) {
+          fixed = (dir == :vertical) ? 3 : 20
+          [
+            @tui.constraint_length(fixed),
+            @tui.constraint_fill(1),
+            @tui.constraint_percentage(25),
+          ]
+        },
+      },
+    ]
+  end
+
+  private def current_direction
+    DIRECTIONS[@direction_index][:value]
+  end
+
+  private def current_flex
+    FLEX_MODES[@flex_index][:value]
+  end
+
+  private def current_constraints
+    demo = @constraint_demos[@constraint_index]
+    demo[:constraints].call(current_direction)
+  end
+
+  private def current_constraint_name
+    demo = @constraint_demos[@constraint_index]
+    name = demo[:name]
+    name.respond_to?(:call) ? name.call(current_direction) : name
+  end
+
+  private def render
+    @tui.draw do |frame|
+      # Split into main content and control panel
+      main_area, controls_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(6),
+        ]
+      )
+
+      render_demo_area(frame, main_area)
+      render_controls(frame, controls_area)
+    end
+  end
+
+  private def render_demo_area(frame, area)
+    # Split demo area into title and content
+    title_area, content_area = @tui.layout_split(
+      area,
+      direction: :vertical,
+      constraints: [
+        @tui.constraint_length(1),
+        @tui.constraint_fill(1),
+      ]
+    )
+
+    # Render title
+    title = @tui.paragraph(
+      text: "Layout.split Demo",
+      style: @tui.style(modifiers: [:bold])
+    )
+    frame.render_widget(title, title_area)
+
+    # Apply current layout settings to 3 colored blocks
+    block_areas = @tui.layout_split(
+      content_area,
+      direction: current_direction,
+      flex: current_flex,
+      constraints: current_constraints
+    )
+
+    block_areas.each_with_index do |block_area, i|
+      block = @tui.block(
+        title: "Block #{i + 1}",
+        borders: [:all],
+        border_color: BLOCK_COLORS[i % BLOCK_COLORS.length]
+      )
+      frame.render_widget(block, block_area)
+    end
+  end
+
+  private def render_controls(frame, area)
+    controls = @tui.block(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        @tui.paragraph(
+          text: [
+            # Row 1: Direction and Flex
+            @tui.text_line(spans: [
+              @tui.text_span(content: "d", style: @hotkey_style),
+              @tui.text_span(content: ": Direction (#{DIRECTIONS[@direction_index][:name]})  "),
+              @tui.text_span(content: "f", style: @hotkey_style),
+              @tui.text_span(content: ": Flex (#{FLEX_MODES[@flex_index][:name]})"),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "c", style: @hotkey_style),
+              @tui.text_span(content: ": Constraints (#{current_constraint_name})"),
+            ]),
+            # Row 3: Quit
+            @tui.text_line(spans: [
+              @tui.text_span(content: "q", style: @hotkey_style),
+              @tui.text_span(content: ": Quit"),
+            ]),
+          ]
+        ),
+      ]
+    )
+    frame.render_widget(controls, area)
+  end
+
+  private def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in type: :key, code: "d"
+      @direction_index = (@direction_index + 1) % DIRECTIONS.length
+    in type: :key, code: "f"
+      @flex_index = (@flex_index + 1) % FLEX_MODES.length
+    in type: :key, code: "c"
+      @constraint_index = (@constraint_index + 1) % @constraint_demos.length
+    else
+      nil
+    end
+  end
+end
+
+WidgetLayoutSplit.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_line_gauge_demo/README.md

@@ -0,0 +1,41 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Line Gauge Widget Example
+
+Demonstrates compact progress bars for constrained spaces.
+
+Standard block gauges take up vertical space. Sometimes you only have one line to show status. The `LineGauge` provides a compact, high-density progress indicator.
+
+## Features Demonstrated
+
+- **Compact Rendering**: Visualizing progress in a single character height.
+- **Custom Symbols**: Replacing the standard line with Blocks, Shades, Dashes, or ASCII characters.
+- **Styling**: Independent styling for the filled (progress) and unfilled (track) portions.
+
+## Hotkeys
+
+- **Arrows (←/→)**: Adjust Ratio (`ratio`)
+- **f**: Cycle Filled Symbol (`filled_symbol`)
+- **u**: Cycle Unfilled Symbol (`unfilled_symbol`)
+- **c**: Cycle Filled Color (`filled_style`)
+- **x**: Cycle Unfilled Color (`unfilled_style`)
+- **b**: Cycle Base Style (`style`)
+- **q**: Cycle Quit
+
+## Usage
+
+```bash
+ruby examples/widget_line_gauge_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Add a progress bar to a list item or table row.
+- Create a status line at the bottom of the screen.
+- Show multiple metrics (CPU, RAM, Net) in a compact list.
+
+![Demo](/doc/images/widget_line_gauge_demo.png)