ratatui_ruby 0.6.0 → 0.7.0

data/lib/ratatui_ruby/buffer/cell.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Buffer
+    # Represents a single cell in the terminal buffer.
+    #
+    # A terminal grid is made of cells. Each cell contains a character (symbol) and styling (colors, modifiers).
+    # When testing, you often need to verify that a specific cell renders correctly.
+    #
+    # This object encapsulates that state. It provides predicate methods for modifiers, making assertions readable.
+    #
+    # Use it to inspect the visual state of your application in tests.
+    #
+    # === Examples
+    #
+    #   cell = RatatuiRuby.get_cell_at(0, 0)
+    #   cell.char   # => "H"
+    #   cell.fg     # => :red
+    #   cell.bold?  # => true
+    #
+    class Cell
+      # The character displayed in the cell.
+      #
+      # Named to match Ratatui's Cell::symbol() method.
+      attr_reader :symbol
+
+      # Alias for Rubyists who prefer a shorter name.
+      alias char symbol
+
+      # The foreground color of the cell (e.g., :red, :blue, "#ff0000").
+      attr_reader :fg
+
+      # The background color of the cell (e.g., :black, nil).
+      attr_reader :bg
+
+      # The list of active modifiers (e.g., ["bold", "italic"]).
+      attr_reader :modifiers
+
+      # Returns an empty cell (space character, no styles).
+      #
+      # === Example
+      #
+      #   Buffer::Cell.empty # => #<RatatuiRuby::Buffer::Cell char=" ">
+      #
+      def self.empty
+        new(symbol: " ", fg: nil, bg: nil, modifiers: [])
+      end
+
+      # Returns a default cell (alias for empty).
+      #
+      # === Example
+      #
+      #   Buffer::Cell.default # => #<RatatuiRuby::Buffer::Cell char=" ">
+      #
+      def self.default
+        empty
+      end
+
+      # Returns a cell with a specific character and no styles.
+      #
+      # [symbol] String (single character).
+      #
+      # === Example
+      #
+      #   Buffer::Cell.symbol("X") # => #<RatatuiRuby::Buffer::Cell symbol="X">
+      #
+      def self.symbol(symbol)
+        new(symbol:, fg: nil, bg: nil, modifiers: [])
+      end
+
+      # Alias for Rubyists who prefer a shorter name.
+      def self.char(char)
+        symbol(char)
+      end
+
+      # Creates a new Cell.
+      #
+      # [symbol] String (single character). Aliased as <tt>char:</tt>.
+      # [fg] Symbol or String (nullable).
+      # [bg] Symbol or String (nullable).
+      # [modifiers] Array of Strings.
+      def initialize(symbol: nil, char: nil, fg: nil, bg: nil, modifiers: [])
+        @symbol = (symbol || char || " ").freeze
+        @fg = fg&.freeze
+        @bg = bg&.freeze
+        @modifiers = modifiers.map(&:freeze).freeze
+        freeze
+      end
+
+      # Returns true if the cell has the bold modifier.
+      def bold?
+        modifiers.include?("bold")
+      end
+
+      # Returns true if the cell has the dim modifier.
+      def dim?
+        modifiers.include?("dim")
+      end
+
+      # Returns true if the cell has the italic modifier.
+      def italic?
+        modifiers.include?("italic")
+      end
+
+      # Returns true if the cell has the underlined modifier.
+      def underlined?
+        modifiers.include?("underlined")
+      end
+
+      # Returns true if the cell has the slow_blink modifier.
+      def slow_blink?
+        modifiers.include?("slow_blink")
+      end
+
+      # Returns true if the cell has the rapid_blink modifier.
+      def rapid_blink?
+        modifiers.include?("rapid_blink")
+      end
+
+      # Returns true if the cell has the reversed modifier.
+      def reversed?
+        modifiers.include?("reversed")
+      end
+
+      # Returns true if the cell has the hidden modifier.
+      def hidden?
+        modifiers.include?("hidden")
+      end
+
+      # Returns true if the cell has the crossed_out modifier.
+      def crossed_out?
+        modifiers.include?("crossed_out")
+      end
+
+      # Checks equality with another Cell.
+      def ==(other)
+        other.is_a?(Cell) &&
+          char == other.char &&
+          fg == other.fg &&
+          bg == other.bg &&
+          modifiers == other.modifiers
+      end
+
+      # Returns a string representation of the cell.
+      def inspect
+        parts = ["symbol=#{symbol.inspect}"]
+        parts << "fg=#{fg.inspect}" if fg
+        parts << "bg=#{bg.inspect}" if bg
+        parts << "modifiers=#{modifiers.inspect}" unless modifiers.empty?
+        "#<#{self.class} #{parts.join(' ')}>"
+      end
+
+      # Returns the cell's character.
+      def to_s
+        symbol
+      end
+
+      # Support for pattern matching.
+      # Supports both <tt>:symbol</tt> and <tt>:char</tt> keys.
+      def deconstruct_keys(keys)
+        { symbol:, char: symbol, fg:, bg:, modifiers: }
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/buffer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Buffer primitives for terminal cell inspection.
+  #
+  # This module mirrors +ratatui::buffer+ and contains:
+  # - {Cell} — Single terminal cell (for inspection)
+  module Buffer
+  end
+end
+
+require_relative "buffer/cell"

