color_contrast_calc 0.5.0 → 0.9.0

data/lib/color_contrast_calc/converter.rb

@@ -29,6 +29,58 @@ module ColorContrastCalc
       vals.map {|val| val.round.clamp(0, 255) }
     end
 
+    module AlphaCompositing
+      module Rgba
+        BLACK = [0, 0, 0, 1.0].freeze
+        WHITE = [255, 255, 255, 1.0].freeze
+      end
+
+      ##
+      # Return a pair of RGBA colors created from two other RGBA
+      # colors placed on a base color.
+      #
+      # The calculation is based on the definition found at
+      # https://www.w3.org/TR/compositing-1/#simplealphacompositing
+      # @param foreground [Array<Integer, Float>] RGBA value
+      # @param background [Array<Integer, Float>] RGBA value
+      # @param base [Array<Integer, Float>] RGBA value
+      # @return [Hash] A pair of RGBA values with :foreground and
+      #   :background as its keys
+
+      def self.compose(foreground, background, base = Rgba::WHITE)
+        back = calc(background, base)
+        fore = calc(foreground, back)
+
+        {
+          foreground: normalize(fore),
+          background: normalize(back)
+        }
+      end
+
+      def self.normalize(raw_rgba)
+        rgb = Converter.rgb_map(raw_rgba[0, 3], &:round)
+        rgb.push(raw_rgba.last)
+      end
+
+      private_class_method :normalize
+
+      def self.calc(source, backdrop)
+        return source if source.last == 1
+
+        fore = source.dup
+        af = fore.pop
+        back = backdrop.dup
+        ab = back.pop
+
+        composed = fore.zip(back).map {|f, b| f * af + b * ab * (1 - af) }
+        a_composed = af + ab * (1 - af)
+
+        composed.push a_composed
+      end
+
+      private_class_method :calc
+    end
+
     module Contrast
       ##
       # Return contrast adjusted RGB value of passed color.

data/lib/color_contrast_calc/data/color_keywords.json

@@ -118,6 +118,7 @@
   ["plum", "#dda0dd"],
   ["powderblue", "#b0e0e6"],
   ["purple", "#800080"],
+  ["rebeccapurple", "#663399"],
   ["red", "#ff0000"],
   ["rosybrown", "#bc8f8f"],
   ["royalblue", "#4169e1"],

data/lib/color_contrast_calc/deprecated.rb

@@ -6,7 +6,7 @@ module ColorContrastCalc
 
   module Deprecated
     def self.warn(old_method, new_method)
-      STDERR.puts "##{old_method} is deprecated. Use ##{new_method} instead"
+      Kernel.warn "##{old_method} is deprecated. Use ##{new_method} instead"
     end
 
     module Color

data/lib/color_contrast_calc/invalid_color_representation_error.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ColorContrastCalc
+  ##
+  # Error raised if creating a Color instance with invalid value.
+
+  class InvalidColorRepresentationError < StandardError
+    module Template
+      RGB = 'An RGB value should be in form of [r, g, b], but %s.'
+      RGBA = <<~RGBA_MESSAGE
+        An RGB value should be in form of [r, g, b, opacity]
+        (r, g, b should be in the range between 0 and 255), but %s.
+      RGBA_MESSAGE
+      COLOR_NAME = '%s seems to be an undefined color name.'
+      HEX = 'A hex code #xxxxxx where 0 <= x <= f is expected, but %s.'
+      UNEXPECTED = 'A color should be given as an array or string, but %s.'
+    end
+
+    def self.may_be_name?(value)
+      # all of the color keywords contain an alphabet between g-z.
+      /^#/ !~ value && /[g-z]/i =~ value
+    end
+
+    private_class_method :may_be_name?
+
+    def self.select_message_template(value)
+      case value
+      when Array
+        value.length == 3 ? Template::RGB : Template::RGBA
+      when String
+        may_be_name?(value) ? Template::COLOR_NAME : Template::HEX
+      else
+        Template::UNEXPECTED
+      end
+    end
+
+    private_class_method :select_message_template
+
+    def self.from_value(value)
+      message = format(select_message_template(value), value)
+      new(message)
+    end
+  end
+end

data/lib/color_contrast_calc/sorter.rb

@@ -18,6 +18,7 @@ module ColorContrastCalc
     module ColorComponent
       RGB = 'rgb'.chars
       HSL = 'hsl'.chars
+      HWB = 'hwb'.chars
     end
 
     module CompFunc
@@ -45,6 +46,9 @@ module ColorContrastCalc
       # The function returned by Sorter.compile_compare_function() expects
       # hex color codes as key values when this constants is specified.
       HEX = :hex
