ratatui_ruby 0.9.1 → 0.10.0

data/lib/ratatui_ruby/schema/overlay.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  # Stacks widgets on top of each other.
-  #
-  # Terminal interfaces are 2D grids, but complex UIs require depth. You need to float modals over text,
-  # or place a status bar on top of a map.
-  #
-  # This widget manages the Z-axis. It renders a list of widgets sequentially into the same area.
-  # Later widgets draw over earlier ones (Painter's Algorithm).
-  #
-  # Use overlays to compose complex scenes. Combine backgrounds, main content, and floating elements.
-  #
-  # === Examples
-  #
-  #--
-  # SPDX-SnippetBegin
-  # SPDX-FileCopyrightText: 2025 Kerrick Long
-  # SPDX-License-Identifier: MIT-0
-  #++
-  #   Overlay.new(
-  #     layers: [
-  #       BackgroundMap.new,
-  #       StatusBar.new,   # Draws over map
-  #       ModalDialog.new  # Draws over everything
-  #     ]
-  #   )
-  #--
-  # SPDX-SnippetEnd
-  #++
-  class Overlay < Data.define(:layers)
-    ##
-    # :attr_reader: layers
-    # The stack of widgets to render.
-    #
-    # Rendered from index 0 to N. Index N is the top-most layer.
-
-    # Creates a new Overlay.
-    #
-    # [layers]
-    #   Array of widgets.
-    def initialize(layers: [])
-      super
-    end
-  end
-end

data/lib/ratatui_ruby/schema/paragraph.rb

@@ -1,107 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  # Displays a block of text.
-  #
-  # Raw strings are insufficient for UIs. They overflow constraints. They don't respect alignment (left, center, right).
-  #
-  # This widget creates a smart text container. It wraps content to fit the area. It aligns text as requested. It supports scrolling.
-  #
-  # Use it for everything from simple labels to complex, multi-paragraph documents.
-  #
-  # === Examples
-  #
-  #--
-  # SPDX-SnippetBegin
-  # SPDX-FileCopyrightText: 2025 Kerrick Long
-  # SPDX-License-Identifier: MIT-0
-  #++
-  #   # Basic Text
-  #   Paragraph.new(text: "Hello, World!")
-  #
-  #   # Styled container with wrapping
-  #   Paragraph.new(
-  #     text: "This is a long line that will wrap automatically.",
-  #     style: Style.new(fg: :green),
-  #     wrap: true,
-  #     block: Block.new(title: "Output", borders: [:all])
-  #   )
-  #
-  #   # Scrolling mechanism
-  #   Paragraph.new(text: large_text, scroll: [scroll_y, 0])
-  #--
-  # SPDX-SnippetEnd
-  #++
-  class Paragraph < Data.define(:text, :style, :block, :wrap, :alignment, :scroll)
-    ##
-    # :attr_reader: text
-    # The content to display.
-
-    ##
-    # :attr_reader: style
-    # Base style for the text.
-
-    ##
-    # :attr_reader: block
-    # Optional wrapping block.
-
-    ##
-    # :attr_reader: wrap
-    # Whether to wrap text at the edge of the container (Boolean).
-
-    ##
-    # :attr_reader: alignment
-    # Text alignment.
-    #
-    # <tt>:left</tt>, <tt>:center</tt>, or <tt>:right</tt>.
-
-    ##
-    # :attr_reader: scroll
-    # Scroll offset [y, x].
-
-    # Creates a new Paragraph.
-    #
-    # [text] String or Text::Line array.
-    # [style] Style object.
-    # [block] Block object.
-    # [wrap] Boolean (default: false).
-    # [alignment] Symbol (default: <tt>:left</tt>).
-    # [scroll] Array of [y, x] integers (duck-typed via +to_int+).
-    def initialize(text:, style: Style.default, block: nil, wrap: false, alignment: :left, scroll: [0, 0])
-      super(
-        text:,
-        style:,
-        block:,
-        wrap:,
-        alignment:,
-        scroll: [Integer(scroll[0]), Integer(scroll[1])]
-      )
-    end
-
-    # Legacy constructor support.
-    def self.new(text:, style: nil, fg: nil, bg: nil, block: nil, wrap: false, alignment: :left, scroll: [0, 0])
-      style ||= Style.new(fg:, bg:)
-      coerced_scroll = [Integer(scroll[0]), Integer(scroll[1])]
-      super(text:, style:, block:, wrap:, alignment:, scroll: coerced_scroll)
-    end
-
-    # Returns the number of lines the paragraph would take up if rendered with the given width.
-    #
-    # [width] Integer (max width).
-    def line_count(width)
-      RatatuiRuby.warn_experimental_feature("Paragraph#line_count")
-      RatatuiRuby._paragraph_line_count(self, Integer(width))
-    end
-
-    # Returns the minimum width needed to not wrap any text.
-    def line_width
-      RatatuiRuby.warn_experimental_feature("Paragraph#line_width")
-      RatatuiRuby._paragraph_line_width(self)
-    end
-  end
-end

