ratatui_ruby 0.5.0 → 0.6.0

data/lib/ratatui_ruby/schema/gauge.rb

@@ -28,6 +28,8 @@ module RatatuiRuby
     # :attr_reader: label
     # Text label to display (optional).
     #
+    # Accepts String or Text::Span for rich styling.
+    #
     # If nil, it often displays the percentage automatically depending on renderer logic,
     # but explicit labels are preferred.
 
@@ -52,7 +54,7 @@ module RatatuiRuby
     #
     # [ratio] Float (0.0 - 1.0).
     # [percent] Integer (0 - 100), alternative to ratio.
-    # [label] String (optional).
+    # [label] String or Text::Span (optional).
     # [style] Style object for the background (optional).
     # [gauge_style] Style object for the filled bar (optional).
     # [block] Block widget (optional).

data/lib/ratatui_ruby/schema/line_gauge.rb

@@ -26,7 +26,7 @@ module RatatuiRuby
 
     ##
     # :attr_reader: label
-    # Optional label.
+    # Optional label (String or Text::Span for rich styling).
 
     ##
     # :attr_reader: style
@@ -55,7 +55,7 @@ module RatatuiRuby
     # Creates a new LineGauge.
     #
     # [ratio] Float (0.0 - 1.0).
-    # [label] String (optional).
+    # [label] String or Text::Span (optional).
     # [style] Style (optional, base style for the gauge).
     # [filled_style] Style.
     # [unfilled_style] Style.

data/lib/ratatui_ruby/schema/list.rb

@@ -27,15 +27,34 @@ module RatatuiRuby
   #     highlight_style: Style.new(bg: :blue),
   #     highlight_symbol: ">> "
   #   )
-  class List < Data.define(:items, :selected_index, :style, :highlight_style, :highlight_symbol, :repeat_highlight_symbol, :highlight_spacing, :direction, :scroll_padding, :block)
+  class List < Data.define(:items, :selected_index, :offset, :style, :highlight_style, :highlight_symbol, :repeat_highlight_symbol, :highlight_spacing, :direction, :scroll_padding, :block)
     ##
     # :attr_reader: items
-    # The items to display (Array of Strings).
+    # The items to display.
+    #
+    # Accepts Array of Strings, Text::Spans, Text::Lines, or ListItem objects.
+    # For styled individual rows, use ListItem with a style.
 
     ##
     # :attr_reader: selected_index
     # Index of the active selection (Integer or nil).
 
+    ##
+    # :attr_reader: offset
+    # Scroll offset (Integer or nil).
+    #
+    # Controls the viewport's starting position in the list.
+    #
+    # When +nil+ (default), Ratatui auto-scrolls to keep the selection visible ("natural scrolling").
+    #
+    # When set, forces the viewport to start at this item index. Use this for:
+    # - **Passive scrolling**: Scroll through a log viewer without selecting items.
+    # - **Click-to-select math**: Calculate which item index corresponds to a click coordinate.
+    #
+    # *Important*: When both +offset+ and +selected_index+ are set, Ratatui may still adjust
+    # the viewport during rendering to ensure the selection stays visible. Set +selected_index+
+    # to +nil+ for fully manual scroll control.
+
     ##
     # :attr_reader: style
     # Base style for unselected items.
@@ -76,8 +95,9 @@ module RatatuiRuby
     #
     # Integer parameters accept any object responding to +to_int+ or +to_i+ (duck-typed).
     #
-    # [items] Array of Strings.
+    # [items] Array of Strings, Text::Spans, Text::Lines, or ListItem objects.
     # [selected_index] Numeric (nullable, coerced to Integer).
+    # [offset] Numeric (nullable, coerced to Integer). Forces scroll position when set.
     # [style] Style object.
     # [highlight_style] Style object.
     # [highlight_symbol] String (default: <tt>"> "</tt>).
@@ -86,10 +106,11 @@ module RatatuiRuby
     # [direction] Symbol (default: <tt>:top_to_bottom</tt>).
     # [scroll_padding] Numeric (nullable, coerced to Integer, default: <tt>nil</tt>).
     # [block] Block (optional).
