ratatui_ruby 0.5.0 → 0.7.0

data/lib/ratatui_ruby/widgets/table.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Widgets
+    # Displays structured data in rows and columns.
+    #
+    # Data is often multidimensional. You need to show relationships between fields (Name, Age, ID).
+    # Aligning columns manually in a monospaced environment is painful and error-prone.
+    #
+    # This widget creates a grid. It enforces column widths using constraints. It renders headers, rows, and footers aligned perfectly.
+    #
+    # Use it to display database records, logs, or file lists.
+    #
+    # {rdoc-image:/doc/images/widget_table_flex.png}[link:/examples/widget_table_flex/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_table_flex/app.rb
+    class Table < Data.define(:header, :rows, :widths, :row_highlight_style, :highlight_symbol, :highlight_spacing, :column_highlight_style, :cell_highlight_style, :selected_row, :selected_column, :offset, :block, :footer, :flex, :style, :column_spacing)
+      ##
+      # :attr_reader: header
+      # Header row content (Array of Strings, Text::Spans, Text::Lines, or Paragraphs).
+
+      ##
+      # :attr_reader: rows
+      # Data rows (Array of Arrays). Each cell can be String, Text::Span, Text::Line, Paragraph, or Cell.
+
+      ##
+      # :attr_reader: widths
+      # Column width constraints (Array of Constraint).
+
+      ##
+      # :attr_reader: row_highlight_style
+      # Style for the selected row.
+
+      ##
+      # :attr_reader: highlight_symbol
+      # Symbol for the selected row.
+
+      ##
+      # :attr_reader: highlight_spacing
+      # When to show the highlight symbol column (<tt>:always</tt>, <tt>:when_selected</tt>, <tt>:never</tt>).
+
+      ##
+      # :attr_reader: column_highlight_style
+      # Style for the selected column.
+
+      ##
+      # :attr_reader: cell_highlight_style
+      # Style for the selected cell (intersection of row and column).
+
+      ##
+      # :attr_reader: selected_row
+      # Index of the selected row (Integer or nil).
+
+      ##
+      # :attr_reader: selected_column
+      # Index of the selected column (Integer or nil).
+
+      ##
+      # :attr_reader: offset
+      # Scroll offset (Integer or nil).
+      #
+      # Controls the viewport's starting row position in the table.
+      #
+      # When +nil+ (default), Ratatui auto-scrolls to keep the selection visible ("natural scrolling").
+      #
+      # When set, forces the viewport to start at this row index. Use this for:
+      # - **Passive scrolling**: Scroll through a log table without selecting rows.
+      # - **Click-to-select math**: Calculate which row index corresponds to a click coordinate.
+      #
+      # *Important*: When both +offset+ and +selected_row+ are set, Ratatui may still adjust
+      # the viewport during rendering to ensure the selection stays visible. Set +selected_row+
+      # to +nil+ for fully manual scroll control.
+
+      ##
+      # :attr_reader: block
+      # Optional wrapping block.
+
+      ##
+      # :attr_reader: footer
+      # Footer row content (Array of Strings, Text::Spans, Text::Lines, or Paragraphs).
+
+      ##
+      # :attr_reader: flex
+      # Flex mode for column distribution.
+
+      ##
+      # :attr_reader: style
+      # Base style for the entire table.
+
+      ##
+      # :attr_reader: column_spacing
+      # Spacing between columns (Integer, default 1).
+
+      # Creates a new Table.
+      #
+      # [header] Array of strings, Text::Spans, Text::Lines, or paragraphs.
+      # [rows] 2D Array where each cell is String, Text::Span, Text::Line, Paragraph, or Cell.
+      # [widths] Array of Constraints.
+      # [row_highlight_style] Style object.
+      # [highlight_symbol] String.
+      # [highlight_spacing] Symbol (optional, default: <tt>:when_selected</tt>).
+      # [column_highlight_style] Style object.
+      # [cell_highlight_style] Style object.
+      # [selected_row] Integer (nullable).
+      # [selected_column] Integer (nullable).
+      # [offset] Numeric (nullable, coerced to Integer). Forces scroll position when set.
+      # [block] Block (optional).
+      # [footer] Array of strings/paragraphs (optional).
+      # [flex] Symbol (optional, default: <tt>:legacy</tt>).
+      # [style] Style object or Hash (optional).
+      # [column_spacing] Integer (optional, default: 1).
+      def initialize(header: nil, rows: [], widths: [], row_highlight_style: nil, highlight_symbol: "> ", highlight_spacing: :when_selected, column_highlight_style: nil, cell_highlight_style: nil, selected_row: nil, selected_column: nil, offset: nil, block: nil, footer: nil, flex: :legacy, style: nil, column_spacing: 1)
+        super(
+          header:,
+          rows:,
+          widths:,
+          row_highlight_style:,
+          highlight_symbol:,
+          highlight_spacing:,
+          column_highlight_style:,
+          cell_highlight_style:,
+          selected_row: selected_row.nil? ? nil : Integer(selected_row),
+          selected_column: selected_column.nil? ? nil : Integer(selected_column),
+          offset: offset.nil? ? nil : Integer(offset),
+          block:,
+          footer:,
+          flex:,
+          style:,
+          column_spacing: Integer(column_spacing)
+        )
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/tabs.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Widgets
+    # Displays a tab bar for navigation.
+    #
+    # Screen real estate is limited. You cannot show everything at once. Segregating content into views is necessary for complex apps.
+    #
+    # This widget separates dimensions. It displays a row of titles, indicating which view is active.
+    #
+    # Use it at the top of your interface to switch between major modes or contexts.
+    #
+    # {rdoc-image:/doc/images/widget_tabs_demo.png}[link:/examples/widget_tabs_demo/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_tabs_demo/app.rb
+    class Tabs < Data.define(:titles, :selected_index, :block, :divider, :highlight_style, :style, :padding_left, :padding_right)
+      ##
+      # :attr_reader: titles
+      # Tab titles (Array of Strings).
+
+      ##
+      # :attr_reader: selected_index
+      # Index of the active tab.
+
+      ##
+      # :attr_reader: block
+      # Optional wrapping block.
+
+      ##
+      # :attr_reader: divider
+      # Separator string between tabs.
+
+      ##
+      # :attr_reader: highlight_style
+      # Style for the selected tab title.
+
+      ##
+      # :attr_reader: style
+      # Base style for the tabs area.
+
+      ##
+      # :attr_reader: padding_left
+      # Left padding for the tabs area (Integer, default: 0).
+
+      ##
+      # :attr_reader: padding_right
+      # Right padding for the tabs area (Integer, default: 0).
+
+      # Creates a new Tabs widget.
+      #
+      # [titles] Array of Strings/Lines.
+      # [selected_index] Integer (default: 0).
+      # [block] Block (optional).
+      # [divider] String (optional).
+      # [highlight_style] Style (optional).
+      # [style] Style (optional).
+      # [padding_left] Integer (default: 0).
+      # [padding_right] Integer (default: 0).
+      def initialize(titles: [], selected_index: 0, block: nil, divider: nil, highlight_style: nil, style: nil, padding_left: 0, padding_right: 0)
+        super(
+          titles:,
+          selected_index: Integer(selected_index),
+          block:,
+          divider:,
+          highlight_style:,
+          style:,
+          padding_left: Integer(padding_left),
+          padding_right: Integer(padding_right)
+        )
+      end
+
+      # Returns the total width of the tabs.
+      def width
+        RatatuiRuby._tabs_width(self)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Widget classes for building terminal UIs.
+  #
+  # This module mirrors +ratatui::widgets+ and contains all renderable
+  # widget types: Block, Paragraph, List, Table, Gauge, Chart, etc.
+  module Widgets
+  end
+end
+
+# Core widgets
+require_relative "widgets/block"
+require_relative "widgets/paragraph"
+require_relative "widgets/list"
+require_relative "widgets/list_item"
+require_relative "widgets/table"
+require_relative "widgets/row"
+require_relative "widgets/cell"
+require_relative "widgets/tabs"
+require_relative "widgets/gauge"
+require_relative "widgets/line_gauge"
+require_relative "widgets/sparkline"
+require_relative "widgets/bar_chart"
+require_relative "widgets/bar_chart/bar"
+require_relative "widgets/bar_chart/bar_group"
+require_relative "widgets/chart"
+require_relative "widgets/scrollbar"
+require_relative "widgets/calendar"
+require_relative "widgets/canvas"
+require_relative "widgets/clear"
+require_relative "widgets/cursor"
+require_relative "widgets/overlay"
+require_relative "widgets/center"
+require_relative "widgets/ratatui_logo"
+require_relative "widgets/ratatui_mascot"
+require_relative "widgets/shape/label"

data/lib/ratatui_ruby.rb

@@ -4,37 +4,26 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 require_relative "ratatui_ruby/version"
-require_relative "ratatui_ruby/schema/rect"
-require_relative "ratatui_ruby/schema/paragraph"
-require_relative "ratatui_ruby/schema/layout"
-require_relative "ratatui_ruby/schema/block"
-require_relative "ratatui_ruby/schema/constraint"
-require_relative "ratatui_ruby/schema/list"
-require_relative "ratatui_ruby/schema/style"
-require_relative "ratatui_ruby/schema/gauge"
-require_relative "ratatui_ruby/schema/line_gauge"
-require_relative "ratatui_ruby/schema/table"
-require_relative "ratatui_ruby/schema/tabs"
-require_relative "ratatui_ruby/schema/bar_chart"
-require_relative "ratatui_ruby/schema/bar_chart/bar"
-require_relative "ratatui_ruby/schema/bar_chart/bar_group"
-require_relative "ratatui_ruby/schema/sparkline"
-require_relative "ratatui_ruby/schema/chart"
-require_relative "ratatui_ruby/schema/clear"
-require_relative "ratatui_ruby/schema/cursor"
-require_relative "ratatui_ruby/schema/overlay"
-require_relative "ratatui_ruby/schema/center"
-require_relative "ratatui_ruby/schema/scrollbar"
-require_relative "ratatui_ruby/schema/canvas"
-require_relative "ratatui_ruby/schema/shape/label"
-require_relative "ratatui_ruby/schema/calendar"
-require_relative "ratatui_ruby/schema/ratatui_logo"
-require_relative "ratatui_ruby/schema/ratatui_mascot"
-require_relative "ratatui_ruby/schema/text"
-require_relative "ratatui_ruby/schema/draw"
+
+# New modularized structure (mirrors ratatui Rust crate)
+require_relative "ratatui_ruby/layout"   # Layout::Rect, Layout::Constraint, Layout::Layout
+require_relative "ratatui_ruby/style"    # Style::Style
+require_relative "ratatui_ruby/widgets"  # Widgets::Block, Widgets::Paragraph, etc.
+require_relative "ratatui_ruby/buffer"   # Buffer::Cell (for inspection)
+require_relative "ratatui_ruby/schema/text"  # Text::Span, Text::Line
+require_relative "ratatui_ruby/schema/draw"  # Draw commands
+
+# Event types
 require_relative "ratatui_ruby/event"
