@yahoo/uds-create-config 4.53.2 → 4.55.0

package/dist/framework/projections.d.ts

@@ -53,8 +53,26 @@ declare function heldLinked({
  * The group segment is kebab-cased and the leaf is not, which is not a stylistic choice: it's the
  * shape the emitted stylesheet declares (`--{prefix}-{kebabCase(namespace)}-{safeTokenName(name)}`).
  * Deriving it any other way produces a `var()` that resolves to nothing for any camelCase group.
+ *
+ * Under the config's own naming, a token's own `cssVariable` is its whole name (`--spacing`), or
+ * the exact name when it starts with `--` (`--mantine-color-primary`, whatever the prefix), and
+ * otherwise the nearest token group that declares a `cssPrefix` spells its part of the name:
+ * `fontSize/sm` under `fontSize: { cssPrefix: 'text' }` is `--text-sm`, and an empty `cssPrefix`
+ * drops the group's segment. An empty config prefix drops its own.
  */
 declare function cssVar(config: Config, _kind: string, path: string, varPrefix?: VarNaming): string;
+/**
+ * Whether a token is declared as a custom property: its own `cssVariable`, else the nearest group's
+ * `cssVariables`, else yes. One that isn't is written into each value that uses it, as Tailwind's
+ * `@theme inline` does.
+ */
+declare function declaresCssVariable(config: Config, path: string): boolean;
+/**
+ * How CSS reaches a token: `var(--…)` when it declares a variable, else its value written in place,
+ * as the stylesheet writes it. For anything that paints a token outside a style prop, a swatch, an
+ * effect colour, a background.
+ */
+declare function tokenReference(config: Config, path: string): string;
 /** `var(--…)` — the CSS reference to {@link cssVar}. */
 declare function cssVarRef(config: Config, kind: string, path: string, varPrefix?: VarNaming): string;
 /** The utility/class name for an entity — `<prefix>-<path-dashed>`. A class is one identifier, so
@@ -238,6 +256,13 @@ declare function resolveFieldValue(config: Config, kind: string, path: string, f
 /** A token's value with alias refs chased to the base literal — {@link resolveFieldValue} for the one
  *  field every token consumer asks about, narrowed to the scalar a display or a stylesheet can use. */
 declare function resolveTokenValue(config: Config, path: string, seen?: Set<string>): string | number | undefined;
+/**
+ * A stored value as the literal it comes to: a string or a number as itself, an OKLCH colour as its
+ * CSS, arithmetic evaluated over its operands' literals (`multiply(Token.ref('spacing'), 4)` with
+ * `spacing` at `0.25rem` is `1rem`), and a token ref as that token's literal. `undefined` for a value
+ * that is no single literal (a shadow, a gradient) or a ref that resolves to nothing.
+ */
+declare function literalValueOf(config: Config, value: unknown): string | number | undefined;
 /**
  * The literal a token resolves to under an override condition: its own override there when it holds
  * one, else its base value, with a ref along the way chased under the same condition. That is how the
@@ -245,6 +270,20 @@ declare function resolveTokenValue(config: Config, path: string, seen?: Set<stri
  * for a dark cell paints what dark will show. `null` is the base, the same as {@link resolveTokenValue}.
  */
 declare function resolveTokenValueUnder(config: Config, path: string, condition: string | null, seen?: Set<string>): string | number | undefined;
+/**
+ * A string's interpolated refs written as their tokens: `blur({token:blur/sm})` is
+ * `blur(var(--blur-sm))`. A ref opening a `var(` is the variable's name, so a fallback can follow it:
+ * `var({token:tw/leading}, 1.5)` is `var(--tw-leading, 1.5)`.
+ */
+declare function renderInterpolated({
+  config,
+  text,
+  varPrefix
+}: {
+  readonly config: Config;
+  readonly text: string;
+  readonly varPrefix?: VarNaming;
+}): string;
 /** A style-bag value → its CSS string: a token ref (or a bare token path) becomes a
  *  `var(--…)` reference (so mode/theme overrides still flow), anything else is the literal.
  *
@@ -254,7 +293,9 @@ declare function resolveTokenValueUnder(config: Config, path: string, condition:
  *  ordinary call — it is `config`'s own prefix. */
 declare function renderStyleValue(config: Config, value: unknown, varPrefix?: VarNaming): string;
 /**
- * The value a negating prop paints — `calc(<value> * -1)`.
+ * The value a negating prop paints: a length or a percentage with a minus sign (`-1px`, `-100%`, and
+ * a zero as it is), a scale step's multiplier negated (`calc(var(--spacing) * -4)`), and anything
+ * else, a `var()` included, as `calc(<value> * -1)` — the spellings Tailwind writes.
  *
  * `calc` rather than a computed literal because the value is usually a `var(--…)`: the token it names
  * has to stay a reference, so a mode override or a theme swap still reaches it. It's applied at the
@@ -371,10 +412,50 @@ declare function routedBag({
   readonly through?: readonly (string | undefined)[];
   readonly bag: Record<string, unknown>;
 }): Record<string, unknown>;
+/** A declaration's key as CSS: a property as itself, a token's key `{token:tw/blur}` as the variable
+ *  the token declares. */
+declare function declarationKeyName({
+  config,
+  key,
+  namespace
+}: {
+  readonly config: Config;
+  readonly key: string;
+  readonly namespace?: VarNaming;
+}): string;
+/**
+ * One block of a bag's declarations: those on the element itself, or those a prop writes under its
+ * `selector` (`&` standing for the element) or a value writes under an at-rule.
+ */
+interface StyleDeclarationGroup {
+  /** The prop's `selector`, with `&` for the element. Absent for the element's own declarations. */
+  readonly selector?: string;
+  /** The at-rule prelude the block sits in (`@media (width >= 40rem)`). */
+  readonly atRule?: string;
+  readonly declarations: Record<string, string>;
+}
+/**
+ * The declarations a bag sets on the element itself. Declarations a prop scopes to a `selector` or a
+ * value scopes to an at-rule are not the element's, so they are left out; a stylesheet reads them
+ * from {@link styleDeclarationGroups}.
+ */
 declare function styleDeclarations({
   config,
   bag,
   namespace
+}: {
+  readonly config: Config;
+  readonly bag: Record<string, unknown>; /** See {@link styleDeclarationGroups}. */
+  readonly namespace?: VarNaming;
+}): Record<string, string>;
+/**
+ * A bag's declarations in the blocks they apply in: the element's own first, then each `selector`
+ * and at-rule block in the order the bag first reaches it. A block that sets nothing is left out.
+ */
+declare function styleDeclarationGroups({
+  config,
+  bag,
+  namespace
 }: {
   readonly config: Config;
   readonly bag: Record<string, unknown>;
@@ -387,7 +468,7 @@ declare function styleDeclarations({
    * nothing on the page declares, which computes to the inherited value and paints silently wrong.
    */
   readonly namespace?: VarNaming;
-}): Record<string, string>;
+}): StyleDeclarationGroup[];
 /**
  * An opacity value as a `color-mix()` share.
  *
@@ -631,4 +712,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, StylePropEntry, StylePropertyItem, VarNaming, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropDefaults, declaredPropRouting, glyphComponentOf, glyphLibrariesOf, glyphPropsOf, heldLinked, holdingPreviewConditions, iconToolAxisOptions, iconToolFor, iconToolOf, iconToolsOf, keyedPreviewConditions, linkedVarNaming, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, refListOf, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };
+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, 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 };

package/dist/framework/projections.js

@@ -1,4 +1,6 @@
-import { isRef, kindOf, memberOf, pathOf, ref, refLeaf, sourceOf, splitRef } from "./utils/refs.js";
+import { declarationText, hasRefMarker, isRef, kindOf, memberOf, pathOf, ref, refLeaf, refOfKey, replaceRefMarkers, sourceOf, splitRef } from "./utils/refs.js";
+import { evaluateCalc, isDivide, isMultiply, leadingNumber } from "../entities/system/calc.js";
+import { isOklchColor, renderOklch } from "../entities/system/color.js";
 import { isComposedValue, renderComposedValue } from "../entities/system/composed-values.js";
 import { modifierCategory } from "../entities/system/modifier-axis.js";
 import { forwardedPropName, forwardsOf, rootLayerOf } from "../entities/system/element.js";
@@ -6,7 +8,7 @@ import { fontFamilyStack } from "../entities/system/Font.js";
 import { listedIn } from "./utils/enumerated.js";
 import "../entities/system/Modifier.js";
 import { createSliceMemo } from "./memo.js";
-import { classPrefixOf, varPrefixOf } from "../entities/system/Settings.js";
+import { classPrefixOf, prefixed, varPrefixOf } from "../entities/system/Settings.js";
 import { StyleProperty, leavesOfStylePropValue } from "../entities/system/StyleProperty.js";
 import { isConditionalPreview, storedPreview, unconditionalPreviewProps } from "./preview-store.js";
 //#region src/framework/projections.ts
@@ -53,7 +55,10 @@ function domainCache(cache, config) {
 * construction, and already the only name resolution uses. So a borrowed variable lives in the
 * consumer's namespace, qualified by the pin it came through.
 */
-const sourceVarPrefix = (config, slug) => `${varPrefixOf(config)}-${kebab(slug)}`;
+const sourceVarPrefix = (config, slug) => prefixed({
+	prefix: varPrefixOf(config),
+	name: kebab(slug)
+});
 /**
 * The name each of a linked system's tokens has in `config`'s stylesheet.
 *
@@ -124,13 +129,114 @@ function kebab(segment) {
 * The group segment is kebab-cased and the leaf is not, which is not a stylistic choice: it's the
 * shape the emitted stylesheet declares (`--{prefix}-{kebabCase(namespace)}-{safeTokenName(name)}`).
 * Deriving it any other way produces a `var()` that resolves to nothing for any camelCase group.
+*
+* Under the config's own naming, a token's own `cssVariable` is its whole name (`--spacing`), or
+* the exact name when it starts with `--` (`--mantine-color-primary`, whatever the prefix), and
+* otherwise the nearest token group that declares a `cssPrefix` spells its part of the name:
+* `fontSize/sm` under `fontSize: { cssPrefix: 'text' }` is `--text-sm`, and an empty `cssPrefix`
+* drops the group's segment. An empty config prefix drops its own.
 */
 function cssVar(config, _kind, path, varPrefix) {
 	if (typeof varPrefix === "function") return varPrefix(path);
-	const slash = path.indexOf("/");
 	const prefix = varPrefix ?? varPrefixOf(config);
-	if (slash <= 0 || slash >= path.length - 1) return `--${prefix}-${kebab(path)}`;
-	return `--${prefix}-${kebab(path.slice(0, slash))}-${path.slice(slash + 1).replaceAll(".", "_").replaceAll("/", "-").replace(/\s+/g, "-")}`;
+	const own = varPrefix === void 0 ? ownCssVariable(config, path) : void 0;
+	if (typeof own === "string") return own.startsWith("--") ? own : `--${prefixed({
+		prefix,
+		name: own
+	})}`;
+	const named = varPrefix === void 0 ? groupPrefixed(config, path) : void 0;
+	if (named) return `--${[
+		prefix,
+		named.prefix,
+		leafSegment(named.rest)
+	].filter(Boolean).join("-")}`;
+	const slash = path.indexOf("/");
+	if (slash <= 0 || slash >= path.length - 1) return `--${prefixed({
+		prefix,
+		name: kebab(path)
+	})}`;
+	return `--${prefixed({
+		prefix,
+		name: `${kebab(path.slice(0, slash))}-${leafSegment(path.slice(slash + 1))}`
+	})}`;
+}
+/**
+* A variable name's leaf: an identifier, so a space would end the name and is written as a hyphen,
+* the same spelling the class carries (`stylePropClassName`).
+*/
+function leafSegment(leaf) {
+	return leaf.replaceAll(".", "_").replaceAll("/", "-").replace(/\s+/g, "-");
+}
+/** Token group path → its stored fields, per groups listing. */
+const groupMetaCache = /* @__PURE__ */ new WeakMap();
+/** Each token group's own fields by path, as the config holds them. */
+function tokenGroupMeta(config) {
+	const groups = config.groups("token");
+	let meta = groupMetaCache.get(groups);
+	if (!meta) {
+		meta = new Map(groups.map((group) => [group.path, group.meta ?? {}]));
+		groupMetaCache.set(groups, meta);
+	}
+	return meta;
+}
+/** The nearest token group above `path` whose fields hold `field`, with the value and the path below
+*  the group. Read on the config itself, since a group's emit fields are local to the config that
+*  holds it. */
+function nearestGroupField({ config, path, field }) {
+	const meta = tokenGroupMeta(config);
+	if (meta.size === 0) return void 0;
+	for (let at = path.lastIndexOf("/"); at > 0; at = path.lastIndexOf("/", at - 1)) {
+		const value = meta.get(path.slice(0, at))?.[field];
+		if (value !== void 0) return {
+			value,
+			rest: path.slice(at + 1)
+		};
+	}
+}
+/**
+* The nearest token group above `path` that declares a `cssPrefix`, and the path below it.
+* `undefined` when none does.
+*/
+function groupPrefixed(config, path) {
+	if (!config) return void 0;
+	const found = nearestGroupField({
+		config,
+		path,
+		field: "cssPrefix"
+	});
+	return typeof found?.value === "string" ? {
+		prefix: found.value,
+		rest: found.rest
+	} : void 0;
+}
+/**
+* Whether a token is declared as a custom property: its own `cssVariable`, else the nearest group's
+* `cssVariables`, else yes. One that isn't is written into each value that uses it, as Tailwind's
+* `@theme inline` does.
+*/
+function declaresCssVariable(config, path) {
+	const own = ownCssVariable(config, path);
+	if (own !== void 0) return own !== false;
+	const overrides = (config.resolve("token", path)?.toJSON())?.overrides;
+	if (overrides && Object.keys(overrides).length > 0) return true;
+	return nearestGroupField({
+		config,
+		path,
+		field: "cssVariables"
+	})?.value !== false;
+}
+/**
+* How CSS reaches a token: `var(--…)` when it declares a variable, else its value written in place,
+* as the stylesheet writes it. For anything that paints a token outside a style prop, a swatch, an
+* effect colour, a background.
+*/
+function tokenReference(config, path) {
+	return renderStyleValue(config, ref("token", path));
+}
+/** A token's own `cssVariable`: the name it declares, `false` for none, `undefined` when unset. */
+function ownCssVariable(config, path) {
+	const own = (config?.resolve("token", path)?.toJSON())?.cssVariable;
+	return typeof own === "string" || own === false ? own : void 0;
 }
 /** `var(--…)` — the CSS reference to {@link cssVar}. */
 function cssVarRef(config, kind, path, varPrefix) {
@@ -140,7 +246,10 @@ function cssVarRef(config, kind, path, varPrefix) {
 *  whitespace in the path is written as a hyphen too; a composite or motion preset named with a space
 *  otherwise declares a rule no element's class list can match. */
 function className(config, _kind, path) {
-	return `${classPrefixOf(config)}-${path.replaceAll("/", "-").replace(/\s+/g, "-")}`;
+	return prefixed({
+		prefix: classPrefixOf(config),
+		name: path.replaceAll("/", "-").replace(/\s+/g, "-")
+	});
 }
 /**
 * A style prop's allowed values, flattened to concrete strings: literal keywords (`row`)
@@ -184,7 +293,7 @@ function memberEntries(config, target, opts) {
 }
 function expandMemberEntries(config, target, opts) {
 	const { kind, path, source, member: facet } = splitRef(target);
-	const offered = (holder, memberPath) => opts?.retired !== false || !holder.retired(kind, memberPath);
+	const offered = (holder, memberPath) => (opts?.retired !== false || !holder.retired(kind, memberPath)) && (holder.resolve(kind, memberPath)?.toJSON())?.utility !== false;
 	/**
 	* Whose members these are.
 	*
@@ -219,7 +328,7 @@ function expandMemberEntries(config, target, opts) {
 		}));
 	}
 	if (owner.resolve(kind, path)) {
-		if (!offered(owner, path)) return [];
+		if (opts?.retired === false && owner.retired(kind, path)) return [];
 		return [{
 			leaf: path.slice(path.lastIndexOf("/") + 1),
 			path: qualify(path)
@@ -533,8 +642,55 @@ function resolveFieldValue(config, kind, path, field, seen = /* @__PURE__ */ new
 /** A token's value with alias refs chased to the base literal — {@link resolveFieldValue} for the one
 *  field every token consumer asks about, narrowed to the scalar a display or a stylesheet can use. */
 function resolveTokenValue(config, path, seen = /* @__PURE__ */ new Set()) {
-	const value = resolveFieldValue(config, "token", path, "value", seen);
-	return typeof value === "string" || typeof value === "number" ? value : void 0;
+	return literalOf({
+		config,
+		value: resolveFieldValue(config, "token", path, "value", seen),
+		seen
+	});
+}
+/**
+* A stored value as the literal it comes to: a string or a number as itself, an OKLCH colour as its
+* CSS, arithmetic evaluated over its operands' literals (`multiply(Token.ref('spacing'), 4)` with
+* `spacing` at `0.25rem` is `1rem`), and a token ref as that token's literal. `undefined` for a value
+* that is no single literal (a shadow, a gradient) or a ref that resolves to nothing.
+*/
+function literalValueOf(config, value) {
+	return literalOf({
+		config,
+		value,
+		seen: /* @__PURE__ */ new Set()
+	});
+}
+/** `condition` reads each token the value names under that override condition, `null` its base. */
+function literalOf({ config, value, seen, condition = null }) {
+	if (typeof value === "number") return value;
+	if (typeof value === "string") {
+		if (!hasRefMarker(value)) return value;
+		let unresolved = false;
+		const text = replaceRefMarkers(value, (target) => {
+			const literal = literalOf({
+				config,
+				value: target,
+				seen,
+				condition
+			});
+			if (literal === void 0) unresolved = true;
+			return String(literal ?? "");
+		});
+		return unresolved ? void 0 : text;
+	}
+	if (isOklchColor(value)) return renderOklch(value);
+	if (isMultiply(value) || isDivide(value)) return evaluateCalc(value, (part) => literalOf({
+		config,
+		value: part,
+		seen,
+		condition
+	}));
+	if (isRef(value) && kindOf(value) === "token") {
+		const source = config.configFor(value);
+		if (!source) return void 0;
+		return condition === null ? resolveTokenValue(source, pathOf(value), new Set(seen)) : resolveTokenValueUnder(source, pathOf(value), condition, new Set(seen));
+	}
 }
 /**
 * The literal a token resolves to under an override condition: its own override there when it holds
@@ -559,7 +715,25 @@ function resolveTokenValueUnder(config, path, condition, seen = /* @__PURE__ */
 		if (kindOf(value) !== "token") return void 0;
 		return resolveTokenValueUnder(source, pathOf(value), condition, seen);
 	}
-	return typeof value === "string" || typeof value === "number" ? value : void 0;
+	return literalOf({
+		config,
+		value,
+		seen,
+		condition
+	});
+}
+/**
+* A string's interpolated refs written as their tokens: `blur({token:blur/sm})` is
+* `blur(var(--blur-sm))`. A ref opening a `var(` is the variable's name, so a fallback can follow it:
+* `var({token:tw/leading}, 1.5)` is `var(--tw-leading, 1.5)`.
+*/
+function renderInterpolated({ config, text, varPrefix }) {
+	if (!text.includes("{")) return text;
+	return text.replace(/(var\(\s*)?\{([a-z][\w-]*:[^{}\s]*)\}/g, (_, open, target) => {
+		const rendered = renderStyleValue(config, { __ref: target }, varPrefix);
+		if (!open) return rendered;
+		return `${open}${/^var\((--[\w-]+)\)$/.exec(rendered)?.[1] ?? rendered}`;
+	});
 }
 /** A style-bag value → its CSS string: a token ref (or a bare token path) becomes a
 *  `var(--…)` reference (so mode/theme overrides still flow), anything else is the literal.
@@ -576,18 +750,33 @@ function renderStyleValue(config, value, varPrefix) {
 		if (!source) return "";
 		if (kindOf(value) === "font") return fontStackOf(source, pathOf(value)) ?? "";
 		const slug = sourceOf(value);
+		if (!declaresCssVariable(source, pathOf(value))) return renderStyleValue(source, inlineValueOf(source, pathOf(value)), slug === void 0 ? varPrefix : linkedVarNaming(config, slug));
 		return cssVarRef(source, "token", pathOf(value), slug === void 0 ? varPrefix : linkedVarNaming(config, slug));
 	}
+	if (typeof value === "string" && hasRefMarker(value)) return renderInterpolated({
+		config,
+		text: value,
+		varPrefix
+	});
 	if (typeof value === "string" && sourceOf(value) !== void 0) {
 		const asRef = ref("token", value);
 		if (config.resolveRef(asRef)) return renderStyleValue(config, asRef, varPrefix);
 	}
-	if (typeof value === "string" && config.resolve("token", value)) return cssVarRef(config, "token", value, varPrefix);
+	if (typeof value === "string" && config.resolve("token", value)) {
+		if (!declaresCssVariable(config, value)) return renderStyleValue(config, inlineValueOf(config, value), varPrefix);
+		return cssVarRef(config, "token", value, varPrefix);
+	}
 	if (typeof value === "string" && value.startsWith("[") && value.endsWith("]")) return value.slice(1, -1).replace(/url\([^)]*\)|_/g, (span) => span === "_" ? " " : span);
 	return String(value);
 }
+/** The stored value of a token that declares no variable, rendered in its place. */
+function inlineValueOf(config, path) {
+	return (config.resolve("token", path)?.toJSON())?.value;
+}
 /**
-* The value a negating prop paints — `calc(<value> * -1)`.
+* The value a negating prop paints: a length or a percentage with a minus sign (`-1px`, `-100%`, and
+* a zero as it is), a scale step's multiplier negated (`calc(var(--spacing) * -4)`), and anything
+* else, a `var()` included, as `calc(<value> * -1)` — the spellings Tailwind writes.
 *
 * `calc` rather than a computed literal because the value is usually a `var(--…)`: the token it names
 * has to stay a reference, so a mode override or a theme swap still reaches it. It's applied at the
@@ -598,8 +787,33 @@ function renderStyleValue(config, value, varPrefix) {
 * literal is worse than one that never negates at all.
 */
 function negatedCssValue(value) {
+	const length = leadingNumber(value);
+	if (length && NEGATABLE_UNIT.test(length.rest)) {
+		const { sign, digits, rest: unit } = length;
+		if (Number(digits) === 0) return value;
+		return sign ? `${digits}${unit}` : `-${digits}${unit}`;
+	}
+	const step = scaleStepOf(value);
+	if (step) return `calc(${step.base} * ${step.sign ? "" : "-"}${step.digits})`;
 	return `calc(${value} * -1)`;
 }
+const NEGATABLE_UNIT = /^(?:px|%|r?em|ch|ex|lh|s?v[hw]|d?v[hw]|l?v[hw]|vmin|vmax|cm|mm|in|pt|pc)$/;
+/** A `calc(var(--name) * <number>)` split into the `var()` and the factor. */
+function scaleStepOf(value) {
+	if (!value.startsWith("calc(") || !value.endsWith(")")) return void 0;
+	const inner = value.slice(5, -1);
+	const times = inner.indexOf(" * ");
+	if (times === -1) return void 0;
+	const base = inner.slice(0, times);
+	if (!/^var\(--[\w-]+\)$/.test(base)) return void 0;
+	const factor = leadingNumber(inner.slice(times + 3));
+	if (factor?.rest !== "") return void 0;
+	return {
+		base,
+		sign: factor.sign,
+		digits: factor.digits
+	};
+}
 /**
 * What one component's own module does with each prop it declares — name → the style property that
 * prop writes, or `null` for a prop that writes none.
@@ -749,6 +963,27 @@ function routedBag({ config, through, bag }) {
 	}
 	return routed;
 }
+/** A declaration's key as CSS: a property as itself, a token's key `{token:tw/blur}` as the variable
+*  the token declares. */
+function declarationKeyName({ config, key, namespace }) {
+	const keyed = refOfKey(key);
+	return keyed ? cssVar(config, "token", pathOf(keyed), namespace) : key;
+}
+/** A style prop's own `declarations`, each ref written as its token: a key `{token:…}` as the
+*  variable the token declares, and an interpolated ref as it renders. `{value}` is left in place. */
+function propDeclarations({ config, body, namespace }) {
+	return Object.fromEntries(Object.entries(body.declarations ?? {}).map(([key, value]) => {
+		return [declarationKeyName({
+			config,
+			key,
+			namespace
+		}), renderInterpolated({
+			config,
+			text: declarationText(value),
+			varPrefix: namespace
+		})];
+	}));
+}
 /**
 * The leaf a bag value names, for looking its entry up — or `undefined` when it names none.
 *
@@ -759,8 +994,38 @@ function leafAuthoredFor(value) {
 	if (typeof value === "boolean") return value ? "" : void 0;
 	if (typeof value === "string" || typeof value === "number") return String(value);
 }
+/**
+* The declarations a bag sets on the element itself. Declarations a prop scopes to a `selector` or a
+* value scopes to an at-rule are not the element's, so they are left out; a stylesheet reads them
+* from {@link styleDeclarationGroups}.
+*/
 function styleDeclarations({ config, bag, namespace }) {
-	const out = {};
+	return styleDeclarationGroups({
+		config,
+		bag,
+		namespace
+	}).find((group) => group.selector === void 0 && group.atRule === void 0)?.declarations ?? {};
+}
+/**
+* A bag's declarations in the blocks they apply in: the element's own first, then each `selector`
+* and at-rule block in the order the bag first reaches it. A block that sets nothing is left out.
+*/
+function styleDeclarationGroups({ config, bag, namespace }) {
+	const groups = /* @__PURE__ */ new Map();
+	const blockFor = ({ selector, atRule }) => {
+		const id = `${selector ?? ""}\u0000${atRule ?? ""}`;
+		let group = groups.get(id);
+		if (!group) {
+			group = {
+				...selector === void 0 ? {} : { selector },
+				...atRule === void 0 ? {} : { atRule },
+				declarations: {}
+			};
+			groups.set(id, group);
+		}
+		return group.declarations;
+	};
+	const out = blockFor({});
 	const fades = /* @__PURE__ */ new Map();
 	for (const [rawKey, value] of Object.entries(bag)) {
 		if (rawKey.startsWith("_") || rawKey.startsWith("--")) continue;
@@ -794,11 +1059,36 @@ function styleDeclarations({ config, bag, namespace }) {
 		if (!prop) continue;
 		const body = prop.toJSON();
 		if (isRef(body.opacityOf)) continue;
-		const cssProperties = Array.isArray(body.properties) ? body.properties : [];
+		const selector = body.selector || void 0;
+		const target = blockFor({ selector });
+		const cssProperties = Array.isArray(body.properties) ? body.properties.map((property) => {
+			const keyed = refOfKey(property);
+			return keyed ? cssVar(config, "token", pathOf(keyed), namespace) : property;
+		}) : [];
 		const authoredLeafValue = leafAuthoredFor(value);
 		const entry = authoredLeafValue === void 0 ? void 0 : stylePropEntries(config, key).find((candidate) => candidate.leaf === authoredLeafValue);
 		if (entry?.declarations) {
-			for (const [cssProperty, declaredValue] of Object.entries(entry.declarations)) out[cssProperty] = renderStyleValue(config, declaredValue, namespace);
+			for (const [key, declaredValue] of Object.entries(entry.declarations)) target[declarationKeyName({
+				config,
+				key,
+				namespace
+			})] = renderStyleValue(config, declaredValue, namespace);
+			for (const [cssProperty, declared] of Object.entries(propDeclarations({
+				config,
+				body,
+				namespace
+			}))) if (!declared.includes("{value}")) target[cssProperty] = declared;
+			for (const [atRule, block] of Object.entries(entry.atRules ?? {})) {
+				const scoped = blockFor({
+					selector,
+					atRule
+				});
+				for (const [key, declaredValue] of Object.entries(block)) scoped[declarationKeyName({
+					config,
+					key,
+					namespace
+				})] = renderStyleValue(config, declaredValue, namespace);
+			}
 			continue;
 		}
 		const base = renderBagValue({
@@ -811,9 +1101,14 @@ function styleDeclarations({ config, bag, namespace }) {
 		let rendered = stylePropNegates(config, key) ? negatedCssValue(base) : base;
 		const fade = fades.get(key);
 		if (fade !== void 0) rendered = `color-mix(in srgb, ${rendered} ${fade}, transparent)`;
-		for (const cssProperty of cssProperties) out[cssProperty] = rendered;
+		for (const cssProperty of cssProperties) target[cssProperty] = rendered;
+		for (const [cssProperty, declared] of Object.entries(propDeclarations({
+			config,
+			body,
+			namespace
+		}))) target[cssProperty] = declared.replaceAll("{value}", rendered);
 	}
-	return out;
+	return [...groups.values()].filter((group) => Object.keys(group.declarations).length > 0);
 }
 /** One bag value as CSS text, or `undefined` for a flag turned off. */
 function renderBagValue({ config, key, value, namespace }) {
@@ -1375,4 +1670,4 @@ function declaredPropDefaults(props) {
 	return out;
 }
 //#endregion
-export { LAYER_PROPS, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropDefaults, declaredPropRouting, glyphComponentOf, glyphLibrariesOf, glyphPropsOf, glyphPropsOfBody, heldLinked, holdingPreviewConditions, iconToolAxisOptions, iconToolFor, iconToolOf, iconToolsOf, keyedPreviewConditions, layerPropsErrors, linkedVarNaming, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, refListOf, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, takenByForward, validateComponentProps };
+export { LAYER_PROPS, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declarationKeyName, declaredPropDefaults, declaredPropRouting, declaresCssVariable, glyphComponentOf, glyphLibrariesOf, glyphPropsOf, glyphPropsOfBody, heldLinked, holdingPreviewConditions, iconToolAxisOptions, iconToolFor, iconToolOf, iconToolsOf, 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 };

package/dist/framework/ref-graph.js

@@ -33,7 +33,7 @@ function edgesOf(ref, data, extra = [], linkKinds = [], singletonKinds = []) {
 	if (linkKinds.length > 0) for (const target of collected) {
 		const slug = sourceOf(target);
 		if (slug === void 0) continue;
-		for (const kind of linkKinds) targets.add(`${kind}:${slug}`);
+		for (const kind of linkKinds) targets.add(`${kind}:${slug.split("~")[0]}`);
 	}
 	for (const target of extra) targets.add(target);
 	targets.delete(ref);

package/dist/framework/registry.d.ts

@@ -49,6 +49,13 @@ type AuthoredValueForm = (ctx: {
 }) => z.ZodTypeAny | undefined;
 interface EntityKind {
   readonly name: string;
+  /** Adapt a pinned source body before this kind validates a linked extension. */
+  readonly prepareLinkedBody?: (args: {
+    readonly path: string;
+    readonly body: Record<string, unknown>;
+    readonly source: Config; /** The config borrowing the body, which resolves the body's source-qualified refs. */
+    readonly config: Config;
+  }) => Record<string, unknown>;
   /** The entity class's name (`style-property` → `StyleProperty`) — what a consumer writes to reach
    *  it (`StyleProperty.ref(...)`, `Token.group(...)`).
    *

package/dist/framework/registry.js

@@ -32,7 +32,7 @@ function titleCase(kind) {
 /** Derive a kind's immutable metadata from its field schemas — the value a `defineEntity`/
 *  `defineDerivedEntity` attaches to its class and a `Config.register` stores in `#entities`. */
 function buildKind(spec) {
-	const { name, fields, groupFields, subEntities = {}, computed, label, labelPlural, schemas: userSchemas, derived, sourceIdentity, sourceOrigin, authoredRefs, linkable, localGroupFields, emergentGroups, singleton = false, bareMember, sourceResolution, bulkAdopts, bulkOverlay, bulkDirectives, bulkOverlayWrite, nameEdges, rewriteName, styleBags, uniqueLeaves, authoredValue, mentionFields, invariants } = spec;
+	const { name, prepareLinkedBody, fields, groupFields, subEntities = {}, computed, label, labelPlural, schemas: userSchemas, derived, sourceIdentity, sourceOrigin, authoredRefs, linkable, localGroupFields, emergentGroups, singleton = false, bareMember, sourceResolution, bulkAdopts, bulkOverlay, bulkDirectives, bulkOverlayWrite, nameEdges, rewriteName, styleBags, uniqueLeaves, authoredValue, mentionFields, invariants } = spec;
 	const allComputed = {
 		sources: ({ member, config }) => sourceSlugs(member, config),
 		borrowedFrom: ({ config, path }) => config.borrowedFrom(name, path),
@@ -48,6 +48,7 @@ function buildKind(spec) {
 	}
 	return {
 		name,
+		...prepareLinkedBody ? { prepareLinkedBody } : {},
 		label: resolvedLabel,
 		entityName: spec.entityName ?? entityClassName(name),
 		labelPlural: labelPlural ?? `${resolvedLabel}s`,

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 = 20261001131000;
+declare const CURRENT_SCHEMA_VERSION = 20261001162046;
 /** 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 {