@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/framework/projections.js

@@ -0,0 +1,974 @@
+import { isRef, kindOf, memberOf, pathOf, ref, refLeaf, sourceOf, splitRef } from "./utils/refs.js";
+import { isDerivedColor, isGradient, renderDerivedColor, renderGradient } from "../entities/system/color.js";
+import { forwardsOf } from "../entities/system/element.js";
+import { listedIn } from "./utils/enumerated.js";
+import { modifierCategory } from "../entities/system/Modifier.js";
+import { classPrefixOf, varPrefixOf } from "../entities/system/Settings.js";
+import { StyleProperty, leavesOfStylePropValue } from "../entities/system/StyleProperty.js";
+//#region src/framework/projections.ts
+/**
+* Expanded value domains, cached per config instance.
+*
+* A domain is read once per authored value, not once per property: `resolveComponentStyleModel` asks
+* `stylePropTokenPath` for every leaf a property offers, and each of those re-expands the whole
+* domain behind it. Over this system's own artifact one CSS emit expanded the token domain 23,895
+* times — 16M `withComputed` reads and 1.7s, on the browser's main thread, per config change.
+*
+* Keyed on the config rather than on its snapshot slices, which is the stronger key: a config is a
+* value, so its snapshot and its attached sources are both fixed for the life of the instance, and a
+* domain reached through a link (`Token.ref('color@yahoo-os')`) is answered by a source config that a
+* slice key cannot see. A hit therefore cannot be stale, and an edit — which allocates a new config —
+* gets a fresh cache, which is exactly the intent: the win here is within one derive.
+*
+* Both arrays are shared with every other caller of that config: consume them, don't mutate them.
+*/
+const memberEntryCache = /* @__PURE__ */ new WeakMap();
+const stylePropEntryCache = /* @__PURE__ */ new WeakMap();
+/** The per-config half of one of the caches above, created on first use. */
+function domainCache(cache, config) {
+	let entry = cache.get(config);
+	if (!entry) {
+		entry = /* @__PURE__ */ new Map();
+		cache.set(config, entry);
+	}
+	return entry;
+}
+/**
+* The variable namespace a linked system's entities are declared under, seen from `config`.
+*
+* Not the source's own prefix. That is a setting the source chose for itself and the one it gets for
+* free is `uds`, so two pinned systems that both took the default would declare the same
+* `--uds-color-brand` and the later `:root` would win — every ref through either pin painting one
+* value, silently, because an over-declared custom property is not an error.
+*
+* The slug is the name that cannot collide: it is a key in the consuming config, unique there by
+* 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)}`;
+/** camelCase → kebab, letter→number split, non-alphanumeric runs collapsed, lowercased. The rule
+*  the emitted CSS uses for a token's group segment (`borderColor` → `border-color`), so a
+*  reference built here resolves against the stylesheet instead of naming a property that was
+*  never declared. */
+function kebab(segment) {
+	return segment.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([a-z])([0-9]+)/gi, "$1-$2").replace(/[^A-Za-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+}
+/**
+* The CSS custom-property name for an entity — `--<prefix>-<group-kebabed>-<leaf>`.
+*
+* 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.
+*/
+function cssVar(config, _kind, path, varPrefix) {
+	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, "-")}`;
+}
+/** `var(--…)` — the CSS reference to {@link cssVar}. */
+function cssVarRef(config, kind, path, varPrefix) {
+	return `var(${cssVar(config, kind, path, varPrefix)})`;
+}
+/** The utility/class name for an entity — `<prefix>-<path-dashed>`. A class is one identifier, so
+*  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, "-")}`;
+}
+/**
+* A style prop's allowed values, flattened to concrete strings: literal keywords (`row`)
+* pass through, and a token group ref (`ref('token', 'color')`) expands to every member
+* Token's path (`color/brand`, `color/accent`, …) — the utility set the prop offers,
+* kept in lockstep with the group instead of restated. A ref that names a single token
+* resolves to just that path. Shared by codegen (utility emit) and the UI value picker so
+* both offer the same set. Order follows the authored `values`, group members in store
+* order. Unknown prop → `[]`.
+*/
+function stylePropValues(config, path) {
+	return stylePropEntries(config, path).map((entry) => entry.value);
+}
+/**
+* The entries a ref target offers as `{leaf, path}` — the one leaf↔qualified-path map behind every
+* ref-bound value domain, whatever the ref names:
+*
+*   Token:color/brand        an item   → itself (leaf = its name)
+*   Token:color              a group   → one entry per member (`color/brand` → `brand`)
+*   icon:phosphor#variants   a facet   → one entry per value that field of the group node lists
+*
+* Style-prop values, composite props, a variant bound to a group, and an icon prop drawing its
+* weights from the library it renders are all the same question, so they are all this. A prop that
+* enumerates instead of delegating is a copy of a list nothing keeps in step — 1,530 glyph names in
+* the component that renders them, which is what the facet arm exists to stop.
+*/
+function memberEntries(config, target) {
+	const cache = domainCache(memberEntryCache, config);
+	const key = isRef(target) ? target.__ref : target;
+	const hit = cache.get(key);
+	if (hit) return hit;
+	const expanded = expandMemberEntries(config, target);
+	cache.set(key, expanded);
+	return expanded;
+}
+function expandMemberEntries(config, target) {
+	const { kind, path, source, member: facet } = splitRef(target);
+	/**
+	* Whose members these are.
+	*
+	* A ref with a source names entities in the linked system, so every lookup below has to run
+	* against that config with the bare path — asking the consumer for a group called `palette@ds` is
+	* asking for something it has never had, and it answered by returning nothing at all. A style prop
+	* whose domain was a borrowed group therefore offered no values: no utilities emitted, and
+	* `bg="accent"` painted nothing, with no error anywhere.
+	*/
+	const owner = source === void 0 ? config : config.configFor(target);
+	if (!owner) return [];
+	/** The value side stays addressable from here, so a member's path keeps its qualifier. */
+	const qualify = (memberPath) => source === void 0 ? memberPath : `${memberPath}@${source}`;
+	if (facet === void 0 && path === "") return owner.list(kind).map((item) => ({
+		leaf: item.path,
+		path: qualify(item.path)
+	}));
+	if (facet !== void 0) {
+		const bare = owner.entityOf(kind)?.bareMember;
+		if (bare !== void 0 && !facet.includes("/")) {
+			const items = owner.resolve(kind, path)?.toJSON()?.[bare];
+			if (typeof items === "object" && items !== null && facet in items) return [{
+				leaf: facet,
+				path: qualify(`${path}#${facet}`)
+			}];
+		}
+		const listed = groupMetaOf(owner, kind, path)?.[facet];
+		if (!Array.isArray(listed)) return [];
+		return listed.filter((value) => typeof value === "string").map((value) => ({
+			leaf: value,
+			path: value
+		}));
+	}
+	if (owner.resolve(kind, path)) return [{
+		leaf: path.slice(path.lastIndexOf("/") + 1),
+		path: qualify(path)
+	}];
+	const leafOf = (memberPath) => memberPath.startsWith(`${path}/`) ? memberPath.slice(path.length + 1) : memberPath;
+	const theirs = owner.members(kind, path);
+	if (source === void 0) return theirs.map((member) => ({
+		leaf: leafOf(member.path),
+		path: member.path
+	}));
+	const ours = config.members(kind, path);
+	const held = new Set(ours.map((member) => member.path));
+	const covered = new Set(theirs.map((member) => member.path));
+	return [...theirs.map((member) => ({
+		leaf: leafOf(member.path),
+		path: held.has(member.path) ? member.path : qualify(member.path)
+	})), ...ours.filter((member) => !covered.has(member.path)).map((member) => ({
+		leaf: leafOf(member.path),
+		path: member.path
+	}))];
+}
+/** A group node's own body, by path. */
+function groupMetaOf(config, kind, path) {
+	return config.groups(kind).find((group) => group.path === path)?.meta;
+}
+/** The leaf value domain a ref offers — for any group-bound prop (composite/variant).
+*
+*  Takes the ref itself, not its parts. A caller holding `token:palette@ds` has the whole address; a
+*  signature that took it apart made every call site split one by hand, and the three that did
+*  disagreed about whether the `@source` survived the trip — which decides which config the members
+*  come from. */
+function memberLeaves(config, target) {
+	return memberEntries(config, target).map((entry) => entry.leaf);
+}
+/** Resolve a group-bound leaf back to its qualified path (`display2` → `textVariant/display2`).
+*  `undefined` when the leaf isn't a member — what validation rejects. */
+function memberFromLeaf(config, target, leaf) {
+	return memberEntries(config, target).find((entry) => entry.leaf === leaf)?.path;
+}
+function stylePropEntries(config, path) {
+	const cache = domainCache(stylePropEntryCache, config);
+	const hit = cache.get(path);
+	if (hit) return hit;
+	const expanded = expandStylePropEntries(config, path);
+	cache.set(path, expanded);
+	return expanded;
+}
+function expandStylePropEntries(config, path) {
+	const prop = config.resolve("style-property", path);
+	if (!prop) return [];
+	const values = prop.toJSON().values ?? [];
+	const members = (target) => memberEntries(config, target);
+	return values.flatMap((entry) => leavesOfStylePropValue(entry, members));
+}
+/**
+* A style prop's leaf value domain — what a consumer/model actually authors (`warning`, `carbon/2`),
+* not the qualified storage path (`color/warning`). This is what the catalog, `uds_get_component`,
+* `uds_validate_props`, and the UI picker should offer, so the model emits `color="warning"`.
+*/
+function stylePropValueLeaves(config, path) {
+	return stylePropEntries(config, path).map((entry) => entry.leaf);
+}
+/**
+* Resolve a style-prop leaf value back to its qualified token path (or literal) — the inverse of
+* {@link stylePropValueLeaves}, for validating + rendering an authored `bg="subtle"`. `undefined`
+* when the leaf isn't in the prop's domain.
+*/
+function stylePropValueFromLeaf(config, path, leaf) {
+	return stylePropEntries(config, path).find((entry) => entry.leaf === leaf)?.value;
+}
+/**
+* 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.
+*
+* The pair below is what lets a bag store the binding as a ref while an author keeps writing the
+* leaf: this direction mints the ref at parse time, {@link stylePropLeafForToken} reads it back for
+* the class name. Narrowed to values that actually resolve as tokens, so a keyword is left as the
+* string it is — a ref to a token that doesn't exist would be a dangling edge, which is worse than
+* the missing one it replaced.
+*/
+function stylePropTokenPath(config, path, leaf) {
+	const value = stylePropValueFromLeaf(config, path, leaf);
+	if (value === void 0) return void 0;
+	return config.resolveRef(ref("token", value)) ? value : void 0;
+}
+/**
+* The leaf a style prop calls a token — `('bg', 'color/brand')` → `brand`. The read twin of
+* {@link stylePropTokenPath}, and the reason storing the ref costs no reader its class name.
+*
+* Not `refLeaf`: that strips one path segment, which is right for a variant value
+* (`value:variant/solid`) and wrong here, because a prop's token group can be several segments deep
+* (`spectrum/blue/1` under group `spectrum/blue` is the leaf `1`, not `blue/1`). The group is a fact
+* about the prop's domain, so only the domain can say where the leaf starts.
+*
+* First match wins, the same way {@link stylePropValueFromLeaf} resolves the other direction — a
+* prop binding two groups that share a value already lets authored order decide.
+*/
+function stylePropLeafForToken(config, path, tokenPath) {
+	return stylePropEntries(config, path).find((entry) => entry.value === tokenPath)?.leaf;
+}
+/**
+* The leaf an author wrote for a stored ref in a bag — the read side of the binding
+* `value-domain.ts` performs on the way in.
+*
+* Two cases, because where the leaf starts differs:
+*
+*  - a token is reached through a style property, whose domain decides how much of the path is the
+*    group. `spectrum/blue/1` under the group `spectrum/blue` is the leaf `1`, so the property's own
+*    domain is the only thing that can say — hence the lookup rather than trimming a segment.
+*  - anything else (a composite member, a motion preset) is named under the group its prop points at,
+*    and the authored name is the last segment. This holds for a nested group too: `overlays/elev/1`
+*    under `overlays/elev` is `1`.
+*
+* `undefined` when the ref isn't one a bag value could have been authored as, so the caller leaves it
+* alone rather than inventing a name for it.
+*/
+function authoredValue(config, key, value) {
+	if (!isRef(value)) return value;
+	return authoredLeaf(config, key, value.__ref) ?? value;
+}
+function authoredLeaf(config, key, stored) {
+	const path = pathOf(stored);
+	if (kindOf(stored) === "token") return stylePropLeafForToken(config, key, path);
+	const slash = path.indexOf("/");
+	return slash === -1 ? path : path.slice(slash + 1);
+}
+/**
+* A style bag as a surface reads it — every token binding read back to the leaf an author wrote.
+*
+* The inverse of the parse-time binding (`bindBagTokens` on `Component`), and the one place that
+* inverse lives: a bag is stored with refs so the dependency graph sees the edges, while every
+* consumer that renders, edits, or bakes one wants the leaf. Two implementations of this would be two
+* chances to disagree about what a value is called — and the panel and the native theme disagreeing
+* about that is exactly the class of bug the single description is meant to remove.
+*
+* Recurses into modifier blocks, since their values are values too. Returns the bag it was given when
+* nothing was bound, so an untouched bag keeps its identity.
+*/
+function authoredBag(config, bag) {
+	const out = {};
+	let changed = false;
+	for (const [key, value] of Object.entries(bag)) {
+		if (isRef(value)) {
+			const leaf = authoredLeaf(config, key, value.__ref);
+			if (leaf !== void 0) {
+				out[key] = leaf;
+				changed = true;
+				continue;
+			}
+		}
+		if (value && typeof value === "object" && !Array.isArray(value) && !isRef(value)) {
+			const inner = authoredBag(config, value);
+			out[key] = inner;
+			changed ||= inner !== value;
+			continue;
+		}
+		out[key] = value;
+	}
+	return changed ? out : bag;
+}
+/**
+* The style property a prop on `elementType` writes through.
+*
+* Two questions get asked of a config constantly — *what CSS does this prop on this element write?*
+* and *which prop writes this CSS?* — and both have to be answered from the config rather than from a
+* prop's name: `spacingX` in one system is `spacingHorizontal` in the next, so CSS is the stable
+* contract between them.
+*
+* One `StyleProperty` read on top of {@link stylePropertyPathFor}, which is where the routing lives:
+* the component's own table where it declares the prop, the name where it doesn't — which is what an
+* element styled through a raw tag needs, since a raw tag declares no props at all.
+*
+* `elementType` may arrive as a spec element's stored marker (`component:Media`) or as a bare path;
+* the marker is stripped, because the component lookup keys on the path. Missing that strip is
+* invisible in a system whose prop names are its style-property paths — the fallback answers
+* correctly — and wrong the moment a component names a prop something else.
+*/
+function stylePropertyFor(config, elementType, propName) {
+	const writes = stylePropertyPathFor({
+		config,
+		through: [elementType],
+		key: propName
+	});
+	return writes === void 0 ? void 0 : StyleProperty.get(config, writes);
+}
+/** Every style property that writes `cssProperty`, in registration order. */
+function stylePropertiesWriting(config, cssProperty) {
+	return StyleProperty.list(config).filter((prop) => prop.properties.includes(cssProperty));
+}
+/** Whether a style property accepts `value` — i.e. the value is one of its leaves. */
+function stylePropertyAccepts(config, prop, value) {
+	return stylePropEntries(config, prop.path).some((entry) => entry.leaf === value);
+}
+/**
+* Each token-backed value a style prop offers, as `leaf → resolved literal` (`'2' → '0.5rem'`) — what
+* a token picker shows beside each name. Keyword values are absent: there's no token behind them, so
+* there's nothing to resolve.
+*/
+function stylePropTokenValues(config, propName) {
+	const map = {};
+	for (const entry of stylePropEntries(config, propName)) {
+		const literal = resolveTokenValue(config, entry.value);
+		if (literal !== void 0) map[entry.leaf] = String(literal);
+	}
+	return map;
+}
+/**
+* The token group a style prop draws its values from (`spacing`) — what an "open this in the system"
+* link needs. `undefined` when the prop's values are keywords rather than tokens.
+*
+* Derived from the values themselves rather than from a declared group list: a token-backed value
+* resolves to its qualified path, and everything before the leaf is the group it lives in.
+*/
+function stylePropTokenGroup(config, propName) {
+	for (const entry of stylePropEntries(config, propName)) {
+		const slash = entry.value.lastIndexOf("/");
+		if (slash > 0 && config.resolve("token", entry.value)) return entry.value.slice(0, slash);
+	}
+}
+/**
+* The value of whichever prop in `props` writes `cssProperty`.
+*
+* Reads the element's own props rather than the styling the config would apply, because a caller
+* asking this is asking about a choice someone made on this element (pinning a position, locking an
+* aspect ratio) — not about what the component's rules paint by default.
+*/
+function cssPropValue(config, elementType, props, cssProperty) {
+	for (const [name, value] of Object.entries(props)) {
+		if (typeof value !== "string") continue;
+		if (stylePropertyFor(config, elementType, name)?.properties.includes(cssProperty)) return value;
+	}
+}
+/**
+* A per-config tag for cycle keys, so one chase can distinguish two configs that spell a path the
+* same way. Assigned lazily and held weakly — a `Config` is a value, so this keys on the exact
+* instance being walked and dies with it.
+*/
+const chaseTags = /* @__PURE__ */ new WeakMap();
+let nextChaseTag = 0;
+function chaseTag(config) {
+	let tag = chaseTags.get(config);
+	if (tag === void 0) {
+		tag = String(nextChaseTag++);
+		chaseTags.set(config, tag);
+	}
+	return tag;
+}
+/**
+* One field of one entity, with refs chased to the literal they denote — local and linked alike.
+*
+* The whole point is that there is no second walk for a borrow. A ref is a ref: `isRef` is the only
+* branch, and whether it carries a `@source` decides only which config the next hop reads, never
+* whether a hop happens. That is what makes "reference something in my system" and "reference
+* something from a linked system" the same feature rather than two that have to agree.
+*
+* A ref stands in for the same field of the entity it names — a token's `value` aliasing another
+* Token's `value`, a composite's `styles` standing in for another composite's `styles` — so the field
+* carries through the chase rather than each kind needing to declare a target.
+*
+* Answers with whatever the ref denotes rather than narrowing to a scalar — a borrowed gradient or
+* derived colour is a resolved value too, and a chase that returned `undefined` for one would be
+* indistinguishable from a chase that failed. A caller wanting a literal narrows.
+*
+* `undefined` only when there is no answer: a missing entity, an unreachable linked source, or a cycle.
+*/
+function resolveFieldValue(config, kind, path, field, seen = /* @__PURE__ */ new Set()) {
+	const entity = config.resolve(kind, path);
+	if (!entity) return void 0;
+	const value = entity.toJSON()[field];
+	if (isRef(value)) {
+		const key = `${chaseTag(config)}|${value.__ref}`;
+		if (seen.has(key)) return void 0;
+		seen.add(key);
+		const source = config.configFor(value);
+		if (source) return resolveFieldValue(source, kindOf(value), pathOf(value), field, seen);
+		return;
+	}
+	return value;
+}
+/** 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;
+}
+/**
+* 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
+* cascade reads it — under `dark`, an alias of `blue/1` is blue/1's dark value — so a swatch painted
+* for a dark cell paints what dark will show. `null` is the base, the same as {@link resolveTokenValue}.
+*/
+function resolveTokenValueUnder(config, path, condition, seen = /* @__PURE__ */ new Set()) {
+	if (condition === null) return resolveTokenValue(config, path, seen);
+	const entity = config.resolve("token", path);
+	if (!entity) return void 0;
+	const body = entity.toJSON();
+	const own = body.overrides?.[condition];
+	const value = own !== void 0 ? own.value : body.value;
+	if (isRef(value)) {
+		const key = `${chaseTag(config)}|${value.__ref}`;
+		if (seen.has(key)) return void 0;
+		seen.add(key);
+		const source = config.configFor(value);
+		if (!source || kindOf(value) !== "token") return void 0;
+		return resolveTokenValueUnder(source, pathOf(value), condition, seen);
+	}
+	return typeof value === "string" || typeof value === "number" ? value : void 0;
+}
+/** 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.
+*
+*  `varPrefix` renames the namespace every variable in the result is spelled under, and is how a
+*  linked source's own values are rendered into the consumer's stylesheet: their token aliasing
+*  another of theirs has to name the variable as we declared it, not as they would have. Absent — the
+*  ordinary call — it is `config`'s own prefix. */
+function renderStyleValue(config, value, varPrefix) {
+	if (Array.isArray(value)) return value.map((part) => renderStyleValue(config, part, varPrefix)).join(" ");
+	if (isDerivedColor(value)) return renderDerivedColor(value, (color) => renderStyleValue(config, color, varPrefix));
+	if (isGradient(value)) return renderGradient(value, (color) => renderStyleValue(config, color, varPrefix));
+	if (isRef(value)) {
+		const source = config.configFor(value);
+		if (!source) return "";
+		const slug = sourceOf(value);
+		return cssVarRef(source, "token", pathOf(value), slug === void 0 ? varPrefix : sourceVarPrefix(config, slug));
+	}
+	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" && value.startsWith("[") && value.endsWith("]")) return value.slice(1, -1).replace(/url\([^)]*\)|_/g, (span) => span === "_" ? " " : span);
+	return String(value);
+}
+/**
+* The value a negating prop paints — `calc(<value> * -1)`.
+*
+* `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
+* declaration, not to the token, since the same token feeds the positive prop too.
+*
+* Exported because three emitters need the same string — the stylesheet, the runtime's off-scale
+* branch, and this file's `styleDeclarations` — and a prop that negates from a token but not from a
+* literal is worse than one that never negates at all.
+*/
+function negatedCssValue(value) {
+	return `calc(${value} * -1)`;
+}
+/**
+* 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.
+*
+* This is the routing an emitted module performs, and it is a different question from
+* {@link resolveComponentProps} / `prop-surface`, which answer what a component exposes by chasing
+* `forwards` and `inherits`. Both are right for their callers — an inspector offers the exposed
+* surface — but only this one describes what happens at runtime, because a module destructures its
+* declared props out of the bag and hands the rest to `processStyleProps`:
+*
+*     const { className, layerProps, variant, size = "md", children, ...__udsBag } = jsxProps;
+*     const [classes, rest] = processStyleProps(__udsBag, { gap: "gapY" });
+*
+* So a declared prop is answered by its declaration whatever its type, and a prop the component does
+* not declare falls through by its own name to the root layer — where every prop the config doesn't
+* model is sent (`rootLayerOf`).
+*
+* Three consequences, each a silent miss for a caller that reads the exposed surface instead:
+*
+*  - **A rename is the component's own.** `TokenCellShell` forwards `*` from `HStack`, so its exposed
+*    surface reports `gap` as `gapX` — but its module carries no alias, consumes `gap` under the
+*    System-wide name, and its baked rule emits `gap:` to match. A forwarded rename is not inherited.
+*  - **A `variant`, `composite`, `slot`, `forward`, `string`, `number` or `boolean` prop writes no
+*    style property at all**, even where a style property shares its name. It is destructured out
+*    before the style-prop table is ever consulted.
+*  - **A `null` tombstone is a declaration too** — the prop is declared gone, not merely absent, and
+*    it is destructured out like any other. It writes nothing and does not fall through.
+*/
+function declaredPropRouting(config, path) {
+	const { props = {} } = config.resolve("component", path)?.toJSON() ?? {};
+	const routing = /* @__PURE__ */ new Map();
+	for (const [name, declaration] of Object.entries(props)) {
+		const writes = declaration?.type === "styleProperty" && isRef(declaration.value) ? pathOf(declaration.value.__ref) : null;
+		routing.set(name, writes);
+	}
+	return routing;
+}
+/**
+* The renames out of {@link declaredPropRouting} — the table a component's module is emitted with and
+* hands to `processStyleProps`.
+*
+* Only the renames, because a prop named after its own property is what the runtime assumes when it
+* finds no entry (`aliases?.[key] ?? key`). So this map is the difference between a prop's
+* consumer-facing name and what it routes to, and an empty answer means "they are the same".
+*/
+function styleAliasesOf(config, path) {
+	const aliases = /* @__PURE__ */ new Map();
+	for (const [name, writes] of declaredPropRouting(config, path)) if (writes !== null && writes !== name) aliases.set(name, writes);
+	return aliases;
+}
+/** Whether a style prop paints the negation of its value (`offsetX`). */
+function stylePropNegates(config, path) {
+	return (config.resolve("style-property", path)?.toJSON())?.negates === true;
+}
+/**
+* Flatten a style bag to resolved CSS declarations — each key resolves to its style prop's
+* CSS `property` (falling back to the key itself as a raw property), each value renders as a
+* Token ref or a literal. `_`-prefixed keys are modifier blocks the caller nests, so they're
+* skipped. The single style→CSS resolver shared by codegen (emit CSS text) and the renderer
+* (inline styles) so a rendered preview matches the emitted stylesheet exactly.
+*/
+/**
+* The style property one bag key writes — the single answer to "what does this prop mean here",
+* for every surface that reads a prop bag.
+*
+* A bag key is an authored name, and what it writes is settled by the definitions it resolves
+* against, in `through` order — first one that declares the key wins, and its answer is the whole
+* answer. A key nothing declares names its own property, which is what a raw tag needs, since a raw
+* tag declares no props at all.
+*
+* `through` is a chain rather than one element because a style rule's bag has two definitions with a
+* claim on it: the component that authored the rule, and the element whose props the rule sets.
+* The author comes first — a component's own declaration of `gap` is what `gap` means throughout its
+* definition, its public API and its style rules alike. So `Row`, which declares `gap` writing
+* `gapX` over a `VStack` layer that writes `gapY`, means column-gap in both places rather than one
+* in each.
+*
+* A member ref key (`component:layout/HStack#props/gap`) names its element outright, so it answers
+* for itself and `through` is irrelevant.
+*
+* `undefined` means "writes no style property": a `variant`, a `composite`, a tombstone, or a key
+* that is not a style property at all (`as`, `type`, a data attribute). Every caller already had to
+* distinguish that from a property, and each one used to decide it differently — the CSS emitter by
+* `config.resolve('style-property', key)` on the authored name, which both mis-resolved a rename and
+* silently dropped a key whose only meaning is a rename (`colSpan`, not itself a property, emitted no
+* declaration at all).
+*/
+function stylePropertyPathFor({ config, through = [], key }) {
+	const member = memberOf(key);
+	if (member) {
+		const name = member.slice(member.indexOf("/") + 1);
+		const writes = declaredPropRouting(config, pathOf(key)).get(name);
+		return writes === void 0 ? nameAsProperty(config, name) : writes ?? void 0;
+	}
+	for (const definition of through) {
+		if (definition === void 0) continue;
+		const writes = declaredPropRouting(config, pathOf(definition)).get(key);
+		if (writes !== void 0) return writes ?? void 0;
+	}
+	return nameAsProperty(config, key);
+}
+/** A key read as a style-property path — `undefined` when no such property exists. */
+function nameAsProperty(config, key) {
+	return config.resolve("style-property", key) ? key : void 0;
+}
+/**
+* A bag with every key rewritten to the property it writes, resolved through the definitions that
+* have a claim on it ({@link stylePropertyPathFor}). The one place a bag's authored names become
+* properties.
+*
+* Applied at each boundary rather than per key inside each consumer, so `styleDeclarations`, the CSS
+* emitter and `splitStyleProps` all stay pure functions of a property-keyed bag and cannot disagree
+* about what a key meant. A key that writes no style property is left alone, under the name it was
+* authored with: it is the element's own (`as`, `type`, `onClick`), and the consumer routes it there.
+*
+* `_<modifier>` blocks hold an ordinary bag against the same definitions, so they recurse.
+*/
+function routedBag({ config, through, bag }) {
+	const routed = {};
+	for (const [key, value] of Object.entries(bag)) {
+		if (key.startsWith("_") && value !== null && typeof value === "object" && !Array.isArray(value)) {
+			routed[key] = routedBag({
+				config,
+				through,
+				bag: value
+			});
+			continue;
+		}
+		const writes = stylePropertyPathFor({
+			config,
+			through,
+			key
+		});
+		routed[writes ?? key] = value;
+	}
+	return routed;
+}
+/**
+* The leaf a bag value names, for looking its entry up — or `undefined` when it names none.
+*
+* 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) {
+	if (typeof value === "boolean") return value ? "" : void 0;
+	if (typeof value === "string" || typeof value === "number") return String(value);
+}
+function styleDeclarations({ config, bag, namespace }) {
+	const out = {};
+	const fades = /* @__PURE__ */ new Map();
+	for (const [rawKey, value] of Object.entries(bag)) {
+		if (rawKey.startsWith("_") || rawKey.startsWith("--")) continue;
+		const key = stylePropertyPathFor({
+			config,
+			key: rawKey
+		}) ?? rawKey;
+		const target = (config.resolve("style-property", key)?.toJSON())?.opacityOf;
+		if (!isRef(target)) continue;
+		const rendered = renderBagValue({
+			config,
+			key,
+			value,
+			namespace
+		});
+		if (rendered === void 0) continue;
+		const amount = opacityPercentage(rendered);
+		if (amount !== void 0) fades.set(pathOf(target), amount);
+	}
+	for (const [rawKey, value] of Object.entries(bag)) {
+		if (rawKey.startsWith("_")) continue;
+		if (rawKey.startsWith("--")) {
+			out[rawKey] = renderStyleValue(config, value, namespace);
+			continue;
+		}
+		const key = stylePropertyPathFor({
+			config,
+			key: rawKey
+		}) ?? rawKey;
+		const prop = config.resolve("style-property", key);
+		if (!prop) continue;
+		const body = prop.toJSON();
+		if (isRef(body.opacityOf)) continue;
+		const cssProperties = Array.isArray(body.properties) ? body.properties : [];
+		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);
+			continue;
+		}
+		const base = renderBagValue({
+			config,
+			key,
+			value,
+			namespace
+		});
+		if (base === void 0) continue;
+		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;
+	}
+	return out;
+}
+/** One bag value as CSS text, or `undefined` for a flag turned off. */
+function renderBagValue({ config, key, value, namespace }) {
+	let resolved = value;
+	if (typeof value === "string") {
+		const qualified = stylePropValueFromLeaf(config, key, value);
+		if (qualified !== void 0) resolved = qualified;
+	}
+	if (typeof value === "boolean") {
+		if (!value) return void 0;
+		const bare = stylePropValueFromLeaf(config, key, "");
+		if (bare === void 0) return void 0;
+		resolved = bare;
+	}
+	return renderStyleValue(config, resolved, namespace);
+}
+/**
+* An opacity value as a `color-mix()` share.
+*
+* A system may scale opacity as a fraction (`0.5`) or as a percentage (`50%`), and `color-mix()`
+* takes only the latter — a bare `0.5` there is not a small share but a syntax error, and the
+* browser drops the whole declaration.
+*
+* A token reference is the common case and cannot be read here: the value is a `var()`, and what it
+* holds is the theme's answer, which changes per mode. So it is scaled in CSS (`calc(… * 100%)`)
+* rather than resolved, which commits the config to authoring opacity tokens as fractions — the same
+* convention CSS's own `opacity` property uses.
+*/
+function opacityPercentage(value) {
+	if (value.includes("var(")) return `calc(${value} * 100%)`;
+	if (value.trim().endsWith("%")) return value.trim();
+	const numeric = Number(value);
+	if (!Number.isFinite(numeric)) return void 0;
+	return numeric <= 1 ? `${numeric * 100}%` : `${numeric}%`;
+}
+/**
+* A component's effective props — its own props merged over those it inherits by `extends`ing
+* another component. A child prop overrides the inherited one of the same name; a `null` child
+* prop omits an inherited one. A native-tag `extends` (a string, not a ref) inherits nothing,
+* and a composite doesn't extend, so both resolve to just their own props. Chases the `extends`
+* chain (transitive inheritance), cycle-guarded.
+*/
+function resolveComponentProps(config, path, seen = /* @__PURE__ */ new Set()) {
+	if (seen.has(path)) return {};
+	seen.add(path);
+	const comp = config.resolve("component", path);
+	if (!comp) return {};
+	const body = comp.toJSON();
+	const merged = {};
+	for (const [layer, entry] of Object.entries(forwardsOf(body))) {
+		const element = body.layers?.[layer];
+		if (!isRef(element)) continue;
+		const exposed = resolveComponentProps(config, pathOf(element.__ref), new Set(seen));
+		const taken = entry === "*" ? exposed : Object.fromEntries((Array.isArray(entry) ? entry : []).map((r) => isRef(r) ? memberOf(r)?.split("/").pop() : void 0).filter((name) => !!name && name in exposed).map((name) => [name, exposed[name]]));
+		for (const [name, decl] of Object.entries(taken)) if (!(name in merged)) merged[name] = decl;
+	}
+	for (const [name, prop] of Object.entries(body.props ?? {})) if (prop === null) delete merged[name];
+	else merged[name] = prop;
+	return merged;
+}
+/**
+* Which component actually declared one of a component's resolved props — its ultimate owner.
+*
+* `resolveComponentProps` answers *what* the props are and deliberately flattens away *where each came
+* from*. That provenance is a real question with more than one caller: a rename recorded against one
+* Component has to reach the documents of every component that exposes that prop through `inherits`
+* (`rewriteSpecRefs`), and telling an author which side of a merge a prop came from needs the same fact.
+*
+* Mirrors the merge exactly, so the two can't disagree:
+*
+*  - an own non-null declaration means this component owns it — a shadow stops the walk, which is why
+*    `HStack`'s own `gap` is `HStack`'s and not the `Box` `gap` it shadows;
+*  - an own `null` is the omit tombstone, so the prop does not exist here and has no owner;
+*  - otherwise the prop is inherited, and the answer is whatever the inherited component says —
+*    transitively, so `Button` → `Pressable` → `Box` reports `Box`.
+*
+* `undefined` when the component doesn't resolve, doesn't expose that prop, or tombstones it.
+*/
+function propOwner(config, path, prop, seen = /* @__PURE__ */ new Set()) {
+	if (seen.has(path)) return void 0;
+	seen.add(path);
+	const comp = config.resolve("component", path);
+	if (!comp) return void 0;
+	const body = comp.toJSON();
+	const own = body.props ?? {};
+	if (prop in own) return own[prop] === null ? void 0 : path;
+	for (const [layer, entry] of Object.entries(forwardsOf(body))) {
+		const element = body.layers?.[layer];
+		if (!isRef(element)) continue;
+		if (Array.isArray(entry) && !entry.some((r) => isRef(r) && memberOf(r)?.split("/").pop() === prop)) continue;
+		const owner = propOwner(config, pathOf(element.__ref), prop, new Set(seen));
+		if (owner) return owner;
+	}
+}
+/** A prop declaration's accepted value domain — the leaves an author may write (`warning`,
+*  `display2`, a variant name), plus an `accepts` check. Resolved once, relationally, from the prop's
+*  `type`: a `variant`'s own values; a `styleProperty`'s referenced value-set leaves; a `composite` group's
+*  member leaves. `null` when there's no enumerable domain (a slot/motion content prop, a free scalar,
+*  or an unconstrained style prop). The one place prop-value domains are derived — consumed by prop
+*  validation, the `get_component` prop-domain display, and the Studio value picker, so none re-derive. */
+function propValueDomain(config, decl) {
+	const domainRef = () => decl.value?.__ref;
+	if (decl.type === "variant") {
+		const target = domainRef();
+		if (target) {
+			const leaves = memberLeaves(config, target);
+			if (leaves.length === 0) return null;
+			return {
+				leaves,
+				accepts: (value) => leaves.includes(value)
+			};
+		}
+		const values = listedIn(decl.value) ?? [];
+		return {
+			leaves: values,
+			accepts: (v) => values.includes(v)
+		};
+	}
+	if (decl.type === "styleProperty") {
+		const target = domainRef();
+		if (!target) return null;
+		const path = splitRef(target).qualifiedPath;
+		const leaves = stylePropValueLeaves(config, path);
+		if (leaves.length === 0) return null;
+		return {
+			leaves,
+			accepts: (v) => stylePropValueFromLeaf(config, path, v) !== void 0
+		};
+	}
+	if (decl.type === "composite") {
+		const target = domainRef();
+		if (!target) return null;
+		const leaves = memberLeaves(config, target);
+		if (leaves.length === 0) return null;
+		return {
+			leaves,
+			accepts: (v) => memberFromLeaf(config, target, v) !== void 0
+		};
+	}
+	return null;
+}
+/** Validate a prop bag against a component's declared props — unknown props + per-value domain
+*  checks. Generic: it resolves each prop's domain via {@link propValueDomain} and checks membership;
+*  no per-prop-type logic here. Returns the error strings (empty = valid). Lives in config so the
+*  `component/validate` op's truth is config-defined and the pipeline only renders it. */
+function validateComponentProps(config, componentPath, props) {
+	const declared = resolveComponentProps(config, componentPath);
+	const errors = [];
+	for (const [name, value] of Object.entries(props)) {
+		const decl = declared[name];
+		if (!decl) {
+			errors.push(`unknown prop \`${name}\``);
+			continue;
+		}
+		const domain = propValueDomain(config, decl);
+		if (domain && !domain.accepts(String(value))) {
+			const shown = domain.leaves.slice(0, 8).map((leaf) => `'${leaf}'`).join(" | ");
+			const more = domain.leaves.length > 8 ? " | …" : "";
+			errors.push(`\`${name}\`: '${value}' not one of ${shown}${more}`);
+		}
+	}
+	return errors;
+}
+/**
+* The props one preview tile starts from: the component's `defaultProps` with its `previewProps`
+* over the top.
+*
+* Preview wins, and that direction is the whole reason this exists once. `previewProps` is the state
+* a person chose to show a component in — Button's `variant`, an Icon prop's example glyph — so a
+* surface showing that tile has to agree with it, while `defaultProps` remains the baseline for every
+* prop the tile doesn't pin. Get the order backwards and the panel reports a value the canvas isn't
+* rendering, which is invisible until someone edits the wrong one.
+*
+* THE PRECEDENCE RULE, stated once: only a RENDER surface — a preview tile, the catalogue card, slot
+* text seeding — reads this merge. An EDIT surface reads and writes the single field it owns
+* (`defaultProps` OR `previewProps`, never the merge), and anything that SEEDS committed data — a
+* prop binding, a forward's re-seed, a stored instance prop, a default-value form — reads raw
+* `defaultProps`. A preview value that reaches any of those stops being staging and becomes a real
+* default the moment it is saved, which is exactly the leak UDS-3514 closed. Before adding a caller,
+* decide which of the three it is.
+*
+* Empty is the answer for a component that declares neither, and for a path that names no component
+* at all — a caller asking about something absent gets "nothing pinned", not a crash.
+*
+* A fresh object per call, like every projection here. Callers that feed it to a React dep array
+* memoize on the config and the path, which is what actually changes.
+*
+* Read through `Entity.body` rather than `Component.get`, which would be the typed way to ask: this
+* module is imported by `entities/system/Component.ts` (for `resolveComponentProps` and
+* `validateComponentProps`), so importing the class back would close a runtime cycle. `body` is the
+* accessor that exists for a reader which can't reach its entity class, and it is not `toJSON` —
+* serialization is for storage and the wire.
+*/
+function previewDefaults(config, path) {
+	const component = config.resolve("component", path);
+	if (!component) return {};
+	const { defaultProps, previewProps } = component.body;
+	return {
+		...defaultProps,
+		...previewProps
+	};
+}
+/**
+* The preview grid a component implies.
+*
+* Nothing new is being said here: a style rule's `when` names a prop and a value, which is an axis
+* and a point on it, and a rule's `_hover` block is a state worth a column. Authoring a matrix
+* restated all of that beside the thing it was derived from, and the two could disagree — a variant
+* added to `styles` and forgotten in the matrix just never appeared in the grid.
+*
+* A composite-typed prop is the same statement made relationally: each member of the group it
+* references is a whole bag of style declarations, so sweeping the prop sweeps styles exactly the
+* way a `when` does — the rules just never restate it. Left unchased, a component styled entirely
+* through composites (a text primitive whose `variant` names a composite group) implies an empty
+* grid, which reads as "no variants" rather than "fifty of them".
+*
+* So a component only authors what a preview can't know: the props one tile starts from.
+*/
+function previewMatrix(config, path) {
+	const component = config.resolve("component", path);
+	if (!component) return {
+		props: {},
+		modifiers: []
+	};
+	const { styles = {}, props: declared = {} } = component.toJSON();
+	const props = {};
+	const modifiers = /* @__PURE__ */ new Set();
+	for (const rule of Object.values(styles)) {
+		for (const [prop, stored] of Object.entries(rule.when ?? {})) {
+			const value = String(refLeaf(stored));
+			const values = props[prop] ?? [];
+			if (!values.includes(value)) values.push(value);
+			props[prop] = values;
+		}
+		for (const bag of Object.values(rule.layers ?? {})) for (const key of Object.keys(bag ?? {})) {
+			if (!key.startsWith("_")) continue;
+			if (modifierCategory(config, key.slice(1)) === "state") modifiers.add(key);
+		}
+	}
+	for (const [name, decl] of Object.entries(declared)) {
+		if (decl?.type === "composite" && isRef(decl.value)) {
+			const values = declaredFirst([...memberLeaves(config, decl.value)], props[name] ?? []);
+			if (values.length > 0) props[name] = values;
+		}
+		if (decl?.type === "variant") {
+			const values = declaredFirst(isRef(decl.value) ? [] : listedIn(decl.value) ?? [], props[name] ?? []);
+			if (values.length > 0) props[name] = values;
+		}
+	}
+	return {
+		props,
+		modifiers: [...modifiers]
+	};
+}
+/** The declared values in declaration order, then any rule-named value the declaration doesn't list. */
+function declaredFirst(declared, ruleNamed) {
+	return [...declared, ...ruleNamed.filter((value) => !declared.includes(value))];
+}
+/**
+* A prop's value as the component declares it, from the string a preview axis spells it as.
+*
+* `previewMatrix` names every axis value as a string (`'true'`, `'2'`), and a rule matches on the
+* string form too, so a surface reading the grid never sees the declared type. Anything that writes
+* a value back — a default chosen off a cell — restores it here, or a boolean prop's default is
+* stored as the string `'true'` and never equals the `true` an author writes.
+*/
+function propValueFromAxis(config, path, prop, value) {
+	const declared = resolveComponentProps(config, path)[prop];
+	if (declared?.type === "boolean") return value === "true";
+	if (declared?.type === "number") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : value;
+	}
+	return value;
+}
+//#endregion
+export { authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropRouting, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };