@yahoo/uds-create-config 4.5.2 → 4.7.0

package/dist/spec/preview-elements.js

@@ -1,18 +1,46 @@
+import { kindOf } from "../framework/utils/refs.js";
 //#region src/spec/preview-elements.ts
+/**
+* A preview element is the JSON-safe form of JSX stored in a component's preview props.
+*
+* It is authoring data, not a React element and not yet a json-render node. The helpers in this file
+* own the conversion into the UDS spec dialect so every render host receives the same shape.
+*/
 /** Whether a stored value names an element to render. */
 function isPreviewElement(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const { element } = value;
 	return typeof element === "string" || typeof element === "object" && element !== null && typeof element.__ref === "string";
 }
+/** Whether a stored value is a bare `{ __ref }` and nothing else, whatever kind it names. */
+function isPreviewRef(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const keys = Object.keys(value);
+	return keys.length === 1 && keys[0] === "__ref" && typeof value.__ref === "string";
+}
+/** The ref kinds a registry keys a renderer under. */
+const RENDERABLE_KINDS = new Set([
+	"component",
+	"icon",
+	"package",
+	"file"
+]);
+/**
+* Whether a stored value names a component to hand over. A `token:` or `value:` ref is data a prop
+* carries and has the same bare shape, so the kind is what tells them apart.
+*/
+function isComponentRef(value) {
+	return isPreviewRef(value) && RENDERABLE_KINDS.has(kindOf(value.__ref));
+}
 /**
-* Whether anything under a value is a stored preview element. Stops at live React elements: walking
-* through their owner Fiber reaches a circular structure.
+* Whether anything under a value is a stored preview element or component ref, so a reviver knows
+* the bag needs work. Stops at live React elements: walking through their owner Fiber reaches a
+* circular structure.
 */
 function hasPreviewElementDeep(value) {
 	if (typeof value !== "object" || value === null) return false;
 	if ("$$typeof" in value) return false;
-	if (isPreviewElement(value)) return true;
+	if (isPreviewElement(value) || isComponentRef(value)) return true;
 	return (Array.isArray(value) ? value : Object.values(value)).some(hasPreviewElementDeep);
 }
 /** The json-render `type` a stored element names. */
@@ -28,13 +56,19 @@ function previewElementNodes(root, rootKey, taken = /* @__PURE__ */ new Set()) {
 		while (used.has(key)) key = `${key}_`;
 		used.add(key);
 		const children = (node.children ?? []).map((child, index) => add(child, `${key}_${index}`));
+		const props = {};
+		const slots = {};
+		for (const [prop, value] of Object.entries(node.props ?? {})) if (isPreviewElement(value)) slots[prop] = [add(value, `${key}_${prop}`)];
+		else if (Array.isArray(value) && value.every(isPreviewElement)) slots[prop] = value.map((held, index) => add(held, `${key}_${prop}_${index}`));
+		else props[prop] = value;
 		elements[key] = {
 			type: previewElementType(node.element),
 			props: {
-				...node.props ?? {},
+				...props,
 				...node.text !== void 0 ? { children: node.text } : {}
 			},
-			...children.length > 0 ? { children } : {}
+			...children.length > 0 ? { children } : {},
+			...Object.keys(slots).length > 0 ? { slots } : {}
 		};
 		return key;
 	};