-require_relative "ratatui_ruby/cell"
+
+# Frame and state objects
 require_relative "ratatui_ruby/frame"
+require_relative "ratatui_ruby/list_state"
+require_relative "ratatui_ruby/table_state"
+require_relative "ratatui_ruby/scrollbar_state"
+
+# TUI facade (for external instantiation and caching)
+require_relative "ratatui_ruby/tui"
 
 begin
   require "ratatui_ruby/ratatui_ruby"
@@ -52,7 +41,13 @@ end
 # Use `RatatuiRuby.run` to start your application.
 module RatatuiRuby
   # Generic error class for RatatuiRuby.
-  class Error < StandardError; end
+  class Error < StandardError
+    # Raised when a terminal operation fails (e.g., I/O error, backend failure).
+    class Terminal < Error; end
+
+    # Raised when an API safety contract is violated (e.g., accessing a Frame outside its valid scope).
+    class Safety < Error; end
+  end
 
   ##
   # Initializes the terminal for TUI mode.
@@ -119,19 +114,19 @@ module RatatuiRuby
   # pass a block to manipulate the frame directly. The block receives a
   # {Frame} object for imperative drawing.
   #
-  # [tree] A widget tree (Paragraph, Layout, etc.) to render. Optional if
+  # [tree] A widget tree (Widgets::Paragraph, Layout::Layout, etc.) to render. Optional if
   #        a block is given.
   #
   # === Examples
   #
   # Legacy declarative style (tree-based):
   #
