ratatui_ruby 1.3.0 → 1.4.0

data/examples/widget_scrollbar/app.rb

@@ -1,155 +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 viewport navigation with interactive theme and orientation cycling.
-#
-# Content overflows. Users get lost in long lists without landmarks. They need to know where they are and how much is left.
-#
-# This demo showcases the <tt>Scrollbar</tt> widget. It provides an interactive playground where you can toggle orientations and cycle through different themes (Standard, Rounded, ASCII, Minimal) in real-time.
-#
-# Use it to understand how to provide spatial awareness and navigation cues for overflowing content.
-#
-# === Example
-#
-# Run the demo from the terminal:
-#
-#   ruby examples/widget_scrollbar/app.rb
-#
-# rdoc-image:/doc/images/widget_scrollbar.png
-class WidgetScrollbar
-  def initialize
-    @scroll_position = 0
-    @content_length = 50
-    @lines = (1..@content_length).map { |i| "Line #{i}" }
-    @orientation_index = 0
-    @orientations = [
-      :vertical,
-      :vertical_right,
-      :vertical_left,
-      :horizontal,
-      :horizontal_bottom,
-      :horizontal_top,
-    ]
-    @theme_index = 0
-    @themes = [
-      {
-        name: "Standard",
-        track_symbol: nil,
-        thumb_symbol: "█",
-        track_style: nil,
-        thumb_style: nil,
-        begin_symbol: nil,
-        end_symbol: nil,
-      },
-      {
-        name: "Rounded",
-        track_symbol: "│",
-        thumb_symbol: "┃",
-        track_style: { fg: "dark_gray" },
-        thumb_style: { fg: "cyan" },
-        begin_symbol: "▲",
-        end_symbol: "▼",
-      },
-      {
-        name: "ASCII",
-        track_symbol: "|",
-        thumb_symbol: "#",
-        track_style: { fg: "white" },
-        thumb_style: { fg: "red" },
-        begin_symbol: "^",
-        end_symbol: "v",
-      },
-      {
-        name: "Minimal",
-        track_symbol: " ",
-        thumb_symbol: "▐",
-        track_style: nil,
-        thumb_style: { fg: "yellow" },
-        begin_symbol: nil,
-        end_symbol: nil,
-      },
-    ]
-  end
-
-  def run
-    RatatuiRuby.run do |tui|
-      @tui = tui
-      loop do
-        draw
-        event = @tui.poll_event
-        break if event == "q" || event == :ctrl_c
-
-        handle_event(event)
-      end
-    end
-  end
-
-  private def handle_event(event)
-    if event.mouse?
-      case event.kind
-      when "scroll_up"
-        @scroll_position = [@scroll_position - 1, 0].max
-      when "scroll_down"
-        @scroll_position = [@scroll_position + 1, @content_length].min
-      end
-    end
-
-    if event.key? && event.to_s == "s"
-      @theme_index = (@theme_index + 1) % @themes.length
-    end
-
-    if event.key? && event.to_s == "o"
-      @orientation_index = (@orientation_index + 1) % @orientations.length
-    end
-  end
-
-  private def draw
-    @tui.draw do |frame|
-      # Calculate visible lines based on scroll position
-      # In a real app, you'd want to know the height of the available area.
-      # For this demo, we'll just show all lines but offset the text.
-      visible_lines = @lines[@scroll_position..-1] || []
-
-      # Paragraph with content
-      theme = @themes[@theme_index]
-      orientation = @orientations[@orientation_index]
-
-      p = @tui.paragraph(
-        text: visible_lines.join("\n"),
-        block: @tui.block(
-          titles: [
-            { content: "Scroll with Mouse Wheel | Theme: #{theme[:name]} | Orientation: #{orientation}" },
-            { content: "Press 's' to cycle theme, 'o' to cycle orientation", position: :bottom, alignment: :center },
-          ],
-          borders: [:all]
-        )
-      )
-
-      # Scrollbar
-      s = @tui.scrollbar(
-        content_length: @content_length,
-        position: @scroll_position,
-        orientation:,
-        track_symbol: theme[:track_symbol],
-        thumb_symbol: theme[:thumb_symbol],
-        track_style: theme[:track_style],
-        thumb_style: theme[:thumb_style],
-        begin_symbol: theme[:begin_symbol],
-        end_symbol: theme[:end_symbol]
-      )
-
-      # Render paragraph first, then scrollbar on top
-      frame.render_widget(p, frame.area)
-      frame.render_widget(s, frame.area)
-    end
-  end
-end
-
-WidgetScrollbar.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_sparkline/README.md

