ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/layout/size.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Layout
+    # Generic dimensions as width and height.
+    #
+    # Layout calculations need sizes. Passing width and height
+    # as separate arguments is verbose and easy to swap by mistake.
+    #
+    # This class bundles dimensions into a single immutable object.
+    # Extract it from a Rect or create it directly for sizing operations.
+    #
+    # Following upstream Ratatui's design, the same Size type represents
+    # both character-grid dimensions (columns × rows) and pixel dimensions.
+    # The semantic meaning depends on the source:
+    #
+    # - From <tt>Terminal.size</tt> or <tt>WindowSize#columns_rows</tt>: columns and rows
+    # - From <tt>WindowSize#pixels</tt>: pixel width and height
+    #
+    # Use it for terminal dimensions, widget sizing constraints,
+    # or anywhere you need width/height without position.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   size = Layout::Size.new(width: 80, height: 24)
+    #   puts "Terminal is #{size.width} columns by #{size.height} rows"
+    #
+    #   # Extract from a Rect
+    #   rect = Layout::Rect.new(x: 10, y: 5, width: 80, height: 24)
+    #   size = rect.as_size # => Size(width: 80, height: 24)
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Size < Data.define(:width, :height)
+      ##
+      # :attr_reader: width
+      # Width dimension (columns for character grids, pixels for pixel sizes).
+
+      ##
+      # :attr_reader: height
+      # Height dimension (rows for character grids, pixels for pixel sizes).
+
+      # Creates a new Size.
+      #
+      # [width] Width in columns (Integer, coerced via +Integer()+).
+      # [height] Height in rows (Integer, coerced via +Integer()+).
+      def initialize(width: 0, height: 0)
+        super(width: Integer(width), height: Integer(height))
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/layout.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
+  # Layout primitives for geometry and space distribution.
+  #
+  # This module mirrors +ratatui::layout+ and contains:
+  # - {Rect} — Rectangle geometry
+  # - {Position} — Terminal coordinates
+  # - {Size} — Terminal dimensions
+  # - {Constraint} — Sizing rules
+  # - {Layout} — Space distribution
+  # - {HorizontalAlignment} — Horizontal alignment constants
+  # - {VerticalAlignment} — Vertical alignment constants
+  # - {Alignment} — Alias for HorizontalAlignment
+  module Layout
+  end
+end
+
+require_relative "layout/alignment"
+require_relative "layout/rect"
+require_relative "layout/position"
+require_relative "layout/size"
+require_relative "layout/constraint"
+require_relative "layout/layout"

data/lib/ratatui_ruby/list_state.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-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 Models.
+  #
+  # == Example
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   @list_state = RatatuiRuby::ListState.new
+  #   @list_state.select(2) # Select third item
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     list = RatatuiRuby::Widgets::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
+  #
+  #--
+  # SPDX-SnippetEnd
+  #++
+  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)
+
+    ##
+    # :method: select_next
+    # :call-seq: select_next() -> nil
+    #
+    # Moves selection to the next item. Selects first item if nothing selected.
+    #
+    # === Optimistic Indexing
+    #
+    # Increments the index immediately, even past list bounds. The renderer
+    # clamps to valid range on draw. Reading <tt>selected</tt> between this
+    # call and render may return an out-of-bounds value.
+    #
+    # Matches upstream Ratatui behavior. See
+    # {ListState#select_next}[https://docs.rs/ratatui/0.30/ratatui/widgets/struct.ListState.html#method.select_next].
+    #
+    # To detect actual selection changes, check bounds first:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   max_index = items.size - 1
+    #   return if (state.selected || 0) >= max_index
+    #   state.select_next
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_previous
+    # :call-seq: select_previous() -> nil
+    #
+    # Moves selection to the previous item. Selects last item if nothing selected.
+    #
+    # === Optimistic Indexing
+    #
+    # At index 0, does nothing. With no selection, sets index to maximum value;
+    # the renderer clamps to actual last item on draw.
+    #
+    # To detect actual selection changes, check bounds first:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   return if (state.selected || 0) <= 0
+    #   state.select_previous
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_first
+    # :call-seq: select_first() -> nil
+    #
+    # Jumps selection to the first item (index 0).
+    #
+    # To detect actual selection changes:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   return if (state.selected || 0) == 0
+    #   state.select_first
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_last
+    # :call-seq: select_last() -> nil
+    #
+    # Jumps selection to the last item.
+    #
+    # === Optimistic Indexing
+    #
+    # Sets index to maximum possible value. The renderer clamps to actual last
+    # item on draw. To get or check the real last index, track item count:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   max_index = items.size - 1
+    #   return if (state.selected || 0) == max_index
+    #   state.select(max_index)
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+  end
+end