data/lib/ratatui_ruby/schema/ratatui_logo.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  # Displays the Ratatui logo.
-  #
-  # Branding is important for identity. Users need to recognize the tools they use.
-  #
-  # This widget renders the official Ratatui logo.
-  #
-  # Use it for splash screens, about sections, or terminal dashboards.
-  #
-  # {rdoc-image:/doc/images/widget_ratatui_logo.png}[link:/examples/widget_ratatui_logo/app_rb.html]
-  #
-  # === Example
-  #
-  # Run the interactive demo from the terminal:
-  #
-  #   ruby examples/widget_ratatui_logo/app.rb
-  class RatatuiLogo < Data.define
-    ##
-    # :method: new
-    # :call-seq: new -> RatatuiLogo
-    #
-    # Creates a new RatatuiLogo.
-  end
-end

data/lib/ratatui_ruby/schema/ratatui_mascot.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  # Displays the Ratatui mascot.
-  #
-  # Interfaces without personality feel clinical and dry. Users appreciate a friendly face in their terminal.
-  #
-  # This widget renders the Ratatui mascot (a mouse).
-  #
-  # Use it to add charm to your application, greet users on startup, or as a decorative element in sidebars.
-  #
-  # {rdoc-image:/doc/images/widget_ratatui_mascot.png}[link:/examples/widget_ratatui_mascot/app_rb.html]
-  #
-  # === Example
-  #
-  # Run the interactive demo from the terminal:
-  #
-  #   ruby examples/widget_ratatui_mascot/app.rb
-  class RatatuiMascot < Data.define(:block)
-    ##
-    # :method: new
-    # :call-seq: new(block: nil) -> RatatuiMascot
-    #
-    # Creates a new RatatuiMascot.
-    #
-    # @param block [Block, nil] A block to wrap the widget in.
-    def initialize(block: nil)
-      super
-    end
-  end
-end

data/lib/ratatui_ruby/schema/rect.rb

