ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/labs.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Experimental lab features.
+  module Labs
+    @enabled_lab = nil #: Symbol?
+
+    class << self
+      # Returns whether the specified lab is enabled.
+      def enabled?(lab)
+        @enabled_lab == lab.to_sym.downcase
+      end
+
+      # Enables a lab programmatically.
+      def enable!(lab)
+        @enabled_lab = lab.to_sym.downcase
+      end
+
+      # Resets all labs (for testing only).
+      def reset!
+        @enabled_lab = nil
+        @warned = false
+      end
+
+      # Emits experimental warning once per session.
+      def warn_once!(feature_name)
+        return if @warned
+
+        RatatuiRuby.warn_experimental_feature(feature_name)
+        @warned = true
+      end
+    end
+  end
+end
+
+# Auto-enable from environment variable
+if (lab = ENV["RR_LABS"])
+  RatatuiRuby::Labs.enable!(lab)
+end
+
+require_relative "labs/a11y"
+require_relative "labs/frame_a11y_capture"

data/lib/ratatui_ruby/layout/alignment.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Layout
+    # Horizontal content alignment within a layout area.
+    #
+    # Use these constants for discoverability, or pass symbols directly
+    # (<tt>:left</tt>, <tt>:center</tt>, <tt>:right</tt>).
+    #
+    # Mirrors +ratatui::layout::HorizontalAlignment+ from upstream Ratatui.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # Using constants (discoverable)
+    #   paragraph = Paragraph.new(
+    #     text: "Hello",
+    #     alignment: HorizontalAlignment::CENTER
+    #   )
+    #
+    #   # Using symbols directly (idiomatic Ruby)
+    #   paragraph = Paragraph.new(text: "Hello", alignment: :center)
+    #--
+    # SPDX-SnippetEnd
+    #++
+    module HorizontalAlignment
+      # Align content to the left edge.
+      LEFT = :left
+
+      # Align content to the center.
+      CENTER = :center
+
+      # Align content to the right edge.
+      RIGHT = :right
+
+      # All valid alignment values.
+      ALL = [LEFT, CENTER, RIGHT].freeze
+    end
+
+    # Vertical content alignment within a layout area.
+    #
+    # Use these constants for discoverability, or pass symbols directly
+    # (<tt>:top</tt>, <tt>:center</tt>, <tt>:bottom</tt>).
+    #
+    # Mirrors +ratatui::layout::VerticalAlignment+ from upstream Ratatui.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # Using constants (discoverable)
+    #   widget.vertical_alignment = VerticalAlignment::CENTER
+    #
+    #   # Using symbols directly (idiomatic Ruby)
+    #   widget.vertical_alignment = :center
+    #--
+    # SPDX-SnippetEnd
+    #++
+    module VerticalAlignment
+      # Align content to the top edge.
+      TOP = :top
+
+      # Align content to the center.
+      CENTER = :center
+
+      # Align content to the bottom edge.
+      BOTTOM = :bottom
+
+      # All valid alignment values.
+      ALL = [TOP, CENTER, BOTTOM].freeze
+    end
+
+    # Type alias for HorizontalAlignment.
+    #
+    # Provided for upstream API parity. In Ratatui, +Alignment+ was the
+    # original name before +HorizontalAlignment+ was introduced in v0.30.0.
+    Alignment = HorizontalAlignment
+  end
+end

data/lib/ratatui_ruby/layout/constraint.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-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
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   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)
+    #--
+    # SPDX-SnippetEnd
+    #++
+    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.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Layout::Constraint.length(10) # 10 characters wide/high
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [v] Number of cells (Integer).
+      def self.length(v)
+        new(type: :length, value: Integer(v))
+      end
+
+      # Requests a percentage of available space.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Layout::Constraint.percentage(25) # 25% of the area
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [v] Percentage 0-100 (Integer).
+      def self.percentage(v)
+        new(type: :percentage, value: Integer(v))
+      end
+
+      # Enforces a minimum size.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Layout::Constraint.min(5) # At least 5 cells
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # 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.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Layout::Constraint.max(10) # At most 10 cells
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [v] Maximum cells (Integer).
+      def self.max(v)
+        new(type: :max, value: Integer(v))
+      end
+
+      # Fills remaining space proportionally.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Layout::Constraint.fill(1) # Equal share
+      #   Layout::Constraint.fill(2) # Double share
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # 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.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Layout::Constraint.ratio(1, 3) # 1/3rd of the area
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [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
+
+      # 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