ratatui_ruby 0.9.0 → 0.10.0

data/sig/ratatui_ruby/draw.rbs

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Draw
+    class StringCmd < Data
+      attr_reader x: Integer
+      attr_reader y: Integer
+      attr_reader string: String
+      attr_reader style: style_input
+
+      def self.new: (x: Integer, y: Integer, string: String, style: style_input) -> StringCmd
+    end
+
+    class CellCmd < Data
+      attr_reader x: Integer
+      attr_reader y: Integer
+      attr_reader cell: Buffer::Cell
+
+      def self.new: (x: Integer, y: Integer, cell: Buffer::Cell) -> CellCmd
+    end
+
+    def self.string: (_ToI x, _ToI y, String string, ?style_input style) -> StringCmd
+    def self.cell: (_ToI x, _ToI y, Buffer::Cell cell) -> CellCmd
+  end
+end

data/sig/ratatui_ruby/event.rbs

@@ -9,17 +9,70 @@
 
 module RatatuiRuby
   class Event
+    def none?: () -> bool
     def key?: () -> bool
     def mouse?: () -> bool
     def resize?: () -> bool
     def paste?: () -> bool
     def focus_gained?: () -> bool
     def focus_lost?: () -> bool
-    def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, untyped]
+    def sync?: () -> bool
+    def method_missing: (Symbol, *untyped, **untyped) ?{ (?) -> untyped } -> untyped
+    def respond_to_missing?: (Symbol, *untyped) -> bool
+    def deconstruct_keys: (Array[Symbol]?) -> { }
 
     type key_kind = :standard | :function | :media | :modifier | :system
 
+    class Sync < Event
+      def sync?: () -> bool
+      def deconstruct_keys: (Array[Symbol]?) -> { type: :sync }
+    end
+
     class Key < Event
+      # Character handling module
+      module Character
+        def text?: () -> bool
+        def char: () -> String?
+      end
+
+      # Modifier key detection module
+      module Modifier
+        def ctrl?: () -> bool
+        def alt?: () -> bool
+        def shift?: () -> bool
+        def super?: () -> bool
+        def hyper?: () -> bool
+        def meta?: () -> bool
+        def modifier?: () -> bool
+        private def match_modifier_dwim?: (String key_name, Symbol key_sym) -> bool
+      end
+
+      # Media key handling module
+      module Media
+        def media?: () -> bool
+        private def match_media_dwim?: (String key_name) -> bool
+      end
+
+      # Navigation key handling module
+      module Navigation
+        def standard?: () -> bool
+        alias unmodified? standard?
+        private def match_navigation_dwim?: (String key_name, Symbol key_sym) -> bool
+      end
+
+      # System key handling module
+      module System
+        def system?: () -> bool
+        def function?: () -> bool
+        private def match_system_dwim?: (String key_name, Symbol key_sym) -> bool
+      end
+
+      include Character
+      include Modifier
+      include Media
+      include Navigation
+      include System
+
       attr_reader code: String
       attr_reader modifiers: Array[String]
       attr_reader kind: key_kind
@@ -33,14 +86,16 @@ module RatatuiRuby
       def alt?: () -> bool
       def shift?: () -> bool
       def text?: () -> bool
-      def char: () -> String
+      def char: () -> String?
       def media?: () -> bool
       def system?: () -> bool
       def function?: () -> bool
       def modifier?: () -> bool
       def standard?: () -> bool
       def unmodified?: () -> bool
-      def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def method_missing: (Symbol, *untyped, **untyped) ?{ (?) -> untyped } -> untyped
+      def respond_to_missing?: (Symbol, *untyped) -> bool
+      def deconstruct_keys: (Array[Symbol]?) -> { type: :key, code: String, modifiers: Array[String], kind: key_kind }
     end
 
     class Mouse < Event
@@ -56,7 +111,7 @@ module RatatuiRuby
       def drag?: () -> bool
       def scroll_up?: () -> bool
       def scroll_down?: () -> bool
-      def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys: (Array[Symbol]?) -> { type: :mouse, kind: String, x: Integer, y: Integer, button: String, modifiers: Array[String] }
     end
 
     class Resize < Event