@@ -1,174 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  # Defines a rectangular area in the terminal grid.
-  #
-  # Geometry management involves passing groups of four integers (`x, y, width, height`) repeatedly.
-  # This is verbose and prone to parameter mismatch errors.
-  #
-  # This class encapsulates the geometry. It provides a standard primitive for passing area definitions
-  # between layout engines and rendering functions.
-  #
-  # Use it when manual positioning is required or when querying layout results.
-  #
-  # === Examples
-  #
-  #--
-  # SPDX-SnippetBegin
-  # SPDX-FileCopyrightText: 2025 Kerrick Long
-  # SPDX-License-Identifier: MIT-0
-  #++
-  #   area = Rect.new(x: 0, y: 0, width: 80, height: 24)
-  #   puts area.width # => 80
-  #--
-  # SPDX-SnippetEnd
-  #++
-  class Rect < Data.define(:x, :y, :width, :height)
-    ##
-    # :attr_reader: x
-    # X coordinate (column) of the top-left corner (Integer, coerced via +to_int+ or +to_i+).
-
-    ##
-    # :attr_reader: y
-    # Y coordinate (row) of the top-left corner (Integer, coerced via +to_int+ or +to_i+).
-
-    ##
-    # :attr_reader: width
-    # Width in characters (Integer, coerced via +to_int+ or +to_i+).
-
-    ##
-    # :attr_reader: height
-    # Height in characters (Integer, coerced via +to_int+ or +to_i+).
-
-    # Creates a new Rect.
-    #
-    # All parameters accept any object responding to +to_int+ or +to_i+ (duck-typed).
-    #
-    # [x] Column index (Numeric).
-    # [y] Row index (Numeric).
-    # [width] Width in columns (Numeric).
-    # [height] Height in rows (Numeric).
-    def initialize(x: 0, y: 0, width: 0, height: 0)
-      super(
-        x: Integer(x),
-        y: Integer(y),
-        width: Integer(width),
-        height: Integer(height)
-      )
-    end
-
-    # Tests whether a point is inside this rectangle.
-    #
-    # Essential for hit testing mouse clicks against layout regions.
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   area = Rect.new(x: 10, y: 5, width: 20, height: 10)
-    #   area.contains?(15, 8) # => true
-    #   area.contains?(5, 8)  # => false
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # [px]
-    #   X coordinate to test (column).
-    # [py]
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   Y coordinate to test (row).
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # Returns true if the point (px, py) is within the rectangle bounds.
-    def contains?(px, py)
-      px >= x && px < x + width && py >= y && py < y + height
-    end
-
-    # Tests whether this rectangle overlaps with another.
-    #
-    # Essential for determining if a widget is visible within a viewport or clipping area.
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2026 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   viewport = Rect.new(x: 0, y: 0, width: 80, height: 24)
-    #   widget = Rect.new(x: 70, y: 20, width: 20, height: 10)
-    #   viewport.intersects?(widget) # => true (partial overlap)
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # [other]
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2026 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   Another Rect to test against.
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # Returns true if the rectangles overlap.
-    def intersects?(other)
-      x < other.x + other.width &&
-        x + width > other.x &&
-        y < other.y + other.height &&
-        y + height > other.y
-    end
-
-    # Returns the overlapping area between this rectangle and another.
-    #
-    # Essential for calculating visible portions of widgets inside scroll views.
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2026 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   viewport = Rect.new(x: 0, y: 0, width: 80, height: 24)
-    #   widget = Rect.new(x: 70, y: 20, width: 20, height: 10)
-    #   visible = viewport.intersection(widget)
-    #   # => Rect(x: 70, y: 20, width: 10, height: 4)
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # [other]
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2026 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   Another Rect to intersect with.
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # Returns a new Rect representing the intersection, or +nil+ if no overlap.
-    def intersection(other)
-      return nil unless intersects?(other)
-
-      new_x = [x, other.x].max
-      new_y = [y, other.y].max
-      new_right = [x + width, other.x + other.width].min
-      new_bottom = [y + height, other.y + other.height].min
-
-      Rect.new(x: new_x, y: new_y, width: new_right - new_x, height: new_bottom - new_y)
-    end
-  end
-end