data/lib/ratatui_ruby/frame.rb

@@ -21,7 +21,7 @@ module RatatuiRuby
   # 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
+  # fine. However, do not include it in immutable Models/Messages or pass
   # it to other Ractors. Frame is only valid during the draw block's execution.
   #
   # === Examples
@@ -29,7 +29,7 @@ module RatatuiRuby
   # Basic usage with a single widget:
   #
   #   RatatuiRuby.draw do |frame|
-  #     paragraph = RatatuiRuby::Paragraph.new(text: "Hello, world!")
+  #     paragraph = RatatuiRuby::Widgets::Paragraph.new(text: "Hello, world!")
   #     frame.render_widget(paragraph, frame.area)
   #   end
   #
@@ -40,8 +40,8 @@ module RatatuiRuby
   #       frame.area,
   #       direction: :horizontal,
   #       constraints: [
-  #         RatatuiRuby::Constraint.length(20),
-  #         RatatuiRuby::Constraint.fill(1)
+  #         RatatuiRuby::Layout::Constraint.length(20),
+  #         RatatuiRuby::Layout::Constraint.fill(1)
   #       ]
   #     )
   #
@@ -86,7 +86,7 @@ module RatatuiRuby
     # === Example
     #
     #   RatatuiRuby.draw do |frame|
-    #     para = RatatuiRuby::Paragraph.new(text: "Content")
+    #     para = RatatuiRuby::Widgets::Paragraph.new(text: "Content")
     #     frame.render_widget(para, frame.area)
     #   end
     #
@@ -122,7 +122,7 @@ module RatatuiRuby
     #   @list_state = RatatuiRuby::ListState.new
     #
     #   RatatuiRuby.draw do |frame|
-    #     list = RatatuiRuby::List.new(items: ["A", "B"])
+    #     list = RatatuiRuby::Widgets::List.new(items: ["A", "B"])
     #     frame.render_stateful_widget(list, frame.area, @list_state)
     #   end
     #
@@ -160,9 +160,9 @@ module RatatuiRuby
     #
     #   RatatuiRuby.draw do |frame|
     #     # Render the input field
-    #     prompt = RatatuiRuby::Paragraph.new(
+    #     prompt = RatatuiRuby::Widgets::Paragraph.new(
     #       text: "#{PREFIX}#{username} ]",
-    #       block: RatatuiRuby::Block.new(borders: :all)
+    #       block: RatatuiRuby::Widgets::Block.new(borders: :all)
     #     )
     #     frame.render_widget(prompt, frame.area)
     #

