ratatui_ruby 0.4.0 → 0.6.0

data/lib/ratatui_ruby/session/autodoc.rb

@@ -0,0 +1,482 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# !!! DO NOT EDIT THIS FILE BY HAND !!!
+# This file is automatically generated by `rake autodoc:rdoc:session`.
+# Any changes will be overwritten.
+
+module RatatuiRuby
+  class Session
+    # == RatatuiRuby Delegates
+    #
+    # :method: _paragraph_line_count
+    # :call-seq: _paragraph_line_count(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby._paragraph_line_count.
+    #
+    # :method: _paragraph_line_width
+    # :call-seq: _paragraph_line_width(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby._paragraph_line_width.
+    #
+    # :method: _tabs_width
+    # :call-seq: _tabs_width(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby._tabs_width.
+    #
+    # :method: _text_width
+    # :call-seq: _text_width(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby._text_width.
+    #
+    # :method: clear_events
+    # :call-seq: clear_events(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.clear_events.
+    #
+    # :method: draw
+    # :call-seq: draw(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.draw.
+    #
+    # :method: experimental_warnings
+    # :call-seq: experimental_warnings(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.experimental_warnings.
+    #
+    # :method: experimental_warnings=
+    # :call-seq: experimental_warnings=(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.experimental_warnings=.
+    #
+    # :method: get_buffer_content
+    # :call-seq: get_buffer_content(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.get_buffer_content.
+    #
+    # :method: get_cell_at
+    # :call-seq: get_cell_at(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.get_cell_at.
+    #
+    # :method: get_cursor_position
+    # :call-seq: get_cursor_position(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.get_cursor_position.
+    #
+    # :method: init_terminal
+    # :call-seq: init_terminal(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.init_terminal.
+    #
+    # :method: init_test_terminal
+    # :call-seq: init_test_terminal(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.init_test_terminal.
+    #
+    # :method: inject_test_event
+    # :call-seq: inject_test_event(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.inject_test_event.
+    #
+    # :method: poll_event
+    # :call-seq: poll_event(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.poll_event.
+    #
+    # :method: resize_terminal
+    # :call-seq: resize_terminal(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.resize_terminal.
+    #
+    # :method: restore_terminal
+    # :call-seq: restore_terminal(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.restore_terminal.
+    #
+    # :method: run
+    # :call-seq: run(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.run.
+    #
+    # :method: warn_experimental_feature
+    # :call-seq: warn_experimental_feature(*args, **kwargs, &block)
+    #
+    # Delegates to RatatuiRuby.warn_experimental_feature.
+    #
+    # == Widget Factories
+    #
+    # :method: axis
+    # :call-seq: axis(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Axis.new.
+    #
+    # :method: bar_chart
+    # :call-seq: bar_chart(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::BarChart.new.
+    #
+    # :method: bar_chart_bar
+    # :call-seq: bar_chart_bar(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::BarChart::Bar.new.
+    #
+    # :method: bar_chart_bar_group
+    # :call-seq: bar_chart_bar_group(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::BarChart::BarGroup.new.
+    #
+    # :method: block
+    # :call-seq: block(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Block.new.
+    #
+    # :method: calendar
+    # :call-seq: calendar(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Calendar.new.
+    #
+    # :method: canvas
+    # :call-seq: canvas(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Canvas.new.
+    #
+    # :method: cell
+    # :call-seq: cell(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Cell.new.
+    #
+    # :method: cell_char
+    # :call-seq: cell_char(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Cell.char.
+    #
+    # :method: cell_default
+    # :call-seq: cell_default(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Cell.default.
+    #
+    # :method: cell_empty
+    # :call-seq: cell_empty(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Cell.empty.
+    #
+    # :method: cell_symbol
+    # :call-seq: cell_symbol(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Cell.symbol.
+    #
+    # :method: center
+    # :call-seq: center(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Center.new.
+    #
+    # :method: chart
+    # :call-seq: chart(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Chart.new.
+    #
+    # :method: clear
+    # :call-seq: clear(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Clear.new.
+    #
+    # :method: constraint
+    # :call-seq: constraint(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Constraint.new.
+    #
+    # :method: constraint_fill
+    # :call-seq: constraint_fill(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Constraint.fill.
+    #
+    # :method: constraint_length
+    # :call-seq: constraint_length(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Constraint.length.
+    #
+    # :method: constraint_max
+    # :call-seq: constraint_max(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Constraint.max.
+    #
+    # :method: constraint_min
+    # :call-seq: constraint_min(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Constraint.min.
+    #
+    # :method: constraint_percentage
+    # :call-seq: constraint_percentage(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Constraint.percentage.
+    #
+    # :method: constraint_ratio
+    # :call-seq: constraint_ratio(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Constraint.ratio.
+    #
+    # :method: cursor
+    # :call-seq: cursor(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Cursor.new.
+    #
+    # :method: dataset
+    # :call-seq: dataset(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Dataset.new.
+    #
+    # :method: draw_cell
+    # :call-seq: draw_cell(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Draw.cell.
+    #
+    # :method: draw_string
+    # :call-seq: draw_string(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Draw.string.
+    #
+    # :method: draw_cell_cmd
+    # :call-seq: draw_cell_cmd(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Draw::CellCmd.new.
+    #
+    # :method: draw_string_cmd
+    # :call-seq: draw_string_cmd(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Draw::StringCmd.new.
+    #
+    # :method: error
+    # :call-seq: error(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Error.new.
+    #
+    # :method: error_safety
+    # :call-seq: error_safety(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Error::Safety.new.
+    #
+    # :method: error_terminal
+    # :call-seq: error_terminal(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Error::Terminal.new.
+    #
+    # :method: event
+    # :call-seq: event(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Event.new.
+    #
+    # :method: event_focus_gained
+    # :call-seq: event_focus_gained(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Event::FocusGained.new.
+    #
+    # :method: event_focus_lost
+    # :call-seq: event_focus_lost(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Event::FocusLost.new.
+    #
+    # :method: event_key
+    # :call-seq: event_key(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Event::Key.new.
+    #
+    # :method: event_mouse
+    # :call-seq: event_mouse(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Event::Mouse.new.
+    #
+    # :method: event_none
+    # :call-seq: event_none(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Event::None.new.
+    #
+    # :method: event_paste
+    # :call-seq: event_paste(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Event::Paste.new.
+    #
+    # :method: event_resize
+    # :call-seq: event_resize(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Event::Resize.new.
+    #
+    # :method: frame
+    # :call-seq: frame(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Frame.new.
+    #
+    # :method: gauge
+    # :call-seq: gauge(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Gauge.new.
+    #
+    # :method: layout
+    # :call-seq: layout(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Layout.new.
+    #
+    # :method: layout_split
+    # :call-seq: layout_split(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Layout.split.
+    #
+    # :method: line_chart
+    # :call-seq: line_chart(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::LineChart.new.
+    #
+    # :method: line_gauge
+    # :call-seq: line_gauge(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::LineGauge.new.
+    #
+    # :method: list
+    # :call-seq: list(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::List.new.
+    #
+    # :method: list_item
+    # :call-seq: list_item(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::ListItem.new.
+    #
+    # :method: list_state
+    # :call-seq: list_state(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::ListState.new.
+    #
+    # :method: list_state_new
+    # :call-seq: list_state_new(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::ListState.new.
+    #
+    # :method: overlay
+    # :call-seq: overlay(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Overlay.new.
+    #
+    # :method: paragraph
+    # :call-seq: paragraph(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Paragraph.new.
+    #
+    # :method: paragraph_new
+    # :call-seq: paragraph_new(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Paragraph.new.
+    #
+    # :method: ratatui_logo
+    # :call-seq: ratatui_logo(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::RatatuiLogo.new.
+    #
+    # :method: ratatui_mascot
+    # :call-seq: ratatui_mascot(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::RatatuiMascot.new.
+    #
+    # :method: rect
+    # :call-seq: rect(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Rect.new.
+    #
+    # :method: scrollbar
+    # :call-seq: scrollbar(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Scrollbar.new.
+    #
+    # :method: scrollbar_state
+    # :call-seq: scrollbar_state(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::ScrollbarState.new.
+    #
+    # :method: scrollbar_state_new
+    # :call-seq: scrollbar_state_new(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::ScrollbarState.new.
+    #
+    # :method: shape_circle
+    # :call-seq: shape_circle(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Shape::Circle.new.
+    #
+    # :method: shape_label
+    # :call-seq: shape_label(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Shape::Label.new.
+    #
+    # :method: shape_line
+    # :call-seq: shape_line(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Shape::Line.new.
+    #
+    # :method: shape_map
+    # :call-seq: shape_map(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Shape::Map.new.
+    #
+    # :method: shape_point
+    # :call-seq: shape_point(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Shape::Point.new.
+    #
+    # :method: shape_rectangle
+    # :call-seq: shape_rectangle(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Shape::Rectangle.new.
+    #
+    # :method: sparkline
+    # :call-seq: sparkline(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Sparkline.new.
+    #
+    # :method: style
+    # :call-seq: style(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Style.new.
+    #
+    # :method: style_default
+    # :call-seq: style_default(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Style.default.
+    #
+    # :method: table
+    # :call-seq: table(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Table.new.
+    #
+    # :method: table_state
+    # :call-seq: table_state(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::TableState.new.
+    #
+    # :method: table_state_new
+    # :call-seq: table_state_new(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::TableState.new.
+    #
+    # :method: tabs
+    # :call-seq: tabs(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Tabs.new.
+    #
+    # :method: text_width
+    # :call-seq: text_width(*args, **kwargs, &block)
+    #
+    # Helper for RatatuiRuby::Text.width.
+    #
+    # :method: text_line
+    # :call-seq: text_line(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Text::Line.new.
+    #
+    # :method: text_span
+    # :call-seq: text_span(*args, **kwargs, &block)
+    #
+    # Factory for RatatuiRuby::Text::Span.new.
+    #
+  end
+end

