ratatui_ruby 0.4.0 → 0.6.0

data/examples/verify_readme_usage/README.md

@@ -0,0 +1,43 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# README Usage Verification
+
+Verifies the primary usage example in the project [README](../../README.md#usage).
+
+This example exists as a documentation regression test. It ensures that the very first code snippet a user sees actually works.
+
+## Usage
+
+<!-- SYNC:START:app.rb:main -->
+```ruby
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw do |frame|
+      frame.render_widget(
+        tui.paragraph(
+          text: "Hello, Ratatui! Press 'q' to quit.",
+          alignment: :center,
+          block: tui.block(
+            title: "My Ruby TUI App",
+            borders: [:all],
+            border_color: "cyan"
+          )
+        ),
+        frame.area
+      )
+    end
+    case tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      break
+    else
+      nil
+    end
+  end
+end
+```
+<!-- SYNC:END -->
+
+![verify_readme_usage](../../doc/images/verify_readme_usage.png)

data/examples/verify_readme_usage/app.rb

@@ -0,0 +1,40 @@
+# 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"
+class VerifyReadmeUsage
+  def run
+    # [SYNC:START:main]
+    RatatuiRuby.run do |tui|
+      loop do
+        tui.draw do |frame|
+          frame.render_widget(
+            tui.paragraph(
+              text: "Hello, Ratatui! Press 'q' to quit.",
+              alignment: :center,
+              block: tui.block(
+                title: "My Ruby TUI App",
+                borders: [:all],
+                border_color: "cyan"
+              )
+            ),
+            frame.area
+          )
+        end
+        case tui.poll_event
+        in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+          break
+        else
+          nil
+        end
+      end
+    end
+    # [SYNC:END:main]
+  end
+end
+
+VerifyReadmeUsage.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_barchart_demo/README.md

@@ -0,0 +1,49 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# BarChart Widget Example
+
+Visualizes categorical data with interactive attribute cycling.
+
+Comparing magnitudes in raw tables requires mental arithmetic. Bar charts make these comparisons instant and intuitive.
+
+## Features Demonstrated
+
+- **Data Formats**: Supports simple Hashes, Arrays with individual styles, and Groups (stacked/grouped bars).
+- **Orientation**: Switch between Vertical and Horizontal layouts.
+- **Customization**:
+    - Adjustable bar widths and gaps.
+    - Custom characters for bars (ASCII art support).
+    - Detailed styling for labels and values.
+- **Mini Mode**: Compact rendering for dashboard widgets.
+
+## Hotkeys
+
+- **d**: Cycle Data Source (`data`)
+- **v**: Toggle Direction (`direction`)
+- **w**: Adjust Bar Width (`bar_width`)
+- **a**: Adjust Bar Gap (`bar_gap`)
+- **g**: Adjust Group Gap (`group_gap`)
+- **b**: Cycle Bar Character Set (`bar_set`)
+- **s**: Cycle Chart Style (`style`)
+- **x**: Cycle Label Style (`label_style`)
+- **z**: Cycle Value Style (`value_style`)
+- **m**: Toggle Mini Mode (Compact View)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_barchart_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Visualize categorical data (e.g., sales by quarter, CPU usage by core).
+- Create "stats" dashboards with compact visualizations.
+- Understand how `RatatuiRuby::BarChart` handles different data structures.
+
+![Demo](/doc/images/widget_barchart_demo.png)

data/examples/widget_barchart_demo/app.rb

@@ -0,0 +1,238 @@
+# 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 categorical data visualization with interactive attribute cycling.
+#
+# Raw tables of numbers are hard to scan. Comparing magnitudes requires mental arithmetic, which slows down decision-making.
+#
+# This demo showcases the <tt>BarChart</tt> widget. It provides an interactive playground where you can cycle through different data formats, styles, and orientations in real-time.
+#
+# Use it to understand how to visualize and compare discrete datasets effectively.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_barchart_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_barchart_demo.png
+class WidgetBarchartDemo
+  def initialize
+    @data_index = 2
+    @styles = nil # Initialized in run
+    @style_index = 3
+    @label_style_index = 3
+    @value_style_index = 3
+    @bar_sets = [
+      { name: "Default", set: nil },
+      { name: "Numbers (Short)", set: { 8 => "8", 7 => "7", 6 => "6", 5 => "5", 4 => "4", 3 => "3", 2 => "2", 1 => "1", 0 => "0" } },
+      { name: "Letters (Long)", set: { full: "H", seven_eighths: "G", three_quarters: "F", five_eighths: "E", half: "D", three_eighths: "C", one_quarter: "B", one_eighth: "A", empty: " " } },
+      { name: "ASCII (Heights)", set: [" ", "_", ".", "-", "=", "+", "*", "#", "@"] },
+    ]
+    @bar_set_index = 0
+    @direction = :vertical
+    @bar_width = 8
+    @bar_gap = 1
+    @group_gap = 2
+    @height_mode = :full
+    @hotkey_style = nil
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      init_styles
+
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def init_styles
+    @styles = [
+      { name: "Green", style: @tui.style(fg: :green) },
+      { name: "Blue", style: @tui.style(fg: :blue) },
+      { name: "Red", style: @tui.style(fg: :red) },
+      { name: "Cyan", style: @tui.style(fg: :cyan) },
+      { name: "Yellow Bold", style: @tui.style(fg: :yellow, modifiers: [:bold]) },
+      { name: "Reversed", style: @tui.style(modifiers: [:reversed]) },
+    ]
+    @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+  end
+
+  private def current_data
+    case @data_index
+    when 0 # Simple Hash
+      {
+        "Q1" => 50,
+        "Q2" => 80,
+        "Q3" => 45,
+        "Q4" => 60,
+        "Q1'" => 55,
+        "Q2'" => 85,
+        "Q3'" => 50,
+        "Q4'" => 65,
+      }
+    when 1 # Array with styles
+      [
+        ["Mon", 120],
+        ["Tue", 150],
+        ["Wed", 130],
+        ["Thu", 160],
+        ["Fri", 140],
+        ["Sat", 110, @tui.style(fg: :red)],
+        ["Sun", 100, @tui.style(fg: :red)],
+      ]
+    when 2 # Groups
+      [
+        @tui.bar_chart_bar_group(label: "2024", bars: [
+          @tui.bar_chart_bar(value: 40, label: "Q1"),
+          @tui.bar_chart_bar(value: 45, label: "Q2"),
+          @tui.bar_chart_bar(value: 50, label: "Q3"),
+          @tui.bar_chart_bar(value: 55, label: "Q4"),
+        ]),
+        @tui.bar_chart_bar_group(label: "2025", bars: [
+          @tui.bar_chart_bar(value: 60, label: "Q1", style: @tui.style(fg: :yellow)),
+          @tui.bar_chart_bar(value: 65, label: "Q2", style: @tui.style(fg: :yellow)),
+          @tui.bar_chart_bar(value: 70, label: "Q3", style: @tui.style(fg: :yellow)),
+          @tui.bar_chart_bar(value: 75, label: "Q4", style: @tui.style(fg: :yellow)),
+        ]),
+      ]
+    end
+  end
+
+  private def data_name
+    ["Simple Hash", "Styled Array", "Groups"][@data_index]
+  end
+
+  private def render
+    @tui.draw do |frame|
+      chart_area, controls_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(6),
+        ]
+      )
+
+      # Handle Mini Mode
+      effective_chart_area = if @height_mode == :mini
+        mini_area, = @tui.layout_split(
+          chart_area,
+          direction: :vertical,
+          constraints: [
+            @tui.constraint_length(3),
+            @tui.constraint_fill(1),
+          ]
+        )
+        mini_area
+      else
+        chart_area
+      end
+
+      bar_chart = @tui.bar_chart(
+        data: current_data,
+        bar_width: @bar_width,
+        style: @styles[@style_index][:style],
+        bar_gap: @bar_gap,
+        group_gap: @group_gap,
+        direction: @direction,
+        label_style: @styles[@label_style_index][:style],
+        value_style: @styles[@value_style_index][:style],
+        bar_set: @bar_sets[@bar_set_index][:set],
+        block: @tui.block(
+          title: "BarChart Demo: #{data_name}",
+          borders: [:all]
+        )
+      )
+      frame.render_widget(bar_chart, effective_chart_area)
+
+      render_controls(frame, controls_area)
+    end
+  end
+
+  private def render_controls(frame, area)
+    controls = @tui.block(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        @tui.paragraph(
+          text: [
+            @tui.text_line(spans: [
+              @tui.text_span(content: "d", style: @hotkey_style),
+              @tui.text_span(content: ": Data (#{data_name})  "),
+              @tui.text_span(content: "v", style: @hotkey_style),
+              @tui.text_span(content: ": Direction (#{@direction})  "),
+              @tui.text_span(content: "q", style: @hotkey_style),
+              @tui.text_span(content: ": Quit"),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "w", style: @hotkey_style),
+              @tui.text_span(content: ": Width (#{@bar_width})  "),
+              @tui.text_span(content: "a", style: @hotkey_style),
+              @tui.text_span(content: ": Gap (#{@bar_gap})  "),
+              @tui.text_span(content: "g", style: @hotkey_style),
+              @tui.text_span(content: ": Group Gap (#{@group_gap})"),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "s", style: @hotkey_style),
+              @tui.text_span(content: ": Style (#{@styles[@style_index][:name]})  "),
+              @tui.text_span(content: "x", style: @hotkey_style),
+              @tui.text_span(content: ": Label (#{@styles[@label_style_index][:name]})  "),
+              @tui.text_span(content: "z", style: @hotkey_style),
+              @tui.text_span(content: ": Value (#{@styles[@value_style_index][:name]})  "),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "b", style: @hotkey_style),
+              @tui.text_span(content: ": Set (#{@bar_sets[@bar_set_index][:name]})  "),
+              @tui.text_span(content: "m", style: @hotkey_style),
+              @tui.text_span(content: ": Mode (#{(@height_mode == :full) ? 'Full' : 'Mini'})"),
+            ]),
+          ]
+        ),
+      ]
+    )
+    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"
+      @data_index = (@data_index + 1) % 3
+    in type: :key, code: "v"
+      @direction = (@direction == :vertical) ? :horizontal : :vertical
+      # Adjust width default based on direction for better UX, though user can manually adjust 'w'
+      @bar_width = (@direction == :vertical) ? 8 : 1
+    in type: :key, code: "w"
+      @bar_width = (@bar_width % 10) + 1
+    in type: :key, code: "a"
+      @bar_gap = (@bar_gap + 1) % 5
+    in type: :key, code: "g"
+      @group_gap = (@group_gap + 1) % 5
+    in type: :key, code: "s"
+      @style_index = (@style_index + 1) % @styles.size
+    in type: :key, code: "x"
+      @label_style_index = (@label_style_index + 1) % @styles.size
+    in type: :key, code: "z"
+      @value_style_index = (@value_style_index + 1) % @styles.size
+    in type: :key, code: "b"
+      @bar_set_index = (@bar_set_index + 1) % @bar_sets.size
+    in type: :key, code: "m"
+      @height_mode = (@height_mode == :full) ? :mini : :full
+    else
+      # Ignore
+    end
+  end
+end
+
+WidgetBarchartDemo.new.run if __FILE__ == $0