data/lib/ratatui_ruby/layout/constraint.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Layout
+    # Defines the sizing rule for a layout section.
+    #
+    # Flexible layouts need rules. You can't just place widgets at absolute coordinates; they must adapt to changing terminal sizes.
+    #
+    # This class defines the rules of engagement. It tells the layout engine exactly how much space a section requires relative to others.
+    #
+    # Mix and match fixed lengths, percentages, ratios, and minimums. Build layouts that breathe.
+    #
+    # === Examples
+    #
+    #   Layout::Constraint.length(5)      # Exactly 5 cells
+    #   Layout::Constraint.percentage(50) # Half the available space
+    #   Layout::Constraint.min(10)        # At least 10 cells, maybe more
+    #   Layout::Constraint.fill(1)        # Fill remaining space (weight 1)
+    class Constraint < Data.define(:type, :value)
+      ##
+      # :attr_reader: type
+      # The type of constraint.
+      #
+      # <tt>:length</tt>, <tt>:percentage</tt>, <tt>:min</tt>, <tt>:max</tt>, <tt>:fill</tt>, or <tt>:ratio</tt>.
+
+      ##
+      # :attr_reader: value
+      # The numeric value (or array for ratio) associated with the rule.
+
+      # Requests a fixed size.
+      #
+      #   Layout::Constraint.length(10) # 10 characters wide/high
+      #
+      # [v] Number of cells (Integer).
+      def self.length(v)
+        new(type: :length, value: Integer(v))
+      end
+
+      # Requests a percentage of available space.
+      #
+      #   Layout::Constraint.percentage(25) # 25% of the area
+      #
+      # [v] Percentage 0-100 (Integer).
+      def self.percentage(v)
+        new(type: :percentage, value: Integer(v))
+      end
+
+      # Enforces a minimum size.
+      #
+      #   Layout::Constraint.min(5) # At least 5 cells
+      #
+      # This section will grow if space permits, but never shrink below +v+.
+      #
+      # [v] Minimum cells (Integer).
+      def self.min(v)
+        new(type: :min, value: Integer(v))
+      end
+
+      # Enforces a maximum size.
+      #
+      #   Layout::Constraint.max(10) # At most 10 cells
+      #
+      # [v] Maximum cells (Integer).
+      def self.max(v)
+        new(type: :max, value: Integer(v))
+      end
+
+      # Fills remaining space proportionally.
+      #
+      #   Layout::Constraint.fill(1) # Equal share
+      #   Layout::Constraint.fill(2) # Double share
+      #
+      # Fill constraints distribute any space left after satisfying strict rules.
+      # They behave like flex-grow. A fill(2) takes twice as much space as a fill(1).
+      #
+      # [v] Proportional weight (Integer, default: 1).
+      def self.fill(v = 1)
+        new(type: :fill, value: Integer(v))
+      end
+
+      # Requests a specific ratio of the total space.
+      #
+      #   Layout::Constraint.ratio(1, 3) # 1/3rd of the area
+      #
+      # [numerator] Top part of fraction (Integer).
+      # [denominator] Bottom part of fraction (Integer).
+      def self.ratio(numerator, denominator)
+        new(type: :ratio, value: [Integer(numerator), Integer(denominator)])
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/layout/layout.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Layout
+    # Divides an area into smaller chunks.
+    #
+    # Terminal screens vary in size. Hardcoded positions break when the window resizes. You need a way to organize space dynamically.
+    #
+    # This class manages geometry. It splits a given area into multiple sections based on a list of constraints.
+    #
+    # Use layouts to build responsive grids. Stack sections vertically for a sidebar-main structure. Partition them horizontally for headers and footers. Let the layout engine do the math.
+    #
+    # {rdoc-image:/doc/images/widget_layout_split.png}[link:/examples/widget_layout_split/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_layout_split/app.rb
+    class Layout < Data.define(:direction, :constraints, :children, :flex)
+      ##
+      # :attr_reader: direction
+      # Direction of the split.
+      #
+      # Either <tt>:vertical</tt> (top to bottom) or <tt>:horizontal</tt> (left to right).
+      #
+      #   layout.direction # => :vertical
+
+      ##
+      # :attr_reader: constraints
+      # Array of rules defining section sizes.
+      #
+      # See RatatuiRuby::Layout::Constraint.
+
+      ##
+      # :attr_reader: children
+      # Widgets to render in each section (optional).
+      #
+      # If provided, `children[i]` is rendered into the area defined by `constraints[i]`.
+
+      ##
+      # :attr_reader: flex
+      # Strategy for distributing extra space.
+      #
+      # One of <tt>:legacy</tt>, <tt>:start</tt>, <tt>:center</tt>, <tt>:end</tt>, <tt>:space_between</tt>, <tt>:space_around</tt>.
+
+      # :nodoc:
+      FLEX_MODES = %i[legacy start center end space_between space_around space_evenly].freeze
+
+      # Creates a new Layout.
+      #
+      # [direction]
+      #   <tt>:vertical</tt> or <tt>:horizontal</tt> (default: <tt>:vertical</tt>).
+      # [constraints]
+      #   list of Constraint objects.
+      # [children]
+      #   List of widgets to render (optional).
+      # [flex]
+      #   Flex mode for spacing (default: <tt>:legacy</tt>).
+      def initialize(direction: :vertical, constraints: [], children: [], flex: :legacy)
+        super
+      end
+
+      # Splits an area into multiple rectangles.
+      #
+      # This is a pure calculation helper for hit testing. It computes where
+      # widgets *would* be placed without actually rendering them.
+      #
+      #   rects = Layout::Layout.split(
+      #     area,
+      #     direction: :horizontal,
+      #     constraints: [Layout::Constraint.percentage(50), Layout::Constraint.percentage(50)]
+      #   )
+      #   left, right = rects
+      #
+      # [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]
+      #   Flex mode for spacing (default: <tt>:legacy</tt>).
+      #
+      # 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)
+          )
+        end
+        raw_rects = _split(area, direction, constraints, flex)
+        raw_rects.map { |r| Rect.new(x: r[:x], y: r[:y], width: r[:width], height: r[:height]) }
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/layout/rect.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Layout
+    # Defines a rectangular area in the terminal grid.
+    #
+    # Geometry management involves passing groups of four integers (`x, y, width, height`) repeatedly.
+    # This is verbose and prone to parameter mismatch errors.
+    #
+    # This class encapsulates the geometry. It provides a standard primitive for passing area definitions
+    # between layout engines and rendering functions.
+    #
+    # Use it when manual positioning is required or when querying layout results.
+    #
+    # === Examples
+    #
+    #   area = Layout::Rect.new(x: 0, y: 0, width: 80, height: 24)
+    #   puts area.width # => 80
+    class Rect < Data.define(:x, :y, :width, :height)
+      ##
+      # :attr_reader: x
+      # X coordinate (column) of the top-left corner (Integer, coerced via +to_int+ or +to_i+).
+
+      ##
+      # :attr_reader: y
+      # Y coordinate (row) of the top-left corner (Integer, coerced via +to_int+ or +to_i+).
+
+      ##
+      # :attr_reader: width
+      # Width in characters (Integer, coerced via +to_int+ or +to_i+).
+
+      ##
+      # :attr_reader: height
+      # Height in characters (Integer, coerced via +to_int+ or +to_i+).
+
+      # Creates a new Rect.
+      #
+      # All parameters accept any object responding to +to_int+ or +to_i+ (duck-typed).
+      #
+      # [x] Column index (Numeric).
+      # [y] Row index (Numeric).
+      # [width] Width in columns (Numeric).
+      # [height] Height in rows (Numeric).
+      def initialize(x: 0, y: 0, width: 0, height: 0)
+        super(
+          x: Integer(x),
+          y: Integer(y),
+          width: Integer(width),
+          height: Integer(height)
+        )
+      end
+
+      # Tests whether a point is inside this rectangle.
+      #
+      # Essential for hit testing mouse clicks against layout regions.
+      #
+      #   area = Layout::Rect.new(x: 10, y: 5, width: 20, height: 10)
+      #   area.contains?(15, 8) # => true
+      #   area.contains?(5, 8)  # => false
+      #
+      # [px]
+      #   X coordinate to test (column).
+      # [py]
+      #   Y coordinate to test (row).
+      #
+      # Returns true if the point (px, py) is within the rectangle bounds.
+      def contains?(px, py)
+        px >= x && px < x + width && py >= y && py < y + height
+      end
+
+      # Tests whether this rectangle overlaps with another.
+      #
+      # Essential for determining if a widget is visible within a viewport or clipping area.
+      #
+      #   viewport = Layout::Rect.new(x: 0, y: 0, width: 80, height: 24)
+      #   widget = Layout::Rect.new(x: 70, y: 20, width: 20, height: 10)
+      #   viewport.intersects?(widget) # => true (partial overlap)
+      #
+      # [other]
+      #   Another Rect to test against.
+      #
+      # Returns true if the rectangles overlap.
+      def intersects?(other)
+        x < other.x + other.width &&
+          x + width > other.x &&
+          y < other.y + other.height &&
+          y + height > other.y
+      end
+
+      # Returns the overlapping area between this rectangle and another.
+      #
+      # Essential for calculating visible portions of widgets inside scroll views.
+      #
+      #   viewport = Layout::Rect.new(x: 0, y: 0, width: 80, height: 24)
+      #   widget = Layout::Rect.new(x: 70, y: 20, width: 20, height: 10)
+      #   visible = viewport.intersection(widget)
+      #   # => Rect(x: 70, y: 20, width: 10, height: 4)
+      #
+      # [other]
+      #   Another Rect to intersect with.
+      #
+      # Returns a new Rect representing the intersection, or +nil+ if no overlap.
+      def intersection(other)
+        return nil unless intersects?(other)
+
+        new_x = [x, other.x].max
+        new_y = [y, other.y].max
+        new_right = [x + width, other.x + other.width].min
+        new_bottom = [y + height, other.y + other.height].min
+
+        Rect.new(x: new_x, y: new_y, width: new_right - new_x, height: new_bottom - new_y)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/layout.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Layout primitives for geometry and space distribution.
+  #
+  # This module mirrors +ratatui::layout+ and contains:
+  # - {Rect} — Rectangle geometry
+  # - {Constraint} — Sizing rules
+  # - {Layout} — Space distribution
+  module Layout
+  end
+end
+
+require_relative "layout/rect"
+require_relative "layout/constraint"
+require_relative "layout/layout"

