ratatui_ruby 0.9.1 → 0.10.0

data/sig/ratatui_ruby/tui/widget_factories.rbs

@@ -9,37 +9,130 @@
 
 module RatatuiRuby
   class TUI
+    # Widget factory methods for TUI.
+    #
+    # All factory methods support DWIM hash coercion: both `tui.table(hash)` and
+    # `tui.table(**hash)` work identically.
     module WidgetFactories
-      def block: (**top) -> Widgets::Block
-      def paragraph: (**top) -> Widgets::Paragraph
-      def list: (**top) -> Widgets::List
-      def list_item: (**top) -> Widgets::ListItem
-      def table: (**top) -> Widgets::Table
-      def row: (**top) -> Widgets::Row
-      def table_row: (**top) -> Widgets::Row
-      def table_cell: (**top) -> Widgets::Cell
-      def tabs: (**top) -> Widgets::Tabs
-      def gauge: (**top) -> Widgets::Gauge
-      def line_gauge: (**top) -> Widgets::LineGauge
-      def sparkline: (**top) -> Widgets::Sparkline
-      def bar_chart: (**top) -> Widgets::BarChart
-      def bar: (**top) -> Widgets::BarChart::Bar
-      def bar_group: (**top) -> Widgets::BarChart::BarGroup
-      def bar_chart_bar: (**top) -> Widgets::BarChart::Bar
-      def bar_chart_bar_group: (**top) -> Widgets::BarChart::BarGroup
-      def chart: (**top) -> Widgets::Chart
-      def dataset: (**top) -> Widgets::Dataset
-      def axis: (**top) -> Widgets::Axis
-      def scrollbar: (**top) -> Widgets::Scrollbar
-      def calendar: (**top) -> Widgets::Calendar
-      def canvas: (**top) -> Widgets::Canvas
-      def clear: (**top) -> Widgets::Clear
-      def cursor: (**top) -> Widgets::Cursor
-      def overlay: (**top) -> Widgets::Overlay
-      def center: (**top) -> Widgets::Center
-      def ratatui_logo: (**top) -> Widgets::RatatuiLogo
-      def ratatui_mascot: (**top) -> Widgets::RatatuiMascot
-      def shape_label: (**top) -> Widgets::Shape::Label
+      # Widgets::Block
+      def block: (Widgets::block_options) -> Widgets::Block
+              | (?title: String?, ?titles: Array[title_entry], ?title_alignment: alignment?, ?title_style: style_input?, ?borders: Array[border_side], ?border_style: style_input?, ?border_type: border_type?, ?border_set: border_set_hash?, ?style: style_input?, ?padding: (_ToI | Array[_ToI]), ?children: Array[widget]) -> Widgets::Block
+
+      # Widgets::Paragraph
+      def paragraph: (Widgets::paragraph_options) -> Widgets::Paragraph
+                   | (text: String, ?style: Style::Style?, ?fg: (String | Symbol)?, ?bg: (String | Symbol)?, ?block: Widgets::Block?, ?wrap: bool, ?alignment: Symbol, ?scroll: [_ToI, _ToI]) -> Widgets::Paragraph
+
+      # Widgets::List
+      def list: (Widgets::list_options) -> Widgets::List
+             | (?items: Array[String | Text::Span | Text::Line | Widgets::ListItem], ?selected_index: _ToI?, ?offset: _ToI?, ?style: Style::Style?, ?highlight_style: Style::Style?, ?highlight_symbol: String?, ?repeat_highlight_symbol: bool, ?highlight_spacing: Symbol, ?direction: Symbol, ?scroll_padding: _ToI?, ?block: Widgets::Block?) -> Widgets::List
+
+      # Widgets::ListItem
+      def list_item: (Widgets::list_item_options) -> Widgets::ListItem
+                   | (content: String | Text::Span | Text::Line, ?style: Style::Style?) -> Widgets::ListItem
+
+      # DWIM alias for list_item (terse form for use in list context)
+      alias item list_item
+
+      # Widgets::Table
+      def table: (Widgets::table_options) -> Widgets::Table
+              | (?header: Array[String | Widgets::Paragraph]?, ?rows: Array[Array[String | Widgets::Paragraph | Style | _ToS]], ?widths: Array[Layout::Constraint | Integer], ?row_highlight_style: Style::Style?, ?highlight_symbol: String?, ?highlight_spacing: Symbol, ?column_highlight_style: Style::Style?, ?cell_highlight_style: Style::Style?, ?selected_row: _ToI?, ?selected_column: _ToI?, ?offset: _ToI?, ?block: Widgets::Block?, ?footer: Array[String | Widgets::Paragraph]?, ?flex: Symbol, ?style: style_input?, ?column_spacing: _ToI) -> Widgets::Table
+
+      # Widgets::Row
+      def row: (Widgets::row_options) -> Widgets::Row
+            | (cells: Array[String | Text::Span | Text::Line | Widgets::Paragraph | Widgets::Cell], ?style: Style::Style?, ?height: Integer?, ?top_margin: Integer?, ?bottom_margin: Integer?) -> Widgets::Row
+      def table_row: (Widgets::row_options) -> Widgets::Row
+                   | (cells: Array[String | Text::Span | Text::Line | Widgets::Paragraph | Widgets::Cell], ?style: Style::Style?, ?height: Integer?, ?top_margin: Integer?, ?bottom_margin: Integer?) -> Widgets::Row
+
+      # Widgets::Cell
+      def table_cell: (Widgets::cell_options) -> Widgets::Cell
+                    | (content: String | Text::Span | Text::Line | Widgets::Paragraph, ?style: Style::Style?) -> Widgets::Cell
+
+      # Widgets::Tabs
+      def tabs: (Widgets::tabs_options) -> Widgets::Tabs
+             | (?titles: Array[String | _ToS], ?selected_index: _ToI, ?block: Widgets::Block?, ?divider: String?, ?highlight_style: Style::Style?, ?style: Style::Style?, ?padding_left: (String | Text::Line | _ToI), ?padding_right: (String | Text::Line | _ToI)) -> Widgets::Tabs
+
+      # Widgets::Gauge
+      def gauge: (Widgets::gauge_options) -> Widgets::Gauge
+              | (?ratio: _ToF?, ?percent: _ToF?, ?label: String | Text::Span | nil, ?style: Style::Style?, ?gauge_style: Style::Style?, ?block: Widgets::Block?, ?use_unicode: bool) -> Widgets::Gauge
+
+      # Widgets::LineGauge
+      def line_gauge: (Widgets::line_gauge_options) -> Widgets::LineGauge
+                    | (?ratio: _ToF, ?label: String | Text::Span | nil, ?style: Style::Style?, ?filled_style: Style::Style?, ?unfilled_style: Style::Style?, ?block: Widgets::Block?, ?filled_symbol: String, ?unfilled_symbol: String) -> Widgets::LineGauge
+
+      # Widgets::Sparkline
+      def sparkline: (Widgets::sparkline_options) -> Widgets::Sparkline
+                   | (data: Array[_ToI?], ?max: _ToI?, ?style: Style::Style?, ?block: Widgets::Block?, ?direction: (:left_to_right | :right_to_left)?, ?absent_value_symbol: String?, ?absent_value_style: Style::Style?, ?bar_set: Hash[Symbol, String]?) -> Widgets::Sparkline
+
+      # Widgets::BarChart
+      def bar_chart: (Widgets::bar_chart_options) -> Widgets::BarChart
+                   | (data: Hash[String | Symbol | _ToS, _ToI] | Array[Array[String | Symbol | _ToS | _ToI]] | Array[Widgets::BarChart::BarGroup], ?bar_width: _ToI, ?bar_gap: _ToI, ?group_gap: _ToI, ?max: _ToI?, ?style: Style::Style?, ?block: Widgets::Block?, ?direction: (:vertical | :horizontal), ?label_style: Style::Style?, ?value_style: Style::Style?, ?bar_set: Hash[Symbol, String]?) -> Widgets::BarChart
+
+      # Widgets::BarChart::Bar
+      def bar: (Widgets::bar_options) -> Widgets::BarChart::Bar
+            | (value: _ToI, ?label: String | Text::Span | Text::Line | nil, ?style: Style::Style?, ?value_style: Style::Style?, ?text_value: String | Text::Span | Text::Line | nil) -> Widgets::BarChart::Bar
+      def bar_chart_bar: (Widgets::bar_options) -> Widgets::BarChart::Bar
+                       | (value: _ToI, ?label: String | Text::Span | Text::Line | nil, ?style: Style::Style?, ?value_style: Style::Style?, ?text_value: String | Text::Span | Text::Line | nil) -> Widgets::BarChart::Bar
+
+      # Widgets::BarChart::BarGroup
+      def bar_group: (Widgets::bar_group_options) -> Widgets::BarChart::BarGroup
+                   | (label: String, bars: Array[Widgets::BarChart::Bar]) -> Widgets::BarChart::BarGroup
+      def bar_chart_bar_group: (Widgets::bar_group_options) -> Widgets::BarChart::BarGroup
+                             | (label: String, bars: Array[Widgets::BarChart::Bar]) -> Widgets::BarChart::BarGroup
+
+      # Widgets::Chart
+      def chart: (Widgets::chart_options) -> Widgets::Chart
+              | (datasets: Array[Widgets::Dataset], x_axis: Widgets::Axis, y_axis: Widgets::Axis, ?block: Widgets::Block?, ?style: Style::Style?, ?legend_position: Symbol?, ?hidden_legend_constraints: Array[Layout::Constraint]) -> Widgets::Chart
+
+      # Widgets::Dataset
+      def dataset: (Widgets::dataset_options) -> Widgets::Dataset
+                | (name: String | Symbol, data: Array[[_ToF, _ToF]], ?style: Style::Style?, ?marker: Symbol, ?graph_type: Symbol) -> Widgets::Dataset
+
+      # Widgets::Axis
+      def axis: (Widgets::axis_options) -> Widgets::Axis
+             | (?title: String, ?bounds: [_ToF, _ToF], ?labels: Array[String], ?style: Style::Style?, ?labels_alignment: Symbol?) -> Widgets::Axis
+
+      # Widgets::Scrollbar
+      def scrollbar: (Widgets::scrollbar_options) -> Widgets::Scrollbar
+                   | (content_length: _ToI, position: _ToI, ?orientation: Symbol, ?thumb_symbol: String, ?thumb_style: Style::Style?, ?track_symbol: String?, ?track_style: Style::Style?, ?begin_symbol: String?, ?begin_style: Style::Style?, ?end_symbol: String?, ?end_style: Style::Style?, ?style: Style::Style?, ?block: Widgets::Block?) -> Widgets::Scrollbar
+
+      # Widgets::Calendar
+      def calendar: (Widgets::calendar_options) -> Widgets::Calendar
+                  | (year: _ToI, month: _ToI, ?events: Hash[date_key, Style], ?default_style: Style::Style?, ?header_style: Style::Style?, ?block: Widgets::Block?, ?show_weekdays_header: bool, ?show_surrounding: Style::Style?, ?show_month_header: bool) -> Widgets::Calendar
+
+      # Widgets::Canvas
+      def canvas: (Widgets::canvas_options) -> Widgets::Canvas
+               | (?shapes: Array[Widgets::Shape::Line | Widgets::Shape::Rectangle | Widgets::Shape::Circle | Widgets::Shape::Map | Widgets::Shape::Label | Widgets::Shape::Point], ?x_bounds: Array[_ToF], ?y_bounds: Array[_ToF], ?marker: Symbol, ?block: Widgets::Block?, ?background_color: (String | Symbol)?) -> Widgets::Canvas
+
+      # Widgets::Clear
+      def clear: (Widgets::clear_options) -> Widgets::Clear
+              | (?block: Widgets::Block?) -> Widgets::Clear
+
+      # Widgets::Cursor
+      def cursor: (Widgets::cursor_options) -> Widgets::Cursor
+               | (x: _ToI, y: _ToI) -> Widgets::Cursor
+
+      # Widgets::Overlay
+      def overlay: (Widgets::overlay_options) -> Widgets::Overlay
+                | (?layers: Array[widget]) -> Widgets::Overlay
+
+      # Widgets::Center
+      def center: (Widgets::center_options) -> Widgets::Center
+               | (child: widget, ?width_percent: _ToF, ?height_percent: _ToF) -> Widgets::Center
+
+      # Widgets::RatatuiLogo
+      def ratatui_logo: (Widgets::ratatui_logo_options) -> Widgets::RatatuiLogo
+                      | () -> Widgets::RatatuiLogo
+
+      # Widgets::RatatuiMascot
+      def ratatui_mascot: (Widgets::ratatui_mascot_options) -> Widgets::RatatuiMascot
+                        | (?block: Widgets::Block?) -> Widgets::RatatuiMascot
+
+      # Widgets::Shape::Label
+      def shape_label: (Widgets::Shape::label_options) -> Widgets::Shape::Label
+                     | (x: _ToF, y: _ToF, text: String | Text::Line, ?style: Style::Style?) -> Widgets::Shape::Label
+
+      # Widget dispatcher (TIMTOWTDI pattern)
+      def widget: (Symbol, ?untyped, **untyped) -> untyped
     end
   end
 end

