@yahoo/uds-create-config 4.6.0 → 4.7.0

package/dist/spec/cell.js

@@ -0,0 +1,361 @@
+import { canonicalCondition, refLeaf } from "../framework/utils/refs.js";
+import { holdingPreviewConditions, previewConditionalProps, previewDefaults } from "../framework/projections.js";
+import { propApplies, surfaceProps } from "../framework/prop-surface.js";
+import { ruleApplies } from "../framework/layer-styles.js";
+import { propsIntoLayer } from "../framework/render-spec.js";
+import { cellAtDefaults, parsePreviewContentKey, previewConditionAt, previewValueSource } from "./preview-content.js";
+import { listSlots, slotOf } from "./slot.js";
+//#region src/spec/cell.ts
+/** A stored condition with every ref read as its leaf. */
+function leaves(when) {
+	return Object.fromEntries(Object.entries(when).map(([prop, value]) => [prop, refLeaf(value)]));
+}
+const cellsByConfig = /* @__PURE__ */ new WeakMap();
+function coordinateKey(path, cell) {
+	return `${path}\u0000${Object.entries(cell).sort(([a], [b]) => a < b ? -1 : 1).map(([prop, value]) => `${prop}=${JSON.stringify(value)}`).join("&")}`;
+}
+const UNSET = Symbol("unset");
+/** Whether `a` governs ahead of `b`: more specific, then a preview entry over a style rule, then
+*  reaching the layer, then the later stored. */
+function outranks(a, b) {
+	const specificity = Object.keys(a.when).length - Object.keys(b.when).length;
+	if (specificity !== 0) return specificity > 0;
+	if (a.source !== b.source) return a.source === "preview";
+	if (a.reaches !== b.reaches) return a.reaches;
+	return a.order > b.order;
+}
+var Cell = class {
+	/** The component the cell shows. */
+	component;
+	/** The axis values the cell pins; empty for the component's own row. */
+	coordinate;
+	memoDefaults = UNSET;
+	memoConditional = UNSET;
+	memoProps = UNSET;
+	memoEntry = UNSET;
+	memoHolding = UNSET;
+	memoOwn = UNSET;
+	memoOwnConditions = UNSET;
+	slotViews = /* @__PURE__ */ new Map();
+	/** Built by {@link cellAt}; a surface reaches one through `Component.cell`. */
+	constructor(config, component, coordinate) {
+		this.config = config;
+		this.component = component;
+		this.coordinate = coordinate;
+	}
+	/** What every cell starts from: the declared defaults, `defaultProps`, then the `*` preview entry. */
+	get defaults() {
+		if (this.memoDefaults === UNSET) this.memoDefaults = previewDefaults(this.config, this.component);
+		return this.memoDefaults;
+	}
+	/** What the conditional `preview` entries that hold for this cell add, later entries over earlier. */
+	get conditional() {
+		if (this.memoConditional === UNSET) this.memoConditional = previewConditionalProps(this.config, this.component, { ...this.coordinate });
+		return this.memoConditional;
+	}
+	/** The values in force: the defaults, what holds for the cell, then the coordinate itself. */
+	get props() {
+		if (this.memoProps === UNSET) this.memoProps = {
+			...this.defaults,
+			...this.conditional,
+			...this.coordinate
+		};
+		return this.memoProps;
+	}
+	/** The `preview` entry whose condition is exactly this coordinate, or `undefined`. */
+	get entry() {
+		if (this.memoEntry === UNSET) this.memoEntry = previewConditionAt({
+			config: this.config,
+			path: this.component,
+			cell: this.coordinate
+		});
+		return this.memoEntry;
+	}
+	/** The conditional `preview` entries that hold for this cell, in stored order. */
+	get holding() {
+		if (this.memoHolding === UNSET) this.memoHolding = holdingPreviewConditions({
+			config: this.config,
+			path: this.component,
+			cell: this.coordinate
+		});
+		return this.memoHolding;
+	}
+	/**
+	* The props this cell shows as its own: the ones a condition reveals under its values, and the
+	* ones its holding preview entries set. What every cell shares belongs to the component's own
+	* row, so a cell repeats none of it.
+	*/
+	get own() {
+		if (this.memoOwn === UNSET) {
+			const own = /* @__PURE__ */ new Set();
+			for (const prop of surfaceProps(this.config, this.component)) if (prop.when && propApplies(prop, this.props)) own.add(prop.name);
+			for (const name of Object.keys(this.conditional)) own.add(name);
+			this.memoOwn = own;
+		}
+		return this.memoOwn;
+	}
+	/**
+	* The conditions the own props are shown under, each once. A gated prop is shown under its own
+	* `when`, which can be wider than the cell (`type = color` on a `color, xs` cell). A prop the
+	* cell's preview pins has no `when` of its own, so the coordinate is what shows it.
+	*/
+	get ownConditions() {
+		if (this.memoOwnConditions === UNSET) {
+			const coordinate = Object.fromEntries(Object.entries(this.coordinate).map(([prop, value]) => [prop, [value]]));
+			const declared = new Map(surfaceProps(this.config, this.component).map((prop) => [prop.name, prop.when]));
+			const distinct = /* @__PURE__ */ new Map();
+			for (const name of this.own) {
+				const when = declared.get(name) ?? coordinate;
+				distinct.set(canonicalCondition(when), when);
+			}
+			this.memoOwnConditions = [...distinct.values()];
+		}
+		return this.memoOwnConditions;
+	}
+	/** Whether the 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. */
+	isDefaults(modifiers = []) {
+		return cellAtDefaults({
+			config: this.config,
+			path: this.component,
+			cell: this.coordinate,
+			modifiers
+		});
+	}
+	/** Whether a stored condition holds at this cell, by the same test a style rule is applied with. */
+	holds(when) {
+		return ruleApplies(when, this.props);
+	}
+	/**
+	* The condition in force for `layer` at this cell, or `null` when only the base holds and an edit
+	* is this cell's alone.
+	*
+	* The candidates are the conditions that hold here and speak only of the axes the coordinate pins,
+	* so a reach can be spelled as cells of the grid: the style rules whose bag names the layer, the
+	* preview entries that set a prop routed into the layer, and every preview entry holding at the
+	* cell, since an entry such as `type = color` is what defines that row. A condition with a list
+	* value is not a coordinate and is left out. The most specific wins; at equal specificity a
+	* preview entry beats a style rule, since an entry is what defines a row, one that reaches the
+	* layer beats one that does not, and a later stored one beats an earlier.
+	*
+	* A preview content key (`messages__children__2`) names an element a slot's content placed, so the
+	* entries filling that slot are what reach it.
+	*/
+	governing(layer = null) {
+		const pinned = new Set(Object.keys(this.coordinate));
+		const isCoordinate = (when) => {
+			const entries = Object.entries(when);
+			return entries.length > 0 && entries.every(([prop, value]) => {
+				const leaf = refLeaf(value);
+				return pinned.has(prop) && (typeof leaf === "string" || typeof leaf === "number" || typeof leaf === "boolean");
+			});
+		};
+		const content = layer ? parsePreviewContentKey(layer) : null;
+		const reaching = new Set(content ? [content.prop] : layer ? propsIntoLayer({
+			config: this.config,
+			path: this.component,
+			layer
+		}) : []);
+		const candidates = [];
+		let order = 0;
+		if (layer && !content) {
+			const { styles = {} } = this.config.resolve("component", this.component)?.body ?? {};
+			for (const [key, rule] of Object.entries(styles)) {
+				if (!rule.when || !isCoordinate(rule.when)) continue;
+				if (Object.keys(rule.layers?.[layer] ?? {}).length === 0) continue;
+				if (!this.holds(rule.when)) continue;
+				candidates.push({
+					source: "style",
+					key,
+					when: leaves(rule.when),
+					reaches: true,
+					order: order++
+				});
+			}
+		}
+		for (const { key, condition } of this.holding) {
+			if (!condition.when || !isCoordinate(condition.when)) continue;
+			candidates.push({
+				source: "preview",
+				key,
+				when: leaves(condition.when),
+				reaches: [...reaching].some((prop) => condition.props[prop] !== void 0),
+				order: order++
+			});
+		}
+		let winner = null;
+		for (const candidate of candidates) if (!winner || outranks(candidate, winner)) winner = candidate;
+		return winner ? {
+			source: winner.source,
+			key: winner.key,
+			when: winner.when
+		} : null;
+	}
+	/** The condition an edit to `layer` at this cell writes under: {@link governing}'s, else the
+	*  coordinate itself. */
+	whenFor(layer = null) {
+		return this.governing(layer)?.when ?? { ...this.coordinate };
+	}
+	/** The stored field the value this cell shows for `prop` comes from, or `undefined` when the
+	*  component stores none. */
+	sourceOf(prop) {
+		return previewValueSource({
+			config: this.config,
+			path: this.component,
+			cell: this.coordinate,
+			prop
+		});
+	}
+	/** The component's slots, each read and written at this coordinate. */
+	slots() {
+		return listSlots({
+			config: this.config,
+			path: this.component
+		}).map((slot) => this.view(slot));
+	}
+	/** The slot a prop names, read and written at this coordinate; `undefined` when the prop is not one. */
+	slot(prop) {
+		const slot = slotOf({
+			config: this.config,
+			path: this.component,
+			slot: prop
+		});
+		return slot ? this.view(slot) : void 0;
+	}
+	view(slot) {
+		let view = this.slotViews.get(slot.from);
+		if (!view) {
+			view = new CellSlot(slot, this.coordinate);
+			this.slotViews.set(slot.from, view);
+		}
+		return view;
+	}
+};
+/**
+* A slot as one cell shows it: the route and acceptance of the {@link Slot}, with its content read
+* and written at the cell's coordinate, so a gesture on a cell never hands the coordinate back.
+*/
+var CellSlot = class {
+	constructor(slot, coordinate) {
+		this.slot = slot;
+		this.coordinate = coordinate;
+	}
+	get component() {
+		return this.slot.component;
+	}
+	/** The prop the content arrives as on the instance. */
+	get from() {
+		return this.slot.from;
+	}
+	/** The layer that holds the content. */
+	get layer() {
+		return this.slot.layer;
+	}
+	/** The prop the content lands under on the layer's element. */
+	get into() {
+		return this.slot.into;
+	}
+	/** The refs the slot accepts; empty when unconstrained. */
+	get accepts() {
+		return this.slot.accepts;
+	}
+	get isChildren() {
+		return this.slot.isChildren;
+	}
+	/** Whether the slot takes an element — see {@link Slot.takes}. */
+	takes(element) {
+		return this.slot.takes(element);
+	}
+	/** The elements this cell shows in the slot, in order. */
+	get content() {
+		return this.slot.content(this.coordinate);
+	}
+	/** The stored field this cell reads the content from, or `undefined` when nothing is stored. */
+	get source() {
+		return this.slot.source(this.coordinate);
+	}
+	/** Append to the content under this coordinate — see {@link Slot.append}. */
+	append(element) {
+		return this.slot.append({
+			cell: this.coordinate,
+			element
+		});
+	}
+	/** The content with one element placed at an address — see {@link Slot.placed}. */
+	placed({ address, element }) {
+		return this.slot.placed({
+			cell: this.coordinate,
+			address,
+			element
+		});
+	}
+	/** The element at an address — see {@link Slot.elementAt}. */
+	elementAt(address) {
+		return this.slot.elementAt({
+			cell: this.coordinate,
+			address
+		});
+	}
+	/** The element at one address moved to another — see {@link Slot.moveAt}. */
+	moveAt({ from, to }) {
+		return this.slot.moveAt({
+			cell: this.coordinate,
+			from,
+			to
+		});
+	}
+	/** A copy of the element at an address, placed after it — see {@link Slot.duplicateAt}. */
+	duplicateAt(address) {
+		return this.slot.duplicateAt({
+			cell: this.coordinate,
+			address
+		});
+	}
+	/** Write one element at an address — see {@link Slot.insertAt}. */
+	insertAt({ address, element }) {
+		return this.slot.insertAt({
+			cell: this.coordinate,
+			address,
+			element
+		});
+	}
+	/** Swap one element in place — see {@link Slot.replaceAt}. */
+	replaceAt({ address, element }) {
+		return this.slot.replaceAt({
+			cell: this.coordinate,
+			address,
+			element
+		});
+	}
+	/** Take one element out — see {@link Slot.removeAt}. */
+	removeAt(address) {
+		return this.slot.removeAt({
+			cell: this.coordinate,
+			address
+		});
+	}
+	/** Store the whole content under this coordinate — see {@link Slot.set}. */
+	set(elements) {
+		return this.slot.set({
+			cell: this.coordinate,
+			elements
+		});
+	}
+};
+/** The component under a coordinate. Always answers: a path naming no component reads as a cell
+*  that stores nothing. The same config, path and coordinate hand back the same cell. */
+function cellAt({ config, path, cell }) {
+	let byKey = cellsByConfig.get(config);
+	if (!byKey) {
+		byKey = /* @__PURE__ */ new Map();
+		cellsByConfig.set(config, byKey);
+	}
+	const key = coordinateKey(path, cell);
+	const hit = byKey.get(key);
+	if (hit) return hit;
+	const made = new Cell(config, path, cell);
+	byKey.set(key, made);
+	return made;
+}
+//#endregion
+export { cellAt };

