ratatui_ruby 0.4.0 → 0.6.0

data/lib/ratatui_ruby/schema/constraint.rb

@@ -4,90 +4,90 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Defines the sizing rule for a layout section.
+  # 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
+  #
+  #   Constraint.length(5)      # Exactly 5 cells
+  #   Constraint.percentage(50) # Half the available space
+  #   Constraint.min(10)        # At least 10 cells, maybe more
+  #   Constraint.fill(1)        # Fill remaining space (weight 1)
+  class Constraint < Data.define(:type, :value)
+    ##
+    # :attr_reader: type
+    # The type of constraint.
     #
-    # Flexible layouts need rules. You can't just place widgets at absolute coordinates; they must adapt to changing terminal sizes.
+    # <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.
     #
-    # This class defines the rules of engagement. It tells the layout engine exactly how much space a section requires relative to others.
+    #   Constraint.length(10) # 10 characters wide/high
     #
-    # Mix and match fixed lengths, percentages, ratios, and minimums. Build layouts that breathe.
+    # [v] Number of cells (Integer).
+    def self.length(v)
+      new(type: :length, value: Integer(v))
+    end
+
+    # Requests a percentage of available space.
     #
-    # === Examples
+    #   Constraint.percentage(25) # 25% of the area
     #
-    #   Constraint.length(5)      # Exactly 5 cells
-    #   Constraint.percentage(50) # Half the available space
-    #   Constraint.min(10)        # At least 10 cells, maybe more
-    #   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.
-      #
-      #   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.
-      #
-      #   Constraint.percentage(25) # 25% of the area
-      #
-      # [v] Percentage 0-100 (Integer).
-      def self.percentage(v)
-        new(type: :percentage, value: Integer(v))
-      end
+    # [v] Percentage 0-100 (Integer).
+    def self.percentage(v)
+      new(type: :percentage, value: Integer(v))
+    end
 
-      # Enforces a minimum size.
-      #
-      #   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 minimum size.
+    #
+    #   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.
-      #
-      #   Constraint.max(10) # At most 10 cells
-      #
-      # [v] Maximum cells (Integer).
-      def self.max(v)
-        new(type: :max, value: Integer(v))
-      end
+    # Enforces a maximum size.
+    #
+    #   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.
-      #
-      #   Constraint.fill(1) # Equal share
-      #   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
+    # Fills remaining space proportionally.
+    #
+    #   Constraint.fill(1) # Equal share
+    #   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.
-      #
-      #   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
+    # Requests a specific ratio of the total space.
+    #
+    #   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

data/lib/ratatui_ruby/schema/cursor.rb

@@ -4,32 +4,37 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Controls the terminal cursor position.
-    #
-    # Interfaces are not just output; they require input. Users need a visual cue—a blinking block or line—to know where their keystrokes will appear.
-    #
-    # This widget renders a ghost. It does not draw a character but instructs the terminal to place the hardware cursor at specific coordinates.
-    #
-    # Use it for text editors, input fields, or command prompts.
-    #
-    # === Examples
-    #
-    #   Cursor.new(x: 10, y: 5)
-    class Cursor < Data.define(:x, :y)
-      ##
-      # :attr_reader: x
-      # X coordinate (column).
+  # Controls the terminal cursor position.
+  #
+  # Interfaces are not just output; they require input. Users need a visual cue—a blinking block or line—to know where their keystrokes will appear.
+  #
+  # This widget renders a ghost. It does not draw a character but instructs the terminal to place the hardware cursor at specific coordinates.
+  #
+  # Use it for text editors, input fields, or command prompts.
+  #
+  # === Examples
+  #
+  #   Cursor.new(x: 10, y: 5)
+  #
+  # See also:
+  # - {Declarative implementation using Tree API}[link:/examples/app_login_form/app_rb.html]
+  # - {Component-based implementation using Frame API}[link:/examples/app_color_picker/app_rb.html]
+  # - RatatuiRuby::Frame#set_cursor_position (Frame API alternative)
+  class Cursor < Data.define(:x, :y)
+    ##
+    # :attr_reader: x
+    # X coordinate (column).
 
-      ##
-      # :attr_reader: y
-      # Y coordinate (row).
+    ##
+    # :attr_reader: y
+    # Y coordinate (row).
 
-      # Creates a new Cursor.
-      #
-      # [x] Integer.
-      # [y] Integer.
-      def initialize(x:, y:)
-        super(x: Integer(x), y: Integer(y))
-      end
+    # Creates a new Cursor.
+    #
+    # [x] Integer.
+    # [y] Integer.
+    def initialize(x:, y:)
+      super(x: Integer(x), y: Integer(y))
     end
+  end
 end

data/lib/ratatui_ruby/schema/gauge.rb

@@ -4,65 +4,67 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Displays a standard progress bar.
-    #
-    # Long-running tasks create anxiety. Users need to know that the system is working and how much is left to do.
-    #
-    # This widget visualizes completion. It fills a bar based on a percentage.
-    #
-    # Use it for downloads, installations, or processing jobs.
+  # Displays a standard progress bar.
+  #
+  # Long-running tasks create anxiety. Users need to know that the system is working and how much is left to do.
+  #
+  # This widget visualizes completion. It fills a bar based on a percentage.
+  #
+  # Use it for downloads, installations, or processing jobs.
+  #
+  # {rdoc-image:/doc/images/widget_gauge_demo.png}[link:/examples/widget_gauge_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_gauge_demo/app.rb
+  class Gauge < Data.define(:ratio, :label, :style, :gauge_style, :block, :use_unicode)
+    ##
+    # :attr_reader: ratio
+    # Progress ratio from 0.0 to 1.0.
+
+    ##
+    # :attr_reader: label
+    # Text label to display (optional).
     #