@@ -64,22 +119,27 @@ module RatatuiRuby
       attr_reader height: Integer
 
       def initialize: (width: Integer, height: Integer) -> void
-      def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys: (Array[Symbol]?) -> { type: :resize, width: Integer, height: Integer }
     end
 
     class Paste < Event
       attr_reader content: String
 
       def initialize: (content: String) -> void
-      def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys: (Array[Symbol]?) -> { type: :paste, content: String }
     end
 
     class FocusGained < Event
-      def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys: (Array[Symbol]?) -> { type: :focus_gained }
     end
 
     class FocusLost < Event
-      def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys: (Array[Symbol]?) -> { type: :focus_lost }
+    end
+
+    class None < Event
+      def none?: () -> bool
+      def deconstruct_keys: (Array[Symbol]?) -> { type: :none }
     end
   end
 end

data/sig/ratatui_ruby/frame.rbs

@@ -11,13 +11,13 @@ module RatatuiRuby
   # Any Ruby object implementing this interface works as a widget.
   # Return an Array of Draw commands describing what to render.
   interface _CustomWidget
-    def render: (Rect area) -> Array[Draw::StringCmd | Draw::CellCmd]
+    def render: (Layout::Rect area) -> Array[Draw::StringCmd | Draw::CellCmd]
   end
 
   class Frame
-    def area: () -> Rect
-    def render_widget: (_CustomWidget | widget widget, Rect area) -> nil
-    def render_stateful_widget: (widget widget, Rect area, (ListState | TableState | ScrollbarState) state) -> nil
+    def area: () -> Layout::Rect
+    def render_widget: ((_CustomWidget | widget) widget, Layout::Rect area) -> nil
+    def render_stateful_widget: (widget widget, Layout::Rect area, (ListState | TableState | ScrollbarState) state) -> nil
     def set_cursor_position: (Integer x, Integer y) -> nil
   end
 end

data/sig/ratatui_ruby/interfaces.rbs

@@ -0,0 +1,25 @@
+# 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
+
+# Duck-typing interfaces for RatatuiRuby.
+#
+# These interfaces enable type-safe duck typing: any object responding to
+# the specified methods can be used, not just the canonical types.
+module RatatuiRuby
+  # Interface for Rect-like objects.
+  #
+  # Any object responding to x, y, width, and height with Integer returns
+  # can be used where Layout::Rect is expected.
+  interface _RectLike
+    def x: () -> Integer
+    def y: () -> Integer
+    def width: () -> Integer
+    def height: () -> Integer
+  end
+end

data/sig/ratatui_ruby/layout/constraint.rbs

@@ -0,0 +1,39 @@
+# 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
+  module Layout
+    class Constraint < Data
+      attr_reader type: Symbol
+      attr_reader value: (Integer | Array[Integer])
+      def self.length: (_ToI) -> Constraint
+      def self.percentage: (_ToI) -> Constraint
+      def self.min: (_ToI) -> Constraint
+      def self.max: (_ToI) -> Constraint
+      def self.fill: (?_ToI) -> Constraint
+      def self.ratio: (_ToI, _ToI) -> Constraint
+      def self.new: (type: Symbol, value: (Integer | Array[Integer])) -> Constraint
+      def initialize: (type: Symbol, value: (Integer | Array[Integer])) -> void
+
+      # Batch constructors
+      def self.from_lengths: (Enumerable[_ToI]) -> Array[Constraint]
+      def self.from_percentages: (Enumerable[_ToI]) -> Array[Constraint]
+      def self.from_mins: (Enumerable[_ToI]) -> Array[Constraint]
+      def self.from_maxes: (Enumerable[_ToI]) -> Array[Constraint]
+      def self.from_fills: (Enumerable[_ToI]) -> Array[Constraint]
+      def self.from_ratios: (Enumerable[[_ToI, _ToI]]) -> Array[Constraint]
+
+      # Instance methods
+      def apply: (_ToInt) -> Integer
+
+      # Ruby-idiomatic alias
+      alias call apply
+    end
+  end
+end

data/sig/ratatui_ruby/layout/layout.rbs

