@luntta/swatch 3.0.0

package/src/operations/gamut.js

@@ -0,0 +1,206 @@
+// Gamut detection and mapping.
+//
+// `inGamut(swatch, spaceId)` reports whether the color fits inside the
+// [0, 1] cube of the target display RGB space. Only gamut-bounded spaces
+// are meaningful; for unbounded spaces (Lab, OKLab, XYZ, polar forms) the
+// function always returns `true`.
+//
+// `toGamut(swatch, opts)` maps an out-of-gamut color into the target
+// space. Two methods:
+//
+//   'clip'   — convert to target and clamp each channel. Fast, but
+//               shifts hue in a perceptually unfriendly way.
+//   'css4'   — the CSS Color 4 binary chroma reduction: hold OKLCh L
+//               and H fixed, binary-search C downward until the clipped
+//               result is within ΔEOK < 0.02 of the candidate. Hue is
+//               preserved, lightness drifts only minimally.
+//
+// 'oklch-chroma' is an alias for 'css4'.
+
+import { Swatch } from "../core/swatch-class.js";
+import { getSpace } from "../core/registry.js";
+import { clamp } from "../util/math.js";
+import { appendSuggestion } from "../util/suggest.js";
+
+const DEFAULT_EPSILON = 1e-5;
+const JND = 0.02;
+const SEARCH_EPSILON = 1e-4;
+
+// The set of display RGB spaces whose natural coord domain is [0, 1]^3.
+// Phase 7 extends this list when display-p3, rec2020, a98, and prophoto
+// register.
+const RGB_GAMUT_SPACES = new Set([
+	"srgb",
+	"srgb-linear",
+	"display-p3",
+	"rec2020",
+	"a98",
+	"prophoto"
+]);
+
+export function isGamutBounded(spaceId) {
+	return RGB_GAMUT_SPACES.has(spaceId);
+}
+
+export function inGamut(swatch, spaceId = "srgb", opts = {}) {
+	if (!isGamutBounded(spaceId)) return true;
+	const epsilon = opts.epsilon ?? DEFAULT_EPSILON;
+	const coords = swatch._getCoordsIn(spaceId);
+	for (let i = 0; i < 3; i++) {
+		if (coords[i] < -epsilon) return false;
+		if (coords[i] > 1 + epsilon) return false;
+	}
+	return true;
+}
+
+function clipCoords(coords) {
+	return [clamp(coords[0], 0, 1), clamp(coords[1], 0, 1), clamp(coords[2], 0, 1)];
+}
+
+function deltaEOK(lab1, lab2) {
+	const dL = lab1[0] - lab2[0];
+	const da = lab1[1] - lab2[1];
+	const db = lab1[2] - lab2[2];
+	return Math.sqrt(dL * dL + da * da + db * db);
+}
+
+// Convert an (L, C, H) OKLCh triple to a target RGB space's coords.
+function oklchToTarget(L, C, H, targetId) {
+	const oklch = getSpace("oklch");
+	const target = getSpace(targetId);
+	// Shortcut if oklch has one, else via XYZ.
+	if (oklch.shortcuts[targetId]) {
+		return oklch.shortcuts[targetId]([L, C, H]);
+	}
+	return target.fromXYZ(oklch.toXYZ([L, C, H]));
+}
+
+// Convert an RGB-space triple to OKLab coords (for ΔEOK).
+function targetToOklab(coords, targetId) {
+	const target = getSpace(targetId);
+	const oklab = getSpace("oklab");
+	if (target.shortcuts.oklab) {
+		return target.shortcuts.oklab(coords);
+	}
+	return oklab.fromXYZ(target.toXYZ(coords));
+}
+
+function oklchToOklab(L, C, H) {
+	const oklch = getSpace("oklch");
+	if (oklch.shortcuts.oklab) {
+		return oklch.shortcuts.oklab([L, C, H]);
+	}
+	const oklab = getSpace("oklab");
+	return oklab.fromXYZ(oklch.toXYZ([L, C, H]));
+}
+
+function clipInto(swatch, targetId) {
+	const coords = swatch._getCoordsIn(targetId);
+	return new Swatch({
+		space: targetId,
+		coords: clipCoords(coords),
+		alpha: swatch.alpha
+	});
+}
+
+function toGamutCss4(swatch, targetId) {
+	// Convert to OKLCh to read L and H.
+	const originOklch = swatch._getCoordsIn("oklch");
+	const L = originOklch[0];
+	const originC = originOklch[1];
+	const H = originOklch[2];
+
+	// Edge cases: pure white / pure black.
+	if (L >= 1 - 1e-12) {
+		return new Swatch({ space: targetId, coords: [1, 1, 1], alpha: swatch.alpha });
+	}
+	if (L <= 1e-12) {
+		return new Swatch({ space: targetId, coords: [0, 0, 0], alpha: swatch.alpha });
+	}
+
+	// Quick-return if the clipped origin is already perceptually close.
+	const originTarget = swatch._getCoordsIn(targetId);
+	const originClipped = clipCoords(originTarget);
+	const originClippedOklab = targetToOklab(originClipped, targetId);
+	const originOklab = oklchToOklab(L, originC, H);
+	if (deltaEOK(originClippedOklab, originOklab) < JND) {
+		return new Swatch({
+			space: targetId,
+			coords: originClipped,
+			alpha: swatch.alpha
+		});
+	}
+
+	// Binary search chroma.
+	let min = 0;
+	let max = originC;
+	let minInGamut = true;
+	let lastClipped = originClipped;
+
+	while (max - min > SEARCH_EPSILON) {
+		const chroma = (min + max) / 2;
+		const candidate = oklchToTarget(L, chroma, H, targetId);
+
+		const candidateInGamut =
+			candidate[0] >= -DEFAULT_EPSILON &&
+			candidate[0] <= 1 + DEFAULT_EPSILON &&
+			candidate[1] >= -DEFAULT_EPSILON &&
+			candidate[1] <= 1 + DEFAULT_EPSILON &&
+			candidate[2] >= -DEFAULT_EPSILON &&
+			candidate[2] <= 1 + DEFAULT_EPSILON;
+
+		if (minInGamut && candidateInGamut) {
+			min = chroma;
+			lastClipped = clipCoords(candidate);
+			continue;
+		}
+
+		const clipped = clipCoords(candidate);
+		const clippedOklab = targetToOklab(clipped, targetId);
+		const candOklab = oklchToOklab(L, chroma, H);
+		const E = deltaEOK(clippedOklab, candOklab);
+
+		if (E < JND) {
+			if (JND - E < SEARCH_EPSILON) {
+				lastClipped = clipped;
+				break;
+			}
+			minInGamut = false;
+			min = chroma;
+			lastClipped = clipped;
+		} else {
+			max = chroma;
+		}
+	}
+
+	return new Swatch({
+		space: targetId,
+		coords: lastClipped,
+		alpha: swatch.alpha
+	});
+}
+
+export function toGamut(swatch, opts = {}) {
+	const spaceId = opts.space ?? "srgb";
+	const method = opts.method ?? "css4";
+	if (!isGamutBounded(spaceId)) {
+		// Not a bounded target — just convert.
+		return swatch.to(spaceId);
+	}
+	if (inGamut(swatch, spaceId)) {
+		return swatch.to(spaceId);
+	}
+	if (method === "clip") {
+		return clipInto(swatch, spaceId);
+	}
+	if (method === "css4" || method === "oklch-chroma") {
+		return toGamutCss4(swatch, spaceId);
+	}
+	throw new Error(
+		appendSuggestion(
+			`toGamut: unknown method "${method}"`,
+			method,
+			["css4", "oklch-chroma", "clip"]
+		)
+	);
+}

