@luntta/swatch 3.0.0

package/src/core/registry.js

@@ -0,0 +1,81 @@
+// Color space registry and conversion router.
+//
+// Spaces register themselves with `registerSpace`. Each space provides:
+//
+//   id        — string identifier (e.g. "srgb", "oklab", "display-p3")
+//   channels  — names of the 3 channels (e.g. ["r", "g", "b"])
+//   ranges    — natural ranges for each channel, used by clamping/normalization
+//   white     — D65 (default) or D50 — used to know whether a Bradford CAT
+//               needs to run on the way to/from the canonical XYZ-D65 hub
+//   toXYZ     — convert this space's coords → CIE XYZ D65
+//   fromXYZ   — convert CIE XYZ D65 → this space's coords
+//   shortcuts — optional direct converters keyed by destination space id, used
+//               to bypass the XYZ hub for accuracy/speed (e.g. linear sRGB ↔
+//               OKLab is a single matrix multiply that loses precision if you
+//               round-trip via XYZ).
+//
+// Conversion lookup: A → B is attempted in this order:
+//   1. A === B → identity
+//   2. A.shortcuts[B] if defined
+//   3. B.fromXYZ(A.toXYZ(coords))
+
+import { appendSuggestion } from "../util/suggest.js";
+
+const spaces = new Map();
+
+export function registerSpace(space) {
+	if (!space || typeof space.id !== "string") {
+		throw new Error("registerSpace: missing id");
+	}
+	if (typeof space.toXYZ !== "function" || typeof space.fromXYZ !== "function") {
+		throw new Error(`registerSpace[${space.id}]: missing toXYZ/fromXYZ`);
+	}
+	const entry = {
+		id: space.id,
+		channels: space.channels || ["c1", "c2", "c3"],
+		ranges: space.ranges || null,
+		white: space.white || "D65",
+		toXYZ: space.toXYZ,
+		fromXYZ: space.fromXYZ,
+		shortcuts: space.shortcuts || {}
+	};
+	spaces.set(space.id, entry);
+	return entry;
+}
+
+export function getSpace(id) {
+	const entry = spaces.get(id);
+	if (!entry) {
+		throw new Error(
+			appendSuggestion(`Unknown color space: ${id}`, id, listSpaces())
+		);
+	}
+	return entry;
+}
+
+export function hasSpace(id) {
+	return spaces.has(id);
+}
+
+export function listSpaces() {
+	return Array.from(spaces.keys());
+}
+
+// Convert coords from one space to another. Coords is a length-3 array.
+// Returns a new length-3 array (does not mutate input).
+export function convert(coords, fromId, toId) {
+	if (fromId === toId) {
+		return [coords[0], coords[1], coords[2]];
+	}
+	const from = getSpace(fromId);
+	const to = getSpace(toId);
+
+	// Direct shortcut?
+	if (from.shortcuts[toId]) {
+		return from.shortcuts[toId](coords);
+	}
+
+	// Hub route via XYZ D65.
+	const xyz = from.toXYZ(coords);
+	return to.fromXYZ(xyz);
+}

package/src/core/state.js

@@ -0,0 +1,36 @@
+// Canonical Swatch state shape.
+//
+// Every Swatch instance holds:
+//   space  — string id of the source color space (e.g. "srgb", "oklab")
+//   coords — length-3 array of numbers in the source space's natural units
+//   alpha  — number in [0, 1]
+//
+// This is the colorjs.io / culori representation: the input space is preserved
+// losslessly and conversions to other spaces are computed lazily on the
+// instance and memoized. Wide-gamut inputs (color(display-p3 1 0 0)) keep
+// their full chromaticity instead of being clamped to sRGB.
+
+export function makeState(space, coords, alpha) {
+	return {
+		space,
+		coords: [coords[0], coords[1], coords[2]],
+		alpha: alpha == null ? 1 : alpha
+	};
+}
+
+export function cloneState(state) {
+	return {
+		space: state.space,
+		coords: [state.coords[0], state.coords[1], state.coords[2]],
+		alpha: state.alpha
+	};
+}
+
+export function statesEqual(a, b, epsilon = 0) {
+	if (a.space !== b.space) return false;
+	if (Math.abs(a.alpha - b.alpha) > epsilon) return false;
+	for (let i = 0; i < 3; i++) {
+		if (Math.abs(a.coords[i] - b.coords[i]) > epsilon) return false;
+	}
+	return true;
+}

