ratatui_ruby 1.4.0-x86_64-linux

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

@@ -0,0 +1,194 @@
+// 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;
+use magnus::{prelude::*, Error, Value};
+use ratatui::buffer::Buffer;
+use ratatui::{layout::Rect, text::Line, widgets::Tabs, widgets::Widget};
+
+pub fn render(buffer: &mut Buffer, area: Rect, node: Value) -> Result<(), Error> {
+    let bump = Bump::new();
+    let tabs = create_tabs(node, &bump)?;
+    tabs.render(area, buffer);
+    Ok(())
+}
+
+/// Parses padding value with duck-typing support:
+/// - Integer: generates that many spaces
+/// - Line: uses styled Line directly
+/// - Span: wraps in Line
+/// - String or `to_s` responder: converts to Line
+fn parse_padding(val: Value) -> Result<Line<'static>, Error> {
+    // Handle nil or zero
+    if val.is_nil() {
+        return Ok(Line::from(""));
+    }
+
+    // Try as Integer first (most common case)
+    if let Ok(n) = usize::try_convert(val) {
+        if n == 0 {
+            return Ok(Line::from(""));
+        }
+        return Ok(Line::from(" ".repeat(n)));
+    }
+
+    // Try to parse as Line
+    if let Ok(line) = parse_line(val) {
+        return Ok(line);
+    }
+
+    // Try to parse as Span (wrap in Line)
+    if let Ok(span) = parse_span(val) {
+        return Ok(Line::from(vec![span]));
+    }
+
+    // Fallback: call to_s and convert to Line
+    let s: String = val.funcall("to_s", ())?;
+    Ok(Line::from(s))
+}
+
+fn create_tabs(node: Value, bump: &Bump) -> Result<Tabs<'_>, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+    let titles_val: Value = node.funcall("titles", ())?;
+    let selected_index: usize = node.funcall("selected_index", ())?;
+    let block_val: Value = node.funcall("block", ())?;
+    let divider_val: Value = node.funcall("divider", ())?;
+    let highlight_style_val: Value = node.funcall("highlight_style", ())?;
+    let padding_left_val: Value = node.funcall("padding_left", ())?;
+    let padding_right_val: Value = node.funcall("padding_right", ())?;
+
+    let titles_array = magnus::RArray::from_value(titles_val)
+        .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() {
+        let index = isize::try_from(i)
+            .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+        let val: Value = titles_array.entry(index)?;
+        if let Ok(line) = parse_line(val) {
+            titles.push(line);
+        } else {
+            let s: String = String::try_convert(val)?;
+            titles.push(Line::from(s));
+        }
+    }
+
+    let mut tabs = Tabs::new(titles).select(selected_index);
+
+    if !divider_val.is_nil() {
+        if let Ok(span) = parse_span(divider_val) {
+            tabs = tabs.divider(span);
+        } else {
+            let divider: String = divider_val.funcall("to_s", ())?;
+            tabs = tabs.divider(divider);
+        }
+    }
+
+    if !highlight_style_val.is_nil() {
+        let style = crate::style::parse_style(highlight_style_val)?;
+        tabs = tabs.highlight_style(style);
+    }
+
+    let style_val: Value = node.funcall("style", ())?;
+    if !style_val.is_nil() {
+        tabs = tabs.style(crate::style::parse_style(style_val)?);
+    }
+
+    if !block_val.is_nil() {
+        tabs = tabs.block(parse_block(block_val, bump)?);
+    }
+
+    // Handle duck-typed padding: Integer (spaces), String, Line, or anything with to_s
+    let left_padding = parse_padding(padding_left_val)?;
+    let right_padding = parse_padding(padding_right_val)?;
+    if !left_padding.spans.is_empty() || !right_padding.spans.is_empty() {
+        tabs = tabs.padding(left_padding, right_padding);
+    }
+
+    Ok(tabs)
+}
+
+pub fn width(node: Value) -> Result<usize, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+    let titles_val: Value = node.funcall("titles", ())?;
+    let divider_val: Value = node.funcall("divider", ())?;
+    let padding_left: usize = node.funcall("padding_left", ())?;
+    let padding_right: usize = node.funcall("padding_right", ())?;
+
+    let titles_array = magnus::RArray::from_value(titles_val)
+        .ok_or_else(|| type_error_with_context(&ruby, "expected array for titles", titles_val))?;
+
+    let mut total_width = padding_left + padding_right;
+
+    let mut titles_count = 0;
+    for i in 0..titles_array.len() {
+        let index = isize::try_from(i)
+            .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+        let val: Value = titles_array.entry(index)?;
+        let line_width = if let Ok(line) = parse_line(val) {
+            line.width()
+        } else {
+            let s: String = String::try_convert(val)?;
+            ratatui::text::Span::raw(s).width()
+        };
+        total_width += line_width;
+        titles_count += 1;
+    }
+
+    if titles_count > 1 {
+        let divider_width = if divider_val.is_nil() {
+            1 // Default divider is "|"
+        } else if let Ok(span) = parse_span(divider_val) {
+            span.width()
+        } else {
+            let d: String = divider_val.funcall("to_s", ())?;
+            ratatui::text::Span::raw(d).width()
+        };
+        total_width += (titles_count - 1) * divider_width;
+    }
+
+    Ok(total_width)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use ratatui::buffer::Buffer;
+    use ratatui::style::{Color, Modifier, Style};
+    use ratatui::text::Line;
+    use ratatui::widgets::{Tabs, Widget};
+
+    #[test]
+    fn test_tabs_rendering() {
+        let titles = vec![Line::from("Tab1"), Line::from("Tab2")];
+        let tabs = Tabs::new(titles).select(1).divider("|");
+        let mut buf = Buffer::empty(Rect::new(0, 0, 15, 1));
+        tabs.render(Rect::new(0, 0, 15, 1), &mut buf);
+        // Should contain tab titles
+        let content = buf.content().iter().map(|c| c.symbol()).collect::<String>();
+        assert!(content.contains("Tab1"));
+        assert!(content.contains("Tab2"));
+        assert!(content.contains('|'));
+    }
+
+    #[test]
+    fn test_tabs_highlight_style() {
+        let titles = vec![Line::from("Tab1"), Line::from("Tab2")];
+        let highlight_style = Style::default().fg(Color::Red).add_modifier(Modifier::BOLD);
+        let tabs = Tabs::new(titles).select(0).highlight_style(highlight_style);
+
+        let mut buf = Buffer::empty(Rect::new(0, 0, 15, 1));
+        tabs.render(Rect::new(0, 0, 15, 1), &mut buf);
+
+        // Check the first cell of the first tab (which is selected)
+        // " Tab1 "
+        // Index 1 should be 'T' with Red+Bold
+        let cell = &buf.content()[1];
+        assert_eq!(cell.symbol(), "T");
+        assert_eq!(cell.fg, Color::Red);
+        assert!(cell.modifier.contains(Modifier::BOLD));
+    }
+}

