@yahoo/uds-create-config 4.5.2 → 4.7.0

package/dist/framework/prop-surface.js

@@ -1,4 +1,4 @@
-import { isRef, kindOf, memberOf, pathOf } from "./utils/refs.js";
+import { isRef, kindOf, memberOf, pathOf, refLeaf } from "./utils/refs.js";
 import { forwardsOf, rootLayerOf } from "../entities/system/element.js";
 import { propValueDomain, resolveComponentProps } from "./projections.js";
 import { Component } from "../entities/system/Component.js";
@@ -19,6 +19,34 @@ import { Component } from "../entities/system/Component.js";
 * its domain (an icon prop drawing its names from the icon library rather than copying them in),
 * which is why value lists are never read straight off `value`.
 */
+/** A stored condition as leaves, one list per prop it names; `undefined` for none. */
+function conditionLeaves(when) {
+	if (when === null || typeof when !== "object" || Array.isArray(when)) return;
+	const entries = Object.entries(when).filter(([, value]) => value !== void 0 && value !== null).map(([name, value]) => [name, (Array.isArray(value) ? value : [value]).map(refLeaf)]);
+	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+}
+/** The projected prop under ITS OWN condition. A forward resolved through carries the far prop's
+*  condition, which speaks of that component's siblings and means nothing here. */
+function conditioned(prop, when) {
+	const { when: _far, ...own } = prop;
+	return when ? {
+		...own,
+		when
+	} : own;
+}
+/**
+* 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.
+*/
+function propApplies(prop, values) {
+	if (!prop.when) return true;
+	return Object.entries(prop.when).every(([name, leaves]) => {
+		const value = values[name];
+		if (value === void 0 || value === null) return false;
+		return leaves.some((leaf) => String(leaf) === String(value));
+	});
+}
 /** The tail of a ref, when the value is one. */
 function refPath(value) {
 	return isRef(value) ? pathOf(value.__ref) : void 0;
@@ -82,25 +110,62 @@ function routedProp(config, componentPath, decl) {
 	return routedPropIn(config, body?.layers, decl);
 }
 function routesContent(config, layers, decl) {
-	const routed = routedPropIn(config, layers, decl);
-	if (routed) return routed.type === "slot";
-	return refPath(decl.target) !== void 0 && intoName(decl.into) === "children";
+	const end = routeEnd(config, layers, decl);
+	if (!end) return false;
+	if (end.decl) return end.decl.type === "slot";
+	return refPath(end.route.target) !== void 0 && intoName(end.route.into) === "children";
+}
+/**
+* Whether a route is typed in place once every forward between is followed: it lands on a text slot,
+* or the last forward it follows says `text` itself. A message's `badge` routes into `Badge.children`,
+* which forwards onto Badge's text layer, so the route is text although neither end of the first hop
+* says so. The declaration the route starts from is the caller's to read.
+*/
+function routesIntoText(config, layers, decl) {
+	const end = routeEnd(config, layers, decl);
+	if (!end) return false;
+	if (end.decl?.type === "slot" && end.decl.text === true) return true;
+	return end.route.text === true;
+}
+/**
+* Where a route ends once every forward between is followed. A message's `badge` routes into
+* `Badge.children`, which is itself a forward onto Badge's text layer; the route ends where that one
+* does. `decl` is the declaration it lands on, absent for a layer that renders a tag or a prop nobody
+* declares, and `route` is the last forward followed, whose `into` names what it asked that layer
+* for. `undefined` for a route that comes back around to itself.
+*/
+function routeEnd(config, layers, decl, seen = /* @__PURE__ */ new Set()) {
+	const landed = routedPropIn(config, layers, decl);
+	if (landed?.type !== "forward") return {
+		decl: landed,
+		route: decl
+	};
+	const layerKey = refPath(decl.target);
+	const target = layerKey ? refPath(layers?.[layerKey]) : void 0;
+	if (!target) return {
+		decl: landed,
+		route: decl
+	};
+	const key = `${target}#${intoName(decl.into)}`;
+	if (seen.has(key)) return void 0;
+	const farLayers = (Component.get(config, target)?.toJSON())?.layers;
+	return routeEnd(config, farLayers, landed, new Set([...seen, key]));
 }
 function slotProp(config, componentPath, name, decl) {
 	const refs = acceptsRefs(decl.accepts);
 	const icons = refs.find((ref) => kindOf(ref) === "icon");
-	const routed = routedProp(config, componentPath, decl);
+	const layers = (Component.get(config, componentPath)?.toJSON())?.layers;
+	const routed = routeEnd(config, layers, decl)?.decl;
 	const routedKind = routed?.type;
 	const targetLayer = refPath(decl.target);
-	const routesIntoText = routed?.type === "slot" && routed.text === true;
 	return {
 		name,
 		kind: "slot",
 		required: decl.required === true,
-		text: decl.text === true || routesIntoText,
+		text: decl.text === true || routesIntoText(config, layers, decl),
 		...targetLayer ? {
 			targetLayer,
-			into: decl.into ?? "children"
+			into: intoName(decl.into)
 		} : {},
 		accepts: refs.filter((ref) => kindOf(ref) === "component").map((ref) => pathOf(ref)),
 		...icons ? { acceptsIconLibrary: pathOf(icons) } : {},
@@ -121,61 +186,62 @@ function surfaceProps(config, componentPath, seen = /* @__PURE__ */ new Set()) {
 	const props = [];
 	for (const [name, decl] of Object.entries(declared)) {
 		const required = decl.required === true;
+		const when = conditionLeaves(decl.when);
 		if (decl.type === "forward") {
 			if (routesContent(config, layers, decl)) {
-				props.push(slotProp(config, componentPath, name, decl));
+				props.push(conditioned(slotProp(config, componentPath, name, decl), when));
 				continue;
 			}
 			const routed = boundProp(config, layers, decl, seen);
-			if (routed) props.push({
+			if (routed) props.push(conditioned({
 				...routed,
 				name,
 				required
-			});
+			}, when));
 			continue;
 		}
 		if (decl.type === "slot") {
-			props.push(slotProp(config, componentPath, name, decl));
+			props.push(conditioned(slotProp(config, componentPath, name, decl), when));
 			continue;
 		}
 		if (decl.type === "variant") {
 			const iconLibrary = variantIconLibrary(config, decl.value);
-			props.push({
+			props.push(conditioned({
 				name,
 				kind: "variant",
 				required,
 				values: propValueDomain(config, decl)?.leaves ?? [],
 				...iconLibrary !== void 0 ? { iconLibrary } : {}
-			});
+			}, when));
 			continue;
 		}
 		if (decl.type === "styleProperty") {
 			const styleProperty = refPath(decl.value);
 			if (!styleProperty) continue;
-			props.push({
+			props.push(conditioned({
 				name,
 				kind: "styleProperty",
 				required,
 				styleProperty
-			});
+			}, when));
 			continue;
 		}
 		if (decl.type === "composite") {
 			const compositeName = refPath(decl.value);
 			if (!compositeName) continue;
-			props.push({
+			props.push(conditioned({
 				name,
 				kind: "composite",
 				required,
 				compositeName
-			});
+			}, when));
 			continue;
 		}
-		if (decl.type === "string" || decl.type === "number" || decl.type === "boolean" || decl.type === "motion") props.push({
+		if (decl.type === "string" || decl.type === "number" || decl.type === "boolean" || decl.type === "motion") props.push(conditioned({
 			name,
 			kind: decl.type,
 			required
-		});
+		}, when));
 	}
 	return props;
 }
@@ -198,6 +264,18 @@ function surfaceProp(config, componentPath, name) {
 	return surfaceProps(config, componentPath).find((prop) => prop.name === name);
 }
 /**
+* 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.
+*/
+function propRegistryRef(config, componentPath, name) {
+	const surfaced = surfaceProp(config, componentPath, name);
+	if (surfaced?.kind === "composite") return surfaced.compositeName;
+	if (surfaced?.kind === "styleProperty") return surfaced.styleProperty;
+	const decl = resolveComponentProps(config, componentPath)[name];
+	return decl?.type === "variant" ? refPath(decl.value) : void 0;
+}
+/**
 * The one precedence walk behind {@link forwardedLayers} and {@link forwardClaims}: every name a
 * `forwards` entry exposes, attributed to the layer that delivers it.
 *
@@ -275,4 +353,4 @@ function forwardClaims(config, componentPath) {
 	};
 }
 //#endregion
-export { forwardClaims, forwardedLayers, intoName, routedProp, routedPropIn, routesContent, surfaceProp, surfaceProps };
+export { forwardClaims, forwardedLayers, intoName, propApplies, propRegistryRef, routedProp, routedPropIn, routesContent, routesIntoText, surfaceProp, surfaceProps };

package/dist/framework/render-spec.d.ts

@@ -204,6 +204,54 @@ type VisibilityOperator = Exclude<keyof StateCondition, '$state' | 'not'>;
 declare function readStatePointer(state: Record<string, unknown>, pointer: string): unknown;
 /** The prop a `$state` pointer reads — its first segment, for a pointer into an object prop. */
 declare function statePointerProp(pointer: string): string;
+/**
+ * The marker on an element a render placed inline, naming its anatomy node. A layer is addressed by
+ * `data-uds-layer`; this is for the node between layers that has no bag of its own. Stamped by the
+ * emitted module and by both projections, so a rendered element and a projected one read alike.
+ */
+declare const ANATOMY_MARKER = "data-uds-anatomy";
+/**
+ * The value prop a component paints as a layer's text: the anatomy node rendering `layer` binds its
+ * `children` to `{ $state: '/<prop>' }`, and that prop is declared a string or number. A forward
+ * surfaces its layer on the prop itself; this answers for a render that reads a value prop and
+ * writes it into a layer by hand, the way a `title` string reaches a heading.
+ */
+declare function layerTextProp({
+  config,
+  path,
+  layer
+}: {
+  config: Config;
+  path: string;
+  layer: string;
+}): string | undefined;
+/**
+ * The value prop a component hands an element it placed inline: the anatomy node `element` binds
+ * `into` to `{ $state: '/<prop>' }`, and that prop is a string or number. `into` is `children` for
+ * text the element shows itself, or the far component's prop the render passed it to
+ * (`<CommentHeader title={title} />` binds `title`).
+ */
+declare function anatomyTextProp({
+  config,
+  path,
+  element,
+  into
+}: {
+  config: Config;
+  path: string;
+  element: string;
+  into: string;
+}): string | undefined;
+/** The component an inline anatomy element renders, when it is one (`component:<path>`). */
+declare function anatomyElementComponent({
+  config,
+  path,
+  element
+}: {
+  config: Config;
+  path: string;
+  element: string;
+}): string | undefined;
 /** A value in json-render's `visible` grammar, resolved against a prop bag. `undefined` when this
  *  reader can't settle it, which leaves the condition on the element for the renderer to judge. */
 declare function resolveVisibility(condition: unknown, state: Record<string, unknown>): boolean | undefined;
@@ -301,10 +349,62 @@ interface SlotTarget {
  * the layer meant to hold it renders empty. Every one of Studio's own components shaped that way
  * (`Badge`, `StudioButton`, `Toggle`, …) painted as an empty shell in the component editor.
  *
- * Exported so the answer has ONE owner. An untargeted slot still resolves to the root here — that is
- * `slotTargets`' rule, not a caller's assumption, and it is the same rule the expansion renders by.
+ * Exported so the answer has ONE owner. An untargeted slot is hosted by the layer the anatomy
+ * places its content-position node in — a row's `leading` slot sits in its `leading` Box — and by the
+ * root when the anatomy records no position for it, which is where the expansion renders it.
  */
 declare function slotTargetsOf(config: Config, path: string): SlotTarget[];
+/**
+ * Layer → the forwards that hand a VALUE to one of its props.
+ *
+ * `startIcon: { type: 'forward', target: 'startIcon/name' }` and `swatch: { type: 'forward', target:
+ * 'swatch/swatchColor' }` are this shape: the instance's value lands on the layer's element as the
+ * prop the forward names, the way the emitted module spreads it into that layer's bundle. A forward
+ * whose target prop is a slot is content instead, and {@link slotTargetsOf} answers for it.
+ */
+declare function valueForwardsOf(config: Config, path: string): SlotTarget[];
+/**
+ * The instance props whose values or content reach `layer`: content routed into it, values
+ * forwarded onto one of its props, and the props the layer exposes through `forwards`. A file
+ * editing a placed instance can change exactly these about the layer; the layer's own styles are
+ * the component's.
+ */
+/**
+ * The instance prop whose content or value lands on `into` of `layer`, or `undefined` when the
+ * layer owns that prop itself. A change to the layer's prop in a cell is then a change to the
+ * instance prop's preview value, not a style.
+ */
+declare function propInto({
+  config,
+  path,
+  layer,
+  into
+}: {
+  config: Config;
+  path: string;
+  layer: string;
+  into: string;
+}): string | undefined;
+/** The route a prop's content or value takes into a layer, or `undefined` for a prop that reaches
+ *  no layer. */
+declare function routeOf({
+  config,
+  path,
+  prop
+}: {
+  config: Config;
+  path: string;
+  prop: string;
+}): SlotTarget | undefined;
+declare function propsIntoLayer({
+  config,
+  path,
+  layer
+}: {
+  config: Config;
+  path: string;
+  layer: string;
+}): string[];
 /**
  * Expand every component element the renderer can't name into the tree it is made of.
  *
@@ -323,4 +423,4 @@ declare function expandSpec(config: Config, spec: RenderSpec, options?: ExpandOp
  */
 declare function expandComponent(config: Config, path: string, props?: Record<string, unknown>, options?: ExpandOptions): ExpansionResult;
 //#endregion
-export { ComponentSpec, ComponentSpecs, ExpandOptions, ExpansionResult, RenderElement, RenderSpec, SlotTarget, VisibilityOperator, VisibilityTerm, boundElementType, componentSpec, deriveSpec, entryKeyOf, expandComponent, expandSpec, instanceSpec, liveStateProps, previewSpec, readStatePointer, resolveVisibility, slotTargetsOf, specWithResolvedVisibility, statePointerProp, visibilityStateProps, visibilityTerms, withoutTruthyTerm, wrappedElementKey };
+export { ANATOMY_MARKER, ComponentSpec, ComponentSpecs, ExpandOptions, ExpansionResult, RenderElement, RenderSpec, SlotTarget, VisibilityOperator, VisibilityTerm, anatomyElementComponent, anatomyTextProp, boundElementType, componentSpec, deriveSpec, entryKeyOf, expandComponent, expandSpec, instanceSpec, layerTextProp, liveStateProps, previewSpec, propInto, propsIntoLayer, readStatePointer, resolveVisibility, routeOf, slotTargetsOf, specWithResolvedVisibility, statePointerProp, valueForwardsOf, visibilityStateProps, visibilityTerms, withoutTruthyTerm, wrappedElementKey };