package/src/operations/image.js

@@ -0,0 +1,192 @@
+// High-throughput ImageData transforms for CVD simulation and daltonization.
+//
+// The color-level CVD APIs are intentionally ergonomic. This module is the hot
+// path for image processing: it works directly on RGBA byte buffers, reuses
+// precomputed transfer-function LUTs, computes the CVD matrix once per image,
+// and preserves alpha untouched.
+
+import {
+	CVD_RGB_MATRICES,
+	IDENTITY3,
+	ACHROMA_MATRIX,
+	interpolateMatrix3,
+	normalizeCVDType
+} from "../data/cvd-matrices.js";
+
+const LUT_SIZE = 65536;
+
+const SRGB8_TO_LINEAR = new Float32Array(256);
+for (let i = 0; i < 256; i++) {
+	const v = i / 255;
+	SRGB8_TO_LINEAR[i] =
+		v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+}
+
+const LINEAR_TO_SRGB8 = new Uint8ClampedArray(LUT_SIZE);
+for (let i = 0; i < LUT_SIZE; i++) {
+	const v = i / (LUT_SIZE - 1);
+	const srgb =
+		v <= 0.0031308 ? 12.92 * v : 1.055 * Math.pow(v, 1 / 2.4) - 0.055;
+	LINEAR_TO_SRGB8[i] = Math.round(srgb * 255);
+}
+
+function clamp01ToByte(v) {
+	if (v <= 0) return 0;
+	if (v >= 1) return 255;
+	return LINEAR_TO_SRGB8[(v * (LUT_SIZE - 1) + 0.5) | 0];
+}
+
+function normalizeSeverity(severity) {
+	const n = Number(severity);
+	if (!Number.isFinite(n)) return 1;
+	return n < 0 ? 0 : n > 1 ? 1 : n;
+}
+
+function assertImageDataLike(imageData) {
+	if (!imageData || !imageData.data) {
+		throw new Error("imageData: expected { data, width, height }");
+	}
+	const { data, width, height } = imageData;
+	if (typeof width !== "number" || typeof height !== "number") {
+		throw new Error("imageData: width and height must be numbers");
+	}
+	if (
+		!Number.isInteger(width) ||
+		!Number.isInteger(height) ||
+		width <= 0 ||
+		height <= 0
+	) {
+		throw new Error("imageData: width and height must be positive integers");
+	}
+	if (typeof data.length !== "number" || data.length % 4 !== 0) {
+		throw new Error("imageData: data length must be a multiple of 4");
+	}
+	const expected = width * height * 4;
+	if (data.length < expected) {
+		throw new Error(
+			`imageData: data length ${data.length} is smaller than width × height × 4 (${expected})`
+		);
+	}
+}
+
+function cloneImageDataLike(imageData) {
+	const data = new Uint8ClampedArray(imageData.data);
+	const width = imageData.width;
+	const height = imageData.height;
+
+	// Preserve the browser-native ImageData shape when possible. The guarded
+	// lookup keeps this module usable in non-DOM runtimes and tests.
+	if (typeof ImageData !== "undefined") {
+		try {
+			if (imageData.colorSpace) {
+				return new ImageData(data, width, height, {
+					colorSpace: imageData.colorSpace
+				});
+			}
+		} catch (_err) {
+			// Fall through to the two-argument constructor.
+		}
+		try {
+			return new ImageData(data, width, height);
+		} catch (_err) {
+			// Fall through to a structural clone.
+		}
+	}
+
+	return { data, width, height };
+}
+
+function targetImageData(imageData, inPlace) {
+	assertImageDataLike(imageData);
+	return inPlace === false ? cloneImageDataLike(imageData) : imageData;
+}
+
+function simulationMatrix(type, severity) {
+	const normalized = normalizeCVDType(type);
+	const sev = normalizeSeverity(severity);
+	const target = normalized === "achroma"
+		? ACHROMA_MATRIX
+		: CVD_RGB_MATRICES[normalized];
+	return interpolateMatrix3(IDENTITY3, target, sev);
+}
+
+function correctionMatrix(type, severity) {
+	const normalized = normalizeCVDType(type);
+	if (normalized === "achroma") {
+		throw new Error(
+			"daltonizeImageData: achromatopsia cannot be corrected (no remaining channels)"
+		);
+	}
+	return {
+		normalized,
+		matrix: interpolateMatrix3(
+			IDENTITY3,
+			CVD_RGB_MATRICES[normalized],
+			normalizeSeverity(severity)
+		)
+	};
+}
+
+function applySimulation(data, M) {
+	const m00 = M[0][0], m01 = M[0][1], m02 = M[0][2];
+	const m10 = M[1][0], m11 = M[1][1], m12 = M[1][2];
+	const m20 = M[2][0], m21 = M[2][1], m22 = M[2][2];
+
+	for (let i = 0; i < data.length; i += 4) {
+		const r = SRGB8_TO_LINEAR[data[i]];
+		const g = SRGB8_TO_LINEAR[data[i + 1]];
+		const b = SRGB8_TO_LINEAR[data[i + 2]];
+
+		data[i] = clamp01ToByte(m00 * r + m01 * g + m02 * b);
+		data[i + 1] = clamp01ToByte(m10 * r + m11 * g + m12 * b);
+		data[i + 2] = clamp01ToByte(m20 * r + m21 * g + m22 * b);
+	}
+}
+
+function applyDaltonize(data, M, normalized) {
+	const m00 = M[0][0], m01 = M[0][1], m02 = M[0][2];
+	const m20 = M[2][0], m21 = M[2][1], m22 = M[2][2];
+
+	// Fidaner shift matrices, inlined for the two cases to keep the inner loop
+	// branch-free after this one-time setup.
+	if (normalized === "tritan") {
+		for (let i = 0; i < data.length; i += 4) {
+			const r = SRGB8_TO_LINEAR[data[i]];
+			const g = SRGB8_TO_LINEAR[data[i + 1]];
+			const b = SRGB8_TO_LINEAR[data[i + 2]];
+
+			const simB = m20 * r + m21 * g + m22 * b;
+			const errB = b - simB;
+			data[i] = clamp01ToByte(r + 0.7 * errB);
+			data[i + 1] = clamp01ToByte(g + 0.7 * errB);
+			data[i + 2] = clamp01ToByte(b);
+		}
+		return;
+	}
+
+	for (let i = 0; i < data.length; i += 4) {
+		const r = SRGB8_TO_LINEAR[data[i]];
+		const g = SRGB8_TO_LINEAR[data[i + 1]];
+		const b = SRGB8_TO_LINEAR[data[i + 2]];
+
+		const simR = m00 * r + m01 * g + m02 * b;
+		const errR = r - simR;
+		data[i] = clamp01ToByte(r);
+		data[i + 1] = clamp01ToByte(g + 0.7 * errR);
+		data[i + 2] = clamp01ToByte(b + 0.7 * errR);
+	}
+}
+
+export function simulateImageData(imageData, type, opts = {}) {
+	const out = targetImageData(imageData, opts.inPlace);
+	const M = simulationMatrix(type, opts.severity ?? 1);
+	applySimulation(out.data, M);
+	return out;
+}
+
+export function daltonizeImageData(imageData, type, opts = {}) {
+	const out = targetImageData(imageData, opts.inPlace);
+	const { matrix, normalized } = correctionMatrix(type, opts.severity ?? 1);
+	applyDaltonize(out.data, matrix, normalized);
+	return out;
+}

