ratatui_ruby 0.9.1 → 0.10.0

data/lib/ratatui_ruby/layout/rect.rb

@@ -379,6 +379,37 @@ module RatatuiRuby
         )
       end
 
+      # Expands the rect by a uniform margin on all sides.
+      #
+      # Containers wrap content with decorations. Adding margin to all four edges inline is verbose.
+      # Off-by-one errors happen when you forget to double the margin.
+      #
+      # This method computes the outer area. Saturates x/y at 0 when margin exceeds position.
+      # Use Rect#clamp to constrain the result if it may exceed screen bounds.
+      #
+      # [margin] Integer expansion on all sides.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 10, width: 20, height: 10)
+      #   rect.outer(5) # => Rect(x: 5, y: 5, width: 30, height: 20)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def outer(margin)
+        new_x = [x - margin, 0].max
+        new_y = [y - margin, 0].max
+        new_width = right + margin - new_x
+        new_height = bottom + margin - new_y
+
+        Rect.new(x: new_x, y: new_y, width: new_width, height: new_height)
+      end
+
       # Moves the rect without changing size.
       #
       # Animations and drag-and-drop shift widgets.
@@ -405,6 +436,32 @@ module RatatuiRuby
         Rect.new(x: x + dx, y: y + dy, width:, height:)
       end
 
+      # Changes dimensions while preserving position.
+      #
+      # Window resizing and responsive layouts adjust size mid-session.
+      # Creating a new rect with the same position but different size is common.
+      #
+      # This method returns a resized copy. Position unchanged.
+      #
+      # [new_size] Size object with new dimensions.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 5, width: 20, height: 10)
+      #   rect.resize(Size.new(width: 40, height: 20))
+      #   # => Rect(x: 10, y: 5, width: 40, height: 20)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def resize(new_size)
+        Rect.new(x:, y:, width: new_size.width, height: new_size.height)
+      end
+
       # Constrains the rect to fit inside bounds.
       #
       # Popups and tooltips may extend beyond screen edges.
@@ -516,6 +573,137 @@ module RatatuiRuby
           end
         end
       end
+
+      # Extracts the position (x, y) from this rect.
+      #
+      # Layout code sometimes separates position from size.
+      # Extracting x and y into multiple variables is verbose.
+      #
+      # This method returns a Position object containing just the coordinates.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 5, width: 80, height: 24)
+      #   rect.as_position # => Position(x: 10, y: 5)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def as_position
+        Position.new(x:, y:)
+      end
+
+      # Extracts the size (width, height) from this rect.
+      #
+      # Layout code sometimes separates size from position.
+      # Extracting width and height into multiple variables is verbose.
+      #
+      # This method returns a Size object containing just the dimensions.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 10, y: 5, width: 80, height: 24)
+      #   rect.as_size # => Size(width: 80, height: 24)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def as_size
+        Size.new(width:, height:)
+      end
+
+      # Returns a new Rect, centered horizontally within this rect based on the constraint.
+      #
+      # Modal dialogs and centered content need horizontal centering.
+      # Computing the left offset manually is error-prone.
+      #
+      # This method uses Layout to compute the centered position.
+      #
+      # [constraint] Constraint defining the width of the centered area.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 0, y: 0, width: 100, height: 24)
+      #   rect.centered_horizontally(Constraint.length(40))
+      #   # => Rect(x: 30, y: 0, width: 40, height: 24)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def centered_horizontally(constraint)
+        areas = Layout.split(self, direction: :horizontal, constraints: [constraint], flex: :center)
+        areas.first
+      end
+
+      # Returns a new Rect, centered vertically within this rect based on the constraint.
+      #
+      # Modal dialogs and centered content need vertical centering.
+      # Computing the top offset manually is error-prone.
+      #
+      # This method uses Layout to compute the centered position.
+      #
+      # [constraint] Constraint defining the height of the centered area.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 0, y: 0, width: 80, height: 100)
+      #   rect.centered_vertically(Constraint.length(20))
+      #   # => Rect(x: 0, y: 40, width: 80, height: 20)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def centered_vertically(constraint)
+        areas = Layout.split(self, direction: :vertical, constraints: [constraint], flex: :center)
+        areas.first
+      end
+
+      # Returns a new Rect, centered both horizontally and vertically within this rect.
+      #
+      # Modal dialogs often need exact centering on both axes.
+      # Computing both offsets manually is tedious.
+      #
+      # This method chains centered_horizontally and centered_vertically.
+      #
+      # [horizontal_constraint] Constraint defining the width of the centered area.
+      # [vertical_constraint] Constraint defining the height of the centered area.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   rect = Layout::Rect.new(x: 0, y: 0, width: 100, height: 100)
+      #   rect.centered(Constraint.length(40), Constraint.length(20))
+      #   # => Rect(x: 30, y: 40, width: 40, height: 20)
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def centered(horizontal_constraint, vertical_constraint)
+        centered_horizontally(horizontal_constraint).centered_vertically(vertical_constraint)
+      end
+
+      # Ruby-idiomatic aliases (TIMTOWTDI)
+      alias position as_position
+      alias size as_size
     end
   end
 end

