ratatui_ruby 0.9.1 → 0.10.0

data/lib/ratatui_ruby/text/line.rb

@@ -0,0 +1,245 @@
+# 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 sequence of styled spans.
+    #
+    # Words form sentences. Spans form lines.
+    #
+    # This class composes multiple {Span} objects into a single horizontal row of text.
+    # It handles the layout of rich text fragments within the flow of a paragraph.
+    #
+    # Use it to build multi-colored headers, status messages, or log entries.
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   Text::Line.new(
+    #     spans: [
+    #       Text::Span.styled("User: ", Style.new(modifiers: [:bold])),
+    #       Text::Span.styled("kerrick", Style.new(fg: :blue))
+    #     ]
+    #   )
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Line < Data.define(:spans, :alignment, :style)
+      ##
+      # :attr_reader: spans
+      # Array of Span objects.
+
+      ##
+      # :attr_reader: alignment
+      # Alignment within the container.
+      #
+      # <tt>:left</tt>, <tt>:center</tt>, or <tt>:right</tt>.
+
+      ##
+      # :attr_reader: style
+      # Line-level style applied to all spans.
+      #
+      # A Style object that sets colors/modifiers for the entire line.
+
+      # Creates a new Line.
+      #
+      # [spans] Array of Span objects (or Strings).
+      # [alignment] Symbol (optional).
+      # [style] Style object (optional).
+      def initialize(spans: [], alignment: nil, style: nil)
+        super
+      end
+
+      # Creates a simple line from a string.
+      #
+      #   Text::Line.from_string("Hello")
+      def self.from_string(content, alignment: nil)
+        new(spans: [Span.new(content:, style: nil)], alignment:)
+      end
+
+      # Calculates the display width of this line in terminal cells.
+      #
+      # Sums the widths of all span contents using the same unicode-aware
+      # algorithm as Text.width. Useful for layout calculations.
+      #
+      # === Examples
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [
+      #     Text::Span.new(content: "Hello "),
+      #     Text::Span.new(content: "世界")
+      #   ])
+      #   line.width  # => 10 (6 ASCII + 4 CJK)
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Integer (number of terminal cells).
+      def width
+        RatatuiRuby::Text.width(spans.map { |s| s.content.to_s }.join)
+      end
+
+      # Left-aligns this line of text.
+      #
+      # Convenience shortcut for <tt>alignment: :left</tt>. Setting the alignment of a Line
+      # overrides the alignment of its parent Text or Widget.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
+      #   aligned = line.left_aligned
+      #   aligned.alignment  # => :left
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Line.
+      def left_aligned
+        with(alignment: :left)
+      end
+
+      # Center-aligns this line of text.
+      #
+      # Convenience shortcut for <tt>alignment: :center</tt>. Setting the alignment of a Line
+      # overrides the alignment of its parent Text or Widget.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
+      #   centered = line.centered
+      #   centered.alignment  # => :center
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Line.
+      def centered
+        with(alignment: :center)
+      end
+
+      # Right-aligns this line of text.
+      #
+      # Convenience shortcut for <tt>alignment: :right</tt>. Setting the alignment of a Line
+      # overrides the alignment of its parent Text or Widget.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
+      #   aligned = line.right_aligned
+      #   aligned.alignment  # => :right
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Line.
+      def right_aligned
+        with(alignment: :right)
+      end
+
+      # Adds a span to the line.
+      #
+      # Since Line is immutable (a Data subclass), this returns a new Line with the span appended.
+      # The original line remains unchanged.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello, ")])
+      #   extended = line.push_span(Text::Span.new(content: "world!"))
+      #   extended.spans.size  # => 2
+      #   line.spans.size      # => 1 (original unchanged)
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [span] Span to append.
+      #
+      # Returns: Line.
+      def push_span(span)
+        with(spans: spans + [span])
+      end
+
+      # Patches the style of this line, adding modifiers from the given style.
+      #
+      # Applies <tt>patch_style</tt> to each span in the line. Use this when you want to layer
+      # styles on all spans without replacing their existing styles.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
+      #   styled = line.patch_style(Style::Style.new(fg: :red))
+      #   styled.spans.first.style.fg  # => :red
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # [patch] Style::Style to merge onto each span.
+      #
+      # Returns: Line.
+      def patch_style(patch)
+        with(spans: spans.map { |s| s.patch_style(patch) })
+      end
+
+      # Resets the style of this line.
+      #
+      # Applies <tt>reset_style</tt> to each span in the line, clearing all styling.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   line = Text::Line.new(spans: [
+      #     Text::Span.new(content: "styled", style: Style::Style.new(fg: :red))
+      #   ])
+      #   reset = line.reset_style
+      #   reset.spans.first.style  # => nil
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # Returns: Line.
+      def reset_style
+        with(spans: spans.map(&:reset_style))
+      end
+    end
+  end
+end

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/canvas_factories.rb

@@ -41,6 +41,109 @@ module RatatuiRuby
       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

@@ -14,8 +14,19 @@ module RatatuiRuby
     module Core
       # Draws the given UI node tree to the terminal.
       # @see RatatuiRuby.draw
-      def draw(tree = nil, &)
-        RatatuiRuby.draw(tree, &)
+      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.

data/lib/ratatui_ruby/tui/layout_factories.rb

@@ -18,10 +18,57 @@ module RatatuiRuby
         Layout::Rect.new(...)
       end
 
-      # Creates a Layout::Constraint.
+      # 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(...)
-        Layout::Constraint.new(...)
+      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.