@yahoo/uds-create-config 4.6.0 → 4.8.0

package/dist/spec/index.js

@@ -1,8 +1,8 @@
-import { graftPreviewElements, hasPreviewElementDeep, isPreviewElement, previewElementNodes, previewElementType } from "./preview-elements.js";
+import { graftPreviewElements, graftSlotContent, hasPreviewElementDeep, isComponentRef, isPreviewElement, isPreviewRef, previewElementNodes, previewElementType } from "./preview-elements.js";
 import { assetJsxForm, jsxIdentifier, parseAssetType } from "./asset-jsx.js";
-import { buildAcceptsChildNodes, buildClassifyChildNodes, namedSlotTargets, stripInjectedSlots, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots } from "./empty-node-slots.js";
 import { applyForcedModifiers, collectForcedModifierProps } from "./apply-forced-modifiers.js";
 import { collapseWrappedTextLabels } from "./collapse-text-labels.js";
+import { buildAcceptsChildNodes, buildClassifyChildNodes, stripInjectedSlots, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots } from "./empty-node-slots.js";
 import { UNRESOLVED, hasUnresolvedProps, jsxToSpec, stripUnresolvedProps } from "./jsxToSpec.js";
 import { documentRenamesFromPatches, rewriteSpecRefs } from "./rewrite-refs.js";
 import { specToJsx } from "./specToJsx.js";
@@ -25,4 +25,4 @@ import { specToJsx } from "./specToJsx.js";
 *  element, without changing the rendered layer hierarchy. */
 const SYNTHETIC_TEXT_SLOT_PROP = "data-uds-synthetic-text-slot";
 //#endregion
-export { SYNTHETIC_TEXT_SLOT_PROP, UNRESOLVED, applyForcedModifiers, assetJsxForm, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, documentRenamesFromPatches, graftPreviewElements, hasPreviewElementDeep, hasUnresolvedProps, isPreviewElement, jsxIdentifier, jsxToSpec, namedSlotTargets, parseAssetType, previewElementNodes, previewElementType, rewriteSpecRefs, specToJsx, stripInjectedSlots, stripUnresolvedProps, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };
+export { SYNTHETIC_TEXT_SLOT_PROP, UNRESOLVED, applyForcedModifiers, assetJsxForm, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, documentRenamesFromPatches, graftPreviewElements, graftSlotContent, hasPreviewElementDeep, hasUnresolvedProps, isComponentRef, isPreviewElement, isPreviewRef, jsxIdentifier, jsxToSpec, parseAssetType, previewElementNodes, previewElementType, rewriteSpecRefs, specToJsx, stripInjectedSlots, stripUnresolvedProps, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };

package/dist/spec/instance.d.ts

@@ -0,0 +1,77 @@
+import { Config } from "../framework/Config.js";
+import { Slot } from "./slot.js";
+
+//#region src/spec/instance.d.ts
+/** A spec element as a design file stores it: what this module reads of one. */
+interface InstanceSpecElement {
+  readonly type?: string;
+  readonly children?: readonly string[];
+  readonly slots?: Readonly<Record<string, readonly string[]>>;
+}
+/** The elements of a spec a design file holds, keyed as the spec keys them. */
+interface InstanceSpec {
+  readonly elements: Readonly<Record<string, InstanceSpecElement | undefined>>;
+}
+/** One slot of a placed instance: the slot as the component declares it, and what this instance holds in it. */
+interface InstanceSlot {
+  readonly slot: Slot;
+  /** The keys of the elements placed in the slot, in order; empty when nothing is. */
+  readonly content: readonly string[];
+  readonly filled: boolean;
+}
+/**
+ * A component placed as one element of a design file's spec: which component it is, and what the
+ * file put in each of its slots. The component's slots come from the config (`Component.slots`),
+ * so a slot's hosting layer, what it takes and whether it is `children` are the component's answer;
+ * the content is this element's `children` for the content slot and its `slots` entry for a named
+ * one. `Component.instance` is the door.
+ */
+declare class Instance {
+  private readonly config;
+  private readonly element;
+  /** The element's key in the spec. */
+  readonly key: string;
+  /** The component the element places, as a path. */
+  readonly component: string;
+  constructor(config: Config, key: string, component: string, element: InstanceSpecElement);
+  /** Every slot the component places content in, with what this instance holds there. */
+  get slots(): readonly InstanceSlot[];
+  /** The slot a prop names, or `undefined` when the prop is no slot. */
+  slot(prop: string): InstanceSlot | undefined;
+  /** The slot whose content lands in `layer`, or `undefined` when the layer hosts none. */
+  slotHostedBy(layer: string): InstanceSlot | undefined;
+  /** The slot holding the element `childKey`, or `undefined` when it holds none of this instance's. */
+  slotHolding(childKey: string): InstanceSlot | undefined;
+}
+/**
+ * The instance an element of a design file's spec places, or `undefined` when the element names no
+ * component of this config.
+ */
+declare function instanceAt({
+  config,
+  spec,
+  elementKey
+}: {
+  config: Config;
+  spec: InstanceSpec | null | undefined;
+  elementKey: string;
+}): Instance | undefined;
+/**
+ * The instance and slot holding the element `childKey`, or `undefined` when no instance in the spec
+ * holds it in a slot. A container's children are its children, not a slot's content: a component
+ * that takes children on its root lists no `children` slot, so its children resolve to nothing here.
+ */
+declare function instanceHolding({
+  config,
+  spec,
+  childKey
+}: {
+  config: Config;
+  spec: InstanceSpec | null | undefined;
+  childKey: string;
+}): {
+  instance: Instance;
+  slot: InstanceSlot;
+} | undefined;
+//#endregion
+export { Instance, InstanceSlot, InstanceSpec, instanceAt, instanceHolding };

