@yahoo/uds-create-config 4.51.3 → 4.53.0

package/dist/entities/canvas/node-gestures.js

@@ -0,0 +1,616 @@
+import { rejectData } from "../../framework/rejection.js";
+import { pathOf, ref } from "../../framework/utils/refs.js";
+import { pathInput } from "../../framework/schemas.js";
+import { childrenPolicy } from "../system/element.js";
+import { surfaceProps } from "../../framework/prop-surface.js";
+import { forceModeProp, forceModeProps } from "../../framework/class-names.js";
+import { slotOf } from "../../spec/slot.js";
+import { PLACED_NODE_KEY, attachedSystem, elementTypeRef, postOrder } from "./node-patches.js";
+import { z } from "zod";
+//#region src/entities/canvas/node-gestures.ts
+const specSchema = z.object({
+	root: z.string().min(1),
+	elements: z.record(z.string(), z.unknown())
+}).passthrough();
+const insertData = z.object({
+	/** The subtree to graft, as a spec; its root becomes the node's last child unless `index` says. */
+	subtree: specSchema,
+	index: z.number().int().nonnegative().optional(),
+	/** A named slot of the node's component to fill instead of its children. */
+	slotProp: z.string().min(1).optional()
+});
+const insertInput = z.object({
+	path: pathInput("node"),
+	data: insertData
+});
+const wrapData = z.object({
+	/** The node's children to wrap, by path; they must all be its direct children. */
+	elements: z.array(z.string().min(1)).min(1),
+	/** The container: a component type as a spec spells it, with the props it starts with. */
+	container: z.object({
+		type: z.string().min(1),
+		props: z.record(z.string(), z.unknown()).optional(),
+		/** A named slot of the container to hold them, instead of its children. */
+		slotProp: z.string().min(1).optional()
+	})
+});
+const wrapInput = z.object({
+	path: pathInput("node"),
+	data: wrapData
+});
+const forceModeData = z.object({
+	/** A modifier group of the attached system whose modes are class-based. */
+	group: z.string().min(1),
+	/** The mode to force, or `null` to follow the page again. */
+	option: z.string().min(1).nullable()
+});
+const elementInput = z.object({ path: pathInput("node") });
+const duplicateInput = z.object({
+	path: pathInput("node"),
+	data: z.object({ 
+	/** How many copies, each placed after the last. */
+count: z.number().int().min(1).max(50).optional() }).optional()
+});
+const swapInput = z.object({
+	path: pathInput("node"),
+	data: z.object({ 
+	/** The component to render instead, as a spec spells a type. */
+type: z.string().min(1) })
+});
+const moveInput = z.object({
+	path: pathInput("node"),
+	data: z.object({
+		/** The element to move it into, by path, inside the same placed node; its own parent when absent. */
+		parent: z.string().min(1).optional(),
+		/** A named slot of the parent to land in, instead of its children. */
+		slotProp: z.string().min(1).optional(),
+		/** Its position there, from 0; past the end is last, and the end when absent under a new parent. */
+		index: z.number().int().nonnegative().optional(),
+		/** How many places to move among its siblings, negative earlier, in place of `index`. */
+		offset: z.number().int().optional()
+	})
+});
+const reorderInput = z.object({
+	path: pathInput("node"),
+	data: z.object({
+		/** Every element of the list, by path, in the order to hold them. */
+		order: z.array(z.string().min(1)),
+		/** The named slot to reorder instead of the children. */
+		slotProp: z.string().min(1).optional()
+	})
+});
+const forceModeInput = z.object({
+	path: pathInput("node"),
+	data: forceModeData
+});
+function bodyOf(config, path, field) {
+	const node = config.resolve("node", path);
+	if (!node) return rejectData(`Node "${path}" does not exist.`, field);
+	return node.body;
+}
+/** The placed node a path belongs to: `card` for `card/title`. */
+function rootOf(path) {
+	return path.split("/")[0] ?? path;
+}
+/**
+* A minter of subtree paths under `root` that no row holds yet. The placed node's own key is taken
+* too: a row at `<root>/root` would read back as the node's own element and replace it.
+*/
+function freshPaths(config, root) {
+	const taken = new Set(config.list("node").map((node) => node.path));
+	taken.add(`${root}/${PLACED_NODE_KEY}`);
+	return (base) => {
+		let candidate = `${root}/${base}`;
+		let n = 0;
+		while (taken.has(candidate)) candidate = `${root}/${base}__${++n}`;
+		taken.add(candidate);
+		return candidate;
+	};
+}
+/** The node's children as refs, in order. */
+function childrenOf(body) {
+	return [...body.children ?? []];
+}
+function insert(config, input) {
+	const { slug } = attachedSystem(config);
+	const parent = bodyOf(config, input.path, ["path"]);
+	const spec = input.data.subtree;
+	const elements = spec.elements;
+	if (!elements[spec.root]) return rejectData(`The subtree's root "${spec.root}" is not among its elements.`, ["data", "subtree"]);
+	const fresh = freshPaths(config, rootOf(input.path));
+	const order = postOrder(spec);
+	const pathFor = /* @__PURE__ */ new Map();
+	for (const key of order) pathFor.set(key, fresh(key));
+	const sub = (key) => {
+		const path = pathFor.get(key);
+		if (!path) return rejectData(`Element "${key}" is not among the subtree's elements.`, ["data", "subtree"]);
+		return ref("node", path);
+	};
+	const patches = [];
+	for (const key of order) {
+		const element = elements[key];
+		if (!element) continue;
+		const slots = {};
+		for (const [name, fills] of Object.entries(element.slots ?? {})) slots[name] = fills.map(sub);
+		patches.push({
+			kind: "node",
+			operation: "create",
+			path: pathFor.get(key),
+			data: {
+				type: elementTypeRef({
+					type: element.type,
+					slug
+				}),
+				props: element.props ?? {},
+				...element.children?.length ? { children: element.children.map(sub) } : {},
+				...Object.keys(slots).length > 0 ? { slots } : {},
+				...element.visible !== void 0 ? { visible: element.visible } : {},
+				...element.repeat !== void 0 ? { repeat: element.repeat } : {}
+			}
+		});
+	}
+	const slot = input.data.slotProp;
+	if (slot !== void 0) {
+		const component = componentOf({
+			config,
+			body: parent
+		});
+		const declared = component ? slotOf({
+			config: component.system,
+			path: component.path,
+			slot
+		}) : void 0;
+		if (!declared || declared.isChildren) return rejectData(`"${input.path}" has no slot "${slot}" to fill.`, ["data", "slotProp"]);
+		const rootType = elements[spec.root]?.type;
+		if (rootType && !declared.takes(rootType)) return rejectData(`The "${slot}" slot does not take ${rootType}.`, ["data", "slotProp"]);
+	}
+	const list = slot === void 0 ? childrenOf(parent) : [...parent.slots?.[slot] ?? []];
+	const at = Math.min(input.data.index ?? list.length, list.length);
+	list.splice(at, 0, sub(spec.root));
+	patches.push({
+		kind: "node",
+		operation: "update",
+		path: input.path,
+		data: slot === void 0 ? { children: list } : { slots: {
+			...parent.slots ?? {},
+			[slot]: list
+		} }
+	});
+	return patches;
+}
+/** The component a node renders, with the system that declares it; `undefined` for any other type. */
+function componentOf({ config, body }) {
+	if (!body.type) return void 0;
+	const { system } = attachedSystem(config);
+	const entity = system.resolve("component", pathOf(body.type));
+	return entity ? {
+		system,
+		path: entity.path
+	} : void 0;
+}
+function placeOf(config, path, field) {
+	const root = rootOf(path);
+	if (path === root) return rejectData(`"${path}" is a placed node; this acts on an element inside one.`, field);
+	const candidates = [config.resolve("node", root), ...config.members("node", root)];
+	for (const candidate of candidates) {
+		if (!candidate) continue;
+		const body = candidate.body;
+		const lists = [[null, childrenOf(body)], ...Object.entries(body.slots ?? {}).map(([name, fills]) => [name, [...fills]])];
+		for (const [slot, list] of lists) {
+			const index = list.findIndex((entry) => pathOf(entry) === path);
+			if (index !== -1) return {
+				parent: candidate.path,
+				body,
+				slot,
+				list,
+				index
+			};
+		}
+	}
+	return rejectData(`"${path}" is not inside a placed node.`, field);
+}
+/** The patch writing a changed list back to the parent it came from. */
+function placeUpdate(place, list) {
+	return {
+		kind: "node",
+		operation: "update",
+		path: place.parent,
+		data: place.slot === null ? { children: list } : { slots: {
+			...place.body.slots ?? {},
+			[place.slot]: list
+		} }
+	};
+}
+/** An element and everything beneath it, deepest first, so each create meets the rows it points at. */
+function subtreeOf(config, path) {
+	const out = [];
+	const visit = (at) => {
+		const body = config.resolve("node", at)?.body;
+		if (!body) return;
+		for (const child of childrenOf(body)) visit(pathOf(child));
+		for (const fills of Object.values(body.slots ?? {})) for (const fill of fills) visit(pathOf(fill));
+		out.push(at);
+	};
+	visit(path);
+	return out;
+}
+function remove(config, input) {
+	const place = placeOf(config, input.path, ["path"]);
+	return [placeUpdate(place, place.list.filter((_, i) => i !== place.index)), ...subtreeOf(config, input.path).reverse().map((path) => ({
+		kind: "node",
+		operation: "delete",
+		path
+	}))];
+}
+function duplicate(config, input) {
+	const place = placeOf(config, input.path, ["path"]);
+	const fresh = freshPaths(config, rootOf(input.path));
+	const subtree = subtreeOf(config, input.path);
+	const count = input.data?.count ?? 1;
+	const patches = [];
+	const copies = [];
+	for (let n = 0; n < count; n++) {
+		const pathFor = new Map(subtree.map((path) => [path, fresh(path.split("/").at(-1) ?? path)]));
+		const remap = (entry) => {
+			const to = pathFor.get(pathOf(entry));
+			return to ? ref("node", to) : entry;
+		};
+		for (const path of subtree) {
+			const body = config.resolve("node", path)?.body;
+			patches.push({
+				kind: "node",
+				operation: "create",
+				path: pathFor.get(path),
+				data: {
+					...body,
+					...body.children ? { children: body.children.map(remap) } : {},
+					...body.slots ? { slots: Object.fromEntries(Object.entries(body.slots).map(([name, fills]) => [name, fills.map(remap)])) } : {}
+				}
+			});
+		}
+		copies.push(ref("node", pathFor.get(input.path)));
+	}
+	const list = [...place.list];
+	list.splice(place.index + 1, 0, ...copies);
+	patches.push(placeUpdate(place, list));
+	return patches;
+}
+function unwrap(config, input) {
+	const place = placeOf(config, input.path, ["path"]);
+	const body = bodyOf(config, input.path, ["path"]);
+	const filled = Object.entries(body.slots ?? {}).find(([, fills]) => fills.length > 0);
+	if (filled) return rejectData(`"${input.path}" holds content in its "${filled[0]}" slot, which would have nowhere to go.`, ["path"]);
+	const children = childrenOf(body);
+	if (children.length === 0) return rejectData(`"${input.path}" holds nothing to keep.`, ["path"]);
+	const list = [...place.list];
+	list.splice(place.index, 1, ...children);
+	return [placeUpdate(place, list), {
+		kind: "node",
+		operation: "delete",
+		path: input.path
+	}];
+}
+function swap(config, input) {
+	const { slug, system } = attachedSystem(config);
+	const body = bodyOf(config, input.path, ["path"]);
+	const type = elementTypeRef({
+		type: input.data.type,
+		slug
+	});
+	const component = system.resolve("component", pathOf(type));
+	if (!component) return rejectData(`The system has no component "${input.data.type}".`, ["data", "type"]);
+	if (childrenOf(body).length > 0 && childrenPolicy(system, component.path) !== "nodes") return rejectData(`${component.path} takes no child elements, and "${input.path}" holds some.`, ["data", "type"]);
+	for (const [name, fills] of Object.entries(body.slots ?? {})) {
+		if (fills.length === 0) continue;
+		const slot = slotOf({
+			config: system,
+			path: component.path,
+			slot: name
+		});
+		if (!slot || fills.some((fill) => !slotTakes({
+			config,
+			slot,
+			fill
+		}))) return rejectData(`${component.path} has no "${name}" slot for what "${input.path}" holds there.`, ["data", "type"]);
+	}
+	const takes = new Set(surfaceProps(system, component.path).map((prop) => prop.name));
+	const props = Object.fromEntries(Object.entries(body.props ?? {}).filter(([name]) => takes.has(name)));
+	return [{
+		kind: "node",
+		operation: "update",
+		path: input.path,
+		data: {
+			type,
+			props
+		}
+	}];
+}
+/** Whether a slot takes the element a fill ref points at. */
+function slotTakes({ config, slot, fill }) {
+	const type = (config.resolve("node", pathOf(fill))?.body)?.type;
+	return !type || slot.takes(type);
+}
+/** A move with no `parent` and no `slotProp` stays among its siblings; any other lands in a parent. */
+function move(config, input) {
+	const { parent, slotProp, index, offset } = input.data;
+	if (index !== void 0 && offset !== void 0) return rejectData("Give `index` or `offset`, not both.", ["data", "offset"]);
+	if (parent !== void 0 || slotProp !== void 0) {
+		if (offset !== void 0) return rejectData("`offset` moves an element among its siblings; give `index` for a place under a parent.", ["data", "offset"]);
+		return reparent({
+			config,
+			path: input.path,
+			parent,
+			slotProp,
+			index
+		});
+	}
+	if (index === void 0 && offset === void 0) return rejectData("Say where to move it: `parent`, `index` or `offset`.", ["data"]);
+	const place = placeOf(config, input.path, ["path"]);
+	const list = [...place.list];
+	const [entry] = list.splice(place.index, 1);
+	if (!entry) return [];
+	const target = index ?? place.index + (offset ?? 0);
+	const at = Math.max(0, Math.min(target, list.length));
+	if (at === place.index) return [];
+	list.splice(at, 0, entry);
+	return [placeUpdate(place, list)];
+}
+function reorder(config, input) {
+	const body = bodyOf(config, input.path, ["path"]);
+	const { slotProp: slot, order } = input.data;
+	const held = (slot === void 0 ? childrenOf(body) : [...body.slots?.[slot] ?? []]).map(pathOf);
+	if (order.length !== held.length || new Set(order).size !== order.length || order.some((path) => !held.includes(path))) return rejectData(`The order has to name each of "${input.path}"'s ${slot ?? "children"} once: ${held.join(", ")}.`, ["data", "order"]);
+	const next = order.map((path) => ref("node", path));
+	return [{
+		kind: "node",
+		operation: "update",
+		path: input.path,
+		data: slot === void 0 ? { children: next } : { slots: {
+			...body.slots ?? {},
+			[slot]: next
+		} }
+	}];
+}
+function reparent({ config, path, parent, slotProp: slot, index }) {
+	const place = placeOf(config, path, ["path"]);
+	const to = parent ?? place.parent;
+	if (rootOf(to) !== rootOf(path)) return rejectData(`"${to}" is in another placed node.`, ["data", "parent"]);
+	if (subtreeOf(config, path).includes(to)) return rejectData(`"${to}" is inside "${path}".`, ["data", "parent"]);
+	const target = bodyOf(config, to, ["data", "parent"]);
+	const moving = (config.resolve("node", path)?.body)?.type;
+	const component = componentOf({
+		config,
+		body: target
+	});
+	if (component) {
+		const declared = slotOf({
+			config: component.system,
+			path: component.path,
+			slot: slot ?? "children"
+		});
+		if (slot && (!declared || declared.isChildren)) return rejectData(`"${to}" has no slot "${slot}".`, ["data", "slotProp"]);
+		if (!slot && childrenPolicy(component.system, component.path) !== "nodes") return rejectData(`"${to}" takes no child elements.`, ["data", "parent"]);
+		if (declared && moving && !declared.takes(moving)) return rejectData(`The ${slot ?? "children"} of "${to}" do not take "${path}".`, ["data", "parent"]);
+	}
+	const entry = place.list[place.index];
+	const sameList = place.parent === to && place.slot === (slot ?? null);
+	const from = place.list.filter((_, i) => i !== place.index);
+	const into = sameList ? from : slot === void 0 ? childrenOf(target) : [...target.slots?.[slot] ?? []];
+	into.splice(Math.min(index ?? into.length, into.length), 0, entry);
+	if (sameList) return [placeUpdate(place, into)];
+	return [placeUpdate(place, from), {
+		kind: "node",
+		operation: "update",
+		path: to,
+		data: slot === void 0 ? { children: into } : { slots: {
+			...target.slots ?? {},
+			[slot]: into
+		} }
+	}];
+}
+function wrap(config, input) {
+	const { slug } = attachedSystem(config);
+	const children = childrenOf(bodyOf(config, input.path, ["path"]));
+	const wrapped = new Set(input.data.elements);
+	for (const element of input.data.elements) if (!children.some((child) => pathOf(child) === element)) return rejectData(`"${element}" is not a child of "${input.path}"; wrap acts on a node's direct children.`, ["data", "elements"]);
+	const type = elementTypeRef({
+		type: input.data.container.type,
+		slug
+	});
+	const slotName = input.data.container.slotProp ?? "children";
+	const component = componentOf({
+		config,
+		body: { type }
+	});
+	const slot = component ? slotOf({
+		config: component.system,
+		path: component.path,
+		slot: slotName
+	}) : void 0;
+	if (input.data.container.slotProp && !slot) return rejectData(`${input.data.container.type} has no "${slotName}" slot.`, [
+		"data",
+		"container",
+		"slot"
+	]);
+	for (const element of input.data.elements) {
+		const held = children.find((child) => pathOf(child) === element);
+		if (slot && held && !slotTakes({
+			config,
+			slot,
+			fill: held
+		})) return rejectData(`The "${slotName}" slot of ${input.data.container.type} does not take "${element}".`, ["data", "elements"]);
+	}
+	const base = pathOf(type).split("/").at(-1)?.toLowerCase() ?? "group";
+	const containerPath = freshPaths(config, rootOf(input.path))(base);
+	const first = children.findIndex((child) => wrapped.has(pathOf(child)));
+	const kept = children.filter((child) => !wrapped.has(pathOf(child)));
+	kept.splice(first, 0, ref("node", containerPath));
+	return [{
+		kind: "node",
+		operation: "create",
+		path: containerPath,
+		data: {
+			type,
+			props: input.data.container.props ?? {},
+			...input.data.container.slotProp ? { slots: { [input.data.container.slotProp]: children.filter((child) => wrapped.has(pathOf(child))) } } : { children: children.filter((child) => wrapped.has(pathOf(child))) }
+		}
+	}, {
+		kind: "node",
+		operation: "update",
+		path: input.path,
+		data: { children: kept }
+	}];
+}
+function forceMode(config, input) {
+	const { system } = attachedSystem(config);
+	const body = bodyOf(config, input.path, ["path"]);
+	const { group, option } = input.data;
+	const members = system.members("modifier", group);
+	if (members.length === 0) return rejectData(`The system has no modifier group "${group}".`, ["data", "group"]);
+	const options = members.filter((member) => member.body.type === "selector").map((member) => member.path.split("/").at(-1) ?? member.path);
+	if (options.length === 0) return rejectData(`"${group}" has no class-based mode, so a layer cannot be forced into one.`, ["data", "group"]);
+	if (option !== null && !options.includes(option)) return rejectData(`"${option}" is not a mode of "${group}"; it offers ${options.join(", ")}.`, ["data", "option"]);
+	const props = { ...body.props ?? {} };
+	const key = forceModeProp(group);
+	if (option === null) delete props[key];
+	else props[key] = option;
+	for (const legacy of forceModeProps(group).slice(1)) delete props[legacy];
+	return [{
+		kind: "node",
+		operation: "update",
+		path: input.path,
+		data: { props }
+	}];
+}
+const applied = (config, patches) => patches.length === 0 ? config : config.applyAll(patches);
+const nodeGestureOps = {
+	update: { description: "Change one or more properties of this node (\"make it rounder\", \"more padding\", \"center the content\", \"size large\"): `data` carries the fields to set, `props` among them. Anything the node's component accepts, in the values the system declares." },
+	"element-insert": {
+		input: insertInput,
+		readOnly: false,
+		label: "Insert into a node",
+		description: "Add a component inside this node (\"add a button\", \"add text\", \"insert an image\"): the `subtree` given in `data`, a spec, is grafted under the node as one of its children, the last unless `index` says otherwise, or into the slot `slotProp` names on the node's component. Every element of the subtree becomes a row of its own beneath the placed node, keyed collision-free, so the root of the subtree is the new child.",
+		scope: "item",
+		title: (entity) => `Insert into ${entity}`,
+		example: () => ({
+			path: "card",
+			data: { subtree: {
+				root: "title",
+				elements: { title: {
+					type: "Text",
+					props: { children: "Hello" }
+				} }
+			} }
+		}),
+		handler: (input, config) => applied(config, insert(config, insertInput.parse(input)))
+	},
+	"element-wrap": {
+		input: wrapInput,
+		readOnly: false,
+		label: "Wrap children in a container",
+		description: "Group or wrap elements (\"wrap these in a stack\", \"group the title and the body\", \"put it in a card\"): some of this node's direct children move into a new container element of the given component type, which takes their place among the node's children. They land in the container's children, or in the slot its `slotProp` names, and a slot that lists what it accepts refuses anything else.",
+		scope: "item",
+		title: (entity) => `Wrap children of ${entity}`,
+		example: () => ({
+			path: "card",
+			data: {
+				elements: ["card/title", "card/body"],
+				container: {
+					type: "VStack",
+					props: { gap: "2" }
+				}
+			}
+		}),
+		handler: (input, config) => applied(config, wrap(config, wrapInput.parse(input)))
+	},
+	"element-delete": {
+		input: elementInput,
+		readOnly: false,
+		label: "Remove an element",
+		description: "Delete this element and everything inside it (\"delete\", \"remove this\", \"get rid of it\"). It leaves the list it sat in, whether its parent's children or one of its parent's slots.",
+		scope: "item",
+		title: (entity) => `Remove ${entity}`,
+		example: () => ({ path: "card/title" }),
+		handler: (input, config) => applied(config, remove(config, elementInput.parse(input)))
+	},
+	"element-duplicate": {
+		input: duplicateInput,
+		readOnly: false,
+		label: "Duplicate an element",
+		description: "Copy this element and everything inside it (\"duplicate\", \"make 3 more of these\"): each copy lands right after it among its siblings, `count` of them.",
+		scope: "item",
+		title: (entity) => `Duplicate ${entity}`,
+		example: () => ({
+			path: "card/title",
+			data: { count: 2 }
+		}),
+		handler: (input, config) => applied(config, duplicate(config, duplicateInput.parse(input)))
+	},
+	"element-unwrap": {
+		input: elementInput,
+		readOnly: false,
+		label: "Unwrap an element",
+		description: "Remove this container but keep what it holds (\"unwrap\", \"ungroup\"): its children take its place among its siblings.",
+		scope: "item",
+		title: (entity) => `Unwrap ${entity}`,
+		example: () => ({ path: "card/row" }),
+		handler: (input, config) => applied(config, unwrap(config, elementInput.parse(input)))
+	},
+	"element-swap": {
+		input: swapInput,
+		readOnly: false,
+		label: "Swap an element for another component",
+		description: "Render this element as a different component (\"make this a VStack\", \"swap to an icon button\", \"turn it into a link\"): it keeps its place, its content and the props the new component takes.",
+		scope: "item",
+		title: (entity) => `Swap ${entity}`,
+		example: () => ({
+			path: "card/row",
+			data: { type: "VStack" }
+		}),
+		handler: (input, config) => applied(config, swap(config, swapInput.parse(input)))
+	},
+	"element-move": {
+		input: moveInput,
+		readOnly: false,
+		label: "Move an element",
+		description: "Move this element among its siblings (\"move up\", \"put it first\") or into another element of the same placed node (\"move it into the card\", \"put it in the footer\"). Without a `parent` or `slotProp` it stays among its siblings: `offset` moves it that many places, negative earlier, and `index` puts it at a position. With `parent`, `slotProp` or both, it lands in that element's children or the slot `slotProp` names, at `index` or the end. A parent that takes no children, a slot that refuses the element, or a parent inside the element itself is refused.",
+		scope: "item",
+		title: (entity) => `Move ${entity}`,
+		example: () => ({
+			path: "card/title",
+			data: { parent: "card/header" }
+		}),
+		handler: (input, config) => applied(config, move(config, moveInput.parse(input)))
+	},
+	"children-reorder": {
+		input: reorderInput,
+		readOnly: false,
+		label: "Reorder an element's children",
+		description: "Put this element's children, or the slot `slotProp` names, in a new order (\"reverse them\", \"sort by name\"): `order` names every one of them once, by path, in the order to hold them.",
+		scope: "item",
+		title: (entity) => `Reorder ${entity}`,
+		example: () => ({
+			path: "card",
+			data: { order: ["card/body", "card/title"] }
+		}),
+		handler: (input, config) => applied(config, reorder(config, reorderInput.parse(input)))
+	},
+	"force-mode": {
+		input: forceModeInput,
+		readOnly: false,
+		label: "Force a mode on a node",
+		description: "Switch this node to a color mode (\"dark mode\", \"make it light\", \"follow the page\"): the node and everything inside it is forced into one option of a color-mode group of the attached system, or `null` lets it follow the page's mode again. The option has to be a class-based mode the system declares.",
+		scope: "item",
+		title: (entity) => `Force a mode on ${entity}`,
+		example: () => ({
+			path: "card",
+			data: {
+				group: "colorMode",
+				option: "dark"
+			}
+		}),
+		handler: (input, config) => applied(config, forceMode(config, forceModeInput.parse(input)))
+	}
+};
+//#endregion
+export { nodeGestureOps };

