ratatui_ruby 1.3.0 → 1.4.0

data/examples/widget_cell/app.rb

@@ -1,112 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$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 WidgetCell
-  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\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
-  WidgetCell.new.run
-end

data/examples/widget_center/README.md

@@ -1,33 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# Center Example
-
-[![widget_center](../../doc/images/widget_center.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/app.rb

@@ -1,118 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
-require "ratatui_ruby"
-
-# Center Widget
-# Demonstrates how to center content horizontally and vertically
-# with adjustable width/height percentages.
-class WidgetCenter
-  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",
-        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
-
-WidgetCenter.new.run if __FILE__ == $0

data/examples/widget_chart/README.md

@@ -1,50 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Chart (Dataset, Axis) Example
-
-[![widget_chart](../../doc/images/widget_chart.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
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_chart/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## 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.
-
-[Read the source code →](app.rb)

data/examples/widget_chart/app.rb

@@ -1,220 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$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/app.rb
-#
-# rdoc-image:/doc/images/widget_chart.png
-class WidgetChart
-  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",
-        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
-
-WidgetChart.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_gauge/README.md

@@ -1,50 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Gauge Widget Example
-
-[![widget_gauge](../../doc/images/widget_gauge.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
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_gauge/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## 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.
-
-[Read the source code →](app.rb)