@simmalugnt-se/payload-visual-editing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simmalugnt AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @simmalugnt-se/payload-visual-editing
+
+Click a block or field in Payload's Live Preview to open it in the edit form. Tabs are opened, rows
+expanded, the field scrolled into view and highlighted; rich text puts the cursor in the clicked
+paragraph. Focusing a field in Admin outlines it in the preview; clicking anything else clears it.
+
+Requires Payload `>=3.85.2 <4` and React 19.
+
+## Setup
+
+1. Install:
+
+   ```bash
+   pnpm add @simmalugnt-se/payload-visual-editing
+   ```
+
+2. Enable it for the collections that have Live Preview, then regenerate the import map:
+
+   ```ts
+   import { visualEditingPlugin } from "@simmalugnt-se/payload-visual-editing";
+
+   plugins: [visualEditingPlugin({ collections: ["pages"] })];
+   ```
+
+   ```bash
+   pnpm payload generate:importmap
+   ```
+
+3. Render the preview listener next to Payload's own, only in draft mode:
+
+   ```tsx
+   "use client";
+   import { RefreshRouteOnSave } from "@payloadcms/live-preview-react";
+   import { VisualEditingPreview } from "@simmalugnt-se/payload-visual-editing/frontend";
+
+   export function LivePreviewListener() {
+     const router = useRouter();
+     return (
+       <>
+         <RefreshRouteOnSave refresh={router.refresh} serverURL={serverURL} />
+         <VisualEditingPreview />
+       </>
+     );
+   }
+   ```
+
+4. Mark what can be clicked. Spread the markers only in draft mode:
+
+   ```tsx
+   import {
+     editableBlock,
+     editableField,
+     editableRichText,
+   } from "@simmalugnt-se/payload-visual-editing/frontend";
+
+   // Each block (or array row) on its outermost element:
+   <section {...editableBlock(block)}>
+     // A field inside it, by its name relative to the block ("button.label" inside a group):
+     <h1 {...editableField("headline")}>{block.headline}</h1>
+     // Rich text, on the element whose direct children are the paragraphs:
+     <div {...editableRichText("content")}>
+       <RichText data={block.content} disableContainer />
+     </div>
+   </section>
+   ```
+
+   Marking blocks alone is enough to start: a click then opens the whole block. Add `editableField`
+   where editors should land on a specific field.
+
+## Labels
+
+The outline shows the same names as Admin: the editor's block name, otherwise the block's
+`labels.singular`, then the field's `label`, e.g. "CTA › Button label". Admin sends them to the
+preview when it loads, so nothing needs configuring.

package/dist/admin/VisualEditingAdminBridge.d.ts

@@ -0,0 +1,7 @@
+import "../styles/admin.css";
+/**
+ * Mounted in the document edit view. Listens for clicks reported by the preview window
+ * and brings the matching block (or field) into view in the form: opens tabs, expands rows,
+ * scrolls, focuses and highlights.
+ */
+export declare function VisualEditingAdminBridge(): import("react").JSX.Element;

package/dist/admin/VisualEditingAdminBridge.js

