color-map 2.2.0 → 2.3.0

package/src/color/contrast.ts

@@ -0,0 +1,277 @@
+import { type ComponentsIn, componentsOver } from './convert.js'
+import { toGamutWith } from './gamut.js'
+import { oklab } from './oklab.js'
+import { oklch } from './oklch.js'
+import { toColor } from './parse.js'
+import { componentsIn } from './spaces.js'
+import { srgb } from './srgb.js'
+import type { Color, Space } from './types.js'
+import { unknownName } from './unknown-name.js'
+import { xyzD65 } from './xyz-d65.js'
+
+/**
+ * A contrast measure: `(fg, bg) => number`, plus what a caller needs to use it
+ * without knowing the algorithm. Any plain `(fg, bg) => number` also works
+ * wherever a `ContrastFn` is taken; the extra fields are optional.
+ */
+export interface ContrastFn {
+	(fg: Color, bg: Color): number
+	/** A label for messages and output, for example `wcag2`. */
+	readonly algorithm?: string
+	/** Named targets, for example `{ AA: 4.5 }`, which `meets` accepts as a level. */
+	readonly thresholds?: Readonly<Record<string, number>>
+	/** `symmetric` when swapping fg and bg gives the same number; `signed` when the sign says which is lighter. */
+	readonly polarity?: 'symmetric' | 'signed'
+}
+
+/** The contrast algorithms built in. */
+export type ContrastAlgorithm = 'wcag2'
+
+/** Either a built-in name or a {@link ContrastFn}. */
+export type ContrastOption = ContrastAlgorithm | ContrastFn
+
+type ColorInput = Color | string
+
+/** Relative luminance (WCAG 2): the Y of the color in XYZ-D65, with white at 1. */
+function luminance(componentsIn: ComponentsIn, color: Color): number {
+	return Math.max(0, componentsIn(color, 'xyz-d65')[1] as number)
+}
+
+/** Lays a translucent color over `bg`, in `srgb`, the way a browser paints it. */
+function flatten(componentsIn: ComponentsIn, fg: Color, bg: Color): Color {
+	const alpha = fg.alpha === null ? 0 : (fg.alpha ?? 1)
+	if (alpha >= 1) return fg
+	const f = componentsIn(fg, 'srgb')
+	const b = componentsIn(bg, 'srgb')
+	return { colorSpace: 'srgb', components: f.map((x, i) => (x as number) * alpha + (b[i] as number) * (1 - alpha)) }
+}
+
+/**
+ * WCAG 2 contrast ratio, 1 to 21. A translucent `fg` is laid over `bg` first;
+ * `bg` is taken as opaque.
+ */
+export const wcag2: ContrastFn = /* @__PURE__ */ wcag2Over(componentsIn)
+
+/** WCAG 2 over the spaces `componentsIn` knows, which must include `srgb` and `xyz-d65`. */
+function wcag2Over(componentsIn: ComponentsIn): ContrastFn {
+	return Object.assign(
+		(fg: Color, bg: Color): number => {
+			const a = luminance(componentsIn, flatten(componentsIn, fg, bg)) + 0.05
+			const b = luminance(componentsIn, bg) + 0.05
+			return a > b ? a / b : b / a
+		},
+		{
+			algorithm: 'wcag2',
+			thresholds: { AA: 4.5, 'AA-large': 3, AAA: 7, 'AAA-large': 4.5, 'non-text': 3 },
+			polarity: 'symmetric'
+		} as const
+	)
+}
+
+/** The measure `algo` names: `wcag2` or a function; anything else is an unknown name. */
+export function pick(algo: ContrastOption): ContrastFn {
+	return pickFrom(wcag2, algo)
+}
+
+/** {@link pick}, with `builtin` as what `wcag2` names. */
+function pickFrom(builtin: ContrastFn, algo: ContrastOption): ContrastFn {
+	if (algo === 'wcag2') return builtin
+	if (typeof algo !== 'function') throw unknownName('contrast algorithm', algo, ['wcag2'])
+	return algo
+}
+
+/** What a narrow contrast helper works over: its spaces and its own `wcag2`. */
+interface ContrastKit {
+	componentsIn: ComponentsIn
+	wcag2: ContrastFn
+}
+
+/** A {@link ContrastKit} over `needed` and `spaces`. */
+function contrastKit(needed: Space[], spaces: Space[]): ContrastKit {
+	const over = componentsOver([...needed, ...spaces])
+	return { componentsIn: over, wcag2: wcag2Over(over) }
+}
+
+/**
+ * Contrast of `fg` on `bg`. Colors may be CSS strings. The default is WCAG 2;
+ * pass a {@link ContrastFn} to use another measure (see the APCA recipe).
+ */
+export function contrast(fg: ColorInput, bg: ColorInput, algo: ContrastOption = 'wcag2'): number {
+	return pick(algo)(toColor(fg), toColor(bg))
+}
+
+/**
+ * Builds {@link contrast} over the spaces given, plus `srgb` and `xyz-d65`,
+ * which WCAG 2 works in, so a bundle contains only those. It takes color
+ * objects, not strings, so it does not carry `parse`. A color in a space not
+ * given throws, naming that space.
+ */
+export function createContrast(...spaces: Space[]): (fg: Color, bg: Color, algo?: ContrastOption) => number {
+	const kit = contrastKit([srgb, xyzD65], spaces)
+	return (fg, bg, algo = 'wcag2') => pickFrom(kit.wcag2, algo)(fg, bg)
+}
+
+/**
+ * True when `fg` on `bg` reaches `level`: a number, or a name from the
+ * algorithm's thresholds (WCAG 2: `AA`, `AA-large`, `AAA`, `AAA-large`,
+ * `non-text`). A signed measure such as APCA is compared by magnitude.
+ */
+export function meets(fg: ColorInput, bg: ColorInput, level: number | string, algo: ContrastOption = 'wcag2'): boolean {
+	const fn = pick(algo)
+	const target = levelOf(fn, level)
+	return Math.abs(fn(toColor(fg), toColor(bg))) >= target
+}
+
+/**
+ * Builds {@link meets} over the spaces given, plus `srgb` and `xyz-d65`, which
+ * WCAG 2 works in, so a bundle contains only those. It takes color objects,
+ * not strings, so it does not carry `parse`. A color in a space not given
+ * throws, naming that space.
+ */
+export function createMeets(
+	...spaces: Space[]
+): (fg: Color, bg: Color, level: number | string, algo?: ContrastOption) => boolean {
+	const kit = contrastKit([srgb, xyzD65], spaces)
+	return (fg, bg, level, algo = 'wcag2') => {
+		const fn = pickFrom(kit.wcag2, algo)
+		return Math.abs(fn(fg, bg)) >= levelOf(fn, level)
+	}
+}
+
+/** The contrast `level` stands for under `fn`: the number itself, or one of its thresholds by name. */
+function levelOf(fn: ContrastFn, level: number | string): number {
+	const named = typeof level === 'number' ? level : fn.thresholds?.[level]
+	// A name that is not the algorithm's own (`constructor`) finds something that is not a number.
+	const target = typeof named === 'number' ? named : undefined
+	if (target === undefined) throw unknownName('contrast level', level, Object.keys(fn.thresholds ?? {}))
+	return target
+}
+
+/** Options for `findContrast` and the function `createFindContrast` returns. */
+export interface FindContrastOptions {
+	/** Hue of the result, in OKLCH degrees. Default: the hue of `bg`. */
+	hue?: number
+	/** Chroma of the result, in OKLCH. Default 0. The result is mapped into the gamut. */
+	chroma?: number
+	/** Which way to look first from `bg`. Default: darker on a light `bg`, lighter on a dark one. */
+	direction?: 'lighter' | 'darker'
+	/** Default `wcag2`. */
+	contrast?: ContrastOption
+}
+
+/** What `findContrast` returns: the color it found and whether it reached the target. */
+export interface FoundContrast {
+	/** The color, in `srgb` and inside the gamut. */
+	color: Color
+	/** The contrast it achieves against `bg`, as the algorithm reports it. */
+	contrast: number
+	/** False when no lightness reaches `target`; `color` is then the best one found. */
+	met: boolean
+}
+
+const STEPS = 32
+
+/**
+ * Finds the color closest in lightness to `bg` (OKLCH L, at the given hue and
+ * chroma) that reaches `target` contrast against it, by binary search. It looks
+ * the preferred way first, then the other. The returned `contrast` is measured
+ * on the final, gamut-mapped color, and `met` says whether it reaches `target`.
+ */
+export function findContrast(bg: ColorInput, target: number, options: FindContrastOptions = {}): FoundContrast {
+	return findContrastWith({ componentsIn, wcag2 }, toColor(bg), target, options)
+}
+
+/**
+ * Builds {@link findContrast} over the spaces given, plus `srgb`, `xyz-d65`,
+ * `oklch` and `oklab`, which WCAG 2 and gamut mapping work in, so a bundle
+ * contains only those. It takes a color object, not a string, so it does not
+ * carry `parse`. A color in a space not given throws, naming that space.
+ */
+export function createFindContrast(
+	...spaces: Space[]
+): (bg: Color, target: number, options?: FindContrastOptions) => FoundContrast {
+	const kit = contrastKit([srgb, xyzD65, oklch, oklab], spaces)
+	return (bg, target, options = {}) => findContrastWith(kit, bg, target, options)
+}
+
+function findContrastWith(
+	{ componentsIn, wcag2 }: ContrastKit,
+	back: Color,
+	target: number,
+	options: FindContrastOptions
+): FoundContrast {
+	const fn = pickFrom(wcag2, options.contrast ?? 'wcag2')
+	const lch = componentsIn(back, 'oklch')
+	const l0 = lch[0] as number
+	const hue = options.hue ?? (lch[2] as number)
+	const chroma = options.chroma ?? 0
+	const at = (l: number): FoundContrast => {
+		const color = toGamutWith(componentsIn, { colorSpace: 'oklch', components: [l, chroma, hue] }, {})
+		const value = fn(color, back)
+		return { color, contrast: value, met: Math.abs(value) >= target }
+	}
+	const first = options.direction ?? (l0 > 0.5 ? 'darker' : 'lighter')
+	let best: FoundContrast | undefined
+	for (const side of [first, first === 'darker' ? 'lighter' : 'darker']) {
+		const far = side === 'darker' ? 0 : 1
+		const end = at(far)
+		if (!end.met) {
+			if (!best || Math.abs(end.contrast) > Math.abs(best.contrast)) best = end
+			continue
+		}
+		// `lo` is on the bg side and fails or is the bg itself; `hi` always passes.
+		let [lo, hi] = [l0, far]
+		let found = end
+		for (let i = 0; i < STEPS; i++) {
+			const mid = (lo + hi) / 2
+			const candidate = at(mid)
+			if (candidate.met) {
+				hi = mid
+				found = candidate
+			} else lo = mid
+		}
+		return found
+	}
+	return { ...(best as FoundContrast), met: false }
+}
+
+/** Options for `onColor` and the function `createOnColor` returns. */
+export interface OnColorOptions {
+	/** The contrast the text needs. Default 4.5 for WCAG 2. */
+	target?: number
+	/** How much of the background's hue the dark text carries, as OKLCH chroma. Default 0.03. */
+	chroma?: number
+	/** Default `wcag2`. */
+	contrast?: ContrastOption
+}
+
+/**
+ * The text color for `bg`, by the Radix rule: white, unless white's contrast
+ * on `bg` is under `target`, then a near-black tinted with the hue of `bg`
+ * (OKLCH lightness 0.2). When neither reaches `target`, whichever contrasts more.
+ */
+export function onColor(bg: ColorInput, options: OnColorOptions = {}): Color {
+	return onColorWith({ componentsIn, wcag2 }, toColor(bg), options)
+}
+
+/**
+ * Builds {@link onColor} over the spaces given, plus `srgb`, `xyz-d65`,
+ * `oklch` and `oklab`, which WCAG 2 and gamut mapping work in, so a bundle
+ * contains only those. It takes a color object, not a string, so it does not
+ * carry `parse`. A color in a space not given throws, naming that space.
+ */
+export function createOnColor(...spaces: Space[]): (bg: Color, options?: OnColorOptions) => Color {
+	const kit = contrastKit([srgb, xyzD65, oklch, oklab], spaces)
+	return (bg, options = {}) => onColorWith(kit, bg, options)
+}
+
+function onColorWith({ componentsIn, wcag2 }: ContrastKit, back: Color, options: OnColorOptions): Color {
+	const fn = pickFrom(wcag2, options.contrast ?? 'wcag2')
+	const target = options.target ?? 4.5
+	const white: Color = { colorSpace: 'srgb', components: [1, 1, 1] }
+	const whiteScore = Math.abs(fn(white, back))
+	if (whiteScore >= target) return white
+	const hue = componentsIn(back, 'oklch')[2] as number
+	const dark = toGamutWith(componentsIn, { colorSpace: 'oklch', components: [0.2, options.chroma ?? 0.03, hue] }, {})
+	return Math.abs(fn(dark, back)) >= whiteScore ? dark : white
+}