data/examples/widget_block_demo/README.md

@@ -0,0 +1,34 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Block Widget Demo
+
+This example demonstrates the versatile `Block` widget, which provides the visual container, borders, and titles for almost every other widget in `ratatui_ruby`.
+
+## Key Concepts
+
+- **Borders:** Choose which sides to show and apply different border types (plain, rounded, double, thick, etc.).
+- **Titles:** Add a main title with alignment or multiple titles at the top and bottom with independent styles and positions.
+- **Padding:** Define inner spacing using uniform or directional (L/R/T/B) values.
+- **Styling:** Individually style the block's content area, its borders, and its titles.
+- **Custom Border Sets:** Create entirely custom border appearances by defining each character in the border set.
+
+## Hotkeys
+
+- `t`: Cycle **Title** (None, Main Title)
+- `a`: Cycle **Title Alignment** (Left, Center, Right)
+- `s`: Cycle **Title Style** (None, Cyan Bold, Yellow Italic)
+- `e`: Cycle **Additional Titles** (None, Top+Bottom, Complex)
+- `b`: Cycle **Borders** (All, Top/Bottom, Left/Right, None)
+- `y`: Cycle **Border Type** (Rounded, Plain, Double, Thick, Quadrant, Custom)
+- `c`: Cycle **Border Style** (Magenta Bold, None, Green, Blue on White)
+- `p`: Cycle **Padding** (Uniform, None, Directional, Narrow)
+- `f`: Cycle **Base Style** (Dark Gray, None, White on Black)
+- `q`: **Quit**
+
+## Usage
+
+```bash
+ruby examples/widget_block_demo/app.rb
+```