@@ -1,51 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Sparkline Widget Example
-
-[![widget_sparkline](../../doc/images/widget_sparkline.png)](app.rb)
-
-Demonstrates high-density data visualization in a condensed footprint.
-
-Users need context. A single number ("90% CPU") tells you status, but not the trend. Full charts take up too much space. Sparklines condense history into a single line, perfect for headers and dashboards.
-
-## Features Demonstrated
-
-- **High Density**: Showing dozens of data points in a small area.
-- **Direction**: Rendering Left-to-Right (standard) or Right-to-Left (like a scrolling ticker).
-- **Gaps**: Handling `nil` values with "absent symbols" to indicate missing data.
-- **Styling**: Using colors and custom characters to indicate severity or type.
-
-## Hotkeys
-
-- **Up/Down (↑/↓)**: Cycle Data Set (`data`)
-- **d**: Cycle Direction (`direction`)
-- **c**: Cycle Color (`style`)
-- **m**: Cycle Absent Value Marker Symbol (`absent_value_symbol`)
-- **s**: Cycle Absent Value Marker Style (`absent_value_style`)
-- **b**: Cycle Bar Character Set (`bar_set`)
-- **q**: Quit
-
-## Usage
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_sparkline/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## Learning Outcomes
-
-Use this example if you need to...
-
-- Add a "CPU Load" graph to your header.
-- Visualize stock price trends in a list row.
-- Monitor memory usage over the last 60 seconds.
-
-[Read the source code →](app.rb)

data/examples/widget_sparkline/app.rb