package/src/color/convert.ts

@@ -0,0 +1,43 @@
+import type { Color, ColorSpaceId, Component, Space, Vec3 } from './types.js'
+import { unknownName } from './unknown-name.js'
+
+/** Converts bare components between two spaces, through the XYZ-D65 hub. */
+export function convertComponents(from: Space, to: Space, c: Vec3): Vec3 {
+	return from === to ? c : to.fromXyz(from.toXyz(c))
+}
+
+/** The components of a color in another space: a copy in the same space, else `none` becomes 0. */
+export type ComponentsIn = (color: Color, to: ColorSpaceId) => Component[]
+
+/** {@link ComponentsIn} over the spaces given. */
+export function componentsOver(spaces: Space[]): ComponentsIn {
+	const byId = new Map(spaces.map((s) => [s.id, s]))
+	const find = (id: ColorSpaceId): Space => {
+		const space = byId.get(id)
+		if (!space) throw unknownName('color space', id, [...byId.keys()])
+		return space
+	}
+	return (color, to) => {
+		if (color.colorSpace === to) return [...color.components]
+		const from = find(color.colorSpace)
+		const c = color.components
+		// Different ids, so different spaces: straight through the hub, `none` as 0.
+		return find(to).fromXyz(from.toXyz([c[0] ?? 0, c[1] ?? 0, c[2] ?? 0]))
+	}
+}
+
+/** `convert` over the spaces `componentsIn` knows: the color in `to`, keeping its alpha. */
+export function convertWith(componentsIn: ComponentsIn, color: Color, to: ColorSpaceId): Color {
+	const result: Color = { colorSpace: to, components: componentsIn(color, to) }
+	if (color.alpha !== undefined) result.alpha = color.alpha
+	return result
+}
+
+/**
+ * Builds `convert` over just the spaces given, so a bundle contains only those.
+ * `none` components become 0 when the space changes.
+ */
+export function createConverter(...spaces: Space[]): (color: Color, to: ColorSpaceId) => Color {
+	const componentsIn = componentsOver(spaces)
+	return (color, to) => convertWith(componentsIn, color, to)
+}