data/sig/ratatui_ruby/widgets/bar_chart.rbs

@@ -0,0 +1,95 @@
+# 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 Widgets
+    # Options hash type for BarChart constructor arguments.
+    type bar_chart_options = {
+      ?data: Hash[String | Symbol | _ToS, _ToI] | Array[Array[String | Symbol | _ToS | _ToI]] | Array[BarChart::BarGroup],
+      ?bar_width: _ToI,
+      ?bar_gap: _ToI,
+      ?group_gap: _ToI,
+      ?max: _ToI?,
+      ?style: Style::Style?,
+      ?block: Widgets::Block?,
+      ?direction: (:vertical | :horizontal),
+      ?label_style: Style::Style?,
+      ?value_style: Style::Style?,
+      ?bar_set: Hash[Symbol, String]?
+    }
+
+    # Options hash type for BarChart::Bar constructor arguments.
+    type bar_options = {
+      ?value: _ToI,
+      ?label: String | Text::Span | Text::Line | nil,
+      ?style: Style::Style?,
+      ?value_style: Style::Style?,
+      ?text_value: String | Text::Span | Text::Line | nil
+    }
+
+    # Options hash type for BarChart::BarGroup constructor arguments.
+    type bar_group_options = {
+      ?label: String,
+      ?bars: Array[BarChart::Bar]
+    }
+
+    class BarChart < Data
+      BAR_KEYS: Array[Symbol]
+
+      attr_reader data: Array[BarChart::BarGroup]
+      attr_reader bar_width: Integer
+      attr_reader bar_gap: Integer
+      attr_reader group_gap: Integer
+      attr_reader max: Integer?
+      attr_reader style: Style::Style?
+      attr_reader block: Widgets::Block?
+      attr_reader direction: (:vertical | :horizontal)
+      attr_reader label_style: Style::Style?
+      attr_reader value_style: Style::Style?
+      attr_reader bar_set: Hash[Symbol, String]?
+
+      include CoerceableWidget
+
+      def self.coerce_args: (bar_chart_options first, ?bar_chart_options kwargs) -> BarChart
+                          | (nil first, bar_chart_options kwargs) -> BarChart
+
+      def self.new: (data: Hash[String | Symbol | _ToS, _ToI] | Array[Array[String | Symbol | _ToS | _ToI]] | Array[BarChart::BarGroup], ?bar_width: _ToI, ?bar_gap: _ToI, ?group_gap: _ToI, ?max: _ToI?, ?style: Style::Style?, ?block: Widgets::Block?, ?direction: (:vertical | :horizontal), ?label_style: Style::Style?, ?value_style: Style::Style?, ?bar_set: Hash[Symbol, String]?) -> BarChart
+      def initialize: (data: Hash[String | Symbol | _ToS, _ToI] | Array[Array[String | Symbol | _ToS | _ToI]] | Array[BarChart::BarGroup], ?bar_width: _ToI, ?bar_gap: _ToI, ?group_gap: _ToI, ?max: _ToI?, ?style: Style::Style?, ?block: Widgets::Block?, ?direction: (:vertical | :horizontal), ?label_style: Style::Style?, ?value_style: Style::Style?, ?bar_set: Hash[Symbol, String]?) -> void
+
+      class Bar < Data
+        attr_reader value: Integer
+        attr_reader label: (String | Text::Span | Text::Line)?
+        attr_reader style: Style::Style?
+        attr_reader value_style: Style::Style?
+        attr_reader text_value: (String | Text::Span | Text::Line)?
+
+        include CoerceableWidget
+
+        def self.coerce_args: (bar_options first, ?bar_options kwargs) -> Bar
+                            | (nil first, bar_options kwargs) -> Bar
+
+        def self.new: (value: _ToI, ?label: String | Text::Span | Text::Line | nil, ?style: Style::Style?, ?value_style: Style::Style?, ?text_value: String | Text::Span | Text::Line | nil) -> Bar
+        def initialize: (value: _ToI, ?label: String | Text::Span | Text::Line | nil, ?style: Style::Style?, ?value_style: Style::Style?, ?text_value: String | Text::Span | Text::Line | nil) -> void
+      end
+
+      class BarGroup < Data
+        attr_reader label: String
+        attr_reader bars: Array[BarChart::Bar]
+
+        include CoerceableWidget
+
+        def self.coerce_args: (bar_group_options first, ?bar_group_options kwargs) -> BarGroup
+                            | (nil first, bar_group_options kwargs) -> BarGroup
+
+        def self.new: (label: String, bars: Array[BarChart::Bar]) -> BarGroup
+        def initialize: (label: String, bars: Array[BarChart::Bar]) -> void
+      end
+    end
+  end
+end

