ratatui_ruby 0.3.1 → 0.5.0

data/lib/ratatui_ruby/schema/style.rb

@@ -4,26 +4,54 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A value object that defines colors and modifiers for text or widgets.
+  # Defines colors and text modifiers.
   #
-  # [fg] The foreground color (e.g., +:red+, +"#ff0000"+).
-  # [bg] The background color (e.g., +:black+, +"#000000"+).
-  # [modifiers] An array of symbols representing text modifiers:
-  #             [+:bold+, +:italic+, +:dim+, +:reversed+, +:underlined+, +:slow_blink+, +:rapid_blink+, +:crossed_out+, +:hidden+]
+  # The terminal is traditionally monochrome, but efficient interfaces use color to convey meaning.
+  # Red for errors. Green for success. Bold for headers.
+  #
+  # This value object encapsulates those choices. It applies foreground and background colors. It adds effects like italics or blinking.
+  #
+  # Use it to theme your application or highlight critical data.
+  #
+  # === Examples
+  #
+  #   # Standard colors
+  #   Style.new(fg: :red, bg: :white, modifiers: [:bold])
+  #
+  #   # Hex colors
+  #   Style.new(fg: "#ff00ff")
   class Style < Data.define(:fg, :bg, :modifiers)
+    ##
+    # :attr_reader: fg
+    # Foreground color.
+    #
+    # Symbol (<tt>:red</tt>) or Hex String (<tt>"#ffffff"</tt>).
+
+    ##
+    # :attr_reader: bg
+    # Background color.
+    #
+    # Symbol (<tt>:black</tt>) or Hex String (<tt>"#000000"</tt>).
+
+    ##
+    # :attr_reader: modifiers
+    # Text effects.
+    #
+    # 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>.
+
     # Creates a new Style.
     #
-    # [fg] The foreground color (e.g., "red", "#ff0000").
-    # [bg] The background color (e.g., "black", "#000000").
-    # [modifiers] An array of symbols representing text modifiers.
+    # [fg] Color (Symbol/String).
+    # [bg] Color (Symbol/String).
+    # [modifiers] Array of Symbols.
     def initialize(fg: nil, bg: nil, modifiers: [])
       super
     end
 
-    # Returns a default style with no colors or modifiers.
+    # Returns an empty style.
     #
-    #   Style.default
-    #   # => #<RatatuiRuby::Style fg=nil, bg=nil, modifiers=[]>
+    # Use this as a baseline to prevent style inheritance issues or when no styling is required.
     def self.default
       new
     end

data/lib/ratatui_ruby/schema/table.rb

@@ -4,27 +4,118 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A widget that displays data in a grid with rows and columns.
+  # Displays structured data in rows and columns.
   #
