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

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 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

@@ -70,5 +70,5 @@ Requires Payload `>=3.85.2 <4` and React 19.
 ## 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";
@@ -53,11 +53,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);
         };

package/dist/frontend/VisualEditingPreview.js

@@ -19,7 +19,14 @@ 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;
         const redraw = () => {
             cancelAnimationFrame(frame);
@@ -34,6 +41,7 @@ export function VisualEditingPreview({ adminOrigin }) {
                 return;
             }
             hovered = hit;
+            describe(hit);
             redraw();
         };
         const onPointerLeave = () => {
@@ -72,7 +80,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();
@@ -164,13 +172,18 @@ 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)}`;
 }
+/** 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.1",
   "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"