@wocart/theme 1.3.0 → 1.5.0

package/dist/preview-bridge.js

@@ -0,0 +1,317 @@
+/// <reference lib="dom" />
+/**
+ * The preview page's side of the preview protocol: a small browser module a
+ * theme loads on its preview route only. It finds the instances the renderer
+ * marked, tells the editor where they are and which one the merchant points
+ * at, and re-renders a draft the editor sends by posting it back to the
+ * storefront and swapping in only the sections that changed — or, when the
+ * page around them changed, the whole page, the way Astro's router swaps one.
+ *
+ * It draws nothing — outlines, toolbars and panels are the editor's. It posts
+ * only to the editor origin it is given and reads only that origin's messages
+ * from the framing window.
+ */
+import { PREVIEW_PROTOCOL_VERSION, THEME_PREVIEW_PATH, parsePreviewMarker, } from "./preview-protocol.js";
+/**
+ * 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 const PREVIEW_SECTION_LOAD_EVENT = "wocart:section-load";
+const ASTRO_PAGE_LOAD_EVENT = "astro:page-load";
+const SHOW_COMMENT = 0x80;
+const ELEMENT_NODE = 1;
+const COMMENT_NODE = 8;
+/**
+ * Every complete marker pair under `root`, in document order, each with the
+ * pair that encloses it. Pairs nest or are ignored: a start still open when an
+ * enclosing pair closes never pairs.
+ */
+function collect(root) {
+    const pairs = [];
+    const open = [];
+    const walker = (root.ownerDocument ?? root).createTreeWalker(root, SHOW_COMMENT);
+    let position = 0;
+    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+        const marker = parsePreviewMarker(node.data);
+        if (marker === null)
+            continue;
+        position += 1;
+        if (marker.kind === "start") {
+            open.push({ id: marker.id, type: marker.type, hidden: marker.hidden, start: node, opened: position });
+            continue;
+        }
+        const index = open.map((entry) => entry.id).lastIndexOf(marker.id);
+        if (index === -1)
+            continue;
+        pairs.push({ ...open.splice(index)[0], end: node, closed: position });
+    }
+    pairs.sort((a, b) => a.opened - b.opened);
+    return pairs.map(({ opened, closed, ...entry }) => {
+        const enclosing = pairs.filter((other) => other.opened < opened && closed < other.closed);
+        return { ...entry, parent: enclosing.at(-1)?.id ?? null, depth: enclosing.length };
+    });
+}
+/** The nodes between a pair of markers, or `null` when the pair are not siblings. */
+function between(entry) {
+    const nodes = [];
+    for (let node = entry.start.nextSibling; node !== entry.end; node = node.nextSibling) {
+        if (node === null)
+            return null;
+        nodes.push(node);
+    }
+    return nodes;
+}
+function markup(nodes) {
+    return nodes
+        .map((node) => {
+        if (node.nodeType === ELEMENT_NODE)
+            return node.outerHTML;
+        if (node.nodeType === COMMENT_NODE)
+            return `<!--${node.data}-->`;
+        return node.textContent ?? "";
+    })
+        .join("");
+}
+/**
+ * The page with every section's content left out — the root's attributes and
+ * the body around the sections: what must not change for sections to be
+ * swapped alone.
+ */
+function frameOf(doc) {
+    const copy = doc.body.cloneNode(true);
+    for (const entry of collect(copy)) {
+        if (entry.parent !== null)
+            continue;
+        const nodes = between(entry);
+        if (nodes === null)
+            return null;
+        for (const node of nodes)
+            node.parentNode?.removeChild(node);
+    }
+    const root = doc.documentElement;
+    const attributes = root.getAttributeNames().map((name) => `${name}=${JSON.stringify(root.getAttribute(name))}`);
+    return `${attributes.join(" ")}\n${copy.outerHTML}`;
+}
+function stylesOf(doc) {
+    return Array.from(doc.head.querySelectorAll('style, link[rel="stylesheet"]'));
+}
+/**
+ * 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 function startPreviewBridge(options) {
+    const win = (options.window ?? window);
+    const doc = win.document;
+    const endpoint = options.endpoint ?? THEME_PREVIEW_PATH;
+    let token = options.token;
+    let mode = "edit";
+    let marked = collect(doc.body);
+    let hovered = null;
+    let frame = 0;
+    let latest = 0;
+    let stopped = false;
+    const post = (message) => win.parent.postMessage({ source: "wocart-preview", version: PREVIEW_PROTOCOL_VERSION, ...message }, options.editorOrigin);
+    const rangeOf = (entry) => {
+        const range = doc.createRange();
+        range.setStartAfter(entry.start);
+        range.setEndBefore(entry.end);
+        return range;
+    };
+    const instances = () => marked.map((entry) => {
+        const box = rangeOf(entry).getBoundingClientRect();
+        const rect = box.width > 0 || box.height > 0 ? { x: box.x, y: box.y, width: box.width, height: box.height } : null;
+        return { id: entry.id, type: entry.type, parent: entry.parent, hidden: entry.hidden, rect };
+    });
+    const innermostAt = (target) => {
+        if (!(target instanceof win.Node))
+            return null;
+        let best;
+        for (const entry of marked) {
+            if (best !== undefined && entry.depth <= best.depth)
+                continue;
+            if (between(entry)?.some((node) => node.contains(target)))
+                best = entry;
+        }
+        return best?.id ?? null;
+    };
+    const reportLayout = () => {
+        if (frame !== 0)
+            return;
+        frame = win.requestAnimationFrame(() => {
+            frame = 0;
+            post({ type: "layout", instances: instances() });
+        });
+    };
+    const onClick = (event) => {
+        if (mode !== "edit")
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        const id = innermostAt(event.target);
+        if (id !== null)
+            post({ type: "select", id });
+    };
+    const onSubmit = (event) => {
+        if (mode !== "edit")
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+    };
+    const onOver = (event) => {
+        const id = innermostAt(event.target);
+        if (id === hovered)
+            return;
+        hovered = id;
+        post({ type: "hover", id });
+    };
+    const onLeave = () => {
+        if (hovered === null)
+            return;
+        hovered = null;
+        post({ type: "hover", id: null });
+    };
+    const swapHead = (next) => {
+        const current = stylesOf(doc);
+        const wanted = stylesOf(next);
+        if (current.length === wanted.length) {
+            current.forEach((node, index) => {
+                if (node.outerHTML !== wanted[index].outerHTML)
+                    node.replaceWith(doc.importNode(wanted[index], true));
+            });
+        }
+        else {
+            for (const node of current)
+                node.remove();
+            for (const node of wanted)
+                doc.head.appendChild(doc.importNode(node, true));
+        }
+        if (next.title !== doc.title)
+            doc.title = next.title;
+    };
+    const swapPage = (next) => {
+        const root = doc.documentElement;
+        for (const name of root.getAttributeNames())
+            if (!next.documentElement.hasAttribute(name))
+                root.removeAttribute(name);
+        for (const name of next.documentElement.getAttributeNames())
+            root.setAttribute(name, next.documentElement.getAttribute(name));
+        const { scrollX, scrollY } = win;
+        doc.body.replaceWith(doc.importNode(next.body, true));
+        win.scrollTo(scrollX, scrollY);
+    };
+    /** Swaps `next` in; `null` when the whole page was replaced, else the sections that were. */
+    const swap = (next) => {
+        swapHead(next);
+        const before = frameOf(doc);
+        if (before === null || before !== frameOf(next)) {
+            swapPage(next);
+            return null;
+        }
+        const incoming = collect(next.body);
+        const swapped = [];
+        for (const entry of marked) {
+            if (entry.parent !== null)
+                continue;
+            const counterpart = incoming.find((candidate) => candidate.parent === null && candidate.id === entry.id);
+            const old = between(entry);
+            const fresh = counterpart === undefined ? null : between(counterpart);
+            if (old === null || fresh === null || markup(old) === markup(fresh))
+                continue;
+            for (const node of old)
+                node.parentNode?.removeChild(node);
+            for (const node of fresh)
+                entry.end.parentNode?.insertBefore(doc.importNode(node, true), entry.end);
+            swapped.push(entry.id);
+        }
+        return swapped;
+    };
+    const render = async (draft, revision) => {
+        const ticket = ++latest;
+        try {
+            const response = await win.fetch(endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Accept: "text/html" },
+                body: JSON.stringify({ token, draft }),
+                credentials: "same-origin",
+            });
+            const html = await response.text();
+            if (stopped || ticket !== latest)
+                return;
+            if (!response.ok) {
+                post({ type: "error", revision, reason: `the preview answered ${response.status}` });
+                return;
+            }
+            const swapped = swap(new win.DOMParser().parseFromString(html, "text/html"));
+            marked = collect(doc.body);
+            if (swapped === null) {
+                doc.dispatchEvent(new win.Event(ASTRO_PAGE_LOAD_EVENT));
+            }
+            else {
+                for (const id of swapped)
+                    doc.dispatchEvent(new win.CustomEvent(PREVIEW_SECTION_LOAD_EVENT, { detail: { id } }));
+            }
+            post({ type: "rendered", revision, instances: instances() });
+        }
+        catch (error) {
+            if (stopped || ticket !== latest)
+                return;
+            post({ type: "error", revision, reason: error instanceof Error ? error.message : String(error) });
+        }
+    };
+    const onMessage = (event) => {
+        if (event.origin !== options.editorOrigin || event.source !== win.parent)
+            return;
+        const message = event.data;
+        if (typeof message !== "object" || message === null)
+            return;
+        if (message.source !== "wocart-editor" || message.version !== PREVIEW_PROTOCOL_VERSION)
+            return;
+        switch (message.type) {
+            case "render":
+                if (typeof message.draft === "object" && message.draft !== null && !Array.isArray(message.draft)) {
+                    void render(message.draft, typeof message.revision === "number" ? message.revision : null);
+                }
+                break;
+            case "mode":
+                if (message.mode === "edit" || message.mode === "interactive")
+                    mode = message.mode;
+                break;
+            case "scroll-to": {
+                const entry = marked.find((candidate) => candidate.id === message.id);
+                const first = entry === undefined ? undefined : between(entry)?.find((node) => node.nodeType === ELEMENT_NODE);
+                first?.scrollIntoView({ block: "start", behavior: "smooth" });
+                break;
+            }
+            case "token":
+                if (typeof message.token === "string" && message.token !== "")
+                    token = message.token;
+                break;
+        }
+    };
+    win.addEventListener("message", onMessage);
+    win.addEventListener("scroll", reportLayout, { passive: true });
+    win.addEventListener("resize", reportLayout);
+    doc.addEventListener("click", onClick, true);
+    doc.addEventListener("submit", onSubmit, true);
+    doc.addEventListener("mouseover", onOver, true);
+    doc.documentElement.addEventListener("mouseleave", onLeave);
+    post({ type: "ready", instances: instances() });
+    return {
+        stop() {
+            win.removeEventListener("message", onMessage);
+            win.removeEventListener("scroll", reportLayout);
+            win.removeEventListener("resize", reportLayout);
+            doc.removeEventListener("click", onClick, true);
+            doc.removeEventListener("submit", onSubmit, true);
+            doc.removeEventListener("mouseover", onOver, true);
+            doc.documentElement.removeEventListener("mouseleave", onLeave);
+            if (frame !== 0)
+                win.cancelAnimationFrame(frame);
+            stopped = true;
+        },
+    };
+}

