ratatui_ruby 0.3.1 → 0.4.0

data/lib/ratatui_ruby/schema/block.rb

@@ -4,20 +4,192 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A widget that wraps other widgets with a border and/or a title.
-  #
-  # [title] The title string to display on the border.
-  # [borders] An array of symbols representing which borders to display:
-  #           [:top, :bottom, :left, :right, :all, :none]
-  # [border_color] The color of the border (e.g., "red", "#ff0000").
-  class Block < Data.define(:title, :borders, :border_color)
-    # Creates a new Block.
+    # Defines the visual container for a widget.
     #
-    # [title] The title string to display on the border.
-    # [borders] An array of symbols representing which borders to display.
-    # [border_color] The color of the border.
-    def initialize(title: nil, borders: [:all], border_color: nil)
-      super
+    # Widgets often float in void. Without boundaries, interfaces become a chaotic mess of text. Users need structure to parse information.
+    #
+    # This widget creates that structure. It wraps content in borders. It labels sections with titles. It paints the background.
+    #
+    # Use blocks to define distinct areas. Group related information. Create a visual hierarchy that guides the user's eye.
+    #
+    # === Examples
+    #
+    #   # A simple bordered block
+    #   Block.new(borders: [:all], title: "Logs")
+    #
+    #   # A complex block with styling and padding
+    #   Block.new(
+    #     title: "Status",
+    #     borders: [:left, :right],
+    #     style: Style.new(fg: :yellow),
+    #     padding: [1, 1, 0, 0] # Left, Right, Top, Bottom
+    #   )
+    class Block < Data.define(:title, :titles, :title_alignment, :title_style, :borders, :border_color, :border_style, :border_type, :border_set, :style, :padding, :children)
+      ##
+      # :attr_reader: title
+      # The main title displayed on the top border.
+      #
+      # === Example
+      #
+      #   Block.new(title: "Main").title # => "Main"
+
+      ##
+      # :attr_reader: titles
+      # Additional titles for complex labeling.
+      #
+      # Each title can be a <tt>String</tt> or a <tt>Hash</tt> with keys <tt>:content</tt>, <tt>:alignment</tt>, <tt>:position</tt> (<tt>:top</tt> or <tt>:bottom</tt>), and <tt>:style</tt>.
+      #
+      # === Example
+      #
+      #   Block.new(titles: ["Top", { content: "Bottom", position: :bottom }]).titles
+
+      ##
+      # :attr_reader: title_alignment
+      # Alignment of the main title.
+      #
+      # One of <tt>:left</tt>, <tt>:center</tt>, or <tt>:right</tt>.
+      #
+      # === Example
+      #
+      #   Block.new(title_alignment: :center).title_alignment # => :center
+
+      ##
+      # :attr_reader: title_style
+      # Style applied to all titles if not overridden.
+      #
+      # === Example
+      #
+      #   Block.new(title_style: Style.new(fg: :red)).title_style
+
+      ##
+      # :attr_reader: borders
+      # Visible borders.
+      #
+      # An array containing any of <tt>:top</tt>, <tt>:bottom</tt>, <tt>:left</tt>, <tt>:right</tt>, or <tt>:all</tt>.
+      #
+      # === Example
+      #
+      #   Block.new(borders: [:left, :right]).borders # => [:left, :right]
+
+      ##
+      # :attr_reader: border_color
+      # Color of the border lines.
+      #
+      # Deprecated: Use <tt>border_style:</tt> instead for full style support.
+
+      ##
+      # :attr_reader: border_style
+      # Full style (colors/modifiers) for the border lines.
+      #
+      # A Style object or Hash with <tt>:fg</tt>, <tt>:bg</tt>, and <tt>:modifiers</tt>.
+      # This allows borders to be bold, italic, colored, etc. If both <tt>border_color</tt>
+      # and <tt>border_style</tt> are provided, <tt>border_style</tt> takes precedence.
+
+      ##
+      # :attr_reader: border_type
+      # Visual style of the border lines.
+      #
+      # One of <tt>:plain</tt>, <tt>:rounded</tt>, <tt>:double</tt>, <tt>:thick</tt>, etc.
+
+      ##
+      # :attr_reader: border_set
+      # Custom characters for the border lines.
+      #
+      # A Hash with keys defining the characters for the borders.
+      # Keys: <tt>:top_left</tt>, <tt>:top_right</tt>, <tt>:bottom_left</tt>, <tt>:bottom_right</tt>,
+      # <tt>:vertical_left</tt>, <tt>:vertical_right</tt>, <tt>:horizontal_top</tt>, <tt>:horizontal_bottom</tt>.
+      #
+      # Providing this overrides <tt>border_type</tt>.
+      #
+      #
+      # === Example
+      #
+      #   Block.new(border_set: { top_left: "1", top_right: "2", bottom_left: "3", bottom_right: "4", vertical_left: "5", vertical_right: "6", horizontal_top: "7", horizontal_bottom: "8" })
+
+      ##
+      # :attr_reader: style
+      # Base style (colors/modifiers) for the block content.
+
+      ##
+      # :attr_reader: padding
+      # Inner padding.
+      #
+      # Can be a single <tt>Integer</tt> (uniform) or a 4-element <tt>Array</tt> (left, right, top, bottom).
+      #
+      # === Example
+      #
+      #   Block.new(padding: 2).padding # => 2
+      #   Block.new(padding: [1, 1, 0, 0]).padding # => [1, 1, 0, 0]
+
+      ##
+      # :attr_reader: children
+      # Widgets to render inside the block (optional).
+      #
+      # When provided, each child widget is rendered within the block's area.
+      #
+      # === Example
+      #
+      #   Block.new(
+      #     title: "Content",
+      #     borders: [:all],
+      #     children: [Paragraph.new(text: "Hello")]
+      #   )
+
+      # Creates a new Block.
+      #
+      # [title]
+      #   Main title string (optional).
+      # [titles]
+      #   Array of additional titles (optional).
+      # [title_alignment]
+      #   Alignment symbol: <tt>:left</tt> (default), <tt>:center</tt>, <tt>:right</tt>.
+      # [title_style]
+      #   Base style for all titles (optional).
+      # [borders]
+      #   Array of borders to show: <tt>:top</tt>, <tt>:bottom</tt>, <tt>:left</tt>, <tt>:right</tt>, or <tt>:all</tt> (default).
+      # [border_color]
+      #   Color string or symbol (e.g., <tt>:red</tt>). Deprecated: use <tt>border_style</tt> instead.
+      # [border_style]
+      #   Style object or Hash for the border lines.
+      # [border_type]
+      #   Symbol: <tt>:plain</tt> (default), <tt>:rounded</tt>, <tt>:double</tt>, <tt>:thick</tt>, <tt>:hidden</tt>, <tt>:quadrant_inside</tt>, <tt>:quadrant_outside</tt>.
+      # [border_set]
+      #   Hash: Custom characters for the border lines. Unique characters are interned (leaked) permanently, so avoid infinite dynamic variations.
+      # [style]
+      #   Style object or Hash for the block's content area.
+      # [padding]
+      #   Integer (uniform) or Array[4] (left, right, top, bottom).
+      # [children]
+      #   Array of widgets to render inside the block (optional).
+      def initialize(title: nil, titles: [], title_alignment: nil, title_style: nil, borders: [:all], border_color: nil, border_style: nil, border_type: nil, border_set: nil, style: nil, padding: 0, children: [])
+        if border_set
+          border_set = border_set.dup
+          %i[top_left top_right bottom_left bottom_right vertical_left vertical_right horizontal_top horizontal_bottom].each do |long_key|
+            short_key = long_key.to_s.split("_").map { |s| s[0] }.join
+            if val = border_set.delete(short_key.to_sym) || border_set.delete(short_key)
+              border_set[long_key] = val
+            end
+          end
+        end
+        coerced_padding = if padding.is_a?(Array)
+          padding.map { |v| Integer(v) }
+        else
+          Integer(padding)
+        end
+        super(
+          title: title,
+          titles: titles,
+          title_alignment: title_alignment,
+          title_style: title_style,
+          borders: borders,
+          border_color: border_color,
+          border_style: border_style,
+          border_type: border_type,
+          border_set: border_set,
+          style: style,
+          padding: coerced_padding,
+          children: children
+        )
+      end
     end