-    # === Examples
+    # Accepts String or Text::Span for rich styling.
     #
-    #   Gauge.new(
-    #     ratio: 0.75,
-    #     label: "75%",
-    #     gauge_style: Style.new(fg: :green)
-    #   )
-    class Gauge < Data.define(:ratio, :label, :style, :gauge_style, :block, :use_unicode)
-      ##
-      # :attr_reader: ratio
-      # Progress ratio from 0.0 to 1.0.
-
-      ##
-      # :attr_reader: label
-      # Text label to display (optional).
-      #
-      # If nil, it often displays the percentage automatically depending on renderer logic,
-      # but explicit labels are preferred.
+    # If nil, it often displays the percentage automatically depending on renderer logic,
+    # but explicit labels are preferred.
 
-      ##
-      # :attr_reader: style
-      # Base style applied to the entire gauge background (optional).
+    ##
+    # :attr_reader: style
+    # Base style applied to the entire gauge background (optional).
 
-      ##
-      # :attr_reader: gauge_style
-      # Style applied specifically to the filled bar portion (optional).
+    ##
+    # :attr_reader: gauge_style
+    # Style applied specifically to the filled bar portion (optional).
 
-      ##
-      # :attr_reader: block
-      # Optional wrapping block.
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
 
-      ##
-      # :attr_reader: use_unicode
-      # Whether to use Unicode block characters (true) or ASCII characters (false).
-      # Default is false (ASCII) to be conservative, though Ratatui defaults to true.
+    ##
+    # :attr_reader: use_unicode
+    # Whether to use Unicode block characters (true) or ASCII characters (false).
+    # Default is false (ASCII) to be conservative, though Ratatui defaults to true.
 
-      # Creates a new Gauge.
-      #
-      # [ratio] Float (0.0 - 1.0).
-      # [percent] Integer (0 - 100), alternative to ratio.
-      # [label] String (optional).
-      # [style] Style object for the background (optional).
-      # [gauge_style] Style object for the filled bar (optional).
-      # [block] Block widget (optional).
-      # [use_unicode] Boolean (default: true).
-      def initialize(ratio: nil, percent: nil, label: nil, style: nil, gauge_style: nil, block: nil, use_unicode: true)
-        if percent
-          ratio = Float(percent) / 100.0
-        end
-        ratio = Float(ratio || 0.0)
-        super(ratio:, label:, style:, gauge_style:, block:, use_unicode:)
+    # Creates a new Gauge.
+    #
+    # [ratio] Float (0.0 - 1.0).
+    # [percent] Integer (0 - 100), alternative to ratio.
+    # [label] String or Text::Span (optional).
+    # [style] Style object for the background (optional).
+    # [gauge_style] Style object for the filled bar (optional).
+    # [block] Block widget (optional).
+    # [use_unicode] Boolean (default: true).
+    def initialize(ratio: nil, percent: nil, label: nil, style: nil, gauge_style: nil, block: nil, use_unicode: true)
+      if percent
+        ratio = Float(percent) / 100.0
       end
+      ratio = Float(ratio || 0.0)
+      super(ratio:, label:, style:, gauge_style:, block:, use_unicode:)
     end
+  end
 end

data/lib/ratatui_ruby/schema/layout.rb

@@ -4,101 +4,101 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Divides an area into smaller chunks.
+  # 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.
     #
-    # Terminal screens vary in size. Hardcoded positions break when the window resizes. You need a way to organize space dynamically.
+    # Either <tt>:vertical</tt> (top to bottom) or <tt>:horizontal</tt> (left to right).
     #
-    # 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.
-    #
-    # === Examples
-    #
-    #   # A simple vertical split (Sidebar / Main)
-    #   Layout.new(
-    #     direction: :horizontal,
-    #     constraints: [
-    #       Constraint.length(20), # Sidebar
-    #       Constraint.min(0)      # Main content
-    #     ]
-    #   )
-    #
-    #   # Flex layout (Centering a block)
-    #   Layout.new(
-    #     direction: :vertical,
-    #     flex: :center,
-    #     constraints: [Constraint.length(10)], # A 10-row block centered vertically
-    #     children: [modal_block]
-    #   )
-    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
+    #   layout.direction # => :vertical
 
-      ##
-      # :attr_reader: constraints
-      # Array of rules defining section sizes.
-      #
-      # See RatatuiRuby::Constraint.
+    ##
+    # :attr_reader: constraints
+    # Array of rules defining section sizes.
+    #
+    # See RatatuiRuby::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: 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>.
+    ##
+    # :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
+    # :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
+    # 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.split(
-      #     area,
-      #     direction: :horizontal,
-      #     constraints: [Constraint.percentage(50), Constraint.percentage(50)]
-      #   )
-      #   left, right = rects
-      #
-      # [area]
-      #   The area to split (a Rect or any object responding to x, y, width, height).
-      # [direction]
-      #   <tt>:vertical</tt> or <tt>:horizontal</tt> (default: <tt>:vertical</tt>).
-      # [constraints]
-      #   Array of Constraint objects defining section sizes.
-      # [flex]
-      #   Flex mode for spacing (default: <tt>:legacy</tt>).
-      #
-      # Returns an Array of Rect objects.
-      def self.split(area, direction: :vertical, constraints:, flex: :legacy)
-        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]) }
+    # 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.split(
+    #     area,
+    #     direction: :horizontal,
+    #     constraints: [Constraint.percentage(50), 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