tincture-apca 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '03519433f7f021e7c641da9814503f7175233ebab635f70599c419616ac18d15'
+  data.tar.gz: 58cb22824f9af6a9d99970e0213b8a761b8597fbcf65aa16b60d51a40ce61ca1
+SHA512:
+  metadata.gz: 3014dc7a59b1deb07bc0686482cb4f2a077df8a73f9db6888f7e5abb140e0c9d391b35459e429ed70d232e91dd6445d9f38582a470f66450e221effb10e78c4e
+  data.tar.gz: 05b97f7f2f23d18296b530945be9fb9c5cfea664b5e3fc36dfc3340c96761572cc64a84bc116a8cd31546d6444180909f0b94db7b536a883d1bcb3a28c703d41

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0 (2026-10-21)
+
+- `apca_contrast` and `contrast_color(method: :apca)` for `Tincture::Color`, ported from apca-w3 0.1.9.

data/LICENSE.md

@@ -0,0 +1,12 @@
+# Licence
+
+This gem is a port of [apca-w3](https://github.com/Myndex/apca-w3) 0.1.9 (base algorithm 0.0.98G-4g) and is distributed under the apca-w3 licence, not MIT: https://github.com/Myndex/apca-w3/blob/master/LICENSE.md
+
+APCA is copyright © 2019-2023 Andrew Somers and Myndex Research, patent pending.
+
+In short, and the licence itself governs:
+
+- Use is allowed only for web content, in support of the WCAG accessibility guidelines. Other uses, such as print or PDF, fall under AGPL v3.
+- A commercial product that uses it must give Myndex free access to audit the code on request.
+- The algorithm and constants must not change, except to port them, and must be kept current.
+- The name "APCA" may describe only a correct, current implementation.

data/README.md

@@ -0,0 +1,53 @@
+# Tincture APCA
+
+[![CI](https://github.com/andycroll/tincture-apca/actions/workflows/ci.yml/badge.svg)](https://github.com/andycroll/tincture-apca/actions/workflows/ci.yml)
+
+APCA contrast for Tincture colours
+
+> [!WARNING]
+> APCA is © Andrew Somers and Myndex Research, patent pending. Its [licence](LICENSE.md) allows use only for web content, in support of the WCAG accessibility guidelines. Other uses, such as print or PDF, fall under AGPL v3. A commercial product that uses it must give Myndex free access to audit the code on request.
+
+## Installation
+
+Add these lines to your Gemfile:
+
+```ruby
+gem "tincture"
+gem "tincture-apca", require: false
+```
+
+Then require it where web content is built, not globally:
+
+```ruby
+require "tincture/apca"
+```
+
+## Usage
+
+Measure APCA lightness contrast (Lc) for text on a background
+
+```ruby
+Tincture::Color.parse("#888").apca_contrast("#fff") # 63.06
+Tincture::Color.parse("#fff").apca_contrast("#888") # -68.54
+```
+
+Positive is dark text on light, negative is light on dark. For body text, Lc 75 is the minimum and Lc 90 preferred.
+
+Pick black or white text by APCA
+
+```ruby
+background.contrast_color(method: :apca)
+background.contrast_color(among: ["#1f2937", "white"], method: :apca)
+```
+
+This is a port of [apca-w3](https://github.com/Myndex/apca-w3) 0.1.9 (algorithm 0.0.98G-4g), checked against its test values.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake        # tests and RuboCop
+bundle exec rake rdoc   # API docs in doc/
+```
+
+To release, set the version in `lib/tincture/apca/version.rb`, date the changelog entry, commit, and push a `vX.Y.Z` tag. GitHub Actions runs the checks and publishes the gem to rubygems.org through trusted publishing.

data/lib/tincture/apca/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tincture
+  module Apca
+    VERSION = '1.0.0' # :nodoc:
+  end
+end

data/lib/tincture/apca.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'tincture'
+require_relative 'apca/version'
+
+module Tincture # :nodoc:
+  # [APCA](https://git.apcacontrast.com/) lightness contrast (Lc), the
+  # perceptual contrast method drafted for WCAG 3. Requiring
+  # `tincture/apca` adds ColorMethods#apca_contrast to Tincture::Color and
+  # `method: :apca` to Tincture::Color#contrast_color.
+  #
+  # A port of [apca-w3](https://github.com/Myndex/apca-w3) 0.1.9: base
+  # algorithm 0.0.98G-4g with its approved constants.
+  #
+  # **Licence restriction.** APCA is copyright © 2019–2023 Andrew Somers and
+  # Myndex Research, patent pending. Its licence allows use only for web
+  # content, in support of the WCAG accessibility guidelines. Other uses,
+  # such as print or PDF, fall under AGPL v3. A commercial product that uses
+  # it must give Myndex free access to audit the code on request. The
+  # algorithm and constants must not change, except to port them, and must
+  # be kept current. See the
+  # [licence](https://github.com/Myndex/apca-w3/blob/master/LICENSE.md).
+  module Apca
+    # Names match apca-w3's SA98G, so each value can be checked against it.
+    SA98G = {
+      mainTRC: 2.4,
+      sRco: 0.2126729,
+      sGco: 0.7151522,
+      sBco: 0.0721750,
+      normBG: 0.56,
+      normTXT: 0.57,
+      revTXT: 0.62,
+      revBG: 0.65,
+      blkThrs: 0.022,
+      blkClmp: 1.414,
+      scaleBoW: 1.14,
+      scaleWoB: 1.14,
+      loBoWoffset: 0.027,
+      loWoBoffset: 0.027,
+      deltaYmin: 0.0005,
+      loClip: 0.1
+    }.freeze
+
+    module_function
+
+    # Lc for text on a background, from their #luminance values. Positive for
+    # dark text on light, negative for light text on dark, up to about ±108.
+    # For body text, Lc 75 is the minimum and Lc 90 preferred.
+    #
+    #: (Float text_y, Float background_y) -> Float
+    def contrast(text_y, background_y)
+      text_y, background_y = [text_y, background_y].map { soft_clamped(it) }
+
+      lc =
+        if (background_y - text_y).abs < SA98G[:deltaYmin] then 0.0
+        elsif background_y > text_y then dark_on_light(text_y, background_y)
+        else light_on_dark(text_y, background_y)
+        end
+
+      lc * 100
+    end
+
+    # APCA's screen luminance (Y) for 0–255 sRGB channels. Not the same as
+    # WCAG 2 relative luminance.
+    #
+    #: ([Integer, Integer, Integer] rgb) -> Float
+    def luminance((red, green, blue))
+      (SA98G[:sRco] * linear(red)) + (SA98G[:sGco] * linear(green)) + (SA98G[:sBco] * linear(blue))
+    end
+
+    def linear(channel) = (channel / 255.0)**SA98G[:mainTRC] # :nodoc:
+
+    def soft_clamped(luminance) # :nodoc:
+      luminance > SA98G[:blkThrs] ? luminance : luminance + ((SA98G[:blkThrs] - luminance)**SA98G[:blkClmp])
+    end
+
+    def dark_on_light(text_y, background_y) # :nodoc:
+      sapc = ((background_y**SA98G[:normBG]) - (text_y**SA98G[:normTXT])) * SA98G[:scaleBoW]
+      sapc < SA98G[:loClip] ? 0.0 : sapc - SA98G[:loBoWoffset]
+    end
+
+    def light_on_dark(text_y, background_y) # :nodoc:
+      sapc = ((background_y**SA98G[:revBG]) - (text_y**SA98G[:revTXT])) * SA98G[:scaleWoB]
+      sapc > -SA98G[:loClip] ? 0.0 : sapc + SA98G[:loWoBoffset]
+    end
+
+    private_class_method :linear, :soft_clamped, :dark_on_light, :light_on_dark
+
+    # Added to Tincture::Color.
+    module ColorMethods
+      # APCA lightness contrast (Lc) of this colour as text on `background`.
+      # Positive for dark text on light, negative for light on dark.
+      # Translucent text is blended onto the background first.
+      #
+      # **Licence restriction:** web content only, in support of WCAG. See
+      # Apca.
+      #
+      #     Tincture::Color.parse("#888").apca_contrast("#fff") # => 63.06…
+      #
+      #: (String | Color background) -> Float
+      def apca_contrast(background)
+        background = Color.parse(background)
+        text = opaque? ? self : blended_over(background)
+
+        Apca.contrast(Apca.luminance(text.rgb), Apca.luminance(background.rgb))
+      end
+
+      private
+
+      def blended_over(background)
+        Color.rgb(*rgb.zip(background.rgb).map { |mine, theirs| (theirs * (1 - alpha)) + (mine * alpha) })
+      end
+    end
+  end
+
+  Color.include(Apca::ColorMethods)
+  Color.contrast_scorers[:apca] = ->(text, background) { text.apca_contrast(background).abs }
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: tincture-apca
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Andy Croll
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tincture
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Adds APCA lightness contrast (Lc) to Tincture::Color, ported from apca-w3.
+  Its licence restricts use to web content in support of WCAG.
+email:
+- andy@goodscary.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- lib/tincture/apca.rb
+- lib/tincture/apca/version.rb
+homepage: https://github.com/andycroll/tincture-apca
+licenses:
+- LicenseRef-apca-w3
+metadata:
+  source_code_uri: https://github.com/andycroll/tincture-apca
+  changelog_uri: https://github.com/andycroll/tincture-apca/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: APCA contrast for Tincture colours, for WCAG web content only
+test_files: []