-    def initialize(items: [], selected_index: nil, style: nil, highlight_style: nil, highlight_symbol: "> ", repeat_highlight_symbol: false, highlight_spacing: :when_selected, direction: :top_to_bottom, scroll_padding: nil, block: nil)
+    def initialize(items: [], selected_index: nil, offset: nil, style: nil, highlight_style: nil, highlight_symbol: "> ", repeat_highlight_symbol: false, highlight_spacing: :when_selected, direction: :top_to_bottom, scroll_padding: nil, block: nil)
       super(
         items:,
         selected_index: selected_index.nil? ? nil : Integer(selected_index),
+        offset: offset.nil? ? nil : Integer(offset),
         style:,
         highlight_style:,
         highlight_symbol:,

data/lib/ratatui_ruby/schema/list_item.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # A styled list item combining content with optional style.
+  #
+  # By default, List items are strings. For more control over styling individual rows,
+  # wrap the content in a ListItem to apply a style specific to that item.
+  #
+  # The content can be a String, Text::Span, or Text::Line. The style applies to the
+  # entire row background.
+  #
+  # === Examples
+  #
+  #   # Item with red background
+  #   ListItem.new(content: "Error", style: Style.new(bg: :red))
+  #
+  #   # Item with styled content
+  #   ListItem.new(
+  #     content: Text::Span.new(content: "Status: OK", style: Style.new(fg: :green, modifiers: [:bold]))
+  #   )
+  class ListItem < Data.define(:content, :style)
+    ##
+    # :attr_reader: content
+    # The content to display (String, Text::Span, or Text::Line).
+
+    ##
+    # :attr_reader: style
+    # The style to apply to the item (optional Style).
+
+    # Creates a new ListItem.
+    #
+    # [content] String, Text::Span, or Text::Line.
+    # [style] Style object (optional).
+    def initialize(content:, style: nil)
+      super
+    end
+  end
+end

data/lib/ratatui_ruby/schema/rect.rb

@@ -69,5 +69,48 @@ module RatatuiRuby
     def contains?(px, py)
       px >= x && px < x + width && py >= y && py < y + height
     end
+
+    # Tests whether this rectangle overlaps with another.
+    #
+    # Essential for determining if a widget is visible within a viewport or clipping area.
+    #
+    #   viewport = Rect.new(x: 0, y: 0, width: 80, height: 24)
+    #   widget = Rect.new(x: 70, y: 20, width: 20, height: 10)
+    #   viewport.intersects?(widget) # => true (partial overlap)
+    #
+    # [other]
+    #   Another Rect to test against.
+    #
+    # Returns true if the rectangles overlap.
+    def intersects?(other)
+      x < other.x + other.width &&
+        x + width > other.x &&
+        y < other.y + other.height &&
+        y + height > other.y
+    end
+
+    # Returns the overlapping area between this rectangle and another.
+    #
+    # Essential for calculating visible portions of widgets inside scroll views.
+    #
+    #   viewport = Rect.new(x: 0, y: 0, width: 80, height: 24)
+    #   widget = Rect.new(x: 70, y: 20, width: 20, height: 10)
+    #   visible = viewport.intersection(widget)
+    #   # => Rect(x: 70, y: 20, width: 10, height: 4)
+    #
+    # [other]
+    #   Another Rect to intersect with.
+    #
+    # Returns a new Rect representing the intersection, or +nil+ if no overlap.
+    def intersection(other)
+      return nil unless intersects?(other)
+
+      new_x = [x, other.x].max
+      new_y = [y, other.y].max
+      new_right = [x + width, other.x + other.width].min
+      new_bottom = [y + height, other.y + other.height].min
+
+      Rect.new(x: new_x, y: new_y, width: new_right - new_x, height: new_bottom - new_y)
+    end
   end
 end

data/lib/ratatui_ruby/schema/style.rb

@@ -20,18 +20,38 @@ module RatatuiRuby
   #
   #   # Hex colors
   #   Style.new(fg: "#ff00ff")
+  #
+  # === Supported Colors
+  #
+  # ==== Integer
+  # Represents an indexed color from the Xterm 256-color palette (0-255).
+  # * <tt>0</tt>–<tt>15</tt>: Standard and bright ANSI colors.
+  # * <tt>16</tt>–<tt>231</tt>: {6x6x6 Color Cube}[https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit].
+  # * <tt>232</tt>–<tt>255</tt>: Grayscale ramp.
+  #
+  # ==== Symbol
+  # Represents a named color from the standard ANSI palette. Supported values:
+  # * <tt>:black</tt>, <tt>:red</tt>, <tt>:green</tt>, <tt>:yellow</tt>,
+  #   <tt>:blue</tt>, <tt>:magenta</tt>, <tt>:cyan</tt>, <tt>:gray</tt>
+  # * <tt>:dark_gray</tt>, <tt>:light_red</tt>, <tt>:light_green</tt>,
+  #   <tt>:light_yellow</tt>, <tt>:light_blue</tt>, <tt>:light_magenta</tt>,
+  #   <tt>:light_cyan</tt>, <tt>:white</tt>
+  #
+  # ==== String
+  # Represents a specific RGB color using a Hex code (<tt>"#RRGGBB"</tt>).
+  # Requires a terminal emulator with "True Color" (24-bit color) support.
   class Style < Data.define(:fg, :bg, :modifiers)
     ##
     # :attr_reader: fg
     # Foreground color.
     #
-    # Symbol (<tt>:red</tt>) or Hex String (<tt>"#ffffff"</tt>).
+    # Symbol (<tt>:red</tt>), Hex String (<tt>"#ffffff"</tt>), or Integer (0-255).
 
     ##
     # :attr_reader: bg
     # Background color.
     #
-    # Symbol (<tt>:black</tt>) or Hex String (<tt>"#000000"</tt>).
+    # Symbol (<tt>:black</tt>), Hex String (<tt>"#000000"</tt>), or Integer (0-255).
 
     ##
     # :attr_reader: modifiers
@@ -42,8 +62,8 @@ module RatatuiRuby
 
     # Creates a new Style.
     #
-    # [fg] Color (Symbol/String).
-    # [bg] Color (Symbol/String).
+    # [fg] Color (Symbol/String/Integer).
+    # [bg] Color (Symbol/String/Integer).
     # [modifiers] Array of Symbols.
     def initialize(fg: nil, bg: nil, modifiers: [])
       super

data/lib/ratatui_ruby/schema/table.rb

@@ -20,7 +20,7 @@ module RatatuiRuby
   # Run the interactive demo from the terminal:
   #
   #   ruby examples/widget_table_flex/app.rb
-  class Table < Data.define(:header, :rows, :widths, :highlight_style, :highlight_symbol, :highlight_spacing, :column_highlight_style, :cell_highlight_style, :selected_row, :selected_column, :block, :footer, :flex, :style, :column_spacing)
+  class Table < Data.define(:header, :rows, :widths, :highlight_style, :highlight_symbol, :highlight_spacing, :column_highlight_style, :cell_highlight_style, :selected_row, :selected_column, :offset, :block, :footer, :flex, :style, :column_spacing)
     ##
     # :attr_reader: header
     # Header row content (Array of Strings).
@@ -43,7 +43,7 @@ module RatatuiRuby
 
     ##
     # :attr_reader: highlight_spacing
-    # When to show the highlight symbol column (:always, :when_selected, :never).
+    # When to show the highlight symbol column (<tt>:always</tt>, <tt>:when_selected</tt>, <tt>:never</tt>).
 
     ##
     # :attr_reader: column_highlight_style
@@ -61,6 +61,22 @@ module RatatuiRuby
     # :attr_reader: selected_column
     # Index of the selected column (Integer or nil).
 
+    ##
+    # :attr_reader: offset
+    # Scroll offset (Integer or nil).
+    #
+    # Controls the viewport's starting row position in the table.
+    #
+    # When +nil+ (default), Ratatui auto-scrolls to keep the selection visible ("natural scrolling").
+    #
+    # When set, forces the viewport to start at this row index. Use this for:
+    # - **Passive scrolling**: Scroll through a log table without selecting rows.
+    # - **Click-to-select math**: Calculate which row index corresponds to a click coordinate.
+    #
+    # *Important*: When both +offset+ and +selected_row+ are set, Ratatui may still adjust
+    # the viewport during rendering to ensure the selection stays visible. Set +selected_row+
+    # to +nil+ for fully manual scroll control.
+
     ##
     # :attr_reader: block
     # Optional wrapping block.
@@ -93,12 +109,13 @@ module RatatuiRuby
     # [cell_highlight_style] Style object.
     # [selected_row] Integer (nullable).
     # [selected_column] Integer (nullable).
+    # [offset] Numeric (nullable, coerced to Integer). Forces scroll position when set.
     # [block] Block (optional).
     # [footer] Array of strings/paragraphs (optional).
     # [flex] Symbol (optional, default: <tt>:legacy</tt>).
     # [style] Style object or Hash (optional).
     # [column_spacing] Integer (optional, default: 1).
-    def initialize(header: nil, rows: [], widths: [], highlight_style: nil, highlight_symbol: "> ", highlight_spacing: :when_selected, column_highlight_style: nil, cell_highlight_style: nil, selected_row: nil, selected_column: nil, block: nil, footer: nil, flex: :legacy, style: nil, column_spacing: 1)
+    def initialize(header: nil, rows: [], widths: [], highlight_style: nil, highlight_symbol: "> ", highlight_spacing: :when_selected, column_highlight_style: nil, cell_highlight_style: nil, selected_row: nil, selected_column: nil, offset: nil, block: nil, footer: nil, flex: :legacy, style: nil, column_spacing: 1)
       super(
         header:,
         rows:,
@@ -110,6 +127,7 @@ module RatatuiRuby
         cell_highlight_style:,
         selected_row: selected_row.nil? ? nil : Integer(selected_row),
         selected_column: selected_column.nil? ? nil : Integer(selected_column),
+        offset: offset.nil? ? nil : Integer(offset),
         block:,
         footer:,
         flex:,

data/lib/ratatui_ruby/schema/text.rb

@@ -4,8 +4,42 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # Namespace for rich text components (Span and Line).
+  # Namespace for rich text components (Span, Line) and text utilities.
   # Distinct from canvas shapes and other Line usages.
+  #
+  # == Text Measurement
+  #
+  # The Text module provides a utility method for calculating the display width
+  # of strings in terminal cells. This accounts for unicode complexity:
+  #
+  # - ASCII characters: 1 cell each
+  # - CJK (Chinese, Japanese, Korean) characters: 2 cells each (full-width)
+  # - Emoji: typically 2 cells each (varies by terminal)
+  # - Combining marks: 0 cells (zero-width)
+  #
+  # This is essential for layout calculations in TUI applications, where you need to know
+  # how much space a string will occupy on the screen, not just its byte or character length.
+  #
+  # === Use Cases
+  #
+  # - Auto-sizing widgets (Button, Badge) that fit their content
+  # - Calculating padding or centering for text alignment
+  # - Building responsive layouts that adapt to content width
+  # - Measuring text for scrolling or truncation logic
+  #
+  # === Examples
+  #
+  #   # Simple ASCII text
+  #   RatatuiRuby::Text.width("Hello")        # => 5
+  #
+  #   # With emoji
+  #   RatatuiRuby::Text.width("Hello 👍")     # => 8 (5 + space + 2-width emoji)
+  #
+  #   # With CJK characters
+  #   RatatuiRuby::Text.width("你好")         # => 4 (each CJK char is 2 cells)
+  #
+  #   # Mixed content
+  #   RatatuiRuby::Text.width("Hi 你好 👍")   # => 11 (2 + space + 4 + space + 2)
   module Text
     # A styled string fragment.
     #
@@ -86,5 +120,39 @@ module RatatuiRuby
         new(spans: [Span.new(content:, style: nil)], alignment:)
       end
     end
+
+    ##
+    # :method: width
+    # :call-seq: width(string) -> Integer
+    #
+    # Calculates the display width of a string in terminal cells.
+    #
+    # Layout demands precision. Terminals measure space in cells, not characters. An ASCII letter occupies one cell. A Chinese character occupies two. An emoji occupies two. Combining marks occupy zero.
+    #
+    # Measuring width manually is error-prone. You can count <tt>string.length</tt>, but that counts characters, not cells. A string with one emoji counts as 1 character but occupies 2 cells.
+    #
+    # This method returns the true display width. Use it to auto-size widgets, calculate padding, center text, or build responsive layouts.
+    #
+    # === Examples
+    #
+    #   RatatuiRuby::Text.width("Hello")        # => 5 (5 ASCII chars × 1 cell)
+    #
+    #   RatatuiRuby::Text.width("你好")         # => 4 (2 CJK chars × 2 cells)
+    #
+    #   RatatuiRuby::Text.width("Hello 👍")     # => 8 (5 ASCII + 1 space + 1 emoji × 2)
+    #
+    #   # In the Session DSL (easier)
+    #   RatatuiRuby.run do |tui|
+    #     width = tui.text_width("Hello 👍")
+    #   end
+    #
+    # [string] String to measure (String or object convertible to String)
+    # Returns: Integer (number of terminal cells the string occupies)
+    # Raises: TypeError if the argument is not a String
+    #
+    # (Native method implemented in Rust)
+    def self.width(string)
+      RatatuiRuby._text_width(string)
+    end
   end
 end

data/lib/ratatui_ruby/scrollbar_state.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Mutable state object for Scrollbar widgets.
+  #
+  # When using {Frame#render_stateful_widget}, the State object is the
+  # *single source of truth* for position and content length. Widget
+  # properties (+position+, +content_length+) are *ignored* in stateful mode.
+  #
+  # == Example
+  #
+  #   @scrollbar_state = RatatuiRuby::ScrollbarState.new(100)
+  #   @scrollbar_state.position = 25
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     scrollbar = RatatuiRuby::Scrollbar.new(orientation: :vertical_right)
+  #     frame.render_stateful_widget(scrollbar, frame.area, @scrollbar_state)
+  #   end
+  #
+  class ScrollbarState
+    ##
+    # :method: new
+    # :call-seq: new(content_length) -> ScrollbarState
+    #
+    # Creates a new ScrollbarState with the given content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: position
+    # :call-seq: position() -> Integer
+    #
+    # Returns the current scroll position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: position=
+    # :call-seq: position=(value) -> Integer
+    #
+    # Sets the current scroll position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: content_length
+    # :call-seq: content_length() -> Integer
+    #
+    # Returns the total content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: content_length=
+    # :call-seq: content_length=(value) -> Integer
+    #
+    # Sets the total content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: viewport_content_length
+    # :call-seq: viewport_content_length() -> Integer
+    #
+    # Returns the viewport content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: viewport_content_length=
+    # :call-seq: viewport_content_length=(value) -> Integer
+    #
+    # Sets the viewport content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: first
+    # :call-seq: first() -> nil
+    #
+    # Scrolls to the first position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: last
+    # :call-seq: last() -> nil
+    #
+    # Scrolls to the last position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: next
+    # :call-seq: next() -> nil
+    #
+    # Scrolls to the next position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: prev
+    # :call-seq: prev() -> nil
+    #
+    # Scrolls to the previous position.
+    #
+    # (Native method implemented in Rust)
+  end
+end

data/lib/ratatui_ruby/session/autodoc.rb

@@ -26,6 +26,11 @@ module RatatuiRuby
     #
     # Delegates to RatatuiRuby._tabs_width.
     #
+    # :method: _text_width
+    # :call-seq: _text_width(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby._text_width.
+    #
     # :method: clear_events
     # :call-seq: clear_events(*args, **kwargs, &block)
     #
@@ -223,6 +228,16 @@ module RatatuiRuby
     #
     # Factory for RatatuiRuby::Dataset.new.
     #
+    # :method: draw_cell
+    # :call-seq: draw_cell(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Draw.cell.
+    #
+    # :method: draw_string
+    # :call-seq: draw_string(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Draw.string.
+    #
     # :method: draw_cell_cmd
     # :call-seq: draw_cell_cmd(*args, **kwargs, &block)
     #
@@ -238,6 +253,16 @@ module RatatuiRuby
     #
     # Factory for RatatuiRuby::Error.new.
     #
+    # :method: error_safety
+    # :call-seq: error_safety(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Error::Safety.new.
+    #
+    # :method: error_terminal
+    # :call-seq: error_terminal(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Error::Terminal.new.
+    #
     # :method: event
     # :call-seq: event(*args, **kwargs, &block)
     #
@@ -313,6 +338,21 @@ module RatatuiRuby
     #
     # Factory for RatatuiRuby::List.new.
     #
+    # :method: list_item
+    # :call-seq: list_item(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::ListItem.new.
+    #
+    # :method: list_state
+    # :call-seq: list_state(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::ListState.new.
+    #
+    # :method: list_state_new
+    # :call-seq: list_state_new(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::ListState.new.
+    #
     # :method: overlay
     # :call-seq: overlay(*args, **kwargs, &block)
     #
@@ -348,6 +388,16 @@ module RatatuiRuby
     #
     # Factory for RatatuiRuby::Scrollbar.new.
     #
+    # :method: scrollbar_state
+    # :call-seq: scrollbar_state(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::ScrollbarState.new.
+    #
+    # :method: scrollbar_state_new
+    # :call-seq: scrollbar_state_new(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::ScrollbarState.new.
+    #
     # :method: shape_circle
     # :call-seq: shape_circle(*args, **kwargs, &block)
     #
@@ -398,11 +448,26 @@ module RatatuiRuby
     #
     # Factory for RatatuiRuby::Table.new.
     #
+    # :method: table_state
+    # :call-seq: table_state(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::TableState.new.
+    #
+    # :method: table_state_new
+    # :call-seq: table_state_new(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::TableState.new.
+    #
     # :method: tabs
     # :call-seq: tabs(*args, **kwargs, &block)
     #
     # Factory for RatatuiRuby::Tabs.new.
     #
+    # :method: text_width
+    # :call-seq: text_width(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Text.width.
+    #
     # :method: text_line
     # :call-seq: text_line(*args, **kwargs, &block)
     #

data/lib/ratatui_ruby/session.rb

@@ -12,6 +12,14 @@ module RatatuiRuby
   #
   # Use it within <tt>RatatuiRuby.run</tt> to build your interface cleanly.
   #
+  # == Thread/Ractor Safety
+  #
+  # Session is an *I/O handle*, not a data object. It has side effects (draw,
+  # poll_event) and is intentionally *not* Ractor-shareable. Caching it in
+  # instance variables (<tt>@tui = tui</tt>) during your application's run loop
+  # is fine. However, do not include it in immutable TEA Models/Messages or
+  # pass it to other Ractors.
+  #
   # == Available Methods
   #
   # The session dynamically defines factory methods for all RatatuiRuby constants.
@@ -40,6 +48,7 @@ module RatatuiRuby
   #
   # *   <tt>text_span(...)</tt> -> <tt>RatatuiRuby::Text::Span.new(...)</tt>
   # *   <tt>text_line(...)</tt> -> <tt>RatatuiRuby::Text::Line.new(...)</tt>
+  # *   <tt>text_width(string)</tt> -> <tt>RatatuiRuby::Text.width(string)</tt>
   #
   # === Examples
   #
@@ -123,15 +132,21 @@ module RatatuiRuby
         define_method(method_name) do |*args, **kwargs, &block|
           const.new(*args, **kwargs, &block)
         end
+      end
+
+      # 2. Singleton Method Helpers (for both Classes and Modules)
+      #    e.g. Layout.split -> layout_split
+      #    e.g. Text.width -> text_width
+      const.singleton_methods(false).each do |class_method|
+        parent_prefix = const_name.to_s
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
 
-        # 2. Class Method Helpers (for Classes only)
-        #    e.g. Layout.split -> layout_split
-        const.singleton_methods(false).each do |class_method|
-          session_method_name = "#{method_name}_#{class_method}"
+        session_method_name = "#{parent_prefix}_#{class_method}"
 
-          define_method(session_method_name) do |*args, **kwargs, &block|
-            const.public_send(class_method, *args, **kwargs, &block)
-          end
+        define_method(session_method_name) do |*args, **kwargs, &block|
+          const.public_send(class_method, *args, **kwargs, &block)
         end
       end