ratatui_ruby 0.5.0 → 0.6.0

data/examples/widget_center_demo/README.md

@@ -0,0 +1,29 @@
+# Center Widget Demo
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+This example demonstrates the `Center` widget, which positions a child widget in the center of the available area.
+
+## Key Concepts
+
+- **Centering**: The widget automatically calculates the necessary padding to center its child.
+- **Sizing**: You can control the size of the centered area using `width_percent` and `height_percent`.
+- **Composition**: The `Center` widget wraps another widget (the child), making it easy to compose layouts.
+
+## Controls
+
+| Key | Action |
+| --- | --- |
+| `←` / `→` | Decrease / Increase width percentage |
+| `↑` / `↓` | Increase / Decrease height percentage |
+| `q` | Quit |
+
+## Screenshot
+
+![Screenshot of Center Widget Demo](../../doc/images/widget_center_demo.png)
+
+## Source Code
+
+- [app.rb](app.rb)

data/examples/widget_center_demo/app.rb

@@ -0,0 +1,116 @@
+# 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"
+
+# Demo: Center Widget
+# Demonstrates how to center content horizontally and vertically
+# with adjustable width/height percentages.
+class WidgetCenterDemo
+  def initialize
+    @width_percent = 50
+    @height_percent = 50
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def render
+    @tui.draw do |frame|
+      layout = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(3),
+        ]
+      )
+
+      # 1. Main Area
+      # Background block frames the centered content
+      bg_block = @tui.block(
+        title: "Center Widget Demo",
+        borders: [:all],
+        style: @tui.style(fg: :gray)
+      )
+      frame.render_widget(bg_block, layout[0])
+
+      # 2. Centered Content
+      # The content itself is just a block with some text
+      content = @tui.paragraph(
+        text: [
+          @tui.text_line(
+            spans: [
+              @tui.text_span(content: "Centered Area", style: @tui.style(modifiers: [:bold])),
+            ],
+            alignment: :center
+          ),
+          @tui.text_line(spans: []),
+          @tui.text_line(spans: [@tui.text_span(content: "Width: #{@width_percent}%", style: @tui.style(fg: :cyan))], alignment: :center),
+          @tui.text_line(spans: [@tui.text_span(content: "Height: #{@height_percent}%", style: @tui.style(fg: :magenta))], alignment: :center),
+        ],
+        block: @tui.block(
+          title: "Child Widget",
+          borders: [:all],
+          style: @tui.style(fg: :white)
+        ),
+        alignment: :center
+      )
+
+      # Create the Center widget
+      center_widget = @tui.center(
+        child: content,
+        width_percent: @width_percent,
+        height_percent: @height_percent
+      )
+
+      # Render center widget into the main layout area
+      frame.render_widget(center_widget, layout[0])
+
+      # 3. Controls
+      control_text = @tui.paragraph(
+        text: [
+          @tui.text_line(spans: [
+            @tui.text_span(content: "←/→", style: @tui.style(modifiers: [:bold, :underlined])),
+            @tui.text_span(content: ": Width  "),
+            @tui.text_span(content: "↑/↓", style: @tui.style(modifiers: [:bold, :underlined])),
+            @tui.text_span(content: ": Height  "),
+            @tui.text_span(content: "q", style: @tui.style(modifiers: [:bold, :underlined])),
+            @tui.text_span(content: ": Quit"),
+          ]),
+        ],
+        block: @tui.block(borders: [:top], style: @tui.style(bg: :black))
+      )
+      frame.render_widget(control_text, layout[1])
+    end
+  end
+
+  def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in { type: :key, code: "left" }
+      @width_percent = [@width_percent - 5, 5].max
+    in { type: :key, code: "right" }
+      @width_percent = [@width_percent + 5, 100].min
+    in { type: :key, code: "up" }
+      @height_percent = [@height_percent + 5, 100].min
+    in { type: :key, code: "down" }
+      @height_percent = [@height_percent - 5, 5].max
+    else
+      # Ignore other events
+    end
+  end
+end
+
+WidgetCenterDemo.new.run if __FILE__ == $0