package/dist/spec/instance.js

@@ -0,0 +1,80 @@
+import { listSlots } from "./slot.js";
+import { Component } from "../entities/system/Component.js";
+//#region src/spec/instance.ts
+/**
+* A component placed as one element of a design file's spec: which component it is, and what the
+* file put in each of its slots. The component's slots come from the config (`Component.slots`),
+* so a slot's hosting layer, what it takes and whether it is `children` are the component's answer;
+* the content is this element's `children` for the content slot and its `slots` entry for a named
+* one. `Component.instance` is the door.
+*/
+var Instance = class {
+	/** The element's key in the spec. */
+	key;
+	/** The component the element places, as a path. */
+	component;
+	constructor(config, key, component, element) {
+		this.config = config;
+		this.element = element;
+		this.key = key;
+		this.component = component;
+	}
+	/** Every slot the component places content in, with what this instance holds there. */
+	get slots() {
+		return listSlots({
+			config: this.config,
+			path: this.component
+		}).map((slot) => {
+			const content = slot.isChildren ? this.element.children ?? [] : this.element.slots?.[slot.from] ?? [];
+			return {
+				slot,
+				content,
+				filled: content.length > 0
+			};
+		});
+	}
+	/** The slot a prop names, or `undefined` when the prop is no slot. */
+	slot(prop) {
+		return this.slots.find((entry) => entry.slot.from === prop);
+	}
+	/** The slot whose content lands in `layer`, or `undefined` when the layer hosts none. */
+	slotHostedBy(layer) {
+		return this.slots.find((entry) => entry.slot.layer === layer);
+	}
+	/** The slot holding the element `childKey`, or `undefined` when it holds none of this instance's. */
+	slotHolding(childKey) {
+		return this.slots.find((entry) => entry.content.includes(childKey));
+	}
+};
+/**
+* The instance an element of a design file's spec places, or `undefined` when the element names no
+* component of this config.
+*/
+function instanceAt({ config, spec, elementKey }) {
+	const element = spec?.elements[elementKey];
+	const component = element?.type ? Component.get(config, element.type) : void 0;
+	if (!element || !component) return void 0;
+	return new Instance(config, elementKey, component.path, element);
+}
+/**
+* The instance and slot holding the element `childKey`, or `undefined` when no instance in the spec
+* holds it in a slot. A container's children are its children, not a slot's content: a component
+* that takes children on its root lists no `children` slot, so its children resolve to nothing here.
+*/
+function instanceHolding({ config, spec, childKey }) {
+	if (!spec) return void 0;
+	for (const key of Object.keys(spec.elements)) {
+		const instance = instanceAt({
+			config,
+			spec,
+			elementKey: key
+		});
+		const slot = instance?.slotHolding(childKey);
+		if (instance && slot) return {
+			instance,
+			slot
+		};
+	}
+}
+//#endregion
+export { instanceAt, instanceHolding };

package/dist/spec/preview-content.d.ts