data/sig/ratatui_ruby/widgets/block.rbs

@@ -0,0 +1,51 @@
+# 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 Widgets
+    # Options hash type for Block constructor arguments.
+    type block_options = {
+      ?title: String?,
+      ?titles: Array[title_entry],
+      ?title_alignment: alignment?,
+      ?title_style: style_input?,
+      ?borders: Array[border_side],
+      ?border_style: style_input?,
+      ?border_type: border_type?,
+      ?border_set: border_set_hash?,
+      ?style: style_input?,
+      ?padding: (_ToI | Array[_ToI]),
+      ?children: Array[widget]
+    }
+
+    class Block < Data
+      attr_reader title: String?
+      attr_reader titles: Array[title_entry]
+      attr_reader title_alignment: alignment?
+      attr_reader title_style: style_input?
+      attr_reader borders: Array[border_side]
+      attr_reader border_style: style_input?
+      attr_reader border_type: border_type?
+      attr_reader border_set: border_set_hash?
+      attr_reader style: style_input?
+      attr_reader padding: (Integer | Array[Integer])
+      attr_reader children: Array[widget]
+
+      include CoerceableWidget
+
+      def self.coerce_args: (block_options first, ?block_options kwargs) -> Block
+                          | (nil first, block_options kwargs) -> Block
+
+      def self.new: (?title: String?, ?titles: Array[title_entry], ?title_alignment: alignment?, ?title_style: style_input?, ?borders: Array[border_side], ?border_style: style_input?, ?border_type: border_type?, ?border_set: border_set_hash?, ?style: style_input?, ?padding: (_ToI | Array[_ToI]), ?children: Array[widget]) -> Block
+      def initialize: (?title: String?, ?titles: Array[title_entry], ?title_alignment: alignment?, ?title_style: style_input?, ?borders: Array[border_side], ?border_style: style_input?, ?border_type: border_type?, ?border_set: border_set_hash?, ?style: style_input?, ?padding: (_ToI | Array[_ToI]), ?children: Array[widget]) -> void
+
+      def inner: (Layout::Rect area) -> Layout::Rect
+    end
+  end
+end