data/lib/ratatui_ruby/layout/size.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 Layout
+    # Terminal dimensions as width and height.
+    #
+    # Layout calculations need sizes. Passing width and height
+    # as separate arguments is verbose and easy to swap by mistake.
+    #
+    # This class bundles dimensions into a single immutable object.
+    # Extract it from a Rect or create it directly for sizing operations.
+    #
+    # Use it for terminal dimensions, widget sizing constraints,
+    # or anywhere you need width/height without position.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   size = Layout::Size.new(width: 80, height: 24)
+    #   puts "Terminal is #{size.width} columns by #{size.height} rows"
+    #
+    #   # Extract from a Rect
+    #   rect = Layout::Rect.new(x: 10, y: 5, width: 80, height: 24)
+    #   size = rect.as_size # => Size(width: 80, height: 24)
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Size < Data.define(:width, :height)
+      ##
+      # :attr_reader: width
+      # Width in terminal columns.
+
+      ##
+      # :attr_reader: height
+      # Height in terminal rows.
+
+      # Creates a new Size.
+      #
+      # [width] Width in columns (Integer, coerced via +Integer()+).
+      # [height] Height in rows (Integer, coerced via +Integer()+).
+      def initialize(width: 0, height: 0)
+        super(width: Integer(width), height: Integer(height))
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/layout.rb

@@ -10,6 +10,8 @@ module RatatuiRuby
   #
   # This module mirrors +ratatui::layout+ and contains:
   # - {Rect} — Rectangle geometry
+  # - {Position} — Terminal coordinates
+  # - {Size} — Terminal dimensions
   # - {Constraint} — Sizing rules
   # - {Layout} — Space distribution
   module Layout
@@ -17,5 +19,7 @@ module RatatuiRuby
 end
 
 require_relative "layout/rect"
+require_relative "layout/position"
+require_relative "layout/size"
 require_relative "layout/constraint"
 require_relative "layout/layout"

