ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/widgets/list_item.rb

@@ -0,0 +1,55 @@
+# 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 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)
+      include CoerceableWidget
+
+      ##
+      # :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
+end

data/lib/ratatui_ruby/widgets/overlay.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # 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: 2026 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)
+      include CoerceableWidget
+
+      ##
+      # :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
+end

data/lib/ratatui_ruby/widgets/paragraph.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # 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.
+    #
+    # See also: <tt>examples/widget_scroll_text/app.rb</tt> for scrollable paragraphs.
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 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)
+      include CoerceableWidget
+
+      ##
+      # :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: RatatuiRuby::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 ||= RatatuiRuby::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
+end

data/lib/ratatui_ruby/widgets/ratatui_logo.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # 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
+      include CoerceableWidget
+
+      ##
+      # :method: new
+      # :call-seq: new -> RatatuiLogo
+      #
+      # Creates a new RatatuiLogo.
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/ratatui_mascot.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # 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)
+      include CoerceableWidget
+
+      ##
+      # :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
+end

data/lib/ratatui_ruby/widgets/row.rb

@@ -0,0 +1,123 @@
+# 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 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)
+      include CoerceableWidget
+
+      ##
+      # :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
+
+      # Returns a new Row with strikethrough styling enabled.
+      #
+      # Table rows sometimes need strikethrough styling to indicate
+      # deleted, deprecated, or cancelled items. Manually managing
+      # style modifiers is tedious.
+      #
+      # This method adds the <tt>:crossed_out</tt> modifier to the row's
+      # style. If the row has no existing style, a new style is created.
+      #
+      # Use it to visually mark rows as cancelled, completed, or invalid.
+      #
+      # *Terminal Compatibility:* Strikethrough (SGR 9) is not universally
+      # supported. macOS Terminal.app notably lacks support. Modern terminals
+      # like Kitty, iTerm2, Alacritty, and WezTerm render it correctly.
+      # Consider pairing with <tt>:dim</tt> as a fallback for visibility.
+      #
+      # Returns a new Row instance with strikethrough enabled.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   row = Row.new(cells: ["Cancelled Task", "2024-01-15"])
+      #   strikethrough_row = row.enable_strikethrough
+      #   # Row style now includes :crossed_out modifier
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def enable_strikethrough
+        current_style = style || Style::Style.new
+        current_modifiers = current_style.modifiers || []
+        new_modifiers = current_modifiers.include?(:crossed_out) ? current_modifiers : current_modifiers + [:crossed_out]
+
+        new_style = current_style.with(modifiers: new_modifiers)
+        with(style: new_style)
+      end
+
+      # Ruby-idiomatic alias
+      alias strikethrough enable_strikethrough
+    end
+  end
+end

data/lib/ratatui_ruby/widgets/scrollbar.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    # 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
+    )
+      include CoerceableWidget
+
+      ##
+      # :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
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Widgets
+    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: 2026 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)
+        include CoerceableWidget
+
+        ##
+        # :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
+end