ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/text/span.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Text
+    # A styled string fragment.
+    #
+    # Text is rarely uniform. You need to bold a keyword, colorize an error, or dim a timestamp.
+    #
+    # This class attaches style to content. It pairs a string with visual attributes.
+    #
+    # combine spans into a {Line} to create rich text.
+    #
+    # === Examples
+    #
+    #   Text::Span.new(content: "Error", style: Style.new(fg: :red, modifiers: [:bold]))
+    class Span < Data.define(:content, :style)
+      ##
+      # :attr_reader: content
+      # The text content.
+
+      ##
+      # :attr_reader: style
+      # The style to apply.
+
+      # Creates a new Span.
+      #
+      # [content] String.
+      # [style] Style object (optional).
+      def initialize(content:, style: nil)
+        super
+      end
+
+      # Concise helper for styling.
+      #
+      # === Example
+      #
+      #   Text::Span.styled("Bold", Style::Style.new(modifiers: [:bold]))
+      def self.styled(content, style = nil)
+        new(content:, style:)
+      end
+
+      # Returns the unicode display width of the content in terminal cells.
+      #
+      # CJK characters and emoji count as 2 cells. ASCII characters count as 1 cell.
+      # Use this to measure how much horizontal space a span will occupy.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   span = Text::Span.new(content: "Hello")
+      #   span.width  # => 5
+      #
+      #   span = Text::Span.new(content: "你好")  # Chinese characters
+      #   span.width  # => 4
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Integer.
+      def width
+        RatatuiRuby::Text.width(content.to_s)
+      end
+
+      # Creates a span with the default style.
+      #
+      # Use this factory method when you want unstyled text. It mirrors the Ratatui API.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   span = Text::Span.raw("test content")
+      #   span.content  # => "test content"
+      #   span.style    # => nil
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [content] String.
+      #
+      # Returns: Span.
+      def self.raw(content)
+        new(content:)
+      end
+
+      # Patches the style of the span, merging modifiers from the given style.
+      #
+      # Non-nil values from the patch style override the existing style. Use this when you want to
+      # layer styles without replacing the entire style. Colors in the patch take precedence over
+      # existing colors. Modifiers are combined.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   span = Text::Span.new(content: "test", style: Style::Style.new(fg: :green))
+      #   patched = span.patch_style(Style::Style.new(bg: :yellow, modifiers: [:bold]))
+      #   patched.style.fg  # => :green (preserved)
+      #   patched.style.bg  # => :yellow (added)
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [patch] Style::Style to merge.
+      #
+      # Returns: Span.
+      def patch_style(patch)
+        return self if patch.nil?
+        return with(style: patch) if style.nil?
+
+        merged = Style::Style.new(
+          fg: patch.fg.nil? ? style.fg : patch.fg,
+          bg: patch.bg.nil? ? style.bg : patch.bg,
+          modifiers: patch.modifiers.empty? ? style.modifiers : (style.modifiers + patch.modifiers).uniq
+        )
+        with(style: merged)
+      end
+
+      # Resets the style of the span.
+      #
+      # Returns a new span with no style applied. Use this to strip all styling.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   span = Text::Span.new(content: "styled", style: Style::Style.new(fg: :red))
+      #   reset = span.reset_style
+      #   reset.style  # => nil
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Span.
+      def reset_style
+        with(style: nil)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/text.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Namespace for rich text components (Span, Line) and text utilities.
+  # Distinct from canvas shapes and other Line usages.
+  #
+  # == Text Measurement
+  #
+  # The Text module provides a utility method for calculating the display width
+  # of strings in terminal cells. This accounts for unicode complexity:
+  #
+  # - ASCII characters: 1 cell each
+  # - CJK (Chinese, Japanese, Korean) characters: 2 cells each (full-width)
+  # - Emoji: typically 2 cells each (varies by terminal)
+  # - Combining marks: 0 cells (zero-width)
+  #
+  # This is essential for layout calculations in TUI applications, where you need to know
+  # how much space a string will occupy on the screen, not just its byte or character length.
+  #
+  # === Use Cases
+  #
+  # - Auto-sizing widgets (Button, Badge) that fit their content
+  # - Calculating padding or centering for text alignment
+  # - Building responsive layouts that adapt to content width
+  # - Measuring text for scrolling or truncation logic
+  #
+  # === Examples
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   # Simple ASCII text
+  #   RatatuiRuby::Text.width("Hello")        # => 5
+  #
+  #   # With emoji
+  #   RatatuiRuby::Text.width("Hello 👍")     # => 8 (5 + space + 2-width emoji)
+  #
+  #   # With CJK characters
+  #   RatatuiRuby::Text.width("你好")         # => 4 (each CJK char is 2 cells)
+  #
+  #   # Mixed content
+  #   RatatuiRuby::Text.width("Hi 你好 👍")   # => 11 (2 + space + 4 + space + 2)
+  #--
+  # SPDX-SnippetEnd
+  #++
+  module Text
+    ##
+    # :method: width
+    # :call-seq: width(string) -> Integer
+    #
+    # Calculates the display width of a string in terminal cells.
+    #
+    # Layout demands precision. Terminals measure space in cells, not characters. An ASCII letter occupies one cell. A Chinese character occupies two. An emoji occupies two. Combining marks occupy zero.
+    #
+    # Measuring width manually is error-prone. You can count <tt>string.length</tt>, but that counts characters, not cells. A string with one emoji counts as 1 character but occupies 2 cells.
+    #
+    # This method returns the true display width. Use it to auto-size widgets, calculate padding, center text, or build responsive layouts.
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   RatatuiRuby::Text.width("Hello")        # => 5 (5 ASCII chars × 1 cell)
+    #
+    #   RatatuiRuby::Text.width("你好")         # => 4 (2 CJK chars × 2 cells)
+    #
+    #   RatatuiRuby::Text.width("Hello 👍")     # => 8 (5 ASCII + 1 space + 1 emoji × 2)
+    #
+    #   # In the Session DSL (easier)
+    #   RatatuiRuby.run do |tui|
+    #     width = tui.text_width("Hello 👍")
+    #   end
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # [string] String to measure (String or object convertible to String)
+    # Returns: Integer (number of terminal cells the string occupies)
+    # Raises: TypeError if the argument is not a String
+    #
+    # (Native method implemented in Rust)
+    def self.width(string)
+      RatatuiRuby._text_width(string)
+    end
+  end
+end
+
+require_relative "text/span"
+require_relative "text/line"

