color-map 2.2.0 → 2.3.0

package/src/color/gamut.ts

@@ -0,0 +1,215 @@
+import { deltaEOkWith } from './compare.js'
+import { type ComponentsIn, componentsOver, convertWith } from './convert.js'
+import { type Matrix, product } from './math.js'
+import { lmsToOklab, lmsToXyz, oklabToLms, srgbToXyz, xyzToLms, xyzToSrgb } from './matrices.js'
+import { oklab } from './oklab.js'
+import { oklch } from './oklch.js'
+import { componentsIn } from './spaces.js'
+import { srgb } from './srgb.js'
+import { srgbToGamma } from './transfer.js'
+import type { Color, ColorSpaceId, Component, Space, Vec3 } from './types.js'
+
+/** The bounded RGB spaces a color can be tested or mapped against. */
+export type GamutId =
+	| 'srgb'
+	| 'srgb-linear'
+	| 'display-p3'
+	| 'display-p3-linear'
+	| 'a98-rgb'
+	| 'prophoto-rgb'
+	| 'rec2020'
+
+const within = (components: Component[], epsilon: number): boolean =>
+	components.every((c) => (c as number) >= -epsilon && (c as number) <= 1 + epsilon)
+
+/** True when every channel of `color`, seen in `gamut`, is within 0 to 1 (± `epsilon`). */
+export function inGamut(color: Color, gamut: GamutId = 'srgb', epsilon = 1e-6): boolean {
+	return within(componentsIn(color, gamut), epsilon)
+}
+
+/**
+ * Builds {@link inGamut} over the spaces given, plus `srgb`, so a bundle
+ * contains only those. Give the gamut too when it is not `srgb`. A color or
+ * gamut in a space not given throws, naming that space.
+ */
+export function createInGamut(...spaces: Space[]): (color: Color, gamut?: GamutId, epsilon?: number) => boolean {
+	const over = componentsOver([srgb, ...spaces])
+	return (color, gamut = 'srgb', epsilon = 1e-6) => within(over(color, gamut), epsilon)
+}
+
+/** Options for `toGamut` and the function `createToGamut` returns. */
+export interface ToGamutOptions {
+	/** The gamut to fit into. Default `srgb`. */
+	gamut?: GamutId
+	/** `css` is the CSS Color 4 OKLCH chroma reduction. `clip` clamps each channel. Default `css`. */
+	method?: 'css' | 'clip'
+}
+
+/** `color` with `components`, which are in `gamut`, clamped to 0 to 1: what `convert` then a clamp gives. */
+function clipped(color: Color, gamut: GamutId, components: Component[]): Color {
+	return withAlpha(
+		{ colorSpace: gamut, components: components.map((c) => Math.min(1, Math.max(0, c as number))) },
+		color
+	)
+}
+
+/**
+ * Maps a color into a gamut and returns it in its original space. `css` follows
+ * CSS Color 4 section 13.2: reduce OKLCH chroma until the clipped color is
+ * within a just-noticeable ΔEOK of 0.02.
+ */
+export function toGamut(color: Color, options: ToGamutOptions = {}): Color {
+	return toGamutWith(componentsIn, color, options)
+}
+
+/**
+ * Builds {@link toGamut} over the spaces given, plus `srgb`, `oklch` and
+ * `oklab`, which the CSS method works in. Give the gamut too when it is not
+ * `srgb`. A color or gamut in a space not given throws, naming that space.
+ */
+export function createToGamut(...spaces: Space[]): (color: Color, options?: ToGamutOptions) => Color {
+	const over = componentsOver([srgb, oklch, oklab, ...spaces])
+	return (color, options = {}) => toGamutWith(over, color, options)
+}
+
+/** {@link toGamut} over the spaces `componentsIn` knows, which must include `oklch` and `oklab`. */
+export function toGamutWith(componentsIn: ComponentsIn, color: Color, options: ToGamutOptions): Color {
+	const { gamut = 'srgb', method = 'css' } = options
+	const deltaEOk = (a: Color, b: Color): number => deltaEOkWith(componentsIn, a, b)
+	const back = (c: Color): Color => convertWith(componentsIn, c, color.colorSpace as ColorSpaceId)
+	// Each candidate is converted to the gamut once, then tested and clipped from that.
+	const fit = componentsIn(color, gamut)
+	if (within(fit, 1e-6)) return color
+	if (method === 'clip') return back(clipped(color, gamut, fit))
+
+	const origin = convertWith(componentsIn, color, 'oklch')
+	const [lightness, chroma, hue] = origin.components as [number, number, Component]
+	if (lightness >= 1) return back(withAlpha({ colorSpace: gamut, components: [1, 1, 1] }, color))
+	if (lightness <= 0) return back(withAlpha({ colorSpace: gamut, components: [0, 0, 0] }, color))
+
+	const JND = 0.02
+	const EPSILON = 0.0001
+	if (gamut === 'srgb') return back(reduceChromaInSrgb(origin, lightness, chroma, hue))
+	let min = 0
+	let max = chroma
+	let minInGamut = true
+	let clip = clipped(origin, gamut, componentsIn(origin, gamut))
+	if (deltaEOk(clip, origin) < JND) return back(clip)
+	while (max - min > EPSILON) {
+		const mid = (min + max) / 2
+		const current = withAlpha({ colorSpace: 'oklch', components: [lightness, mid, hue] }, origin)
+		const inGamutSpace = componentsIn(current, gamut)
+		if (minInGamut && within(inGamutSpace, 1e-6)) {
+			min = mid
+			continue
+		}
+		clip = clipped(current, gamut, inGamutSpace)
+		const e = deltaEOk(clip, current)
+		if (e < JND) {
+			if (JND - e < EPSILON) return back(clip)
+			minInGamut = false
+			min = mid
+		} else {
+			max = mid
+		}
+	}
+	// The search ended by narrowing to EPSILON rather than by an early return. A
+	// sweep of 88,000 colors never gets here, but the algorithm allows it.
+	/* v8 ignore next */
+	return back(clip)
+}
+
+function withAlpha(c: Color, source: Color): Color {
+	if (source.alpha !== undefined) c.alpha = source.alpha
+	return c
+}
+
+let lmsToLinear: Matrix | undefined
+let linearToLms: Matrix | undefined
+// The gamma-space tolerance of 1e-6 on each side, as a linear one: the transfer curve is monotone.
+const LOW = -1e-6 / 12.92
+const HIGH = ((1 + 1e-6 + 0.055) / 1.055) ** 2.4
+
+// A clipped channel of exactly 0 or 1 stays exactly that, as clipping after the curve gives.
+const encode = (n: number): number => (n === 0 || n === 1 ? n : srgbToGamma(n))
+const clamp01 = (n: number): number => Math.min(1, Math.max(0, n))
+
+/**
+ * The CSS Color 4 section 13.2 search of `toGamut` for the `srgb` gamut, done in
+ * linear sRGB so the loop has no hub conversion, `**` or trigonometry. Clipping
+ * to 0 to 1 commutes with the monotone transfer curve, so it finds what the
+ * generic path finds, up to rounding. Returns the mapped color in `srgb`.
+ */
+function reduceChromaInSrgb(origin: Color, lightness: number, chroma: number, hue: Component): Color {
+	// Composed on first use, so a bundle without this path does not pay for them at load.
+	const m = (lmsToLinear ??= product(xyzToSrgb, lmsToXyz))
+	const n = (linearToLms ??= product(xyzToLms, srgbToXyz))
+	const o = oklabToLms
+	const k = lmsToOklab
+	// A `none` hue or chroma reads as 0, as it does in a conversion. A `none` lightness never gets here.
+	const l = lightness
+	const radians = ((hue ?? 0) * Math.PI) / 180
+	const cos = Math.cos(radians)
+	const sin = Math.sin(radians)
+	let r = 0
+	let g = 0
+	let b = 0
+	let inside = false
+	/** Puts the candidate of chroma `c` in linear sRGB into r, g, b (unclipped), and says if it is within the gamut. */
+	const place = (c: number): void => {
+		const a = c * cos
+		const bb = c * sin
+		const x = l + o[1] * a + o[2] * bb
+		const y = l + o[4] * a + o[5] * bb
+		const z = l + o[7] * a + o[8] * bb
+		const x3 = x * x * x
+		const y3 = y * y * y
+		const z3 = z * z * z
+		r = m[0] * x3 + m[1] * y3 + m[2] * z3
+		g = m[3] * x3 + m[4] * y3 + m[5] * z3
+		b = m[6] * x3 + m[7] * y3 + m[8] * z3
+		inside = r >= LOW && r <= HIGH && g >= LOW && g <= HIGH && b >= LOW && b <= HIGH
+	}
+	/** Clips r, g, b and returns its ΔEOK to the candidate of chroma `c`. */
+	const clipAndMeasure = (c: number): number => {
+		r = clamp01(r)
+		g = clamp01(g)
+		b = clamp01(b)
+		const x = Math.cbrt(n[0] * r + n[1] * g + n[2] * b)
+		const y = Math.cbrt(n[3] * r + n[4] * g + n[5] * b)
+		const z = Math.cbrt(n[6] * r + n[7] * g + n[8] * b)
+		const dl = k[0] * x + k[1] * y + k[2] * z - l
+		const da = k[3] * x + k[4] * y + k[5] * z - c * cos
+		const db = k[6] * x + k[7] * y + k[8] * z - c * sin
+		return Math.sqrt(dl * dl + da * da + db * db)
+	}
+	const JND = 0.02
+	const EPSILON = 0.0001
+	let min = 0
+	let max = chroma
+	let minInGamut = true
+	place(chroma ?? 0)
+	let clip: Vec3
+	let e = clipAndMeasure(chroma ?? 0)
+	clip = [r, g, b]
+	if (e >= JND) {
+		while (max - min > EPSILON) {
+			const mid = (min + max) / 2
+			place(mid)
+			if (minInGamut && inside) {
+				min = mid
+				continue
+			}
+			e = clipAndMeasure(mid)
+			clip = [r, g, b]
+			if (e < JND) {
+				if (JND - e < EPSILON) break
+				minInGamut = false
+				min = mid
+			} else {
+				max = mid
+			}
+		}
+	}
+	return withAlpha({ colorSpace: 'srgb', components: clip.map(encode) }, origin)
+}

