@luntta/swatch 3.0.0

package/src/operations/naming.js

@@ -0,0 +1,158 @@
+// Color naming — nearest named color by ΔE2000.
+//
+// Uses the CSS Color Module Level 4 named-color list from
+// src/data/named-colors.js. At module load time we precompute Lab
+// D65 coordinates for each entry so that `name()` only needs to
+// convert the query color once per call.
+//
+// Because several CSS names are synonyms (aqua ↔ cyan, grey ↔ gray,
+// magenta ↔ fuchsia), we deduplicate by hex — an exact match to any
+// of these returns one canonical name but both names remain valid
+// matches via the dedup table.
+
+import { Swatch, swatch } from "../core/swatch-class.js";
+import { convert } from "../core/registry.js";
+import { deltaE2000 } from "./deltaE.js";
+import namedColors from "../data/named-colors.js";
+
+// Canonical list: deduplicated by hex, preferring the first name in
+// iteration order. `transparent` is excluded (it has no chromatic
+// meaning for naming purposes).
+//
+// We build the table at module-load time without going through the
+// swatch() factory, because the bootstrap sequence imports this module
+// *before* it installs the parser — using swatch() here would crash
+// with "parser not initialized".
+const ENTRIES = [];
+const SEEN_HEX = new Map();
+
+function hexToSrgb(hex) {
+	const r = parseInt(hex.slice(0, 2), 16) / 255;
+	const g = parseInt(hex.slice(2, 4), 16) / 255;
+	const b = parseInt(hex.slice(4, 6), 16) / 255;
+	return [r, g, b];
+}
+
+for (const [colorName, hex] of Object.entries(namedColors)) {
+	if (colorName === "transparent") continue;
+	if (SEEN_HEX.has(hex)) continue;
+	SEEN_HEX.set(hex, colorName);
+	const srgb = hexToSrgb(hex);
+	const lab = convert(srgb, "srgb", "lab");
+	ENTRIES.push({ name: colorName, hex: "#" + hex, lab });
+}
+
+function lab2000FromLab(lab1, lab2) {
+	// Inlined ΔE2000 so we avoid constructing a Swatch for every
+	// precomputed entry on every lookup.
+	const deg = Math.PI / 180;
+	const [L1, a1, b1] = lab1;
+	const [L2, a2, b2] = lab2;
+
+	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 termL = dLp / Sl;
+	const termC = dCp / Sc;
+	const termH = dHp / Sh;
+
+	return Math.sqrt(
+		termL * termL +
+			termC * termC +
+			termH * termH +
+			Rt * termC * termH
+	);
+}
+
+function toSwatch(input) {
+	return input instanceof Swatch ? input : swatch(input);
+}
+
+export function name(input, _opts = {}) {
+	const s = toSwatch(input);
+	const queryLab = s._getCoordsIn("lab");
+	let best = null;
+	let bestD = Infinity;
+	for (const entry of ENTRIES) {
+		const d = lab2000FromLab(queryLab, entry.lab);
+		if (d < bestD) {
+			bestD = d;
+			best = entry;
+		}
+	}
+	return { name: best.name, hex: best.hex, deltaE: bestD };
+}
+
+export function toName(input) {
+	return name(input).name;
+}
+
+// Useful for tests and users who want the raw data table.
+export function listNamedColors() {
+	return ENTRIES.map((e) => ({ name: e.name, hex: e.hex }));
+}

package/src/operations/palette.js