@@ -0,0 +1,310 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useConfig, useDocumentForm, useDocumentInfo, useLivePreviewContext, useTranslation, } from "@payloadcms/ui";
+import { useEffect, useRef } from "react";
+import "../styles/admin.css";
+import { collectBlockLabels } from "../labels.js";
+import { fieldDomId, focusTargets, isReadyMessage, isSelectMessage, MESSAGE_TYPE, matchNodeIndex, pathFromDomId, pathFromRowDomId, resolveBlockTarget, rowDomId, } from "../protocol.js";
+import { planReveal } from "../reveal-plan.js";
+import { HIGHLIGHT_TINT } from "../theme.js";
+const HIGHLIGHT_CLASS = "pve-highlight";
+const HIGHLIGHT_MS = 1600;
+/** Tabs and rows render within a few frames. */
+const WAIT_MS = 1000;
+/** Rich text editors are lazy loaded and can take noticeably longer to mount. Only rich text clicks wait this long. */
+const FIELD_WAIT_MS = 4000;
+/**
+ * Mounted in the document edit view. Listens for clicks reported by the preview window
+ * and brings the matching block (or field) into view in the form: opens tabs, expands rows,
+ * scrolls, focuses and highlights.
+ */
+export function VisualEditingAdminBridge() {
+    const livePreview = useLivePreviewContext();
+    const form = useDocumentForm();
+    const { config, getEntityConfig } = useConfig();
+    const { collectionSlug } = useDocumentInfo();
+    const { i18n } = useTranslation();
+    const language = i18n.language;
+    const anchorRef = useRef(null);
+    const latest = useRef({ form, livePreview, config, getEntityConfig, collectionSlug, language });
+    useEffect(() => {
+        latest.current = { form, livePreview, config, getEntityConfig, collectionSlug, language };
+    });
+    useEffect(() => {
+        let run = 0;
+        const onMessage = (event) => {
+            // Only trust the preview window Payload itself opened; origin alone is not enough
+            // because the preview often shares the Admin origin.
+            const preview = latest.current.livePreview;
+            const fromPreview = event.source !== null &&
+                (event.source === preview?.iframeRef?.current?.contentWindow ||
+                    event.source === preview?.popupRef?.current);
+            if (!fromPreview) {
+                return;
+            }
+            if (isReadyMessage(event.data)) {
+                sendLabels(event.source, event.origin);
+                return;
+            }
+            if (!isSelectMessage(event.data)) {
+                return;
+            }
+            run += 1;
+            void select(event.data, run);
+        };
+        const sendLabels = (preview, origin) => {
+            const { config, getEntityConfig, collectionSlug, language } = latest.current;
+            const message = {
+                type: MESSAGE_TYPE,
+                action: "labels",
+                blocks: collectBlockLabels(rootFieldsOf(getEntityConfig, collectionSlug), config.blocksMap, language),
+            };
+            preview.postMessage(message, origin);
+        };
+        const select = async (message, id) => {
+            const { form, config, getEntityConfig, collectionSlug } = latest.current;
+            const fields = form.getFields();
+            const target = resolveBlockTarget(fields, message.blockId);
+            if (!target) {
+                return;
+            }
+            expandRows(target, fields, form.dispatchFields);
+            const rootFields = rootFieldsOf(getEntityConfig, collectionSlug);
+            const lookup = {
+                blockTypeAt: (rowPath) => rowAt(fields, rowPath)?.blockType,
+                blocksBySlug: config.blocksMap,
+            };
+            const fieldPath = message.field ? `${target.rowPath}.${message.field}` : undefined;
+            const fieldPlan = fieldPath ? planReveal(rootFields, fieldPath, lookup) : null;
+            const plan = fieldPlan ?? planReveal(rootFields, target.rowPath, lookup) ?? [];
+            const root = formRoot(anchorRef.current);
+            const opened = await openSteps(plan, root, () => id === run);
+            if (!opened || id !== run) {
+                return;
+            }
+            // Wait for the field itself; the row renders first and would otherwise win.
+            const field = fieldPlan && message.field ? `${target.rowPath}.${message.field}` : undefined;
+            const element = (field
+                ? await waitFor(() => findField(field), message.node ? FIELD_WAIT_MS : WAIT_MS)
+                : null) ?? (await waitFor(() => findRow(target)));
+            if (!element || id !== run) {
+                return;
+            }
+            if (message.node && (await revealRichTextNode(element, message.node))) {
+                return;
+            }
+            reveal(element, field !== undefined && element !== findRow(target));
+        };
+        window.addEventListener("message", onMessage);
+        return () => window.removeEventListener("message", onMessage);
+    }, []);
+    // Admin → preview: outline the block the editor is working in, or clear the outline.
+    // Sent on every click and focus change, even back to the same field: a click in the preview
+    // may have moved the selection since. Anything outside a block's fields and row (the document
+    // title, empty space, the nav) has no targets, which clears the selection.
+    useEffect(() => {
+        const onInteract = (event) => {
+            if (!(event.target instanceof Element) || event.target instanceof HTMLIFrameElement) {
+                // Focus moving into the preview iframe is the preview's own click; it already selected.
+                return;
+            }
+            const root = formRoot(anchorRef.current);
+            const path = root.contains(event.target) ? pathOf(event.target) : undefined;
+            const fields = latest.current.form.getFields();
+            const targets = path ? focusTargets(path, fields) : [];
+            postToPreview(latest.current.livePreview, { type: MESSAGE_TYPE, action: "focus", targets });
+        };
+        document.addEventListener("pointerdown", onInteract, true);
+        document.addEventListener("focusin", onInteract);
+        return () => {
+            document.removeEventListener("pointerdown", onInteract, true);
+            document.removeEventListener("focusin", onInteract);
+        };
+    }, []);
+    return _jsx("span", { hidden: true, ref: anchorRef });
+}
+function rootFieldsOf(getEntityConfig, collectionSlug) {
+    return collectionSlug
+        ? (getEntityConfig({ collectionSlug })?.fields ?? [])
+        : [];
+}
+/**
+ * Form path of the field or row an element belongs to. Rich text wrappers carry
+ * `data-field-path`, inputs carry `field-…` ids, block and array rows (header included) `…-row-N` ids.
+ */
+function pathOf(element) {
+    const field = element.closest("[data-field-path], [id^='field-']");
+    const row = closestRow(element);
+    // The blocks field itself carries a `field-…` id, so a row header sits inside a "field";
+    // whichever is innermost is what was clicked.
+    if (row && (!field || field.contains(row.element))) {
+        return row.path;
+    }
+    return field ? (field.getAttribute("data-field-path") ?? pathFromDomId(field.id)) : undefined;
+}
+function closestRow(element) {
+    let row = element.closest("[id*='-row-']");
+    while (row) {
+        const path = pathFromRowDomId(row.id);
+        if (path) {
+            return { element: row, path };
+        }
+        row = row.parentElement?.closest("[id*='-row-']") ?? null;
+    }
+    return undefined;
+}
+function postToPreview(preview, message) {
+    const target = preview?.popupRef?.current ?? preview?.iframeRef?.current?.contentWindow;
+    const url = typeof preview?.url === "string" ? preview.url : undefined;
+    if (!target || !url) {
+        return;
+    }
+    try {
+        target.postMessage(message, new URL(url, window.location.href).origin);
+    }
+    catch {
+        // Preview URL was not a valid URL; nothing to notify.
+    }
+}
+function expandRows(target, fields, dispatchFields) {
+    for (const step of target.rows) {
+        const rows = fields[step.parentPath]?.rows;
+        if (!rows?.[step.index]?.collapsed) {
+            continue;
+        }
+        dispatchFields({
+            type: "SET_ROW_COLLAPSED",
+            path: step.parentPath,
+            updatedRows: rows.map((row, index) => index === step.index ? { ...row, collapsed: false } : row),
+        });
+    }
+}
+function rowAt(fields, rowPath) {
+    const cut = rowPath.lastIndexOf(".");
+    return fields[rowPath.slice(0, cut)]?.rows?.[Number(rowPath.slice(cut + 1))];
+}
+/** The edit form this bridge belongs to, not one in a document drawer. */
+function formRoot(anchor) {
+    const view = anchor?.closest(".collection-edit");
+    return view?.querySelector(".collection-edit__form") ?? document;
+}
+/** Click the tabs the plan needs, one level at a time, waiting for each tab's content to render. */
+async function openSteps(steps, root, current) {
+    let scope = root;
+    for (const step of steps) {
+        if (!current()) {
+            return false;
+        }
+        if (step.kind === "row") {
+            const row = await waitFor(() => document.getElementById(rowDomId(step)));
+            if (!row) {
+                return false;
+            }
+            scope = row;
+            continue;
+        }
+        const tabs = await waitFor(() => tabsFieldsIn(scope)[step.ordinal] ?? null);
+        const button = tabs?.querySelectorAll(":scope > .tabs-field__tabs-wrap > .tabs-field__tabs > .tabs-field__tab-button")[step.index];
+        if (!tabs || !button) {
+            return false;
+        }
+        if (!button.classList.contains("tabs-field__tab-button--active")) {
+            button.click();
+        }
+        const content = await waitFor(() => button.classList.contains("tabs-field__tab-button--active")
+            ? tabs.querySelector(":scope > .tabs-field__content-wrap")
+            : null);
+        if (!content) {
+            return false;
+        }
+        scope = content;
+    }
+    return true;
+}
+/** Tabs fields at this level of the scope, in DOM order; nested tabs and rows are other scopes. */
+function tabsFieldsIn(scope) {
+    return Array.from(scope.querySelectorAll(".tabs-field")).filter((element) => {
+        const outer = element.parentElement?.closest(".tabs-field, .blocks-field, .array-field");
+        return !outer || !scope.contains(outer);
+    });
+}
+function waitFor(find, timeoutMs = WAIT_MS) {
+    const deadline = performance.now() + timeoutMs;
+    return new Promise((resolve) => {
+        const tick = () => {
+            const found = find();
+            if (found || performance.now() >= deadline) {
+                resolve(found);
+                return;
+            }
+            requestAnimationFrame(tick);
+        };
+        tick();
+    });
+}
+/** Inputs carry `field-…` ids; rich text and some other fields only carry `data-field-path`. */
+function findField(path) {
+    return (document.getElementById(fieldDomId(path)) ??
+        document.querySelector(`[data-field-path="${CSS.escape(path)}"]`));
+}
+function findRow(target) {
+    const last = target.rows.at(-1);
+    return last ? document.getElementById(rowDomId(last)) : null;
+}
+/**
+ * Put the cursor at the start of the clicked paragraph in a Lexical editor.
+ * Lexical renders each top-level node as one child of the contenteditable root.
+ */
+async function revealRichTextNode(field, node) {
+    const editor = await waitFor(() => field.querySelector("[contenteditable='true'][data-lexical-editor='true']") ??
+        field.querySelector("[contenteditable='true']"), FIELD_WAIT_MS);
+    const children = editor ? Array.from(editor.children) : [];
+    if (!editor || children.length === 0) {
+        return false;
+    }
+    const target = children[matchNodeIndex(children.map((child) => child.textContent ?? ""), node)];
+    if (!(target instanceof HTMLElement)) {
+        return false;
+    }
+    target.scrollIntoView({ behavior: "smooth", block: "center" });
+    editor.focus({ preventScroll: true });
+    const range = document.createRange();
+    const firstText = document.createTreeWalker(target, NodeFilter.SHOW_TEXT).nextNode();
+    range.setStart(firstText ?? target, 0);
+    range.collapse(true);
+    const selection = window.getSelection();
+    selection?.removeAllRanges();
+    selection?.addRange(range);
+    // Animate instead of adding a class: Lexical owns this element's attributes.
+    target.animate([{ backgroundColor: HIGHLIGHT_TINT }, { backgroundColor: "transparent" }], {
+        duration: HIGHLIGHT_MS,
+        easing: "ease-out",
+    });
+    return true;
+}
+/**
+ * Scroll to and highlight a field or a block row. Only a field gets focus: focusing a row
+ * would land in its first input (the block name), which is not what was clicked.
+ */
+function reveal(element, isField) {
+    // A row sits inside the blocks field's `.field-type`; highlighting that would mark the whole list.
+    const highlighted = isField ? (element.closest(".field-type") ?? element) : element;
+    highlighted.scrollIntoView({ behavior: "smooth", block: "center" });
+    if (isField) {
+        const focusable = isFocusable(element)
+            ? element
+            : (element.querySelector("input:not([type='hidden']):not([type='file']), textarea, select, [contenteditable='true']") ?? element.querySelector("button:not([disabled])"));
+        focusable?.focus({ preventScroll: true });
+    }
+    highlighted.classList.remove(HIGHLIGHT_CLASS);
+    // Restart the animation when the same element is clicked twice.
+    void highlighted.offsetWidth;
+    highlighted.classList.add(HIGHLIGHT_CLASS);
+    window.setTimeout(() => highlighted.classList.remove(HIGHLIGHT_CLASS), HIGHLIGHT_MS);
+}
+function isFocusable(element) {
+    return (element instanceof HTMLInputElement ||
+        element instanceof HTMLTextAreaElement ||
+        element instanceof HTMLSelectElement ||
+        element.isContentEditable);
+}

