ratatui_ruby 0.5.0 → 0.7.0

data/lib/ratatui_ruby/schema/table.rb

@@ -20,21 +20,21 @@ 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, :row_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).
+    # Header row content (Array of Strings, Text::Spans, Text::Lines, or Paragraphs).
 
     ##
     # :attr_reader: rows
-    # Data rows (Array of Arrays of Strings).
+    # Data rows (Array of Arrays). Each cell can be String, Text::Span, Text::Line, Paragraph, or Cell.
 
     ##
     # :attr_reader: widths
     # Column width constraints (Array of Constraint).
 
     ##
-    # :attr_reader: highlight_style
+    # :attr_reader: row_highlight_style
     # Style for the selected row.
 
     ##
@@ -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,13 +61,29 @@ 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.
 
     ##
     # :attr_reader: footer
-    # Footer row content (Array of Strings).
+    # Footer row content (Array of Strings, Text::Spans, Text::Lines, or Paragraphs).
 
     ##
     # :attr_reader: flex
@@ -83,33 +99,35 @@ module RatatuiRuby
 
     # Creates a new Table.
     #
-    # [header] Array of strings/paragraphs.
-    # [rows] 2D Array of strings/paragraphs.
+    # [header] Array of strings, Text::Spans, Text::Lines, or paragraphs.
+    # [rows] 2D Array where each cell is String, Text::Span, Text::Line, Paragraph, or Cell.
     # [widths] Array of Constraints.
-    # [highlight_style] Style object.
+    # [row_highlight_style] Style object.
     # [highlight_symbol] String.
     # [highlight_spacing] Symbol (optional, default: <tt>:when_selected</tt>).
     # [column_highlight_style] Style object.
     # [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: [], row_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:,
         widths:,
-        highlight_style:,
+        row_highlight_style:,
         highlight_symbol:,
         highlight_spacing:,
         column_highlight_style:,
         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.
     #
@@ -60,7 +94,7 @@ module RatatuiRuby
     #       Text::Span.styled("kerrick", Style.new(fg: :blue))
     #     ]
     #   )
-    class Line < Data.define(:spans, :alignment)
+    class Line < Data.define(:spans, :alignment, :style)
       ##
       # :attr_reader: spans
       # Array of Span objects.
@@ -71,11 +105,18 @@ module RatatuiRuby
       #
       # <tt>:left</tt>, <tt>:center</tt>, or <tt>:right</tt>.
 
+      ##
+      # :attr_reader: style
+      # Line-level style applied to all spans.
+      #
+      # A Style object that sets colors/modifiers for the entire line.
+
       # Creates a new Line.
       #
       # [spans] Array of Span objects (or Strings).
       # [alignment] Symbol (optional).
-      def initialize(spans: [], alignment: nil)
+      # [style] Style object (optional).
+      def initialize(spans: [], alignment: nil, style: nil)
         super
       end
 
@@ -85,6 +126,58 @@ module RatatuiRuby
       def self.from_string(content, alignment: nil)
         new(spans: [Span.new(content:, style: nil)], alignment:)
       end
+
+      # Calculates the display width of this line in terminal cells.
+      #
+      # Sums the widths of all span contents using the same unicode-aware
+      # algorithm as Text.width. Useful for layout calculations.
+      #
+      # === Examples
+      #
+      #   line = Text::Line.new(spans: [
+      #     Text::Span.new(content: "Hello "),
+      #     Text::Span.new(content: "世界")
+      #   ])
+      #   line.width  # => 10 (6 ASCII + 4 CJK)
+      #
+      # Returns: Integer (number of terminal cells)
+      def width
+        RatatuiRuby::Text.width(spans.map { |s| s.content.to_s }.join)
+      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/style/style.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Style
+    # Defines colors and text modifiers.
+    #
+    # The terminal is traditionally monochrome, but efficient interfaces use color to convey meaning.
+    # Red for errors. Green for success. Bold for headers.
+    #
+    # This value object encapsulates those choices. It applies foreground and background colors. It adds effects like italics or blinking.
+    #
+    # Use it to theme your application or highlight critical data.
+    #
+    # === Examples
+    #
+    #   # Standard colors
+    #   Style::Style.new(fg: :red, bg: :white, modifiers: [:bold])
+    #
+    #   # Hex colors
+    #   Style::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>), Hex String (<tt>"#ffffff"</tt>), or Integer (0-255).
+
+      ##
+      # :attr_reader: bg
+      # Background color.
+      #
+      # Symbol (<tt>:black</tt>), Hex String (<tt>"#000000"</tt>), or Integer (0-255).
+
+      ##
+      # :attr_reader: modifiers
+      # Text effects.
+      #
+      # Array of symbols: <tt>:bold</tt>, <tt>:dim</tt>, <tt>:italic</tt>, <tt>:underlined</tt>,
+      # <tt>:slow_blink</tt>, <tt>:rapid_blink</tt>, <tt>:reversed</tt>, <tt>:hidden</tt>, <tt>:crossed_out</tt>.
+
+      # Creates a new Style.
+      #
+      # [fg] Color (Symbol/String/Integer).
+      # [bg] Color (Symbol/String/Integer).
+      # [modifiers] Array of Symbols.
+      def initialize(fg: nil, bg: nil, modifiers: [])
+        super
+      end
+
+      # Returns an empty style.
+      #
+      # Use this as a baseline to prevent style inheritance issues or when no styling is required.
+      def self.default
+        new
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/style.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Styling primitives for colors and text effects.
+  #
+  # This module mirrors +ratatui::style+ and contains:
+  # - {Style} — Colors and modifiers
+  module Style
+  end
+end
+
+require_relative "style/style"

data/lib/ratatui_ruby/table_state.rb

@@ -0,0 +1,90 @@
+# 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 Table widgets.
+  #
+  # When using {Frame#render_stateful_widget}, the State object is the
+  # *single source of truth* for selection and scroll offset. Widget
+  # properties (+selected_row+, +selected_column+, +offset+) are *ignored*
+  # in stateful mode.
+  #
+  # == Example
+  #
+  #   @table_state = RatatuiRuby::TableState.new
+  #   @table_state.select(1)        # Select second row
+  #   @table_state.select_column(0) # Select first column
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     table = RatatuiRuby::Widgets::Table.new(rows: [...], widths: [...])
+  #     frame.render_stateful_widget(table, frame.area, @table_state)
+  #   end
+  #
+  class TableState
+    ##
+    # :method: new
+    # :call-seq: new(selected = nil) -> TableState
+    #
+    # Creates a new TableState with optional initial row selection.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select
+    # :call-seq: select(index) -> nil
+    #
+    # Sets the selected row index. Pass +nil+ to deselect.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: selected
+    # :call-seq: selected() -> Integer or nil
+    #
+    # Returns the currently selected row index.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_column
+    # :call-seq: select_column(index) -> nil
+    #
+    # Sets the selected column index. Pass +nil+ to deselect.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: selected_column
+    # :call-seq: selected_column() -> Integer or nil
+    #
+    # Returns the currently selected column index.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: offset
+    # :call-seq: offset() -> Integer
+    #
+    # Returns the current scroll offset.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: scroll_down_by
+    # :call-seq: scroll_down_by(n) -> nil
+    #
+    # Scrolls down by +n+ rows.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: scroll_up_by
+    # :call-seq: scroll_up_by(n) -> nil
+    #
+    # Scrolls up by +n+ rows.
+    #
+    # (Native method implemented in Rust)
+  end
+end