package/src/color/hsl.ts

@@ -0,0 +1,57 @@
+import { normalizeHue } from './math.js'
+import { srgb } from './srgb.js'
+import type { Space, Vec3 } from './types.js'
+
+function channel(t1: number, t2: number, sextant: number): number {
+	const h = (sextant + 6) % 6
+	if (h < 1) return (t2 - t1) * h + t1
+	if (h < 3) return t2
+	if (h < 4) return (t2 - t1) * (4 - h) + t1
+	return t1
+}
+
+/** CSS Color 4 hslToRgb. Hue in degrees, s and l in 0 to 1. */
+export function hslToSrgb(h: number, s: number, l: number): Vec3 {
+	const t2 = l <= 0.5 ? l * (s + 1) : l + s - l * s
+	const t1 = l * 2 - t2
+	const hue = normalizeHue(h) / 60
+	return [channel(t1, t2, hue + 2), channel(t1, t2, hue), channel(t1, t2, hue - 2)]
+}
+
+/**
+ * CSS Color 4 rgbToHsl. Returns hue in degrees, s and l in 0 to 1. For
+ * out-of-gamut input the saturation can come out negative; it is made positive
+ * and the hue turned by 180 degrees, unless `flipNegative` is false.
+ */
+export function srgbToHsl([r, g, b]: Vec3, flipNegative = true): Vec3 {
+	const max = Math.max(r, g, b)
+	const min = Math.min(r, g, b)
+	const l = (min + max) / 2
+	const d = max - min
+	let h = 0
+	let s = 0
+	// A spread of rounding noise is a gray: a round trip leaves white at 1 - 1e-16.
+	if (d > 1e-9) {
+		s = l === 0 || l === 1 ? 0 : (max - l) / Math.min(l, 1 - l)
+		h = max === r ? (g - b) / d + (g < b ? 6 : 0) : max === g ? (b - r) / d + 2 : (r - g) / d + 4
+		h *= 60
+	}
+	if (s < 0) {
+		if (flipNegative) h += 180
+		s = -s
+	}
+	return [normalizeHue(h), s, l]
+}
+
+/**
+ * The CSS `hsl` space. Components are hue in degrees, then saturation and lightness in 0 to 100.
+ * Pass it to `createConverter` and to the narrow helpers such as `createMix` and `createToGamut`.
+ */
+export const hsl: Space = {
+	id: 'hsl',
+	toXyz: ([h, s, l]) => srgb.toXyz(hslToSrgb(h, s / 100, l / 100)),
+	fromXyz: (xyz) => {
+		const [h, s, l] = srgbToHsl(srgb.fromXyz(xyz))
+		return [h, s * 100, l * 100]
+	}
+}

