ratatui_ruby 0.5.0 → 0.7.0

data/lib/ratatui_ruby/layout/layout.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Layout
+    # 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.
+      #
+      #   rects = Layout::Layout.split(
+      #     area,
+      #     direction: :horizontal,
+      #     constraints: [Layout::Constraint.percentage(50), Layout::Constraint.percentage(50)]
+      #   )
+      #   left, right = rects
+      #
+      # [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]
+      #   Flex mode for spacing (default: <tt>:legacy</tt>).
+      #
+      # 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
+end

data/lib/ratatui_ruby/layout/rect.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module Layout
+    # Defines a rectangular area in the terminal grid.
+    #
+    # Geometry management involves passing groups of four integers (`x, y, width, height`) repeatedly.
+    # This is verbose and prone to parameter mismatch errors.
+    #
+    # This class encapsulates the geometry. It provides a standard primitive for passing area definitions
+    # between layout engines and rendering functions.
+    #
+    # Use it when manual positioning is required or when querying layout results.
+    #
+    # === Examples
+    #
+    #   area = Layout::Rect.new(x: 0, y: 0, width: 80, height: 24)
+    #   puts area.width # => 80
+    class Rect < Data.define(:x, :y, :width, :height)
+      ##
+      # :attr_reader: x
+      # X coordinate (column) of the top-left corner (Integer, coerced via +to_int+ or +to_i+).
+
+      ##
+      # :attr_reader: y
+      # Y coordinate (row) of the top-left corner (Integer, coerced via +to_int+ or +to_i+).
+
+      ##
+      # :attr_reader: width
+      # Width in characters (Integer, coerced via +to_int+ or +to_i+).
+
+      ##
+      # :attr_reader: height
+      # Height in characters (Integer, coerced via +to_int+ or +to_i+).
+
+      # Creates a new Rect.
+      #
+      # All parameters accept any object responding to +to_int+ or +to_i+ (duck-typed).
+      #
+      # [x] Column index (Numeric).
+      # [y] Row index (Numeric).
+      # [width] Width in columns (Numeric).
+      # [height] Height in rows (Numeric).
+      def initialize(x: 0, y: 0, width: 0, height: 0)
+        super(
+          x: Integer(x),
+          y: Integer(y),
+          width: Integer(width),
+          height: Integer(height)
+        )
+      end
+
+      # Tests whether a point is inside this rectangle.
+      #
+      # Essential for hit testing mouse clicks against layout regions.
+      #
+      #   area = Layout::Rect.new(x: 10, y: 5, width: 20, height: 10)
+      #   area.contains?(15, 8) # => true
+      #   area.contains?(5, 8)  # => false
+      #
+      # [px]
+      #   X coordinate to test (column).
+      # [py]
+      #   Y coordinate to test (row).
+      #
+      # Returns true if the point (px, py) is within the rectangle bounds.
+      def contains?(px, py)
+        px >= x && px < x + width && py >= y && py < y + height
+      end
+
+      # Tests whether this rectangle overlaps with another.
+      #
+      # Essential for determining if a widget is visible within a viewport or clipping area.
+      #
+      #   viewport = Layout::Rect.new(x: 0, y: 0, width: 80, height: 24)
+      #   widget = Layout::Rect.new(x: 70, y: 20, width: 20, height: 10)
+      #   viewport.intersects?(widget) # => true (partial overlap)
+      #
+      # [other]
+      #   Another Rect to test against.
+      #
+      # Returns true if the rectangles overlap.
+      def intersects?(other)
+        x < other.x + other.width &&
+          x + width > other.x &&
+          y < other.y + other.height &&
+          y + height > other.y
+      end
+
+      # Returns the overlapping area between this rectangle and another.
+      #
+      # Essential for calculating visible portions of widgets inside scroll views.
+      #
+      #   viewport = Layout::Rect.new(x: 0, y: 0, width: 80, height: 24)
+      #   widget = Layout::Rect.new(x: 70, y: 20, width: 20, height: 10)
+      #   visible = viewport.intersection(widget)
+      #   # => Rect(x: 70, y: 20, width: 10, height: 4)
+      #
+      # [other]
+      #   Another Rect to intersect with.
+      #
+      # Returns a new Rect representing the intersection, or +nil+ if no overlap.
+      def intersection(other)
+        return nil unless intersects?(other)
+
+        new_x = [x, other.x].max
+        new_y = [y, other.y].max
+        new_right = [x + width, other.x + other.width].min
+        new_bottom = [y + height, other.y + other.height].min
+
+        Rect.new(x: new_x, y: new_y, width: new_right - new_x, height: new_bottom - new_y)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/layout.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Layout primitives for geometry and space distribution.
+  #
+  # This module mirrors +ratatui::layout+ and contains:
+  # - {Rect} — Rectangle geometry
+  # - {Constraint} — Sizing rules
+  # - {Layout} — Space distribution
+  module Layout
+  end
+end
+
+require_relative "layout/rect"
+require_relative "layout/constraint"
+require_relative "layout/layout"