@@ -0,0 +1,133 @@
+// Palette helpers.
+//
+//   checkPalette(palette, { cvd, severity, minDeltaE, mode })
+//     Pairwise ΔE scan (under an optional CVD simulation) reporting
+//     the smallest distance and any pairs that fall under the threshold.
+//
+//   nearestDistinguishable(target, against, { cvd, severity, minDeltaE, mode, step })
+//     Walk target's HSL lightness until it is ≥ minDeltaE away from
+//     `against` under the chosen CVD simulation.
+//
+//   mostReadable(background, candidates, { level, size, includeFallback })
+//     Pick the highest-contrast foreground that passes WCAG. Falls
+//     back to black/white if none pass (unless includeFallback=false).
+
+import { Swatch, swatch } from "../core/swatch-class.js";
+import { simulate } from "./cvd.js";
+import { deltaE as defaultDeltaE } from "./deltaE.js";
+import { contrast, isReadable } from "./accessibility.js";
+
+function toSwatch(input) {
+	return input instanceof Swatch ? input : swatch(input);
+}
+
+export function checkPalette(palette, opts = {}) {
+	const {
+		cvd = null,
+		severity = 1,
+		minDeltaE = 11,
+		mode = "2000"
+	} = opts;
+
+	const colors = palette.map(toSwatch);
+	const view = cvd
+		? colors.map((c) => simulate(c, cvd, { severity }))
+		: colors;
+
+	const pairs = [];
+	const unsafe = [];
+	let minDE = Infinity;
+
+	for (let i = 0; i < view.length; i++) {
+		for (let j = i + 1; j < view.length; j++) {
+			const de = defaultDeltaE(view[i], view[j], mode);
+			const safe = de >= minDeltaE;
+			const entry = { i, j, deltaE: de, safe };
+			pairs.push(entry);
+			if (!safe) unsafe.push(entry);
+			if (de < minDE) minDE = de;
+		}
+	}
+
+	return {
+		pairs,
+		unsafe,
+		minDeltaE: minDE === Infinity ? 0 : minDE,
+		safe: unsafe.length === 0
+	};
+}
+
+export function nearestDistinguishable(target, against, opts = {}) {
+	const {
+		cvd = null,
+		severity = 1,
+		minDeltaE = 11,
+		mode = "2000",
+		step = 2
+	} = opts;
+
+	const targetT = toSwatch(target);
+	const againstT = toSwatch(against);
+
+	function evalDE(t) {
+		const a = cvd ? simulate(t, cvd, { severity }) : t;
+		const b = cvd ? simulate(againstT, cvd, { severity }) : againstT;
+		return defaultDeltaE(a, b, mode);
+	}
+
+	if (evalDE(targetT) >= minDeltaE) return targetT;
+
+	const baseHsl = targetT.hsl;
+	let best = targetT;
+	let bestDE = evalDE(targetT);
+
+	for (let d = step; d <= 100; d += step) {
+		for (const sign of [-1, 1]) {
+			const newL = baseHsl.l + sign * d;
+			if (newL < 0 || newL > 100) continue;
+			const candidate = swatch({
+				space: "hsl",
+				coords: [baseHsl.h, baseHsl.s, newL],
+				alpha: targetT.alpha
+			});
+			const de = evalDE(candidate);
+			if (de > bestDE) {
+				bestDE = de;
+				best = candidate;
+			}
+			if (de >= minDeltaE) return candidate;
+		}
+	}
+	return best;
+}
+
+export function mostReadable(background, candidates, opts = {}) {
+	const bg = toSwatch(background);
+	const cands = candidates.map(toSwatch);
+
+	let bestPass = null;
+	let bestPassRatio = -Infinity;
+	let bestAny = null;
+	let bestAnyRatio = -Infinity;
+
+	for (const c of cands) {
+		const ratio = contrast(c, bg);
+		if (isReadable(c, bg, opts)) {
+			if (ratio > bestPassRatio) {
+				bestPassRatio = ratio;
+				bestPass = c;
+			}
+		}
+		if (ratio > bestAnyRatio) {
+			bestAnyRatio = ratio;
+			bestAny = c;
+		}
+	}
+
+	if (bestPass) return bestPass;
+	if (opts.includeFallback === false) return bestAny;
+
+	const black = swatch("#000000");
+	const white = swatch("#ffffff");
+	return contrast(black, bg) >= contrast(white, bg) ? black : white;
+}

package/src/operations/random.js

