ratatui_ruby 0.3.1 → 0.4.0

data/lib/ratatui_ruby/schema/chart.rb

@@ -9,55 +9,159 @@ module RatatuiRuby
   # [bounds] Array<Float> [min, max]
   # [labels] Array<String>
   # [style] Style
-  class Axis < Data.define(:title, :bounds, :labels, :style)
-    # Creates a new Axis.
-    #
-    # [title] String
-    # [bounds] Array<Float> [min, max]
-    # [labels] Array<String>
-    # [style] Style
-    def initialize(title: "", bounds: [0.0, 10.0], labels: [], style: nil)
-      super
+  # [labels_alignment] Symbol (<tt>:left</tt>, <tt>:center</tt>, <tt>:right</tt>)
+    class Axis < Data.define(:title, :bounds, :labels, :style, :labels_alignment)
+      ##
+      # :attr_reader: title
+      # Label for the axis (String).
+
+      ##
+      # :attr_reader: bounds
+      # Range [min, max] (Array of Floats).
+
+      ##
+      # :attr_reader: labels
+      # Explicit labels for ticks (Array of Strings).
+
+      ##
+      # :attr_reader: style
+      # Style for axis lines/text.
+
+      ##
+      # :attr_reader: labels_alignment
+      # Alignment of axis labels (:left, :center, :right).
+
+      # Creates a new Axis.
+      #
+      # [title] String.
+      # [bounds] Array [min, max].
+      # [labels] Array of Strings.
+      # [style] Style.
+      # [labels_alignment] Symbol (:left, :center, :right).
+      def initialize(title: "", bounds: [0.0, 10.0], labels: [], style: nil, labels_alignment: nil)
+        super(
+          title: title,
+          bounds: [Float(bounds[0]), Float(bounds[1])],
+          labels: labels,
+          style: style,
+          labels_alignment: labels_alignment
+        )
+      end
     end
-  end
 
   # Defines a Dataset for a Chart.
   # [name] The name of the dataset.
   # [data] Array of arrays [[x, y], [x, y]] (Floats).
-  # [color] The color of the line.
-  # [marker] Symbol (:dot, :braille, :block, :bar)
-  # [graph_type] Symbol (:line, :scatter)
-  class Dataset < Data.define(:name, :data, :color, :marker, :graph_type)
-    # Creates a new Dataset.
-    #
-    # [name] The name of the dataset.
-    # [data] Array of arrays [[x, y], [x, y]] (Floats).
-    # [color] The color of the line.
-    # [marker] Symbol (:dot, :braille, :block, :bar)
-    # [graph_type] Symbol (:line, :scatter)
-    def initialize(name:, data:, color: "reset", marker: :dot, graph_type: :line)
-      super
+  # [style] The style of the line.
+  # [marker] Symbol (<tt>:dot</tt>, <tt>:braille</tt>, <tt>:block</tt>, <tt>:bar</tt>)
+  # [graph_type] Symbol (<tt>:line</tt>, <tt>:scatter</tt>)
+    class Dataset < Data.define(:name, :data, :style, :marker, :graph_type)
+      ##
+      # :attr_reader: name
+      # Name for logical identification or legend.
+
+      ##
+      # :attr_reader: data
+      # list of [x, y] coordinates.
+
+      ##
+      # :attr_reader: style
+      # Style applied to the dataset (Style).
+      #
+      # **Note**: Due to Ratatui's Chart widget design, only the foreground color (<tt>fg</tt>) is applied to markers in the chart area.
+      # The full style (including <tt>bg</tt> and <tt>modifiers</tt>) is displayed in the legend.
+      #
+      # Supports:
+      # - +fg+: Foreground color of markers (Symbol/Hex) - _applied to chart_
+      # - +bg+: Background color (Symbol/Hex) - _legend only_
+      # - +modifiers+: Array of effects (<tt>:bold</tt>, <tt>:dim</tt>, <tt>:italic</tt>, <tt>:underlined</tt>, <tt>:slow_blink</tt>, <tt>:rapid_blink</tt>, <tt>:reversed</tt>, <tt>:hidden</tt>, <tt>:crossed_out</tt>) - _legend only_
+
+      ##
+      # :attr_reader: marker
+      # Marker type (<tt>:dot</tt>, <tt>:braille</tt>).
+
+      ##
+      # :attr_reader: graph_type
+      # Type of graph (<tt>:line</tt>, <tt>:scatter</tt>).
+
+      # Creates a new Dataset.
+      #
+      # [name] String.
+      # [data] Array of [x, y] (Numeric, duck-typed via +to_f+).
+      # [style] Style.
+      # [marker] Symbol.
+      # [graph_type] Symbol.
+      def initialize(name:, data:, style: nil, marker: :dot, graph_type: :line)
+        coerced_data = data.map { |point| [Float(point[0]), Float(point[1])] }
+        super(name: name, data: coerced_data, style: style, marker: marker, graph_type: graph_type)
+      end
     end
