@wocart/theme 1.4.0 → 1.5.0

package/dist/operations.js

@@ -0,0 +1,377 @@
+/**
+ * Document operations: the changes a writer makes to a page document, with
+ * the rules every writer must apply — an editor, a CLI, an assistant. Each
+ * returns a new document or says why it refused; the input is never changed.
+ *
+ * The rules are the reader's rules made strict: a document these operations
+ * build is one `validatePageData` reads without a report, and that the
+ * renderer renders as the writer saw it. How an editor lets a merchant drag,
+ * select or undo is the editor's own.
+ */
+import { surfaceCovers } from "./composition.js";
+import { checkStoredValue, hasFallback, ownValue } from "./instances.js";
+import { ComponentInstanceSchema } from "./schemas.js";
+/**
+ * A new instance id: `cmp_` and 16 random hex digits. Operations refuse an id
+ * the document already holds, so a collision is reported, never written.
+ */
+export function newInstanceId() {
+    const bytes = crypto.getRandomValues(new Uint8Array(8));
+    return `cmp_${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const definitionOf = (theme, type) => Object.hasOwn(theme.components, type) ? theme.components[type] : undefined;
+const refuse = (code, message, path = "") => ({
+    ok: false,
+    issue: { path, code, message },
+});
+/** A node's children and slots as one map; the default slot merges `children` and `slots.default`, in render order. */
+function slotLists(node) {
+    const lists = [];
+    const defaults = [...(node.children ?? []), ...(node.slots?.default ?? [])];
+    if (defaults.length > 0 || node.children !== undefined)
+        lists.push(["default", defaults, "children"]);
+    for (const [name, list] of Object.entries(node.slots ?? {})) {
+        if (name !== "default")
+            lists.push([name, list, `slots.${name}`]);
+    }
+    return lists;
+}
+/** Every instance with its location, depth first. */
+function* walk(list, parent, slot) {
+    for (const [index, instance] of list.entries()) {
+        yield { instance, parent, slot, index };
+        for (const [name, children] of slotLists(instance))
+            yield* walk(children, instance.id, name);
+    }
+}
+/** Where `id` is in the document, or `null`. */
+export function findInstance(page, id) {
+    for (const location of walk(page.sections, null, null)) {
+        if (location.instance.id === id)
+            return location;
+    }
+    return null;
+}
+function documentIds(page) {
+    const ids = new Set();
+    for (const { instance } of walk(page.sections, null, null))
+        ids.add(instance.id);
+    return ids;
+}
+/**
+ * The editable list a placement names, in a copy of the document: the sections,
+ * or a parent's slot. The default slot is normalized to `children` (the order
+ * the reader renders), so a write never leaves content in two places.
+ */
+function targetList(page, placement) {
+    if (placement.parent === undefined)
+        return page.sections;
+    const location = findInstance(page, placement.parent);
+    if (location === null)
+        return null;
+    const parent = location.instance;
+    const slot = placement.slot ?? "default";
+    if (slot === "default") {
+        if (parent.slots?.default !== undefined) {
+            parent.children = [...(parent.children ?? []), ...parent.slots.default];
+            delete parent.slots.default;
+            if (Object.keys(parent.slots).length === 0)
+                delete parent.slots;
+        }
+        parent.children ??= [];
+        return parent.children;
+    }
+    parent.slots ??= {};
+    parent.slots[slot] ??= [];
+    return parent.slots[slot];
+}
+/** Can `type` go into the placement's slot, given what is already there? */
+function placementIssue(theme, page, type, placement, occupied) {
+    if (placement.parent === undefined) {
+        if (placement.slot !== undefined)
+            return refuse("unknown-slot", "the top-level sections have no slots");
+        return null;
+    }
+    const location = findInstance(page, placement.parent);
+    if (location === null)
+        return refuse("unknown-instance", `no instance "${placement.parent}" in the document`);
+    const definition = definitionOf(theme, location.instance.type);
+    if (definition === undefined)
+        return refuse("unknown-type", `"${location.instance.type}" is not in the theme catalog`);
+    const name = placement.slot ?? "default";
+    const slot = (definition.slots ?? []).find((candidate) => candidate.name === name);
+    if (slot === undefined)
+        return refuse("unknown-slot", `"${definition.type}" declares no slot "${name}"`);
+    if (slot.allow !== undefined && !slot.allow.includes(type)) {
+        return refuse("not-allowed", `"${type}" is not allowed in slot "${name}" of "${definition.type}"`);
+    }
+    if (slot.multiple === false && occupied >= 1) {
+        return refuse("slot-full", `slot "${name}" of "${definition.type}" holds at most one instance`);
+    }
+    return null;
+}
+/**
+ * An instance tree a writer may store, on this surface: known types, declared
+ * props with values their fields accept, required fields filled, slots used as
+ * declared, every component available on the surface, and ids unique among
+ * themselves and `taken`. Returns the first problem.
+ */
+function treeIssue(theme, node, surface, taken, path) {
+    const definition = definitionOf(theme, node.type);
+    if (definition === undefined)
+        return { path: `${path}.type`, code: "unknown-type", message: `"${node.type}" is not in the theme catalog` };
+    const surfaces = definition.capabilities?.surfaces;
+    if (surfaces !== undefined && !surfaces.some((entry) => surfaceCovers(entry, surface))) {
+        return { path, code: "not-available", message: `"${node.type}" cannot be placed on "${surface}"` };
+    }
+    if (taken.has(node.id))
+        return { path: `${path}.id`, code: "duplicate-id", message: `the id "${node.id}" is already in the document` };
+    taken.add(node.id);
+    const fields = new Map((definition.fields ?? []).map((field) => [field.key, field]));
+    const props = node.props ?? {};
+    for (const [key, value] of Object.entries(props)) {
+        const field = fields.get(key);
+        if (field === undefined)
+            return { path: `${path}.props.${key}`, code: "invalid-props", message: `"${key}" is not a declared field of "${node.type}"` };
+        const checked = checkStoredValue(field, value);
+        if (!checked.ok)
+            return { path: `${path}.props.${key}`, code: "invalid-props", message: `"${key}" ${checked.message}` };
+    }
+    for (const field of fields.values()) {
+        if (field.required === true && ownValue(props, field.key) === undefined && !hasFallback(field)) {
+            return { path: `${path}.props.${field.key}`, code: "invalid-props", message: `required field "${field.key}" needs a value` };
+        }
+    }
+    const slots = new Map((definition.slots ?? []).map((slot) => [slot.name, slot]));
+    for (const [name, list, listPath] of slotLists(node)) {
+        const slot = slots.get(name);
+        if (slot === undefined) {
+            if (list.length === 0)
+                continue;
+            return { path: `${path}.${listPath}`, code: "unknown-slot", message: `"${node.type}" declares no slot "${name}"` };
+        }
+        if (slot.multiple === false && list.length > 1) {
+            return { path: `${path}.${listPath}`, code: "slot-full", message: `slot "${name}" of "${node.type}" holds at most one instance` };
+        }
+        for (const [index, child] of list.entries()) {
+            const childPath = `${path}.${listPath}[${index}]`;
+            if (slot.allow !== undefined && !slot.allow.includes(child.type)) {
+                return { path: childPath, code: "not-allowed", message: `"${child.type}" is not allowed in slot "${name}" of "${node.type}"` };
+            }
+            const issue = treeIssue(theme, child, surface, taken, childPath);
+            if (issue !== null)
+                return issue;
+        }
+    }
+    return null;
+}
+function parseInstance(instance) {
+    const parsed = ComponentInstanceSchema.safeParse(instance);
+    if (!parsed.success) {
+        return { path: "", code: "invalid-instance", message: `not an instance: ${parsed.error.issues[0]?.message ?? "invalid shape"}` };
+    }
+    return parsed.data;
+}
+const isIssue = (value) => "code" in value && "message" in value && !("type" in value);
+function indexIssue(index, length) {
+    if (index === undefined)
+        return null;
+    if (!Number.isInteger(index) || index < 0 || index > length) {
+        return refuse("invalid-index", `index ${index} is outside 0…${length}`);
+    }
+    return null;
+}
+/**
+ * Insert a new instance — from `createInstance` or `instantiatePreset` — at a
+ * placement. Refused when the component is not insertable or not available on
+ * the document's surface, when the slot does not take it, or when any id is
+ * already in the document.
+ */
+export function insertInstance(theme, page, instance, placement = {}) {
+    const parsed = parseInstance(instance);
+    if (isIssue(parsed))
+        return { ok: false, issue: parsed };
+    const definition = definitionOf(theme, parsed.type);
+    if (definition === undefined)
+        return refuse("unknown-type", `"${parsed.type}" is not in the theme catalog`);
+    if (definition.capabilities?.insertable === false) {
+        return refuse("not-insertable", `"${parsed.type}" is not inserted by editors`);
+    }
+    const next = structuredClone(page);
+    const list = targetList(next, placement);
+    if (list === null)
+        return refuse("unknown-instance", `no instance "${placement.parent}" in the document`);
+    const position = indexIssue(placement.index, list.length);
+    if (position !== null)
+        return position;
+    const slotProblem = placementIssue(theme, next, parsed.type, placement, list.length);
+    if (slotProblem !== null)
+        return slotProblem;
+    const issue = treeIssue(theme, parsed, next.surface, documentIds(page), "instance");
+    if (issue !== null)
+        return { ok: false, issue };
+    list.splice(placement.index ?? list.length, 0, structuredClone(parsed));
+    return { ok: true, page: next };
+}
+/** Remove an instance and everything inside it. */
+export function removeInstance(page, id) {
+    const next = structuredClone(page);
+    const location = findInstance(next, id);
+    if (location === null)
+        return refuse("unknown-instance", `no instance "${id}" in the document`);
+    const list = location.parent === null
+        ? next.sections
+        : targetList(next, { parent: location.parent, slot: location.slot ?? "default" });
+    if (list === null)
+        return refuse("unknown-instance", `no instance "${location.parent}" in the document`);
+    list.splice(list.findIndex((candidate) => candidate.id === id), 1);
+    return { ok: true, page: next };
+}
+/**
+ * Move an instance (with everything inside it) to a placement. `index` counts
+ * positions in the destination after the instance has left its old place.
+ */
+export function moveInstance(theme, page, id, placement = {}) {
+    const location = findInstance(page, id);
+    if (location === null)
+        return refuse("unknown-instance", `no instance "${id}" in the document`);
+    if (placement.parent !== undefined) {
+        if (placement.parent === id)
+            return refuse("cycle", "an instance cannot be moved into itself");
+        for (const inner of walk([location.instance], null, null)) {
+            if (inner.instance.id === placement.parent)
+                return refuse("cycle", `"${placement.parent}" is inside "${id}"`);
+        }
+    }
+    const removed = removeInstance(page, id);
+    if (!removed.ok)
+        return removed;
+    const next = removed.page;
+    const list = targetList(next, placement);
+    if (list === null)
+        return refuse("unknown-instance", `no instance "${placement.parent}" in the document`);
+    const position = indexIssue(placement.index, list.length);
+    if (position !== null)
+        return position;
+    const slotProblem = placementIssue(theme, next, location.instance.type, placement, list.length);
+    if (slotProblem !== null)
+        return slotProblem;
+    const surfaces = definitionOf(theme, location.instance.type)?.capabilities?.surfaces;
+    if (surfaces !== undefined && !surfaces.some((entry) => surfaceCovers(entry, next.surface))) {
+        return refuse("not-available", `"${location.instance.type}" cannot be placed on "${next.surface}"`);
+    }
+    list.splice(placement.index ?? list.length, 0, structuredClone(location.instance));
+    return { ok: true, page: next };
+}
+/**
+ * Copy an instance and everything inside it right after the original, every
+ * copied instance with an id from `newId`. List items keep their ids: they
+ * are unique within their list, not the document.
+ */
+export function duplicateInstance(theme, page, id, newId) {
+    const location = findInstance(page, id);
+    if (location === null)
+        return refuse("unknown-instance", `no instance "${id}" in the document`);
+    const copy = structuredClone(location.instance);
+    for (const inner of walk([copy], null, null))
+        inner.instance.id = newId();
+    const placement = location.parent === null
+        ? { index: location.index + 1 }
+        : { parent: location.parent, slot: location.slot ?? "default", index: location.index + 1 };
+    const next = structuredClone(page);
+    const list = targetList(next, placement);
+    if (list === null)
+        return refuse("unknown-instance", `no instance "${location.parent}" in the document`);
+    const slotProblem = placementIssue(theme, next, copy.type, placement, list.length);
+    if (slotProblem !== null)
+        return slotProblem;
+    const issue = treeIssue(theme, copy, next.surface, documentIds(page), "instance");
+    if (issue !== null)
+        return { ok: false, issue };
+    list.splice(location.index + 1, 0, copy);
+    return { ok: true, page: next };
+}
+/**
+ * Change an instance's props: each value is checked by its field;
+ * `undefined` removes the stored value, so the field falls back to its
+ * content-pack text or default.
+ */
+export function setInstanceProps(theme, page, id, changes) {
+    const next = structuredClone(page);
+    const location = findInstance(next, id);
+    if (location === null)
+        return refuse("unknown-instance", `no instance "${id}" in the document`);
+    const instance = location.instance;
+    const definition = definitionOf(theme, instance.type);
+    if (definition === undefined)
+        return refuse("unknown-type", `"${instance.type}" is not in the theme catalog`);
+    const fields = new Map((definition.fields ?? []).map((field) => [field.key, field]));
+    const props = { ...(instance.props ?? {}) };
+    for (const [key, value] of Object.entries(changes)) {
+        const field = fields.get(key);
+        if (field === undefined)
+            return refuse("invalid-props", `"${key}" is not a declared field of "${instance.type}"`, `props.${key}`);
+        if (value === undefined) {
+            if (field.required === true && !hasFallback(field)) {
+                return refuse("invalid-props", `required field "${key}" needs a value`, `props.${key}`);
+            }
+            delete props[key];
+            continue;
+        }
+        const checked = checkStoredValue(field, value);
+        if (!checked.ok)
+            return refuse("invalid-props", `"${key}" ${checked.message}`, `props.${key}`);
+        props[key] = value;
+    }
+    if (Object.keys(props).length > 0)
+        instance.props = props;
+    else
+        delete instance.props;
+    return { ok: true, page: next };
+}
+/** Switch an instance off (kept, not rendered) or back on. */
+export function setInstanceHidden(page, id, hidden) {
+    const next = structuredClone(page);
+    const location = findInstance(next, id);
+    if (location === null)
+        return refuse("unknown-instance", `no instance "${id}" in the document`);
+    if (hidden)
+        location.instance.hidden = true;
+    else
+        delete location.instance.hidden;
+    return { ok: true, page: next };
+}
+/**
+ * Everything a writer must fix before saving a document for this theme —
+ * the strict counterpart of `validatePageData`: an envelope for one of the
+ * theme's surfaces when it declares any, and every section a tree the
+ * operations would have built. An empty list means the document may be saved.
+ */
+export function checkPageData(theme, input) {
+    if (!isRecord(input) || input.version !== 1 || typeof input.surface !== "string" || !Array.isArray(input.sections)) {
+        return [{ path: "", code: "invalid-document", message: "a page document is { version: 1, surface, sections }" }];
+    }
+    const issues = [];
+    const surface = input.surface;
+    const declared = theme.surfaces ?? [];
+    if (declared.length > 0 && !declared.some((spec) => spec.key === surface)) {
+        issues.push({ path: "surface", code: "invalid-document", message: `"${surface}" is not a surface this theme declares` });
+    }
+    if (input.theme !== undefined && !(isRecord(input.theme) && input.theme.key === theme.key && typeof input.theme.version === "string" && input.theme.version.length > 0)) {
+        issues.push({ path: "theme", code: "invalid-document", message: `\`theme\` must name this theme: { key: "${theme.key}", version }` });
+    }
+    const taken = new Set();
+    input.sections.forEach((section, index) => {
+        const path = `sections[${index}]`;
+        const parsed = parseInstance(section);
+        if (isIssue(parsed)) {
+            issues.push({ ...parsed, path });
+            return;
+        }
+        const issue = treeIssue(theme, parsed, surface, taken, path);
+        if (issue !== null)
+            issues.push(issue);
+    });
+    return issues;
+}