package/src/color/display-p3-linear.ts

@@ -0,0 +1,9 @@
+import { p3ToXyz, xyzToP3 } from './matrices.js'
+import { rgbSpace } from './rgb.js'
+import { identity } from './transfer.js'
+
+/**
+ * The CSS `display-p3-linear` space: Display P3 primaries without a transfer curve. Components are red, green and blue in 0 to 1.
+ * Pass it to `createConverter` and to the narrow helpers such as `createMix` and `createToGamut`.
+ */
+export const displayP3Linear = rgbSpace('display-p3-linear', identity, identity, p3ToXyz, xyzToP3)

package/src/color/display-p3.ts

@@ -0,0 +1,9 @@
+import { p3ToXyz, xyzToP3 } from './matrices.js'
+import { rgbSpace } from './rgb.js'
+import { srgbToGamma, srgbToLinear } from './transfer.js'
+
+/**
+ * The CSS `display-p3` space. Components are red, green and blue in 0 to 1, with the sRGB transfer curve.
+ * Pass it to `createConverter` and to the narrow helpers such as `createMix` and `createToGamut`.
+ */
+export const displayP3 = rgbSpace('display-p3', srgbToLinear, srgbToGamma, p3ToXyz, xyzToP3)

package/src/color/expr.ts

@@ -0,0 +1,158 @@
+import type { HueMethod } from './mix.js'
+import { COLOR_SPACES, FUNCTIONS, fail, parse, VALUES_NEEDING_RESOLVE } from './parse.js'
+import type { Color, ColorSpaceId } from './types.js'
+
+/** A color that needs a context to become concrete: see {@link resolve}. */
+export type ColorExpr =
+	| Color
+	| { type: 'currentcolor' }
+	| { type: 'system'; name: string }
+	| { type: 'light-dark'; light: ColorExpr; dark: ColorExpr }
+	| { type: 'contrast-color'; color: ColorExpr }
+	| {
+			type: 'color-mix'
+			space: ColorSpaceId
+			hue?: HueMethod
+			/** Exactly two. `percent` is 0 to 100, absent when not written. */
+			items: { color: ColorExpr; percent?: number }[]
+	  }
+	| {
+			/** `rgb(from red r g b)` and the like. The channels are kept as written, for `resolve` to evaluate. */
+			type: 'relative'
+			/** The function name: `rgb`, `hsl`, `hwb`, `lab`, `lch`, `oklab`, `oklch` or `color`. */
+			fn: string
+			space: ColorSpaceId
+			from: ColorExpr
+			channels: [string, string, string]
+			alpha?: string
+	  }
+
+const INTERPOLATION_SPACES: Record<string, ColorSpaceId> = {
+	__proto__: null as never,
+	...COLOR_SPACES,
+	hsl: 'hsl',
+	hwb: 'hwb',
+	lab: 'lab',
+	lch: 'lch',
+	oklab: 'oklab',
+	oklch: 'oklch'
+}
+const HUE_METHODS = new Set(['shorter', 'longer', 'increasing', 'decreasing'])
+const RELATIVE = new Set(['rgb', 'rgba', 'hsl', 'hsla', 'hwb', 'lab', 'lch', 'oklab', 'oklch', 'color'])
+const PERCENT = /^[+-]?(?:\d+\.?\d*|\.\d+)%$/
+
+/** Splits at top-level commas, or at top-level whitespace with `/` as its own item. */
+function split(text: string, commas: boolean, input: string): string[] {
+	const out: string[] = []
+	let depth = 0
+	let current = ''
+	const flush = (): void => {
+		if (commas || current) out.push(current.trim())
+		current = ''
+	}
+	for (const ch of text) {
+		if (ch === '(') depth++
+		else if (ch === ')') depth--
+		if (depth === 0 && (commas ? ch === ',' : /\s|\//.test(ch))) {
+			flush()
+			if (ch === '/') out.push('/')
+		} else current += ch
+	}
+	if (depth !== 0) return fail(input, 'unbalanced parentheses')
+	flush()
+	return out
+}
+
+/** Splits `name(body)`, or returns undefined when the text is not one call that ends the text. */
+function call(text: string): [string, string] | undefined {
+	const open = text.indexOf('(')
+	if (open < 1 || !text.endsWith(')') || !/^[a-z-]+$/.test(text.slice(0, open))) return undefined
+	let depth = 0
+	for (let i = open; i < text.length; i++) {
+		if (text[i] === '(') depth++
+		else if (text[i] === ')' && --depth === 0 && i < text.length - 1) return undefined
+	}
+	return [text.slice(0, open), text.slice(open + 1, -1)]
+}
+
+function colorMix(body: string, input: string): ColorExpr {
+	const [head, ...rest] = split(body, true, input)
+	const words = head.split(/\s+/)
+	if (words[0] !== 'in' || !INTERPOLATION_SPACES[words[1]])
+		return fail(input, 'color-mix() needs "in <space>"', words[1])
+	const space = INTERPOLATION_SPACES[words[1]]
+	let hue: HueMethod | undefined
+	if (words.length > 2) {
+		if (words.length !== 4 || words[3] !== 'hue' || !HUE_METHODS.has(words[2])) {
+			return fail(input, 'invalid hue interpolation', words.slice(2).join(' '))
+		}
+		hue = words[2] as HueMethod
+	}
+	if (rest.length !== 2) return fail(input, `color-mix() needs two colors, got ${rest.length}`)
+	const items = rest.map((text) => {
+		const parts = split(text, false, input)
+		const percents = parts.filter((p) => PERCENT.test(p))
+		if (parts.length - percents.length !== 1 || percents.length > 1)
+			return fail(input, 'invalid color-mix() item', text)
+		const percent = percents.length === 1 ? Number.parseFloat(percents[0]) : undefined
+		if (percent !== undefined && percent < 0) return fail(input, 'negative percentage', text)
+		const color = parseExpr(parts.find((p) => !PERCENT.test(p)) as string)
+		return percent === undefined ? { color } : { color, percent }
+	})
+	return hue === undefined ? { type: 'color-mix', space, items } : { type: 'color-mix', space, hue, items }
+}
+
+function relative(name: string, words: string[], input: string): ColorExpr {
+	const from = words[1] === undefined ? fail(input, 'missing origin color') : parseExpr(words[1])
+	let space: ColorSpaceId
+	let at = 2
+	const fn = name === 'rgba' ? 'rgb' : name === 'hsla' ? 'hsl' : name
+	if (fn === 'color') {
+		const id = COLOR_SPACES[words[2]]
+		if (!id) return fail(input, 'unknown color space', words[2])
+		space = id
+		at = 3
+	} else space = FUNCTIONS[fn].space
+	const channels = words.slice(at, at + 3)
+	const tail = words.slice(at + 3)
+	if (channels.length !== 3) return fail(input, `expected 3 components, got ${channels.length}`)
+	if (tail.length > 0 && (tail[0] !== '/' || tail.length !== 2))
+		return fail(input, 'expected "/ alpha" after the components')
+	const node: Extract<ColorExpr, { type: 'relative' }> = {
+		type: 'relative',
+		fn,
+		space,
+		from,
+		channels: channels as [string, string, string]
+	}
+	if (tail.length === 2) node.alpha = tail[1]
+	return node
+}
+
+/**
+ * Parses any CSS Color 4 or 5 color into a {@link ColorExpr}: everything
+ * `parse` takes, plus `currentcolor`, system colors, `light-dark()`,
+ * `color-mix()`, `contrast-color()` and relative colors such as
+ * `oklch(from #3b82f6 calc(l + 0.1) c h)`. A concrete color comes back as a
+ * plain {@link Color}; the rest are nodes that {@link resolve} turns into one.
+ */
+export function parseExpr(input: string): ColorExpr {
+	const text = input.trim().toLowerCase()
+	if (text === 'currentcolor') return { type: 'currentcolor' }
+	if (VALUES_NEEDING_RESOLVE.test(text)) return { type: 'system', name: text }
+	const parts = call(text)
+	if (!parts) return parse(text)
+	const [name, body] = parts
+	if (name === 'color-mix') return colorMix(body, input)
+	if (name === 'light-dark') {
+		const list = split(body, true, input)
+		if (list.length !== 2) return fail(input, `light-dark() needs two colors, got ${list.length}`)
+		return { type: 'light-dark', light: parseExpr(list[0]), dark: parseExpr(list[1]) }
+	}
+	if (name === 'contrast-color') return { type: 'contrast-color', color: parseExpr(body) }
+	if (RELATIVE.has(name)) {
+		const words = split(body, false, input)
+		if (words[0] === 'from') return relative(name, words, input)
+	}
+	return parse(text)
+}