@yahoo/uds-create-config 4.6.0 → 4.8.0

package/dist/spec/slot.js

@@ -0,0 +1,542 @@
+import { canonicalCondition, isRef, kindOf, pathOf, splitRef } from "../framework/utils/refs.js";
+import { rootLayerOf } from "../entities/system/element.js";
+import { createSliceMemo } from "../framework/memo.js";
+import "../framework/preview-store.js";
+import { resolveComponentProps } from "../framework/projections.js";
+import { routesIntoText } from "../framework/prop-surface.js";
+import { isPreviewElement } from "./preview-elements.js";
+import { slotTargetsOf } from "../framework/render-spec.js";
+import { previewConditionAt, previewContentList, previewValueSource } from "./preview-content.js";
+//#region src/spec/slot.ts
+/**
+* A slot of a component: one prop that content is placed in, as the config states it.
+*
+* A `Slot` is a value over one config, so every question about a slot has one owner: where its
+* content lands (`layer`, `into`), what it takes (`accepts`, `takes`), what a cell shows in it
+* (`content`, `source`) and how that content changes (`append`, `insertAt`, `replaceAt`, `removeAt`,
+* `set`).
+* Its content is a list of preview elements stored on the `preview` entry the cell reads it from;
+* a bare element stored on the prop reads as a list of one.
+*
+* The list of a component's slots is cached per component slice, the way every component
+* projection is, so a surface may ask per render. `Component.slots`, `Component.slot`,
+* `Component.slotHostedBy` and `Component.namedSlots` are the door; the functions below back them.
+*/
+const factsCache = createSliceMemo({
+	kinds: ["component"],
+	compute: (_config) => /* @__PURE__ */ new Map()
+});
+const listsByConfig = /* @__PURE__ */ new WeakMap();
+var Slot = class {
+	/** The component that declares the slot. */
+	component;
+	/** The prop the content arrives as on the instance (`children`, `startIcon`). */
+	from;
+	/** The layer that holds the content. */
+	layer;
+	/** The prop the content lands under on the layer's element. */
+	into;
+	/** The refs the slot accepts (`component:X`, `icon:phosphor`); empty when unconstrained. */
+	accepts;
+	/** Built by {@link listSlots}; a surface reaches one through `Component.slots` or `Component.slot`. */
+	constructor(config, component, facts) {
+		this.config = config;
+		this.component = component;
+		this.from = facts.from;
+		this.layer = facts.layer;
+		this.into = facts.into;
+		this.accepts = facts.accepts;
+	}
+	/** Whether this is the component's `children`, positioned inside one of its layers. */
+	get isChildren() {
+		return this.from === "children";
+	}
+	/**
+	* 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) {
+		if (this.accepts.length === 0) return true;
+		const named = elementRefOf(this.config, element);
+		if (!named) return false;
+		const kind = kindOf(named);
+		const elementPath = pathOf(named);
+		return this.accepts.some((accepted) => {
+			if (kindOf(accepted) !== kind) return false;
+			const acceptedPath = pathOf(accepted);
+			if (acceptedPath === elementPath) return true;
+			return !(this.config.resolve(kind, acceptedPath) !== void 0) && elementPath.startsWith(`${acceptedPath}/`);
+		});
+	}
+	/** The stored field a cell reads the slot's content from, or `undefined` when nothing is stored. */
+	source(cell) {
+		return previewValueSource({
+			config: this.config,
+			path: this.component,
+			cell,
+			prop: this.from
+		});
+	}
+	/** The elements a cell shows in the slot, in order. */
+	content(cell) {
+		return previewContentList(this.stored(this.source(cell)));
+	}
+	/**
+	* 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 }) {
+		return this.set({
+			cell,
+			elements: [...this.content(cell), element]
+		});
+	}
+	/**
+	* 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 }) {
+		if (address.prop !== this.from) return void 0;
+		return placeIn(this.content(cell), address, element);
+	}
+	/**
+	* 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 }) {
+		if (from.prop !== this.from || to.prop !== this.from) return [];
+		if (reachesInside(from, to)) return [];
+		const source = this.source(cell);
+		if (!source) return [];
+		const list = previewContentList(this.stored(source));
+		const element = elementIn(list, from);
+		if (!element) return [];
+		const without = removeIn(list, from);
+		if (!without) return [];
+		const content = placeIn(without, to, element);
+		if (!content) return [];
+		return this.writeSource({
+			source,
+			content
+		});
+	}
+	/** The element at `address` in the content shown under `cell`, or `undefined` when it names nothing. */
+	elementAt({ cell, address }) {
+		if (address.prop !== this.from) return void 0;
+		return elementIn(this.content(cell), address);
+	}
+	/**
+	* 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 }) {
+		if (address.prop !== this.from) return [];
+		const last = address.path[address.path.length - 1];
+		if (typeof last === "string") return [];
+		const source = this.source(cell);
+		if (!source) return [];
+		const list = previewContentList(this.stored(source));
+		const element = elementIn(list, address);
+		if (!element) return [];
+		const content = placeIn(list, last === void 0 ? {
+			...address,
+			index: address.index + 1
+		} : {
+			...address,
+			path: [...address.path.slice(0, -1), last + 1]
+		}, structuredClone(element));
+		if (!content) return [];
+		return this.writeSource({
+			source,
+			content
+		});
+	}
+	/** 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 }) {
+		const content = this.placed({
+			cell,
+			address,
+			element
+		});
+		return content ? this.set({
+			cell,
+			elements: content
+		}) : [];
+	}
+	/**
+	* 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 }) {
+		return this.rewrite({
+			cell,
+			address,
+			next: element
+		});
+	}
+	/**
+	* 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 }) {
+		return this.rewrite({
+			cell,
+			address,
+			next: null
+		});
+	}
+	/**
+	* 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 }) {
+		const conditional = Object.keys(cell).length > 0;
+		const when = conditional ? { ...cell } : null;
+		const exact = conditional ? previewConditionAt({
+			config: this.config,
+			path: this.component,
+			cell
+		}) : void 0;
+		let key = "*";
+		if (exact) key = exact.key;
+		else if (when) key = canonicalCondition(when);
+		return [{
+			kind: "component",
+			operation: "sub-update",
+			path: this.component,
+			field: "preview",
+			key,
+			data: {
+				...exact ? {} : { when },
+				[`props.${this.from}`]: storedContent(elements)
+			}
+		}];
+	}
+	stored(source) {
+		if (!source) return void 0;
+		const body = this.config.resolve("component", this.component)?.body;
+		if (source.kind === "defaultProps") return body?.defaultProps?.[this.from];
+		return body?.preview?.[source.key]?.props?.[this.from];
+	}
+	/** `replaceAt` and `removeAt`: one element rewritten or dropped, written back where it was read. */
+	rewrite({ cell, address, next }) {
+		if (address.prop !== this.from) return [];
+		const source = this.source(cell);
+		if (!source) return [];
+		const list = previewContentList(this.stored(source));
+		const target = list[address.index];
+		if (!target) return [];
+		const rewritten = rewriteAt(target, address.path, next);
+		if (rewritten === void 0) return [];
+		const content = [...list];
+		if (rewritten === null) content.splice(address.index, 1);
+		else content[address.index] = rewritten;
+		return this.writeSource({
+			source,
+			content
+		});
+	}
+	/** 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. */
+	writeSource({ source, content }) {
+		const value = content.length === 0 ? null : storedContent(content);
+		if (source.kind === "defaultProps") return [{
+			kind: "component",
+			operation: "update",
+			path: this.component,
+			data: { [`defaultProps.${this.from}`]: value }
+		}];
+		const body = this.config.resolve("component", this.component)?.body;
+		const remaining = Object.keys(body?.preview?.[source.key]?.props ?? {}).filter((name) => name !== this.from);
+		if (value === null && remaining.length === 0) return [{
+			kind: "component",
+			operation: "sub-delete",
+			path: this.component,
+			field: "preview",
+			key: source.key
+		}];
+		return [{
+			kind: "component",
+			operation: "sub-update",
+			path: this.component,
+			field: "preview",
+			key: source.key,
+			data: { [`props.${this.from}`]: value }
+		}];
+	}
+};
+/**
+* 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.
+*/
+function listSlots({ config, path }) {
+	let byPath = listsByConfig.get(config);
+	if (!byPath) {
+		byPath = /* @__PURE__ */ new Map();
+		listsByConfig.set(config, byPath);
+	}
+	const hit = byPath.get(path);
+	if (hit) return hit;
+	const slots = slotFacts(config, path).map((facts) => new Slot(config, path, facts));
+	byPath.set(path, slots);
+	return slots;
+}
+/** The named node slots alone: what a design node's render injects an empty placeholder for. */
+function namedSlots({ config, path }) {
+	return listSlots({
+		config,
+		path
+	}).filter((slot) => !slot.isChildren);
+}
+/** The slot a prop names, or `undefined` when the prop is not a slot content is placed in. */
+function slotOf({ config, path, slot }) {
+	return listSlots({
+		config,
+		path
+	}).find((entry) => entry.from === slot);
+}
+/** The slot whose content lands in `layer`, or `undefined` when the layer hosts none. */
+function slotHostedBy({ config, path, layer }) {
+	return listSlots({
+		config,
+		path
+	}).find((entry) => entry.layer === layer);
+}
+/** A list stored back the way content is authored: one element bare, several as the list. */
+function storedContent(list) {
+	return list.length === 1 ? list[0] : [...list];
+}
+/**
+* `root` with the element at `steps` replaced by `next`, or removed when `next` is `null`;
+* `undefined` when a step names nothing. A number steps into a child, a string into an
+* element-valued prop.
+*/
+function rewriteAt(root, steps, next) {
+	const [step, ...rest] = steps;
+	if (step === void 0) return next;
+	if (typeof step === "number") {
+		const child = root.children?.[step];
+		if (!child) return void 0;
+		const replaced = rewriteAt(child, rest, next);
+		if (replaced === void 0) return void 0;
+		const children = [...root.children ?? []];
+		if (replaced === null) children.splice(step, 1);
+		else children[step] = replaced;
+		const out = {
+			...root,
+			children
+		};
+		if (children.length === 0) delete out.children;
+		return out;
+	}
+	const held = root.props?.[step];
+	if (!isPreviewElement(held)) return void 0;
+	const replaced = rewriteAt(held, rest, next);
+	if (replaced === void 0) return void 0;
+	const props = { ...root.props };
+	if (replaced === null) delete props[step];
+	else props[step] = replaced;
+	const out = {
+		...root,
+		props
+	};
+	if (Object.keys(props).length === 0) delete out.props;
+	return out;
+}
+/** The element `address` names in `content`, or `undefined`. */
+function elementIn(content, address) {
+	let current = content[address.index];
+	for (const step of address.path) {
+		if (!current) return void 0;
+		const next = typeof step === "number" ? current.children?.[step] : current.props?.[step];
+		current = isPreviewElement(next) ? next : void 0;
+	}
+	return current;
+}
+/** `content` with `element` placed at `address`; `undefined` when a step reaches nothing. */
+function placeIn(content, address, element) {
+	const next = [...content];
+	if (address.path.length === 0) {
+		const index = Math.min(Math.max(address.index, 0), next.length);
+		next.splice(index, 0, element);
+		return next;
+	}
+	const target = next[address.index];
+	if (!target) return void 0;
+	const inner = insertInto(target, address.path, element);
+	if (inner === void 0) return void 0;
+	next[address.index] = inner;
+	return next;
+}
+/** `content` without the element at `address`; `undefined` when it names nothing. */
+function removeIn(content, address) {
+	const next = [...content];
+	const target = next[address.index];
+	if (!target) return void 0;
+	if (address.path.length === 0) {
+		next.splice(address.index, 1);
+		return next;
+	}
+	const inner = rewriteAt(target, address.path, null);
+	if (inner === void 0 || inner === null) return void 0;
+	next[address.index] = inner;
+	return next;
+}
+/** Whether `to` is `from` or a position inside the element `from` names. */
+function reachesInside(from, to) {
+	if (to.index !== from.index) return false;
+	if (to.path.length < from.path.length) return false;
+	return from.path.every((step, i) => to.path[i] === step);
+}
+/**
+* `root` with `element` placed along `steps`: the last step is where it goes, a number among the
+* children there (past the end appending) or a string as that element-valued prop; the steps
+* before it walk the same way {@link rewriteAt} does. `undefined` when a step reaches nothing.
+*/
+function insertInto(root, steps, element) {
+	const [step, ...rest] = steps;
+	if (step === void 0) return void 0;
+	if (rest.length === 0) {
+		if (typeof step === "number") {
+			const children = [...root.children ?? []];
+			children.splice(Math.min(Math.max(step, 0), children.length), 0, element);
+			return {
+				...root,
+				children
+			};
+		}
+		return {
+			...root,
+			props: {
+				...root.props,
+				[step]: element
+			}
+		};
+	}
+	if (typeof step === "number") {
+		const child = root.children?.[step];
+		if (!child) return void 0;
+		const placed = insertInto(child, rest, element);
+		if (placed === void 0) return void 0;
+		const children = [...root.children ?? []];
+		children[step] = placed;
+		return {
+			...root,
+			children
+		};
+	}
+	const held = root.props?.[step];
+	if (!isPreviewElement(held)) return void 0;
+	const placed = insertInto(held, rest, element);
+	if (placed === void 0) return void 0;
+	return {
+		...root,
+		props: {
+			...root.props,
+			[step]: placed
+		}
+	};
+}
+/** The `kind:path` an element names, or `undefined` for an intrinsic tag, which no `accepts` can name. */
+function elementRefOf(config, element) {
+	if (isRef(element)) return element.__ref;
+	const { kind } = splitRef(element);
+	if (kind && kind !== element && config.entityOf(kind)) return element;
+	return config.resolve("component", element) ? `component:${element}` : void 0;
+}
+/** Every ref an `accepts` declaration names, one or a list. */
+function acceptsRefsOf(accepts) {
+	return (Array.isArray(accepts) ? accepts : [accepts]).filter(isRef).map((entry) => entry.__ref);
+}
+/** The slots of a component as facts, computed once per component slice. */
+function slotFacts(config, path) {
+	const cache = factsCache(config);
+	const hit = cache.get(path);
+	if (hit) return hit;
+	const body = config.resolve("component", path)?.body;
+	const facts = factsOfBody({
+		config,
+		body: body ?? {},
+		routes: slotTargetsOf(config, path)
+	});
+	cache.set(path, facts);
+	return facts;
+}
+function factsOfBody({ config, body, routes }) {
+	const props = body.props;
+	const layers = body.layers;
+	const fillable = routes.filter((route) => {
+		if ((props?.[route.from])?.text === true) return false;
+		return !routesToText(config, layers, route);
+	});
+	const root = layers ? rootLayerOf(layers)[0] : void 0;
+	const positionedChildren = layers !== void 0 && Object.keys(layers).length >= 2;
+	return fillable.filter((route) => route.from !== "children" || positionedChildren && route.layer !== root).map((route) => ({
+		...route,
+		accepts: acceptsOf({
+			config,
+			props,
+			layers,
+			route
+		})
+	}));
+}
+/**
+* The refs a slot accepts: its own `accepts`, else the `accepts` of the prop at the far end of its
+* route, read in the config that owns the host layer's component, since a borrowed host with no
+* derived row is spelled in its source's namespace.
+*/
+function acceptsOf({ config, props, layers, route }) {
+	const decl = props?.[route.from];
+	const own = acceptsRefsOf(decl?.accepts);
+	if (own.length > 0) return own;
+	return acceptsRefsOf(farEndProp(config, layers, route)?.accepts);
+}
+/** The component a layer's element names, resolved where it lives; `undefined` for an intrinsic tag. */
+function hostComponent(config, hostRef) {
+	if (!isRef(hostRef) && !hostRef.includes(":")) return config.resolve("component", hostRef);
+	return (config.configFor(hostRef) ?? config).resolve("component", pathOf(hostRef));
+}
+/** The declaration a route lands on, when the host layer is a component; `undefined` for a tag. */
+function farEndProp(config, layers, route) {
+	const hostRef = layers?.[route.layer];
+	if (!hostRef || !hostComponent(config, hostRef)) return void 0;
+	return resolveComponentProps(config.configFor(hostRef) ?? config, pathOf(hostRef))[route.into];
+}
+/**
+* Whether a route ends in text: the host layer is a component whose prop at the far end is a text
+* slot, or forwards on to one (a badge's `children` onto its text layer), so the layer holds a
+* string. An intrinsic host has no declaration and takes nodes; a host that declares no such prop
+* cannot take the route at all, which reads the same way here.
+*/
+function routesToText(config, layers, route) {
+	const hostRef = layers?.[route.layer];
+	if (!hostRef || !hostComponent(config, hostRef)) return false;
+	const into = farEndProp(config, layers, route);
+	if (!into) return true;
+	if (into.text === true) return true;
+	if (into.type !== "forward") return false;
+	const owner = config.configFor(hostRef) ?? config;
+	const hostLayers = (owner.resolve("component", pathOf(hostRef))?.body)?.layers;
+	return routesIntoText(owner, hostLayers, into);
+}
+//#endregion
+export { listSlots, namedSlots, slotHostedBy, slotOf };

