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

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.0
+
+- Globals: `visualEditingPlugin({ globals: ["header", "footer"] })` supports click-to-edit in a
+  global's Live Preview.
+- `editableField` outside a block marks a top-level field of the document, such as a header's site
+  name.
+- `editableGlobal("header")` on the element that renders a global: its markers respond only while
+  that global is edited, so a header shown on a page preview no longer targets the page's form.
+
+## 0.2.1
+
+- A preview click right after the page loads no longer lands on the wrong tab: Payload restores the
+  editor's last tab once preferences load, and now leaves it alone because the bridge always clicks
+  the tab it needs.
+
 ## 0.2.0
 
 - A click in the preview dispatches `visual-editing:select` on Admin's `window` with the form path,

package/README.md

@@ -17,12 +17,13 @@ Requires Payload `>=3.85.2 <4` and React 19.
    pnpm add @simmalugnt-se/payload-visual-editing
    ```
 
-2. Enable it for the collections that have Live Preview, then regenerate the import map:
+2. Enable it for the collections and globals that have Live Preview, then regenerate the import
+   map:
 
    ```ts
    import { visualEditingPlugin } from "@simmalugnt-se/payload-visual-editing";
 
-   plugins: [visualEditingPlugin({ collections: ["pages"] })];
+   plugins: [visualEditingPlugin({ collections: ["pages"], globals: ["header", "footer"] })];
    ```
 
    ```bash
@@ -73,6 +74,31 @@ Requires Payload `>=3.85.2 <4` and React 19.
    Marking blocks alone is enough to start: a click then opens the whole block. Add `editableField`
    where editors should land on a specific field.
 
