ratatui_ruby 0.9.1 → 0.10.0

data/sig/ratatui_ruby/symbols.rbs

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Symbols
+    module Shade
+      EMPTY: String
+      LIGHT: String
+      MEDIUM: String
+      DARK: String
+      FULL: String
+    end
+
+    # Type alias for line set hashes
+    type line_set = {
+      vertical: String,
+      horizontal: String,
+      top_right: String,
+      top_left: String,
+      bottom_right: String,
+      bottom_left: String,
+      vertical_left: String,
+      vertical_right: String,
+      horizontal_down: String,
+      horizontal_up: String,
+      cross: String
+    }
+
+    module Line
+      # Individual character constants
+      VERTICAL: String
+      DOUBLE_VERTICAL: String
+      THICK_VERTICAL: String
+      HORIZONTAL: String
+      DOUBLE_HORIZONTAL: String
+      THICK_HORIZONTAL: String
+      TOP_RIGHT: String
+      ROUNDED_TOP_RIGHT: String
+      DOUBLE_TOP_RIGHT: String
+      THICK_TOP_RIGHT: String
+      TOP_LEFT: String
+      ROUNDED_TOP_LEFT: String
+      DOUBLE_TOP_LEFT: String
+      THICK_TOP_LEFT: String
+      BOTTOM_RIGHT: String
+      ROUNDED_BOTTOM_RIGHT: String
+      DOUBLE_BOTTOM_RIGHT: String
+      THICK_BOTTOM_RIGHT: String
+      BOTTOM_LEFT: String
+      ROUNDED_BOTTOM_LEFT: String
+      DOUBLE_BOTTOM_LEFT: String
+      THICK_BOTTOM_LEFT: String
+      VERTICAL_LEFT: String
+      DOUBLE_VERTICAL_LEFT: String
+      THICK_VERTICAL_LEFT: String
+      VERTICAL_RIGHT: String
+      DOUBLE_VERTICAL_RIGHT: String
+      THICK_VERTICAL_RIGHT: String
+      HORIZONTAL_DOWN: String
+      DOUBLE_HORIZONTAL_DOWN: String
+      THICK_HORIZONTAL_DOWN: String
+      HORIZONTAL_UP: String
+      DOUBLE_HORIZONTAL_UP: String
+      THICK_HORIZONTAL_UP: String
+      CROSS: String
+      DOUBLE_CROSS: String
+      THICK_CROSS: String
+
+      # Predefined sets
+      NORMAL: line_set
+      ROUNDED: line_set
+      DOUBLE: line_set
+      THICK: line_set
+    end
+
+    # Type alias for bar set hashes
+    type bar_set = {
+      full: String,
+      seven_eighths: String,
+      three_quarters: String,
+      five_eighths: String,
+      half: String,
+      three_eighths: String,
+      one_quarter: String,
+      one_eighth: String,
+      empty: String
+    }
+
+    module Bar
+      # Individual character constants
+      FULL: String
+      SEVEN_EIGHTHS: String
+      THREE_QUARTERS: String
+      FIVE_EIGHTHS: String
+      HALF: String
+      THREE_EIGHTHS: String
+      ONE_QUARTER: String
+      ONE_EIGHTH: String
+
+      # Predefined sets
+      NINE_LEVELS: bar_set
+      THREE_LEVELS: bar_set
+    end
+
+    module Block
+      # Individual character constants
+      FULL: String
+      SEVEN_EIGHTHS: String
+      THREE_QUARTERS: String
+      FIVE_EIGHTHS: String
+      HALF: String
+      THREE_EIGHTHS: String
+      ONE_QUARTER: String
+      ONE_EIGHTH: String
+
+      # Predefined sets (same structure as bar_set)
+      NINE_LEVELS: bar_set
+      THREE_LEVELS: bar_set
+    end
+
+    # Type alias for scrollbar set hashes
+    type scrollbar_set = {
+      track: String,
+      thumb: String,
+      begin_char: String,
+      end_char: String
+    }
+
+    module Scrollbar
+      # Predefined sets
+      DOUBLE_VERTICAL: scrollbar_set
+      DOUBLE_HORIZONTAL: scrollbar_set
+      VERTICAL: scrollbar_set
+      HORIZONTAL: scrollbar_set
+    end
+  end
+end