-  #   RatatuiRuby.draw(Paragraph.new(text: "Hello"))
+  #   RatatuiRuby.draw(Widgets::Paragraph.new(text: "Hello"))
   #
   # New imperative style (block-based):
   #
   #   RatatuiRuby.draw do |frame|
-  #     frame.render_widget(Paragraph.new(text: "Hello"), frame.area)
+  #     frame.render_widget(Widgets::Paragraph.new(text: "Hello"), frame.area)
   #   end
   #
   def self.draw(tree = nil, &block)
@@ -155,41 +150,54 @@ module RatatuiRuby
   ##
   # Checks for user input.
   #
-  # Returns a discrete event (Key, Mouse, Resize) if one is available in the queue.
-  # Returns RatatuiRuby::Event::None if the queue is empty (non-blocking).
+  # Interactive apps must respond to input. Loops need to poll without burning CPU.
   #
-  # === Example
+  # This method checks for an event. It returns the event if one is found. It returns {RatatuiRuby::Event::None} if the timeout expires.
   #
+  # [timeout] Float seconds to wait (default: 0.016).
+  #           Pass <tt>nil</tt> to block indefinitely (wait forever).
+  #           Pass <tt>0.0</tt> for a non-blocking check.
+  #
+  # === Examples
+  #
+  #   # Standard loop (approx 60 FPS)
   #   event = RatatuiRuby.poll_event
-  #   if event.none?
-  #     puts "No input available"
-  #   elsif event.key?
-  #     puts "Key pressed"
-  #   end
   #
-  def self.poll_event
-    raw = _poll_event
-    return Event::None.new if raw.nil?
+  #   # Block until event (pauses execution)
+  #   event = RatatuiRuby.poll_event(timeout: nil)
+  #
+  #   # Non-blocking check (returns immediately)
+  #   event = RatatuiRuby.poll_event(timeout: 0.0)
+  #
+  def self.poll_event(timeout: 0.016)
+    raise ArgumentError, "timeout must be non-negative" if timeout && timeout < 0
+
+    raw = _poll_event(timeout)
+    return Event::None.new.freeze if raw.nil?
 
     case raw[:type]
     when :key
-      Event::Key.new(code: raw[:code], modifiers: raw[:modifiers] || [])
+      Event::Key.new(
+        code: raw[:code],
+        modifiers: (raw[:modifiers] || []).freeze,
+        kind: raw[:kind] || :standard
+      ).freeze
     when :mouse
       Event::Mouse.new(
         kind: raw[:kind].to_s,
         x: raw[:x],
         y: raw[:y],
         button: raw[:button].to_s,
-        modifiers: raw[:modifiers] || []
-      )
+        modifiers: (raw[:modifiers] || []).freeze
+      ).freeze
     when :resize
-      Event::Resize.new(width: raw[:width], height: raw[:height])
+      Event::Resize.new(width: raw[:width], height: raw[:height]).freeze
     when :paste
-      Event::Paste.new(content: raw[:content])
+      Event::Paste.new(content: raw[:content]).freeze
     when :focus_gained
-      Event::FocusGained.new
+      Event::FocusGained.new.freeze
     when :focus_lost
-      Event::FocusLost.new
+      Event::FocusLost.new.freeze
     else
       # Fallback for unknown events, though ideally we cover them all
       nil
@@ -204,7 +212,7 @@ module RatatuiRuby
   #
   # Managing generic setup/teardown (raw mode, alternate screen) manualy is error-prone. If your app crashes, the terminal might be left in a broken state.
   #
-  # This method handles the safety net. It initializes the terminal, yields a {Session}, and ensures the terminal state is restored even if exceptions occur.
+  # This method handles the safety net. It initializes the terminal, yields a {TUI}, and ensures the terminal state is restored even if exceptions occur.
   #
   # === Example
   #