data/lib/ratatui_ruby/list_state.rb

@@ -18,7 +18,7 @@ module RatatuiRuby
   # == Thread/Ractor Safety
   #
   # ListState is *not* Ractor-shareable. It contains mutable internal state.
-  # Store it in instance variables, not in immutable TEA Models.
+  # Store it in instance variables, not in immutable Models.
   #
   # == Example
   #
@@ -26,7 +26,7 @@ module RatatuiRuby
   #   @list_state.select(2) # Select third item
   #
   #   RatatuiRuby.draw do |frame|
-  #     list = RatatuiRuby::List.new(items: ["A", "B", "C", "D", "E"])
+  #     list = RatatuiRuby::Widgets::List.new(items: ["A", "B", "C", "D", "E"])
   #     frame.render_stateful_widget(list, frame.area, @list_state)
   #   end
   #

data/lib/ratatui_ruby/schema/layout.rb

@@ -32,7 +32,7 @@ module RatatuiRuby
     # :attr_reader: constraints
     # Array of rules defining section sizes.
     #
-    # See RatatuiRuby::Constraint.
+    # See RatatuiRuby::Layout::Constraint.
 
     ##
     # :attr_reader: children

data/lib/ratatui_ruby/schema/row.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # A styled table row combining cells with optional row-level styling.
+  #
+  # By default, Table rows are arrays of cell content. For more control over styling
+  # individual rows, wrap the cells in a Row object to apply row-level style.
+  #
+  # The cells can be Strings, Text::Spans, Text::Lines, Paragraphs, or Cells.
+  # The style applies to the entire row background.
+  #
+  # === Examples
+  #
+  #   # Row with red background
+  #   Row.new(cells: ["Error", "Something went wrong"], style: Style.new(bg: :red))
+  #
+  #   # Row with styled cells and custom height
+  #   Row.new(
+  #     cells: [
+  #       Text::Span.new(content: "Status", style: Style.new(modifiers: [:bold])),
+  #       Text::Span.new(content: "OK", style: Style.new(fg: :green))
+  #     ],
+  #     height: 2
+  #   )
+  class Row < Data.define(:cells, :style, :height, :top_margin, :bottom_margin)
+    ##
+    # :attr_reader: cells
+    # The cells to display (Array of Strings, Text::Spans, Text::Lines, Paragraphs, or Cells).
+
+    ##
+    # :attr_reader: style
+    # The style to apply to the row (optional Style).
+
+    ##
+    # :attr_reader: height
+    # Fixed row height in lines (optional Integer).
+
+    ##
+    # :attr_reader: top_margin
+    # Margin above the row in lines (optional Integer).
+
+    ##
+    # :attr_reader: bottom_margin
+    # Margin below the row in lines (optional Integer).
+
+    # Creates a new Row.
+    #
+    # [cells] Array of Strings, Text::Spans, Text::Lines, Paragraphs, or Cells.
+    # [style] Style object (optional).
+    # [height] Integer for fixed height (optional).
+    # [top_margin] Integer for top margin (optional).
+    # [bottom_margin] Integer for bottom margin (optional).
+    def initialize(cells:, style: nil, height: nil, top_margin: nil, bottom_margin: nil)
+      super(
+        cells:,
+        style:,
+        height: height.nil? ? nil : Integer(height),
+        top_margin: top_margin.nil? ? nil : Integer(top_margin),
+        bottom_margin: bottom_margin.nil? ? nil : Integer(bottom_margin)
+      )
+    end
+  end
+end