package/dist/preview-protocol.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The preview protocol: how a framed storefront page in preview mode and the
+ * editor that frames it talk, and how the page marks its sections. Plain data
+ * and string helpers — shared by the renderer (`InstanceView`), the page's
+ * bridge (`@wocart/theme/preview`) and an editor, so the three cannot drift.
+ *
+ * Every message is `{ source, version, type, … }`. The page sends
+ * `source: "wocart-preview"`; the editor sends `source: "wocart-editor"`. Both
+ * sides post with the other's exact origin and check `event.origin` and
+ * `event.source` before reading a message.
+ */
+/** Incremented on a change an older counterpart could not read. */
+export declare const PREVIEW_PROTOCOL_VERSION: 1;
+/** Where a theme that supports preview serves it: a POST route of the storefront. */
+export declare const THEME_PREVIEW_PATH = "/wocart-preview";
+/** A section's place on the page, in the frame's viewport coordinates. */
+export interface PreviewRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** One rendered instance, as the page reports it. `rect` is null when it shows nothing. */
+export interface PreviewInstance {
+    id: string;
+    type: string;
+    /** The instance it is inside, or `null` for a section of the document. */
+    parent: string | null;
+    hidden: boolean;
+    rect: PreviewRect | null;
+}
+/** What the preview page tells the editor. */
+export type PreviewPageMessage = {
+    source: "wocart-preview";
+    version: typeof PREVIEW_PROTOCOL_VERSION;
+} & ({
+    type: "ready";
+    instances: PreviewInstance[];
+} | {
+    type: "layout";
+    instances: PreviewInstance[];
+} | {
+    type: "rendered";
+    revision: number | null;
+    instances: PreviewInstance[];
+} | {
+    type: "select";
+    id: string;
+} | {
+    type: "hover";
+    id: string | null;
+} | {
+    type: "error";
+    revision: number | null;
+    reason: string;
+});
+/** The interaction an editor allows: `edit` turns clicks into selections; `interactive` lets the page behave. */
+export type PreviewMode = "edit" | "interactive";
+/**
+ * What the editor tells the preview page. `draft` is a `PreviewDraft` of
+ * `@wocart/storefront`; `revision`, when given, comes back on the `rendered`
+ * or `error` it causes, and a render answered after a newer one is dropped.
+ */
+export type PreviewEditorMessage = {
+    source: "wocart-editor";
+    version: typeof PREVIEW_PROTOCOL_VERSION;
+} & ({
+    type: "render";
+    draft: Record<string, unknown>;
+    revision?: number;
+} | {
+    type: "mode";
+    mode: PreviewMode;
+} | {
+    type: "scroll-to";
+    id: string;
+} | {
+    type: "token";
+    token: string;
+});
+/** The comment text that opens an instance's nodes. */
+export declare function previewStartMarker(instance: {
+    id: string;
+    type: string;
+    hidden?: boolean;
+}): string;
+/** The comment text that closes them. */
+export declare function previewEndMarker(instance: {
+    id: string;
+}): string;
+/** What a marker comment says, or `null` for any other comment. */
+export declare function parsePreviewMarker(text: string): {
+    kind: "start";
+    id: string;
+    type: string;
+    hidden: boolean;
+} | {
+    kind: "end";
+    id: string;
+} | null;

