@yahoo/uds-v5-wip 1.61.0 → 1.62.0

package/dist/config/dist/Component.js

@@ -0,0 +1,897 @@
+import { compact } from "./entity-utils.js";
+import { isPlaceable } from "./asset-kind.js";
+import { readSourcePath } from "./captureCallerPath.js";
+import { isAssetGroupRef, isCompositeRef, isStylePropRef, isTokenRef, tag } from "./refs.js";
+import { isColorExpression } from "./colorExpressions.js";
+import { readAssetGroupSlug } from "./defineAssetGroup.js";
+import { serializeElementsDeep } from "./element-marker.js";
+import { isBoolMarker, isNumberMarker, isSlotMarker, isStringMarker, isVariantArrayMarker, isVariantMarker } from "./markers.js";
+import { componentClassNames } from "../../utils/dist/string-utils/componentClassName.js";
+import "../../utils/dist/index.js";
+//#region ../config/dist/Component.js
+/**
+* `Component` — a registered component with layers, props, and base
+* styles.
+*
+* Layer instances are purely structural (no derived). Cross-layer
+* derivations live on `Component.derived` because they walk
+* `compoundProps` + `base` together. `derived.propInfo(name)` returns a
+* discriminated union narrowed by `.kind` — that surface replaces
+* Studio's bespoke `componentInfo.ts` walker.
+*
+* `subcomponentOf` / `subcomponents` aren't authored on the component
+* itself — they fall out of a parent's
+* `defineComponent(...).subcomponents({...})` chain when `Config.
+* registerComponents` walks it. They live under `.derived` to keep the
+* authored-vs-derived split clean per the config naming convention.
+*/
+/**
+* Humanize a PascalCase/camelCase component name into a space-separated
+* display label — `"GridItem"` → `"Grid Item"`, `"HStack"` → `"H Stack"`,
+* `"TableHeadCell"` → `"Table Head Cell"`. Used as the default
+* `metadata.label` when an author didn't supply one, so every consumer
+* reads a label off `metadata` uniformly instead of re-deriving a
+* fallback from `name` at each call site.
+*/
+function humanizeComponentName(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").trim();
+}
+/**
+* Normalize each layer-input authoring form down to the canonical
+* marker shape stored on `Layer.tag`:
+*
+*  - bare string → `TagRef`
+*  - `LayerWithOverrides` (`{ tag, defaultProps?, base?, ... }`) →
+*    the unwrapped `tag` field (recursing once for the bare-string
+*    case nested inside).
+*  - Existing `TagRef` / `ComponentRef` / `ComponentDefinition` value
+*    is passed through unchanged.
+*
+* Centralized here so every Layer constructed downstream sees the
+* marker shape, regardless of how the consumer authored the layer.
+*/
+function normalizeLayerInput(input) {
+	if (input === void 0) return void 0;
+	if (typeof input === "string") return tag(input);
+	if (typeof input === "object" && input !== null && "tag" in input && typeof input.tag !== "undefined" && !("__kind" in input)) {
+		const inner = input.tag;
+		return typeof inner === "string" ? tag(inner) : inner;
+	}
+	return input;
+}
+/**
+* Preserve component identity across the JSON wire when a layer was
+* authored with a registered `ComponentDefinition` value (e.g.
+* `.layers({ root: Box, text: Text })`). Without this, `JSON.stringify`
+* inlines the whole definition and drops the non-enumerable
+* `__componentName` stamp — consumers reading `Layer.tag` from a
+* `Config.fromJSON` round-trip then have no way to tell which
+* registered component the layer references. We emit a `ComponentRef`
+* marker instead so the identity round-trips.
+*/
+function serializeLayerTag(input) {
+	if (typeof input === "object" && input !== null && !("__kind" in input) && "__componentName" in input) {
+		const name = input.__componentName;
+		if (typeof name === "string") return {
+			__kind: "component",
+			ref: name
+		};
+	}
+	return input;
+}
+var Layer = class {
+	name;
+	tag;
+	base;
+	constructor(args) {
+		this.name = args.name;
+		this.tag = normalizeLayerInput(args.tag);
+		this.base = args.base;
+	}
+	/**
+	* What this layer renders, normalized across the tag's representations:
+	*  - `{ kind: 'component', ref }` — renders a registered component (`Box`,
+	*    `Text`), so the layer takes that component's prop surface. The identity
+	*    survives both in memory (a non-enumerable `__componentName` stamp on the
+	*    builder) and on the wire (`{ __kind: 'component', ref }` from `fromJSON`).
+	*  - `{ kind: 'tag', ref }` — renders a bare HTML element (`'div'`).
+	*  - `undefined` — an inline anonymous builder with no registered identity.
+	*/
+	get renders() {
+		const t = this.tag;
+		if (t === void 0) return void 0;
+		if (typeof t === "string") return {
+			kind: "tag",
+			ref: t
+		};
+		const obj = t;
+		if (obj.__kind === "component" && typeof obj.ref === "string") return {
+			kind: "component",
+			ref: obj.ref
+		};
+		if (obj.__kind === "tag" && typeof obj.ref === "string") return {
+			kind: "tag",
+			ref: obj.ref
+		};
+		if (typeof obj.__componentName === "string") return {
+			kind: "component",
+			ref: obj.__componentName
+		};
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			...compact({
+				tag: this.tag,
+				base: this.base
+			})
+		};
+	}
+};
+var Component = class {
+	name;
+	layers;
+	props;
+	base;
+	defaultProps;
+	compoundProps;
+	motion;
+	preview;
+	metadata;
+	/**
+	* Absolute path of the file that called `defineComponent('Name', …)`.
+	* Captured via the stack walk in `captureCallerPath` and stashed
+	* non-enumerably on the authored definition; lifted onto the class
+	* here so codegen consumers don't have to thread a separate
+	* `componentSourceMap`. `undefined` when the component was hydrated
+	* from JSON (no original define call) or built outside the `define*`
+	* helpers.
+	*/
+	sourceFilePath;
+	/**
+	* `true` when the authored definition chained `.render(fn)` — the
+	* non-enumerable `__hasRenderFn` flag set by the builder. Codegen
+	* needs this to classify single-layer components that ship a custom
+	* render fn (e.g. Accordion) into the transform path rather than
+	* the inline primitive emitter, so the two paths don't both emit a
+	* wrapper FC with the same name.
+	*/
+	hasRenderFn;
+	/**
+	* The actual `.render(fn)` callback when `hasRenderFn` is `true`.
+	* Lifted from the seed's non-enumerable `__renderFn` so the spec
+	* extractor can invoke it under the mock-react plugin to capture
+	* the component's internal structure as a Spec. Not used at
+	* production render time — the codegen-emitted per-file FC handles
+	* that path.
+	*/
+	renderFn;
+	/**
+	* Name of the component this one value-extends from
+	* (`defineComponent(Box)` → `'Box'`). Resolved from the non-
+	* enumerable `__extendsFrom.__componentName` chain stamped by
+	* `defineComponent`'s value-extend branch and `Config.registerComponents`'
+	* registration loop. `undefined` for primitives, brace-ref shorthand
+	* forms, and JSON-hydrated configs (the wire format doesn't carry
+	* this relationship).
+	*/
+	extendsFrom;
+	#componentGroup;
+	#subcomponentOf;
+	#subcomponents;
+	#namespaceGetter;
+	#prefixGetter;
+	#componentResolver;
+	#resolveStylePropValueToken;
+	#isStyleProp;
+	/**
+	* Globally-unique lookup key — the spec `type` string a renderer
+	* resolves against the registry. When the owning `Config` has a
+	* namespace set (`Config.configure({ namespace: 'uds' })`), this is
+	* `<namespace>:<name>` (`uds:Badge`); otherwise it's the bare `name`
+	* (un-namespaced configs). Read live via a getter so it reflects the
+	* namespace regardless of whether `configure` ran before or after the
+	* component was registered — mirrors the lazy `prefixGetter` pattern
+	* used for token CSS vars.
+	*
+	* `name` stays the bare authored/display/export identifier; codegen
+	* emits a bare-name alias alongside the canonical key so existing
+	* specs referencing the bare `name` keep resolving.
+	*/
+	get registryKey() {
+		const namespace = this.#namespaceGetter?.();
+		return namespace ? `${namespace}:${this.name}` : this.name;
+	}
+	#derived;
+	constructor(args) {
+		this.name = args.name;
+		this.#namespaceGetter = args.namespaceGetter;
+		this.#prefixGetter = args.prefixGetter;
+		this.#componentResolver = args.componentResolver;
+		this.#resolveStylePropValueToken = args.resolveStylePropValueToken;
+		this.#isStyleProp = args.isStyleProp;
+		const layers = /* @__PURE__ */ new Map();
+		const liftedLayerBase = {};
+		for (const [layerName, tag] of Object.entries(args.definition.layers)) {
+			layers.set(layerName, new Layer({
+				name: layerName,
+				tag
+			}));
+			if (typeof tag === "object" && tag !== null && !("__kind" in tag) && "tag" in tag) {
+				const overrides = tag;
+				const merged = {
+					...overrides.defaultProps,
+					...overrides.base
+				};
+				if (Object.keys(merged).length > 0) liftedLayerBase[layerName] = merged;
+			}
+		}
+		this.layers = layers;
+		this.props = args.definition.props ?? {};
+		const authoredBase = args.definition.base;
+		if (Object.keys(liftedLayerBase).length > 0) {
+			const merged = { ...liftedLayerBase };
+			if (authoredBase) for (const [layerName, layerStyles] of Object.entries(authoredBase)) merged[layerName] = {
+				...merged[layerName] ?? {},
+				...layerStyles
+			};
+			this.base = merged;
+		} else this.base = authoredBase;
+		this.defaultProps = args.definition.defaultProps;
+		this.compoundProps = args.definition.compoundProps;
+		this.motion = args.definition.motion;
+		const def = args.definition;
+		const previewField = typeof def.preview === "function" ? void 0 : def.preview;
+		this.preview = def.__preview ?? previewField;
+		const metaField = def.metadata;
+		this.metadata = {
+			...metaField,
+			label: metaField?.label ?? humanizeComponentName(this.name)
+		};
+		this.sourceFilePath = readSourcePath(args.definition);
+		this.hasRenderFn = args.definition.__hasRenderFn === true;
+		this.renderFn = args.definition.__renderFn;
+		const extendsFromSeed = args.definition.__extendsFrom;
+		const extendsFromName = extendsFromSeed && typeof extendsFromSeed === "object" && typeof extendsFromSeed.__componentName === "string" ? extendsFromSeed.__componentName : void 0;
+		this.extendsFrom = extendsFromName ?? args.definition.extendsFrom;
+		this.#componentGroup = args.componentGroup;
+		this.#subcomponentOf = args.subcomponentOf;
+		this.#subcomponents = args.subcomponents;
+	}
+	get derived() {
+		if (!this.#derived) {
+			const propsArray = [];
+			const propsIndex = /* @__PURE__ */ new Map();
+			for (const [propName, binding] of Object.entries(this.props)) {
+				const info = inferPropInfo(propName, binding, this.layers, this.#componentResolver);
+				if (info === void 0) continue;
+				propsArray.push(info);
+				propsIndex.set(propName, info);
+			}
+			const styleUsage = collectStyleUsage(this.base, this.props, this.compoundProps, this.#resolveStylePropValueToken, this.#isStyleProp);
+			this.#derived = {
+				layers: Array.from(this.layers.values()),
+				classNames: componentClassNames(this.#prefixGetter?.() ?? "", this.name),
+				compoundOverrides: buildCompoundOverrides(this.compoundProps),
+				...compact({
+					componentGroup: this.#componentGroup,
+					subcomponentOf: this.#subcomponentOf,
+					subcomponents: this.#subcomponents
+				}),
+				props: propsArray,
+				stylePropNames: propsArray.filter((p) => p.kind === "styleProp").map((p) => p.name),
+				tokenRefs: styleUsage.tokenRefs,
+				stylePropTokenUsages: styleUsage.stylePropTokenUsages,
+				stylePropKeywords: styleUsage.stylePropKeywords,
+				kind: this.#deriveKind(),
+				acceptsChildren: derivesAcceptsChildren(this.layers, propsArray),
+				acceptsChildNodes: derivesAcceptsChildNodes(this.layers, propsArray),
+				prop(propName) {
+					return propsIndex.get(propName);
+				}
+			};
+		}
+		return this.#derived;
+	}
+	/** Classify authoring shape: `extends` wins (value-extension is the defining
+	*  trait), then anything with multiple layers or a custom render is
+	*  `multi-layer`, else a bare single-tag `primitive`. */
+	#deriveKind() {
+		if (this.extendsFrom) return "extends";
+		if (this.layers.size > 1 || this.hasRenderFn) return "multi-layer";
+		return "primitive";
+	}
+	toJSON(opts) {
+		const layers = {};
+		for (const [layerName, layer] of this.layers) {
+			if (layer.tag === void 0) continue;
+			layers[layerName] = serializeLayerTag(layer.tag);
+		}
+		let sourceFilePath = this.sourceFilePath;
+		if (sourceFilePath && opts?.projectRoot) sourceFilePath = sourceFilePath.replace(`${opts.projectRoot}/`, "");
+		return {
+			name: this.name,
+			layers,
+			...compact({
+				props: Object.keys(this.props).length > 0 ? serializeAcceptsInProps(this.props) : void 0,
+				base: this.base,
+				defaultProps: this.defaultProps,
+				compoundProps: this.compoundProps,
+				motion: this.motion,
+				preview: this.preview ? serializeElementsDeep(this.preview) : void 0,
+				metadata: this.metadata,
+				sourceFilePath,
+				subcomponentOf: this.#subcomponentOf,
+				subcomponents: this.#subcomponents,
+				extendsFrom: this.extendsFrom
+			})
+		};
+	}
+};
+/**
+* The token + keyword usage a component carries across its styling — one walk
+* of `base`, each prop binding's variant styles, and `compoundProps` overrides,
+* recursing modifier sub-objects (`_hover`) and color expressions. Produces
+* three views the reverse lookups read for "what breaks if I remove this?":
+*  - `tokenRefs` — every qualified token name referenced, from structured
+*    `token('color/brand')` refs (matched at any depth) and shorthand
+*    style-prop values (`bg: 'tertiary'`, resolved via `resolveStylePropValueToken`,
+*    which returns `undefined` for keywords / arbitrary literals).
+*  - `stylePropTokenUsages` — the `(styleProp, token)` pair for each, so a
+*    consumer can tell *which* prop used a token. A token's style prop is the
+*    key it sits under: directly (`bg: token(...)` / `bg: 'tertiary'`) or as a
+*    color-expression value (`bg: darken(token(...))`), whose nested refs are
+*    all attributed to that key.
+*  - `stylePropKeywords` — `(styleProp, value)` pairs for the *non-token*
+*    keyword values a style prop carries (`display=flex`). Disjoint from
+*    `tokenRefs`; `isStyleProp` gates it so layer keys / marker internals
+*    don't read as keywords, and bracketed arbitrary literals are excluded.
+* Internal `__`-prefixed keys (`__kind`, a slot's `__accepts` child defs) are
+* skipped, so a child's usage never bleeds into the parent's sets.
+*/
+function collectStyleUsage(base, props, compoundProps, resolveStylePropValueToken, isStyleProp) {
+	const refs = /* @__PURE__ */ new Set();
+	const pairKeys = /* @__PURE__ */ new Set();
+	const pairs = [];
+	const keywords = /* @__PURE__ */ new Map();
+	const seen = /* @__PURE__ */ new WeakSet();
+	const addPair = (styleProp, token) => {
+		const key = `${styleProp}${token}`;
+		if (pairKeys.has(key)) return;
+		pairKeys.add(key);
+		pairs.push({
+			styleProp,
+			token
+		});
+	};
+	const collectUnder = (node, styleProp) => {
+		if (node === null || typeof node !== "object") return;
+		if (isTokenRef(node)) {
+			refs.add(node.ref);
+			addPair(styleProp, node.ref);
+			return;
+		}
+		for (const value of Object.values(node)) collectUnder(value, styleProp);
+	};
+	const walk = (node) => {
+		if (node === null || typeof node !== "object") return;
+		if (isTokenRef(node)) {
+			refs.add(node.ref);
+			return;
+		}
+		if (seen.has(node)) return;
+		seen.add(node);
+		if (Array.isArray(node)) {
+			for (const item of node) walk(item);
+			return;
+		}
+		for (const [key, value] of Object.entries(node)) {
+			if (key.startsWith("__")) continue;
+			if (typeof value === "string") {
+				const ref = resolveStylePropValueToken?.(key, value);
+				if (ref) {
+					refs.add(ref);
+					addPair(key, ref);
+				} else if (isStyleProp?.(key) && !value.startsWith("[")) {
+					const values = keywords.get(key) ?? /* @__PURE__ */ new Set();
+					values.add(value);
+					keywords.set(key, values);
+				}
+			} else if (isTokenRef(value)) {
+				refs.add(value.ref);
+				addPair(key, value.ref);
+			} else if (isColorExpression(value)) collectUnder(value, key);
+			else walk(value);
+		}
+	};
+	if (base) walk(base);
+	for (const binding of Object.values(props)) walk(binding);
+	for (const entry of compoundProps ?? []) walk(entry.layers);
+	const stylePropKeywords = [...keywords].flatMap(([styleProp, values]) => [...values].map((value) => ({
+		styleProp,
+		value
+	})));
+	return {
+		tokenRefs: [...refs],
+		stylePropTokenUsages: pairs,
+		stylePropKeywords
+	};
+}
+function inferPropInfo(name, binding, layers, resolve) {
+	if (binding === void 0 || binding === null) return void 0;
+	if (typeof binding === "function") return {
+		kind: "function",
+		name,
+		required: false,
+		isEventHandler: name.startsWith("on") && name.length > 2
+	};
+	if (typeof binding !== "object") return void 0;
+	if (isSlotMarker(binding)) return resolveSlotPropInfo(name, binding, layers, resolve);
+	if (isVariantMarker(binding)) {
+		const values = isVariantArrayMarker(binding) ? binding.values : Object.keys(binding.values);
+		return {
+			kind: "variant",
+			name,
+			required: binding.__required === true,
+			values
+		};
+	}
+	if (isBoolMarker(binding)) return {
+		kind: "boolean",
+		name,
+		required: binding.__required === true
+	};
+	if (isStringMarker(binding)) return {
+		kind: "string",
+		name,
+		required: binding.__required === true
+	};
+	if (isNumberMarker(binding)) return {
+		kind: "number",
+		name,
+		required: binding.__required === true
+	};
+	if (isStylePropRef(binding)) return {
+		kind: "styleProp",
+		name,
+		required: false,
+		stylePropName: binding.ref
+	};
+	const obj = binding;
+	if (obj.__kind === "composite" && typeof obj.ref === "string") return {
+		kind: "composite",
+		name,
+		required: false,
+		compositeName: obj.ref,
+		...typeof obj.layer === "string" ? { layer: obj.layer } : {}
+	};
+}
+/**
+* Build a `kind: 'slot'` `PropInfo` from a `SlotMarker | SlotRef`.
+* Walks the slot's forward chain (when it targets a composed-component
+* layer's slot prop) to resolve:
+*
+*   - `accepts` — outer marker's `__accepts` wins; otherwise inherits
+*     from the innermost descendant slot that declared `.accepts(...)`.
+*   - `valueType` — what the JSX value resolves to at the terminal
+*     binding (the non-slot binding the chain bottoms out at, or
+*     `'ReactNode'` for open/children slots).
+*
+* Cycle protection: `seen` keys on `"layer/layerProp"`.
+*/
+function resolveSlotPropInfo(name, binding, layers, resolve) {
+	const layer = "layer" in binding ? binding.layer : void 0;
+	const layerProp = "layerProp" in binding && binding.layerProp || "children";
+	const required = binding.__required === true;
+	const isEventHandler = layerProp.startsWith("on") && layerProp.length > 2;
+	const chain = walkSlotForwardChain(binding, layers, resolve);
+	const baseValueType = isEventHandler ? "function" : chain.valueType;
+	const authoredType = binding.__valueType ?? (baseValueType === "string" ? "string" : void 0);
+	return {
+		kind: "slot",
+		name,
+		required,
+		layerProp,
+		valueType: baseValueType,
+		...layer !== void 0 ? { layer } : {},
+		...chain.accepts !== void 0 ? { accepts: chain.accepts } : {},
+		...chain.acceptsAssetGroup !== void 0 ? { acceptsAssetGroup: chain.acceptsAssetGroup } : {},
+		...authoredType !== void 0 ? { authoredType } : {},
+		...baseValueType === "variant" && chain.options !== void 0 ? { valueOptions: chain.options } : {},
+		...baseValueType === "composite" && chain.compositeName !== void 0 ? { compositeName: chain.compositeName } : {}
+	};
+}
+/**
+* Walk a slot's forward chain across composed-component layers.
+*
+* The chain ends when we hit a non-slot binding (boolean/variant/string/
+* styleProp/function/etc.), an HTML-element layer (no `__config`), or an
+* open slot with no further layer to follow. A `children`-targeted ref is
+* followed into its layer (a Text leaf resolves to `'string'`, a node
+* container to `'ReactNode'`) rather than short-circuited — only the
+* component's own open `slot()` is treated as a node container outright.
+* `accepts` is collected as the first `__accepts` seen anywhere in the
+* chain (outermost wins, then any inner ancestor that declared one).
+*/
+function walkSlotForwardChain(start, startLayers, resolve) {
+	const startAccepts = resolveAccepts(start.__accepts);
+	let accepts = startAccepts.names;
+	let acceptsAssetGroup = startAccepts.assetGroup;
+	let current = start;
+	let currentLayers = startLayers;
+	let followed = false;
+	const seen = /* @__PURE__ */ new Set();
+	while (true) {
+		const layer = "layer" in current ? current.layer : void 0;
+		const layerProp = "layerProp" in current && current.layerProp || "children";
+		if (!layer) return {
+			valueType: (followed && current.__valueType === "string" ? "string" : void 0) ?? "ReactNode",
+			accepts,
+			acceptsAssetGroup
+		};
+		const key = `${layer}/${layerProp}`;
+		if (seen.has(key)) return {
+			valueType: "ReactNode",
+			accepts,
+			acceptsAssetGroup
+		};
+		seen.add(key);
+		const innerLayers = currentLayers;
+		if (!innerLayers) return {
+			valueType: "ReactNode",
+			accepts,
+			acceptsAssetGroup
+		};
+		const layerTag = innerLayers.get(layer)?.tag;
+		const surface = resolveLayerSurface(layerTag, resolve);
+		if (!surface) return {
+			valueType: layerProp === "children" ? "ReactNode" : "string",
+			accepts,
+			acceptsAssetGroup
+		};
+		const innerBinding = surface.props?.[layerProp];
+		if (innerBinding === void 0) return {
+			valueType: layerProp === "children" ? "ReactNode" : "string",
+			accepts,
+			acceptsAssetGroup
+		};
+		if (isSlotMarker(innerBinding)) {
+			if (accepts === void 0 || acceptsAssetGroup === void 0) {
+				const inner = resolveAccepts(innerBinding.__accepts);
+				if (accepts === void 0) accepts = inner.names;
+				if (acceptsAssetGroup === void 0) acceptsAssetGroup = inner.assetGroup;
+			}
+			current = innerBinding;
+			currentLayers = surface.layers;
+			followed = true;
+			continue;
+		}
+		return {
+			...terminalResult(innerBinding),
+			accepts,
+			acceptsAssetGroup
+		};
+	}
+}
+/**
+* A layer's prop surface + sub-layers, resolved from either an inline
+* composed definition or a registered-component ref. `undefined` for HTML-
+* element layers (`'div'`) and unresolvable refs — the chain stops there.
+*/
+function resolveLayerSurface(layerTag, resolve) {
+	const inlineDef = getComposedLayerDefinition(layerTag);
+	if (inlineDef) return {
+		props: inlineDef.props,
+		layers: toLayerMap(inlineDef.layers)
+	};
+	const ref = componentRefName(layerTag);
+	const comp = ref ? resolve?.(ref) : void 0;
+	if (comp) return {
+		props: comp.props,
+		layers: comp.layers
+	};
+}
+/** Read a registered-component-ref layer tag's target name, from the wire
+*  form (`{ __kind: 'component', ref }`) or the in-memory `__componentName`
+*  stamp. Element/inline layers have neither and return `undefined`. */
+function componentRefName(tag) {
+	if (tag === null || typeof tag !== "object") return void 0;
+	const obj = tag;
+	if (obj.__kind === "component" && typeof obj.ref === "string") return obj.ref;
+	if (typeof obj.__componentName === "string") return obj.__componentName;
+}
+/** Resolve a terminal (non-slot) binding's value kind plus, for a variant, its
+*  selectable values, or for a composite ref its registry name, so tools can
+*  render the matching control (a dropdown / composite picker). */
+function terminalResult(binding) {
+	if (typeof binding === "function") return { valueType: "function" };
+	if (binding === null || typeof binding !== "object") return { valueType: "string" };
+	if (isVariantMarker(binding)) return {
+		valueType: "variant",
+		options: isVariantArrayMarker(binding) ? binding.values : Object.keys(binding.values)
+	};
+	if (isCompositeRef(binding)) return {
+		valueType: "composite",
+		compositeName: binding.ref
+	};
+	if (isBoolMarker(binding)) return { valueType: "boolean" };
+	if (isNumberMarker(binding)) return { valueType: "number" };
+	if (isStringMarker(binding)) return { valueType: "string" };
+	if (isStylePropRef(binding)) return { valueType: "string" };
+	return { valueType: "string" };
+}
+/**
+* Resolve a slot's `__accepts` into the two distinct things a slot can
+* accept: registered component *names* and a placeable asset-group *slug*.
+*
+* Component entries are `ComponentDefinition`s in memory (carrying an
+* authored `name` or the `__componentName` stamp) and bare name strings on
+* the wire; either way `readDefinitionName` reads the name. Asset-group
+* entries are the double-duty group definition in memory and a
+* `{ __kind: 'assetGroup', ref }` marker on the wire; `isAssetGroupRef`
+* catches both and `readAcceptedAssetGroupSlug` reads the slug. The asset
+* branch throws for a non-placeable class (a font group), keyed to the
+* `isPlaceable` capability rather than to any one class — without it a font
+* group would silently contribute nothing and the designer panel would fall
+* back to the all-components picker.
+*
+* `names` is `undefined` (not `[]`) when no component was accepted, so callers
+* can distinguish "unconstrained" from "empty list"; `assetGroup` is the first
+* accepted group's slug (slots target a single group in practice).
+*/
+function resolveAccepts(accepts) {
+	if (!accepts) return {};
+	const names = [];
+	let assetGroup;
+	for (const entry of accepts) {
+		if (isAssetGroupRef(entry)) {
+			assertAcceptedAssetGroupPlaceable(entry);
+			const slug = readAcceptedAssetGroupSlug(entry);
+			if (slug === void 0) throw new Error(UNREGISTERED_ACCEPTED_GROUP_ERROR);
+			if (assetGroup === void 0) assetGroup = slug;
+			continue;
+		}
+		const name = readDefinitionName(entry);
+		if (name) names.push(name);
+	}
+	return {
+		names: names.length > 0 ? names : void 0,
+		assetGroup
+	};
+}
+/**
+* Read an accepted asset group's slug from either form an `__accepts` entry
+* takes: the live double-duty definition (slug on the internal `__slug` slot)
+* or the serialized `{ __kind: 'assetGroup', ref }` wire marker.
+*
+* Crucially this never reads the live definition's `ref` *getter* — that getter
+* throws "read before registration" until `registerAssetGroups` stamps `__slug`,
+* which would turn a recoverable "group not registered" condition into a cryptic
+* crash on the first `derived`/`toJSON` access. The `.ref` fallback is reached
+* only for wire markers (no `assetKind` field); an unregistered *live* group
+* resolves to `undefined` here, and the caller raises a clear error.
+*/
+function readAcceptedAssetGroupSlug(entry) {
+	const live = readAssetGroupSlug(entry);
+	if (live) return live;
+	if (entry !== null && typeof entry === "object" && !("assetKind" in entry)) {
+		const ref = entry.ref;
+		if (typeof ref === "string" && ref.length > 0) return ref;
+	}
+}
+/** Shared message for an accepted asset group whose slug can't be resolved —
+*  it was pointed at by `.accepts(...)` but never registered. */
+const UNREGISTERED_ACCEPTED_GROUP_ERROR = "slot .accepts(<asset group>) references a group that has not been registered — call Config.registerAssetGroups(...) for it before the slot is resolved or serialized.";
+/**
+* Throw for `.accepts(<non-placeable group>)`. Reads the stamped
+* `assetKind` off the accepted group (the double-duty definition
+* object); a bare `{ __kind, ref }` marker carries no class to
+* validate, so it passes through.
+*/
+function assertAcceptedAssetGroupPlaceable(entry, context) {
+	const group = entry;
+	const assetKind = group.assetKind;
+	if (assetKind === void 0) return;
+	if (isPlaceable({ assetKind })) return;
+	const slug = readAssetGroupSlug(entry) ?? group.label ?? "unknown";
+	const where = context ? `component "${context.componentName}" prop "${context.propName}": ` : "";
+	throw new Error(`${where}slot accepts asset group "${slug}" (class "${assetKind}"), which is not placeable — only placeable asset classes (e.g. icons) can fill a slot.`);
+}
+/**
+* Catches a slot that declares `.accepts(<non-placeable group>)` — e.g.
+* a slot wired to accept a font group, which can never fill a slot.
+*
+* This is the *eager* guard: `Config.registerComponents` and
+* `registerComponentGroups` run it once per definition at registration
+* time, so the error surfaces right when the component is registered
+* rather than later, on the first lazy `derived` read buried deep in a
+* render path (where it'd be much harder to trace back to the cause).
+*
+* There's also a *lazy* check inside `resolveAccepts`. We keep both
+* on purpose: this eager walk only sees the top-level definition, so the
+* lazy check is the backstop for bindings it can't reach. (Inner slots
+* of a composed layer aren't a gap — they get validated through their
+* own component's registration.)
+*
+* The same pass enforces the `slot({ type: 'component' })` contract: a
+* component-typed slot resolves to the icon component itself, which is only
+* meaningful when it accepts an asset group, so one declared without an
+* asset-group `.accepts(...)` is a config-load error.
+*
+* Hydration note: the serialized `{ __kind: 'assetGroup', ref }` marker
+* (`serializeAcceptsList`) is enumerable plain JSON, so `isAssetGroupRef`
+* recognizes it browser-side and the placeable group's slug reaches
+* `SlotInfo.acceptsAssetGroup` after a round-trip. The placeability throw,
+* however, does NOT re-fire on the wire form — the marker carries no
+* `assetKind`, so `assertAcceptedAssetGroupPlaceable` returns early. That's
+* fine in practice: `serializeAcceptsList` runs the same throw on the way
+* *out*, so a non-placeable group can never be written to a wire blob this
+* code produces. The browser-side guarantee is the safe-degradation one —
+* an unresolvable or non-icon group yields no `acceptsAssetGroup` and an
+* empty picker, never the all-components fallback — not a re-validation.
+*/
+function assertDefinitionAcceptsPlaceable(componentName, definition) {
+	for (const [propName, binding] of Object.entries(definition.props ?? {})) {
+		if (!isSlotMarker(binding)) continue;
+		const groupRefs = (binding.__accepts ?? []).filter(isAssetGroupRef);
+		for (const entry of groupRefs) assertAcceptedAssetGroupPlaceable(entry, {
+			componentName,
+			propName
+		});
+		if (groupRefs.length > 1) throw new Error(`component "${componentName}" prop "${propName}": a slot can accept at most one asset group (got ${groupRefs.length}).`);
+		const isForwardingRef = "layer" in binding && binding.layer !== void 0;
+		if (binding.__valueType === "component" && groupRefs.length === 0 && !isForwardingRef) throw new Error(`component "${componentName}" prop "${propName}": slot({ type: 'component' }) requires an asset-group .accepts() — it resolves to the asset's component (e.g. the aliased Icon pattern), so it must target a placeable asset group.`);
+	}
+}
+function readDefinitionName(entry) {
+	if (typeof entry === "string") return entry.length > 0 ? entry : void 0;
+	if (entry === null) return void 0;
+	if (typeof entry !== "object" && typeof entry !== "function") return void 0;
+	const direct = entry.name;
+	if (typeof direct === "string" && direct.length > 0) return direct;
+	const stamped = entry.__componentName;
+	if (typeof stamped === "string" && stamped.length > 0) return stamped;
+	const inner = entry.__config;
+	if (inner && typeof inner === "object") return readDefinitionName(inner);
+}
+/**
+* Rewrite each slot binding's `__accepts` to bare component-name strings
+* for the wire. In memory `__accepts` holds whole `ComponentDefinition`
+* references; serializing them verbatim both bloats the JSON (the entire
+* accepted component is deep-cloned into every consumer) and loses the
+* non-enumerable `__componentName` stamp `JSON.stringify` drops — so after
+* a `fromJSON` round-trip the names can't be recovered and the slot reads
+* as unconstrained. Resolving to names here (while the stamp is present)
+* keeps `accepts` intact across the DB round-trip. Non-slot bindings pass
+* through untouched; the marker's methods are non-enumerable and so are
+* already dropped by the spread.
+*
+* Asset-group entries can't be name strings — the group's live FCs are
+* non-enumerable (so they never leak across the wire) and its `__kind`/`ref`
+* tag is likewise non-enumerable, so a verbatim `JSON.stringify` would drop
+* the ref entirely and the slot would rehydrate as unconstrained. They are
+* rewritten to an explicit `{ __kind: 'assetGroup', ref: slug }` marker —
+* plain JSON that `isAssetGroupRef` recognizes on the way back in.
+*/
+function serializeAcceptsInProps(props) {
+	const out = {};
+	for (const [name, binding] of Object.entries(props)) {
+		if (!isSlotMarker(binding)) {
+			out[name] = binding;
+			continue;
+		}
+		const { __accepts: _drop, ...rest } = binding;
+		const list = serializeAcceptsList(binding.__accepts);
+		out[name] = list ? {
+			...rest,
+			__accepts: list
+		} : rest;
+	}
+	return out;
+}
+/**
+* Serialize a slot's `__accepts` to its wire form: component entries become
+* bare name strings, asset-group entries become `{ __kind: 'assetGroup', ref }`
+* markers. The non-placeability throw fires here too, so a bad group can't slip
+* onto the wire even if a caller serializes before the eager registration
+* guard runs. Returns `undefined` for an empty/absent list so the serializer
+* omits `__accepts` rather than writing `[]`.
+*/
+function serializeAcceptsList(accepts) {
+	if (!accepts) return void 0;
+	const out = [];
+	for (const entry of accepts) {
+		if (isAssetGroupRef(entry)) {
+			assertAcceptedAssetGroupPlaceable(entry);
+			const slug = readAcceptedAssetGroupSlug(entry);
+			if (slug === void 0) throw new Error(UNREGISTERED_ACCEPTED_GROUP_ERROR);
+			out.push({
+				__kind: "assetGroup",
+				ref: slug
+			});
+			continue;
+		}
+		const componentName = readDefinitionName(entry);
+		if (componentName) out.push(componentName);
+	}
+	return out.length > 0 ? out : void 0;
+}
+/**
+* Pull the inner `ComponentDefinition` off a layer tag value when the
+* layer was authored as a composed-component reference. HTML-element
+* layers (`tag('div')` / bare `'div'`) and `ComponentRef` markers
+* return `undefined` — the chain walk stops there.
+*/
+function getComposedLayerDefinition(tagValue) {
+	if (tagValue === void 0 || tagValue === null) return void 0;
+	if (typeof tagValue === "string") return void 0;
+	if (typeof tagValue !== "object" && typeof tagValue !== "function") return;
+	const obj = tagValue;
+	if (obj.__kind === "tag" || obj.__kind === "component") return void 0;
+	if (obj.__config && typeof obj.__config === "object") return obj.__config;
+	if (obj.layers && typeof obj.layers === "object") return tagValue;
+}
+/** Build a `Map<layerName, Layer>` from a definition's authored layers. */
+function toLayerMap(layersDef) {
+	if (!layersDef) return void 0;
+	const out = /* @__PURE__ */ new Map();
+	for (const [layerName, layerTag] of Object.entries(layersDef)) out.set(layerName, new Layer({
+		name: layerName,
+		tag: layerTag
+	}));
+	return out;
+}
+/**
+* A single primitive root layer (`{ root: 'div' }` or `{ root: tag('div') }`)
+* — render forwards children straight to the element, so the component holds
+* arbitrary node children.
+*/
+function hasSinglePrimitiveRoot(layers) {
+	if (layers.size !== 1) return false;
+	const t = layers.get("root")?.tag;
+	if (typeof t === "string") return true;
+	if (typeof t === "object" && t !== null) return t.__kind === "tag";
+	return false;
+}
+/**
+* `acceptsChildren` is true when either:
+*   - the component has a single primitive root layer, OR
+*   - a `slot()` prop binds its value to a layer's `children` surface
+*     (covered by `kind: 'slot'` with `layerProp === 'children'`).
+*
+* Composed-component roots and multi-layer configs without a children
+* slot do NOT accept children — the auto-render has nowhere to put
+* them. This stays value-kind-agnostic: a string-label `children` (Button)
+* still counts as "accepts children" for codegen/prop purposes. Tools that
+* need "accepts *droppable layers*" should use {@link derivesAcceptsChildNodes}.
+*/
+function derivesAcceptsChildren(layers, props) {
+	if (hasSinglePrimitiveRoot(layers)) return true;
+	for (const info of props) if (info.kind === "slot" && info.layerProp === "children") return true;
+	return false;
+}
+/**
+* `acceptsChildNodes` narrows {@link derivesAcceptsChildren} to children that
+* are *renderable nodes* — the ones a layer-reparent tool can drop into. A
+* single primitive root qualifies (it forwards `ReactNode` children), as does
+* a `children` slot — unless the author declared it `slot({ type: 'string' })`
+* (a text label like Button's). The decision keys on the *authored intent*,
+* not the resolved `valueType` (a string label still resolves to `'ReactNode'`,
+* so `valueType` alone can't distinguish the two).
+*/
+function derivesAcceptsChildNodes(layers, props) {
+	if (hasSinglePrimitiveRoot(layers)) return true;
+	for (const info of props) if (info.kind === "slot" && info.layerProp === "children" && info.authoredType !== "string") return true;
+	return false;
+}
+function buildCompoundOverrides(entries) {
+	const out = {};
+	if (!entries) return out;
+	for (const entry of entries) for (const [layerName, override] of Object.entries(entry.layers)) {
+		if (!out[layerName]) out[layerName] = {};
+		Object.assign(out[layerName], override);
+	}
+	return out;
+}
+//#endregion
+export { Component, Layer, assertDefinitionAcceptsPlaceable };