ratatui_ruby 0.9.0 → 0.10.0

data/lib/ratatui_ruby/debug.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  ##
+  # Debug mode control for RatatuiRuby.
+  #
+  # TUI applications are hard to debug. Rust panics show cryptic stack traces.
+  # Ruby exceptions lack Rust context.
+  #
+  # This module controls debug visibility. Enable Rust backtraces only, or
+  # enable full debug mode for both Rust and Ruby-side features.
+  #
+  # == Activation Methods
+  #
+  # Three ways to enable debug features:
+  #
+  # [<tt>RUST_BACKTRACE=1</tt>] Rust backtraces only (no Ruby-side debug).
+  # [<tt>RR_DEBUG=1</tt>] Full debug mode (backtraces + Ruby features).
+  # [<tt>include RatatuiRuby::TestHelper</tt>] Auto-enables debug mode.
+  #
+  # === Example
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   # Programmatic activation
+  #   RatatuiRuby::Debug.enable!
+  #
+  #   # Or use the convenience alias
+  #   RatatuiRuby.debug_mode!
+  #
+  #--
+  # SPDX-SnippetEnd
+  #++
+  module Debug
+    @rust_backtrace_enabled = false
+    @debug_mode_enabled = false
+
+    class << self
+      ##
+      # Enables Rust backtraces only.
+      #
+      # Call this to get meaningful stack traces when Rust panics.
+      # Does not enable Ruby-side debug features.
+      #
+      # Safe to call multiple times; subsequent calls are no-ops.
+      def enable_rust_backtrace!
+        return if @rust_backtrace_enabled
+
+        @rust_backtrace_enabled = true
+        RatatuiRuby.__send__(:_enable_rust_backtrace)
+      end
+
+      ##
+      # Enables full debug mode.
+      #
+      # Activates Rust backtraces plus any Ruby-side debug features.
+      # Optionally enables remote debugging via the debug gem.
+      #
+      # Safe to call multiple times; subsequent calls are no-ops.
+      #
+      # [source] <tt>:env</tt> if called from RR_DEBUG env var,
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #          <tt>:test</tt> from TestHelper (skips remote debugging),
+      #          <tt>:programmatic</tt> otherwise.
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def enable!(source: :programmatic)
+        return @socket_path if @debug_mode_enabled
+
+        @debug_mode_enabled = true
+        enable_rust_backtrace!
+
+        # Tests don't need remote debugging — it would cause hangs
+        return if source == :test
+
+        @remote_debugging_mode = (source == :env) ? :open : :open_nonstop
+        @socket_path = enable_remote_debugging!
+      end
+
+      # rubocop:disable Lint/Debugger -- intentional debug gem integration
+      private def enable_remote_debugging!
+        # Suppress the "Debugger can attach via..." message that corrupts TUI displays
+        # Only suppress for programmatic activation; RR_DEBUG=1 users need to see it
+        old_log_level = ENV["RUBY_DEBUG_LOG_LEVEL"]
+        ENV["RUBY_DEBUG_LOG_LEVEL"] = "ERROR" if @remote_debugging_mode == :open_nonstop
+
+        case @remote_debugging_mode
+        when :open
+          # Stop at load so user can read socket path before TUI enters raw mode
+          ENV["RUBY_DEBUG_STOP_AT_LOAD"] = "1"
+          require "debug/open"
+        when :open_nonstop
+          require "debug/open_nonstop"
+        end
+
+        # Restore log level after require (the require is what prints the message)
+        ENV["RUBY_DEBUG_LOG_LEVEL"] = old_log_level if @remote_debugging_mode == :open_nonstop
+
+        # Return the socket path so apps can display it
+        ::DEBUGGER__.create_unix_domain_socket_name
+      rescue NameError
+        # Windows uses TCP/IP, not Unix sockets — DEBUGGER__ might not have this method
+        nil
+      # rubocop:enable Lint/Debugger
+      rescue LoadError
+        return unless @remote_debugging_mode == :open
+
+        raise LoadError,
+          "RR_DEBUG=1 requires the 'debug' gem for remote debugging. " \
+            "Add `gem 'debug'` to your Gemfile or install it with `gem install debug`."
+      end
+
+      ##
+      # Returns whether full debug mode is enabled.
+      public def enabled?
+        @debug_mode_enabled
+      end
+
+      ##
+      # Returns whether Rust backtraces are enabled.
+      public def rust_backtrace_enabled?
+        @rust_backtrace_enabled
+      end
+
+      ##
+      # Returns the remote debugging mode for debug gem integration.
+      #
+      # TUI apps run in raw terminal mode, making interactive debugging
+      # impossible. The debug gem's remote debugging feature lets you
+      # attach from another terminal via UNIX socket.
+      #
+      # Returns one of:
+      # <tt>:open</tt> Stop at program start, wait for debugger attach.
+      #                   Activated when <tt>RR_DEBUG=1</tt> is set at startup.
+      # <tt>:open_nonstop</tt> Continue running, attach whenever ready.
+      #                           Activated when <tt>enable!</tt> is called programmatically.
+      # <tt>nil</tt> No remote debugging configured.
+      public def remote_debugging_mode
+        @remote_debugging_mode
+      end
+
+      ##
+      # Triggers a Rust panic for backtrace verification.
+      #
+      # Debugging TUI apps is hard. Rust errors lack context. You want to
+      # confirm <tt>RUST_BACKTRACE=1</tt> actually shows stack traces before
+      # hitting a real bug.
+      #
+      # This method deliberately panics. The panic hook catches it and prints
+      # the Rust backtrace to stderr. If you see stack frames, your setup works.
+      #
+      # <b>WARNING</b>: Crashes your process. Use only for debugging.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   RUST_BACKTRACE=1 ruby -e 'require "ratatui_ruby"; RatatuiRuby::Debug.test_panic!'
+      #--
+      # SPDX-SnippetEnd
+      #++
+      public def test_panic!
+        RatatuiRuby.__send__(:_test_panic)
+      end
+
+      ##
+      # Temporarily suppresses Ruby-side debug mode checks.
+      #
+      # Rust backtraces remain enabled if previously activated; only
+      # Ruby-side features (like unknown-key errors) are suppressed
+      # within the block.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   RatatuiRuby::Debug.suppress_debug_mode do
+      #     tui.table({ unknown_key: 1 }) # Does not raise
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      public def suppress_debug_mode
+        old_value = @debug_mode_enabled
+        @debug_mode_enabled = false
+        yield
+      ensure
+        @debug_mode_enabled = old_value
+      end
+    end
+  end
+end
+
+# Auto-enable based on environment variables
+RatatuiRuby::Debug.enable_rust_backtrace! if ENV["RUST_BACKTRACE"]
+RatatuiRuby::Debug.enable!(source: :env) if ENV["RR_DEBUG"]