package/dist/exports/client.d.ts

@@ -0,0 +1 @@
+export { VisualEditingAdminBridge } from "../admin/VisualEditingAdminBridge.tsx";

package/dist/exports/client.js

@@ -0,0 +1 @@
+export { VisualEditingAdminBridge } from "../admin/VisualEditingAdminBridge.js";

package/dist/exports/frontend.d.ts

@@ -0,0 +1,2 @@
+export { editableBlock, editableField, editableRichText } from "../frontend/editable.ts";
+export { VisualEditingPreview } from "../frontend/VisualEditingPreview.tsx";

package/dist/exports/frontend.js

@@ -0,0 +1,2 @@
+export { editableBlock, editableField, editableRichText } from "../frontend/editable.js";
+export { VisualEditingPreview } from "../frontend/VisualEditingPreview.js";

package/dist/frontend/VisualEditingPreview.d.ts

@@ -0,0 +1,10 @@
+type Props = {
+    /** Origin of Payload Admin. Defaults to the page that embedded the preview. */
+    adminOrigin?: string;
+};
+/**
+ * Render only in draft mode. Inside the Live Preview window it outlines editable blocks
+ * on hover and tells Admin which block or field was clicked. Outside a preview window it does nothing.
+ */
+export declare function VisualEditingPreview({ adminOrigin }: Props): null;
+export {};