ratatui_ruby 0.4.0 → 0.6.0

data/examples/widget_cell_demo/app.rb

@@ -0,0 +1,111 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+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 = @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 << @tui.draw_cell(area.x + x, area.y + y, cell)
+        end
+      end
+    end
+    commands
+  end
+end
+
+class WidgetCellDemo
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      # Define some reusable cells for our table
+      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 = [
+        ["Database", ok_cell],
+        ["Cache", ok_cell],
+        ["Worker", fail_cell],
+        ["Analytics", pending_cell],
+        ["Web Server", @tui.cell(char: "RESTARTING", fg: :blue, modifiers: ["rapid_blink"])],
+      ]
+
+      table = @tui.table(
+        header: ["Service", @tui.cell(char: "Status", modifiers: ["underlined"])],
+        rows:,
+        widths: [
+          @tui.constraint_percentage(70),
+          @tui.constraint_percentage(30),
+        ],
+        block: @tui.block(title: "System Status", borders: :all),
+        column_spacing: 1
+      )
+
+      # Main loop
+      loop do
+        @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 = @tui.layout_split(
+            frame.area,
+            direction: :vertical,
+            constraints: [
+              @tui.constraint_length(10), # Top section
+              @tui.constraint_min(0), # Bottom section
+            ]
+          )
+
+          # Top Child: An Overlay of Paragraph on top of CheckeredBackground
+          overlay = @tui.overlay(
+            layers: [
+              CheckeredBackground.new(@tui),
+              @tui.center(
+                width_percent: 50,
+                height_percent: 50,
+                child: @tui.paragraph(
+                  text: "Custom Widget Demo\n(CheckeredBackground)",
+                  alignment: :center,
+                  block: @tui.block(borders: :all, title: "Overlay")
+                )
+              ),
+            ]
+          )
+          frame.render_widget(overlay, top_area)
+
+          # Bottom Child: The Table
+          frame.render_widget(table, bottom_area)
+        end
+
+        case @tui.poll_event
+        in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+          break
+        else
+          nil
+        end
+      end
+    end
+  end
+end
+
+if __FILE__ == $0
+  WidgetCellDemo.new.run
+end

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