-  end
 
-  # A generic Cartesian chart.
-  # [datasets] Array<Dataset>
-  # [x_axis] Axis
-  # [y_axis] Axis
-  # [block] Block
-  # [style] Style (base style)
-  class Chart < Data.define(:datasets, :x_axis, :y_axis, :block, :style)
-    # Creates a new Chart widget.
+    # Plots data points on a Cartesian coordinate system.
     #
-    # [datasets] Array<Dataset>
-    # [x_axis] Axis
-    # [y_axis] Axis
-    # [block] Block
-    # [style] Style (base style)
-    def initialize(datasets:, x_axis:, y_axis:, block: nil, style: nil)
-      super
+    # Trends and patterns are invisible in raw logs. You need to see the shape of the data to understand the story it tells.
+    #
+    # This widget plots X/Y coordinates. It supports multiple datasets, custom axes, and different marker types.
+    #
+    # Use it for analytics, scientific data, or monitoring metrics over time.
+    #
+    # === Examples
+    #
+    #   Chart.new(
+    #     datasets: [
+    #       Dataset.new(
+    #         name: "Requests",
+    #         data: [[0.0, 1.0], [1.0, 2.0], [2.0, 1.5]],
+    #         style: Style.new(fg: :yellow)
+    #       )
+    #     ],
+    #     x_axis: Axis.new(title: "Time", bounds: [0.0, 5.0]),
+    #     y_axis: Axis.new(title: "RPS", bounds: [0.0, 5.0]),
+    #     legend_position: :top_right
+    #   )
+    class Chart < Data.define(:datasets, :x_axis, :y_axis, :block, :style, :legend_position, :hidden_legend_constraints)
+      ##
+      # :attr_reader: datasets
+      # Array of Dataset objects to plot.
+
+      ##
+      # :attr_reader: x_axis
+      # Configuration for the X Axis.
+
+      ##
+      # :attr_reader: y_axis
+      # Configuration for the Y Axis.
+
+      ##
+      # :attr_reader: block
+      # Optional wrapping block.
+
+      ##
+      # :attr_reader: style
+      # Base style for the chart area.
+
+      ##
+      # :attr_reader: legend_position
+      # Position of the legend (<tt>:top_left</tt>, <tt>:top_right</tt>, <tt>:bottom_left</tt>, <tt>:bottom_right</tt>).
+
+      ##
+      # :attr_reader: hidden_legend_constraints
+      # Constraints for hiding the legend when the chart is too small (Array of [width, height]).
+
+
+      # Creates a new Chart widget.
+      #
+      # [datasets] Array of Datasets.
+      # [x_axis] X Axis config.
+      # [y_axis] Y Axis config.
+      # [block] Wrapper (optional).
+      # [style] Base style (optional).
+      # [legend_position] Symbol (<tt>:top_left</tt>, <tt>:top_right</tt>, <tt>:bottom_left</tt>, <tt>:bottom_right</tt>).
+      # [hidden_legend_constraints] Array of two Constraints [width, height] (optional).
+      def initialize(datasets:, x_axis:, y_axis:, block: nil, style: nil, legend_position: nil, hidden_legend_constraints: [])
+        super
+      end
     end
-  end
 
   # A complex chart widget. (Legacy/Alias for Chart)
   #
@@ -75,7 +179,13 @@ module RatatuiRuby
     # [y_bounds] Array of two Floats [min, max] for the Y-axis.
     # [block] Optional block widget to wrap the chart.
     def initialize(datasets:, x_labels: [], y_labels: [], y_bounds: [0.0, 100.0], block: nil)
-      super
+      super(
+        datasets: datasets,
+        x_labels: x_labels,
+        y_labels: y_labels,
+        y_bounds: [Float(y_bounds[0]), Float(y_bounds[1])],
+        block: block
+      )
     end
   end
 end

