ratatui_ruby 0.4.0 → 0.6.0

data/lib/ratatui_ruby/schema/sparkline.rb

@@ -4,128 +4,129 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Displays high-density data in a compact row.
-    #
-    # Users need context. A single value ("90% CPU") tells you current status, but not the trend.
-    # Full charts take up too much room.
-    #
-    # This widget solves the density problem. It condenses history into a single line of variable-height blocks.
-    #
-    # Use it in dashboards, headers, or list items to providing trending data at a glance.
-    #
-    # === Examples
-    #
-    #   Sparkline.new(
-    #     data: [1, 4, 3, 8, 2, 9, 3, 2],
-    #     style: Style.new(fg: :yellow)
-    #   )
-    class Sparkline < Data.define(:data, :max, :style, :block, :direction, :absent_value_symbol, :absent_value_style, :bar_set)
-      ##
-      # :attr_reader: data
-      # Array of integer values to plot.
+  # Displays high-density data in a compact row.
+  #
+  # Users need context. A single value ("90% CPU") tells you current status, but not the trend.
+  # Full charts take up too much room.
+  #
+  # This widget solves the density problem. It condenses history into a single line of variable-height blocks.
+  #
+  # Use it in dashboards, headers, or list items to providing trending data at a glance.
+  #
+  # {rdoc-image:/doc/images/widget_sparkline_demo.png}[link:/examples/widget_sparkline_demo/app_rb.html]
+  #
+  # === Example
+  #
+  # Run the interactive demo from the terminal:
+  #
+  #   ruby examples/widget_sparkline_demo/app.rb
+  class Sparkline < Data.define(:data, :max, :style, :block, :direction, :absent_value_symbol, :absent_value_style, :bar_set)
+    ##
+    # :attr_reader: data
+    # Array of integer values to plot.
 
-      ##
-      # :attr_reader: max
-      # Maximum value for scaling (optional).
-      #
-      # If nil, derived from data max.
+    ##
+    # :attr_reader: max
+    # Maximum value for scaling (optional).
+    #
+    # If nil, derived from data max.
 
-      ##
-      # :attr_reader: style
-      # Style for the bars.
+    ##
+    # :attr_reader: style
+    # Style for the bars.
 
-      ##
-      # :attr_reader: block
-      # Optional wrapping block.
+    ##
+    # :attr_reader: block
+    # Optional wrapping block.
 
-      ##
-      # :attr_reader: direction
-      # Direction to render data.
-      #
-      # Accepts +:left_to_right+ (default) or +:right_to_left+.
-      # Use +:right_to_left+ when new data should appear on the left.
+    ##
+    # :attr_reader: direction
+    # Direction to render data.
+    #
+    # Accepts +:left_to_right+ (default) or +:right_to_left+.
+    # Use +:right_to_left+ when new data should appear on the left.
 
-      ##
-      # :attr_reader: absent_value_symbol
-      # Character to render for absent (nil) values (optional).
-      #
-      # If nil, absent values are rendered with a space.
+    ##
+    # :attr_reader: absent_value_symbol
+    # Character to render for absent (nil) values (optional).
+    #
+    # If nil, absent values are rendered with a space.
 
-      ##
-      # :attr_reader: absent_value_style
-      # Style for absent (nil) values (optional).
+    ##
+    # :attr_reader: absent_value_style
+    # Style for absent (nil) values (optional).
 
