ratatui_ruby 0.9.1 → 0.10.1

data/lib/ratatui_ruby/table_state.rb

@@ -96,5 +96,56 @@ module RatatuiRuby
     # Scrolls up by +n+ rows.
     #
     # (Native method implemented in Rust)
+
+    ##
+    # :method: selected_cell
+    # :call-seq: selected_cell() -> Array or nil
+    #
+    # Returns the currently selected cell as <tt>[row, column]</tt>.
+    # Returns +nil+ if either row or column is not selected.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_next_column
+    # :call-seq: select_next_column() -> nil
+    #
+    # Selects the next column, or column 0 if none selected.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_previous_column
+    # :call-seq: select_previous_column() -> nil
+    #
+    # Selects the previous column. Saturates at 0.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_first_column
+    # :call-seq: select_first_column() -> nil
+    #
+    # Selects column 0.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_last_column
+    # :call-seq: select_last_column() -> nil
+    #
+    # Selects the last column. The index is clamped during rendering.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :singleton-method: with_selected_cell
+    # :call-seq: with_selected_cell(cell) -> TableState
+    #
+    # Creates a new TableState with both row and column selected.
+    #
+    # [cell] <tt>[row, column]</tt> array, or +nil+.
+    #
+    # (Native method implemented in Rust)
   end
 end

data/lib/ratatui_ruby/terminal_lifecycle.rb

@@ -90,7 +90,7 @@ module RatatuiRuby
     ##
     # Restores the terminal to its original state.
     # Leaves alternate screen and disables raw mode.
-    # Also flushes any deferred warnings that were queued during the session.
+    # Also flushes any deferred warnings and panic info that were queued during the session.
     #
     # In headless mode ({headless!}), this method is a silent no-op since
     # no terminal was ever initialized.
@@ -103,6 +103,7 @@ module RatatuiRuby
     ensure
       @tui_session_active = false
       flush_warnings
+      flush_panic_info
     end
 
     ##

data/lib/ratatui_ruby/test_helper/event_injection.rb

@@ -64,7 +64,7 @@ module RatatuiRuby
       # [event] A <tt>RatatuiRuby::Event</tt> object.
       def inject_event(event)
         unless @_ratatui_test_terminal_active
-          raise "Events must be injected inside a `with_test_terminal` block. " \
+          raise RatatuiRuby::Error::Invariant, "Events must be injected inside a `with_test_terminal` block. " \
             "Calling this method outside the block causes a race condition where the event " \
             "is flushed before the application starts."
         end
@@ -209,6 +209,11 @@ module RatatuiRuby
       # pending async operations to complete before processing the next event.
       # This enables deterministic testing of async behavior.
       #
+      # *Important*: Sync waits for commands to _complete_. Do not use it
+      # with long-running commands that wait indefinitely (e.g., for
+      # cancellation). Those commands will block forever, causing a timeout.
+      # For cancellation tests, dispatch the cancel command without Sync.
+      #
       # === Example
       #
       #--

data/lib/ratatui_ruby/test_helper.rb

@@ -92,6 +92,15 @@ module RatatuiRuby
   # SPDX-SnippetEnd
   #++
   module TestHelper
+    ##
+    # Auto-enables debug mode when TestHelper is included.
+    #
+    # This ensures Rust backtraces are available in tests.
+    # Skips remote debugging since tests don't need it.
+    def self.included(base)
+      RatatuiRuby::Debug.enable!(source: :test)
+    end
+
     include Terminal
     include Snapshot
     include EventInjection