package/src/color/hwb.ts

@@ -0,0 +1,26 @@
+import { hslToSrgb, srgbToHsl } from './hsl.js'
+import { srgb } from './srgb.js'
+import type { Space } from './types.js'
+
+/**
+ * The CSS `hwb` space. Components are hue in degrees, then whiteness and blackness in 0 to 100.
+ * Pass it to `createConverter` and to the narrow helpers such as `createMix` and `createToGamut`.
+ */
+export const hwb: Space = {
+	id: 'hwb',
+	toXyz: ([h, w, b]) => {
+		const white = w / 100
+		const black = b / 100
+		if (white + black >= 1) {
+			const gray = white / (white + black)
+			return srgb.toXyz([gray, gray, gray])
+		}
+		const k = 1 - white - black
+		const [red, green, blue] = hslToSrgb(h, 1, 0.5)
+		return srgb.toXyz([red * k + white, green * k + white, blue * k + white])
+	},
+	fromXyz: (xyz) => {
+		const rgb = srgb.fromXyz(xyz)
+		return [srgbToHsl(rgb, false)[0], Math.min(...rgb) * 100, (1 - Math.max(...rgb)) * 100]
+	}
+}

package/src/color/index.ts

@@ -0,0 +1,43 @@
+export { a98Rgb } from './a98-rgb.js'
+export { fromArgb, toArgb } from './argb.js'
+export { createDeltaEOk, createEquals, deltaEOk, equals } from './compare.js'
+export {
+	type ContrastAlgorithm,
+	type ContrastFn,
+	type ContrastOption,
+	contrast,
+	createContrast,
+	createFindContrast,
+	createMeets,
+	createOnColor,
+	type FindContrastOptions,
+	type FoundContrast,
+	findContrast,
+	meets,
+	type OnColorOptions,
+	onColor,
+	wcag2
+} from './contrast.js'
+export { convertComponents, createConverter } from './convert.js'
+export { displayP3 } from './display-p3.js'
+export { displayP3Linear } from './display-p3-linear.js'
+export { type ColorExpr, parseExpr } from './expr.js'
+export { createInGamut, createToGamut, type GamutId, inGamut, type ToGamutOptions, toGamut } from './gamut.js'
+export { hsl } from './hsl.js'
+export { hwb } from './hwb.js'
+export { lab } from './lab.js'
+export { lch } from './lch.js'
+export { createMix, type HueMethod, type MixOptions, mix } from './mix.js'
+export { oklab } from './oklab.js'
+export { oklch } from './oklch.js'
+export { parse } from './parse.js'
+export { prophotoRgb } from './prophoto-rgb.js'
+export { rec2020 } from './rec2020.js'
+export { type ResolveContext, resolve } from './resolve.js'
+export { createToHex, type ToCssOptions, toCss, toHex } from './serialize.js'
+export { convert, spaces } from './spaces.js'
+export { srgb } from './srgb.js'
+export { srgbLinear } from './srgb-linear.js'
+export type { Color, ColorSpaceId, Component, Space, Vec3 } from './types.js'
+export { xyzD50 } from './xyz-d50.js'
+export { xyzD65 } from './xyz-d65.js'

