ratatui_ruby 1.3.0 → 1.3.3

data/examples/widget_barchart/app.rb

@@ -1,240 +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 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/app.rb
-#
-# rdoc-image:/doc/images/widget_barchart.png
-class WidgetBarchart
-  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: #{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
-
-WidgetBarchart.new.run if __FILE__ == $0

data/examples/widget_block/README.md

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

data/examples/widget_block/app.rb

@@ -1,258 +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 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/app.rb
-#
-# rdoc-image:/doc/images/widget_block.png
-class WidgetBlock
-  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
-
-WidgetBlock.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_box/README.md

@@ -1,54 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Block (Box) Example
-
-[![widget_box](../../doc/images/widget_box.png)](app.rb)
-
-Demonstrates visual container attributes with interactive cycling.
-
-Widgets often float in a void. Without boundaries, interfaces become a chaotic mess of text. `Block` (often called a Box) provides the structure and visual hierarchy needed to organize information.
-
-## Features Demonstrated
-
-- **Border Types**: Native styles like `:plain`, `:rounded`, `:double`, `:thick`.
-- **Custom Borders**: defining completely custom character sets (e.g. using numbers or letters for borders).
-- **Styling**: Independent control over border color, background style, and title style.
-- **Positioning**: Placing titles on the `:top` or `:bottom` border (`position`).
-- **Alignment**: Aligning titles to `:left`, `:center`, or `:right` (`alignment`).
-
-## Hotkeys
-
-- **Arrow Keys**: Change Border/Content Color
-- **Space**: Cycle Border Type (`border_type`)
-- **c**: Cycle Custom Border Set (`border_set`)
-- **Enter**: Cycle Title Alignment (`title_alignment`)
-- **s**: Cycle Content Style (`style`)
-- **t**: Cycle Title Style (`title_style`)
-- **b**: Cycle Border Style (`border_style`)
-- **q**: Quit
-
-## Usage
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_box/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## Learning Outcomes
-
-Use this example if you need to...
-
-- Group related widgets together.
-- Create distinct "panels" or "cards" in your UI.
-- Style borders to indicate state (e.g., Red border for error state).
-- Understand the difference between `style` (content) and `border_style` (frame).
-
-[Read the source code →](app.rb)