@@ -0,0 +1,45 @@
+# 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
+  module Layout
+    type flex_mode = Symbol
+
+    class Layout < Data
+      FLEX_MODES: Array[Symbol]
+      DIRECTION_VERTICAL: Symbol
+      DIRECTION_HORIZONTAL: Symbol
+      FLEX_LEGACY: Symbol
+      FLEX_START: Symbol
+      FLEX_CENTER: Symbol
+      FLEX_END: Symbol
+      FLEX_SPACE_BETWEEN: Symbol
+      FLEX_SPACE_AROUND: Symbol
+      FLEX_SPACE_EVENLY: Symbol
+
+      attr_reader direction: Symbol
+      attr_reader constraints: Array[Constraint]
+      attr_reader children: Array[RatatuiRuby::widget]
+      attr_reader flex: flex_mode
+      attr_reader margin: (Integer | Hash[Symbol, Integer])
+      attr_reader spacing: Integer
+      def self.new: (?direction: Symbol, ?constraints: Array[Constraint], ?children: Array[RatatuiRuby::widget], ?flex: flex_mode, ?margin: (Integer | Hash[Symbol, Integer]), ?spacing: Integer) -> Layout
+      def initialize: (?direction: Symbol, ?constraints: Array[Constraint], ?children: Array[RatatuiRuby::widget], ?flex: flex_mode, ?margin: (Integer | Hash[Symbol, Integer]), ?spacing: Integer) -> void
+      def self.split: ((Rect | Hash[Symbol, Integer]) area, ?direction: Symbol, constraints: Array[Constraint], ?flex: flex_mode) -> Array[Rect]
+
+      # Splits an area into segments and spacers.
+      # Returns [segments, spacers] where each is an Array of Rects.
+      def self.split_with_spacers: ((Rect | Hash[Symbol, Integer]) area, ?direction: Symbol, constraints: Array[Constraint], ?flex: flex_mode) -> [Array[Rect], Array[Rect]]
+
+      private
+
+      def self._split: (Rect, Symbol, Array[Constraint], Symbol) -> Array[Hash[Symbol, Integer]]
+    end
+  end
+end

data/sig/ratatui_ruby/layout/position.rbs

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Layout
+    class Position < Data
+      attr_reader x: Integer
+      attr_reader y: Integer
+
+      def self.new: (?x: _ToInt, ?y: _ToInt) -> instance
+      def initialize: (?x: _ToInt, ?y: _ToInt) -> void
+    end
+  end
+end

data/sig/ratatui_ruby/layout/rect.rbs

@@ -0,0 +1,64 @@
+# 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
+  module Layout
+    class Rect < Data
+      attr_reader x: Integer
+      attr_reader y: Integer
+      attr_reader width: Integer
+      attr_reader height: Integer
+
+      def self.new: (?x: _ToI, ?y: _ToI, ?width: _ToI, ?height: _ToI) -> instance
+      def initialize: (?x: _ToI, ?y: _ToI, ?width: _ToI, ?height: _ToI) -> void
+
+      # Predicates
+      def contains?: (Integer px, Integer py) -> bool
+      def intersects?: (Rect other) -> bool
+      def empty?: () -> bool
+
+      # Edge accessors
+      def left: () -> Integer
+      def right: () -> Integer
+      def top: () -> Integer
+      def bottom: () -> Integer
+      def area: () -> Integer
+
+      # Geometry transformations
+      def intersection: (Rect other) -> Rect?
+      def union: (Rect other) -> Rect
+      def inner: (Integer margin) -> Rect
+      def outer: (Integer margin) -> Rect
+      def resize: (Size new_size) -> Rect
+      def offset: (Integer dx, Integer dy) -> Rect
+      def clamp: (Rect other) -> Rect
+
+      # Iterators
+      def rows: () -> Enumerator[Rect, void]
+              | () { (Rect) -> void } -> void
+      def columns: () -> Enumerator[Rect, void]
+                 | () { (Rect) -> void } -> void
+      def positions: () -> Enumerator[[Integer, Integer], void]
+                   | () { ([Integer, Integer]) -> void } -> void
+
+      # Conversions
+      def as_position: () -> Position
+      def as_size: () -> Size
+
+      # Centering
+      def centered_horizontally: (Constraint) -> Rect
+      def centered_vertically: (Constraint) -> Rect
+      def centered: (Constraint, Constraint) -> Rect
+
+      # Ruby-idiomatic aliases
+      alias position as_position
+      alias size as_size
+    end
+  end
+end

