ratatui_ruby 0.4.0 → 0.5.0

data/lib/ratatui_ruby/schema/canvas.rb

@@ -65,7 +65,7 @@ module RatatuiRuby
       # [y2] End Y (Numeric).
       # [color] Line color (Symbol).
       def initialize(x1:, y1:, x2:, y2:, color:)
-        super(x1: Float(x1), y1: Float(y1), x2: Float(x2), y2: Float(y2), color: color)
+        super(x1: Float(x1), y1: Float(y1), x2: Float(x2), y2: Float(y2), color:)
       end
     end
 
@@ -105,7 +105,7 @@ module RatatuiRuby
       # [height] Height (Numeric).
       # [color] Color (Symbol).
       def initialize(x:, y:, width:, height:, color:)
-        super(x: Float(x), y: Float(y), width: Float(width), height: Float(height), color: color)
+        super(x: Float(x), y: Float(y), width: Float(width), height: Float(height), color:)
       end
     end
 
@@ -139,7 +139,7 @@ module RatatuiRuby
       # [radius] Radius (Numeric).
       # [color] Color (Symbol).
       def initialize(x:, y:, radius:, color:)
-        super(x: Float(x), y: Float(y), radius: Float(radius), color: color)
+        super(x: Float(x), y: Float(y), radius: Float(radius), color:)
       end
     end
 
@@ -158,72 +158,72 @@ module RatatuiRuby
     end
   end
 
-    # Provides a drawing surface for custom shapes.
+  # Provides a drawing surface for custom shapes.
+  #
+  # Standard widgets cover standard cases. Sometimes you need to draw a map, a custom diagram, or a game.
+  # Character grids are too coarse for fine detail.
+  #
+  # This widget increases the resolution. It uses Braille patterns or block characters to create a "sub-pixel" drawing surface.
+  #
+  # Use it to implement free-form graphics, high-resolution plots, or geographic maps.
+  #
+  # === Examples
+  #
+  #   Canvas.new(
+  #     x_bounds: [-180, 180],
+  #     y_bounds: [-90, 90],
+  #     shapes: [
+  #       Shape::Map.new(color: :green, resolution: :high),
+  #       Shape::Circle.new(x: 0, y: 0, radius: 10, color: :red),
+  #       Shape::Label.new(x: -122.4, y: 37.8, text: "San Francisco")
+  #     ]
+  #   )
+  class Canvas < Data.define(:shapes, :x_bounds, :y_bounds, :marker, :block, :background_color)
+    ##
+    # :attr_reader: shapes
+    # Array of shapes to render.
     #
-    # Standard widgets cover standard cases. Sometimes you need to draw a map, a custom diagram, or a game.
-    # Character grids are too coarse for fine detail.
-    #
-    # This widget increases the resolution. It uses Braille patterns or block characters to create a "sub-pixel" drawing surface.
-    #
-    # Use it to implement free-form graphics, high-resolution plots, or geographic maps.
-    #
-    # === Examples
-    #
-    #   Canvas.new(
-    #     x_bounds: [-180, 180],
-    #     y_bounds: [-90, 90],
-    #     shapes: [
-    #       Shape::Map.new(color: :green, resolution: :high),
-    #       Shape::Circle.new(x: 0, y: 0, radius: 10, color: :red),
-    #       Shape::Label.new(x: -122.4, y: 37.8, text: "San Francisco")
-    #     ]
-    #   )
-    class Canvas < Data.define(:shapes, :x_bounds, :y_bounds, :marker, :block, :background_color)
-      ##
-      # :attr_reader: shapes
-      # Array of shapes to render.
-      #
-      # Includes {Shape::Line}, {Shape::Circle}, {Shape::Map}, etc.
+    # Includes {Shape::Line}, {Shape::Circle}, {Shape::Map}, etc.
 
-      ##
-      # :attr_reader: x_bounds
-      # [min, max] range for the x-axis.
+    ##
+    # :attr_reader: x_bounds
+    # [min, max] range for the x-axis.
 