data/lib/ratatui_ruby/backend/window_size.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Backend
+    # Terminal window dimensions in characters and pixels.
+    #
+    # Some operations need both character grid size and pixel dimensions.
+    # Sixel graphics, image rendering, and precise layout calculations all
+    # benefit from knowing both measurements at once.
+    #
+    # This struct bundles both sizes together. It matches upstream Ratatui's
+    # <tt>backend::WindowSize</tt> struct exactly.
+    #
+    # Both fields are <tt>Layout::Size</tt> instances. This reuses the same
+    # type for character and pixel dimensions, matching upstream design.
+    #
+    # Note: Pixel dimensions may be zero on some systems. Unix marks these
+    # fields "unused" in TIOCGWINSZ. Windows does not implement them.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   ws = RatatuiRuby::Terminal.window_size
+    #   if ws
+    #     puts "#{ws.columns_rows.width}x#{ws.columns_rows.height} chars"
+    #     puts "#{ws.pixels.width}x#{ws.pixels.height} pixels"
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class WindowSize < Data.define(:columns_rows, :pixels)
+      ##
+      # :attr_reader: columns_rows
+      # Size of the window in characters (columns/rows) as <tt>Layout::Size</tt>.
+
+      ##
+      # :attr_reader: pixels
+      # Size of the window in pixels as <tt>Layout::Size</tt>.
+    end
+  end
+end

data/lib/ratatui_ruby/backend.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Backend abstractions for terminal rendering.
+  #
+  # This module contains types related to terminal backend operations.
+  # It mirrors upstream Ratatui's <tt>backend</tt> module structure.
+  module Backend
+    class << self
+      # Queries terminal window size in characters and pixels.
+      #
+      # Some operations need both the character grid and pixel dimensions.
+      # Querying them separately wastes syscalls. Most backends fetch both
+      # at once anyway.
+      #
+      # This method queries crossterm for window dimensions. It returns a
+      # <tt>Backend::WindowSize</tt> with <tt>columns_rows</tt> and
+      # <tt>pixels</tt> fields, each as <tt>Layout::Size</tt> instances.
+      # Returns <tt>nil</tt> if the query fails.
+      #
+      # Note: Pixel dimensions may be zero on some systems. Unix marks
+      # these fields "unused" in TIOCGWINSZ. Windows does not implement them.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   ws = RatatuiRuby::Backend.window_size
+      #   if ws
+      #     puts "#{ws.columns_rows.width}x#{ws.columns_rows.height} chars"
+      #     puts "#{ws.pixels.width}x#{ws.pixels.height} pixels"
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def window_size
+        window_size = Terminal._terminal_window_size
+        return nil unless window_size
+        columns, rows, px_width, px_height = window_size
+        WindowSize.new(
+          columns_rows: Layout::Size.new(width: columns, height: rows),
+          pixels: Layout::Size.new(width: px_width, height: px_height)
+        )
+      rescue
+        nil
+      end
+    end
+  end
+end
+
+require_relative "backend/window_size"

