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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

package/README.md

@@ -78,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";
@@ -50,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;
             }
@@ -85,6 +90,9 @@ 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 scope = await openSteps(plan, root, () => id === run);
             if (!scope || id !== run) {
@@ -117,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();

package/dist/frontend/VisualEditingPreview.js

@@ -75,11 +75,20 @@ 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;
             }
             // A click selects, and must not leave the page: links and submits are cancelled. Anything
@@ -134,7 +143,7 @@ export function VisualEditingPreview({ adminOrigin }) {
         };
         const onKeyDown = (event) => {
             if (event.key === "Escape") {
-                clearSelection();
+                dropSelection();
             }
         };
         document.addEventListener("pointermove", onPointerMove, { passive: true });

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.2",
+  "version": "0.2.0",
   "description": "Click a block in Payload Live Preview to open its fields in the edit form",
   "keywords": [
     "payload",