-      ##
-      # :attr_reader: bar_set
-      # Custom characters for the bars (optional).
-      #
-      # A Hash with keys defining the characters for the bars.
-      # Keys: <tt>:empty</tt>, <tt>:one_eighth</tt>, <tt>:one_quarter</tt>, <tt>:three_eighths</tt>, <tt>:half</tt>, <tt>:five_eighths</tt>, <tt>:three_quarters</tt>, <tt>:seven_eighths</tt>, <tt>:full</tt>.
-      #
-      # You can also use integers (0-8) as keys, where 0 is empty, 4 is half, and 8 is full.
-      #
-      # Alternatively, you can pass an Array of 9 strings, where index 0 is empty and index 8 is full.
-      #
-      # === Examples
-      #
-      #   bar_set: {
-      #     empty: " ",
-      #     one_eighth: " ",
-      #     one_quarter: "▂",
-      #     three_eighths: "▃",
-      #     half: "▄",
-      #     five_eighths: "▅",
-      #     three_quarters: "▆",
-      #     seven_eighths: "▇",
-      #     full: "█"
-      #   }
-      #
-      #   # Numeric keys (0-8)
-      #   bar_set: {
-      #     0 => " ", 1 => " ", 2 => "▂", 3 => "▃", 4 => "▄", 5 => "▅", 6 => "▆", 7 => "▇", 8 => "█"
-      #   }
-      #
-      #   # Array (9 items)
-      #   bar_set: [" ", " ", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
+    ##
+    # :attr_reader: bar_set
+    # Custom characters for the bars (optional).
+    #
+    # A Hash with keys defining the characters for the bars.
+    # Keys: <tt>:empty</tt>, <tt>:one_eighth</tt>, <tt>:one_quarter</tt>, <tt>:three_eighths</tt>, <tt>:half</tt>, <tt>:five_eighths</tt>, <tt>:three_quarters</tt>, <tt>:seven_eighths</tt>, <tt>:full</tt>.
+    #
+    # You can also use integers (0-8) as keys, where 0 is empty, 4 is half, and 8 is full.
+    #
+    # Alternatively, you can pass an Array of 9 strings, where index 0 is empty and index 8 is full.
+    #
+    # === Examples
+    #
+    #   bar_set: {
+    #     empty: " ",
+    #     one_eighth: " ",
+    #     one_quarter: "▂",
+    #     three_eighths: "▃",
+    #     half: "▄",
+    #     five_eighths: "▅",
+    #     three_quarters: "▆",
+    #     seven_eighths: "▇",
+    #     full: "█"
+    #   }
+    #
+    #   # Numeric keys (0-8)
+    #   bar_set: {
+    #     0 => " ", 1 => " ", 2 => "▂", 3 => "▃", 4 => "▄", 5 => "▅", 6 => "▆", 7 => "▇", 8 => "█"
+    #   }
+    #
+    #   # Array (9 items)
+    #   bar_set: [" ", " ", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
 
-      BAR_KEYS = %i[empty one_eighth one_quarter three_eighths half five_eighths three_quarters seven_eighths full].freeze
+    BAR_KEYS = %i[empty one_eighth one_quarter three_eighths half five_eighths three_quarters seven_eighths full].freeze
 
-      # Creates a new Sparkline widget.
-      #
-      # [data] Array of Integers or nil. nil marks an absent value (distinct from 0).
-      # [max] Max value (optional).
-      # [style] Style (optional).
-      # [block] Block (optional).
-      # [direction] +:left_to_right+ or +:right_to_left+ (default: +:left_to_right+).
-      # [absent_value_symbol] Character for absent (nil) values (optional).
-      # [absent_value_style] Style for absent (nil) values (optional).
-      # [bar_set] Hash or Array of custom characters (optional).
-      def initialize(data:, max: nil, style: nil, block: nil, direction: :left_to_right, absent_value_symbol: nil, absent_value_style: nil, bar_set: nil)
-        if bar_set
-          if bar_set.is_a?(Array) && bar_set.size == 9
-            # Convert Array to Hash using BAR_KEYS order
-            bar_set = BAR_KEYS.zip(bar_set).to_h
-          else
-            bar_set = bar_set.dup
-            # Normalize numeric keys (0-8) to symbolic keys
-            BAR_KEYS.each_with_index do |key, i|
-              if val = bar_set.delete(i) || bar_set.delete(i.to_s)
-                bar_set[key] = val
-              end
+    # Creates a new Sparkline widget.
+    #
+    # [data] Array of Integers or nil. nil marks an absent value (distinct from 0).
+    # [max] Max value (optional).
+    # [style] Style (optional).
+    # [block] Block (optional).
+    # [direction] +:left_to_right+ or +:right_to_left+ (default: +:left_to_right+).
+    # [absent_value_symbol] Character for absent (nil) values (optional).
+    # [absent_value_style] Style for absent (nil) values (optional).
+    # [bar_set] Hash or Array of custom characters (optional).
+    def initialize(data:, max: nil, style: nil, block: nil, direction: :left_to_right, absent_value_symbol: nil, absent_value_style: nil, bar_set: nil)
+      if bar_set
+        if bar_set.is_a?(Array) && bar_set.size == 9
+          # Convert Array to Hash using BAR_KEYS order
+          bar_set = BAR_KEYS.zip(bar_set).to_h
+        else
+          bar_set = bar_set.dup
+          # Normalize numeric keys (0-8) to symbolic keys
+          BAR_KEYS.each_with_index do |key, i|
+            if (val = bar_set.delete(i) || bar_set.delete(i.to_s))
+              bar_set[key] = val
             end
           end
         end