data/lib/ratatui_ruby/list_state.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Mutable state object for List widgets.
+  #
+  # When using {Frame#render_stateful_widget}, the State object is the
+  # *single source of truth* for selection and scroll offset. Widget
+  # properties (+selected_index+, +offset+) are *ignored* in stateful mode.
+  #
+  # State objects persist across frames, allowing you to:
+  # - Track selection without manual index management
+  # - Read back the scroll offset calculated by Ratatui
+  # - Implement mouse click-to-row hit testing
+  #
+  # == Thread/Ractor Safety
+  #
+  # ListState is *not* Ractor-shareable. It contains mutable internal state.
+  # Store it in instance variables, not in immutable Models.
+  #
+  # == Example
+  #
+  #   @list_state = RatatuiRuby::ListState.new
+  #   @list_state.select(2) # Select third item
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     list = RatatuiRuby::Widgets::List.new(items: ["A", "B", "C", "D", "E"])
+  #     frame.render_stateful_widget(list, frame.area, @list_state)
+  #   end
+  #
+  #   puts @list_state.offset # Scroll position after render
+  #
+  class ListState
+    ##
+    # :method: new
+    # :call-seq: new(selected = nil) -> ListState
+    #
+    # Creates a new ListState with optional initial selection.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select
+    # :call-seq: select(index) -> nil
+    #
+    # Sets the selected index. Pass +nil+ to deselect.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: selected
+    # :call-seq: selected() -> Integer or nil
+    #
+    # Returns the currently selected index, or +nil+ if nothing is selected.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: offset
+    # :call-seq: offset() -> Integer
+    #
+    # Returns the current scroll offset.
+    #
+    # This is the critical read-back method. After +render_stateful_widget+,
+    # this returns the scroll position calculated by Ratatui to keep the
+    # selection visible.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: scroll_down_by
+    # :call-seq: scroll_down_by(n) -> nil
+    #
+    # Scrolls down by +n+ items.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: scroll_up_by
+    # :call-seq: scroll_up_by(n) -> nil
+    #
+    # Scrolls up by +n+ items.
+    #
+    # (Native method implemented in Rust)
+  end
+end

data/lib/ratatui_ruby/schema/bar_chart/bar.rb

@@ -17,7 +17,7 @@ module RatatuiRuby
 
       ##
       # :attr_reader: label
-      # The label of the bar (optional String).
+      # The label of the bar (optional String, Text::Span, or Text::Line for rich styling).
 
       ##
       # :attr_reader: style
@@ -29,7 +29,7 @@ module RatatuiRuby
 
       ##
       # :attr_reader: text_value