@@ -48,11 +82,52 @@ function isElementValue(value) {
 	return isPreviewElement(value) || Array.isArray(value) && value.some(isPreviewElement);
 }
 /**
-* Lower direct element-valued props into json-render's native slot form.
+* Graft a slot's content under its host: the elements join the spec's keyed element map as
+* `<host>__<prop>__<index>` subtrees, and the host's `slots[into]` names their roots — json-render
+* traverses `slots` itself, so the keys join neither `props` nor `children`. What an earlier graft
+* of the same slot put there goes first, so the same keys are minted again for the content this
+* pass holds and nothing stale is left for the next key to collide with. The spec comes back
+* unchanged, by reference, when the grafted content is already what is there.
 *
-* The element subtrees join the spec's keyed element map, and the root's `slots` record names their
-* keys under the prop that carried them — json-render traverses `slots` itself, so the keys join
-* neither `props` nor `children`. Plain values—including text in `props.children`—remain props.
+* Every host that grafts slot content goes through here: the tile projection, the matrix cell and
+* the cell panel, so their keys agree and the layers rail and the drop hit-test read one scheme.
+*/
+function graftSlotContent({ spec, hostKey, prop, into, elements: content }) {
+	const host = spec.elements[hostKey];
+	if (!host) return spec;
+	const prefix = `${hostKey}__${prop}__`;
+	const kept = Object.fromEntries(Object.entries(spec.elements).filter(([key]) => !key.startsWith(prefix)));
+	const grafted = {};
+	const used = new Set(Object.keys(kept));
+	const roots = content.map((node, index) => {
+		const built = previewElementNodes(node, `${prefix}${index}`, used);
+		for (const [key, element] of Object.entries(built.elements)) {
+			grafted[key] = element;
+			used.add(key);
+		}
+		return built.root;
+	});
+	const current = host.slots?.[into];
+	if (current !== void 0 && current.length === roots.length && roots.every((root, index) => current[index] === root) && Object.keys(spec.elements).filter((key) => key.startsWith(prefix)).length === Object.keys(grafted).length && Object.entries(grafted).every(([key, element]) => JSON.stringify(spec.elements[key]) === JSON.stringify(element))) return spec;
+	return {
+		...spec,
+		elements: {
+			...kept,
+			...grafted,
+			[hostKey]: {
+				...host,
+				slots: {
+					...host.slots,
+					[into]: roots
+				}
+			}
+		}
+	};
+}
+/**
+* Lower the root's direct element-valued props into json-render's native slot form, one
+* {@link graftSlotContent} per prop, under the prop's own name. Plain values — including text in
+* `props.children` — remain props.
 *
 * Elements nested inside arbitrary structured data are deliberately left for runtime marker
 * revival. A `slots` entry identifies a component prop, not a path inside an opaque application
@@ -61,29 +136,34 @@ function isElementValue(value) {
 function graftPreviewElements(spec, values) {
 	const entries = Object.entries(values).filter(([, value]) => isElementValue(value));
 	if (entries.length === 0) return spec;
-	const next = structuredClone(spec);
-	const elements = next.elements;
-	const rootKey = next.root;
-	const rootElement = elements[rootKey];
-	if (!rootElement) return spec;
-	const used = new Set(Object.keys(elements));
-	const rootProps = { ...rootElement.props ?? {} };
-	const rootSlots = { ...rootElement.slots ?? {} };
+	const rootKey = spec.root;
+	if (!spec.elements[rootKey]) return spec;
+	let next = spec;
 	for (const [prop, value] of entries) {
-		const keys = (Array.isArray(value) ? value.filter(isPreviewElement) : [value]).map((node, index) => {
-			const graft = previewElementNodes(node, `${rootKey}__${prop}__${index}`, used);
-			for (const [key, element] of Object.entries(graft.elements)) {
-				elements[key] = element;
-				used.add(key);
-			}
-			return graft.root;
+		const content = Array.isArray(value) ? value.filter(isPreviewElement) : [value];
+		next = graftSlotContent({
+			spec: next,
+			hostKey: rootKey,
+			prop,
+			into: prop,
+			elements: content
 		});
-		delete rootProps[prop];
-		rootSlots[prop] = keys;
+		const root = next.elements[rootKey];
+		if (root?.props && prop in root.props) {
+			const { [prop]: _lowered, ...rest } = root.props;
+			next = {
+				...next,
+				elements: {
+					...next.elements,
+					[rootKey]: {
+						...root,
+						props: rest
+					}
+				}
+			};
+		}
 	}
-	rootElement.props = rootProps;
-	rootElement.slots = rootSlots;
 	return next;
 }
 //#endregion
-export { graftPreviewElements, hasPreviewElementDeep, isPreviewElement, previewElementNodes, previewElementType };
+export { graftPreviewElements, graftSlotContent, hasPreviewElementDeep, isComponentRef, isPreviewElement, isPreviewRef, previewElementNodes, previewElementType };

package/dist/spec/prop-conditions.d.ts

@@ -0,0 +1,28 @@
+import { Config } from "../framework/Config.js";
+
+//#region src/spec/prop-conditions.d.ts
+/** A sibling a prop's condition may name, with the values the condition may hold it at. A boolean
+ *  offers `true`/`false` as the strings a form works in; a number offers no list, since any number
+ *  is a value. */
+interface ConditionableProp {
+  readonly name: string;
+  readonly kind: 'variant' | 'boolean' | 'number';
+  readonly values: readonly string[];
+}
+/**
+ * The siblings a condition on one of a component's props may name: its own declared props that are
+ * a closed axis or a scalar the condition schema coerces. A name exposed only through `forwards` is
+ * not one, since `when` is validated against the component's own declarations. `except` leaves out
+ * the prop being conditioned.
+ */
+declare function conditionableProps({
+  config,
+  path,
+  except
+}: {
+  config: Config;
+  path: string;
+  except?: string;
+}): ConditionableProp[];
+//#endregion
+export { ConditionableProp, conditionableProps };