data/lib/ratatui_ruby/output_guard.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  ##
+  # Output protection for TUI sessions and batch/CLI mode.
+  #
+  # This module provides mechanisms to prevent accidental output to stdout/stderr
+  # during TUI sessions and to support headless (batch/CLI) mode for applications
+  # that can run with or without a TUI.
+  #
+  # @see guard_io
+  # @see headless!
+  module OutputGuard
+    # A null IO object that swallows all output.
+    #
+    # Used by {guard_io} to temporarily replace $stdout and $stderr.
+    # Implements method_missing to accept any IO method and discard output.
+    #
+    # Returns self for method chaining (e.g., puts.flush).
+    class NullIO
+      # Accepts any method call and returns self, discarding all output.
+      def method_missing(name, *args, &block)
+        self
+      end
+
+      # Reports that all methods are supported.
+      def respond_to_missing?(name, include_private = false)
+        true
+      end
+    end
+
+    ##
+    # Whether headless (batch/pipeline/CLI) mode is enabled.
+    #
+    # When headless mode is active:
+    # - {guard_io} becomes a silent no-op (output is not swallowed)
+    # - {init_terminal} and {run} raise {Error::Invariant}
+    #
+    # Use this when your app has a `--no-tui` or `--batch` flag and you want
+    # the same code to work in both TUI and non-TUI modes.
+    #
+    # @see headless!
+    def is_headless?
+      @headless_mode
+    end
+
+    ##
+    # Enables headless (batch/CLI) mode.
+    #
+    # Call this at app startup when running in batch/CLI mode (e.g., `--no-tui`).
+    # This tells RatatuiRuby that you intentionally don't want a TUI session.
+    #
+    # When headless mode is active:
+    # - {guard_io} becomes a silent no-op (output flows normally)
+    # - {init_terminal} and {run} raise {Error::Invariant}
+    #
+    # Headless mode and TUI sessions are mutually exclusive. Calling this
+    # while a TUI session is active raises {Error::Invariant}.
+    #
+    # === Why there is no exit_headless!
+    #
+    # Headless mode is a startup-time decision for the entire app run.
+    # If you need to temporarily exit TUI mode for user interaction
+    # (like lazygit does when editing a commit message), use
+    # {restore_terminal} and {init_terminal} instead:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   RatatuiRuby.restore_terminal
+    #   puts "Press enter to continue..."
+    #   gets
+    #   RatatuiRuby.init_terminal
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   if ARGV.include?("--no-tui")
+    #     RatatuiRuby.headless!
+    #     process_batch_work  # guard_io calls are silent no-ops
+    #   else
+    #     RatatuiRuby.run do |tui|  # This branch only runs in TUI mode
+    #       # ... TUI code ...
+    #     end
+    #   end
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # Note: Calling {run} or {init_terminal} after {headless!} raises
+    # {Error::Invariant}. The block is never executed.
+    #
+    # @raise [Error::Invariant] if a TUI session is already active
+    # @see is_headless?
+    # @see restore_terminal
+    def headless!
+      if @tui_session_active
+        raise Error::Invariant, "Cannot enable headless mode: TUI session already active"
+      end
+      @headless_mode = true
+    end
+
+    ##
+    # Guards a block from stdout/stderr output.
+    #
+    # During a TUI session, writes to $stdout or $stderr corrupt the display.
+    # Wrap code that might produce output (e.g., chatty gems) in this block.
+    #
+    # This temporarily replaces $stdout and $stderr with a {NullIO} object
+    # that discards all output. The original streams are restored when the
+    # block exits, even if an exception occurs.
+    #
+    # === Behavior by mode
+    #
+    # - **TUI session active**: Output is swallowed (guarded)
+    # - **Headless mode**: Silent no-op (output flows normally)
+    # - **Neither**: Warns and yields (catches potential mistakes)
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   RatatuiRuby.run do |tui|
+    #     RatatuiRuby.guard_io do
+    #       SomeChattyGem.do_something  # Any puts/warn calls are swallowed
+    #     end
+    #   end
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # @see headless!
+    def guard_io
+      # TUI active: guard the output
+      if terminal_active?
+        $stdout = NullIO.new
+        $stderr = NullIO.new
+        begin
+          return yield
+        ensure
+          $stdout = Object::STDOUT
+          $stderr = Object::STDERR
+        end
+      end
+
+      # Headless mode: silent no-op
+      return yield if is_headless?
+
+      # Neither: warn about potential mistake
+      warn "guard_io called outside TUI session. If this is intentional (batch/CLI mode), call RatatuiRuby.headless! at startup to silence this warning."
+      yield
+    end
+  end
+end

data/lib/ratatui_ruby/scrollbar_state.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Mutable state object for Scrollbar widgets.
+  #
+  # When using {Frame#render_stateful_widget}, the State object is the
+  # *single source of truth* for position and content length. Widget
+  # properties (+position+, +content_length+) are *ignored* in stateful mode.
+  #
+  # == Example
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   @scrollbar_state = RatatuiRuby::ScrollbarState.new(100)
+  #   @scrollbar_state.position = 25
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     scrollbar = RatatuiRuby::Scrollbar.new(orientation: :vertical_right)
+  #     frame.render_stateful_widget(scrollbar, frame.area, @scrollbar_state)
+  #   end
+  #
+  #--
+  # SPDX-SnippetEnd
+  #++
+  class ScrollbarState
+    ##
+    # :method: new
+    # :call-seq: new(content_length) -> ScrollbarState
+    #
+    # Creates a new ScrollbarState with the given content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: position
+    # :call-seq: position() -> Integer
+    #
+    # Returns the current scroll position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: position=
+    # :call-seq: position=(value) -> Integer
+    #
+    # Sets the current scroll position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: content_length
+    # :call-seq: content_length() -> Integer
+    #
+    # Returns the total content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: content_length=
+    # :call-seq: content_length=(value) -> Integer
+    #
+    # Sets the total content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: viewport_content_length
+    # :call-seq: viewport_content_length() -> Integer
+    #
+    # Returns the viewport content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: viewport_content_length=
+    # :call-seq: viewport_content_length=(value) -> Integer
+    #
+    # Sets the viewport content length.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: first
+    # :call-seq: first() -> nil
+    #
+    # Scrolls to the first position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: last
+    # :call-seq: last() -> nil
+    #
+    # Scrolls to the last position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: next
+    # :call-seq: next() -> nil
+    #
+    # Scrolls to the next position.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: prev
+    # :call-seq: prev() -> nil
+    #
+    # Scrolls to the previous position.
+    #
+    # (Native method implemented in Rust)
+  end
+end