@yahoo/uds-create-config 5.15.1 → 5.16.0

package/dist/framework/projections.d.ts

@@ -1,6 +1,6 @@
 import { Ref } from "./utils/refs.js";
 import { ItemOf } from "./defineEntity.js";
-import { StylePropLeaf, StyleProperty } from "../entities/system/StyleProperty.js";
+import { StylePropLeaf, StylePropNumberUnit, StyleProperty } from "../entities/system/StyleProperty.js";
 import { StoredPreviewCondition, UNCONDITIONAL_PREVIEW_KEY, storedPreview, unconditionalPreviewProps } from "./preview-store.js";
 import { Config, ListOptions } from "./Config.js";
 
@@ -142,6 +142,89 @@ declare function stylePropValueLeaves(config: Config, path: string, opts?: ListO
  * when the leaf isn't in the prop's domain.
  */
 declare function stylePropValueFromLeaf(config: Config, path: string, leaf: string): string | undefined;
+/**
+ * The leaves a style property's body declares AS NUMBERS: a numeric literal (`values: [1, 2]`) or a
+ * numeric alias (`{ alias: 3, value: 'repeat(3, minmax(0, 1fr))' }`). Only these match a bare number
+ * — `columns={3}` — while a token's name is a string however it reads (`spacing="4"`, never
+ * `spacing={4}`), as is a string alias.
+ */
+declare function bodyNumberLeaves(stored: unknown): string[];
+/** The leaves a style prop declares as numbers ({@link StylePropLeaf.numeric}), by path. */
+declare function stylePropNumberLeaves(config: Config, path: string): string[];
+/**
+ * The leaf a bare number names on a style prop — `columns={3}` → `'3'` — or `undefined` when the
+ * prop declares no such number (`spacing={4}`, whose `4` is a token's name) or the value isn't a
+ * number.
+ */
+declare function stylePropNumberLeaf(config: Config, path: string, value: unknown): string | undefined;
+/** The unit a style property's body reads a bare number in, or `undefined` when it takes none. */
+declare function bodyNumberUnit(stored: unknown): StylePropNumberUnit | undefined;
+/** The unit a style prop reads a bare number in (`maxWidth={600}` with `arbitrary: 'px'`), or
+ *  `undefined` when it takes none. */
+declare function stylePropNumberUnit(config: Config, path: string): StylePropNumberUnit | undefined;
+/**
+ * The CSS a bare number on a style prop is written as, in the unit the prop declares (`arbitrary`):
+ * `maxWidth={600}` with `arbitrary: 'px'` is `600px`, `lineHeight={1.5}` with `arbitrary: 'unitless'` is
+ * `1.5`. `undefined` for a prop that declares none, for any other value, and for a number the
+ * prop declares as a value ({@link stylePropNumberLeaf}), which is that value. A token's name never
+ * reads as a number, so `spacing="4"` is the step wherever `spacing={4}` is a length.
+ *
+ * Read wherever a bag value meets a style prop: the canvas split, a rule's declarations, and the
+ * emitted runtime, which carries the same facts in its table.
+ */
+declare function stylePropNumberCss(config: Config, path: string, value: unknown): string | undefined;
+/**
+ * The value a bare number on a style prop spelled before a value's type decided what it names: `gap: 6`
+ * → `'6'`, where `'6'` is one of the prop's values (UDS-4828). `undefined` when the prop reads the
+ * number itself — a number it declares (`columns={3}`) or a length in its unit (`maxWidth={600}`) —
+ * and when no value is spelled that way, which validation refuses.
+ *
+ * Read where a design meets numbers written under the old reading: rows stored before the change,
+ * a model's unquoted YAML, the code view's `gap={6}`.
+ */
+declare function stylePropNumberName(config: Config, path: string, value: unknown): string | undefined;
+/**
+ * Why a style prop can't read a bare number in a unit, or `undefined` when it can — what an editor
+ * says beside its unit picker instead of offering one the config refuses.
+ */
+declare function stylePropNumberUnitRefusal(config: Config, path: string): string | undefined;
+/**
+ * A style prop's values whose names are numbers it doesn't declare as numbers — a spacing step `'4'`,
+ * an opacity `'50'`. On a prop with a unit these and a bare number part ways: `opacity="50"` is the
+ * value, `opacity={50}` is 50 in the unit. Empty when no value is named that way.
+ */
+declare function stylePropNumberNamedLeaves(config: Config, path: string): string[];
+/**
+ * `props` with `rewrite` applied to each bare number on a style prop — in modifier blocks, and in
+ * `layerProps` bags against the layer's own component. `rewrite` gets the style property the key writes
+ * and the number, and answers what to store instead, or `undefined` to keep it. The same object when
+ * nothing changed, so a reader can tell a row it rewrote from one it didn't.
+ */
+declare function rewriteStyleNumbers(config: Config, elementType: string | undefined, props: Record<string, unknown>, rewrite: (path: string, value: number) => string | undefined, depth?: number): Record<string, unknown>;
+/** `props` with each bare number spelled as the value it names ({@link stylePropNumberName}). */
+declare function nameStyleNumbers(config: Config, elementType: string | undefined, props: Record<string, unknown>): Record<string, unknown>;
+/**
+ * A bare number on a style prop as it painted while the prop read numbers in `before` — a unit, or none
+ * — written in a form that paints the same whatever unit the prop reads in: the value it names (`'6'`)
+ * or its bracket literal (`[6px]`). `undefined` when it painted nothing then, and for a number the prop
+ * declares (`columns={3}`), which reads the same under any unit.
+ *
+ * What a stored number becomes when its prop's unit changes, so the change doesn't reread it: `gap: 6`
+ * named the token `'6'` until `gap` took `px`, and stays that token after.
+ */
+declare function styleNumberAsPainted(config: Config, path: string, value: number, before: StylePropNumberUnit | undefined): string | undefined;
+/**
+ * The style properties whose bare-number reading differs between two versions of a config, each with
+ * the unit it read numbers in before (`undefined` for none) — what {@link pinStyleNumbers} takes. A
+ * property only one version holds isn't a change of reading.
+ */
+declare function styleNumberReadingChanges(before: Config, after: Config): Map<string, StylePropNumberUnit | undefined>;
+/**
+ * `props` with each bare number on a prop whose unit changed written as it painted before
+ * ({@link styleNumberAsPainted}). `before` maps each such style property's path to the unit it read
+ * numbers in before the change, `undefined` for none.
+ */
+declare function pinStyleNumbers(config: Config, elementType: string | undefined, props: Record<string, unknown>, before: ReadonlyMap<string, StylePropNumberUnit | undefined>): Record<string, unknown>;
 /**
  * The token a style-prop leaf binds, as a qualified path — `('bg', 'brand')` → `color/brand`.
  * `undefined` when the leaf is a keyword the system declared rather than a token (`row`,
@@ -732,4 +815,4 @@ declare function propValueFromAxis(config: Config, path: string, prop: string, v
 /** The `value` a string, number or boolean prop declares as its default, per prop. */
 declare function declaredPropDefaults(props: Record<string, unknown> | undefined): Record<string, unknown>;
 //#endregion
-export { IconTool, IndexedPreviewCondition, PreviewMatrix, PropDeclaration, StyleDeclarationGroup, StylePropEntry, StylePropertyItem, VarNaming, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declarationKeyName, declaredPropDefaults, declaredPropRouting, declaresCssVariable, glyphComponentOf, glyphLibrariesOf, glyphPropsOf, heldLinked, holdingPreviewConditions, iconToolAxisOptions, iconToolFor, iconToolOf, iconToolsOf, isCustomPropertyKey, keyedPreviewConditions, linkedVarNaming, literalValueOf, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, refListOf, renderInterpolated, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarationGroups, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, tokenReference, validateComponentProps };
+export { IconTool, IndexedPreviewCondition, PreviewMatrix, PropDeclaration, StyleDeclarationGroup, StylePropEntry, StylePropertyItem, VarNaming, authoredBag, authoredValue, bodyNumberLeaves, bodyNumberUnit, className, cssPropValue, cssVar, cssVarRef, declarationKeyName, declaredPropDefaults, declaredPropRouting, declaresCssVariable, glyphComponentOf, glyphLibrariesOf, glyphPropsOf, heldLinked, holdingPreviewConditions, iconToolAxisOptions, iconToolFor, iconToolOf, iconToolsOf, isCustomPropertyKey, keyedPreviewConditions, linkedVarNaming, literalValueOf, memberFromLeaf, memberLeaves, nameStyleNumbers, negatedCssValue, opacityPercentage, pinStyleNumbers, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, refListOf, renderInterpolated, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, rewriteStyleNumbers, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarationGroups, styleDeclarations, styleNumberAsPainted, styleNumberReadingChanges, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropNumberCss, stylePropNumberLeaf, stylePropNumberLeaves, stylePropNumberName, stylePropNumberNamedLeaves, stylePropNumberUnit, stylePropNumberUnitRefusal, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, tokenReference, validateComponentProps };

package/dist/framework/projections.js

@@ -9,7 +9,7 @@ import { listedIn } from "./utils/enumerated.js";
 import "../entities/system/Modifier.js";
 import { createSliceMemo } from "./memo.js";
 import { classPrefixOf, prefixed, varPrefixOf } from "../entities/system/Settings.js";
-import { StyleProperty, leavesOfStylePropValue } from "../entities/system/StyleProperty.js";
+import { StyleProperty, leavesOfStylePropValue, numberUnitRefusal } from "../entities/system/StyleProperty.js";
 import { isConditionalPreview, storedPreview, unconditionalPreviewProps } from "./preview-store.js";
 //#region src/framework/projections.ts
 /**
@@ -457,6 +457,265 @@ function stylePropValueFromLeaf(config, path, leaf) {
 	return stylePropEntries(config, path).find((entry) => entry.leaf === leaf)?.value;
 }
 /**
+* The leaves a style property's body declares AS NUMBERS: a numeric literal (`values: [1, 2]`) or a
+* numeric alias (`{ alias: 3, value: 'repeat(3, minmax(0, 1fr))' }`). Only these match a bare number
+* — `columns={3}` — while a token's name is a string however it reads (`spacing="4"`, never
+* `spacing={4}`), as is a string alias.
+*/
+function bodyNumberLeaves(stored) {
+	const values = stored?.values ?? [];
+	const out = [];
+	for (const entry of values) if (typeof entry === "number") out.push(String(entry));
+	else if (entry && typeof entry === "object" && "alias" in entry && typeof entry.alias === "number") out.push(String(entry.alias));
+	return out;
+}
+/** The leaves a style prop declares as numbers ({@link StylePropLeaf.numeric}), by path. */
+function stylePropNumberLeaves(config, path) {
+	return stylePropEntries(config, path).filter((entry) => entry.numeric).map((entry) => entry.leaf);
+}
+/**
+* The leaf a bare number names on a style prop — `columns={3}` → `'3'` — or `undefined` when the
+* prop declares no such number (`spacing={4}`, whose `4` is a token's name) or the value isn't a
+* number.
+*/
+function stylePropNumberLeaf(config, path, value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return void 0;
+	const leaf = String(value);
+	return stylePropNumberLeaves(config, path).includes(leaf) ? leaf : void 0;
+}
+/** The unit a style property's body reads a bare number in, or `undefined` when it takes none. */
+function bodyNumberUnit(stored) {
+	const body = stored;
+	if (!body?.properties?.length || body.selector || Object.keys(body.declarations ?? {}).length > 0) return;
+	return typeof body.arbitrary === "string" ? body.arbitrary : void 0;
+}
+/** The unit a style prop reads a bare number in (`maxWidth={600}` with `arbitrary: 'px'`), or
+*  `undefined` when it takes none. */
+function stylePropNumberUnit(config, path) {
+	return bodyNumberUnit(config.resolve("style-property", path)?.toJSON());
+}
+/**
+* The CSS a bare number on a style prop is written as, in the unit the prop declares (`arbitrary`):
+* `maxWidth={600}` with `arbitrary: 'px'` is `600px`, `lineHeight={1.5}` with `arbitrary: 'unitless'` is
+* `1.5`. `undefined` for a prop that declares none, for any other value, and for a number the
+* prop declares as a value ({@link stylePropNumberLeaf}), which is that value. A token's name never
+* reads as a number, so `spacing="4"` is the step wherever `spacing={4}` is a length.
+*
+* Read wherever a bag value meets a style prop: the canvas split, a rule's declarations, and the
+* emitted runtime, which carries the same facts in its table.
+*/
+function stylePropNumberCss(config, path, value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return void 0;
+	const unit = stylePropNumberUnit(config, path);
+	if (unit === void 0) return void 0;
+	if (stylePropNumberLeaf(config, path, value) !== void 0) return void 0;
+	return unit === "unitless" ? String(value) : `${value}${unit}`;
+}
+/**
+* The value a bare number on a style prop spelled before a value's type decided what it names: `gap: 6`
+* → `'6'`, where `'6'` is one of the prop's values (UDS-4828). `undefined` when the prop reads the
+* number itself — a number it declares (`columns={3}`) or a length in its unit (`maxWidth={600}`) —
+* and when no value is spelled that way, which validation refuses.
+*
+* Read where a design meets numbers written under the old reading: rows stored before the change,
+* a model's unquoted YAML, the code view's `gap={6}`.
+*/
+function stylePropNumberName(config, path, value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return void 0;
+	if (stylePropNumberLeaf(config, path, value) !== void 0) return void 0;
+	if (stylePropNumberUnit(config, path) !== void 0) return void 0;
+	const leaf = String(value);
+	return stylePropEntries(config, path).some((entry) => entry.leaf === leaf) ? leaf : void 0;
+}
+/**
+* Why a style prop can't read a bare number in a unit, or `undefined` when it can — what an editor
+* says beside its unit picker instead of offering one the config refuses.
+*/
+function stylePropNumberUnitRefusal(config, path) {
+	const body = config.resolve("style-property", path)?.toJSON();
+	if (!body) return void 0;
+	return numberUnitRefusal({
+		...body,
+		properties: body.properties ?? []
+	});
+}
+/**
+* A style prop's values whose names are numbers it doesn't declare as numbers — a spacing step `'4'`,
+* an opacity `'50'`. On a prop with a unit these and a bare number part ways: `opacity="50"` is the
+* value, `opacity={50}` is 50 in the unit. Empty when no value is named that way.
+*/
+function stylePropNumberNamedLeaves(config, path) {
+	const numeric = new Set(stylePropNumberLeaves(config, path));
+	return stylePropEntries(config, path).map((entry) => entry.leaf).filter((leaf) => leaf !== "" && !numeric.has(leaf) && Number.isFinite(Number(leaf)) && String(Number(leaf)) === leaf);
+}
+/**
+* `props` with `rewrite` applied to each bare number on a style prop — in modifier blocks, and in
+* `layerProps` bags against the layer's own component. `rewrite` gets the style property the key writes
+* and the number, and answers what to store instead, or `undefined` to keep it. The same object when
+* nothing changed, so a reader can tell a row it rewrote from one it didn't.
+*/
+function rewriteStyleNumbers(config, elementType, props, rewrite, depth = 0) {
+	let next;
+	const set = (key, value) => {
+		next ??= { ...props };
+		next[key] = value;
+	};
+	for (const [key, value] of Object.entries(props)) if (key === "layerProps") {
+		if (depth >= 5 || !isBag(value)) continue;
+		const layers = ((elementType ? config.resolve("component", pathOf(elementType)) : void 0)?.body)?.layers;
+		let layerProps;
+		for (const [layer, bag] of Object.entries(value)) {
+			if (!isBag(bag)) continue;
+			const element = layers?.[layer];
+			const written = rewriteStyleNumbers(config, isRef(element) ? pathOf(element) : void 0, bag, rewrite, depth + 1);
+			if (written !== bag) {
+				layerProps ??= { ...value };
+				layerProps[layer] = written;
+			}
+		}
+		if (layerProps) set(key, layerProps);
+	} else if (key.startsWith("_")) {
+		if (!isBag(value)) continue;
+		const written = rewriteStyleNumbers(config, elementType, value, rewrite, depth);
+		if (written !== value) set(key, written);
+	} else if (typeof value === "number" && Number.isFinite(value)) {
+		const path = stylePropertyPathFor({
+			config,
+			through: [elementType],
+			key
+		});
+		const written = path === void 0 ? void 0 : rewrite(path, value);
+		if (written !== void 0) set(key, written);
+	}
+	return next ?? props;
+}
+/** `props` with each bare number spelled as the value it names ({@link stylePropNumberName}). */
+function nameStyleNumbers(config, elementType, props) {
+	return rewriteStyleNumbers(config, elementType, props, (path, value) => stylePropNumberName(config, path, value));
+}
+/**
+* A bare number on a style prop as it painted while the prop read numbers in `before` — a unit, or none
+* — written in a form that paints the same whatever unit the prop reads in: the value it names (`'6'`)
+* or its bracket literal (`[6px]`). `undefined` when it painted nothing then, and for a number the prop
+* declares (`columns={3}`), which reads the same under any unit.
+*
+* What a stored number becomes when its prop's unit changes, so the change doesn't reread it: `gap: 6`
+* named the token `'6'` until `gap` took `px`, and stays that token after.
+*/
+function styleNumberAsPainted(config, path, value, before) {
+	if (!Number.isFinite(value)) return void 0;
+	if (stylePropNumberLeaf(config, path, value) !== void 0) return void 0;
+	if (before !== void 0) return `[${value}${before === "unitless" ? "" : before}]`;
+	const leaf = String(value);
+	return stylePropEntries(config, path).some((entry) => entry.leaf === leaf) ? leaf : void 0;
+}
+/** A keyed collection with `rewrite` applied to each entry; the same object when none changed. */
+function eachMember(collection, rewrite) {
+	if (!isBag(collection)) return collection;
+	let next;
+	for (const [key, entry] of Object.entries(collection)) {
+		const written = isBag(entry) ? rewrite(entry) : entry;
+		if (written !== entry) {
+			next ??= { ...collection };
+			next[key] = written;
+		}
+	}
+	return next ?? collection;
+}
+/**
+* A stored component or canvas-role body with {@link pinStyleNumbers} applied to every bag it keeps: a
+* component's style rules (each layer's bag against the component that layer renders), `defaultProps`
+* and `preview` props, an `extend` delta's the same way, and the `defaultProps` a canvas role inserts its
+* component with. The same object when nothing changed.
+*/
+function pinBodyStyleNumbers(config, kind, body, before, self) {
+	if (kind === "canvas-role") {
+		if (!Array.isArray(body.entries)) return body;
+		let changed = false;
+		const entries = body.entries.map((entry) => {
+			if (!isBag(entry) || !isBag(entry.defaultProps)) return entry;
+			const defaultProps = pinStyleNumbers(config, isRef(entry.component) ? pathOf(entry.component) : void 0, entry.defaultProps, before);
+			if (defaultProps === entry.defaultProps) return entry;
+			changed = true;
+			return {
+				...entry,
+				defaultProps
+			};
+		});
+		return changed ? {
+			...body,
+			entries
+		} : body;
+	}
+	if (kind !== "component") return body;
+	if (isBag(body.extend) && isRef(body)) {
+		const extend = pinBodyStyleNumbers(config, kind, body.extend, before, pathOf(body));
+		return extend === body.extend ? body : {
+			...body,
+			extend
+		};
+	}
+	const layers = isBag(body.layers) ? body.layers : {};
+	const layerType = (layer) => {
+		const element = layers[layer];
+		return isRef(element) ? pathOf(element) : void 0;
+	};
+	const pin = (type, bag) => isBag(bag) ? pinStyleNumbers(config, type, bag, before) : bag;
+	let next;
+	const set = (field, value) => {
+		if (value === body[field]) return;
+		next ??= { ...body };
+		next[field] = value;
+	};
+	set("styles", eachMember(body.styles, (rule) => {
+		if (!isBag(rule.layers)) return rule;
+		let written;
+		for (const [layer, bag] of Object.entries(rule.layers)) {
+			const pinned = pin(layerType(layer), bag);
+			if (pinned !== bag) {
+				written ??= { ...rule.layers };
+				written[layer] = pinned;
+			}
+		}
+		return written ? {
+			...rule,
+			layers: written
+		} : rule;
+	}));
+	set("defaultProps", pin(self, body.defaultProps));
+	set("preview", eachMember(body.preview, (entry) => {
+		const props = pin(self, entry.props);
+		return props === entry.props ? entry : {
+			...entry,
+			props
+		};
+	}));
+	return next ?? body;
+}
+/**
+* The style properties whose bare-number reading differs between two versions of a config, each with
+* the unit it read numbers in before (`undefined` for none) — what {@link pinStyleNumbers} takes. A
+* property only one version holds isn't a change of reading.
+*/
+function styleNumberReadingChanges(before, after) {
+	const changes = /* @__PURE__ */ new Map();
+	for (const prop of StyleProperty.list(after)) {
+		if (!before.resolve("style-property", prop.path)) continue;
+		const was = stylePropNumberUnit(before, prop.path);
+		if (was !== stylePropNumberUnit(after, prop.path)) changes.set(prop.path, was);
+	}
+	return changes;
+}
+/**
+* `props` with each bare number on a prop whose unit changed written as it painted before
+* ({@link styleNumberAsPainted}). `before` maps each such style property's path to the unit it read
+* numbers in before the change, `undefined` for none.
+*/
+function pinStyleNumbers(config, elementType, props, before) {
+	if (before.size === 0) return props;
+	return rewriteStyleNumbers(config, elementType, props, (path, value) => before.has(path) ? styleNumberAsPainted(config, path, value, before.get(path)) : void 0);
+}
+/**
 * The token a style-prop leaf binds, as a qualified path — `('bg', 'brand')` → `color/brand`.
 * `undefined` when the leaf is a keyword the system declared rather than a token (`row`,
 * `flex-start`), or isn't in the prop's domain at all.
@@ -1045,9 +1304,10 @@ function propDeclarations({ config, body, namespace }) {
 * A flag is written bare (`truncate: true`) and its entry sits under the empty leaf, which is the same
 * entry the class `.uds-truncate` is built from. `false` is the prop's absence and has no entry.
 */
-function leafAuthoredFor(value) {
+function leafAuthoredFor(config, key, value) {
 	if (typeof value === "boolean") return value ? "" : void 0;
-	if (typeof value === "string" || typeof value === "number") return String(value);
+	if (typeof value === "string") return value;
+	if (typeof value === "number") return stylePropNumberLeaf(config, key, value);
 }
 /**
 * The declarations a bag sets on the element itself. Declarations a prop scopes to a `selector` or a
@@ -1124,7 +1384,7 @@ function styleDeclarationGroups({ config, bag, namespace }) {
 			const keyed = refOfKey(property);
 			return keyed ? cssVar(config, "token", pathOf(keyed), namespace) : property;
 		}) : [];
-		const authoredLeafValue = leafAuthoredFor(value);
+		const authoredLeafValue = leafAuthoredFor(config, key, value);
 		const entry = authoredLeafValue === void 0 ? void 0 : stylePropEntries(config, key).find((candidate) => candidate.leaf === authoredLeafValue);
 		if (entry?.declarations) {
 			for (const [key, declaredValue] of Object.entries(entry.declarations)) target[declarationKeyName({
@@ -1171,11 +1431,14 @@ function styleDeclarationGroups({ config, bag, namespace }) {
 }
 /** One bag value as CSS text, or `undefined` for a flag turned off. */
 function renderBagValue({ config, key, value, namespace }) {
+	const number = stylePropNumberCss(config, key, value);
+	if (number !== void 0) return number;
 	let resolved = value;
-	if (typeof value === "string") {
-		const qualified = stylePropValueFromLeaf(config, key, value);
+	const leaf = typeof value === "string" ? value : stylePropNumberLeaf(config, key, value);
+	if (leaf !== void 0) {
+		const qualified = stylePropValueFromLeaf(config, key, leaf);
 		if (qualified !== void 0) resolved = qualified;
-	}
+	} else if (typeof value === "number") return;
 	if (typeof value === "boolean") {
 		if (!value) return void 0;
 		const bare = stylePropValueFromLeaf(config, key, "");
@@ -1536,6 +1799,15 @@ function validateComponentProps(config, componentPath, props) {
 			errors.push(`unknown prop \`${name}\``);
 			continue;
 		}
+		if (decl.type === "styleProperty" && isRef(decl.value) && stylePropNumberCss(config, splitRef(decl.value.__ref).qualifiedPath, value) !== void 0) continue;
+		if (decl.type === "styleProperty" && typeof value === "number" && isRef(decl.value)) {
+			const path = splitRef(decl.value.__ref).qualifiedPath;
+			if (stylePropNumberLeaf(config, path, value) === void 0) {
+				const declared = stylePropNumberLeaves(config, path);
+				errors.push(declared.length > 0 ? `\`${name}\`: ${value} is not one of the numbers it takes (${declared.join(" | ")})` : `\`${name}\`: takes no number; a value named \`${value}\` is written as the string '${value}'`);
+			}
+			continue;
+		}
 		const domain = propValueDomain(config, decl);
 		if (domain && !domain.accepts(String(value))) {
 			const shown = domain.leaves.slice(0, 8).map((leaf) => `'${leaf}'`).join(" | ");
@@ -1729,4 +2001,4 @@ function declaredPropDefaults(props) {
 	return out;
 }
 //#endregion
-export { LAYER_PROPS, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declarationKeyName, declaredPropDefaults, declaredPropRouting, declaresCssVariable, fontStackOf, glyphComponentOf, glyphLibrariesOf, glyphPropsOf, glyphPropsOfBody, heldLinked, holdingPreviewConditions, iconToolAxisOptions, iconToolFor, iconToolOf, iconToolsOf, isCustomPropertyKey, keyedPreviewConditions, layerPropsErrors, linkedVarNaming, literalValueOf, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, refListOf, renderInterpolated, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarationGroups, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, takenByForward, tokenReference, validateComponentProps };
+export { LAYER_PROPS, authoredBag, authoredValue, bodyNumberLeaves, bodyNumberUnit, className, cssPropValue, cssVar, cssVarRef, declarationKeyName, declaredPropDefaults, declaredPropRouting, declaresCssVariable, fontStackOf, glyphComponentOf, glyphLibrariesOf, glyphPropsOf, glyphPropsOfBody, heldLinked, holdingPreviewConditions, iconToolAxisOptions, iconToolFor, iconToolOf, iconToolsOf, isCustomPropertyKey, keyedPreviewConditions, layerPropsErrors, linkedVarNaming, literalValueOf, memberFromLeaf, memberLeaves, nameStyleNumbers, negatedCssValue, opacityPercentage, pinBodyStyleNumbers, pinStyleNumbers, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, refListOf, renderInterpolated, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, rewriteStyleNumbers, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarationGroups, styleDeclarations, styleNumberAsPainted, styleNumberReadingChanges, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropNumberCss, stylePropNumberLeaf, stylePropNumberLeaves, stylePropNumberName, stylePropNumberNamedLeaves, stylePropNumberUnit, stylePropNumberUnitRefusal, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, takenByForward, tokenReference, validateComponentProps };

package/dist/framework/render-spec.js

@@ -1216,6 +1216,7 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 		routes.push(route);
 		valueRoutes.set(route.layer, routes);
 	}
+	const forwardsClassName = [...valueRoutes.values()].some((routes) => routes.some((route) => route.from === "className"));
 	const supplied = {
 		...declaredDefaults,
 		...body.defaultProps ?? {},
@@ -1356,7 +1357,8 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 			...layerProps[layer],
 			className: classesFor(config, path, layer, state, [
 				isRoot ? styleClasses : void 0,
-				isRoot ? instanceProps.className : void 0,
+				isRoot && !forwardsClassName ? instanceProps.className : void 0,
+				...(valueRoutes.get(layer) ?? []).filter(({ into }) => into === "className").map(({ from }) => state[from]),
 				layerProps[layer]?.className
 			]) || void 0
 		} : {

package/dist/framework/schema-version.d.ts

@@ -15,7 +15,7 @@ import { Patch, SerializedConfig } from "./Config.js";
  * sets this constant to its own older timestamp; the merge ref then carries a registered migration
  * newer than the constant, and the assertion fails until the author re-mints.
  */
-declare const CURRENT_SCHEMA_VERSION = 20261007182932;
+declare const CURRENT_SCHEMA_VERSION = 20261007210309;
 /** What the walkers need to see of an envelope — loose on purpose, so a typed `SerializedConfig`
  *  and a raw old-shape record both flow in without casts. */
 interface VersionStamped {

package/dist/framework/schema-version.js

@@ -13,7 +13,7 @@ import { ConfigFormatError } from "./rejection.js";
 * sets this constant to its own older timestamp; the merge ref then carries a registered migration
 * newer than the constant, and the assertion fails until the author re-mints.
 */
-const CURRENT_SCHEMA_VERSION = 20261007182932;
+const CURRENT_SCHEMA_VERSION = 20261007210309;
 /** The mint that moved `options` into the `settings` kind — restated here, rather than imported
 *  from the migration that owns it, because that migration imports this module. */
 const SETTINGS_AS_KIND_VERSION = 20260908171448;
@@ -45,7 +45,7 @@ function registerSchemaMigrations(...migrations) {
 	for (const migration of migrations) {
 		if (migration.version !== 1 && !isMintTimestamp(migration.version)) throw new Error(`Schema migration version ${migration.version} is not a mint timestamp — mint one with \`date +%Y%m%d%H%M%S\`, like a supabase migration.`);
 		if (REGISTERED.has(migration.version)) throw new Error(`A schema migration at version ${migration.version} is already registered.`);
-		if (migration.version > 20261007182932) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
+		if (migration.version > 20261007210309) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
 		REGISTERED.set(migration.version, migration);
 	}
 }
@@ -102,7 +102,7 @@ function pendingFor(version, target, options) {
 * Already-current input passes through untouched — same reference, so hot paths pay nothing.
 */
 function upgradeSerializedConfig(json, options) {
-	const target = options?.target ?? 20261007182932;
+	const target = options?.target ?? 20261007210309;
 	const version = detectedWireVersion(json);
 	if (version > target) throw new SchemaVersionTooNew(version, target);
 	const raw = json;
@@ -160,7 +160,7 @@ function upgradedSources(json, options) {
 * meaning under the current schema and replay skips it — reported by the caller, not swallowed here.
 */
 function upgradePatch(patch, writtenAt, options) {
-	const target = options?.target ?? 20261007182932;
+	const target = options?.target ?? 20261007210309;
 	if (writtenAt > target) throw new SchemaVersionTooNew(writtenAt, target);
 	let current = patch;
 	for (const migration of pendingFor(writtenAt, target, options)) {
@@ -179,7 +179,7 @@ function upgradePatch(patch, writtenAt, options) {
 * stamp would cause.
 */
 function upgradeDraftEntries(draft, options) {
-	const target = options?.target ?? 20261007182932;
+	const target = options?.target ?? 20261007210309;
 	const entries = [];
 	const held = [];
 	const retired = [];

package/dist/framework/value-domain.js

@@ -1,6 +1,6 @@
 import { isRef, kindOf, memberOf, pathOf, ref, refSchema } from "./utils/refs.js";
 import { listedIn } from "./utils/enumerated.js";
-import { memberFromLeaf, memberLeaves, refListOf, stylePropValueFromLeaf, stylePropValueLeaves } from "./projections.js";
+import { bodyNumberLeaves, bodyNumberUnit, memberFromLeaf, memberLeaves, refListOf, stylePropValueFromLeaf, stylePropValueLeaves } from "./projections.js";
 import { z } from "zod";
 //#region src/framework/value-domain.ts
 /**
@@ -132,12 +132,12 @@ function buildRefDomainSchema(target, config, seen) {
 	if (enumerated === void 0) return z.unknown();
 	const property = stylePropertyOf(target, config);
 	const also = [];
-	if (property?.arbitrary === true) also.push(arbitraryValue);
+	if (property?.arbitrary) also.push(arbitraryValue);
 	if (isFlag(property)) also.push(z.boolean());
-	if (property !== void 0) {
-		const leaf = enumerated;
-		also.push(z.number().transform(String).pipe(leaf));
-	}
+	const numbered = oneOf(bodyNumberLeaves(property));
+	if (numbered !== void 0) also.push(z.number().transform(String).pipe(numbered));
+	const unit = bodyNumberUnit(property);
+	if (unit) also.push(z.number().finite());
 	const own = config.entityOf(kindOf(target))?.authoredValue?.({
 		config,
 		target,
@@ -150,8 +150,9 @@ function buildRefDomainSchema(target, config, seen) {
 		refSchema
 	], { error: () => {
 		const forms = [`one of ${spellValues(leaves)}`];
-		if (property?.arbitrary === true) forms.push("a bracketed literal such as `[13px]`");
-		if (property !== void 0) forms.push("a number spelling one of those leaves");
+		if (property?.arbitrary) forms.push("a bracketed literal such as `[13px]`");
+		if (unit) forms.push(unit === "unitless" ? "a number, written as it is" : `a number of \`${unit}\` such as \`600\``);
+		else if (numbered !== void 0) forms.push("a number it declares as a value");
 		if (isFlag(property)) forms.push("a boolean");
 		return `${forms.join(", ")}, or a ref to one of those tokens (\`{ "__ref": "${target}/<name>" }\`)`;
 	} }).transform((value) => typeof value === "string" ? refForLeaf(target, value, config) ?? value : value);