+      # The function returned by Sorter.compile_compare_function() expects
+      # color functions as key values when this constants is specified.
+      FUNCTION = :function
       # @private
       CLASS_TO_TYPE = {
         Color => COLOR,
@@ -62,14 +66,157 @@ module ColorContrastCalc
 
       def self.guess(color, key_mapper = nil)
         key = key_mapper ? key_mapper[color] : color
+        return FUNCTION if non_hex_code_string?(key)
         CLASS_TO_TYPE[key.class]
       end
+
+      def self.non_hex_code_string?(color)
+        color.is_a?(String) && !Utils.valid_hex?(color)
+      end
+
+      private_class_method :non_hex_code_string?
+    end
+
+    class CompareFunctionCompiler
+      def initialize(converters = nil)
+        @converters = converters
+      end
+
+      def compile(color_order)
+        order = parse_color_order(color_order)
+        create_proc(order, color_order)
+      end
+
+      # @private
+
+      def parse_color_order(color_order)
+        ordered_components = select_ordered_components(color_order)
+        pos = color_component_pos(color_order, ordered_components)
+        funcs = []
+        pos.each_with_index do |ci, i|
+          c = color_order[i]
+          funcs[ci] = Utils.uppercase?(c) ? CompFunc::DESCEND : CompFunc::ASCEND
+        end
+        { pos: pos, funcs: funcs }
+      end
+
+      def select_ordered_components(color_order)
+        case color_order
+        when /[hsl]{3}/i
+          ColorComponent::HSL
+        when /[hwb]{3}/i
+          ColorComponent::HWB
+        else
+          ColorComponent::RGB
+        end
+      end
+
+      private :select_ordered_components
+
+      # @private
+
+      def color_component_pos(color_order, ordered_components)
+        color_order.downcase.chars.map do |component|
+          ordered_components.index(component)
+        end
+      end
+
+      def create_proc(order, color_order)
+        if @converters
+          conv = select_converter(color_order)
+          proc {|color1, color2| compare(conv[color1], conv[color2], order) }
+        else
+          proc {|color1, color2| compare(color1, color2, order) }
+        end
+      end
+
+      private :create_proc
+
+      # @private
+
+      def compare_components(color1, color2, order)
+        funcs = order[:funcs]
+        order[:pos].each do |i|
+          result = funcs[i][color1[i], color2[i]]
+          return result unless result.zero?
+        end
+
+        0
+      end
+
+      alias compare compare_components
+
+      def select_converter(color_order)
+        scheme = select_scheme(color_order)
+        @converters[scheme]
+      end
+
+      private :select_converter
+
+      def select_scheme(color_order)
+        case color_order
+        when /[hsl]{3}/i
+          :hsl
+        when /[hwb]{3}/i
+          :hwb
+        else
+          :rgb
+        end
+      end
+
+      private :select_scheme
+    end
+
+    class CachingCompiler < CompareFunctionCompiler
+      def create_proc(order, color_order)
+        converter = select_converter(color_order)
+        cache = {}
+
+        proc do |color1, color2|
+          c1 = to_components(color1, converter, cache)
+          c2 = to_components(color2, converter, cache)
+
+          compare(c1, c2, order)
+        end
+      end
+
+      def to_components(color, converter, cache)
+        cached_components = cache[color]
+        return cached_components if cached_components
+
+        components = converter[color]
+        cache[color] = components
+
+        components
+      end
+
+      private :to_components
     end
 
-    # @private shorthands for Utils.hex_to_rgb() and .hex_to_hsl()
-    HEX_TO_COMPONENTS = {
+    hex_to_components = {
+      # shorthands for Utils.hex_to_rgb() and .hex_to_hsl()
       rgb: Utils.method(:hex_to_rgb),
-      hsl: Utils.method(:hex_to_hsl)
+      hsl: Utils.method(:hex_to_hsl),
+      hwb: Utils.method(:hex_to_hwb)
+    }
+
+    function_to_components = {
+      rgb: proc {|func| ColorContrastCalc.color_from(func).rgb },
+      hsl: proc {|func| ColorContrastCalc.color_from(func).hsl },
+      hwb: proc {|func| ColorContrastCalc.color_from(func).hwb }
+    }
+
+    color_to_components = {
+      rgb: proc {|color| color.rgb },
+      hsl: proc {|color| color.hsl },
+      hwb: proc {|color| color.hwb }
+    }
+
+    COMPARE_FUNCTION_COMPILERS = {
+      KeyTypes::COLOR => CompareFunctionCompiler.new(color_to_components),
+      KeyTypes::COMPONENTS => CompareFunctionCompiler.new,
+      KeyTypes::HEX => CachingCompiler.new(hex_to_components),
+      KeyTypes::FUNCTION => CachingCompiler.new(function_to_components)
     }.freeze
 
     ##
@@ -114,14 +261,7 @@ module ColorContrastCalc
                                       key_mapper = nil, &key_mapper_block)
       key_mapper = key_mapper_block if !key_mapper && key_mapper_block
 
-      case key_type
-      when KeyTypes::COLOR
-        compare = compile_color_compare_function(color_order)
-      when KeyTypes::COMPONENTS
-        compare = compile_components_compare_function(color_order)
-      when KeyTypes::HEX
-        compare = compile_hex_compare_function(color_order)
-      end
+      compare = COMPARE_FUNCTION_COMPILERS[key_type].compile(color_order)
 
       compose_function(compare, key_mapper)
     end
@@ -135,101 +275,5 @@ module ColorContrastCalc
         compare_function[key_mapper[color1], key_mapper[color2]]
       end
     end
-
-    # @private
-
-    def self.color_component_pos(color_order, ordered_components)
-      color_order.downcase.chars.map do |component|
-        ordered_components.index(component)
-      end
-    end
-
-    # @private
-
-    def self.parse_color_order(color_order)
-      ordered_components = ColorComponent::RGB
-      ordered_components = ColorComponent::HSL if hsl_order?(color_order)
-      pos = color_component_pos(color_order, ordered_components)
-      funcs = []
-      pos.each_with_index do |ci, i|
-        c = color_order[i]
-        funcs[ci] = Utils.uppercase?(c) ? CompFunc::DESCEND : CompFunc::ASCEND
-      end
-      { pos: pos, funcs: funcs }
-    end
-
-    # @private
-
-    def self.hsl_order?(color_order)
-      /[hsl]{3}/i.match?(color_order)
-    end
-
-    # @private
-
-    def self.compare_color_components(color1, color2, order)
-      funcs = order[:funcs]
-      order[:pos].each do |i|
-        result = funcs[i][color1[i], color2[i]]
-        return result unless result.zero?
-      end
-
-      0
-    end
-
-    # @private
-
-    def self.compile_components_compare_function(color_order)
-      order = parse_color_order(color_order)
-
-      proc do |color1, color2|
-        compare_color_components(color1, color2, order)
-      end
-    end
-
-    # @private
-
-    def self.compile_hex_compare_function(color_order)
-      order = parse_color_order(color_order)
-      converter = HEX_TO_COMPONENTS[:rgb]
-      converter = HEX_TO_COMPONENTS[:hsl] if hsl_order?(color_order)
-      cache = {}
-
-      proc do |hex1, hex2|
-        color1 = hex_to_components(hex1, converter, cache)
-        color2 = hex_to_components(hex2, converter, cache)
-
-        compare_color_components(color1, color2, order)
-      end
-    end
-
-    # @private
-
-    def self.hex_to_components(hex, converter, cache)
-      cached_components = cache[hex]
-      return cached_components if cached_components
-
-      components = converter[hex]
-      cache[hex] = components
-
-      components
-    end
-
-    private_class_method :hex_to_components
-
-    # @private
-
-    def self.compile_color_compare_function(color_order)
-      order = parse_color_order(color_order)
-
-      if hsl_order?(color_order)
-        proc do |color1, color2|
-          compare_color_components(color1.hsl, color2.hsl, order)
-        end
-      else
-        proc do |color1, color2|
-          compare_color_components(color1.rgb, color2.rgb, order)
-        end
-      end
-    end
   end
 end

data/lib/color_contrast_calc/transparency_calc.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'color_contrast_calc/converter'
+require 'color_contrast_calc/checker'
+
+module ColorContrastCalc
+  ##
+  # Provides methods to calculate the contrast ratio between transparent colors.
+  #
+  # Colors are given as RGBA values represented as arrays of Float.
+  # Note that during the process of calculation, each of RGB components
+  # is treated as a Float, though some of them may be rounded up/down in the
+  # final return value.
+
+  module TransparencyCalc
+    include Converter::AlphaCompositing::Rgba
+
+    def self.contrast_ratio(foreground, background, base = WHITE)
+      colors = [foreground, background]
+
+      rgb_colors = if colors.all? {|color| opaque?(color) }
+                     colors.map {|color| to_rgb(color) }
+                   else
+                     to_opaque_rgbs(foreground, background, base)
+                   end
+
+      Checker.contrast_ratio(*rgb_colors)
+    end
+
+    def self.opaque?(rgba)
+      rgba[-1] == Utils::MAX_OPACITY
+    end
+
+    private_class_method :opaque?
+
+    def self.to_rgb(rgba)
+      rgba[0, 3]
+    end
+
+    private_class_method :to_rgb
+
+    def self.compose(foreground, background, base)
+      Converter::AlphaCompositing.compose(foreground, background, base)
+    end
+
+    private_class_method :compose
+
+    def self.to_opaque_rgbs(foreground, background, base)
+      composed = compose(foreground, background, base)
+      %i[foreground background].map {|key| to_rgb(composed[key]) }
+    end
+
+    private_class_method :to_opaque_rgbs
+  end
+end