data/lib/ratatui_ruby/event/key.rb

@@ -330,9 +330,10 @@ module RatatuiRuby
       #--
       # SPDX-SnippetEnd
       #++
-      def method_missing(name, *args, &block)
+      def method_missing(name, *args, **kwargs, &block)
         if name.to_s.end_with?("?")
-          key_name = name.to_s[0...-1]
+          name_str = name.to_s
+          key_name = name_str.chop # Returns String, never nil for non-empty string
           key_sym = key_name.to_sym
 
           # Fast path: Exact match (e.g., media_pause? for media_pause)

data/lib/ratatui_ruby/event/sync.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class Event
+    # Synthetic event for synchronizing async operations in tests.
+    #
+    # Testing async behavior is tricky. You inject an event, but results arrive
+    # later. By the time you assert, the async work may not have completed.
+    #
+    # When a runtime (Tea, Kit) encounters this event, it should wait for all
+    # pending async operations to complete before processing the next event.
+    # This enables deterministic testing without changing production code paths.
+    #
+    # Inject this event between user actions and assertions to ensure async
+    # results have been processed:
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   inject_key("s")           # Triggers async command
+    #   inject_sync               # Wait for command to complete
+    #   inject_key(:q)            # Quit after seeing results
+    #   Tea.run(...)
+    #   assert_snapshots("after_s_with_results")
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # This is not "test mode"—it's a real event that runtimes handle.
+    # Production apps could use it too (e.g., "ensure saves complete before quit").
+    class Sync < Event
+      # Returns true for Sync events.
+      def sync?
+        true
+      end
+
+      # Deconstructs the event for pattern matching.
+      def deconstruct_keys(keys)
+        { type: :sync }
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event.rb

