@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/entities/system/defineComponent.js

@@ -0,0 +1,337 @@
+import { isRef, kindOf, memberRef, pathOf } from "../../framework/utils/refs.js";
+import { Component, canonicalWhen, layerRef } from "./Component.js";
+//#region src/entities/system/defineComponent.ts
+function build(body) {
+	const handle = (() => null);
+	const next = (patch) => build({
+		...body,
+		...patch
+	});
+	Object.assign(handle, {
+		kind: "component",
+		body,
+		path: void 0,
+		layers: (layers) => next({ layers }),
+		props: (props) => next({ props }),
+		styles: (rules) => next({ styles: rules }),
+		defaultProps: (defaults) => next({ defaultProps: defaults }),
+		forwards: (forwards) => next({ forwards }),
+		metadata: (meta) => next(meta),
+		render: () => handle,
+		renderCanvas: () => handle,
+		preview: (spec) => spec?.defaultProps === void 0 ? handle : next({ previewProps: spec.defaultProps }),
+		toStored: () => toStored(body),
+		assignPath(path) {
+			handle.path = path;
+		}
+	});
+	return handle;
+}
+/**
+* The preview props a CONFIG can hold.
+*
+* A preview default is often authored as JSX (`icon: <PlusIcon/>`, `children: <><Box>Item 1</Box>…</>`),
+* and a React element is not data: `$$typeof` is a symbol and `type` is a function, both of which
+* `JSON.stringify` drops, so storing one yields `{ key, props, _owner, _store }` — React internals that
+* will never revive and that no reader can tell from a real value.
+*
+* So an element is CONVERTED to the same `PreviewElement` shape the build stores — a thing to render
+* and what to render it with — rather than dropped. Both producers then agree, which matters because
+* only one of them runs for any given config: the build reads `.preview()` from source with ts-morph,
+* this runs when a config is registered, and a reader can't tell which made the config it holds.
+*
+* What this path CANNOT do is name an element the source could. A tag is its own name and a component
+* handle carries its adopted path, but a foreign function (a Phosphor glyph, say) is just a function
+* at runtime — its `displayName` is a label, not an identity, and two libraries may both export
+* `StarIcon`. Such a prop is DROPPED: an absent default renders nothing, while a guessed ref renders
+* the wrong glyph and reads as authored. The build resolves those from the import specifier, which is
+* why ~a third of the element-valued preview props in a real system only survive a build.
+*/
+function storableProps(props) {
+	if (props === void 0) return void 0;
+	const out = {};
+	for (const [key, value] of Object.entries(props)) {
+		const stored = storableValue(value);
+		if (stored !== void 0) out[key] = stored;
+	}
+	return Object.keys(out).length === 0 ? void 0 : out;
+}
+/** A live React element, by the marker anything pretending to be one also carries. */
+function isReactElement(value) {
+	return typeof value === "object" && value !== null && "$$typeof" in value;
+}
+const FRAGMENT = Symbol.for("react.fragment");
+/**
+* What a runtime element renders, named the way a stored one names it — or `undefined` when this path
+* can't say faithfully. See {@link storableProps}.
+*/
+function storableElementName(type) {
+	if (typeof type === "string") return type;
+	if (isComponentElement(type) && type.path) return Component.ref(type.path);
+}
+/** The scalar half of an element's props — what `PreviewElement.props` may hold. */
+function storableAttributes(props) {
+	const out = {};
+	for (const [key, value] of Object.entries(props)) {
+		if (key === "children") continue;
+		if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") out[key] = value;
+	}
+	return out;
+}
+/** Children as a list, however one was written — a lone child isn't wrapped in an array. */
+function childList(children) {
+	if (children === void 0 || children === null) return [];
+	return Array.isArray(children) ? children.flat(Number.POSITIVE_INFINITY) : [children];
+}
+/** One React element as the stored shape, or `undefined` when it can't be named. */
+function storableElement(value) {
+	const element = storableElementName(value.type);
+	if (element === void 0) return void 0;
+	const props = {
+		...value.key !== null && value.key !== void 0 ? { key: String(value.key) } : {},
+		...storableAttributes(value.props ?? {})
+	};
+	const children = [];
+	let text;
+	for (const child of childList(value.props?.children)) {
+		if (typeof child === "string" || typeof child === "number") {
+			const literal = String(child).trim();
+			if (literal) text = literal;
+			continue;
+		}
+		if (!isReactElement(child)) continue;
+		const nested = storableElement(child);
+		if (nested) children.push(nested);
+	}
+	return {
+		element,
+		...Object.keys(props).length > 0 ? { props } : {},
+		...children.length > 0 ? { children } : {},
+		...text !== void 0 ? { text } : {}
+	};
+}
+/**
+* One preview-prop value as the config stores it, or `undefined` to drop the prop.
+*
+* Mirrors the arms the build reads from source: a literal, an element, a fragment (several elements
+* under one prop), an array, and a nested record.
+*/
+function storableValue(value) {
+	if (value === null) return null;
+	const type = typeof value;
+	if (type === "string" || type === "number" || type === "boolean") return value;
+	if (type !== "object") return void 0;
+	if (isReactElement(value)) {
+		if (value.type === FRAGMENT) {
+			const items = childList(value.props?.children).filter(isReactElement).map(storableElement).filter((item) => item !== void 0);
+			return items.length > 0 ? items : void 0;
+		}
+		return storableElement(value);
+	}
+	if (Array.isArray(value)) {
+		const items = value.map(storableValue).filter((item) => item !== void 0);
+		return items.length > 0 ? items : void 0;
+	}
+	const out = {};
+	for (const [key, member] of Object.entries(value)) {
+		const stored = storableValue(member);
+		if (stored !== void 0) out[key] = stored;
+	}
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+/**
+* One prop declaration as the config stores it — the tagged union, with the tag DERIVED from what a
+* bare form already says.
+*
+* Two kinds mean something particular as a prop: a style property writes CSS through it, and a
+* composite applies a whole bag. Anything else a ref can name is a set of VALUES, which is what a
+* variant is — an icon library, most often, so `name: Icon.ref('phosphor')` is a variant over its
+* glyphs without copying 1,530 names into the component that renders them.
+*/
+function storedProp(decl, layers) {
+	if (Array.isArray(decl)) return {
+		type: "variant",
+		value: decl
+	};
+	if (isAuthoredForward(decl)) return storedForward(decl, layers);
+	if (!isRef(decl)) return decl;
+	const kind = kindOf(decl);
+	if (kind === "style-property") return {
+		type: "styleProperty",
+		value: decl
+	};
+	if (kind === "composite") return {
+		type: "composite",
+		value: decl
+	};
+	return {
+		type: "variant",
+		value: decl
+	};
+}
+/**
+* A route whose far end is still a NAME — either half of the authored form.
+*
+* `target: 'input/disabled'` is what a config file writes; `into: 'disabled'` beside a layer ref is
+* what the schema's split leaves. Both are the same declaration one step from storage, and both need
+* the member ref this builder is about to mint. A body read back from the config already spells it and
+* is left alone.
+*
+* `toStored` runs BEFORE the schema, so the path form is what actually arrives here — testing only for
+* a string `into` meant nothing matched and the ref was never minted.
+*/
+function isAuthoredForward(decl) {
+	if (typeof decl !== "object" || decl === null || decl.type !== "forward") return false;
+	const { target, into } = decl;
+	return typeof target === "string" || typeof into === "string";
+}
+/**
+* A `bind()` declaration with its `into` resolved to a member ref at the target layer's element.
+*
+* Left as authored when the layer's element is a tag or an unadopted handle: a tag's props are the
+* DOM's and have no entity to point into, and minting a ref against an empty path would produce
+* `component:#props/x`, which resolves to nothing and reads as authored. The schema refuses a
+* non-ref `into`, so the failure is loud at registration rather than silent in the data.
+*/
+function storedForward(decl, layers) {
+	return storedRoutedForward(typeof decl.target === "string" ? {
+		...decl,
+		target: layerRef(decl.target.slice(0, decl.target.indexOf("/"))),
+		into: decl.target.slice(decl.target.indexOf("/") + 1)
+	} : {
+		...decl,
+		target: decl.target,
+		into: decl.into ?? "children"
+	}, layers);
+}
+function storedRoutedForward(decl, layers) {
+	const layer = pathOf(decl.target);
+	const element = layers?.[layer];
+	const path = isComponentElement(element) ? element.path : isRef(element) ? pathOf(element) : void 0;
+	if (!path) return decl;
+	const declaring = declaringPath(element, decl.into) ?? path;
+	return {
+		...decl,
+		into: memberRef("component", declaring, "props", decl.into)
+	};
+}
+/** The prop name a forwarding entry identifies, whichever spelling it is in — authored names have not
+*  become member refs yet at this point, and a re-authored body may hold either. */
+function forwardedName(entry) {
+	if (typeof entry === "string") return entry;
+	if (isRef(entry)) return pathOf(entry).split("/").pop();
+}
+/**
+* Which component in the layer chain actually DECLARES `prop` — the one a member ref can point into.
+*
+* A forwarded prop has no declaration on the component that exposes it, so the walk follows
+* `forwards` into the layer that supplies it and asks the same question there. `seen` guards a cycle:
+* the chain is authored data, so nothing stops a config from describing one.
+*/
+function declaringPath(element, prop, seen = /* @__PURE__ */ new Set()) {
+	if (!isComponentElement(element) || seen.has(element)) return void 0;
+	const body = element.body;
+	if (!body) return void 0;
+	const props = body.props;
+	if (props && prop in props) return props[prop] === null ? void 0 : element.path;
+	const forwards = body.forwards;
+	if (!forwards) return void 0;
+	const next = new Set(seen).add(element);
+	const layers = body.layers;
+	for (const [layer, entry] of Object.entries(forwards)) {
+		if (!(entry === "*" || Array.isArray(entry) && entry.some((one) => forwardedName(one) === prop))) continue;
+		const found = declaringPath(layers?.[layer], prop, next);
+		if (found) return found;
+	}
+}
+/** Whether a layer's element is another component's handle rather than a tag or a ref. */
+function isComponentElement(value) {
+	return typeof value === "function" && value.kind === "component";
+}
+/**
+* A `forwards` record with each narrowing list's prop NAMES resolved to member refs — the same step
+* {@link storedForward} performs, for the same reason and at the same moment.
+*
+* Each ref names the component that DECLARES the prop, which is not always the layer's own element:
+* `Button` forwarding `width` from a `Pressable` root names `Box`, since `Pressable` only forwards it
+* on from there. A ref at `Pressable` would resolve to nothing, and the build refuses a config that
+* spells one. The element's own path is the fallback when nothing in the chain declares the name.
+*
+* `'*'` passes through: it names nothing, so it has no ref to mint and cannot rot on a rename. A list
+* against a tag or an unadopted handle is left as authored, so the schema's refusal is loud at
+* registration rather than silent in the data.
+*/
+function storedForwards(forwards, layers) {
+	const out = {};
+	for (const [layer, entry] of Object.entries(forwards)) {
+		if (!Array.isArray(entry)) {
+			out[layer] = entry;
+			continue;
+		}
+		const element = layers?.[layer];
+		const path = isComponentElement(element) ? element.path : isRef(element) ? pathOf(element) : void 0;
+		out[layer] = path ? entry.map((name) => typeof name === "string" ? memberRef("component", declaringPath(element, name) ?? path, "props", name) : name) : entry;
+	}
+	return out;
+}
+/** The authored body as the entity's stored shape — which differs in exactly four places. */
+function toStored(body) {
+	const stored = { ...body };
+	if (body.previewProps !== void 0) {
+		const previewProps = storableProps(body.previewProps);
+		if (previewProps === void 0) delete stored.previewProps;
+		else stored.previewProps = previewProps;
+	}
+	if (body.props && typeof body.props === "object") {
+		const props = {};
+		for (const [name, decl] of Object.entries(body.props)) props[name] = storedProp(decl, body.layers);
+		stored.props = props;
+	}
+	if (body.layers && typeof body.layers === "object") {
+		const layers = {};
+		for (const [name, element] of Object.entries(body.layers)) layers[name] = isComponentElement(element) ? Component.ref(element.path ?? "") : element;
+		stored.layers = layers;
+	}
+	if (body.forwards && typeof body.forwards === "object") stored.forwards = storedForwards(body.forwards, body.layers);
+	const rules = body.styles;
+	if (!Array.isArray(rules)) return stored;
+	const styles = {};
+	for (const rule of rules) styles[canonicalWhen(rule.when)] = {
+		when: rule.when ?? null,
+		layers: rule.layers
+	};
+	return {
+		...stored,
+		styles
+	};
+}
+/**
+* Author a component.
+*
+* Callable for the case with nothing to narrow — `defineComponent({ layers: { root: 'div' } })` — and
+* chainable for every other, since a chain is what lets each step's types come from the last.
+*/
+/**
+* Author a component.
+*
+* Called with an ELEMENT — `defineComponent('input')`, `defineComponent(Component.ref('Box'))` — that
+* element becomes the root layer, because a component with one layer IS that element and saying so
+* twice adds nothing. It's also what makes the element's props type correctly: v1 expressed this as a
+* `defaultProps: { as: 'input' }` on a `div`-rooted component, which left the config claiming the
+* element was a `div` while every call site treated it as an input.
+*
+* The render follows from it too — one layer needs no anatomy, so the build generates the element
+* rather than reading a `.render()` that would only restate the layer.
+*/
+function defineComponentImpl(bodyOrElement) {
+	if (isComponentElement(bodyOrElement)) return build({ layers: { root: bodyOrElement } });
+	if (typeof bodyOrElement === "function" || isRef(bodyOrElement) && kindOf(bodyOrElement) === "package") throw new Error("[uds] defineComponent(<package export>): a package export cannot be a component's only layer yet — the generated one-layer render emits web elements. Declare `layers` and a `.render()` instead.");
+	if (typeof bodyOrElement === "string" || isRef(bodyOrElement)) return build({ layers: { root: bodyOrElement } });
+	return build(bodyOrElement ?? {});
+}
+const defineComponent = Object.assign(defineComponentImpl, {
+	layers: (layers) => build({}).layers(layers),
+	props: (props) => build({}).props(props)
+});
+//#endregion
+export { defineComponent };

package/dist/entities/system/element.d.ts

@@ -0,0 +1,101 @@
+import { Config } from "../../framework/Config.js";
+
+//#region src/entities/system/element.d.ts
+/**
+ * A component's forwarded layers, as `{ [layer]: '*' | Ref[] }` — the ONE reader of the field.
+ *
+ * A field read directly is a field that has to be found again when its shape changes; there were six
+ * such callers once, and three read it raw.
+ *
+ * It used to fall back to `inherits`, the pre-migration spelling, read as `{ [layer]: '*' }`. That
+ * reader is gone: `v1-artifact` folds a v1 config straight to `forwards`, so nothing mints the old
+ * field, and a stored config still carrying it now forwards nothing rather than being quietly
+ * translated. Deliberate — one name for one concept beats two where the second is invisible.
+ */
+declare function forwardsOf(body: {
+  forwards?: Record<string, unknown> | undefined;
+}): Record<string, unknown>;
+/**
+ * A component's root layer — where every prop the config doesn't model is sent.
+ *
+ * The schema REQUIRES a layer called `root` (see `Component`'s `layers`), so the fallback below is for
+ * malformed data only: a per-member `sub-delete` doesn't re-validate its owner, so this answers
+ * defensively rather than assuming. It is not a way to have a differently-named root.
+ */
+declare function rootLayerOf(layers: Record<string, unknown>): [name: string, element: unknown];
+/**
+ * What a component renders, as the two things React's element type can be.
+ *
+ * A `tag` is already an element type — `'div'`, `'input'` — and needs no lookup. A `ref` is a
+ * package export (`package:reactNative/Pressable`), which is what a native layer always is, and
+ * reaching it means generating its import. Only the emitter that generates imports can do that, so
+ * this hands back the ref rather than resolving it.
+ */
+type RenderedTarget = {
+  readonly kind: 'tag';
+  readonly tag: string;
+} | {
+  readonly kind: 'ref';
+  readonly ref: string;
+};
+/**
+ * The element `path` renders, following component roots until something concrete turns up.
+ *
+ * `div` when nothing resolves — a component whose root is a dangling ref still has to render as
+ * something, and the neutral container is the answer that breaks the least.
+ */
+declare function renderedTarget(config: Config, path: string, seen?: Set<string>): RenderedTarget;
+/**
+ * The TAG `path` renders — the web half of {@link renderedTarget}, where a package export has no
+ * tag to be and the neutral container stands in.
+ *
+ * Expressed over the same walk rather than repeating it: two walks that answer "what does this
+ * render" can disagree about a pinned `as` or a component root, and only one of them is consulted
+ * by the module that ships.
+ */
+declare function renderedElement(config: Config, path: string, seen?: Set<string>): string;
+/**
+ * Elements that may not be given children — React throws when one is.
+ *
+ * The list is HTML's, not the config's: whether `<input>` takes children is a fact about the DOM, and
+ * a design system has no say in it.
+ */
+declare const VOID_ELEMENTS: ReadonlySet<string>;
+/**
+ * What a component may be given as children — the ONE answer to a question v1 asks as two
+ * complementary name lists, and gets subtly wrong at the edges.
+ *
+ * Two facts decide it, and neither implies the other:
+ *
+ *  - the ELEMENT it renders. A void one takes no children; React throws if it's given any. `as` is
+ *    part of this, which is what v1's `voidComponents` misses — `Input` is `div`-layered and an
+ *    `<input>`, so a leaked child forwards onto a void element and throws (UDS-2907).
+ *  - what the COMPONENT declares. One with no `children` slot has nowhere to put them, whatever its
+ *    element would allow — a `div`-rooted form control is the case that lands here and nowhere else.
+ *
+ * `text` is the third answer, not a special case of `nodes`: a slot marked `text` takes a string,
+ * so a picker offers a text field rather than a node well.
+ */
+type ChildrenPolicy = 'none' | 'text' | 'nodes';
+declare function childrenPolicy(config: Config, path: string): ChildrenPolicy;
+/**
+ * The component one is a PART of — `Card/Header` is part of `Card`.
+ *
+ * A part is not a new relationship needing a new field: in this model identity IS the path, so a
+ * component nested under another is nested by being named that way, exactly as `color/brand` is a
+ * token in `color` and `phosphor/StarIcon` is a glyph in `phosphor`. Storing the edge as well would
+ * be the same fact in two places, and the two could disagree the moment either moved.
+ *
+ * `undefined` when the path names no owner (a component in a plain group, or a top-level one) — which
+ * is also the test for "offer this in a palette", since a part is reached through the thing it belongs
+ * to rather than listed beside it.
+ */
+declare function ownerOf(config: Config, path: string): string | undefined;
+/**
+ * The components that are parts of this one, in registration order.
+ *
+ * Direct parts only: `Card/Header/Title` is a part of `Card/Header`, which is what the path says.
+ */
+declare function partsOf(config: Config, path: string): string[];
+//#endregion
+export { ChildrenPolicy, RenderedTarget, VOID_ELEMENTS, childrenPolicy, forwardsOf, ownerOf, partsOf, renderedElement, renderedTarget, rootLayerOf };

package/dist/entities/system/element.js

@@ -0,0 +1,171 @@
+import { memberOf, splitRef } from "../../framework/utils/refs.js";
+//#region src/entities/system/element.ts
+/** The path a value points at when it's a ref to a component, else `undefined`. */
+function componentPathOf(value) {
+	const marker = value?.__ref;
+	if (typeof marker !== "string") return void 0;
+	const { kind, qualifiedPath } = splitRef(marker);
+	return kind === "component" && qualifiedPath !== marker ? qualifiedPath : void 0;
+}
+/**
+* A component's forwarded layers, as `{ [layer]: '*' | Ref[] }` — the ONE reader of the field.
+*
+* A field read directly is a field that has to be found again when its shape changes; there were six
+* such callers once, and three read it raw.
+*
+* It used to fall back to `inherits`, the pre-migration spelling, read as `{ [layer]: '*' }`. That
+* reader is gone: `v1-artifact` folds a v1 config straight to `forwards`, so nothing mints the old
+* field, and a stored config still carrying it now forwards nothing rather than being quietly
+* translated. Deliberate — one name for one concept beats two where the second is invisible.
+*/
+function forwardsOf(body) {
+	return body.forwards ?? {};
+}
+/**
+* A component's root layer — where every prop the config doesn't model is sent.
+*
+* The schema REQUIRES a layer called `root` (see `Component`'s `layers`), so the fallback below is for
+* malformed data only: a per-member `sub-delete` doesn't re-validate its owner, so this answers
+* defensively rather than assuming. It is not a way to have a differently-named root.
+*/
+function rootLayerOf(layers) {
+	if ("root" in layers) return ["root", layers.root];
+	const [name = "root", element] = Object.entries(layers)[0] ?? [];
+	return [name, element];
+}
+/** The ref a value points at when it's a package export used as an element, else `undefined`. */
+function packageRefOf(value) {
+	const marker = value?.__ref;
+	if (typeof marker !== "string") return void 0;
+	const { kind, qualifiedPath } = splitRef(marker);
+	return kind === "package" && qualifiedPath !== marker ? marker : void 0;
+}
+/**
+* The element `path` renders, following component roots until something concrete turns up.
+*
+* `div` when nothing resolves — a component whose root is a dangling ref still has to render as
+* something, and the neutral container is the answer that breaks the least.
+*/
+function renderedTarget(config, path, seen = /* @__PURE__ */ new Set()) {
+	const fallback = {
+		kind: "tag",
+		tag: "div"
+	};
+	if (seen.has(path)) return fallback;
+	seen.add(path);
+	const body = config.resolve("component", path)?.toJSON();
+	if (!body) return fallback;
+	const pinned = body.defaultProps?.as;
+	if (typeof pinned === "string") return {
+		kind: "tag",
+		tag: pinned
+	};
+	const [, element] = rootLayerOf(body.layers ?? {});
+	if (typeof element === "string") return {
+		kind: "tag",
+		tag: element
+	};
+	const packageRef = packageRefOf(element);
+	if (packageRef) return {
+		kind: "ref",
+		ref: packageRef
+	};
+	const target = componentPathOf(element);
+	return target ? renderedTarget(config, target, seen) : fallback;
+}
+/**
+* The TAG `path` renders — the web half of {@link renderedTarget}, where a package export has no
+* tag to be and the neutral container stands in.
+*
+* Expressed over the same walk rather than repeating it: two walks that answer "what does this
+* render" can disagree about a pinned `as` or a component root, and only one of them is consulted
+* by the module that ships.
+*/
+function renderedElement(config, path, seen = /* @__PURE__ */ new Set()) {
+	const target = renderedTarget(config, path, seen);
+	return target.kind === "tag" ? target.tag : "div";
+}
+/**
+* Elements that may not be given children — React throws when one is.
+*
+* The list is HTML's, not the config's: whether `<input>` takes children is a fact about the DOM, and
+* a design system has no say in it.
+*/
+const VOID_ELEMENTS = new Set([
+	"area",
+	"base",
+	"br",
+	"col",
+	"embed",
+	"hr",
+	"img",
+	"input",
+	"link",
+	"meta",
+	"param",
+	"source",
+	"track",
+	"wbr"
+]);
+function childrenPolicy(config, path) {
+	if (VOID_ELEMENTS.has(renderedElement(config, path))) return "none";
+	const slot = childrenSlot(config, path);
+	if (slot === void 0) return "none";
+	return slot?.text ? "text" : "nodes";
+}
+/**
+* The `children` slot a component exposes — its own, or the one it inherits from the layer it's
+* built on. `undefined` when it has none.
+*
+* A DECLARED `null` is the omit tombstone: a component drops an inherited slot that way, so a
+* present key is not the same as an accepted slot.
+*/
+function childrenSlot(config, path, seen = /* @__PURE__ */ new Set()) {
+	if (seen.has(path)) return void 0;
+	seen.add(path);
+	const body = config.resolve("component", path)?.toJSON();
+	if (!body) return void 0;
+	const declared = body.props?.children;
+	if (declared !== void 0) return declared === null ? void 0 : declared;
+	for (const [layer, entry] of Object.entries(forwardsOf(body))) {
+		if (Array.isArray(entry) && !entry.some((r) => namesChildren(r))) continue;
+		const target = componentPathOf(body.layers?.[layer]);
+		if (!target) continue;
+		const slot = childrenSlot(config, target, seen);
+		if (slot !== void 0) return slot;
+	}
+}
+/** Whether a forwarded member ref names a `children` prop. */
+function namesChildren(entry) {
+	const marker = entry?.__ref;
+	if (typeof marker !== "string") return false;
+	return memberOf(marker)?.endsWith("/children") ?? false;
+}
+/**
+* The component one is a PART of — `Card/Header` is part of `Card`.
+*
+* A part is not a new relationship needing a new field: in this model identity IS the path, so a
+* component nested under another is nested by being named that way, exactly as `color/brand` is a
+* token in `color` and `phosphor/StarIcon` is a glyph in `phosphor`. Storing the edge as well would
+* be the same fact in two places, and the two could disagree the moment either moved.
+*
+* `undefined` when the path names no owner (a component in a plain group, or a top-level one) — which
+* is also the test for "offer this in a palette", since a part is reached through the thing it belongs
+* to rather than listed beside it.
+*/
+function ownerOf(config, path) {
+	const slash = path.lastIndexOf("/");
+	if (slash === -1) return void 0;
+	const owner = path.slice(0, slash);
+	return config.resolve("component", owner) ? owner : void 0;
+}
+/**
+* The components that are parts of this one, in registration order.
+*
+* Direct parts only: `Card/Header/Title` is a part of `Card/Header`, which is what the path says.
+*/
+function partsOf(config, path) {
+	return config.list("component").filter((item) => ownerOf(config, item.path) === path).map((item) => item.path);
+}
+//#endregion
+export { VOID_ELEMENTS, childrenPolicy, forwardsOf, ownerOf, partsOf, renderedElement, renderedTarget, rootLayerOf };

package/dist/entities/system/icon-library.d.ts

@@ -0,0 +1,64 @@
+import { Config } from "../../framework/Config.js";
+
+//#region src/entities/system/icon-library.d.ts
+/** An icon library, as its group node describes it. */
+interface IconLibrary {
+  /** The group path — the `slug` half of a placed glyph's type. */
+  readonly path: string;
+  /** The glyphs it ships, by leaf name. */
+  readonly members: readonly string[];
+  /** Named sizes (`sm: 16`). */
+  readonly sizes: Readonly<Record<string, number>>;
+  /** Weights/styles the set ships. */
+  readonly variants: readonly string[];
+  /** The component a placed glyph renders through, if the set declares one. */
+  readonly component?: string;
+  /** The npm module that supplies the library's glyph implementations. */
+  readonly module?: string;
+  /** The version of the package the glyphs come from, when the set pins one —
+   *  what an assets index shows beside the library's name. */
+  readonly version?: string;
+  /** The variant the bound component declares in its `defaultProps` — what a
+   *  picker seeds when nothing is stored. Passed through as DECLARED; a policy
+   *  read validates against {@link variants} before trusting it. */
+  readonly defaultVariant?: string;
+  /** The size bucket the bound component declares in its `defaultProps`.
+   *  Same contract as {@link defaultVariant}: declared, not validated. */
+  readonly defaultSizeKey?: string;
+}
+/** The spec `type` a placed glyph of this library carries — its own ref. */
+declare function assetType(library: IconLibrary, member: string): string;
+/** One library by its group path — `undefined` when the config has no such set. */
+declare function iconLibrary(config: Config | null | undefined, path: string): IconLibrary | undefined;
+/** Every icon library the config declares. */
+declare function iconLibraries(config: Config | null | undefined): IconLibrary[];
+/**
+ * The library a surface should show: the hinted one when a caller carries a slug (a slot's
+ * `accepts` ref, a stored fill), else the first library that actually has members. One home for
+ * that policy — the toolbar, placement, and the panel all resolve through here, so no surface
+ * carries its own idea of a default set. A hint that names no library resolves to `undefined`
+ * rather than falling back: the caller knows whether a stale slug should show empty or pick anew.
+ */
+declare function resolveIconLibrary(config: Config | null | undefined, hint?: string): IconLibrary | undefined;
+/**
+ * Every category the library's members carry, RAW as stored (lowercase, unsorted within a member,
+ * plural per member), deduplicated and sorted for a filter menu. Casing is display policy — a
+ * surface title-cases for headings; values compare and filter by the stored form.
+ */
+declare function iconCategories(config: Config | null | undefined, libraryPath: string): readonly string[];
+/**
+ * The variants a placed glyph may take.
+ *
+ * The whole library's variants: nothing in the model describes one glyph's own set yet
+ * (config-v2 model gap 8 — per-item `variants` narrowing). So a set that ships a variant only
+ * some of its glyphs support will offer it for all of them until that closes.
+ */
+declare function memberVariantOptions(library: IconLibrary, _member: string): readonly string[];
+/**
+ * Whether an element type declares a prop that may survive layer-style projection. A placed
+ * glyph's type isn't a component, so its prop surface comes from its library instead: the
+ * component the set renders through, plus the size and variant axes the set ships.
+ */
+declare function isDeclaredElementProp(config: Config | null | undefined, elementType: string, propName: string): boolean;
+//#endregion
+export { IconLibrary, assetType, iconCategories, iconLibraries, iconLibrary, isDeclaredElementProp, memberVariantOptions, resolveIconLibrary };