ratatui_ruby 0.5.0 → 0.6.0

data/examples/widget_scrollbar_demo/README.md

@@ -0,0 +1,37 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Scrollbar Widget Example
+
+Demonstrates explicit scrollbars for navigation feedback.
+
+Content overflows. Users get lost in long lists. Scrollbars provide essential spatial awareness ("How far down am I?") and navigation controls.
+
+## Features Demonstrated
+
+- **Orientation**: Vertical, Horizontal, and variation modes (Right/Left, Top/Bottom).
+- **Styling**: Custom characters for Track, Thumb, and arrows.
+- **State Integration**: Linking the scrollbar `position` to the content view state.
+
+## Hotkeys
+
+- **Mouse Wheel**: Scroll content (`position`)
+- **s**: Cycle Scrollbar Theme (Standard, Rounded, ASCII, Minimal)
+- **o**: Cycle Orientation (`orientation`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_scrollbar_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Add visual scroll indicators to Lists or Tables.
+- Implement specialized inputs like sliders or volume controls.
+
+![Demo](/doc/images/widget_scrollbar_demo.png)

data/examples/widget_sparkline_demo/README.md

@@ -0,0 +1,42 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Sparkline Widget Example
+
+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
+
+```bash
+ruby examples/widget_sparkline_demo/app.rb
+```
+
+## 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.
+
+![Demo](/doc/images/widget_sparkline_demo.png)

data/examples/widget_sparkline_demo/app.rb

@@ -57,7 +57,8 @@ class WidgetSparklineDemo
         data: [1, 5, 1, 8, 1, 6, 1, 9, 1, 7, 1, 10],
       },
     ]
-    @data_index = 0
+    @data_index = 2
+    srand(12345) # Ensure reproducible "Random" data for snapshots
 
     @directions = [
       { name: "Left to Right", direction: :left_to_right },
@@ -72,7 +73,7 @@ class WidgetSparklineDemo
       { name: "Cyan", style: @tui.style(fg: :cyan) },
       { name: "Magenta", style: @tui.style(fg: :magenta) },
     ]
-    @style_index = 0
+    @style_index = 3
 
     @absent_symbols = [
       { name: "None", symbol: nil },
@@ -89,7 +90,7 @@ class WidgetSparklineDemo
       { name: "Dim Red", style: @tui.style(fg: :red, modifiers: [:dim]) },
       { name: "Dim Yellow", style: @tui.style(fg: :yellow, modifiers: [:dim]) },
     ]