@@ -111,9 +111,14 @@ module RatatuiRuby
       false
     end
 
+    # Returns true if this is a Sync event.
+    def sync?
+      false
+    end
+
     # Responds to dynamic predicate methods for key checks.
     # All non-Key events return false for any key predicate.
-    def method_missing(name, *args, &block)
+    def method_missing(name, *args, **kwargs, &block)
       if name.to_s.end_with?("?")
         false
       else
@@ -155,3 +160,4 @@ require_relative "event/resize"
 require_relative "event/paste"
 require_relative "event/focus_gained"
 require_relative "event/focus_lost"
+require_relative "event/sync"

data/lib/ratatui_ruby/layout/constraint.rb

@@ -148,6 +148,190 @@ module RatatuiRuby
       def self.ratio(numerator, denominator)
         new(type: :ratio, value: [Integer(numerator), Integer(denominator)])
       end
+
+      # Converts an array of lengths into an array of Length constraints.
+      #
+      # Complex layouts often use multiple fixed-size sections. Manually creating each constraint
+      # clutters the code.
+      #
+      # This method maps over the input, returning a constraint array in one call.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.from_lengths([10, 20, 10])
+      #   # => [Constraint.length(10), Constraint.length(20), Constraint.length(10)]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [values] Enumerable of Integers.
+      def self.from_lengths(values)
+        values.map { |v| length(v) }
+      end
+
+      # Converts an array of percentages into an array of Percentage constraints.
+      #
+      # Percentage-based layouts distribute space proportionally. This method batches the creation.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.from_percentages([25, 50, 25])
+      #   # => [Constraint.percentage(25), Constraint.percentage(50), Constraint.percentage(25)]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [values] Enumerable of Integers (0-100).
+      def self.from_percentages(values)
+        values.map { |v| percentage(v) }
+      end
+
+      # Converts an array of minimums into an array of Min constraints.
+      #
+      # Minimum constraints ensure sections never shrink below a threshold. Batch them here.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.from_mins([5, 10, 5])
+      #   # => [Constraint.min(5), Constraint.min(10), Constraint.min(5)]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [values] Enumerable of Integers.
+      def self.from_mins(values)
+        values.map { |v| min(v) }
+      end
+
+      # Converts an array of maximums into an array of Max constraints.
+      #
+      # Maximum constraints cap section sizes. Batch them here.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.from_maxes([20, 30, 40])
+      #   # => [Constraint.max(20), Constraint.max(30), Constraint.max(40)]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [values] Enumerable of Integers.
+      def self.from_maxes(values)
+        values.map { |v| max(v) }
+      end
+
+      # Converts an array of weights into an array of Fill constraints.
+      #
+      # Fill constraints distribute remaining space by weight. Batch them here.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.from_fills([1, 2, 1])
+      #   # => [Constraint.fill(1), Constraint.fill(2), Constraint.fill(1)]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [values] Enumerable of Integers.
+      def self.from_fills(values)
+        values.map { |v| fill(v) }
+      end
+
+      # Converts an array of ratio pairs into an array of Ratio constraints.
+      #
+      # Ratio constraints define exact fractions of space. Batch them here.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.from_ratios([[1, 4], [2, 4], [1, 4]])
+      #   # => [Constraint.ratio(1, 4), Constraint.ratio(2, 4), Constraint.ratio(1, 4)]
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [pairs] Enumerable of <tt>[numerator, denominator]</tt> arrays.
+      def self.from_ratios(pairs)
+        pairs.map { |n, d| ratio(n, d) }
+      end
+
+      # Computes the size this constraint would produce given available space.
+      #
+      # Layout engines use constraints to compute actual dimensions.
+      # Calling apply lets you preview the result without rendering.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Constraint.percentage(50).apply(100) # => 50
+      #   Constraint.length(10).apply(100)     # => 10
+      #   Constraint.min(10).apply(5)          # => 10
+      #   Constraint.max(10).apply(15)         # => 10
+      #   Constraint.ratio(1, 4).apply(100)    # => 25
+      #--
+      # SPDX-SnippetEnd
+      #++
+      #
+      # [length] Available space (Integer).
+      #
+      # Returns the computed size (Integer).
+      def apply(length)
+        length = Integer(length)
+        case type
+        when :length
+          value
+        when :percentage
+          (length * value) / 100
+        when :min
+          [value, length].max
+        when :max
+          [value, length].min
+        when :fill
+          length
+        when :ratio
+          numerator, denominator = value
+          denominator.zero? ? 0 : (length * numerator) / denominator
+        else
+          length
+        end
+      end
+
+      # Ruby-idiomatic alias (TIMTOWTDI)
+      # Allows proc-like invocation: constraint.(100)
+      alias call apply
     end
   end
 end