@@ -0,0 +1,218 @@
+# 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 Cartesian plotting attributes with interactive cycling.
+#
+# Trends and patterns are invisible in raw logs. You need to see the shape of the data to understand the story it tells.
+#
+# This demo showcases the <tt>Chart</tt> widget. It provides an interactive playground where you can toggle marker types, axis alignments, and legend positions in real-time.
+#
+# Use it to understand how to visualize complex X/Y datasets and trends efficiently.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_chart_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_chart_demo.png
+class WidgetChartDemo
+  MARKERS = [
+    { name: "Dot (·)", marker: :dot },
+    { name: "Braille", marker: :braille },
+    { name: "Block (█)", marker: :block },
+    { name: "Bar", marker: :bar },
+  ].freeze
+
+  X_ALIGNMENTS = [
+    { name: "Left", alignment: :left },
+    { name: "Center", alignment: :center },
+    { name: "Right", alignment: :right },
+  ].freeze
+
+  Y_ALIGNMENTS = [
+    { name: "Left", alignment: :left },
+    { name: "Center", alignment: :center },
+    { name: "Right", alignment: :right },
+  ].freeze
+
+  LEGEND_POSITIONS = [
+    { name: "Top Right", position: :top_right },
+    { name: "Top Left", position: :top_left },
+    { name: "Bottom Right", position: :bottom_right },
+    { name: "Bottom Left", position: :bottom_left },
+  ].freeze
+
+  def run
+    RatatuiRuby.run do |tui|
+      @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
+      @y_alignment_index = 2
+      @legend_position_index = 0
+
+      loop do
+        render
+        break if handle_input == :quit
+        sleep 0.05
+      end
+    end
+  end
+
+  private def init_styles
+    @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+    @dataset_styles = [
+      { name: "Yellow", style: @tui.style(fg: :yellow) },
+      { name: "Green", style: @tui.style(fg: :green) },
+      { name: "Cyan", style: @tui.style(fg: :cyan) },
+      { name: "Red", style: @tui.style(fg: :red) },
+      { name: "Magenta", style: @tui.style(fg: :magenta) },
+      { name: "Bold Blue", style: @tui.style(fg: :blue, modifiers: [:bold]) },
+      { name: "Dim White", style: @tui.style(fg: :white, modifiers: [:dim]) },
+      { name: "Italic Green", style: @tui.style(fg: :green, modifiers: [:italic]) },
+      { name: "Alert (Red/White/Bar)", style: @tui.style(fg: :white, bg: :red, modifiers: [:bold]) },
+    ]
+  end
+
+  private def render
+    # Static sample data: sine wave with wider range for better visibility
+    line_data = (0..50).map do |i|
+      x = i / 5.0
+      [x, Math.sin(x)]
+    end
+
+    # Scatter: Random points (deterministic when RATA_SEED is set)
+    scatter_data = (0..20).map do |_|
+      [@rng.rand(0.0..10.0), @rng.rand(-1.0..1.0)]
+    end
+
+    style = @dataset_styles[@dataset_style_index][:style]
+    # Ensure the second dataset has a different style
+    scatter_style = @dataset_styles[(@dataset_style_index + 2) % @dataset_styles.length][:style]
+
+    datasets = [
+      @tui.dataset(
+        name: "Line",
+        data: line_data,
+        style:,
+        marker: (style.modifiers.include?(:bold) && style.bg) ? :bar : MARKERS[@marker_index][:marker],
+        graph_type: :line
+      ),
+      @tui.dataset(
+        name: "Scatter",
+        data: scatter_data,
+        style: scatter_style,
+        marker: (scatter_style.modifiers.include?(:bold) && scatter_style.bg) ? :bar : MARKERS[@marker_index][:marker],
+        graph_type: :scatter
+      ),
+    ]
+
+    chart = @tui.chart(
+      datasets:,
+      x_axis: @tui.axis(
+        title: "Time",
+        bounds: [0.0, 10.0],
+        labels: %w[0 5 10],
+        style: @tui.style(fg: :yellow),
+        labels_alignment: X_ALIGNMENTS[@x_alignment_index][:alignment]
+      ),
+      y_axis: @tui.axis(
+        title: "Amplitude",
+        bounds: [-1.0, 1.0],
+        labels: %w[-1 0 1],
+        style: @tui.style(fg: :cyan),
+        labels_alignment: Y_ALIGNMENTS[@y_alignment_index][:alignment]
+      ),
+      block: @tui.block(
+        title: "Chart Widget Demo",
+        borders: [:all]
+      ),
+      legend_position: LEGEND_POSITIONS[@legend_position_index][:position],
+      hidden_legend_constraints: [
+        @tui.constraint_min(20),
+        @tui.constraint_min(10),
+      ]
+    )
+
+    controls = @tui.block(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        @tui.paragraph(
+          text: [
+            # Line 1: Markers & Colors
+            @tui.text_line(spans: [
+              @tui.text_span(content: "m", style: @hotkey_style),
+              @tui.text_span(content: ": Marker (#{MARKERS[@marker_index][:name]})  "),
+              @tui.text_span(content: "s", style: @hotkey_style),
+              @tui.text_span(content: ": Style (#{@dataset_styles[@dataset_style_index][:name]})"),
+            ]),
+            # Line 2: Axis alignments
+            @tui.text_line(spans: [
+              @tui.text_span(content: "x", style: @hotkey_style),
+              @tui.text_span(content: ": X Align (#{X_ALIGNMENTS[@x_alignment_index][:name]})  "),
+              @tui.text_span(content: "y", style: @hotkey_style),
+              @tui.text_span(content: ": Y Align (#{Y_ALIGNMENTS[@y_alignment_index][:name]})  "),
+              @tui.text_span(content: "l", style: @hotkey_style),
+              @tui.text_span(content: ": Legend (#{LEGEND_POSITIONS[@legend_position_index][:name]})"),
+            ]),
+            # Line 3: Quit
+            @tui.text_line(spans: [
+              @tui.text_span(content: "q", style: @hotkey_style),
+              @tui.text_span(content: ": Quit"),
+            ]),
+          ]
+        ),
+      ]
+    )
+
+    @tui.draw do |frame|
+      chart_area, controls_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(5),
+        ]
+      )
+      frame.render_widget(chart, chart_area)
+      frame.render_widget(controls, controls_area)
+    end
+  end
+
+  private def handle_input
+    event = @tui.poll_event
+
+    case event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in type: :key, code: "m"
+      @marker_index = (@marker_index + 1) % MARKERS.length
+    in type: :key, code: "s"
+      @dataset_style_index = (@dataset_style_index + 1) % @dataset_styles.length
+    in type: :key, code: "x"
+      @x_alignment_index = (@x_alignment_index + 1) % X_ALIGNMENTS.length
+    in type: :key, code: "y"
+      @y_alignment_index = (@y_alignment_index + 1) % Y_ALIGNMENTS.length
+    in type: :key, code: "l"
+      @legend_position_index = (@legend_position_index + 1) % LEGEND_POSITIONS.length
+    else
+      nil
+    end
+  end
+end
+
+WidgetChartDemo.new.run if __FILE__ == $PROGRAM_NAME

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)