ratatui_ruby 0.4.0 → 0.6.0

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

@@ -0,0 +1,181 @@
+# 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"
+require "faker"
+
+# Demonstrates view segregation with interactive tab navigation.
+#
+# Screen real estate is limited. You cannot show everything at once. Segregating content into views is necessary for complex apps.
+#
+# This demo showcases the <tt>Tabs</tt> widget. It provides an interactive playground where you can select tabs, cycle through dividers and styles, and adjust padding in real-time.
+#
+# Use it to understand how to build major mode switches or context navigation for your interface.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_tabs_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_tabs_demo.png
+class WidgetTabsDemo
+  def initialize
+    @selected_tab = 0
+    @tabs = ["Revenue", "Traffic", "Errors", "Quarterly"]
+    @highlight_styles = nil
+    @highlight_style_index = 0
+    @divider_index = 0
+    @dividers = [" | ", " • ", " > ", " / "]
+    @base_styles = nil
+    @base_style_index = 0
+    @padding_left = 0
+    @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
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      init_styles
+
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def init_styles
+    @highlight_styles = [
+      { name: "Yellow Bold", style: @tui.style(fg: :yellow, modifiers: [:bold]) },
+      { name: "Italic Blue on White", style: @tui.style(fg: :blue, bg: :white, modifiers: [:italic]) },
+      { name: "Underlined Red", style: @tui.style(fg: :red, modifiers: [:underlined]) },
+      { name: "Reversed", style: @tui.style(modifiers: [:reversed]) },
+    ]
+    @base_styles = [
+      { name: "Default", style: nil },
+      { name: "White on Gray", style: @tui.style(fg: :white, bg: :dark_gray) },
+      { name: "White on Blue", style: @tui.style(fg: :white, bg: :blue) },
+      { name: "Italic", style: @tui.style(modifiers: [:italic]) },
+    ]
+    @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+  end
+
+  private def render
+    @tui.draw do |frame|
+      main_area, controls_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(5),
+        ]
+      )
+
+      # Center the tabs vertically in the main area
+      tabs_area, content_area = @tui.layout_split(
+        main_area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_length(3),
+          @tui.constraint_fill(1),
+        ]
+      )
+
+      tabs = @tui.tabs(
+        titles: @tabs,
+        selected_index: @selected_tab,
+        block: @tui.block(title: "Tabs Demo", borders: [:all]),
+        divider: @dividers[@divider_index],
+        highlight_style: @highlight_styles[@highlight_style_index][:style],
+        style: @base_styles[@base_style_index][:style],
+        padding_left: @padding_left,
+        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
+  end
+
+  private def render_controls(frame, area, current_width)
+    controls = @tui.block(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        @tui.paragraph(
+          text: [
+            @tui.text_line(spans: [
+              @tui.text_span(content: "←/→", style: @hotkey_style),
+              @tui.text_span(content: ": Select Tab  "),
+              @tui.text_span(content: "h/l", style: @hotkey_style),
+              @tui.text_span(content: ": Pad Left (#{@padding_left})  "),
+              @tui.text_span(content: "j/k", style: @hotkey_style),
+              @tui.text_span(content: ": Pad Right (#{@padding_right})  "),
+              @tui.text_span(content: "q", style: @hotkey_style),
+              @tui.text_span(content: ": Quit"),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "d", style: @hotkey_style),
+              @tui.text_span(content: ": Divider (#{@dividers[@divider_index]})  "),
+              @tui.text_span(content: "s", style: @hotkey_style),
+              @tui.text_span(content: ": Highlight (#{@highlight_styles[@highlight_style_index][:name]})  "),
+              @tui.text_span(content: "b", style: @hotkey_style),
+              @tui.text_span(content: ": Base Style (#{@base_styles[@base_style_index][:name]})  "),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "Width: #{current_width}"),
+            ]),
+          ]
+        ),
+      ]
+    )
+    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: "right"
+      @selected_tab = (@selected_tab + 1) % @tabs.size
+    in type: :key, code: "left"
+      @selected_tab = (@selected_tab - 1) % @tabs.size
+    in type: :key, code: "d"
+      @divider_index = (@divider_index + 1) % @dividers.size
+    in type: :key, code: "s"
+      @highlight_style_index = (@highlight_style_index + 1) % @highlight_styles.size
+    in type: :key, code: "b"
+      @base_style_index = (@base_style_index + 1) % @base_styles.size
+    in type: :key, code: "h"
+      @padding_left = [@padding_left - 1, 0].max
+    in type: :key, code: "l"
+      @padding_left += 1
+    in type: :key, code: "j"
+      @padding_right = [@padding_right - 1, 0].max
+    in type: :key, code: "k"
+      @padding_right += 1
+    else
+      # 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.4.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.4.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"