ratatui_ruby 0.9.0 → 0.10.0

data/lib/ratatui_ruby/tui/state_factories.rb

@@ -30,6 +30,48 @@ module RatatuiRuby
       def scrollbar_state(...)
         ScrollbarState.new(...)
       end
+
+      # =====================================
+      # State Dispatcher (TIMTOWTDI)
+      # =====================================
+
+      # Creates a state object by type symbol.
+      #
+      # Stateful widgets need companion state objects. When building dynamic UIs,
+      # the state type must be determined at runtime.
+      #
+      # This dispatcher routes state creation through a single entry point.
+      # Pass the type as a symbol and the remaining parameters.
+      #
+      # Use it for generic list/table factories or config-driven components.
+      #
+      # Also available as: <tt>tui.list_state</tt>, <tt>tui.table_state</tt>
+      #
+      # === Examples
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   tui.state(:list, nil)           # => ListState with no selection
+      #   tui.state(:table, 0)            # => TableState with row 0 selected
+      #   tui.state(:scrollbar, 100)      # => ScrollbarState with 100 content length
+      #--
+      # SPDX-SnippetEnd
+      #++
+      #
+      # @param type [Symbol] State type: :list, :table, :scrollbar
+      # @return [ListState, TableState, ScrollbarState]
+      def state(type, arg = nil)
+        case type
+        when :list then list_state(arg)
+        when :table then table_state(arg)
+        when :scrollbar then scrollbar_state(arg || 0)
+        else
+          raise ArgumentError, "Unknown state type: :#{type}. Valid types: :list, :table, :scrollbar"
+        end
+      end
     end
   end
 end

data/lib/ratatui_ruby/tui/text_factories.rb

@@ -41,6 +41,46 @@ module RatatuiRuby
       def text_width(string)
         Text.width(string)
       end
+
+      # =====================================
+      # Text Dispatcher (TIMTOWTDI)
+      # =====================================
+
+      # Creates a text element by type symbol.
+      #
+      # Building text programmatically requires knowing which method to call.
+      # When the text type comes from config or user input, you need a dispatcher.
+      #
+      # This method routes text creation through a single entry point.
+      # Pass the type as a symbol and the remaining parameters as kwargs.
+      #
+      # Use it for dynamic text generation or config-driven rendering.
+      #
+      # Also available as: <tt>tui.span</tt>, <tt>tui.text_span</tt>
+      #
+      # === Examples
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   tui.text(:span, content: "Hello", style: Style.with(fg: :blue))
+      #   tui.text(:line, spans: [tui.span(content: "World")])
+      #--
+      # SPDX-SnippetEnd
+      #++
+      #
+      # @param type [Symbol] Text type: :span, :line
+      # @return [Text::Span, Text::Line]
+      def text(type, **)
+        case type
+        when :span then text_span(**)
+        when :line then text_line(**)
+        else
+          raise ArgumentError, "Unknown text type: #{type.inspect}. Valid types: :span, :line"
+        end
+      end
     end
   end
 end

data/lib/ratatui_ruby/tui/widget_factories.rb

@@ -12,185 +12,260 @@ module RatatuiRuby
     # Provides convenient access to all Widgets::* classes without
     # fully qualifying the class names. This is the largest mixin,
     # covering all renderable UI components.
+    #
+    # All factories use DWIM hash coercion: both `tui.table(hash)` and
+    # `tui.table(**hash)` work correctly.
     module WidgetFactories
       # Creates a Widgets::Block.
       # @return [Widgets::Block]
-      def block(...)
-        Widgets::Block.new(...)
+      def block(first = nil, **kwargs)
+        Widgets::Block.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Paragraph.
       # @return [Widgets::Paragraph]
-      def paragraph(...)
-        Widgets::Paragraph.new(...)
+      def paragraph(first = nil, **kwargs)
+        Widgets::Paragraph.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::List.
       # @return [Widgets::List]
-      def list(...)
-        Widgets::List.new(...)
+      def list(first = nil, **kwargs)
+        Widgets::List.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::ListItem.
       # @return [Widgets::ListItem]
-      def list_item(...)
-        Widgets::ListItem.new(...)
+      def list_item(first = nil, **kwargs)
+        Widgets::ListItem.coerce_args(first, kwargs)
       end
 