@@ -0,0 +1,75 @@
+// Random color generation.
+//
+//   swatch.random()
+//     Uniform random sRGB color.
+//
+//   swatch.random({ space, hue, lightness, chroma, saturation, seed })
+//     Constrained random color in the chosen space ('oklch' or 'hsl').
+//     Each of `hue`, `lightness`, `chroma`, `saturation` is either a
+//     single number (fixed) or a [min, max] tuple (uniform range). If
+//     `seed` is given, an xorshift32 PRNG is used for reproducibility;
+//     otherwise Math.random() is used.
+//
+// Unknown constraint keys for the current space are ignored.
+
+import { Swatch } from "../core/swatch-class.js";
+
+function xorshift32(seed) {
+	// Classic xorshift32 PRNG. Seed must be a non-zero 32-bit integer;
+	// if the caller passes 0 we nudge it to 1.
+	let s = seed | 0;
+	if (s === 0) s = 1;
+	return function next() {
+		s ^= s << 13;
+		s ^= s >>> 17;
+		s ^= s << 5;
+		// Map to [0, 1). Shift into positive and divide by 2^32.
+		return (s >>> 0) / 0x100000000;
+	};
+}
+
+function pick(rng, value, defaultRange) {
+	if (value == null) {
+		const [lo, hi] = defaultRange;
+		return lo + rng() * (hi - lo);
+	}
+	if (typeof value === "number") return value;
+	if (Array.isArray(value) && value.length === 2) {
+		const [lo, hi] = value;
+		if (lo === hi) return lo;
+		return lo + rng() * (hi - lo);
+	}
+	throw new Error("random: constraints must be a number or [min, max]");
+}
+
+export function random(opts = {}) {
+	const rng = opts.seed != null ? xorshift32(opts.seed) : Math.random;
+	const space = opts.space;
+
+	if (!space) {
+		// Uniform sRGB.
+		const r = rng();
+		const g = rng();
+		const b = rng();
+		return new Swatch({ space: "srgb", coords: [r, g, b], alpha: 1 });
+	}
+
+	if (space === "oklch") {
+		const l = pick(rng, opts.lightness, [0, 1]);
+		const c = pick(rng, opts.chroma, [0, 0.4]);
+		const h = pick(rng, opts.hue, [0, 360]);
+		return new Swatch({ space: "oklch", coords: [l, c, h], alpha: 1 });
+	}
+
+	if (space === "hsl") {
+		// HSL stores S/L as percent (0..100) per CSS convention.
+		// Callers can pass either percent ([0, 100]) or any tuple
+		// consistent with the HSL registration.
+		const h = pick(rng, opts.hue, [0, 360]);
+		const s = pick(rng, opts.saturation, [0, 100]);
+		const l = pick(rng, opts.lightness, [0, 100]);
+		return new Swatch({ space: "hsl", coords: [h, s, l], alpha: 1 });
+	}
+
+	throw new Error(`random: unsupported space "${space}"`);
+}

package/src/operations/temperature.js