data/sig/ratatui_ruby/synthetic_events.rbs

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Synthetic event queue for injecting events into the event loop.
+  # Used primarily for testing and the andThen-like integration pattern.
+  module SyntheticEvents
+    @queue: Array[Event]
+
+    def self.push: (Event event) -> void
+    def self.pop: () -> Event?
+    def self.clear: () -> void
+    def self.pending?: () -> bool
+  end
+end

data/sig/ratatui_ruby/table_state.rbs

@@ -10,10 +10,16 @@
 module RatatuiRuby
   class TableState
     def self.new: (?Integer? selected) -> TableState
+    def self.with_selected_cell: ([Integer, Integer]? cell) -> TableState
     def select: (Integer? index) -> nil
     def selected: () -> Integer?
     def select_column: (Integer? index) -> nil
     def selected_column: () -> Integer?
+    def selected_cell: () -> [Integer, Integer]?
+    def select_next_column: () -> nil
+    def select_previous_column: () -> nil
+    def select_first_column: () -> nil
+    def select_last_column: () -> nil
     def offset: () -> Integer
     def scroll_down_by: (Integer n) -> nil
     def scroll_up_by: (Integer n) -> nil

data/sig/ratatui_ruby/terminal_lifecycle.rbs

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Terminal lifecycle management for TUI sessions.
+  # Provides methods to initialize and restore the terminal state.
+  module TerminalLifecycle
+    @tui_session_active: bool?
+    @headless_mode: bool?
+
+    def init_terminal: (?focus_events: bool, ?bracketed_paste: bool) -> void
+    def restore_terminal: () -> void
+    def terminal_active?: () -> (bool | nil)
+    def init_test_terminal: (Integer width, Integer height) -> void
+    def run: (?focus_events: bool, ?bracketed_paste: bool) { (TUI) -> void } -> void
+
+    # Private native methods
+    def _init_terminal: (bool focus_events, bool bracketed_paste) -> void
+    def _init_test_terminal: (Integer width, Integer height) -> void
+    def _restore_terminal: () -> void
+    def flush_warnings: () -> void
+    def flush_panic_info: () -> void
+  end
+end
+

data/sig/ratatui_ruby/test_helper/event_injection.rbs

@@ -10,12 +10,12 @@
 module RatatuiRuby
   module TestHelper
     module EventInjection
-      def inject_event: (Event::Base event) -> void
+      def inject_event: (Event event) -> void
       def inject_mouse: (x: Integer, y: Integer, ?kind: Symbol, ?modifiers: Array[String], ?button: Symbol) -> void
       def inject_click: (x: Integer, y: Integer, ?modifiers: Array[String]) -> void
       def inject_right_click: (x: Integer, y: Integer, ?modifiers: Array[String]) -> void
       def inject_drag: (x: Integer, y: Integer, ?modifiers: Array[String], ?button: Symbol) -> void
-      def inject_keys: (*(String | Symbol | (Hash[Symbol, untyped]) | Event::Key) args) -> void
+      def inject_keys: (*(String | Symbol | { code: String, ?modifiers: Array[String] } | Event::Key) args) -> void
       alias inject_key inject_keys
     end
   end

data/sig/ratatui_ruby/test_helper/snapshot.rbs

@@ -10,9 +10,28 @@
 module RatatuiRuby
   module TestHelper
     module Snapshot
-      def assert_snapshot: (String name, ?String? msg) ?{ (Array[String]) -> Array[String] } -> void
-      def assert_screen_matches: (String | Array[String] expected, ?String? msg) ?{ (Array[String]) -> Array[String] } -> void
-      def assert_rich_snapshot: (String name, ?String? msg) ?{ (Array[String]) -> Array[String] } -> void
+      include ::Minitest::Assertions
+
+      # Public assertions
+      def assert_plain_snapshot: (String name, ?String? msg, ?snapshot_dir: String?) ?{ (Array[String]) -> Array[String] } -> void
+      def assert_screen_matches: ((String | Array[String]) expected, ?String? msg) ?{ (Array[String]) -> Array[String] } -> void
+      def assert_rich_snapshot: (String name, ?String? msg, ?snapshot_dir: String?) ?{ (Array[String]) -> Array[String] } -> void
+      def assert_snapshots: (String name, ?String? msg) ?{ (Array[String]) -> Array[String] } -> void
+      def render_rich_buffer: () -> String
+
+      # Methods available via mixin context (from Minitest::Assertions)
+      # untyped: assert_equal from Minitest compares any two values
+      def assert_equal: (untyped expected, untyped actual, ?String? msg) -> void
+
+      # Methods available via mixin context (from Terminal)
+      def buffer_content: () -> Array[String]
+
+      private
+
+      def _render_buffer_with_ansi: () -> String
+      def _ansi_for_color: ((Symbol | String)?, Symbol layer) -> String
+      def _ansi_named_color: (Symbol name, bool is_fg) -> String
+      def _ansi_for_modifiers: (Array[Symbol]?) -> String
     end
   end
 end