+      # Creates a Widgets::ListItem (DWIM alias).
+      #
+      # Terse alias for list_item. Clear in list context.
+      #
+      # @return [Widgets::ListItem]
+      alias item list_item
+
       # Creates a Widgets::Table.
       # @return [Widgets::Table]
-      def table(...)
-        Widgets::Table.new(...)
+      def table(first = nil, **kwargs)
+        Widgets::Table.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Row (for Table rows).
       # @return [Widgets::Row]
-      def row(...)
-        Widgets::Row.new(...)
+      def row(first = nil, **kwargs)
+        Widgets::Row.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Row (alias for table row).
       # @return [Widgets::Row]
-      def table_row(...)
-        Widgets::Row.new(...)
+      def table_row(first = nil, **kwargs)
+        Widgets::Row.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Cell (for Table cells).
       # @return [Widgets::Cell]
-      def table_cell(...)
-        Widgets::Cell.new(...)
+      def table_cell(first = nil, **kwargs)
+        Widgets::Cell.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Tabs.
       # @return [Widgets::Tabs]
-      def tabs(...)
-        Widgets::Tabs.new(...)
+      def tabs(first = nil, **kwargs)
+        Widgets::Tabs.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Gauge.
       # @return [Widgets::Gauge]
-      def gauge(...)
-        Widgets::Gauge.new(...)
+      def gauge(first = nil, **kwargs)
+        Widgets::Gauge.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::LineGauge.
       # @return [Widgets::LineGauge]
-      def line_gauge(...)
-        Widgets::LineGauge.new(...)
+      def line_gauge(first = nil, **kwargs)
+        Widgets::LineGauge.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Sparkline.
       # @return [Widgets::Sparkline]
-      def sparkline(...)
-        Widgets::Sparkline.new(...)
+      def sparkline(first = nil, **kwargs)
+        Widgets::Sparkline.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::BarChart.
       # @return [Widgets::BarChart]
-      def bar_chart(...)
-        Widgets::BarChart.new(...)
+      def bar_chart(first = nil, **kwargs)
+        Widgets::BarChart.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::BarChart::Bar.
       # @return [Widgets::BarChart::Bar]
-      def bar(...)
-        Widgets::BarChart::Bar.new(...)
+      def bar(first = nil, **kwargs)
+        Widgets::BarChart::Bar.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::BarChart::BarGroup.
       # @return [Widgets::BarChart::BarGroup]
-      def bar_group(...)
-        Widgets::BarChart::BarGroup.new(...)
+      def bar_group(first = nil, **kwargs)
+        Widgets::BarChart::BarGroup.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::BarChart::Bar (alias).
       # @return [Widgets::BarChart::Bar]
-      def bar_chart_bar(...)
-        Widgets::BarChart::Bar.new(...)
+      def bar_chart_bar(first = nil, **kwargs)
+        Widgets::BarChart::Bar.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::BarChart::BarGroup (alias).
       # @return [Widgets::BarChart::BarGroup]
-      def bar_chart_bar_group(...)
-        Widgets::BarChart::BarGroup.new(...)
+      def bar_chart_bar_group(first = nil, **kwargs)
+        Widgets::BarChart::BarGroup.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Chart.
       # @return [Widgets::Chart]
-      def chart(...)
-        Widgets::Chart.new(...)
+      def chart(first = nil, **kwargs)
+        Widgets::Chart.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Dataset.
       # @return [Widgets::Dataset]
-      def dataset(...)
-        Widgets::Dataset.new(...)
+      def dataset(first = nil, **kwargs)
+        Widgets::Dataset.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Axis.
       # @return [Widgets::Axis]
-      def axis(...)
-        Widgets::Axis.new(...)
+      def axis(first = nil, **kwargs)
+        Widgets::Axis.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Scrollbar.
       # @return [Widgets::Scrollbar]
-      def scrollbar(...)
-        Widgets::Scrollbar.new(...)
+      def scrollbar(first = nil, **kwargs)
+        Widgets::Scrollbar.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Calendar.
       # @return [Widgets::Calendar]
-      def calendar(...)
-        Widgets::Calendar.new(...)
+      def calendar(first = nil, **kwargs)
+        Widgets::Calendar.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Canvas.
       # @return [Widgets::Canvas]
