@plitzi/sdk-schema 0.37.2 → 0.37.4

package/dist/helpers/FlatMap.d.ts

@@ -1,4 +1,3 @@
-import { SchemaValidationResult } from './schemaValidator';
 import { MintElementId } from './elementId';
 import { Style, Element, Schema, DropPosition, SchemaVariable } from '@plitzi/sdk-shared';
 /** An element on its way in. Its id is the name it will answer to, and leaving it out asks this map to mint one. */
@@ -31,6 +30,12 @@ declare class FlatMap {
     /** Inserts an element, minting its id when the caller did not name it. Nothing else in the codebase mints an
      *  element id: every writer goes through here, so "every element has a name" is true by construction. */
     addElement: (input: ElementInput, to: Element["id"], dropPosition?: DropPosition, initialItems?: Record<Element["id"], Element>) => boolean;
+    /**
+     * Where `ids` go when dropped at `dropPosition` of `to`: the parent that takes them and its items with them in place.
+     * Null when there is nowhere to put them — no such element, a sibling of an element with no parent, a parent that
+     * holds no items, or an anchor its parent does not list. Computed without writing, so a refusal leaves no trace.
+     */
+    private placement;
     /** Replaces a stored element with an edited copy of itself. The id is its identity, not a field an update may
      *  carry a new value for — changing the name is `renameElement`, which is a document-wide operation. */
     updateElement: (element?: Element) => boolean;
@@ -46,15 +51,14 @@ declare class FlatMap {
      * change has to publish: the one element it renamed is almost never the whole of what moved.
      */
     renameElement: (from: Element["id"], to: Element["id"]) => Element["id"][] | false;
-    /** Why this element cannot be renamed to `id` (charset or a clash), or null when the name is free. */
-    renameConflict: (from: Element["id"], id: string) => string | null;
+    /**
+     * Moves an element — and everything in it — next to or inside `to`. Refused when `to` is the element itself or one
+     * of its own descendants: the subtree would end up holding itself. Crossing into another page or layout takes the
+     * subtree's `rootId` along, so the tree agrees with itself about where everything lives.
+     */
     moveElement: (from: Element["id"], to: Element["id"], elementId: Element["id"], dropPosition?: DropPosition) => boolean;
-    getElement: (elementId: Element["id"]) => Element<Record<string, unknown>>;
-    /** Every id currently in use, so a newly minted one stays unique across the document. */
-    takenIds: () => Set<string>;
-    /** Why an id cannot be used here (charset or a clash), or null when it is free. `ignoreElementId` exempts the
-     *  element being edited, so re-saving an element its own name is not a conflict. */
-    elementIdConflict: (id: string, ignoreElementId?: Element["id"]) => string | null;
+    /** Points a subtree at the root it now lives under, when a move took it into another page or layout. */
+    private carryRoot;
     /**
      * Copies a subtree onto fresh names.
      *
@@ -74,13 +78,6 @@ declare class FlatMap {
     updateVariable: (variable: SchemaVariable) => boolean;
     removeVariables: (variables: string[]) => boolean;
     removeVariable: (variable: string) => boolean;
-    /**
-     * Everything an element is rendered inside, nearest first — its ancestors, and past a root the shell that root is
-     * shown in. A layout names its own shell the way a page does, so the walk continues through as many as are nested;
-     * `visited` keeps a document whose shells name each other from walking forever.
-     */
-    parentTree: (elementId: Element["id"], visited?: Set<Element["id"]>) => string[];
-    childTree: (elementId: Element["id"]) => string[];
     isValidElement: (element?: Partial<Element>) => boolean;
     flatAsTemplate: (style: Style, elementId: Element["id"], excludeRoot?: boolean) => {
         elements: {
@@ -90,31 +87,21 @@ declare class FlatMap {
         elementsStyle: Style;
         variables: SchemaVariable[];
     };
-    validate: () => SchemaValidationResult;
-    isValid: () => boolean;
-    assertValid: (context?: string) => void;
     getElementVariables: (style: Style, elementId: Element["id"], flat?: Record<string, Element<Record<string, unknown>>>, variables?: SchemaVariable[]) => SchemaVariable[];
     static getInstance: (props: FlatMapProps) => FlatMap;
     static addElement: (flat: Schema["flat"], data: ElementInput, to: Element["id"], dropPosition?: DropPosition, initialItems?: Record<Element["id"], Element>) => boolean;
     static updateElement: (flat: Schema["flat"], element: Element) => boolean;
     static renameElement: (schema: Pick<Schema, "flat" | "pages">, from: Element["id"], to: Element["id"]) => false | string[];
     static moveElement: (flat: Schema["flat"], from: Element["id"], to: Element["id"], elementId: Element["id"], dropPosition?: DropPosition) => boolean;
-    static getElement: (flat: Schema["flat"], elementId: Element["id"]) => Element<Record<string, unknown>>;
     static cloneElements: (flat: Schema["flat"], elementId: Element["id"], parentId?: Element["id"], rootId?: Element["id"], excludeRoot?: boolean) => {
         acum: Record<Element["id"], Element>;
         item?: Element;
     };
     static removeElement: (flat: Schema["flat"], elementId: Element["id"], removePage?: boolean) => boolean;
-    static takenIds: (flat: Schema["flat"]) => Set<string>;
-    static elementIdConflict: (flat: Schema["flat"], id: string, ignoreElementId?: Element["id"]) => string | null;
     static addVariables: (schemaVariables: Schema["variables"], variables: Schema["variables"]) => boolean;
     static addVariable: (schemaVariables: Schema["variables"], variable: SchemaVariable) => boolean;
     static updateVariable: (schemaVariables: Schema["variables"], variable: SchemaVariable) => boolean;
-    static removeVariables: (schemaVariables: Schema["variables"], variables: string[]) => boolean;
     static removeVariable: (schemaVariables: Schema["variables"], variable: string) => boolean;
-    static parentTree: (flat: Schema["flat"], elementId: Element["id"]) => string[];
-    static childTree: (flat: Schema["flat"], elementId: Element["id"]) => string[];
-    static isValidElement: (flat: Schema["flat"], element: Element) => boolean;
     static flatAsTemplate: (schema: Schema, style: Style, elementId: Element["id"], excludeRoot?: boolean) => {
         elements: {
             acum: Record<Element["id"], Element>;
@@ -123,9 +110,5 @@ declare class FlatMap {
         elementsStyle: Style;
         variables: SchemaVariable[];
     };
-    static getElementVariables: (schema: Schema, style: Style, elementId: Element["id"]) => SchemaVariable[];
-    static validate: (schema: Schema) => SchemaValidationResult;
-    static isValid: (schema: Schema) => boolean;
-    static assertValid: (schema: Schema, context?: string) => void;
 }
 export default FlatMap;

package/dist/helpers/FlatMap.mjs

@@ -1,11 +1,10 @@
 import { elementIdConflict as e, elementIdsFree as t, randomElementId as n, repointIds as r, takenIds as i, uniqueElementId as a } from "./elementId.mjs";
-import { validateSchema as o } from "./schemaValidator.mjs";
-import { get as s, set as c } from "@plitzi/plitzi-ui/helpers";
-import { EMPTY_SCHEMA as l, VARIABLE_REGEX as u } from "@plitzi/sdk-shared/schema/schemaConstants";
-import { EMPTY_STYLE_SCHEMA as d } from "@plitzi/sdk-shared/style/styleConstants";
-import f from "@plitzi/sdk-style/helpers/calculateInheriting";
+import { descendants as o, parentChain as s } from "./elementTree.mjs";
+import { VARIABLE_REGEX as c } from "@plitzi/sdk-shared/schema/schemaConstants";
+import { EMPTY_STYLE_SCHEMA as l } from "@plitzi/sdk-shared/style/styleConstants";
+import u from "@plitzi/sdk-style/helpers/calculateInheriting";
 //#region src/helpers/FlatMap.ts
-var p = class {
+var d = class {
 	flat;
 	variables;
 	pages;
@@ -16,97 +15,55 @@ var p = class {
 		this.flat = t, this.variables = r ?? [], this.pages = i ?? [], this.mintId = a ?? n;
 	}
 	nextId = (e, t = () => !1) => {
-		let n = this.takenIds();
+		let n = i(this.flat);
 		return this.mintId(e, (e) => n.has(e) || t(e));
 	};
 	addElement = (e, n, r = "inside", i = {}) => {
 		let a = e.id ? e : {
 			...e,
 			id: this.nextId(e.definition.type)
-		}, o;
+		};
+		if (!this.isValidElement(a) || !t(this.flat, [a, ...Object.values(i)])) return !1;
 		if (r !== "custom") {
-			if (r !== "inside") {
-				let e = this.flat[n];
-				if (!e) return !1;
-				e.definition.parentId && (o = this.flat[e.definition.parentId]);
-			} else o = this.flat[n];
-			if (!o) return !1;
-		}
-		if (r !== "custom" && !Array.isArray(s(o, "definition.items")) || !this.isValidElement(a) || !t(this.flat, [a, ...Object.values(i)])) return !1;
-		switch (c(this.flat, a.id, a), r) {
-			case "left":
-			case "top": {
-				let e = s(o, "definition.items", []);
-				if (e.splice(e.findIndex((e) => e === n), 0, a.id), !o) return !1;
-				c(this.flat, `${o.id}.definition.items`, e), c(this.flat, `${a.id}.definition.parentId`, o.id), c(this.flat, `${a.id}.definition.rootId`, o.definition.rootId);
-				break;
-			}
-			case "right":
-			case "bottom": {
-				let e = s(o, "definition.items", []);
-				if (e.splice(e.findIndex((e) => e === n) + 1, 0, a.id), !o) return !1;
-				c(this.flat, `${o.id}.definition.items`, e), c(this.flat, `${a.id}.definition.parentId`, o.id), c(this.flat, `${a.id}.definition.rootId`, o.definition.rootId);
-				break;
-			}
-			case "inside": {
-				let e = s(o, "definition.items", []);
-				if (!o) return !1;
-				c(this.flat, `${n}.definition.items`, [...e, a.id]), c(this.flat, `${a.id}.definition.parentId`, n), c(this.flat, `${a.id}.definition.rootId`, o.definition.rootId);
-				break;
-			}
-			case "custom": break;
-			default: return !1;
-		}
-		return Object.keys(i).length > 0 && Object.keys(i).forEach((e) => {
-			this.flat[e] = i[e];
-		}), !0;
-	};
-	updateElement = (e) => !e || !this.flat[e.id] ? !1 : (this.flat[e.id] = e, !0);
-	renameElement = (t, n) => this.flat[t] ? t === n ? [] : !e(this.flat, n) && r(this.flat, { [t]: n }, this.pages) : !1;
-	renameConflict = (t, n) => e(this.flat, n, t);
-	moveElement = (e, t, n, r = "inside") => {
-		if (n === t || !this.flat[e]) return !1;
-		let i = this.flat[t];
-		if (!i) return !1;
-		let a = this.flat[t];
-		for (; a;) {
-			let e = s(a, "definition.parentId");
-			if (!e) break;
-			if (a.id === n) return !1;
-			a = this.flat[e];
+			let e = this.placement(n, r, [a.id]);
+			if (!e) return !1;
+			e.parent.definition.items = e.items, a.definition.parentId = e.parent.id, a.definition.rootId = e.parent.definition.rootId;
 		}
-		if (!a) return !1;
-		let o = s(this.flat, `${e}.definition.items`, []).filter((e) => e !== n);
-		if ([
+		return this.flat[a.id] = a, Object.assign(this.flat, i), !0;
+	};
+	placement = (e, t, n, r) => {
+		let i = this.flat[e], a = t === "inside" ? e : i?.definition.parentId, o = a ? this.flat[a] : void 0;
+		if (!i || !o?.definition.items) return null;
+		let s = o.definition.items.filter((e) => e !== r), c = t === "inside" ? s.length : s.indexOf(e);
+		return c < 0 || ![
+			"inside",
 			"left",
 			"top",
 			"right",
 			"bottom"
-		].includes(r)) {
-			if (!i.definition.parentId) return !1;
-			let a = this.flat[i.definition.parentId];
-			if (!a) return !1;
-			let l = s(a, "definition.items", []);
-			a.id === e && (l = o);
-			let u = l.findIndex((e) => e === t);
-			["right", "bottom"].includes(r) && u++, l.splice(u, 0, n), c(this.flat, `${e}.definition.items`, o), c(this.flat, `${a.id}.definition.items`, l), c(this.flat, `${n}.definition.parentId`, a.id);
-		} else if (r === "inside") {
-			if (!this.flat[t]) return !1;
-			let r = s(this.flat, `${t}.definition.items`, []);
-			e === t && (r = o), r = [...r, n], c(this.flat, `${e}.definition.items`, o), c(this.flat, `${t}.definition.items`, r), c(this.flat, `${n}.definition.parentId`, t);
-		}
-		return !0;
+		].includes(t) ? null : (s.splice(t === "right" || t === "bottom" ? c + 1 : c, 0, ...n), {
+			parent: o,
+			items: s
+		});
 	};
-	getElement = (e) => s(this.flat, e);
-	takenIds = () => i(this.flat);
-	elementIdConflict = (t, n) => e(this.flat, t, n);
-	cloneElements = (e, t = "", n = "", i = !1) => {
-		let o = {
+	updateElement = (e) => !e || !this.flat[e.id] ? !1 : (this.flat[e.id] = e, !0);
+	renameElement = (t, n) => this.flat[t] ? t === n ? [] : !e(this.flat, n) && r(this.flat, { [t]: n }, this.pages) : !1;
+	moveElement = (e, t, n, r = "inside") => {
+		let i = this.flat[e], a = this.flat[n];
+		if (!i || !a || n === t || s(this.flat, t).includes(n)) return !1;
+		let o = this.placement(t, r, [n], n);
+		return o ? (i.definition.items = (i.definition.items ?? []).filter((e) => e !== n), o.parent.definition.items = o.items, a.definition.parentId = o.parent.id, this.carryRoot(n, o.parent.definition.rootId), !0) : !1;
+	};
+	carryRoot = (e, t) => {
+		if (this.flat[e].definition.rootId !== t) for (let n of [e, ...o(this.flat, e)]) this.flat[n].definition.rootId = t;
+	};
+	cloneElements = (e, t = "", n = "", s = !1) => {
+		let c = {
 			acum: {},
 			item: void 0
 		}, l = {}, u = this.flat[e];
-		if (!u) return o;
-		let d = [e, ...this.childTree(e)].filter((e) => this.flat[e] !== void 0), f = this.takenIds();
+		if (!u) return c;
+		let d = [e, ...o(this.flat, e)], f = i(this.flat);
 		for (let e of d) {
 			let t = a(e, (e) => f.has(e));
 			f.add(t), l[e] = t;
@@ -116,21 +73,16 @@ var p = class {
 			let t = structuredClone(this.flat[e]);
 			n && (t.definition.rootId = n), p[e] = t;
 		}
-		r(p, l), o.acum = p, o.item = p[l[e]], i && delete o.acum[l[e]];
+		r(p, l), c.acum = p, c.item = p[l[e]], s && delete c.acum[l[e]];
 		let m = this.flat[t];
-		return (!m || !Array.isArray(s(m, "definition.items"))) && (t = s(m, "definition.parentId", s(u, "definition.parentId"))), t && c(o, "item.definition.parentId", t), o;
+		return m?.definition.items || (t = m?.definition.parentId ?? u.definition.parentId ?? ""), t && (c.item.definition.parentId = t), c;
 	};
 	removeElement = (e, t = !1) => {
 		let n = this.flat[e];
-		if (!n || n.definition.type === "page" && !t || t && s(n, "attributes.default", !1)) return !1;
-		let r = s(n, "definition.items");
-		r && r.length > 0 && r.forEach((e) => this.removeElement(e));
-		let i = s(n, "definition.parentId"), a = i ? this.flat[i] : void 0;
-		if (i && a) {
-			let { definition: { items: t = [] } } = a;
-			c(a, "definition.items", t.filter((t) => t !== e)), this.flat[i] = a;
-		}
-		return delete this.flat[e], !0;
+		if (!n || n.definition.type === "page" && !t || t && n.attributes.default) return !1;
+		for (let t of o(this.flat, e)) delete this.flat[t];
+		let r = n.definition.parentId ? this.flat[n.definition.parentId] : void 0;
+		return r?.definition.items && (r.definition.items = r.definition.items.filter((t) => t !== e)), delete this.flat[e], !0;
 	};
 	addVariables = (e) => {
 		if (e && e.length > 0) {
@@ -151,26 +103,6 @@ var p = class {
 		return this.variables = this.variables.filter((t) => e.includes(t.name)), t !== this.variables.length;
 	};
 	removeVariable = (e) => this.removeVariables([e]);
-	parentTree = (e, t = /* @__PURE__ */ new Set()) => {
-		let n = this.flat[e], r = [];
-		if (!n) return r;
-		do {
-			let i = s(n, "definition.type");
-			if ((i === "page" || i === "layoutContainer") && !t.has(n.id)) {
-				t.add(n.id);
-				let e = s(n, "attributes.layout"), i = s(n, "attributes.layoutContainer");
-				e && i && r.push(i, ...this.parentTree(i, t));
-			}
-			e !== n.id && r.push(n.id), n = s(this.flat, s(n, "definition.parentId"), void 0);
-		} while (n);
-		return r;
-	};
-	childTree = (e) => {
-		let t = this.flat[e];
-		if (!t) return [];
-		let n = [], r = s(t, "definition.items");
-		return r && r.forEach((e) => n.push(e, ...this.childTree(e))), n;
-	};
 	isValidElement = (e) => {
 		if (!e) return !1;
 		let { id: t, attributes: n, definition: r } = e;
@@ -180,7 +112,7 @@ var p = class {
 	};
 	flatAsTemplate = (e, t, n = !1) => {
 		let r = {
-			...d,
+			...l,
 			platform: {
 				desktop: {},
 				tablet: {},
@@ -195,7 +127,7 @@ var p = class {
 			elementsStyle: r,
 			variables: i
 		};
-		let a = s(this.flat, t);
+		let a = this.flat[t];
 		if (!a) return {
 			elements: {
 				acum: {},
@@ -207,14 +139,14 @@ var p = class {
 		let o = this.cloneElements(t, a.definition.parentId);
 		return o.item ? (Object.values(o.acum).forEach((t) => {
 			let { id: n } = t;
-			if (c(o.acum, `${n}.definition.rootId`, o.item?.id), f(t, t.definition.type, this.flat, e.platform, {}, { includeSelf: !0 }).tree.forEach((t) => {
+			if (o.item && (t.definition.rootId = o.item.id), u(t, t.definition.type, this.flat, e.platform, {}, { includeSelf: !0 }).tree.forEach((t) => {
 				let { displayMode: n, name: i } = t;
 				!(i in r.platform[n]) && i in e.platform[n] && (r.platform[n][i] = e.platform[n][i]);
 			}), this.variables.length > 0) {
 				let t = this.getElementVariables(e, n, o.acum);
 				i = [...i, ...t];
 			}
-		}), c(o.acum, `${o.item.id}.definition.parentId`, null), n && delete o.acum[o.item.id], i.length > 1 && (i = [...new Set(i)]), {
+		}), delete o.acum[o.item.id].definition.parentId, n && delete o.acum[o.item.id], i.length > 1 && (i = [...new Set(i)]), {
 			elements: o,
 			elementsStyle: r,
 			variables: i
@@ -227,27 +159,10 @@ var p = class {
 			variables: i
 		};
 	};
-	validate = () => o({
-		...l.schema,
-		flat: this.flat,
-		variables: this.variables
-	});
-	isValid = () => this.validate().valid;
-	assertValid = (e) => {
-		let t = o({
-			...l.schema,
-			flat: this.flat,
-			variables: this.variables
-		});
-		if (!t.valid) {
-			let n = `Invalid schema${e ? ` (${e})` : ""}: ${t.errors.map((e) => e.message).join("; ")}`;
-			throw Error(n);
-		}
-	};
 	getElementVariables = (e, t, n = this.flat, r = this.variables) => {
-		let i = [], a = s(n, `${t}.definition.styleSelectors`);
+		let i = [], a = n[t]?.definition.styleSelectors;
 		if (!a) return i;
-		let o = new RegExp(u, "g");
+		let o = new RegExp(c, "g");
 		return Object.values(a).filter(Boolean).forEach((t) => {
 			Object.values(e.platform).forEach((e) => {
 				let n = e[t];
@@ -266,19 +181,12 @@ var p = class {
 		pages: e.pages
 	}).renameElement(t, n);
 	static moveElement = (e, t, n, r, i = "inside") => this.getInstance({ flat: e }).moveElement(t, n, r, i);
-	static getElement = (e, t) => this.getInstance({ flat: e }).getElement(t);
 	static cloneElements = (e, t, n = "", r = "", i = !1) => this.getInstance({ flat: e }).cloneElements(t, n, r, i);
 	static removeElement = (e, t, n = !1) => this.getInstance({ flat: e }).removeElement(t, n);
-	static takenIds = (e) => this.getInstance({ flat: e }).takenIds();
-	static elementIdConflict = (e, t, n) => this.getInstance({ flat: e }).elementIdConflict(t, n);
 	static addVariables = (e, t) => this.getInstance({ variables: e }).addVariables(t);
 	static addVariable = (e, t) => this.getInstance({ variables: e }).addVariable(t);
 	static updateVariable = (e, t) => this.getInstance({ variables: e }).updateVariable(t);
-	static removeVariables = (e, t) => this.getInstance({ variables: e }).removeVariables(t);
 	static removeVariable = (e, t) => this.getInstance({ variables: e }).removeVariable(t);
-	static parentTree = (e, t) => this.getInstance({ flat: e }).parentTree(t);
-	static childTree = (e, t) => this.getInstance({ flat: e }).childTree(t);
-	static isValidElement = (e, t) => this.getInstance({ flat: e }).isValidElement(t);
 	static flatAsTemplate = (e, t, n, r = !1) => {
 		let { flat: i, variables: a } = e;
 		return this.getInstance({
@@ -286,22 +194,6 @@ var p = class {
 			variables: a
 		}).flatAsTemplate(t, n, r);
 	};
-	static getElementVariables = (e, t, n) => {
-		let { flat: r, variables: i } = e;
-		return this.getInstance({
-			flat: r,
-			variables: i
-		}).getElementVariables(t, n);
-	};
-	static validate = (e) => o(e);
-	static isValid = (e) => o(e).valid;
-	static assertValid = (e, t) => {
-		let n = o(e);
-		if (!n.valid) {
-			let e = `Invalid schema${t ? ` (${t})` : ""}: ${n.errors.map((e) => e.message).join("; ")}`;
-			throw Error(e);
-		}
-	};
 };
 //#endregion
-export { p as default };
+export { d as default };

package/dist/helpers/elementTree.d.ts

@@ -0,0 +1,44 @@
+import { Element, Schema } from '@plitzi/sdk-shared';
+/**
+ * The flat schema, typed as it actually behaves: a `parentId` or an item can name an element the document no longer
+ * has, and every walk here has to survive that. `Record<string, Element>` would call those checks dead code.
+ */
+type Flat = Schema['flat'] | Record<string, Element | undefined>;
+/**
+ * The elements `id` is nested in, nearest first, up to its page or layout root.
+ *
+ * The tree as it is stored — no layout crossed. What the builder opens to reveal an element, and what "inside a list"
+ * means for an author. A schema edited by two people at once can briefly describe a cycle, so every id is visited once.
+ */
+export declare const parentChain: (flat: Flat, id: string) => string[];
+/**
+ * Everything an element renders inside, nearest first: its ancestors and, past a page or a layout that is shown in a
+ * layout, the container that shell renders it in and that container's own ancestors — through as many layouts as are
+ * nested.
+ *
+ * What the runtime walks to decide which data sources an element sees, so it is what any check of that — the linter's
+ * scope rules — has to walk too. A provider elsewhere in the layout, beside the slot rather than around it, is not in
+ * it.
+ */
+export declare const renderContext: (flat: Flat, id: string) => string[];
+/** Every element under `id`, depth first in document order. Items that name nothing are skipped; a cycle is walked once. */
+export declare const descendants: (flat: Flat, id: string) => string[];
+/** What the author calls a page or layout: its `name`, else its label, else the id when the root is not in `flat`. */
+export declare const rootName: (flat: Flat, rootId: string) => string;
+/** One root of a schema — a page, or a layout several pages render inside — and how many elements it holds. */
+export type RootElements = {
+    /** What the author called it (`rootName`). */
+    page: string;
+    elements: number;
+};
+/**
+ * The element count, grouped by the root each element names (`definition.rootId`), heaviest first. `only` narrows it
+ * to the elements it accepts — where a plugin is used, say — still named after the page or layout that holds them.
+ *
+ * Unnarrowed it is a grouping, not a second measurement: it always adds up to the number of elements in `flat`, so the
+ * builder's live meter and the API's usage panel agree with the count the element ceilings are judged on. Layouts are
+ * roots too and are listed as themselves rather than shared out over the pages that render inside them — their
+ * elements are authored once, and splitting them between pages would report a total that no page has.
+ */
+export declare const elementsByRoot: (flat: Flat, only?: (element: Element) => boolean) => RootElements[];
+export {};

package/dist/helpers/elementTree.mjs

@@ -0,0 +1,41 @@
+//#region src/helpers/elementTree.ts
+var e = (e, t) => t && Object.hasOwn(e, t) ? e[t] : void 0, t = (t, n) => {
+	let r = [], i = /* @__PURE__ */ new Set([n]);
+	for (let a = e(t, e(t, n)?.definition.parentId); a && !i.has(a.id);) i.add(a.id), r.push(a.id), a = e(t, a.definition.parentId);
+	return r;
+}, n = (n, r) => {
+	let i = [], a = /* @__PURE__ */ new Set([r]), o = (s) => {
+		for (let c of [s, ...t(n, s)]) {
+			let t = e(n, c);
+			if (c !== s || s !== r) {
+				if (a.has(c)) continue;
+				a.add(c), i.push(c);
+			}
+			let l = t?.definition.type, { layout: u, layoutContainer: d } = t?.attributes ?? {};
+			(l === "page" || l === "layoutContainer") && u && typeof d == "string" && !a.has(d) && o(d);
+		}
+	};
+	return o(r), i;
+}, r = (t, n) => {
+	let r = [], i = /* @__PURE__ */ new Set([n]), a = (n) => {
+		for (let o of e(t, n)?.definition.items ?? []) !i.has(o) && e(t, o) && (i.add(o), r.push(o), a(o));
+	};
+	return a(n), r;
+}, i = (t, n) => {
+	let r = e(t, n);
+	if (!r) return n;
+	let { name: i } = r.attributes;
+	return typeof i == "string" && i ? i : r.definition.label;
+}, a = (e, t = () => !0) => {
+	let n = /* @__PURE__ */ new Map();
+	for (let r of Object.values(e)) if (r && t(r)) {
+		let e = r.definition.rootId;
+		n.set(e, (n.get(e) ?? 0) + 1);
+	}
+	return [...n.entries()].map(([t, n]) => ({
+		page: i(e, t),
+		elements: n
+	})).sort((e, t) => t.elements - e.elements);
+};
+//#endregion
+export { r as descendants, a as elementsByRoot, t as parentChain, n as renderContext, i as rootName };

package/dist/helpers/schemaValidator.d.ts

@@ -21,6 +21,18 @@ export type SchemaValidationResult = {
     errors: SchemaValidationError[];
     warnings: SchemaValidationError[];
 };
+/**
+ * The errors that are a reference to something no longer there, rather than the document being broken.
+ *
+ * An editor produces them in the ordinary course of editing: delete a provider and the binding that read it names
+ * nothing, delete an element and the step aimed at it has no target. The next edit is what settles them — rebind, or
+ * drop the step — so a writer that edits one change at a time reports them and refuses them only when the space is
+ * about to be served. Every other error is the tree itself broken — an orphan, a cycle, two ids for one element — and
+ * no sequence of edits should ever leave one behind.
+ */
+export declare const REFERENCE_ERROR_CODES: ReadonlySet<string>;
+/** Whether an error is the document itself being broken, as opposed to a reference an edit left dangling. */
+export declare const isIntegrityError: (error: SchemaValidationError) => boolean;
 export declare const validateSchema: (schema: Schema, options?: SchemaValidationOptions) => SchemaValidationResult;
 export declare const assertSchemaValid: (schema: Schema, options?: SchemaValidationOptions, context?: string) => void;
 export declare const isSchemaValid: (schema: Schema, options?: SchemaValidationOptions) => boolean;

package/dist/helpers/schemaValidator.mjs

@@ -1,7 +1,11 @@
 import { isValidElementId as e } from "./elementId.mjs";
 import { findLayoutCycle as t } from "@plitzi/sdk-shared/schema/layoutChain";
 //#region src/helpers/schemaValidator.ts
-var n = (n) => {
+var n = /* @__PURE__ */ new Set([
+	"UNRESOLVED_BINDING_SOURCE",
+	"MISMATCHED_BINDING_SOURCE",
+	"UNRESOLVED_INTERACTION_TARGET"
+]), r = (e) => !n.has(e.code), i = (n) => {
 	let r = [], i = [], { flat: a, pages: o, pageFolders: s, variables: c } = n, l = (e) => !!a[e], u = (e) => a[e], d = () => Object.values(a).filter((e) => e?.definition?.type === "layoutContainer" && !e.definition.parentId).map((e) => e.id), f = () => [...o, ...d()], p = () => !a || typeof a != "object" ? (r.push({
 		code: "INVALID_FLAT",
 		message: "Schema.flat must be a valid Record<string, Element>"
@@ -389,12 +393,12 @@ var n = (n) => {
 			warnings: i
 		};
 	} };
-}, r = (e, t) => n(e).validate(t), i = (e, t, n) => {
-	let i = r(e, t);
-	if (!i.valid) {
-		let e = `Invalid schema${n ? ` (${n})` : ""}: ${i.errors.map((e) => e.message).join("; ")}`;
+}, a = (e, t) => i(e).validate(t), o = (e, t, n) => {
+	let r = a(e, t);
+	if (!r.valid) {
+		let e = `Invalid schema${n ? ` (${n})` : ""}: ${r.errors.map((e) => e.message).join("; ")}`;
 		throw Error(e);
 	}
-}, a = (e, t) => r(e, t).valid;
+}, s = (e, t) => a(e, t).valid;
 //#endregion
-export { i as assertSchemaValid, a as isSchemaValid, r as validateSchema };
+export { n as REFERENCE_ERROR_CODES, o as assertSchemaValid, r as isIntegrityError, s as isSchemaValid, a as validateSchema };

package/dist/helpers/styleWithoutTag.d.ts

@@ -1,4 +1,9 @@
 import { Element, Style } from '@plitzi/sdk-shared';
+/**
+ * Whether an element renders no element of its own — an `apiContainer` with no `subType`, the builder's "Container
+ * Tag: None". Its children sit straight in its parent, so it has no box: nothing to style, and nothing a test can see.
+ */
+export declare const rendersNoTag: (element: Pick<Element, "attributes" | "definition">) => boolean;
 /**
  * Why an element's style applies to nothing, if it does not.
  *

package/dist/helpers/styleWithoutTag.mjs

@@ -1,10 +1,11 @@
 //#region src/helpers/styleWithoutTag.ts
-var e = (e) => Object.keys(e ?? {}).length > 0, t = (t) => Object.values(t ?? {}).some(e), n = (n) => e(n.default) || t(n.states) || Object.values(n.variants ?? {}).some((n) => e(n.default) || t(n.states)), r = (e, t) => Object.values(e.platform).some((e) => Object.hasOwn(e, t) && Object.values(e[t].attributes).some(n)), i = (e, t) => {
-	if (e.definition.type !== "apiContainer") return;
-	let n = e.attributes.subType;
-	if (typeof n == "string" && n !== "") return;
-	let { styleSelectors: i, initialState: a, bindings: o } = e.definition, s = Object.values(i).some((e) => e.split(" ").some((e) => e && r(t, e))), c = Object.keys(a?.styleVariant ?? {}).length > 0, l = (o?.style?.length ?? 0) > 0;
+var e = (e) => Object.keys(e ?? {}).length > 0, t = (t) => Object.values(t ?? {}).some(e), n = (n) => e(n.default) || t(n.states) || Object.values(n.variants ?? {}).some((n) => e(n.default) || t(n.states)), r = (e, t) => Object.values(e.platform).some((e) => Object.hasOwn(e, t) && Object.values(e[t].attributes).some(n)), i = (e) => {
+	let t = e.attributes.subType;
+	return e.definition.type === "apiContainer" && (typeof t != "string" || t === "");
+}, a = (e, t) => {
+	if (!i(e)) return;
+	let { styleSelectors: n, initialState: a, bindings: o } = e.definition, s = Object.values(n).some((e) => e.split(" ").some((e) => e && r(t, e))), c = Object.keys(a?.styleVariant ?? {}).length > 0, l = (o?.style?.length ?? 0) > 0;
 	if (s || c || l) return "has style but no `subType` (container tag), so it renders no element of its own and the style applies to nothing — its children lay out in its parent. Give it a tag (a `subType` of `div`, `section`, …) or move the style onto its parent or a child.";
 };
 //#endregion
-export { i as styleWithoutTag };
+export { i as rendersNoTag, a as styleWithoutTag };

package/dist/index.d.ts

@@ -2,5 +2,6 @@ import { default as FlatMap } from './helpers/FlatMap';
 import { default as SchemaReducer } from './SchemaReducer';
 export * from './SchemaReducer';
 export * from './helpers/FlatMap';
+export * from './helpers/elementTree';
 export * from './helpers/schemaValidator';
 export { FlatMap, SchemaReducer };

package/dist/index.mjs

@@ -1,4 +1,5 @@
-import { assertSchemaValid as e, isSchemaValid as t, validateSchema as n } from "./helpers/schemaValidator.mjs";
-import r from "./helpers/FlatMap.mjs";
-import i, { SchemaActions as a } from "./SchemaReducer.mjs";
-export { r as FlatMap, a as SchemaActions, i as SchemaReducer, e as assertSchemaValid, t as isSchemaValid, n as validateSchema };
+import { descendants as e, elementsByRoot as t, parentChain as n, renderContext as r, rootName as i } from "./helpers/elementTree.mjs";
+import a from "./helpers/FlatMap.mjs";
+import o, { SchemaActions as s } from "./SchemaReducer.mjs";
+import { REFERENCE_ERROR_CODES as c, assertSchemaValid as l, isIntegrityError as u, isSchemaValid as d, validateSchema as f } from "./helpers/schemaValidator.mjs";
+export { a as FlatMap, c as REFERENCE_ERROR_CODES, s as SchemaActions, o as SchemaReducer, l as assertSchemaValid, e as descendants, t as elementsByRoot, u as isIntegrityError, d as isSchemaValid, n as parentChain, r as renderContext, i as rootName, f as validateSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-schema",
-  "version": "0.37.2",
+  "version": "0.37.4",
   "license": "AGPL-3.0",
   "files": [
     "dist"
@@ -22,6 +22,10 @@
       "types": "./dist/helpers/elementId.d.ts",
       "import": "./dist/helpers/elementId.mjs"
     },
+    "./helpers/elementTree": {
+      "types": "./dist/helpers/elementTree.d.ts",
+      "import": "./dist/helpers/elementTree.mjs"
+    },
     "./helpers/schemaValidator": {
       "types": "./dist/helpers/schemaValidator.d.ts",
       "import": "./dist/helpers/schemaValidator.mjs"
@@ -48,15 +52,15 @@
     "build:prod": "vite build && node ../sdk-shared/scripts/generate-exports.mjs"
   },
   "dependencies": {
-    "@plitzi/plitzi-ui": "^1.6.22",
-    "@plitzi/sdk-shared": "0.37.2",
-    "@plitzi/sdk-style": "0.37.2",
+    "@plitzi/plitzi-ui": "^1.6.24",
+    "@plitzi/sdk-shared": "0.37.4",
+    "@plitzi/sdk-style": "0.37.4",
     "prop-types": "^15.8.1"
   },
   "devDependencies": {
     "eslint": "^9.39.5",
     "typescript": "^6.0.3",
-    "vite": "^8.3.0",
+    "vite": "^8.3.1",
     "vitest": "^5.0.1"
   }
 }