-      # The text to display as the value (optional String).
+      # The text to display as the value (optional String, Text::Span, or Text::Line for rich styling).
 
       def initialize(value:, label: nil, style: nil, value_style: nil, text_value: nil)
         super(

data/lib/ratatui_ruby/schema/cursor.rb

@@ -15,6 +15,11 @@ module RatatuiRuby
   # === Examples
   #
   #   Cursor.new(x: 10, y: 5)
+  #
+  # 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

data/lib/ratatui_ruby/schema/gauge.rb

@@ -28,6 +28,8 @@ module RatatuiRuby
     # :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.
 
@@ -52,7 +54,7 @@ module RatatuiRuby
     #
     # [ratio] Float (0.0 - 1.0).
     # [percent] Integer (0 - 100), alternative to ratio.
-    # [label] String (optional).
+    # [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).

data/lib/ratatui_ruby/schema/layout.rb

@@ -32,7 +32,7 @@ module RatatuiRuby
     # :attr_reader: constraints
     # Array of rules defining section sizes.
     #
-    # See RatatuiRuby::Constraint.
+    # See RatatuiRuby::Layout::Constraint.
 
     ##
     # :attr_reader: children

data/lib/ratatui_ruby/schema/line_gauge.rb

@@ -26,7 +26,7 @@ module RatatuiRuby
 
     ##
     # :attr_reader: label
-    # Optional label.
+    # Optional label (String or Text::Span for rich styling).
 
     ##
     # :attr_reader: style
@@ -55,7 +55,7 @@ module RatatuiRuby
     # Creates a new LineGauge.
     #
     # [ratio] Float (0.0 - 1.0).
-    # [label] String (optional).
+    # [label] String or Text::Span (optional).
     # [style] Style (optional, base style for the gauge).
     # [filled_style] Style.
     # [unfilled_style] Style.

data/lib/ratatui_ruby/schema/list.rb

@@ -27,15 +27,34 @@ module RatatuiRuby
   #     highlight_style: Style.new(bg: :blue),
   #     highlight_symbol: ">> "
   #   )
-  class List < Data.define(:items, :selected_index, :style, :highlight_style, :highlight_symbol, :repeat_highlight_symbol, :highlight_spacing, :direction, :scroll_padding, :block)
+  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 (Array of Strings).
+    # 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.
@@ -76,8 +95,9 @@ module RatatuiRuby
     #
     # Integer parameters accept any object responding to +to_int+ or +to_i+ (duck-typed).
     #
-    # [items] Array of Strings.
+    # [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>).
@@ -86,10 +106,11 @@ module RatatuiRuby
     # [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, style: nil, highlight_style: nil, highlight_symbol: "> ", repeat_highlight_symbol: false, highlight_spacing: :when_selected, direction: :top_to_bottom, scroll_padding: nil, block: nil)
+    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:,

data/lib/ratatui_ruby/schema/list_item.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-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
+  #
+  #   # 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]))
+  #   )
+  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

data/lib/ratatui_ruby/schema/rect.rb

@@ -69,5 +69,48 @@ module RatatuiRuby
     def contains?(px, py)
       px >= x && px < x + width && py >= y && py < y + height
     end
+
+    # Tests whether this rectangle overlaps with another.
+    #
+    # Essential for determining if a widget is visible within a viewport or clipping area.
+    #
+    #   viewport = Rect.new(x: 0, y: 0, width: 80, height: 24)
+    #   widget = Rect.new(x: 70, y: 20, width: 20, height: 10)
+    #   viewport.intersects?(widget) # => true (partial overlap)
+    #
+    # [other]
+    #   Another Rect to test against.
+    #
+    # Returns true if the rectangles overlap.
+    def intersects?(other)
+      x < other.x + other.width &&
+        x + width > other.x &&
+        y < other.y + other.height &&
+        y + height > other.y
+    end
+
+    # Returns the overlapping area between this rectangle and another.
+    #
+    # Essential for calculating visible portions of widgets inside scroll views.
+    #
+    #   viewport = Rect.new(x: 0, y: 0, width: 80, height: 24)
+    #   widget = Rect.new(x: 70, y: 20, width: 20, height: 10)
+    #   visible = viewport.intersection(widget)
+    #   # => Rect(x: 70, y: 20, width: 10, height: 4)
+    #
+    # [other]
+    #   Another Rect to intersect with.
+    #
+    # Returns a new Rect representing the intersection, or +nil+ if no overlap.
+    def intersection(other)
+      return nil unless intersects?(other)
+
+      new_x = [x, other.x].max
+      new_y = [y, other.y].max
+      new_right = [x + width, other.x + other.width].min
+      new_bottom = [y + height, other.y + other.height].min
+
+      Rect.new(x: new_x, y: new_y, width: new_right - new_x, height: new_bottom - new_y)
+    end
   end
 end

data/lib/ratatui_ruby/schema/row.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # 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
+  #
+  #   # 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
+  #   )
+  class Row < Data.define(:cells, :style, :height, :top_margin, :bottom_margin)
+    ##
+    # :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
+  end
+end

data/lib/ratatui_ruby/schema/style.rb

@@ -20,18 +20,38 @@ module RatatuiRuby
   #
   #   # Hex colors
   #   Style.new(fg: "#ff00ff")
+  #
+  # === Supported Colors
+  #
+  # ==== Integer
+  # Represents an indexed color from the Xterm 256-color palette (0-255).
+  # * <tt>0</tt>–<tt>15</tt>: Standard and bright ANSI colors.
+  # * <tt>16</tt>–<tt>231</tt>: {6x6x6 Color Cube}[https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit].
+  # * <tt>232</tt>–<tt>255</tt>: Grayscale ramp.
+  #
+  # ==== Symbol
+  # Represents a named color from the standard ANSI palette. Supported values:
+  # * <tt>:black</tt>, <tt>:red</tt>, <tt>:green</tt>, <tt>:yellow</tt>,
+  #   <tt>:blue</tt>, <tt>:magenta</tt>, <tt>:cyan</tt>, <tt>:gray</tt>
+  # * <tt>:dark_gray</tt>, <tt>:light_red</tt>, <tt>:light_green</tt>,
+  #   <tt>:light_yellow</tt>, <tt>:light_blue</tt>, <tt>:light_magenta</tt>,
+  #   <tt>:light_cyan</tt>, <tt>:white</tt>
+  #
+  # ==== 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)
     ##
     # :attr_reader: fg
     # Foreground color.
     #
-    # Symbol (<tt>:red</tt>) or Hex String (<tt>"#ffffff"</tt>).
+    # Symbol (<tt>:red</tt>), Hex String (<tt>"#ffffff"</tt>), or Integer (0-255).
 
     ##
     # :attr_reader: bg
     # Background color.
     #
-    # Symbol (<tt>:black</tt>) or Hex String (<tt>"#000000"</tt>).
+    # Symbol (<tt>:black</tt>), Hex String (<tt>"#000000"</tt>), or Integer (0-255).
 
     ##
     # :attr_reader: modifiers
@@ -42,8 +62,8 @@ module RatatuiRuby
 
     # Creates a new Style.
     #
-    # [fg] Color (Symbol/String).
-    # [bg] Color (Symbol/String).
+    # [fg] Color (Symbol/String/Integer).
+    # [bg] Color (Symbol/String/Integer).
     # [modifiers] Array of Symbols.
     def initialize(fg: nil, bg: nil, modifiers: [])
       super