data/examples/widget_chart_demo/README.md

@@ -0,0 +1,41 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Chart Widget Example
+
+Demonstrates Cartesian plotting with interactive styling and configuration.
+
+Trends and patterns are invisible in raw logs. Charts visualize X/Y datasets to reveal the story behind the data.
+
+## Features Demonstrated
+
+- **Dataset Types**: Line charts and Scatter plots.
+- **Markers**: Braille patterns, dots, blocks, and bars.
+- **Axis Configuration**: Controlling labels, bounds, and alignment (Left/Center/Right).
+- **Legend**: Positioning the legend in any of the four corners or hiding it based on constraints.
+
+## Hotkeys
+
+- **m**: Cycle Marker Type (`marker`)
+- **s**: Cycle Dataset Style (`style`)
+- **x**: Cycle X-Axis Alignment (`labels_alignment`)
+- **y**: Cycle Y-Axis Alignment (`labels_alignment`)
+- **l**: Cycle Legend Position (`legend_position`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_chart_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Plot real-time data monitoring (CPU history, request latency).
+- Visualize mathematical functions.
+- Compare multiple datasets on the same axis.
+
+![Demo](/doc/images/widget_chart_demo.png)

data/examples/widget_chart_demo/app.rb

@@ -53,6 +53,11 @@ class WidgetChartDemo
       @tui = tui
       init_styles
 
+      # Support seeded random for deterministic testing
+      # Set RATA_SEED=42 for reproducible scatter plot data
+      seed = ENV.fetch("RATA_SEED", nil)
+      @rng = seed ? Random.new(seed.to_i) : Random.new
+
       @marker_index = 0
       @dataset_style_index = 0
       @x_alignment_index = 1
@@ -89,9 +94,9 @@ class WidgetChartDemo
       [x, Math.sin(x)]
     end
 
-    # Scatter: Random points
+    # Scatter: Random points (deterministic when RATA_SEED is set)
     scatter_data = (0..20).map do |_|
-      [rand(0.0..10.0), rand(-1.0..1.0)]
+      [@rng.rand(0.0..10.0), @rng.rand(-1.0..1.0)]
     end
 
     style = @dataset_styles[@dataset_style_index][:style]

data/examples/widget_gauge_demo/README.md

@@ -0,0 +1,41 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Gauge Widget Example
+
+Demonstrates progress bars with interactive configuration.
+
+Long-running tasks create anxiety. Users need to know the system is working. Gauges provide visual feedback on completion status.
+
+## Features Demonstrated
+
+- **Progress styles**: standard block characters or Unicode bars.
+- **Labels**: Customizing the text overlay (Percentage, Ratio, etc.).
+- **Styling**: Independent control of the filled gauge color and the background track.
+- **Thresholds**: Implementing multi-colored gauges based on values.
+
+## Hotkeys
+
+- **Arrows (←/→)**: Adjust Ratio (`ratio`)
+- **g**: Cycle Gauge Color (`gauge_style`)
+- **b**: Cycle Background Style (`style`)
+- **u**: Toggle Unicode Mode (`use_unicode`)
+- **l**: Cycle Label Mode (`label`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_gauge_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Show download or upload progress.
+- Visualize resource quotas (disk space, memory usage).
+- Create "health bars" or status indicators.
+
+![Demo](/doc/images/widget_gauge_demo.png)

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_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)

data/examples/widget_list_demo/README.md

@@ -0,0 +1,49 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# List Widget Example
+
+Demonstrates a selectable list with extensive configuration options.
+
+Lists are the workhorse of terminal interfaces. Managing selection state, scrolling windows, and highlight styles logic is complex. The `List` widget handles all of this.
+
+## Features Demonstrated
+
+- **Scrolling**: Automatically handles lists larger than the view area.
+- **Selection**: Maintains selected index and supports "no selection" state.
+- **Highlighting**: Custom styles and symbols (e.g., `>>`) for the selected item.
+- **Offset Modes**: Manual control over the scroll offset vs automatic "scroll to selection" behavior.
+- **Scroll Padding**: Keeping a margin of items visible above/below the selection.
+
+## Hotkeys
+
+- **i**: Cycle Item Data (`items`)
+- **Arrow Keys (↑/↓)**: Navigate (`selected_index`)
+- **x**: Toggle Selection (`selected_index`)
+- **h**: Cycle Highlight Style (`highlight_style`)
+- **y**: Cycle Highlight Symbol (`highlight_symbol`)
+- **d**: Toggle Direction (`direction`)
+- **s**: Cycle Highlight Spacing (`highlight_spacing`)
+- **p**: Cycle Scroll Padding (`scroll_padding`)
+- **b**: Cycle Base Style (`style`)
+- **r**: Toggle Repeat Highlight Symbol (`repeat_highlight_symbol`)
+- **o**: Cycle Offset Mode (`offset`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_list_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Create a file explorer.
+- Build a navigation menu.
+- Display a log where users can scroll back to read history.
+- Implement "infinite select" behaviors.
+
+![Demo](/doc/images/widget_list_demo.png)

data/examples/widget_list_demo/app.rb

@@ -5,6 +5,7 @@
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
+require "faker" # Use Faker for large, realistic datasets
 
 # Demonstrates a selectable list of items with interactive attribute cycling.
 #
@@ -24,111 +25,18 @@ require "ratatui_ruby"
 class WidgetListDemo
   # Initializes the demo with example data and default configuration.
   def initialize
-    @selected_index = nil
+    Faker::Config.random = Random.new(12345)
+    @selected_index = 6 # Start at C# to avoid highlighting the rich text examples
+    @tui_for_setup = nil
 
     @item_sets = [
-      {
-        name: "Large List",
-        items: (1..200).map { |i| "Item #{i}" },
-      },
-      {
-        name: "Colors",
-        items: [
-          "Red",
-          "Orange",
-          "Yellow",
-          "Green",
-          "Cyan",
-          "Blue",
-          "Indigo",
-          "Violet",
-          "Scarlet",
-          "Crimson",
-          "Maroon",
-          "Brown",
-          "Tan",
-          "Beige",
-          "Khaki",
-          "Gold",
-          "Silver",
-          "White",
-          "Gray",
-          "Black",
-          "Pink",
-          "Magenta",
-          "Turquoise",
-          "Teal",
-          "Coral",
-          "Salmon",
-          "Peach",
-          "Lavender",
-          "Lilac",
-          "Olive",
-          "Lime",
-          "Navy",
-          "Charcoal",
-          "Ivory",
-          "Azure",
-        ],
-      },
-      {
-        name: "Fruits",
-        items: [
-          "Apple",
-          "Apricot",
-          "Avocado",
-          "Banana",
-          "Blueberry",
-          "Blackberry",
-          "Cherry",
-          "Cranberry",
-          "Cucumber",
-          "Date",
-          "Dragonfruit",
-          "Elderberry",
-          "Fig",
-          "Grape",
-          "Grapefruit",
-          "Guava",
-          "Honeydew",
-          "Huckleberry",
-          "Jackfruit",
-          "Kiwi",
-          "Kumquat",
-          "Lemon",
-          "Lime",
-          "Lychee",
-          "Mango",
-          "Melon",
-          "Mulberry",
-          "Nectarine",
-          "Olive",
-          "Orange",
-          "Papaya",
-          "Passion Fruit",
-          "Peach",
-          "Pear",
-          "Persimmon",
-          "Pineapple",
-          "Plum",
-          "Pomegranate",
-          "Prune",
-          "Rambutan",
-          "Raspberry",
-          "Starfruit",
-          "Strawberry",
-          "Tangerine",
-          "Watermelon",
-          "Ugli Fruit",
-        ],
-      },
       {
         name: "Programming",
         items: [
-          "Ruby",
-          "Rust",
-          "Python",
-          "JavaScript",
+          :ruby_styled, # Will be replaced with rich text in run()
+          :rust_styled, # Will be replaced with rich text in run()
+          :python_styled, # Will be replaced with rich text in run()
+          :javascript_styled, # Will be replaced with rich text in run()
           "Go",
           "C++",
           "C#",
@@ -175,6 +83,24 @@ class WidgetListDemo
           "BASIC",
         ],
       },
+      {
+        name: "Large List",
+        items: (1..200).map { |i| "Item #{i}" },
+      },
+      {
+        name: "Colors",
+        items: begin
+          Faker::Color.unique.clear
+          Array.new(100) { Faker::Color.color_name }
+        end,
+      },
+      {
+        name: "Fruits",
+        items: begin
+          Faker::Food.unique.clear
+          Array.new(100) { Faker::Food.fruits }
+        end,
+      },
     ]
     @item_set_index = 0
 
@@ -192,7 +118,7 @@ class WidgetListDemo
       { name: "Always", spacing: :always },
       { name: "Never", spacing: :never },
     ]
-    @highlight_spacing_index = 0
+    @highlight_spacing_index = 1
 
     @repeat_modes = [
       { name: "Off", repeat: false },
@@ -205,7 +131,15 @@ class WidgetListDemo
       { name: "1 item", padding: 1 },
       { name: "2 items", padding: 2 },
     ]
-    @scroll_padding_index = 0
+    @scroll_padding_index = 1
+
+    # Offset mode configurations to demonstrate offset + selection interaction
+    @offset_modes = [
+      { name: "Auto (No Offset)", offset: nil, allow_selection: true },
+      { name: "Offset Only", offset: 10, allow_selection: false },
+      { name: "Selection + Offset (Conflict)", offset: 0, allow_selection: true },
+    ]
+    @offset_mode_index = 0
   end
 
   # Runs the demo application.
@@ -214,8 +148,45 @@ class WidgetListDemo
   def run
     RatatuiRuby.run do |tui|
       @tui = tui
+
+      # Create rich text for "Ruby" - each letter with a different red style
+      ruby_line = @tui.text_line(spans: [
+        @tui.text_span(content: "R", style: @tui.style(fg: :red, modifiers: [:underlined])),
+        @tui.text_span(content: "u", style: @tui.style(fg: :light_red, modifiers: [:bold])),
+        @tui.text_span(content: "b", style: @tui.style(fg: :red, modifiers: [:italic])),
+        @tui.text_span(content: "y", style: @tui.style(fg: :light_red, modifiers: [:reversed])),
+      ])
+
+      # Create rich text for "Rust" - single styled Span
+      rust_span = @tui.text_span(
+        content: "Rust",
+        style: @tui.style(fg: :magenta, modifiers: [:bold, :underlined])
+      )
+
+      # Create ListItem for "Python" - demonstrates content + row background
+      python_item = @tui.list_item(
+        content: @tui.text_span(content: "Python", style: @tui.style(fg: :yellow)),
+        style: @tui.style(bg: :dark_gray)
+      )
+
+      # Create ListItem for "JavaScript" - demonstrates styled text with row background
+      javascript_item = @tui.list_item(
+        content: @tui.text_line(spans: [
+          @tui.text_span(content: "Java", style: @tui.style(fg: :yellow, modifiers: [:bold])),
+          @tui.text_span(content: "Script", style: @tui.style(fg: :light_yellow, modifiers: [:italic])),
+        ]),
+        style: @tui.style(bg: :blue)
+      )
+
+      # Replace the styled placeholders
+      @item_sets[0][:items][0] = ruby_line
+      @item_sets[0][:items][1] = rust_span
+      @item_sets[0][:items][2] = python_item
+      @item_sets[0][:items][3] = javascript_item
+
       # Initialize styles that require @tui
       @highlight_styles = [
+        { name: "Blue on White Bold", style: @tui.style(fg: :blue, bg: :white, modifiers: [:bold]) },
         { name: "Blue Bold", style: @tui.style(fg: :blue, modifiers: [:bold]) },
         { name: "Yellow on Black", style: @tui.style(fg: :yellow, bg: :black) },
         { name: "Green Italic", style: @tui.style(fg: :green, modifiers: [:italic]) },
@@ -245,7 +216,6 @@ class WidgetListDemo
   # :nodoc:
   private def render
     items = @item_sets[@item_set_index][:items]
-    selection_label = @selected_index.nil? ? "none" : @selected_index.to_s
     direction_config = @direction_configs[@direction_index]
     spacing_config = @highlight_spacing_configs[@highlight_spacing_index]
     repeat_config = @repeat_modes[@repeat_index]
@@ -253,6 +223,13 @@ class WidgetListDemo
     highlight_symbol = @highlight_symbol_names[@highlight_symbol_index]
     base_style_config = @base_styles[@base_style_index]
     scroll_padding_config = @scroll_padding_configs[@scroll_padding_index]
+    offset_mode_config = @offset_modes[@offset_mode_index]
+
+    # Determine selection/offset based on mode
+    effective_selection = offset_mode_config[:allow_selection] ? @selected_index : nil
+    effective_offset = offset_mode_config[:offset]
+    selection_label = effective_selection.nil? ? "none" : effective_selection.to_s
+    offset_label = effective_offset.nil? ? "auto" : effective_offset.to_s
 
     @tui.draw do |frame|
       # Split into main content and control panel
@@ -261,7 +238,7 @@ class WidgetListDemo
         direction: :vertical,
         constraints: [
           @tui.constraint_fill(1),
-          @tui.constraint_length(7),
+          @tui.constraint_length(8),
         ]
       )
 
@@ -282,7 +259,8 @@ class WidgetListDemo
       # Render list
       list = @tui.list(
         items:,
-        selected_index: @selected_index,
+        selected_index: effective_selection,
+        offset: effective_offset,
         style: base_style_config[:style],
         highlight_style: highlight_style_config[:style],
         highlight_symbol:,
@@ -291,7 +269,7 @@ class WidgetListDemo
         direction: direction_config[:direction],
         scroll_padding: scroll_padding_config[:padding],
         block: @tui.block(
-          title: "#{@item_sets[@item_set_index][:name]} (Selection: #{selection_label})",
+          title: "#{@item_sets[@item_set_index][:name]} | Sel: #{selection_label} | Offset: #{offset_label}",
           borders: [:all]
         )
       )
@@ -330,7 +308,11 @@ class WidgetListDemo
                 @tui.text_span(content: "b", style: @hotkey_style),
                 @tui.text_span(content: ": Base (#{base_style_config[:name]})  "),
                 @tui.text_span(content: "r", style: @hotkey_style),
-                @tui.text_span(content: ": Repeat (#{repeat_config[:name]})  "),
+                @tui.text_span(content: ": Repeat (#{repeat_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "o", style: @hotkey_style),
+                @tui.text_span(content: ": Offset Mode (#{offset_mode_config[:name]})  "),
                 @tui.text_span(content: "q", style: @hotkey_style),
                 @tui.text_span(content: ": Quit"),
               ]),
@@ -373,6 +355,8 @@ class WidgetListDemo
       @repeat_index = (@repeat_index + 1) % @repeat_modes.size
     in type: :key, code: "p"
       @scroll_padding_index = (@scroll_padding_index + 1) % @scroll_padding_configs.size
+    in type: :key, code: "o"
+      @offset_mode_index = (@offset_mode_index + 1) % @offset_modes.size
     else
       nil
     end