sai 0.3.0 → 0.3.1

data/lib/sai/conversion/rgb.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require 'sai/ansi'
+require 'sai/conversion/rgb/color_classifier'
+require 'sai/conversion/rgb/color_indexer'
+require 'sai/conversion/rgb/color_space'
+require 'sai/conversion/rgb/color_transformer'
 
 module Sai
   module Conversion
@@ -12,60 +16,30 @@ module Sai
     # @api private
     module RGB
       class << self
-        # 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 closest_ansi_color(red, green, blue)
-          return :black if dark?(red, green, blue)
-          return :white if grayscale?(red, green, blue)
-          return primary_color(red, green, blue) if primary?(red, green, blue)
-          return secondary_color(red, green, blue) if secondary?(red, green, blue)
-
-          :white
+        # @return [Module<ColorClassifier>] the ColorClassifier module
+        # @rbs () -> singleton(ColorClassifier)
+        def classify
+          ColorClassifier
         end
 
-        # 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 dark?(red, green, blue)
-          [red, green, blue].max < 0.3
-        end
-
-        # 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 grayscale?(red, green, blue)
-          red == green && green == blue
+        # @return [Module<ColorIndexer>] the ColorIndexer module
+        # @rbs () -> singleton(ColorIndexer)
+        def index
+          ColorIndexer
         end
 
         # Convert a color value to RGB components
@@ -81,240 +55,20 @@ module Sai
         # @return [Array<Integer>] the RGB components
         # @rbs (Array[Integer] | String | Symbol color) -> Array[Integer]
         def resolve(color)
-          case color
-          when Array then validate_rgb(color)
-          when /^#?([A-Fa-f0-9]{6})$/
-            hex_to_rgb(
-              Regexp.last_match(1) #: String
-            )
-          when String, Symbol then named_to_rgb(color.to_s.downcase)
-          else
-            raise ArgumentError, "Invalid color format: #{color}"
-          end
-        end
-
-        # 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 to_color_cube_index(rgb)
-          r, g, b = rgb.map { |c| ((c / 255.0) * 5).round } #: [Integer, Integer, Integer]
-          16 + (r * 36) + (g * 6) + b
-        end
-
-        # 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 to_grayscale_index(rgb)
-          232 + ((rgb[0] / 255.0) * 23).round
-        end
-
-        private
-
-        # 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
-        def cyan?(red, green, blue)
-          green > red && blue > red
-        end
-
-        # 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]
-        def hex_to_rgb(hex)
-          hex = hex.delete_prefix('#') #: String
-          [
-            hex[0..1].to_i(16), # steep:ignore UnexpectedPositionalArgument
-            hex[2..3].to_i(16), # steep:ignore UnexpectedPositionalArgument
-            hex[4..5].to_i(16) # steep:ignore UnexpectedPositionalArgument
-          ]
-        end
-
-        # Check if RGB values represent magenta
-        #
-        # @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 magenta
-        # @rbs (Float red, Float green, Float blue) -> bool
-        def magenta?(red, green, blue)
-          red > green && blue > green
-        end
-
-        # 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]
-        def named_to_rgb(color_name)
-          ANSI::COLOR_NAMES.fetch(color_name.to_sym) do
-            raise ArgumentError, "Unknown color name: #{color_name}"
-          end
-        end
-
-        # 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
-        def primary?(red, green, blue)
-          max = [red, green, blue].max
-          mid = [red, green, blue].sort[1]
-          (max - mid) > 0.3
-        end
-
-        # 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
-        def primary_color(red, green, blue)
-          max = [red, green, blue].max
-          case max
-          when red then :red
-          when green then :green
-          else :blue
-          end
-        end
-
-        # 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
-        def secondary?(red, green, blue)
-          return true if yellow?(red, green, blue)
-          return true if magenta?(red, green, blue)
-          return true if cyan?(red, green, blue)
-
-          false
-        end
-
-        # 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
-        def secondary_color(red, green, blue)
-          return :yellow if yellow?(red, green, blue)
-          return :magenta if magenta?(red, green, blue)
-          return :cyan if cyan?(red, green, blue)
-
-          :white
+          ColorSpace.resolve(color)
         end
 
-        # Validate RGB values
+        # Transform RGB values
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since 0.1.0
+        # @since 0.3.1
         #
         # @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]
-        def validate_rgb(color)
-          unless color.size == 3 && color.all? { |c| c.is_a?(Integer) && c.between?(0, 255) }
-            raise ArgumentError, "Invalid RGB values: #{color}"
-          end
-
-          color
-        end
-
-        # 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
-        def yellow?(red, green, blue)
-          red > blue && green > blue && (red - green).abs < 0.3
+        # @return [Module<ColorTransformer>] the color transformer
+        # @rbs () -> singleton(ColorTransformer)
+        def transform
+          ColorTransformer
         end
       end
     end

data/lib/sai/decorator/color_manipulations.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+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(amount)
+        raise ArgumentError, "Invalid percentage: #{amount}" unless amount >= 0.0 && amount <= 1.0
+
+        darken(amount, :background)
+      end
+      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(amount)
+        raise ArgumentError, "Invalid percentage: #{amount}" unless amount >= 0.0 && amount <= 1.0
+
+        darken(amount, :foreground)
+      end
+      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(amount)
+        raise ArgumentError, "Invalid percentage: #{amount}" unless amount >= 0.0 && amount <= 1.0
+
+        lighten(amount, :background)
+      end
+      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(amount)
+        raise ArgumentError, "Invalid percentage: #{amount}" unless amount >= 0.0 && amount <= 1.0
+
+        lighten(amount, :foreground)
+      end
+      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(amount, component)
+        color = instance_variable_get(:"@#{component}")
+
+        # @type self: Decorator
+
+        dup.tap do |duped|
+          if color
+            rgb = Conversion::RGB.transform.darken(color, amount)
+            duped.instance_variable_set(:"@#{component}", rgb)
+          end
+        end
+      end
+
+      # 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(amount, component)
+        color = instance_variable_get(:"@#{component}")
+
+        # @type self: Decorator
+
+        dup.tap do |duped|
+          if color
+            rgb = Conversion::RGB.transform.lighten(color, amount)
+            duped.instance_variable_set(:"@#{component}", rgb)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sai/decorator/delegation.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'sai/decorator'
+require 'sai/decorator/color_manipulations'
+require 'sai/decorator/gradients'
+require 'sai/decorator/hex_colors'
+require 'sai/decorator/named_colors'
+require 'sai/decorator/named_styles'
+require 'sai/decorator/rgb_colors'
+
+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 = %i[
+        ColorManipulations
+        Gradients
+        HexColors
+        NamedColors
+        NamedStyles
+        RGBColors
+      ].freeze #: Array[Symbol]
+      private_constant :COMPONENT_MODULES
+
+      class << self
+        # 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 install(klass)
+          ignored_methods = %i[apply call decorate encode]
+          methods = collect_delegatable_methods.reject { |m| ignored_methods.include?(m) }
+
+          methods.each do |method|
+            klass.define_method(method) do |*args, **kwargs|
+              Decorator.new(mode: Sai.mode.auto).public_send(method, *args, **kwargs)
+            end
+          end
+        end
+
+        private
+
+        # 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]
+        def collect_delegatable_methods
+          methods = Decorator.instance_methods(false)
+
+          COMPONENT_MODULES.each do |mod|
+            methods.concat(Decorator.const_get(mod).instance_methods(false))
+          end
+
+          methods.uniq
+        end
+      end
+    end
+  end
+end