-  end
 end

data/lib/ratatui_ruby/schema/calendar.rb

@@ -4,23 +4,80 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A Monthly Calendar widget.
-  #
-  # [year] Integer (e.g., 2025)
-  # [month] Integer (1-12)
-  # [day_style] Style (Style for regular days)
-  # [header_style] Style (Style for the month title)
-  # [block] Block
-  class Calendar < Data.define(:year, :month, :day_style, :header_style, :block)
-    # Creates a new Calendar.
+    # Displays a monthly calendar grid.
     #
-    # [year] Integer (e.g., 2025)
-    # [month] Integer (1-12)
-    # [day_style] Style (Style for regular days)
-    # [header_style] Style (Style for the month title)
-    # [block] Block
-    def initialize(year:, month:, day_style: nil, header_style: nil, block: nil)
-      super
+    # Dates are complex. Rendering them in a grid requires calculation of leap years, month lengths, and day-of-week offsets.
+    # Use this widget to skip the boilerplate.
+    #
+    # This widget renders a standard monthly view. It highlights the current date. It structures time.
+    #
+    # Use it for date pickers, schedulers, or logs.
+    #
+    # === Examples
+    #
+    #   Calendar.new(
+    #     year: 2025,
+    #     month: 12,
+    #     default_style: Style.new(fg: :white),
+    #     header_style: Style.new(fg: :yellow, modifiers: [:bold])
+    #   )
+    class Calendar < Data.define(:year, :month, :events, :default_style, :header_style, :block, :show_weekdays_header, :show_surrounding, :show_month_header)
+      ##
+      # :attr_reader: year
+      # The year to display (Integer).
+
+      ##
+      # :attr_reader: month
+      # The month to display (1–12).
+
+      ##
+      # :attr_reader: events
+      # A Hash mapping Dates to Styles for event highlighting.
+      # Keys must be `Date` objects (or objects responding to `day`, `month`, `year`).
+      # Values must be `Style` objects.
+
+      ##
+      # :attr_reader: default_style
+      # Style for the days.
+
+      ##
+      # :attr_reader: header_style
+      # Style for the month name header.
+
+      ##
+      # :attr_reader: block
+      # Optional wrapping block.
+
+      ##
+      # :attr_reader: show_weekdays_header
+      # Whether to show the weekday header (Mon, Tue, etc.).
+
+      ##
+      # :attr_reader: show_surrounding
+      # Style for dates from surrounding months. If <tt>nil</tt>, surrounding dates are hidden.
+
+      # Creates a new Calendar.
+      #
+      # [year] Integer.
+      # [month] Integer.
+      # [events] Hash<Date, Style>. Optional.
+      # [default_style] Style.
+      # [header_style] Style.
+      # [block] Block.
+      # [show_weekdays_header] Boolean. Whether to show the weekday header.
+      # [show_surrounding] <tt>Style</tt> or <tt>nil</tt>. Style for surrounding month dates.
+      def initialize(year:, month:, events: {}, default_style: nil, header_style: nil, block: nil, show_weekdays_header: true, show_surrounding: nil, show_month_header: false)
+        super(
+          year: Integer(year),
+          month: Integer(month),
+          events: events,
+          default_style: default_style,
+          header_style: header_style,
+          block: block,
+          show_weekdays_header: show_weekdays_header,
+          show_surrounding: show_surrounding,
+          show_month_header: show_month_header
+        )
+      end
     end
