@plitzi/sdk-schema 0.37.8 → 0.37.9

package/dist/helpers/components.d.ts

@@ -0,0 +1,68 @@
+import { default as FlatMap } from './FlatMap';
+import { MintElementId } from './elementId';
+import { Element, Schema, SpaceComponent, SpaceComponentDeclaration } from '@plitzi/sdk-shared';
+/** The parts of a schema that hold elements: the pages' tree and every component's. */
+export type ElementDocument = Pick<Schema, 'flat' | 'pages' | 'components'>;
+/** One tree of a document: the space's own `flat`, or the one of the component named. */
+export type ElementTree = {
+    flat: Schema['flat'];
+    componentId?: SpaceComponent['id'];
+};
+/**
+ * Attributes an instance already answers to, so a prop may not be called one of them: a prop IS an attribute of the
+ * instance, and a prop named `referenceId` would be the instance pointing at another component.
+ */
+export declare const RESERVED_PROP_NAMES: ReadonlySet<string>;
+/** Why `name` cannot be a prop, phrased for a person, or null when it can. */
+export declare const propNameProblem: (name: string) => string | null;
+export declare const treesOf: (schema: Pick<Schema, "flat" | "components">) => ElementTree[];
+/** The tree `id` lives in. Ids are one namespace across the document, so there is at most one. */
+export declare const treeOf: (schema: Pick<Schema, "flat" | "components">, id: Element["id"]) => ElementTree | undefined;
+/** Every element id the document holds, in any tree. */
+export declare const documentIds: (schema: Pick<Schema, "flat" | "components">) => Set<Element["id"]>;
+/**
+ * A `FlatMap` over the tree that holds `id`, held to the ids every other tree holds.
+ *
+ * What lets an element edit carry nothing but the element: its id already says which tree it is in, so the writers
+ * of a space — the builder's reducer and the server's model — resolve the tree here and edit it as they always have.
+ */
+export declare const flatMapOf: (schema: ElementDocument, id: Element["id"], mintId?: MintElementId) => FlatMap | undefined;
+/** The component declared under `componentId`, if any: a key read off a document cannot be trusted to be there. */
+export declare const componentNamed: (schema: Pick<Schema, "components">, componentId: SpaceComponent["id"]) => SpaceComponent | undefined;
+/** Whether `element` is an instance — of `componentId`, when one is named. */
+export declare const isInstance: (element: Element, componentId?: SpaceComponent["id"]) => boolean;
+/** Every instance of a component, wherever it is placed: on a page, in a layout or inside another component. */
+export declare const instancesOf: (schema: Pick<Schema, "flat" | "components">, componentId: SpaceComponent["id"]) => Element[];
+/**
+ * Renames an element wherever it is, carrying every reference to it — in any tree.
+ *
+ * The element's own tree is rewritten by `FlatMap`, as a rename always was; the others are rewritten too, because a
+ * page can name an element of a component as little as a component can name a page, and the declarations name their
+ * roots and slots. Returns the ids of everything it touched, under their new names.
+ */
+export declare const renameElement: (schema: ElementDocument, from: Element["id"], to: Element["id"]) => Element["id"][] | false;
+/**
+ * Declares a component.
+ *
+ * With `from`, the component is made OF an element already in the document: the subtree leaves its tree for the
+ * component's, and an instance named `from.instanceId` takes its place, so the page renders what it rendered. Without
+ * it, the component brings its own tree. Both sides of a live document apply the same call and arrive at the same
+ * document, which is why the instance's name is the caller's to give. Returns false, changing nothing, when the
+ * component cannot be declared — a name taken, a tree that is not one, a declaration its tree does not bear out.
+ */
+export declare const addComponent: (schema: ElementDocument, component: SpaceComponent, from?: {
+    elementId: Element["id"];
+    instanceId: Element["id"];
+}) => boolean;
+/** Changes what a component declares — never its tree, which is edited element by element like any other. */
+export declare const updateComponent: (schema: Pick<Schema, "components">, componentId: SpaceComponent["id"], declaration: SpaceComponentDeclaration) => boolean;
+/** Removes a component nothing places any more. One still placed is refused: its instances would render nothing. */
+export declare const removeComponent: (schema: Pick<Schema, "flat" | "components">, componentId: SpaceComponent["id"]) => boolean;
+/**
+ * Replaces an instance with a copy of what its component renders, which is then the page's own to edit.
+ *
+ * The copy takes names derived from the component's (`card` → `card-2`), each the first one free in the document,
+ * so every side of a live document that applies it arrives at the same names. What filled the instance's slots goes
+ * into the copies of those slots. Refused when a child has no slot to go to. Returns the copy's root id.
+ */
+export declare const detachInstance: (schema: ElementDocument, instanceId: Element["id"]) => Element["id"] | false;

