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

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# 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")
+  instead of "Block › Title".
+
+## 0.1.0
+
+- First release: click a block or field in Live Preview to open it in the edit form, with Admin's
+  block and field labels in the preview outline.

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,11 +67,14 @@ 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.
 
 ## 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.
+`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.

package/dist/admin/VisualEditingAdminBridge.js

@@ -3,7 +3,7 @@ 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 { collectBlockLabels, collectRowLabels } 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";
@@ -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,
@@ -53,11 +57,15 @@ export function VisualEditingAdminBridge() {
             void select(event.data, run);
         };
         const sendLabels = (preview, origin) => {
-            const { config, getEntityConfig, collectionSlug, language } = latest.current;
+            const { form, config, getEntityConfig, collectionSlug, language } = latest.current;
+            const fields = form.getFields();
+            const rootFields = rootFieldsOf(getEntityConfig, collectionSlug);
+            const blocksBySlug = config.blocksMap;
             const message = {
                 type: MESSAGE_TYPE,
                 action: "labels",
-                blocks: collectBlockLabels(rootFieldsOf(getEntityConfig, collectionSlug), config.blocksMap, language),
+                blocks: collectBlockLabels(rootFields, blocksBySlug, language),
+                rows: collectRowLabels(rootFields, fields, { blockTypeAt: (rowPath) => rowAt(fields, rowPath)?.blockType, blocksBySlug }, language),
             };
             preview.postMessage(message, origin);
         };
@@ -78,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);
@@ -188,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();
@@ -215,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) {
@@ -255,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) : [];
@@ -266,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();
@@ -286,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;
     }
-    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);
+    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" });
+    }
+}
+/** 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

@@ -19,11 +19,39 @@ export function VisualEditingPreview({ adminOrigin }) {
         let hovered = null;
         let current = null;
         // Until Admin answers, labels fall back to the slugs.
-        let labels = {};
+        let labels = { blocks: {}, rows: {} };
+        // Array row numbers change as rows move, so ask again whenever the pointer reaches a row.
+        const describe = (hit) => {
+            if (hit && isArrayRow(hit.element)) {
+                const message = { type: MESSAGE_TYPE, action: "describe" };
+                admin.postMessage(message, targetOrigin);
+            }
+        };
         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);
             });
@@ -34,6 +62,7 @@ export function VisualEditingPreview({ adminOrigin }) {
                 return;
             }
             hovered = hit;
+            describe(hit);
             redraw();
         };
         const onPointerLeave = () => {
@@ -53,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 = {
@@ -72,7 +103,7 @@ export function VisualEditingPreview({ adminOrigin }) {
                 return;
             }
             if (isLabelsMessage(event.data)) {
-                labels = event.data.blocks;
+                labels = { blocks: event.data.blocks, rows: event.data.rows ?? labels.rows };
                 hovered = hovered && relabel(hovered, labels);
                 current = current && relabel(current, labels);
                 redraw();
@@ -113,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 () => {
@@ -124,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();
         };
@@ -164,13 +201,29 @@ function hitForBlock(blockId, field, labels) {
 /** Same order as Admin's row header: the editor's block name, then the block's label, then its slug. */
 function labelFor(block, field, labels) {
     const type = block.getAttribute(ATTR_BLOCK_TYPE) ?? undefined;
-    const known = type ? labels[type] : undefined;
+    const known = type ? labels.blocks[type] : labels.rows[block.getAttribute(ATTR_BLOCK) ?? ""];
     const blockLabel = block.getAttribute(ATTR_BLOCK_NAME) || known?.label || (type ? humanize(type) : "Block");
     if (!field) {
         return blockLabel;
     }
     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}]`);