package/src/color/lab.ts

@@ -0,0 +1,29 @@
+import { D50, multiply } from './math.js'
+import { d50ToD65, d65ToD50 } from './matrices.js'
+import type { Space } from './types.js'
+
+const EPSILON = 216 / 24389
+const KAPPA = 24389 / 27
+
+const finv = (f: number): number => (f ** 3 > EPSILON ? f ** 3 : (116 * f - 16) / KAPPA)
+const forward = (v: number): number => (v > EPSILON ? Math.cbrt(v) : (KAPPA * v + 16) / 116)
+
+/**
+ * The CSS `lab` space (CIE Lab, D50 white). Components are lightness in 0 to 100, then the a and b axes, which are not bounded but stay near -125 to 125 for real colors.
+ * Pass it to `createConverter` and to the narrow helpers such as `createMix` and `createToGamut`.
+ */
+export const lab: Space = {
+	id: 'lab',
+	toXyz: ([l, a, b]) => {
+		const fy = (l + 16) / 116
+		const y = l > KAPPA * EPSILON ? fy ** 3 : l / KAPPA
+		const x = finv(fy + a / 500)
+		const z = finv(fy - b / 200)
+		return multiply(d50ToD65, x * D50[0], y * D50[1], z * D50[2])
+	},
+	fromXyz: (xyz) => {
+		const [x, y, z] = multiply(d65ToD50, xyz[0], xyz[1], xyz[2])
+		const fy = forward(y / D50[1])
+		return [116 * fy - 16, 500 * (forward(x / D50[0]) - fy), 200 * (fy - forward(z / D50[2]))]
+	}
+}

package/src/color/lch.ts

@@ -0,0 +1,8 @@
+import { lab } from './lab.js'
+import { polarSpace } from './polar.js'
+
+/**
+ * The CSS `lch` space, the polar form of `lab`. Components are lightness in 0 to 100, chroma (not bounded, about 0 to 150) and hue in degrees.
+ * Pass it to `createConverter` and to the narrow helpers such as `createMix` and `createToGamut`.
+ */
+export const lch = polarSpace('lch', lab)

package/src/color/math.ts