data/lib/ratatui_ruby/session.rb

@@ -12,6 +12,14 @@ module RatatuiRuby
   #
   # Use it within <tt>RatatuiRuby.run</tt> to build your interface cleanly.
   #
+  # == 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 TEA Models/Messages or
+  # pass it to other Ractors.
+  #
   # == Available Methods
   #
   # The session dynamically defines factory methods for all RatatuiRuby constants.
@@ -40,6 +48,7 @@ module RatatuiRuby
   #
   # *   <tt>text_span(...)</tt> -> <tt>RatatuiRuby::Text::Span.new(...)</tt>
   # *   <tt>text_line(...)</tt> -> <tt>RatatuiRuby::Text::Line.new(...)</tt>
+  # *   <tt>text_width(string)</tt> -> <tt>RatatuiRuby::Text.width(string)</tt>
   #
   # === Examples
   #
@@ -105,40 +114,63 @@ module RatatuiRuby
       end
     end
 
-    # Wrap classes as snake_case factories
+    # Wrap classes and modules as snake_case factories
     RatatuiRuby.constants.each do |const_name|
       next if const_name == :Buffer
 
-      klass = RatatuiRuby.const_get(const_name)
-      next unless klass.is_a?(Class)
+      const = RatatuiRuby.const_get(const_name)
+      next unless const.is_a?(Module) # Class is a Module, so this catches both
 
