@luntta/swatch 3.0.0

package/src/util/suggest.js

@@ -0,0 +1,66 @@
+// Small string-suggestion helpers for developer-facing error messages.
+
+function editDistance(a, b) {
+	const left = String(a).toLowerCase();
+	const right = String(b).toLowerCase();
+	const rows = left.length + 1;
+	const cols = right.length + 1;
+	const dp = Array.from({ length: rows }, () => new Array(cols).fill(0));
+
+	for (let i = 0; i < rows; i++) dp[i][0] = i;
+	for (let j = 0; j < cols; j++) dp[0][j] = j;
+
+	for (let i = 1; i <= left.length; i++) {
+		for (let j = 1; j <= right.length; j++) {
+			const cost = left[i - 1] === right[j - 1] ? 0 : 1;
+			dp[i][j] = Math.min(
+				dp[i - 1][j] + 1,
+				dp[i][j - 1] + 1,
+				dp[i - 1][j - 1] + cost
+			);
+			if (
+				i > 1 &&
+				j > 1 &&
+				left[i - 1] === right[j - 2] &&
+				left[i - 2] === right[j - 1]
+			) {
+				dp[i][j] = Math.min(dp[i][j], dp[i - 2][j - 2] + 1);
+			}
+		}
+	}
+
+	return dp[left.length][right.length];
+}
+
+export function closestMatch(value, candidates, maxDistance) {
+	if (value == null) return null;
+	const input = String(value);
+	if (!input || !Array.isArray(candidates) || candidates.length === 0) {
+		return null;
+	}
+
+	let best = null;
+	let bestDistance = Infinity;
+	for (const candidate of candidates) {
+		const distance = editDistance(input, candidate);
+		if (distance < bestDistance) {
+			best = candidate;
+			bestDistance = distance;
+		}
+	}
+
+	const threshold =
+		maxDistance ?? Math.max(2, Math.floor(Math.max(input.length, 4) * 0.4));
+	return bestDistance <= threshold ? best : null;
+}
+
+export function quotedList(items) {
+	return items.map((item) => `"${item}"`).join(", ");
+}
+
+export function appendSuggestion(message, value, candidates) {
+	const match = closestMatch(value, candidates);
+	const suffix = [`Valid options: ${quotedList(candidates)}.`];
+	if (match) suffix.unshift(`Did you mean "${match}"?`);
+	return `${message}. ${suffix.join(" ")}`;
+}

package/types/swatch.d.ts

