color-map 2.2.0 → 2.3.0

package/src/cli/commands/palette.ts

@@ -0,0 +1,66 @@
+import { type cli, command, t } from 'clibuilder'
+import { fullOption, orEmpty, result } from 'clibuilder/axi'
+import { toCss, toHex } from '../../color/index.js'
+import { semanticPalette, validate } from '../../palette/index.js'
+import { GAMUTS, MODES, readColor, round } from '../shared.js'
+
+const definition = command({
+	name: 'palette',
+	description:
+		'A semantic palette from one brand color: primary, status colors, surface and outline, each with a text color and its WCAG 2 ratio',
+	arguments: [{ name: 'brand', description: 'The brand color', type: t.string() }],
+	options: {
+		mode: { description: 'light or dark', type: t.enum([...MODES]), default: 'light' },
+		target: {
+			description: 'The WCAG 2 ratio every text pair must reach',
+			type: t.number({ min: 1, max: 21 }),
+			default: 4.5
+		},
+		gamut: { description: 'The gamut every color must fit', type: t.enum([...GAMUTS]), default: 'srgb' },
+		full: fullOption
+	},
+	run(args) {
+		const brand = readColor(args.brand, 'brand')
+		const made = semanticPalette({ brand, mode: args.mode, target: args.target, gamut: args.gamut })
+		const checked = validate(made, { target: args.target, gamut: args.gamut })
+		const roles = Object.entries(made.roles).map(([role, p]) => ({
+			role,
+			bg: toHex(p.bg),
+			fg: toHex(p.fg),
+			ratio: round(p.ratio),
+			target: p.target,
+			pass: p.ratio >= p.target
+		}))
+		const failing = roles.filter((r) => !r.pass).length
+		const full = args.full === true
+		return result(
+			{
+				brand: args.brand,
+				mode: args.mode,
+				contrast: made.meta.contrast,
+				passing: roles.length - failing,
+				failing,
+				roles,
+				issues: orEmpty(
+					checked.issues.map((i) => ({ kind: i.kind, path: i.path, message: i.message })),
+					'none: every pair meets its target and every color fits the gamut'
+				),
+				...(full
+					? {
+							primary: made.scales.primary.map((c) => toCss(c)),
+							neutral: made.scales.neutral.map((c) => toCss(c))
+						}
+					: {})
+			},
+			{
+				help: [
+					`Run \`color-map export '${args.brand}' --source palette --mode ${args.mode} --to css\` for CSS variables`,
+					`Run \`color-map palette '${args.brand}' --mode ${args.mode === 'light' ? 'dark' : 'light'}\` for the other mode`
+				]
+			}
+		)
+	}
+})
+
+/** Typed as the plain command so its declaration does not name args-minus' internals. */
+export const palette: cli.Command = definition

package/src/cli/commands/scale.ts