-      method_name = const_name.to_s
-                              .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-                              .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-                              .downcase
+      # 1. Top-level factories (for Classes only)
+      #    e.g. RatatuiRuby::Paragraph -> tui.paragraph(...)
+      if const.is_a?(Class)
+        method_name = const_name.to_s
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
 
-      define_method(method_name) do |*args, **kwargs, &block|
-        klass.new(*args, **kwargs, &block)
+        define_method(method_name) do |*args, **kwargs, &block|
+          const.new(*args, **kwargs, &block)
+        end
       end
-    end
 
-    # Wrap nested module classes with prefixed names (e.g., shape_line, text_span)
-    { Shape: :shape, Text: :text }.each do |mod_name, prefix|
-      next unless RatatuiRuby.const_defined?(mod_name)
+      # 2. Singleton Method Helpers (for both Classes and Modules)
+      #    e.g. Layout.split -> layout_split
+      #    e.g. Text.width -> text_width
+      const.singleton_methods(false).each do |class_method|
+        parent_prefix = const_name.to_s
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+
+        session_method_name = "#{parent_prefix}_#{class_method}"
+
+        define_method(session_method_name) do |*args, **kwargs, &block|
+          const.public_send(class_method, *args, **kwargs, &block)
+        end
+      end
+
+      # 3. Nested Class Factories (for both Modules and Classes)
+      #    e.g. RatatuiRuby::Text::Span -> tui.text_span(...)
+      #    e.g. RatatuiRuby::Shape::Line -> tui.shape_line(...)
+      const.constants.each do |child_name|
+        child = const.const_get(child_name)
+        next unless child.is_a?(Class)
+
+        parent_prefix = const_name.to_s
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
 