package/dist/preview-protocol.js

@@ -0,0 +1,51 @@
+/**
+ * The preview protocol: how a framed storefront page in preview mode and the
+ * editor that frames it talk, and how the page marks its sections. Plain data
+ * and string helpers — shared by the renderer (`InstanceView`), the page's
+ * bridge (`@wocart/theme/preview`) and an editor, so the three cannot drift.
+ *
+ * Every message is `{ source, version, type, … }`. The page sends
+ * `source: "wocart-preview"`; the editor sends `source: "wocart-editor"`. Both
+ * sides post with the other's exact origin and check `event.origin` and
+ * `event.source` before reading a message.
+ */
+/** Incremented on a change an older counterpart could not read. */
+export const PREVIEW_PROTOCOL_VERSION = 1;
+/** Where a theme that supports preview serves it: a POST route of the storefront. */
+export const THEME_PREVIEW_PATH = "/wocart-preview";
+// ── Section markers ─────────────────────────────────────────────────────────
+// A preview render brackets each instance with two HTML comments, so the page
+// can find every section's nodes — even a section that rendered nothing — and
+// a shopper's page carries none of them.
+const START = "wocart:start";
+const END = "wocart:end";
+/** The comment text that opens an instance's nodes. */
+export function previewStartMarker(instance) {
+    return `${START} id=${encodeURIComponent(instance.id)} type=${encodeURIComponent(instance.type)}${instance.hidden === true ? " hidden" : ""}`;
+}
+/** The comment text that closes them. */
+export function previewEndMarker(instance) {
+    return `${END} id=${encodeURIComponent(instance.id)}`;
+}
+/** What a marker comment says, or `null` for any other comment. */
+export function parsePreviewMarker(text) {
+    const start = /^wocart:start id=([^ ]+) type=([^ ]+)( hidden)?$/.exec(text);
+    if (start) {
+        try {
+            return { kind: "start", id: decodeURIComponent(start[1]), type: decodeURIComponent(start[2]), hidden: start[3] !== undefined };
+        }
+        catch {
+            return null;
+        }
+    }
+    const end = /^wocart:end id=([^ ]+)$/.exec(text);
+    if (end) {
+        try {
+            return { kind: "end", id: decodeURIComponent(end[1]) };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}

package/dist/rich-text.d.ts

@@ -0,0 +1,31 @@
+import type { RichTextDocument, RichTextFormat } from "./types.js";
+/** Every format a rich-text field can allow, in the order an editor lists them. */
+export declare const RICH_TEXT_FORMATS: readonly RichTextFormat[];
+/** Whether a stored value is meant as one document (rather than a per-language map). */
+export declare function isRichTextDocumentShape(value: unknown): boolean;
+/**
+ * Why `value` is not a valid rich-text document under `formats`, or `null`
+ * when it is. Absent `formats` allows every format.
+ */
+export declare function richTextProblem(value: unknown, formats?: readonly RichTextFormat[]): string | null;
+/** How `richTextToHtml` writes links. */
+export interface RichTextHtmlOptions {
+    /**
+     * Turns a stored link target into the `href` to render — a theme passes its
+     * own localizing function so a site path keeps the shopper's language. The
+     * result is escaped; a target that fails the link rule never reaches it.
+     */
+    href?: (target: string) => string;
+}
+/**
+ * The document as HTML: `<p>`, `<h2>`–`<h4>`, `<ul>`/`<ol>`, `<strong>`, `<em>`,
+ * `<u>`, `<s>`, `<a href>` and `<br>`, every text and attribute escaped. Nodes
+ * outside the format and unsafe links are left out rather than trusted, so
+ * the output is safe for Astro's `set:html` even for an unchecked value.
+ */
+export declare function richTextToHtml(document: RichTextDocument, options?: RichTextHtmlOptions): string;
+/**
+ * The document's text without formatting: blocks and list items on their own
+ * lines, line breaks kept — for meta descriptions, `aria-label`s and previews.
+ */
+export declare function richTextToPlainText(document: RichTextDocument): string;