package/dist/helpers/components.mjs

@@ -0,0 +1,130 @@
+import { isValidElementId as e, repointIds as t, uniqueElementId as n } from "./elementId.mjs";
+import { descendants as r } from "./elementTree.mjs";
+import i from "./FlatMap.mjs";
+import { jsonCopy as a } from "@plitzi/sdk-shared/history";
+//#region src/helpers/components.ts
+var o = /* @__PURE__ */ new Set([
+	"referenceType",
+	"referenceId",
+	"slot",
+	"className",
+	"style",
+	"children",
+	"ref",
+	"id"
+]), s = /^[A-Za-z][A-Za-z0-9_]*$/, c = (e) => s.test(e) ? o.has(e) ? `"${e}" is an attribute every instance already has` : null : `"${e}" is not a valid prop name: start with a letter, then letters, numbers and underscores — it is read as {{ props.${e} }}`, l = (e) => [{ flat: e.flat }, ...Object.values(e.components).map((e) => ({
+	flat: e.flat,
+	componentId: e.id
+}))], u = (e, t) => l(e).find((e) => Object.hasOwn(e.flat, t)), d = (e) => new Set(l(e).flatMap((e) => Object.keys(e.flat))), f = (e, t, n) => {
+	let r = u(e, t);
+	if (!r) return;
+	let a = l(e).filter((e) => e.flat !== r.flat);
+	return new i({
+		flat: r.flat,
+		pages: r.componentId ? void 0 : e.pages,
+		mintId: n,
+		takenElsewhere: (e) => a.some((t) => Object.hasOwn(t.flat, e))
+	});
+}, p = (e, t) => Object.hasOwn(e.components, t) ? e.components[t] : void 0, m = (e, t) => e.definition.type === "reference" && e.attributes.referenceType === "component" && (t === void 0 || e.attributes.referenceId === t), h = (e, t) => l(e).flatMap((e) => Object.values(e.flat).filter((e) => m(e, t))), g = (e, n, r) => {
+	let i = f(e, n);
+	if (!i) return !1;
+	let a = i.renameElement(n, r);
+	if (!a || n === r) return a;
+	for (let o of l(e)) o.flat !== i.flat && a.push(...t(o.flat, { [n]: r }));
+	for (let t of Object.values(e.components)) t.rootId === n && (t.rootId = r), t.slots?.includes(n) && (t.slots = t.slots.map((e) => e === n ? r : e));
+	return [...new Set(a)];
+}, _ = (e, t) => {
+	for (let t of Object.keys(e.props ?? {})) {
+		let e = c(t);
+		if (e) return e;
+	}
+	let n = (e.slots ?? []).find((e) => !Object.hasOwn(t, e));
+	return n ? `slot "${n}" is not an element of the component` : null;
+}, v = (e, t, n) => ({
+	id: t,
+	attributes: {
+		referenceType: "component",
+		referenceId: e.id
+	},
+	definition: {
+		label: e.label ?? e.id,
+		type: "reference",
+		items: [],
+		bindings: {},
+		parentId: n.definition.parentId,
+		rootId: n.definition.rootId,
+		styleSelectors: { base: "" },
+		initialState: { visibility: !0 }
+	}
+}), y = (t, n, i) => {
+	if (!e(n.id) || Object.hasOwn(t.components, n.id)) return !1;
+	if (!i) {
+		let e = n.flat[n.rootId], r = d(t);
+		return !e || e.definition.parentId || Object.keys(n.flat).some((e) => r.has(e)) || _(n, n.flat) ? !1 : (t.components[n.id] = n, !0);
+	}
+	let { elementId: a, instanceId: o } = i, s = u(t, a), c = s?.flat[a], l = c?.definition.parentId ? s?.flat[c.definition.parentId] : void 0;
+	if (!s || !c || !l?.definition.items || !e(o) || d(t).has(o)) return !1;
+	let f = {};
+	for (let e of [a, ...r(s.flat, a)]) {
+		let { parentId: t, ...n } = s.flat[e].definition;
+		f[e] = {
+			...s.flat[e],
+			definition: {
+				...n,
+				...e === a ? {} : { parentId: t },
+				rootId: a
+			}
+		};
+	}
+	let p = {
+		...n,
+		rootId: a,
+		flat: f
+	};
+	if (_(p, f)) return !1;
+	for (let e of Object.keys(f)) delete s.flat[e];
+	return s.flat[o] = v(p, o, c), l.definition.items = l.definition.items.map((e) => e === a ? o : e), t.components[p.id] = p, !0;
+}, b = (e, t, n) => {
+	let r = p(e, t);
+	return !r || _({
+		...r,
+		...n
+	}, r.flat) ? !1 : (e.components[t] = {
+		...r,
+		...n
+	}, !0);
+}, x = (e, t) => !Object.hasOwn(e.components, t) || h(e, t).length > 0 ? !1 : (delete e.components[t], !0), S = (e, i) => {
+	let o = u(e, i), s = o?.flat[i], { referenceId: c } = s?.attributes ?? {}, l = s && m(s) && typeof c == "string" ? p(e, c) : void 0, f = s?.definition.parentId ? o?.flat[s.definition.parentId] : void 0;
+	if (!o || !s || !l || !f?.definition.items) return !1;
+	let h = s.definition.items ?? [], g = (e) => {
+		let { slot: t } = o.flat[e].attributes;
+		return typeof t == "string" ? t : l.slots?.[0];
+	};
+	if (h.some((e) => !l.slots?.includes(g(e) ?? ""))) return !1;
+	let _ = d(e);
+	_.delete(i);
+	let v = [l.rootId, ...r(l.flat, l.rootId)], y = {};
+	for (let e of v) y[e] = n(e, (e) => _.has(e)), _.add(y[e]);
+	let b = {};
+	for (let e of v) {
+		let t = a(l.flat[e]);
+		t.definition.rootId = s.definition.rootId, b[e] = t;
+	}
+	t(b, y);
+	let x = b[y[l.rootId]];
+	x.definition.parentId = s.definition.parentId;
+	for (let e of h) {
+		let t = b[y[g(e) ?? ""]], n = o.flat[e], { slot: r, ...i } = n.attributes;
+		o.flat[e] = {
+			...n,
+			attributes: i,
+			definition: {
+				...n.definition,
+				parentId: t.id
+			}
+		}, t.definition.items = [...t.definition.items ?? [], e];
+	}
+	return Object.assign(o.flat, b), delete o.flat[i], f.definition.items = f.definition.items.map((e) => e === i ? x.id : e), x.id;
+};
+//#endregion
+export { o as RESERVED_PROP_NAMES, y as addComponent, p as componentNamed, S as detachInstance, d as documentIds, f as flatMapOf, h as instancesOf, m as isInstance, c as propNameProblem, x as removeComponent, g as renameElement, u as treeOf, l as treesOf, b as updateComponent };