@@ -0,0 +1,95 @@
+import { Config } from "../framework/Config.js";
+import { RenderElement } from "../framework/render-spec.js";
+import { IndexedPreviewCondition, holdingPreviewConditions } from "../framework/projections.js";
+import { PreviewElement } from "./preview-elements.js";
+
+//#region src/spec/preview-content.d.ts
+/** Where a slot prop's value for a cell is stored: the last holding conditional `preview` entry,
+ *  else the `*` entry, else `defaultProps`, the order `previewDefaults` merges them in. */
+type PreviewValueSource = {
+  readonly kind: 'preview'; /** The entry's key, which a `sub-update` on `preview` addresses; `*` for the unconditional one. */
+  readonly key: string;
+  readonly prop: string;
+} | {
+  readonly kind: 'defaultProps';
+  readonly prop: string;
+};
+/**
+ * The stored field the value a cell shows for `prop` comes from, or `undefined` when the component
+ * stores none. A default the prop's declaration carries is not stored preview content.
+ */
+declare function previewValueSource({
+  config,
+  path,
+  cell,
+  prop
+}: {
+  config: Config;
+  path: string;
+  cell: Readonly<Record<string, unknown>>;
+  prop: string;
+}): PreviewValueSource | undefined;
+/** The `preview` entry whose condition is exactly this coordinate, or `undefined` when the
+ *  component stores none there. */
+declare function previewConditionAt({
+  config,
+  path,
+  cell
+}: {
+  config: Config;
+  path: string;
+  cell: Readonly<Record<string, unknown>>;
+}): IndexedPreviewCondition | undefined;
+/** Whether a cell's coordinate is the component's defaults, so its preview is every tile's. A forced
+ *  modifier is a state the defaults never show, so a cell with one is not the defaults. */
+declare function cellAtDefaults({
+  config,
+  path,
+  cell,
+  modifiers
+}: {
+  config: Config;
+  path: string;
+  cell: Readonly<Record<string, unknown>>;
+  modifiers?: readonly string[];
+}): boolean;
+/** Where a grafted preview element sits inside the stored preview content. */
+interface PreviewContentAddress {
+  /** The slot prop whose preview content the element is part of. */
+  readonly prop: string;
+  /** Which element of the prop's value, when the value is a list. */
+  readonly index: number;
+  /** Steps from that element down: a number is a child, a string an element-valued prop. */
+  readonly path: readonly (string | number)[];
+}
+/**
+ * The address a grafted element's key spells, or `null` for a key that is not preview content.
+ * A trailing bare `_` is a collision suffix and names no step.
+ *
+ * OPEN: a prop name holding `_` reads as two steps.
+ */
+declare function parsePreviewContentKey(anatomyKey: string): PreviewContentAddress | null;
+/** A rendered spec's elements, narrowed to what a preview element is read back from. */
+type SpecElementsForPreview = Readonly<Record<string, Partial<Pick<RenderElement, 'type' | 'props' | 'children' | 'slots'>> | undefined>>;
+/**
+ * A spec subtree read back as the preview element that would produce it: the inverse of
+ * `previewElementNodes`. A string `children` prop is the element's text, `children` keys are its
+ * children, a slot filled by one element is that element handed as a prop, and a slot filled by
+ * several is the list of them.
+ */
+declare function previewElementFromSpec({
+  elements,
+  key,
+  config
+}: {
+  elements: SpecElementsForPreview;
+  key: string;
+  /** Given, a type spelled as a marker (`component:Badge`) is stored as the ref it names, so the
+   *  element joins the dependency graph; a marker the config resolves nothing for stays a type. */
+  config?: Config;
+}): PreviewElement | null;
+/** A slot prop's stored content as the list it is: a bare element is one element, a list is itself,
+ *  and anything else holds no elements. */
+declare function previewContentList(value: unknown): PreviewElement[];
+//#endregion
+export { type IndexedPreviewCondition, PreviewContentAddress, PreviewValueSource, SpecElementsForPreview, cellAtDefaults, holdingPreviewConditions, parsePreviewContentKey, previewConditionAt, previewContentList, previewElementFromSpec, previewValueSource };

package/dist/spec/preview-content.js

