ratatui_ruby 0.5.0 → 0.7.0

data/examples/widget_cell_demo/app.rb

@@ -9,15 +9,19 @@ require "ratatui_ruby"
 
 # A custom widget that fills its area with a checkered pattern using Cell objects.
 class CheckeredBackground
+  def initialize(tui)
+    @tui = tui
+  end
+
   def render(area)
-    cell = RatatuiRuby::Cell.new(char: "░", fg: :dark_gray)
+    cell = @tui.cell(char: "░", fg: :dark_gray)
     commands = []
     area.height.times do |y|
       area.width.times do |x|
         # Checkerboard logic
         if (x + y).even?
           # Use a dim cell for the background pattern
-          commands << RatatuiRuby::Draw.cell(area.x + x, area.y + y, cell)
+          commands << @tui.draw_cell(area.x + x, area.y + y, cell)
         end
       end
     end
@@ -26,12 +30,13 @@ class CheckeredBackground
 end
 
 class WidgetCellDemo
-  def main
+  def run
     RatatuiRuby.run do |tui|
+      @tui = tui
       # Define some reusable cells for our table
-      ok_cell = RatatuiRuby::Cell.new(char: "OK", fg: :green)
-      fail_cell = RatatuiRuby::Cell.new(char: "FAIL", fg: :red, modifiers: ["bold"])
-      pending_cell = RatatuiRuby::Cell.new(char: "...", fg: :yellow, modifiers: ["dim"])
+      ok_cell = @tui.cell(char: "OK", fg: :green)
+      fail_cell = @tui.cell(char: "FAIL", fg: :red, modifiers: ["bold"])
+      pending_cell = @tui.cell(char: "...", fg: :yellow, modifiers: ["dim"])
 
       # A mix of Strings and Cells in rows
       rows = [
@@ -39,47 +44,47 @@ class WidgetCellDemo
         ["Cache", ok_cell],
         ["Worker", fail_cell],
         ["Analytics", pending_cell],
-        ["Web Server", RatatuiRuby::Cell.new(char: "RESTARTING", fg: :blue, modifiers: ["rapid_blink"])],
+        ["Web Server", @tui.cell(char: "RESTARTING", fg: :blue, modifiers: ["rapid_blink"])],
       ]
 
-      table = RatatuiRuby::Table.new(
-        header: ["Service", RatatuiRuby::Cell.new(char: "Status", modifiers: ["underlined"])],
+      table = @tui.table(
+        header: ["Service", @tui.cell(char: "Status", modifiers: ["underlined"])],
         rows:,
         widths: [
-          RatatuiRuby::Constraint.percentage(70),
-          RatatuiRuby::Constraint.percentage(30),
+          @tui.constraint_percentage(70),
+          @tui.constraint_percentage(30),
         ],
-        block: RatatuiRuby::Block.new(title: "System Status", borders: :all),
+        block: @tui.block(title: "System Status", borders: :all),
         column_spacing: 1
       )
 
       # Main loop
       loop do
-        tui.draw do |frame|
+        @tui.draw do |frame|
           # Create a layout that holds both widgets
           # We use a vertical layout:
           # Top: Custom CheckeredBackground with specific height
           # Bottom: Table using remaining space
-          top_area, bottom_area = RatatuiRuby::Layout.split(
+          top_area, bottom_area = @tui.layout_split(
             frame.area,
             direction: :vertical,
             constraints: [
-              RatatuiRuby::Constraint.length(10), # Top section
-              RatatuiRuby::Constraint.min(0), # Bottom section
+              @tui.constraint_length(10), # Top section
+              @tui.constraint_min(0), # Bottom section
             ]
           )
 
           # Top Child: An Overlay of Paragraph on top of CheckeredBackground
-          overlay = RatatuiRuby::Overlay.new(
+          overlay = @tui.overlay(
             layers: [
-              CheckeredBackground.new,
-              RatatuiRuby::Center.new(
+              CheckeredBackground.new(@tui),
+              @tui.center(
                 width_percent: 50,
                 height_percent: 50,
-                child: RatatuiRuby::Paragraph.new(
+                child: @tui.paragraph(
                   text: "Custom Widget Demo\n(CheckeredBackground)",
                   alignment: :center,
-                  block: RatatuiRuby::Block.new(borders: :all, title: "Overlay")
+                  block: @tui.block(borders: :all, title: "Overlay")
                 )
               ),
             ]
@@ -90,9 +95,11 @@ class WidgetCellDemo
           frame.render_widget(table, bottom_area)
         end
 
-        event = RatatuiRuby.poll_event
-        if event.is_a?(RatatuiRuby::Event::Key) && (event.code == "q" || (event.code == "c" && event.modifiers.include?("ctrl")))
+        case @tui.poll_event
+        in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
           break
+        else
+          nil
         end
       end
     end
@@ -100,5 +107,5 @@ class WidgetCellDemo
 end
 
 if __FILE__ == $0
-  WidgetCellDemo.new.main
+  WidgetCellDemo.new.run
 end

data/examples/widget_center_demo/README.md

@@ -0,0 +1,29 @@
+# Center Widget Demo
+
+[![widget_center_demo](../../doc/images/widget_center_demo.png)](app.rb)
+
+<!--
+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
+## 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
+
+[![widget_chart_demo](../../doc/images/widget_chart_demo.png)](app.rb)
+
+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.

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
+
+[![widget_gauge_demo](../../doc/images/widget_gauge_demo.png)](app.rb)
+
+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.

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
+
+[![widget_layout_split](../../doc/images/widget_layout_split.png)](app.rb)
+
+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.

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
+
+[![widget_line_gauge_demo](../../doc/images/widget_line_gauge_demo.png)](app.rb)
+
+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.

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
+
+[![widget_list_demo](../../doc/images/widget_list_demo.png)](app.rb)
+
+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.