-      ##
-      # :attr_reader: y_bounds
-      # [min, max] range for the y-axis.
+    ##
+    # :attr_reader: y_bounds
+    # [min, max] range for the y-axis.
 
-      ##
-      # :attr_reader: marker
-      # The marker type used for drawing.
-      #
-      # <tt>:braille</tt> (high res), <tt>:half_block</tt>, <tt>:dot</tt>, <tt>:block</tt>, <tt>:bar</tt>.
+    ##
+    # :attr_reader: marker
+    # The marker type used for drawing.
+    #
+    # <tt>:braille</tt> (high res), <tt>:half_block</tt>, <tt>:dot</tt>, <tt>:block</tt>, <tt>:bar</tt>.
 
-      ##
-      # :attr_reader: block
-      # Optional wrapping block.
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
 
-      ##
-      # :attr_reader: background_color
-      # The background color of the canvas.
+    ##
+    # :attr_reader: background_color
+    # The background color of the canvas.
 
-      # Creates a new Canvas.
-      #
-      # [shapes] Array of Shapes.
-      # [x_bounds] Array of [min, max] (Numeric, duck-typed via +to_f+).
-      # [y_bounds] Array of [min, max] (Numeric, duck-typed via +to_f+).
-      # [marker] Symbol (default: <tt>:braille</tt>).
-      # [block] Block (optional).
-      # [background_color] Color (optional).
-      def initialize(shapes: [], x_bounds: [0.0, 100.0], y_bounds: [0.0, 100.0], marker: :braille, block: nil, background_color: nil)
-        super(
-          shapes: shapes,
-          x_bounds: [Float(x_bounds[0]), Float(x_bounds[1])],
-          y_bounds: [Float(y_bounds[0]), Float(y_bounds[1])],
-          marker: marker,
-          block: block,
-          background_color: background_color
-        )
-      end
+    # Creates a new Canvas.
+    #
+    # [shapes] Array of Shapes.
+    # [x_bounds] Array of [min, max] (Numeric, duck-typed via +to_f+).
+    # [y_bounds] Array of [min, max] (Numeric, duck-typed via +to_f+).
+    # [marker] Symbol (default: <tt>:braille</tt>).
+    # [block] Block (optional).
+    # [background_color] Color (optional).
+    def initialize(shapes: [], x_bounds: [0.0, 100.0], y_bounds: [0.0, 100.0], marker: :braille, block: nil, background_color: nil)
+      super(
+        shapes:,
+        x_bounds: [Float(x_bounds[0]), Float(x_bounds[1])],
+        y_bounds: [Float(y_bounds[0]), Float(y_bounds[1])],
+        marker:,
+        block:,
+        background_color:
+      )
     end
+  end
 end

data/lib/ratatui_ruby/schema/center.rb

@@ -4,54 +4,54 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Centers content within available space.
-    #
-    # Layouts often require alignment. Manually calculating offsets for centering is error-prone and brittle.
-    #
-    # This widget handles the math. It centers a child widget within the current area, resizing the child
-    # according to optional percentage modifiers.
-    #
-    # Use it to position modals, splash screens, or floating dialogue boxes.
-    #
-    # === Examples
-    #
-    #   # Center a paragraph using 50% of width and height
-    #   Center.new(
-    #     child: Paragraph.new(text: "Hello"),
-    #     width_percent: 50,
-    #     height_percent: 50
-    #   )
-    class Center < Data.define(:child, :width_percent, :height_percent)
-      ##
-      # :attr_reader: child
-      # The widget to be centered.
+  # Centers content within available space.
+  #
+  # Layouts often require alignment. Manually calculating offsets for centering is error-prone and brittle.
+  #
+  # This widget handles the math. It centers a child widget within the current area, resizing the child
+  # according to optional percentage modifiers.
+  #
+  # Use it to position modals, splash screens, or floating dialogue boxes.
+  #
+  # === Examples
+  #
+  #   # Center a paragraph using 50% of width and height
+  #   Center.new(
+  #     child: Paragraph.new(text: "Hello"),
+  #     width_percent: 50,
+  #     height_percent: 50
+  #   )
+  class Center < Data.define(:child, :width_percent, :height_percent)
+    ##
+    # :attr_reader: child
+    # The widget to be centered.
 