data/sig/ratatui_ruby/layout/size.rbs

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Layout
+    class Size < Data
+      attr_reader width: Integer
+      attr_reader height: Integer
+
+      def self.new: (?width: _ToInt, ?height: _ToInt) -> instance
+      def initialize: (?width: _ToInt, ?height: _ToInt) -> void
+    end
+  end
+end

data/sig/ratatui_ruby/output_guard.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
+#++
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module OutputGuard
+    # Null IO object that discards all output
+    class NullIO
+      def method_missing: (Symbol name, *untyped args) ?{ (*untyped) -> untyped } -> NullIO
+      def respond_to_missing?: (Symbol name, ?bool include_private) -> true
+    end
+
+    def is_headless?: () -> bool
+    def headless!: () -> void
+    def guard_io: [T] () { () -> T } -> T
+    def terminal_active?: () -> bool
+  end
+end

data/sig/ratatui_ruby/ratatui_ruby.rbs

@@ -8,17 +8,96 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  type widget = Paragraph | Layout | List | Gauge | Table | Tabs | BarChart | Block | Sparkline
+  # Common type aliases for widget parameters
+  type alignment = :left | :center | :right
+  type border_side = :top | :bottom | :left | :right | :all
+  type border_type = :plain | :rounded | :double | :thick | :hidden | :quadrant_inside | :quadrant_outside
+  type title_position = :top | :bottom
+  type style_input = Style::Style | { ?fg: (Symbol | String | Integer), ?bg: (Symbol | String | Integer), ?modifiers: Array[Symbol] }
+  type title_entry = String | { content: (String | Text::Line), ?alignment: alignment, ?position: title_position, ?style: style_input }
+  type border_set_hash = { ?top_left: String, ?top_right: String, ?bottom_left: String, ?bottom_right: String, ?vertical_left: String, ?vertical_right: String, ?horizontal_top: String, ?horizontal_bottom: String }
+  type date_key = Date | [Integer, Integer, Integer]
+
+  type widget = Widgets::Paragraph | Layout::Layout | Widgets::List | Widgets::Gauge | Widgets::Table | Widgets::Tabs | Widgets::BarChart | Widgets::Block | Widgets::Sparkline
 
   interface _ToS
     def to_s: () -> String
   end
 
-  def self.init_terminal: (focus_events: bool, bracketed_paste: bool) -> void
+  # Error classes
+  class Error < StandardError
+    class Terminal < Error
+    end
+    class Safety < Error
+    end
+    class Invariant < Error
+    end
+  end
+
+  # NullIO for headless mode
+
+
+  # Core module methods
+  def self.init_terminal: (?focus_events: bool, ?bracketed_paste: bool) -> void
+  def self.init_test_terminal: (Integer width, Integer height) -> void
   def self.restore_terminal: () -> void
-  def self.draw: (widget tree) -> void
+  def self.terminal_active?: () -> bool
+  def self.run: (?focus_events: bool, ?bracketed_paste: bool) { (TUI) -> void } -> void
+  def self.draw: (?widget? tree) -> void
                | () { (Frame) -> void } -> void
+  # untyped: FFI boundary - Rust returns dynamic event hash with varying keys per event type
   def self._poll_event: (Float?) -> Hash[Symbol, untyped]?
   def self.poll_event: (?timeout: Float?) -> Event?
