@simmalugnt-se/payload-visual-editing 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.2.0
+
+- A click in the preview dispatches `visual-editing:select` on Admin's `window` with the form path,
+  so other Admin components can follow the selection, and with `path: null` when the editor clears
+  it in the preview (empty space, Escape).
+- Clicks inside `data-visual-editing-keep-selection` keep the preview outline.
+
+## 0.1.2
+
+- A click in the preview no longer blocks the page's own click handlers: accordions, tabs and
+  sliders keep working while the click also selects. Only links and form submits are cancelled, so
+  the preview does not navigate away.
+- The outline follows its element when it changes size or moves without scrolling, e.g. an accordion
+  opening, instead of waiting for the next pointer move.
+- Admin scrolls to the right field even while the form grows under the scroll (field groups
+  rendering, textareas resizing): it waits for the layout to settle, and scrolls again if the target
+  moved out of view.
+- Clicks in the preview no longer sometimes do nothing. Payload renders a group of fields only when
+  it is near the viewport, so rows, tabs and fields far down the form were not in the DOM yet; the
+  Admin bridge now scrolls each level into view before waiting for the next one.
+
 ## 0.1.1
 
 - Array rows in the preview outline are labeled like Admin's row headers ("Item 02 › Title")

package/README.md

@@ -4,6 +4,9 @@ Click a block or field in Payload's Live Preview to open it in the edit form. Ta
 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.
 
+In the preview a click selects without leaving the page: links and form submits are cancelled, while
+the page's own click handlers (accordions, tabs, sliders) still run.
+
 Requires Payload `>=3.85.2 <4` and React 19.
 
 ## Setup