package/dist/spec/prop-conditions.js

@@ -0,0 +1,39 @@
+import { surfaceProps } from "../framework/prop-surface.js";
+import { Component } from "../entities/system/Component.js";
+//#region src/spec/prop-conditions.ts
+/**
+* What a prop's `when` may name, for the form that authors one.
+*/
+const BOOLEAN_CONDITION_VALUES = ["true", "false"];
+/**
+* The siblings a condition on one of a component's props may name: its own declared props that are
+* a closed axis or a scalar the condition schema coerces. A name exposed only through `forwards` is
+* not one, since `when` is validated against the component's own declarations. `except` leaves out
+* the prop being conditioned.
+*/
+function conditionableProps({ config, path, except }) {
+	const own = Component.get(config, path)?.props ?? {};
+	const out = [];
+	for (const prop of surfaceProps(config, path)) {
+		if (prop.name === except) continue;
+		if (own[prop.name] === null || own[prop.name] === void 0) continue;
+		if (prop.kind === "variant") out.push({
+			name: prop.name,
+			kind: "variant",
+			values: prop.values
+		});
+		else if (prop.kind === "boolean") out.push({
+			name: prop.name,
+			kind: "boolean",
+			values: BOOLEAN_CONDITION_VALUES
+		});
+		else if (prop.kind === "number") out.push({
+			name: prop.name,
+			kind: "number",
+			values: []
+		});
+	}
+	return out;
+}
+//#endregion
+export { conditionableProps };

package/dist/spec/slot.d.ts