data/lib/ratatui_ruby/buffer/cell.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Buffer
+    # Represents a single cell in the terminal buffer.
+    #
+    # A terminal grid is made of cells. Each cell contains a character (symbol) and styling (colors, modifiers).
+    # When testing, you often need to verify that a specific cell renders correctly.
+    #
+    # This object encapsulates that state. It provides predicate methods for modifiers, making assertions readable.
+    #
+    # Use it to inspect the visual state of your application in tests.
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   cell = RatatuiRuby.get_cell_at(0, 0)
+    #   cell.char   # => "H"
+    #   cell.fg     # => :red
+    #   cell.bold?  # => true
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Cell
+      # The character displayed in the cell.
+      #
+      # Named to match Ratatui's Cell::symbol() method.
+      attr_reader :symbol
+
+      # Alias for Rubyists who prefer a shorter name.
+      alias char symbol
+
+      # The foreground color of the cell (e.g., :red, :blue, "#ff0000").
+      attr_reader :fg
+
+      # 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).
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Buffer::Cell.empty # => #<RatatuiRuby::Buffer::Cell char=" ">
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def self.empty
+        new(symbol: " ", fg: nil, bg: nil, underline_color: nil, modifiers: [])
+      end
+
+      # Returns a default cell (alias for empty).
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Buffer::Cell.default # => #<RatatuiRuby::Buffer::Cell char=" ">
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def self.default
+        empty
+      end
+
+      # Returns a cell with a specific character and no styles.
+      #
+      # [symbol] String (single character).
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Buffer::Cell.symbol("X") # => #<RatatuiRuby::Buffer::Cell symbol="X">
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def self.symbol(symbol)
+        new(symbol:, fg: nil, bg: nil, underline_color: nil, modifiers: [])
+      end
+
+      # Alias for Rubyists who prefer a shorter name.
+      def self.char(char)
+        symbol(char)
+      end
+
+      # Creates a new Cell.
+      #
+      # [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, 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
+        @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)
+      end
+
+      # Returns true if the cell has the dim modifier.
+      def dim?
+        modifiers.include?(:dim)
+      end
+
+      # Returns true if the cell has the italic modifier.
+      def italic?
+        modifiers.include?(:italic)
+      end
+
+      # Returns true if the cell has the underlined modifier.
+      def underlined?
+        modifiers.include?(:underlined)
+      end
+
+      # Returns true if the cell has the slow_blink modifier.
+      def slow_blink?
+        modifiers.include?(:slow_blink)
+      end
+
+      # Returns true if the cell has the rapid_blink modifier.
+      def rapid_blink?
+        modifiers.include?(:rapid_blink)
+      end
+
+      # Returns true if the cell has the reversed modifier.
+      def reversed?
+        modifiers.include?(:reversed)
+      end
+
+      # Returns true if the cell has the hidden modifier.
+      def hidden?
+        modifiers.include?(:hidden)
+      end
+
+      # Returns true if the cell has the crossed_out modifier.
+      def crossed_out?
+        modifiers.include?(:crossed_out)
+      end
+
+      # Checks equality with another Cell.
+      def ==(other)
+        other.is_a?(Cell) &&
+          char == other.char &&
+          fg == other.fg &&
+          bg == other.bg &&
+          underline_color == other.underline_color &&
+          modifiers == other.modifiers
+      end
+
+      # Returns a string representation of the cell.
+      def inspect
+        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
+
+      # Returns the cell's character.
+      def to_s
+        symbol
+      end
+
+      # Support for pattern matching.
+      # Supports both <tt>:symbol</tt> and <tt>:char</tt> keys.
+      def deconstruct_keys(keys)
+        { symbol:, char: symbol, fg:, bg:, underline_color:, modifiers: }
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/buffer.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Buffer primitives for terminal cell 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
+
+require_relative "buffer/cell"