data/lib/ratatui_ruby/text/line.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Text
+    # A sequence of styled spans.
+    #
+    # Words form sentences. Spans form lines.
+    #
+    # This class composes multiple {Span} objects into a single horizontal row of text.
+    # It handles the layout of rich text fragments within the flow of a paragraph.
+    #
+    # Use it to build multi-colored headers, status messages, or log entries.
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   Text::Line.new(
+    #     spans: [
+    #       Text::Span.styled("User: ", Style.new(modifiers: [:bold])),
+    #       Text::Span.styled("kerrick", Style.new(fg: :blue))
+    #     ]
+    #   )
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Line < Data.define(:spans, :alignment, :style)
+      ##
+      # :attr_reader: spans
+      # Array of Span objects.
+
+      ##
+      # :attr_reader: alignment
+      # Alignment within the container.
+      #
+      # <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).
+      # [style] Style object (optional).
+      def initialize(spans: [], alignment: nil, style: nil)
+        super
+      end
+
+      # Creates a simple line from a string.
+      #
+      #   Text::Line.from_string("Hello")
+      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
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [
+      #     Text::Span.new(content: "Hello "),
+      #     Text::Span.new(content: "世界")
+      #   ])
+      #   line.width  # => 10 (6 ASCII + 4 CJK)
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Integer (number of terminal cells).
+      def width
+        RatatuiRuby::Text.width(spans.map { |s| s.content.to_s }.join)
+      end
+
+      # Left-aligns this line of text.
+      #
+      # Convenience shortcut for <tt>alignment: :left</tt>. Setting the alignment of a Line
+      # overrides the alignment of its parent Text or Widget.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
+      #   aligned = line.left_aligned
+      #   aligned.alignment  # => :left
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Line.
+      def left_aligned
+        with(alignment: :left)
+      end
+
+      # Center-aligns this line of text.
+      #
+      # Convenience shortcut for <tt>alignment: :center</tt>. Setting the alignment of a Line
+      # overrides the alignment of its parent Text or Widget.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
+      #   centered = line.centered
+      #   centered.alignment  # => :center
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Line.
+      def centered
+        with(alignment: :center)
+      end
+
+      # Right-aligns this line of text.
+      #
+      # Convenience shortcut for <tt>alignment: :right</tt>. Setting the alignment of a Line
+      # overrides the alignment of its parent Text or Widget.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
+      #   aligned = line.right_aligned
+      #   aligned.alignment  # => :right
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Line.
+      def right_aligned
+        with(alignment: :right)
+      end
+
+      # Adds a span to the line.
+      #
+      # Since Line is immutable (a Data subclass), this returns a new Line with the span appended.
+      # The original line remains unchanged.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello, ")])
+      #   extended = line.push_span(Text::Span.new(content: "world!"))
+      #   extended.spans.size  # => 2
+      #   line.spans.size      # => 1 (original unchanged)
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [span] Span to append.
+      #
+      # Returns: Line.
+      def push_span(span)
+        with(spans: spans + [span])
+      end
+
+      # Patches the style of this line, adding modifiers from the given style.
+      #
+      # Applies <tt>patch_style</tt> to each span in the line. Use this when you want to layer
+      # styles on all spans without replacing their existing styles.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
+      #   styled = line.patch_style(Style::Style.new(fg: :red))
+      #   styled.spans.first.style.fg  # => :red
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [patch] Style::Style to merge onto each span.
+      #
+      # Returns: Line.
+      def patch_style(patch)
+        with(spans: spans.map { |s| s.patch_style(patch) })
+      end
+
+      # Resets the style of this line.
+      #
+      # Applies <tt>reset_style</tt> to each span in the line, clearing all styling.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [
+      #     Text::Span.new(content: "styled", style: Style::Style.new(fg: :red))
+      #   ])
+      #   reset = line.reset_style
+      #   reset.spans.first.style  # => nil
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Line.
+      def reset_style
+        with(spans: spans.map(&:reset_style))
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/text/span.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Text
+    # A styled string fragment.
+    #
+    # Text is rarely uniform. You need to bold a keyword, colorize an error, or dim a timestamp.
+    #
+    # This class attaches style to content. It pairs a string with visual attributes.
+    #
+    # combine spans into a {Line} to create rich text.
+    #
+    # === Examples
+    #
+    #   Text::Span.new(content: "Error", style: Style.new(fg: :red, modifiers: [:bold]))
+    class Span < Data.define(:content, :style)
+      ##
+      # :attr_reader: content
+      # The text content.
+
+      ##
+      # :attr_reader: style
+      # The style to apply.
+
+      # Creates a new Span.
+      #
+      # [content] String.
+      # [style] Style object (optional).
+      def initialize(content:, style: nil)
+        super
+      end
+
+      # Concise helper for styling.
+      #
+      # === Example
+      #
+      #   Text::Span.styled("Bold", Style::Style.new(modifiers: [:bold]))
+      def self.styled(content, style = nil)
+        new(content:, style:)
+      end
+
+      # Returns the unicode display width of the content in terminal cells.
+      #
+      # CJK characters and emoji count as 2 cells. ASCII characters count as 1 cell.
+      # Use this to measure how much horizontal space a span will occupy.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   span = Text::Span.new(content: "Hello")
+      #   span.width  # => 5
+      #
+      #   span = Text::Span.new(content: "你好")  # Chinese characters
+      #   span.width  # => 4
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Integer.
+      def width
+        RatatuiRuby::Text.width(content.to_s)
+      end
+
+      # Creates a span with the default style.
+      #
+      # Use this factory method when you want unstyled text. It mirrors the Ratatui API.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   span = Text::Span.raw("test content")
+      #   span.content  # => "test content"
+      #   span.style    # => nil
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [content] String.
+      #
+      # Returns: Span.
+      def self.raw(content)
+        new(content:)
+      end
+
+      # Patches the style of the span, merging modifiers from the given style.
+      #
+      # Non-nil values from the patch style override the existing style. Use this when you want to
+      # layer styles without replacing the entire style. Colors in the patch take precedence over
+      # existing colors. Modifiers are combined.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   span = Text::Span.new(content: "test", style: Style::Style.new(fg: :green))
+      #   patched = span.patch_style(Style::Style.new(bg: :yellow, modifiers: [:bold]))
+      #   patched.style.fg  # => :green (preserved)
+      #   patched.style.bg  # => :yellow (added)
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [patch] Style::Style to merge.
+      #
+      # Returns: Span.
+      def patch_style(patch)
+        return self if patch.nil?
+        return with(style: patch) if style.nil?
+
+        merged = Style::Style.new(
+          fg: patch.fg.nil? ? style.fg : patch.fg,
+          bg: patch.bg.nil? ? style.bg : patch.bg,
+          modifiers: patch.modifiers.empty? ? style.modifiers : (style.modifiers + patch.modifiers).uniq
+        )
+        with(style: merged)
+      end
+
+      # Resets the style of the span.
+      #
+      # Returns a new span with no style applied. Use this to strip all styling.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   span = Text::Span.new(content: "styled", style: Style::Style.new(fg: :red))
+      #   reset = span.reset_style
+      #   reset.style  # => nil
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Span.
+      def reset_style
+        with(style: nil)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/text.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # 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
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   # 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)
+  #--
+  # SPDX-SnippetEnd
+  #++
+  module Text
+    ##
+    # :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
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   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
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # [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
+
+require_relative "text/span"
+require_relative "text/line"