-  end
 end

data/lib/ratatui_ruby/schema/canvas.rb

@@ -4,59 +4,226 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A point in the canvas coordinate system.
-  # @param x [Float] The x-coordinate.
-  # @param y [Float] The y-coordinate.
-  class Point < Data.define(:x, :y)
-  end
+  # 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+).
 
-  # A line shape on a canvas.
-  # @param x1 [Float] The starting x-coordinate.
-  # @param y1 [Float] The starting y-coordinate.
-  # @param x2 [Float] The ending x-coordinate.
-  # @param y2 [Float] The ending y-coordinate.
-  # @param color [String, Symbol] The color of the line.
-  class Line < Data.define(:x1, :y1, :x2, :y2, :color)
-  end
+      ##
+      # :attr_reader: y
+      # Y coordinate (Float, duck-typed via +to_f+).
 
-  # A rectangle shape on a canvas.
-  # @param x [Float] The x-coordinate of the bottom-left corner.
-  # @param y [Float] The y-coordinate of the bottom-left corner.
-  # @param width [Float] The width of the rectangle.
-  # @param height [Float] The height of the rectangle.
-  # @param color [String, Symbol] The color of the rectangle.
-  class Rectangle < Data.define(:x, :y, :width, :height, :color)
-  end
+      # 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 circle shape on a canvas.
-  # @param x [Float] The x-coordinate of the center.
-  # @param y [Float] The y-coordinate of the center.
-  # @param radius [Float] The radius of the circle.
-  # @param color [String, Symbol] The color of the circle.
-  class Circle < Data.define(:x, :y, :radius, :color)
-  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+).
 