@@ -1,277 +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 high-density data visualization with interactive attribute cycling.
-#
-# Users need context. A single value ("90% CPU") tells you current status, but not the trend. Full charts take up too much room.
-#
-# This demo showcases the <tt>Sparkline</tt> widget. It provides an interactive playground where you can cycle through data sets, directions, colors, and custom bar sets.
-#
-# Use it to understand how to condense history into a single line for dashboards or headers.
-#
-# === Example
-#
-# Run the demo from the terminal:
-#
-#   ruby examples/widget_sparkline/app.rb
-#
-# rdoc-image:/doc/images/widget_sparkline.png
-class WidgetSparkline
-  def run
-    RatatuiRuby.run do |tui|
-      @tui = tui
-      setup
-      loop do
-        render
-        break if handle_input == :quit
-      end
-    end
-  end
-
-  private def setup
-    # Data sets with different characteristics
-    @data_sets = [
-      {
-        name: "Steady Growth",
-        data: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
-      },
-      {
-        name: "With Gaps",
-        data: [5, nil, 8, nil, 6, nil, 9, nil, 7, nil, 10, nil],
-      },
-      {
-        name: "Random",
-        data: [3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5, 8],
-      },
-      {
-        name: "Sawtooth",
-        data: [1, 2, 3, 4, 5, 4, 3, 2, 1, 2, 3, 4],
-      },
-      {
-        name: "Peaks",
-        data: [1, 5, 1, 8, 1, 6, 1, 9, 1, 7, 1, 10],
-      },
-    ]
-    @data_index = 2
-    srand(12345) # Ensure reproducible "Random" data for snapshots
-
-    @directions = [
-      { name: "Left to Right", direction: :left_to_right },
-      { name: "Right to Left", direction: :right_to_left },
-    ]
-    @direction_index = 0
-
-    @styles = [
-      { name: "Green", style: @tui.style(fg: :green) },
-      { name: "Yellow", style: @tui.style(fg: :yellow) },
-      { name: "Red", style: @tui.style(fg: :red) },
-      { name: "Cyan", style: @tui.style(fg: :cyan) },
-      { name: "Magenta", style: @tui.style(fg: :magenta) },
-    ]
-    @style_index = 3
-
-    @absent_symbols = [
-      { name: "None", symbol: nil },
-      { name: "Dot (·)", symbol: "·" },
-      { name: "Square (▫)", symbol: "▫" },
-      { name: "Dash (-)", symbol: "-" },
-      { name: "Underscore (_)", symbol: "_" },
-    ]
-    @absent_symbol_index = 1
-
-    @absent_styles = [
-      { name: "Default", style: nil },
-      { name: "Dark Gray", style: @tui.style(fg: :dark_gray) },
-      { name: "Dim Red", style: @tui.style(fg: :red, modifiers: [:dim]) },
-      { name: "Dim Yellow", style: @tui.style(fg: :yellow, modifiers: [:dim]) },
-    ]
-    @absent_style_index = 2
-
-    @bar_sets = [
-      { name: "Default (Block)", set: nil },
-      {
-        name: "Numbers (0-8)",
-        set: {
-          0 => "0", 1 => "1", 2 => "2", 3 => "3", 4 => "4", 5 => "5", 6 => "6", 7 => "7", 8 => "8"
-        },
-      },
-      { name: "ASCII (Heights)", set: [" ", "_", ".", "-", "=", "+", "*", "#", "@"] },
-    ]
-    @bar_set_index = 0
-
-    @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
-  end
-
-  private def render
-    @tui.draw do |frame|
-      data_set = @data_sets[@data_index]
-      direction = @directions[@direction_index][:direction]
-      style = @styles[@style_index][:style]
-      absent_symbol = @absent_symbols[@absent_symbol_index][:symbol]
-      absent_value_style = @absent_styles[@absent_style_index][:style]
-      bar_set = @bar_sets[@bar_set_index][:set]
-
-      # Use static data for clarity when cycling options
-      current_data = data_set[:data]
-
-      layout = @tui.layout_split(
-        frame.area,
-        direction: :vertical,
-        constraints: [
-          @tui.constraint_fill(1),
-          @tui.constraint_length(6),
-        ]
-      )
-
-      # Main content area with multiple sparkline examples
-      main_content_area = layout[0]
-      main_layout = @tui.layout_split(
-        main_content_area,
-        direction: :vertical,
-        constraints: [
-          @tui.constraint_length(1),
-          @tui.constraint_length(3),
-          @tui.constraint_length(3),
-          @tui.constraint_length(3),
-          @tui.constraint_length(3),
-          @tui.constraint_fill(1),
-        ]
-      )
-
-      frame.render_widget(
-        @tui.paragraph(text: "Sparkline Widget - Cycle attributes with hotkeys"),
-        main_layout[0]
-      )
-
-      # Sparkline 1: Main interactive sparkline
-      frame.render_widget(
-        @tui.sparkline(
-          data: current_data,
-          direction:,
-          style:,
-          absent_value_symbol: absent_symbol,
-          absent_value_style:,
-          bar_set:,
-          block: @tui.block(title: "Interactive Sparkline")
-        ),
-        main_layout[1]
-      )
-
-      # Sparkline 2: Same data, opposite direction
-      frame.render_widget(
-        @tui.sparkline(
-          data: current_data.reverse,
-          direction:,
-          style:,
-          absent_value_symbol: absent_symbol,
-          absent_value_style:,
-          bar_set:,
-          block: @tui.block(title: "Reversed Data")
-        ),
-        main_layout[2]
-      )
-
-      # Sparkline 3: Without absent value symbol (for comparison)
-      frame.render_widget(
-        @tui.sparkline(
-          data: current_data,
-          direction:,
-          style:,
-          bar_set:,
-          block: @tui.block(title: "Without Absent Marker")
-        ),
-        main_layout[3]
-      )
-
-      # Sparkline 4: Gap pattern responsive to absent marker controls
-      frame.render_widget(
-        @tui.sparkline(
-          data: [5, nil, 8, nil, 6, nil, 9, nil, 7, nil, 10, nil],
-          direction:,
-          style: @tui.style(fg: :blue),
-          absent_value_symbol: absent_symbol,
-          absent_value_style:,
-          bar_set:,
-          block: @tui.block(title: "Gap Pattern (Responsive)")
-        ),
-        main_layout[4]
-      )
-
-      # Bottom control panel
-      control_area = layout[1]
-      frame.render_widget(
-        @tui.block(
-          title: "Controls",
-          borders: [:all],
-          children: [
-            @tui.paragraph(
-              text: [
-                # Line 1: Data
-                @tui.text_line(spans: [
-                  @tui.text_span(content: "↑/↓", style: @hotkey_style),
-                  @tui.text_span(content: ": Data (#{@data_sets[@data_index][:name]})"),
-                ]),
-                # Line 2: View
-                @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: "c", style: @hotkey_style),
-                  @tui.text_span(content: ": Color (#{@styles[@style_index][:name]})"),
-                ]),
-                # Line 3: Markers
-                @tui.text_line(spans: [
-                  @tui.text_span(content: "m", style: @hotkey_style),
-                  @tui.text_span(content: ": Absent Value Symbol (#{@absent_symbols[@absent_symbol_index][:name]})  "),
-                  @tui.text_span(content: "s", style: @hotkey_style),
-                  @tui.text_span(content: ": Absent Value Style (#{@absent_styles[@absent_style_index][:name]})"),
-                ]),
-                # Line 4: General
-                @tui.text_line(spans: [
-                  @tui.text_span(content: "b", style: @hotkey_style),
-                  @tui.text_span(content: ": Bar Set (#{@bar_sets[@bar_set_index][:name]})  "),
-                  @tui.text_span(content: "q", style: @hotkey_style),
-                  @tui.text_span(content: ": Quit"),
-                ]),
-              ]
-            ),
-          ]
-        ),
-        control_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: "up"
-      @data_index = (@data_index - 1) % @data_sets.length
-    in type: :key, code: "down"
-      @data_index = (@data_index + 1) % @data_sets.length
-    in type: :key, code: "d"
-      @direction_index = (@direction_index + 1) % @directions.length
-    in type: :key, code: "c"
-      @style_index = (@style_index + 1) % @styles.length
-    in type: :key, code: "m"
-      @absent_symbol_index = (@absent_symbol_index + 1) % @absent_symbols.length
-    in type: :key, code: "s"
-      @absent_style_index = (@absent_style_index + 1) % @absent_styles.length
-    in type: :key, code: "b"
-      @bar_set_index = (@bar_set_index + 1) % @bar_sets.length
-    else
-      nil
-    end
-  end
-end
-
-WidgetSparkline.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_style_colors/README.md