-  def self.inject_test_event: (String, Hash[Symbol, untyped]) -> void
+  def self.inject_test_event: ("key", { code: String, ?modifiers: Array[String], ?kind: Event::key_kind }) -> void
+                            | ("mouse", { kind: String, x: Integer, y: Integer, ?button: String, ?modifiers: Array[String] }) -> void
+                            | ("resize", { width: Integer, height: Integer }) -> void
+                            | ("paste", { content: String }) -> void
+                            | ("focus_gained", { }) -> void
+                            | ("focus_lost", { }) -> void
+  def self.get_cell_at: (Integer x, Integer y) -> Buffer::Cell
+  def self.experimental_warnings: () -> bool
+  def self.experimental_warnings=: (bool) -> bool
+  def self.warn_experimental_feature: (String feature_name) -> void
+
+  # Warning queue (private)
+  def self.queue_warning: (String message) -> void
+  def self.flush_warnings: () -> void
+
+  # Panic info (private, for deferred backtrace output)
+  def self._get_last_panic: () -> String?
+  def self.flush_panic_info: () -> void
+
+  # Draw internal
+  def self._draw: (widget) -> void
+               | () { (Frame) -> void } -> void
+
+  # Cell accessor internal (returns Hash with String keys from Rust FFI)
+  def self._get_cell_at: (Integer x, Integer y) -> Hash[String, untyped]
+
+  # Signal handling
+  def self.trap: (String | Symbol signal) { () -> void } -> void
+
+  # Paragraph helpers
+  def self._paragraph_line_count: (Widgets::Paragraph p, Integer width) -> Integer
+  def self._paragraph_line_width: (Widgets::Paragraph p) -> Integer
+
+  # Tabs/Text helpers
+  def self._tabs_width: (Widgets::Tabs t) -> Integer
+  def self._text_width: (String text) -> Integer
+
+  # Debug mode convenience method
+  def self.debug_mode!: () -> void
+
+  # Headless mode
+  def self.headless!: () -> void
+  def self.headless?: () -> bool
+
+  # Terminal area accessor (internal, returns Hash with String keys from Rust FFI)
+  def self._get_terminal_area: () -> Hash[String, Integer]
+
+  # Color conversion (internal, Rust FFI)
+  def self._color_from_u32: (Integer) -> String
+  def self._color_from_hsl: (Float, Float, Float) -> String
+  def self._color_from_hsluv: (Float, Float, Float) -> String
 end
+

data/sig/ratatui_ruby/rect.rbs

@@ -0,0 +1,17 @@
+# 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
+
+# NOTE: RatatuiRuby::Rect is not defined at runtime in the main gem.
+# This file exists only to satisfy the build system.
+# The actual Rect class is Layout::Rect in sig/ratatui_ruby/schema/rect.rbs.
+#
+# The schema/ folder structure is pending migration per:
+# doc/contributors/v1.0.0_blockers.md
+
+# Empty placeholder - actual type is RatatuiRuby::Layout::Rect

data/sig/ratatui_ruby/style/color.rbs

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Style
+    module Color
+      def self.from_u32: (Integer) -> String
+      def self.from_hsl: (_ToF, _ToF, _ToF) -> String
+      def self.from_hsluv: (_ToF, _ToF, _ToF) -> String
+
+      # Ruby-idiomatic aliases
+      alias self.hex self.from_u32
+      alias self.hsl self.from_hsl
+      alias self.hsluv self.from_hsluv
+    end
+  end
+end
+

data/sig/ratatui_ruby/style/style.rbs

@@ -0,0 +1,29 @@
+# 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
+  # Style module at RatatuiRuby::Style
+  module Style
+    # Style class for RatatuiRuby::Style::Style
+    class Style < Data
+      type color = String | Symbol | Integer
+
+      attr_reader fg: color?
+      attr_reader bg: color?
+      attr_reader underline_color: color?
+      attr_reader modifiers: Array[Symbol]
+      attr_reader remove_modifiers: Array[Symbol]
+
+      def self.new: (?fg: color?, ?bg: color?, ?underline_color: color?, ?modifiers: Array[Symbol], ?remove_modifiers: Array[Symbol]) -> Style
+      def initialize: (?fg: color?, ?bg: color?, ?underline_color: color?, ?modifiers: Array[Symbol], ?remove_modifiers: Array[Symbol]) -> void
+      def self.default: () -> Style
+      def self.with: (?fg: color?, ?bg: color?, ?underline_color: color?, ?modifiers: Array[Symbol], ?remove_modifiers: Array[Symbol]) -> Style
+    end
+  end
+end