package/src/operations/manipulation.js

@@ -0,0 +1,100 @@
+// OKLCh-based perceptual manipulation.
+//
+// BREAKING CHANGE from v2: `lighten`/`darken`/`saturate` all operate on
+// OKLCh coordinates instead of HSL. Amounts are in the native OKLCh
+// unit (L is 0..1, C is the absolute chroma, H is degrees), NOT the
+// v2 0..100 percent scale. See MIGRATING.md.
+//
+// Rationale: HSL's "lightness" is not perceptually uniform — lightening
+// yellow and blue by 10% HSL lightness produces very different visual
+// lightness changes. OKLCh is designed to be perceptually uniform so
+// the same numeric delta produces the same perceived change.
+//
+// Each operation returns a new Swatch. By default the result is passed
+// through `toGamut('srgb')` so you still get a displayable sRGB color;
+// pass `{ gamut: false }` to keep the raw OKLCh result (useful when
+// chaining further operations).
+
+import { Swatch } from "../core/swatch-class.js";
+import { toGamut } from "./gamut.js";
+
+const DEFAULT_LIGHTEN = 0.1;
+const DEFAULT_SATURATE = 0.05;
+
+function applyOklch(swatch, mutator, opts = {}) {
+	const oklch = swatch._getCoordsIn("oklch");
+	const out = mutator(oklch.slice());
+	const result = new Swatch({
+		space: "oklch",
+		coords: out,
+		alpha: swatch.alpha
+	});
+	if (opts.gamut === false) return result;
+	return toGamut(result, { space: "srgb" });
+}
+
+export function lighten(swatch, amount = DEFAULT_LIGHTEN, opts) {
+	return applyOklch(
+		swatch,
+		(c) => {
+			c[0] = Math.min(1, Math.max(0, c[0] + amount));
+			return c;
+		},
+		opts
+	);
+}
+
+export function darken(swatch, amount = DEFAULT_LIGHTEN, opts) {
+	return lighten(swatch, -amount, opts);
+}
+
+export function saturate(swatch, amount = DEFAULT_SATURATE, opts) {
+	return applyOklch(
+		swatch,
+		(c) => {
+			c[1] = Math.max(0, c[1] + amount);
+			return c;
+		},
+		opts
+	);
+}
+
+export function desaturate(swatch, amount = DEFAULT_SATURATE, opts) {
+	return saturate(swatch, -amount, opts);
+}
+
+export function spin(swatch, degrees, opts) {
+	return applyOklch(
+		swatch,
+		(c) => {
+			c[2] = ((c[2] + degrees) % 360 + 360) % 360;
+			return c;
+		},
+		opts
+	);
+}
+
+export function greyscale(swatch, opts) {
+	return applyOklch(
+		swatch,
+		(c) => {
+			c[1] = 0;
+			return c;
+		},
+		opts
+	);
+}
+
+export function complement(swatch, opts) {
+	return spin(swatch, 180, opts);
+}
+
+export function invert(swatch) {
+	// sRGB channel inversion — unchanged from v2 semantics.
+	const { r, g, b } = swatch.srgb;
+	return new Swatch({
+		space: "srgb",
+		coords: [1 - r, 1 - g, 1 - b],
+		alpha: swatch.alpha
+	});
+}

