color-map 2.2.0 → 2.3.0

package/src/color/oklab.ts

@@ -0,0 +1,19 @@
+import { multiply } from './math.js'
+import { lmsToOklab, lmsToXyz, oklabToLms, xyzToLms } from './matrices.js'
+import type { Space } from './types.js'
+
+/**
+ * The CSS `oklab` space. Components are lightness in 0 to 1, then the a and b axes, which stay within about -0.4 to 0.4 for real colors.
+ * Pass it to `createConverter` and to the narrow helpers such as `createMix` and `createToGamut`.
+ */
+export const oklab: Space = {
+	id: 'oklab',
+	toXyz: (c) => {
+		const v = multiply(oklabToLms, c[0], c[1], c[2])
+		return multiply(lmsToXyz, v[0] ** 3, v[1] ** 3, v[2] ** 3)
+	},
+	fromXyz: (xyz) => {
+		const v = multiply(xyzToLms, xyz[0], xyz[1], xyz[2])
+		return multiply(lmsToOklab, Math.cbrt(v[0]), Math.cbrt(v[1]), Math.cbrt(v[2]))
+	}
+}

package/src/color/oklch.ts

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

package/src/color/parse.ts

@@ -0,0 +1,355 @@
+import { namedColor } from './named.js'
+import type { Color, ColorSpaceId, Component } from './types.js'
+
+export const NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?/
+// Tables keyed by text a caller wrote have no prototype (`__proto__: null`), so `constructor` or `toString` is an unknown name, not Object.prototype's.
+export const UNITS: Record<string, number> = {
+	__proto__: null as never,
+	'': 1,
+	deg: 1,
+	grad: 0.9,
+	rad: 180 / Math.PI,
+	turn: 360
+}
+
+/** How one channel reads: what 100% means, and the allowed range. */
+export interface Channel {
+	/** The value of 100%. Also the factor applied to a plain number, usually 1. */
+	pct: number
+	/** A plain number is divided by this (255 for sRGB channels). */
+	div?: number
+	min?: number
+	max?: number
+	hue?: boolean
+}
+
+export function fail(input: string, what: string, token?: string): never {
+	throw new Error(`color-map: cannot parse "${input}": ${what}${token === undefined ? '' : ` "${token}"`}`)
+}
+
+export function channel(token: string, spec: Channel, input: string): Component {
+	if (token === 'none') return null
+	const m = NUMBER.exec(token)
+	if (!m) return fail(input, 'invalid value', token)
+	const n = Number(m[0])
+	const rest = token.slice(m[0].length)
+	let value: number
+	if (spec.hue) {
+		const unit = UNITS[rest]
+		if (unit === undefined) return fail(input, 'invalid angle', token)
+		return n * unit
+	}
+	if (rest === '%') value = (n * spec.pct) / 100
+	else if (rest === '') value = n / (spec.div ?? 1)
+	else return fail(input, 'invalid value', token)
+	return Math.min(spec.max ?? Number.POSITIVE_INFINITY, Math.max(spec.min ?? Number.NEGATIVE_INFINITY, value))
+}
+
+export const SRGB: Channel = { pct: 1, div: 255 }
+const PCT100: Channel = { pct: 100, min: 0 }
+export const UNIT: Channel = { pct: 1 }
+export const ALPHA: Channel = { pct: 1, min: 0, max: 1 }
+const HUE: Channel = { pct: 0, hue: true }
+
+export const FUNCTIONS: Record<string, { space: ColorSpaceId; channels: [Channel, Channel, Channel] }> = {
+	__proto__: null as never,
+	rgb: { space: 'srgb', channels: [SRGB, SRGB, SRGB] },
+	hsl: { space: 'hsl', channels: [HUE, PCT100, PCT100] },
+	hwb: { space: 'hwb', channels: [HUE, PCT100, PCT100] },
+	lab: { space: 'lab', channels: [{ pct: 100, min: 0, max: 100 }, { pct: 125 }, { pct: 125 }] },
+	lch: { space: 'lch', channels: [{ pct: 100, min: 0, max: 100 }, { pct: 150, min: 0 }, HUE] },
+	oklab: { space: 'oklab', channels: [{ pct: 1, min: 0, max: 1 }, { pct: 0.4 }, { pct: 0.4 }] },
+	oklch: { space: 'oklch', channels: [{ pct: 1, min: 0, max: 1 }, { pct: 0.4, min: 0 }, HUE] }
+}
+
+/** The spaces `color()` names, by the name it uses: their own, and `xyz` for `xyz-d65`. */
+export const COLOR_SPACES: Record<string, ColorSpaceId> = { __proto__: null as never, xyz: 'xyz-d65' }
+for (const id of [
+	'srgb',
+	'srgb-linear',
+	'display-p3',
+	'display-p3-linear',
+	'a98-rgb',
+	'prophoto-rgb',
+	'rec2020',
+	'xyz-d50',
+	'xyz-d65'
+] as const)
+	COLOR_SPACES[id] = id
+
+/** `currentcolor` and the CSS Color 4 system colors (canvas, canvastext, linktext, buttonface, ...). */
+export const VALUES_NEEDING_RESOLVE =
+	/^(?:currentcolor|(?:canvas|field|highlight|selecteditem|mark|accentcolor)(?:text)?|(?:link|visited|active|button|gray)text|button(?:face|border))$/
+
+function hex(input: string): Color {
+	const digits = input.slice(1)
+	if (!/^(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/.test(digits)) return fail(input, 'invalid hex color')
+	const full = digits.length < 5 ? [...digits].map((d) => d + d).join('') : digits
+	const byte = (i: number): number => Number.parseInt(full.slice(i * 2, i * 2 + 2), 16) / 255
+	const color: Color = { colorSpace: 'srgb', components: [byte(0), byte(1), byte(2)] }
+	if (full.length === 8) color.alpha = byte(3)
+	return color
+}
+
+const ALIASES: Record<string, string> = { __proto__: null as never, rgba: 'rgb', hsla: 'hsl' }
+
+function functional(rawName: string, body: string, input: string): Color {
+	const name = ALIASES[rawName] ?? rawName
+	const [main, alphaToken, ...extra] = body.split('/').map((s) => s.trim())
+	if (extra.length > 0) return fail(input, 'more than one "/"')
+	const legacy = main.includes(',')
+	const tokens = (legacy ? main.split(',') : main.split(/\s+/)).map((s) => s.trim()).filter(Boolean)
+	let alpha = alphaToken
+	if (legacy) {
+		if (name !== 'rgb' && name !== 'hsl') return fail(input, 'the comma syntax is only for rgb() and hsl()')
+		if (alpha !== undefined) return fail(input, 'cannot mix "," and "/"')
+		if (tokens.length === 4) alpha = tokens.pop() as string
+		if (tokens.includes('none')) return fail(input, '"none" is not allowed in the comma syntax')
+	}
+	let space: ColorSpaceId
+	let channels: [Channel, Channel, Channel]
+	if (name === 'color') {
+		const id = COLOR_SPACES[tokens.shift() ?? '']
+		if (!id) return fail(input, 'unknown color space', main.split(/\s+/)[0])
+		space = id
+		channels = [UNIT, UNIT, UNIT]
+	} else {
+		const fn = FUNCTIONS[name]
+		if (!fn) return fail(input, 'unknown function', rawName)
+		;({ space, channels } = fn)
+	}
+	if (tokens.length !== 3) return fail(input, `expected 3 components, got ${tokens.length}`)
+	if (legacy) {
+		const percents = tokens.map((t) => t.endsWith('%'))
+		const ok = space === 'hsl' ? !percents[0] && percents[1] && percents[2] : percents.every((p) => p === percents[0])
+		if (!ok) return fail(input, 'mixed numbers and percentages', tokens.join(', '))
+	}
+	const color: Color = {
+		colorSpace: space,
+		components: tokens.map((t, i) => channel(t, channels[i], input))
+	}
+	if (alpha !== undefined) color.alpha = channel(alpha, ALPHA, input)
+	return color
+}
+
+/**
+ * Parses a CSS Color 4 color: hex, named colors, `transparent`, `rgb()`,
+ * `hsl()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()` and `color()`.
+ * `none` becomes `null`. Values that need a context (`currentcolor`, system
+ * colors) throw, because nothing here can resolve them.
+ */
+export function parse(input: string): Color {
+	const text = input.trim().toLowerCase()
+	return scan(text) ?? parseGeneric(input, text)
+}
+
+/**
+ * The regex-based parser: every accepted form, and every error message. `parse`
+ * tries {@link scan} first, which takes only the plain valid forms and leaves
+ * the rest, including every error, to this.
+ */
+export function parseGeneric(input: string, text: string): Color {
+	if (text.startsWith('#')) return hex(text)
+	const fn = /^([a-z]+)\((.*)\)$/s.exec(text)
+	if (fn) return functional(fn[1], fn[2], input)
+	if (text === 'transparent') return { colorSpace: 'srgb', components: [0, 0, 0], alpha: 0 }
+	const named = namedColor(text)
+	if (named !== undefined) {
+		return { colorSpace: 'srgb', components: [(named >> 16) / 255, ((named >> 8) & 255) / 255, (named & 255) / 255] }
+	}
+	if (VALUES_NEEDING_RESOLVE.test(text)) return fail(input, 'needs a context to resolve', text)
+	return fail(input, 'not a color')
+}
+
+/** A color as given, or parsed with {@link parse} when it is a string. */
+export const toColor = (c: Color | string): Color => (typeof c === 'string' ? parse(c) : c)
+
+// --- The scanner: a char-code fast path for hex and the functional forms ---
+
+const isSpace = (c: number): boolean => c === 32 || c === 9 || c === 10 || c === 13 || c === 12
+const isDigit = (c: number): boolean => c >= 48 && c <= 57
+const hexValue = (c: number): number => (c >= 48 && c <= 57 ? c - 48 : c >= 97 && c <= 102 ? c - 87 : -1)
+
+// Scanner state, shared across calls: `parse` is synchronous and does not re-enter.
+let at = 0
+let percent = false
+
+function scanHex(text: string): Color | undefined {
+	const len = text.length
+	if (len !== 4 && len !== 5 && len !== 7 && len !== 9) return undefined
+	const short = len < 6
+	const count = short ? len - 1 : (len - 1) / 2
+	const bytes: number[] = []
+	for (let i = 0; i < count; i++) {
+		let value: number
+		if (short) {
+			const d = hexValue(text.charCodeAt(1 + i))
+			value = d * 17
+			if (d < 0) return undefined
+		} else {
+			const hi = hexValue(text.charCodeAt(1 + i * 2))
+			const lo = hexValue(text.charCodeAt(2 + i * 2))
+			if (hi < 0 || lo < 0) return undefined
+			value = hi * 16 + lo
+		}
+		bytes.push(value / 255)
+	}
+	const color: Color = { colorSpace: 'srgb', components: [bytes[0], bytes[1], bytes[2]] }
+	if (count === 4) color.alpha = bytes[3]
+	return color
+}
+
+/** Skips whitespace from `at` up to `end`. */
+function skip(text: string, end: number): void {
+	while (at < end && isSpace(text.charCodeAt(at))) at++
+}
+
+/** The end of the token that starts at `at`: it runs to whitespace, a comma, a slash or `end`. */
+function tokenEnd(text: string, end: number): number {
+	let j = at
+	while (j < end) {
+		const c = text.charCodeAt(j)
+		if (isSpace(c) || c === 44 || c === 47) break
+		j++
+	}
+	return j
+}
+
+/**
+ * Reads the token at `at` as {@link channel} would, or returns `undefined` when
+ * it is anything but a plain valid one. Leaves `at` after the token.
+ */
+function scanChannel(text: string, end: number, spec: Channel): Component | undefined {
+	const s = at
+	const e = tokenEnd(text, end)
+	at = e
+	if (e === s) return undefined
+	if (e - s === 4 && text.startsWith('none', s)) return null
+	let j = s
+	let c = text.charCodeAt(j)
+	if (c === 43 || c === 45) c = text.charCodeAt(++j)
+	let digits = 0
+	while (isDigit(c)) {
+		c = text.charCodeAt(++j)
+		digits++
+	}
+	if (c === 46) {
+		c = text.charCodeAt(++j)
+		while (isDigit(c)) {
+			c = text.charCodeAt(++j)
+			digits++
+		}
+	}
+	if (digits === 0) return undefined
+	if (c === 101) {
+		let k = j + 1
+		let x = text.charCodeAt(k)
+		if (x === 43 || x === 45) x = text.charCodeAt(++k)
+		if (isDigit(x)) {
+			while (isDigit(text.charCodeAt(k))) k++
+			j = k
+		}
+	}
+	const n = Number(text.slice(s, j))
+	if (spec.hue) {
+		const unit = j === e ? 1 : UNITS[text.slice(j, e)]
+		return unit === undefined ? undefined : n * unit
+	}
+	let value: number
+	if (j === e) value = n / (spec.div ?? 1)
+	else if (e - j === 1 && text.charCodeAt(j) === 37) {
+		percent = true
+		value = (n * spec.pct) / 100
+	} else return undefined
+	return Math.min(spec.max ?? Number.POSITIVE_INFINITY, Math.max(spec.min ?? Number.NEGATIVE_INFINITY, value))
+}
+
+/**
+ * Parses the plain valid forms (hex, and the comma or space forms of the
+ * functions) by char code, with no regex, split or per-token array. Anything
+ * else returns `undefined`, so that {@link parseGeneric} handles it and says
+ * why it is wrong.
+ */
+function scan(text: string): Color | undefined {
+	if (text.charCodeAt(0) === 35) return scanHex(text)
+	const end = text.length - 1
+	if (text.charCodeAt(end) !== 41) return undefined
+	let open = 0
+	while (open < end) {
+		const c = text.charCodeAt(open)
+		if (c < 97 || c > 122) break
+		open++
+	}
+	if (open === 0 || text.charCodeAt(open) !== 40) return undefined
+	const rawName = text.slice(0, open)
+	const name = ALIASES[rawName] ?? rawName
+	let space: ColorSpaceId
+	let channels: [Channel, Channel, Channel]
+	at = open + 1
+	skip(text, end)
+	if (name === 'color') {
+		const s = at
+		while (at < end && !isSpace(text.charCodeAt(at))) at++
+		const id = COLOR_SPACES[text.slice(s, at)]
+		if (!id) return undefined
+		space = id
+		channels = [UNIT, UNIT, UNIT]
+		skip(text, end)
+	} else {
+		const fn = FUNCTIONS[name]
+		if (!fn) return undefined
+		;({ space, channels } = fn)
+	}
+	percent = false
+	const c0 = scanChannel(text, end, channels[0])
+	if (c0 === undefined) return undefined
+	const p0 = percent
+	skip(text, end)
+	const comma = text.charCodeAt(at) === 44
+	if (comma && name !== 'rgb' && name !== 'hsl') return undefined
+	let alpha: Component | undefined
+	let c1: Component | undefined
+	let c2: Component | undefined
+	let p1 = false
+	let p2 = false
+	if (comma) {
+		at++
+		skip(text, end)
+		percent = false
+		c1 = scanChannel(text, end, channels[1])
+		p1 = percent
+		skip(text, end)
+		if (text.charCodeAt(at++) !== 44) return undefined
+		skip(text, end)
+		percent = false
+		c2 = scanChannel(text, end, channels[2])
+		p2 = percent
+		skip(text, end)
+		if (c0 === null || c1 === undefined || c1 === null || c2 === undefined || c2 === null) return undefined
+		const ok = space === 'hsl' ? !p0 && p1 && p2 : p0 === p1 && p1 === p2
+		if (!ok) return undefined
+		if (at < end) {
+			if (text.charCodeAt(at++) !== 44) return undefined
+			skip(text, end)
+			alpha = scanChannel(text, end, ALPHA)
+			if (alpha === undefined || alpha === null) return undefined
+			skip(text, end)
+		}
+	} else {
+		c1 = scanChannel(text, end, channels[1])
+		skip(text, end)
+		c2 = scanChannel(text, end, channels[2])
+		skip(text, end)
+		if (at < end) {
+			if (text.charCodeAt(at++) !== 47) return undefined
+			skip(text, end)
+			alpha = scanChannel(text, end, ALPHA)
+			if (alpha === undefined) return undefined
+			skip(text, end)
+		}
+	}
+	if (at !== end || c1 === undefined || c2 === undefined) return undefined
+	const color: Color = { colorSpace: space, components: [c0, c1, c2] }
+	if (alpha !== undefined) color.alpha = alpha
+	return color
+}

package/src/color/polar.ts

@@ -0,0 +1,17 @@
+import { normalizeHue } from './math.js'
+import type { Space } from './types.js'
+
+/** Wraps a rectangular Lab-like space as its polar (LCH-like) twin. */
+export function polarSpace(id: 'lch' | 'oklch', base: Space): Space {
+	return {
+		id,
+		toXyz: ([l, c, h]) => {
+			const r = (h * Math.PI) / 180
+			return base.toXyz([l, c * Math.cos(r), c * Math.sin(r)])
+		},
+		fromXyz: (xyz) => {
+			const [l, a, b] = base.fromXyz(xyz)
+			return [l, Math.hypot(a, b), normalizeHue((Math.atan2(b, a) * 180) / Math.PI)]
+		}
+	}
+}

package/src/color/prophoto-rgb.ts

@@ -0,0 +1,18 @@
+import { prophotoToXyzD50, xyzD50ToProphoto } from './matrices.js'
+import { rgbSpace } from './rgb.js'
+import { prophotoToGamma, prophotoToLinear } from './transfer.js'
+import type { Space } from './types.js'
+import { xyzD50 } from './xyz-d50.js'
+
+// ProPhoto's matrices lead to XYZ-D50, so it goes through that space on the way to the hub.
+const d50 = rgbSpace('prophoto-rgb', prophotoToLinear, prophotoToGamma, prophotoToXyzD50, xyzD50ToProphoto)
+
+/**
+ * The CSS `prophoto-rgb` space. Components are red, green and blue in 0 to 1. It is defined against a D50 white and converted through `xyzD50`.
+ * Pass it to `createConverter` and to the narrow helpers such as `createMix` and `createToGamut`.
+ */
+export const prophotoRgb: Space = {
+	id: 'prophoto-rgb',
+	toXyz: (c) => xyzD50.toXyz(d50.toXyz(c)),
+	fromXyz: (xyz) => d50.fromXyz(xyzD50.fromXyz(xyz))
+}

package/src/color/rec2020.ts

@@ -0,0 +1,11 @@
+import { rec2020ToXyz, xyzToRec2020 } from './matrices.js'
+import { rgbSpace } from './rgb.js'
+import { power } from './transfer.js'
+
+const [toLinear, toGamma] = power(2.4)
+
+/**
+ * The CSS `rec2020` space. Components are red, green and blue in 0 to 1, with a 2.4 power transfer curve.
+ * Pass it to `createConverter` and to the narrow helpers such as `createMix` and `createToGamut`.
+ */
+export const rec2020 = rgbSpace('rec2020', toLinear, toGamma, rec2020ToXyz, xyzToRec2020)

package/src/color/resolve.ts

@@ -0,0 +1,87 @@
+import { evaluate } from './calc.js'
+import { wcag2 } from './contrast.js'
+import { type ColorExpr, parseExpr } from './expr.js'
+import { mix } from './mix.js'
+import { ALPHA, channel, FUNCTIONS, fail, UNIT } from './parse.js'
+import { componentsIn } from './spaces.js'
+import type { Color, Component } from './types.js'
+
+/** What `resolve` needs from its surroundings to settle `currentcolor`, `light-dark()` and system colors. */
+export interface ResolveContext {
+	/** What `currentcolor` means. */
+	currentColor?: string | ColorExpr
+	/** Which side `light-dark()` takes. Default `light`. */
+	colorScheme?: 'light' | 'dark'
+	/** What each system color (`canvas`, `buttontext`, ...) means, by lowercase name. */
+	systemColors?: Record<string, string | ColorExpr>
+}
+
+/** The names a relative color's channel keywords have, by space, one letter each. The RGB spaces use `rgb`. */
+const KEYWORDS: Record<string, string> = {
+	__proto__: null as never,
+	hsl: 'hsl',
+	hwb: 'hwb',
+	lab: 'lab',
+	lch: 'lch',
+	oklab: 'lab',
+	oklch: 'lch',
+	'xyz-d50': 'xyz',
+	'xyz-d65': 'xyz'
+}
+const SIMPLE = /^(?:none|[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?[a-z%]*)$/
+
+const WHITE: Color = { colorSpace: 'srgb', components: [1, 1, 1] }
+const BLACK: Color = { colorSpace: 'srgb', components: [0, 0, 0] }
+
+/** WCAG 2 choice between white and black: whichever contrasts more with the color. */
+function contrastColor(color: Color): Color {
+	return wcag2(WHITE, color) >= wcag2(BLACK, color) ? WHITE : BLACK
+}
+
+function resolveRelative(node: Extract<ColorExpr, { type: 'relative' }>, context: ResolveContext): Color {
+	const origin = resolve(node.from, context)
+	const c = componentsIn(origin, node.space)
+	const scale = node.fn === 'rgb' ? 255 : 1
+	const names = KEYWORDS[node.space] ?? 'rgb'
+	const vars: Record<string, number> = { alpha: origin.alpha === undefined ? 1 : (origin.alpha ?? 0) }
+	for (let i = 0; i < 3; i++) vars[names[i]] = (c[i] ?? 0) * scale
+	const specs = node.fn === 'color' ? [UNIT, UNIT, UNIT] : FUNCTIONS[node.fn].channels
+	const value = (token: string, spec: typeof ALPHA): Component =>
+		channel(SIMPLE.test(token) ? token : String(evaluate(token, vars)), spec, token)
+	const result: Color = { colorSpace: node.space, components: node.channels.map((t, i) => value(t, specs[i])) }
+	const alpha = node.alpha === undefined ? origin.alpha : value(node.alpha, ALPHA)
+	if (alpha !== undefined) result.alpha = alpha
+	return result
+}
+
+function resolveMix(node: Extract<ColorExpr, { type: 'color-mix' }>, context: ResolveContext): Color {
+	const [first, second] = node.items
+	const p1 = first.percent ?? (second.percent === undefined ? 50 : 100 - second.percent)
+	const p2 = second.percent ?? 100 - p1
+	const sum = p1 + p2
+	if (sum <= 0) return fail('color-mix()', 'the percentages must add up to more than 0')
+	const options = node.hue === undefined ? { in: node.space } : { in: node.space, hue: node.hue }
+	const result = mix(resolve(first.color, context), resolve(second.color, context), p2 / sum, options)
+	// Percentages adding up to less than 100% make the result translucent.
+	if (sum < 100 && result.alpha !== null) result.alpha = (result.alpha ?? 1) * (sum / 100)
+	return result
+}
+
+/**
+ * Turns a color, a CSS string or a {@link ColorExpr} into a concrete {@link Color}.
+ * `currentcolor`, system colors and `light-dark()` read `context`; nothing is
+ * guessed, so a missing entry throws and names the value.
+ */
+export function resolve(input: string | ColorExpr, context: ResolveContext = {}): Color {
+	const expr = typeof input === 'string' ? parseExpr(input) : input
+	if ('colorSpace' in expr) return expr
+	if (expr.type === 'light-dark') return resolve(context.colorScheme === 'dark' ? expr.dark : expr.light, context)
+	if (expr.type === 'color-mix') return resolveMix(expr, context)
+	if (expr.type === 'relative') return resolveRelative(expr, context)
+	if (expr.type === 'contrast-color') return contrastColor(resolve(expr.color, context))
+	const name = expr.type === 'currentcolor' ? 'currentcolor' : expr.name
+	const value = expr.type === 'currentcolor' ? context.currentColor : context.systemColors?.[name]
+	if (value === undefined)
+		return fail(name, `needs ${expr.type === 'currentcolor' ? 'currentColor' : `systemColors.${name}`} to resolve`)
+	return resolve(value, { ...context, currentColor: undefined })
+}

package/src/color/rgb.ts

@@ -0,0 +1,20 @@
+import { type Matrix, multiply } from './math.js'
+import type { ColorSpaceId, Space } from './types.js'
+
+/** An RGB space: a transfer function, then a matrix to XYZ-D65. */
+export function rgbSpace(
+	id: ColorSpaceId,
+	toLinear: (n: number) => number,
+	toGamma: (n: number) => number,
+	toXyz: Matrix,
+	fromXyz: Matrix
+): Space {
+	return {
+		id,
+		toXyz: (c) => multiply(toXyz, toLinear(c[0]), toLinear(c[1]), toLinear(c[2])),
+		fromXyz: (xyz) => {
+			const v = multiply(fromXyz, xyz[0], xyz[1], xyz[2])
+			return [toGamma(v[0]), toGamma(v[1]), toGamma(v[2])]
+		}
+	}
+}

package/src/color/serialize.ts

@@ -0,0 +1,96 @@
+import { type ComponentsIn, componentsOver } from './convert.js'
+import { componentsIn } from './spaces.js'
+import { srgb } from './srgb.js'
+import type { Color, ColorSpaceId, Component, Space } from './types.js'
+
+/** Options for `toCss`. */
+export interface ToCssOptions {
+	/** Decimal places kept in every number. Default 5. */
+	precision?: number
+}
+
+const POWERS = Array.from({ length: 23 }, (_, i) => Number(`1e${i}`))
+
+/**
+ * `Number(n.toFixed(precision))`, without building the string. `toFixed` rounds
+ * the exact value of `n` half up (away from zero), and the number it then reads
+ * is `k / 10^precision` for that integer `k`, which one division gives exactly.
+ * `k` comes from `t = |n| * 10^precision`. The product is rounded, but a tie
+ * (`t` ending in .5) is a double, and rounding is monotonic, so any `t` that
+ * is not exactly a tie lies on the same side of it as the exact product: only
+ * `t` ending in .5 is left to `toFixed`. So are NaN, the infinities, products
+ * of 1e9 and up, and precisions that `POWERS` lacks.
+ */
+export function roundTo(n: number, precision: number): number {
+	const scale = POWERS[precision]
+	const t = Math.abs(n) * scale
+	const whole = Math.floor(t)
+	const rest = t - whole
+	if (t < 1e9 && rest !== 0.5) {
+		const r = (rest > 0.5 ? whole + 1 : whole) / scale
+		return n < 0 ? -r : r
+	}
+	return Number(n.toFixed(precision))
+}
+
+/** Prints a number with at most `precision` decimals, without `-0` or trailing zeros. */
+function num(n: number, precision: number): string {
+	return String(roundTo(n, precision) + 0)
+}
+
+const part = (c: Component, precision: number, scale = 1, suffix = ''): string =>
+	c === null ? 'none' : num(c * scale, precision) + suffix
+
+const RECTANGULAR = new Set<ColorSpaceId>(['hsl', 'hwb', 'lab', 'lch', 'oklab', 'oklch'])
+
+/**
+ * Serializes a color as CSS. `srgb` and `hsl` print in the comma syntax
+ * (`rgb(255, 0, 0)`, `rgba(...)`) unless a component is `none`; the other
+ * spaces print in the space syntax (`oklch(0.7 0.1 200 / 0.5)`,
+ * `color(display-p3 1 0 0)`). Out-of-gamut values are kept, not clipped.
+ */
+export function toCss(color: Color, options: ToCssOptions = {}): string {
+	const { precision = 5 } = options
+	const id = color.colorSpace
+	const [c0, c1, c2] = color.components
+	const p = (c: Component, scale?: number, suffix?: string): string => part(c, precision, scale, suffix)
+	const hasAlpha = color.alpha !== undefined && color.alpha !== 1
+	const a = hasAlpha ? p(color.alpha as Component) : undefined
+	const percent = id === 'hsl' || id === 'hwb' ? '%' : ''
+	const scale = id === 'srgb' ? 255 : 1
+	const args = [p(c0, scale), p(c1, scale, percent), p(c2, scale, percent)]
+	if ((id === 'srgb' || id === 'hsl') && color.alpha !== null && !color.components.includes(null)) {
+		const name = id === 'srgb' ? 'rgb' : 'hsl'
+		return a === undefined ? `${name}(${args.join(', ')})` : `${name}a(${args.join(', ')}, ${a})`
+	}
+	const head = id === 'srgb' ? 'rgb(' : RECTANGULAR.has(id) ? `${id}(` : `color(${id} `
+	return `${head}${args.join(' ')}${a === undefined ? '' : ` / ${a}`})`
+}
+
+const hexByte = (n: number): string =>
+	Math.min(255, Math.max(0, Math.round(n * 255)))
+		.toString(16)
+		.padStart(2, '0')
+
+/**
+ * The hex form of a color, `#rrggbb` or `#rrggbbaa` when it is not opaque.
+ * Colors outside sRGB are converted and clipped, so map them with `toGamut` first.
+ */
+export function toHex(color: Color): string {
+	return hexWith(componentsIn, color)
+}
+
+function hexWith(componentsIn: ComponentsIn, color: Color): string {
+	const [r, g, b] = componentsIn(color, 'srgb') as number[]
+	const alpha = color.alpha ?? 1
+	return `#${hexByte(r)}${hexByte(g)}${hexByte(b)}${alpha === 1 ? '' : hexByte(alpha)}`
+}
+
+/**
+ * Builds {@link toHex} over the spaces given, plus `srgb`, so a bundle contains
+ * only those. A color in a space not given throws, naming that space.
+ */
+export function createToHex(...spaces: Space[]): (color: Color) => string {
+	const over = componentsOver([srgb, ...spaces])
+	return (color) => hexWith(over, color)
+}

package/src/color/spaces.ts

@@ -0,0 +1,42 @@
+import { a98Rgb } from './a98-rgb.js'
+import { componentsOver, createConverter } from './convert.js'
+import { displayP3 } from './display-p3.js'
+import { displayP3Linear } from './display-p3-linear.js'
+import { hsl } from './hsl.js'
+import { hwb } from './hwb.js'
+import { lab } from './lab.js'
+import { lch } from './lch.js'
+import { oklab } from './oklab.js'
+import { oklch } from './oklch.js'
+import { prophotoRgb } from './prophoto-rgb.js'
+import { rec2020 } from './rec2020.js'
+import { srgb } from './srgb.js'
+import { srgbLinear } from './srgb-linear.js'
+import type { ColorSpaceId, Space } from './types.js'
+import { xyzD50 } from './xyz-d50.js'
+import { xyzD65 } from './xyz-d65.js'
+
+/** Every space. Importing this pulls them all in; import single spaces to avoid that. */
+export const spaces: Record<ColorSpaceId, Space> = {
+	srgb,
+	'srgb-linear': srgbLinear,
+	hsl,
+	hwb,
+	lab,
+	lch,
+	oklab,
+	oklch,
+	'display-p3': displayP3,
+	'display-p3-linear': displayP3Linear,
+	'a98-rgb': a98Rgb,
+	'prophoto-rgb': prophotoRgb,
+	rec2020,
+	'xyz-d50': xyzD50,
+	'xyz-d65': xyzD65
+}
+
+/** A color's components in any of the 15 spaces, as `convert` gives them, without the color object. */
+export const componentsIn = componentsOver(Object.values(spaces))
+
+/** Converts a color to any of the 15 spaces. */
+export const convert = createConverter(...Object.values(spaces))