@@ -0,0 +1,30 @@
+import type { Vec3 } from './types.js'
+
+/** A 3x3 matrix, flat, row by row. */
+export type Matrix = readonly [number, number, number, number, number, number, number, number, number]
+
+/** `m` times the column vector (x, y, z). Takes numbers rather than a Vec3, so callers need no array. */
+export function multiply(m: Matrix, x: number, y: number, z: number): Vec3 {
+	return [m[0] * x + m[1] * y + m[2] * z, m[3] * x + m[4] * y + m[5] * z, m[6] * x + m[7] * y + m[8] * z]
+}
+
+/** Keeps the sign, so out-of-gamut values survive the transfer function. */
+export function signed(f: (abs: number) => number): (n: number) => number {
+	return (n) => (n < 0 ? -f(-n) : f(n))
+}
+
+export function normalizeHue(h: number): number {
+	return ((h % 360) + 360) % 360
+}
+
+export const D50: Vec3 = [0.3457 / 0.3585, 1, (1 - 0.3457 - 0.3585) / 0.3585]
+
+/** The product of 3x3 matrices, left to right: `product(a, b)` applies `b` first. */
+export function product(...ms: Matrix[]): Matrix {
+	return ms.reduce((a, b) => {
+		const out: number[] = []
+		for (let i = 0; i < 3; i++)
+			for (let j = 0; j < 3; j++) out.push(a[i * 3] * b[j] + a[i * 3 + 1] * b[3 + j] + a[i * 3 + 2] * b[6 + j])
+		return out as unknown as Matrix
+	})
+}

package/src/color/matrices.ts

@@ -0,0 +1,91 @@
+// biome-ignore-all format: each matrix is written as its three rows
+// CSS Color 4, section 19 (sample code for color conversions). Each matrix is
+// flat, row by row.
+import type { Matrix } from './math.js'
+
+export const srgbToXyz: Matrix = [
+	506752 / 1228815, 87881 / 245763, 12673 / 70218,
+	87098 / 409605, 175762 / 245763, 12673 / 175545,
+	7918 / 409605, 87881 / 737289, 1001167 / 1053270
+]
+export const xyzToSrgb: Matrix = [
+	12831 / 3959, -329 / 214, -1974 / 3959,
+	-851781 / 878810, 1648619 / 878810, 36519 / 878810,
+	705 / 12673, -2585 / 12673, 705 / 667
+]
+
+export const p3ToXyz: Matrix = [
+	608311 / 1250200, 189793 / 714400, 198249 / 1000160,
+	35783 / 156275, 247089 / 357200, 198249 / 2500400,
+	0, 32229 / 714400, 5220557 / 5000800
+]
+export const xyzToP3: Matrix = [
+	446124 / 178915, -333277 / 357830, -72051 / 178915,
+	-14852 / 17905, 63121 / 35810, 423 / 17905,
+	11844 / 330415, -50337 / 660830, 316169 / 330415
+]
+
+export const a98ToXyz: Matrix = [
+	573536 / 994567, 263643 / 1420810, 187206 / 994567,
+	591459 / 1989134, 6239551 / 9945670, 374412 / 4972835,
+	53769 / 1989134, 351524 / 4972835, 4929758 / 4972835
+]
+export const xyzToA98: Matrix = [
+	1829569 / 896150, -506331 / 896150, -308931 / 896150,
+	-851781 / 878810, 1648619 / 878810, 36519 / 878810,
+	16779 / 1248040, -147721 / 1248040, 1266979 / 1248040
+]
+
+export const prophotoToXyzD50: Matrix = [
+	0.7977666449006423, 0.13518129740053308, 0.0313477341283922,
+	0.2880748288194013, 0.711835234241873, 0.00008993693872564,
+	0, 0, 0.8251046025104602
+]
+export const xyzD50ToProphoto: Matrix = [
+	1.3457868816471583, -0.25557208737979464, -0.05110186497554526,
+	-0.5446307051249019, 1.5082477428451468, 0.02052744743642139,
+	0, 0, 1.2119675456389452
+]
+
+export const rec2020ToXyz: Matrix = [
+	63426534 / 99577255, 20160776 / 139408157, 47086771 / 278816314,
+	26158966 / 99577255, 472592308 / 697040785, 8267143 / 139408157,
+	0, 19567812 / 697040785, 295819943 / 278816314
+]
+export const xyzToRec2020: Matrix = [
+	30757411 / 17917100, -6372589 / 17917100, -4539589 / 17917100,
+	-19765991 / 29648200, 47925759 / 29648200, 467509 / 29648200,
+	792561 / 44930125, -1921689 / 44930125, 42328811 / 44930125
+]
+
+export const d65ToD50: Matrix = [
+	1.0479297925449969, 0.022946870601609652, -0.05019226628920524,
+	0.02962780877005599, 0.9904344267538799, -0.017073799063418826,
+	-0.009243040646204504, 0.015055191490298152, 0.7518742814281371
+]
+export const d50ToD65: Matrix = [
+	0.955473421488075, -0.02309845494876471, 0.06325924320057072,
+	-0.0283697093338637, 1.0099953980813041, 0.021041441191917323,
+	0.012314014864481998, -0.020507649298898964, 1.330365926242124
+]
+
+export const xyzToLms: Matrix = [
+	0.819022437996703, 0.3619062600528904, -0.1288737815209879,
+	0.0329836539323885, 0.9292868615863434, 0.0361446663506424,
+	0.0481771893596242, 0.2642395317527308, 0.6335478284694309
+]
+export const lmsToOklab: Matrix = [
+	0.210454268309314, 0.7936177747023054, -0.0040720430116193,
+	1.9779985324311684, -2.42859224204858, 0.450593709617411,
+	0.0259040424655478, 0.7827717124575296, -0.8086757549230774
+]
+export const lmsToXyz: Matrix = [
+	1.2268798758459243, -0.5578149944602171, 0.2813910456659647,
+	-0.0405757452148008, 1.112286803280317, -0.0717110580655164,
+	-0.0763729366746601, -0.4214933324022432, 1.5869240198367816
+]
+export const oklabToLms: Matrix = [
+	1, 0.3963377773761749, 0.2158037573099136,
+	1, -0.1055613458156586, -0.0638541728258133,
+	1, -0.0894841775298119, -1.2914855480194092
+]