-      def canvas(...)
-        Widgets::Canvas.new(...)
+      def canvas(first = nil, **kwargs)
+        Widgets::Canvas.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Clear.
       # @return [Widgets::Clear]
-      def clear(...)
-        Widgets::Clear.new(...)
+      def clear(first = nil, **kwargs)
+        Widgets::Clear.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Cursor.
       # @return [Widgets::Cursor]
-      def cursor(...)
-        Widgets::Cursor.new(...)
+      def cursor(first = nil, **kwargs)
+        Widgets::Cursor.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Overlay.
       # @return [Widgets::Overlay]
-      def overlay(...)
-        Widgets::Overlay.new(...)
+      def overlay(first = nil, **kwargs)
+        Widgets::Overlay.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Center.
       # @return [Widgets::Center]
-      def center(...)
-        Widgets::Center.new(...)
+      def center(first = nil, **kwargs)
+        Widgets::Center.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::RatatuiLogo.
       # @return [Widgets::RatatuiLogo]
-      def ratatui_logo(...)
-        Widgets::RatatuiLogo.new(...)
+      def ratatui_logo(first = nil, **kwargs)
+        Widgets::RatatuiLogo.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::RatatuiMascot.
       # @return [Widgets::RatatuiMascot]
-      def ratatui_mascot(...)
-        Widgets::RatatuiMascot.new(...)
+      def ratatui_mascot(first = nil, **kwargs)
+        Widgets::RatatuiMascot.coerce_args(first, kwargs)
       end
 
       # Creates a Widgets::Shape::Label.
       # @return [Widgets::Shape::Label]
-      def shape_label(...)
-        Widgets::Shape::Label.new(...)
+      def shape_label(first = nil, **kwargs)
+        Widgets::Shape::Label.coerce_args(first, kwargs)
+      end
+
+      # =====================================
+      # Widget Dispatcher (TIMTOWTDI)
+      # =====================================
+
+      # Creates a widget by type symbol.
+      #
+      # Plugin systems and config-driven UIs need to instantiate widgets by name.
+      # Without a dispatcher, you need tedious case statements or reflection.
+      #
+      # This method routes widget creation through a single entry point.
+      # Pass the type as a symbol and the remaining parameters as kwargs.
+      #
+      # Use it for dynamic UI generation, dashboard builders, or plugin architectures.
+      #
+      # Also available as: <tt>tui.paragraph</tt>, <tt>tui.list</tt>, etc.
+      #
+      # === Examples
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   tui.widget(:paragraph, text: "Hello World")
+      #   tui.widget(:list, items: %w[One Two Three])
+      #
+      #   # Config-driven widget creation
+      #   widgets_config.each do |cfg|
+      #     frame.render_widget(tui.widget(cfg[:type], **cfg[:options]), area)
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      #
+      # @param type [Symbol] Widget type (see error message for full list)
+      # @return [Widgets::*]
+      def widget(type, first = nil, **)
+        case type
+        when :block then block(first, **)
+        when :paragraph then paragraph(first, **)
+        when :list then list(first, **)
+        when :table then table(first, **)
+        when :tabs then tabs(first, **)
+        when :gauge then gauge(first, **)
+        when :line_gauge then line_gauge(first, **)
+        when :sparkline then sparkline(first, **)
+        when :bar_chart then bar_chart(first, **)
+        when :chart then chart(first, **)
+        when :scrollbar then scrollbar(first, **)
+        when :calendar then calendar(first, **)
+        when :canvas then canvas(first, **)
+        when :clear then clear(first, **)
+        when :cursor then cursor(first, **)
+        when :overlay then overlay(first, **)
+        when :center then center(first, **)
+        when :ratatui_logo then ratatui_logo(first, **)
+        when :ratatui_mascot then ratatui_mascot(first, **)
+        else
+          raise ArgumentError, "Unknown widget type: #{type.inspect}. " \
+            "Valid types: :block, :paragraph, :list, :table, :tabs, :gauge, :line_gauge, " \
+            ":sparkline, :bar_chart, :chart, :scrollbar, :calendar, :canvas, :clear, " \
+            ":cursor, :overlay, :center, :ratatui_logo, :ratatui_mascot"
+        end
       end
     end
   end