data/lib/ratatui_ruby/tui/buffer_factories.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class TUI
+    # Buffer inspection factory methods for Session.
+    #
+    # Provides convenient access to Buffer::Cell for testing
+    # and buffer inspection purposes.
+    module BufferFactories
+      # Creates a Buffer::Cell (for testing).
+      # @return [Buffer::Cell]
+      def cell(...)
+        Buffer::Cell.new(...)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tui/canvas_factories.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class TUI
+    # Canvas shape factory methods for Session.
+    #
+    # Provides convenient access to Widgets::Shape::* classes
+    # for creating custom drawings on Canvas widgets.
+    module CanvasFactories
+      # Creates a map shape for Canvas.
+      # @return [Widgets::Shape::Map]
+      def shape_map(...)
+        Widgets::Shape::Map.new(...)
+      end
+
+      # Creates a line shape for Canvas.
+      # @return [Widgets::Shape::Line]
+      def shape_line(...)
+        Widgets::Shape::Line.new(...)
+      end
+
+      # Creates a point (single pixel) shape for Canvas.
+      # @return [Widgets::Shape::Point]
+      def shape_point(...)
+        Widgets::Shape::Point.new(...)
+      end
+
+      # Creates a circle shape for Canvas.
+      # @return [Widgets::Shape::Circle]
+      def shape_circle(...)
+        Widgets::Shape::Circle.new(...)
+      end
+
+      # Creates a rectangle shape for Canvas.
+      # @return [Widgets::Shape::Rectangle]
+      def shape_rectangle(...)
+        Widgets::Shape::Rectangle.new(...)
+      end
+
+      # =====================================
+      # Terse Shape Aliases (DWIM)
+      # =====================================
+
+      # Creates a circle shape (terse alias).
+      # @return [Widgets::Shape::Circle]
+      alias circle shape_circle
+
+      # Creates a point shape (terse alias).
+      # @return [Widgets::Shape::Point]
+      alias point shape_point
+
+      # NOTE: No terse 'rectangle' alias - would conflict with Layout::Rect concept.
+      # Use shape_rectangle() explicitly.
+
+      # Creates a map shape (terse alias).
+      # @return [Widgets::Shape::Map]
+      alias map shape_map
+
+      # Creates a label shape (terse alias).
+      #
+      # Note: shape_label is defined in WidgetFactories.
+      # @return [Widgets::Shape::Label]
+      def label(first = nil, **kwargs)
+        Widgets::Shape::Label.coerce_args(first, kwargs)
+      end
+
+      # =====================================
+      # Bidirectional Shape Aliases (*_shape)
+      # =====================================
+
+      # Creates a circle shape (bidirectional alias).
+      # @return [Widgets::Shape::Circle]
+      alias circle_shape shape_circle
+
+      # Creates a point shape (bidirectional alias).
+      # @return [Widgets::Shape::Point]
+      alias point_shape shape_point
+
+      # Creates a rectangle shape (bidirectional alias).
+      # Note: Terse 'rectangle' is intentionally excluded to avoid confusion with Layout::Rect,
+      # but 'rectangle_shape' is unambiguous.
+      # @return [Widgets::Shape::Rectangle]
+      alias rectangle_shape shape_rectangle
+
+      # Creates a map shape (bidirectional alias).
+      # @return [Widgets::Shape::Map]
+      alias map_shape shape_map
+
+      # Creates a label shape (bidirectional alias).
+      # @return [Widgets::Shape::Label]
+      alias label_shape label
+
+      # =====================================
+      # Shape Dispatcher (TIMTOWTDI)
+      # =====================================
+
+      # Creates a shape by type symbol.
+      #
+      # Hard-coding method names limits flexibility. Programmatic shape creation
+      # from user input or config files requires tedious case statements.
+      #
+      # This dispatcher routes shape creation through a single entry point.
+      # Pass the type as a symbol and the remaining parameters as kwargs.
+      #
+      # Use it for dynamic shape generation, config-driven UIs, or when you
+      # prefer explicit type specification over method names.
+      #
+      # Also available as: <tt>tui.circle</tt>, <tt>tui.shape_circle</tt>
+      #
+      # === Examples
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   # Direct dispatch
+      #   tui.shape(:circle, x: 5.0, y: 5.0, radius: 2.5, color: :red)
+      #
+      #   # Dynamic shape creation from config
+      #   config = { type: :rectangle, x: 0.0, y: 0.0, width: 10.0, height: 10.0 }
+      #   tui.shape(config[:type], **config.except(:type))
+      #--
+      # SPDX-SnippetEnd
+      #++
+      #
+      # @param type [Symbol] Shape type: :circle, :line, :point, :rectangle, :map, :label
+      # @return [Widgets::Shape::*]
+      def shape(type, **)
+        case type
+        when :circle then shape_circle(**)
+        when :line then shape_line(**)
+        when :point then shape_point(**)
+        when :rectangle then shape_rectangle(**)
+        when :map then shape_map(**)
+        when :label then label(**)
+        else
+          raise ArgumentError, "Unknown shape type: #{type.inspect}. " \
+            "Valid types: :circle, :line, :point, :rectangle, :map, :label"
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tui/core.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class TUI
+    # Core terminal methods delegated to RatatuiRuby module.
+    #
+    # These are the fundamental operations for the render loop:
+    # drawing UI, polling events, and inspecting the buffer.
+    module Core
+      # Draws the given UI node tree to the terminal.
+      # @see RatatuiRuby.draw
+      def draw(tree = nil, &block)
+        if tree && block
+          raise ArgumentError, "Cannot provide both a tree and a block to draw"
+        end
+        unless tree || block
+          raise ArgumentError, "Must provide either a tree or a block to draw"
+        end
+
+        if block
+          RatatuiRuby.draw(&block)
+        else
+          RatatuiRuby.draw(tree)
+        end
+      end
+
+      # Checks for user input.
+      # @see RatatuiRuby.poll_event
+      def poll_event(timeout: 0.016)
+        RatatuiRuby.poll_event(timeout:)
+      end
+
+      # Inspects the terminal buffer at specific coordinates.
+      # @see RatatuiRuby.get_cell_at
+      def get_cell_at(x, y)
+        RatatuiRuby.get_cell_at(x, y)
+      end
+
+      # Creates a Draw::CellCmd for placing a cell at coordinates.
+      # @return [Draw::CellCmd]
+      def draw_cell(x, y, cell)
+        Draw.cell(x, y, cell)
+      end
+
+      # Inserts content above an inline viewport.
+      # @see RatatuiRuby.insert_before
+      def insert_before(height, widget = nil, &)
+        RatatuiRuby.insert_before(height, widget, &)
+      end
+
+      # Gets the Rect of the entire terminal, regardless of viewport
+      def terminal_area
+        RatatuiRuby.terminal_area
+      end
+
+      # Gets the Rect of the viewport
+      def viewport_area
+        RatatuiRuby.viewport_area
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tui/layout_factories.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class TUI
+    # Layout factory methods for Session.
+    #
+    # Provides convenient access to Layout::Rect, Layout::Constraint,
+    # and Layout::Layout without fully qualifying the class names.
+    module LayoutFactories
+      # Creates a Layout::Rect.
+      # @return [Layout::Rect]
+      def rect(...)
+        Layout::Rect.new(...)
+      end
+
+      # Creates a Layout::Constraint, with optional type-based dispatch.
+      #
+      # When called with a type symbol as the first argument, dispatches to
+      # the appropriate constraint factory (TIMTOWTDI pattern).
+      #
+      # Also available as: <tt>tui.percent(50)</tt>, <tt>tui.flex(1)</tt>
+      #
+      # === Examples
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   tui.constraint(:length, 10)     # => Constraint.length(10)
+      #   tui.constraint(:percentage, 50) # => Constraint.percentage(50)
+      #   tui.constraint(:min, 5)         # => Constraint.min(5)
+      #   tui.constraint(:fill, 2)        # => Constraint.fill(2)
+      #   tui.constraint(:ratio, 1, 3)    # => Constraint.ratio(1, 3)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # @return [Layout::Constraint]
+      def constraint(type_or_arg = nil, arg1 = nil, arg2 = nil, **)
+        # Type-based dispatch when first arg is a symbol
+        if type_or_arg.is_a?(Symbol)
+          case type_or_arg
+          when :length, :fixed
+            constraint_length(arg1 || raise(ArgumentError, "#{type_or_arg} requires a value"))
+          when :percentage, :percent
+            constraint_percentage(arg1 || raise(ArgumentError, "#{type_or_arg} requires a value"))
+          when :min
+            constraint_min(arg1 || raise(ArgumentError, "min requires a value"))
+          when :max
+            constraint_max(arg1 || raise(ArgumentError, "max requires a value"))
+          when :fill, :flex, :fr
+            constraint_fill(arg1 || 1)
+          when :ratio, :aspect
+            n = arg1 || raise(ArgumentError, "ratio requires numerator")
+            d = arg2 || raise(ArgumentError, "ratio requires denominator")
+            constraint_ratio(n, d)
+          else
+            # Use to_s since type_or_arg must be a Symbol here
+            raise ArgumentError, "Unknown constraint type: :#{type_or_arg}. " \
+              "Valid types: :length, :percentage, :min, :max, :fill, :ratio"
+          end
+        elsif type_or_arg.nil? && arg1.nil?
+          Layout::Constraint.new(**)
+        else
+          Layout::Constraint.new(type_or_arg, arg1, arg2, **)
+        end
+      end
+
+      # Creates a Layout::Constraint.length.
+      # @return [Layout::Constraint]
+      def constraint_length(n)
+        Layout::Constraint.length(n)
+      end
+
+      # Creates a Layout::Constraint.percentage.
+      # @return [Layout::Constraint]
+      def constraint_percentage(n)
+        Layout::Constraint.percentage(n)
+      end
+
+      # Creates a Layout::Constraint.min.
+      # @return [Layout::Constraint]
+      def constraint_min(n)
+        Layout::Constraint.min(n)
+      end
+
+      # Creates a Layout::Constraint.max.
+      # @return [Layout::Constraint]
+      def constraint_max(n)
+        Layout::Constraint.max(n)
+      end
+
+      # Creates a Layout::Constraint.fill.
+      # @return [Layout::Constraint]
+      def constraint_fill(n = 1)
+        Layout::Constraint.fill(n)
+      end
+
+      # Creates a Layout::Constraint.ratio.
+      # @return [Layout::Constraint]
+      def constraint_ratio(numerator, denominator)
+        Layout::Constraint.ratio(numerator, denominator)
+      end
+
+      # Creates a Layout::Layout.
+      # @return [Layout::Layout]
+      def layout(...)
+        Layout::Layout.new(...)
+      end
+
+      # Splits an area using Layout::Layout.split.
+      # @return [Array<Layout::Rect>]
+      def layout_split(area, direction: :vertical, constraints:, flex: :legacy)
+        Layout::Layout.split(area, direction:, constraints:, flex:)
+      end
+
+      # Alias for {#layout_split} — shorter, more ergonomic.
+      # @return [Array<Layout::Rect>]
+      def split(area, direction: :vertical, constraints:, flex: :legacy)
+        layout_split(area, direction:, constraints:, flex:)
+      end
+
+      # Alias for {#constraint_length} — CSS-inspired "fixed" sizing.
+      # @return [Layout::Constraint]
+      def fixed(n)
+        constraint_length(n)
+      end
+
+      # Alias for {#constraint_percentage} — CSS-inspired percent sizing.
+      # @return [Layout::Constraint]
+      def percent(n)
+        constraint_percentage(n)
+      end
+
+      # Alias for {#constraint_fill} — CSS Flexbox-inspired flexible sizing.
+      # @return [Layout::Constraint]
+      def flex(n = 1)
+        constraint_fill(n)
+      end
+
+      # Alias for {#constraint_fill} — CSS Grid-inspired "fr" (fraction) unit.
+      # @return [Layout::Constraint]
+      def fr(n = 1)
+        constraint_fill(n)
+      end
+    end
+  end
+end