package/src/core/swatch-class.js

@@ -0,0 +1,524 @@
+// Swatch — the v3 color class.
+//
+// Each instance holds an immutable canonical `state` object
+// ({ space, coords, alpha }) and exposes lazy memoized getters for every
+// registered color space. Conversions are routed through the space registry
+// (see src/core/registry.js), which uses CIE XYZ D65 as the hub.
+//
+// For Phase 1 the public surface is minimal: the canonical state, the
+// `to(space)` converter, and the foundation-space getters (`srgb`,
+// `linearSrgb`, `xyz`). Later phases register more spaces and each one
+// automatically becomes accessible via `swatch.to('<space>')` without
+// touching this file.
+
+import { makeState, cloneState } from "./state.js";
+import { convert, getSpace, listSpaces } from "./registry.js";
+import { formatCss } from "../format/css.js";
+
+function byteFromUnit(value) {
+	return Math.round(Math.max(0, Math.min(1, value)) * 255);
+}
+
+function parseEqualsOptions(options) {
+	if (typeof options === "number") return { epsilon: options };
+	if (options == null) return { epsilon: 1e-6 };
+	return {
+		epsilon: options.epsilon ?? options.tolerance ?? 1e-6,
+		space: options.space
+	};
+}
+
+export class Swatch {
+	constructor(state) {
+		if (!state || typeof state.space !== "string") {
+			throw new Error("Swatch: state must be { space, coords, alpha }");
+		}
+		// Validate the space up-front so invalid state objects fail at the
+		// boundary instead of producing a Swatch that explodes later during
+		// conversion or serialization.
+		getSpace(state.space);
+		if (!Array.isArray(state.coords) || state.coords.length !== 3) {
+			throw new Error("Swatch: coords must be a length-3 array");
+		}
+		const coords = state.coords.map(Number);
+		const alpha = state.alpha == null ? 1 : Number(state.alpha);
+		if (coords.some((value) => !Number.isFinite(value))) {
+			throw new Error("Swatch: coords must be finite numbers");
+		}
+		if (!Number.isFinite(alpha)) {
+			throw new Error("Swatch: alpha must be a finite number");
+		}
+		this._state = makeState(state.space, coords, alpha);
+		this._cache = new Map();
+		// Expose foundation fields directly for ergonomics.
+		this.space = this._state.space;
+		this.alpha = this._state.alpha;
+	}
+
+	// Raw coords in the source space (no conversion).
+	get coords() {
+		return [
+			this._state.coords[0],
+			this._state.coords[1],
+			this._state.coords[2]
+		];
+	}
+
+	// Convert to another registered space. Returns a new Swatch.
+	to(spaceId) {
+		if (spaceId === this._state.space) return this;
+		const coords = this._getCoordsIn(spaceId);
+		return new Swatch({
+			space: spaceId,
+			coords,
+			alpha: this._state.alpha
+		});
+	}
+
+	// Memoized raw coords in a given space, as a length-3 array. Internal use;
+	// most callers should use the named getters below or `.to(space).coords`.
+	_getCoordsIn(spaceId) {
+		if (spaceId === this._state.space) {
+			return [
+				this._state.coords[0],
+				this._state.coords[1],
+				this._state.coords[2]
+			];
+		}
+		if (this._cache.has(spaceId)) {
+			const cached = this._cache.get(spaceId);
+			return [cached[0], cached[1], cached[2]];
+		}
+		const result = convert(this._state.coords, this._state.space, spaceId);
+		this._cache.set(spaceId, result);
+		return [result[0], result[1], result[2]];
+	}
+
+	// Return a plain object {c1, c2, c3} keyed by the space's channel names.
+	_asObjectIn(spaceId) {
+		const coords = this._getCoordsIn(spaceId);
+		const space = getSpace(spaceId);
+		const [k1, k2, k3] = space.channels;
+		return { [k1]: coords[0], [k2]: coords[1], [k3]: coords[2] };
+	}
+
+	// Clone (independent copy). The cache is not copied, which is fine because
+	// lookups are deterministic.
+	clone() {
+		return new Swatch(cloneState(this._state));
+	}
+
+	// Structural equality with tolerance. Compares the same-space view of
+	// the other swatch against this swatch's native coords. Different source
+	// spaces will round-trip through conversion so visually-equivalent
+	// colors compare equal.
+	equals(other, options = 1e-6) {
+		let rhs;
+		try {
+			rhs = other instanceof Swatch ? other : swatch(other);
+		} catch (_err) {
+			return false;
+		}
+		const { epsilon, space } = parseEqualsOptions(options);
+		const spaceId = space || this._state.space;
+		const lhsCoords = space ? this._getCoordsIn(spaceId) : this._state.coords;
+		const rhsCoords = rhs._getCoordsIn(spaceId);
+		if (Math.abs(rhsCoords[0] - lhsCoords[0]) > epsilon) return false;
+		if (Math.abs(rhsCoords[1] - lhsCoords[1]) > epsilon) return false;
+		if (Math.abs(rhsCoords[2] - lhsCoords[2]) > epsilon) return false;
+		if (Math.abs(rhs.alpha - this._state.alpha) > epsilon) return false;
+		return true;
+	}
+
+	toJSON() {
+		return {
+			space: this._state.space,
+			coords: this.coords,
+			alpha: this._state.alpha
+		};
+	}
+
+	// ─── Foundation-space getters ──────────────────────────────────────
+	//
+	// These return plain objects in the natural channel layout of each space.
+	// Later phases register the other spaces in the registry and add matching
+	// getters here.
+
+	get srgb() {
+		return this._asObjectIn("srgb");
+	}
+
+	get linearSrgb() {
+		return this._asObjectIn("srgb-linear");
+	}
+
+	get xyz() {
+		return this._asObjectIn("xyz");
+	}
+
+	get lab() {
+		return this._asObjectIn("lab");
+	}
+
+	get lch() {
+		return this._asObjectIn("lch");
+	}
+
+	get oklab() {
+		return this._asObjectIn("oklab");
+	}
+
+	get oklch() {
+		return this._asObjectIn("oklch");
+	}
+
+	get hsl() {
+		return this._asObjectIn("hsl");
+	}
+
+	get displayP3() {
+		return this._asObjectIn("display-p3");
+	}
+
+	get rec2020() {
+		return this._asObjectIn("rec2020");
+	}
+
+	get a98() {
+		return this._asObjectIn("a98");
+	}
+
+	get prophoto() {
+		return this._asObjectIn("prophoto");
+	}
+
+	get hsv() {
+		return this._asObjectIn("hsv");
+	}
+
+	get hwb() {
+		return this._asObjectIn("hwb");
+	}
+
+	get cmyk() {
+		// CMYK is special: we derive K from max(R,G,B) for presentation.
+		const { r, g, b } = this.srgb;
+		const k = 1 - Math.max(r, g, b);
+		if (k >= 1 - 1e-12) return { c: 0, m: 0, y: 0, k: 1 };
+		const c = (1 - r - k) / (1 - k);
+		const m = (1 - g - k) / (1 - k);
+		const y = (1 - b - k) / (1 - k);
+		return { c, m, y, k };
+	}
+
+	get hsluv() {
+		return this._asObjectIn("hsluv");
+	}
+
+	get luv() {
+		return this._asObjectIn("luv");
+	}
+
+	// ─── CSS serialization ─────────────────────────────────────────────
+
+	toString(opts) {
+		return formatCss(this, opts);
+	}
+
+	toCss(opts) {
+		return formatCss(this, opts);
+	}
+
+	css(opts) {
+		return formatCss(this, opts);
+	}
+
+	// ─── Debug representation ──────────────────────────────────────────
+	//
+	// Without these, `console.log(swatch("#f00"))` dumps `_state`, `_cache`,
+	// and the bound internals. Surface the canonical color instead. The
+	// `nodejs.util.inspect.custom` symbol is registered cross-realm, so this
+	// is a no-op in browsers (which simply ignore the unknown symbol key).
+
+	get [Symbol.toStringTag]() {
+		return "Swatch";
+	}
+
+	[Symbol.for("nodejs.util.inspect.custom")]() {
+		return `Swatch <${this.css()}>`;
+	}
+
+	// sRGB view for the lossy display helpers (`hex`, `rgb`). Wide-gamut
+	// sources are perceptually mapped into sRGB (CSS Color 4 chroma
+	// reduction) by default so `.hex()` / `.rgb()` never silently clip
+	// chromaticity. Pass `gamut: false` to fall back to a raw clamp.
+	_displaySrgb(gamutMap = true) {
+		if (!gamutMap || this.inGamut("srgb")) return this;
+		return this.toGamut({ space: "srgb", method: "css4" });
+	}
+
+	hex(opts = {}) {
+		const includeAlpha =
+			typeof opts === "boolean" ? opts : opts?.alpha === true;
+		const gamutMap = typeof opts === "boolean" ? true : opts?.gamut !== false;
+		return formatCss(this._displaySrgb(gamutMap), {
+			format: includeAlpha ? "hex-alpha" : "hex"
+		});
+	}
+
+	rgb(opts = {}) {
+		const alphaMode =
+			typeof opts === "boolean" ? opts : opts?.alpha ?? "auto";
+		const gamutMap = typeof opts === "boolean" ? true : opts?.gamut !== false;
+		const { r, g, b } = this._displaySrgb(gamutMap).srgb;
+		const out = {
+			r: byteFromUnit(r),
+			g: byteFromUnit(g),
+			b: byteFromUnit(b)
+		};
+		if (
+			alphaMode === true ||
+			alphaMode === "always" ||
+			(alphaMode === "auto" && this.alpha < 1)
+		) {
+			out.a = this.alpha;
+		}
+		return out;
+	}
+
+	// ─── Channel get/set ───────────────────────────────────────────────
+	//
+	// Late-bound to avoid circulars with src/operations/channels.js.
+
+	get(path) {
+		return _getChannel(this, path);
+	}
+
+	set(path, value) {
+		return _setChannel(this, path, value);
+	}
+
+	// ─── Gamut ─────────────────────────────────────────────────────────
+
+	// The smallest standard RGB gamut that contains this color, walking the
+	// nested ladder srgb ⊂ display-p3 ⊂ rec2020 ⊂ prophoto. Returns null for
+	// imaginary colors that fall outside even ProPhoto. Useful for noticing
+	// out-of-sRGB colors before a `.hex()` / `.rgb()` round-trip maps them in.
+	get gamut() {
+		const ladder = ["srgb", "display-p3", "rec2020", "prophoto"];
+		for (const id of ladder) {
+			if (this.inGamut(id)) return id;
+		}
+		return null;
+	}
+
+	inGamut(spaceId, opts) {
+		return _inGamut(this, spaceId, opts);
+	}
+
+	toGamut(opts) {
+		return _toGamut(this, opts);
+	}
+
+	// ─── Manipulation (OKLCh-based, late-bound) ────────────────────────
+
+	lighten(amount, opts) {
+		return _manip.lighten(this, amount, opts);
+	}
+
+	darken(amount, opts) {
+		return _manip.darken(this, amount, opts);
+	}
+
+	saturate(amount, opts) {
+		return _manip.saturate(this, amount, opts);
+	}
+
+	desaturate(amount, opts) {
+		return _manip.desaturate(this, amount, opts);
+	}
+
+	spin(degrees, opts) {
+		return _manip.spin(this, degrees, opts);
+	}
+
+	greyscale(opts) {
+		return _manip.greyscale(this, opts);
+	}
+
+	complement(opts) {
+		return _manip.complement(this, opts);
+	}
+
+	invert() {
+		return _manip.invert(this);
+	}
+
+	tint(amount) {
+		return _tintShade.tint(this, amount);
+	}
+
+	shade(amount) {
+		return _tintShade.shade(this, amount);
+	}
+
+	tone(amount) {
+		return _tintShade.tone(this, amount);
+	}
+
+	mix(other, amount, opts) {
+		return _mix.mix(this, other, amount, opts);
+	}
+
+	blend(other, mode) {
+		return _mix.blend(this, other, mode);
+	}
+
+	// ─── ΔE ────────────────────────────────────────────────────────────
+
+	deltaE(other, mode, opts) {
+		return _deltaE.deltaE(this, other, mode, opts);
+	}
+
+	// ─── Naming ────────────────────────────────────────────────────────
+
+	name(opts) {
+		return _naming.name(this, opts);
+	}
+
+	toName() {
+		return _naming.toName(this);
+	}
+
+	// ─── Temperature ───────────────────────────────────────────────────
+
+	temperature() {
+		return _temperature.kelvin(this);
+	}
+
+	// ─── Accessibility ─────────────────────────────────────────────────
+
+	luminance() {
+		return _accessibility.luminance(this);
+	}
+
+	contrast(other) {
+		return _accessibility.contrast(this, other);
+	}
+
+	isReadable(other, opts) {
+		return _accessibility.isReadable(this, other, opts);
+	}
+
+	ensureContrast(other, opts) {
+		return _accessibility.ensureContrast(this, other, opts);
+	}
+
+	apcaContrast(other) {
+		// Receiver is the text; `other` is the background.
+		return _apca.apcaContrast(this, other);
+	}
+
+	// ─── CVD ───────────────────────────────────────────────────────────
+
+	simulate(type, opts) {
+		return _cvd.simulate(this, type, opts);
+	}
+
+	daltonize(type, opts) {
+		return _cvd.daltonize(this, type, opts);
+	}
+}
+
+let _getChannel = null;
+let _setChannel = null;
+export function _bindChannels(getFn, setFn) {
+	_getChannel = getFn;
+	_setChannel = setFn;
+}
+
+let _inGamut = null;
+let _toGamut = null;
+export function _bindGamut(inFn, toFn) {
+	_inGamut = inFn;
+	_toGamut = toFn;
+}
+
+let _manip = {};
+export function _bindManipulation(fns) {
+	_manip = fns;
+}
+
+let _tintShade = {};
+export function _bindTintShade(fns) {
+	_tintShade = fns;
+}
+
+let _mix = {};
+export function _bindMix(fns) {
+	_mix = fns;
+}
+
+let _deltaE = {};
+export function _bindDeltaE(fns) {
+	_deltaE = fns;
+}
+
+let _naming = {};
+export function _bindNaming(fns) {
+	_naming = fns;
+}
+
+let _temperature = {};
+export function _bindTemperature(fns) {
+	_temperature = fns;
+}
+
+let _accessibility = {};
+export function _bindAccessibility(fns) {
+	_accessibility = fns;
+}
+
+let _apca = {};
+export function _bindApca(fns) {
+	_apca = fns;
+}
+
+let _cvd = {};
+export function _bindCvd(fns) {
+	_cvd = fns;
+}
+
+// Factory / invocation without `new`.
+export function swatchFromState(state) {
+	return new Swatch(state);
+}
+
+// Build a Swatch from any recognized input form (string, object literal,
+// or existing Swatch). Throws on unrecognized input. Lazily imported to
+// avoid a circular dep between Swatch and the parser dispatcher.
+let _parseInput = null;
+export function _bindParseInput(fn) {
+	_parseInput = fn;
+}
+
+export function swatch(input) {
+	if (input instanceof Swatch) return input;
+	if (!_parseInput) {
+		throw new Error(
+			"swatch(): parser not initialized. Import swatch from '@luntta/swatch' (the package entry point) rather than reaching into core/swatch-class.js directly."
+		);
+	}
+	const state = _parseInput(input);
+	if (!state) {
+		throw new Error(
+			"swatch(): could not parse input: " + JSON.stringify(input)
+		);
+	}
+	return new Swatch(state);
+}
+
+// Helper for tests: is a given id registered?
+export function knownSpaces() {
+	return listSpaces();
+}