@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/framework/render-spec.js

@@ -0,0 +1,809 @@
+import { kindOf, memberOf, pathOf, ref, splitRef } from "./utils/refs.js";
+import { authoredBag, memberFromLeaf, resolveComponentProps } from "./projections.js";
+import { intoName, routesContent } from "./prop-surface.js";
+import { graftPreviewElements } from "../spec/preview-elements.js";
+import { componentLayerClass, componentPropClasses, componentRuleClasses, layerCompositeProps, splitStyleProps, styleRuleMotionClasses } from "./class-names.js";
+//#region src/framework/render-spec.ts
+const refOf = (value) => typeof value?.__ref === "string" ? value.__ref : void 0;
+const layerOf = (element) => {
+	const target = refOf(element);
+	if (target === void 0) return void 0;
+	const { kind, qualifiedPath } = splitRef(target);
+	return kind === "layer" ? qualifiedPath : void 0;
+};
+/** The prop a node's element is CHOSEN BY — `{ $state: '/name' }`. */
+const boundPropOf = (element) => {
+	const marker = element?.$state;
+	return typeof marker === "string" ? marker.replace(/^\//, "") : void 0;
+};
+/** The slot PROP a node STANDS FOR — a `Slot`-typed node whose `name` prop says which prop's
+*  instance content splices at its position among the siblings. json-render's own vocabulary (the
+*  `Slot` registry primitive and its `name` prop), so the stored node and the rendered element are
+*  one grammar. */
+const slotAnatomyPropOf = (node) => {
+	if (node?.element !== "Slot") return void 0;
+	const name = node.props?.name;
+	return typeof name === "string" ? name : void 0;
+};
+const bodyOf = (config, path) => config.resolve("component", path)?.toJSON();
+/** The node a tree is rooted at — the one named `root`, else the first declared. The same rule
+*  `rootLayerOf` uses for layers, which is why neither is stored. */
+function rootKeyOf(nodes) {
+	return "root" in nodes ? "root" : Object.keys(nodes)[0] ?? "root";
+}
+/** Every key a node holds — child edges plus slot fills, which nest without an edge. */
+function heldKeys(node) {
+	return [...node?.children ?? [], ...Object.values(node?.slots ?? {}).flat()];
+}
+/** How many nodes a key reaches, itself included — the size of the tree hanging off it. Visited-set
+*  guarded, so a cycle counts each node once instead of running forever. */
+function reachOf(nodes, from) {
+	const seen = new Set([from]);
+	const queue = [from];
+	while (queue.length > 0) {
+		const key = queue.shift();
+		for (const child of heldKeys(nodes[key])) {
+			if (seen.has(child)) continue;
+			seen.add(child);
+			queue.push(child);
+		}
+	}
+	return seen.size;
+}
+/**
+* The node a tree ENTERS at — the one nothing else claims as a child.
+*
+* A name can't answer this. `root` names the root LAYER, and a render is free to put a wrapper above
+* that layer — a menu provider, a positioner, a portal — so the layer is somewhere in the middle of
+* its own tree. Entering by name amputated every ancestor: the tree rendered without the provider
+* that its own descendants read from, and those descendants threw on the first paint.
+*
+* Structure states it instead, and in a whole tree exactly one node is unclaimed. Two or more is a
+* FOREST — a reader that couldn't finish, or a condition that left siblings with no parent — and then
+* the component is whichever of them holds most of it: the strays get dropped either way, and
+* dropping the real tree to render a stray leaf is the worse of the two. Nothing unclaimed at all
+* (a cycle) falls back to the name, which is the best a malformed tree deserves.
+*/
+function entryKeyOf(nodes) {
+	const claimed = /* @__PURE__ */ new Set();
+	for (const node of Object.values(nodes)) for (const child of heldKeys(node)) claimed.add(child);
+	const unclaimed = Object.keys(nodes).filter((key) => !claimed.has(key));
+	if (unclaimed.length <= 1) return unclaimed[0] ?? rootKeyOf(nodes);
+	let best = unclaimed[0];
+	let bestReach = reachOf(nodes, best);
+	for (const key of unclaimed.slice(1)) {
+		const reach = reachOf(nodes, key);
+		if (reach > bestReach || reach === bestReach && key === "root") {
+			best = key;
+			bestReach = reach;
+		}
+	}
+	return best;
+}
+/** What a node's `element` renders, as a spec `type`. A layer ref resolves through the component's
+*  own layers to whatever that layer is; a bound element has no json-render form (its `type` is a
+*  plain string), so it is reported rather than guessed at. */
+function typeOf(layers, element) {
+	const layer = layerOf(element);
+	const target = layer === void 0 ? element : layers[layer];
+	if (typeof target === "string") return target;
+	return refOf(target);
+}
+/**
+* A node's stored props as an author wrote them. The anatomy keeps a style prop's token as a ref
+* (`bg` as `token:spectrum/carbon/5`) so a rename cascades; a spec sets the leaf the prop's own
+* domain names (`carbon/5`), and a component handed the ref object paints nothing. `authoredBag` is
+* the one inverse of that binding, so the projection reads through it rather than trimming a path.
+*/
+function authoredProps(config, props) {
+	return props ? authoredBag(config, props) : {};
+}
+/**
+* A component's anatomy, projected to the json-render spec a canvas reads.
+*
+* The artifact's SOURCE changes and its shape does not: `element` becomes `type` and a ref
+* serializes to its string form, while `children` / `visible` / `text` pass through, since those
+* were borrowed from json-render's own vocabulary rather than invented.
+*
+* A component with no stored anatomy but ONE layer is still answered outright — it is one element,
+* and that was always stated rather than run.
+*/
+function deriveSpec(config, path) {
+	const body = bodyOf(config, path) ?? {};
+	const layers = body.layers ?? {};
+	const anatomy = body.anatomy;
+	if (!anatomy || Object.keys(anatomy).length === 0) {
+		if (Object.keys(layers).length !== 1) return void 0;
+		return instanceSpec(path, {
+			"data-uds-component": path,
+			"data-uds-layer": rootKeyOf(layers)
+		});
+	}
+	const elements = {};
+	for (const [key, node] of Object.entries(anatomy)) {
+		const slotAnatomyProp = slotAnatomyPropOf(node);
+		if (slotAnatomyProp !== void 0) {
+			elements[key] = {
+				type: "Slot",
+				props: {
+					...authoredProps(config, node.props),
+					"data-uds-slot-anatomy": slotAnatomyProp
+				}
+			};
+			continue;
+		}
+		const type = typeOf(layers, node.element);
+		if (!type) return void 0;
+		const layer = layerOf(node.element);
+		const props = {
+			...authoredProps(config, node.props),
+			...node.text !== void 0 ? { children: node.text } : {},
+			...layer !== void 0 ? {
+				"data-uds-layer": layer,
+				"data-uds-component": path
+			} : {}
+		};
+		elements[key] = {
+			type,
+			...Object.keys(props).length ? { props } : {},
+			...node.children?.length ? { children: node.children } : {},
+			...node.slots && Object.keys(node.slots).length ? { slots: node.slots } : {},
+			...node.visible !== void 0 ? { visible: node.visible } : {}
+		};
+	}
+	return {
+		root: entryKeyOf(elements),
+		elements
+	};
+}
+/**
+* ONE COMPONENT, as a spec — the instance form, and the only place the `component:` prefix is minted.
+*
+* A spec type is `kind:identity`, always: the emitted registry keys every entry that way and holds
+* no bare names, so `Box` resolves to nothing while `component:Box` resolves to the module. That
+* makes the prefix load-bearing rather than decorative, and something load-bearing spelled by
+* string-concatenation at each site is a spelling waiting to drift — three places in this file did
+* it, and a consumer that wanted the same shape had no choice but to add a fourth.
+*
+* So consumers ask for the SHAPE instead of assembling it, and the type itself comes from `ref` —
+* the same maker `Component.ref` is bound to — rather than a template. A caller outside this
+* package has no business knowing the prefix at all.
+*/
+function instanceSpec(path, props = {}) {
+	return {
+		root: "root",
+		elements: { root: {
+			type: ref("component", path).__ref,
+			props
+		} }
+	};
+}
+/**
+* The spec for a component, ALWAYS — the leaf form when its composition doesn't project.
+*
+* `deriveSpec` declines rather than guess, and that is right: a tree missing a node is worse than an
+* admission that it can't be built. But a caller still has to paint something, and the honest thing to
+* paint is the component ITSELF — one element, `component:<path>`, which the renderer resolves to the
+* real module with whatever its render closes over intact. That is strictly better than the previous
+* fallback (a spec captured by an earlier build), which showed a structure the config no longer
+* describes and let an editor author against it.
+*
+* So the two answers are separated: what to RENDER (always available) and WHICH of the two it is. A
+* surface reads `kind` to decide whether to offer composition tools, and `reason` to explain why not.
+*/
+function componentSpec(config, path) {
+	const derived = deriveSpec(config, path);
+	if (derived) return {
+		spec: derived,
+		kind: "composition"
+	};
+	const body = bodyOf(config, path) ?? {};
+	const layers = Object.keys(body.layers ?? {}).length;
+	const reason = !body.anatomy || Object.keys(body.anatomy).length === 0 ? `"${path}" has ${layers} layers but no anatomy saying how they assemble, so its composition can't be shown or edited here — it renders as itself.` : `"${path}" has an element whose type only an instance settles (a bound element), so its composition can't be shown or edited here — it renders as itself.`;
+	return {
+		spec: instanceSpec(path),
+		kind: "leaf",
+		reason
+	};
+}
+/**
+* A component as it is SHOWN — itself, in the example state its author wrote.
+*
+* The sibling above answers "what is this made of", and that is the question a layer panel and a
+* variant matrix ask. A catalogue card, a palette card and a docs thumbnail ask the other one, and
+* answering them with a composition is what left those tiles wrong: {@link deriveSpec} reads anatomy
+* off the render's JSX STATICALLY, without the preview's props, so a prop-driven branch arrives as an
+* unresolved `$state` condition and prop-driven text doesn't arrive at all. The tile painted the
+* structure with its example content missing.
+*
+* One element, always, whatever the component is made of — because WHO DRAWS IT isn't this
+* projection's call. A built component is in the renderer's registry, so the element resolves to its
+* real module and is handed the example props directly. One created in Studio isn't, so
+* {@link expandSpec} replaces it with the tree the config describes, resolving those same props'
+* conditions and bound elements on the way. Both paths exist already; emitting the component and
+* letting the renderer choose is what reaches them.
+*
+* Only the preview's props. A component's `defaultProps` are already folded into its layer's
+* zero-specificity rule at build time, so seeding them here would re-apply as an instance's style
+* props what the stylesheet has said once already.
+*
+* One stored preview value is not a prop yet: JSX such as `startIcon: <Icon/>` crosses config.json as
+* a `PreviewElement` data marker. It is lowered here into the native `slots` + keyed-element form a
+* spec authors directly. That makes this projection render-ready for every host instead of relying on
+* a Studio-only registry wrapper to revive the marker later.
+*/
+function previewSpec(config, path) {
+	const body = bodyOf(config, path);
+	if (!body) return void 0;
+	const values = body.previewProps ?? {};
+	return graftPreviewElements(instanceSpec(path, values), values);
+}
+/** A key no emitted element is using yet. Anatomy keys are namespaced under the instance they belong
+*  to, so two instances of one component can't collide; the suffix loop is the backstop for a
+*  design file that happens to have named an element the same thing. */
+function freeKey(sink, hint) {
+	if (!(hint in sink.elements)) return hint;
+	let index = 2;
+	while (`${hint}${index}` in sink.elements) index += 1;
+	return `${hint}${index}`;
+}
+/** Whether this expansion should replace `type` with what the config says it's made of. */
+function expandable(sink, type) {
+	if (kindOf(type) !== "component") return false;
+	if (sink.rendered?.has(type)) return false;
+	const path = pathOf(type);
+	if (sink.expanding.includes(path)) return false;
+	return sink.config.resolve("component", path) !== void 0;
+}
+/**
+* Resolve every element's `visible` CONDITION against a prop bag, leaving a plain boolean.
+*
+* json-render evaluates the condition itself at render time, so this changes nothing about what
+* paints. What it changes is what the spec can be ASKED: an unresolved `{ $state: '/startIcon' }`
+* says only "it depends", where `false` says "this draws nothing", and a reader that has to decide
+* whether a container is empty needs the second.
+*
+* That reader is the UDS renderer. A container whose children all draw nothing must fall back to its
+* `props.children` label — and with the condition unresolved it could not tell, so every `Button`
+* cell in the matrix rendered blank: the root lists `startIcon`/`endIcon`, and an unset icon is a
+* node whose condition is false. `expandSpec` already resolves visibility for an INSTANCE; this is
+* the same answer for a spec rendered as the component's own anatomy, where the caller supplies the
+* state instead of an instance.
+*
+* A condition that does not resolve is left exactly as it was, so nothing is claimed about it.
+*/
+function specWithResolvedVisibility(spec, state) {
+	let changed = false;
+	const elements = {};
+	for (const [key, element] of Object.entries(spec.elements)) {
+		const resolved = element.visible === void 0 ? void 0 : resolveVisibility(element.visible, state);
+		if (resolved === void 0 || resolved === element.visible) {
+			elements[key] = element;
+			continue;
+		}
+		changed = true;
+		elements[key] = {
+			...element,
+			visible: resolved
+		};
+	}
+	return changed ? {
+		...spec,
+		elements
+	} : spec;
+}
+/**
+* How each operator judges a state value against its operand. One table for every reader of the
+* grammar: `resolveVisibility` applies it, `visibilityTerms` names it, and the entity's schema is
+* checked against its keys. Insertion order is precedence for a malformed test that carries more
+* than one operator, and the readers share it through {@link OPERATORS}.
+*/
+const COMPARATORS = {
+	eq: (value, operand) => value === operand,
+	neq: (value, operand) => value !== operand,
+	gt: (value, operand) => Number(value) > Number(operand),
+	gte: (value, operand) => Number(value) >= Number(operand),
+	lt: (value, operand) => Number(value) < Number(operand),
+	lte: (value, operand) => Number(value) <= Number(operand)
+};
+const OPERATORS = Object.keys(COMPARATORS);
+/** The operator a `$state` test carries, or undefined for a bare truthiness test. */
+function operatorOf(test) {
+	return OPERATORS.find((name) => name in test);
+}
+/** A value in json-render's `visible` grammar, resolved against a prop bag. `undefined` when this
+*  reader can't settle it, which leaves the condition on the element for the renderer to judge. */
+function resolveVisibility(condition, state) {
+	if (condition === void 0) return true;
+	if (typeof condition === "boolean") return condition;
+	if (Array.isArray(condition)) {
+		let known = true;
+		for (const entry of condition) {
+			const result = resolveVisibility(entry, state);
+			if (result === false) return false;
+			if (result === void 0) known = false;
+		}
+		return known ? true : void 0;
+	}
+	if (typeof condition !== "object" || condition === null) return void 0;
+	const test = condition;
+	if (Array.isArray(test.$or)) {
+		let known = true;
+		for (const entry of test.$or) {
+			const result = resolveVisibility(entry, state);
+			if (result === true) return true;
+			if (result === void 0) known = false;
+		}
+		return known ? false : void 0;
+	}
+	if (Array.isArray(test.$and)) return resolveVisibility(test.$and, state);
+	if (typeof test.$state !== "string") return void 0;
+	const value = state[test.$state.replace(/^\//, "")];
+	const operator = operatorOf(test);
+	const result = operator ? COMPARATORS[operator](value, test[operator]) : Boolean(value);
+	return test.not === true ? !result : result;
+}
+/**
+* Which PROPS a `visible` condition reads, in the order they appear.
+*
+* `resolveVisibility` answers "does this draw here"; this answers "what decides that" — the question
+* an editor asks. A surface offering to bind visibility to a property needs to know whether one is
+* already driving it, and a surface refusing an edit needs to name what to change instead of the
+* layer. Both were guessing: the layers panel told an author to "switch to a matching cell" for a
+* node gated on a slot being filled, where no cell in the matrix can ever match.
+*
+* Duplicates are collapsed, so a condition testing one prop twice reads as the one prop it is about.
+*/
+function visibilityStateProps(condition) {
+	const names = [];
+	collectStateProps(condition, names);
+	return [...new Set(names)];
+}
+function collectStateProps(condition, sink) {
+	if (Array.isArray(condition)) {
+		for (const entry of condition) collectStateProps(entry, sink);
+		return;
+	}
+	if (typeof condition !== "object" || condition === null) return;
+	const test = condition;
+	if (Array.isArray(test.$or)) {
+		for (const entry of test.$or) collectStateProps(entry, sink);
+		return;
+	}
+	if (Array.isArray(test.$and)) {
+		for (const entry of test.$and) collectStateProps(entry, sink);
+		return;
+	}
+	if (typeof test.$state === "string") sink.push(test.$state.replace(/^\//, ""));
+}
+/**
+* The tests a `visible` condition makes, in order, flattened to one list.
+*
+* `visibilityStateProps` names the props; this keeps what is asked of each one, so a surface can say
+* "shows when `tone` is `danger`" rather than "follows `tone`". Grouping survives as `junction` and
+* `group`: the stored grammar is an and-list whose entries are single tests or one `$or` each, so
+* the two together are enough to read the condition back. A boolean or a shape this reader does not
+* know yields no terms.
+*/
+function visibilityTerms(condition) {
+	const sink = [];
+	collectTerms({
+		condition,
+		junction: "and",
+		group: 0,
+		sink
+	});
+	return sink;
+}
+/** The index for a term that opens a new group: one past the last term collected. */
+function nextGroup(sink) {
+	const last = sink[sink.length - 1];
+	return last ? last.group + 1 : 0;
+}
+function collectTerms({ condition, junction, group, sink }) {
+	if (Array.isArray(condition)) {
+		for (const entry of condition) collectTerms({
+			condition: entry,
+			junction: "and",
+			group: nextGroup(sink),
+			sink
+		});
+		return;
+	}
+	if (typeof condition !== "object" || condition === null) return;
+	const test = condition;
+	if (Array.isArray(test.$or)) {
+		const shared = nextGroup(sink);
+		for (const entry of test.$or) collectTerms({
+			condition: entry,
+			junction: "or",
+			group: shared,
+			sink
+		});
+		return;
+	}
+	if (Array.isArray(test.$and)) {
+		collectTerms({
+			condition: test.$and,
+			junction: "and",
+			group,
+			sink
+		});
+		return;
+	}
+	if (typeof test.$state !== "string") return;
+	const operator = operatorOf(test);
+	sink.push({
+		prop: test.$state.replace(/^\//, ""),
+		operator: operator ?? "truthy",
+		...operator ? { value: test[operator] } : {},
+		negated: test.not === true,
+		junction,
+		group
+	});
+}
+/**
+* A `visible` condition with every bare truthiness test of `prop` taken out.
+*
+* Three answers: `undefined` for a condition that makes no such test, so a caller leaves the field
+* alone; `null` when nothing survives the removal, which is the value that clears it; otherwise the
+* condition that remains, unwrapped when one term is left.
+*
+* Only the bare form goes — `{ $state: '/prop' }` with no comparison and no `not`, which is the test
+* a value being present answers. A `$or` group holding one goes whole, since a true member settles
+* the group; its other members go with it, and moving the fill out later does not bring them back,
+* which is also true of a bare gate. `$state` is matched without its JSON-pointer slash, so both
+* spellings are the same test.
+*/
+function withoutTruthyTerm({ condition, prop }) {
+	if (spentBy({
+		condition,
+		prop
+	})) return null;
+	if (!Array.isArray(condition)) return void 0;
+	const kept = condition.filter((entry) => !spentBy({
+		condition: entry,
+		prop
+	}));
+	if (kept.length === condition.length) return void 0;
+	if (kept.length === 0) return null;
+	return kept.length === 1 ? kept[0] : kept;
+}
+/** Whether a single term of an and-list is one `prop` being present makes true: the bare test, an
+*  `eq: true` test (content is never the boolean `true`, so presence is the only reading that can
+*  ever hold), or an `$or` group with one of those among its members. */
+function spentBy({ condition, prop }) {
+	if (typeof condition !== "object" || condition === null) return false;
+	const test = condition;
+	if (Array.isArray(test.$or)) return test.$or.some((entry) => spentBy({
+		condition: entry,
+		prop
+	}));
+	if (typeof test.$state !== "string") return false;
+	return test.$state.replace(/^\//, "") === prop && test.not !== true && (operatorOf(test) === void 0 || operatorOf(test) === "eq" && test.eq === true);
+}
+/**
+* The type a BOUND element resolves to, given the value its prop was handed.
+*
+* This is the one thing json-render has no vocabulary for — `UIElement.type` is a plain string — so
+* a stored spec can't hold it and `deriveSpec` declines. An expansion is a different position: the
+* instance is right here, so the prop has a value, and the prop's own declaration says what domain
+* that value is drawn from. `Icon` is the case that matters: one bound node, resolved per instance,
+* rather than 51 conditioned siblings copying a library's index into every component that draws a
+* glyph.
+*
+* Two ways the domain is known, in order: the prop DELEGATES it (`value` is a ref to the library,
+* which is the shape that keeps 1,530 names in one place), or the prop enumerates its values and the
+* member is found by asking which group declares it. The second exists because a config migrated
+* from v1 spells an icon prop as an enumeration, and a glyph is no less resolvable for it.
+*/
+function boundElementType(config, componentPath, prop, value) {
+	if (typeof value !== "string" || !value) return void 0;
+	if (value.includes("/")) return void 0;
+	const decl = resolveComponentProps(config, componentPath)[prop];
+	const target = refOf(decl?.value);
+	if (target) {
+		if (memberOf(target) !== void 0) return void 0;
+		const member = memberFromLeaf(config, target, value);
+		return member ? `${kindOf(target)}:${member}` : void 0;
+	}
+	const matches = config.list("icon").filter((member) => (member.path.split("/").pop() ?? "") === value);
+	return matches.length === 1 ? `icon:${matches[0]?.path}` : void 0;
+}
+/**
+* The props of an instance that the component CONSUMES rather than passes on — the same split the
+* emitted module's destructuring makes (`downlevel.ts`, `styleRuleBindings`).
+*
+* A variant selects a style rule and a slot routes content, so neither reaches the DOM. Neither does
+* a DECLARED prop a style rule tests: the config says it picks a class and says nothing else about
+* it, which makes it part of the component's API rather than an attribute. `PanelIconButton`'s
+* `active` is the shape of it — a boolean the rules branch on, spread onto the button by both this
+* projection and the emitted module until each learned to consume it.
+*
+* An UNDECLARED prop a rule tests stays: the component never claimed it, so a call site passing it
+* (`disabled` on a Pressable) means it for the element.
+*/
+function consumedProps(config, path, body) {
+	const consumed = new Set(["className", "layerProps"]);
+	const declared = body.props ?? {};
+	for (const [name, decl] of Object.entries(declared)) if (decl?.type === "variant" || decl?.type === "slot" || decl?.type === "forward" || decl?.type === "composite") consumed.add(name);
+	for (const rule of componentRuleClasses(config, path)) for (const prop of Object.keys(rule.when)) if (declared[prop]) consumed.add(prop);
+	return consumed;
+}
+/** The prop JSX children arrive on — json-render's content channel, and the same name
+*  `childrenPolicy` reads to answer whether a component accepts any. Not a system-defined name: a
+*  design system names its components and tokens, and this one names the channel. */
+const CONTENT_PROP = "children";
+function slotTargets(config, body) {
+	const byLayer = /* @__PURE__ */ new Map();
+	const untargeted = [];
+	for (const [from, decl] of Object.entries(body.props ?? {})) {
+		if (decl?.type === "slot") {
+			untargeted.push({
+				...decl,
+				from,
+				untargeted: true
+			});
+			continue;
+		}
+		if (decl?.type !== "forward") continue;
+		if (!routesContent(config, body.layers, decl)) continue;
+		const target = refOf(decl.target);
+		if (target) byLayer.set(pathOf(target), {
+			...decl,
+			from
+		});
+		else untargeted.push({
+			...decl,
+			from,
+			untargeted: true
+		});
+	}
+	const root = rootKeyOf(body.layers ?? {});
+	const content = untargeted.find((route) => route.from === CONTENT_PROP) ?? untargeted[0];
+	if (root && content && !byLayer.has(root)) byLayer.set(root, content);
+	return {
+		byLayer,
+		untargeted
+	};
+}
+/**
+* Where a component's slot props route their content, as the config states it.
+*
+* {@link expandInstance} has always known this; nothing outside this file could ask. A surface that
+* needs the same answer had to guess from the spec's shape instead — "the one element carrying a
+* string" — and a spec projected from the ANATOMY carries no strings at all, so the guess fell
+* through to the root. For a component whose content slot NAMES its layer that is the wrong element
+* AND an occupied one: the label lands beside the element children it was supposed to go inside, and
+* the layer meant to hold it renders empty. Every one of Studio's own components shaped that way
+* (`Badge`, `StudioButton`, `Toggle`, …) painted as an empty shell in the component editor.
+*
+* Exported so the answer has ONE owner. An untargeted slot still resolves to the root here — that is
+* `slotTargets`' rule, not a caller's assumption, and it is the same rule the expansion renders by.
+*/
+function slotTargetsOf(config, path) {
+	const body = bodyOf(config, path);
+	if (!body) return [];
+	const { byLayer, untargeted } = slotTargets(config, body);
+	const root = rootKeyOf(body.layers ?? {});
+	return [...[...byLayer].filter(([, decl]) => !decl.untargeted).map(([layer, decl]) => ({
+		layer,
+		from: decl.from,
+		into: intoName(decl.into)
+	})), ...root ? untargeted.map((decl) => ({
+		layer: root,
+		from: decl.from,
+		into: intoName(decl.into)
+	})) : []];
+}
+/** The className a layer wears for one instance: its own class, every style rule whose condition
+*  holds, and — on the root only — what the call site passed. */
+function classesFor(config, path, layer, state, extra) {
+	const parts = [componentLayerClass(config, path, layer)];
+	parts.push(...componentPropClasses(config, path, state)[layer] ?? []);
+	parts.push(...styleRuleMotionClasses(config, path, state)[layer] ?? []);
+	for (const rule of componentRuleClasses(config, path)) {
+		if (rule.layer !== layer) continue;
+		if (Object.entries(rule.when).every(([prop, value]) => String(state[prop]) === String(value))) parts.push(rule.className);
+	}
+	parts.push(...extra);
+	return parts.filter(Boolean).join(" ");
+}
+/** Emit one element, expanding it when the config describes what it's made of. Returns the key it
+*  was emitted under. */
+function place(sink, type, props, children, hint, slots) {
+	if (expandable(sink, type)) return expandInstance(sink, pathOf(type), props, children, hint, slots);
+	let tag = type;
+	let own = props;
+	if (!type.includes(":") && typeof props.as === "string") {
+		const { as, ...rest } = props;
+		tag = as;
+		own = rest;
+	}
+	if (sink.rendered && !sink.rendered.has(tag)) sink.unresolved.add(tag);
+	const key = freeKey(sink, hint);
+	sink.elements[key] = {
+		type: tag,
+		props: own,
+		...children.length ? { children: [...children] } : {},
+		...slots && Object.keys(slots).length ? { slots } : {}
+	};
+	return key;
+}
+/**
+* Replace one component instance with the tree it is made of.
+*
+* Every class is computed HERE, from the config as it stands, which is the difference between this
+* and a stored spec: an edit to a token, a style rule or a layer shows up on the next render with
+* nothing to regenerate. `content` is the children the instance was given — placed on the root when
+* the component has nowhere else declared to put them.
+*/
+function expandInstance(sink, path, instanceProps, content, hint, instanceSlots) {
+	const { config } = sink;
+	const body = bodyOf(config, path) ?? {};
+	const layers = body.layers ?? {};
+	const anatomy = body.anatomy && Object.keys(body.anatomy).length > 0 ? body.anatomy : { root: { element: { __ref: `layer:${rootKeyOf(layers)}` } } };
+	const filled = {};
+	for (const [from, fills] of Object.entries(instanceSlots ?? {})) if (fills.length > 0 && instanceProps[from] === void 0) filled[from] = true;
+	const state = {
+		...body.defaultProps,
+		...filled,
+		...instanceProps
+	};
+	const consumed = consumedProps(config, path, body);
+	const { byLayer: targets } = slotTargets(config, body);
+	const supplied = {
+		...body.defaultProps ?? {},
+		...instanceProps
+	};
+	const bag = {};
+	for (const [name, value] of Object.entries(supplied)) if (!consumed.has(name)) bag[name] = value;
+	const { className: styleClasses, rest } = splitStyleProps({
+		config,
+		bag,
+		through: [path]
+	});
+	const layerProps = instanceProps.layerProps ?? {};
+	const forwarded = layerCompositeProps(config, path, state);
+	const entryNode = entryKeyOf(anatomy);
+	const rootLayer = rootKeyOf(layers);
+	const hostNode = Object.keys(anatomy).find((key) => layerOf(anatomy[key]?.element) === rootLayer) ?? entryNode;
+	const nested = {
+		...sink,
+		expanding: [...sink.expanding, path]
+	};
+	const rootTarget = targets.get(rootLayer);
+	const untargetedSlot = rootTarget?.untargeted ? rootTarget.from : void 0;
+	let contentPlaced = false;
+	const routedFroms = /* @__PURE__ */ new Set();
+	for (const target of targets.values()) routedFroms.add(target.from);
+	const unroutedFills = Object.entries(instanceSlots ?? {}).filter(([from]) => !routedFroms.has(from)).flatMap(([, fills]) => fills);
+	const allContent = [...content, ...unroutedFills];
+	const emit = (key, keyHint) => {
+		const node = anatomy[key];
+		if (!node) return void 0;
+		const visible = resolveVisibility(node.visible, state);
+		const layer = layerOf(node.element);
+		const isRoot = key === hostNode;
+		let type = typeOf(layers, node.element);
+		const bound = boundPropOf(node.element);
+		if (bound) type = boundElementType(config, path, bound, state[bound]);
+		if (!type) {
+			sink.unresolved.add(bound ? `component:${path}#${key} (${bound})` : `component:${path}#${key}`);
+			return;
+		}
+		if (visible === false) {
+			const key = freeKey(nested, keyHint);
+			nested.elements[key] = {
+				type,
+				props: {},
+				visible: false
+			};
+			return key;
+		}
+		const slot = layer ? targets.get(layer) : void 0;
+		const slotValue = slot ? instanceProps[slot.from] : void 0;
+		const props = layer ? {
+			...authoredProps(config, node.props),
+			"data-uds-component": path,
+			"data-uds-layer": layer,
+			...forwarded[layer],
+			...isRoot ? rest : {},
+			...slot && slotValue !== void 0 ? { [intoName(slot.into)]: slotValue } : {},
+			...layerProps[layer],
+			className: classesFor(config, path, layer, state, [
+				isRoot ? styleClasses : void 0,
+				isRoot ? instanceProps.className : void 0,
+				layerProps[layer]?.className
+			]) || void 0
+		} : authoredProps(config, node.props);
+		if (node.text !== void 0) props.children = node.text;
+		const children = [];
+		for (const child of node.children ?? []) {
+			const childSlot = slotAnatomyPropOf(anatomy[child]);
+			if (childSlot !== void 0) {
+				if (childSlot === untargetedSlot && allContent.length > 0) {
+					children.push(...allContent);
+					contentPlaced = true;
+				}
+				continue;
+			}
+			const placed = emit(child, `${keyHint}•${child}`);
+			if (placed) children.push(placed);
+		}
+		if (isRoot && allContent.length > 0 && !contentPlaced) children.push(...allContent);
+		const slots = {};
+		const routed = slot ? instanceSlots?.[slot.from] : void 0;
+		const overridden = routed?.length && slot && !slot.untargeted ? intoName(slot.into) : void 0;
+		for (const [name, fills] of Object.entries(node.slots ?? {})) {
+			if (name === overridden) continue;
+			const placedFills = fills.map((fill) => emit(fill, `${keyHint}•${fill}`)).filter((fillKey) => fillKey !== void 0);
+			if (placedFills.length) slots[name] = placedFills;
+		}
+		if (overridden && routed) slots[overridden] = [...routed];
+		if (routed?.length && !overridden) children.push(...routed);
+		const placed = place(nested, type, props, children, keyHint, Object.keys(slots).length ? slots : void 0);
+		if (visible === void 0) withCondition(nested, placed, { visible: node.visible });
+		return placed;
+	};
+	return emit(entryNode, hint) ?? hint;
+}
+/** Attach a condition the reader couldn't settle to an already-emitted element. */
+function withCondition(sink, key, condition) {
+	const element = sink.elements[key];
+	if (element && condition.visible !== void 0) sink.elements[key] = {
+		...element,
+		visible: condition.visible
+	};
+	return key;
+}
+/**
+* Expand every component element the renderer can't name into the tree it is made of.
+*
+* The spec's own keys are KEPT — an expanded instance's root is emitted under the key it already
+* had, so a `slots` entry, a selection marker, or anything else that names an element by key
+* still resolves. Only the nodes an expansion adds get new keys, namespaced under the instance they
+* belong to.
+*/
+function expandSpec(config, spec, options = {}) {
+	const sink = {
+		config,
+		rendered: options.rendered,
+		elements: {},
+		unresolved: /* @__PURE__ */ new Set(),
+		expanding: []
+	};
+	const emit = (key) => {
+		const element = spec.elements[key];
+		if (!element) return void 0;
+		const children = [];
+		for (const child of element.children ?? []) {
+			const placed = emit(child);
+			if (placed) children.push(placed);
+		}
+		const slots = {};
+		for (const [name, fills] of Object.entries(element.slots ?? {})) slots[name] = fills.map((fill) => emit(fill)).filter((placed) => placed !== void 0);
+		const placed = place(sink, element.type, { ...element.props }, children, key, slots);
+		if (element.visible !== void 0) withCondition(sink, placed, { visible: element.visible });
+		return placed;
+	};
+	return {
+		spec: {
+			root: emit(spec.root) ?? spec.root,
+			elements: sink.elements
+		},
+		unresolved: [...sink.unresolved]
+	};
+}
+/**
+* One component instance, expanded from nothing but the config — what a canvas paints for a
+* component created in Studio.
+*
+* The single-element spec this starts from is what a design-file node amounts to, so this is
+* {@link expandSpec} with the ceremony removed.
+*/
+function expandComponent(config, path, props = {}, options = {}) {
+	return expandSpec(config, instanceSpec(path, props), options);
+}
+//#endregion
+export { boundElementType, componentSpec, deriveSpec, entryKeyOf, expandComponent, expandSpec, instanceSpec, previewSpec, resolveVisibility, slotAnatomyPropOf, slotTargetsOf, specWithResolvedVisibility, visibilityStateProps, visibilityTerms, withoutTruthyTerm };