@@ -0,0 +1,664 @@
+// Type definitions for swatch 3.0
+// Project: https://github.com/luntta/swatch
+
+// ─── Space names ──────────────────────────────────────────────────────
+
+export type SpaceId =
+	| "srgb"
+	| "srgb-linear"
+	| "display-p3"
+	| "rec2020"
+	| "a98"
+	| "prophoto"
+	| "xyz"
+	| "xyz-d65"
+	| "xyz-d50"
+	| "lab"
+	| "lab-d50"
+	| "lch"
+	| "lch-d50"
+	| "oklab"
+	| "oklch"
+	| "hsl"
+	| "hsv"
+	| "hwb"
+	| "cmyk"
+	| "luv"
+	| "hsluv";
+
+export interface SpaceConstants {
+	readonly srgb: "srgb";
+	readonly linearSrgb: "srgb-linear";
+	readonly displayP3: "display-p3";
+	readonly rec2020: "rec2020";
+	readonly a98: "a98";
+	readonly prophoto: "prophoto";
+	readonly xyz: "xyz";
+	readonly xyzD65: "xyz-d65";
+	readonly xyzD50: "xyz-d50";
+	readonly lab: "lab";
+	readonly labD50: "lab-d50";
+	readonly lch: "lch";
+	readonly lchD50: "lch-d50";
+	readonly oklab: "oklab";
+	readonly oklch: "oklch";
+	readonly hsl: "hsl";
+	readonly hsv: "hsv";
+	readonly hwb: "hwb";
+	readonly cmyk: "cmyk";
+	readonly luv: "luv";
+	readonly hsluv: "hsluv";
+}
+
+type RgbLikeSpaceId =
+	| "rgb"
+	| "srgb"
+	| "srgb-linear"
+	| "display-p3"
+	| "rec2020"
+	| "a98"
+	| "prophoto";
+type XyzLikeSpaceId = "xyz" | "xyz-d65" | "xyz-d50";
+type LabLikeSpaceId = "lab" | "lab-d50" | "oklab";
+type LchLikeSpaceId = "lch" | "lch-d50" | "oklch";
+
+export type ChannelPath =
+	| "alpha"
+	| `${RgbLikeSpaceId}.${"r" | "g" | "b"}`
+	| `${XyzLikeSpaceId}.${"x" | "y" | "z"}`
+	| `${LabLikeSpaceId}.${"l" | "a" | "b"}`
+	| `${LchLikeSpaceId}.${"l" | "c" | "h"}`
+	| `hsl.${"h" | "s" | "l"}`
+	| `hsv.${"h" | "s" | "v"}`
+	| `hwb.${"h" | "w" | "b"}`
+	| `hsluv.${"h" | "s" | "l"}`
+	| `luv.${"l" | "u" | "v"}`
+	| `cmyk.${"c" | "m" | "y" | "k"}`;
+
+// ─── Channel object shapes (returned by the per-space getters) ─────
+
+export interface SrgbChannels {
+	r: number;
+	g: number;
+	b: number;
+}
+
+export interface XyzChannels {
+	x: number;
+	y: number;
+	z: number;
+}
+
+export interface LabChannels {
+	l: number;
+	a: number;
+	b: number;
+}
+
+export interface LchChannels {
+	l: number;
+	c: number;
+	h: number;
+}
+
+export interface HslChannels {
+	h: number;
+	s: number;
+	l: number;
+}
+
+export interface HsvChannels {
+	h: number;
+	s: number;
+	v: number;
+}
+
+export interface HwbChannels {
+	h: number;
+	w: number;
+	b: number;
+}
+
+export interface CmykChannels {
+	c: number;
+	m: number;
+	y: number;
+	k: number;
+}
+
+export interface HsluvChannels {
+	h: number;
+	s: number;
+	l: number;
+}
+
+export interface LuvChannels {
+	l: number;
+	u: number;
+	v: number;
+}
+
+// ─── Input forms ──────────────────────────────────────────────────────
+
+export interface StateInput {
+	space: SpaceId;
+	coords: [number, number, number];
+	alpha?: number;
+	a?: number;
+}
+
+export interface LegacyRgbInput {
+	/** Legacy object input in 0..255 channel units. */
+	r: number;
+	g: number;
+	b: number;
+	a?: number;
+}
+
+export interface HslInput {
+	h: number;
+	s: number;
+	l: number;
+	a?: number;
+}
+
+export interface HsvInput {
+	h: number;
+	s: number;
+	v: number;
+	a?: number;
+}
+
+export interface HwbInput {
+	h: number;
+	w: number;
+	b: number;
+	a?: number;
+}
+
+export interface LabInput {
+	l: number;
+	a: number;
+	b: number;
+	alpha?: number;
+}
+
+export interface LchInput {
+	l: number;
+	c: number;
+	h: number;
+	alpha?: number;
+}
+
+export interface CmykInput {
+	c: number;
+	m: number;
+	y: number;
+	k: number;
+	alpha?: number;
+	a?: number;
+}
+
+export type ColorInput =
+	| string
+	| Swatch
+	| StateInput
+	| LegacyRgbInput
+	| HslInput
+	| LabInput
+	| LchInput
+	| HsvInput
+	| HwbInput
+	| CmykInput;
+
+// ─── Options bags ─────────────────────────────────────────────────────
+
+export type CVDType =
+	| "protan"
+	| "protanopia"
+	| "protanomaly"
+	| "deutan"
+	| "deuteranopia"
+	| "deuteranomaly"
+	| "tritan"
+	| "tritanopia"
+	| "tritanomaly"
+	| "achroma"
+	| "achromatopsia";
+
+export interface CvdConstants {
+	readonly protan: "protan";
+	readonly protanopia: "protanopia";
+	readonly protanomaly: "protanomaly";
+	readonly deutan: "deutan";
+	readonly deuteranopia: "deuteranopia";
+	readonly deuteranomaly: "deuteranomaly";
+	readonly tritan: "tritan";
+	readonly tritanopia: "tritanopia";
+	readonly tritanomaly: "tritanomaly";
+	readonly achroma: "achroma";
+	readonly achromatopsia: "achromatopsia";
+}
+
+export type DeltaEMode = "76" | "94" | "2000" | "cmc" | "hyab" | "ok";
+
+export interface DeltaECmcOptions {
+	l?: number;
+	c?: number;
+}
+
+export type WCAGLevel = "AA" | "AAA";
+export type WCAGSize = "normal" | "large" | "ui";
+
+export interface IsReadableOptions {
+	level?: WCAGLevel;
+	size?: WCAGSize;
+}
+
+export interface EnsureContrastOptions {
+	minRatio?: number;
+	direction?: "auto" | "lighter" | "darker";
+	step?: number;
+}
+
+export interface MixOptions {
+	space?: SpaceId;
+}
+
+export interface EqualsOptions {
+	epsilon?: number;
+	/** Alias for epsilon. */
+	tolerance?: number;
+	/** Compare both colors in this space instead of the receiver's native space. */
+	space?: SpaceId;
+}
+
+export interface HexOptions {
+	/** Include alpha as #rrggbbaa. Default false. */
+	alpha?: boolean;
+	/** Map wide-gamut colors into sRGB before serializing. Default true. */
+	gamut?: boolean;
+}
+
+export interface RgbOptions {
+	/** Include `a`; default "auto" includes it only when alpha < 1. */
+	alpha?: boolean | "auto" | "always" | "never";
+	/** Map wide-gamut colors into sRGB before serializing. Default true. */
+	gamut?: boolean;
+}
+
+export interface SimulateOptions {
+	severity?: number;
+}
+
+export interface DaltonizeOptions {
+	severity?: number;
+}
+
+export interface ImageDataLike {
+	data: Uint8ClampedArray;
+	width: number;
+	height: number;
+}
+
+export interface ImageDataTransformOptions {
+	severity?: number;
+	/** Mutate and return the provided ImageData-like object. Default true. */
+	inPlace?: boolean;
+}
+
+export interface ImageApi {
+	simulate<T extends ImageDataLike>(
+		imageData: T,
+		type: CVDType,
+		opts?: ImageDataTransformOptions & { inPlace?: true }
+	): T;
+	simulate(
+		imageData: ImageDataLike,
+		type: CVDType,
+		opts: ImageDataTransformOptions & { inPlace: false }
+	): ImageDataLike;
+	daltonize<T extends ImageDataLike>(
+		imageData: T,
+		type: Exclude<CVDType, "achroma" | "achromatopsia">,
+		opts?: ImageDataTransformOptions & { inPlace?: true }
+	): T;
+	daltonize(
+		imageData: ImageDataLike,
+		type: Exclude<CVDType, "achroma" | "achromatopsia">,
+		opts: ImageDataTransformOptions & { inPlace: false }
+	): ImageDataLike;
+}
+
+export interface ManipulationOptions {
+	/** Skip sRGB gamut mapping after the op. Default true (mapping on). */
+	gamut?: boolean;
+}
+
+export interface GamutOptions {
+	space?: SpaceId;
+	method?: "clip" | "css4" | "oklch-chroma";
+}
+
+export type BlendMode =
+	| "normal"
+	| "multiply"
+	| "screen"
+	| "darken"
+	| "lighten"
+	| "overlay"
+	| "color-dodge"
+	| "color-burn"
+	| "hard-light"
+	| "soft-light"
+	| "difference"
+	| "exclusion";
+
+export type FormatName =
+	| "hex"
+	| "hex-alpha"
+	| "rgb"
+	| "rgb-legacy"
+	| "hsl"
+	| "hsl-legacy"
+	| "hwb"
+	| "lab"
+	| "lch"
+	| "oklab"
+	| "oklch"
+	| "color";
+
+export type ColorFunctionSpaceId =
+	| "srgb"
+	| "srgb-linear"
+	| "display-p3"
+	| "rec2020"
+	| "a98"
+	| "prophoto"
+	| "xyz"
+	| "xyz-d65"
+	| "xyz-d50";
+
+export interface FormatOptions {
+	format?: FormatName;
+	precision?: number;
+	space?: ColorFunctionSpaceId;
+}
+
+export interface NameResult {
+	name: string;
+	hex: string;
+	deltaE: number;
+}
+
+export interface CheckPaletteOptions {
+	cvd?: CVDType | null;
+	severity?: number;
+	minDeltaE?: number;
+	mode?: DeltaEMode;
+}
+
+export interface PalettePair {
+	i: number;
+	j: number;
+	deltaE: number;
+	safe: boolean;
+}
+
+export interface PaletteReport {
+	pairs: PalettePair[];
+	unsafe: PalettePair[];
+	minDeltaE: number;
+	safe: boolean;
+}
+
+export interface NearestDistinguishableOptions extends CheckPaletteOptions {
+	step?: number;
+}
+
+export interface MostReadableOptions extends IsReadableOptions {
+	includeFallback?: boolean;
+}
+
+export interface RandomRange {
+	hue?: number | [number, number];
+	lightness?: number | [number, number];
+	chroma?: number | [number, number];
+	saturation?: number | [number, number];
+}
+
+export interface RandomOptions extends RandomRange {
+	space?: "oklch" | "hsl";
+	seed?: number;
+}
+
+export interface CubehelixOptions {
+	start?: number;
+	rotations?: number;
+	hue?: number;
+	gamma?: number;
+	lightness?: [number, number];
+}
+
+// ─── Scale ────────────────────────────────────────────────────────────
+
+export interface Scale {
+	(t: number): Swatch;
+	colors(n: number): Swatch[];
+	colors(n: number, format: FormatName): string[];
+	domain(): [number, number];
+	domain(d: [number, number]): Scale;
+	classes(): number[] | null;
+	classes(n: number | number[] | null): Scale;
+	padding(): [number, number];
+	padding(p: number | [number, number]): Scale;
+	gamma(): number;
+	gamma(g: number): Scale;
+	mode(): SpaceId;
+	mode(space: SpaceId): Scale;
+	correctLightness(enable?: boolean): Scale;
+	cache(): boolean;
+	cache(on: boolean): Scale;
+}
+
+// ─── Swatch class ─────────────────────────────────────────────────────
+
+export interface Swatch {
+	readonly space: SpaceId;
+	readonly alpha: number;
+	readonly coords: [number, number, number];
+
+	// Per-space getters.
+	readonly srgb: SrgbChannels;
+	readonly linearSrgb: SrgbChannels;
+	readonly xyz: XyzChannels;
+	readonly lab: LabChannels;
+	readonly lch: LchChannels;
+	readonly oklab: LabChannels;
+	readonly oklch: LchChannels;
+	readonly hsl: HslChannels;
+	readonly hsv: HsvChannels;
+	readonly hwb: HwbChannels;
+	readonly cmyk: CmykChannels;
+	readonly hsluv: HsluvChannels;
+	readonly luv: LuvChannels;
+	readonly displayP3: SrgbChannels;
+	readonly rec2020: SrgbChannels;
+	readonly a98: SrgbChannels;
+	readonly prophoto: SrgbChannels;
+
+	// Core plumbing.
+	to(space: SpaceId): Swatch;
+	clone(): Swatch;
+	equals(other: ColorInput, epsilon?: number): boolean;
+	equals(other: ColorInput, opts?: EqualsOptions): boolean;
+	toJSON(): { space: SpaceId; coords: [number, number, number]; alpha: number };
+	toString(opts?: FormatOptions): string;
+	toCss(opts?: FormatOptions): string;
+	css(opts?: FormatOptions): string;
+	hex(opts?: boolean | HexOptions): string;
+	rgb(opts?: boolean | RgbOptions): LegacyRgbInput;
+
+	// Channel get/set.
+	get(path: ChannelPath): number;
+	set(path: ChannelPath, value: number): Swatch;
+
+	// Gamut.
+	/** Smallest standard RGB gamut containing this color (srgb ⊂ display-p3 ⊂ rec2020 ⊂ prophoto), or null if outside all of them. */
+	readonly gamut: SpaceId | null;
+	inGamut(space?: SpaceId, opts?: { epsilon?: number }): boolean;
+	toGamut(opts?: GamutOptions): Swatch;
+
+	// Manipulation (OKLCh-based).
+	lighten(amount?: number, opts?: ManipulationOptions): Swatch;
+	darken(amount?: number, opts?: ManipulationOptions): Swatch;
+	saturate(amount?: number, opts?: ManipulationOptions): Swatch;
+	desaturate(amount?: number, opts?: ManipulationOptions): Swatch;
+	spin(degrees: number, opts?: ManipulationOptions): Swatch;
+	greyscale(opts?: ManipulationOptions): Swatch;
+	complement(opts?: ManipulationOptions): Swatch;
+	invert(): Swatch;
+
+	// Tint/shade/tone.
+	tint(amount?: number): Swatch;
+	shade(amount?: number): Swatch;
+	tone(amount?: number): Swatch;
+
+	// Mix / blend.
+	mix(other: ColorInput, amount?: number, opts?: MixOptions): Swatch;
+	blend(other: ColorInput, mode: BlendMode): Swatch;
+
+	// ΔE / naming.
+	deltaE(other: ColorInput, mode?: DeltaEMode, opts?: DeltaECmcOptions): number;
+	name(): NameResult;
+	toName(): string;
+
+	// Temperature (inverse).
+	temperature(): number;
+
+	// Accessibility.
+	luminance(): number;
+	contrast(other: ColorInput): number;
+	isReadable(other: ColorInput, opts?: IsReadableOptions): boolean;
+	ensureContrast(other: ColorInput, opts?: EnsureContrastOptions): Swatch;
+	apcaContrast(background: ColorInput): number;
+
+	// CVD.
+	simulate(type: CVDType, opts?: SimulateOptions): Swatch;
+	daltonize(
+		type: Exclude<CVDType, "achroma" | "achromatopsia">,
+		opts?: DaltonizeOptions
+	): Swatch;
+}
+
+// ─── Factory / statics ────────────────────────────────────────────────
+
+export interface SwatchFactory {
+	(input: ColorInput): Swatch;
+
+	// Safe parsing.
+	"try"(input: unknown): Swatch | null;
+	isColor(input: unknown): input is ColorInput;
+
+	// String constants for autocomplete-friendly call sites.
+	readonly spaces: SpaceConstants;
+	readonly cvd: CvdConstants;
+
+	// Temperature.
+	temperature(kelvin: number): Swatch;
+
+	// Random.
+	random(opts?: RandomOptions): Swatch;
+
+	// Accessibility.
+	contrast(a: ColorInput, b: ColorInput): number;
+	isReadable(a: ColorInput, b: ColorInput, opts?: IsReadableOptions): boolean;
+	ensureContrast(
+		a: ColorInput,
+		b: ColorInput,
+		opts?: EnsureContrastOptions
+	): Swatch;
+	apcaContrast(text: ColorInput, background: ColorInput): number;
+
+	// CVD.
+	simulate(c: ColorInput, type: CVDType, opts?: SimulateOptions): Swatch;
+	daltonize(
+		c: ColorInput,
+		type: Exclude<CVDType, "achroma" | "achromatopsia">,
+		opts?: DaltonizeOptions
+	): Swatch;
+	simulateImageData<T extends ImageDataLike>(
+		imageData: T,
+		type: CVDType,
+		opts?: ImageDataTransformOptions & { inPlace?: true }
+	): T;
+	simulateImageData(
+		imageData: ImageDataLike,
+		type: CVDType,
+		opts: ImageDataTransformOptions & { inPlace: false }
+	): ImageDataLike;
+	daltonizeImageData<T extends ImageDataLike>(
+		imageData: T,
+		type: Exclude<CVDType, "achroma" | "achromatopsia">,
+		opts?: ImageDataTransformOptions & { inPlace?: true }
+	): T;
+	daltonizeImageData(
+		imageData: ImageDataLike,
+		type: Exclude<CVDType, "achroma" | "achromatopsia">,
+		opts: ImageDataTransformOptions & { inPlace: false }
+	): ImageDataLike;
+	readonly image: ImageApi;
+
+	// Palette helpers.
+	checkPalette(
+		palette: ColorInput[],
+		opts?: CheckPaletteOptions
+	): PaletteReport;
+	nearestDistinguishable(
+		target: ColorInput,
+		against: ColorInput,
+		opts?: NearestDistinguishableOptions
+	): Swatch;
+	mostReadable(
+		background: ColorInput,
+		candidates: ColorInput[],
+		opts?: MostReadableOptions
+	): Swatch;
+
+	// Scales.
+	scale(stops: ColorInput[] | ((t: number) => Swatch) | string): Scale;
+	bezier(colors: ColorInput[]): (t: number) => Swatch;
+	cubehelix(opts?: CubehelixOptions): (t: number) => Swatch;
+	palettes(): string[];
+}
+
+declare const swatch: SwatchFactory;
+export default swatch;
+export { swatch };
+
+// ─── Named re-exports of the factory statics ──────────────────────────
+//
+//   import { scale, contrast, spaces } from "@luntta/swatch";
+//
+// `swatch.try` stays on the factory only (`try` is a reserved word).
+export const temperature: SwatchFactory["temperature"];
+export const random: SwatchFactory["random"];
+export const contrast: SwatchFactory["contrast"];
+export const isReadable: SwatchFactory["isReadable"];
+export const ensureContrast: SwatchFactory["ensureContrast"];
+export const apcaContrast: SwatchFactory["apcaContrast"];
+export const simulate: SwatchFactory["simulate"];
+export const daltonize: SwatchFactory["daltonize"];
+export const simulateImageData: SwatchFactory["simulateImageData"];
+export const daltonizeImageData: SwatchFactory["daltonizeImageData"];
+export const image: SwatchFactory["image"];
+export const checkPalette: SwatchFactory["checkPalette"];
+export const nearestDistinguishable: SwatchFactory["nearestDistinguishable"];
+export const mostReadable: SwatchFactory["mostReadable"];
+export const scale: SwatchFactory["scale"];
+export const bezier: SwatchFactory["bezier"];
+export const cubehelix: SwatchFactory["cubehelix"];
+export const palettes: SwatchFactory["palettes"];
+export const isColor: SwatchFactory["isColor"];
+export const spaces: SwatchFactory["spaces"];
+export const cvd: SwatchFactory["cvd"];