-  # [header] An array of strings or Paragraphs representing the header row.
-  # [rows] An array of arrays of strings or Paragraphs representing the data rows.
-  # [widths] An array of Constraint objects defining column widths.
-  # [highlight_style] The style for the selected row.
-  # [highlight_symbol] The symbol to display in front of the selected row.
-  # [selected_row] The index of the currently selected row, or nil if none.
-  # [block] An optional Block widget to wrap the table.
-  class Table < Data.define(:header, :rows, :widths, :highlight_style, :highlight_symbol, :selected_row, :block)
+  # Data is often multidimensional. You need to show relationships between fields (Name, Age, ID).
+  # Aligning columns manually in a monospaced environment is painful and error-prone.
+  #
+  # This widget creates a grid. It enforces column widths using constraints. It renders headers, rows, and footers aligned perfectly.
+  #
+  # Use it to display database records, logs, or file lists.
+  #
+  # {rdoc-image:/doc/images/widget_table_flex.png}[link:/examples/widget_table_flex/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_table_flex/app.rb
+  class Table < Data.define(:header, :rows, :widths, :highlight_style, :highlight_symbol, :highlight_spacing, :column_highlight_style, :cell_highlight_style, :selected_row, :selected_column, :block, :footer, :flex, :style, :column_spacing)
+    ##
+    # :attr_reader: header
+    # Header row content (Array of Strings).
+
+    ##
+    # :attr_reader: rows
+    # Data rows (Array of Arrays of Strings).
+
+    ##
+    # :attr_reader: widths
+    # Column width constraints (Array of Constraint).
+
+    ##
+    # :attr_reader: highlight_style
+    # Style for the selected row.
+
+    ##
+    # :attr_reader: highlight_symbol
+    # Symbol for the selected row.
+
+    ##
+    # :attr_reader: highlight_spacing
+    # When to show the highlight symbol column (:always, :when_selected, :never).
+
+    ##
+    # :attr_reader: column_highlight_style
+    # Style for the selected column.
+
+    ##
+    # :attr_reader: cell_highlight_style
+    # Style for the selected cell (intersection of row and column).
+
+    ##
+    # :attr_reader: selected_row
+    # Index of the selected row (Integer or nil).
+
+    ##
+    # :attr_reader: selected_column
+    # Index of the selected column (Integer or nil).
+
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
+
+    ##
+    # :attr_reader: footer
+    # Footer row content (Array of Strings).
+
+    ##
+    # :attr_reader: flex
+    # Flex mode for column distribution.
+
+    ##
+    # :attr_reader: style
+    # Base style for the entire table.
+
+    ##
+    # :attr_reader: column_spacing
+    # Spacing between columns (Integer, default 1).
+
     # Creates a new Table.
     #
-    # [header] An array of strings or Paragraphs representing the header row.
-    # [rows] An array of arrays of strings or Paragraphs representing the data rows.
-    # [widths] An array of Constraint objects defining column widths.
-    # [highlight_style] The style for the selected row.
-    # [highlight_symbol] The symbol to display in front of the selected row.
-    # [selected_row] The index of the currently selected row, or nil if none.
-    # [block] An optional Block widget to wrap the table.
-    def initialize(header: nil, rows: [], widths: [], highlight_style: nil, highlight_symbol: "> ", selected_row: nil, block: nil)
-      super
+    # [header] Array of strings/paragraphs.
+    # [rows] 2D Array of strings/paragraphs.
+    # [widths] Array of Constraints.
+    # [highlight_style] Style object.
+    # [highlight_symbol] String.
+    # [highlight_spacing] Symbol (optional, default: <tt>:when_selected</tt>).
+    # [column_highlight_style] Style object.
+    # [cell_highlight_style] Style object.
+    # [selected_row] Integer (nullable).
+    # [selected_column] Integer (nullable).
+    # [block] Block (optional).
+    # [footer] Array of strings/paragraphs (optional).
+    # [flex] Symbol (optional, default: <tt>:legacy</tt>).
+    # [style] Style object or Hash (optional).
+    # [column_spacing] Integer (optional, default: 1).
+    def initialize(header: nil, rows: [], widths: [], highlight_style: nil, highlight_symbol: "> ", highlight_spacing: :when_selected, column_highlight_style: nil, cell_highlight_style: nil, selected_row: nil, selected_column: nil, block: nil, footer: nil, flex: :legacy, style: nil, column_spacing: 1)
+      super(
+        header:,
+        rows:,
+        widths:,
+        highlight_style:,
+        highlight_symbol:,
+        highlight_spacing:,
+        column_highlight_style:,
+        cell_highlight_style:,
+        selected_row: selected_row.nil? ? nil : Integer(selected_row),
+        selected_column: selected_column.nil? ? nil : Integer(selected_column),
+        block:,
+        footer:,
+        flex:,
+        style:,
+        column_spacing: Integer(column_spacing)
+      )
     end
   end
 end

data/lib/ratatui_ruby/schema/tabs.rb