data/sig/ratatui_ruby/test_helper/style_assertions.rbs

@@ -7,12 +7,19 @@
 
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# untyped: **untyped splat - assertions accept any attribute combination (fg, bg, bold, etc.)
+
 module RatatuiRuby
   module TestHelper
     module StyleAssertions
+      include ::Minitest::Assertions
+
+      # From Terminal module
+      def get_cell: (Integer x, Integer y) -> Hash[Symbol, untyped]
+
       def assert_cell_style: (Integer x, Integer y, **untyped expected_attributes) -> void
       def assert_color: (Symbol | Integer | String expected, x: Integer, y: Integer, ?layer: Symbol) -> void
-      def assert_area_style: (Rect | Hash[Symbol, Integer] area, **untyped attributes) -> void
+      def assert_area_style: (Layout::Rect | Hash[Symbol, Integer] area, **untyped attributes) -> void
       def assert_fg_color: (Symbol | Integer | String expected, Integer x, Integer y) -> void
       alias assert_fg assert_fg_color
       def assert_bg_color: (Symbol | Integer | String expected, Integer x, Integer y) -> void

data/sig/ratatui_ruby/test_helper/test_doubles.rbs

@@ -7,13 +7,16 @@
 
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# untyped: widget parameter/storage - test mocks accept any widget type for flexibility
+
 module RatatuiRuby
   module TestHelper
     module TestDoubles
       class MockFrame < Data
-        attr_accessor rendered_widgets: Array[{ widget: untyped, area: Rect }]
-        def self.new: (?rendered_widgets: Array[{ widget: untyped, area: Rect }]) -> MockFrame
-        def render_widget: (untyped widget, Rect area) -> void
+        attr_accessor rendered_widgets: Array[{ widget: untyped, area: Layout::Rect }]
+        def self.new: (?rendered_widgets: Array[{ widget: untyped, area: Layout::Rect }]) -> MockFrame
+        def initialize: (?rendered_widgets: Array[{ widget: untyped, area: Layout::Rect }]) -> void
+        def render_widget: (untyped widget, Layout::Rect area) -> void
       end
 
       class StubRect < Data
@@ -22,6 +25,7 @@ module RatatuiRuby
         attr_accessor width: Integer
         attr_accessor height: Integer
         def self.new: (?x: Integer, ?y: Integer, ?width: Integer, ?height: Integer) -> StubRect
+        def initialize: (?x: Integer, ?y: Integer, ?width: Integer, ?height: Integer) -> void
       end
     end
   end

data/sig/ratatui_ruby/text/line.rbs

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Text
+    class Line < Data
+      attr_reader spans: Array[Span]
+      attr_reader alignment: Symbol?
+      attr_reader style: Style::Style?
+
+      def self.new: (?spans: Array[Span], ?alignment: Symbol?, ?style: Style::Style?) -> Line
+      def initialize: (?spans: Array[Span], ?alignment: Symbol?, ?style: Style::Style?) -> void
+      def self.from_string: (String, ?alignment: Symbol?) -> Line
+      def width: () -> Integer
+      def left_aligned: () -> Line
+      def centered: () -> Line
+      def right_aligned: () -> Line
+      def push_span: (Span) -> Line
+      def patch_style: (Style::Style?) -> Line
+      def reset_style: () -> Line
+    end
+  end
+end

