sai 0.3.0 → 0.3.1

data/sig/sai/conversion/rgb.rbs

@@ -9,50 +9,27 @@ module Sai
     #
     # @api private
     module RGB
-      # Get closest ANSI color for RGB values
+      # Color classification utilities
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
+      # @since 0.3.1
       #
       # @api private
       #
-      # @param red [Float] the red component (0-1)
-      # @param green [Float] the green component (0-1)
-      # @param blue [Float] the blue component (0-1)
-      #
-      # @return [Symbol] the closest ANSI color name
-      # @rbs (Float red, Float green, Float blue) -> Symbol
-      def self.closest_ansi_color: (Float red, Float green, Float blue) -> Symbol
+      # @return [Module<ColorClassifier>] the ColorClassifier module
+      # @rbs () -> singleton(ColorClassifier)
+      def self.classify: () -> singleton(ColorClassifier)
 
-      # Determine if a color is dark
+      # Color indexing utilities
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
+      # @since 0.3.1
       #
       # @api private
       #
-      # @param red [Float] the red component (0-1)
-      # @param green [Float] the green component (0-1)
-      # @param blue [Float] the blue component (0-1)
-      #
-      # @return [Boolean] true if color is dark
-      # @rbs (Float red, Float green, Float blue) -> bool
-      def self.dark?: (Float red, Float green, Float blue) -> bool
-
-      # Determine if a color is grayscale
-      #
-      # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
-      #
-      # @api private
-      #
-      # @param red [Float] the red component (0-1)
-      # @param green [Float] the green component (0-1)
-      # @param blue [Float] the blue component (0-1)
-      #
-      # @return [Boolean] true if color is grayscale
-      # @rbs (Float red, Float green, Float blue) -> bool
-      def self.grayscale?: (Float red, Float green, Float blue) -> bool
+      # @return [Module<ColorIndexer>] the ColorIndexer module
+      # @rbs () -> singleton(ColorIndexer)
+      def self.index: () -> singleton(ColorIndexer)
 
       # Convert a color value to RGB components
       #
@@ -68,176 +45,16 @@ module Sai
       # @rbs (Array[Integer] | String | Symbol color) -> Array[Integer]
       def self.resolve: (Array[Integer] | String | Symbol color) -> Array[Integer]
 
-      # Convert RGB values to 256-color cube index
-      #
-      # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
-      #
-      # @api private
-      #
-      # @param rgb [Array<Integer>] RGB values (0-255)
-      #
-      # @return [Integer] the color cube index
-      # @rbs (Array[Integer] rgb) -> Integer
-      def self.to_color_cube_index: (Array[Integer] rgb) -> Integer
-
-      # Convert RGB values to grayscale index
-      #
-      # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
-      #
-      # @api private
-      #
-      # @param rgb [Array<Integer>] RGB values
-      #
-      # @return [Integer] the grayscale index
-      # @rbs (Array[Integer] rgb) -> Integer
-      def self.to_grayscale_index: (Array[Integer] rgb) -> Integer
-
-      # Check if RGB values represent cyan
-      #
-      # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
-      #
-      # @api private
-      #
-      # @param red [Float] the red component (0-1)
-      # @param green [Float] the green component (0-1)
-      # @param blue [Float] the blue component (0-1)
-      #
-      # @return [Boolean] true if color is cyan
-      # @rbs (Float red, Float green, Float blue) -> bool
-      private def self.cyan?: (Float red, Float green, Float blue) -> bool
-
-      # Convert a hex string to RGB values
-      #
-      # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
-      #
-      # @api private
-      #
-      # @param hex [String] the hex color code
-      #
-      # @return [Array<Integer>] the RGB components
-      # @rbs (String hex) -> Array[Integer]
-      private def self.hex_to_rgb: (String hex) -> Array[Integer]
-
-      # Check if RGB values represent magenta
+      # Transform RGB values
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
+      # @since 0.3.1
       #
       # @api private
       #
