@luntta/swatch 3.0.0

package/src/operations/apca.js

@@ -0,0 +1,80 @@
+// APCA — Accessible Perceptual Contrast Algorithm (Andrew Somers).
+//
+// Returns the Lightness Contrast (Lc) on a ~[-108, +106] scale:
+//   • Positive Lc — dark text on light background ("BoW")
+//   • Negative Lc — light text on dark background ("WoB")
+//
+// Typical body-text thresholds: |Lc| ≥ 75 comfortable, ≥ 60 minimum.
+// Reference: https://github.com/Myndex/SAPC-APCA (SA98G constants).
+// Uses the "simple" γ = 2.4 model, not the full sRGB EOTF, matching
+// the spec.
+
+import { Swatch, swatch } from "../core/swatch-class.js";
+import { inGamut, toGamut } from "./gamut.js";
+
+function toSwatch(input) {
+	return input instanceof Swatch ? input : swatch(input);
+}
+
+function toDisplaySrgb(input) {
+	const s = toSwatch(input);
+	if (inGamut(s, "srgb")) return s.to("srgb");
+	return toGamut(s, { space: "srgb" });
+}
+
+const mainTRC = 2.4;
+const sRco = 0.2126729;
+const sGco = 0.7151522;
+const sBco = 0.072175;
+
+function apcaY({ r, g, b }) {
+	return (
+		sRco * Math.pow(r, mainTRC) +
+		sGco * Math.pow(g, mainTRC) +
+		sBco * Math.pow(b, mainTRC)
+	);
+}
+
+// Soft clamp for luminances near black.
+const blkThrs = 0.022;
+const blkClmp = 1.414;
+function clampY(Y) {
+	return Y >= blkThrs ? Y : Y + Math.pow(blkThrs - Y, blkClmp);
+}
+
+const deltaYmin = 0.0005;
+const normBG = 0.56;
+const normTXT = 0.57;
+const revTXT = 0.62;
+const revBG = 0.65;
+const scaleBoW = 1.14;
+const scaleWoB = 1.14;
+const loBoWoffset = 0.027;
+const loWoBoffset = 0.027;
+const loClip = 0.1;
+
+export function apcaContrast(text, background) {
+	const t = toDisplaySrgb(text);
+	const b = toDisplaySrgb(background);
+
+	const txtY = clampY(apcaY(t.srgb));
+	const bgY = clampY(apcaY(b.srgb));
+
+	if (Math.abs(bgY - txtY) < deltaYmin) return 0;
+
+	let SAPC;
+	let outputContrast;
+	if (bgY > txtY) {
+		// BoW — light background, dark text (positive Lc).
+		SAPC =
+			(Math.pow(bgY, normBG) - Math.pow(txtY, normTXT)) * scaleBoW;
+		outputContrast = SAPC < loClip ? 0 : SAPC - loBoWoffset;
+	} else {
+		// WoB — dark background, light text (negative Lc).
+		SAPC =
+			(Math.pow(bgY, revBG) - Math.pow(txtY, revTXT)) * scaleWoB;
+		outputContrast = SAPC > -loClip ? 0 : SAPC + loWoBoffset;
+	}
+
+	return outputContrast * 100;
+}

package/src/operations/blend.js

