ratatui_ruby 0.4.0 → 0.6.0

data/lib/ratatui_ruby/frame.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Provides access to the terminal buffer for rendering widgets.
+  #
+  # Rendering in immediate-mode TUIs requires knowing the terminal dimensions and
+  # placing widgets at specific positions. Without explicit control, layout
+  # calculations become duplicated between rendering and hit testing.
+  #
+  # This class exposes the terminal frame during a draw call. It provides the
+  # current area and methods to render widgets at precise locations.
+  #
+  # Use it inside a <tt>RatatuiRuby.draw</tt> block to render widgets with full
+  # control over placement.
+  #
+  # == Thread/Ractor Safety
+  #
+  # Frame is an *I/O handle*, not a data object. It has side effects
+  # (render_widget, set_cursor_position) and is intentionally *not*
+  # Ractor-shareable. Passing it to helper methods during the draw block is
+  # fine. However, do not include it in immutable TEA Models/Messages or pass
+  # it to other Ractors. Frame is only valid during the draw block's execution.
+  #
+  # === Examples
+  #
+  # Basic usage with a single widget:
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     paragraph = RatatuiRuby::Paragraph.new(text: "Hello, world!")
+  #     frame.render_widget(paragraph, frame.area)
+  #   end
+  #
+  # Using Layout.split for multi-region layouts:
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     sidebar, main = RatatuiRuby::Layout.split(
+  #       frame.area,
+  #       direction: :horizontal,
+  #       constraints: [
+  #         RatatuiRuby::Constraint.length(20),
+  #         RatatuiRuby::Constraint.fill(1)
+  #       ]
+  #     )
+  #
+  #     frame.render_widget(sidebar_widget, sidebar)
+  #     frame.render_widget(main_widget, main)
+  #
+  #     # Store rects for hit testing — no duplication!
+  #     @regions = { sidebar: sidebar, main: main }
+  #   end
+  class Frame
+    ##
+    # :method: area
+    # :call-seq: area() -> Rect
+    #
+    # Returns the full terminal area as a Rect.
+    #
+    # The returned Rect represents the entire drawable area of the terminal.
+    # Use it as the starting point for layout calculations.
+    #
+    # === Example
+    #
+    #   RatatuiRuby.draw do |frame|
+    #     puts "Terminal size: #{frame.area.width}x#{frame.area.height}"
+    #   end
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: render_widget
+    # :call-seq: render_widget(widget, area) -> nil
+    #
+    # Renders a widget at the specified area.
+    #
+    # Widgets in RatatuiRuby are immutable Data objects. This method takes a
+    # widget and a Rect, rendering the widget's content within that region.
+    #
+    # [widget]
+    #   The widget to render (Paragraph, Layout, List, Table, etc.).
+    # [area]
+    #   A Rect specifying where to render the widget.
+    #
+    # === Example
+    #
+    #   RatatuiRuby.draw do |frame|
+    #     para = RatatuiRuby::Paragraph.new(text: "Content")
+    #     frame.render_widget(para, frame.area)
+    #   end
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: render_stateful_widget
+    # :call-seq: render_stateful_widget(widget, area, state) -> nil
+    #
+    # Renders a widget with persistent state.
+    #
+    # Some UI components (like List or Table) have **runtime status** (Status) that
+    # changes during rendering, such as the current scroll offset.
+    #
+    # Since Widget definitions (Configuration Definition) are immutable inputs,
+    # you must pass a separate mutable State object (Output Status) to capture
+    # these changes.
+    #
+    # Note: The Widget configuration is *always* required. The State object is
+    # only used for specific widgets that need to persist runtime status.
+    #
+    #
+    # [widget]
+    #   The immutable widget configuration (Input) (e.g., RatatuiRuby::List).
+    # [area]
+    #   The Rect area to render into.
+    # [state]
+    #   The mutable state object (Output) (e.g., RatatuiRuby::ListState).
+    #
+    # === Example
+    #
+    #   # Initialize state once (outside the loop)
+    #   @list_state = RatatuiRuby::ListState.new
+    #
+    #   RatatuiRuby.draw do |frame|
+    #     list = RatatuiRuby::List.new(items: ["A", "B"])
+    #     frame.render_stateful_widget(list, frame.area, @list_state)
+    #   end
+    #
+    #   # Read back the offset calculated by Ratatui
+    #   puts @list_state.offset
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: set_cursor_position
+    # :call-seq: set_cursor_position(x, y) -> nil
+    #
+    # Positions the blinking cursor at the given coordinates.
+    #
+    # Text input fields show users where typed characters will appear. Without
+    # a visible cursor, users cannot tell if the input is focused or where text
+    # will insert.
+    #
+    # This method moves the terminal cursor to a specific cell. Coordinates are
+    # 0-indexed from the terminal's top-left corner.
+    #
+    # Use it when building login forms, search bars, or command palettes.
+    #
+    # [x]
+    #   Column position (<tt>0</tt> = leftmost column).
+    # [y]
+    #   Row position (<tt>0</tt> = topmost row).
+    #
+    # === Example
+    #
+    # Position the cursor at the end of typed text in a login form:
+    #
+    #   PREFIX = "Username: [ "
+    #   username = "alice"
+    #
+    #   RatatuiRuby.draw do |frame|
+    #     # Render the input field
+    #     prompt = RatatuiRuby::Paragraph.new(
+    #       text: "#{PREFIX}#{username} ]",
+    #       block: RatatuiRuby::Block.new(borders: :all)
+    #     )
+    #     frame.render_widget(prompt, frame.area)
+    #
+    #     # Position cursor after the typed text
+    #     # Account for border (1) + prefix length + username length
+    #     cursor_x = 1 + PREFIX.length + username.length
+    #     cursor_y = 1  # First line inside border
+    #     frame.set_cursor_position(cursor_x, cursor_y)
+    #   end
+    #
+    # See also:
+    # - {Component-based implementation using Frame API}[link:/examples/app_color_picker/app_rb.html]
+    # - {Declarative implementation using Tree API}[link:/examples/app_login_form/app_rb.html]
+    # - RatatuiRuby::Cursor (Tree API alternative)
+    #
+    # (Native method implemented in Rust)
+  end
+end

data/lib/ratatui_ruby/list_state.rb

@@ -0,0 +1,88 @@
+# 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 List widgets.
+  #
+  # When using {Frame#render_stateful_widget}, the State object is the
+  # *single source of truth* for selection and scroll offset. Widget
+  # properties (+selected_index+, +offset+) are *ignored* in stateful mode.
+  #
+  # State objects persist across frames, allowing you to:
+  # - Track selection without manual index management
+  # - Read back the scroll offset calculated by Ratatui
+  # - Implement mouse click-to-row hit testing
+  #
+  # == Thread/Ractor Safety
+  #
+  # ListState is *not* Ractor-shareable. It contains mutable internal state.
+  # Store it in instance variables, not in immutable TEA Models.
+  #
+  # == Example
+  #
+  #   @list_state = RatatuiRuby::ListState.new
+  #   @list_state.select(2) # Select third item
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     list = RatatuiRuby::List.new(items: ["A", "B", "C", "D", "E"])
+  #     frame.render_stateful_widget(list, frame.area, @list_state)
+  #   end
+  #
+  #   puts @list_state.offset # Scroll position after render
+  #
+  class ListState
+    ##
+    # :method: new
+    # :call-seq: new(selected = nil) -> ListState
+    #
+    # Creates a new ListState with optional initial selection.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select
+    # :call-seq: select(index) -> nil
+    #
+    # Sets the selected index. Pass +nil+ to deselect.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: selected
+    # :call-seq: selected() -> Integer or nil
+    #
+    # Returns the currently selected index, or +nil+ if nothing is selected.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: offset
+    # :call-seq: offset() -> Integer
+    #
+    # Returns the current scroll offset.
+    #
+    # This is the critical read-back method. After +render_stateful_widget+,
+    # this returns the scroll position calculated by Ratatui to keep the
+    # selection visible.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: scroll_down_by
+    # :call-seq: scroll_down_by(n) -> nil
+    #
+    # Scrolls down by +n+ items.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: scroll_up_by
+    # :call-seq: scroll_up_by(n) -> nil
+    #
+    # Scrolls up by +n+ items.
+    #
+    # (Native method implemented in Rust)
+  end
+end

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

@@ -6,7 +6,7 @@
 module RatatuiRuby
   class BarChart
     # A bar in a grouped bar chart.
-    # 
+    #
     # === Examples
     #
     #   BarChart::Bar.new(value: 10, style: Style.new(fg: :red), label: "A")
@@ -14,32 +14,32 @@ module RatatuiRuby
       ##
       # :attr_reader: value
       # The value of the bar (Integer).
-  
+
       ##
       # :attr_reader: label
-      # The label of the bar (optional String).
-  
+      # 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).
-  
+      # 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: label,
-          style: style,
-          value_style: value_style,
-          text_value: text_value
+          label:,
+          style:,
+          value_style:,
+          text_value:
         )
       end
     end
   end
-end
+end

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

@@ -14,14 +14,10 @@ module RatatuiRuby
       ##
       # :attr_reader: label
       # The label of the group (String).
-  
+
       ##
       # :attr_reader: bars
       # The bars in the group (Array of Bar).
-  
-      def initialize(label:, bars:)
-        super
-      end
     end
   end
 end