ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/tui/state_factories.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class TUI
+    # State object factory methods for Session.
+    #
+    # Provides convenient access to stateful widget state objects
+    # (ListState, TableState, ScrollbarState) without fully
+    # qualifying the class names.
+    module StateFactories
+      # Creates a ListState.
+      # @return [ListState]
+      def list_state(...)
+        ListState.new(...)
+      end
+
+      # Creates a TableState.
+      # @return [TableState]
+      def table_state(...)
+        TableState.new(...)
+      end
+
+      # Creates a ScrollbarState.
+      # @return [ScrollbarState]
+      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/style_factories.rb

@@ -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
+  class TUI
+    # Style factory methods for Session.
+    #
+    # Provides convenient access to Style::Style without fully
+    # qualifying the class name.
+    module StyleFactories
+      # Creates a Style::Style.
+      # @return [Style::Style]
+      def style(...)
+        Style::Style.new(...)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tui/text_factories.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class TUI
+    # Text factory methods for Session.
+    #
+    # Provides convenient access to Text::Span and Text::Line
+    # without fully qualifying the class names.
+    module TextFactories
+      # Creates a Text::Span.
+      # @return [Text::Span]
+      def text_span(...)
+        Text::Span.new(...)
+      end
+
+      # Creates a Text::Span (alias).
+      # @return [Text::Span]
+      def span(...)
+        Text::Span.new(...)
+      end
+
+      # Creates a Text::Line.
+      # @return [Text::Line]
+      def text_line(...)
+        Text::Line.new(...)
+      end
+
+      # Creates a Text::Line (alias).
+      # @return [Text::Line]
+      def line(...)
+        Text::Line.new(...)
+      end
+
+      # Calculates the display width of a string.
+      # @return [Integer]
+      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

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class TUI
+    # Widget factory methods for Session.
+    #
+    # 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(first = nil, **kwargs)
+        Widgets::Block.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Paragraph.
+      # @return [Widgets::Paragraph]
+      def paragraph(first = nil, **kwargs)
+        Widgets::Paragraph.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::List.
+      # @return [Widgets::List]
+      def list(first = nil, **kwargs)
+        Widgets::List.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::ListItem.
+      # @return [Widgets::ListItem]
+      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(first = nil, **kwargs)
+        Widgets::Table.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Row (for Table rows).
+      # @return [Widgets::Row]
+      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(first = nil, **kwargs)
+        Widgets::Row.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Cell (for Table cells).
+      # @return [Widgets::Cell]
+      def table_cell(first = nil, **kwargs)
+        Widgets::Cell.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Tabs.
+      # @return [Widgets::Tabs]
+      def tabs(first = nil, **kwargs)
+        Widgets::Tabs.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Gauge.
+      # @return [Widgets::Gauge]
+      def gauge(first = nil, **kwargs)
+        Widgets::Gauge.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::LineGauge.
+      # @return [Widgets::LineGauge]
+      def line_gauge(first = nil, **kwargs)
+        Widgets::LineGauge.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Sparkline.
+      # @return [Widgets::Sparkline]
+      def sparkline(first = nil, **kwargs)
+        Widgets::Sparkline.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::BarChart.
+      # @return [Widgets::BarChart]
+      def bar_chart(first = nil, **kwargs)
+        Widgets::BarChart.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::BarChart::Bar.
+      # @return [Widgets::BarChart::Bar]
+      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(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(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(first = nil, **kwargs)
+        Widgets::BarChart::BarGroup.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Chart.
+      # @return [Widgets::Chart]
+      def chart(first = nil, **kwargs)
+        Widgets::Chart.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Dataset.
+      # @return [Widgets::Dataset]
+      def dataset(first = nil, **kwargs)
+        Widgets::Dataset.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Axis.
+      # @return [Widgets::Axis]
+      def axis(first = nil, **kwargs)
+        Widgets::Axis.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Scrollbar.
+      # @return [Widgets::Scrollbar]
+      def scrollbar(first = nil, **kwargs)
+        Widgets::Scrollbar.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Calendar.
+      # @return [Widgets::Calendar]
+      def calendar(first = nil, **kwargs)
+        Widgets::Calendar.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Canvas.
+      # @return [Widgets::Canvas]
+      def canvas(first = nil, **kwargs)
+        Widgets::Canvas.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Clear.
+      # @return [Widgets::Clear]
+      def clear(first = nil, **kwargs)
+        Widgets::Clear.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Cursor.
+      # @return [Widgets::Cursor]
+      def cursor(first = nil, **kwargs)
+        Widgets::Cursor.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Overlay.
+      # @return [Widgets::Overlay]
+      def overlay(first = nil, **kwargs)
+        Widgets::Overlay.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::Center.
+      # @return [Widgets::Center]
+      def center(first = nil, **kwargs)
+        Widgets::Center.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::RatatuiLogo.
+      # @return [Widgets::RatatuiLogo]
+      def ratatui_logo(first = nil, **kwargs)
+        Widgets::RatatuiLogo.coerce_args(first, kwargs)
+      end
+
+      # Creates a Widgets::RatatuiMascot.
+      # @return [Widgets::RatatuiMascot]
+      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(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
+end

data/lib/ratatui_ruby/tui.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require_relative "tui/core"
+require_relative "tui/layout_factories"
+require_relative "tui/style_factories"
+require_relative "tui/widget_factories"
+require_relative "tui/text_factories"
+require_relative "tui/state_factories"
+require_relative "tui/canvas_factories"
+require_relative "tui/buffer_factories"
+
+module RatatuiRuby
+  # Manages the terminal lifecycle and provides a concise API for the render loop.
+  #
+  # Writing a TUI loop involves repetitive boilerplate. You constantly instantiate widgets
+  # (<tt>RatatuiRuby::Widgets::Paragraph.new</tt>) and call global methods (<tt>RatatuiRuby.draw</tt>).
+  # This is verbose and hard to read.
+  #
+  # The Session object simplifies this. It acts as a factory and a facade. It provides short helper
+  # methods for every widget and delegates core commands to the main module.
+  #
+  # 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,
+  # poll_event) and is intentionally *not* Ractor-shareable. Caching it in
+  # instance variables (<tt>@tui = tui</tt>) during your application's run loop
+  # is fine. However, do not include it in immutable Models/Messages or
+  # pass it to other Ractors.
+  #
+  # == Included Mixins
+  #
+  # [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. (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.
+  # [BufferFactories] Buffer inspection: cell.
+  #
+  # === Examples
+  #
+  # ==== Basic Usage (Recommended)
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   RatatuiRuby.run do |tui|
+  #     loop do
+  #       tui.draw \
+  #         tui.paragraph \
+  #             text: "Hello, Ratatui! Press 'q' to quit.",
+  #             alignment: :center,
+  #             block: tui.block(
+  #               title: "My Ruby TUI App",
+  #               borders: [:all],
+  #               border_style: { fg: \"cyan\" }
+  #             )
+  #       event = tui.poll_event
+  #       break if event == "q" || event == :ctrl_c
+  #     end
+  #   end
+  #--
+  # SPDX-SnippetEnd
+  #++
+  class TUI
+    include Core
+    include LayoutFactories
+    include StyleFactories
+    include WidgetFactories
+    include TextFactories
+    include StateFactories
+    include CanvasFactories
+    include BufferFactories
+  end
+end

data/lib/ratatui_ruby/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # The version of the ratatui_ruby gem.
+  # See https://semver.org/spec/v2.0.0.html
+  VERSION = "1.4.0"
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    class BarChart
+      # A bar in a grouped bar chart.
+      #
+      # === Examples
+      #
+      #   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).
+
+        ##
+        # :attr_reader: label
+        # The label of the bar (optional String, Text::Span, or Text::Line for rich styling).
+
+        ##
+        # :attr_reader: style
+        # The style of the bar (optional Style).
+
+        ##
+        # :attr_reader: value_style
+        # The style of the value (optional Style).
+
+        ##
+        # :attr_reader: text_value
+        # The text to display as the value (optional String, Text::Span, or Text::Line for rich styling).
+
+        def initialize(value:, label: nil, style: nil, value_style: nil, text_value: nil)
+          super(
+            value: Integer(value),
+            label:,
+            style:,
+            value_style:,
+            text_value:
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    class BarChart
+      # A group of bars in a grouped bar chart.
+      #
+      # === Examples
+      #
+      #   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).
+
+        ##
+        # :attr_reader: bars
+        # The bars in the group (Array of Bar).
+      end
+    end
+  end
+end