+## Globals and top-level fields
+
+Outside a block, `editableField` names a top-level field of the document, such as a header's site
+name or a page title shown on the page.
+
+A global such as a header is rendered on every page, but its fields belong to the global's form,
+not the page's. Wrap it in `editableGlobal` with its slug, so its markers respond only while that
+global is edited, and the page's blocks only while the page is:
+
+```tsx
+<header {...editableGlobal("header")}>
+  <strong {...editableField("siteName")}>{header.siteName}</strong>
+  <nav>
+    {header.navItems.map((item) => (
+      <a key={item.id} {...editableBlock(item)} href={href(item)}>
+        <span {...editableField("link.label")}>{item.link.label}</span>
+      </a>
+    ))}
+  </nav>
+</header>
+```
+
+The global needs a `livePreview.url` of its own, for example a page that shows the header and
+footer around neutral content.
+
 ## Labels
 
 The outline shows the same names as Admin: the editor's block name, otherwise the block's

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, collectRowLabels } from "../labels.js";
+import { collectBlockLabels, collectRootLabels, collectRowLabels } from "../labels.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";
@@ -26,13 +26,14 @@ export function VisualEditingAdminBridge() {
     const livePreview = useLivePreviewContext();
     const form = useDocumentForm();
     const { config, getEntityConfig } = useConfig();
-    const { collectionSlug } = useDocumentInfo();
+    const { collectionSlug, globalSlug } = useDocumentInfo();
     const { i18n } = useTranslation();
     const language = i18n.language;
     const anchorRef = useRef(null);
-    const latest = useRef({ form, livePreview, config, getEntityConfig, collectionSlug, language });
+    const entity = { collectionSlug, globalSlug };
+    const latest = useRef({ form, livePreview, config, getEntityConfig, entity, language });
     useEffect(() => {
-        latest.current = { form, livePreview, config, getEntityConfig, collectionSlug, language };
+        latest.current = { form, livePreview, config, getEntityConfig, entity, language };
     });
     useEffect(() => {
         let run = 0;
@@ -62,47 +63,61 @@ export function VisualEditingAdminBridge() {
             void select(event.data, run);
         };
         const sendLabels = (preview, origin) => {
-            const { form, config, getEntityConfig, collectionSlug, language } = latest.current;
+            const { form, config, getEntityConfig, entity, language } = latest.current;
             const fields = form.getFields();
-            const rootFields = rootFieldsOf(getEntityConfig, collectionSlug);
+            const rootFields = rootFieldsOf(getEntityConfig, entity);
             const blocksBySlug = config.blocksMap;
             const message = {
                 type: MESSAGE_TYPE,
                 action: "labels",
                 blocks: collectBlockLabels(rootFields, blocksBySlug, language),
                 rows: collectRowLabels(rootFields, fields, { blockTypeAt: (rowPath) => rowAt(fields, rowPath)?.blockType, blocksBySlug }, language),
+                fields: collectRootLabels(rootFields, language),
+                // The preview keeps the markers of other documents (a header on a page preview) inert.
+                ...(entity.globalSlug ? { global: entity.globalSlug } : {}),
             };
             preview.postMessage(message, origin);
         };
         const select = async (message, id) => {
-            const { form, config, getEntityConfig, collectionSlug } = latest.current;
+            const { form, config, getEntityConfig, entity } = latest.current;
             const fields = form.getFields();
-            const target = resolveBlockTarget(fields, message.blockId);
-            if (!target) {
+            // Without a block id the field is a top-level field of the document.
+            const target = message.blockId ? resolveBlockTarget(fields, message.blockId) : null;
+            if (message.blockId && !target) {
                 return;
             }
-            expandRows(target, fields, form.dispatchFields);
-            const rootFields = rootFieldsOf(getEntityConfig, collectionSlug);
+            if (target) {
+                expandRows(target, fields, form.dispatchFields);
+            }
+            const rootFields = rootFieldsOf(getEntityConfig, entity);
             const lookup = {
                 blockTypeAt: (rowPath) => rowAt(fields, rowPath)?.blockType,
                 blocksBySlug: config.blocksMap,
             };
-            const fieldPath = message.field ? `${target.rowPath}.${message.field}` : undefined;
+            const fieldPath = message.field
+                ? target
+                    ? `${target.rowPath}.${message.field}`
+                    : 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 rowPlan = target ? (planReveal(rootFields, target.rowPath, lookup) ?? []) : null;
+            const plan = fieldPlan ?? rowPlan;
+            const path = fieldPlan && fieldPath ? fieldPath : target?.rowPath;
+            if (!plan || !path) {
+                return;
+            }
+            window.dispatchEvent(new CustomEvent(SELECT_EVENT, { detail: { path } }));
             const root = formRoot(anchorRef.current);
             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 field = fieldPlan ? fieldPath : undefined;
+            const row = () => (target ? findRow(target) : null);
             const element = (field
                 ? await waitForRendered(() => findField(field), scope, message.node ? FIELD_WAIT_MS : WAIT_MS)
-                : null) ?? (await waitFor(() => findRow(target)));
+                : null) ?? (target ? await waitFor(row) : null);
             if (!element || id !== run) {
                 return;
             }
@@ -110,7 +125,7 @@ export function VisualEditingAdminBridge() {
             if (message.node && (await revealRichTextNode(element, message.node, current))) {
                 return;
             }
-            await reveal(element, field !== undefined && element !== findRow(target), current);
+            await reveal(element, field !== undefined && element !== row(), current);
         };
         window.addEventListener("message", onMessage);
         return () => window.removeEventListener("message", onMessage);
@@ -143,10 +158,13 @@ export function VisualEditingAdminBridge() {
     }, []);
     return _jsx("span", { hidden: true, ref: anchorRef });
 }
-function rootFieldsOf(getEntityConfig, collectionSlug) {
-    return collectionSlug
-        ? (getEntityConfig({ collectionSlug })?.fields ?? [])
-        : [];
+function rootFieldsOf(getEntityConfig, { collectionSlug, globalSlug }) {
+    const entity = collectionSlug
+        ? getEntityConfig({ collectionSlug })
+        : globalSlug
+            ? getEntityConfig({ globalSlug })
+            : undefined;
+    return entity?.fields ?? [];
 }
 /**
  * Form path of the field or row an element belongs to. Rich text wrappers carry
@@ -203,7 +221,10 @@ 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. */
+/**
+ * The edit form this bridge belongs to, not one in a document drawer. Globals use the same edit
+ * view, so the classes are the same.
+ */
 function formRoot(anchor) {
     const view = anchor?.closest(".collection-edit");
     return view?.querySelector(".collection-edit__form") ?? document;
@@ -232,9 +253,9 @@ async function openSteps(steps, root, current) {
         if (!tabs || !button) {
             return null;
         }
-        if (!button.classList.contains("tabs-field__tab-button--active")) {
-            button.click();
-        }
+        // Click even the active tab: Payload restores the editor's last tab from preferences once they
+        // load, unless a tab was clicked first. A click right after the page loads would lose to it.
+        button.click();
         const content = await waitFor(() => button.classList.contains("tabs-field__tab-button--active")
             ? tabs.querySelector(":scope > .tabs-field__content-wrap")
             : null);

package/dist/exports/frontend.d.ts

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

package/dist/exports/frontend.js

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

package/dist/frontend/VisualEditingPreview.js

@@ -1,6 +1,6 @@
 "use client";
 import { useEffect } from "react";
-import { ATTR_BLOCK, ATTR_BLOCK_NAME, ATTR_BLOCK_TYPE, ATTR_FIELD, ATTR_RICHTEXT, isFocusMessage, isLabelsMessage, MESSAGE_TYPE, nodeSnippet, } from "../protocol.js";
+import { ATTR_BLOCK, ATTR_BLOCK_NAME, ATTR_BLOCK_TYPE, ATTR_FIELD, ATTR_GLOBAL, ATTR_RICHTEXT, inScope, isFocusMessage, isLabelsMessage, MESSAGE_TYPE, nodeSnippet, } from "../protocol.js";
 import { HIGHLIGHT_COLOR, HIGHLIGHT_TINT } from "../theme.js";
 const SELECTOR = `[${ATTR_FIELD}], [${ATTR_BLOCK}]`;
 /**
@@ -19,10 +19,10 @@ export function VisualEditingPreview({ adminOrigin }) {
         let hovered = null;
         let current = null;
         // Until Admin answers, labels fall back to the slugs.
-        let labels = { blocks: {}, rows: {} };
+        let labels = { blocks: {}, rows: {}, fields: {} };
         // Array row numbers change as rows move, so ask again whenever the pointer reaches a row.
         const describe = (hit) => {
-            if (hit && isArrayRow(hit.element)) {
+            if (hit?.blockId && isArrayRow(hit.element)) {
                 const message = { type: MESSAGE_TYPE, action: "describe" };
                 admin.postMessage(message, targetOrigin);
             }
@@ -101,7 +101,7 @@ export function VisualEditingPreview({ adminOrigin }) {
             const message = {
                 type: MESSAGE_TYPE,
                 action: "select",
-                blockId: hit.blockId,
+                ...(hit.blockId ? { blockId: hit.blockId } : {}),
                 ...(hit.field ? { field: hit.field } : {}),
                 ...(hit.node ? { node: hit.node } : {}),
             };
@@ -112,7 +112,12 @@ export function VisualEditingPreview({ adminOrigin }) {
                 return;
             }
             if (isLabelsMessage(event.data)) {
-                labels = { blocks: event.data.blocks, rows: event.data.rows ?? labels.rows };
+                labels = {
+                    blocks: event.data.blocks,
+                    rows: event.data.rows ?? labels.rows,
+                    fields: event.data.fields ?? labels.fields,
+                    global: event.data.global,
+                };
                 hovered = hovered && relabel(hovered, labels);
                 current = current && relabel(current, labels);
                 redraw();
@@ -128,7 +133,7 @@ export function VisualEditingPreview({ adminOrigin }) {
                     continue;
                 }
                 // Keep a finer selection (e.g. a paragraph) that Admin just echoed back as its field.
-                if (current?.blockId === hit.blockId && current.field === hit.field) {
+                if (current && current.blockId === hit.blockId && current.field === hit.field) {
                     return;
                 }
                 current = hit;
@@ -176,17 +181,34 @@ export function VisualEditingPreview({ adminOrigin }) {
     }, [adminOrigin]);
     return null;
 }
+/**
+ * The block a marked element belongs to, and whether it responds at all: only markers of the
+ * document Admin is editing do. A block outside the element's global (a global rendered inside a
+ * page block) is another document's, so the element is then a top-level field of the global.
+ */
+function ownerOf(element, labels) {
+    const global = element.closest(`[${ATTR_GLOBAL}]`);
+    if (!inScope(global?.getAttribute(ATTR_GLOBAL) ?? undefined, labels.global)) {
+        return null;
+    }
+    const block = element.closest(`[${ATTR_BLOCK}]`);
+    return { block: block && (!global || global.contains(block)) ? block : null };
+}
 function hitFromTarget(target, labels) {
     if (!(target instanceof Element)) {
         return null;
     }
     const marked = target.closest(SELECTOR);
-    const block = marked?.closest(`[${ATTR_BLOCK}]`);
-    const blockId = block?.getAttribute(ATTR_BLOCK);
-    if (!marked || !block || !blockId) {
+    const owner = marked && ownerOf(marked, labels);
+    if (!marked || !owner) {
         return null;
     }
+    const { block } = owner;
+    const blockId = block?.getAttribute(ATTR_BLOCK) || undefined;
     const field = marked !== block ? (marked.getAttribute(ATTR_FIELD) ?? undefined) : undefined;
+    if (!blockId && !field) {
+        return null;
+    }
     const label = labelFor(block, field, labels);
     const node = field && marked.hasAttribute(ATTR_RICHTEXT) ? richTextNode(marked, target) : null;
     if (node) {
@@ -195,8 +217,15 @@ function hitFromTarget(target, labels) {
     return { element: marked, blockId, field, label };
 }
 function hitForBlock(blockId, field, labels) {
+    if (!blockId) {
+        // A top-level field: marked outside any block of this document.
+        const element = field
+            ? Array.from(document.querySelectorAll(`[${ATTR_FIELD}="${CSS.escape(field)}"]`)).find((candidate) => ownerOf(candidate, labels)?.block === null)
+            : undefined;
+        return element && field ? { element, field, label: labelFor(null, field, labels) } : null;
+    }
     const block = document.querySelector(`[${ATTR_BLOCK}="${CSS.escape(blockId)}"]`);
-    if (!block) {
+    if (!block || !ownerOf(block, labels)) {
         return null;
     }
     const fieldElement = field
@@ -207,8 +236,14 @@ function hitForBlock(blockId, field, labels) {
     }
     return { element: block, blockId, label: labelFor(block, undefined, labels) };
 }
-/** Same order as Admin's row header: the editor's block name, then the block's label, then its slug. */
+/**
+ * Same order as Admin's row header: the editor's block name, then the block's label, then its slug.
+ * A top-level field has only its own label.
+ */
 function labelFor(block, field, labels) {
+    if (!block) {
+        return field ? (labels.fields[field] ?? humanize(field)) : "";
+    }
     const type = block.getAttribute(ATTR_BLOCK_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");
@@ -233,9 +268,10 @@ function isArrayRow(element) {
     const row = element.closest(`[${ATTR_BLOCK}]`);
     return !!row && !row.hasAttribute(ATTR_BLOCK_TYPE);
 }
+/** New labels may also name another global, which makes this hit's markers inert. */
 function relabel(hit, labels) {
-    const block = hit.element.closest(`[${ATTR_BLOCK}]`);
-    return block ? { ...hit, label: labelFor(block, hit.field, labels) } : hit;
+    const owner = ownerOf(hit.element, labels);
+    return owner ? { ...hit, label: labelFor(owner.block, hit.field, labels) } : null;
 }
 function inViewport(element) {
     const rect = element.getBoundingClientRect();

package/dist/frontend/editable.d.ts

@@ -10,9 +10,15 @@ export declare function editableBlock(block: {
 }): EditableAttributes;
 /**
  * Mark one field inside a block, e.g. `<h1 {...editableField("headline")}>`.
- * Clicking it opens that field instead of the whole block.
+ * Clicking it opens that field instead of the whole block. Outside a block the name is a
+ * top-level field of the document, e.g. a header's `siteName`.
  */
 export declare function editableField(name: string): EditableAttributes;
+/**
+ * Mark the element that renders a global, e.g. `<header {...editableGlobal("header")}>`.
+ * The markers inside it respond only while that global is edited, not on every page it shows on.
+ */
+export declare function editableGlobal(slug: string): EditableAttributes;
 /**
  * Mark a rich text field on the element whose direct children are the rendered top-level nodes
  * (paragraphs, headings, lists). Clicking a paragraph puts the cursor in that paragraph in Admin.

package/dist/frontend/editable.js

@@ -1,4 +1,4 @@
-import { ATTR_BLOCK, ATTR_BLOCK_NAME, ATTR_BLOCK_TYPE, ATTR_FIELD, ATTR_RICHTEXT, } from "../protocol.js";
+import { ATTR_BLOCK, ATTR_BLOCK_NAME, ATTR_BLOCK_TYPE, ATTR_FIELD, ATTR_GLOBAL, ATTR_RICHTEXT, } from "../protocol.js";
 /**
  * Mark the element that renders a block. Spread it on the block's outermost element:
  * `<section {...editableBlock(block)}>`. Emits nothing without a block id.
@@ -15,11 +15,19 @@ export function editableBlock(block) {
 }
 /**
  * Mark one field inside a block, e.g. `<h1 {...editableField("headline")}>`.
- * Clicking it opens that field instead of the whole block.
+ * Clicking it opens that field instead of the whole block. Outside a block the name is a
+ * top-level field of the document, e.g. a header's `siteName`.
  */
 export function editableField(name) {
     return { [ATTR_FIELD]: name };
 }
+/**
+ * Mark the element that renders a global, e.g. `<header {...editableGlobal("header")}>`.
+ * The markers inside it respond only while that global is edited, not on every page it shows on.
+ */
+export function editableGlobal(slug) {
+    return { [ATTR_GLOBAL]: slug };
+}
 /**
  * Mark a rich text field on the element whose direct children are the rendered top-level nodes
  * (paragraphs, headings, lists). Clicking a paragraph puts the cursor in that paragraph in Admin.

package/dist/labels.d.ts

@@ -23,5 +23,7 @@ export declare function collectBlockLabels(rootFields: FieldLike[], blocksBySlug
 export declare function collectRowLabels(rootFields: FieldLike[], formFields: Record<string, {
     value?: unknown;
 } | undefined>, lookup: Lookup, language: string): BlockLabels;
+/** Labels of the document's own fields, for markers outside any block ("siteName", "meta.title"). */
+export declare function collectRootLabels(rootFields: FieldLike[], language: string): Record<string, string>;
 /** 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

@@ -59,6 +59,12 @@ export function collectRowLabels(rootFields, formFields, lookup, language) {
     }
     return result;
 }
+/** Labels of the document's own fields, for markers outside any block ("siteName", "meta.title"). */
+export function collectRootLabels(rootFields, language) {
+    const result = {};
+    collectFieldLabels(rootFields, "", language, result);
+    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/plugin.d.ts

@@ -2,6 +2,8 @@ import type { Plugin } from "payload";
 export type VisualEditingPluginOptions = {
     /** Collection slugs whose Live Preview should support click-to-edit. */
     collections: string[];
+    /** Global slugs whose Live Preview should support click-to-edit, such as a header. */
+    globals?: string[];
     disabled?: boolean;
 };
 export declare function visualEditingPlugin(options: VisualEditingPluginOptions): Plugin;

package/dist/plugin.js

@@ -5,10 +5,12 @@ export function visualEditingPlugin(options) {
         if (options.disabled) {
             return config;
         }
-        const enabled = new Set(options.collections);
+        const collections = new Set(options.collections);
+        const globals = new Set(options.globals ?? []);
         return {
             ...config,
-            collections: (config.collections ?? []).map((collection) => enabled.has(collection.slug) ? withBridge(collection) : collection),
+            collections: (config.collections ?? []).map((collection) => collections.has(collection.slug) ? withBridge(collection) : collection),
+            globals: (config.globals ?? []).map((global) => globals.has(global.slug) ? withGlobalBridge(global) : global),
         };
     };
 }
@@ -28,3 +30,20 @@ function withBridge(collection) {
         },
     };
 }
+/** Globals have no `edit` components; their edit view reads `elements` instead. */
+function withGlobalBridge(global) {
+    const elements = global.admin?.components?.elements;
+    return {
+        ...global,
+        admin: {
+            ...global.admin,
+            components: {
+                ...global.admin?.components,
+                elements: {
+                    ...elements,
+                    beforeDocumentControls: [...(elements?.beforeDocumentControls ?? []), BRIDGE],
+                },
+            },
+        },
+    };
+}

package/dist/protocol.d.ts

@@ -9,6 +9,13 @@ 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";
+/** On the element that renders a global; the markers inside it belong to that global's form. */
+export declare const ATTR_GLOBAL = "data-payload-global";
+/**
+ * Whether a marker belongs to the document being edited: a marker inside `editableGlobal("header")`
+ * only while the header is edited, any other marker only while a collection document is.
+ */
+export declare function inScope(markerGlobal: string | undefined, editedGlobal: string | undefined): boolean;
 /**
  * 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`
@@ -18,11 +25,12 @@ export declare const ATTR_RICHTEXT = "data-payload-richtext";
 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";
+/** A block, a field in it, or without `blockId` a top-level field of the document. */
 export type SelectMessage = {
     type: typeof MESSAGE_TYPE;
     action: "select";
-    blockId: string;
-    /** Field name relative to the block, e.g. "headline". */
+    blockId?: string;
+    /** Field name relative to the block (e.g. "headline"), or to the document without a block. */
     field?: string;
     /** Top-level rich text node that was clicked; `text` disambiguates when indexes drift. */
     node?: {
@@ -51,9 +59,12 @@ export declare function nodeSnippet(text: string | null | undefined): string | u
 export type FocusMessage = {
     type: typeof MESSAGE_TYPE;
     action: "focus";
-    /** Candidates from the innermost row outwards; the preview uses the first it has marked. */
+    /**
+     * Candidates from the innermost row outwards; the preview uses the first it has marked.
+     * A target without `blockId` is a top-level field.
+     */
     targets: Array<{
-        blockId: string;
+        blockId?: string;
         field?: string;
     }>;
 };
@@ -67,12 +78,17 @@ export type ReadyMessage = {
     action: "ready" | "describe";
 };
 export declare function isReadyMessage(value: unknown): value is ReadyMessage;
-/** Admin → preview: labels for the overlay, blocks keyed by slug and array rows by row id. */
+/**
+ * Admin → preview: labels for the overlay, blocks keyed by slug, array rows by row id and
+ * top-level fields by path; and the global being edited, if the form is a global's.
+ */
 export type LabelsMessage = {
     type: typeof MESSAGE_TYPE;
     action: "labels";
     blocks: BlockLabels;
     rows?: BlockLabels;
+    fields?: Record<string, string>;
+    global?: string;
 };
 export declare function isLabelsMessage(value: unknown): value is LabelsMessage;
 /** Inverse of `fieldDomId`: "field-layout__0__headline" → "layout.0.headline". */
@@ -81,6 +97,7 @@ export declare function pathFromDomId(id: string): string | undefined;
  * Rows enclosing a form path, innermost first, with the rest of the path as the field.
  * "layout.1.items.0.title" → the items row (field "title"), then the layout row (field undefined:
  * "items.0.title" is not a plain field name the preview could have marked).
+ * A path outside any row ("siteName", "meta.title") targets the top-level field.
  */
 export declare function focusTargets(path: string, fields: Record<string, {
     value?: unknown;

package/dist/protocol.js

@@ -8,6 +8,15 @@ 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";
+/** On the element that renders a global; the markers inside it belong to that global's form. */
+export const ATTR_GLOBAL = "data-payload-global";
+/**
+ * Whether a marker belongs to the document being edited: a marker inside `editableGlobal("header")`
+ * only while the header is edited, any other marker only while a collection document is.
+ */
+export function inScope(markerGlobal, editedGlobal) {
+    return (markerGlobal || undefined) === (editedGlobal || undefined);
+}
 /**
  * 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`
@@ -32,11 +41,20 @@ export function isSelectMessage(value) {
     const message = value;
     return (message.type === MESSAGE_TYPE &&
         message.action === "select" &&
-        typeof message.blockId === "string" &&
-        message.blockId.length > 0 &&
-        (message.field === undefined || isFieldName(message.field)) &&
+        isTarget(message) &&
         (message.node === undefined || isNode(message.node)));
 }
+/** A block id, a field name, or both; never neither. */
+function isTarget(value) {
+    const { blockId, field } = value;
+    if (blockId !== undefined && (typeof blockId !== "string" || blockId.length === 0)) {
+        return false;
+    }
+    if (field !== undefined && !isFieldName(field)) {
+        return false;
+    }
+    return blockId !== undefined || field !== undefined;
+}
 function isNode(value) {
     if (!value || typeof value !== "object") {
         return false;
@@ -86,11 +104,7 @@ export function isFocusMessage(value) {
         message.action === "focus" &&
         Array.isArray(message.targets) &&
         message.targets.length <= 10 &&
-        message.targets.every((target) => target &&
-            typeof target === "object" &&
-            typeof target.blockId === "string" &&
-            target.blockId.length > 0 &&
-            (target.field === undefined || isFieldName(target.field))));
+        message.targets.every((target) => isRecord(target) && isTarget(target)));
 }
 export function isReadyMessage(value) {
     if (!value || typeof value !== "object") {
@@ -110,7 +124,17 @@ export function isLabelsMessage(value) {
     return (message.type === MESSAGE_TYPE &&
         message.action === "labels" &&
         isLabelMap(message.blocks) &&
-        (message.rows === undefined || isLabelMap(message.rows)));
+        (message.rows === undefined || isLabelMap(message.rows)) &&
+        (message.fields === undefined || isFieldLabels(message.fields)) &&
+        (message.global === undefined ||
+            (typeof message.global === "string" && message.global.length <= MAX_LABEL)));
+}
+function isFieldLabels(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const labels = Object.values(value);
+    return labels.length <= MAX_LABELED_FIELDS && labels.every(isLabel);
 }
 function isLabelMap(value) {
     if (!isRecord(value)) {
@@ -144,6 +168,7 @@ export function pathFromDomId(id) {
  * Rows enclosing a form path, innermost first, with the rest of the path as the field.
  * "layout.1.items.0.title" → the items row (field "title"), then the layout row (field undefined:
  * "items.0.title" is not a plain field name the preview could have marked).
+ * A path outside any row ("siteName", "meta.title") targets the top-level field.
  */
 export function focusTargets(path, fields) {
     const segments = path.split(".");
@@ -160,6 +185,9 @@ export function focusTargets(path, fields) {
         const rest = segments.slice(i + 1).join(".");
         targets.push(rest && isFieldName(rest) ? { blockId: id, field: rest } : { blockId: id });
     }
+    if (isFieldName(path)) {
+        targets.push({ field: path });
+    }
     return targets;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simmalugnt-se/payload-visual-editing",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Click a block in Payload Live Preview to open its fields in the edit form",
   "keywords": [
     "payload",
@@ -51,11 +51,11 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@payloadcms/ui": "3.87.1",
+    "@payloadcms/ui": "3.90.2",
     "@types/node": "^22",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
-    "payload": "3.87.1",
+    "payload": "3.90.2",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "tsx": "^4.21.0",