data/lib/ratatui_ruby/layout/layout.rb

@@ -22,7 +22,7 @@ module RatatuiRuby
     # Run the interactive demo from the terminal:
     #
     #   ruby examples/widget_layout_split/app.rb
-    class Layout < Data.define(:direction, :constraints, :children, :flex)
+    class Layout < Data.define(:direction, :constraints, :children, :flex, :margin, :spacing)
       ##
       # :attr_reader: direction
       # Direction of the split.
@@ -81,6 +81,23 @@ module RatatuiRuby
       # Flex: space evenly between elements.
       FLEX_SPACE_EVENLY = :space_evenly
 
+      ##
+      # :attr_reader: margin
+      # Margin around the layout area.
+      #
+      # Either a single <tt>Integer</tt> for uniform margin on all sides, or a
+      # <tt>Hash</tt> with <tt>:horizontal</tt> and <tt>:vertical</tt> keys.
+      #
+      #   layout.margin # => 2
+
+      ##
+      # :attr_reader: spacing
+      # Gap between segments (in cells).
+      #
+      # A positive integer that specifies the number of cells between each segment.
+      #
+      #   layout.spacing # => 1
+
       # Creates a new Layout.
       #
       # [direction]
@@ -91,7 +108,11 @@ module RatatuiRuby
       #   List of widgets to render (optional).
       # [flex]
       #   Flex mode for spacing (default: <tt>:legacy</tt>).
-      def initialize(direction: :vertical, constraints: [], children: [], flex: :legacy)
+      # [margin]
+      #   Edge margin in cells (default: <tt>0</tt>).
+      # [spacing]
+      #   Gap between segments in cells (default: <tt>0</tt>).
+      def initialize(direction: :vertical, constraints: [], children: [], flex: :legacy, margin: 0, spacing: 0)
         super
       end
 
@@ -134,20 +155,105 @@ module RatatuiRuby
       #++
       # Returns an Array of <tt>Rect</tt> objects.
       def self.split(area, direction: :vertical, constraints:, flex: :legacy)
