ratatui_ruby 1.0.0 → 1.0.1

data/examples/widget_gauge/app.rb

@@ -1,229 +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 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/app.rb
-#
-# rdoc-image:/doc/images/widget_gauge.png
-class WidgetGauge
-  def initialize
-    @ratio = 0.65
-    @ratios = [0.0, 0.25, 0.5, 0.65, 0.8, 0.95, 1.0]
-    @ratio_index = 3
-
-    # Demonstrates both ratio (0.0-1.0) and percent (0-100) input modes
-    @input_modes = [:ratio, :percent]
-    @input_mode_index = 0
-
-    @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",
-        style: @tui.style(modifiers: [:bold])
-      )
-      frame.render_widget(title, title_area)
-
-      # Gauge 1: Main interactive gauge
-      # Demonstrates both ratio (0.0-1.0) and percent (0-100) input modes
-      input_mode = @input_modes[@input_mode_index]
-      gauge_opts = if input_mode == :percent
-        { percent: (@ratio * 100).to_i } # percent: accepts 0-100
-      else
-        { ratio: @ratio } # ratio: accepts 0.0-1.0
-      end
-      gauge1 = @tui.gauge(
-        **gauge_opts,
-        label:,
-        style: bg_style,
-        gauge_style:,
-        use_unicode:,
-        block: @tui.block(title: "Interactive Gauge (#{input_mode}:)")
-      )
-      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]})  "),
-                @tui.text_span(content: "i", style: @hotkey_style),
-                @tui.text_span(content: ": Input (#{@input_modes[@input_mode_index]}:)"),
-              ]),
-            ]
-          ),
-        ]
-      )
-      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
-    in type: :key, code: "i"
-      @input_mode_index = (@input_mode_index + 1) % @input_modes.length
-    else
-      # Ignore other events
-      nil
-    end
-  end
-end
-
-WidgetGauge.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_layout_split/README.md

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

data/examples/widget_layout_split/app.rb

@@ -1,260 +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 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),
-          ]
-        },
-      },
-      {
-        name: "Batch (from_percentages)",
-        constraints: -> (_dir) {
-          RatatuiRuby::Layout::Constraint.from_percentages([25, 50, 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",
-      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_style: @tui.style(fg: BLOCK_COLORS[i % BLOCK_COLORS.length])
-      )
-      frame.render_widget(block, block_area)
-    end
-  end
-
-  private def render_controls(frame, area)
-    # Demonstrate Constraint#call - show computed sizes for 100 units
-    constraints = current_constraints
-    applied = constraints.map { |c| c.(100) } # proc-like invocation
-    apply_str = "constraint.(100): #{applied.join(', ')}"
-
-    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})  "),
-              @tui.text_span(content: "q", style: @hotkey_style),
-              @tui.text_span(content: ": Quit"),
-            ]),
-            # Row 3: Apply demonstration
-            @tui.text_line(spans: [
-              @tui.text_span(content: apply_str, style: @tui.style(fg: :dark_gray)),
-            ]),
-          ]
-        ),
-      ]
-    )
-    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/README.md

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