data/lib/ratatui_ruby/schema/row.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  # A styled table row combining cells with optional row-level styling.
-  #
-  # By default, Table rows are arrays of cell content. For more control over styling
-  # individual rows, wrap the cells in a Row object to apply row-level style.
-  #
-  # The cells can be Strings, Text::Spans, Text::Lines, Paragraphs, or Cells.
-  # The style applies to the entire row background.
-  #
-  # === Examples
-  #
-  #--
-  # SPDX-SnippetBegin
-  # SPDX-FileCopyrightText: 2026 Kerrick Long
-  # SPDX-License-Identifier: MIT-0
-  #++
-  #   # Row with red background
-  #   Row.new(cells: ["Error", "Something went wrong"], style: Style.new(bg: :red))
-  #
-  #   # Row with styled cells and custom height
-  #   Row.new(
-  #     cells: [
-  #       Text::Span.new(content: "Status", style: Style.new(modifiers: [:bold])),
-  #       Text::Span.new(content: "OK", style: Style.new(fg: :green))
-  #     ],
-  #     height: 2
-  #   )
-  #--
-  # SPDX-SnippetEnd
-  #++
-  class Row < Data.define(:cells, :style, :height, :top_margin, :bottom_margin)
-    ##
-    # :attr_reader: cells
-    # The cells to display (Array of Strings, Text::Spans, Text::Lines, Paragraphs, or Cells).
-
-    ##
-    # :attr_reader: style
-    # The style to apply to the row (optional Style).
-
-    ##
-    # :attr_reader: height
-    # Fixed row height in lines (optional Integer).
-
-    ##
-    # :attr_reader: top_margin
-    # Margin above the row in lines (optional Integer).
-
-    ##
-    # :attr_reader: bottom_margin
-    # Margin below the row in lines (optional Integer).
-
-    # Creates a new Row.
-    #
-    # [cells] Array of Strings, Text::Spans, Text::Lines, Paragraphs, or Cells.
-    # [style] Style object (optional).
-    # [height] Integer for fixed height (optional).
-    # [top_margin] Integer for top margin (optional).
-    # [bottom_margin] Integer for bottom margin (optional).
-    def initialize(cells:, style: nil, height: nil, top_margin: nil, bottom_margin: nil)
-      super(
-        cells:,
-        style:,
-        height: height.nil? ? nil : Integer(height),
-        top_margin: top_margin.nil? ? nil : Integer(top_margin),
-        bottom_margin: bottom_margin.nil? ? nil : Integer(bottom_margin)
-      )
-    end
-  end
-end

data/lib/ratatui_ruby/schema/scrollbar.rb

@@ -1,143 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  # Visualizes the scroll state of a viewport.
-  #
-  # Content overflows. Users get lost in long lists without landmarks. They need to know where they are and how much is left.
-  #
-  # This widget maps your context. It draws a track and a thumb, representing your current position relative to the total length.
-  #
-  # Overlay it on top of lists, paragraphs, or tables to provide spatial awareness.
-  #
-  # {rdoc-image:/doc/images/widget_scrollbar.png}[link:/examples/widget_scrollbar/app_rb.html]
-  #
-  # === Example
-  #
-  # Run the interactive demo from the terminal:
-  #
-  #   ruby examples/widget_scrollbar/app.rb
-  class Scrollbar < Data.define(
-    :content_length,
-    :position,
-    :orientation,
-    :thumb_symbol,
-    :thumb_style,
-    :track_symbol,
-    :track_style,
-    :begin_symbol,
-    :begin_style,
-    :end_symbol,
-    :end_style,
-    :style,
-    :block
-  )
-    ##
-    # :attr_reader: content_length
-    # Total items or lines in the content.
-
-    ##
-    # :attr_reader: position
-    # Current scroll offset (index).
-    #
-    # Maps to Ratatui's <tt>ScrollbarState::get_position()</tt> (new in 0.30.0).
-
-    ##
-    # :attr_reader: orientation
-    # Direction of the scrollbar.
-    #
-    # <tt>:vertical</tt> (default, alias for <tt>:vertical_right</tt>), <tt>:horizontal</tt> (alias for <tt>:horizontal_bottom</tt>),
-    # <tt>:vertical_left</tt>, <tt>:vertical_right</tt>, <tt>:horizontal_top</tt>, or <tt>:horizontal_bottom</tt>.
-
-    ##
-    # :attr_reader: thumb_symbol
-    # Symbol used to represent the current position indicator.
-
-    ##
-    # :attr_reader: thumb_style
-    # Style of the position indicator (thumb).
-
-    ##
-    # :attr_reader: track_symbol
-    # Symbol used to represent the empty space of the scrollbar.
-
-    ##
-    # :attr_reader: track_style
-    # Style of the filled track area.
-
-    ##
-    # :attr_reader: begin_symbol
-    # Symbol rendered at the start of the track (e.g., arrow).
-
-    ##
-    # :attr_reader: begin_style
-    # Style of the start symbol.
-
-    ##
-    # :attr_reader: end_symbol
-    # Symbol rendered at the end of the track (e.g., arrow).
-
-    ##
-    # :attr_reader: end_style
-    # Style of the end symbol.
-
-    ##
-    # :attr_reader: style
-    # Base style applied to the entire widget.
-
-    ##
-    # :attr_reader: block
-    # Optional wrapping block.
-
-    # Creates a new Scrollbar.
-    #
-    # [content_length] Integer.
-    # [position] Integer.
-    # [orientation] Symbol (default: <tt>:vertical</tt>).
-    # [thumb_symbol] String (default: <tt>"█"</tt>).
-    # [thumb_style] Style (optional).
-    # [track_symbol] String (optional).
-    # [track_style] Style (optional).
-    # [begin_symbol] String (optional).
-    # [begin_style] Style (optional).
-    # [end_symbol] String (optional).
-    # [end_style] Style (optional).
-    # [style] Style (optional).
-    # [block] Block (optional).
-    def initialize(
-      content_length:,
-      position:,
-      orientation: :vertical,
-      thumb_symbol: "█",
-      thumb_style: nil,
-      track_symbol: nil,
-      track_style: nil,
-      begin_symbol: nil,
-      begin_style: nil,
-      end_symbol: nil,
-      end_style: nil,
-      style: nil,
-      block: nil
-    )
-      super(
-        content_length: Integer(content_length),
-        position: Integer(position),
-        orientation:,
-        thumb_symbol:,
-        thumb_style:,
-        track_symbol:,
-        track_style:,
-        begin_symbol:,
-        begin_style:,
-        end_symbol:,
-        end_style:,
-        style:,
-        block:
-      )
-    end
-  end
-end