package/dist/helpers/elementId.d.ts

@@ -11,9 +11,9 @@ export declare const isValidElementId: (id: string) => boolean;
  *  collapse, and a leading non-letter is dropped — so a name is editable as prose in the builder's tree and still
  *  lands as a valid key. Empty when nothing usable survives, which the caller reports rather than storing. */
 export declare const slugifyElementId: (value: string) => string;
-/** Every id currently in use, so a new one can be checked or minted against it. Uniqueness is per DOCUMENT — a
- *  space schema, and each segment separately — which is what makes a lookup a `flat` key access. A segment used on
- *  several pages repeats its ids in the rendered tree; `rootId`/`referenceId` are what tell those apart. */
+/** Every id in use in one tree, so a new one can be checked or minted against it. Uniqueness spans the DOCUMENT —
+ *  the space's `flat` and every component's (`documentIds`) — which is what makes a lookup a `flat` key access. A
+ *  component placed several times repeats its ids in the rendered tree; each instance's scope tells those apart. */
 export declare const takenIds: (flat: Record<Element["id"], Element>) => Set<string>;
 /** Why `id` cannot be used in this document, phrased for a person, or null when it is free and well formed.
  *  `ignoreElementId` exempts the element being edited, so re-saving an element its own id is not a conflict. */

package/dist/helpers/elementId.mjs

@@ -78,6 +78,8 @@ var e = /^[A-Za-z](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?$/, t = (t) => e.test(t), n = (
 			let r = o[n];
 			typeof r == "string" && t[r] && (!i || i(o)) && (o[n] = t[r], e = !0);
 		}
+		let { slot: s } = o;
+		typeof s == "string" && t[s] && (o.slot = t[s], e = !0);
 		for (let n of Object.values(r.bindings ?? {})) for (let r of n) {
 			let n = p(r.source, t);
 			n !== r.source && (r.source = n, e = !0), r.transformers && g(r.transformers, t) && (e = !0), r.when && g(r.when, t) && (e = !0);

package/dist/helpers/schemaValidator.d.ts

@@ -1,5 +1,6 @@
 import { Schema } from '@plitzi/sdk-shared';
 export type SchemaValidationOptions = {
+    /** Validates `flat` as a fragment hung off this element — a component's tree — instead of as the pages' tree. */
     baseElementId?: string;
     /**
      * Element type → the source name it publishes under.
@@ -14,6 +15,8 @@ export type SchemaValidationError = {
     code: string;
     message: string;
     elementId?: string;
+    /** The component whose tree the error is in; absent for the pages' tree. */
+    componentId?: string;
     details?: unknown;
 };
 export type SchemaValidationResult = {