data/lib/ratatui_ruby/style/color.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
+  module Style
+    # Color constructors for creating RGB color values.
+    #
+    # Styles accept colors in multiple formats: symbols (<tt>:red</tt>),
+    # indexed integers (0-255), or hex strings (<tt>"#FF0000"</tt>).
+    # Converting from other color representations manually is tedious.
+    #
+    # This module provides factory methods matching Ratatui's Color API.
+    # Convert from hex integers, HSL, or other formats in a single call.
+    #
+    # Use these constructors when you have color data in non-standard formats.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # From a hex integer (common in design tools)
+    #   red = Style::Color.from_u32(0xFF0000)
+    #   style = Style::Style.new(fg: red)
+    #
+    #   # From HSL (common in color pickers)
+    #   blue = Style::Color.from_hsl(240, 100, 50)
+    #   style = Style::Style.new(bg: blue)
+    #--
+    # SPDX-SnippetEnd
+    #++
+    module Color
+      class << self
+        # Creates a color from a 32-bit unsigned integer.
+        #
+        # Design tools and APIs often represent colors as hex integers.
+        # Manually extracting RGB components and formatting is error-prone.
+        #
+        # This method parses the integer and returns a hex string
+        # ready for use with Style.
+        #
+        # === Example
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   Color.from_u32(0xFF0000) # => "#ff0000" (red)
+        #   Color.from_u32(0x00FF00) # => "#00ff00" (green)
+        #   Color.from_u32(0x0000FF) # => "#0000ff" (blue)
+        #--
+        # SPDX-SnippetEnd
+        #++
+        #
+        # [value] Integer in <tt>0xRRGGBB</tt> format.
+        #
+        # Returns a hex string like <tt>"#rrggbb"</tt>.
+        def from_u32(value)
+          RatatuiRuby._color_from_u32(value)
+        end
+
+        # Creates a color from HSL (Hue, Saturation, Lightness) values.
+        #
+        # Color pickers often use HSL because it matches human perception
+        # better than RGB. Converting HSL to RGB manually requires math.
+        #
+        # This method handles the conversion by delegating to Ratatui's
+        # palette integration.
+        #
+        # Note: This implementation uses degrees (0-360) for hue and
+        # percentages (0-100) for saturation and lightness, matching
+        # common UI conventions.
+        #
+        # === Example
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   Color.from_hsl(0, 100, 50)   # => "#ff0000" (red)
+        #   Color.from_hsl(120, 100, 50) # => "#00ff00" (green)
+        #   Color.from_hsl(240, 100, 50) # => "#0000ff" (blue)
+        #   Color.from_hsl(0, 0, 50)     # => "#808080" (gray)
+        #--
+        # SPDX-SnippetEnd
+        #++
+        #
+        # [h] Hue in degrees (0-360). Values wrap automatically.
+        # [s] Saturation as percentage (0-100).
+        # [l] Lightness as percentage (0-100).
+        #
+        # Returns a hex string like <tt>"#rrggbb"</tt>.
+        def from_hsl(h, s, l)
+          RatatuiRuby._color_from_hsl(h.to_f, s.to_f, l.to_f)
+        end
+
+        # Ruby-idiomatic aliases (TIMTOWTDI)
+        alias hex from_u32
+        alias hsl from_hsl
+
+        # Creates a color from HSLuv (Human-friendly Hue, Saturation, Lightness) values.
+        #
+        # HSLuv is a perceptually uniform color space. Unlike standard HSL,
+        # colors at the same lightness appear equally bright regardless of hue.
+        # This makes it ideal for generating color palettes with consistent
+        # perceived brightness.
+        #
+        # This method delegates to Ratatui's palette integration for the
+        # complex HSLuv to RGB conversion.
+        #
+        # Note: Ratatui uses the range [-180, 180] for hue and [0, 100] for
+        # saturation and lightness. This implementation matches those conventions.
+        #
+        # === Example
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   Color.from_hsluv(12.18, 100, 53.2)   # => "#ff0000" (bright red)
+        #   Color.from_hsluv(-94.13, 100, 32.3) # => "#0000ff" (bright blue)
+        #   Color.from_hsluv(0, 0, 50)          # => gray
+        #--
+        # SPDX-SnippetEnd
+        #++
+        #
+        # [h] Hue in degrees (-180 to 360). Values wrap automatically.
+        # [s] Saturation as percentage (0-100). Values are clamped.
+        # [l] Lightness as percentage (0-100). Values are clamped.
+        #
+        # Returns a hex string like <tt>"#rrggbb"</tt>.
+        def from_hsluv(h, s, l)
+          RatatuiRuby._color_from_hsluv(h.to_f, s.to_f, l.to_f)
+        end
+
+        alias hsluv from_hsluv
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/style/style.rb