@@ -0,0 +1,206 @@
+import { ConfigEdit } from "../framework/config-op.js";
+import { Ref } from "../framework/utils/refs.js";
+import { Config } from "../framework/Config.js";
+import { SlotTarget } from "../framework/render-spec.js";
+import { PreviewElement } from "./preview-elements.js";
+import { PreviewContentAddress, PreviewValueSource } from "./preview-content.js";
+
+//#region src/spec/slot.d.ts
+/** A cell's coordinate: the axis values it pins. Empty for the component's own row. */
+type SlotCell = Readonly<Record<string, unknown>>;
+/** What one slot is, apart from the config it is read over. */
+interface SlotFacts extends SlotTarget {
+  readonly accepts: readonly string[];
+}
+declare class Slot implements SlotTarget {
+  private readonly config;
+  /** The component that declares the slot. */
+  readonly component: string;
+  /** The prop the content arrives as on the instance (`children`, `startIcon`). */
+  readonly from: string;
+  /** The layer that holds the content. */
+  readonly layer: string;
+  /** The prop the content lands under on the layer's element. */
+  readonly into: string;
+  /** The refs the slot accepts (`component:X`, `icon:phosphor`); empty when unconstrained. */
+  readonly accepts: readonly string[];
+  /** Built by {@link listSlots}; a surface reaches one through `Component.slots` or `Component.slot`. */
+  constructor(config: Config, component: string, facts: SlotFacts);
+  /** Whether this is the component's `children`, positioned inside one of its layers. */
+  get isChildren(): boolean;
+  /**
+   * Whether the slot takes an element: anything when it accepts nothing in particular, else an
+   * element whose ref one of the accepted refs names, exactly or as a member of a group the ref
+   * names (`icon:phosphor` takes `icon:phosphor/StarIcon`). A `@source` marker on either side is
+   * not part of the name. `element` is a spec type, a bare component path, or the ref a preview
+   * element stores.
+   */
+  takes(element: string | Ref): boolean;
+  /** The stored field a cell reads the slot's content from, or `undefined` when nothing is stored. */
+  source(cell: SlotCell): PreviewValueSource | undefined;
+  /** The elements a cell shows in the slot, in order. */
+  content(cell: SlotCell): PreviewElement[];
+  /**
+   * Append `element` to the content under `cell`: the entry keyed on exactly that coordinate, `*`
+   * for none, created where none spells it yet and seeded with the list the coordinate shows, so the
+   * cells it covers gain the element and every other cell keeps what it had.
+   */
+  append({
+    cell,
+    element
+  }: {
+    cell: SlotCell;
+    element: PreviewElement;
+  }): ConfigEdit[];
+  /**
+   * The content shown under `cell` with `element` placed at `address`: at `index` of the list when
+   * the path is empty, past the end appending; otherwise inside the element at `index`, where a
+   * number step is the position among that element's children and a string step the element-valued
+   * prop it becomes. `undefined` when the address names another slot or a path that reaches nothing.
+   * What a surface paints while a drop is still being decided, and what {@link insertAt} writes.
+   */
+  placed({
+    cell,
+    address,
+    element
+  }: {
+    cell: SlotCell;
+    address: PreviewContentAddress;
+    element: PreviewElement;
+  }): PreviewElement[] | undefined;
+  /**
+   * The element at `from` moved to `to`, both in this slot's content under `cell`, on the entry the
+   * cell reads the content from. `to` names a position in the content with the moved element
+   * already taken out, the way a drop between the remaining elements resolves it. Empty when either
+   * address names nothing, or `to` reaches inside the moved element.
+   */
+  moveAt({
+    cell,
+    from,
+    to
+  }: {
+    cell: SlotCell;
+    from: PreviewContentAddress;
+    to: PreviewContentAddress;
+  }): ConfigEdit[];
+  /** The element at `address` in the content shown under `cell`, or `undefined` when it names nothing. */
+  elementAt({
+    cell,
+    address
+  }: {
+    cell: SlotCell;
+    address: PreviewContentAddress;
+  }): PreviewElement | undefined;
+  /**
+   * A copy of the element at `address`, placed right after it: the next index of the list, or the
+   * next position among its parent's children. Written on the entry the cell reads the content
+   * from, like {@link replaceAt}, so a copy made in a conditional cell of `*` content is every
+   * cell's. An element held as a prop has no "after", so it is not duplicated. Empty when the
+   * address names nothing.
+   */
+  duplicateAt({
+    cell,
+    address
+  }: {
+    cell: SlotCell;
+    address: PreviewContentAddress;
+  }): ConfigEdit[];
+  /** Write the content {@link placed} gives, onto the cell's own entry the way `append` writes.
+   *  Empty when nothing is placed. */
+  insertAt({
+    cell,
+    address,
+    element
+  }: {
+    cell: SlotCell;
+    address: PreviewContentAddress;
+    element: PreviewElement;
+  }): ConfigEdit[];
+  /**
+   * Swap the element at `address` for `element`, on the entry the cell reads the content from —
+   * `*` included, so a `*` value shown in a conditional cell changes for every cell rather than
+   * being copied into a new keyed entry. Empty when the address names nothing.
+   */
+  replaceAt({
+    cell,
+    address,
+    element
+  }: {
+    cell: SlotCell;
+    address: PreviewContentAddress;
+    element: PreviewElement;
+  }): ConfigEdit[];
+  /**
+   * Take the element at `address` out, on the entry the cell reads the content from. A list emptied
+   * this way clears the prop, and an entry left with no props goes with it. Empty when the address
+   * names nothing.
+   */
+  removeAt({
+    cell,
+    address
+  }: {
+    cell: SlotCell;
+    address: PreviewContentAddress;
+  }): ConfigEdit[];
+  /**
+   * Store `elements` as the whole content under `cell`: one `sub-update` on the `preview` entry
+   * keyed on the coordinate, `*` for none, created where none spells it and joined where one does.
+   * What a picker that shows the whole list writes; the verbs above build on it.
+   */
+  set({
+    cell,
+    elements
+  }: {
+    cell: SlotCell;
+    elements: readonly PreviewElement[];
+  }): ConfigEdit[];
+  private stored;
+  /** `replaceAt` and `removeAt`: one element rewritten or dropped, written back where it was read. */
+  private rewrite;
+  /** The edits that store `content` on `source`: the field the content came from, cleared when the
+   *  list is empty, and the entry it leaves with nothing else going with it. */
+  private writeSource;
+}
+/**
+ * Every slot of a component that content can be placed in: its named node slots, and its `children`
+ * when a layer of several positions them. A text slot is typed in place rather than filled, so it is
+ * not one; nor is `children` landing on the root, which is the open hole every container has. The
+ * same array comes back for the same config.
+ */
+declare function listSlots({
+  config,
+  path
+}: {
+  config: Config;
+  path: string;
+}): readonly Slot[];
+/** The named node slots alone: what a design node's render injects an empty placeholder for. */
+declare function namedSlots({
+  config,
+  path
+}: {
+  config: Config;
+  path: string;
+}): readonly Slot[];
+/** The slot a prop names, or `undefined` when the prop is not a slot content is placed in. */
+declare function slotOf({
+  config,
+  path,
+  slot
+}: {
+  config: Config;
+  path: string;
+  slot: string;
+}): Slot | undefined;
+/** The slot whose content lands in `layer`, or `undefined` when the layer hosts none. */
+declare function slotHostedBy({
+  config,
+  path,
+  layer
+}: {
+  config: Config;
+  path: string;
+  layer: string;
+}): Slot | undefined;
+//#endregion
+export { Slot, SlotCell, listSlots, namedSlots, slotHostedBy, slotOf };