@@ -0,0 +1,75 @@
+import { type cli, command, t } from 'clibuilder'
+import { CliError, exitCodes, fullOption, result } from 'clibuilder/axi'
+import { type Color, contrast, inGamut, toCss, toHex } from '../../color/index.js'
+import { createContrastScale, createScale, scaleFromBrand } from '../../scale/index.js'
+import { GAMUTS, MODES, PRESETS, readColor, round } from '../shared.js'
+
+const WHITE = '#ffffff'
+const BLACK = '#000000'
+
+function rows(colors: Color[], full: boolean) {
+	return colors.map((color, i) => ({
+		step: i + 1,
+		hex: toHex(color),
+		onWhite: round(contrast(color, WHITE)),
+		onBlack: round(contrast(color, BLACK)),
+		...(full ? { css: toCss(color), inSrgb: inGamut(color, 'srgb') } : {})
+	}))
+}
+
+const definition = command({
+	name: 'scale',
+	description: 'Build a color scale from a seed color: a preset, a Radix-style brand scale, or contrast targets',
+	arguments: [{ name: 'seed', description: 'The color the scale is built around', type: t.string() }],
+	options: {
+		preset: { description: 'The scale shape', type: t.enum([...PRESETS]), default: 'tailwind-11' },
+		steps: { description: 'Steps of an even scale; replaces --preset', type: t.int({ min: 2 }).optional() },
+		brand: { description: 'Build a 12-step UI scale where the seed is step 9 exactly', type: t.boolean().optional() },
+		mode: { description: 'light or dark, for --brand', type: t.enum([...MODES]), default: 'light' },
+		background: {
+			description: 'The background: page color for --brand, or what --targets are measured against',
+			type: t.string().optional()
+		},
+		targets: {
+			description: 'Contrast ratios, one per step, such as 3,4.5,7: builds a contrast scale',
+			type: t.array(t.number({ min: 1, max: 21 })).optional()
+		},
+		gamut: { description: 'The gamut every step must fit', type: t.enum([...GAMUTS]), default: 'srgb' },
+		full: fullOption
+	},
+	run(args) {
+		const full = args.full === true
+		const seed = readColor(args.seed, 'seed')
+		const background = args.background === undefined ? undefined : readColor(args.background, 'background')
+		if (args.targets) {
+			if (!background)
+				throw new CliError('--targets needs --background', {
+					code: 'missing-option',
+					exitCode: exitCodes.usage,
+					details: { option: 'background' },
+					help: `Run \`color-map scale '${args.seed}' --targets 3 --targets 4.5 --background '#ffffff'\``
+				})
+			const steps = createContrastScale({ seed, background, targets: args.targets })
+			const rows = steps.map((s) => ({
+				step: Number(s.name) + 1,
+				target: s.target,
+				hex: toHex(s.color),
+				ratio: round(s.contrast),
+				met: s.met,
+				...(full ? { css: toCss(s.color) } : {})
+			}))
+			return result({ kind: 'contrast', seed: args.seed, background: args.background, steps: rows })
+		}
+		const colors = args.brand
+			? scaleFromBrand(seed, { mode: args.mode, background, gamut: args.gamut })
+			: createScale({ seed, steps: args.steps ?? args.preset, gamut: args.gamut })
+		const kind = args.brand ? 'brand-12' : args.steps ? `even-${args.steps}` : args.preset
+		return result(
+			{ kind, seed: args.seed, steps: rows(colors, full) },
+			{ help: `Run \`color-map export '${args.seed}' --source scale --to tailwind\` to get it as a Tailwind v4 theme` }
+		)
+	}
+})
+
+/** Typed as the plain command so its declaration does not name args-minus' internals. */
+export const scale: cli.Command = definition

package/src/cli/index.ts

@@ -0,0 +1,2 @@
+export { commands, createApp } from './cli.js'
+export { type SchemaSource, schemaOf } from './schemas.js'

package/src/cli/schema-command.ts

@@ -0,0 +1,31 @@
+import { type cli, command, t } from 'clibuilder'
+import { CliError, document, exitCodes, result } from 'clibuilder/axi'
+import { type SchemaSource, schemaOf } from './schemas.js'
+
+/** The `schema` command, bound to the commands it describes. */
+export function schemaCommand(sources: readonly SchemaSource[]): cli.Command {
+	const definition = command({
+		name: 'schema',
+		description: "Print the JSON Schema of a command's arguments and options",
+		arguments: [
+			{ name: 'command', description: 'The command to describe; leave out to list them', type: t.string().optional() }
+		],
+		run(args) {
+			if (args.command === undefined)
+				return result(
+					{ commands: sources.map((s) => s.name) },
+					{ help: 'Run `color-map schema <command>` for one schema' }
+				)
+			const source = sources.find((s) => s.name === args.command)
+			if (!source)
+				throw new CliError(`no command named "${args.command}"`, {
+					code: 'unknown-command',
+					exitCode: exitCodes.usage,
+					details: { command: args.command },
+					help: 'Run `color-map schema` to list the commands'
+				})
+			return document(`${JSON.stringify(schemaOf(source), null, 2)}\n`)
+		}
+	})
+	return definition
+}

package/src/cli/schemas.ts