@@ -4,19 +4,80 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-  # A widget that displays a set of tabs, one of which is selected.
+  # Displays a tab bar for navigation.
   #
-  # [titles] Array of strings or lines to display as tab titles.
-  # [selected_index] The index of the currently selected tab.
-  # [block] Optional block widget to wrap the tabs.
-  class Tabs < Data.define(:titles, :selected_index, :block)
+  # Screen real estate is limited. You cannot show everything at once. Segregating content into views is necessary for complex apps.
+  #
+  # This widget separates dimensions. It displays a row of titles, indicating which view is active.
+  #
+  # Use it at the top of your interface to switch between major modes or contexts.
+  #
+  # {rdoc-image:/doc/images/widget_tabs_demo.png}[link:/examples/widget_tabs_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_tabs_demo/app.rb
+  class Tabs < Data.define(:titles, :selected_index, :block, :divider, :highlight_style, :style, :padding_left, :padding_right)
+    ##
+    # :attr_reader: titles
+    # Tab titles (Array of Strings).
+
+    ##
+    # :attr_reader: selected_index
+    # Index of the active tab.
+
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
+
+    ##
+    # :attr_reader: divider
+    # Separator string between tabs.
+
+    ##
+    # :attr_reader: highlight_style
+    # Style for the selected tab title.
+
+    ##
+    # :attr_reader: style
+    # Base style for the tabs area.
+
+    ##
+    # :attr_reader: padding_left
+    # Left padding for the tabs area (Integer, default: 0).
+
+    ##
+    # :attr_reader: padding_right
+    # Right padding for the tabs area (Integer, default: 0).
+
     # Creates a new Tabs widget.
     #
-    # [titles] Array of strings or lines to display as tab titles.
-    # [selected_index] The index of the currently selected tab.
-    # [block] Optional block widget to wrap the tabs.
-    def initialize(titles: [], selected_index: 0, block: nil)
-      super
+    # [titles] Array of Strings/Lines.
+    # [selected_index] Integer (default: 0).
+    # [block] Block (optional).
+    # [divider] String (optional).
+    # [highlight_style] Style (optional).
+    # [style] Style (optional).
+    # [padding_left] Integer (default: 0).
+    # [padding_right] Integer (default: 0).
+    def initialize(titles: [], selected_index: 0, block: nil, divider: nil, highlight_style: nil, style: nil, padding_left: 0, padding_right: 0)
+      super(
+        titles:,
+        selected_index: Integer(selected_index),
+        block:,
+        divider:,
+        highlight_style:,
+        style:,
+        padding_left: Integer(padding_left),
+        padding_right: Integer(padding_right)
+      )
+    end
+
+    # Returns the total width of the tabs.
+    def width
+      RatatuiRuby._tabs_width(self)
     end
   end
 end

data/lib/ratatui_ruby/schema/text.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Namespace for rich text components (Span and Line).
+  # Distinct from canvas shapes and other Line usages.
+  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.
+      #
+      #   Text::Span.styled("Bold", Style.new(modifiers: [:bold]))
+      def self.styled(content, style = nil)
+        new(content:, style:)
+      end
+    end
+
+    # 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
+    #
+    #   Text::Line.new(
+    #     spans: [
+    #       Text::Span.styled("User: ", Style.new(modifiers: [:bold])),
+    #       Text::Span.styled("kerrick", Style.new(fg: :blue))
+    #     ]
+    #   )
+    class Line < Data.define(:spans, :alignment)
+      ##
+      # :attr_reader: spans
+      # Array of Span objects.
+
+      ##
+      # :attr_reader: alignment
+      # Alignment within the container.
+      #
+      # <tt>:left</tt>, <tt>:center</tt>, or <tt>:right</tt>.
+
+      # Creates a new Line.
+      #
+      # [spans] Array of Span objects (or Strings).
+      # [alignment] Symbol (optional).
+      def initialize(spans: [], alignment: 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
+    end
+  end
+end