package/dist/{capture → entities/canvas}/node-patches.d.ts

@@ -1,7 +1,9 @@
-import { Config, Patch } from "../framework/Config.js";
-import { Spec } from "./capture-to-spec.js";
+import { Config, Patch } from "../../framework/Config.js";
+import { Spec } from "../../capture/capture-to-spec.js";
 
-//#region src/capture/node-patches.d.ts
+//#region src/entities/canvas/node-patches.d.ts
+/** The key a placed node's own element takes when its rows read back as a spec. */
+declare const PLACED_NODE_KEY = "root";
 interface Placement {
   readonly page: string;
   readonly x?: number;
@@ -29,4 +31,4 @@ declare function specToNodePatches({
   readonly placement: Placement;
 }): Patch[];
 //#endregion
-export { specToNodePatches };
+export { PLACED_NODE_KEY, specToNodePatches };

package/dist/{capture → entities/canvas}/node-patches.js

@@ -1,10 +1,23 @@
-import { ref } from "../framework/utils/refs.js";
-//#region src/capture/node-patches.ts
+import { rejectData } from "../../framework/rejection.js";
+import { ref } from "../../framework/utils/refs.js";
+//#region src/entities/canvas/node-patches.ts
 /**
 * A spec as the node rows of one new placed node. A placed node's content is its subtree rows, one
 * per element, at `<node>/<element key>`, each pointing at its children by ref; the root element's
 * content lives on the placed node itself beside its placement.
 */
+/** The system this canvas draws on, with the slug node types are qualified by. */
+function attachedSystem(config) {
+	const [source] = config.list("system-source");
+	const system = source ? config.sourceFor(source.path) : void 0;
+	if (!source || !system) return rejectData("This canvas has no system attached, so there are no components to place on it.");
+	return {
+		slug: source.path,
+		system
+	};
+}
+/** The key a placed node's own element takes when its rows read back as a spec. */
+const PLACED_NODE_KEY = "root";
 const INTRINSIC_TAG = /^[a-z][a-zA-Z0-9-]*$/;
 const SPEC_PRIMITIVES = new Set(["Slot", "Fragment"]);
 /** A spec element's `type` as the ref a node row stores, qualified with the system's slug. */
@@ -96,4 +109,4 @@ function specToNodePatches({ config, nodeId, spec, slug, placement }) {
 	return patches;
 }
 //#endregion
-export { specToNodePatches };
+export { PLACED_NODE_KEY, attachedSystem, elementTypeRef, postOrder, specToNodePatches };