@@ -0,0 +1,86 @@
+/** The introspection data of a clibuilder `t` descriptor, as far as the schema needs it. */
+interface Data {
+	kind: string
+	min?: number
+	max?: number
+	values?: readonly string[]
+	element?: Data
+}
+
+/** The slice of a clibuilder command that a schema is read from. */
+export interface SchemaSource {
+	name: string
+	description?: string | undefined
+	arguments?:
+		| readonly { name: string; description?: string | undefined; type?: { [k: string]: any } | undefined }[]
+		| undefined
+	options?: Record<
+		string,
+		{ description?: string | undefined; type?: { [k: string]: any } | undefined; default?: unknown } | undefined
+	>
+}
+
+type Json = Record<string, unknown>
+
+function ofType(data: Data): Json {
+	switch (data.kind) {
+		case 'string':
+			return { type: 'string' }
+		case 'number':
+		case 'int': {
+			const { min, max } = data
+			return {
+				type: data.kind === 'int' ? 'integer' : 'number',
+				...(min === undefined ? {} : { minimum: min }),
+				...(max === undefined ? {} : { maximum: max })
+			}
+		}
+		case 'boolean':
+			return { type: 'boolean' }
+		case 'enum':
+			return { type: 'string', enum: [...(data.values as readonly string[])] }
+		case 'array':
+			return { type: 'array', items: ofType(data.element as Data) }
+		default:
+			// literal, custom and json are not used by this CLI's options
+			return {}
+	}
+}
+
+function property(entry: NonNullable<SchemaSource['options']>[string], extra: Json = {}): Json {
+	const { description, type, default: value } = entry ?? {}
+	return {
+		...ofType((type ?? { kind: 'string' }) as Data),
+		...(description === undefined ? {} : { description }),
+		...(value === undefined ? {} : { default: value }),
+		...extra
+	}
+}
+
+/**
+ * The JSON Schema (2020-12) of one command's arguments and options, read from
+ * the same descriptors the parser uses, so the two cannot drift. An argument
+ * or option with no default that is not optional is `required`.
+ */
+export function schemaOf(command: SchemaSource): Json {
+	const properties: Record<string, Json> = {}
+	const required: string[] = []
+	for (const arg of command.arguments ?? []) {
+		properties[arg.name] = property(arg, { 'x-kind': 'argument' })
+		if (!arg.type?.isOptional) required.push(arg.name)
+	}
+	for (const [name, option] of Object.entries(command.options ?? {})) {
+		properties[name] = property(option, { 'x-kind': 'option' })
+		if (option && !option.type?.isOptional && option.default === undefined) required.push(name)
+	}
+	return {
+		$schema: 'https://json-schema.org/draft/2020-12/schema',
+		$id: `https://unpkg.com/color-map/schemas/${command.name}.schema.json`,
+		title: `color-map ${command.name}`,
+		...(command.description === undefined ? {} : { description: command.description }),
+		type: 'object',
+		properties,
+		required,
+		additionalProperties: false
+	}
+}

package/src/cli/shared.ts

@@ -0,0 +1,72 @@
+import { CliError, exitCodes } from 'clibuilder/axi'
+import { type Color, type ColorSpaceId, parseExpr, resolve, toCss, toHex } from '../color/index.js'
+
+/** Every space `convert` can target, with the CSS names. */
+export const SPACES = [
+	'srgb',
+	'srgb-linear',
+	'hsl',
+	'hwb',
+	'lab',
+	'lch',
+	'oklab',
+	'oklch',
+	'display-p3',
+	'display-p3-linear',
+	'a98-rgb',
+	'prophoto-rgb',
+	'rec2020',
+	'xyz-d50',
+	'xyz-d65'
+] as const satisfies readonly ColorSpaceId[]
+
+/** The bounded RGB spaces a color can be mapped into. */
+export const GAMUTS = [
+	'srgb',
+	'srgb-linear',
+	'display-p3',
+	'display-p3-linear',
+	'a98-rgb',
+	'prophoto-rgb',
+	'rec2020'
+] as const
+
+export const PRESETS = ['tailwind-11', 'radix-12', 'tone-13', 'even'] as const
+export const MODES = ['light', 'dark'] as const
+export const HUE_METHODS = ['shorter', 'longer', 'increasing', 'decreasing'] as const
+export const EXPORT_TARGETS = ['dtcg', 'css', 'tailwind'] as const
+export const EXPORT_SOURCES = ['palette', 'scale'] as const
+export const POLAR_SPACES = ['hsl', 'hwb', 'lch', 'oklch'] as const
+
+/** Round to `digits` decimals; keeps TOON tables short. */
+export const round = (n: number, digits = 2): number => Number(n.toFixed(digits))
+
+/**
+ * Reads a color from its CSS text: any Color 4 form, plus `color-mix()`,
+ * relative colors and `light-dark()` (resolved for the light scheme).
+ * Fails with a coded usage error that names the text.
+ */
+export function readColor(text: string, name = 'color'): Color {
+	try {
+		return resolve(parseExpr(text), { colorScheme: 'light' })
+	} catch (cause) {
+		throw new CliError(`cannot read ${name} "${text}" as a CSS color`, {
+			code: 'invalid-color',
+			exitCode: exitCodes.usage,
+			details: { [name]: text, reason: (cause as Error).message },
+			help: 'Pass a CSS color such as "#3b82f6", "oklch(0.7 0.15 250)" or "color-mix(in oklab, red, blue)"'
+		})
+	}
+}
+
+/** A color as the essential fields: CSS text and hex. `--full` adds the parts. */
+export function describe(color: Color, full: boolean): Record<string, string | number | boolean | null> {
+	const base = { css: toCss(color), hex: toHex(color) }
+	if (!full) return base
+	return {
+		...base,
+		space: color.colorSpace,
+		components: color.components.map((c) => (c === null ? 'none' : round(c, 5))).join(' '),
+		alpha: color.alpha === undefined ? 1 : color.alpha
+	}
+}

