@yahoo/uds-create-config 4.5.2 → 4.7.0

package/dist/framework/class-names.js

@@ -1,7 +1,8 @@
-import { isRef, kindOf, pathOf, refLeaf } from "./utils/refs.js";
-import { rootLayerOf } from "../entities/system/element.js";
+import { isRef, kindOf, memberOf, pathOf, refLeaf } from "./utils/refs.js";
+import { forwardsOf, rootLayerOf } from "../entities/system/element.js";
 import { classPrefixOf } from "../entities/system/Settings.js";
 import { createSliceMemo } from "./memo.js";
+import { storedPreview } from "./preview-store.js";
 import { authoredValue, className, negatedCssValue, renderStyleValue, resolveComponentProps, stylePropLeafForToken, stylePropValueLeaves, stylePropertyPathFor } from "./projections.js";
 import { ruleApplies } from "./layer-styles.js";
 //#region src/framework/class-names.ts
@@ -295,38 +296,74 @@ function componentMotionClasses(config, path) {
 function componentPropClasses(config, path, state = {}) {
 	const declared = compositePropsOf(config, path);
 	if (!declared) return {};
-	const { root, groups, defaultProps } = declared;
+	const { groups, defaultProps } = declared;
 	if (groups.length === 0) return {};
 	const resolved = {
 		...defaultProps,
 		...state
 	};
-	const classes = [];
-	for (const [prop, group] of groups) {
+	const out = {};
+	for (const [prop, group, layer] of groups) {
 		const value = resolved[prop];
 		const target = memberNamed(group, value);
 		if (target === void 0) continue;
 		if (!config.resolve("composite", target)) continue;
+		const classes = out[layer] ?? [];
 		classes.push(className(config, "composite", target));
+		out[layer] = classes;
 	}
-	return classes.length > 0 ? { [root]: classes } : {};
+	return out;
 }
 /** The part of {@link componentPropClasses} that depends on the component alone, once per slice:
 *  an expansion asks it for every instance it paints. `undefined` for a path no component answers. */
-function compositePropsOf(config, path) {
+function compositePropsOf(config, path, seen = /* @__PURE__ */ new Set()) {
 	const cache = compositePropsCache(config);
 	if (cache.has(path)) return cache.get(path);
 	const component = config.resolve("component", path);
 	let declared;
 	if (component) {
-		const { layers = {}, props = {}, defaultProps = {} } = component.toJSON();
+		const body = component.toJSON();
+		const { layers = {}, props = {} } = body;
 		const [root] = rootLayerOf(layers);
 		const groups = [];
+		let defaultProps = {};
 		for (const [prop, decl] of Object.entries(props)) {
 			if (decl?.type !== "composite") continue;
 			const group = isRef(decl.value) ? decl.value.__ref : void 0;
-			if (group) groups.push([prop, group]);
+			if (group) groups.push([
+				prop,
+				group,
+				root
+			]);
 		}
+		const inner = new Set([...seen, path]);
+		for (const [layer, entry] of Object.entries(forwardsOf(body))) {
+			const element = layers[layer];
+			if (!isRef(element) || kindOf(element.__ref) !== "component") continue;
+			const from = pathOf(element.__ref);
+			if (inner.has(from)) continue;
+			const exposed = compositePropsOf(config, from, inner);
+			if (!exposed) continue;
+			const names = Array.isArray(entry) ? new Set(entry.flatMap((r) => isRef(r) ? [memberOf(r.__ref)?.split("/").pop()] : [])) : void 0;
+			for (const [prop, group, at] of exposed.groups) {
+				if (at !== exposed.root) continue;
+				if (prop in props) continue;
+				if (entry !== "*" && !names?.has(prop)) continue;
+				groups.push([
+					prop,
+					group,
+					layer
+				]);
+			}
+			defaultProps = {
+				...exposed.defaultProps,
+				...defaultProps
+			};
+		}
+		defaultProps = {
+			...defaultProps,
+			...body.defaultProps
+		};
 		declared = {
 			root,
 			groups,
@@ -349,8 +386,10 @@ const compositePropsCache = createSliceMemo({
 * travels to it as one, whether or not the element declares it: a composite (`variant` on a
 * `Text`-backed layer, which the receiver resolves to its own class), the receiver's own variant or
 * scalar prop (`size: 'sm'` on an Icon layer), or an attribute of a plain element (`as: 'div'`,
-* `type: 'button'`, `aria-hidden`). A receiver prop with a channel of its own — a style property
-* under another name, a slot, a forward, motion — stays out, since that channel already carries it.
+* `type: 'button'`, `aria-hidden`), or a value the rule hands a receiver's forward or slot
+* (`children: 'AI'` on a badge layer, `icon: 'XIcon'` on a button layer), which the emitted module
+* routes the same way. A style property under another name and motion stay out, since the
+* stylesheet and the motion classes already carry them.
 *
 * Forwarding rather than resolving is what makes a layer's styling live-editable at all: a class only
 * exists once a build has emitted the stylesheet, so an edit that makes a NEW style rule paints
@@ -377,7 +416,7 @@ function layerRoutedProps(config, path, state = {}) {
 			}) ?? prop;
 			if (config.resolve("style-property", styleKey)) continue;
 			const decl = declared[prop];
-			if (decl?.type === "styleProperty" || decl?.type === "slot" || decl?.type === "forward" || decl?.type === "motion") continue;
+			if (decl?.type === "styleProperty" || decl?.type === "motion") continue;
 			out[layer] ??= {};
 			out[layer][prop] = authoredValue(config, prop, value);
 		}
@@ -598,7 +637,7 @@ function modifierUtilitiesUsed(config) {
 /**
 * Every style bag a COMPONENT states it wants, each with the definitions its keys resolve against.
 *
-* Not uniform, which is the whole reason it travels with the bag. `defaultProps` and `previewProps`
+* Not uniform, which is the whole reason it travels with the bag. `defaultProps` and a preview entry's `props`
 * are the component's OWN props, and nothing else has a claim. A style rule's per-layer bag and an
 * anatomy node's props are set on a LAYER'S ELEMENT, so that element answers too — after the
 * component itself, whose own declaration of a name is what that name means throughout its
@@ -606,14 +645,14 @@ function modifierUtilitiesUsed(config) {
 */
 function componentBags(entity) {
 	const { path } = entity;
-	const { defaultProps, previewProps, styles, anatomy, layers } = entity.toJSON();
+	const { defaultProps, styles, anatomy, layers } = entity.toJSON();
 	const bags = [{
 		bag: defaultProps,
 		through: [path]
-	}, {
-		bag: previewProps,
+	}, ...Object.values(storedPreview(entity.toJSON())).map((entry) => ({
+		bag: entry?.props,
 		through: [path]
-	}];
+	}))];
 	for (const rule of Object.values(styles ?? {})) for (const [layer, bag] of Object.entries(rule?.layers ?? {})) bags.push({
 		bag,
 		through: [path, componentElementOf(layers?.[layer])]

package/dist/framework/defineDerivedEntity.d.ts

@@ -2,8 +2,8 @@ import { Entity } from "./Entity.js";
 import { Ref } from "./utils/refs.js";
 import { TraverseOptions } from "./ref-graph.js";
 import { FieldsSchema } from "./utils/field-schema.js";
-import { Config } from "./Config.js";
 import { ComputedInput, EntityKind } from "./registry.js";
+import { Config } from "./Config.js";
 import { z } from "zod";
 
 //#region src/framework/defineDerivedEntity.d.ts

package/dist/framework/defineEntity.d.ts

@@ -4,11 +4,11 @@ import { TraverseOptions } from "./ref-graph.js";
 import { CreateInput, FieldsSchema } from "./utils/field-schema.js";
 import { FieldsCtx, UserSchemas } from "./schemas.js";
 import { SubEntityClass } from "./defineSubEntity.js";
-import { PathOf } from "./registered.js";
 import { BulkOverlayWrite, BulkQuery, SourceOverlay, SourceResolutionSchemas } from "./sources.js";
+import { ComputedFields, EntityKind, Linkable } from "./registry.js";
+import { PathOf } from "./registered.js";
 import { GroupBody } from "./utils/group.js";
 import { Config, ListOptions, TreeNode } from "./Config.js";
-import { ComputedFields, EntityKind, Linkable } from "./registry.js";
 import { z } from "zod";
 
 //#region src/framework/defineEntity.d.ts

package/dist/framework/defineSubEntity.d.ts

@@ -71,7 +71,8 @@ type SubEntityClass<F extends z.ZodTypeAny = z.ZodTypeAny> = CollectionSchema<F>
   readonly subEntities?: Readonly<Record<string, SubEntityClass>>;
   /**
    * Fields of the OWNING ENTITY that hold this member's NAME as a VALUE, keyed by the member's
-   * owner — a component's `defaultProps` and `previewProps` are both `{ [prop]: value }`.
+   * owner — a component's `defaultProps` and each `preview` entry's `props` are `{ [prop]: value }`.
+   * A field is a `/` path; `*` stands for every key at that level.
    *
    * The mirror of {@link namesMembersOf}, which covers a name held as a record KEY. Neither is
    * reachable by a ref rewrite, and both leave the same kind of wreckage: a default naming a
@@ -81,7 +82,7 @@ type SubEntityClass<F extends z.ZodTypeAny = z.ZodTypeAny> = CollectionSchema<F>
   readonly namedValuesIn?: readonly string[];
   /**
    * Fields of the OWNING ENTITY that are KEYED by this member's name — a component's
-   * `defaultProps` and `previewProps` are both `{ [prop]: value }`, so the prop's name is the key
+   * `defaultProps` and each `preview` entry's `props` are `{ [prop]: value }`, so the prop's name is the key
    * rather than the value.
    *
    * The other half of {@link namedValuesIn}, which covers the same two fields from the value side

package/dist/framework/preview-store.d.ts

@@ -0,0 +1,19 @@
+//#region src/framework/preview-store.d.ts
+/**
+ * A component's stored `preview` collection, read off a body with nothing else in scope: the render
+ * spec builder and the class scanner read it without reaching the projections module.
+ */
+/** One `preview` entry as stored: the condition it holds under, `null` for the `*` entry every
+ *  cell reads, and the props the matching cells preview with. */
+interface StoredPreviewCondition {
+  readonly when: Record<string, unknown> | null;
+  readonly props: Record<string, unknown>;
+}
+/** The `*` entry the `preview` collection stores — see `preview({ defaultProps })`. */
+declare const UNCONDITIONAL_PREVIEW_KEY = "*";
+/** Every `preview` entry a body stores, keyed as stored. Empty for a body that stores none. */
+declare function storedPreview(body: unknown): Readonly<Record<string, StoredPreviewCondition>>;
+/** The props the `*` entry previews with, `undefined` when the body stores no such entry. */
+declare function unconditionalPreviewProps(body: unknown): Record<string, unknown> | undefined;
+//#endregion
+export { StoredPreviewCondition, UNCONDITIONAL_PREVIEW_KEY, storedPreview, unconditionalPreviewProps };

package/dist/framework/preview-store.js

@@ -0,0 +1,18 @@
+//#region src/framework/preview-store.ts
+/** The `*` entry the `preview` collection stores — see `preview({ defaultProps })`. */
+const UNCONDITIONAL_PREVIEW_KEY = "*";
+/** Every `preview` entry a body stores, keyed as stored. Empty for a body that stores none. */
+function storedPreview(body) {
+	const preview = body?.preview;
+	return preview && typeof preview === "object" && !Array.isArray(preview) ? preview : {};
+}
+/** The props the `*` entry previews with, `undefined` when the body stores no such entry. */
+function unconditionalPreviewProps(body) {
+	return storedPreview(body)["*"]?.props;
+}
+/** Whether an entry holds under a condition rather than for every cell. */
+function isConditionalPreview(entry) {
+	return entry.when !== null && Object.keys(entry.when).length > 0;
+}
+//#endregion
+export { UNCONDITIONAL_PREVIEW_KEY, isConditionalPreview, storedPreview, unconditionalPreviewProps };

package/dist/framework/projections.d.ts

@@ -2,6 +2,7 @@ import { Ref } from "./utils/refs.js";
 import { ItemOf } from "./defineEntity.js";
 import { Config } from "./Config.js";
 import { StylePropLeaf, StyleProperty } from "../entities/system/StyleProperty.js";
+import { StoredPreviewCondition, UNCONDITIONAL_PREVIEW_KEY, storedPreview, unconditionalPreviewProps } from "./preview-store.js";
 
 //#region src/framework/projections.d.ts
 /**
@@ -410,10 +411,10 @@ declare function propValueDomain(config: Config, decl: PropDeclaration): {
  *  `component/validate` op's truth is config-defined and the pipeline only renders it. */
 declare function validateComponentProps(config: Config, componentPath: string, props: Record<string, unknown>): string[];
 /**
- * The props one preview tile starts from: the component's `defaultProps` with its `previewProps`
+ * The props one preview tile starts from: the component's `defaultProps` with its `*` preview entry
  * over the top.
  *
- * Preview wins, and that direction is the whole reason this exists once. `previewProps` is the state
+ * Preview wins, and that direction is the whole reason this exists once. The `*` entry is the state
  * a person chose to show a component in — Button's `variant`, an Icon prop's example glyph — so a
  * surface showing that tile has to agree with it, while `defaultProps` remains the baseline for every
  * prop the tile doesn't pin. Get the order backwards and the panel reports a value the canvas isn't
@@ -421,7 +422,7 @@ declare function validateComponentProps(config: Config, componentPath: string, p
  *
  * THE PRECEDENCE RULE, stated once: only a RENDER surface — a preview tile, the catalogue card, slot
  * text seeding — reads this merge. An EDIT surface reads and writes the single field it owns
- * (`defaultProps` OR `previewProps`, never the merge), and anything that SEEDS committed data — a
+ * (`defaultProps` OR the `*` entry, never the merge), and anything that SEEDS committed data — a
  * prop binding, a forward's re-seed, a stored instance prop, a default-value form — reads raw
  * `defaultProps`. A preview value that reaches any of those stops being staging and becomes a real
  * default the moment it is saved, which is exactly the leak UDS-3514 closed. Before adding a caller,
@@ -451,16 +452,33 @@ cell?: Record<string, unknown>): Record<string, unknown>;
  * without restating defaults that would shadow an edit.
  */
 declare function previewConditionalProps(config: Config, path: string, cell: Record<string, unknown>): Record<string, unknown>;
-/** One preview condition as stored — see `defineComponent`'s `PreviewCondition`. */
-interface StoredPreviewCondition {
-  readonly when: Record<string, unknown>;
-  readonly props: Record<string, unknown>;
+/** One conditional `preview` entry with the key it is stored under, which is how a write addresses it. */
+interface IndexedPreviewCondition {
+  readonly key: string;
+  readonly condition: StoredPreviewCondition;
 }
+/**
+ * The conditional `preview` entries that hold for a cell, in stored order: every prop a condition names
+ * holds the value it asks for in the defaults under the cell's own values. The same test
+ * `ruleApplies` makes for a style rule, kept here because `layer-styles` imports this module.
+ */
+declare function holdingPreviewConditions({
+  config,
+  path,
+  cell
+}: {
+  config: Config;
+  path: string;
+  cell: Readonly<Record<string, unknown>>;
+}): IndexedPreviewCondition[];
 /**
  * A component's conditional preview props, in authored order. Empty for a component that declares
  * none, or a path that names no component.
  */
 declare function previewConditions(config: Config, path: string): readonly StoredPreviewCondition[];
+/** The conditional entries under the keys they are stored at, the `*` entry left out. Empty for a
+ *  component that declares none. */
+declare function keyedPreviewConditions(config: Config, path: string): Readonly<Record<string, StoredPreviewCondition>>;
 /** A preview grid, derived. Rows sweep a prop's declared values; columns are the states the
  *  Component actually styles for. */
 interface PreviewMatrix {
@@ -497,5 +515,7 @@ declare function previewMatrix(config: Config, path: string): PreviewMatrix;
  * stored as the string `'true'` and never equals the `true` an author writes.
  */
 declare function propValueFromAxis(config: Config, path: string, prop: string, value: string): unknown;
+/** The `value` a string, number or boolean prop declares as its default, per prop. */
+declare function declaredPropDefaults(props: Record<string, unknown> | undefined): Record<string, unknown>;
 //#endregion
-export { PreviewMatrix, PropDeclaration, StoredPreviewCondition, StylePropEntry, StylePropertyItem, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropRouting, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };
+export { IndexedPreviewCondition, PreviewMatrix, PropDeclaration, StylePropEntry, StylePropertyItem, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropDefaults, declaredPropRouting, holdingPreviewConditions, keyedPreviewConditions, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };

package/dist/framework/projections.js

@@ -7,6 +7,7 @@ import { modifierCategory } from "../entities/system/Modifier.js";
 import { classPrefixOf, varPrefixOf } from "../entities/system/Settings.js";
 import { StyleProperty, leavesOfStylePropValue } from "../entities/system/StyleProperty.js";
 import { createSliceMemo } from "./memo.js";
+import { isConditionalPreview, storedPreview, unconditionalPreviewProps } from "./preview-store.js";
 //#region src/framework/projections.ts
 /**
 * Expanded value domains, cached per config instance.
@@ -903,10 +904,10 @@ function validateComponentProps(config, componentPath, props) {
 	return errors;
 }
 /**
-* The props one preview tile starts from: the component's `defaultProps` with its `previewProps`
+* The props one preview tile starts from: the component's `defaultProps` with its `*` preview entry
 * over the top.
 *
-* Preview wins, and that direction is the whole reason this exists once. `previewProps` is the state
+* Preview wins, and that direction is the whole reason this exists once. The `*` entry is the state
 * a person chose to show a component in — Button's `variant`, an Icon prop's example glyph — so a
 * surface showing that tile has to agree with it, while `defaultProps` remains the baseline for every
 * prop the tile doesn't pin. Get the order backwards and the panel reports a value the canvas isn't
@@ -914,7 +915,7 @@ function validateComponentProps(config, componentPath, props) {
 *
 * THE PRECEDENCE RULE, stated once: only a RENDER surface — a preview tile, the catalogue card, slot
 * text seeding — reads this merge. An EDIT surface reads and writes the single field it owns
-* (`defaultProps` OR `previewProps`, never the merge), and anything that SEEDS committed data — a
+* (`defaultProps` OR the `*` entry, never the merge), and anything that SEEDS committed data — a
 * prop binding, a forward's re-seed, a stored instance prop, a default-value form — reads raw
 * `defaultProps`. A preview value that reaches any of those stops being staging and becomes a real
 * default the moment it is saved, which is exactly the leak UDS-3514 closed. Before adding a caller,
@@ -935,8 +936,10 @@ function validateComponentProps(config, componentPath, props) {
 function previewDefaults(config, path, cell) {
 	const component = config.resolve("component", path);
 	if (!component) return {};
-	const { defaultProps, previewProps } = component.body;
+	const { props, defaultProps } = component.body;
+	const previewProps = unconditionalPreviewProps(component.body);
 	const base = {
+		...declaredPropDefaults(props),
 		...defaultProps,
 		...previewProps
 	};
@@ -953,28 +956,48 @@ function previewDefaults(config, path, cell) {
 * without restating defaults that would shadow an edit.
 */
 function previewConditionalProps(config, path, cell) {
+	const conditional = {};
+	for (const { condition } of holdingPreviewConditions({
+		config,
+		path,
+		cell
+	})) Object.assign(conditional, condition.props);
+	return conditional;
+}
+/**
+* The conditional `preview` entries that hold for a cell, in stored order: every prop a condition names
+* holds the value it asks for in the defaults under the cell's own values. The same test
+* `ruleApplies` makes for a style rule, kept here because `layer-styles` imports this module.
+*/
+function holdingPreviewConditions({ config, path, cell }) {
 	const component = config.resolve("component", path);
-	if (!component) return {};
-	const { defaultProps, previewProps } = component.body;
+	if (!component) return [];
+	const { defaultProps } = component.body;
 	const state = {
 		...defaultProps,
-		...previewProps,
+		...unconditionalPreviewProps(component.body),
 		...cell
 	};
-	const holds = (when) => Object.entries(when).every(([prop, value]) => String(state[prop]) === String(refLeaf(value)));
-	const conditional = {};
-	for (const { when, props } of previewConditions(config, path)) if (holds(when)) Object.assign(conditional, props);
-	return conditional;
+	return Object.entries(keyedPreviewConditions(config, path)).flatMap(([key, condition]) => {
+		return Object.entries(condition.when ?? {}).every(([prop, value]) => String(state[prop]) === String(refLeaf(value))) ? [{
+			key,
+			condition
+		}] : [];
+	});
 }
 /**
 * A component's conditional preview props, in authored order. Empty for a component that declares
 * none, or a path that names no component.
 */
 function previewConditions(config, path) {
+	return Object.values(keyedPreviewConditions(config, path));
+}
+/** The conditional entries under the keys they are stored at, the `*` entry left out. Empty for a
+*  component that declares none. */
+function keyedPreviewConditions(config, path) {
 	const component = config.resolve("component", path);
-	if (!component) return [];
-	const { previewWhen } = component.body;
-	return Array.isArray(previewWhen) ? previewWhen : [];
+	if (!component) return {};
+	return Object.fromEntries(Object.entries(storedPreview(component.body)).filter(([, entry]) => isConditionalPreview(entry)));
 }
 /**
 * The preview grid a component implies.
@@ -1014,7 +1037,7 @@ function previewMatrix(config, path) {
 			if (modifierCategory(config, key.slice(1)) === "state") modifiers.add(key);
 		}
 	}
-	for (const { when } of previewConditions(config, path)) for (const [prop, stored] of Object.entries(when)) nameAxisPoint(prop, stored);
+	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] ?? []);
@@ -1052,5 +1075,16 @@ function propValueFromAxis(config, path, prop, value) {
 	}
 	return value;
 }
+/** The `value` a string, number or boolean prop declares as its default, per prop. */
+function declaredPropDefaults(props) {
+	const out = {};
+	for (const [name, decl] of Object.entries(props ?? {})) {
+		if (!decl || typeof decl !== "object") continue;
+		const { type, value } = decl;
+		if (type !== "string" && type !== "number" && type !== "boolean") continue;
+		if (value !== void 0) out[name] = value;
+	}
+	return out;
+}
 //#endregion
-export { authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropRouting, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };
+export { authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropDefaults, declaredPropRouting, holdingPreviewConditions, keyedPreviewConditions, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };

package/dist/framework/prop-surface.d.ts

@@ -3,9 +3,14 @@ import { Config } from "./Config.js";
 //#region src/framework/prop-surface.d.ts
 /** What a prop IS — the config's own prop types, and nothing invented. */
 type SurfacePropKind = 'variant' | 'styleProperty' | 'composite' | 'motion' | 'slot' | 'string' | 'number' | 'boolean';
+/** When a prop applies, as leaves: each key a sibling prop, each value the leaves it must hold one
+ *  of. What a control compares the values in force against — see {@link propApplies}. */
+type SurfacePropCondition = Readonly<Record<string, readonly unknown[]>>;
 interface SurfacePropBase {
   readonly name: string;
   readonly required: boolean;
+  /** Absent when the prop always applies. */
+  readonly when?: SurfacePropCondition;
 }
 interface SurfaceVariantProp extends SurfacePropBase {
   readonly kind: 'variant';
@@ -62,7 +67,16 @@ interface PropDecl extends Record<string, unknown> {
   into?: string;
   text?: boolean;
   accepts?: unknown;
+  when?: unknown;
 }
+/**
+ * Whether a prop applies under the values in force — every prop its condition names holds one of the
+ * leaves listed for it. A prop with no condition always applies; an unset prop satisfies nothing.
+ * Compared as strings, since a control hands back what it displays.
+ */
+declare function propApplies(prop: {
+  readonly when?: SurfacePropCondition;
+}, values: Readonly<Record<string, unknown>>): boolean;
 /**
  * The prop a slot routes INTO, resolved through the layer it targets: the layer's element is a
  * component, and `into` names one of that component's props. `undefined` when the slot targets
@@ -110,6 +124,12 @@ declare function surfaceProps(config: Config, componentPath: string, /** Forward
 seen?: ReadonlySet<string>): SurfaceProp[];
 /** One prop by name, or `undefined` when the component doesn't expose it. */
 declare function surfaceProp(config: Config, componentPath: string, name: string): SurfaceProp | undefined;
+/**
+ * The registry entity a prop writes through, as a path: its composite, its style property, or the
+ * ref a variant's values come from. Resolved through a route, so a prop forwarded into a layer's
+ * composite names that composite. `undefined` for a prop with none.
+ */
+declare function propRegistryRef(config: Config, componentPath: string, name: string): string | undefined;
 /**
  * Each non-root layer a component forwards to, and the sorted prop names each one receives — the
  * emitter's view, which writes a literal key set per layer. Root is absent on purpose: it takes
@@ -129,4 +149,4 @@ interface ForwardClaims {
 }
 declare function forwardClaims(config: Config, componentPath: string): ForwardClaims;
 //#endregion
-export { ForwardClaims, SurfaceCompositeProp, SurfaceProp, SurfacePropKind, SurfaceScalarProp, SurfaceSlotProp, SurfaceStylePropertyProp, SurfaceVariantProp, forwardClaims, forwardedLayers, intoName, routedProp, routedPropIn, routesContent, surfaceProp, surfaceProps };
+export { ForwardClaims, SurfaceCompositeProp, SurfaceProp, SurfacePropCondition, SurfacePropKind, SurfaceScalarProp, SurfaceSlotProp, SurfaceStylePropertyProp, SurfaceVariantProp, forwardClaims, forwardedLayers, intoName, propApplies, propRegistryRef, routedProp, routedPropIn, routesContent, surfaceProp, surfaceProps };