data/sig/ratatui_ruby/text/span.rbs

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Text
+    class Span < Data
+      attr_reader content: String
+      attr_reader style: Style::Style?
+
+      def self.new: (content: String, ?style: Style::Style?) -> Span
+      def initialize: (content: String, ?style: Style::Style?) -> void
+      def self.styled: (String, ?Style?) -> Span
+      def width: () -> Integer
+      def self.raw: (String) -> Span
+      def patch_style: (Style::Style?) -> Span
+      def reset_style: () -> Span
+    end
+  end
+end

data/sig/ratatui_ruby/text.rbs

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Text
+    def self.width: (String) -> Integer
+  end
+end

data/sig/ratatui_ruby/tui/buffer_factories.rbs

@@ -10,7 +10,7 @@
 module RatatuiRuby
   class TUI
     module BufferFactories
-      def cell: (?char: String?, ?fg: Symbol?, ?bg: Symbol?, ?modifiers: Array[Symbol]?) -> Buffer::Cell
+      def cell: (?symbol: String?, ?char: String?, ?fg: (Symbol | String | nil), ?bg: (Symbol | String | nil), ?modifiers: Array[String]) -> Buffer::Cell
     end
   end
 end

data/sig/ratatui_ruby/tui/canvas_factories.rbs

@@ -10,11 +10,29 @@
 module RatatuiRuby
   class TUI
     module CanvasFactories
-      def shape_map: (**top) -> Widgets::Shape::Map
-      def shape_line: (**top) -> Widgets::Shape::Line
-      def shape_point: (**top) -> Widgets::Shape::Point
-      def shape_circle: (**top) -> Widgets::Shape::Circle
-      def shape_rectangle: (**top) -> Widgets::Shape::Rectangle
+      # Core shape methods
+      def shape_map: (?color: (String | Symbol), ?resolution: Symbol) -> Widgets::Shape::Map
+      def shape_line: (x1: _ToF, y1: _ToF, x2: _ToF, y2: _ToF, color: (String | Symbol)) -> Widgets::Shape::Line
+      def shape_point: (x: _ToF, y: _ToF) -> Widgets::Shape::Point
+      def shape_circle: (x: _ToF, y: _ToF, radius: _ToF, color: (String | Symbol)) -> Widgets::Shape::Circle
+      def shape_rectangle: (x: _ToF, y: _ToF, width: _ToF, height: _ToF, color: (String | Symbol)) -> Widgets::Shape::Rectangle
+      def shape_label: (x: _ToF, y: _ToF, ?text: String?, ?line: Text::Line?) -> Widgets::Shape::Label
+
+      # Terse aliases (DWIM) - no rectangle to avoid confusion with Layout::Rect
+      alias circle shape_circle
+      alias point shape_point
+      alias map shape_map
+      def label: (?untyped first, **untyped kwargs) -> Widgets::Shape::Label
+
+      # Bidirectional aliases (*_shape)
+      alias circle_shape shape_circle
+      alias point_shape shape_point
+      alias rectangle_shape shape_rectangle
+      alias map_shape shape_map
+      alias label_shape label
+
+      # Shape dispatcher (TIMTOWTDI pattern)
+      def shape: (Symbol, **untyped) -> untyped
     end
   end
 end

data/sig/ratatui_ruby/tui/core.rbs

@@ -10,9 +10,9 @@
 module RatatuiRuby
   class TUI
     module Core
-      def draw: (?Widgets::_Widget? tree) -> void
+      def draw: (?widget? tree) -> void
               | () { (Frame) -> void } -> void
-      def poll_event: (?timeout: Float) -> Event::event
+      def poll_event: (?timeout: Float) -> Event?
       def get_cell_at: (Integer x, Integer y) -> Buffer::Cell
       def draw_cell: (Integer x, Integer y, Buffer::Cell cell) -> Draw::CellCmd
     end

data/sig/ratatui_ruby/tui/layout_factories.rbs

@@ -11,15 +11,29 @@ module RatatuiRuby
   class TUI
     module LayoutFactories
       def rect: (?x: Integer, ?y: Integer, ?width: Integer, ?height: Integer) -> Layout::Rect