package/src/cli/testing.ts

@@ -0,0 +1,27 @@
+import { Writable } from 'node:stream'
+import { createApp } from './cli.js'
+
+/** Runs the CLI in process and returns what it wrote and how it exited. */
+export async function run(...argv: string[]) {
+	let out = ''
+	let err = ''
+	const sink = (append: (s: string) => void) =>
+		new Writable({
+			decodeStrings: false,
+			write(chunk, _encoding, callback) {
+				append(String(chunk))
+				callback()
+			}
+		})
+	const code = await createApp({
+		version: '1.0.0',
+		streams: { stdout: sink((s) => (out += s)), stderr: sink((s) => (err += s)) }
+	}).parse(['node', 'color-map', ...argv])
+	return { out, err, code: typeof code === 'number' ? code : 0 }
+}
+
+/** Runs with `--format json` and parses stdout. */
+export async function runJson(...argv: string[]) {
+	const r = await run(...argv, '--format', 'json')
+	return { ...r, json: JSON.parse(r.out) as Record<string, any> }
+}

package/src/color/a98-rgb.ts

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

package/src/color/argb.ts

@@ -0,0 +1,21 @@
+import type { Color } from './types.js'
+
+const byte = (n: number): number => Math.min(255, Math.max(0, Math.round(n * 255)))
+
+/** An sRGB color from a 32-bit ARGB integer, as Material Color Utilities uses. */
+export function fromArgb(argb: number): Color {
+	const n = argb >>> 0
+	return {
+		colorSpace: 'srgb',
+		components: [((n >>> 16) & 255) / 255, ((n >>> 8) & 255) / 255, (n & 255) / 255],
+		alpha: (n >>> 24) / 255
+	}
+}
+
+/** The unsigned 32-bit ARGB integer for an sRGB color. Convert other spaces to `srgb` first. */
+export function toArgb(color: Color): number {
+	if (color.colorSpace !== 'srgb') throw new Error(`color-map: toArgb needs an srgb color, got "${color.colorSpace}"`)
+	const [r, g, b] = color.components
+	const a = color.alpha ?? 1
+	return ((byte(a) << 24) | (byte(r ?? 0) << 16) | (byte(g ?? 0) << 8) | byte(b ?? 0)) >>> 0
+}

package/src/color/calc.ts