package/src/color/mix.ts

@@ -0,0 +1,158 @@
+import { type ComponentsIn, componentsOver, convertWith } from './convert.js'
+import { normalizeHue } from './math.js'
+import { oklab } from './oklab.js'
+import { toColor } from './parse.js'
+import { componentsIn } from './spaces.js'
+import type { Color, ColorSpaceId, Component, Space } from './types.js'
+import { unknownName } from './unknown-name.js'
+
+/** How `mix` travels around the hue circle (CSS Color 4 section 12.4). */
+export type HueMethod = 'shorter' | 'longer' | 'increasing' | 'decreasing'
+
+/** Options for `mix` and the function `createMix` returns. */
+export interface MixOptions {
+	/** The space to interpolate in. Default `oklab`, which is what `color-mix()` uses. */
+	in?: ColorSpaceId
+	/** How hues are interpolated, in the polar spaces. Default `shorter`. */
+	hue?: HueMethod
+}
+
+/** Index of the hue component, for the polar spaces. */
+const HUE_AT: Record<string, number> = { __proto__: null as never, hsl: 0, hwb: 0, lch: 2, oklch: 2 }
+
+/**
+ * Which components are "analogous" (CSS Color 4 section 4.4): a `none` in one
+ * space carries to the analogous component of another. One letter per
+ * component; the RGB spaces share `RGB` and the XYZ ones `XYZ`.
+ */
+const ANALOGOUS: Record<string, string> = {
+	__proto__: null as never,
+	hsl: 'hcl',
+	hwb: 'hwk',
+	lab: 'lab',
+	lch: 'lch',
+	oklab: 'lab',
+	oklch: 'lch',
+	'xyz-d50': 'XYZ',
+	'xyz-d65': 'XYZ'
+}
+const analogous = (id: ColorSpaceId): string => ANALOGOUS[id] ?? 'RGB'
+
+/** Converts, keeping `none` on components that have an analogous one in the source. */
+function convertKeepingNone(componentsIn: ComponentsIn, color: Color, space: ColorSpaceId): Color {
+	const out = convertWith(componentsIn, color, space)
+	// Nothing to carry when no component is `none`, the common case.
+	if (color.colorSpace !== space && color.components.includes(null)) {
+		const from = analogous(color.colorSpace)
+		const to = analogous(space)
+		out.components = out.components.map((c, i) => (color.components[from.indexOf(to[i])] === null ? null : c))
+	}
+	return out
+}
+
+/**
+ * Chroma below which a converted hue is powerless and so `none`, per polar
+ * space. Follows colorjs.io, which treats a hue as powerless when both Lab
+ * axes are under 1/100000 of their reference extent: 0.8 for Oklab (a, b in
+ * -0.4 to 0.4) gives 8e-6, 250 for Lab (-125 to 125) gives 0.0025.
+ */
+const POWERLESS: Record<string, number> = { __proto__: null as never, oklch: 8e-6, lch: 0.0025, hsl: 1e-4 }
+
+/**
+ * Converts for interpolation. A hue that conversion produced for a gray
+ * becomes `none`, so it takes the other color's hue; a hue the author wrote
+ * (the color already in `space`) stays as written.
+ */
+function prepare(componentsIn: ComponentsIn, color: Color, space: ColorSpaceId): Color {
+	const out = convertKeepingNone(componentsIn, color, space)
+	// A space with no powerless entry (and not `hwb`) has no hue to lose.
+	if (color.colorSpace === space || (space !== 'hwb' && POWERLESS[space] === undefined)) return out
+	const [, x, y] = out.components
+	const epsilon = POWERLESS[space]
+	const gray =
+		typeof x === 'number' &&
+		(space === 'hwb' ? typeof y === 'number' && x + y > 100 - 1e-4 : epsilon !== undefined && x < epsilon)
+	if (gray) out.components[HUE_AT[space] as number] = null
+	return out
+}
+
+const HUE_METHODS = ['shorter', 'longer', 'increasing', 'decreasing']
+
+/** Fixes up two hues so they interpolate by `method` (section 12.4). */
+function fixHues(h1: number, h2: number, method: HueMethod): [number, number] {
+	let a = normalizeHue(h1)
+	let b = normalizeHue(h2)
+	const d = b - a
+	if (method === 'shorter') {
+		if (d > 180) a += 360
+		else if (d < -180) b += 360
+	} else if (method === 'longer') {
+		if (d > 0 && d < 180) a += 360
+		else if (d > -180 && d <= 0) b += 360
+	} else if (method === 'increasing') {
+		if (b < a) b += 360
+	} else if (method !== 'decreasing') throw unknownName('hue method', method, HUE_METHODS)
+	else if (a < b) a += 360
+	return [a, b]
+}
+
+/**
+ * Interpolates two colors the way CSS does (Color 4 section 13): in the space
+ * `in`, with premultiplied alpha, `none` taking the other color's value, and
+ * the chosen hue method. `t` is the weight of `b`, 0 to 1 (outside it
+ * extrapolates). Strings are parsed with `parse`.
+ *
+ * A hue that conversion makes powerless (chroma under 8e-6 in `oklch`, 0.0025
+ * in `lch`, saturation under 1e-4 in `hsl`, whiteness plus blackness filling `hwb`; for example white) becomes `none`, so it takes the other color's
+ * hue. A hue you wrote in the target space stays as written.
+ */
+export function mix(a: Color | string, b: Color | string, t = 0.5, options: MixOptions = {}): Color {
+	return mixWith(componentsIn, toColor(a), toColor(b), t, options)
+}
+
+/**
+ * Builds {@link mix} over the spaces given, plus `oklab`, the default `in`, so
+ * a bundle contains only those. Give the `in` space too when it is not
+ * `oklab`. It takes color objects, not strings, so it does not carry `parse`;
+ * pass strings through `parse` first. A color in a space not given throws,
+ * naming that space.
+ */
+export function createMix(...spaces: Space[]): (a: Color, b: Color, t?: number, options?: MixOptions) => Color {
+	const over = componentsOver([oklab, ...spaces])
+	return (a, b, t = 0.5, options = {}) => mixWith(over, a, b, t, options)
+}
+
+/** {@link mix} of two colors over the spaces `componentsIn` knows. */
+function mixWith(componentsIn: ComponentsIn, a: Color, b: Color, t: number, options: MixOptions): Color {
+	const space = options.in ?? 'oklab'
+	const c1 = prepare(componentsIn, a, space)
+	const c2 = prepare(componentsIn, b, space)
+	// A `none` takes the other side's value; both `none` stays `none`.
+	const alpha1 = c1.alpha === undefined ? 1 : c1.alpha
+	const alpha2 = c2.alpha === undefined ? 1 : c2.alpha
+	const a1 = alpha1 ?? alpha2
+	const p1 = a1 ?? 1
+	const p2 = alpha2 ?? alpha1 ?? 1
+	const alpha = p1 * (1 - t) + p2 * t
+	const hueAt = HUE_AT[space]
+	const method = options.hue ?? 'shorter'
+	const components: Component[] = []
+	for (let i = 0; i < c1.components.length; i++) {
+		const x = c1.components[i] as Component
+		const y = c2.components[i] as Component
+		const u = x ?? y
+		const v = y ?? x
+		if (u === null || v === null) {
+			components.push(null)
+		} else if (i === hueAt) {
+			const [h1, h2] = fixHues(u, v, method)
+			components.push(normalizeHue(h1 * (1 - t) + h2 * t))
+		} else {
+			const premultiplied = u * p1 * (1 - t) + v * p2 * t
+			components.push(alpha === 0 ? premultiplied : premultiplied / alpha)
+		}
+	}
+	const result: Color = { colorSpace: space, components }
+	if (a1 === null || alpha !== 1) result.alpha = a1 === null ? null : alpha
+	return result
+}