@@ -213,9 +221,8 @@ module RatatuiRuby
   #     sleep 1
   #   end
   def self.run(focus_events: true, bracketed_paste: true)
-    require_relative "ratatui_ruby/session"
     init_terminal(focus_events:, bracketed_paste:)
-    yield Session.new
+    yield TUI.new
   ensure
     restore_terminal
   end
@@ -226,7 +233,7 @@ module RatatuiRuby
   # When writing tests, you need to verify that your widget drew the correct characters and styles.
   # This method provides deep inspection of the cell's state (symbol, colors, modifiers).
   #
-  # Returns a {Cell} object.
+  # Returns a {Buffer::Cell} object.
   #
   # Values depend on what the backend has rendered. If nothing has been rendered to a cell, it may contain defaults (empty symbol, nil colors).
   #
@@ -239,7 +246,7 @@ module RatatuiRuby
   #
   def self.get_cell_at(x, y)
     raw = _get_cell_at(x, y)
-    Cell.new(
+    Buffer::Cell.new(
       char: raw["char"],
       fg: raw["fg"],
       bg: raw["bg"],
@@ -251,5 +258,5 @@ module RatatuiRuby
   private_class_method :_get_cell_at
 
   # Hide native Layout._split helper
-  Layout.singleton_class.__send__(:private, :_split)
+  Layout::Layout.singleton_class.__send__(:private, :_split)
 end

data/sig/examples/app_all_events/view.rbs

@@ -3,6 +3,6 @@
 
 module View
   interface _View
-    def call(state: ViewState, tui: RatatuiRuby::Session, frame: RatatuiRuby::Frame, area: RatatuiRuby::Rect) -> void
+    def call(state: ViewState, tui: RatatuiRuby::TUI, frame: RatatuiRuby::Frame, area: RatatuiRuby::Rect) -> void
   end
 end

data/sig/examples/app_all_events/view_state.rbs

@@ -10,6 +10,6 @@ class ViewState < Data
   attr_reader border_color: Symbol
   attr_reader area: RatatuiRuby::Rect?
 
-  def self.build(events: Events, focused: bool, tui: RatatuiRuby::Session, _resize_sub_counter: untyped) -> instance
+  def self.build(events: Events, focused: bool, tui: RatatuiRuby::TUI, _resize_sub_counter: untyped) -> instance
   def self.new: (?events: Events, ?focused: bool, ?hotkey_style: RatatuiRuby::Style, ?dimmed_style: RatatuiRuby::Style, ?lit_style: RatatuiRuby::Style, ?border_color: Symbol, ?area: RatatuiRuby::Rect | nil) -> instance
 end

data/sig/examples/app_stateful_interaction/app.rbs

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class AppStatefulInteraction
+  @tables: Array[String]
+  @data: Hash[String, Array[Array[String]]]
+  @list_state: RatatuiRuby::ListState
+  @table_state: RatatuiRuby::TableState
+  @active_pane: :list | :table
+  @tui: untyped
+  @style_active: RatatuiRuby::Style
+  @style_inactive: RatatuiRuby::Style
+  @style_highlight: RatatuiRuby::Style
+  @list_area: RatatuiRuby::Rect
+  @table_area: RatatuiRuby::Rect
+
+  # @public
+  def self.new: () -> AppStatefulInteraction
+
+  # @public
+  def run: () -> void
+
+  private
+
+  def render: () -> void
+  def render_list: (untyped frame, RatatuiRuby::Rect area) -> void
+  def render_table: (untyped frame, RatatuiRuby::Rect area) -> void
+  def handle_input: () -> (:quit | nil)
+  def scroll_active: (Integer delta) -> void
+  def handle_click: (Integer x, Integer y) -> void
+  def handle_list_click: (Integer mouse_y) -> void
+  def handle_table_click: (Integer mouse_y) -> void
+end

data/sig/examples/widget_block_demo/app.rbs

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+#
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+class WidgetBlockDemo
+  @tui: RatatuiRuby::Tui
+  @hotkey_style: RatatuiRuby::Style
+  @title_configs: Array[{name: String, title: String?}]
+  @title_index: Integer
+  @titles_configs: Array[{name: String, titles: Array[RatatuiRuby::Block::title_input]}]
+  @titles_index: Integer
+  @alignment_configs: Array[{name: String, alignment: RatatuiRuby::Alignment}]
+  @alignment_index: Integer
+  @title_styles: Array[{name: String, style: RatatuiRuby::Style?}]
+  @title_style_index: Integer
+  @border_configs: Array[{name: String, borders: Array[RatatuiRuby::Block::border_option]}]
+  @border_index: Integer
+  @border_type_configs: Array[{name: String, type: RatatuiRuby::Block::border_type?, set: Hash[Symbol, String]?}]
+  @border_type_index: Integer
+  @border_styles: Array[{name: String, style: RatatuiRuby::Style?}]
+  @border_style_index: Integer
+  @base_styles: Array[{name: String, style: RatatuiRuby::Style?}]
+  @base_style_index: Integer
+  @padding_configs: Array[{name: String, padding: RatatuiRuby::Block::padding_input}]
+  @padding_index: Integer
+
+  def self.new: () -> WidgetBlockDemo
+  def run: () -> void
+  private def render: () -> void
+  private def handle_input: () -> (:quit)?
+end

data/sig/examples/{app_map_demo → widget_map_demo}/app.rbs

@@ -2,9 +2,9 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-class AppMapDemo
+class WidgetMapDemo
   # @public
-  def self.new: () -> AppMapDemo
+  def self.new: () -> WidgetMapDemo
 
   # @public
   def run: () -> void

data/sig/examples/{app_table_select → widget_table_demo}/app.rbs

@@ -2,9 +2,9 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-class AppTableSelect
+class WidgetTableDemo
   # @public
-  def self.new: () -> AppTableSelect
+  def self.new: () -> WidgetTableDemo
 
   # @public
   def run: () -> void

data/sig/examples/{widget_table_flex → widget_text_width}/app.rbs

@@ -1,10 +1,9 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-#
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-class WidgetTableFlex
+class WidgetTextWidth
   # @public
-  def self.new: () -> WidgetTableFlex
+  def self.new: () -> WidgetTextWidth
 
   # @public
   def run: () -> void

data/sig/ratatui_ruby/event.rbs

@@ -11,11 +11,14 @@ module RatatuiRuby
     def focus_lost?: () -> bool
     def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, untyped]
 
+    type key_kind = :standard | :function | :media | :modifier | :system
+
     class Key < Event
       attr_reader code: String
       attr_reader modifiers: Array[String]
+      attr_reader kind: key_kind
 
-      def initialize: (code: String, modifiers: Array[String]) -> void
+      def initialize: (code: String, ?modifiers: Array[String], ?kind: key_kind) -> void
       def ==: (untyped other) -> bool
       def to_sym: () -> Symbol
       def to_s: () -> String
@@ -24,6 +27,13 @@ module RatatuiRuby
       def alt?: () -> bool
       def shift?: () -> bool
       def text?: () -> bool
+      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]
     end
 

data/sig/ratatui_ruby/frame.rbs

@@ -5,5 +5,7 @@ module RatatuiRuby
   class Frame
     def area: () -> Rect
     def render_widget: (widget widget, Rect area) -> nil
+    def render_stateful_widget: (widget widget, Rect area, (ListState | TableState | ScrollbarState) state) -> nil
+    def set_cursor_position: (Integer x, Integer y) -> nil
   end
 end

data/sig/ratatui_ruby/list_state.rbs

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class ListState
+    def self.new: (?Integer? selected) -> ListState
+    def select: (Integer? index) -> nil
+    def selected: () -> Integer?
+    def offset: () -> Integer
+    def scroll_down_by: (Integer n) -> nil
+    def scroll_up_by: (Integer n) -> nil
+  end
+end

data/sig/ratatui_ruby/ratatui_ruby.rbs

@@ -12,7 +12,7 @@ module RatatuiRuby
   def self.restore_terminal: () -> void
   def self.draw: (widget tree) -> void
                | () { (Frame) -> void } -> void
-  def self._poll_event: () -> Hash[Symbol, untyped]?
-  def self.poll_event: () -> Event?
+  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
 end