immosquare-colors 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 731aff145269af33588fd72b5abef8720b45cb260de44d9083a4f8c1417b86de
-  data.tar.gz: 35a426a289463a8c93d326c548217107e9e1932dc068be64d50d35bc8135e548
+  metadata.gz: 298cb3ad3c069e4f68cd9de80e71708a7cc96c4dec84809c7f23f4181ad80d1d
+  data.tar.gz: 40f23aae65b3b72611898ca2b52a1605781bf345e45bd62b6587c3cb17a8d09f
 SHA512:
-  metadata.gz: 71b29cc00937ae63c5b228c65e0e1461ee3f784c545b6f2b326b792f897584ba2e54d04076949fdcc457ac6e8bec388deefa2532c13f5febba1302f45e23ea15
-  data.tar.gz: 2d25bf197fbf33ef50b67f5ebddf84e7c6a5a2fa036478fd7b26d7db52d1b7843dd6d2e6847c1fcc3e045f39481a3a9538804ed580fbab0ced0258a833c9efe3
+  metadata.gz: 0d7207b2ff2ef514539cb159e4b05ea5830f38d4aed38bce7bf5f77ebdf5a04efcf1d04c745266b05fcf6904dcfb1843e92651f8d32d6d9863bc8d4967a07c08
+  data.tar.gz: e9f0713467cc5cc73ad32c32dd50f896be52cc07bfc836ea066768759e271adcf109143d8e7cddc5d6286e2eece9f5fe1bf454117e4e773ae86f119a2bb075d0

data/lib/immosquare-colors/version.rb

@@ -1,3 +1,3 @@
 module ImmosquareColors
-  VERSION = "0.1.5".freeze
+  VERSION = "0.1.6".freeze
 end

data/lib/immosquare-colors.rb

@@ -5,26 +5,33 @@ module ImmosquareColors
 
     ##============================================================##
     ## To determine whether the complementary color should be
-    ## black or white
+    ## black or white.
+    ##
+    ## The answer is the overlay that actually reads best, decided by
+    ## WCAG contrast ratio. A perceived-brightness cutoff does not
+    ## agree with that ratio around mid luminance: olives, mauves and
+    ## muted greens sit just under a 127.5 cutoff and are handed white,
+    ## while black reads better on them. `#6c8539` for instance scores
+    ## 4.16:1 against white and 5.05:1 against black.
+    ##
+    ## Passing `:luminance` keeps the former behaviour, for callers
+    ## that tuned their own brightness cutoff.
     ##============================================================##
     def get_complementary_color(color, options = {})
       begin
-        luminance_std = (options[:luminance] || 127.5).to_f
-        black         = "#000000"
-        white         = "#FFFFFF"
-        color_hex     = color.start_with?("#") ? color : color_name_to_hex(color)
+        black     = "#000000"
+        white     = "#FFFFFF"
+        color_hex = color.start_with?("#") ? color : color_name_to_hex(color)
 
         raise("Not valid size") if ![7, 9].include?(color_hex.length)
 
+        if options[:luminance]
+          r, g, b = hex_to_rgba(color_hex)
+          brightness = Math.sqrt((0.299 * (r**2)) + (0.587 * (g**2)) + (0.114 * (b**2)))
+          return brightness > options[:luminance].to_f ? black : white
+        end
 
-        color_rgba = hex_to_rgba(color_hex)
-        r, g, b, a = color_rgba
-
-        ##============================================================##
-        ## luminance calculation
-        ##============================================================##
-        luminance = Math.sqrt((0.299 * (r**2)) + (0.587 * (g**2)) + (0.114 * (b**2)))
-        luminance > luminance_std ? black : white
+        contrast_ratio(color_hex, white) >= contrast_ratio(color_hex, black) ? white : black
       rescue StandardError => e
         puts("=== Error! ===")
         puts(e.message)
@@ -33,6 +40,28 @@ module ImmosquareColors
       end
     end
 
+    ##============================================================##
+    ## WCAG 2.1 contrast ratio between two colors, from 1 (identical)
+    ## to 21 (black on white). Body text wants 4.5, large text and
+    ## graphical objects 3.
+    ##============================================================##
+    def contrast_ratio(color_one, color_two)
+      lighter, darker = [relative_luminance(color_one), relative_luminance(color_two)].minmax.reverse
+      (lighter + 0.05) / (darker + 0.05)
+    end
+
+    ##============================================================##
+    ## WCAG 2.1 relative luminance, between 0 (black) and 1 (white).
+    ## Channels are linearised before being weighted, which is what
+    ## separates it from a plain brightness average.
+    ##============================================================##
+    def relative_luminance(color)
+      color_hex = color.start_with?("#") ? color : color_name_to_hex(color)
+      channels  = hex_to_rgba(color_hex).first(3).map {|channel| channel / 255.0 }
+      linear    = channels.map {|channel| channel <= 0.03928 ? channel / 12.92 : (((channel + 0.055) / 1.055)**2.4) }
+      (0.2126 * linear[0]) + (0.7152 * linear[1]) + (0.0722 * linear[2])
+    end
+
     ##============================================================##
     ## To transform a hex color to rgba
     ##============================================================##
@@ -88,5 +117,94 @@ module ImmosquareColors
       rgba_to_hex([shaded_r, shaded_g, shaded_b, a])
     end
 
+    ##============================================================##
+    ## Mix two colors in sRGB, `weight` being the share of the second
+    ## one. Generalises tint (mix with white) and shade (mix with
+    ## black), and mirrors what CSS `color-mix(in srgb, ...)` computes,
+    ## so a value derived here matches what a browser would render.
+    ## Alpha is carried over from the first color.
+    ##============================================================##
+    def mix_colors(color_one, color_two, weight)
+      one_hex        = color_one.start_with?("#") ? color_one : color_name_to_hex(color_one)
+      two_hex        = color_two.start_with?("#") ? color_two : color_name_to_hex(color_two)
+      r1, g1, b1, a1 = hex_to_rgba(one_hex)
+      r2, g2, b2     = hex_to_rgba(two_hex)
+      mixed          = [[r1, r2], [g1, g2], [b1, b2]].map {|from, to| (((1 - weight) * from) + (weight * to)).round }
+      rgba_to_hex(mixed + [a1].compact)
+    end
+
+    ##============================================================##
+    ## The color sitting opposite on the color wheel: same saturation
+    ## and lightness, hue rotated by 180°. Useful to derive a secondary
+    ## color that cannot be mistaken for a tint of the primary one.
+    ##============================================================##
+    def get_opposite_color(color)
+      h, s, l = hex_to_hsl(color)
+      hsl_to_hex([h + 180, s, l])
+    end
+
+    ##============================================================##
+    ## Whether two colors are far enough apart to be read together.
+    ## `:level` accepts :aa (4.5, body text), :aa_large (3, large text
+    ## and graphical objects such as icons or logos) and :aaa (7).
+    ##============================================================##
+    def accessible_contrast?(color_one, color_two, options = {})
+      thresholds = {:aa => 4.5, :aa_large => 3.0, :aaa => 7.0}
+      threshold  = thresholds[(options[:level] || :aa).to_sym] || thresholds[:aa]
+      contrast_ratio(color_one, color_two) >= threshold
+    end
+
+    ##============================================================##
+    ## To transform a hex color to HSL, hue in degrees (0...360),
+    ## saturation and lightness between 0 and 1.
+    ##============================================================##
+    def hex_to_hsl(color)
+      color_hex   = color.start_with?("#") ? color : color_name_to_hex(color)
+      r, g, b     = hex_to_rgba(color_hex).first(3).map {|channel| channel / 255.0 }
+      high, low   = [r, g, b].minmax.reverse
+      lightness   = (high + low) / 2.0
+      return [0.0, 0.0, lightness.round(4)] if high == low
+
+      delta      = high - low
+      saturation = lightness > 0.5 ? delta / (2.0 - high - low) : delta / (high + low)
+      hue        = case high
+                   when r then ((g - b) / delta) + (g < b ? 6.0 : 0.0)
+                   when g then ((b - r) / delta) + 2.0
+                   else        ((r - g) / delta) + 4.0
+                   end
+      [(hue * 60.0).round(2), saturation.round(4), lightness.round(4)]
+    end
+
+    ##============================================================##
+    ## To transform an HSL array back to hex. The hue wraps around, so
+    ## a rotation past 360° needs no clamping by the caller.
+    ##============================================================##
+    def hsl_to_hex(hsl)
+      hue, saturation, lightness = hsl
+      hue = (hue % 360) / 360.0
+      return rgba_to_hex([(lightness * 255).round] * 3) if saturation == 0
+
+      second = lightness < 0.5 ? lightness * (1 + saturation) : lightness + saturation - (lightness * saturation)
+      first  = (2 * lightness) - second
+      rgba_to_hex([1.0 / 3, 0, -1.0 / 3].map {|offset| (hue_to_channel(first, second, hue + offset) * 255).round })
+    end
+
+
+    private
+
+    ##============================================================##
+    ## One channel of an HSL → RGB conversion, from the two
+    ## intermediate values and the hue shifted for that channel.
+    ##============================================================##
+    def hue_to_channel(first, second, hue)
+      hue += 1 if hue < 0
+      hue -= 1 if hue > 1
+      return first + ((second - first) * 6 * hue)       if hue < 1.0 / 6
+      return second                                     if hue < 1.0 / 2
+      return first + ((second - first) * ((2.0 / 3) - hue) * 6) if hue < 2.0 / 3
+
+      first
+    end
+
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: immosquare-colors
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
-- IMMO SQUARE
-autorequire:
+- immosquare
 bindir: bin
 cert_chain: []
-date: 2023-10-09 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: immosquare-constants
@@ -30,8 +29,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.3
-description: Provides methods to suggest complementary colors based on luminance,
-  convert HEX to RGBA, and map named colors to HEX
+description: Provides methods to derive a black/white complementary color from luminance,
+  tint or shade a color, convert HEX <-> RGBA, and resolve named colors to HEX.
 email:
 - jules@immosquare.com
 executables: []
@@ -40,11 +39,10 @@ extra_rdoc_files: []
 files:
 - lib/immosquare-colors.rb
 - lib/immosquare-colors/version.rb
-homepage: https://github.com/IMMOSQUARE/immosquare-colors
+homepage: https://github.com/immosquare/immosquare-colors
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -52,15 +50,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.2
+      version: 3.2.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.13
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Ruby utility for complementary color derivation and color conversions.
+summary: Ruby utility for complementary color derivation, tinting, shading and color
+  conversions.
 test_files: []