@@ -1,43 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Style Colors Example
-
-[![widget_style_colors](../../doc/images/widget_style_colors.png)](app.rb)
-
-Demonstrates high-fidelity color support.
-
-Terminals support millions of colors. This example generates a mathematically precise HSL gradient to prove the rendering engine's color fidelity.
-
-## Features Demonstrated
-
-- **HSL to RGB Conversion**: generating smooth color gradients programmatically.
-- **TrueColor Support**: Rendering arbitrary HEX colors.
-
-## Hotkeys
-
-- **q** / **Ctrl+c**: Quit
-
-## Usage
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_style_colors/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## Learning Outcomes
-
-Use this example if you need to...
-
-- Create meaningful heatmaps.
-- Generate color palettes dynamically.
-- Test your terminal's color support capabilities.
-
-[Read the source code →](app.rb)

data/examples/widget_style_colors/app.rb

@@ -1,83 +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 terminal color rendering and the Color module.
-#
-# Terminal apps need vibrant colors. Specifying colors as symbols or
-# calculated hex strings works but limits expressiveness.
-#
-# This demo shows the Color module's constructors for creating colors
-# from HSL values or hex integers, producing a full-spectrum gradient.
-#
-# Use it to understand color representation and the Color.hsl/Color.hex APIs.
-class WidgetStyleColors
-  def initialize
-    @width = 80
-    @height = 24
-  end
-
-  def run
-    RatatuiRuby.run do |tui|
-      loop do
-        tui.draw do |frame|
-          frame.render_widget(render(tui), frame.area)
-        end
-        event = tui.poll_event
-        break if event.key? && (event.ctrl_c? || event == :q)
-      end
-    end
-  end
-
-  private def render(tui)
-    lines = []
-
-    (0...@height).each do |row|
-      spans = []
-      (0...@width).each do |col|
-        hue = (col.to_f / @width) * 360.0
-        lightness = 50.0 - ((row.to_f / @height) * 50.0)
-
-        # Use Color.hsl for top half, Color.hsluv for bottom half
-        # HSLuv provides perceptually uniform colors (same visual brightness)
-        hex = if row < @height / 2
-          RatatuiRuby::Style::Color.hsl(hue, 100.0, lightness)
-        else
-          # HSLuv: perceptually uniform - all colors appear equal brightness
-          RatatuiRuby::Style::Color.hsluv(hue, 100.0, lightness)
-        end
-
-        # Demonstrate Style.with for concise inline styling
-        span = tui.text_span(
-          content: " ",
-          style: RatatuiRuby::Style::Style.with(bg: hex)
-        )
-        spans << span
-      end
-
-      lines << tui.text_line(spans:)
-    end
-
-    # Also demonstrate Color.hex for the border
-    border_color = RatatuiRuby::Style::Color.hex(0xFFD700) # Gold
-
-    tui.paragraph(
-      text: lines,
-      block: tui.block(
-        title: "HSL (top) vs HSLuv (bottom) - Style.with demo (Press 'q' to exit)",
-        borders: [:all],
-        border_type: :rounded,
-        # Using Style.with for concise border styling
-        border_style: RatatuiRuby::Style::Style.with(fg: border_color)
-      )
-    )
-  end
-end
-
-WidgetStyleColors.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_table/README.md

