@yahoo/uds-create-config 1.1.1

package/dist/spec/layer-props.js

@@ -0,0 +1,149 @@
+import { makeTokenRefToCss } from "../entity-utils.js";
+import { isTokenRef } from "../refs.js";
+import { isColorExpression, resolveColorExpression } from "../colorExpressions.js";
+//#region src/spec/layer-props.ts
+const REST_STATE = "rest";
+const isStateKey = (key) => key.startsWith("_");
+/**
+* Resolve the styles a layer effectively has for a set of prop-axis values and
+* (optionally) one forced interaction state, walking the authoring surfaces
+* codegen reads:
+*
+*   1. `component.base[layer]` — the always-on baseline.
+*   2. `component.props[axis].values[value][layer]` — per axis key in `propValues`.
+*   3. `component.compoundProps[].layers[layer]` — for entries whose `when`
+*       is a subset of `propValues` (multi-axis overrides).
+*   4. State overlay — when `state` names a modifier sub-object (`_hover`) on
+*       the merged surface, its props overlay the base so a static preview
+*       shows that state.
+*
+* `propValues` are plain axis names → values (no reserved keys). `state` is a
+* single forced interaction modifier (`'_hover'`); pass it directly rather than
+* smuggling it into `propValues`. **Modes are intentionally not a parameter** —
+* mode visuals ride a scoped wrapper class (`.dark &`) and flip live, so they
+* are never folded into the static base here.
+*/
+function resolveAuthoredLayerProps(component, layer, propValues, state) {
+	if (!component) return {};
+	const merged = { ...component.base?.[layer] ?? {} };
+	for (const [key, value] of Object.entries(propValues)) {
+		const binding = component.props?.[key];
+		if (!binding || typeof binding !== "object") continue;
+		const layerStyles = pickAxisLayers(binding, value)?.[layer];
+		if (layerStyles) mergeLayerStyles(merged, layerStyles);
+	}
+	if (component.compoundProps) for (const entry of component.compoundProps) {
+		if (!matchesContext(entry.when, propValues)) continue;
+		const layerStyles = entry.layers[layer];
+		if (layerStyles && typeof layerStyles === "object") mergeLayerStyles(merged, layerStyles);
+	}
+	if (state && state !== REST_STATE && isStateKey(state)) {
+		const stateStyles = merged[state];
+		if (stateStyles && typeof stateStyles === "object") Object.assign(merged, stateStyles);
+	}
+	return merged;
+}
+/**
+* Resolve per-layer style bags for a set of prop values, mirroring the config's
+* variant resolution. `buildRenderSpec` calls this once per variant combo to
+* bake the bags onto the render spec.
+*
+* `state` is left `null` by the bake path — modifier blocks ride through as
+* nested style props and forced state is applied per cell (the render-spec
+* consumers fold the active modifier into props), so folding it into the base
+* here would be redundant. (Derived callers like the layers panel also pass no
+* state.) `cssVarPrefix` resolves color expressions to a `var(...)`-referencing
+* arbitrary value.
+*/
+function resolveRenderedLayerProps(component, propValues, state, cssVarPrefix) {
+	if (!component) return {};
+	const layerStyles = {};
+	for (const layerName of component.layers.keys()) layerStyles[layerName] = finalizeLayerProps(resolveAuthoredLayerProps(component, layerName, propValues, state), state, cssVarPrefix);
+	return layerStyles;
+}
+/**
+* Fold the active (selected) state's styles into the flat bag so the static
+* preview shows that state without real interaction, KEEP modifier blocks as
+* nested objects so the component renderer emits their classes (`_hover:bg-x`,
+* `_stackedChildren:ms-[-6px]`) — structural modifiers (child combinators,
+* attrs) apply and interaction states stay live — and bake color expressions
+* into arbitrary style-prop values so they flow through the class system
+* instead of an inline `style`.
+*/
+function finalizeLayerProps(styles, state, cssVarPrefix) {
+	const merged = { ...styles };
+	const stateStyles = state && isStateKey(state) ? styles[state] : void 0;
+	if (stateStyles && typeof stateStyles === "object") Object.assign(merged, stateStyles);
+	return bakeColorValues(merged, makeTokenRefToCss(cssVarPrefix));
+}
+/**
+* Resolve every color expression / token ref in a layer's style map to an
+* arbitrary `[…]` value, recursing into nested modifier blocks. A
+* `color-mix(...)` / `var(--…)` isn't a pre-compiled token class, so the
+* bracket form lets `getClassName` encode it into a class the same way it
+* handles `[16px]` — keeping styling renderer-agnostic (no inline `style` whose
+* `var(...)` the build would tree-shake).
+*/
+function bakeColorValues(styles, tokenRefToCss) {
+	const out = {};
+	for (const [key, value] of Object.entries(styles)) if (isColorExpression(value)) out[key] = `[${resolveColorExpression(value, tokenRefToCss)}]`;
+	else if (isTokenRef(value)) out[key] = `[${tokenRefToCss(value.ref)}]`;
+	else if (value !== null && typeof value === "object" && !Array.isArray(value)) out[key] = bakeColorValues(value, tokenRefToCss);
+	else out[key] = value;
+	return out;
+}
+/**
+* Layer `from` onto `into`, deep-merging interaction-state modifier blocks
+* (`_hover`, `_disabled`, …) instead of replacing them. A variant's
+* `_disabled: { borderColor }` must combine with `base`'s `_disabled: { opacity }`
+* — a shallow `Object.assign` would drop the base opacity, so the
+* secondary+disabled cell loses its dimming. Non-modifier props still
+* shallow-replace (a later authoring surface wins that property outright).
+*/
+function mergeLayerStyles(into, from) {
+	for (const [key, value] of Object.entries(from)) {
+		const existing = into[key];
+		if (isStateKey(key) && isStyleMap(existing) && isStyleMap(value)) into[key] = {
+			...existing,
+			...value
+		};
+		else into[key] = value;
+	}
+}
+/**
+* Pull the per-layer style map keyed by `value` off a `variant` / `boolean`
+* marker. Booleans accept a real boolean or its string form.
+*/
+function pickAxisLayers(binding, value) {
+	if (binding.__kind === "variant") {
+		const values = binding.values;
+		if (!values) return void 0;
+		const entry = values[String(value)];
+		return isStyleMap(entry) ? entry : void 0;
+	}
+	if (binding.__kind === "boolean") {
+		const values = binding.values;
+		if (!values) return void 0;
+		const key = coerceBooleanKey(value);
+		if (key === void 0) return void 0;
+		const entry = values[key];
+		return isStyleMap(entry) ? entry : void 0;
+	}
+}
+function isStyleMap(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function coerceBooleanKey(value) {
+	if (value === true || value === "true") return "true";
+	if (value === false || value === "false") return "false";
+}
+/**
+* `when` is a subset of `context` when every key in `when` is present in
+* `context` with the same stringified value.
+*/
+function matchesContext(when, context) {
+	for (const [k, v] of Object.entries(when)) if (String(context[k]) !== String(v)) return false;
+	return true;
+}
+//#endregion
+export { resolveAuthoredLayerProps, resolveRenderedLayerProps };

package/dist/spec/preview-controls.d.ts

@@ -0,0 +1,44 @@
+import { Component } from "../Component.js";
+import { Config } from "../Config.js";
+
+//#region src/spec/preview-controls.d.ts
+type PreviewControlKind = 'variant' | 'boolean' | 'string';
+interface PreviewControl {
+  readonly name: string;
+  readonly kind: PreviewControlKind;
+  readonly defaultValue: unknown;
+  /** Selectable values — set for `variant` controls (incl. composite/styleProp). */
+  readonly options?: readonly string[];
+}
+/**
+ * The selectable values for a prop, or `undefined` when it isn't option-backed.
+ * Resolves by the prop's declared kind: a `variant()`'s declared values, a
+ * `composite()`'s registered style keys (e.g. `textVariant` → its variant
+ * names), or a `styleProp()`'s token + keyword names. A name that isn't a
+ * declared prop falls back to a same-named registered style prop (the Box
+ * surface — e.g. `color`/`bg` set only via `preview.defaultProps`).
+ */
+declare function propOptions(config: Config, component: Component, name: string): readonly string[] | undefined;
+/**
+ * Editable preview controls for a component:
+ *
+ *   - `variant` → dropdown of declared values
+ *   - `composite` → dropdown, options from the registered composite
+ *   - `boolean` → toggle; `string` / `number` → text input
+ *   - `slot` → text input when string-typed/seeded (`children: 'Badge'`); a
+ *     ReactNode slot is omitted (its content is a keyed spec element, not a
+ *     scalar prop — it can't be set from a value control)
+ *   - `styleProp` / `function` → omitted from the main walk (the Box style
+ *     surface would flood; event handlers aren't value-editable)
+ *   - any scalar `preview.defaultProps` entry not already covered (e.g.
+ *     `children` on a primitive) → text/toggle, or a dropdown when the prop is
+ *     option-backed (e.g. a `color` styleProp default → token dropdown)
+ *
+ * `seed` is the rendered instance's current root props (the authored example /
+ * live override); a seed value wins over `defaultProps` for the shown default.
+ * Variant/slot stay unset when nothing seeds them so the row reads "Default".
+ * Sorted variant-first, then the rest, each group alphabetized.
+ */
+declare function derivePreviewControls(config: Config, component: Component, seed?: Record<string, unknown>): PreviewControl[];
+//#endregion
+export { PreviewControl, PreviewControlKind, derivePreviewControls, propOptions };

package/dist/spec/preview-controls.js

@@ -0,0 +1,139 @@
+//#region src/spec/preview-controls.ts
+/**
+* The selectable values for a prop, or `undefined` when it isn't option-backed.
+* Resolves by the prop's declared kind: a `variant()`'s declared values, a
+* `composite()`'s registered style keys (e.g. `textVariant` → its variant
+* names), or a `styleProp()`'s token + keyword names. A name that isn't a
+* declared prop falls back to a same-named registered style prop (the Box
+* surface — e.g. `color`/`bg` set only via `preview.defaultProps`).
+*/
+function propOptions(config, component, name) {
+	const info = component.derived.props.find((p) => p.name === name);
+	if (!info) return optionsForStyleProp(config, name);
+	switch (info.kind) {
+		case "variant": return info.values.map(String);
+		case "composite": {
+			const composite = config.compositeStyles.get(info.compositeName);
+			return composite ? [...composite.styles.keys()] : void 0;
+		}
+		case "styleProp": return optionsForStyleProp(config, info.stylePropName);
+		default: return;
+	}
+}
+function optionsForStyleProp(config, propName) {
+	const styleProp = config.styleProps.get(propName);
+	if (!styleProp) return void 0;
+	const values = [];
+	for (const token of styleProp.derived.tokens) values.push(token.name);
+	for (const key of styleProp.derived.keywords.keys()) if (typeof key === "string") values.push(key);
+	return values.length > 0 ? values : void 0;
+}
+/**
+* Editable preview controls for a component:
+*
+*   - `variant` → dropdown of declared values
+*   - `composite` → dropdown, options from the registered composite
+*   - `boolean` → toggle; `string` / `number` → text input
+*   - `slot` → text input when string-typed/seeded (`children: 'Badge'`); a
+*     ReactNode slot is omitted (its content is a keyed spec element, not a
+*     scalar prop — it can't be set from a value control)
+*   - `styleProp` / `function` → omitted from the main walk (the Box style
+*     surface would flood; event handlers aren't value-editable)
+*   - any scalar `preview.defaultProps` entry not already covered (e.g.
+*     `children` on a primitive) → text/toggle, or a dropdown when the prop is
+*     option-backed (e.g. a `color` styleProp default → token dropdown)
+*
+* `seed` is the rendered instance's current root props (the authored example /
+* live override); a seed value wins over `defaultProps` for the shown default.
+* Variant/slot stay unset when nothing seeds them so the row reads "Default".
+* Sorted variant-first, then the rest, each group alphabetized.
+*/
+function derivePreviewControls(config, component, seed = {}) {
+	const controls = [];
+	const seen = /* @__PURE__ */ new Set();
+	const declaredDefaults = component.defaultProps ?? {};
+	for (const info of component.derived.props) {
+		const control = describeProp(config, component, info, declaredDefaults[info.name], seed[info.name]);
+		if (!control) continue;
+		controls.push(control);
+		seen.add(info.name);
+	}
+	const previewDefaults = component.preview?.defaultProps ?? {};
+	for (const [name, value] of Object.entries(previewDefaults)) {
+		if (seen.has(name)) continue;
+		const options = propOptions(config, component, name);
+		if (options && options.length > 0) {
+			controls.push({
+				name,
+				kind: "variant",
+				defaultValue: seed[name] ?? value,
+				options
+			});
+			seen.add(name);
+			continue;
+		}
+		const kind = scalarKind(value);
+		if (!kind) continue;
+		controls.push({
+			name,
+			kind,
+			defaultValue: seed[name] ?? value
+		});
+		seen.add(name);
+	}
+	return sortPreviewControls(controls);
+}
+function describeProp(config, component, info, declaredDefault, seed) {
+	switch (info.kind) {
+		case "variant": return {
+			name: info.name,
+			kind: "variant",
+			defaultValue: seed ?? declaredDefault ?? void 0,
+			options: info.values.map(String)
+		};
+		case "boolean": return {
+			name: info.name,
+			kind: "boolean",
+			defaultValue: seed ?? declaredDefault ?? false
+		};
+		case "string":
+		case "number": return {
+			name: info.name,
+			kind: "string",
+			defaultValue: seed ?? declaredDefault ?? ""
+		};
+		case "composite": {
+			const options = propOptions(config, component, info.name);
+			if (!options || options.length === 0) return null;
+			return {
+				name: info.name,
+				kind: "variant",
+				defaultValue: seed ?? declaredDefault ?? void 0,
+				options
+			};
+		}
+		case "slot": {
+			const value = seed ?? declaredDefault;
+			if (info.authoredType === "string" || typeof value === "string") return {
+				name: info.name,
+				kind: "string",
+				defaultValue: typeof value === "string" ? value : ""
+			};
+			return null;
+		}
+		default: return null;
+	}
+}
+function scalarKind(value) {
+	if (typeof value === "boolean") return "boolean";
+	if (typeof value === "string" || typeof value === "number") return "string";
+	return null;
+}
+function sortPreviewControls(controls) {
+	const byName = (a, b) => a.name.localeCompare(b.name);
+	const variants = controls.filter((c) => c.kind === "variant").sort(byName);
+	const rest = controls.filter((c) => c.kind !== "variant").sort(byName);
+	return [...variants, ...rest];
+}
+//#endregion
+export { derivePreviewControls, propOptions };

package/dist/spec/slot-refs.d.ts

@@ -0,0 +1,39 @@
+//#region src/spec/slot-refs.d.ts
+/**
+ * `$slot` resolution utilities for json-render specs.
+ *
+ * UDS extends json-render's prop-value markers with a `$slot` reference
+ * that points to another element in the same Spec's `elements` map:
+ *
+ *     { "$slot": "btn1" }              // single ref
+ *     { "$slot": ["btn1", "btn2"] }    // multi-ref (e.g. Card.actions)
+ *
+ * Used for composition patterns where a slot prop on one component
+ * (Card.actions, Button.startIcon) receives whole sub-trees of other
+ * elements. The shared helpers here are consumed by:
+ *
+ *   - `wrapSlotResolution` (renderer wrapper) — resolves $slot refs to
+ *     rendered React children at paint time.
+ *   - `prepareRenderSpec` (studio) — injects $slot-referenced keys
+ *     into the parent's `children` array so json-render's `Renderer`
+ *     traverses them (otherwise an unreferenced element in the
+ *     `elements` map is never visited).
+ *   - Inspection / debug surfaces (layers panel, dev code panel,
+ *     control inference, RPC routes) that need to skip past $slot
+ *     prop markers when inspecting "real" prop values.
+ */
+declare function isSlotRef(value: unknown): value is {
+  $slot: string | string[];
+};
+/**
+ * Walk a Spec's `elements` map and return, for each parent element
+ * that has at least one `$slot`-prop reference, the set of element
+ * keys it references. Used by render-time and edit-time code that
+ * needs to know "which sibling elements does this parent pull in
+ * through slot props."
+ */
+declare function collectSlotRefs(elements: Record<string, {
+  props?: Record<string, unknown>;
+} | undefined>): Map<string, Set<string>>;
+//#endregion
+export { collectSlotRefs, isSlotRef };

package/dist/spec/slot-refs.js

@@ -0,0 +1,56 @@
+//#region src/spec/slot-refs.ts
+/**
+* `$slot` resolution utilities for json-render specs.
+*
+* UDS extends json-render's prop-value markers with a `$slot` reference
+* that points to another element in the same Spec's `elements` map:
+*
+*     { "$slot": "btn1" }              // single ref
+*     { "$slot": ["btn1", "btn2"] }    // multi-ref (e.g. Card.actions)
+*
+* Used for composition patterns where a slot prop on one component
+* (Card.actions, Button.startIcon) receives whole sub-trees of other
+* elements. The shared helpers here are consumed by:
+*
+*   - `wrapSlotResolution` (renderer wrapper) — resolves $slot refs to
+*     rendered React children at paint time.
+*   - `prepareRenderSpec` (studio) — injects $slot-referenced keys
+*     into the parent's `children` array so json-render's `Renderer`
+*     traverses them (otherwise an unreferenced element in the
+*     `elements` map is never visited).
+*   - Inspection / debug surfaces (layers panel, dev code panel,
+*     control inference, RPC routes) that need to skip past $slot
+*     prop markers when inspecting "real" prop values.
+*/
+function isSlotRef(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("$slot" in value)) return false;
+	const inner = value.$slot;
+	return typeof inner === "string" || Array.isArray(inner);
+}
+/**
+* Walk a Spec's `elements` map and return, for each parent element
+* that has at least one `$slot`-prop reference, the set of element
+* keys it references. Used by render-time and edit-time code that
+* needs to know "which sibling elements does this parent pull in
+* through slot props."
+*/
+function collectSlotRefs(elements) {
+	const parentToSlotKeys = /* @__PURE__ */ new Map();
+	for (const [key, el] of Object.entries(elements)) {
+		if (!el?.props) continue;
+		for (const value of Object.values(el.props)) {
+			if (!isSlotRef(value)) continue;
+			const refs = Array.isArray(value.$slot) ? value.$slot : [value.$slot];
+			let slotKeys = parentToSlotKeys.get(key);
+			if (!slotKeys) {
+				slotKeys = /* @__PURE__ */ new Set();
+				parentToSlotKeys.set(key, slotKeys);
+			}
+			for (const ref of refs) slotKeys.add(ref);
+		}
+	}
+	return parentToSlotKeys;
+}
+//#endregion
+export { collectSlotRefs, isSlotRef };

