ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/widgets/canvas.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # Namespace for canvas shape primitives (Point, Line, Rectangle, Circle, Map, Label).
+    # Distinct from text components and other Line usages.
+    module Shape
+      # A point in the canvas coordinate system.
+      #
+      # [x] The x-coordinate.
+      # [y] The y-coordinate.
+      class Point < Data.define(:x, :y)
+        ##
+        # :attr_reader: x
+        # X coordinate (Float, duck-typed via +to_f+).
+
+        ##
+        # :attr_reader: y
+        # Y coordinate (Float, duck-typed via +to_f+).
+
+        # Creates a new Point.
+        #
+        # [x] X coordinate (Numeric).
+        # [y] Y coordinate (Numeric).
+        def initialize(x:, y:)
+          super(x: Float(x), y: Float(y))
+        end
+      end
+
+      # A line shape on a canvas.
+      #
+      # [x1] The starting x-coordinate.
+      # [y1] The starting y-coordinate.
+      # [x2] The ending x-coordinate.
+      # [y2] The ending y-coordinate.
+      # [color] The color of the line.
+      class Line < Data.define(:x1, :y1, :x2, :y2, :color)
+        ##
+        # :attr_reader: x1
+        # Start X (Float, duck-typed via +to_f+).
+
+        ##
+        # :attr_reader: y1
+        # Start Y (Float, duck-typed via +to_f+).
+
+        ##
+        # :attr_reader: x2
+        # End X (Float, duck-typed via +to_f+).
+
+        ##
+        # :attr_reader: y2
+        # End Y (Float, duck-typed via +to_f+).
+
+        ##
+        # :attr_reader: color
+        # Line color.
+
+        # Creates a new Line.
+        #
+        # [x1] Start X (Numeric).
+        # [y1] Start Y (Numeric).
+        # [x2] End X (Numeric).
+        # [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:)
+        end
+      end
+
+      # A rectangle shape on a canvas.
+      #
+      # [x] The x-coordinate of the bottom-left corner.
+      # [y] The y-coordinate of the bottom-left corner.
+      # [width] The width of the rectangle.
+      # [height] The height of the rectangle.
+      # [color] The color of the rectangle.
+      class Rectangle < Data.define(:x, :y, :width, :height, :color)
+        ##
+        # :attr_reader: x
+        # Bottom-left X (Float, duck-typed via +to_f+).
+
+        ##
+        # :attr_reader: y
+        # Bottom-left Y (Float, duck-typed via +to_f+).
+
+        ##
+        # :attr_reader: width
+        # Width (Float, duck-typed via +to_f+).
+
+        ##
+        # :attr_reader: height
+        # Height (Float, duck-typed via +to_f+).
+
+        ##
+        # :attr_reader: color
+        # Color.
+
+        # Creates a new Rectangle.
+        #
+        # [x] Bottom-left X (Numeric).
+        # [y] Bottom-left Y (Numeric).
+        # [width] Width (Numeric).
+        # [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:)
+        end
+      end
+
+      # A circle shape on a canvas.
+      #
+      # [x] The x-coordinate of the center.
+      # [y] The y-coordinate of the center.
+      # [radius] The radius of the circle.
+      # [color] The color of the circle.
+      class Circle < Data.define(:x, :y, :radius, :color)
+        ##
+        # :attr_reader: x
+        # Center X (Float, duck-typed via +to_f+).
+
+        ##
+        # :attr_reader: y
+        # Center Y (Float, duck-typed via +to_f+).
+
+        ##
+        # :attr_reader: radius
+        # Radius (Float, duck-typed via +to_f+).
+
+        ##
+        # :attr_reader: color
+        # Color.
+
+        # Creates a new Circle.
+        #
+        # [x] Center X (Numeric).
+        # [y] Center Y (Numeric).
+        # [radius] Radius (Numeric).
+        # [color] Color (Symbol).
+        def initialize(x:, y:, radius:, color:)
+          super(x: Float(x), y: Float(y), radius: Float(radius), color:)
+        end
+      end
+
+      # A world map shape on a canvas.
+      #
+      # [color] The color of the map.
+      # [resolution] The resolution of the map (<tt>:low</tt>, <tt>:high</tt>).
+      class Map < Data.define(:color, :resolution)
+        ##
+        # :attr_reader: color
+        # Map color.
+
+        ##
+        # :attr_reader: resolution
+        # Resolution (<tt>:low</tt> or <tt>:high</tt>).
+      end
+    end
+
+    # 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
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   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")
+    #     ]
+    #   )
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Canvas < Data.define(:shapes, :x_bounds, :y_bounds, :marker, :block, :background_color)
+      include CoerceableWidget
+
+      ##
+      # :attr_reader: shapes
+      # Array of shapes to render.
+      #
+      # Includes {Shape::Line}, {Shape::Circle}, {Shape::Map}, etc.
+
+      ##
+      # :attr_reader: x_bounds
+      # [min, max] range for the x-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: block
+      # Optional wrapping block.
+
+      ##
+      # :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:,
+          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
+
+      # Converts canvas coordinates to normalized grid coordinates.
+      #
+      # Hit testing and layout decisions need to know where a canvas point
+      # falls within the drawing surface. This method maps from the canvas
+      # coordinate system to normalized [0.0, 1.0] coordinates.
+      #
+      # Use it to determine if a click or touch event lands within the
+      # canvas bounds, and where proportionally.
+      #
+      # [x] X coordinate in canvas coordinate system.
+      # [y] Y coordinate in canvas coordinate system.
+      #
+      # Returns an Array <tt>[normalized_x, normalized_y]</tt> where each
+      # value is between 0.0 and 1.0, or <tt>nil</tt> if the point is
+      # outside the canvas bounds.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   canvas = Canvas.new(x_bounds: [0.0, 100.0], y_bounds: [0.0, 50.0])
+      #   canvas.get_point(50.0, 25.0)  # => [0.5, 0.5] (center)
+      #   canvas.get_point(0.0, 0.0)    # => [0.0, 1.0] (bottom-left)
+      #   canvas.get_point(101.0, 0.0)  # => nil (out of bounds)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def get_point(x, y)
+        left, right = x_bounds
+        bottom, top = y_bounds
+
+        # Check bounds
+        return nil if x < left || x > right || y < bottom || y > top
+
+        width = right - left
+        height = top - bottom
+
+        # Avoid division by zero
+        return nil if width <= 0.0 || height <= 0.0
+
+        # Normalize to [0.0, 1.0] range
+        normalized_x = (x - left) / width
+        normalized_y = (top - y) / height # Y inverted: top is 0, bottom is 1
+
+        [normalized_x, normalized_y]
+      end
+
+      # Ruby-idiomatic aliases (TIMTOWTDI)
+      alias point get_point
+      alias [] get_point
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/cell.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # A styled table cell combining content with optional styling.
+    #
+    # By default, Table cells are plain strings. For more control over cell styling,
+    # wrap the content in a Cell object to apply cell-level background style.
+    #
+    # The content can be a String, Text::Span, or Text::Line.
+    # The style applies to the entire cell area (background).
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # Cell with yellow background
+    #   Widgets::Cell.new(content: "Warning", style: Style::Style.new(bg: :yellow))
+    #
+    #   # Cell with rich text content
+    #   Widgets::Cell.new(
+    #     content: Text::Line.new(spans: [
+    #       Text::Span.new(content: "Error: ", style: Style::Style.new(fg: :red)),
+    #       Text::Span.new(content: "Details here")
+    #     ]),
+    #     style: Style::Style.new(bg: :dark_gray)
+    #   )
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Cell < Data.define(:content, :style)
+      include CoerceableWidget
+
+      ##
+      # :attr_reader: content
+      # The content to display (String, Text::Span, or Text::Line).
+
+      ##
+      # :attr_reader: style
+      # The style to apply to the cell area (optional Style::Style).
+
+      # Creates a new Cell.
+      #
+      # [content] String, Text::Span, or Text::Line.
+      # [style] Style::Style object (optional).
+      def initialize(content:, style: nil)
+        super
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/center.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # 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
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # Center a paragraph using 50% of width and height
+    #   Center.new(
+    #     child: Paragraph.new(text: "Hello"),
+    #     width_percent: 50,
+    #     height_percent: 50
+    #   )
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Center < Data.define(:child, :width_percent, :height_percent)
+      include CoerceableWidget
+
+      ##
+      # :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: 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:,
+          width_percent: Float(width_percent),
+          height_percent: Float(height_percent)
+        )
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/chart.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # Defines an Axis for a Chart
+    # [title] String
+    # [bounds] Array<Float> [min, max]
+    # [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)
+      include CoerceableWidget
+
+      ##
+      # :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.
+    # [data] Array of arrays [[x, y], [x, y]] (Floats).
+    # [style] The style of the line.
+    # [marker] Symbol (<tt>:dot</tt>, <tt>:braille</tt>, <tt>:block</tt>, <tt>:bar</tt>, <tt>:half_block</tt>)
+    # [graph_type] Symbol (<tt>:line</tt>, <tt>:scatter</tt>)
+    class Dataset < Data.define(:name, :data, :style, :marker, :graph_type)
+      include CoerceableWidget
+
+      ##
+      # :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>, <tt>:block</tt>, <tt>:bar</tt>, <tt>:half_block</tt>).
+      #
+      # <tt>:half_block</tt> uses ▀ and ▄ characters for higher resolution than <tt>:dot</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:, 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.png}[link:/examples/widget_chart/app_rb.html]
+    #
+    # === Example
+    #
+    # Run the interactive demo from the terminal:
+    #
+    #   ruby examples/widget_chart/app.rb
+    class Chart < Data.define(:datasets, :x_axis, :y_axis, :block, :style, :legend_position, :hidden_legend_constraints)
+      include CoerceableWidget
+
+      ##
+      # :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.
+      #
+      # Corners: <tt>:top_left</tt>, <tt>:top_right</tt>, <tt>:bottom_left</tt>, <tt>:bottom_right</tt>.
+      # Edges: <tt>:top</tt>, <tt>:bottom</tt>, <tt>:left</tt>, <tt>: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 — corners: <tt>:top_left</tt>, <tt>:top_right</tt>, <tt>:bottom_left</tt>, <tt>:bottom_right</tt>; edges: <tt>:top</tt>, <tt>:bottom</tt>, <tt>:left</tt>, <tt>: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
+end

data/lib/ratatui_ruby/widgets/clear.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # 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
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # 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]))
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Clear < Data.define(:block)
+      include CoerceableWidget
+
+      ##
+      # :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