data/examples/widget_block_demo/app.rb

@@ -0,0 +1,256 @@
+# 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 the Block widget with interactive attribute cycling.
+#
+# Blocks are the foundation of terminal layouts, providing structure, borders, and titles.
+# This demo showcases all available parameters, including advanced title positioning,
+# directional padding, and custom border sets.
+#
+# === Examples
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_block_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_block_demo.png
+class WidgetBlockDemo
+  def initialize
+    @title_configs = [
+      { name: "None", title: nil },
+      { name: "Main Title", title: "Main Title" },
+    ]
+    @title_index = 1
+
+    @titles_configs = [
+      { name: "None", titles: [] },
+      {
+name: "Top + Bottom",
+titles: [
+  { content: "Top Right", alignment: :right, position: :top },
+  { content: "Bottom Left", alignment: :left, position: :bottom },
+      ],
+},
+      {
+name: "Complex",
+titles: [
+  { content: "★ Left ★", alignment: :left, position: :top },
+  { content: "Center", alignment: :center, position: :top },
+  { content: "Right", alignment: :right, position: :top },
+  { content: "Bottom Center", alignment: :center, position: :bottom },
+      ],
+},
+    ]
+    @titles_index = 1
+
+    @alignment_configs = [
+      { name: "Left", alignment: :left },
+      { name: "Center", alignment: :center },
+      { name: "Right", alignment: :right },
+    ]
+    @alignment_index = 1 # Center
+
+    @border_configs = [
+      { name: "All", borders: [:all] },
+      { name: "Top/Bottom", borders: [:top, :bottom] },
+      { name: "Left/Right", borders: [:left, :right] },
+      { name: "None", borders: [] },
+    ]
+    @border_index = 0
+
+    @border_type_configs = [
+      { name: "Rounded", type: :rounded },
+      { name: "Plain", type: :plain },
+      { name: "Double", type: :double },
+      { name: "Thick", type: :thick },
+      { name: "Quadrant Inside", type: :quadrant_inside },
+      { name: "Quadrant Outside", type: :quadrant_outside },
+      {
+name: "Custom Set",
+type: nil,
+set: {
+        top_left: "1",
+        top_right: "2",
+        bottom_left: "3",
+        bottom_right: "4",
+        vertical_left: "5",
+        vertical_right: "6",
+        horizontal_top: "7",
+        horizontal_bottom: "8",
+      },
+},
+    ]
+    @border_type_index = 0
+
+    @padding_configs = [
+      { name: "Uniform (2)", padding: 2 },
+      { name: "None (0)", padding: 0 },
+      { name: "Directional (L:4, T:2)", padding: [4, 0, 2, 0] },
+      { name: "Narrow (H:1, V:0)", padding: [1, 1, 0, 0] },
+    ]
+    @padding_index = 0
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+
+      @title_styles = [
+        { name: "None", style: nil },
+        { name: "Magenta Bold", style: @tui.style(fg: :magenta, modifiers: [:bold]) },
+        { name: "Cyan Bold", style: @tui.style(fg: :cyan, modifiers: [:bold]) },
+        { name: "Yellow Italic", style: @tui.style(fg: :yellow, modifiers: [:italic]) },
+      ]
+      @title_style_index = 1 # Magenta Bold
+
+      @border_styles = [
+        { name: "Cyan", style: @tui.style(fg: :cyan) },
+        { name: "Magenta Bold", style: @tui.style(fg: :magenta, modifiers: [:bold]) },
+        { name: "None", style: nil },
+        { name: "Blue on White", style: @tui.style(fg: :blue, bg: :white) },
+      ]
+      @border_style_index = 0
+
+      @base_styles = [
+        { name: "Dark Gray", style: @tui.style(fg: :dark_gray) },
+        { name: "None", style: nil },
+        { name: "White on Black", style: @tui.style(fg: :white, bg: :black) },
+      ]
+      @base_style_index = 1
+
+      @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+
+      loop do
+        render
+        break if handle_input == :quit
+        sleep 0.05
+      end
+    end
+  end
+
+  private def render
+    title_config = @title_configs[@title_index]
+    titles_config = @titles_configs[@titles_index]
+    alignment_config = @alignment_configs[@alignment_index]
+    title_style_config = @title_styles[@title_style_index]
+    border_config = @border_configs[@border_index]
+    border_type_config = @border_type_configs[@border_type_index]
+    border_style_config = @border_styles[@border_style_index]
+    base_style_config = @base_styles[@base_style_index]
+    padding_config = @padding_configs[@padding_index]
+
+    @tui.draw do |frame|
+      main_area, control_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(10),
+        ]
+      )
+
+      # Render the demo block
+      demo_block = @tui.block(
+        title: title_config[:title],
+        titles: titles_config[:titles],
+        title_alignment: alignment_config[:alignment],
+        title_style: title_style_config[:style],
+        borders: border_config[:borders],
+        border_type: border_type_config[:type],
+        border_set: border_type_config[:set],
+        border_style: border_style_config[:style],
+        style: base_style_config[:style],
+        padding: padding_config[:padding]
+      )
+
+      # Paragraph inside the block to show padding/content interaction
+      content = @tui.paragraph(
+        text: "This paragraph is rendered inside the Block widget.\n" \
+          "You can see how padding and base style affect this content.\n\n" \
+          "Current State:\n" \
+          "• Padding: #{padding_config[:name]}\n" \
+          "• Borders: #{border_config[:name]}\n" \
+          "• Type: #{border_type_config[:name]}",
+        block: demo_block
+      )
+      frame.render_widget(content, main_area)
+
+      # Render control panel
+      control_panel = @tui.block(
+        title: "Controls",
+        borders: [:all],
+        children: [
+          @tui.paragraph(
+            text: [
+              @tui.text_line(spans: [
+                @tui.text_span(content: "t", style: @hotkey_style),
+                @tui.text_span(content: ": Title (#{title_config[:name]})  "),
+                @tui.text_span(content: "a", style: @hotkey_style),
+                @tui.text_span(content: ": Alignment (#{alignment_config[:name]})  "),
+                @tui.text_span(content: "s", style: @hotkey_style),
+                @tui.text_span(content: ": Title Style (#{title_style_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "e", style: @hotkey_style),
+                @tui.text_span(content: ": Additional Titles (#{titles_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "b", style: @hotkey_style),
+                @tui.text_span(content: ": Borders (#{border_config[:name]})  "),
+                @tui.text_span(content: "y", style: @hotkey_style),
+                @tui.text_span(content: ": Border Type (#{border_type_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "c", style: @hotkey_style),
+                @tui.text_span(content: ": Border Style (#{border_style_config[:name]})  "),
+                @tui.text_span(content: "p", style: @hotkey_style),
+                @tui.text_span(content: ": Padding (#{padding_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "f", style: @hotkey_style),
+                @tui.text_span(content: ": Base Style (#{base_style_config[:name]})  "),
+                @tui.text_span(content: "q", style: @hotkey_style),
+                @tui.text_span(content: ": Quit"),
+              ]),
+            ]
+          ),
+        ]
+      )
+      frame.render_widget(control_panel, control_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: "t"
+      @title_index = (@title_index + 1) % @title_configs.size
+    in type: :key, code: "e"
+      @titles_index = (@titles_index + 1) % @titles_configs.size
+    in type: :key, code: "a"
+      @alignment_index = (@alignment_index + 1) % @alignment_configs.size
+    in type: :key, code: "s"
+      @title_style_index = (@title_style_index + 1) % @title_styles.size
+    in type: :key, code: "b"
+      @border_index = (@border_index + 1) % @border_configs.size
+    in type: :key, code: "y"
+      @border_type_index = (@border_type_index + 1) % @border_type_configs.size
+    in type: :key, code: "c"
+      @border_style_index = (@border_style_index + 1) % @border_styles.size
+    in type: :key, code: "p"
+      @padding_index = (@padding_index + 1) % @padding_configs.size
+    in type: :key, code: "f"
+      @base_style_index = (@base_style_index + 1) % @base_styles.size
+    else
+      nil
+    end
+  end
+end
+
+WidgetBlockDemo.new.run if __FILE__ == $PROGRAM_NAME