data/sig/ratatui_ruby/widgets/calendar.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 Widgets
+    # Options hash type for Calendar constructor arguments.
+    type calendar_options = {
+      ?year: _ToI,
+      ?month: _ToI,
+      ?events: Hash[date_key, Style],
+      ?default_style: Style::Style?,
+      ?header_style: Style::Style?,
+      ?block: Widgets::Block?,
+      ?show_weekdays_header: bool,
+      ?show_surrounding: Style::Style?,
+      ?show_month_header: bool
+    }
+
+    class Calendar < Data
+      attr_reader year: Integer
+      attr_reader month: Integer
+      attr_reader events: Hash[date_key, Style]
+      attr_reader default_style: Style::Style?
+      attr_reader header_style: Style::Style?
+      attr_reader block: Widgets::Block?
+      attr_reader show_weekdays_header: bool
+      attr_reader show_surrounding: Style::Style?
+      attr_reader show_month_header: bool
+
+      include CoerceableWidget
+
+      def self.coerce_args: (calendar_options first, ?calendar_options kwargs) -> Calendar
+                          | (nil first, calendar_options kwargs) -> Calendar
+
+      def self.new: (year: _ToI, month: _ToI, ?events: Hash[date_key, Style], ?default_style: Style::Style?, ?header_style: Style::Style?, ?block: Widgets::Block?, ?show_weekdays_header: bool, ?show_surrounding: Style::Style?, ?show_month_header: bool) -> Calendar
+      def initialize: (year: _ToI, month: _ToI, ?events: Hash[date_key, Style], ?default_style: Style::Style?, ?header_style: Style::Style?, ?block: Widgets::Block?, ?show_weekdays_header: bool, ?show_surrounding: Style::Style?, ?show_month_header: bool) -> void
+    end
+  end
+end

