ratatui_ruby 0.9.1 → 0.10.0

data/lib/ratatui_ruby/schema/constraint.rb

@@ -1,151 +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 the sizing rule for a layout section.
-  #
-  # Flexible layouts need rules. You can't just place widgets at absolute coordinates; they must adapt to changing terminal sizes.
-  #
-  # This class defines the rules of engagement. It tells the layout engine exactly how much space a section requires relative to others.
-  #
-  # Mix and match fixed lengths, percentages, ratios, and minimums. Build layouts that breathe.
-  #
-  # === Examples
-  #
-  #--
-  # SPDX-SnippetBegin
-  # SPDX-FileCopyrightText: 2025 Kerrick Long
-  # SPDX-License-Identifier: MIT-0
-  #++
-  #   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)
-  #--
-  # SPDX-SnippetEnd
-  #++
-  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.
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   Constraint.length(10) # 10 characters wide/high
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # [v] Number of cells (Integer).
-    def self.length(v)
-      new(type: :length, value: Integer(v))
-    end
-
-    # Requests a percentage of available space.
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   Constraint.percentage(25) # 25% of the area
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # [v] Percentage 0-100 (Integer).
-    def self.percentage(v)
-      new(type: :percentage, value: Integer(v))
-    end
-
-    # Enforces a minimum size.
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   Constraint.min(5) # At least 5 cells
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # 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.
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   Constraint.max(10) # At most 10 cells
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # [v] Maximum cells (Integer).
-    def self.max(v)
-      new(type: :max, value: Integer(v))
-    end
-
-    # Fills remaining space proportionally.
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   Constraint.fill(1) # Equal share
-    #   Constraint.fill(2) # Double share
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # 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.
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   Constraint.ratio(1, 3) # 1/3rd of the area
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # [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

data/lib/ratatui_ruby/schema/cursor.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  # Controls the terminal cursor position.
-  #
-  # 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
-  #
-  #--
-  # SPDX-SnippetBegin
-  # SPDX-FileCopyrightText: 2026 Kerrick Long
-  # SPDX-License-Identifier: MIT-0
-  #++
-  #   Cursor.new(x: 10, y: 5)
-  #
-  #--
-  # SPDX-SnippetEnd
-  #++
-  # See also:
-  # - {Declarative implementation using Tree API}[link:/examples/app_login_form/app_rb.html]
-  # - {Component-based implementation using Frame API}[link:/examples/app_color_picker/app_rb.html]
-  # - RatatuiRuby::Frame#set_cursor_position (Frame API alternative)
-  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/gauge.rb

@@ -1,72 +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 standard progress bar.
-  #
-  # 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.
-  #
-  # {rdoc-image:/doc/images/widget_gauge.png}[link:/examples/widget_gauge/app_rb.html]
-  #
-  # === Example
-  #
-  # Run the interactive demo from the terminal:
-  #
-  #   ruby examples/widget_gauge/app.rb
-  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).
-    #
-    # Accepts String or Text::Span for rich styling.
-    #
-    # 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 or Text::Span (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

data/lib/ratatui_ruby/schema/layout.rb