@@ -0,0 +1,149 @@
+import { ref, refLeaf, splitRef } from "../framework/utils/refs.js";
+import { unconditionalPreviewProps } from "../framework/preview-store.js";
+import { holdingPreviewConditions, keyedPreviewConditions } from "../framework/projections.js";
+import { isPreviewElement } from "./preview-elements.js";
+//#region src/spec/preview-content.ts
+/** The `defaultProps` a component stores and the props of its `*` preview entry, empty for a path
+*  naming none. */
+function storedDefaults(config, path) {
+	const body = config.resolve("component", path)?.body;
+	return {
+		defaultProps: body?.defaultProps,
+		previewProps: unconditionalPreviewProps(body)
+	};
+}
+/**
+* The stored field the value a cell shows for `prop` comes from, or `undefined` when the component
+* stores none. A default the prop's declaration carries is not stored preview content.
+*/
+function previewValueSource({ config, path, cell, prop }) {
+	const holding = holdingPreviewConditions({
+		config,
+		path,
+		cell
+	});
+	for (let i = holding.length - 1; i >= 0; i--) {
+		const { key, condition } = holding[i];
+		if (prop in condition.props) return {
+			kind: "preview",
+			key,
+			prop
+		};
+	}
+	const { defaultProps, previewProps } = storedDefaults(config, path);
+	if (previewProps?.[prop] !== void 0) return {
+		kind: "preview",
+		key: "*",
+		prop
+	};
+	if (defaultProps?.[prop] !== void 0) return {
+		kind: "defaultProps",
+		prop
+	};
+}
+/** Whether two condition values name the same value, a ref or its leaf. */
+function sameLeaf(a, b) {
+	return String(refLeaf(a)) === String(refLeaf(b));
+}
+/** The `preview` entry whose condition is exactly this coordinate, or `undefined` when the
+*  component stores none there. */
+function previewConditionAt({ config, path, cell }) {
+	const props = Object.keys(cell);
+	const found = Object.entries(keyedPreviewConditions(config, path)).find(([, { when }]) => when !== null && Object.keys(when).length === props.length && props.every((prop) => prop in when && sameLeaf(when[prop], cell[prop])));
+	return found ? {
+		key: found[0],
+		condition: found[1]
+	} : void 0;
+}
+const NO_MODIFIERS = [];
+/** Whether a cell's coordinate is the component's defaults, so its preview is every tile's. A forced
+*  modifier is a state the defaults never show, so a cell with one is not the defaults. */
+function cellAtDefaults({ config, path, cell, modifiers = NO_MODIFIERS }) {
+	const { defaultProps = {} } = storedDefaults(config, path);
+	return modifiers.length === 0 && Object.entries(cell).every(([prop, value]) => sameLeaf(defaultProps[prop], value));
+}
+/**
+* The address a grafted element's key spells, or `null` for a key that is not preview content.
+* A trailing bare `_` is a collision suffix and names no step.
+*
+* OPEN: a prop name holding `_` reads as two steps.
+*/
+function parsePreviewContentKey(anatomyKey) {
+	const parts = anatomyKey.split("__");
+	if (parts.length !== 3) return null;
+	const [owner, prop, rest] = parts;
+	if (!owner || !prop || !rest) return null;
+	const [head, ...steps] = rest.split("_");
+	if (!/^\d+$/.test(head)) return null;
+	return {
+		prop,
+		index: Number(head),
+		path: steps.filter((step) => step.length > 0).map((step) => /^\d+$/.test(step) ? Number(step) : step)
+	};
+}
+/** Props a projection stamps on an element to say what it is, never part of its content. */
+const IDENTITY_PROPS = new Set([
+	"data-uds-layer",
+	"data-uds-anatomy",
+	"data-uds-component",
+	"data-uds-slot-anatomy",
+	"data-uds-slot-prop",
+	"data-element-key",
+	"data-element-parent",
+	"data-element-type"
+]);
+/**
+* A spec subtree read back as the preview element that would produce it: the inverse of
+* `previewElementNodes`. A string `children` prop is the element's text, `children` keys are its
+* children, a slot filled by one element is that element handed as a prop, and a slot filled by
+* several is the list of them.
+*/
+function previewElementFromSpec({ elements, key, config }) {
+	const el = elements[key];
+	if (!el?.type) return null;
+	const props = {};
+	let text;
+	for (const [name, value] of Object.entries(el.props ?? {})) {
+		if (IDENTITY_PROPS.has(name) || name.startsWith("data-uds-")) continue;
+		if (name === "children" && typeof value === "string") {
+			text = value;
+			continue;
+		}
+		if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") props[name] = value;
+	}
+	for (const [into, keys] of Object.entries(el.slots ?? {})) {
+		const held = keys.map((fill) => previewElementFromSpec({
+			elements,
+			key: fill,
+			config
+		})).filter((fill) => fill !== null);
+		if (held.length === 1) props[into] = held[0];
+		else if (held.length > 1) props[into] = held;
+	}
+	const children = (el.children ?? []).map((child) => previewElementFromSpec({
+		elements,
+		key: child,
+		config
+	})).filter((child) => child !== null);
+	return {
+		element: config ? elementRefOf(config, el.type) : el.type,
+		...Object.keys(props).length > 0 ? { props } : {},
+		...children.length > 0 ? { children } : {},
+		...text !== void 0 ? { text } : {}
+	};
+}
+/** A type spelled as a marker the config resolves, as the ref it names; anything else as it was. */
+function elementRefOf(config, type) {
+	const { kind, qualifiedPath } = splitRef(type);
+	if (!kind || kind === type) return type;
+	return config.entityOf(kind) ? ref(kind, qualifiedPath) : type;
+}
+/** A slot prop's stored content as the list it is: a bare element is one element, a list is itself,
+*  and anything else holds no elements. */
+function previewContentList(value) {
+	if (isPreviewElement(value)) return [value];
+	if (Array.isArray(value)) return value.filter(isPreviewElement);
+	return [];
+}
+//#endregion
+export { cellAtDefaults, holdingPreviewConditions, parsePreviewContentKey, previewConditionAt, previewContentList, previewElementFromSpec, previewValueSource };