-      # @param red [Float] the red component (0-1)
-      # @param green [Float] the green component (0-1)
-      # @param blue [Float] the blue component (0-1)
-      #
-      # @return [Boolean] true if color is magenta
-      # @rbs (Float red, Float green, Float blue) -> bool
-      private def self.magenta?: (Float red, Float green, Float blue) -> bool
-
-      # Convert a named color to RGB values
-      #
-      # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
-      #
-      # @api private
-      #
-      # @param color_name [String] the color name
-      #
-      # @raise [ArgumentError] if the color name is unknown
-      # @return [Array<Integer>] the RGB components
-      # @rbs (String color_name) -> Array[Integer]
-      private def self.named_to_rgb: (String color_name) -> Array[Integer]
-
-      # Determine if RGB values represent a primary color
-      #
-      # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
-      #
-      # @api private
-      #
-      # @param red [Float] the red component (0-1)
-      # @param green [Float] the green component (0-1)
-      # @param blue [Float] the blue component (0-1)
-      #
-      # @return [Boolean] true if color is primary
-      # @rbs (Float red, Float green, Float blue) -> bool
-      private def self.primary?: (Float red, Float green, Float blue) -> bool
-
-      # Get the closest primary color
-      #
-      # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
-      #
-      # @api private
-      #
-      # @param red [Float] the red component (0-1)
-      # @param green [Float] the green component (0-1)
-      # @param blue [Float] the blue component (0-1)
-      #
-      # @return [Symbol] the primary color name
-      # @rbs (Float red, Float green, Float blue) -> Symbol
-      private def self.primary_color: (Float red, Float green, Float blue) -> Symbol
-
-      # Determine if RGB values represent a secondary color
-      #
-      # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
-      #
-      # @api private
-      #
-      # @param red [Float] the red component (0-1)
-      # @param green [Float] the green component (0-1)
-      # @param blue [Float] the blue component (0-1)
-      #
-      # @return [Boolean] true if color is secondary
-      # @rbs (Float red, Float green, Float blue) -> bool
-      private def self.secondary?: (Float red, Float green, Float blue) -> bool
-
-      # Get the closest secondary color
-      #
-      # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
-      #
-      # @api private
-      #
-      # @param red [Float] the red component (0-1)
-      # @param green [Float] the green component (0-1)
-      # @param blue [Float] the blue component (0-1)
-      #
-      # @return [Symbol] the secondary color name
-      # @rbs (Float red, Float green, Float blue) -> Symbol
-      private def self.secondary_color: (Float red, Float green, Float blue) -> Symbol
-
-      # Validate RGB values
-      #
-      # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
-      #
-      # @api private
-      #
-      # @param color [Array<Integer>] the RGB components to validate
-      # @return [Array<Integer>] the validated RGB components
-      # @raise [ArgumentError] if the RGB values are invalid
-      # @rbs (Array[Integer] color) -> Array[Integer]
-      private def self.validate_rgb: (Array[Integer] color) -> Array[Integer]
-
-      # Check if RGB values represent yellow
-      #
-      # @author {https://aaronmallen.me Aaron Allen}
-      # @since 0.1.0
-      #
-      # @api private
-      #
-      # @param red [Float] the red component (0-1)
-      # @param green [Float] the green component (0-1)
-      # @param blue [Float] the blue component (0-1)
-      #
-      # @return [Boolean] true if color is yellow
-      # @rbs (Float red, Float green, Float blue) -> bool
-      private def self.yellow?: (Float red, Float green, Float blue) -> bool
+      # @return [Module<ColorTransformer>] the color transformer
+      # @rbs () -> singleton(ColorTransformer)
+      def self.transform: () -> singleton(ColorTransformer)
     end
   end
 end

data/sig/sai/decorator/color_manipulations.rbs

