ratatui_ruby 0.9.1 → 0.10.1

data/lib/ratatui_ruby/layout/constraint.rb

@@ -283,6 +283,55 @@ module RatatuiRuby
       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

data/lib/ratatui_ruby/layout/position.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Layout
+    # A position in terminal coordinates.
+    #
+    # Layout code passes x/y pairs between functions. Bundling them
+    # into separate variables is verbose and prone to ordering mistakes.
+    #
+    # This class wraps column and row into a single immutable object.
+    # Pass it around, destructure it, or convert from a Rect.
+    #
+    # Use it for cursor positioning, mouse coordinates, or anywhere
+    # you need to represent a single point on the terminal grid.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   pos = Layout::Position.new(x: 10, y: 5)
+    #   puts "Cursor at column #{pos.x}, row #{pos.y}"
+    #
+    #   # Extract from a Rect
+    #   rect = Layout::Rect.new(x: 10, y: 5, width: 80, height: 24)
+    #   pos = rect.as_position # => Position(x: 10, y: 5)
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Position < Data.define(:x, :y)
+      ##
+      # :attr_reader: x
+      # Column index (0-indexed from left edge).
+
+      ##
+      # :attr_reader: y
+      # Row index (0-indexed from top edge).
+
+      # Creates a new Position.
+      #
+      # [x] Column index (Integer, coerced via +Integer()+).
+      # [y] Row index (Integer, coerced via +Integer()+).
+      def initialize(x: 0, y: 0)
+        super(x: Integer(x), y: Integer(y))
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/layout/rect.rb

@@ -379,6 +379,37 @@ module RatatuiRuby
         )
       end
 
+      # Expands the rect by a uniform margin on all sides.
+      #
+      # Containers wrap content with decorations. Adding margin to all four edges inline is verbose.
+      # Off-by-one errors happen when you forget to double the margin.
+      #
+      # This method computes the outer area. Saturates x/y at 0 when margin exceeds position.
+      # Use Rect#clamp to constrain the result if it may exceed screen bounds.
+      #
+      # [margin] Integer expansion on all sides.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 10, width: 20, height: 10)
+      #   rect.outer(5) # => Rect(x: 5, y: 5, width: 30, height: 20)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def outer(margin)
+        new_x = [x - margin, 0].max
+        new_y = [y - margin, 0].max
+        new_width = right + margin - new_x
+        new_height = bottom + margin - new_y
+
+        Rect.new(x: new_x, y: new_y, width: new_width, height: new_height)
+      end
+
       # Moves the rect without changing size.
       #
       # Animations and drag-and-drop shift widgets.
@@ -405,6 +436,32 @@ module RatatuiRuby
         Rect.new(x: x + dx, y: y + dy, width:, height:)
       end
 
+      # Changes dimensions while preserving position.
+      #
+      # Window resizing and responsive layouts adjust size mid-session.
+      # Creating a new rect with the same position but different size is common.
+      #
+      # This method returns a resized copy. Position unchanged.
+      #
+      # [new_size] Size object with new dimensions.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 5, width: 20, height: 10)
+      #   rect.resize(Size.new(width: 40, height: 20))
+      #   # => Rect(x: 10, y: 5, width: 40, height: 20)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def resize(new_size)
+        Rect.new(x:, y:, width: new_size.width, height: new_size.height)
+      end
+
       # Constrains the rect to fit inside bounds.
       #
       # Popups and tooltips may extend beyond screen edges.
@@ -516,6 +573,137 @@ module RatatuiRuby
           end
         end
       end
+
+      # Extracts the position (x, y) from this rect.
+      #
+      # Layout code sometimes separates position from size.
+      # Extracting x and y into multiple variables is verbose.
+      #
+      # This method returns a Position object containing just the coordinates.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 5, width: 80, height: 24)
+      #   rect.as_position # => Position(x: 10, y: 5)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def as_position
+        Position.new(x:, y:)
+      end
+
+      # Extracts the size (width, height) from this rect.
+      #
+      # Layout code sometimes separates size from position.
+      # Extracting width and height into multiple variables is verbose.
+      #
+      # This method returns a Size object containing just the dimensions.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 5, width: 80, height: 24)
+      #   rect.as_size # => Size(width: 80, height: 24)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def as_size
+        Size.new(width:, height:)
+      end
+
+      # Returns a new Rect, centered horizontally within this rect based on the constraint.
+      #
+      # Modal dialogs and centered content need horizontal centering.
+      # Computing the left offset manually is error-prone.
+      #
+      # This method uses Layout to compute the centered position.
+      #
+      # [constraint] Constraint defining the width of the centered area.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 0, y: 0, width: 100, height: 24)
+      #   rect.centered_horizontally(Constraint.length(40))
+      #   # => Rect(x: 30, y: 0, width: 40, height: 24)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def centered_horizontally(constraint)
+        areas = Layout.split(self, direction: :horizontal, constraints: [constraint], flex: :center)
+        areas.first
+      end
+
+      # Returns a new Rect, centered vertically within this rect based on the constraint.
+      #
+      # Modal dialogs and centered content need vertical centering.
+      # Computing the top offset manually is error-prone.
+      #
+      # This method uses Layout to compute the centered position.
+      #
+      # [constraint] Constraint defining the height of the centered area.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 0, y: 0, width: 80, height: 100)
+      #   rect.centered_vertically(Constraint.length(20))
+      #   # => Rect(x: 0, y: 40, width: 80, height: 20)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def centered_vertically(constraint)
+        areas = Layout.split(self, direction: :vertical, constraints: [constraint], flex: :center)
+        areas.first
+      end
+
+      # Returns a new Rect, centered both horizontally and vertically within this rect.
+      #
+      # Modal dialogs often need exact centering on both axes.
+      # Computing both offsets manually is tedious.
+      #
+      # This method chains centered_horizontally and centered_vertically.
+      #
+      # [horizontal_constraint] Constraint defining the width of the centered area.
+      # [vertical_constraint] Constraint defining the height of the centered area.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 0, y: 0, width: 100, height: 100)
+      #   rect.centered(Constraint.length(40), Constraint.length(20))
+      #   # => Rect(x: 30, y: 40, width: 40, height: 20)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def centered(horizontal_constraint, vertical_constraint)
+        centered_horizontally(horizontal_constraint).centered_vertically(vertical_constraint)
+      end
+
+      # Ruby-idiomatic aliases (TIMTOWTDI)
+      alias position as_position
+      alias size as_size
     end
   end
 end

data/lib/ratatui_ruby/layout/size.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Layout
+    # Terminal 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.
+    #
+    # 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 in terminal columns.
+
+      ##
+      # :attr_reader: height
+      # Height in terminal rows.
+
+      # 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

@@ -10,6 +10,8 @@ module RatatuiRuby
   #
   # This module mirrors +ratatui::layout+ and contains:
   # - {Rect} — Rectangle geometry
+  # - {Position} — Terminal coordinates
+  # - {Size} — Terminal dimensions
   # - {Constraint} — Sizing rules
   # - {Layout} — Space distribution
   module Layout
@@ -17,5 +19,7 @@ module RatatuiRuby
 end
 
 require_relative "layout/rect"
+require_relative "layout/position"
+require_relative "layout/size"
 require_relative "layout/constraint"
 require_relative "layout/layout"