-      mod = RatatuiRuby.const_get(mod_name)
-      mod.constants.each do |const_name|
-        klass = mod.const_get(const_name)
-        next unless klass.is_a?(Class)
+        child_suffix = child_name.to_s
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
 
-        class_snake = const_name.to_s
-                                .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-                                .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-                                .downcase
-        method_name = "#{prefix}_#{class_snake}"
+        method_name = "#{parent_prefix}_#{child_suffix}"
 
         define_method(method_name) do |*args, **kwargs, &block|
-          klass.new(*args, **kwargs, &block)
+          child.new(*args, **kwargs, &block)
         end
       end
     end

data/lib/ratatui_ruby/table_state.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Mutable state object for Table widgets.
+  #
+  # When using {Frame#render_stateful_widget}, the State object is the
+  # *single source of truth* for selection and scroll offset. Widget
+  # properties (+selected_row+, +selected_column+, +offset+) are *ignored*
+  # in stateful mode.
+  #
+  # == Example
+  #
+  #   @table_state = RatatuiRuby::TableState.new
+  #   @table_state.select(1)        # Select second row
+  #   @table_state.select_column(0) # Select first column
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     table = RatatuiRuby::Table.new(rows: [...], widths: [...])
+  #     frame.render_stateful_widget(table, frame.area, @table_state)
+  #   end
+  #
+  class TableState
+    ##
+    # :method: new
+    # :call-seq: new(selected = nil) -> TableState
+    #
+    # Creates a new TableState with optional initial row selection.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select
+    # :call-seq: select(index) -> nil
+    #
+    # Sets the selected row index. Pass +nil+ to deselect.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: selected
+    # :call-seq: selected() -> Integer or nil
+    #
+    # Returns the currently selected row index.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_column
+    # :call-seq: select_column(index) -> nil
+    #
+    # Sets the selected column index. Pass +nil+ to deselect.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: selected_column
+    # :call-seq: selected_column() -> Integer or nil
+    #
+    # Returns the currently selected column index.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: offset
+    # :call-seq: offset() -> Integer
+    #
+    # Returns the current scroll offset.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: scroll_down_by
+    # :call-seq: scroll_down_by(n) -> nil
+    #
+    # Scrolls down by +n+ rows.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: scroll_up_by
+    # :call-seq: scroll_up_by(n) -> nil
+    #
+    # Scrolls up by +n+ rows.
+    #
+    # (Native method implemented in Rust)
+  end
+end