@capacms/sdk 1.0.0-next.0 → 1.0.0-next.10

package/dist/overlay/index.js

@@ -0,0 +1,596 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REFRESH_TIMEOUT_MS = exports.SITE_SOURCE = exports.SITE_FEATURES = exports.PROTOCOL_VERSION = exports.PATCH_MAX_LENGTH = exports.PATCH_MAX_FIELDS = exports.ADMIN_SOURCE = exports.visibleMessage = exports.textAround = exports.selectMessage = exports.scrollEdge = exports.readyMessage = exports.pickCentred = exports.patchedText = exports.normaliseOrigins = exports.hoverMessage = exports.acceptMessage = void 0;
+exports.startOverlay = startOverlay;
+/**
+ * `@capacms/sdk/overlay`: the site half of Capa's live preview.
+ *
+ *   "use client";
+ *   useEffect(() => startOverlay({ adminOrigins: ["https://app.capacms.com"] }), []);
+ *
+ * Inside the Capa editor's preview frame this outlines the element an editor is
+ * working on, reports clicks on tagged elements back to the editor, shows the
+ * text being typed in the elements that show it verbatim, and re-renders the
+ * draft after a save. Outside a frame it does nothing at all:
+ * no listeners, no DOM, no cost.
+ *
+ * A click on a tagged element selects its field. A ⌘-click (Ctrl-click on
+ * Windows and Linux) on a tagged element that is a link, or sits inside one,
+ * follows the link in the frame instead, so an editor can move between pages.
+ *
+ * Vanilla DOM and no imports beyond the pure protocol module, so it works in
+ * any framework and adds nothing to a bundle that does not call it.
+ */
+const protocol_js_1 = require("./protocol.js");
+var protocol_js_2 = require("./protocol.js");
+Object.defineProperty(exports, "acceptMessage", { enumerable: true, get: function () { return protocol_js_2.acceptMessage; } });
+Object.defineProperty(exports, "hoverMessage", { enumerable: true, get: function () { return protocol_js_2.hoverMessage; } });
+Object.defineProperty(exports, "normaliseOrigins", { enumerable: true, get: function () { return protocol_js_2.normaliseOrigins; } });
+Object.defineProperty(exports, "patchedText", { enumerable: true, get: function () { return protocol_js_2.patchedText; } });
+Object.defineProperty(exports, "pickCentred", { enumerable: true, get: function () { return protocol_js_2.pickCentred; } });
+Object.defineProperty(exports, "readyMessage", { enumerable: true, get: function () { return protocol_js_2.readyMessage; } });
+Object.defineProperty(exports, "scrollEdge", { enumerable: true, get: function () { return protocol_js_2.scrollEdge; } });
+Object.defineProperty(exports, "selectMessage", { enumerable: true, get: function () { return protocol_js_2.selectMessage; } });
+Object.defineProperty(exports, "textAround", { enumerable: true, get: function () { return protocol_js_2.textAround; } });
+Object.defineProperty(exports, "visibleMessage", { enumerable: true, get: function () { return protocol_js_2.visibleMessage; } });
+Object.defineProperty(exports, "ADMIN_SOURCE", { enumerable: true, get: function () { return protocol_js_2.ADMIN_SOURCE; } });
+Object.defineProperty(exports, "PATCH_MAX_FIELDS", { enumerable: true, get: function () { return protocol_js_2.PATCH_MAX_FIELDS; } });
+Object.defineProperty(exports, "PATCH_MAX_LENGTH", { enumerable: true, get: function () { return protocol_js_2.PATCH_MAX_LENGTH; } });
+Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_js_2.PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "SITE_FEATURES", { enumerable: true, get: function () { return protocol_js_2.SITE_FEATURES; } });
+Object.defineProperty(exports, "SITE_SOURCE", { enumerable: true, get: function () { return protocol_js_2.SITE_SOURCE; } });
+const BLUE = "#2563eb";
+const TAGGED = "[data-capa-entry][data-capa-field]";
+/** What a ⌘-click on a tagged element follows when it sits in one. */
+const LINK = "a[href]";
+/** Survives the `location.reload()` fallback so the page comes back where it was. */
+const SCROLL_KEY = "capa-overlay:scrollY";
+/** How long a refresh keeps putting the scroll position back once the page has re-rendered. */
+const RESTORE_WINDOW_MS = 1500;
+/** How long an in-place refresh may take before the page reloads instead. */
+exports.REFRESH_TIMEOUT_MS = 10_000;
+/** `visible` is sent at most this often while the page scrolls. */
+const VISIBLE_THROTTLE_MS = 150;
+/**
+ * Apple platforms open a link with ⌘, Windows and Linux with Ctrl. Read from
+ * the browser's own platform report, falling back to the user agent.
+ */
+function isApple(nav) {
+    if (!nav)
+        return false;
+    const data = nav.userAgentData;
+    return /mac|iphone|ipad|ipod/i.test(data?.platform || nav.platform || nav.userAgent || "");
+}
+/** A usable refresh timeout: a positive number of milliseconds, or the default. */
+function timeoutOf(ms) {
+    return typeof ms === "number" && ms > 0 && Number.isFinite(ms) ? ms : exports.REFRESH_TIMEOUT_MS;
+}
+const noop = () => { };
+let running = null;
+/**
+ * Start the overlay. Returns a disposer that removes every listener and the
+ * drawing layer. Calling it again while it runs updates the options and returns
+ * the same disposer, so a React effect that runs twice does not listen twice.
+ */
+function startOverlay(options) {
+    if (typeof window === "undefined" || typeof document === "undefined")
+        return noop;
+    // Not framed: this is an ordinary visit to the site.
+    if (window.parent === window)
+        return noop;
+    if (running) {
+        running.setOptions(options);
+        return running.dispose;
+    }
+    running = createOverlay(options);
+    return running.dispose;
+}
+function createOverlay(initial) {
+    let origins = (0, protocol_js_1.normaliseOrigins)(initial.adminOrigins ?? []);
+    let onRefresh = initial.onRefresh;
+    let refreshTimeout = timeoutOf(initial.refreshTimeoutMs);
+    const apple = isApple(typeof navigator === "undefined" ? undefined : navigator);
+    const linkHint = apple ? "⌘-click to open link" : "Ctrl-click to open link";
+    /** The origin that said hello. Every message this page sends goes there and nowhere else. */
+    let adminOrigin = null;
+    let highlight = null;
+    let outlineAll = false;
+    let hovered = null;
+    /** The link the pointer is in, when it is also over a tagged element: a ⌘-click follows it. */
+    let hoveredLink = null;
+    let lastReady = "";
+    /** Where a refresh keeps the page. `until` is Infinity while the refresh is still pending. */
+    let pendingScroll = null;
+    /** Counts refreshes, so only the latest one settles the scroll or reloads. */
+    let refreshes = 0;
+    let refreshTimer = 0;
+    /** True while this overlay replays a ⌘-click as a plain click, which it must let through. */
+    let following = false;
+    let layer = null;
+    let frame = 0;
+    let readyFrame = 0;
+    let hoverFrame = 0;
+    let lastPointer = null;
+    let visibleTimer = 0;
+    let lastVisible = "";
+    const post = (message) => {
+        if (!adminOrigin)
+            return;
+        window.parent.postMessage(message, adminOrigin);
+    };
+    // ------------------------------------------------------------- drawing ---
+    const ensureLayer = () => {
+        if (layer && layer.isConnected)
+            return layer;
+        layer = document.createElement("div");
+        layer.setAttribute("data-capa-overlay", "");
+        layer.setAttribute("aria-hidden", "true");
+        Object.assign(layer.style, {
+            position: "fixed",
+            inset: "0",
+            pointerEvents: "none",
+            zIndex: "2147483647",
+            overflow: "hidden",
+        });
+        document.body.appendChild(layer);
+        return layer;
+    };
+    const tagged = () => Array.from(document.querySelectorAll(TAGGED));
+    const matching = (entryId, field) => tagged().filter((el) => el.getAttribute("data-capa-entry") === entryId &&
+        (field === null || el.getAttribute("data-capa-field") === field));
+    const box = (el, style, label) => {
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0)
+            return null;
+        const pad = style === "faint" ? 1 : 3;
+        const div = document.createElement("div");
+        Object.assign(div.style, {
+            position: "absolute",
+            left: `${rect.left - pad}px`,
+            top: `${rect.top - pad}px`,
+            width: `${rect.width + pad * 2}px`,
+            height: `${rect.height + pad * 2}px`,
+            boxSizing: "border-box",
+            borderRadius: "3px",
+            border: style === "faint"
+                ? "1px solid rgba(37, 99, 235, 0.35)"
+                : style === "hover"
+                    ? `2px dashed ${BLUE}`
+                    : `2px solid ${BLUE}`,
+        });
+        if (label) {
+            const chip = document.createElement("span");
+            chip.textContent = label;
+            // Above the box when there is room, tucked inside its top edge when the
+            // element sits at the very top of the viewport.
+            const above = rect.top - pad >= 20;
+            Object.assign(chip.style, {
+                position: "absolute",
+                left: "-2px",
+                top: above ? "-20px" : "0px",
+                background: BLUE,
+                color: "#fff",
+                font: "500 11px/18px system-ui, -apple-system, 'Segoe UI', sans-serif",
+                padding: "0 6px",
+                borderRadius: "3px",
+                whiteSpace: "nowrap",
+                letterSpacing: "0",
+            });
+            div.appendChild(chip);
+        }
+        return div;
+    };
+    const draw = () => {
+        frame = 0;
+        const nothing = !outlineAll && !highlight && !hovered;
+        if (nothing) {
+            if (layer)
+                layer.replaceChildren();
+            return;
+        }
+        const target = ensureLayer();
+        const boxes = [];
+        const active = highlight ? matching(highlight.entryId, highlight.field) : [];
+        if (outlineAll) {
+            for (const el of tagged()) {
+                if (active.includes(el))
+                    continue;
+                const b = box(el, "faint", null);
+                if (b)
+                    boxes.push(b);
+            }
+        }
+        // Over a link, the label says how to follow it.
+        const hint = hovered && hoveredLink ? ` · ${linkHint}` : "";
+        if (hovered && hovered.isConnected && !active.includes(hovered)) {
+            const b = box(hovered, "hover", `${hovered.getAttribute("data-capa-field") ?? ""}${hint}`);
+            if (b)
+                boxes.push(b);
+        }
+        active.forEach((el, i) => {
+            const name = i === 0 ? (highlight?.field ?? "entry") : null;
+            const label = el === hovered && hint ? `${name ?? el.getAttribute("data-capa-field") ?? ""}${hint}` : name;
+            const b = box(el, "active", label);
+            if (b)
+                boxes.push(b);
+        });
+        target.replaceChildren(...boxes);
+    };
+    const render = () => {
+        if (frame)
+            return;
+        frame = window.requestAnimationFrame(draw);
+    };
+    // --------------------------------------------------------------- ready ---
+    const sendReady = (force) => {
+        readyFrame = 0;
+        if (!adminOrigin)
+            return;
+        const entries = [];
+        for (const el of tagged()) {
+            const id = el.getAttribute("data-capa-entry");
+            if (id && !entries.includes(id))
+                entries.push(id);
+        }
+        const path = window.location.pathname;
+        const key = `${path}\n${entries.join(",")}`;
+        if (!force && key === lastReady)
+            return;
+        lastReady = key;
+        post((0, protocol_js_1.readyMessage)(path, entries, protocol_js_1.SITE_FEATURES));
+    };
+    const scheduleReady = () => {
+        if (readyFrame)
+            return;
+        readyFrame = window.requestAnimationFrame(() => sendReady(false));
+    };
+    // ------------------------------------------------------------- visible ---
+    /**
+     * Which tagged element sits at the centre of the viewport, reported when it
+     * changes. The editor's "Follow the page" scrolls the form to match. Sent
+     * only to an admin that has said hello, and only on a change, so a still
+     * page sends nothing.
+     */
+    const reportVisible = () => {
+        visibleTimer = 0;
+        if (!adminOrigin)
+            return;
+        const boxes = tagged().map((el) => {
+            const rect = el.getBoundingClientRect();
+            return {
+                entryId: el.getAttribute("data-capa-entry") ?? "",
+                field: el.getAttribute("data-capa-field") ?? "",
+                top: rect.top,
+                bottom: rect.bottom,
+            };
+        });
+        const edge = (0, protocol_js_1.scrollEdge)(window.scrollY, window.innerHeight, document.documentElement.scrollHeight);
+        const pick = (0, protocol_js_1.pickCentred)(boxes, window.innerHeight, edge);
+        if (!pick)
+            return;
+        const key = `${pick.entryId}\n${pick.field}`;
+        if (key === lastVisible)
+            return;
+        lastVisible = key;
+        post((0, protocol_js_1.visibleMessage)(pick.entryId, pick.field));
+    };
+    const onScroll = () => {
+        render();
+        if (!visibleTimer)
+            visibleTimer = window.setTimeout(reportVisible, VISIBLE_THROTTLE_MS);
+    };
+    // -------------------------------------------------------------- scroll ---
+    const restoreScroll = () => {
+        if (!pendingScroll)
+            return;
+        if (Date.now() > pendingScroll.until) {
+            pendingScroll = null;
+            return;
+        }
+        if (Math.abs(window.scrollY - pendingScroll.y) > 1)
+            window.scrollTo(0, pendingScroll.y);
+    };
+    // A `location.reload()` fallback left the position behind before it went.
+    try {
+        const saved = window.sessionStorage.getItem(SCROLL_KEY);
+        if (saved !== null) {
+            window.sessionStorage.removeItem(SCROLL_KEY);
+            const y = Number(saved);
+            if (Number.isFinite(y)) {
+                pendingScroll = { y, until: Date.now() + RESTORE_WINDOW_MS };
+                window.requestAnimationFrame(restoreScroll);
+            }
+        }
+    }
+    catch {
+        // Storage blocked (a sandboxed or third-party frame): start at the top.
+    }
+    /** The editor scrolled on purpose: stop putting the old position back. */
+    const onScrollIntent = () => {
+        pendingScroll = null;
+    };
+    const reload = (y) => {
+        try {
+            window.sessionStorage.setItem(SCROLL_KEY, String(y));
+        }
+        catch {
+            // Nowhere to keep it; the reload lands at the top.
+        }
+        window.location.reload();
+    };
+    /**
+     * Re-render the draft in place, or reload. While an in-place refresh is
+     * pending the position is held (a page whose re-render moves things keeps
+     * its place), and for a moment after it lands. A refresh that fails, or is
+     * still pending after `refreshTimeout`, reloads from where the editor is.
+     */
+    const refresh = () => {
+        const y = window.scrollY;
+        const refreshFn = onRefresh;
+        if (!refreshFn) {
+            reload(y);
+            return;
+        }
+        const id = ++refreshes;
+        pendingScroll = { y, until: Infinity };
+        if (refreshTimer)
+            window.clearTimeout(refreshTimer);
+        refreshTimer = window.setTimeout(() => {
+            refreshTimer = 0;
+            if (id === refreshes)
+                reload(pendingScroll?.y ?? window.scrollY);
+        }, refreshTimeout);
+        Promise.resolve()
+            .then(() => refreshFn())
+            .then(() => {
+            // A later refresh owns the timer and the scroll from here on.
+            if (id !== refreshes)
+                return;
+            window.clearTimeout(refreshTimer);
+            refreshTimer = 0;
+            if (pendingScroll)
+                pendingScroll = { y: pendingScroll.y, until: Date.now() + RESTORE_WINDOW_MS };
+            window.requestAnimationFrame(restoreScroll);
+        }, () => {
+            if (id !== refreshes)
+                return;
+            window.clearTimeout(refreshTimer);
+            refreshTimer = 0;
+            reload(pendingScroll?.y ?? window.scrollY);
+        });
+    };
+    // ---------------------------------------------------- unsaved text, live ---
+    /** What this overlay last wrote into a text node, and the whitespace it found around the text. */
+    const written = new WeakMap();
+    /** The text node a patch wrote into, by element, so one typed away to nothing is found again. */
+    const writtenIn = new WeakMap();
+    /**
+     * The one text node that holds a tagged element's text: through a chain of
+     * single elements (`<a><span>Book now</span></a>`), and only when there is
+     * exactly one. Text split across elements is not one field's text, and is
+     * left alone. Comments (React's text separators) do not count.
+     */
+    const textNodeOf = (el) => {
+        const kept = writtenIn.get(el);
+        if (kept && kept.parentNode && el.contains(kept))
+            return kept;
+        let node = el;
+        for (;;) {
+            const kids = Array.from(node.childNodes).filter((c) => c.nodeType === 1 || (c.nodeType === 3 && c.data.trim() !== ""));
+            if (kids.length === 1 && kids[0].nodeType === 3)
+                return kids[0];
+            if (kids.length === 1 && kids[0].nodeType === 1) {
+                node = kids[0];
+                continue;
+            }
+            if (kids.length === 0 && node === el) {
+                return Array.from(el.childNodes).find((c) => c.nodeType === 3) ?? null;
+            }
+            return null;
+        }
+    };
+    /**
+     * Put the text being typed into the tagged elements of these fields, while
+     * they show the saved text or what this page last patched them to
+     * (`patchedText`). As text, through a text node's `data`, never as markup.
+     */
+    const applyPatch = (entryId, fields) => {
+        for (const change of fields) {
+            for (const el of matching(entryId, change.field)) {
+                let node = textNodeOf(el);
+                // An empty field shows as an empty element: it takes the first text.
+                if (!node && change.saved.trim() === "" && el.childNodes.length === 0) {
+                    node = document.createTextNode("");
+                    el.appendChild(node);
+                }
+                if (!node)
+                    continue;
+                const before = written.get(node);
+                const around = before ?? (0, protocol_js_1.textAround)(node.data);
+                const next = (0, protocol_js_1.patchedText)(node.data, change, before ? before.text : null, around);
+                if (next === null)
+                    continue;
+                node.data = next;
+                written.set(node, { text: change.value, lead: around.lead, trail: around.trail });
+                writtenIn.set(el, node);
+            }
+        }
+        // The boxes follow the text's new size.
+        render();
+    };
+    // ------------------------------------------------------------ messages ---
+    const onMessage = (event) => {
+        const message = (0, protocol_js_1.acceptMessage)(event, origins, window.parent);
+        if (!message)
+            return;
+        switch (message.type) {
+            case "hello":
+                adminOrigin = event.origin;
+                lastVisible = "";
+                sendReady(true);
+                render();
+                return;
+            case "highlight": {
+                if (message.entryId === "") {
+                    highlight = null;
+                    render();
+                    return;
+                }
+                highlight = { entryId: message.entryId, field: message.field };
+                const first = matching(message.entryId, message.field)[0];
+                if (first)
+                    first.scrollIntoView({ block: "center", behavior: "smooth" });
+                render();
+                return;
+            }
+            case "outline":
+                outlineAll = message.on;
+                render();
+                return;
+            case "refresh":
+                refresh();
+                return;
+            case "patch":
+                // Only from the admin this page is talking to.
+                if (!adminOrigin || event.origin !== adminOrigin)
+                    return;
+                applyPatch(message.entryId, message.fields);
+                return;
+        }
+    };
+    // --------------------------------------------------------- interaction ---
+    const closestFrom = (target, selector) => {
+        const el = target;
+        return el && typeof el.closest === "function" ? el.closest(selector) : null;
+    };
+    const taggedFrom = (target) => closestFrom(target, TAGGED);
+    /**
+     * A ⌘-click on a tagged link: click the same spot again, without the
+     * modifier, and let it through. The site then follows the link in this
+     * frame exactly as it would for a visitor's click: a Next `<Link>`
+     * navigates client-side, a plain `<a>` loads the page, `target` and the
+     * site's own handlers are honoured. The browser's own ⌘-click would open a
+     * new tab, outside the editor.
+     */
+    const follow = (event) => {
+        const target = event.target;
+        const click = new MouseEvent("click", {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+            view: window,
+            detail: event.detail,
+            screenX: event.screenX,
+            screenY: event.screenY,
+            clientX: event.clientX,
+            clientY: event.clientY,
+            button: 0,
+        });
+        following = true;
+        try {
+            target.dispatchEvent(click);
+        }
+        finally {
+            following = false;
+        }
+    };
+    const onClick = (event) => {
+        // Only once the admin has said hello: a framed page that is not talking to
+        // Capa keeps its links working. And never the plain click `follow` sends.
+        if (!adminOrigin || following)
+            return;
+        const el = taggedFrom(event.target);
+        if (!el)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        if ((apple ? event.metaKey : event.ctrlKey) && closestFrom(event.target, LINK)) {
+            follow(event);
+            return;
+        }
+        post((0, protocol_js_1.selectMessage)(el.getAttribute("data-capa-entry") ?? "", el.getAttribute("data-capa-field") ?? ""));
+    };
+    const updateHover = () => {
+        hoverFrame = 0;
+        const el = taggedFrom(lastPointer);
+        const link = el ? closestFrom(lastPointer, LINK) : null;
+        if (el === hovered && link === hoveredLink)
+            return;
+        const moved = el !== hovered;
+        hovered = el;
+        hoveredLink = link;
+        if (moved) {
+            post(el
+                ? (0, protocol_js_1.hoverMessage)(el.getAttribute("data-capa-entry") ?? "", el.getAttribute("data-capa-field"))
+                : (0, protocol_js_1.hoverMessage)("", null));
+        }
+        render();
+    };
+    const onPointerMove = (event) => {
+        if (!adminOrigin)
+            return;
+        lastPointer = event.target;
+        if (!hoverFrame)
+            hoverFrame = window.requestAnimationFrame(updateHover);
+    };
+    const onPointerLeave = () => {
+        lastPointer = null;
+        if (!hoverFrame)
+            hoverFrame = window.requestAnimationFrame(updateHover);
+    };
+    const observer = new MutationObserver((records) => {
+        // Our own layer redrawing is not the page changing.
+        if (records.every((r) => layer !== null && (r.target === layer || layer.contains(r.target))))
+            return;
+        scheduleReady();
+        render();
+        restoreScroll();
+    });
+    const INTENT = ["wheel", "touchmove", "keydown"];
+    window.addEventListener("message", onMessage);
+    window.addEventListener("scroll", onScroll, { capture: true, passive: true });
+    window.addEventListener("resize", render, { passive: true });
+    window.addEventListener("popstate", scheduleReady);
+    for (const type of INTENT)
+        window.addEventListener(type, onScrollIntent, { capture: true, passive: true });
+    document.addEventListener("click", onClick, true);
+    document.addEventListener("pointermove", onPointerMove, { capture: true, passive: true });
+    document.documentElement.addEventListener("pointerleave", onPointerLeave);
+    observer.observe(document.body, { childList: true, subtree: true, characterData: true });
+    const dispose = () => {
+        window.removeEventListener("message", onMessage);
+        window.removeEventListener("scroll", onScroll, { capture: true });
+        window.removeEventListener("resize", render);
+        window.removeEventListener("popstate", scheduleReady);
+        for (const type of INTENT)
+            window.removeEventListener(type, onScrollIntent, { capture: true });
+        document.removeEventListener("click", onClick, true);
+        document.removeEventListener("pointermove", onPointerMove, { capture: true });
+        document.documentElement.removeEventListener("pointerleave", onPointerLeave);
+        observer.disconnect();
+        for (const id of [frame, readyFrame, hoverFrame])
+            if (id)
+                window.cancelAnimationFrame(id);
+        if (visibleTimer)
+            window.clearTimeout(visibleTimer);
+        // A refresh still pending when the overlay goes must not reload the page later.
+        if (refreshTimer)
+            window.clearTimeout(refreshTimer);
+        refreshTimer = 0;
+        refreshes++;
+        layer?.remove();
+        layer = null;
+        if (running?.dispose === dispose)
+            running = null;
+    };
+    return {
+        dispose,
+        setOptions: (next) => {
+            origins = (0, protocol_js_1.normaliseOrigins)(next.adminOrigins ?? []);
+            onRefresh = next.onRefresh;
+            refreshTimeout = timeoutOf(next.refreshTimeoutMs);
+            if (adminOrigin && !origins.includes(adminOrigin))
+                adminOrigin = null;
+        },
+    };
+}