package/dist/spec/visibility.d.ts

@@ -0,0 +1,82 @@
+import { ComponentStyleBody, ProjectedVisibility } from "../entities/system/Component.js";
+import { StateCondition } from "@json-render/core";
+
+//#region src/spec/visibility.d.ts
+/** One `axis differs from value` test: json-render's `$state` test carrying only `neq`. */
+type VariantExclusionTest = Pick<StateCondition, '$state' | 'neq'>;
+/** The clause that hides a layer at one coordinate: one test, or an `$or` of one per pinned axis. */
+type VariantExclusion = VariantExclusionTest | {
+  $or: VariantExclusionTest[];
+};
+/**
+ * The clause that hides a layer at one coordinate, or `null` for a cell that pins nothing: a
+ * zero-axis component has one cell, and hiding the layer there is deleting it.
+ */
+declare function variantExclusion(cellProps: Readonly<Record<string, unknown>>): VariantExclusion | null;
+/**
+ * A condition split into the clauses the eye writes, one per variant a layer is hidden in, and the
+ * rest, which is what a boolean binding reads and edits. A surface that rewrites the rest puts the
+ * exclusions back with `spelledWith`, so a hide in one variant survives a change of binding.
+ */
+declare function splitVariantExclusions(visible: ProjectedVisibility | undefined): {
+  exclusions: unknown[];
+  rest: unknown[];
+};
+/** The stored spelling of `clauses` followed by `exclusions`: `null` for none, a bare clause for one,
+ *  the and-list for several. */
+declare function spelledWith({
+  clauses,
+  exclusions
+}: {
+  clauses: readonly unknown[];
+  exclusions: readonly unknown[];
+}): unknown | null;
+/** Whether the node's condition carries the eye's exclusion for this cell. */
+declare function excludesVariant({
+  visible,
+  cellProps
+}: {
+  visible: ProjectedVisibility | undefined;
+  cellProps: Readonly<Record<string, unknown>>;
+}): boolean;
+/**
+ * The condition with this cell excluded: the stored one plus the clause, or unchanged when the
+ * clause is already there. `undefined` when the cell pins nothing, since there is no coordinate to
+ * exclude.
+ */
+declare function withVariantHidden({
+  visible,
+  cellProps
+}: {
+  visible: ProjectedVisibility | undefined;
+  cellProps: Readonly<Record<string, unknown>>;
+}): unknown | undefined;
+/**
+ * The condition with this cell's exclusion taken out, `null` when nothing is left (which clears the
+ * field), or `undefined` when the condition never excluded it.
+ */
+declare function withVariantShown({
+  visible,
+  cellProps
+}: {
+  visible: ProjectedVisibility | undefined;
+  cellProps: Readonly<Record<string, unknown>>;
+}): unknown | null | undefined;
+/**
+ * The style rules that hide `layer` with `display: none` under `state`, in stored order. The
+ * projection keeps no source for a hidden layer, so a surface asking which rule hid it reads them
+ * here.
+ */
+declare function layerHidingRules({
+  component,
+  layer,
+  state
+}: {
+  component: {
+    readonly styles?: Readonly<Record<string, ComponentStyleBody>> | null;
+  };
+  layer: string; /** The instance's prop bag, defaults included, the same bag `layerStyles` resolves against. */
+  state: Record<string, unknown>;
+}): ComponentStyleBody[];
+//#endregion
+export { VariantExclusion, VariantExclusionTest, excludesVariant, layerHidingRules, spelledWith, splitVariantExclusions, variantExclusion, withVariantHidden, withVariantShown };