@@ -0,0 +1,125 @@
+# Generated from lib/sai/decorator/color_manipulations.rb with RBS::Inline
+
+module Sai
+  class Decorator
+    # Color manipulation methods for the {Decorator} class
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.1
+    #
+    # @abstract This module is meant to be included in the {Decorator} class to provide color manipulation methods
+    # @api private
+    module ColorManipulations
+      # Darken the background color by a percentage
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api public
+      #
+      # @example
+      #   decorator.on_blue.darken_text(0.5).decorate('Hello, world!').to_s #=> "\e[48;2;0;0;238mHello, world!\e[0m"
+      #
+      # @param amount [Float] the amount to darken the background color (0.0...1.0)
+      #
+      # @raise [ArgumentError] if the percentage is out of range
+      # @return [Decorator] a new instance of Decorator with the darkened background color
+      # @rbs (Float amount) -> Decorator
+      def darken_background: (Float amount) -> Decorator
+
+      alias darken_bg darken_background
+
+      # Darken the text color by a percentage
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api public
+      #
+      # @example
+      #   decorator.blue.darken_text(0.5).decorate('Hello, world!').to_s #=> "\e[38;2;0;0;119mHello, world!\e[0m"
+      #
+      # @param amount [Float] the amount to darken the text color (0.0...1.0)
+      #
+      # @raise [ArgumentError] if the percentage is out of range
+      # @return [Decorator] a new instance of Decorator with the darkened text color
+      # @rbs (Float amount) -> Decorator
+      def darken_text: (Float amount) -> Decorator
+
+      alias darken_fg darken_text
+
+      alias darken_foreground darken_text
+
+      # Lighten the background color by a percentage
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api public
+      #
+      # @example
+      #   decorator.on_blue.lighten_background(0.5).decorate('Hello, world!').to_s
+      #   #=> "\e[48;2;0;0;255mHello, world!\e[0m"
+      #
+      # @param amount [Float] the amount to lighten the background color (0.0...1.0)
+      #
+      # @raise [ArgumentError] if the percentage is out of range
+      # @return [Decorator] a new instance of Decorator with the lightened background color
+      # @rbs (Float amount) -> Decorator
+      def lighten_background: (Float amount) -> Decorator
+
+      alias lighten_bg lighten_background
+
+      # Lighten the text color by a percentage
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api public
+      #
+      # @example
+      #   decorator.blue.lighten_text(0.5).decorate('Hello, world!').to_s #=> "\e[38;2;0;0;127mHello, world!\e[0m"
+      #
+      # @param amount [Float] the amount to lighten the text color (0.0...1.0)
+      #
+      # @raise [ArgumentError] if the percentage is out of range
+      # @return [Decorator] a new instance of Decorator with the lightened text color
+      # @rbs (Float amount) -> Decorator
+      def lighten_text: (Float amount) -> Decorator
+
+      alias lighten_fg lighten_text
+
+      alias lighten_foreground lighten_text
+
+      private
+
+      # Darken the foreground or background color by a specified amount
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param amount [Float] a value between 0.0 and 1.0 to darken the color by
+      # @param component [Symbol] the color component to darken
+      #
+      # @return [Decorator] a new instance of Decorator with the color darkened
+      # @rbs (Float amount, Symbol component) -> Decorator
+      def darken: (Float amount, Symbol component) -> Decorator
+
+      # Lighten the foreground or background color by a specified amount
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param amount [Float] a value between 0.0 and 1.0 to lighten the color by
+      # @param component [Symbol] the color component to lighten
+      #
+      # @return [Decorator] a new instance of Decorator with the color lightened
+      # @rbs (Float amount, Symbol component) -> Decorator
+      def lighten: (Float amount, Symbol component) -> Decorator
+    end
+  end
+end

data/sig/sai/decorator/delegation.rbs

@@ -0,0 +1,47 @@
+# Generated from lib/sai/decorator/delegation.rb with RBS::Inline
+
+module Sai
+  class Decorator
+    # Delegates all methods from the Decorator class and its component modules
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.1
+    #
+    # @api private
+    module Delegation
+      # The list of component modules to delegate methods from
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @return [Array<Symbol>] the list of component modules
+      COMPONENT_MODULES: Array[Symbol]
+
+      # Install delegated methods on the given class or module
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param klass [Class, Module] the class or module to install the methods on
+      #
+      # @return [void]
+      # @rbs (Class | Module) -> void
+      def self.install: (Class | Module) -> void
+
+      # Collect all methods from the Decorator class and its component modules
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @return [Array<Symbol>] the list of methods to delegate
+      # @rbs () -> Array[Symbol]
+      private def self.collect_delegatable_methods: () -> Array[Symbol]
+    end
+  end
+end

data/sig/sai/decorator/gradients.rbs

