@yahoo/uds-create-config 4.54.0 → 4.55.0

package/dist/entities/system/StyleProperty.js

@@ -1,9 +1,10 @@
-import { isRef, kindOf, pathOf, ref, refSchema, sourceOf, splitRef } from "../../framework/utils/refs.js";
+import { declarationText, isRef, kindOf, pathOf, ref, refOfKey, refSchema, replaceRefMarkers, sourceOf, splitRef } from "../../framework/utils/refs.js";
 import { defineEntity } from "../../framework/defineEntity.js";
 import { cssValueIssue, isCssProperty } from "../../css/values.js";
 import { camelCase } from "./style-bag.js";
 import { createSliceMemo } from "../../framework/memo.js";
 import { isIdentifier } from "../../framework/utils/identifier.js";
+import { cssVar, declaresCssVariable } from "../../framework/projections.js";
 import { z } from "zod";
 //#region src/entities/system/StyleProperty.ts
 /**
@@ -31,10 +32,11 @@ const aliasName = z.union([z.string(), z.number()]);
 /** The first property among `properties` that refuses `text`, as the refusal. A property the table
 *  can't judge says nothing. */
 function cssIssue(properties, text, grammar) {
+	const written = replaceRefMarkers(text, () => "var(--ref)");
 	for (const property of properties ?? []) {
 		const issue = cssValueIssue({
 			property,
-			value: text,
+			value: written,
 			grammar
 		});
 		if (issue !== void 0 && issue !== "unknown") return issue;
@@ -76,6 +78,14 @@ const namesItem = (config, wanted) => (ctx) => {
 /** A declaration bag's key. A ref is a record of one string too, so the ref marker is not a key here,
 *  or a ref no ref form admits would read as a bag. */
 const declarationKey = z.string().regex(/^(?!__ref$)/);
+/** A declaration's value: CSS text, or a ref to the token it is, `'border-style':
+*  Token.ref('tw/border-style')`. */
+const declarationValue = z.union([z.string(), refSchema]);
+/** The class an alias or a flag is written as, in place of `<classPrefix>-<alias>`. */
+const valueClassName = z.string().regex(/^[^\s]+$/).meta({
+	title: "Class name",
+	description: "The class this value is written as, in place of the prop's `<classPrefix>-<leaf>`: `{ alias: 'auto', value: 'auto', className: 'isolation-auto' }`. The system's class prefix still applies."
+}).optional();
 const STYLE_PROP_VALUE_FORMS = {
 	keyword: (ctx = {}) => z.string().meta({
 		title: "Keyword",
@@ -105,32 +115,46 @@ const STYLE_PROP_VALUE_FORMS = {
 		value: z.union([
 			z.string(),
 			refSchema,
-			z.record(z.string(), z.string())
-		])
+			z.record(z.string(), declarationValue)
+		]),
+		className: valueClassName
 	}).meta({
 		title: "Flag",
 		description: "A boolean alias for a boolean-shaped prop: `<Box border />` sets `border-width: 1px`."
 	}),
 	aliasToken: ({ config } = {}) => z.strictObject({
 		alias: aliasName,
-		value: refSchema.check(namesItem(config, true))
+		value: refSchema.check(namesItem(config, true)),
+		className: valueClassName
 	}).meta({
 		title: "Token alias",
 		description: "One token under a name of the prop's own, still emitted as its `var()`."
 	}),
 	aliasLiteral: (ctx = {}) => z.strictObject({
 		alias: aliasName,
-		value: z.string()
+		value: z.string(),
+		className: valueClassName
 	}).meta({
 		title: "Alias",
 		description: "The authored key and the CSS value it resolves to: `{ alias: \"col\", value: \"column\" }`."
 	}).check(cssText(ctx, (value) => value.value)),
 	aliasDeclarations: (_ctx = {}) => z.strictObject({
 		alias: aliasName,
-		value: z.record(declarationKey, z.string())
+		value: z.record(declarationKey, z.union([declarationValue, z.record(declarationKey, declarationValue)])),
+		className: valueClassName
+	}).check((ctx) => {
+		for (const [key, value] of Object.entries(ctx.value.value)) {
+			if (typeof value === "string" || isRef(value) || key.startsWith("@")) continue;
+			ctx.issues.push({
+				code: "custom",
+				input: value,
+				path: ["value", key],
+				message: `\`${key}\` holds a block, and only an at-rule (\`@supports …\`, \`@media …\`) holds declarations of its own.`
+			});
+		}
 	}).meta({
 		title: "Declarations",
-		description: "A leaf that stands for a whole declaration bag: `truncate` sets `overflow`, `text-overflow` and `white-space`."
+		description: "A leaf that stands for a whole declaration bag: `truncate` sets `overflow`, `text-overflow` and `white-space`. A key that is an at-rule (`@media (forced-colors: active)`) holds the declarations that apply under it."
 	})
 };
 const KINDS = Object.keys(STYLE_PROP_VALUE_FORMS);
@@ -140,7 +164,7 @@ function flagValue(value, members) {
 	if ("__ref" in value && typeof value.__ref === "string") return members(value).map(({ path }) => ({ value: path }));
 	return [{
 		value: "",
-		declarations: value
+		declarations: textOf(value)
 	}];
 }
 /**
@@ -172,22 +196,45 @@ const STYLE_PROP_VALUE_LEAVES = {
 	})),
 	flag: (entry, members) => entry.alias ? flagValue(entry.value, members).map((rest) => ({
 		leaf: "",
-		...rest
+		...rest,
+		...classNameOf(entry)
 	})) : [],
 	aliasToken: (entry, members) => members(entry.value).map(({ path }) => ({
 		leaf: String(entry.alias),
-		value: path
+		value: path,
+		...classNameOf(entry)
 	})),
 	aliasLiteral: (entry) => [{
 		leaf: String(entry.alias),
-		value: entry.value
+		value: entry.value,
+		...classNameOf(entry)
 	}],
 	aliasDeclarations: (entry) => [{
 		leaf: String(entry.alias),
 		value: "",
-		declarations: entry.value
+		...splitDeclarations(entry.value),
+		...classNameOf(entry)
 	}]
 };
+/** A bag's declarations as text, each ref as its marker. */
+function textOf(bag) {
+	return Object.fromEntries(Object.entries(bag).map(([key, value]) => [key, declarationText(value)]));
+}
+/** A declaration bag as a leaf holds it: the plain declarations, and the blocks under at-rules. */
+function splitDeclarations(bag) {
+	const declarations = {};
+	const atRules = {};
+	for (const [key, value] of Object.entries(bag)) if (typeof value === "string" || isRef(value)) declarations[key] = declarationText(value);
+	else atRules[key] = textOf(value);
+	return Object.keys(atRules).length > 0 ? {
+		declarations,
+		atRules
+	} : { declarations };
+}
+/** An entry's own class, spread into its leaf when it names one. */
+function classNameOf(entry) {
+	return entry.className === void 0 ? {} : { className: entry.className };
+}
 /** The leaves one stored entry stands for; none for a value no form admits. */
 function leavesOfStylePropValue(entry, members) {
 	const kind = stylePropValueFormOf(entry);
@@ -221,7 +268,7 @@ function classifyStylePropValue({ config, entry }) {
 */
 const cssPropertyName = z.string().check((ctx) => {
 	const name = ctx.value;
-	if (name.startsWith("-")) return;
+	if (name.startsWith("-") || refOfKey(name)) return;
 	if (/[A-Z]/.test(name)) {
 		const css = name.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
 		ctx.issues.push({
@@ -263,6 +310,8 @@ function eachValueOnce(ctx) {
 }
 /** One comparable form for a CSS value, so `#FFFFFF` and `#ffffff ` read as the same value. */
 const comparable = (value) => typeof value === "string" || typeof value === "number" ? String(value).trim().toLowerCase() : void 0;
+/** A colour spelled as a hex or a colour function. */
+const COLOR_LITERAL = /^(?:#[0-9a-f]{3,8}|(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\(.*\))$/;
 /** Whether `values` reaches the token at `path` — through the token itself, an alias naming it, or
 *  a group above it. */
 function reaches(values, path) {
@@ -307,15 +356,80 @@ const copiesNoToken = (config) => (ctx) => {
 		});
 	});
 };
-/** Each token value, as `comparable` spells it, and the first token path that holds it. Kept per token
-*  slice, since a batch of style-property writes would otherwise list every token once per write. */
+/** Each variable a token declares, by name, and the token declaring it. */
+const tokenPathsByVariable = createSliceMemo({
+	kinds: ["token", "settings"],
+	compute: (config) => {
+		const tokens = /* @__PURE__ */ new Map();
+		for (const token of config.list("token")) {
+			if (!declaresCssVariable(config, token.path)) continue;
+			tokens.set(cssVar(config, "token", token.path), token.path);
+		}
+		return tokens;
+	}
+});
+/**
+* This config's style properties whose values or declarations spell a token's variable as text. The
+* text stops naming the token on a rename or a prefix change, where an interpolated `Token.ref`
+* follows it. A variable no token declares, such as a third-party library's, isn't one.
+*/
+function tokenVariablesAsText(config) {
+	const tokens = tokenPathsByVariable(config);
+	const found = [];
+	const visit = ({ styleProperty, value, at }) => {
+		if (typeof value === "string") for (const [, variable = ""] of value.matchAll(/var\((--[\w-]+)/g)) {
+			const token = tokens.get(variable);
+			if (token) found.push({
+				styleProperty,
+				at: at.join("."),
+				variable,
+				token
+			});
+		}
+		else if (Array.isArray(value)) for (const [index, item] of value.entries()) visit({
+			styleProperty,
+			value: item,
+			at: [...at, index]
+		});
+		else if (value && typeof value === "object" && !("__ref" in value)) for (const [key, nested] of Object.entries(value)) visit({
+			styleProperty,
+			value: nested,
+			at: [...at, key]
+		});
+	};
+	for (const prop of config.list("style-property")) {
+		if (config.configFor(ref("style-property", prop.path)) !== config) continue;
+		const { values, declarations } = prop.toJSON();
+		visit({
+			styleProperty: prop.path,
+			value: values,
+			at: ["values"]
+		});
+		visit({
+			styleProperty: prop.path,
+			value: declarations,
+			at: ["declarations"]
+		});
+	}
+	return found;
+}
+/**
+* Each colour token's value, as `comparable` spells it, and the first token path that holds it. Kept
+* per token slice, since a batch of style-property writes would otherwise list every token once per
+* write.
+*
+* Only colours: a colour literal that equals a token is that token written out, while a length or a
+* number coincides across unrelated scales — `4px` is a blur radius and a stroke width, `1` a line
+* height and `flex: 1`.
+*/
 const tokenPathsByValue = createSliceMemo({
 	kinds: ["token"],
 	compute: (config) => {
 		const tokens = /* @__PURE__ */ new Map();
 		for (const token of config.list("token")) {
 			const value = comparable(token.body.value);
-			if (value !== void 0 && !tokens.has(value)) tokens.set(value, token.path);
+			if (value === void 0 || !COLOR_LITERAL.test(value)) continue;
+			if (!tokens.has(value)) tokens.set(value, token.path);
 		}
 		return tokens;
 	}
@@ -397,6 +511,15 @@ const styleFields = ({ config, body, linked } = {}) => z.object({
 	*/
 	negates: z.boolean().default(false).describe("Apply the negation of the value, so one scale works in both directions. Defaults to `false`."),
 	/**
+	* Declarations the prop sets beside every value. A prop whose value is one part of a composed
+	* property writes its part to a custom property and the whole here: `translateX` sets
+	* `--tw-translate-x` and `translate: var(--tw-translate-x) var(--tw-translate-y)`, so the X and Y
+	* props compose on one element.
+	*/
+	selector: z.string().regex(/&/).optional().describe("The selector the prop's rules are written under, with `&` for its class: `:where(& > :not(:last-child))` styles the element's children, as `space-x-4` does."),
+	alpha: z.string().refine((name) => name.startsWith("--") || refOfKey(name) !== void 0).optional().describe("The custom property holding the alpha the prop's colour values are mixed at, as `--tw-shadow-alpha` for `shadow-red-500`, or a token's key for the variable it declares. A colour value is written as its literal, and under `@supports` as its variable mixed at that alpha."),
+	declarations: z.record(declarationKey, declarationValue).optional().describe("Declarations the prop sets with every value, as `translate: var(--tw-translate-x) var(--tw-translate-y)` beside a prop writing `--tw-translate-x`. `{value}` stands for the value the prop was given, so a prop with no `properties` of its own can still place it: `margin-inline-start: calc({value} * var(--tw-space-x-reverse))`."),
+	/**
 	* The style prop whose alpha this one controls — `bgOpacity` is the opacity of `bg`.
 	*
 	* The pairing is modelled from the SIBLING's side, and the sibling is a real entity. The old model
@@ -455,4 +578,4 @@ function cssPropertyNames(styleProp) {
 	return styleProp.properties.map(toCssPropertyName);
 }
 //#endregion
-export { STYLE_PROP_VALUE_FORMS, STYLE_PROP_VALUE_LEAVES, StyleProperty, classifyStylePropValue, cssPropertyNames, leavesOfStylePropValue, stylePropValueFormOf, stylePropValueSchema, toCssPropertyName };
+export { STYLE_PROP_VALUE_FORMS, STYLE_PROP_VALUE_LEAVES, StyleProperty, classifyStylePropValue, cssPropertyNames, leavesOfStylePropValue, stylePropValueFormOf, stylePropValueSchema, toCssPropertyName, tokenVariablesAsText };

package/dist/entities/system/Token.d.ts

@@ -2,8 +2,8 @@ import { Ref } from "../../framework/utils/ref-grammar.js";
 import { Ref as Ref$1 } from "../../framework/utils/refs.js";
 import { SubEntityClass } from "../../framework/defineSubEntity.js";
 import { PathOf } from "../../framework/registered.js";
-import { EntityClass, KindRef } from "../../framework/defineEntity.js";
 import { ComposedValue } from "./composed-values.js";
+import { EntityClass, KindRef } from "../../framework/defineEntity.js";
 import { TokenReaders } from "./token-values.js";
 import { z } from "zod";
 
@@ -48,6 +48,12 @@ declare const tokenFields: z.ZodObject<{
     on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
     value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
   }, z.core.$strip>>>;
+  utility: z.ZodOptional<z.ZodBoolean>;
+  property: z.ZodOptional<z.ZodObject<{
+    syntax: z.ZodOptional<z.ZodString>;
+    inherits: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strict>>;
+  cssVariable: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
 }, z.core.$strip>;
 /** A token's stored body — what a `create` writes and what `Token.get` hands back typed. Exported
  *  so a consumer building one names the entity's own shape instead of restating it. */
@@ -59,8 +65,15 @@ declare const TokenEntity: EntityClass<z.ZodObject<{
     on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
     value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
   }, z.core.$strip>>>;
+  utility: z.ZodOptional<z.ZodBoolean>;
+  property: z.ZodOptional<z.ZodObject<{
+    syntax: z.ZodOptional<z.ZodString>;
+    inherits: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strict>>;
+  cssVariable: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
 }, z.core.$strip>, z.ZodObject<{
   cssPrefix: z.ZodOptional<z.ZodString>;
+  cssVariables: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, "token", {}, Record<never, never>, false, Record<never, never>, Record<never, never>>;
 /** A token ref as an authoring file holds it: the marker, `extend`, and the value readers. */
 type TokenReference<Path extends string> = KindRef<typeof TokenEntity, 'token', Path> & TokenReaders<Path>;

package/dist/entities/system/Token.js

@@ -4,8 +4,10 @@ import { defineEntity } from "../../framework/defineEntity.js";
 import { defineSubEntity } from "../../framework/defineSubEntity.js";
 import { Font } from "./Font.js";
 import { Modifier } from "./Modifier.js";
+import { WEB_CONFIG_NAME } from "../../configs/platform.js";
 import { authoringPhantom } from "../../framework/utils/authoring-phantom.js";
 import { TOKEN_READERS, spellTokenRead } from "./token-values.js";
+import { prepareLinkedTokenBody } from "./linked-token-values.js";
 import { z } from "zod";
 //#region src/entities/system/Token.ts
 /**
@@ -116,13 +118,29 @@ function defineOverride(value) {
 const Override = defineOverride(tokenValue);
 const TokenEntity = defineEntity({
 	kind: "token",
+	prepareLinkedBody: ({ path, body, source, config }) => prepareLinkedTokenBody({
+		path,
+		body,
+		source,
+		config,
+		destinationPlatform: WEB_CONFIG_NAME
+	}),
 	fields: z.object({
 		value: tokenValue.describe("The base value: a literal, a ref to another token, or a composed value such as a gradient."),
 		type: z.string().optional().describe("The CSS value type, when the value alone does not say it."),
-		overrides: Override.optional().describe("Per-mode values, keyed by the condition they apply under.")
+		overrides: Override.optional().describe("Per-mode values, keyed by the condition they apply under."),
+		utility: z.boolean().optional().describe("`false` keeps the token out of its group's values, so a style prop that takes the group writes no class for it — `spacing/scale` powers `--spacing` without becoming a `p-scale`. A ref naming the token still resolves."),
+		property: z.strictObject({
+			syntax: z.string().optional().describe("The `@property` syntax, as `<length>`. Defaults to `*`."),
+			inherits: z.boolean().optional().describe("Whether the property inherits. Defaults to `false`.")
+		}).optional().describe("Registers the token's custom property with `@property` instead of declaring it on `:root`, with the token's value as its initial value, or none for `initial`. For a variable utilities set on an element, as Tailwind's `--tw-border-style`."),
+		cssVariable: z.union([z.string().regex(/^(?:--)?[A-Za-z0-9_][A-Za-z0-9_-]*$/), z.literal(false)]).optional().describe("The custom property this token is declared as. A name is placed under the system's prefix: `'spacing'` is `--uds-spacing`, or `--spacing` with an empty prefix. A name starting with `--` is used exactly, whatever the prefix, as for a third-party library's variable: `'--mantine-color-primary'`. `false` declares none and writes the token into the values that use it. Unset, its name comes from its path and the nearest group's `cssPrefix`, and whether it is declared from the nearest group's `cssVariables`.")
+	}),
+	groupFields: z.object({
+		cssPrefix: z.string().optional().describe("The prefix the group emits its custom properties under. Local to the config that holds the group."),
+		cssVariables: z.boolean().optional().describe("`false` writes the group's tokens into the values that use them instead of declaring a custom property for each, as Tailwind's `@theme inline` does. A token's own `cssVariable` wins. Local to the config that holds the group.")
 	}),
-	groupFields: z.object({ cssPrefix: z.string().optional().describe("The prefix the group emits its custom properties under. Local to the config that holds the group.") }),
-	localGroupFields: ["cssPrefix"],
+	localGroupFields: ["cssPrefix", "cssVariables"],
 	subEntities: { overrides: Override },
 	schemas: { create: { description: `Create a token at \`<group>/<name>\` — \`data.value\` is the CSS value. The first path segment is its group, and a style property takes a whole group as one ref (\`${JSON.stringify(ref("token", "<group>"))}\`), so put the tokens one prop should offer in one group rather than listing values on the prop.` } }
 });

package/dist/entities/system/calc.d.ts

@@ -0,0 +1,28 @@
+import { Ref } from "../../framework/utils/refs.js";
+import { z } from "zod";
+
+//#region src/entities/system/calc.d.ts
+/** One side of the arithmetic: a number, a CSS length such as `0.25rem`, or a ref to a token. */
+type CalcOperand = number | string | Ref;
+interface Multiply {
+  readonly multiply: readonly [CalcOperand, CalcOperand];
+}
+interface Divide {
+  readonly divide: readonly [CalcOperand, CalcOperand];
+}
+/** Whether a value is a `multiply(…)`. */
+declare function isMultiply(value: unknown): value is Multiply;
+/** Whether a value is a `divide(…)`. */
+declare function isDivide(value: unknown): value is Divide;
+/** `multiply(Token.ref('spacing'), 4)` — the first operand times the second. */
+declare function multiply(left: CalcOperand, right: CalcOperand): Multiply;
+/** `divide(1.25, 0.875)` — the first operand over the second. */
+declare function divide(left: CalcOperand, right: CalcOperand): Divide;
+/**
+ * What the arithmetic comes to, given each operand's literal — `1rem` for `0.25rem` times 4,
+ * `1.4286` for `1.25` over `0.875` — or `undefined` when the operands are not plain quantities or
+ * their units don't combine. `literal` resolves an operand (a ref to the token's value).
+ */
+declare function evaluateCalc(value: Multiply | Divide, literal: (part: CalcOperand) => string | number | undefined): string | number | undefined;
+//#endregion
+export { CalcOperand, Divide, Multiply, divide, evaluateCalc, isDivide, isMultiply, multiply };

package/dist/entities/system/calc.js

@@ -0,0 +1,121 @@
+import { refSchema } from "../../framework/utils/refs.js";
+import { z } from "zod";
+//#region src/entities/system/calc.ts
+/**
+* A value that is arithmetic on others — `multiply(Token.ref('spacing'), 4)` is
+* `calc(var(--spacing) * 4)`, and `divide(1.25, 0.875)` is `calc(1.25 / 0.875)`.
+*
+* Held as its operands rather than as the `calc()` string so a ref in it stays a ref: a rename
+* follows into it, the dependency graph sees it, and a reader can work out what it comes to
+* (`spacing` at `0.25rem` times 4 is `1rem`) where a string would only be text.
+*/
+const operand = z.union([
+	z.number(),
+	z.string().min(1),
+	refSchema
+]);
+const operands = z.tuple([operand, operand]);
+const multiplyValue = z.strictObject({ multiply: operands });
+const divideValue = z.strictObject({ divide: operands });
+const isPair = (value) => Array.isArray(value) && value.length === 2;
+/** Whether a value is a `multiply(…)`. */
+function isMultiply(value) {
+	return typeof value === "object" && value !== null && isPair(value.multiply);
+}
+/** Whether a value is a `divide(…)`. */
+function isDivide(value) {
+	return typeof value === "object" && value !== null && isPair(value.divide);
+}
+/** `multiply(Token.ref('spacing'), 4)` — the first operand times the second. */
+function multiply(left, right) {
+	return { multiply: [left, right] };
+}
+/** `divide(1.25, 0.875)` — the first operand over the second. */
+function divide(left, right) {
+	return { divide: [left, right] };
+}
+/** A `multiply(…)` as CSS — `calc(var(--spacing) * 4)` — with `render` resolving each operand. */
+function renderMultiply(value, render) {
+	const [left, right] = value.multiply;
+	return `calc(${render(left)} * ${render(right)})`;
+}
+/** A `divide(…)` as CSS — `calc(1.25 / 0.875)`. */
+function renderDivide(value, render) {
+	const [left, right] = value.divide;
+	return `calc(${render(left)} / ${render(right)})`;
+}
+function multiplyAuthoring(value) {
+	return {
+		helper: "multiply",
+		args: [...value.multiply]
+	};
+}
+function divideAuthoring(value) {
+	return {
+		helper: "divide",
+		args: [...value.divide]
+	};
+}
+const isDigit = (char) => char !== void 0 && char >= "0" && char <= "9";
+/**
+* The plain number a string starts with — an optional minus, digits, and an optional fraction
+* (`-1`, `0.25`, `.5`) — split from what follows it, or `undefined` when it starts with none.
+* A scan rather than a regex, so its cost stays linear on any input.
+*/
+function leadingNumber(text) {
+	let at = text.startsWith("-") ? 1 : 0;
+	const start = at;
+	while (isDigit(text[at])) at++;
+	const whole = at > start;
+	if (text[at] === "." && isDigit(text[at + 1])) {
+		at++;
+		while (isDigit(text[at])) at++;
+	} else if (!whole) return;
+	return {
+		sign: start === 1 ? "-" : "",
+		digits: text.slice(start, at),
+		rest: text.slice(at)
+	};
+}
+function quantityOf(value) {
+	if (typeof value === "number") return {
+		amount: value,
+		unit: ""
+	};
+	if (value === void 0) return void 0;
+	const number = leadingNumber(value.trim());
+	if (!number || !/^[a-z%]*$/i.test(number.rest)) return void 0;
+	return {
+		amount: Number(`${number.sign}${number.digits}`),
+		unit: number.rest
+	};
+}
+/**
+* What the arithmetic comes to, given each operand's literal — `1rem` for `0.25rem` times 4,
+* `1.4286` for `1.25` over `0.875` — or `undefined` when the operands are not plain quantities or
+* their units don't combine. `literal` resolves an operand (a ref to the token's value).
+*/
+function evaluateCalc(value, literal) {
+	const [left, right] = isMultiply(value) ? value.multiply : value.divide;
+	const a = quantityOf(literal(left));
+	const b = quantityOf(literal(right));
+	if (!a || !b) return void 0;
+	let result;
+	if (isMultiply(value)) {
+		if (a.unit && b.unit) return void 0;
+		result = {
+			amount: a.amount * b.amount,
+			unit: a.unit || b.unit
+		};
+	} else {
+		if (b.amount === 0 || b.unit && b.unit !== a.unit) return void 0;
+		result = {
+			amount: a.amount / b.amount,
+			unit: b.unit ? "" : a.unit
+		};
+	}
+	const amount = Math.round(result.amount * 1e4) / 1e4;
+	return result.unit ? `${amount}${result.unit}` : amount;
+}
+//#endregion
+export { divide, divideAuthoring, divideValue, evaluateCalc, isDivide, isMultiply, leadingNumber, multiply, multiplyAuthoring, multiplyValue, renderDivide, renderMultiply };

package/dist/entities/system/color.d.ts

@@ -1,10 +1,32 @@
 import { z } from "zod";
 
 //#region src/entities/system/color.d.ts
-/** A colour: a literal, a token ref, a derived colour, or a gradient. */
+/** A colour: a literal, a token ref, an OKLCH colour, a derived colour, or a gradient. */
 type ColorValue = string | {
   readonly __ref: string;
-} | DerivedColor | Gradient;
+} | OklchColor | DerivedColor | Gradient;
+/**
+ * A colour as its OKLCH channels — `oklch(63.7, 0.237, 25.331)` is CSS `oklch(63.7% 0.237 25.331)`.
+ *
+ * Held as numbers rather than as the CSS string so an editor reads and adjusts the channels
+ * themselves: lightness and chroma move without the hue drifting, which is what makes a ramp of them
+ * a scale. It renders to the CSS function, so the browser paints it in its own gamut.
+ */
+interface OklchColor {
+  readonly oklch: {
+    /** Lightness, as a percentage (0–100). */readonly l: number; /** Chroma, from 0 (grey) up; sRGB colours stay under about 0.37. */
+    readonly c: number; /** Hue in degrees. Absent for a grey, whose hue CSS spells `none`. */
+    readonly h?: number; /** Opacity, 0–1. Absent is opaque. */
+    readonly alpha?: number;
+  };
+}
+/** Whether a value is an OKLCH colour. */
+declare function isOklchColor(value: unknown): value is OklchColor;
+/** `oklch(63.7, 0.237, 25.331)` — lightness as a percentage, chroma, and hue in degrees. A grey
+ *  leaves the hue out. */
+declare function oklch(l: number, c: number, h?: number, alpha?: number): OklchColor;
+/** An OKLCH colour as CSS: `oklch(63.7% 0.237 25.331)`, `oklch(98.5% 0 none)`, `oklch(… / 0.5)`. */
+declare function renderOklch(value: OklchColor): string;
 interface DerivedColor {
   readonly op: 'darken' | 'lighten' | 'alpha' | 'mix';
   readonly color: ColorValue;
@@ -46,11 +68,14 @@ declare function isDerivedColor(value: unknown): value is DerivedColor;
 /** The interpolation space each op is authored in: `oklch` for shading (perceptually even), `srgb`
  *  for alpha. */
 declare const DERIVED_COLOR_SPACE: Record<DerivedColor['op'], string>;
+/** The space a derived colour with no `space` of its own mixes in, on every platform. */
+declare const DERIVED_COLOR_DEFAULT_SPACE = "oklch";
 /** Blend toward black in light mode and white in dark — so a hover state darkens in both. */
 declare function darken(color: ColorValue, amount: number): DerivedColor;
 /** Mirror of {@link darken}: toward white in light mode, black in dark. */
 declare function lighten(color: ColorValue, amount: number): DerivedColor;
-/** `alpha(color, 0.2)` — the colour at 20% opacity. Takes a 0–1 opacity, like CSS. */
+/** `alpha(color, 0.2)` — the colour at 20% opacity. Takes a 0–1 opacity, like CSS, kept to a tenth
+ *  of a percent. */
 declare function alpha(color: ColorValue, opacity: number): DerivedColor;
 /** `mix(a, b, 30)` — 30% of the way from `a` to `b`. */
 declare function mix(color: ColorValue, towards: ColorValue, amount: number, space?: string): DerivedColor;
@@ -64,4 +89,4 @@ declare function renderDerivedColor(value: DerivedColor, render: (color: ColorVa
 /** A gradient as CSS — `linear-gradient(to right, transparent 0%, var(--uds-bg-primary) 50%)`. */
 declare function renderGradient(value: Gradient, render: (color: ColorValue) => string): string;
 //#endregion
-export { ColorValue, DERIVED_COLOR_SPACE, DerivedColor, Gradient, alpha, darken, isDerivedColor, isGradient, lighten, linearGradient, mix, renderDerivedColor, renderGradient };
+export { ColorValue, DERIVED_COLOR_DEFAULT_SPACE, DERIVED_COLOR_SPACE, DerivedColor, Gradient, OklchColor, alpha, darken, isDerivedColor, isGradient, isOklchColor, lighten, linearGradient, mix, oklch, renderDerivedColor, renderGradient, renderOklch };