package/dist/page-data.js

@@ -8,7 +8,7 @@
  * document itself is not rewritten by `validatePageData`.
  */
 import { resolveInstance } from "./instances.js";
-import { ComponentInstanceSchema, SURFACE_KEY_PATTERN } from "./schemas.js";
+import { ComponentInstanceSchema, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN } from "./schemas.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const envelopeFailure = (message) => ({
     page: null,
@@ -45,12 +45,29 @@ export function parsePageData(input) {
     // name a prototype.
     const page = { version: 1, surface, sections };
     for (const key of Object.keys(input)) {
-        if (key === "version" || key === "surface" || key === "sections")
+        if (key === "version" || key === "surface" || key === "sections" || key === "theme")
             continue;
         if (key === "__proto__")
             continue;
         page[key] = input[key];
     }
+    if (input.theme !== undefined) {
+        const theme = input.theme;
+        if (isRecord(theme) &&
+            typeof theme.key === "string" &&
+            THEME_KEY_PATTERN.test(theme.key) &&
+            typeof theme.version === "string" &&
+            theme.version.length > 0) {
+            page.theme = { key: theme.key, version: theme.version };
+        }
+        else {
+            issues.push({
+                path: "theme",
+                code: "invalid-provenance",
+                message: "`theme` must be { key, version } naming the theme that wrote the document; ignored",
+            });
+        }
+    }
     return { page, issues };
 }
 /**
@@ -64,6 +81,13 @@ export function validatePageData(theme, input, scope = {}) {
         return parsed;
     }
     const issues = [...parsed.issues];
+    if (parsed.page.theme !== undefined && parsed.page.theme.key !== theme.key) {
+        issues.push({
+            path: "theme.key",
+            code: "theme-mismatch",
+            message: `the document was written for theme "${parsed.page.theme.key}", not "${theme.key}"; its sections were composed from another catalog`,
+        });
+    }
     const walk = (instance, path) => {
         const definition = Object.hasOwn(theme.components, instance.type)
             ? theme.components[instance.type]
@@ -126,6 +150,9 @@ function pruneDuplicateIds(instance, path, seenIds, issues) {
     if (instance.props !== undefined) {
         pruned.props = instance.props;
     }
+    if (instance.hidden !== undefined) {
+        pruned.hidden = instance.hidden;
+    }
     if (instance.children !== undefined) {
         const children = [];
         instance.children.forEach((child, index) => {

package/dist/preview-bridge.d.ts

@@ -0,0 +1,28 @@
+export interface PreviewBridgeOptions {
+    /** The editor's origin: the verified token's `editor` claim. */
+    editorOrigin: string;
+    /** The verified token, posted back with every re-render. */
+    token: string;
+    /** The theme's preview route; `THEME_PREVIEW_PATH` by default. */
+    endpoint?: string;
+    /** The window to run in; the page's own by default. */
+    window?: Window;
+}
+export interface PreviewBridge {
+    /** Removes every listener; the page keeps what it last rendered. */
+    stop(): void;
+}
+/**
+ * Dispatched on `document` for each section the bridge swapped in, with the
+ * instance id as `detail.id`: a section with browser behavior binds it again.
+ * When the whole page was replaced instead, the bridge dispatches Astro's own
+ * `astro:page-load`, as Astro's router does after it swaps a page.
+ */
+export declare const PREVIEW_SECTION_LOAD_EVENT = "wocart:section-load";
+/**
+ * Starts the bridge on a preview page. It posts `ready` with every marked
+ * instance, `layout` as the page scrolls or resizes, `hover` as the merchant
+ * points, `select` as they click (in `edit` mode, where links and forms do
+ * nothing), and `rendered` after each draft it swaps in.
+ */
+export declare function startPreviewBridge(options: PreviewBridgeOptions): PreviewBridge;