package/src/color/named.ts

@@ -0,0 +1,13 @@
+// The 148 CSS named colors (CSS Color 4 section 6.1), as `name:rrggbb` pairs.
+const DATA =
+	'aliceblue:f0f8ff,antiquewhite:faebd7,aqua:00ffff,aquamarine:7fffd4,azure:f0ffff,beige:f5f5dc,bisque:ffe4c4,black:000000,blanchedalmond:ffebcd,blue:0000ff,blueviolet:8a2be2,brown:a52a2a,burlywood:deb887,cadetblue:5f9ea0,chartreuse:7fff00,chocolate:d2691e,coral:ff7f50,cornflowerblue:6495ed,cornsilk:fff8dc,crimson:dc143c,cyan:00ffff,darkblue:00008b,darkcyan:008b8b,darkgoldenrod:b8860b,darkgray:a9a9a9,darkgreen:006400,darkgrey:a9a9a9,darkkhaki:bdb76b,darkmagenta:8b008b,darkolivegreen:556b2f,darkorange:ff8c00,darkorchid:9932cc,darkred:8b0000,darksalmon:e9967a,darkseagreen:8fbc8f,darkslateblue:483d8b,darkslategray:2f4f4f,darkslategrey:2f4f4f,darkturquoise:00ced1,darkviolet:9400d3,deeppink:ff1493,deepskyblue:00bfff,dimgray:696969,dimgrey:696969,dodgerblue:1e90ff,firebrick:b22222,floralwhite:fffaf0,forestgreen:228b22,fuchsia:ff00ff,gainsboro:dcdcdc,ghostwhite:f8f8ff,gold:ffd700,goldenrod:daa520,gray:808080,green:008000,greenyellow:adff2f,grey:808080,honeydew:f0fff0,hotpink:ff69b4,indianred:cd5c5c,indigo:4b0082,ivory:fffff0,khaki:f0e68c,lavender:e6e6fa,lavenderblush:fff0f5,lawngreen:7cfc00,lemonchiffon:fffacd,lightblue:add8e6,lightcoral:f08080,lightcyan:e0ffff,lightgoldenrodyellow:fafad2,lightgray:d3d3d3,lightgreen:90ee90,lightgrey:d3d3d3,lightpink:ffb6c1,lightsalmon:ffa07a,lightseagreen:20b2aa,lightskyblue:87cefa,lightslategray:778899,lightslategrey:778899,lightsteelblue:b0c4de,lightyellow:ffffe0,lime:00ff00,limegreen:32cd32,linen:faf0e6,magenta:ff00ff,maroon:800000,mediumaquamarine:66cdaa,mediumblue:0000cd,mediumorchid:ba55d3,mediumpurple:9370db,mediumseagreen:3cb371,mediumslateblue:7b68ee,mediumspringgreen:00fa9a,mediumturquoise:48d1cc,mediumvioletred:c71585,midnightblue:191970,mintcream:f5fffa,mistyrose:ffe4e1,moccasin:ffe4b5,navajowhite:ffdead,navy:000080,oldlace:fdf5e6,olive:808000,olivedrab:6b8e23,orange:ffa500,orangered:ff4500,orchid:da70d6,palegoldenrod:eee8aa,palegreen:98fb98,paleturquoise:afeeee,palevioletred:db7093,papayawhip:ffefd5,peachpuff:ffdab9,peru:cd853f,pink:ffc0cb,plum:dda0dd,powderblue:b0e0e6,purple:800080,rebeccapurple:663399,red:ff0000,rosybrown:bc8f8f,royalblue:4169e1,saddlebrown:8b4513,salmon:fa8072,sandybrown:f4a460,seagreen:2e8b57,seashell:fff5ee,sienna:a0522d,silver:c0c0c0,skyblue:87ceeb,slateblue:6a5acd,slategray:708090,slategrey:708090,snow:fffafa,springgreen:00ff7f,steelblue:4682b4,tan:d2b48c,teal:008080,thistle:d8bfd8,tomato:ff6347,turquoise:40e0d0,violet:ee82ee,wheat:f5deb3,white:ffffff,whitesmoke:f5f5f5,yellow:ffff00,yellowgreen:9acd32'
+
+let table: Map<string, number> | undefined
+
+/** The 0xRRGGBB value of a CSS named color, or undefined. Built on first use. */
+export function namedColor(name: string): number | undefined {
+	table ??= new Map(
+		DATA.split(',').map((p) => [p.slice(0, p.indexOf(':')), Number.parseInt(p.slice(p.indexOf(':') + 1), 16)])
+	)
+	return table.get(name)
+}