package/dist/spec/specToJsx.d.ts

@@ -0,0 +1,35 @@
+import { AssetComponentMap } from "./asset-jsx.js";
+import { Spec } from "@json-render/core";
+
+//#region src/spec/specToJsx.d.ts
+interface SpecToJsxOptions {
+  /** Component import source (default: './uds/components') */
+  importSource?: string;
+  /**
+   * When true, skip the leading `import { ... } from '...';` line and
+   * return only the JSX expression in `jsx`. Callers that need to
+   * assemble bespoke import lines (e.g. per-component kebab-cased
+   * paths for downloadable file exports) can read the type names
+   * from the returned `imports` array.
+   */
+  omitImports?: boolean;
+  /**
+   * `asset group slug → component tag used for JSX export`
+   * (e.g. `{ icons: 'Icon' }`).
+   *
+   * This is derived from `Config.assetGroups[*].component`. It does not affect
+   * asset registration or rendering; it only controls whether a stored asset node
+   * like `yahoo-os:asset:icons/Trophy` prints as `<Icon name="Trophy" />`
+   * instead of the fallback `<Trophy />`.
+   */
+  assetComponents?: AssetComponentMap;
+}
+interface SpecToJsxResult {
+  /** Generated JSX source code */
+  jsx: string;
+  /** Component names used (for imports) */
+  imports: string[];
+}
+declare function specToJsx(spec: Spec, options?: SpecToJsxOptions): SpecToJsxResult;
+//#endregion
+export { SpecToJsxOptions, SpecToJsxResult, specToJsx };

