color-contrast-js 2.0.0

package/API.md

@@ -0,0 +1,183 @@
+# colorContrast.js API
+
+All functions are named exports from `color-contrast-js`. TypeScript declarations are included in the package.
+
+```js
+import { contrastRatio, meetsContrast } from "color-contrast-js";
+```
+
+## Common options
+
+Functions that resolve transparency accept an optional opaque fallback color:
+
+```ts
+type ColorOptions = {
+  fallback?: string; // default: "#fff"
+};
+```
+
+## `backgroundTone(color, options?)`
+
+Classifies the supplied background as `"light"` or `"dark"`. The result describes the background, not the recommended text color.
+
+```js
+backgroundTone("#111"); // "dark"
+backgroundTone("tomato"); // "light"
+```
+
+## `analyzeColor(color, options?)`
+
+Returns the resolved color, WCAG relative luminance, black and white contrast ratios, the background tone, recommended text color, and AA/AAA compliance.
+
+```js
+const result = analyzeColor("#FF5733");
+
+result.backgroundTone; // "light"
+result.recommendedTextColor; // "#000000"
+result.contrastWithBlack; // approximately 6.66
+result.blackText.aa; // true
+```
+
+The returned object has this shape:
+
+```ts
+type ColorAnalysis = {
+  color: string;
+  resolvedColor: string;
+  luminance: number;
+  recommendedTextColor: "#000000" | "#FFFFFF";
+  backgroundTone: "light" | "dark";
+  contrastWithBlack: number;
+  contrastWithWhite: number;
+  blackText: ContrastCompliance;
+  whiteText: ContrastCompliance;
+};
+
+type ContrastCompliance = {
+  aa: boolean;
+  aaLarge: boolean;
+  aaa: boolean;
+  aaaLarge: boolean;
+};
+```
+
+## `contrastRatio(foreground, background, options?)`
+
+Returns a WCAG contrast ratio from 1 to 21. Translucent foregrounds are composited over the background before calculation.
+
+```js
+contrastRatio("#000", "#fff"); // 21
+```
+
+## `bestTextColor(background, candidates?, options?)`
+
+Returns the candidate with the strongest contrast against the background. Candidates default to black and white.
+
+```js
+bestTextColor("#336699"); // "#FFFFFF"
+bestTextColor("#336699", ["#fff", "#000", "#ff0"]); // "#fff"
+```
+
+## `meetsContrast(foreground, background, options?)`
+
+Checks a foreground/background pair against WCAG AA or AAA thresholds.
+
+```js
+meetsContrast("#000", "#FF5733", {
+  level: "AA", // "AA" or "AAA"
+  textSize: "normal", // "normal" or "large"
+}); // true
+```
+
+## `compositeColors(foreground, background)`
+
+Composites a translucent foreground over a background and returns CSS RGB or RGBA.
+
+```js
+compositeColors("rgb(0 0 0 / 50%)", "#fff");
+// "rgb(128, 128, 128)"
+```
+
+## `parseColor(color)`
+
+Parses a supported CSS color and returns numeric sRGB channels from 0–255 plus alpha from 0–1. Returns `null` for unsupported input.
+
+```js
+parseColor("tomato");
+// { r: 255, g: 99, b: 71, a: 1 }
+```
+
+Supported inputs include HEX, RGB, HSL, named colors, Lab, LCH, Oklab, OKLCH, and CSS `color()` spaces. Wide-gamut inputs are converted to sRGB and clipped to the sRGB gamut.
+
+## `analyzePalette(colors, options?)`
+
+Returns `analyzeColor()` results for every palette entry.
+
+```js
+analyzePalette(["#000", "#fff", "tomato"]);
+```
+
+## `contrastMatrix(colors, options?)`
+
+Returns a pairwise matrix where rows are foreground colors and columns are background colors.
+
+```js
+contrastMatrix(["#000", "#fff"]);
+// [[1, 21], [21, 1]]
+```
+
+## `getBackgroundColor(element, options?)`
+
+Resolves an element's visible `background-color`, compositing translucent ancestor background colors until it reaches an opaque color or the fallback.
+
+```js
+getBackgroundColor(document.querySelector(".card"));
+```
+
+This helper handles solid and translucent CSS background colors. It does not analyze background images, gradients, blend modes, canvas content, or video.
+
+## `analyzeElement(element, options?)`
+
+Analyzes an element's computed foreground, resolved background, font size and weight. It selects the applicable WCAG normal/large text thresholds automatically.
+
+```js
+const result = analyzeElement(document.querySelector(".card"));
+
+result.foregroundColor;
+result.backgroundColor;
+result.contrastRatio;
+result.textSize; // "normal" or "large"
+result.aa;
+result.aaa;
+```
+
+## `applyBackgroundTone(target, options?)`
+
+Applies a class describing the background tone to one element, a selector, or an iterable of elements. Every element is evaluated independently.
+
+```js
+applyBackgroundTone(".card");
+
+applyBackgroundTone(".card", {
+  lightClass: "on-light",
+  darkClass: "on-dark",
+  fallback: "#fff",
+  root: document,
+});
+```
+
+The function returns the affected elements.
+
+## Historical aliases
+
+The original project names remain available as aliases:
+
+- `colorBrightness` and `colourBrightness` → `backgroundTone`
+- `applyColorBrightness` and `applyColourBrightness` → `applyBackgroundTone`
+- `analyseColour` → `analyzeColor`
+- `parseColour` → `parseColor`
+- `bestTextColour` → `bestTextColor`
+- `compositeColours` → `compositeColors`
+- `getBackgroundColour` → `getBackgroundColor`
+- `analyseElement` → `analyzeElement`
+- `analysePalette` → `analyzePalette`

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 2.0.0 — 2026-07-13
+
+- Rebuilt the project as colorContrast.js, a browser-ready ES module with compatibility aliases for the original plugin names.
+- Added readable and minified module builds plus a complete API reference.
+- Relicensed the project under the MIT License.
+- Added `backgroundTone` and `applyBackgroundTone` as clearer canonical names for the original brightness helpers.
+- Added `analyzeColor`, `contrastRatio`, `bestTextColor`, `meetsContrast`, `compositeColors`, palette analysis, and contrast matrices.
+- Added `analyzeElement` for computed foreground/background contrast and font-aware WCAG checks.
+- Added HEX, RGB, HSL, named-color, Lab, LCH, Oklab, OKLCH, and CSS `color()` parsing.
+- Switched the recommended contrast calculation to WCAG relative luminance.
+- Added DOM helpers for individual elements, selectors and element collections.
+- Added alpha compositing through translucent ancestor backgrounds, building on the proposal in [#9](https://github.com/jamiebrittain/colorContrast.js/pull/9) by [@ioliva](https://github.com/ioliva).
+- Added TypeScript declarations, automated tests, npm package metadata, and third-party notices.
+- Added strict runtime validation for parsed channel objects and consistent option errors.
+- Centralized WCAG thresholds and corrected the 14pt bold large-text boundary.
+- Added guarded npm packaging, readable/minified build parity checks, and continuous integration.
+- Added [hex.madebynifty.com](https://hex.madebynifty.com/) as the live v2 example.
+
+## 1.3.0 — 2026-07-13
+
+This release is intended to be tagged from a dedicated legacy-only commit before the v2 release. It is a GitHub compatibility release for existing jQuery users, not part of the `color-contrast-js` npm package.
+
+- Fixed every element in a jQuery collection receiving the first element's result ([#7](https://github.com/jamiebrittain/colorContrast.js/issues/7)).
+- Improved zero-alpha and transparent background detection.
+- Included the HTML element when looking for an inherited background.
+- Added a white fallback for a completely transparent document.
+- Preserved the v1 brightness algorithm and class behavior.
+- Left elements unchanged when their computed background color cannot be parsed.
+- Documented that partially transparent backgrounds remain a v1 limitation; use v2 for compositing-aware analysis.
+- Added regression tests and reproducible minification.
+
+## 1.2.0 — 2015-12-29
+
+- Added a terminating semicolon for compatibility with concatenated scripts.
+- Updated the project metadata and version header.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2013-2026 Jamie Brittain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,13 @@
+# Third-party notices
+
+The bundled CSS colour conversions use Culori.
+
+MIT License
+
+Copyright (c) 2018 Dan Burzo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.