@@ -0,0 +1,72 @@
+// Blend modes.
+//
+// The W3C "Compositing and Blending Level 1" non-separable blend modes
+// (minus hue/saturation/color/luminosity, which require a separate HSL
+// pass and aren't covered by the acceptance criteria). Operates on
+// sRGB-encoded channels per the CSS default blending color space —
+// this matches Canvas2D/Photoshop/CSS `mix-blend-mode` behavior.
+//
+// Alpha composition: for simplicity we combine alphas as `a_src +
+// a_dst - a_src * a_dst` (normal compositing); blending only affects
+// color channels.
+
+import { Swatch, swatch } from "../core/swatch-class.js";
+
+function clamp01(v) {
+	return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+
+const MODES = {
+	normal: (_cb, cs) => cs,
+	multiply: (cb, cs) => cb * cs,
+	screen: (cb, cs) => cb + cs - cb * cs,
+	darken: (cb, cs) => Math.min(cb, cs),
+	lighten: (cb, cs) => Math.max(cb, cs),
+	difference: (cb, cs) => Math.abs(cb - cs),
+	exclusion: (cb, cs) => cb + cs - 2 * cb * cs,
+	"color-dodge": (cb, cs) => {
+		if (cb === 0) return 0;
+		if (cs === 1) return 1;
+		return Math.min(1, cb / (1 - cs));
+	},
+	"color-burn": (cb, cs) => {
+		if (cb === 1) return 1;
+		if (cs === 0) return 0;
+		return 1 - Math.min(1, (1 - cb) / cs);
+	},
+	"hard-light": (cb, cs) => {
+		if (cs <= 0.5) return cb * cs * 2;
+		return cb + (2 * cs - 1) - cb * (2 * cs - 1);
+	},
+	"soft-light": (cb, cs) => {
+		if (cs <= 0.5) {
+			return cb - (1 - 2 * cs) * cb * (1 - cb);
+		}
+		const d =
+			cb <= 0.25 ? ((16 * cb - 12) * cb + 4) * cb : Math.sqrt(cb);
+		return cb + (2 * cs - 1) * (d - cb);
+	},
+	overlay: (cb, cs) => MODES["hard-light"](cs, cb)
+};
+
+export function listBlendModes() {
+	return Object.keys(MODES);
+}
+
+export function blend(backdrop, source, mode = "normal") {
+	const fn = MODES[mode];
+	if (!fn) throw new Error(`blend: unknown mode "${mode}"`);
+	const bs = backdrop instanceof Swatch ? backdrop : swatch(backdrop);
+	const ss = source instanceof Swatch ? source : swatch(source);
+	const b = bs.srgb;
+	const s = ss.srgb;
+	const r = clamp01(fn(b.r, s.r));
+	const g = clamp01(fn(b.g, s.g));
+	const bl = clamp01(fn(b.b, s.b));
+	const alpha = bs.alpha + ss.alpha - bs.alpha * ss.alpha;
+	return new Swatch({
+		space: "srgb",
+		coords: [r, g, bl],
+		alpha
+	});
+}

package/src/operations/channels.js

@@ -0,0 +1,123 @@
+// Channel get/set by path.
+//
+// Paths are either the literal `'alpha'`, or `'<space>.<channel>'` where
+// space is a registered space id (with `'rgb'` as an alias for `'srgb'`)
+// and channel is one of the space's channel names.
+//
+// `get(swatch, path)` returns the current value — converting to the
+// target space if necessary. `set(swatch, path, value)` returns a NEW
+// Swatch with the channel updated; the result's source space is the
+// space named in the path (so `set(red, 'oklch.l', 0.5).space === 'oklch'`).
+
+import { Swatch } from "../core/swatch-class.js";
+import { getSpace, hasSpace, listSpaces } from "../core/registry.js";
+import { appendSuggestion, closestMatch } from "../util/suggest.js";
+
+const SPACE_ALIASES = {
+	rgb: "srgb"
+};
+
+// Long-form channel names → the single-letter channel they refer to, scoped
+// per channel layout. Scoping matters because the same letter means different
+// things in different spaces: "b" is blue in rgb but blackness in hwb, and in
+// lab/oklab the a/b axes have no common long name at all. A single global map
+// would mis-suggest blackness's "b" for a stray `hwb.blue`.
+const CHANNEL_HINTS_BY_LAYOUT = {
+	"r,g,b": { red: "r", green: "g", blue: "b" },
+	"h,s,l": { hue: "h", saturation: "s", lightness: "l", luminosity: "l" },
+	"h,s,v": { hue: "h", saturation: "s", value: "v", brightness: "v" },
+	"h,w,b": { hue: "h", whiteness: "w", white: "w", blackness: "b", black: "b" },
+	"l,c,h": { lightness: "l", luminance: "l", chroma: "c", hue: "h" },
+	"c,m,y,k": { cyan: "c", magenta: "m", yellow: "y", black: "k", key: "k" }
+};
+
+function foldCmyk({ c, m, y, k }) {
+	return [c + k - c * k, m + k - m * k, y + k - y * k];
+}
+
+function resolveSpaceId(token) {
+	if (SPACE_ALIASES[token]) return SPACE_ALIASES[token];
+	return token;
+}
+
+function suggestChannel(channel, channels) {
+	const table = CHANNEL_HINTS_BY_LAYOUT[channels.join(",")];
+	const hinted = table?.[channel];
+	if (hinted && channels.includes(hinted)) return hinted;
+	return closestMatch(channel, channels);
+}
+
+function parsePath(path) {
+	if (typeof path !== "string" || path.length === 0) {
+		throw new Error("channel path: expected non-empty string");
+	}
+	if (path === "alpha") {
+		return { kind: "alpha" };
+	}
+	const dotIdx = path.indexOf(".");
+	if (dotIdx < 0) {
+		throw new Error(
+			`channel path: "${path}" must be "<space>.<channel>" or "alpha"`
+		);
+	}
+	const spaceToken = path.slice(0, dotIdx).toLowerCase();
+	const channel = path.slice(dotIdx + 1).toLowerCase();
+	const spaceId = resolveSpaceId(spaceToken);
+	if (!hasSpace(spaceId)) {
+		throw new Error(
+			appendSuggestion(
+				`channel path: unknown space "${spaceToken}"`,
+				spaceToken,
+				["rgb", ...listSpaces()]
+			)
+		);
+	}
+	if (spaceId === "cmyk" && channel === "k") {
+		return { kind: "cmyk-k" };
+	}
+	const space = getSpace(spaceId);
+	const idx = space.channels.indexOf(channel);
+	if (idx < 0) {
+		const suggestion = suggestChannel(channel, space.channels);
+		const maybeSuggestion = suggestion
+			? ` Did you mean "${suggestion}"?`
+			: "";
+		throw new Error(
+			`channel path: space "${spaceId}" has no channel "${channel}".${maybeSuggestion} Valid channels: ${space.channels.join(", ")}.`
+		);
+	}
+	return { kind: "channel", spaceId, channel, index: idx };
+}
+
+export function getChannel(swatch, path) {
+	const parsed = parsePath(path);
+	if (parsed.kind === "alpha") return swatch.alpha;
+	if (parsed.kind === "cmyk-k") return swatch.cmyk.k;
+	return swatch._getCoordsIn(parsed.spaceId)[parsed.index];
+}
+
+export function setChannel(swatch, path, value) {
+	const parsed = parsePath(path);
+	if (parsed.kind === "alpha") {
+		return new Swatch({
+			space: swatch.space,
+			coords: swatch.coords,
+			alpha: value
+		});
+	}
+	if (parsed.kind === "cmyk-k") {
+		const cmyk = swatch.cmyk;
+		return new Swatch({
+			space: "cmyk",
+			coords: foldCmyk({ ...cmyk, k: value }),
+			alpha: swatch.alpha
+		});
+	}
+	const coords = swatch._getCoordsIn(parsed.spaceId);
+	coords[parsed.index] = value;
+	return new Swatch({
+		space: parsed.spaceId,
+		coords,
+		alpha: swatch.alpha
+	});
+}

package/src/operations/cvd.js

@@ -0,0 +1,119 @@
+// Color Vision Deficiency simulation and daltonization.
+//
+// Projection matrices for protan/deutan/tritan come from
+// data/cvd-matrices.js via the Brettel/Viénot anchor-line method.
+// simulate() interpolates between the identity and the dichromat
+// matrix by `severity` (0..1). daltonize() uses Fidaner-style error
+// redistribution: compute what the dichromat loses (the delta in
+// linear sRGB) and shift it into channels the user can still see.
+
+import { Swatch, swatch } from "../core/swatch-class.js";
+import { srgbToLinear, linearToSrgb } from "../spaces/srgb.js";
+import {
+	CVD_RGB_MATRICES,
+	IDENTITY3,
+	ACHROMA_MATRIX,
+	interpolateMatrix3,
+	normalizeCVDType
+} from "../data/cvd-matrices.js";
+
+function toSwatch(input) {
+	return input instanceof Swatch ? input : swatch(input);
+}
+
+function mat3mulVec3(M, v) {
+	return [
+		M[0][0] * v[0] + M[0][1] * v[1] + M[0][2] * v[2],
+		M[1][0] * v[0] + M[1][1] * v[1] + M[1][2] * v[2],
+		M[2][0] * v[0] + M[2][1] * v[1] + M[2][2] * v[2]
+	];
+}
+
+function clamp01Triplet(v) {
+	for (let i = 0; i < 3; i++) {
+		if (v[i] < 0) v[i] = 0;
+		else if (v[i] > 1) v[i] = 1;
+	}
+	return v;
+}
+
+export function simulate(input, type, { severity = 1 } = {}) {
+	const s = toSwatch(input);
+	const sev = Math.max(0, Math.min(1, severity));
+	const normalized = normalizeCVDType(type);
+
+	let M;
+	if (normalized === "achroma") {
+		M = interpolateMatrix3(IDENTITY3, ACHROMA_MATRIX, sev);
+	} else {
+		M = interpolateMatrix3(
+			IDENTITY3,
+			CVD_RGB_MATRICES[normalized],
+			sev
+		);
+	}
+
+	const { r, g, b } = s.srgb;
+	const lin = srgbToLinear([r, g, b]);
+	const linOut = clamp01Triplet(mat3mulVec3(M, lin));
+	const out = linearToSrgb(linOut);
+
+	return new Swatch({
+		space: "srgb",
+		coords: out,
+		alpha: s.alpha
+	});
+}
+
+export function daltonize(input, type, { severity = 1 } = {}) {
+	const s = toSwatch(input);
+	const sev = Math.max(0, Math.min(1, severity));
+	const normalized = normalizeCVDType(type);
+	if (normalized === "achroma") {
+		throw new Error(
+			"daltonize: achromatopsia cannot be corrected (no remaining channels)"
+		);
+	}
+
+	const M = interpolateMatrix3(
+		IDENTITY3,
+		CVD_RGB_MATRICES[normalized],
+		sev
+	);
+
+	const { r, g, b } = s.srgb;
+	const lin = srgbToLinear([r, g, b]);
+	const linSim = mat3mulVec3(M, lin);
+	const err = [lin[0] - linSim[0], lin[1] - linSim[1], lin[2] - linSim[2]];
+
+	// Fidaner shift matrices:
+	//   red-green deficits push red-channel error into G and B;
+	//   blue-yellow (tritan) pushes blue error into R and G.
+	let shift;
+	if (normalized === "tritan") {
+		shift = [
+			[0, 0, 0.7],
+			[0, 0, 0.7],
+			[0, 0, 0]
+		];
+	} else {
+		shift = [
+			[0, 0, 0],
+			[0.7, 0, 0],
+			[0.7, 0, 0]
+		];
+	}
+
+	const corrected = clamp01Triplet([
+		lin[0] + shift[0][0] * err[0] + shift[0][1] * err[1] + shift[0][2] * err[2],
+		lin[1] + shift[1][0] * err[0] + shift[1][1] * err[1] + shift[1][2] * err[2],
+		lin[2] + shift[2][0] * err[0] + shift[2][1] * err[1] + shift[2][2] * err[2]
+	]);
+
+	const out = linearToSrgb(corrected);
+	return new Swatch({
+		space: "srgb",
+		coords: out,
+		alpha: s.alpha
+	});
+}

package/src/operations/deltaE.js

@@ -0,0 +1,207 @@
+// Color difference metrics.
+//
+//   deltaE(a, b, mode)
+//     "76"   — CIE76 euclidean distance in CIE Lab D65
+//     "94"   — CIE94 (graphic arts, kL=kC=kH=1, K1=0.045, K2=0.015)
+//     "2000" — CIEDE2000 (Sharma, Wu, Dalal 2005), kL = kC = kH = 1
+//     "cmc"  — CMC l:c with default l=1 c=1; override via opts
+//              (pass as { mode: 'cmc', l, c }, or deltaE(a,b,'cmc',opts))
+//     "hyab" — Abasi/Fairchild HyAB for large color differences
+//     "ok"   — euclidean distance in OKLab
+//
+// All Lab-based metrics operate on D65 Lab (matching v2 behavior
+// and the colorjs.io convention).
+
+import { Swatch, swatch } from "../core/swatch-class.js";
+
+function toSwatch(input) {
+	return input instanceof Swatch ? input : swatch(input);
+}
+
+function lab(s) {
+	return s._getCoordsIn("lab");
+}
+function oklab(s) {
+	return s._getCoordsIn("oklab");
+}
+
+export function deltaE76(a, b) {
+	const [l1, a1, b1] = lab(toSwatch(a));
+	const [l2, a2, b2] = lab(toSwatch(b));
+	return Math.hypot(l1 - l2, a1 - a2, b1 - b2);
+}
+
+export function deltaEOK(a, b) {
+	const [l1, a1, b1] = oklab(toSwatch(a));
+	const [l2, a2, b2] = oklab(toSwatch(b));
+	return Math.hypot(l1 - l2, a1 - a2, b1 - b2);
+}
+
+// CIEDE2000 — Sharma, Wu, Dalal (2005).
+export function deltaE2000(a, b) {
+	const [L1, a1, b1] = lab(toSwatch(a));
+	const [L2, a2, b2] = lab(toSwatch(b));
+	const deg = Math.PI / 180;
+
+	const C1 = Math.hypot(a1, b1);
+	const C2 = Math.hypot(a2, b2);
+	const Cbar = (C1 + C2) / 2;
+
+	const Cbar7 = Math.pow(Cbar, 7);
+	const G = 0.5 * (1 - Math.sqrt(Cbar7 / (Cbar7 + Math.pow(25, 7))));
+
+	const a1p = (1 + G) * a1;
+	const a2p = (1 + G) * a2;
+
+	const C1p = Math.hypot(a1p, b1);
+	const C2p = Math.hypot(a2p, b2);
+
+	let h1p = (Math.atan2(b1, a1p) * 180) / Math.PI;
+	if (h1p < 0) h1p += 360;
+	let h2p = (Math.atan2(b2, a2p) * 180) / Math.PI;
+	if (h2p < 0) h2p += 360;
+
+	const dLp = L2 - L1;
+	const dCp = C2p - C1p;
+
+	let dhp;
+	if (C1p * C2p === 0) {
+		dhp = 0;
+	} else if (Math.abs(h2p - h1p) <= 180) {
+		dhp = h2p - h1p;
+	} else if (h2p - h1p > 180) {
+		dhp = h2p - h1p - 360;
+	} else {
+		dhp = h2p - h1p + 360;
+	}
+	const dHp = 2 * Math.sqrt(C1p * C2p) * Math.sin((dhp / 2) * deg);
+
+	const LbarP = (L1 + L2) / 2;
+	const CbarP = (C1p + C2p) / 2;
+
+	let hbarP;
+	if (C1p * C2p === 0) {
+		hbarP = h1p + h2p;
+	} else if (Math.abs(h1p - h2p) <= 180) {
+		hbarP = (h1p + h2p) / 2;
+	} else if (h1p + h2p < 360) {
+		hbarP = (h1p + h2p + 360) / 2;
+	} else {
+		hbarP = (h1p + h2p - 360) / 2;
+	}
+
+	const T =
+		1 -
+		0.17 * Math.cos((hbarP - 30) * deg) +
+		0.24 * Math.cos(2 * hbarP * deg) +
+		0.32 * Math.cos((3 * hbarP + 6) * deg) -
+		0.2 * Math.cos((4 * hbarP - 63) * deg);
+
+	const dTheta = 30 * Math.exp(-Math.pow((hbarP - 275) / 25, 2));
+
+	const CbarP7 = Math.pow(CbarP, 7);
+	const Rc = 2 * Math.sqrt(CbarP7 / (CbarP7 + Math.pow(25, 7)));
+
+	const Sl =
+		1 +
+		(0.015 * Math.pow(LbarP - 50, 2)) /
+			Math.sqrt(20 + Math.pow(LbarP - 50, 2));
+	const Sc = 1 + 0.045 * CbarP;
+	const Sh = 1 + 0.015 * CbarP * T;
+
+	const Rt = -Math.sin(2 * dTheta * deg) * Rc;
+
+	const kL = 1;
+	const kC = 1;
+	const kH = 1;
+	const termL = dLp / (kL * Sl);
+	const termC = dCp / (kC * Sc);
+	const termH = dHp / (kH * Sh);
+
+	return Math.sqrt(
+		termL * termL +
+			termC * termC +
+			termH * termH +
+			Rt * termC * termH
+	);
+}
+
+// CIE94 — graphic-arts application (textiles uses different constants).
+// kL = kC = kH = 1, K1 = 0.045, K2 = 0.015.
+// Symmetric by using sample 1 as reference (v2 convention).
+export function deltaE94(a, b) {
+	const [L1, a1, b1] = lab(toSwatch(a));
+	const [L2, a2, b2] = lab(toSwatch(b));
+
+	const C1 = Math.hypot(a1, b1);
+	const C2 = Math.hypot(a2, b2);
+
+	const dL = L1 - L2;
+	const dC = C1 - C2;
+	const da = a1 - a2;
+	const db = b1 - b2;
+	// dH² = da² + db² − dC². Guard against tiny negatives from rounding.
+	const dH2 = Math.max(da * da + db * db - dC * dC, 0);
+
+	const SL = 1;
+	const SC = 1 + 0.045 * C1;
+	const SH = 1 + 0.015 * C1;
+
+	const termL = dL / SL;
+	const termC = dC / SC;
+	// termH² = dH² / SH²
+	return Math.sqrt(termL * termL + termC * termC + dH2 / (SH * SH));
+}
+
+// CMC l:c — sample 1 is reference. Defaults l=1 c=1 ("acceptability");
+// pass l=2 for "perceptibility".
+export function deltaECMC(a, b, { l = 1, c = 1 } = {}) {
+	const [L1, a1, b1] = lab(toSwatch(a));
+	const [L2, a2, b2] = lab(toSwatch(b));
+	const deg = Math.PI / 180;
+
+	const C1 = Math.hypot(a1, b1);
+	const C2 = Math.hypot(a2, b2);
+
+	let H1 = (Math.atan2(b1, a1) * 180) / Math.PI;
+	if (H1 < 0) H1 += 360;
+
+	const dL = L1 - L2;
+	const dC = C1 - C2;
+	const da = a1 - a2;
+	const db = b1 - b2;
+	const dH2 = Math.max(da * da + db * db - dC * dC, 0);
+
+	const SL = L1 < 16 ? 0.511 : (0.040975 * L1) / (1 + 0.01765 * L1);
+	const SC = (0.0638 * C1) / (1 + 0.0131 * C1) + 0.638;
+
+	const F = Math.sqrt(Math.pow(C1, 4) / (Math.pow(C1, 4) + 1900));
+	const T =
+		H1 >= 164 && H1 <= 345
+			? 0.56 + Math.abs(0.2 * Math.cos((H1 + 168) * deg))
+			: 0.36 + Math.abs(0.4 * Math.cos((H1 + 35) * deg));
+	const SH = SC * (F * T + 1 - F);
+
+	const termL = dL / (l * SL);
+	const termC = dC / (c * SC);
+	return Math.sqrt(termL * termL + termC * termC + dH2 / (SH * SH));
+}
+
+// HyAB — Abasi & Fairchild (2020), "Distancing colour signals from the
+// visual system." L distance plus euclidean (a,b) distance; performs
+// better than ΔE2000 for large color differences.
+export function deltaEHyAB(a, b) {
+	const [L1, a1, b1] = lab(toSwatch(a));
+	const [L2, a2, b2] = lab(toSwatch(b));
+	return Math.abs(L1 - L2) + Math.hypot(a1 - a2, b1 - b2);
+}
+
+export function deltaE(a, b, mode = "2000", opts) {
+	if (mode === "76") return deltaE76(a, b);
+	if (mode === "94") return deltaE94(a, b);
+	if (mode === "2000") return deltaE2000(a, b);
+	if (mode === "cmc") return deltaECMC(a, b, opts);
+	if (mode === "hyab") return deltaEHyAB(a, b);
+	if (mode === "ok") return deltaEOK(a, b);
+	throw new Error(`deltaE: unknown mode "${mode}"`);
+}