-      def constraint: (**top) -> Layout::Constraint
+
+      # Constraint dispatcher (TIMTOWTDI pattern)
+      def constraint: (?type: Symbol, ?value: (Integer | Array[Integer])) -> Layout::Constraint
+                   | (:length | :fixed, Integer) -> Layout::Constraint
+                   | (:percentage | :percent, Integer) -> Layout::Constraint
+                   | (:min, Integer) -> Layout::Constraint
+                   | (:max, Integer) -> Layout::Constraint
+                   | (:fill | :flex | :fr, ?Integer) -> Layout::Constraint
+                   | (:ratio | :aspect, Integer, Integer) -> Layout::Constraint
+
       def constraint_length: (Integer n) -> Layout::Constraint
       def constraint_percentage: (Integer n) -> Layout::Constraint
       def constraint_min: (Integer n) -> Layout::Constraint
       def constraint_max: (Integer n) -> Layout::Constraint
       def constraint_fill: (?Integer n) -> Layout::Constraint
       def constraint_ratio: (Integer numerator, Integer denominator) -> Layout::Constraint
-      def layout: (**top) -> Layout::Layout
+      def layout: (?direction: Symbol, ?constraints: Array[Layout::Constraint], ?children: Array[widget], ?flex: Layout::flex_mode) -> Layout::Layout
       def layout_split: (Layout::Rect area, ?direction: Symbol, constraints: Array[Layout::Constraint], ?flex: Symbol) -> Array[Layout::Rect]
+      def split: (Layout::Rect area, ?direction: Symbol, constraints: Array[Layout::Constraint], ?flex: Symbol) -> Array[Layout::Rect]
+      def fixed: (Integer n) -> Layout::Constraint
+      def percent: (Integer n) -> Layout::Constraint
+      def flex: (?Integer n) -> Layout::Constraint
+      def fr: (?Integer n) -> Layout::Constraint
     end
   end
 end

data/sig/ratatui_ruby/tui/state_factories.rbs

@@ -10,9 +10,14 @@
 module RatatuiRuby
   class TUI
     module StateFactories
-      def list_state: (**top) -> ListState
-      def table_state: (**top) -> TableState
-      def scrollbar_state: (**top) -> ScrollbarState
+      def list_state: (?Integer? selected) -> ListState
+      def table_state: (?Integer? selected) -> TableState
+      def scrollbar_state: (?Integer content_length) -> ScrollbarState
+
+      # State dispatcher (TIMTOWTDI pattern)
+      def state: (:list, ?Integer? arg) -> ListState
+              | (:table, ?Integer? arg) -> TableState
+              | (:scrollbar, ?Integer arg) -> ScrollbarState
     end
   end
 end

data/sig/ratatui_ruby/tui/style_factories.rbs

@@ -10,7 +10,9 @@
 module RatatuiRuby
   class TUI
     module StyleFactories
-      def style: (?fg: Symbol?, ?bg: Symbol?, ?modifiers: Array[Symbol]?) -> Style::Style
+      type color = String | Symbol | Integer
+
+      def style: (?fg: color?, ?bg: color?, ?underline_color: color?, ?modifiers: Array[Symbol], ?remove_modifiers: Array[Symbol]) -> Style::Style
     end
   end
 end

data/sig/ratatui_ruby/tui/text_factories.rbs

@@ -10,11 +10,14 @@
 module RatatuiRuby
   class TUI
     module TextFactories
-      def text_span: (?content: String, ?style: Style::Style?) -> Text::Span
-      def span: (?content: String, ?style: Style::Style?) -> Text::Span
-      def text_line: (?spans: Array[Text::Span], ?alignment: Symbol?) -> Text::Line
-      def line: (?spans: Array[Text::Span], ?alignment: Symbol?) -> Text::Line
+      def text_span: (content: String, ?style: Style::Style?) -> Text::Span
+      def span: (content: String, ?style: Style::Style?) -> Text::Span
+      def text_line: (?spans: Array[Text::Span], ?alignment: Symbol?, ?style: Style::Style?) -> Text::Line
+      def line: (?spans: Array[Text::Span], ?alignment: Symbol?, ?style: Style::Style?) -> Text::Line
       def text_width: (String string) -> Integer
+
+      # Text dispatcher (TIMTOWTDI pattern)
+      def text: (Symbol, **untyped) -> (Text::Span | Text::Line)
     end
   end
 end