@@ -0,0 +1,267 @@
+# Generated from lib/sai/decorator/gradients.rb with RBS::Inline
+
+module Sai
+  class Decorator
+    # Color gradient methods for the {Decorator} class
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.1
+    #
+    # @abstract This module is meant to be included in the {Decorator} class to provide color gradient methods
+    # @api private
+    module Gradients
+      # Build a foreground gradient between two colors for text decoration
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api public
+      #
+      # @example Create a foreground gradient from red to blue
+      #   decorator.gradient(:red, :blue, 10).decorate('Hello, World!')
+      #   #=> "\e[38;2;255;0;0mH\e[0m\e[38;2;204;0;51me\e[0m..."
+      #
+      # @param start_color [Array<Integer>, String, Symbol] the starting color
+      # @param end_color [Array<Integer>, String, Symbol] the ending color
+      # @param steps [Integer] the number of gradient steps (minimum 2)
+      #
+      # @raise [ArgumentError] if steps is less than 2
+      # @return [Decorator] a new instance of Decorator with foreground gradient colors
+      # @rbs (
+      #   Array[Integer] | String | Symbol start_color,
+      #   Array[Integer] | String | Symbol end_color,
+      #   Integer steps
+      #   ) -> Decorator
+      def gradient: (Array[Integer] | String | Symbol start_color, Array[Integer] | String | Symbol end_color, Integer steps) -> Decorator
+
+      # Build a background gradient between two colors for text decoration
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api public
+      #
+      # @example Create a background gradient from red to blue
+      #   decorator.on_gradient(:red, :blue, 10).decorate('Hello, World!')
+      #   #=> "\e[48;2;255;0;0mH\e[0m\e[48;2;204;0;51me\e[0m..."
+      #
+      # @param start_color [Array<Integer>, String, Symbol] the starting color
+      # @param end_color [Array<Integer>, String, Symbol] the ending color
+      # @param steps [Integer] the number of gradient steps (minimum 2)
+      #
+      # @raise [ArgumentError] if steps is less than 2
+      # @return [Decorator] a new instance of Decorator with background gradient colors
+      # @rbs (
+      #   Array[Integer] | String | Symbol start_color,
+      #   Array[Integer] | String | Symbol end_color,
+      #   Integer steps
+      #   ) -> Decorator
+      def on_gradient: (Array[Integer] | String | Symbol start_color, Array[Integer] | String | Symbol end_color, Integer steps) -> Decorator
+
+      # Build a background rainbow gradient for text decoration
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api public
+      #
+      # @example Create a rainbow background gradient
+      #   decorator.on_rainbow(6).decorate('Hello, World!')
+      #   #=> "\e[48;2;255;0;0mH\e[0m\e[48;2;255;255;0me\e[0m..."
+      #
+      # @param steps [Integer] the number of colors to generate (minimum 2)
+      #
+      # @raise [ArgumentError] if steps is less than 2
+      # @return [Decorator] a new instance of Decorator with background rainbow colors
+      # @rbs (Integer steps) -> Decorator
+      def on_rainbow: (Integer steps) -> Decorator
+
+      # Build a foreground rainbow gradient for text decoration
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api public
+      #
+      # @example Create a rainbow text gradient
+      #   decorator.rainbow(6).decorate('Hello, World!')
+      #   #=> "\e[38;2;255;0;0mH\e[0m\e[38;2;255;255;0me\e[0m..."
+      #
+      # @param steps [Integer] the number of colors to generate (minimum 2)
+      #
+      # @raise [ArgumentError] if steps is less than 2
+      # @return [Decorator] a new instance of Decorator with foreground rainbow colors
+      # @rbs (Integer steps) -> Decorator
+      def rainbow: (Integer steps) -> Decorator
+
+      private
+
+      # Adjust number of colors to match text length
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param colors [Array<Array<Integer>>] original color sequence
+      # @param text_length [Integer] desired number of colors
+      #
+      # @return [Array<Array<Integer>>] adjusted color sequence
+      # @rbs (Array[Array[Integer]] colors, Integer text_length) -> Array[Array[Integer]]
+      def adjust_colors_to_text_length: (Array[Array[Integer]] colors, Integer text_length) -> Array[Array[Integer]]
+
+      # Apply color sequence gradients to text
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param text [String] the text to apply the gradient to
+      #
+      # @return [ANSI::SequencedString] the text with gradient applied
+      # @rbs (String text) -> ANSI::SequencedString
+      def apply_sequence_gradient: (String text) -> ANSI::SequencedString
+
+      # Build color sequences for a single character
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param colors [Hash] color sequences for foreground and background
+      # @param index [Integer] character position
+      #
+      # @return [Array<String>] ANSI sequences for the character
+      # @rbs (Hash[Symbol, Array[Array[Integer]]] colors, Integer index) -> Array[String]
+      def build_color_sequences: (Hash[Symbol, Array[Array[Integer]]] colors, Integer index) -> Array[String]
+
+      # Build gradient text from characters and color sequences
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param chars [Array<String>] text characters
+      # @param colors [Hash] color sequences for foreground and background
+      #
+      # @return [Array<String>] colored characters
+      # @rbs (Array[String] chars, Hash[Symbol, Array[Array[Integer]]] colors) -> Array[String]
+      def build_gradient_text: (Array[String] chars, Hash[Symbol, Array[Array[Integer]]] colors) -> Array[String]
+
+      # Calculate indices and progress for color interpolation
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param position [Integer] current position in sequence
+      # @param step_size [Float] size of each step
+      # @param max_index [Integer] maximum index allowed
+      #
+      # @return [Hash] interpolation indices and progress
+      # @rbs (Integer position, Float step_size, Integer max_index) -> Hash[Symbol, Integer | Float]
+      def calculate_interpolation_indices: (Integer position, Float step_size, Integer max_index) -> Hash[Symbol, Integer | Float]
+
+      # Get background sequence for a character
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param colors [Array<Array<Integer>>, nil] background color sequence
+      # @param index [Integer] character position
+      #
+      # @return [String, nil] ANSI sequence for background
+      # @rbs (Array[Array[Integer]]? colors, Integer index) -> String?
+      def get_background_sequence: (Array[Array[Integer]]? colors, Integer index) -> String?
+
+      # Get foreground sequence for a character
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param colors [Array<Array<Integer>>, nil] foreground color sequence
+      # @param index [Integer] character position
+      #
+      # @return [String, nil] ANSI sequence for foreground
+      # @rbs (Array[Array[Integer]]? colors, Integer index) -> String?
+      def get_foreground_sequence: (Array[Array[Integer]]? colors, Integer index) -> String?
+
+      # Interpolate between two colors in a sequence
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param colors [Array<Array<Integer>>] color sequence
+      # @param indices [Hash] interpolation indices and progress
+      #
+      # @return [Array<Integer>] interpolated color
+      # @rbs (Array[Array[Integer]] colors, Hash[Symbol, Integer | Float]) -> Array[Integer]
+      def interpolate_sequence_colors: (Array[Array[Integer]] colors, Hash[Symbol, Integer | Float]) -> Array[Integer]
+
+      # Prepare foreground and background color sequences for text
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param text_length [Integer] length of text to color
+      #
+      # @return [Hash] adjusted color sequences
+      # @rbs (Integer text_length) -> Hash[Symbol, Array[Array[Integer]]]
+      def prepare_color_sequences: (Integer text_length) -> Hash[Symbol, Array[Array[Integer]]]
+
+      # Prepare a single color sequence
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param sequence [Array<Array<Integer>>, nil] color sequence to prepare
+      # @param text_length [Integer] length of text to color
+      #
+      # @return [Array<Array<Integer>>, nil] adjusted color sequence
+      # @rbs (Array[Array[Integer]]? sequence, Integer text_length) -> Array[Array[Integer]]?
+      def prepare_sequence: (Array[Array[Integer]]? sequence, Integer text_length) -> Array[Array[Integer]]?
+
+      # Shrink a color sequence to fit desired length
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param colors [Array<Array<Integer>>] original color sequence
+      # @param target_length [Integer] desired number of colors
+      #
+      # @return [Array<Array<Integer>>] shrunk color sequence
+      # @rbs (Array[Array[Integer]] colors, Integer target_length) -> Array[Array[Integer]]
+      def shrink_colors: (Array[Array[Integer]] colors, Integer target_length) -> Array[Array[Integer]]
+
+      # Stretch a color sequence to fit desired length
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param colors [Array<Array<Integer>>] original color sequence
+      # @param target_length [Integer] desired number of colors
+      #
+      # @return [Array<Array<Integer>>] stretched color sequence
+      # @rbs (Array[Array[Integer]] colors, Integer target_length) -> Array[Array[Integer]]
+      def stretch_colors: (Array[Array[Integer]] colors, Integer target_length) -> Array[Array[Integer]]
+    end
+  end
+end