package/dist/spec/specToJsx.js

@@ -0,0 +1,127 @@
+import { isSlotRef } from "./slot-refs.js";
+import { assetJsxForm } from "./asset-jsx.js";
+import { collectUsedComponents, serializeProps } from "@json-render/codegen";
+//#region src/spec/specToJsx.ts
+function statePathToExpression(path) {
+	return `state${path.split("/").filter(Boolean).map((s) => `.${s}`).join("")}`;
+}
+function isDynamicValue(value) {
+	return typeof value === "object" && value !== null && "$state" in value && typeof value.$state === "string";
+}
+/** Collect all element keys referenced via $slot in a spec element's props */
+function collectSlotKeys(props) {
+	const keys = /* @__PURE__ */ new Set();
+	for (const value of Object.values(props)) if (isSlotRef(value)) {
+		const refs = Array.isArray(value.$slot) ? value.$slot : [value.$slot];
+		for (const ref of refs) keys.add(ref);
+	}
+	return keys;
+}
+function resolveDynamicValue(value) {
+	if (isDynamicValue(value)) return statePathToExpression(value.$state);
+	return String(value);
+}
+function renderActionBinding(binding) {
+	if (Array.isArray(binding)) return `{() => { ${binding.map((b) => b.action).map((a) => `${a}()`).join("; ")} }}`;
+	return `{${binding.action}}`;
+}
+function eventNameToJsx(name) {
+	return `on${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+}
+function renderElement(key, spec, depth, assetComponents) {
+	const element = spec.elements[key];
+	if (!element) return "";
+	const indent = "  ".repeat(depth);
+	const { children: _children, ...restProps } = element.props ?? {};
+	const slotKeys = collectSlotKeys(restProps);
+	const slotAttrs = [];
+	const propsWithoutSlots = {};
+	for (const [propName, propValue] of Object.entries(restProps)) if (isSlotRef(propValue)) {
+		const refs = Array.isArray(propValue.$slot) ? propValue.$slot : [propValue.$slot];
+		if (refs.length === 1) {
+			const rendered = renderElement(refs[0], spec, 0, assetComponents).trim();
+			slotAttrs.push(`${propName}={${rendered}}`);
+		} else {
+			const rendered = refs.map((r) => renderElement(r, spec, 0, assetComponents).trim()).filter(Boolean);
+			slotAttrs.push(`${propName}={<>${rendered.join("")}</>}`);
+		}
+	} else propsWithoutSlots[propName] = propValue;
+	const assetForm = assetJsxForm(element.type, assetComponents);
+	const tag = assetForm?.tag ?? element.type;
+	const nameAttr = assetForm?.nameAttr ? `name="${assetForm.nameAttr}"` : "";
+	if (assetForm?.nameAttr) delete propsWithoutSlots.name;
+	const staticAttrs = Object.keys(propsWithoutSlots).length > 0 ? serializeProps(propsWithoutSlots) : "";
+	const eventAttrs = [];
+	if (element.on && typeof element.on === "object") {
+		const onRecord = element.on;
+		for (const [eventName, binding] of Object.entries(onRecord)) eventAttrs.push(`${eventNameToJsx(eventName)}=${renderActionBinding(binding)}`);
+	}
+	const dynamicAttrs = [];
+	for (const [propName, propValue] of Object.entries(propsWithoutSlots)) if (isDynamicValue(propValue)) dynamicAttrs.push(`${propName}={${resolveDynamicValue(propValue)}}`);
+	let propsStr;
+	if (dynamicAttrs.length > 0 || slotAttrs.length > 0) {
+		const staticOnly = {};
+		for (const [k, v] of Object.entries(propsWithoutSlots)) if (!isDynamicValue(v)) staticOnly[k] = v;
+		const parts = [
+			nameAttr,
+			Object.keys(staticOnly).length > 0 ? serializeProps(staticOnly) : "",
+			...dynamicAttrs,
+			...slotAttrs,
+			...eventAttrs
+		].filter(Boolean);
+		propsStr = parts.length > 0 ? ` ${parts.join(" ")}` : "";
+	} else {
+		const parts = [
+			nameAttr,
+			staticAttrs,
+			...eventAttrs
+		].filter(Boolean);
+		propsStr = parts.length > 0 ? ` ${parts.join(" ")}` : "";
+	}
+	const rawChildren = element.props?.children;
+	const textContent = typeof rawChildren === "string" ? rawChildren : null;
+	const dynamicChildren = isDynamicValue(rawChildren) ? `{${resolveDynamicValue(rawChildren)}}` : null;
+	const inlineContent = textContent ?? dynamicChildren;
+	const childKeys = (element.children ?? []).filter((k) => !slotKeys.has(k));
+	const hasChildren = childKeys.length > 0 || inlineContent !== null;
+	let jsxLine;
+	if (!hasChildren) jsxLine = `${indent}<${tag}${propsStr} />`;
+	else if (inlineContent !== null && childKeys.length === 0) jsxLine = `${indent}<${tag}${propsStr}>${inlineContent}</${tag}>`;
+	else {
+		const childLines = [];
+		if (inlineContent !== null) childLines.push(`${"  ".repeat(depth + 1)}${inlineContent}`);
+		for (const childKey of childKeys) {
+			if (!spec.elements[childKey]) continue;
+			childLines.push(renderElement(childKey, spec, depth + 1, assetComponents));
+		}
+		jsxLine = `${indent}<${tag}${propsStr}>\n${childLines.join("\n")}\n${indent}</${tag}>`;
+	}
+	if (element.repeat && typeof element.repeat === "object") {
+		const repeat = element.repeat;
+		const stateExpr = statePathToExpression(repeat.statePath);
+		const keyProp = repeat.key ? `key={item.${repeat.key}}` : "key={index}";
+		jsxLine = `${indent}{${stateExpr}.map((item, index) => (\n${jsxLine.replace(new RegExp(`^${indent}`), `${indent}  `)}\n${indent}))}`.replace(`<${tag}`, `<${tag} ${keyProp}`);
+	}
+	if (element.visible != null) jsxLine = `${indent}{${isDynamicValue(element.visible) ? resolveDynamicValue(element.visible) : String(element.visible)} && (\n${jsxLine.replace(new RegExp(`^${indent}`), `${indent}  `)}\n${indent})}`;
+	return jsxLine;
+}
+function specToJsx(spec, options) {
+	const importSource = options?.importSource ?? "./uds/components";
+	if (!spec.elements[spec.root]) return {
+		jsx: "",
+		imports: []
+	};
+	const assetComponents = options?.assetComponents;
+	const sortedImports = [...new Set([...collectUsedComponents(spec)].map((type) => assetJsxForm(type, assetComponents)?.importName ?? type))].sort();
+	const jsxTree = renderElement(spec.root, spec, 0, assetComponents);
+	if (options?.omitImports) return {
+		jsx: jsxTree,
+		imports: sortedImports
+	};
+	return {
+		jsx: `${`import { ${sortedImports.join(", ")} } from '${importSource}';`}\n\n${jsxTree}`,
+		imports: sortedImports
+	};
+}
+//#endregion
+export { specToJsx };

package/dist/token-override-rows.d.ts

@@ -0,0 +1,66 @@
+import { TokenModifierKey } from "./types.js";
+
+//#region src/token-override-rows.d.ts
+type OverrideModeRef = `${string}.${string}`;
+type ModifierTreeValue<TValue> = TValue | {
+  value?: TValue;
+  [modifier: TokenModifierKey]: ModifierTreeValue<TValue> | undefined;
+};
+type ModifierTree<TValue> = Partial<Record<TokenModifierKey, ModifierTreeValue<TValue>>>;
+type ModifierUpdateValue<TValue> = TValue | null | ModifierUpdateObject<TValue>;
+interface ModifierUpdateObject<TValue> {
+  value?: TValue | null;
+  [key: string]: ModifierUpdateValue<TValue> | undefined;
+  [modifier: TokenModifierKey]: ModifierUpdateValue<TValue> | undefined;
+}
+type ModifierUpdate<TValue> = Record<string, ModifierUpdateValue<TValue> | undefined>;
+interface ModeBackedModifierInput {
+  modifier: TokenModifierKey;
+  mode: string;
+  option: string;
+  label?: string;
+  modeOrder: number;
+  optionOrder: number;
+}
+interface ModeBackedModifierDefinition extends ModeBackedModifierInput {
+  modeRef: OverrideModeRef;
+}
+interface ModeBackedModifierLookup {
+  byModifier: ReadonlyMap<TokenModifierKey, ModeBackedModifierDefinition>;
+  byModeRef: ReadonlyMap<OverrideModeRef, ModeBackedModifierDefinition>;
+}
+interface OverrideRow<TValue = string> {
+  modes: OverrideModeRef[];
+  value: TValue;
+  sourceModifierPath: TokenModifierKey[];
+  sourceOrder: number;
+}
+interface ModeBackedModeMetadata {
+  name: string;
+  options: readonly {
+    name: string;
+    label?: string;
+  }[];
+}
+interface ModeBackedModifierMetadata {
+  modifier: TokenModifierKey;
+  selector?: unknown;
+}
+declare function createModeBackedModifierLookup(inputs: readonly ModeBackedModifierInput[]): ModeBackedModifierLookup;
+declare function buildModeBackedModifierLookup(modes: readonly ModeBackedModeMetadata[], modifiers: readonly ModeBackedModifierMetadata[]): ModeBackedModifierLookup;
+declare function modifierTreeToOverrideRows<TValue>(modifiers: ModifierTree<TValue> | undefined, lookup: ModeBackedModifierLookup): OverrideRow<TValue>[];
+declare function overrideRowsToModifierTree<TValue>(rows: readonly OverrideRow<TValue>[], lookup: ModeBackedModifierLookup): ModifierTree<TValue>;
+declare function resolveOverrideRowValue<TValue>(baseValue: TValue, rows: readonly Pick<OverrideRow<TValue>, 'modes' | 'value'>[], activeModes: Iterable<OverrideModeRef>): TValue;
+declare function modifierPathToId(path: readonly TokenModifierKey[]): string;
+declare function modifierIdToPath(id: string): TokenModifierKey[];
+declare function buildNestedModifierUpdate<TValue>(modifierPath: readonly TokenModifierKey[], value: ModifierUpdateValue<TValue>): Record<TokenModifierKey, ModifierUpdateValue<TValue>>;
+/**
+ * Combines multiple token-modifier update payloads into one patch
+ * object. Later updates win on scalar/null leaves; object branches
+ * deep-merge so swap operations can delete one nested row and set
+ * another nested row under the same parent modifier in a single
+ * patch.
+ */
+declare function mergeModifierUpdates<TValue>(...updates: readonly ModifierUpdate<TValue>[]): Record<string, ModifierUpdateValue<TValue>>;
+//#endregion
+export { ModeBackedModifierDefinition, ModeBackedModifierInput, ModeBackedModifierLookup, OverrideModeRef, OverrideRow, buildModeBackedModifierLookup, buildNestedModifierUpdate, createModeBackedModifierLookup, mergeModifierUpdates, modifierIdToPath, modifierPathToId, modifierTreeToOverrideRows, overrideRowsToModifierTree, resolveOverrideRowValue };