@@ -1,122 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: LGPL-3.0-or-later
-#++
-
-module RatatuiRuby
-  # Divides an area into smaller chunks.
-  #
-  # Terminal screens vary in size. Hardcoded positions break when the window resizes. You need a way to organize space dynamically.
-  #
-  # This class manages geometry. It splits a given area into multiple sections based on a list of constraints.
-  #
-  # Use layouts to build responsive grids. Stack sections vertically for a sidebar-main structure. Partition them horizontally for headers and footers. Let the layout engine do the math.
-  #
-  # {rdoc-image:/doc/images/widget_layout_split.png}[link:/examples/widget_layout_split/app_rb.html]
-  #
-  # === Example
-  #
-  # Run the interactive demo from the terminal:
-  #
-  #   ruby examples/widget_layout_split/app.rb
-  class Layout < Data.define(:direction, :constraints, :children, :flex)
-    ##
-    # :attr_reader: direction
-    # Direction of the split.
-    #
-    # Either <tt>:vertical</tt> (top to bottom) or <tt>:horizontal</tt> (left to right).
-    #
-    #   layout.direction # => :vertical
-
-    ##
-    # :attr_reader: constraints
-    # Array of rules defining section sizes.
-    #
-    # See RatatuiRuby::Layout::Constraint.
-
-    ##
-    # :attr_reader: children
-    # Widgets to render in each section (optional).
-    #
-    # If provided, `children[i]` is rendered into the area defined by `constraints[i]`.
-
-    ##
-    # :attr_reader: flex
-    # Strategy for distributing extra space.
-    #
-    # One of <tt>:legacy</tt>, <tt>:start</tt>, <tt>:center</tt>, <tt>:end</tt>, <tt>:space_between</tt>, <tt>:space_around</tt>.
-
-    # :nodoc:
-    FLEX_MODES = %i[legacy start center end space_between space_around space_evenly].freeze
-
-    # Creates a new Layout.
-    #
-    # [direction]
-    #   <tt>:vertical</tt> or <tt>:horizontal</tt> (default: <tt>:vertical</tt>).
-    # [constraints]
-    #   list of Constraint objects.
-    # [children]
-    #   List of widgets to render (optional).
-    # [flex]
-    #   Flex mode for spacing (default: <tt>:legacy</tt>).
-    def initialize(direction: :vertical, constraints: [], children: [], flex: :legacy)
-      super
-    end
-
-    # Splits an area into multiple rectangles.
-    #
-    # This is a pure calculation helper for hit testing. It computes where
-    # widgets *would* be placed without actually rendering them.
-    #
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   rects = Layout.split(
-    #     area,
-    #     direction: :horizontal,
-    #     constraints: [Constraint.percentage(50), Constraint.percentage(50)]
-    #   )
-    #   left, right = rects
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # [area]
-    #   The area to split. Can be a <tt>Rect</tt> or a <tt>Hash</tt> containing <tt>:x</tt>, <tt>:y</tt>, <tt>:width</tt>, and <tt>:height</tt>.
-    # [direction]
-    #   <tt>:vertical</tt> or <tt>:horizontal</tt> (default: <tt>:vertical</tt>).
-    # [constraints]
-    #   Array of <tt>Constraint</tt> objects defining section sizes.
-    # [flex]
-    #--
-    # SPDX-SnippetBegin
-    # SPDX-FileCopyrightText: 2025 Kerrick Long
-    # SPDX-License-Identifier: MIT-0
-    #++
-    #   Flex mode for spacing (default: <tt>:legacy</tt>).
-    #
-    #--
-    # SPDX-SnippetEnd
-    #++
-    # Returns an Array of <tt>Rect</tt> objects.
-    def self.split(area, direction: :vertical, constraints:, flex: :legacy)
-      # Duck-typing: If it lacks geometry methods but can be a Hash, convert it.
-      if !area.respond_to?(:x) && area.respond_to?(:to_h)
-        # Assume it's a Hash-like object with :x, :y, etc.
-        hash = area.to_h
-        area = Rect.new(
-          x: hash.fetch(:x, 0),
-          y: hash.fetch(:y, 0),
-          width: hash.fetch(:width, 0),
-          height: hash.fetch(:height, 0)
-        )
-      end
-      raw_rects = _split(area, direction, constraints, flex)
-      raw_rects.map { |r| Rect.new(x: r[:x], y: r[:y], width: r[:width], height: r[:height]) }
-    end
-  end
-end

data/lib/ratatui_ruby/schema/line_gauge.rb

@@ -1,80 +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 compact, single-line progress bar.
-  #
-  # Screen space is precious. Standard block gauges are bulky and consume multiple rows.
-  #
-  # This widget compresses the feedback. It draws a progress bar using line characters, fitting perfectly into tight layouts or lists.
-  #
-  # Use it when you need to show status without stealing focus or space.
-  #
-  # {rdoc-image:/doc/images/widget_line_gauge.png}[link:/examples/widget_line_gauge/app_rb.html]
-  #
-  # === Example
-  #
-  # Run the interactive demo from the terminal:
-  #
-  #   ruby examples/widget_line_gauge/app.rb
-  class LineGauge < Data.define(:ratio, :label, :style, :filled_style, :unfilled_style, :block, :filled_symbol, :unfilled_symbol)
-    ##
-    # :attr_reader: ratio
-    # Progress ratio from 0.0 to 1.0.
-
-    ##
-    # :attr_reader: label
-    # Optional label (String or Text::Span for rich styling).
-
-    ##
-    # :attr_reader: style
-    # Base style applied to the entire gauge.
-
-    ##
-    # :attr_reader: filled_style
-    # Style for the completed portion.
-
-    ##
-    # :attr_reader: unfilled_style
-    # Style for the remainder.
-
-    ##
-    # :attr_reader: block
-    # Optional wrapping block.
-
-    ##
-    # :attr_reader: filled_symbol
-    # Character for filled segments.
-
-    ##
-    # :attr_reader: unfilled_symbol
-    # Character for empty segments.
-
-    # Creates a new LineGauge.
-    #
-    # [ratio] Float (0.0 - 1.0).
-    # [label] String or Text::Span (optional).
-    # [style] Style (optional, base style for the gauge).
-    # [filled_style] Style.
-    # [unfilled_style] Style.
-    # [block] Block.
-    # [filled_symbol] String (default: <tt>"█"</tt>).
-    # [unfilled_symbol] String (default: <tt>"░"</tt>).
-    def initialize(ratio: 0.0, label: nil, style: nil, filled_style: nil, unfilled_style: nil, block: nil, filled_symbol: "█", unfilled_symbol: "░")
-      super(
-        ratio: Float(ratio),
-        label:,
-        style:,
-        filled_style:,
-        unfilled_style:,
-        block:,
-        filled_symbol:,
-        unfilled_symbol:
-      )
-    end
-  end
-end

data/lib/ratatui_ruby/schema/list.rb

@@ -1,135 +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 selectable list of items.
-  #
-  # Users need to choose from options. Menus, file explorers, and selectors are everywhere.
-  # Implementing navigation, highlighting, and scrolling state from scratch is tedious.
-  #
-  # This widget manages the list. It renders the items. It highlights the selection. It handles the scrolling window.
-  #
-  # Use it to build main menus, navigation sidebars, or logs.
-  #
-  # {rdoc-image:/doc/images/widget_list.png}[link:/examples/widget_list/app_rb.html]
-  #
-  # === Examples
-  #
-  #--
-  # SPDX-SnippetBegin
-  # SPDX-FileCopyrightText: 2025 Kerrick Long
-  # SPDX-License-Identifier: MIT-0
-  #++
-  #   # Basic List
-  #   List.new(items: ["Item 1", "Item 2"])
-  #
-  #   # Navigation Menu
-  #   List.new(
-  #     items: ["New Game", "Load Game", "Options", "Quit"],
-  #     selected_index: 0,
-  #     highlight_style: Style.new(bg: :blue),
-  #     highlight_symbol: ">> "
-  #   )
-  #--
-  # SPDX-SnippetEnd
-  #++
-  class List < Data.define(:items, :selected_index, :offset, :style, :highlight_style, :highlight_symbol, :repeat_highlight_symbol, :highlight_spacing, :direction, :scroll_padding, :block)
-    ##
-    # :attr_reader: items
-    # The items to display.
-    #
-    # Accepts Array of Strings, Text::Spans, Text::Lines, or ListItem objects.
-    # For styled individual rows, use ListItem with a style.
-
-    ##
-    # :attr_reader: selected_index
-    # Index of the active selection (Integer or nil).
-
-    ##
-    # :attr_reader: offset
-    # Scroll offset (Integer or nil).
-    #
-    # Controls the viewport's starting position in the list.
-    #
-    # When +nil+ (default), Ratatui auto-scrolls to keep the selection visible ("natural scrolling").
-    #
-    # When set, forces the viewport to start at this item index. Use this for:
-    # - **Passive scrolling**: Scroll through a log viewer without selecting items.
-    # - **Click-to-select math**: Calculate which item index corresponds to a click coordinate.
-    #
-    # *Important*: When both +offset+ and +selected_index+ are set, Ratatui may still adjust
-    # the viewport during rendering to ensure the selection stays visible. Set +selected_index+
-    # to +nil+ for fully manual scroll control.
-
-    ##
-    # :attr_reader: style
-    # Base style for unselected items.
-
-    ##
-    # :attr_reader: highlight_style
-    # Style for the selected item.
-
-    ##
-    # :attr_reader: highlight_symbol
-    # Symbol drawn before the selected item.
-
-    ##
-    # :attr_reader: repeat_highlight_symbol
-    # Whether to repeat the highlight symbol for each line of the selected item.
-
-    ##
-    # :attr_reader: highlight_spacing
-    # When to show the highlight symbol column.
-    #
-    # <tt>:always</tt>, <tt>:when_selected</tt>, or <tt>:never</tt>.
-
-    ##
-    # :attr_reader: direction
-    # Render direction.
-    #
-    # <tt>:top_to_bottom</tt> or <tt>:bottom_to_top</tt>.
-
-    ##
-    # :attr_reader: scroll_padding
-    # Number of items to keep visible above/below the selected item when scrolling (Integer or nil).
-
-    ##
-    # :attr_reader: block
-    # Optional wrapping block.
-
-    # Creates a new List.
-    #
-    # Integer parameters accept any object responding to +to_int+ or +to_i+ (duck-typed).
-    #
-    # [items] Array of Strings, Text::Spans, Text::Lines, or ListItem objects.
-    # [selected_index] Numeric (nullable, coerced to Integer).
-    # [offset] Numeric (nullable, coerced to Integer). Forces scroll position when set.
-    # [style] Style object.
-    # [highlight_style] Style object.
-    # [highlight_symbol] String (default: <tt>"> "</tt>).
-    # [repeat_highlight_symbol] Boolean (default: <tt>false</tt>).
-    # [highlight_spacing] Symbol (default: <tt>:when_selected</tt>).
-    # [direction] Symbol (default: <tt>:top_to_bottom</tt>).
-    # [scroll_padding] Numeric (nullable, coerced to Integer, default: <tt>nil</tt>).
-    # [block] Block (optional).
-    def initialize(items: [], selected_index: nil, offset: nil, style: nil, highlight_style: nil, highlight_symbol: "> ", repeat_highlight_symbol: false, highlight_spacing: :when_selected, direction: :top_to_bottom, scroll_padding: nil, block: nil)
-      super(
-        items:,
-        selected_index: selected_index.nil? ? nil : Integer(selected_index),
-        offset: offset.nil? ? nil : Integer(offset),
-        style:,
-        highlight_style:,
-        highlight_symbol:,
-        repeat_highlight_symbol:,
-        highlight_spacing:,
-        direction:,
-        scroll_padding: scroll_padding.nil? ? nil : Integer(scroll_padding),
-        block:
-      )
-    end
-  end
-end

data/lib/ratatui_ruby/schema/list_item.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
-  # A styled list item combining content with optional style.
-  #
-  # By default, List items are strings. For more control over styling individual rows,
-  # wrap the content in a ListItem to apply a style specific to that item.
-  #
-  # The content can be a String, Text::Span, or Text::Line. The style applies to the
-  # entire row background.
-  #
-  # === Examples
-  #
-  #--
-  # SPDX-SnippetBegin
-  # SPDX-FileCopyrightText: 2026 Kerrick Long
-  # SPDX-License-Identifier: MIT-0
-  #++
-  #   # Item with red background
-  #   ListItem.new(content: "Error", style: Style.new(bg: :red))
-  #
-  #   # Item with styled content
-  #   ListItem.new(
-  #     content: Text::Span.new(content: "Status: OK", style: Style.new(fg: :green, modifiers: [:bold]))
-  #   )
-  #--
-  # SPDX-SnippetEnd
-  #++
-  class ListItem < Data.define(:content, :style)
-    ##
-    # :attr_reader: content
-    # The content to display (String, Text::Span, or Text::Line).
-
-    ##
-    # :attr_reader: style
-    # The style to apply to the item (optional Style).
-
-    # Creates a new ListItem.
-    #
-    # [content] String, Text::Span, or Text::Line.
-    # [style] Style object (optional).
-    def initialize(content:, style: nil)
-      super
-    end
-  end
-end