-    @absent_style_index = 0
+    @absent_style_index = 2
 
     @bar_sets = [
       { name: "Default (Block)", set: nil },

data/examples/widget_style_colors/README.md

@@ -0,0 +1,34 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Style Colors Example
+
+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
+
+```bash
+ruby examples/widget_style_colors/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Create meaningful heatmaps.
+- Generate color palettes dynamically.
+- Test your terminal's color support capabilities.
+
+![Demo](/doc/images/widget_style_colors.png)

data/examples/widget_table_demo/README.md

@@ -0,0 +1,48 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Table Widget Example
+
+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
+
+```bash
+ruby examples/widget_table_demo/app.rb
+```
+
+## 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").
+
+![Demo](/doc/images/widget_table_demo.png)

data/examples/{app_table_select → widget_table_demo}/app.rb

@@ -1,4 +1,3 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
@@ -19,7 +18,7 @@ PROCESSES = [
   { pid: 6789, name: "node", cpu: 18.9 },
 ].freeze
 
-class AppTableSelect
+class WidgetTableDemo
   attr_reader :selected_index, :selected_col, :current_style_index, :column_spacing, :highlight_spacing, :column_highlight_style, :cell_highlight_style
 
   HIGHLIGHT_SPACINGS = [
@@ -28,6 +27,22 @@ class AppTableSelect
     { name: "Never", spacing: :never },
   ].freeze
 
+  OFFSET_MODES = [
+    { name: "Auto (No Offset)", offset: nil, allow_selection: true },
+    { name: "Offset Only (row 3)", offset: 3, allow_selection: false },
+    { name: "Selection + Offset (Conflict)", offset: 0, allow_selection: true },
+  ].freeze
+
+  FLEX_MODES = [
+    { name: "Legacy (Default)", flex: :legacy },
+    { name: "Start", flex: :start },
+    { name: "Center", flex: :center },
+    { name: "End", flex: :end },
+    { name: "Space Between", flex: :space_between },
+    { name: "Space Around", flex: :space_around },
+    { name: "Space Evenly", flex: :space_evenly },
+  ].freeze
+
   def initialize
     @selected_index = 1
     @selected_col = 1
@@ -36,6 +51,8 @@ class AppTableSelect
     @highlight_spacing_index = 0
     @show_column_highlight = true
     @show_cell_highlight = true
+    @offset_mode_index = 0
+    @flex_mode_index = 0
   end
 
   def run
@@ -80,15 +97,23 @@ class AppTableSelect
 
     current_style_entry = @styles[@current_style_index]
     current_spacing_entry = HIGHLIGHT_SPACINGS[@highlight_spacing_index]
-    selection_label = @selected_index.nil? ? "none" : @selected_index.to_s
+    offset_mode_entry = OFFSET_MODES[@offset_mode_index]
+    flex_mode_entry = FLEX_MODES[@flex_mode_index]
+
+    # Determine selection/offset based on mode
+    effective_selection = offset_mode_entry[:allow_selection] ? @selected_index : nil
+    effective_offset = offset_mode_entry[:offset]
+    selection_label = effective_selection.nil? ? "none" : effective_selection.to_s
+    offset_label = effective_offset.nil? ? "auto" : effective_offset.to_s
 
     # Main table
     table = @tui.table(
       header: ["PID", "Name", "CPU"],
       rows:,
       widths:,
-      selected_row: @selected_index,
+      selected_row: effective_selection,
       selected_column: @selected_col,
+      offset: effective_offset,
       highlight_style:,
       highlight_symbol: "> ",
       highlight_spacing: current_spacing_entry[:spacing],
@@ -96,8 +121,9 @@ class AppTableSelect
       cell_highlight_style: @show_cell_highlight ? @cell_highlight_style : nil,
       style: current_style_entry[:style],
       column_spacing: @column_spacing,
+      flex: flex_mode_entry[:flex],
       block: @tui.block(
-        title: "Processes",
+        title: "Processes | Sel: #{selection_label} | Offset: #{offset_label} | Flex: #{flex_mode_entry[:name]}",
         borders: :all
       ),
       footer: ["Total: #{PROCESSES.length}", "Total CPU: #{PROCESSES.sum { |p| p[:cpu] }}%", ""]
@@ -130,11 +156,19 @@ class AppTableSelect
             ]),
             # Line 3: More Controls
             @tui.text_line(spans: [
+              @tui.text_span(content: "+/-", style: @hotkey_style),
               @tui.text_span(content: ": Col Space (#{@column_spacing})  "),
               @tui.text_span(content: "c", style: @hotkey_style),
               @tui.text_span(content: ": Col Highlight (#{@show_column_highlight ? 'On' : 'Off'})  "),
+              @tui.text_span(content: "f", style: @hotkey_style),
+              @tui.text_span(content: ": Flex Mode (#{flex_mode_entry[:name]})"),
+            ]),
+            # Line 4: Offset Mode
+            @tui.text_line(spans: [
               @tui.text_span(content: "z", style: @hotkey_style),
-              @tui.text_span(content: ": Cell Highlight (#{@show_cell_highlight ? 'On' : 'Off'})"),
+              @tui.text_span(content: ": Cell Highlight (#{@show_cell_highlight ? 'On' : 'Off'})  "),
+              @tui.text_span(content: "o", style: @hotkey_style),
+              @tui.text_span(content: ": Offset Mode (#{offset_mode_entry[:name]})"),
             ]),
           ]
         ),
@@ -147,7 +181,7 @@ class AppTableSelect
       direction: :vertical,
       constraints: [
         @tui.constraint_fill(1),
-        @tui.constraint_length(5),
+        @tui.constraint_length(6),
       ]
     )
 
@@ -190,6 +224,10 @@ class AppTableSelect
       @show_column_highlight = !@show_column_highlight
     in type: :key, code: "z"
       @show_cell_highlight = !@show_cell_highlight
+    in type: :key, code: "o"
+      @offset_mode_index = (@offset_mode_index + 1) % OFFSET_MODES.length
+    in type: :key, code: "f"
+      @flex_mode_index = (@flex_mode_index + 1) % FLEX_MODES.length
     else
       nil
     end
@@ -197,5 +235,5 @@ class AppTableSelect
 end
 
 if __FILE__ == $0
-  AppTableSelect.new.run
+  WidgetTableDemo.new.run
 end

data/examples/widget_tabs_demo/README.md

@@ -0,0 +1,41 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Tabs Widget Example
+
+Demonstrates view segregation with interactive navigation.
+
+Screen real estate is limited. You cannot show everything at once. Tabs segregate content into specialized views (modes), allowing users to switch contexts easily.
+
+## Features Demonstrated
+
+- **Condition Rendering**: Changing the *content* of the screen based on the selected tab (Revenue vs Traffic vs Errors).
+- **Styling**: Configurable highlight styles, dividers, and padding.
+- **Interaction**: Keyboard navigation to cycle through tabs.
+
+## Hotkeys
+
+- **Left/Right (←/→)**: Select Tab (`selected_index`)
+- **d**: Cycle Divider Character (`divider`)
+- **s**: Cycle Highlight Style (`highlight_style`)
+- **b**: Cycle Base Style (`style`)
+- **h/l**: Adjust Left Padding (`padding_left`)
+- **j/k**: Adjust Right Padding (`padding_right`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_tabs_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Build a multi-pane dashboard.
+- Create a "Settings" screen with different categories.
+- Implement a "wizard" interface with steps.
+
+![Demo](/doc/images/widget_tabs_demo.png)

data/examples/widget_tabs_demo/app.rb

@@ -5,6 +5,7 @@
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
+require "faker"
 
 # Demonstrates view segregation with interactive tab navigation.
 #
@@ -35,6 +36,9 @@ class WidgetTabsDemo
     @padding_right = 0
     @width_constraint_index = 0
     @hotkey_style = nil
+
+    # Generate the content once, not on every frame
+    @tab_text = 4.times.map { |it| Faker::Lorem.paragraph(sentence_count: 10 + it) }
   end
 
   def run
@@ -77,11 +81,12 @@ class WidgetTabsDemo
       )
 
       # Center the tabs vertically in the main area
-      tabs_area, = @tui.layout_split(
+      tabs_area, content_area = @tui.layout_split(
         main_area,
         direction: :vertical,
         constraints: [
           @tui.constraint_length(3),
+          @tui.constraint_fill(1),
         ]
       )
 
@@ -96,6 +101,7 @@ class WidgetTabsDemo
         padding_right: @padding_right
       )
       frame.render_widget(tabs, tabs_area)
+      frame.render_widget(tab_contents, content_area)
 
       render_controls(frame, controls_area, tabs.width)
     end
@@ -162,6 +168,14 @@ class WidgetTabsDemo
       # Ignore other events
     end
   end
+
+  private def tab_contents
+    @tui.paragraph(
+      text: @tab_text[@selected_tab],
+      wrap: true,
+      block: @tui.block(borders: [:all], title: @tabs[@selected_tab])
+    )
+  end
 end
 
 WidgetTabsDemo.new.run if __FILE__ == $0

data/examples/widget_text_width/README.md

@@ -0,0 +1,35 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Text Width Calculator
+
+Demonstrates string width calculation in a terminal environment.
+
+Not all characters are created equal. In a TUI, "Width" means cell count, not string length. Emoji (`👍`) take 2 cells. Chinese characters (`你`) take 2 cells. The `tui.text_width` helper tells you the visual width of a string.
+
+## Features Demonstrated
+
+- **Unicode Width**: Rendering ASCII (1 cell), CJK (2 cells), and Emoji (2 cells).
+- **Calculation**: Comparing `string.length` vs `tui.text_width(string)`.
+
+## Hotkeys
+
+- **Up/Down (↑/↓)**: Cycle Text Sample
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_text_width/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Align text correctly in columns.
+- Truncate strings that are too long for a widget.
+- Build your own custom layout engine.
+
+![Demo](/doc/images/widget_text_width.png)

data/examples/widget_text_width/app.rb

@@ -0,0 +1,106 @@
+# 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 WidgetTextWidth
+  def initialize
+    @text_samples = [
+      { label: "ASCII", text: "Hello, World!", desc: "Simple English text" },
+      { label: "CJK", text: "你好世界", desc: "Chinese (full-width characters)" },
+      { label: "Emoji", text: "Hello 👍 World 🌍", desc: "Mixed text with emoji (2 cells each)" },
+      { label: "Mixed", text: "Hi 你好 👍", desc: "ASCII + CJK + emoji" },
+      { label: "Empty", text: "", desc: "Empty string" },
+    ]
+    @selected_index = 0
+  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: main content above, controls below
+      areas = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [@tui.constraint_fill(1), @tui.constraint_length(7)]
+      )
+
+      # Main content area with sample text
+      render_content(frame, areas[0])
+
+      # Controls footer
+      render_controls(frame, areas[1])
+    end
+  end
+
+  private def render_content(frame, area)
+    sample = @text_samples[@selected_index]
+    measured_width = @tui.text_width(sample[:text])
+
+    # Build content text with newlines
+    content = []
+    content << "Sample: #{sample[:text]}"
+    content << ""
+    content << "Display Width: #{measured_width} cells"
+    content << "Character Count: #{sample[:text].length}"
+    content << ""
+    content << sample[:desc]
+    text = content.join("\n")
+
+    widget = @tui.paragraph(
+      text:,
+      block: @tui.block(
+        title: "Text Width Calculator",
+        borders: [:all],
+        border_color: "cyan"
+      ),
+      alignment: :left
+    )
+
+    frame.render_widget(widget, area)
+  end
+
+  private def render_controls(frame, area)
+    info = "Sample #{@selected_index + 1}/#{@text_samples.length}: #{@text_samples[@selected_index][:label]}"
+    controls = "↑/↓ Select   q Quit"
+    text = "#{info}\n#{controls}"
+
+    widget = @tui.paragraph(
+      text:,
+      block: @tui.block(borders: [:top], border_color: "gray"),
+      alignment: :center
+    )
+
+    frame.render_widget(widget, area)
+  end
+
+  private def handle_input
+    event = @tui.poll_event
+    case event
+    in { type: :key, code: "q" }
+      :quit
+    in { type: :key, code: "up" }
+      @selected_index = (@selected_index - 1) % @text_samples.length
+      nil
+    in { type: :key, code: "down" }
+      @selected_index = (@selected_index + 1) % @text_samples.length
+      nil
+    else
+      nil
+    end
+  end
+end
+
+WidgetTextWidth.new.run if __FILE__ == $PROGRAM_NAME

data/ext/ratatui_ruby/Cargo.lock

@@ -956,7 +956,7 @@ dependencies = [
  "thiserror 2.0.17",
  "unicode-segmentation",
  "unicode-truncate",
- "unicode-width",
+ "unicode-width 0.2.0",
 ]
 
 [[package]]
@@ -1007,18 +1007,19 @@ dependencies = [
  "strum",
  "time",
  "unicode-segmentation",
- "unicode-width",
+ "unicode-width 0.2.0",
 ]
 
 [[package]]
 name = "ratatui_ruby"
-version = "0.5.0"
+version = "0.6.0"
 dependencies = [
  "bumpalo",
  "lazy_static",
  "magnus",
  "ratatui",
  "time",
+ "unicode-width 0.1.14",
 ]
 
 [[package]]
@@ -1464,9 +1465,15 @@ checksum = "8fbf03860ff438702f3910ca5f28f8dac63c1c11e7efb5012b8b175493606330"
 dependencies = [
  "itertools 0.13.0",
  "unicode-segmentation",
- "unicode-width",
+ "unicode-width 0.2.0",
 ]
 
+[[package]]
+name = "unicode-width"
+version = "0.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
+
 [[package]]
 name = "unicode-width"
 version = "0.2.0"

data/ext/ratatui_ruby/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "ratatui_ruby"
-version = "0.5.0"
+version = "0.6.0"
 edition = "2021"
 
 [lib]
@@ -12,6 +12,7 @@ crate-type = ["cdylib", "staticlib"]
 [dependencies]
 magnus = "0.8.2"
 ratatui = { version = "0.30", features = ["widget-calendar", "layout-cache", "unstable-rendered-line-info"] }
+unicode-width = "0.1"
 
 bumpalo = "3.16"
 lazy_static = "1.4"