@@ -0,0 +1,84 @@
+import { fail, UNITS } from './parse.js'
+
+const TOKEN = /\s*(?:(\d*\.?\d+(?:e[+-]?\d+)?)([a-z%]*)|([a-z][a-z0-9-]*)|([-+*/(),]))/y
+
+/**
+ * Evaluates the `calc()` subset relative colors accept: numbers (angles become
+ * degrees), `+ - * /`, parentheses, `calc`, `min`, `max`, `clamp`, the
+ * constants `pi` and `e`, and the channel keywords in `vars`.
+ */
+export function evaluate(text: string, vars: Record<string, number>): number {
+	const tokens: string[] = []
+	TOKEN.lastIndex = 0
+	let end = 0
+	for (let m = TOKEN.exec(text); m; m = TOKEN.exec(text)) {
+		end = TOKEN.lastIndex
+		if (m[1] === undefined) tokens.push(m[3] ?? m[4])
+		else {
+			const unit = UNITS[m[2]]
+			if (unit === undefined) return fail(text, 'units other than angles are not supported in calc()', m[1] + m[2])
+			tokens.push(String(Number(m[1]) * unit))
+		}
+	}
+	if (end !== text.trimEnd().length) return fail(text, 'invalid calc() expression')
+	let pos = 0
+	const next = (): string => tokens[pos++]
+	const eat = (t: string): boolean => (tokens[pos] === t ? ++pos > 0 : false)
+	const need = (t: string): void => {
+		if (!eat(t)) fail(text, `expected "${t}" in calc()`, tokens[pos])
+	}
+	function sum(): number {
+		let v = product()
+		for (;;) {
+			if (eat('+')) v += product()
+			else if (eat('-')) v -= product()
+			else return v
+		}
+	}
+	function product(): number {
+		let v = unary()
+		for (;;) {
+			if (eat('*')) v *= unary()
+			else if (eat('/')) v /= unary()
+			else return v
+		}
+	}
+	function unary(): number {
+		if (eat('-')) return -unary()
+		if (eat('+')) return unary()
+		return atom()
+	}
+	function args(): number[] {
+		const list = [sum()]
+		while (eat(',')) list.push(sum())
+		need(')')
+		return list
+	}
+	function atom(): number {
+		const t = next()
+		if (t === undefined) return fail(text, 'unfinished calc() expression')
+		if (/^[\d.]/.test(t)) return Number(t)
+		if (t === '(') {
+			const v = sum()
+			need(')')
+			return v
+		}
+		if (!/^[a-z]/.test(t)) return fail(text, 'unexpected token', t)
+		if (eat('(')) {
+			const list = args()
+			if (t === 'calc' && list.length === 1) return list[0]
+			if (t === 'min') return Math.min(...list)
+			if (t === 'max') return Math.max(...list)
+			if (t === 'clamp' && list.length === 3) return Math.min(list[2], Math.max(list[0], list[1]))
+			return fail(text, 'unknown function', t)
+		}
+		if (t === 'pi') return Math.PI
+		if (t === 'e') return Math.E
+		const v = vars[t]
+		if (typeof v === 'number') return v
+		return fail(text, 'unknown keyword', t)
+	}
+	const value = sum()
+	if (pos < tokens.length) return fail(text, 'unexpected token', tokens[pos])
+	return value
+}

package/src/color/compare.ts

@@ -0,0 +1,53 @@
+import { type ComponentsIn, componentsOver, convertWith } from './convert.js'
+import { oklab } from './oklab.js'
+import { componentsIn } from './spaces.js'
+import type { Color, Space } from './types.js'
+
+/** Euclidean distance in OKLab, the ΔEOK of CSS Color 4 gamut mapping. */
+export function deltaEOk(a: Color, b: Color): number {
+	return deltaEOkWith(componentsIn, a, b)
+}
+
+/** {@link deltaEOk} over the spaces `componentsIn` knows, which must include `oklab`. */
+export function deltaEOkWith(componentsIn: ComponentsIn, a: Color, b: Color): number {
+	const [l1, a1, b1] = componentsIn(a, 'oklab') as number[]
+	const [l2, a2, b2] = componentsIn(b, 'oklab') as number[]
+	return Math.hypot(l1 - l2, a1 - a2, b1 - b2)
+}
+
+/**
+ * Builds {@link deltaEOk} over the spaces given, plus `oklab`, so a bundle
+ * contains only those. A color in a space not given throws, naming that space.
+ */
+export function createDeltaEOk(...spaces: Space[]): (a: Color, b: Color) => number {
+	const over = componentsOver([oklab, ...spaces])
+	return (a, b) => deltaEOkWith(over, a, b)
+}
+
+const same = (x: number | null | undefined, y: number | null | undefined, epsilon: number): boolean =>
+	x === y || (x != null && y != null && Math.abs(x - y) <= epsilon)
+
+/**
+ * True when both colors are the same within `epsilon` per component. Colors in
+ * different spaces are compared in the first one's space. `none` equals only
+ * `none`, and a missing alpha equals 1.
+ */
+export function equals(a: Color, b: Color, epsilon = 1e-6): boolean {
+	return equalsWith(componentsIn, a, b, epsilon)
+}
+
+function equalsWith(componentsIn: ComponentsIn, a: Color, b: Color, epsilon: number): boolean {
+	const other = convertWith(componentsIn, b, a.colorSpace)
+	return (
+		same(a.alpha ?? 1, other.alpha ?? 1, epsilon) && a.components.every((c, i) => same(c, other.components[i], epsilon))
+	)
+}
+
+/**
+ * Builds {@link equals} over the spaces given, so a bundle contains only those.
+ * It needs no space of its own: give the spaces of both colors.
+ */
+export function createEquals(...spaces: Space[]): (a: Color, b: Color, epsilon?: number) => boolean {
+	const over = componentsOver(spaces)
+	return (a, b, epsilon = 1e-6) => equalsWith(over, a, b, epsilon)
+}