package/src/operations/mix.js

@@ -0,0 +1,129 @@
+// Mix (lerp) and average operations.
+//
+// `mix(a, b, amount, { space })` interpolates between two colors in the
+// given color space. `amount` is 0..1 (0 = a, 1 = b). Default space is
+// `'oklab'` since linear interpolation there is perceptually meaningful.
+//
+// Polar spaces (hsl, hsv, hwb, lch, oklch, hsluv) use shortest-arc hue
+// interpolation — the hue walks the smaller of the two directions
+// around the 360° circle.
+//
+// `average(colors, { space })` is the multi-color analogue: take the
+// arithmetic mean of the coord arrays in the given space. Hue is
+// averaged as a unit-vector sum (handles wrap-around correctly).
+
+import { Swatch, swatch } from "../core/swatch-class.js";
+import { clamp } from "../util/math.js";
+
+const POLAR_SPACES = new Set([
+	"hsl",
+	"hsv",
+	"hwb",
+	"lch",
+	"lch-d50",
+	"oklch",
+	"hsluv"
+]);
+
+// Each polar space has its hue as channel 0 except for lch/oklch which
+// have L/C/H — hue is channel 2.
+const HUE_INDEX = {
+	hsl: 0,
+	hsv: 0,
+	hwb: 0,
+	hsluv: 0,
+	lch: 2,
+	"lch-d50": 2,
+	oklch: 2
+};
+
+function lerp(a, b, t) {
+	return a + (b - a) * t;
+}
+
+function lerpHueShortest(a, b, t) {
+	let dh = b - a;
+	if (dh > 180) dh -= 360;
+	else if (dh < -180) dh += 360;
+	let h = a + dh * t;
+	if (h < 0) h += 360;
+	if (h >= 360) h -= 360;
+	return h;
+}
+
+function toSwatch(input) {
+	return input instanceof Swatch ? input : swatch(input);
+}
+
+export function mix(a, b, amount = 0.5, opts = {}) {
+	const spaceId = opts.space || "oklab";
+	const t = clamp(amount, 0, 1);
+	const as = toSwatch(a);
+	const bs = toSwatch(b);
+	const ac = as._getCoordsIn(spaceId);
+	const bc = bs._getCoordsIn(spaceId);
+	const alpha = as.alpha + (bs.alpha - as.alpha) * t;
+
+	const out = [ac[0], ac[1], ac[2]];
+	if (POLAR_SPACES.has(spaceId)) {
+		const hIdx = HUE_INDEX[spaceId];
+		for (let i = 0; i < 3; i++) {
+			if (i === hIdx) out[i] = lerpHueShortest(ac[i], bc[i], t);
+			else out[i] = lerp(ac[i], bc[i], t);
+		}
+	} else {
+		out[0] = lerp(ac[0], bc[0], t);
+		out[1] = lerp(ac[1], bc[1], t);
+		out[2] = lerp(ac[2], bc[2], t);
+	}
+
+	return new Swatch({ space: spaceId, coords: out, alpha });
+}
+
+// Hue average as unit-vector sum — handles wrap-around correctly
+// (averaging 350° and 10° should give 0°, not 180°).
+function averageHue(hues) {
+	let x = 0;
+	let y = 0;
+	for (const h of hues) {
+		const rad = (h * Math.PI) / 180;
+		x += Math.cos(rad);
+		y += Math.sin(rad);
+	}
+	let result = (Math.atan2(y, x) * 180) / Math.PI;
+	if (result < 0) result += 360;
+	return result;
+}
+
+export function average(inputs, opts = {}) {
+	const spaceId = opts.space || "oklab";
+	if (!Array.isArray(inputs) || inputs.length === 0) {
+		throw new Error("average: inputs must be a non-empty array");
+	}
+	const swatches = inputs.map(toSwatch);
+	const n = swatches.length;
+	const coords = swatches.map((s) => s._getCoordsIn(spaceId));
+	const alphas = swatches.map((s) => s.alpha);
+
+	const out = [0, 0, 0];
+	if (POLAR_SPACES.has(spaceId)) {
+		const hIdx = HUE_INDEX[spaceId];
+		for (let i = 0; i < 3; i++) {
+			if (i === hIdx) {
+				out[i] = averageHue(coords.map((c) => c[i]));
+			} else {
+				let sum = 0;
+				for (const c of coords) sum += c[i];
+				out[i] = sum / n;
+			}
+		}
+	} else {
+		for (let i = 0; i < 3; i++) {
+			let sum = 0;
+			for (const c of coords) sum += c[i];
+			out[i] = sum / n;
+		}
+	}
+	const alpha = alphas.reduce((a, b) => a + b, 0) / n;
+	return new Swatch({ space: spaceId, coords: out, alpha });
+}