data/lib/ratatui_ruby/schema/clear.rb

@@ -4,80 +4,49 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A widget that clears (resets) the terminal buffer in the area it is rendered into.
-  #
-  # The Clear widget is essential for creating opaque popups and modals. Without it,
-  # background content or styles (like background colors) will "bleed through"
-  # empty spaces or transparent widgets.
-  #
-  # > [!TIP]
-  # > Use `Clear` to prevent "Style Bleed". If a widget rendered behind the popup
-  # > has a background color, widgets rendered on top with `Style.default` will
-  # > inherit that background color unless you `Clear` the area first.
-  #
-  # == Usage with Overlay
-  #
-  # Because RatatuiRuby uses an immediate-mode UI pattern, you must use {Overlay} to
-  # layer widgets properly. The typical pattern for creating an opaque popup is:
-  #
-  #   background = Paragraph.new(text: "Background content...")
-  #   popup = Paragraph.new(
-  #     text: "Popup content",
-  #     block: Block.new(title: "Popup", borders: [:all])
-  #   )
-  #
-  #   # Create an opaque popup by layering: background -> Clear -> popup
-  #   ui = Overlay.new(
-  #     layers: [
-  #       background,
-  #       Center.new(
-  #         child: Overlay.new(
-  #           layers: [
-  #             Clear.new,  # Erases background in this area
-  #             popup       # Draws on top of cleared area
-  #           ]
-  #         ),
-  #         width_percent: 50,
-  #         height_percent: 40
-  #       )
-  #     ]
-  #   )
-  #
-  # Without the Clear widget, the background text would be visible through the
-  # empty spaces in the popup.
-  #
-  # == Optional Block Parameter
-  #
-  # You can optionally provide a {Block} to draw borders around the cleared area:
-  #
-  #   Clear.new(block: Block.new(title: "Cleared Area", borders: [:all]))
-  #
-  # This is equivalent to:
-  #
-  #   Overlay.new(
-  #     layers: [
-  #       Clear.new,
-  #       Block.new(title: "Cleared Area", borders: [:all])
-  #     ]
-  #   )
-  #
-  # [block] Optional {Block} widget to render on top of the cleared area.
-  #
-  # @see Overlay
-  # @see Center
-  # @see Block
-  class Clear < Data.define(:block)
-    # Creates a new Clear widget.
+    # Resets the terminal buffer for a specific area.
     #
-    # @param block [Block, nil] Optional block widget to render on top of the cleared area.
+    # Painting in a terminal is additive. New content draws over old content. If the new content has transparency
+    # or empty spaces, the old content "bleeds" through. This ruins popups and modals.
     #
-    # @example Basic usage
-    #   Clear.new
+    # This widget wipes the slate clean. It resets all cells in its area to their default state (spaces with default background).
     #
-    # @example With a border
-    #   Clear.new(block: Block.new(title: "Modal", borders: [:all]))
-    def initialize(block: nil)
-      super
+    # Use it as the first layer in an Overlay stack when building popups. Ensure your floating windows are truly opaque.
+    #
+    # === Examples
+    #
+    #   # Opaque Popup Construction
+    #   Overlay.new(
+    #     layers: [
+    #       MainUI.new,
+    #       Center.new(
+    #         child: Overlay.new(
+    #           layers: [
+    #             Clear.new, # Wipe the area first
+    #             Block.new(title: "Modal", borders: [:all])
+    #           ]
+    #         ),
+    #         width_percent: 50,
+    #         height_percent: 50
+    #       )
+    #     ]
+    #   )
+    #
+    #   # Shortcut: rendering a block directly
+    #   Clear.new(block: Block.new(title: "Cleared area", borders: [:all]))
+    class Clear < Data.define(:block)
+      ##
+      # :attr_reader: block
+      # Optional Block to render after clearing.
+      #
+      # If provided, the borders/title of this block are drawn on top of the cleared area.
+
+      # Creates a new Clear widget.
+      #
+      # [block]
+      #   Block widget to render (optional).
+      def initialize(block: nil)
+        super
+      end
     end
-  end
 end

data/lib/ratatui_ruby/schema/constraint.rb

@@ -4,30 +4,90 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # Defines constraints for layout sections or table columns.
-  #
-  # [type] The type of constraint (:length, :percentage, :min).
-  # [value] The numeric value associated with the constraint.
-  class Constraint < Data.define(:type, :value)
-    # Creates a length constraint (fixed number of cells).
+    # Defines the sizing rule for a layout section.
     #