data/lib/ratatui_ruby/schema/shape/label.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  module Shape
-    # A text label on a canvas.
-    #
-    # Labels render text at specific coordinates in canvas space.
-    # Unlike shapes, labels are always rendered on top of all other canvas elements.
-    #
-    # [x] The x-coordinate in canvas space (Numeric).
-    # [y] The y-coordinate in canvas space (Numeric).
-    # [text] The text content (String or Text::Line).
-    # [style] Optional style for the text.
-    #
-    # === Examples
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   # Simple label
-    #   Shape::Label.new(x: 0, y: 0, text: "Origin")
-    #
-    #   # Styled label
-    #   Shape::Label.new(
-    #     x: -122.4, y: 37.8,
-    #     text: "San Francisco",
-    #     style: Style.new(fg: :cyan, add_modifier: :bold)
-    #   )
-    #
-    #   # Label with Text::Line for rich formatting
-    #   Shape::Label.new(
-    #     x: 0.0, y: 0.0,
-    #     text: Text::Line.new(spans: [
-    #       Text::Span.new(content: "Hello ", style: Style.new(fg: :red)),
-    #       Text::Span.new(content: "World", style: Style.new(fg: :blue))
-    #     ])
-    #   )
-    #--
-    # SPDX-SnippetEnd
-    #++
-    class Label < Data.define(:x, :y, :text, :style)
-      ##
-      # :attr_reader: x
-      # X coordinate in canvas space (Float, duck-typed via +to_f+).
-
-      ##
-      # :attr_reader: y
-      # Y coordinate in canvas space (Float, duck-typed via +to_f+).
-
-      ##
-      # :attr_reader: text
-      # Text content (String or Text::Line).
-
-      ##
-      # :attr_reader: style
-      # Optional style for the text.
-
-      # Creates a new Label.
-      #
-      # [x] X coordinate (Numeric).
-      # [y] Y coordinate (Numeric).
-      # [text] Text content (String or Text::Line).
-      # [style] Style (optional).
-      def initialize(x:, y:, text:, style: nil)
-        super(x: Float(x), y: Float(y), text:, style:)
-      end
-    end
-  end
-end