@yahoo/uds-create-config 4.22.1 → 4.23.0

package/dist/entities/system/Component.js

@@ -19,6 +19,7 @@ import { instanceAt } from "../../spec/instance.js";
 import { Package } from "./Package.js";
 import { File } from "./File.js";
 import { iconDomainInvariants } from "./icon-domain-invariants.js";
+import { rootLayerInvariants } from "./root-layer-invariants.js";
 import { Token } from "./Token.js";
 import { intoName, routedPropIn, routesContent } from "../../framework/prop-surface.js";
 import { z } from "zod";
@@ -744,7 +745,7 @@ function exampleStyleBag(config, primitivePath) {
 	const bag = {};
 	for (const [name, prop] of Object.entries(props)) {
 		if (prop?.type !== "styleProperty" || !isRef(prop.value)) continue;
-		const leaves = stylePropValueLeaves(config, pathOf(prop.value.__ref));
+		const leaves = stylePropValueLeaves(config, pathOf(prop.value.__ref), { retired: false });
 		const value = leaves.find((leaf) => !inert.has(leaf)) ?? leaves[0];
 		if (value !== void 0) bag[name] = value;
 		if (Object.keys(bag).length >= 3) break;
@@ -1371,7 +1372,8 @@ const AnatomyNode = defineSubEntity({
 			...node,
 			element: { __ref: `layer:${key}` }
 		} : node);
-	}
+	},
+	listedIn: ["anatomy/*/children", "anatomy/*/slots/*"]
 });
 const componentFields = z.strictObject({
 	/**
@@ -2071,7 +2073,7 @@ subtree: z.boolean().default(true) }).optional()
 			handler: (input, config) => validateComponentProps(config, String(input.path), input.data.props ?? {})
 		}
 	},
-	invariants: (config) => iconDomainInvariants(config)
+	invariants: (config) => [...iconDomainInvariants(config), ...rootLayerInvariants(config)]
 });
 const baseComponentRef = ComponentEntity.ref.bind(ComponentEntity);
 /** Component refs add the source-only authoring steps to the generic ref-extension value. All of them

package/dist/entities/system/root-layer-invariants.d.ts

@@ -0,0 +1,9 @@
+import type { Config } from '../../framework/Config';
+/**
+ * A component's layers include one named `root`. The name is what the anatomy's edge list starts
+ * from, where a slot prop's content lands when it has no node of its own, and what the authored
+ * TypeScript surface types the root element by, so a component whose layers are named anything
+ * else renders a top nothing addresses. A component with no layers at all is not judged here: a
+ * leaf renders as itself and declares none.
+ */
+export declare const rootLayerInvariants: (config: Config) => string[];

package/dist/entities/system/root-layer-invariants.js

@@ -0,0 +1,25 @@
+import { isPlainRecord } from "./style-bag.js";
+import { createSliceMemo } from "../../framework/memo.js";
+//#region src/entities/system/root-layer-invariants.ts
+/**
+* A component's layers include one named `root`. The name is what the anatomy's edge list starts
+* from, where a slot prop's content lands when it has no node of its own, and what the authored
+* TypeScript surface types the root element by, so a component whose layers are named anything
+* else renders a top nothing addresses. A component with no layers at all is not judged here: a
+* leaf renders as itself and declares none.
+*/
+const rootLayerInvariants = createSliceMemo({
+	kinds: ["component"],
+	compute: (config) => {
+		const problems = [];
+		for (const item of config.list("component")) {
+			const layers = (config.resolve("component", item.path)?.toJSON())?.layers;
+			if (!isPlainRecord(layers) || Object.keys(layers).length === 0) continue;
+			if ("root" in layers) continue;
+			problems.push(`Component "${item.path}" has layers (${Object.keys(layers).join(", ")}) but none named "root"; the root layer is the top of the anatomy and keeps that name.`);
+		}
+		return problems;
+	}
+});
+//#endregion
+export { rootLayerInvariants };

package/dist/framework/Config.d.ts

@@ -1623,8 +1623,10 @@ declare class Config {
    *
    * An authoring question, not a resolution one. The entity is still here and still resolves, because
    * references already going through it have to keep working — so nothing that emits a *value* reads
-   * this. What does: a surface that lists paths for someone to pick from, and the emitted type union,
-   * which is exactly such a list.
+   * this, and neither does the emitted ref-path union: a hidden token is still a legal target for a
+   * `Token.ref` in another token's value, a style prop's `values`, a rule or a render read. What does
+   * read it: a surface that lists values for someone to pick from — a picker, a catalogue, and the
+   * emitted style-prop value unions, which are exactly such a list.
    *
    * True when the entity's own body says `hidden`, when any folder above it does, or when the pin a
    * borrowed row came through hides its path. A folder's flag reaches every member without the members

package/dist/framework/Config.js

@@ -476,6 +476,48 @@ function renameKeyedByName(sub, def, from, to) {
 	return out;
 }
 /**
+* Follow a member's name into the lists that hold it — an anatomy node's `children` and each of its
+* `slots` entries name sibling nodes by key. `to: undefined` drops the entry: a list naming a key no
+* node has is a child nothing renders, and the node's own key rename would leave exactly that.
+*/
+function renameListedNames(sub, def, from, to) {
+	if (!sub?.listedIn?.length) return def;
+	let out = def;
+	for (const field of sub.listedIn) {
+		const next = relistAt(out, field.split("/"), from, to);
+		if (isPlainObject(next)) out = next;
+	}
+	return out;
+}
+/**
+* Rewrite `from` → `to` (or drop it, for `to: undefined`) in every string list `path` reaches; the
+* path ends at the list, and a `*` segment stands for every key at that level. Rebuilds only the
+* branches that changed, so an untouched owner keeps its reference.
+*/
+function relistAt(node, path, from, to) {
+	const [head, ...rest] = path;
+	if (head === void 0) {
+		if (!Array.isArray(node) || !node.includes(from)) return node;
+		return to === void 0 ? node.filter((entry) => entry !== from) : node.map((entry) => entry === from ? to : entry);
+	}
+	if (!isPlainObject(node)) return node;
+	if (head === "*") {
+		let changed = false;
+		const next = {};
+		for (const [key, value] of Object.entries(node)) {
+			const rewritten = relistAt(value, rest, from, to);
+			if (rewritten !== value) changed = true;
+			next[key] = rewritten;
+		}
+		return changed ? next : node;
+	}
+	const rewritten = relistAt(node[head], rest, from, to);
+	return rewritten === node[head] ? node : {
+		...node,
+		[head]: rewritten
+	};
+}
+/**
 * Rewrite `from` → `to` (or drop it, for `to: undefined`) in the record `path` addresses.
 *
 * A `*` segment stands for every key at that level, which is what reaches a nested bag: a layer's
@@ -1743,6 +1785,7 @@ var Config = class Config {
 			def = rewriteRefs(def, `${refKind}:${refPathOf(patch, patch.key)}`, `${refKind}:${refPathOf(patch, patch.to)}`);
 			def = renameNamedValues(sub, def, patch.owner, patch.key, patch.to);
 			def = renameKeyedByName(sub, def, patch.key, patch.to);
+			def = renameListedNames(sub, def, patch.key, patch.to);
 			const namespaces = sub?.namespaces;
 			if (namespaces) def = rewriteRefNamespace(def, namespaces, patch.key, patch.to);
 			def = this.rekeyRecords(entry, def, patch.field, patch.key, patch.to);
@@ -1759,6 +1802,7 @@ var Config = class Config {
 			def = store(def, collection);
 			def = renameNamedValues(sub, def, patch.owner, patch.key, void 0);
 			def = renameKeyedByName(sub, def, patch.key, void 0);
+			def = renameListedNames(sub, def, patch.key, void 0);
 			def = dropVacated(entry, sub, def);
 			def = dropOrphans(sub, def, `${leafOf(patch.field).replace(/s$/, "")}:${refPathOf(patch, patch.key)}`, sub?.namespaces ? {
 				kind: sub.namespaces,
@@ -2963,8 +3007,10 @@ var Config = class Config {
 	*
 	* An authoring question, not a resolution one. The entity is still here and still resolves, because
 	* references already going through it have to keep working — so nothing that emits a *value* reads
-	* this. What does: a surface that lists paths for someone to pick from, and the emitted type union,
-	* which is exactly such a list.
+	* this, and neither does the emitted ref-path union: a hidden token is still a legal target for a
+	* `Token.ref` in another token's value, a style prop's `values`, a rule or a render read. What does
+	* read it: a surface that lists values for someone to pick from — a picker, a catalogue, and the
+	* emitted style-prop value unions, which are exactly such a list.
 	*
 	* True when the entity's own body says `hidden`, when any folder above it does, or when the pin a
 	* borrowed row came through hides its path. A folder's flag reaches every member without the members

package/dist/framework/defineSubEntity.d.ts

@@ -91,6 +91,13 @@ type SubEntityClass<F extends z.ZodTypeAny = z.ZodTypeAny> = CollectionSchema<F>
    * the renamed prop reports no default and the component reports one for a prop it hasn't got.
    */
   readonly keyedByNameIn?: readonly string[];
+  /**
+   * Fields of the OWNING ENTITY that LIST this member's name among others — an anatomy node's
+   * `children` and each of its `slots` entries name sibling nodes by key. A field is a `/` path;
+   * `*` stands for every key at that level, and the path ends at the list. A rename rewrites the
+   * entry and a delete drops it, since a list holding a key no node has is a child nothing renders.
+   */
+  readonly listedIn?: readonly string[];
   /**
    * Sibling collections whose members exist only to say something ABOUT one of these — a style
    * rule IS its condition, so a rule conditioned on a variant value that has been removed has
@@ -143,6 +150,7 @@ declare function defineSubEntity<F extends z.ZodTypeAny>(spec: {
   subEntities?: Readonly<Record<string, SubEntityClass>>;
   namedValuesIn?: readonly string[];
   keyedByNameIn?: readonly string[];
+  listedIn?: readonly string[];
   orphans?: readonly string[];
 }): SubEntityClass<F>;
 //#endregion

package/dist/framework/defineSubEntity.js

@@ -85,6 +85,7 @@ function defineSubEntity(spec) {
 		subEntities: spec.subEntities,
 		namedValuesIn: spec.namedValuesIn,
 		keyedByNameIn: spec.keyedByNameIn,
+		listedIn: spec.listedIn,
 		orphans: spec.orphans,
 		ref: (kind, path, member) => memberRef(kind, path, spec.name, member),
 		get: (config, owner, member, ownerMember) => {

package/dist/framework/projections.d.ts

@@ -1,6 +1,6 @@
 import { Ref } from "./utils/refs.js";
 import { ItemOf } from "./defineEntity.js";
-import { Config } from "./Config.js";
+import { Config, ListOptions } from "./Config.js";
 import { StylePropLeaf, StyleProperty } from "../entities/system/StyleProperty.js";
 import { StoredPreviewCondition, UNCONDITIONAL_PREVIEW_KEY, storedPreview, unconditionalPreviewProps } from "./preview-store.js";
 
@@ -58,20 +58,28 @@ type StylePropEntry = StylePropLeaf;
  *  signature that took it apart made every call site split one by hand, and the three that did
  *  disagreed about whether the `@source` survived the trip — which decides which config the members
  *  come from. */
-declare function memberLeaves(config: Config, target: string | Ref): string[];
+declare function memberLeaves(config: Config, target: string | Ref, opts?: ListOptions): string[];
 /** Resolve a group-bound leaf back to its qualified path (`display2` → `textVariant/display2`).
  *  `undefined` when the leaf isn't a member — what validation rejects. */
 declare function memberFromLeaf(config: Config, target: string | Ref, leaf: string): string | undefined;
 /** The refs of a domain written as a list of them, else `undefined`. A string list, a single ref
  *  and a keyed collection all answer `undefined`, so this is the one test for the list form. */
 declare function refListOf(domain: unknown): string[] | undefined;
-declare function stylePropEntries(config: Config, path: string): StylePropEntry[];
+/**
+ * Every value a style prop accepts, as `{ leaf, value }` pairs. Total by default: the stylesheet
+ * emits a utility per entry, and a value already bound to a retired token keeps resolving through
+ * it. `{ retired: false }` is what a surface offers for a new value — a picker, a catalogue, the
+ * emitted value union — and leaves out a token that is hidden or deprecated, itself or through a
+ * folder above it.
+ */
+declare function stylePropEntries(config: Config, path: string, opts?: ListOptions): StylePropEntry[];
 /**
  * A style prop's leaf value domain — what a consumer/model actually authors (`warning`, `carbon/2`),
  * not the qualified storage path (`color/warning`). This is what the catalog, `uds_get_component`,
- * `uds_validate_props`, and the UI picker should offer, so the model emits `color="warning"`.
+ * `uds_validate_props`, and the UI picker should offer, so the model emits `color="warning"`; an
+ * offer reads it with `{ retired: false }`, as {@link stylePropEntries} describes.
  */
-declare function stylePropValueLeaves(config: Config, path: string): string[];
+declare function stylePropValueLeaves(config: Config, path: string, opts?: ListOptions): string[];
 /**
  * Resolve a style-prop leaf value back to its qualified token path (or literal) — the inverse of
  * {@link stylePropValueLeaves}, for validating + rendering an authored `bg="subtle"`. `undefined`

package/dist/framework/projections.js

@@ -27,6 +27,10 @@ import { isConditionalPreview, storedPreview, unconditionalPreviewProps } from "
 */
 const memberEntryCache = /* @__PURE__ */ new WeakMap();
 const stylePropEntryCache = /* @__PURE__ */ new WeakMap();
+/** The cache key of a domain read: the target, and whether the read leaves out retired members. */
+function domainKey(target, opts) {
+	return opts?.retired === false ? `${target}\u0000offered` : target;
+}
 /** The per-config half of one of the caches above, created on first use. */
 function domainCache(cache, config) {
 	let entry = cache.get(config);
@@ -103,18 +107,25 @@ function stylePropValues(config, path) {
 * weights from the library it renders are all the same question, so they are all this. A prop that
 * enumerates instead of delegating is a copy of a list nothing keeps in step — 1,530 glyph names in
 * the component that renders them, which is what the facet arm exists to stop.
+*
+* Total by default, the same way {@link Config.list} is: the stylesheet, the validator and the
+* leaf↔path lookups all read it, and a value already bound to a retired member has to keep
+* resolving. `{ retired: false }` is the offer surface's read — a picker, a catalogue, the emitted
+* value union — and leaves out every member {@link Config.retired} answers true for, asked of the
+* config that holds the member.
 */
-function memberEntries(config, target) {
+function memberEntries(config, target, opts) {
 	const cache = domainCache(memberEntryCache, config);
-	const key = isRef(target) ? target.__ref : target;
+	const key = domainKey(isRef(target) ? target.__ref : target, opts);
 	const hit = cache.get(key);
 	if (hit) return hit;
-	const expanded = expandMemberEntries(config, target);
+	const expanded = expandMemberEntries(config, target, opts);
 	cache.set(key, expanded);
 	return expanded;
 }
-function expandMemberEntries(config, target) {
+function expandMemberEntries(config, target, opts) {
 	const { kind, path, source, member: facet } = splitRef(target);
+	const offered = (holder, memberPath) => opts?.retired !== false || !holder.retired(kind, memberPath);
 	/**
 	* Whose members these are.
 	*
@@ -128,7 +139,7 @@ function expandMemberEntries(config, target) {
 	if (!owner) return [];
 	/** The value side stays addressable from here, so a member's path keeps its qualifier. */
 	const qualify = (memberPath) => source === void 0 ? memberPath : `${memberPath}@${source}`;
-	if (facet === void 0 && path === "") return owner.list(kind).map((item) => ({
+	if (facet === void 0 && path === "") return owner.list(kind, opts).map((item) => ({
 		leaf: item.path,
 		path: qualify(item.path)
 	}));
@@ -148,23 +159,26 @@ function expandMemberEntries(config, target) {
 			path: value
 		}));
 	}
-	if (owner.resolve(kind, path)) return [{
-		leaf: path.slice(path.lastIndexOf("/") + 1),
-		path: qualify(path)
-	}];
+	if (owner.resolve(kind, path)) {
+		if (!offered(owner, path)) return [];
+		return [{
+			leaf: path.slice(path.lastIndexOf("/") + 1),
+			path: qualify(path)
+		}];
+	}
 	const leafOf = (memberPath) => memberPath.startsWith(`${path}/`) ? memberPath.slice(path.length + 1) : memberPath;
 	const theirs = owner.members(kind, path);
-	if (source === void 0) return theirs.map((member) => ({
+	if (source === void 0) return theirs.filter((member) => offered(owner, member.path)).map((member) => ({
 		leaf: leafOf(member.path),
 		path: member.path
 	}));
 	const ours = config.members(kind, path);
 	const held = new Set(ours.map((member) => member.path));
 	const covered = new Set(theirs.map((member) => member.path));
-	return [...theirs.map((member) => ({
+	return [...theirs.filter((member) => offered(held.has(member.path) ? config : owner, member.path)).map((member) => ({
 		leaf: leafOf(member.path),
 		path: held.has(member.path) ? member.path : qualify(member.path)
-	})), ...ours.filter((member) => !covered.has(member.path)).map((member) => ({
+	})), ...ours.filter((member) => !covered.has(member.path) && offered(config, member.path)).map((member) => ({
 		leaf: leafOf(member.path),
 		path: member.path
 	}))];
@@ -179,8 +193,8 @@ function groupMetaOf(config, kind, path) {
 *  signature that took it apart made every call site split one by hand, and the three that did
 *  disagreed about whether the `@source` survived the trip — which decides which config the members
 *  come from. */
-function memberLeaves(config, target) {
-	return memberEntries(config, target).map((entry) => entry.leaf);
+function memberLeaves(config, target, opts) {
+	return memberEntries(config, target, opts).map((entry) => entry.leaf);
 }
 /** Resolve a group-bound leaf back to its qualified path (`display2` → `textVariant/display2`).
 *  `undefined` when the leaf isn't a member — what validation rejects. */
@@ -193,28 +207,37 @@ function refListOf(domain) {
 	if (!Array.isArray(domain) || domain.length === 0 || !domain.every(isRef)) return;
 	return domain.map((entry) => entry.__ref);
 }
-function stylePropEntries(config, path) {
+/**
+* Every value a style prop accepts, as `{ leaf, value }` pairs. Total by default: the stylesheet
+* emits a utility per entry, and a value already bound to a retired token keeps resolving through
+* it. `{ retired: false }` is what a surface offers for a new value — a picker, a catalogue, the
+* emitted value union — and leaves out a token that is hidden or deprecated, itself or through a
+* folder above it.
+*/
+function stylePropEntries(config, path, opts) {
 	const cache = domainCache(stylePropEntryCache, config);
-	const hit = cache.get(path);
+	const key = domainKey(path, opts);
+	const hit = cache.get(key);
 	if (hit) return hit;
-	const expanded = expandStylePropEntries(config, path);
-	cache.set(path, expanded);
+	const expanded = expandStylePropEntries(config, path, opts);
+	cache.set(key, expanded);
 	return expanded;
 }
-function expandStylePropEntries(config, path) {
+function expandStylePropEntries(config, path, opts) {
 	const prop = config.resolve("style-property", path);
 	if (!prop) return [];
 	const values = prop.toJSON().values ?? [];
-	const members = (target) => memberEntries(config, target);
+	const members = (target) => memberEntries(config, target, opts);
 	return values.flatMap((entry) => leavesOfStylePropValue(entry, members));
 }
 /**
 * A style prop's leaf value domain — what a consumer/model actually authors (`warning`, `carbon/2`),
 * not the qualified storage path (`color/warning`). This is what the catalog, `uds_get_component`,
-* `uds_validate_props`, and the UI picker should offer, so the model emits `color="warning"`.
+* `uds_validate_props`, and the UI picker should offer, so the model emits `color="warning"`; an
+* offer reads it with `{ retired: false }`, as {@link stylePropEntries} describes.
 */
-function stylePropValueLeaves(config, path) {
-	return stylePropEntries(config, path).map((entry) => entry.leaf);
+function stylePropValueLeaves(config, path, opts) {
+	return stylePropEntries(config, path, opts).map((entry) => entry.leaf);
 }
 /**
 * Resolve a style-prop leaf value back to its qualified token path (or literal) — the inverse of
@@ -1171,7 +1194,7 @@ function previewMatrix(config, path) {
 	for (const { when } of previewConditions(config, path)) for (const [prop, stored] of Object.entries(when ?? {})) nameAxisPoint(prop, stored);
 	for (const [name, decl] of Object.entries(declared)) {
 		if (decl?.type === "composite" && isRef(decl.value)) {
-			const values = declaredFirst([...memberLeaves(config, decl.value)], props[name] ?? []);
+			const values = declaredFirst([...memberLeaves(config, decl.value, { retired: false })], props[name] ?? []);
 			if (values.length > 0) props[name] = values;
 		}
 		if (decl?.type === "boolean" && props[name]) props[name] = declaredFirst(["false", "true"], props[name] ?? []);