ratatui_ruby 0.9.1 → 0.10.0

data/ext/ratatui_ruby/src/widgets/list.rs

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+use crate::errors::type_error_with_context;
 use crate::style::{parse_block, parse_style};
 use crate::text::{parse_line, parse_span};
 use crate::widgets::list_state::RubyListState;
@@ -18,7 +19,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let items_val: Value = node.funcall("items", ())?;
     let items_array = magnus::RArray::from_value(items_val)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array"))?;
+        .ok_or_else(|| type_error_with_context(&ruby, "expected array for items", items_val))?;
     let selected_index_val: Value = node.funcall("selected_index", ())?;
     let style_val: Value = node.funcall("style", ())?;
     let highlight_style_val: Value = node.funcall("highlight_style", ())?;
@@ -129,7 +130,7 @@ pub fn render_stateful(
     // Build items
     let items_val: Value = node.funcall("items", ())?;
     let items_array = magnus::RArray::from_value(items_val)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array"))?;
+        .ok_or_else(|| type_error_with_context(&ruby, "expected array for items", items_val))?;
 
     let mut items: Vec<ListItem> = Vec::new();
     for i in 0..items_array.len() {
@@ -270,10 +271,10 @@ fn parse_list_item(value: Value) -> Result<ListItem<'static>, Error> {
         return Ok(ListItem::new(Line::from(vec![span])));
     }
 
-    // Fallback
-    Err(Error::new(
-        ruby.exception_type_error(),
+    Err(type_error_with_context(
+        &ruby,
         "expected String, Text::Span, Text::Line, or ListItem",
+        value,
     ))
 }
 

data/ext/ratatui_ruby/src/widgets/overlay.rs

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+use crate::errors::type_error_with_context;
 use crate::rendering::render_node;
 use magnus::{prelude::*, Error, Value};
 use ratatui::{layout::Rect, Frame};
@@ -9,7 +10,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let layers_val: Value = node.funcall("layers", ())?;
     let layers_array = magnus::RArray::from_value(layers_val)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for layers"))?;
+        .ok_or_else(|| type_error_with_context(&ruby, "expected array for layers", layers_val))?;
 
     for i in 0..layers_array.len() {
         let index = isize::try_from(i)

data/ext/ratatui_ruby/src/widgets/table.rs

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+use crate::errors::type_error_with_context;
 use crate::style::{parse_block, parse_style};
 use crate::text::{parse_line, parse_span, parse_text};
 use crate::widgets::table_state::RubyTableState;
@@ -19,10 +20,10 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     let footer_val: Value = node.funcall("footer", ())?;
     let rows_value: Value = node.funcall("rows", ())?;
     let rows_array = magnus::RArray::from_value(rows_value)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for rows"))?;
+        .ok_or_else(|| type_error_with_context(&ruby, "expected array for rows", rows_value))?;
     let widths_val: Value = node.funcall("widths", ())?;
     let widths_array = magnus::RArray::from_value(widths_val)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for widths"))?;
+        .ok_or_else(|| type_error_with_context(&ruby, "expected array for widths", widths_val))?;
     let row_highlight_style_val: Value = node.funcall("row_highlight_style", ())?;
     let column_highlight_style_val: Value = node.funcall("column_highlight_style", ())?;
     let cell_highlight_style_val: Value = node.funcall("cell_highlight_style", ())?;
@@ -145,10 +146,10 @@ pub fn render_stateful(
     // Parse rows
     let rows_value: Value = node.funcall("rows", ())?;
     let rows_array = magnus::RArray::from_value(rows_value)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for rows"))?;
+        .ok_or_else(|| type_error_with_context(&ruby, "expected array for rows", rows_value))?;
     let widths_val: Value = node.funcall("widths", ())?;
     let widths_array = magnus::RArray::from_value(widths_val)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for widths"))?;
+        .ok_or_else(|| type_error_with_context(&ruby, "expected array for widths", widths_val))?;
 
     let mut rows = Vec::new();
     for i in 0..rows_array.len() {
@@ -251,7 +252,7 @@ fn parse_row(row_val: Value) -> Result<Row<'static>, Error> {
         let bottom_margin_val: Value = row_val.funcall("bottom_margin", ())?;
 
         let cells_array = magnus::RArray::from_value(cells_val).ok_or_else(|| {
-            Error::new(ruby.exception_type_error(), "expected array for Row.cells")
+            type_error_with_context(&ruby, "expected array for Row.cells", cells_val)
         })?;
 
         let mut cells = Vec::new();
@@ -285,7 +286,7 @@ fn parse_row(row_val: Value) -> Result<Row<'static>, Error> {
 
     // Fallback: plain array of cells
     let row_array = magnus::RArray::from_value(row_val)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for row"))?;
+        .ok_or_else(|| type_error_with_context(&ruby, "expected array for row", row_val))?;
 
     let mut cells = Vec::new();
     for i in 0..row_array.len() {

data/ext/ratatui_ruby/src/widgets/table_state.rs

@@ -69,6 +69,40 @@ impl RubyTableState {
         self.inner.borrow_mut().scroll_up_by(amount);
     }
 
+    /// Returns the currently selected cell as (row, column) tuple.
+    /// Returns None if either row or column is not selected.
+    pub fn selected_cell(&self) -> Option<(usize, usize)> {
+        self.inner.borrow().selected_cell()
+    }
+
+    /// Selects the next column or the first one if no column is selected.
+    pub fn select_next_column(&self) {
+        self.inner.borrow_mut().select_next_column();
+    }
+
+    /// Selects the previous column or the last one if no column is selected.
+    pub fn select_previous_column(&self) {
+        self.inner.borrow_mut().select_previous_column();
+    }
+
+    /// Selects the first column.
+    pub fn select_first_column(&self) {
+        self.inner.borrow_mut().select_first_column();
+    }
+
+    /// Selects the last column.
+    pub fn select_last_column(&self) {
+        self.inner.borrow_mut().select_last_column();
+    }
+
+    /// Creates a new `RubyTableState` with a selected cell (row, column).
+    pub fn with_selected_cell(cell: Option<(usize, usize)>) -> Self {
+        let state = TableState::default().with_selected_cell(cell);
+        Self {
+            inner: RefCell::new(state),
+        }
+    }
+
     /// Borrows the inner `TableState` mutably for rendering.
     pub fn borrow_mut(&self) -> std::cell::RefMut<'_, TableState> {
         self.inner.borrow_mut()
@@ -79,6 +113,10 @@ impl RubyTableState {
 pub fn register(ruby: &Ruby, module: magnus::RModule) -> Result<(), Error> {
     let class = module.define_class("TableState", ruby.class_object())?;
     class.define_singleton_method("new", function!(RubyTableState::new, 1))?;
+    class.define_singleton_method(
+        "with_selected_cell",
+        function!(RubyTableState::with_selected_cell, 1),
+    )?;
     class.define_method("select", method!(RubyTableState::select, 1))?;
     class.define_method("selected", method!(RubyTableState::selected, 0))?;
     class.define_method("select_column", method!(RubyTableState::select_column, 1))?;
@@ -86,6 +124,23 @@ pub fn register(ruby: &Ruby, module: magnus::RModule) -> Result<(), Error> {
         "selected_column",
         method!(RubyTableState::selected_column, 0),
     )?;
+    class.define_method("selected_cell", method!(RubyTableState::selected_cell, 0))?;
+    class.define_method(
+        "select_next_column",
+        method!(RubyTableState::select_next_column, 0),
+    )?;
+    class.define_method(
+        "select_previous_column",
+        method!(RubyTableState::select_previous_column, 0),
+    )?;
+    class.define_method(
+        "select_first_column",
+        method!(RubyTableState::select_first_column, 0),
+    )?;
+    class.define_method(
+        "select_last_column",
+        method!(RubyTableState::select_last_column, 0),
+    )?;
     class.define_method("offset", method!(RubyTableState::offset, 0))?;
     class.define_method("scroll_down_by", method!(RubyTableState::scroll_down_by, 1))?;
     class.define_method("scroll_up_by", method!(RubyTableState::scroll_up_by, 1))?;

data/ext/ratatui_ruby/src/widgets/tabs.rs

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+use crate::errors::type_error_with_context;
 use crate::style::parse_block;
 use crate::text::{parse_line, parse_span};
 use bumpalo::Bump;
@@ -59,7 +60,7 @@ fn create_tabs(node: Value, bump: &Bump) -> Result<Tabs<'_>, Error> {
     let padding_right_val: Value = node.funcall("padding_right", ())?;
 
     let titles_array = magnus::RArray::from_value(titles_val)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for titles"))?;
+        .ok_or_else(|| type_error_with_context(&ruby, "expected array for titles", titles_val))?;
 
     let mut titles = Vec::new();
     for i in 0..titles_array.len() {
@@ -117,7 +118,7 @@ pub fn width(node: Value) -> Result<usize, Error> {
     let padding_right: usize = node.funcall("padding_right", ())?;
 
     let titles_array = magnus::RArray::from_value(titles_val)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for titles"))?;
+        .ok_or_else(|| type_error_with_context(&ruby, "expected array for titles", titles_val))?;
 
     let mut total_width = padding_left + padding_right;
 

data/lib/ratatui_ruby/buffer/cell.rb

@@ -46,6 +46,11 @@ module RatatuiRuby
       # The background color of the cell (e.g., :black, nil).
       attr_reader :bg
 
+      # The underline color of the cell.
+      #
+      # Distinct from foreground color. Some terminals support colored underlines.
+      attr_reader :underline_color
+
       # The list of active modifiers (e.g., ["bold", "italic"]).
       attr_reader :modifiers
 
@@ -64,7 +69,7 @@ module RatatuiRuby
       # SPDX-SnippetEnd
       #++
       def self.empty
-        new(symbol: " ", fg: nil, bg: nil, modifiers: [])
+        new(symbol: " ", fg: nil, bg: nil, underline_color: nil, modifiers: [])
       end
 
       # Returns a default cell (alias for empty).
@@ -102,7 +107,7 @@ module RatatuiRuby
       # SPDX-SnippetEnd
       #++
       def self.symbol(symbol)
-        new(symbol:, fg: nil, bg: nil, modifiers: [])
+        new(symbol:, fg: nil, bg: nil, underline_color: nil, modifiers: [])
       end
 
       # Alias for Rubyists who prefer a shorter name.
@@ -115,58 +120,61 @@ module RatatuiRuby
       # [symbol] String (single character). Aliased as <tt>char:</tt>.
       # [fg] Symbol or String (nullable).
       # [bg] Symbol or String (nullable).
-      # [modifiers] Array of Strings.
-      def initialize(symbol: nil, char: nil, fg: nil, bg: nil, modifiers: [])
+      # [underline_color] Symbol or String (nullable).
+      # [modifiers] Array of Strings, Symbols, or any object responding to to_sym or to_s.
+      #             Normalized to Symbols for consistent output.
+      def initialize(symbol: nil, char: nil, fg: nil, bg: nil, underline_color: nil, modifiers: [])
         @symbol = (symbol || char || " ").freeze
         @fg = fg&.freeze
         @bg = bg&.freeze
-        @modifiers = modifiers.map(&:freeze).freeze
+        @underline_color = underline_color&.freeze
+        @modifiers = modifiers.map { |m| m.respond_to?(:to_sym) ? m.to_sym : m.to_s.to_sym }.freeze
         freeze
       end
 
       # Returns true if the cell has the bold modifier.
       def bold?
-        modifiers.include?("bold")
+        modifiers.include?(:bold)
       end
 
       # Returns true if the cell has the dim modifier.
       def dim?
-        modifiers.include?("dim")
+        modifiers.include?(:dim)
       end
 
       # Returns true if the cell has the italic modifier.
       def italic?
-        modifiers.include?("italic")
+        modifiers.include?(:italic)
       end
 
       # Returns true if the cell has the underlined modifier.
       def underlined?
-        modifiers.include?("underlined")
+        modifiers.include?(:underlined)
       end
 
       # Returns true if the cell has the slow_blink modifier.
       def slow_blink?
-        modifiers.include?("slow_blink")
+        modifiers.include?(:slow_blink)
       end
 
       # Returns true if the cell has the rapid_blink modifier.
       def rapid_blink?
-        modifiers.include?("rapid_blink")
+        modifiers.include?(:rapid_blink)
       end
 
       # Returns true if the cell has the reversed modifier.
       def reversed?
-        modifiers.include?("reversed")
+        modifiers.include?(:reversed)
       end
 
       # Returns true if the cell has the hidden modifier.
       def hidden?
-        modifiers.include?("hidden")
+        modifiers.include?(:hidden)
       end
 
       # Returns true if the cell has the crossed_out modifier.
       def crossed_out?
-        modifiers.include?("crossed_out")
+        modifiers.include?(:crossed_out)
       end
 
       # Checks equality with another Cell.
@@ -175,6 +183,7 @@ module RatatuiRuby
           char == other.char &&
           fg == other.fg &&
           bg == other.bg &&
+          underline_color == other.underline_color &&
           modifiers == other.modifiers
       end
 
@@ -183,6 +192,7 @@ module RatatuiRuby
         parts = ["symbol=#{symbol.inspect}"]
         parts << "fg=#{fg.inspect}" if fg
         parts << "bg=#{bg.inspect}" if bg
+        parts << "underline_color=#{underline_color.inspect}" if underline_color
         parts << "modifiers=#{modifiers.inspect}" unless modifiers.empty?
         "#<#{self.class} #{parts.join(' ')}>"
       end
@@ -195,7 +205,7 @@ module RatatuiRuby
       # Support for pattern matching.
       # Supports both <tt>:symbol</tt> and <tt>:char</tt> keys.
       def deconstruct_keys(keys)
-        { symbol:, char: symbol, fg:, bg:, modifiers: }
+        { symbol:, char: symbol, fg:, bg:, underline_color:, modifiers: }
       end
     end
   end

data/lib/ratatui_ruby/buffer.rb

@@ -8,9 +8,141 @@
 module RatatuiRuby
   # Buffer primitives for terminal cell inspection.
   #
-  # This module mirrors +ratatui::buffer+ and contains:
-  # - {Cell} — Single terminal cell (for inspection)
+  # Widgets render to an intermediate buffer, not directly to the terminal.
+  # Testing and debugging require access to buffer state.
+  #
+  # This module mirrors +ratatui::buffer+ and provides query methods
+  # for inspecting buffer contents, converting between coordinates and indices,
+  # and retrieving individual cells.
+  #
+  # Use it in tests to verify rendered output or in debugging to inspect state.
   module Buffer
+    class << self
+      # Converts a position to a linear buffer index.
+      #
+      # Buffers store cells in a flat array, row by row. Widget code
+      # works with (x, y) coordinates. Bridging these representations
+      # requires index translation.
+      #
+      # The index is calculated as <tt>y * width + x</tt>.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   # In a 10-wide buffer, position (3, 2) maps to index 23
+      #   Buffer.index_of(3, 2) # => 23
+      #--
+      # SPDX-SnippetEnd
+      #++
+      #
+      # [x] Column (0-indexed from left).
+      # [y] Row (0-indexed from top).
+      #
+      # Returns the linear index (Integer).
+      def index_of(x, y)
+        area = RatatuiRuby._get_terminal_area
+        (y * area["width"]) + x
+      end
+
+      # Converts a linear buffer index to position coordinates.
+      #
+      # Inverse of +index_of+. When iterating over buffer content
+      # by index, use this to recover the original coordinates.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   # In a 10-wide buffer, index 23 maps to position (3, 2)
+      #   Buffer.pos_of(23) # => [3, 2]
+      #--
+      # SPDX-SnippetEnd
+      #++
+      #
+      # [index] Linear buffer index (Integer).
+      #
+      # Returns <tt>[x, y]</tt> coordinates.
+      def pos_of(index)
+        area = RatatuiRuby._get_terminal_area
+        width = area["width"]
+        x = index % width
+        y = index / width
+        [x, y]
+      end
+
+      # Returns the Cell at the specified position.
+      #
+      # Tests assert on cell contents. This method provides direct
+      # access without iterating the entire buffer.
+      #
+      # Delegates to +RatatuiRuby.get_cell_at+.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   cell = Buffer.get(0, 0)
+      #   assert_equal "H", cell.char
+      #--
+      # SPDX-SnippetEnd
+      #++
+      #
+      # [x] Column (0-indexed from left).
+      # [y] Row (0-indexed from top).
+      #
+      # Returns a Buffer::Cell containing the character and style at that position.
+      def get(x, y)
+        RatatuiRuby.get_cell_at(x, y)
+      end
+
+      # Returns all cells in the buffer as a flat array.
+      #
+      # Snapshot testing compares entire buffer states. Manually
+      # iterating coordinates is verbose and error-prone.
+      #
+      # This method returns every cell, ordered row by row
+      # (top to bottom, left to right).
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   cells = Buffer.content
+      #   cells.each { |cell| puts cell.char }
+      #--
+      # SPDX-SnippetEnd
+      #++
+      #
+      # Returns an Array of Buffer::Cell objects.
+      def content
+        area = RatatuiRuby._get_terminal_area
+        width = area["width"]
+        height = area["height"]
+        cells = [] #: Array[Buffer::Cell]
+        (0...height).each do |y|
+          (0...width).each do |x|
+            cells << RatatuiRuby.get_cell_at(x, y)
+          end
+        end
+        cells
+      end
+
+      # Ruby-idiomatic alias (TIMTOWTDI)
+      alias [] get
+    end
   end
 end
 

data/lib/ratatui_ruby/cell.rb

@@ -45,8 +45,12 @@ module RatatuiRuby
     # The background color of the cell (e.g., :black, nil).
     attr_reader :bg
 
+    # The underline color of the cell.
+    #
+    # Distinct from foreground color. Some terminals support colored underlines.
+    attr_reader :underline_color
+
     # The list of active modifiers (e.g., ["bold", "italic"]).
-    attr_reader :modifiers
 
     # Returns an empty cell (space character, no styles).
     #
@@ -63,7 +67,7 @@ module RatatuiRuby
     # SPDX-SnippetEnd
     #++
     def self.empty
-      new(symbol: " ", fg: nil, bg: nil, modifiers: [])
+      new(symbol: " ", fg: nil, bg: nil, underline_color: nil, modifiers: [])
     end
 
     # Returns a default cell (alias for empty).
@@ -101,7 +105,7 @@ module RatatuiRuby
     # SPDX-SnippetEnd
     #++
     def self.symbol(symbol)
-      new(symbol:, fg: nil, bg: nil, modifiers: [])
+      new(symbol:, fg: nil, bg: nil, underline_color: nil, modifiers: [])
     end
 
     # Alias for Rubyists who prefer a shorter name.
@@ -114,11 +118,13 @@ module RatatuiRuby
     # [symbol] String (single character). Aliased as <tt>char:</tt>.
     # [fg] Symbol or String (nullable).
     # [bg] Symbol or String (nullable).
+    # [underline_color] Symbol or String (nullable).
     # [modifiers] Array of Strings.
-    def initialize(symbol: nil, char: nil, fg: nil, bg: nil, modifiers: [])
+    def initialize(symbol: nil, char: nil, fg: nil, bg: nil, underline_color: nil, modifiers: [])
       @symbol = (symbol || char || " ").freeze
       @fg = fg&.freeze
       @bg = bg&.freeze
+      @underline_color = underline_color&.freeze
       @modifiers = modifiers.map(&:freeze).freeze
       freeze
     end
@@ -174,6 +180,7 @@ module RatatuiRuby
         char == other.char &&
         fg == other.fg &&
         bg == other.bg &&
+        underline_color == other.underline_color &&
         modifiers == other.modifiers
     end
 
@@ -182,6 +189,7 @@ module RatatuiRuby
       parts = ["symbol=#{symbol.inspect}"]
       parts << "fg=#{fg.inspect}" if fg
       parts << "bg=#{bg.inspect}" if bg
+      parts << "underline_color=#{underline_color.inspect}" if underline_color
       parts << "modifiers=#{modifiers.inspect}" unless modifiers.empty?
       "#<#{self.class} #{parts.join(' ')}>"
     end
@@ -194,7 +202,7 @@ module RatatuiRuby
     # Support for pattern matching.
     # Supports both <tt>:symbol</tt> and <tt>:char</tt> keys.
     def deconstruct_keys(keys)
-      { symbol:, char: symbol, fg:, bg:, modifiers: }
+      { symbol:, char: symbol, fg:, bg:, underline_color:, modifiers: }
     end
   end
 end