data/lib/ratatui_ruby/tui.rb

@@ -26,6 +26,27 @@ module RatatuiRuby
   #
   # Use it within <tt>RatatuiRuby.run</tt> to build your interface cleanly.
   #
+  # == "Do What I Mean" (DWIM) Coercion
+  #
+  # The TUI factories add a *DWIM argument coercion layer* that the underlying
+  # Widget classes don't have. This means:
+  #
+  # - <tt>tui.table(rows: [...])</tt> coerces types, normalizes arrays, etc.
+  # - <tt>RatatuiRuby::Widgets::Table.new(rows: [...])</tt> passes arguments directly
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   to Rust without coercion — invalid types will raise <tt>TypeError</tt>.
+  #
+  #--
+  # SPDX-SnippetEnd
+  #++
+  # If you bypass the factories and call <tt>Widgets::Table.new</tt> directly,
+  # you're responsible for providing correctly-typed arguments. This is useful
+  # for debugging (to trigger real Rust TypeErrors) or performance-critical code.
+  #
   # == Thread/Ractor Safety
   #
   # Session is an *I/O handle*, not a data object. It has side effects (draw,
@@ -39,7 +60,7 @@ module RatatuiRuby
   # [Core] Terminal operations: draw, poll_event, get_cell_at, draw_cell.
   # [LayoutFactories] Layout helpers: rect, constraint_*, layout, layout_split.
   # [StyleFactories] Style helpers: style.
-  # [WidgetFactories] Widget creation: block, paragraph, list, table, etc.
+  # [WidgetFactories] Widget creation: block, paragraph, list, table, etc. (DWIM coercion)
   # [TextFactories] Text helpers: span, line, text_width.
   # [StateFactories] State objects: list_state, table_state, scrollbar_state.
   # [CanvasFactories] Canvas shapes: shape_map, shape_line, shape_point, etc.

data/lib/ratatui_ruby/version.rb

@@ -8,5 +8,5 @@
 module RatatuiRuby
   # The version of the ratatui_ruby gem.
   # See https://semver.org/spec/v2.0.0.html
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/lib/ratatui_ruby/widgets/bar_chart/bar.rb

@@ -14,6 +14,8 @@ module RatatuiRuby
       #
       #   BarChart::Bar.new(value: 10, style: Style.new(fg: :red), label: "A")
       class Bar < Data.define(:value, :label, :style, :value_style, :text_value)
+        include CoerceableWidget
+
         ##
         # :attr_reader: value
         # The value of the bar (Integer).

data/lib/ratatui_ruby/widgets/bar_chart/bar_group.rb

@@ -14,6 +14,8 @@ module RatatuiRuby
       #
       #   BarChart::BarGroup.new(label: "Q1", bars: [BarChart::Bar.new(value: 10), BarChart::Bar.new(value: 20)])
       class BarGroup < Data.define(:label, :bars)
+        include CoerceableWidget
+
         ##
         # :attr_reader: label
         # The label of the group (String).

data/lib/ratatui_ruby/widgets/bar_chart.rb

@@ -41,6 +41,8 @@ module RatatuiRuby
     # SPDX-SnippetEnd
     #++
     class BarChart < Data.define(:data, :bar_width, :bar_gap, :group_gap, :max, :style, :block, :direction, :label_style, :value_style, :bar_set)
+      include CoerceableWidget
+
       ##
       ##
       ##
@@ -215,19 +217,25 @@ module RatatuiRuby
       # SPDX-SnippetEnd
       #++
       def initialize(data:, bar_width: 3, bar_gap: 1, group_gap: 0, max: nil, style: nil, block: nil, direction: :vertical, label_style: nil, value_style: nil, bar_set: nil)