@@ -60,7 +60,7 @@ module RatatuiRuby
     # ==== String
     # Represents a specific RGB color using a Hex code (<tt>"#RRGGBB"</tt>).
     # Requires a terminal emulator with "True Color" (24-bit color) support.
-    class Style < Data.define(:fg, :bg, :modifiers)
+    class Style < Data.define(:fg, :bg, :underline_color, :modifiers, :remove_modifiers)
       ##
       # :attr_reader: fg
       # Foreground color.
@@ -73,19 +73,36 @@ module RatatuiRuby
       #
       # Symbol (<tt>:black</tt>), Hex String (<tt>"#000000"</tt>), or Integer (0-255).
 
+      ##
+      # :attr_reader: underline_color
+      # Color of the underline.
+      #
+      # Symbol (<tt>:red</tt>), Hex String (<tt>"#ff0000"</tt>), or Integer (0-255).
+      # Distinct from foreground color. Terminals supporting this feature render
+      # the underline in this color while text remains in the foreground color.
+
       ##
       # :attr_reader: modifiers
-      # Text effects.
+      # Text effects to add.
       #
       # Array of symbols: <tt>:bold</tt>, <tt>:dim</tt>, <tt>:italic</tt>, <tt>:underlined</tt>,
       # <tt>:slow_blink</tt>, <tt>:rapid_blink</tt>, <tt>:reversed</tt>, <tt>:hidden</tt>, <tt>:crossed_out</tt>.
 
+      ##
+      # :attr_reader: remove_modifiers
+      # Text effects to remove.
+      #
+      # Array of symbols. When this style is applied, these modifiers are removed
+      # from any inherited/patched styles. Corresponds to Ratatui's sub_modifier.
+
       # Creates a new Style.
       #
       # [fg] Color (Symbol/String/Integer).
       # [bg] Color (Symbol/String/Integer).
-      # [modifiers] Array of Symbols.
-      def initialize(fg: nil, bg: nil, modifiers: [])
+      # [underline_color] Color for underline (Symbol/String/Integer).
+      # [modifiers] Array of Symbols to add.
+      # [remove_modifiers] Array of Symbols to remove (Ratatui: sub_modifier).
+      def initialize(fg: nil, bg: nil, underline_color: nil, modifiers: [], remove_modifiers: [])
         super
       end
 
@@ -95,6 +112,36 @@ module RatatuiRuby
       def self.default
         new
       end
+
+      # Creates a new Style (convenience alias for {#initialize}).
+      #
+      # Constructor keyword arguments require typing out the full <tt>Style.new</tt> form.
+      # This gets verbose in tight layout code or one-liners.
+      #
+      # <tt>Style.with</tt> reads more naturally and enables method chaining.
+      # It shows intent: "use this style with these properties."
+      #
+      # Use it for inline styling where conciseness matters.
+      #
+      # === Examples
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   Style.with(fg: :red, bg: :black, modifiers: [:bold])
+      #   Style.with(fg: :white, modifiers: [:underlined], underline_color: :red)
+      #   Style.with(modifiers: [:bold], remove_modifiers: [:italic])  # Add bold, remove italic
+      #   paragraph = Paragraph.new(text: "Alert!", style: Style.with(fg: :red))
+      #--
+      # SPDX-SnippetEnd
+      #++
+      #
+      # @return [Style]
+      def self.with(fg: nil, bg: nil, underline_color: nil, modifiers: [], remove_modifiers: [])
+        new(fg:, bg:, underline_color:, modifiers:, remove_modifiers:)
+      end
     end
   end
 end

data/lib/ratatui_ruby/style.rb

@@ -10,8 +10,10 @@ module RatatuiRuby
   #
   # This module mirrors +ratatui::style+ and contains:
   # - {Style} — Colors and modifiers
+  # - {Color} — Color constructors
   module Style
   end
 end
 
 require_relative "style/style"
+require_relative "style/color"