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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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.
 

package/dist/admin/VisualEditingAdminBridge.js

@@ -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,
@@ -82,22 +86,23 @@ export function VisualEditingAdminBridge() {
             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) {
+            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);
@@ -192,25 +197,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 +228,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 +283,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 +294,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 +314,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);
             });
@@ -61,9 +82,11 @@ export function VisualEditingPreview({ adminOrigin }) {
                 clearSelection();
                 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 = {
@@ -121,6 +144,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 +158,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 +208,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/package.json

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