-        if bar_set && !bar_set.is_a?(Symbol)
-          if bar_set.is_a?(Array) && bar_set.size == 9
-            # Convert Array to Hash using BAR_KEYS order
-            bar_set = BAR_KEYS.zip(bar_set).to_h
-          else
-            bar_set = bar_set.dup
-            # Normalize numeric keys (0-8) to symbolic keys
-            BAR_KEYS.each_with_index do |key, i|
-              if (val = bar_set.delete(i) || bar_set.delete(i.to_s))
-                bar_set[key] = val
-              end
-            end
-          end
+        # Normalize bar_set to Hash[Symbol, String] if provided as Array or Hash
+        bar_set = case bar_set
+                  when Symbol, nil
+                    bar_set
+                  when Array
+                    # Convert Array to Hash using BAR_KEYS order
+                    BAR_KEYS.zip(bar_set).to_h
+                  when Hash
+                    # @type var raw_hash: Hash[untyped, untyped]
+                    raw_hash = bar_set.dup
+                    normalized = {} #: Hash[Symbol, String]
+                    # Normalize numeric keys (0-8) to symbolic keys
+                    BAR_KEYS.each_with_index do |key, i|
+                      val = raw_hash.delete(i) || raw_hash.delete(i.to_s) || raw_hash.delete(key)
+                      normalized[key] = val.to_s if val
+                    end
+                    normalized
+                  else
+                    bar_set
         end
 
         # Normalize data to Array of BarGroup
@@ -248,12 +256,13 @@ module RatatuiRuby
           elsif data.first.is_a?(BarGroup)
             data
           elsif data.first.is_a?(Array)
-            # Tuples
+            # Tuples - use type assertion for Steep
             if direction == :horizontal
               bars = data.map do |item|
-                label = item[0].to_s
-                value = item[1]
-                style = item[2]
+                tuple = item #: Array[untyped]
+                label = tuple[0].to_s
+                value = tuple[1]
+                style = tuple[2]
 
                 bar = Bar.new(value:, label:)
                 bar = bar.with(style:) if style
@@ -262,9 +271,10 @@ module RatatuiRuby
               [BarGroup.new(label: "", bars:)]
             else
               data.map do |item|
-                label = item[0].to_s
-                value = item[1]
-                style = item[2]
+                tuple = item #: Array[untyped]
+                label = tuple[0].to_s
+                value = tuple[1]
+                style = tuple[2]
 
                 bar = Bar.new(value:)
                 bar = bar.with(style:) if style

data/lib/ratatui_ruby/widgets/block.rb

@@ -23,6 +23,8 @@ module RatatuiRuby
     #
     #   ruby examples/widget_box/app.rb
     class Block < Data.define(:title, :titles, :title_alignment, :title_style, :borders, :border_style, :border_type, :border_set, :style, :padding, :children)
+      include CoerceableWidget
+
       ##
       # :attr_reader: title
       # The main title displayed on the top border.
@@ -170,8 +172,8 @@ module RatatuiRuby
         if border_set
           border_set = border_set.dup
           %i[top_left top_right bottom_left bottom_right vertical_left vertical_right horizontal_top horizontal_bottom].each do |long_key|
-            short_key = long_key.to_s.split("_").map { |s| s[0] }.join
-            if (val = border_set.delete(short_key.to_sym) || border_set.delete(short_key))
+            short_key = long_key.to_s.split("_").map { |s| s[0] }.join.to_sym
+            if (val = border_set.delete(short_key))
               border_set[long_key] = val
             end
           end
@@ -237,12 +239,18 @@ module RatatuiRuby
         top_border = has_border.call(:top) ? 1 : 0
         bottom_border = has_border.call(:bottom) ? 1 : 0
 
-        # Calculate padding offsets
-        if padding.is_a?(Array)
+        # Calculate padding offsets - ensure all are Integer
+        pad_left, pad_right, pad_top, pad_bottom = if padding.is_a?(Array)
           # [left, right, top, bottom]
-          pad_left, pad_right, pad_top, pad_bottom = padding
+          [
+            Integer(padding[0] || 0),
+            Integer(padding[1] || 0),
+            Integer(padding[2] || 0),
+            Integer(padding[3] || 0),
+          ]
         else
-          pad_left = pad_right = pad_top = pad_bottom = padding
+          p = Integer(padding)
+          [p, p, p, p]
         end
 
         # Compute inner area

data/lib/ratatui_ruby/widgets/calendar.rb

@@ -24,6 +24,8 @@ module RatatuiRuby
     #
     #   ruby examples/widget_calendar/app.rb
     class Calendar < Data.define(:year, :month, :events, :default_style, :header_style, :block, :show_weekdays_header, :show_surrounding, :show_month_header)
+      include CoerceableWidget
+
       ##
       # :attr_reader: year
       # The year to display (Integer).