data/sig/ratatui_ruby/widgets/canvas.rbs

@@ -0,0 +1,95 @@
+# 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 Widgets
+    # Options hash type for Canvas constructor arguments.
+    type canvas_options = {
+      ?shapes: Array[Shape::Line | Shape::Rectangle | Shape::Circle | Shape::Map | Shape::Label | Shape::Point],
+      ?x_bounds: Array[_ToF],
+      ?y_bounds: Array[_ToF],
+      ?marker: Symbol,
+      ?block: Widgets::Block?,
+      ?background_color: (String | Symbol)?
+    }
+
+    class Canvas < Data
+      attr_reader shapes: Array[Shape::Line | Shape::Rectangle | Shape::Circle | Shape::Map | Shape::Label | Shape::Point]
+      attr_reader x_bounds: Array[Float]
+      attr_reader y_bounds: Array[Float]
+      attr_reader marker: Symbol
+      attr_reader block: Widgets::Block?
+      attr_reader background_color: (String | Symbol)?
+
+      include CoerceableWidget
+
+      def self.coerce_args: (canvas_options first, ?canvas_options kwargs) -> Canvas
+                          | (nil first, canvas_options kwargs) -> Canvas
+
+      def self.new: (?shapes: Array[Shape::Line | Shape::Rectangle | Shape::Circle | Shape::Map | Shape::Label | Shape::Point], ?x_bounds: Array[_ToF], ?y_bounds: Array[_ToF], ?marker: Symbol, ?block: Widgets::Block?, ?background_color: (String | Symbol)?) -> Canvas
+      def initialize: (?shapes: Array[Shape::Line | Shape::Rectangle | Shape::Circle | Shape::Map | Shape::Label | Shape::Point], ?x_bounds: Array[_ToF], ?y_bounds: Array[_ToF], ?marker: Symbol, ?block: Widgets::Block?, ?background_color: (String | Symbol)?) -> void
+
+      # Converts canvas coordinates to normalized grid coordinates.
+      # Returns [normalized_x, normalized_y] or nil if out of bounds.
+      def get_point: (_ToF x, _ToF y) -> Array[Float]?
+      alias point get_point
+      alias [] get_point
+    end
+
+    module Shape
+      class Point < Data
+        attr_reader x: Float
+        attr_reader y: Float
+
+        def self.new: (x: _ToF, y: _ToF) -> Point
+        def initialize: (x: _ToF, y: _ToF) -> void
+      end
+
+      class Line < Data
+        attr_reader x1: Float
+        attr_reader y1: Float
+        attr_reader x2: Float
+        attr_reader y2: Float
+        attr_reader color: (String | Symbol)
+
+        def self.new: (x1: _ToF, y1: _ToF, x2: _ToF, y2: _ToF, color: (String | Symbol)) -> Line
+        def initialize: (x1: _ToF, y1: _ToF, x2: _ToF, y2: _ToF, color: (String | Symbol)) -> void
+      end
+
+      class Rectangle < Data
+        attr_reader x: Float
+        attr_reader y: Float
+        attr_reader width: Float
+        attr_reader height: Float
+        attr_reader color: (String | Symbol)
+
+        def self.new: (x: _ToF, y: _ToF, width: _ToF, height: _ToF, color: (String | Symbol)) -> Rectangle
+        def initialize: (x: _ToF, y: _ToF, width: _ToF, height: _ToF, color: (String | Symbol)) -> void
+      end
+
+      class Circle < Data
+        attr_reader x: Float
+        attr_reader y: Float
+        attr_reader radius: Float
+        attr_reader color: (String | Symbol)
+
+        def self.new: (x: _ToF, y: _ToF, radius: _ToF, color: (String | Symbol)) -> Circle
+        def initialize: (x: _ToF, y: _ToF, radius: _ToF, color: (String | Symbol)) -> void
+      end
+
+      class Map < Data
+        attr_reader color: (String | Symbol)
+        attr_reader resolution: Symbol
+
+        def self.new: (?color: (String | Symbol), ?resolution: Symbol) -> Map
+        def initialize: (?color: (String | Symbol), ?resolution: Symbol) -> void
+      end
+    end
+  end
+end