package/dist/spec/preview-elements.d.ts

@@ -1,26 +1,41 @@
 //#region src/spec/preview-elements.d.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.
- */
 interface PreviewElement {
   readonly element: string | {
     readonly __ref: string;
   };
-  readonly props?: Record<string, string | number | boolean>;
+  /** Literals, an element handed as a prop (`<IconButton icon={<PlusIcon />} />`) or a list of them,
+   *  which fill the slot the prop names the way the root's own element-valued props do, or a
+   *  component handed as a prop (`icon={PlusIcon}`), which stays a prop as a ref. */
+  readonly props?: Record<string, string | number | boolean | PreviewElement | PreviewElement[] | PreviewRef>;
   readonly children?: PreviewElement[];
   readonly text?: string;
 }
-type PreviewValue = string | number | boolean | PreviewElement | PreviewValue[] | {
+/**
+ * A component handed as a prop value rather than rendered: `icon={DotsThreeIcon}` names the glyph
+ * and lets the receiving component draw it. It is the `element` half of a {@link PreviewElement} on
+ * its own, spelled as the same ref the registry keys the component under (`icon:phosphor/StarIcon`,
+ * `component:studio/IconButton`, `package:@ariakit/react#Menu`), and a reviver hands the component
+ * back, not a node.
+ */
+interface PreviewRef {
+  readonly __ref: string;
+}
+type PreviewValue = string | number | boolean | PreviewElement | PreviewRef | PreviewValue[] | {
   readonly [key: string]: PreviewValue;
 };
 /** Whether a stored value names an element to render. */
 declare function isPreviewElement(value: unknown): value is PreviewElement;
+/** Whether a stored value is a bare `{ __ref }` and nothing else, whatever kind it names. */
+declare function isPreviewRef(value: unknown): value is PreviewRef;
+/**
+ * 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.
+ */
+declare function isComponentRef(value: unknown): value is PreviewRef;
 /**
- * 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.
  */
 declare function hasPreviewElementDeep(value: unknown): boolean;
 /** The json-render `type` a stored element names. */
@@ -31,6 +46,8 @@ interface PreviewSpecNode {
   readonly props?: Record<string, unknown>;
   /** Child element keys, never literal content. */
   readonly children?: string[];
+  /** Element keys filling a slot prop, under that prop's name — json-render traverses these. */
+  readonly slots?: Record<string, string[]>;
 }
 /** Flatten one stored preview element into json-render's keyed element map. */
 declare function previewElementNodes(root: PreviewElement, rootKey: string, taken?: ReadonlySet<string>): {
@@ -48,11 +65,33 @@ type GraftableElement = {
   slots?: Record<string, string[]>;
 };
 /**
- * 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.
+ */
+declare function graftSlotContent<S extends GraftableSpec>({
+  spec,
+  hostKey,
+  prop,
+  into,
+  elements: content
+}: {
+  spec: S; /** The element whose `slots` names the fills. */
+  hostKey: string; /** The slot prop the content arrives as, which the grafted keys carry. */
+  prop: string; /** The host element's prop the fills land under. */
+  into: string;
+  elements: readonly PreviewElement[];
+}): S;
+/**
+ * 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
@@ -60,4 +99,4 @@ type GraftableElement = {
  */
 declare function graftPreviewElements<S extends GraftableSpec>(spec: S, values: Record<string, unknown>): S;
 //#endregion
-export { GraftableElement, GraftableSpec, PreviewElement, PreviewSpecNode, PreviewValue, graftPreviewElements, hasPreviewElementDeep, isPreviewElement, previewElementNodes, previewElementType };
+export { GraftableElement, GraftableSpec, PreviewElement, PreviewRef, PreviewSpecNode, PreviewValue, graftPreviewElements, graftSlotContent, hasPreviewElementDeep, isComponentRef, isPreviewElement, isPreviewRef, previewElementNodes, previewElementType };