@@ -64,6 +67,9 @@ Requires Payload `>=3.85.2 <4` and React 19.
    </section>
    ```
 
+   In lists, put `key` before the spread (`<li key={row.id} {...editableBlock(row)}>`). A spread
+   before `key` makes React warn that list children have no unique key.
+
    Marking blocks alone is enough to start: a click then opens the whole block. Add `editableField`
    where editors should land on a specific field.
 
@@ -72,3 +78,23 @@ Requires Payload `>=3.85.2 <4` and React 19.
 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". Array rows get their row
 header, e.g. "Item 02 › Title". Admin sends the labels to the preview, so nothing needs configuring.
+
+## Following the selection in other Admin components
+
+A click in the preview dispatches `visual-editing:select` on Admin's `window`, with the form path
+in `detail.path` (`layout.2` for a block, `layout.2.headline` for a field), and with `path: null`
+when the editor clears the selection in the preview (empty space, Escape). Other components can
+follow the editor's selection without depending on this package;
+`@simmalugnt-se/payload-editor-assistant` uses it so "this" in a message means the clicked block.
+
+```ts
+window.addEventListener("visual-editing:select", (event) => {
+  const { path } = (event as CustomEvent<{ path: string | null }>).detail;
+});
+```
+
+Clicks in Admin clear the preview outline. Put `data-visual-editing-keep-selection` on a panel
+whose clicks should keep it, such as a chat next to the form.
+
+The event name, its `detail` and the attribute are public API: renaming or removing them is a
+breaking change and needs a major version.

package/dist/admin/VisualEditingAdminBridge.js

@@ -4,7 +4,7 @@ import { useConfig, useDocumentForm, useDocumentInfo, useLivePreviewContext, use
 import { useEffect, useRef } from "react";
 import "../styles/admin.css";
 import { collectBlockLabels, collectRowLabels } from "../labels.js";
-import { fieldDomId, focusTargets, isReadyMessage, isSelectMessage, MESSAGE_TYPE, matchNodeIndex, pathFromDomId, pathFromRowDomId, resolveBlockTarget, rowDomId, } from "../protocol.js";
+import { ATTR_KEEP_SELECTION, fieldDomId, focusTargets, isClearMessage, isReadyMessage, isSelectMessage, MESSAGE_TYPE, matchNodeIndex, pathFromDomId, pathFromRowDomId, resolveBlockTarget, rowDomId, SELECT_EVENT, } from "../protocol.js";
 import { planReveal } from "../reveal-plan.js";
 import { HIGHLIGHT_TINT } from "../theme.js";
 const HIGHLIGHT_CLASS = "pve-highlight";
@@ -13,6 +13,10 @@ const HIGHLIGHT_MS = 1600;
 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;
+/** Frames an element must keep its position before the layout counts as settled. */
+const STABLE_FRAMES = 3;
+/** Roughly how long a smooth scroll takes. */
+const SCROLL_MS = 600;
 /**
  * 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,
@@ -46,6 +50,11 @@ export function VisualEditingAdminBridge() {
                 sendLabels(event.source, event.origin);
                 return;
             }
+            if (isClearMessage(event.data)) {
+                run += 1;
+                window.dispatchEvent(new CustomEvent(SELECT_EVENT, { detail: { path: null } }));
+                return;
+            }
             if (!isSelectMessage(event.data)) {
                 return;
             }
@@ -81,23 +90,27 @@ export function VisualEditingAdminBridge() {
             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) ?? [];
+            window.dispatchEvent(new CustomEvent(SELECT_EVENT, {
+                detail: { path: fieldPlan && fieldPath ? fieldPath : target.rowPath },
+            }));
             const root = formRoot(anchorRef.current);
-            const opened = await openSteps(plan, root, () => id === run);
-            if (!opened || id !== run) {
+            const scope = await openSteps(plan, root, () => id === run);
+            if (!scope || 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)
+                ? await waitForRendered(() => findField(field), scope, 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))) {
+            const current = () => id === run;
+            if (message.node && (await revealRichTextNode(element, message.node, current))) {
                 return;
             }
-            reveal(element, field !== undefined && element !== findRow(target));
+            await reveal(element, field !== undefined && element !== findRow(target), current);
         };
         window.addEventListener("message", onMessage);
         return () => window.removeEventListener("message", onMessage);
@@ -112,6 +125,9 @@ export function VisualEditingAdminBridge() {
                 // Focus moving into the preview iframe is the preview's own click; it already selected.
                 return;
             }
+            if (event.target.closest(`[${ATTR_KEEP_SELECTION}]`)) {
+                return;
+            }
             const root = formRoot(anchorRef.current);
             const path = root.contains(event.target) ? pathOf(event.target) : undefined;
             const fields = latest.current.form.getFields();
@@ -192,25 +208,29 @@ 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. */
+/**
+ * Open the rows and tabs the plan needs, one level at a time, waiting for each to render.
+ * Returns the innermost scope (row or tab content), where the target field renders.
+ */
 async function openSteps(steps, root, current) {
     let scope = root;
     for (const step of steps) {
         if (!current()) {
-            return false;
+            return null;
         }
         if (step.kind === "row") {
-            const row = await waitFor(() => document.getElementById(rowDomId(step)));
+            const row = await waitForRendered(() => document.getElementById(rowDomId(step)), scope);
             if (!row) {
-                return false;
+                return null;
             }
             scope = row;
             continue;
         }
-        const tabs = await waitFor(() => tabsFieldsIn(scope)[step.ordinal] ?? null);
+        const tabsScope = scope;
+        const tabs = await waitForRendered(() => tabsFieldsIn(tabsScope)[step.ordinal] ?? null, tabsScope);
         const button = tabs?.querySelectorAll(":scope > .tabs-field__tabs-wrap > .tabs-field__tabs > .tabs-field__tab-button")[step.index];
         if (!tabs || !button) {
-            return false;
+            return null;
         }
         if (!button.classList.contains("tabs-field__tab-button--active")) {
             button.click();
@@ -219,11 +239,26 @@ async function openSteps(steps, root, current) {
             ? tabs.querySelector(":scope > .tabs-field__content-wrap")
             : null);
         if (!content) {
-            return false;
+            return null;
         }
         scope = content;
     }
-    return true;
+    return scope;
+}
+/**
+ * Payload renders a group of fields only once it is within 1000px of the viewport
+ * (`RenderIfInViewport`); until then the group is an empty div. So when the next level is not in
+ * the DOM yet, bring the enclosing scope into view to make Payload render it, then wait.
+ */
+async function waitForRendered(find, scope, timeoutMs = WAIT_MS) {
+    const found = find();
+    if (found) {
+        return found;
+    }
+    if (scope instanceof HTMLElement) {
+        scope.scrollIntoView({ block: "start" });
+    }
+    return waitFor(find, timeoutMs);
 }
 /** Tabs fields at this level of the scope, in DOM order; nested tabs and rows are other scopes. */
 function tabsFieldsIn(scope) {
@@ -259,7 +294,7 @@ function findRow(target) {
  * 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) {
+async function revealRichTextNode(field, node, current) {
     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) : [];
@@ -270,7 +305,7 @@ async function revealRichTextNode(field, node) {
     if (!(target instanceof HTMLElement)) {
         return false;
     }
-    target.scrollIntoView({ behavior: "smooth", block: "center" });
+    await scrollWhenSettled(target, current);
     editor.focus({ preventScroll: true });
     const range = document.createRange();
     const firstText = document.createTreeWalker(target, NodeFilter.SHOW_TEXT).nextNode();
@@ -290,21 +325,66 @@ async function revealRichTextNode(field, node) {
  * 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) {
+async function reveal(element, isField, current) {
     // 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 });
+    await scrollWhenSettled(highlighted, current, () => {
+        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);
+    });
+}
+/**
+ * Scroll `element` to the middle of the form, robust to the form changing under the scroll:
+ * Payload renders field groups as they come near the viewport and textareas grow to fit their
+ * text, which pushes the target down. Start once its position is stable, and scroll again if it
+ * has moved out of view by the time the scroll is done. `onScroll` runs as the scroll starts.
+ */
+async function scrollWhenSettled(element, current, onScroll) {
+    await layoutSettled(element);
+    if (!current()) {
+        return;
+    }
+    element.scrollIntoView({ behavior: "smooth", block: "center" });
+    onScroll?.();
+    await new Promise((resolve) => window.setTimeout(resolve, SCROLL_MS));
+    await layoutSettled(element);
+    if (current() && !inView(element)) {
+        element.scrollIntoView({ behavior: "smooth", block: "center" });
     }
-    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);
+}
+/** Resolves once the element has kept its position for a few frames (or after a timeout). */
+function layoutSettled(element, timeoutMs = WAIT_MS) {
+    const deadline = performance.now() + timeoutMs;
+    let last = Number.NaN;
+    let stable = 0;
+    return new Promise((resolve) => {
+        const tick = () => {
+            const top = element.getBoundingClientRect().top;
+            stable = top === last ? stable + 1 : 0;
+            last = top;
+            if (stable >= STABLE_FRAMES || performance.now() >= deadline) {
+                resolve();
+                return;
+            }
+            requestAnimationFrame(tick);
+        };
+        tick();
+    });
+}
+/** Mostly visible: its middle, or for a tall element any part, is within the middle of the viewport. */
+function inView(element) {
+    const rect = element.getBoundingClientRect();
+    const margin = window.innerHeight * 0.15;
+    return rect.bottom > margin && rect.top < window.innerHeight - margin;
 }
 function isFocusable(element) {
     return (element instanceof HTMLInputElement ||

package/dist/frontend/VisualEditingPreview.js

@@ -28,9 +28,30 @@ export function VisualEditingPreview({ adminOrigin }) {
             }
         };
         let frame = 0;
+        // Outlined elements can change size without any scroll or pointer event (an accordion opening,
+        // an image loading); follow them. Observing a new element runs the callback once, which only
+        // re-places the outlines, so this settles.
+        const observed = new Set();
+        const resizes = new ResizeObserver(() => redraw());
+        const observeOutlined = () => {
+            const wanted = new Set([hovered?.element, current?.element].filter((el) => !!el));
+            for (const element of observed) {
+                if (!wanted.has(element)) {
+                    resizes.unobserve(element);
+                    observed.delete(element);
+                }
+            }
+            for (const element of wanted) {
+                if (!observed.has(element)) {
+                    resizes.observe(element);
+                    observed.add(element);
+                }
+            }
+        };
         const redraw = () => {
             cancelAnimationFrame(frame);
             frame = requestAnimationFrame(() => {
+                observeOutlined();
                 place(hover, hovered && hovered.element !== current?.element ? hovered : null);
                 place(selected, current);
             });
@@ -54,16 +75,27 @@ export function VisualEditingPreview({ adminOrigin }) {
                 redraw();
             }
         };
+        /** The editor dropped the selection here; Admin tells components following it. */
+        const dropSelection = () => {
+            if (!current) {
+                return;
+            }
+            clearSelection();
+            const message = { type: MESSAGE_TYPE, action: "clear" };
+            admin.postMessage(message, targetOrigin);
+        };
         const onClick = (event) => {
             const hit = hitFromTarget(event.target, labels);
             if (!hit) {
                 // Outside any editable element the page behaves normally; only the selection is dropped.
-                clearSelection();
+                dropSelection();
                 return;
             }
-            // In the editor a click selects; it must not follow links or submit forms.
-            event.preventDefault();
-            event.stopPropagation();
+            // A click selects, and must not leave the page: links and submits are cancelled. Anything
+            // else still reaches the page's own handlers, so accordions, tabs and sliders keep working.
+            if (navigates(event.target)) {
+                event.preventDefault();
+            }
             current = hit;
             redraw();
             const message = {
@@ -111,7 +143,7 @@ export function VisualEditingPreview({ adminOrigin }) {
         };
         const onKeyDown = (event) => {
             if (event.key === "Escape") {
-                clearSelection();
+                dropSelection();
             }
         };
         document.addEventListener("pointermove", onPointerMove, { passive: true });
@@ -121,6 +153,9 @@ export function VisualEditingPreview({ adminOrigin }) {
         window.addEventListener("message", onMessage);
         window.addEventListener("scroll", redraw, { passive: true, capture: true });
         window.addEventListener("resize", redraw);
+        // Elements that move because something above them grew or shrank.
+        document.addEventListener("transitionend", redraw, true);
+        document.addEventListener("animationend", redraw, true);
         const ready = { type: MESSAGE_TYPE, action: "ready" };
         admin.postMessage(ready, targetOrigin);
         return () => {
@@ -132,6 +167,9 @@ export function VisualEditingPreview({ adminOrigin }) {
             window.removeEventListener("message", onMessage);
             window.removeEventListener("scroll", redraw, { capture: true });
             window.removeEventListener("resize", redraw);
+            document.removeEventListener("transitionend", redraw, true);
+            document.removeEventListener("animationend", redraw, true);
+            resizes.disconnect();
             hover.remove();
             selected.remove();
         };
@@ -179,6 +217,17 @@ function labelFor(block, field, labels) {
     }
     return `${blockLabel} › ${known?.fields[field] ?? humanize(field)}`;
 }
+/** Whether the default action of a click here would navigate away or submit a form. */
+function navigates(target) {
+    if (!(target instanceof Element)) {
+        return false;
+    }
+    if (target.closest("a[href]")) {
+        return true;
+    }
+    const control = target.closest("button, input");
+    return !!control?.form && control.type === "submit";
+}
 /** Rows marked without a block type are array rows. */
 function isArrayRow(element) {
     const row = element.closest(`[${ATTR_BLOCK}]`);

package/dist/protocol.d.ts

@@ -9,6 +9,15 @@ export declare const ATTR_BLOCK_NAME = "data-payload-block-name";
 export declare const ATTR_FIELD = "data-payload-field";
 /** On the rich text container whose direct children are the top-level editor nodes. */
 export declare const ATTR_RICHTEXT = "data-payload-richtext";
+/**
+ * Dispatched on Admin's `window` when a preview click selects something, with the form path as
+ * `detail.path` (`layout.2` for a block, `layout.2.headline` for a field), and with `path: null`
+ * when the editor clears the selection in the preview. Other Admin components, such as an
+ * assistant, can follow the editor's selection without depending on this package.
+ */
+export declare const SELECT_EVENT = "visual-editing:select";
+/** Clicks and focus inside an element with this attribute keep the preview outline. */
+export declare const ATTR_KEEP_SELECTION = "data-visual-editing-keep-selection";
 export type SelectMessage = {
     type: typeof MESSAGE_TYPE;
     action: "select";
@@ -21,6 +30,12 @@ export type SelectMessage = {
         text?: string;
     };
 };
+/** Preview → Admin: the editor dropped the selection in the preview (empty space, Escape). */
+export type ClearMessage = {
+    type: typeof MESSAGE_TYPE;
+    action: "clear";
+};
+export declare function isClearMessage(value: unknown): value is ClearMessage;
 export declare function isSelectMessage(value: unknown): value is SelectMessage;
 /**
  * Pick the editor node matching the clicked preview node. Text wins over index because

package/dist/protocol.js

@@ -8,7 +8,23 @@ export const ATTR_BLOCK_NAME = "data-payload-block-name";
 export const ATTR_FIELD = "data-payload-field";
 /** On the rich text container whose direct children are the top-level editor nodes. */
 export const ATTR_RICHTEXT = "data-payload-richtext";
+/**
+ * Dispatched on Admin's `window` when a preview click selects something, with the form path as
+ * `detail.path` (`layout.2` for a block, `layout.2.headline` for a field), and with `path: null`
+ * when the editor clears the selection in the preview. Other Admin components, such as an
+ * assistant, can follow the editor's selection without depending on this package.
+ */
+export const SELECT_EVENT = "visual-editing:select";
+/** Clicks and focus inside an element with this attribute keep the preview outline. */
+export const ATTR_KEEP_SELECTION = "data-visual-editing-keep-selection";
 const MAX_NODE_TEXT = 200;
+export function isClearMessage(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const message = value;
+    return message.type === MESSAGE_TYPE && message.action === "clear";
+}
 export function isSelectMessage(value) {
     if (!value || typeof value !== "object") {
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simmalugnt-se/payload-visual-editing",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Click a block in Payload Live Preview to open its fields in the edit form",
   "keywords": [
     "payload",