+    return !!row && !row.hasAttribute(ATTR_BLOCK_TYPE);
+}
 function relabel(hit, labels) {
     const block = hit.element.closest(`[${ATTR_BLOCK}]`);
     return block ? { ...hit, label: labelFor(block, hit.field, labels) } : hit;

package/dist/labels.d.ts

@@ -3,15 +3,25 @@
  * the same names ("CTA › Title") instead of guessing from slugs ("C ta › Title").
  * Pure: takes client field config, returns plain strings safe to post to the preview.
  */
-import type { BlockLike, FieldLike } from "./reveal-plan.ts";
+import { type BlockLike, type FieldLike, type Lookup } from "./reveal-plan.ts";
 export type BlockLabel = {
     /** `labels.singular` of the block config. */
     label?: string;
     /** Field path relative to the block (e.g. "title", "hero.headline") → its label. */
     fields: Record<string, string>;
 };
-/** Block slug → labels. */
+/** Block slug (or, for array rows, row id) → labels. */
 export type BlockLabels = Record<string, BlockLabel>;
+/** More than any page has; keeps the message within what the preview accepts. */
+export declare const MAX_ROW_LABELS = 500;
 export declare function collectBlockLabels(rootFields: FieldLike[], blocksBySlug: Record<string, BlockLike | undefined> | undefined, language: string): BlockLabels;
+/**
+ * Labels for array rows, keyed by row id, as Admin's row headers show them: "Item 02".
+ * Array rows have no block slug to look labels up by, and their number changes when rows move,
+ * so these come from the current form state rather than the config alone.
+ */
+export declare function collectRowLabels(rootFields: FieldLike[], formFields: Record<string, {
+    value?: unknown;
+} | undefined>, lookup: Lookup, language: string): BlockLabels;
 /** Client config labels are a string or a `{ [language]: string }` map; anything else has no static text. */
 export declare function labelText(label: unknown, language: string): string | undefined;

package/dist/labels.js

@@ -3,6 +3,9 @@
  * the same names ("CTA › Title") instead of guessing from slugs ("C ta › Title").
  * Pure: takes client field config, returns plain strings safe to post to the preview.
  */
+import { fieldAtPath } from "./reveal-plan.js";
+/** More than any page has; keeps the message within what the preview accepts. */
+export const MAX_ROW_LABELS = 500;
 export function collectBlockLabels(rootFields, blocksBySlug, language) {
     const result = {};
     const visitFields = (fields) => {
@@ -28,6 +31,34 @@ export function collectBlockLabels(rootFields, blocksBySlug, language) {
     visitFields(rootFields);
     return result;
 }
+/**
+ * Labels for array rows, keyed by row id, as Admin's row headers show them: "Item 02".
+ * Array rows have no block slug to look labels up by, and their number changes when rows move,
+ * so these come from the current form state rather than the config alone.
+ */
+export function collectRowLabels(rootFields, formFields, lookup, language) {
+    const result = {};
+    for (const [path, formField] of Object.entries(formFields)) {
+        const id = formField?.value;
+        const match = /^(.+)\.(\d+)\.id$/.exec(path);
+        if (typeof id !== "string" || !id || !match) {
+            continue;
+        }
+        const [, parentPath = "", index = "0"] = match;
+        const field = fieldAtPath(rootFields, parentPath, lookup);
+        if (field?.type !== "array") {
+            continue;
+        }
+        const singular = labelText(field.labels?.singular, language) ?? labelText(field.label, language) ?? field.name;
+        const fields = {};
+        collectFieldLabels(field.fields ?? [], "", language, fields);
+        result[id] = { label: `${singular} ${String(Number(index) + 1).padStart(2, "0")}`, fields };
+        if (Object.keys(result).length >= MAX_ROW_LABELS) {
+            break;
+        }
+    }
+    return result;
+}
 /** Labels of the fields a block's preview can mark: named fields and paths into named groups and tabs. */
 function collectFieldLabels(fields, prefix, language, into) {
     for (const field of fields) {

package/dist/protocol.d.ts

@@ -43,17 +43,21 @@ export type FocusMessage = {
     }>;
 };
 export declare function isFocusMessage(value: unknown): value is FocusMessage;
-/** Preview → Admin: the preview has loaded and wants the block labels. */
+/**
+ * Preview → Admin: send the labels. "ready" when the preview loads; "describe" when it points at
+ * an array row, whose number may have changed since.
+ */
 export type ReadyMessage = {
     type: typeof MESSAGE_TYPE;
-    action: "ready";
+    action: "ready" | "describe";
 };
 export declare function isReadyMessage(value: unknown): value is ReadyMessage;
-/** Admin → preview: labels for the overlay, keyed by block slug. */
+/** Admin → preview: labels for the overlay, blocks keyed by slug and array rows by row id. */
 export type LabelsMessage = {
     type: typeof MESSAGE_TYPE;
     action: "labels";
     blocks: BlockLabels;
+    rows?: BlockLabels;
 };
 export declare function isLabelsMessage(value: unknown): value is LabelsMessage;
 /** Inverse of `fieldDomId`: "field-layout__0__headline" → "layout.0.headline". */

package/dist/protocol.js

@@ -77,10 +77,11 @@ export function isFocusMessage(value) {
             (target.field === undefined || isFieldName(target.field))));
 }
 export function isReadyMessage(value) {
-    return (!!value &&
-        typeof value === "object" &&
-        value.type === MESSAGE_TYPE &&
-        value.action === "ready");
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const message = value;
+    return (message.type === MESSAGE_TYPE && (message.action === "ready" || message.action === "describe"));
 }
 const MAX_LABELED_BLOCKS = 500;
 const MAX_LABELED_FIELDS = 500;
@@ -90,10 +91,16 @@ export function isLabelsMessage(value) {
         return false;
     }
     const message = value;
-    if (message.type !== MESSAGE_TYPE || message.action !== "labels" || !isRecord(message.blocks)) {
+    return (message.type === MESSAGE_TYPE &&
+        message.action === "labels" &&
+        isLabelMap(message.blocks) &&
+        (message.rows === undefined || isLabelMap(message.rows)));
+}
+function isLabelMap(value) {
+    if (!isRecord(value)) {
         return false;
     }
-    const blocks = Object.values(message.blocks);
+    const blocks = Object.values(value);
     return (blocks.length <= MAX_LABELED_BLOCKS &&
         blocks.every((block) => {
             if (!isRecord(block) || !isRecord(block.fields)) {

package/dist/reveal-plan.d.ts

@@ -7,6 +7,10 @@ export type FieldLike = {
     type: string;
     name?: string;
     label?: unknown;
+    /** Array fields: Payload fills `singular` from the name when the config leaves it out. */
+    labels?: {
+        singular?: unknown;
+    };
     fields?: FieldLike[];
     tabs?: Array<{
         name?: string;
@@ -35,11 +39,12 @@ export type RevealStep =
     parentPath: string;
     index: number;
 };
-type Lookup = {
+export type Lookup = {
     /** Block slug of the row at a form path, e.g. "layout.0" → "hero". */
     blockTypeAt: (rowPath: string) => string | undefined;
     /** Blocks declared once in config and referenced by slug. */
     blocksBySlug?: Record<string, BlockLike | undefined>;
 };
 export declare function planReveal(rootFields: FieldLike[], path: string, lookup: Lookup): RevealStep[] | null;
-export {};
+/** The field config a form path ends at, e.g. "layout.2.items" → the `items` array field. */
+export declare function fieldAtPath(rootFields: FieldLike[], path: string, lookup: Lookup): FieldLike | null;

package/dist/reveal-plan.js

@@ -4,11 +4,19 @@
  * Pure: takes client field config, returns steps for the Admin bridge to perform.
  */
 export function planReveal(rootFields, path, lookup) {
+    return walkPath(rootFields, path, lookup)?.steps ?? null;
+}
+/** The field config a form path ends at, e.g. "layout.2.items" → the `items` array field. */
+export function fieldAtPath(rootFields, path, lookup) {
+    return walkPath(rootFields, path, lookup)?.field ?? null;
+}
+function walkPath(rootFields, path, lookup) {
     const segments = path.split(".");
     const steps = [];
     let fields = rootFields;
     let counter = { value: 0 };
     let walked = [];
+    let last = null;
     for (let i = 0; i < segments.length;) {
         const segment = segments[i] ?? "";
         const found = findIn(fields, segment, counter);
@@ -25,6 +33,7 @@ export function planReveal(rootFields, path, lookup) {
             continue;
         }
         const field = found.field;
+        last = field;
         const next = segments[i];
         if ((field.type === "blocks" || field.type === "array") &&
             next !== undefined &&
@@ -51,9 +60,9 @@ export function planReveal(rootFields, path, lookup) {
             continue;
         }
         // A leaf; anything after it (e.g. rich text internals) is not a form field.
-        return i === segments.length ? steps : null;
+        return i === segments.length ? { steps, field } : null;
     }
-    return steps;
+    return { steps, field: last };
 }
 function findIn(fields, name, counter) {
     for (const field of fields) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simmalugnt-se/payload-visual-editing",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Click a block in Payload Live Preview to open its fields in the edit form",
   "keywords": [
     "payload",
@@ -18,7 +18,8 @@
     "node": ">=22"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "sideEffects": [
     "*.css"