ratatui_ruby 0.5.0 → 0.7.0

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
@@ -65,8 +82,23 @@ class AppTableSelect
   end
 
   private def render(frame)
-    # Create table rows from process data
-    rows = PROCESSES.map { |p| [p[:pid].to_s, p[:name], "#{p[:cpu]}%"] }
+    # v0.7.0: Create table rows using table_row and table_cell for per-cell styling
+    rows = PROCESSES.map do |p|
+      cpu_style = case p[:cpu]
+                  when 0...10 then @tui.style(fg: :green)
+                  when 10...30 then @tui.style(fg: :yellow)
+                  else @tui.style(fg: :red, modifiers: [:bold])
+      end
+      @tui.table_row(
+        cells: [
+          p[:pid].to_s,
+          p[:name],
+          @tui.table_cell(content: "#{p[:cpu]}%", style: cpu_style),
+        ],
+        # Apply alternating row backgrounds for readability
+        style: p[:pid].even? ? @tui.style(bg: :dark_gray) : nil
+      )
+    end
 
     # Define column widths
     widths = [
@@ -76,28 +108,37 @@ class AppTableSelect
     ]
 
     # Create highlight style (yellow text)
-    highlight_style = @tui.style(fg: :yellow)
+    row_highlight_style = @tui.style(fg: :yellow)
 
     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,
-      highlight_style:,
+      offset: effective_offset,
+      row_highlight_style:,
       highlight_symbol: "> ",
       highlight_spacing: current_spacing_entry[:spacing],
       column_highlight_style: @show_column_highlight ? @column_highlight_style : nil,
       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 +171,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 +196,7 @@ class AppTableSelect
       direction: :vertical,
       constraints: [
         @tui.constraint_fill(1),
-        @tui.constraint_length(5),
+        @tui.constraint_length(6),
       ]
     )
 
@@ -190,6 +239,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 +250,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
+
+[![widget_tabs_demo](../../doc/images/widget_tabs_demo.png)](app.rb)
+
+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.

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
+
+[![widget_text_width](../../doc/images/widget_text_width.png)](app.rb)
+
+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.

data/examples/widget_text_width/app.rb

@@ -0,0 +1,113 @@
+# 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])
+
+    # v0.7.0: Text::Line#width instance method for rich text measurement
+    styled_line = @tui.text_line(spans: [
+      @tui.text_span(content: sample[:text], style: @tui.style(fg: :cyan)),
+    ])
+    line_width = styled_line.width
+
+    # Build content text with newlines
+    content = []
+    content << "Sample: #{sample[:text]}"
+    content << ""
+    content << "Display Width (text_width): #{measured_width} cells"
+    content << "Display Width (line.width): #{line_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.7.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.7.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"