-        coerced_data = data.map { |v| v.nil? ? nil : Integer(v) }
-        super(
-          data: coerced_data,
-          max: max.nil? ? nil : Integer(max),
-          style: style,
-          block: block,
-          direction: direction,
-          absent_value_symbol: absent_value_symbol,
-          absent_value_style: absent_value_style,
-          bar_set: bar_set
-        )
       end
+      coerced_data = data.map { |v| v.nil? ? nil : Integer(v) }
+      super(
+        data: coerced_data,
+        max: max.nil? ? nil : Integer(max),
+        style:,
+        block:,
+        direction:,
+        absent_value_symbol:,
+        absent_value_style:,
+        bar_set:
+      )
     end
+  end
 end

data/lib/ratatui_ruby/schema/style.rb

@@ -4,56 +4,76 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Defines colors and text modifiers.
+  # Defines colors and text modifiers.
+  #
+  # 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")
+  #
+  # === 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.
     #
-    # 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>).
+    # 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>).
+    ##
+    # :attr_reader: bg
+    # Background color.
+    #
+    # Symbol (<tt>:black</tt>), Hex String (<tt>"#000000"</tt>), or Integer (0-255).
 
-      ##
-      # :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>.
+    ##
+    # :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] Color (Symbol/String).
-      # [bg] Color (Symbol/String).
-      # [modifiers] Array of Symbols.
-      def initialize(fg: nil, bg: nil, modifiers: [])
-        super
-      end
+    # 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: [])
+      super
+    end
 
-      # Returns an empty style.
-      #
-      # Use this as a baseline to prevent style inheritance issues or when no styling is required.
-      def self.default
-        new
-      end
+    # Returns an empty style.
+    #
+    # Use this as a baseline to prevent style inheritance issues or when no styling is required.
+    def self.default
+      new
     end
+  end
 end

data/lib/ratatui_ruby/schema/table.rb

@@ -4,125 +4,136 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
-    # Displays structured data in rows and columns.
+  # Displays structured data in rows and columns.
+  #
+  # 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, :offset, :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 (<tt>:always</tt>, <tt>:when_selected</tt>, <tt>:never</tt>).
+
+    ##
+    # :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: offset
+    # Scroll offset (Integer or nil).
     #
-    # 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.
+    # Controls the viewport's starting row position in the table.
     #
-    # This widget creates a grid. It enforces column widths using constraints. It renders headers, rows, and footers aligned perfectly.
+    # When +nil+ (default), Ratatui auto-scrolls to keep the selection visible ("natural scrolling").
     #
-    # Use it to display database records, logs, or file lists.
+    # When set, forces the viewport to start at this row index. Use this for:
+    # - **Passive scrolling**: Scroll through a log table without selecting rows.
+    # - **Click-to-select math**: Calculate which row index corresponds to a click coordinate.
     #
-    # === Examples
+    # *Important*: When both +offset+ and +selected_row+ are set, Ratatui may still adjust
+    # the viewport during rendering to ensure the selection stays visible. Set +selected_row+
+    # to +nil+ for fully manual scroll control.
+
+    ##
+    # :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.
     #
-    #   Table.new(
-    #     header: ["ID", "Name", "Status"],
-    #     rows: [
-    #       ["1", "Hideo", "Active"],
-    #       ["2", "Kojima", "Idle"]
-    #     ],
-    #     widths: [
-    #       Constraint.length(5),
-    #       Constraint.fill(1),
-    #       Constraint.length(10)
-    #     ]
-    #   )
-    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] 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: header,
-          rows: rows,
-          widths: widths,
-          highlight_style: highlight_style,
-          highlight_symbol: highlight_symbol,
-          highlight_spacing: highlight_spacing,
-          column_highlight_style: column_highlight_style,
-          cell_highlight_style: cell_highlight_style,
-          selected_row: selected_row.nil? ? nil : Integer(selected_row),
-          selected_column: selected_column.nil? ? nil : Integer(selected_column),
-          block: block,
-          footer: footer,
-          flex: flex,
-          style: style,
-          column_spacing: Integer(column_spacing)
-        )
-      end
+    # [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).
+    # [offset] Numeric (nullable, coerced to Integer). Forces scroll position when set.
+    # [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, offset: 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),
+        offset: offset.nil? ? nil : Integer(offset),
+        block:,
+        footer:,
+        flex:,
+        style:,
+        column_spacing: Integer(column_spacing)
+      )
     end
+  end
 end