-      ##
-      # :attr_reader: width_percent
-      # Width of the centered area as a percentage (0-100).
-      #
-      # If 50, the child occupies half the available width.
+    ##
+    # :attr_reader: width_percent
+    # Width of the centered area as a percentage (0-100).
+    #
+    # If 50, the child occupies half the available width.
 
-      ##
-      # :attr_reader: height_percent
-      # Height of the centered area as a percentage (0-100).
-      #
-      # If 50, the child occupies half the available height.
+    ##
+    # :attr_reader: height_percent
+    # Height of the centered area as a percentage (0-100).
+    #
+    # If 50, the child occupies half the available height.
 
-      # Creates a new Center widget.
-      #
-      # [child]
-      #   Widget to render.
-      # [width_percent]
-      #   Target width percentage (Integer, default: 100).
-      # [height_percent]
-      #   Target height percentage (Integer, default: 100).
-      def initialize(child:, width_percent: 100, height_percent: 100)
-        super(
-          child: child,
-          width_percent: Float(width_percent),
-          height_percent: Float(height_percent)
-        )
-      end
+    # Creates a new Center widget.
+    #
+    # [child]
+    #   Widget to render.
+    # [width_percent]
+    #   Target width percentage (Integer, default: 100).
+    # [height_percent]
+    #   Target height percentage (Integer, default: 100).
+    def initialize(child:, width_percent: 100, height_percent: 100)
+      super(
+        child:,
+        width_percent: Float(width_percent),
+        height_percent: Float(height_percent)
+      )
     end
+  end
 end

data/lib/ratatui_ruby/schema/chart.rb

@@ -10,44 +10,44 @@ module RatatuiRuby
   # [labels] Array<String>
   # [style] Style
   # [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
+  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:,
+        bounds: [Float(bounds[0]), Float(bounds[1])],
+        labels:,
+        style:,
+        labels_alignment:
+      )
     end
+  end
 
   # Defines a Dataset for a Chart.
   # [name] The name of the dataset.
@@ -55,113 +55,105 @@ module RatatuiRuby
   # [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
-
-    # Plots data points on a Cartesian coordinate system.
+  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).
     #
-    # Trends and patterns are invisible in raw logs. You need to see the shape of the data to understand the story it tells.
+    # **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.
     #
-    # 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.
+    # 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.
     #
-    # === Examples
+    # [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:, data: coerced_data, style:, marker:, graph_type:)
+    end
+  end
+
+  # Plots data points on a Cartesian coordinate system.
+  #
+  # 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.
+  #
+  # {rdoc-image:/doc/images/widget_chart_demo.png}[link:/examples/widget_chart_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_chart_demo/app.rb
+  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.
     #
-    #   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
+    # [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
 
   # A complex chart widget. (Legacy/Alias for Chart)
   #
@@ -180,11 +172,11 @@ module RatatuiRuby
     # [block] Optional block widget to wrap the chart.
     def initialize(datasets:, x_labels: [], y_labels: [], y_bounds: [0.0, 100.0], block: nil)
       super(
-        datasets: datasets,
-        x_labels: x_labels,
-        y_labels: y_labels,
+        datasets:,
+        x_labels:,
+        y_labels:,
         y_bounds: [Float(y_bounds[0]), Float(y_bounds[1])],
-        block: block
+        block:
       )
     end
   end

data/lib/ratatui_ruby/schema/clear.rb

@@ -4,49 +4,49 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Resets the terminal buffer for a specific area.
+  # Resets the terminal buffer for a specific 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.
+  #
+  # This widget wipes the slate clean. It resets all cells in its area to their default state (spaces with default background).
+  #
+  # 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.
     #
-    # 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.
-    #
-    # This widget wipes the slate clean. It resets all cells in its area to their default state (spaces with default background).
-    #
-    # 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.
+    # 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
+    # Creates a new Clear widget.
+    #
+    # [block]
+    #   Block widget to render (optional).
+    def initialize(block: nil)
+      super
     end
+  end
 end