[6.x] Antlers Live Preview Field Sync

config/antlers.php

@@ -15,6 +15,36 @@
 
     'debugbar' => env('STATAMIC_ANTLERS_DEBUGBAR', true),
 
+    /*
+    |--------------------------------------------------------------------------
+    | Tracing
+    |--------------------------------------------------------------------------
+    |
+    | When tracing is enabled, every tracer listed here is resolved from the
+    | container and notified as every Antlers node is entered and exited.
+    |
+    */
+
+    'tracing' => env('STATAMIC_ANTLERS_TRACING', false),
+
+    'tracers' => [],
+
+    /*
+    |--------------------------------------------------------------------------
+    | HTML Instrumentation
+    |--------------------------------------------------------------------------
+    |
+    | When enabled, rendered Antlers output is annotated with markers that
+    | point back to the templates it came from. Since the markers expose
+    | template details, this is intended for development and tooling.
+    |
+    */
+
+    'instrumentation' => [
+        'enabled' => env('STATAMIC_ANTLERS_INSTRUMENTATION', false),
+        'cache' => env('STATAMIC_ANTLERS_INSTRUMENTATION_CACHE', true),
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | Guarded Variables

resources/js/components/fieldtypes/GroupFieldtype.vue

@@ -9,7 +9,7 @@
                     @close="toggleFullscreen"
                 >
                 </publish-field-fullscreen-header>
-                <section :class="{ 'mt-14 p-4': fullScreenMode }">
+                <section ref="fieldsContainer" :class="{ 'mt-14 p-4': fullScreenMode }">
                     <div class="@container/panel" :class="{
                         'bg-white dark:bg-gray-800 dark:border-gray-900 rounded-lg border': config.border,
                         'hidden' : isCollapsed && !fullScreenMode
@@ -33,11 +33,12 @@
 <script>
 import Fieldtype from './Fieldtype.vue';
 import ManagesPreviewText from './replicator/ManagesPreviewText';
-import {PublishFields as Fields, PublishFieldsProvider as FieldsProvider} from '@ui';
+import { PublishFields as Fields, PublishFieldsProvider as FieldsProvider } from '@ui';
+import { reveal } from '@api';
 
 export default {
     mixins: [Fieldtype, ManagesPreviewText],
-    components: {Fields, FieldsProvider },
+    components: { Fields, FieldsProvider },
     data() {
         return {
             containerWidth: null,
@@ -49,6 +50,11 @@ export default {
             },
         };
     },
+    mounted() {
+        reveal.mount(this.$refs.fieldsContainer, () => {
+            this.isCollapsed = false;
+        });
+    },
     computed: {
         values() {
             return this.value;

resources/js/components/ui/LivePreview/FieldHighlights.js

@@ -0,0 +1,108 @@
+const outlineColor = '96 165 250';
+const outlinePadding = 8;
+const fadeDuration = 180;
+
+export function createHighlightOverlay(doc) {
+    const win = doc.defaultView;
+    const duration = win.matchMedia('(prefers-reduced-motion: reduce)').matches ? 0 : fadeDuration;
+
+    const overlay = doc.createElement('div');
+    overlay.setAttribute('aria-hidden', 'true');
+    overlay.style.cssText = 'position:fixed;inset:0;pointer-events:none;z-index:2147483647;';
+    overlay.style.transition = `opacity ${duration}ms ease-out`;
+    doc.documentElement.append(overlay);
+
+    function createOutline(rect) {
+        const outline = doc.createElement('div');
+
+        Object.assign(outline.style, {
+            position: 'absolute',
+            left: `${rect.left - outlinePadding}px`,
+            top: `${rect.top - outlinePadding}px`,
+            width: `${rect.width + outlinePadding * 2}px`,
+            height: `${rect.height + outlinePadding * 2}px`,
+            border: `2px solid rgb(${outlineColor})`,
+            background: `rgb(${outlineColor} / 5%)`,
+            borderRadius: '5px',
+            boxSizing: 'border-box',
+        });
+
+        return outline;
+    }
+
+    function isOnScreen(rect) {
+        return rect.width && rect.height && rect.bottom >= 0 && rect.top <= win.innerHeight;
+    }
+
+    return {
+        fadeDuration: duration,
+
+        contains(node) {
+            return overlay.contains(node);
+        },
+
+        draw(entries, { faded = false } = {}) {
+            overlay.replaceChildren();
+            overlay.style.opacity = faded ? '0' : '1';
+
+            const drawn = new Set();
+
+            for (const entry of entries) {
+                const rect = entry.boundingRect();
+                if (!isOnScreen(rect)) continue;
+
+                const key = [rect.left, rect.top, rect.width, rect.height].join(',');
+                if (drawn.has(key)) continue;
+                drawn.add(key);
+
+                overlay.append(createOutline(rect));
+            }
+        },
+
+        dispose() {
+            overlay.remove();
+        },
+    };
+}
+
+export function createTimedHighlight(win, fadeDuration, onChange) {
+    let path = null;
+    let faded = false;
+    let fadeTimer;
+    let clearTimer;
+
+    function cancelTimers() {
+        win.clearTimeout(fadeTimer);
+        win.clearTimeout(clearTimer);
+    }
+
+    return {
+        get path() {
+            return path;
+        },
+
+        get faded() {
+            return faded;
+        },
+
+        show(newPath, duration) {
+            cancelTimers();
+            path = newPath;
+            faded = false;
+            onChange();
+
+            fadeTimer = win.setTimeout(() => {
+                faded = true;
+                onChange();
+
+                clearTimer = win.setTimeout(() => {
+                    path = null;
+                    faded = false;
+                    onChange();
+                }, fadeDuration);
+            }, duration);
+        },
+
+        dispose: cancelTimers,
+    };
+}

resources/js/components/ui/LivePreview/FieldIndex.js

@@ -0,0 +1,129 @@
+export const fieldManifestId = 'statamic-preview-fields';
+
+const fieldAttribute = 'data-statamic-field';
+const markerComment = /^(\/?)statamic:field:(\d+)$/;
+
+export function readFieldManifest(doc) {
+    let manifest;
+
+    try {
+        manifest = JSON.parse(doc.getElementById(fieldManifestId)?.textContent ?? 'null');
+    } catch {
+        return null;
+    }
+
+    return manifest?.owner && manifest.fields && manifest.markers ? manifest : null;
+}
+
+export function fieldPath(field) {
+    return field.path.join('.');
+}
+
+function createFieldEntry(fields, element, range, depth) {
+    const rects = () => (range ? Array.from(range.getClientRects()) : [element.getBoundingClientRect()]);
+
+    return {
+        fields,
+        element,
+        depth,
+        rects,
+        boundingRect: () => (range ?? element).getBoundingClientRect(),
+        contains: (x, y) => rects().some(rect => x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom),
+    };
+}
+
+function isSelectable(entry) {
+    return entry.fields.length === 1;
+}
+
+export function createFieldIndex(doc, manifest) {
+    const byElement = new WeakMap();
+    const byPath = new Map();
+
+    function ownedFieldsFor(marker) {
+        return (manifest.markers[marker] ?? [])
+            .map(id => manifest.fields[id])
+            .filter(field => {
+                return Array.isArray(field?.path)
+                    && field.reference === manifest.owner.reference
+                    && field.locale === manifest.owner.locale;
+            });
+    }
+
+    function register(marker, element, range = null, depth = 0) {
+        const fields = ownedFieldsFor(marker);
+        if (!fields.length || !element) return;
+
+        const entry = createFieldEntry(fields, element, range, depth);
+
+        byElement.set(element, [...(byElement.get(element) ?? []), entry]);
+
+        for (const field of fields) {
+            const path = fieldPath(field);
+            byPath.set(path, [...(byPath.get(path) ?? []), entry]);
+        }
+    }
+
+    function rangeBetween(start, end) {
+        const range = doc.createRange();
+        range.setStartAfter(start);
+        range.setEndBefore(end);
+
+        return range;
+    }
+
+    function indexDocument() {
+        const win = doc.defaultView;
+        const walker = doc.createTreeWalker(doc.body, win.NodeFilter.SHOW_ELEMENT | win.NodeFilter.SHOW_COMMENT);
+        const openMarkers = new Map();
+        let depth = 0;
+
+        const indexElement = element => {
+            if (element.hasAttribute(fieldAttribute)) register(element.getAttribute(fieldAttribute), element);
+        };
+
+        const indexComment = comment => {
+            const match = comment.data.match(markerComment);
+            if (!match) return;
+
+            const [, closing, marker] = match;
+
+            if (!closing) {
+                openMarkers.set(marker, { node: comment, depth: ++depth });
+                return;
+            }
+
+            const opened = openMarkers.get(marker);
+            openMarkers.delete(marker);
+            depth = Math.max(0, depth - 1);
+
+            if (opened && opened.node.parentNode === comment.parentNode) {
+                register(marker, comment.parentElement, rangeBetween(opened.node, comment), opened.depth);
+            }
+        };
+
+        while (walker.nextNode()) {
+            const node = walker.currentNode;
+
+            node.nodeType === win.Node.ELEMENT_NODE ? indexElement(node) : indexComment(node);
+        }
+    }
+
+    if (manifest && doc.body) indexDocument();
+
+    return {
+        entriesFor(path) {
+            return byPath.get(path) ?? [];
+        },
+
+        entryAt(x, y, target) {
+            for (let element = target; element; element = element.parentElement) {
+                const hits = (byElement.get(element) ?? []).filter(entry => isSelectable(entry) && entry.contains(x, y));
+
+                if (hits.length) return hits.sort((a, b) => b.depth - a.depth)[0];
+            }
+
+            return null;
+        },
+    };
+}

resources/js/components/ui/LivePreview/FieldScrolling.js

@@ -0,0 +1,61 @@
+function scrollContainersOf(doc, element) {
+    const win = doc.defaultView;
+    const containers = [];
+
+    for (let el = element; el && el !== doc.body; el = el.parentElement) {
+        if (el.scrollHeight > el.clientHeight && /auto|scroll|hidden/.test(win.getComputedStyle(el).overflowY)) {
+            containers.push(el);
+        }
+    }
+
+    return containers;
+}
+
+function isInView(doc, entry, rect) {
+    const win = doc.defaultView;
+
+    if (rect.top < 0 || rect.bottom > win.innerHeight || rect.left < 0 || rect.right > win.innerWidth) return false;
+
+    return scrollContainersOf(doc, entry.element).every(container => {
+        const bounds = container.getBoundingClientRect();
+
+        return rect.top >= bounds.top && rect.bottom <= bounds.bottom;
+    });
+}
+
+function scrollEntryIntoView(doc, entry) {
+    const win = doc.defaultView;
+
+    for (const container of scrollContainersOf(doc, entry.element)) {
+        const rect = entry.rects()[0];
+        const bounds = container.getBoundingClientRect();
+
+        if (rect.top < bounds.top || rect.bottom > bounds.bottom) {
+            container.scrollTop += rect.top - bounds.top + rect.height / 2 - container.clientHeight / 2;
+        }
+    }
+
+    entry.element.scrollIntoView({ block: 'center', inline: 'nearest' });
+
+    const rect = entry.rects()[0];
+
+    if (rect && (rect.top < 0 || rect.bottom > win.innerHeight)) {
+        win.scrollBy(0, rect.top + rect.height / 2 - win.innerHeight / 2);
+    }
+}
+
+export function scrollFieldIntoView(doc, entries) {
+    const win = doc.defaultView;
+    const occurrences = entries.flatMap(entry => {
+        return entry.rects()
+            .filter(rect => rect.width && rect.height)
+            .map(rect => ({ entry, rect }));
+    });
+
+    if (!occurrences.length || occurrences.some(({ entry, rect }) => isInView(doc, entry, rect))) return;
+
+    const distanceFromCenter = ({ rect }) => Math.abs(rect.top - win.innerHeight / 2);
+    const nearest = occurrences.sort((a, b) => distanceFromCenter(a) - distanceFromCenter(b))[0];
+
+    scrollEntryIntoView(doc, nearest.entry);
+}