@simmalugnt-se/payload-visual-editing 0.1.0

package/dist/protocol.js

@@ -0,0 +1,184 @@
+/** Shared between the preview (iframe) and Admin. No React, no DOM access. */
+export const MESSAGE_TYPE = "payload-visual-editing";
+export const ATTR_BLOCK = "data-payload-block";
+/** Block slug; the preview looks up the label Admin sent for it. */
+export const ATTR_BLOCK_TYPE = "data-payload-block-type";
+/** The editor's own block name, which Admin also prefers over the block label in row headers. */
+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";
+const MAX_NODE_TEXT = 200;
+export function isSelectMessage(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    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)) &&
+        (message.node === undefined || isNode(message.node)));
+}
+function isNode(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const node = value;
+    return (Number.isInteger(node.index) &&
+        node.index >= 0 &&
+        (node.text === undefined ||
+            (typeof node.text === "string" && node.text.length <= MAX_NODE_TEXT)));
+}
+/**
+ * Pick the editor node matching the clicked preview node. Text wins over index because
+ * converters may render a node as zero or several elements, shifting indexes.
+ */
+export function matchNodeIndex(nodeTexts, node) {
+    const wanted = normalize(node.text);
+    if (wanted) {
+        const exact = nodeTexts.findIndex((text) => normalize(text) === wanted);
+        if (exact !== -1) {
+            return exact;
+        }
+        const prefix = nodeTexts.findIndex((text) => normalize(text).startsWith(wanted));
+        if (prefix !== -1) {
+            return prefix;
+        }
+    }
+    return Math.min(node.index, Math.max(nodeTexts.length - 1, 0));
+}
+function normalize(text) {
+    return (text ?? "").replace(/\s+/g, " ").trim();
+}
+/** Preview text sent with a node: enough to recognise it, never the whole document. */
+export function nodeSnippet(text) {
+    const value = normalize(text ?? undefined).slice(0, 80);
+    return value || undefined;
+}
+/** A single field name or a dotted path inside the block; never array syntax or traversal. */
+function isFieldName(value) {
+    return typeof value === "string" && /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/.test(value);
+}
+export function isFocusMessage(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const message = value;
+    return (message.type === MESSAGE_TYPE &&
+        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))));
+}
+export function isReadyMessage(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        value.type === MESSAGE_TYPE &&
+        value.action === "ready");
+}
+const MAX_LABELED_BLOCKS = 500;
+const MAX_LABELED_FIELDS = 500;
+const MAX_LABEL = 200;
+export function isLabelsMessage(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const message = value;
+    if (message.type !== MESSAGE_TYPE || message.action !== "labels" || !isRecord(message.blocks)) {
+        return false;
+    }
+    const blocks = Object.values(message.blocks);
+    return (blocks.length <= MAX_LABELED_BLOCKS &&
+        blocks.every((block) => {
+            if (!isRecord(block) || !isRecord(block.fields)) {
+                return false;
+            }
+            const fields = Object.values(block.fields);
+            return ((block.label === undefined || isLabel(block.label)) &&
+                fields.length <= MAX_LABELED_FIELDS &&
+                fields.every(isLabel));
+        }));
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isLabel(value) {
+    return typeof value === "string" && value.length <= MAX_LABEL;
+}
+/** Inverse of `fieldDomId`: "field-layout__0__headline" → "layout.0.headline". */
+export function pathFromDomId(id) {
+    return id.startsWith("field-") && id.length > "field-".length
+        ? id.slice("field-".length).replace(/__/g, ".")
+        : 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).
+ */
+export function focusTargets(path, fields) {
+    const segments = path.split(".");
+    const targets = [];
+    for (let i = segments.length - 1; i > 0; i -= 1) {
+        if (!/^\d+$/.test(segments[i] ?? "")) {
+            continue;
+        }
+        const rowPath = segments.slice(0, i + 1).join(".");
+        const id = fields[`${rowPath}.id`]?.value;
+        if (typeof id !== "string" || !id) {
+            continue;
+        }
+        const rest = segments.slice(i + 1).join(".");
+        targets.push(rest && isFieldName(rest) ? { blockId: id, field: rest } : { blockId: id });
+    }
+    return targets;
+}
+/**
+ * Find the block row whose `id` matches, using Payload form state keys ("layout.2.id").
+ * Ids survive reordering in the unsaved form; indexes from the preview would not.
+ */
+export function resolveBlockTarget(fields, blockId) {
+    for (const [path, field] of Object.entries(fields)) {
+        if (!path.endsWith(".id") || field?.value !== blockId) {
+            continue;
+        }
+        const rowPath = path.slice(0, -".id".length);
+        const rows = rowSteps(rowPath);
+        if (rows.length === 0) {
+            continue;
+        }
+        return { rowPath, rows };
+    }
+    return null;
+}
+function rowSteps(rowPath) {
+    const segments = rowPath.split(".");
+    const steps = [];
+    for (let i = 1; i < segments.length; i += 1) {
+        const segment = segments[i] ?? "";
+        if (/^\d+$/.test(segment)) {
+            steps.push({ parentPath: segments.slice(0, i).join("."), index: Number(segment) });
+        }
+    }
+    const last = segments.at(-1) ?? "";
+    return /^\d+$/.test(last) ? steps : [];
+}
+/** DOM id Payload gives field inputs: "layout.0.headline" → "field-layout__0__headline". */
+export function fieldDomId(path) {
+    return `field-${path.replace(/\./g, "__")}`;
+}
+/** Inverse of `rowDomId`: "layout-0-items-row-1" → "layout.0.items.1". */
+export function pathFromRowDomId(id) {
+    const match = /^(.+)-row-(\d+)$/.exec(id);
+    return match ? `${match[1]?.split("-").join(".")}.${match[2]}` : undefined;
+}
+/** DOM id Payload gives block and array rows: ("layout", 0) → "layout-row-0". */
+export function rowDomId(step) {
+    return `${step.parentPath.split(".").join("-")}-row-${step.index}`;
+}

package/dist/reveal-plan.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Work out which tabs must be opened to show a form path. Payload only renders the active tab,
+ * so a field in another tab has no DOM element until its tab button is clicked.
+ * Pure: takes client field config, returns steps for the Admin bridge to perform.
+ */
+export type FieldLike = {
+    type: string;
+    name?: string;
+    label?: unknown;
+    fields?: FieldLike[];
+    tabs?: Array<{
+        name?: string;
+        fields?: FieldLike[];
+    }>;
+    blocks?: BlockLike[];
+    blockReferences?: Array<BlockLike | string>;
+};
+export type BlockLike = {
+    slug: string;
+    labels?: {
+        singular?: unknown;
+    };
+    fields?: FieldLike[];
+};
+export type RevealStep = 
+/** Click tab `index` of the `ordinal`-th tabs field in the current scope. The tab content becomes the scope. */
+{
+    kind: "tab";
+    ordinal: number;
+    index: number;
+}
+/** Enter a block or array row. The row element becomes the scope. */
+ | {
+    kind: "row";
+    parentPath: string;
+    index: number;
+};
+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 {};

package/dist/reveal-plan.js

@@ -0,0 +1,122 @@
+/**
+ * Work out which tabs must be opened to show a form path. Payload only renders the active tab,
+ * so a field in another tab has no DOM element until its tab button is clicked.
+ * Pure: takes client field config, returns steps for the Admin bridge to perform.
+ */
+export function planReveal(rootFields, path, lookup) {
+    const segments = path.split(".");
+    const steps = [];
+    let fields = rootFields;
+    let counter = { value: 0 };
+    let walked = [];
+    for (let i = 0; i < segments.length;) {
+        const segment = segments[i] ?? "";
+        const found = findIn(fields, segment, counter);
+        if (!found) {
+            return null;
+        }
+        steps.push(...found.tabs);
+        counter = found.counter;
+        walked = [...walked, segment];
+        i += 1;
+        if (found.kind === "namedTab") {
+            fields = found.fields;
+            counter = { value: 0 };
+            continue;
+        }
+        const field = found.field;
+        const next = segments[i];
+        if ((field.type === "blocks" || field.type === "array") &&
+            next !== undefined &&
+            /^\d+$/.test(next)) {
+            const parentPath = walked.join(".");
+            steps.push({ kind: "row", parentPath, index: Number(next) });
+            walked = [...walked, next];
+            i += 1;
+            counter = { value: 0 };
+            if (field.type === "array") {
+                fields = field.fields ?? [];
+                continue;
+            }
+            const block = findBlock(field, lookup.blockTypeAt(walked.join(".")), lookup.blocksBySlug);
+            if (!block) {
+                return null;
+            }
+            fields = block.fields ?? [];
+            continue;
+        }
+        if (field.fields) {
+            // Named group: same DOM scope, keep counting tabs.
+            fields = field.fields;
+            continue;
+        }
+        // A leaf; anything after it (e.g. rich text internals) is not a form field.
+        return i === segments.length ? steps : null;
+    }
+    return steps;
+}
+function findIn(fields, name, counter) {
+    for (const field of fields) {
+        if (field.type === "tabs") {
+            const ordinal = counter.value;
+            counter.value += 1;
+            for (const [index, tab] of (field.tabs ?? []).entries()) {
+                const step = { kind: "tab", ordinal, index };
+                if (tab.name === name) {
+                    return {
+                        kind: "namedTab",
+                        fields: tab.fields ?? [],
+                        tabs: [step],
+                        counter: { value: 0 },
+                    };
+                }
+                if (!tab.name) {
+                    const inner = findIn(tab.fields ?? [], name, { value: 0 });
+                    if (inner) {
+                        return { ...inner, tabs: [step, ...inner.tabs] };
+                    }
+                }
+            }
+            continue;
+        }
+        if (field.name === name) {
+            return { kind: "field", field, tabs: [], counter };
+        }
+        if (!field.name && field.fields) {
+            // Row, collapsible or unnamed group: transparent for paths.
+            const inner = findIn(field.fields, name, counter);
+            if (inner) {
+                return inner;
+            }
+            continue;
+        }
+        counter.value += countTabs(field);
+    }
+    return null;
+}
+/** Tabs fields rendered inside a field that is skipped, so later ordinals stay aligned with the DOM. */
+function countTabs(field) {
+    if (field.type === "tabs") {
+        return 1;
+    }
+    if (field.type === "blocks" || field.type === "array" || !field.fields) {
+        return 0;
+    }
+    return field.fields.reduce((sum, child) => sum + countTabs(child), 0);
+}
+function findBlock(field, slug, blocksBySlug) {
+    if (!slug) {
+        return undefined;
+    }
+    const inline = field.blocks?.find((block) => block.slug === slug);
+    if (inline) {
+        return inline;
+    }
+    for (const reference of field.blockReferences ?? []) {
+        const block = typeof reference === "string" ? blocksBySlug?.[reference] : reference;
+        if (block?.slug === slug) {
+            return block;
+        }
+    }
+    return undefined;
+}

package/dist/styles/admin.css

@@ -0,0 +1,19 @@
+/* Keep in sync with HIGHLIGHT_COLOR / HIGHLIGHT_TINT in src/theme.ts (the preview overlay colours). */
+.pve-highlight {
+  border-radius: 4px;
+  animation: pve-highlight 1.6s ease-out;
+}
+
+@keyframes pve-highlight {
+  0%,
+  40% {
+    outline: 2px solid #2563eb;
+    outline-offset: 4px;
+    background-color: rgba(37, 99, 235, 0.12);
+  }
+  100% {
+    outline: 2px solid transparent;
+    outline-offset: 4px;
+    background-color: transparent;
+  }
+}

package/dist/theme.d.ts

@@ -0,0 +1,3 @@
+/** One highlight colour for the preview overlay and the Admin form, so they read as the same selection. */
+export declare const HIGHLIGHT_COLOR = "#2563eb";
+export declare const HIGHLIGHT_TINT = "rgba(37, 99, 235, 0.12)";

package/dist/theme.js

@@ -0,0 +1,3 @@
+/** One highlight colour for the preview overlay and the Admin form, so they read as the same selection. */
+export const HIGHLIGHT_COLOR = "#2563eb";
+export const HIGHLIGHT_TINT = "rgba(37, 99, 235, 0.12)";

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@simmalugnt-se/payload-visual-editing",
+  "version": "0.1.0",
+  "description": "Click a block in Payload Live Preview to open its fields in the edit form",
+  "keywords": [
+    "payload",
+    "payload-plugin"
+  ],
+  "license": "MIT",
+  "author": "Simmalugnt AB",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simmalugnt-se/payload-plugins.git",
+    "directory": "packages/payload-visual-editing"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "import": "./dist/exports/client.js",
+      "types": "./dist/exports/client.d.ts",
+      "default": "./dist/exports/client.js"
+    },
+    "./frontend": {
+      "import": "./dist/exports/frontend.js",
+      "types": "./dist/exports/frontend.d.ts",
+      "default": "./dist/exports/frontend.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@payloadcms/ui": ">=3.85.2 <4",
+    "payload": ">=3.85.2 <4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@payloadcms/ui": "3.87.1",
+    "@types/node": "^22",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "payload": "3.87.1",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tsx": "^4.21.0",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp -R src/styles dist/styles",
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}