-    # [v] The length value in cells.
-    def self.length(v)
-      new(type: :length, value: v)
-    end
-
-    # Creates a percentage constraint (portion of available space).
+    # Flexible layouts need rules. You can't just place widgets at absolute coordinates; they must adapt to changing terminal sizes.
     #
-    # [v] The percentage value (0-100).
-    def self.percentage(v)
-      new(type: :percentage, value: v)
-    end
-
-    # Creates a minimum size constraint.
+    # This class defines the rules of engagement. It tells the layout engine exactly how much space a section requires relative to others.
     #
-    # [v] The minimum number of cells.
-    def self.min(v)
-      new(type: :min, value: v)
+    # 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.
+      #
+      # <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
+
+      # 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
+
+      # 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
     end
-  end
 end

data/lib/ratatui_ruby/schema/cursor.rb

@@ -4,14 +4,32 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # Sets the terminal cursor position (ghost widget).
-  #
-  # [x] the x coordinate.
-  # [y] the y coordinate.
-  class Cursor < Data.define(:x, :y)
-    # Creates a new Cursor.
+    # Controls the terminal cursor position.
     #
-    # [x] the x coordinate.
-    # [y] the y coordinate.
-  end
+    # 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).
+
+      ##
+      # :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
+    end
 end

data/lib/ratatui_ruby/schema/draw.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Draw commands for custom widgets.
+  #
+  # Custom widgets return an array of Draw commands instead of writing directly to a buffer.
+  # This keeps all pointers safely inside Rust while Ruby works with pure data.
+  #
+  # === Example
+  #
+  #   class MyWidget
+  #     def render(area)
+  #       [
+  #         RatatuiRuby::Draw.string(area.x, area.y, "Hello", {fg: :red}),
+  #         RatatuiRuby::Draw.cell(area.x + 6, area.y, RatatuiRuby::Cell.char("!"))
+  #       ]
+  #     end
+  #   end
+  module Draw
+    # Command to draw a string at the given coordinates.
+    #
+    # [x] X coordinate (absolute).
+    # [y] Y coordinate (absolute).
+    # [string] The text to draw.
+    # [style] Style hash or Style object.
+    StringCmd = Data.define(:x, :y, :string, :style)
+
+    # Command to draw a cell at the given coordinates.
+    #
+    # [x] X coordinate (absolute).
+    # [y] Y coordinate (absolute).
+    # [cell] The Cell to draw.
+    CellCmd = Data.define(:x, :y, :cell)
+
+    # Creates a string draw command.
+    #
+    # [x] X coordinate (Integer, duck-typed via +to_int+).
+    # [y] Y coordinate (Integer, duck-typed via +to_int+).
+    # [string] Text to draw.
+    # [style] Optional style (Hash or Style).
+    def self.string(x, y, string, style = {}) = StringCmd.new(x: Integer(x), y: Integer(y), string:, style:)
+
+    # Creates a cell draw command.
+    #
+    # [x] X coordinate (Integer, duck-typed via +to_int+).
+    # [y] Y coordinate (Integer, duck-typed via +to_int+).
+    # [cell] Cell to draw.
+    def self.cell(x, y, cell) = CellCmd.new(x: Integer(x), y: Integer(y), cell:)
+  end
+end

data/lib/ratatui_ruby/schema/gauge.rb

@@ -4,21 +4,65 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A widget that displays a progress bar.
-  #
-  # [ratio] A value between 0.0 and 1.0 representing the progress.
-  # [label] An optional string to display on the gauge.
-  # [style] The Style object to apply to the gauge.
-  # [block] An optional Block widget to wrap the gauge.
-  class Gauge < Data.define(:ratio, :label, :style, :block)
-    # Creates a new Gauge.
+    # Displays a standard progress bar.
     #
-    # [ratio] A value between 0.0 and 1.0 representing the progress.
-    # [label] An optional string to display on the gauge.
-    # [style] The Style object to apply to the gauge.
-    # [block] An optional Block widget to wrap the gauge.
-    def initialize(ratio: 0.0, label: nil, style: Style.default, block: nil)
-      super
+    # 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.
+    #
+    # === Examples
+    #
+    #   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.
+
+      ##
+      # :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: 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.
+
+      # 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:)
+      end
     end
-  end
 end