data/sig/ratatui_ruby/widgets/chart.rbs

@@ -0,0 +1,91 @@
+# 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 Widgets
+    # Options hash type for Chart constructor arguments.
+    type chart_options = {
+      ?datasets: Array[Dataset],
+      ?x_axis: Axis,
+      ?y_axis: Axis,
+      ?block: Widgets::Block?,
+      ?style: Style::Style?,
+      ?legend_position: Symbol?,
+      ?hidden_legend_constraints: Array[Layout::Constraint]
+    }
+
+    # Options hash type for Dataset constructor arguments.
+    type dataset_options = {
+      ?name: String | Symbol,
+      ?data: Array[[_ToF, _ToF]],
+      ?style: Style::Style?,
+      ?marker: Symbol,
+      ?graph_type: Symbol
+    }
+
+    # Options hash type for Axis constructor arguments.
+    type axis_options = {
+      ?title: String,
+      ?bounds: [_ToF, _ToF],
+      ?labels: Array[String],
+      ?style: Style::Style?,
+      ?labels_alignment: Symbol?
+    }
+
+    class Chart < Data
+      attr_reader datasets: Array[Dataset]
+      attr_reader x_axis: Axis
+      attr_reader y_axis: Axis
+      attr_reader block: Widgets::Block?
+      attr_reader style: Style::Style?
+      attr_reader legend_position: Symbol?
+      attr_reader hidden_legend_constraints: Array[Layout::Constraint]
+
+      include CoerceableWidget
+
+      def self.coerce_args: (chart_options first, ?chart_options kwargs) -> Chart
+                          | (nil first, chart_options kwargs) -> Chart
+
+      def self.new: (datasets: Array[Dataset], x_axis: Axis, y_axis: Axis, ?block: Widgets::Block?, ?style: Style::Style?, ?legend_position: Symbol?, ?hidden_legend_constraints: Array[Layout::Constraint]) -> Chart
+      def initialize: (datasets: Array[Dataset], x_axis: Axis, y_axis: Axis, ?block: Widgets::Block?, ?style: Style::Style?, ?legend_position: Symbol?, ?hidden_legend_constraints: Array[Layout::Constraint]) -> void
+    end
+
+    class Dataset < Data
+      attr_reader name: String | Symbol
+      attr_reader data: Array[[Float, Float]]
+      attr_reader style: Style::Style?
+      attr_reader marker: Symbol
+      attr_reader graph_type: Symbol
+
+      include CoerceableWidget
+
+      def self.coerce_args: (dataset_options first, ?dataset_options kwargs) -> Dataset
+                          | (nil first, dataset_options kwargs) -> Dataset
+
+      def self.new: (name: String | Symbol, data: Array[[_ToF, _ToF]], ?style: Style::Style?, ?marker: Symbol, ?graph_type: Symbol) -> Dataset
+      def initialize: (name: String | Symbol, data: Array[[_ToF, _ToF]], ?style: Style::Style?, ?marker: Symbol, ?graph_type: Symbol) -> void
+    end
+
+    class Axis < Data
+      attr_reader title: String
+      attr_reader bounds: [Float, Float]
+      attr_reader labels: Array[String]
+      attr_reader style: Style::Style?
+      attr_reader labels_alignment: Symbol?
+
+      include CoerceableWidget
+
+      def self.coerce_args: (axis_options first, ?axis_options kwargs) -> Axis
+                          | (nil first, axis_options kwargs) -> Axis
+
+      def self.new: (?title: String, ?bounds: [_ToF, _ToF], ?labels: Array[String], ?style: Style::Style?, ?labels_alignment: Symbol?) -> Axis
+      def initialize: (?title: String, ?bounds: [_ToF, _ToF], ?labels: Array[String], ?style: Style::Style?, ?labels_alignment: Symbol?) -> void
+    end
+  end
+end