package/dist/spec/detach.d.ts

@@ -0,0 +1,125 @@
+import { ConfigEdit } from "../framework/config-op.js";
+import { Ref } from "../framework/utils/refs.js";
+import { Config } from "../framework/Config.js";
+import { PreviewElement } from "./preview-elements.js";
+import { PreviewContentAddress } from "./preview-content.js";
+import { Slot, SlotCell } from "./slot.js";
+
+//#region src/spec/detach.d.ts
+/**
+ * The edits that detach the instance the layer `layer` of `path` renders: one `element-insert` of
+ * the instance's component's anatomy under the instance's parent at its index, a move for each
+ * element the instance held in a slot, and the instance's deletion last. `null` when the layer
+ * renders no component, or nothing places it.
+ */
+declare function detachInstanceEdit({
+  config,
+  path,
+  layer
+}: {
+  config: Config; /** The edited component. */
+  path: string; /** The layer whose element is the instance's component. */
+  layer: string;
+}): ConfigEdit[] | null;
+/**
+ * The edits that detach one element of a slot's content: the element the address names in the
+ * content the cell shows becomes anatomy under the layer its slot routes to, baked at the props
+ * the element sets, and the content loses it. Its own children and the elements it hands to its
+ * slots come along as instance nodes under the layers the element's component routes them to.
+ * `null` for an address inside another element, or one naming no component.
+ */
+declare function detachContentEdit({
+  config,
+  path,
+  cell,
+  address
+}: {
+  config: Config; /** The edited component. */
+  path: string; /** The coordinate whose content the address reads. */
+  cell: SlotCell;
+  address: PreviewContentAddress;
+}): ConfigEdit[] | null;
+/** A baked instance as page-spec elements: json-render's shape, keyed by the source's node names. */
+interface DetachedElementSpec {
+  readonly root: string;
+  readonly elements: Record<string, {
+    type: string;
+    props?: Record<string, unknown>;
+    children?: string[];
+  }>;
+  /** For each slot prop of the source, the element its content belongs under. */
+  readonly slotHosts: Record<string, string>;
+}
+/**
+ * The anatomy an instance of `source` renders under `props`, as the elements a page document
+ * stores: the layer's element as the spec `type` (a component as its `component:` marker), the baked
+ * bag and any text as props, the kept edges as children. What a design-canvas Detach splices in
+ * place of the instance; the content the instance held goes under `slotHosts[<prop>]`.
+ */
+declare function detachedElementSpec({
+  config,
+  source,
+  props,
+  filled
+}: {
+  config: Config; /** The component ref the instance renders (`component:Badge`). */
+  source: string; /** The instance's props, a `layerProps` bag included. */
+  props: Record<string, unknown>;
+  /**
+   * The slot props the instance fills with elements. A layer shown only while its slot has content
+   * (`media`, `actions`) is kept for a filled slot and dropped for an empty one, so the content has
+   * that layer to land under rather than falling back to the root.
+   */
+  filled?: ReadonlySet<string>;
+}): DetachedElementSpec | null;
+/**
+ * A preview element that renders a component, as the tree its component is made of, baked at the
+ * props the element sets: each kept source node becomes an element (a component as its ref, a tag
+ * as itself), the baked bag as its props, its text as text, its edges as children. The children
+ * and element-valued props the original held ride along under the elements the component routes
+ * them to. `null` when the component stores nothing.
+ */
+declare function detachedPreviewElement({
+  config,
+  source,
+  element
+}: {
+  config: Config; /** The component ref the element renders (`component:Button`). */
+  source: string;
+  element: PreviewElement;
+}): PreviewElement | null;
+/** Why a slot would not hold a detached element: the slot, and what the element becomes. */
+interface DetachRefusal {
+  /** The slot the element sits in, on its parent's component. */
+  readonly slot: Slot;
+  /** What the detached element's root is: a tag, or a component ref. */
+  readonly becomes: string | Ref;
+}
+/** The root element a detached instance of `source` would render, under `props`. */
+declare function detachedRootElement({
+  config,
+  source,
+  props
+}: {
+  config: Config;
+  source: string;
+  props: Record<string, unknown>;
+}): string | Ref | undefined;
+/**
+ * Why the element an address names inside another element cannot detach in place: the slot of the
+ * parent's component that holds it refuses what the element becomes. `null` when it can, or when
+ * the address is not inside another element.
+ */
+declare function detachContentRefusal({
+  config,
+  path,
+  cell,
+  address
+}: {
+  config: Config;
+  path: string;
+  cell: SlotCell;
+  address: PreviewContentAddress;
+}): DetachRefusal | null;
+//#endregion
+export { DetachRefusal, DetachedElementSpec, detachContentEdit, detachContentRefusal, detachInstanceEdit, detachedElementSpec, detachedPreviewElement, detachedRootElement };