@simmalugnt-se/payload-visual-editing 0.1.0

package/dist/frontend/VisualEditingPreview.js

@@ -0,0 +1,256 @@
+"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 { HIGHLIGHT_COLOR, HIGHLIGHT_TINT } from "../theme.js";
+const SELECTOR = `[${ATTR_FIELD}], [${ATTR_BLOCK}]`;
+/**
+ * Render only in draft mode. Inside the Live Preview window it outlines editable blocks
+ * on hover and tells Admin which block or field was clicked. Outside a preview window it does nothing.
+ */
+export function VisualEditingPreview({ adminOrigin }) {
+    useEffect(() => {
+        const admin = window.opener ?? (window.parent !== window ? window.parent : null);
+        if (!admin) {
+            return;
+        }
+        const targetOrigin = adminOrigin ?? referrerOrigin() ?? window.location.origin;
+        const hover = createOverlay(false);
+        const selected = createOverlay(true);
+        let hovered = null;
+        let current = null;
+        // Until Admin answers, labels fall back to the slugs.
+        let labels = {};
+        let frame = 0;
+        const redraw = () => {
+            cancelAnimationFrame(frame);
+            frame = requestAnimationFrame(() => {
+                place(hover, hovered && hovered.element !== current?.element ? hovered : null);
+                place(selected, current);
+            });
+        };
+        const onPointerMove = (event) => {
+            const hit = hitFromTarget(event.target, labels);
+            if (hit?.element === hovered?.element && hit?.label === hovered?.label) {
+                return;
+            }
+            hovered = hit;
+            redraw();
+        };
+        const onPointerLeave = () => {
+            hovered = null;
+            redraw();
+        };
+        const clearSelection = () => {
+            if (current) {
+                current = null;
+                redraw();
+            }
+        };
+        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();
+                return;
+            }
+            // In the editor a click selects; it must not follow links or submit forms.
+            event.preventDefault();
+            event.stopPropagation();
+            current = hit;
+            redraw();
+            const message = {
+                type: MESSAGE_TYPE,
+                action: "select",
+                blockId: hit.blockId,
+                ...(hit.field ? { field: hit.field } : {}),
+                ...(hit.node ? { node: hit.node } : {}),
+            };
+            admin.postMessage(message, targetOrigin);
+        };
+        const onMessage = (event) => {
+            if (event.source !== admin || event.origin !== targetOrigin) {
+                return;
+            }
+            if (isLabelsMessage(event.data)) {
+                labels = event.data.blocks;
+                hovered = hovered && relabel(hovered, labels);
+                current = current && relabel(current, labels);
+                redraw();
+                return;
+            }
+            if (!isFocusMessage(event.data)) {
+                return;
+            }
+            // Admin → preview: the editor focused a field; show where it is on the page.
+            for (const target of event.data.targets) {
+                const hit = hitForBlock(target.blockId, target.field, labels);
+                if (!hit) {
+                    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) {
+                    return;
+                }
+                current = hit;
+                redraw();
+                if (!inViewport(hit.element)) {
+                    hit.element.scrollIntoView({ behavior: "smooth", block: "center" });
+                }
+                return;
+            }
+            // The editor moved to a field this page does not mark, e.g. the document title.
+            clearSelection();
+        };
+        const onKeyDown = (event) => {
+            if (event.key === "Escape") {
+                clearSelection();
+            }
+        };
+        document.addEventListener("pointermove", onPointerMove, { passive: true });
+        document.documentElement.addEventListener("pointerleave", onPointerLeave);
+        document.addEventListener("click", onClick, true);
+        document.addEventListener("keydown", onKeyDown);
+        window.addEventListener("message", onMessage);
+        window.addEventListener("scroll", redraw, { passive: true, capture: true });
+        window.addEventListener("resize", redraw);
+        const ready = { type: MESSAGE_TYPE, action: "ready" };
+        admin.postMessage(ready, targetOrigin);
+        return () => {
+            cancelAnimationFrame(frame);
+            document.removeEventListener("pointermove", onPointerMove);
+            document.documentElement.removeEventListener("pointerleave", onPointerLeave);
+            document.removeEventListener("click", onClick, true);
+            document.removeEventListener("keydown", onKeyDown);
+            window.removeEventListener("message", onMessage);
+            window.removeEventListener("scroll", redraw, { capture: true });
+            window.removeEventListener("resize", redraw);
+            hover.remove();
+            selected.remove();
+        };
+    }, [adminOrigin]);
+    return 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) {
+        return null;
+    }
+    const field = marked !== block ? (marked.getAttribute(ATTR_FIELD) ?? undefined) : undefined;
+    const label = labelFor(block, field, labels);
+    const node = field && marked.hasAttribute(ATTR_RICHTEXT) ? richTextNode(marked, target) : null;
+    if (node) {
+        return { element: node.element, blockId, field, node: node.ref, label };
+    }
+    return { element: marked, blockId, field, label };
+}
+function hitForBlock(blockId, field, labels) {
+    const block = document.querySelector(`[${ATTR_BLOCK}="${CSS.escape(blockId)}"]`);
+    if (!block) {
+        return null;
+    }
+    const fieldElement = field
+        ? Array.from(block.querySelectorAll(`[${ATTR_FIELD}="${CSS.escape(field)}"]`)).find((element) => element.closest(`[${ATTR_BLOCK}]`) === block)
+        : undefined;
+    if (field && fieldElement) {
+        return { element: fieldElement, blockId, field, label: labelFor(block, 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. */
+function labelFor(block, field, labels) {
+    const type = block.getAttribute(ATTR_BLOCK_TYPE) ?? undefined;
+    const known = type ? labels[type] : undefined;
+    const blockLabel = block.getAttribute(ATTR_BLOCK_NAME) || known?.label || (type ? humanize(type) : "Block");
+    if (!field) {
+        return blockLabel;
+    }
+    return `${blockLabel} › ${known?.fields[field] ?? humanize(field)}`;
+}
+function relabel(hit, labels) {
+    const block = hit.element.closest(`[${ATTR_BLOCK}]`);
+    return block ? { ...hit, label: labelFor(block, hit.field, labels) } : hit;
+}
+function inViewport(element) {
+    const rect = element.getBoundingClientRect();
+    return rect.bottom > 0 && rect.top < window.innerHeight;
+}
+/** The top-level node (direct child of the rich text container) that contains the target. */
+function richTextNode(container, target) {
+    let element = target;
+    while (element && element.parentElement !== container) {
+        element = element.parentElement;
+    }
+    if (!(element instanceof HTMLElement)) {
+        return null;
+    }
+    const index = Array.from(container.children).indexOf(element);
+    const text = nodeSnippet(element.textContent);
+    return { element, ref: text ? { index, text } : { index } };
+}
+function createOverlay(solid) {
+    const box = document.createElement("div");
+    Object.assign(box.style, {
+        position: "fixed",
+        zIndex: "2147483646",
+        pointerEvents: "none",
+        display: "none",
+        boxSizing: "border-box",
+        border: `2px ${solid ? "solid" : "dashed"} ${HIGHLIGHT_COLOR}`,
+        borderRadius: "4px",
+        background: solid ? HIGHLIGHT_TINT : "transparent",
+        transition: "top 60ms, left 60ms, width 60ms, height 60ms",
+    });
+    const tag = document.createElement("span");
+    Object.assign(tag.style, {
+        position: "absolute",
+        top: "-22px",
+        left: "-2px",
+        padding: "2px 6px",
+        borderRadius: "4px 4px 0 0",
+        background: HIGHLIGHT_COLOR,
+        color: "#fff",
+        font: "500 11px/16px system-ui, sans-serif",
+        whiteSpace: "nowrap",
+    });
+    box.append(tag);
+    document.body.append(box);
+    return box;
+}
+function place(box, hit) {
+    if (!hit || !hit.element.isConnected) {
+        box.style.display = "none";
+        return;
+    }
+    const rect = hit.element.getBoundingClientRect();
+    Object.assign(box.style, {
+        display: "block",
+        top: `${rect.top}px`,
+        left: `${rect.left}px`,
+        width: `${rect.width}px`,
+        height: `${rect.height}px`,
+    });
+    const tag = box.firstElementChild;
+    tag.textContent = hit.label;
+    // Keep the label inside the viewport for blocks that start at the top.
+    tag.style.top = rect.top < 22 ? "0" : "-22px";
+}
+function humanize(value) {
+    const words = value
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[-_.]+/g, " ")
+        .toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+function referrerOrigin() {
+    try {
+        return document.referrer ? new URL(document.referrer).origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/frontend/editable.d.ts

@@ -0,0 +1,21 @@
+type EditableAttributes = Partial<Record<string, string>>;
+/**
+ * Mark the element that renders a block. Spread it on the block's outermost element:
+ * `<section {...editableBlock(block)}>`. Emits nothing without a block id.
+ */
+export declare function editableBlock(block: {
+    id?: string | null;
+    blockType?: string | null;
+    blockName?: string | null;
+}): EditableAttributes;
+/**
+ * Mark one field inside a block, e.g. `<h1 {...editableField("headline")}>`.
+ * Clicking it opens that field instead of the whole block.
+ */
+export declare function editableField(name: 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.
+ */
+export declare function editableRichText(name: string): EditableAttributes;
+export {};

package/dist/frontend/editable.js

@@ -0,0 +1,29 @@
+import { ATTR_BLOCK, ATTR_BLOCK_NAME, ATTR_BLOCK_TYPE, ATTR_FIELD, 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.
+ */
+export function editableBlock(block) {
+    if (!block.id) {
+        return {};
+    }
+    return {
+        [ATTR_BLOCK]: block.id,
+        ...(block.blockType ? { [ATTR_BLOCK_TYPE]: block.blockType } : {}),
+        ...(block.blockName ? { [ATTR_BLOCK_NAME]: block.blockName } : {}),
+    };
+}
+/**
+ * Mark one field inside a block, e.g. `<h1 {...editableField("headline")}>`.
+ * Clicking it opens that field instead of the whole block.
+ */
+export function editableField(name) {
+    return { [ATTR_FIELD]: name };
+}
+/**
+ * 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.
+ */
+export function editableRichText(name) {
+    return { [ATTR_FIELD]: name, [ATTR_RICHTEXT]: "" };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { VisualEditingPluginOptions } from "./plugin.ts";
+export { visualEditingPlugin } from "./plugin.ts";

package/dist/index.js

@@ -0,0 +1 @@
+export { visualEditingPlugin } from "./plugin.js";

package/dist/labels.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Collect the labels Admin shows for blocks and their fields, so the preview overlay can use
+ * 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";
+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. */
+export type BlockLabels = Record<string, BlockLabel>;
+export declare function collectBlockLabels(rootFields: FieldLike[], blocksBySlug: Record<string, BlockLike | undefined> | undefined, 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

@@ -0,0 +1,73 @@
+/**
+ * Collect the labels Admin shows for blocks and their fields, so the preview overlay can use
+ * 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.
+ */
+export function collectBlockLabels(rootFields, blocksBySlug, language) {
+    const result = {};
+    const visitFields = (fields) => {
+        for (const field of fields) {
+            if (field.type === "blocks") {
+                for (const block of blocksOf(field, blocksBySlug)) {
+                    if (result[block.slug]) {
+                        continue;
+                    }
+                    const fields = {};
+                    result[block.slug] = { label: labelText(block.labels?.singular, language), fields };
+                    collectFieldLabels(block.fields ?? [], "", language, fields);
+                    visitFields(block.fields ?? []);
+                }
+                continue;
+            }
+            for (const tab of field.tabs ?? []) {
+                visitFields(tab.fields ?? []);
+            }
+            visitFields(field.fields ?? []);
+        }
+    };
+    visitFields(rootFields);
+    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) {
+        if (field.type === "tabs") {
+            for (const tab of field.tabs ?? []) {
+                collectFieldLabels(tab.fields ?? [], tab.name ? `${prefix}${tab.name}.` : prefix, language, into);
+            }
+            continue;
+        }
+        if (!field.name) {
+            // Row, collapsible or unnamed group: transparent for paths.
+            collectFieldLabels(field.fields ?? [], prefix, language, into);
+            continue;
+        }
+        const path = `${prefix}${field.name}`;
+        const label = labelText(field.label, language);
+        if (label) {
+            into[path] = label;
+        }
+        // Array rows and nested blocks are marked as their own rows, not as fields of this block.
+        if (field.type === "group") {
+            collectFieldLabels(field.fields ?? [], `${path}.`, language, into);
+        }
+    }
+}
+function blocksOf(field, blocksBySlug) {
+    const referenced = (field.blockReferences ?? []).map((reference) => typeof reference === "string" ? blocksBySlug?.[reference] : reference);
+    return [...(field.blocks ?? []), ...referenced].filter((block) => typeof block?.slug === "string");
+}
+/** Client config labels are a string or a `{ [language]: string }` map; anything else has no static text. */
+export function labelText(label, language) {
+    if (typeof label === "string") {
+        return label || undefined;
+    }
+    if (!label || typeof label !== "object") {
+        return undefined;
+    }
+    const translations = label;
+    const text = translations[language] ??
+        translations.en ??
+        Object.values(translations).find((value) => typeof value === "string");
+    return typeof text === "string" && text ? text : undefined;
+}

package/dist/package-name.d.ts

@@ -0,0 +1,2 @@
+export declare const PACKAGE_NAME = "@simmalugnt-se/payload-visual-editing";
+export declare const CLIENT_ENTRY = "@simmalugnt-se/payload-visual-editing/client";

package/dist/package-name.js

@@ -0,0 +1,2 @@
+export const PACKAGE_NAME = "@simmalugnt-se/payload-visual-editing";
+export const CLIENT_ENTRY = `${PACKAGE_NAME}/client`;

package/dist/plugin.d.ts

@@ -0,0 +1,7 @@
+import type { Plugin } from "payload";
+export type VisualEditingPluginOptions = {
+    /** Collection slugs whose Live Preview should support click-to-edit. */
+    collections: string[];
+    disabled?: boolean;
+};
+export declare function visualEditingPlugin(options: VisualEditingPluginOptions): Plugin;

package/dist/plugin.js

@@ -0,0 +1,30 @@
+import { CLIENT_ENTRY } from "./package-name.js";
+const BRIDGE = `${CLIENT_ENTRY}#VisualEditingAdminBridge`;
+export function visualEditingPlugin(options) {
+    return (config) => {
+        if (options.disabled) {
+            return config;
+        }
+        const enabled = new Set(options.collections);
+        return {
+            ...config,
+            collections: (config.collections ?? []).map((collection) => enabled.has(collection.slug) ? withBridge(collection) : collection),
+        };
+    };
+}
+function withBridge(collection) {
+    const edit = collection.admin?.components?.edit;
+    return {
+        ...collection,
+        admin: {
+            ...collection.admin,
+            components: {
+                ...collection.admin?.components,
+                edit: {
+                    ...edit,
+                    beforeDocumentControls: [...(edit?.beforeDocumentControls ?? []), BRIDGE],
+                },
+            },
+        },
+    };
+}

package/dist/protocol.d.ts

@@ -0,0 +1,92 @@
+/** Shared between the preview (iframe) and Admin. No React, no DOM access. */
+import type { BlockLabels } from "./labels.ts";
+export declare const MESSAGE_TYPE = "payload-visual-editing";
+export declare const ATTR_BLOCK = "data-payload-block";
+/** Block slug; the preview looks up the label Admin sent for it. */
+export declare 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 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";
+export type SelectMessage = {
+    type: typeof MESSAGE_TYPE;
+    action: "select";
+    blockId: string;
+    /** Field name relative to the block, e.g. "headline". */
+    field?: string;
+    /** Top-level rich text node that was clicked; `text` disambiguates when indexes drift. */
+    node?: {
+        index: number;
+        text?: string;
+    };
+};
+export declare function isSelectMessage(value: unknown): value is SelectMessage;
+/**
+ * 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 declare function matchNodeIndex(nodeTexts: string[], node: {
+    index: number;
+    text?: string;
+}): number;
+/** Preview text sent with a node: enough to recognise it, never the whole document. */
+export declare function nodeSnippet(text: string | null | undefined): string | undefined;
+/** Admin → preview: the editor moved focus to a field; outline the matching element. */
+export type FocusMessage = {
+    type: typeof MESSAGE_TYPE;
+    action: "focus";
+    /** Candidates from the innermost row outwards; the preview uses the first it has marked. */
+    targets: Array<{
+        blockId: string;
+        field?: string;
+    }>;
+};
+export declare function isFocusMessage(value: unknown): value is FocusMessage;
+/** Preview → Admin: the preview has loaded and wants the block labels. */
+export type ReadyMessage = {
+    type: typeof MESSAGE_TYPE;
+    action: "ready";
+};
+export declare function isReadyMessage(value: unknown): value is ReadyMessage;
+/** Admin → preview: labels for the overlay, keyed by block slug. */
+export type LabelsMessage = {
+    type: typeof MESSAGE_TYPE;
+    action: "labels";
+    blocks: BlockLabels;
+};
+export declare function isLabelsMessage(value: unknown): value is LabelsMessage;
+/** Inverse of `fieldDomId`: "field-layout__0__headline" → "layout.0.headline". */
+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).
+ */
+export declare function focusTargets(path: string, fields: Record<string, {
+    value?: unknown;
+} | undefined>): FocusMessage["targets"];
+/** One step from the document root down to the clicked row. */
+export type RowStep = {
+    parentPath: string;
+    index: number;
+};
+export type BlockTarget = {
+    /** Form path of the block row, e.g. "layout.2". */
+    rowPath: string;
+    /** Rows to expand, outermost first. */
+    rows: RowStep[];
+};
+/**
+ * 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 declare function resolveBlockTarget(fields: Record<string, {
+    value?: unknown;
+} | undefined>, blockId: string): BlockTarget | null;
+/** DOM id Payload gives field inputs: "layout.0.headline" → "field-layout__0__headline". */
+export declare function fieldDomId(path: string): string;
+/** Inverse of `rowDomId`: "layout-0-items-row-1" → "layout.0.items.1". */
+export declare function pathFromRowDomId(id: string): string | undefined;
+/** DOM id Payload gives block and array rows: ("layout", 0) → "layout-row-0". */
+export declare function rowDomId(step: RowStep): string;