data/sig/ratatui_ruby/widgets/coerceable_widget.rbs

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+module RatatuiRuby
+  module Widgets
+    # Mixin that provides DWIM hash coercion for widget classes.
+    #
+    # When users call `tui.table(hash)` instead of `tui.table(**hash)`,
+    # this mixin detects the bare hash and automatically splats it.
+    #
+    # This module is designed to be included in Data subclasses.
+    # The coerce_args method is typed per-widget rather than generically
+    # here because RBS cannot express "self.new" in module ClassMethods.
+    module CoerceableWidget
+      KNOWN_KEYS: Array[Symbol]
+
+      # Class methods extended onto widget classes.
+      # Each widget class provides its own typed coerce_args signature.
+      module ClassMethods
+      end
+
+      # Called when the module is included; extends ClassMethods.
+      def self.included: (Class base) -> void
+    end
+  end
+end

data/sig/ratatui_ruby/widgets/gauge.rbs

@@ -0,0 +1,44 @@
+# 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 Widgets
+    # Options hash type for Gauge constructor arguments.
+    type gauge_options = {
+      ?ratio: _ToF?,
+      ?percent: _ToF?,
+      ?label: String | Text::Span | nil,
+      ?style: Style::Style?,
+      ?gauge_style: Style::Style?,
+      ?block: Widgets::Block?,
+      ?use_unicode: bool
+    }
+
+    class Gauge < Data
+      attr_reader ratio: Float
+      attr_reader label: (String | Text::Span)?
+      attr_reader style: Style::Style?
+      attr_reader gauge_style: Style::Style?
+      attr_reader block: Widgets::Block?
+      attr_reader use_unicode: bool
+
+      include CoerceableWidget
+
+      def self.coerce_args: (gauge_options first, ?gauge_options kwargs) -> Gauge
+                          | (nil first, gauge_options kwargs) -> Gauge
+
+      def self.new: (?ratio: _ToF?, ?percent: _ToF?, ?label: String | Text::Span | nil, ?style: Style::Style?, ?gauge_style: Style::Style?, ?block: Widgets::Block?, ?use_unicode: bool) -> Gauge
+      def initialize: (?ratio: _ToF?, ?percent: _ToF?, ?label: String | Text::Span | nil, ?style: Style::Style?, ?gauge_style: Style::Style?, ?block: Widgets::Block?, ?use_unicode: bool) -> void
+
+      def filled?: () -> bool
+      def complete?: () -> bool
+      def percent: () -> Integer
+    end
+  end
+end