@@ -0,0 +1,126 @@
+// Correlated color temperature (CCT) ↔ color.
+//
+// Forward: Krystek 1985 piecewise polynomial maps blackbody CCT
+// (Kelvin) onto CIE 1931 xy chromaticity, then to XYZ, then to a
+// scaled sRGB triple normalized so the brightest channel equals 1.
+//
+// Inverse: McCamy 1992 cubic approximation from xy to CCT. This is
+// a *fit*, not an exact inversion — documented as approximate. The
+// fit is accurate to within a few kelvin for daylight illuminants
+// but degrades at the extremes of the Planckian locus.
+//
+// Supported range: 1000 K – 40000 K. Outside this range the
+// polynomial is not defined and we throw.
+
+import { Swatch } from "../core/swatch-class.js";
+import { convert } from "../core/registry.js";
+
+const MIN_K = 1000;
+const MAX_K = 40000;
+
+// Krystek 1985 (also published as CIE D illuminant series refinement).
+// Reference: Krystek, M. (1985) "An algorithm to calculate correlated
+// colour temperature", Color Research & Application 10, 38–40.
+//
+// Implementation here uses the classic piecewise-cubic fit
+// (Kim et al. 2002, also reproduced in Wikipedia's
+// "Planckian locus" article) which matches the blackbody locus to
+// within a few ΔE across the working range.
+function kelvinToXy(k) {
+	if (k < MIN_K || k > MAX_K) {
+		throw new Error(
+			`temperature: ${k}K is out of range [${MIN_K}, ${MAX_K}]`
+		);
+	}
+	const T = k;
+	let x;
+	if (T <= 4000) {
+		// 1667 K ≤ T ≤ 4000 K
+		x =
+			-0.2661239 * (1e9 / (T * T * T)) -
+			0.2343589 * (1e6 / (T * T)) +
+			0.8776956 * (1e3 / T) +
+			0.17991;
+	} else {
+		// 4000 K ≤ T ≤ 25000 K — also used as an extrapolation up to 40000 K.
+		x =
+			-3.0258469 * (1e9 / (T * T * T)) +
+			2.1070379 * (1e6 / (T * T)) +
+			0.2226347 * (1e3 / T) +
+			0.24039;
+	}
+	let y;
+	if (T <= 2222) {
+		y =
+			-1.1063814 * (x * x * x) -
+			1.3481102 * (x * x) +
+			2.18555832 * x -
+			0.20219683;
+	} else if (T <= 4000) {
+		y =
+			-0.9549476 * (x * x * x) -
+			1.37418593 * (x * x) +
+			2.09137015 * x -
+			0.16748867;
+	} else {
+		y =
+			3.081758 * (x * x * x) -
+			5.8733867 * (x * x) +
+			3.75112997 * x -
+			0.37001483;
+	}
+	return [x, y];
+}
+
+function xyToXyz(x, y) {
+	// Y normalized to 1; XYZ scaled by Y/y.
+	if (y === 0) return [0, 0, 0];
+	const Y = 1;
+	const X = (x * Y) / y;
+	const Z = ((1 - x - y) * Y) / y;
+	return [X, Y, Z];
+}
+
+// Build a Swatch for the blackbody radiator at `kelvin`. The returned
+// color is in sRGB, gamut-clipped and normalized so the brightest
+// channel is 1 (which is how temperature-picker widgets conventionally
+// present these colors).
+export function temperature(kelvin) {
+	const [x, y] = kelvinToXy(kelvin);
+	const xyz = xyToXyz(x, y);
+	const srgbLinear = convert(xyz, "xyz", "srgb-linear");
+	// Normalize so the max linear channel is 1 (preserve chromaticity).
+	let m = Math.max(srgbLinear[0], srgbLinear[1], srgbLinear[2]);
+	if (m <= 0) m = 1;
+	const scaled = [
+		srgbLinear[0] / m,
+		srgbLinear[1] / m,
+		srgbLinear[2] / m
+	];
+	// Clip any residual negatives (blackbody below ~1900K can still
+	// produce small negative B values even after chroma scaling).
+	for (let i = 0; i < 3; i++) {
+		if (scaled[i] < 0) scaled[i] = 0;
+		if (scaled[i] > 1) scaled[i] = 1;
+	}
+	const srgb = convert(scaled, "srgb-linear", "srgb");
+	return new Swatch({ space: "srgb", coords: srgb, alpha: 1 });
+}
+
+// McCamy 1992: xy chromaticity → approximate CCT in Kelvin.
+// n = (x − 0.3320) / (0.1858 − y)
+// CCT ≈ 449 n³ + 3525 n² + 6823.3 n + 5520.33
+//
+// Accurate for daylight-ish illuminants; degrades on extreme locus
+// points. Documented as an approximation.
+export function kelvin(input) {
+	// `input` must be a Swatch — wrapping is the caller's job, and
+	// temperature() exposes this only via the prototype method below.
+	const [X, Y, Z] = input._getCoordsIn("xyz");
+	const sum = X + Y + Z;
+	if (sum === 0) return NaN;
+	const x = X / sum;
+	const y = Y / sum;
+	const n = (x - 0.332) / (0.1858 - y);
+	return 449 * n * n * n + 3525 * n * n + 6823.3 * n + 5520.33;
+}

package/src/operations/tint-shade.js

@@ -0,0 +1,42 @@
+// Tint / shade / tone helpers.
+//
+// All three operations are OKLab linear interpolations between the
+// source and a reference color:
+//
+//   tint(c, t)   mixes toward white        — OKLab (1, 0, 0)
+//   shade(c, t)  mixes toward black        — OKLab (0, 0, 0)
+//   tone(c, t)   mixes toward mid-gray     — OKLab (0.5, 0, 0)
+//
+// Amount is a 0..1 fraction: 0 is identity, 1 is fully at the reference.
+//
+// OKLab is used instead of sRGB so tints/shades stay on a visually
+// straight line and mid-gray is perceptually mid.
+
+import { Swatch } from "../core/swatch-class.js";
+
+function lerpOklab(swatch, targetLab, amount) {
+	const src = swatch._getCoordsIn("oklab");
+	const t = amount;
+	const lerp = (a, b) => a + (b - a) * t;
+	return new Swatch({
+		space: "oklab",
+		coords: [
+			lerp(src[0], targetLab[0]),
+			lerp(src[1], targetLab[1]),
+			lerp(src[2], targetLab[2])
+		],
+		alpha: swatch.alpha
+	});
+}
+
+export function tint(swatch, amount = 0.1) {
+	return lerpOklab(swatch, [1, 0, 0], amount);
+}
+
+export function shade(swatch, amount = 0.1) {
+	return lerpOklab(swatch, [0, 0, 0], amount);
+}
+
+export function tone(swatch, amount = 0.1) {
+	return lerpOklab(swatch, [0.5, 0, 0], amount);
+}