@@ -1,57 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Table (Row, Cell) Example
-
-[![widget_table](../../doc/images/widget_table.png)](app.rb)
-
-Demonstrates advanced options for the `Table` widget, including selection, row-level highlighting, and column-level highlighting.
-
-Data grids are complex. Users expect to navigate them with keys, select rows, and clearly see which cell is active. The `Table` widget provides these features out of the box efficiently.
-
-## Features Demonstrated
-
-- **Selection State**: Managing `selected_row` and `selected_column` to track user focus.
-- **Complex Highlighting**:
-    - **Row**: Highlight the entire active row.
-    - **Highlight Symbol:** Adding a visual indicator (like `> `) to the selected row.
-- **Spacing:** Adjusting `column_spacing` and `highlight_spacing` to control layout density.
-- **Flex Layout:** Switching between different column distribution modes (`legacy`, `start`, `space_between`, etc.).
-- **Offset Control:** Manually controlling the scroll position using `offset`.
-
-## Hotkeys
-
-- **Arrows (↑/↓)**: Navigate Rows (`selected_row`)
-- **Arrows (←/→)**: Navigate Columns (`selected_column`)
-- **x**: Toggle Row Selection (`selected_row` = nil)
-- **s**: Cycle Table Style (`style`)
-- **p**: Cycle Spacing (`highlight_spacing`)
-- **c**: Toggle Column Highlight (`column_highlight_style`)
-- **z**: Toggle Cell Highlight (`cell_highlight_style`)
-- **o**: Cycle Offset Mode (`offset`)
-- **f**: Cycle Flex Mode (`flex`)
-- **q**: Quit
-
-## Usage
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_table/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## Learning Outcomes
-
-Use this example if you need to...
-
-- Build a file explorer or process list.
-- Create a data-heavy dashboard.
-- Handle conflicting style requirements (e.g., "Highlight this row, but make this error cell red").
-
-[Read the source code →](app.rb)