data/sig/ratatui_ruby/widgets/line_gauge.rbs

@@ -0,0 +1,48 @@
+# 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 Widgets
+    # Options hash type for LineGauge constructor arguments.
+    type line_gauge_options = {
+      ?ratio: _ToF?,
+      ?percent: _ToF?,
+      ?label: String | Text::Span | nil,
+      ?style: Style::Style?,
+      ?filled_style: Style::Style?,
+      ?unfilled_style: Style::Style?,
+      ?block: Widgets::Block?,
+      ?filled_symbol: String,
+      ?unfilled_symbol: String
+    }
+
+    class LineGauge < Data
+      attr_reader ratio: Float
+      attr_reader label: (String | Text::Span)?
+      attr_reader style: Style::Style?
+      attr_reader filled_style: Style::Style?
+      attr_reader unfilled_style: Style::Style?
+      attr_reader block: Widgets::Block?
+      attr_reader filled_symbol: String
+      attr_reader unfilled_symbol: String
+
+      include CoerceableWidget
+
+      def self.coerce_args: (line_gauge_options first, ?line_gauge_options kwargs) -> LineGauge
+                          | (nil first, line_gauge_options kwargs) -> LineGauge
+
+      def self.new: (?ratio: _ToF?, ?percent: _ToF?, ?label: String | Text::Span | nil, ?style: Style::Style?, ?filled_style: Style::Style?, ?unfilled_style: Style::Style?, ?block: Widgets::Block?, ?filled_symbol: String, ?unfilled_symbol: String) -> LineGauge
+      def initialize: (?ratio: _ToF?, ?percent: _ToF?, ?label: String | Text::Span | nil, ?style: Style::Style?, ?filled_style: Style::Style?, ?unfilled_style: Style::Style?, ?block: Widgets::Block?, ?filled_symbol: String, ?unfilled_symbol: String) -> void
+
+      def filled?: () -> bool
+      def complete?: () -> bool
+      def percent: () -> Integer
+    end
+  end
+end