-  # A world map shape on a canvas.
-  # @param color [String, Symbol] The color of the map.
-  # @param resolution [Symbol] The resolution of the map (:low, :high).
-  class Map < Data.define(:color, :resolution)
-  end
+      ##
+      # :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.
 
-  # The Canvas Widget.
-  # @param shapes [Array] Array of shape objects (Line, Rectangle, Circle, Map).
-  # @param x_bounds [Array<Float>] [min, max] range for the x-axis.
-  # @param y_bounds [Array<Float>] [min, max] range for the y-axis.
-  # @param marker [Symbol] The marker to use for drawing (:braille, :dot, :block, :bar).
-  # @param block [Block, nil] Optional Block widget to wrap the canvas.
-  class Canvas < Data.define(:shapes, :x_bounds, :y_bounds, :marker, :block)
-    # Creates a new Canvas.
-    # @param shapes [Array] Array of shape objects (Line, Rectangle, Circle, Map).
-    # @param x_bounds [Array<Float>] [min, max] range for the x-axis.
-    # @param y_bounds [Array<Float>] [min, max] range for the y-axis.
-    # @param marker [Symbol] The marker to use for drawing (:braille, :dot, :block, :bar).
-    # @param block [Block, nil] Optional Block widget to wrap the canvas.
-    def initialize(shapes: [], x_bounds: [0.0, 100.0], y_bounds: [0.0, 100.0], marker: :braille, block: nil)
-      super
+      # 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: 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: 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: 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
+    #
+    #   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.
+
+      ##
+      # :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: 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
+    end
 end

data/lib/ratatui_ruby/schema/center.rb

@@ -4,16 +4,54 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # Centers a child widget within the current area.
-  #
-  # [child] the widget to center.
-  # [width_percent] the width percentage of the centered area.
-  # [height_percent] the height percentage of the centered area.
-  class Center < Data.define(:child, :width_percent, :height_percent)
-    # Creates a new Center.
+    # Centers content within available space.
     #
-    # [child] the widget to center.
-    # [width_percent] the width percentage of the centered area.
-    # [height_percent] the height percentage of the centered area.
-  end
+    # 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: 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
+    end
 end