-        # Duck-typing: If it lacks geometry methods but can be a Hash, convert it.
-        if !area.respond_to?(:x) && area.respond_to?(:to_h)
-          # Assume it's a Hash-like object with :x, :y, etc.
-          hash = area.to_h
-          area = Rect.new(
-            x: hash.fetch(:x, 0),
-            y: hash.fetch(:y, 0),
-            width: hash.fetch(:width, 0),
-            height: hash.fetch(:height, 0)
-          )
+        # Coerce area to Rect for type safety (supports duck typing via _RectLike interface)
+        rect = case area
+               when Rect
+                 area
+               when Hash
+                 Rect.new(
+                   x: Integer(area.fetch(:x, 0)),
+                   y: Integer(area.fetch(:y, 0)),
+                   width: Integer(area.fetch(:width, 0)),
+                   height: Integer(area.fetch(:height, 0))
+                 )
+               else
+                 # Duck typing: accept any object responding to x, y, width, height
+                 if area.respond_to?(:x) && area.respond_to?(:y) && area.respond_to?(:width) && area.respond_to?(:height)
+                   # @type var rect_like: _RectLike
+                   rect_like = area
+                   Rect.new(x: rect_like.x, y: rect_like.y, width: rect_like.width, height: rect_like.height)
+                 else
+                   raise ArgumentError, "area must be a Rect, Hash, or respond to x/y/width/height, got #{area.class}"
+                 end
         end
-        raw_rects = _split(area, direction, constraints, flex)
+        raw_rects = _split(rect, direction, constraints, flex)
         raw_rects.map { |r| Rect.new(x: r[:x], y: r[:y], width: r[:width], height: r[:height]) }
       end
+
+      # Splits an area into multiple rectangles, returning both segments and spacers.
+      #
+      # Layout splitting returns only the content areas. But some designs need to
+      # render content in the gaps (dividers, separators, decorations).
+      #
+      # This method returns both the segments (content areas) and the spacers
+      # (gaps between segments) as separate arrays. The spacers are the Rects
+      # that represent the spacing between each segment.
+      #
+      # Use it to render custom separators or to calculate layout with spacing.
+      #
+      # [area]
+      #   The area to split. Can be a <tt>Rect</tt> or a <tt>Hash</tt> containing <tt>:x</tt>, <tt>:y</tt>, <tt>:width</tt>, and <tt>:height</tt>.
+      # [direction]
+      #   <tt>:vertical</tt> or <tt>:horizontal</tt> (default: <tt>:vertical</tt>).
+      # [constraints]
+      #   Array of <tt>Constraint</tt> objects defining section sizes.
+      # [flex]
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Flex mode for spacing (default: <tt>:legacy</tt>).
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns an Array of two Arrays: <tt>[segments, spacers]</tt>, each containing <tt>Rect</tt> objects.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   area = Rect.new(x: 0, y: 0, width: 100, height: 10)
+      #   segments, spacers = Layout.split_with_spacers(
+      #     area,
+      #     direction: :horizontal,
+      #     constraints: [Constraint.length(40), Constraint.length(40)],
+      #     flex: :space_around
+      #   )
+      #   # segments: 2 Rects for content
+      #   # spacers: Rects for gaps between/around segments
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def self.split_with_spacers(area, direction: :vertical, constraints:, flex: :legacy)
+        # Coerce area to Rect for type safety
+        rect = case area
+               when Rect
+                 area
+               when Hash
+                 Rect.new(
+                   x: Integer(area.fetch(:x, 0)),
+                   y: Integer(area.fetch(:y, 0)),
+                   width: Integer(area.fetch(:width, 0)),
+                   height: Integer(area.fetch(:height, 0))
+                 )
+               else
+                 if area.respond_to?(:x) && area.respond_to?(:y) && area.respond_to?(:width) && area.respond_to?(:height)
+                   rect_like = area
+                   Rect.new(x: rect_like.x, y: rect_like.y, width: rect_like.width, height: rect_like.height)
+                 else
+                   raise ArgumentError, "area must be a Rect, Hash, or respond to x/y/width/height, got #{area.class}"
+                 end
+        end
+        raw_segments, raw_spacers = _split_with_spacers(rect, direction, constraints, flex)
+        segments = raw_segments.map { |r| Rect.new(x: r[:x], y: r[:y], width: r[:width], height: r[:height]) }
+        spacers = raw_spacers.map { |r| Rect.new(x: r[:x], y: r[:y], width: r[:width], height: r[:height]) }
+        [segments, spacers]
+      end
     end
   end
 end