@worthy-ventures/metaglotta-observer 1.0.0

package/src/observer.ts

@@ -0,0 +1,471 @@
+import type { TranslateProps } from '@worthy-ventures/metaglotta-runtime';
+import { isMarked, mark, readMarks, type MarkedKey } from './marks.js';
+
+/**
+ * Watches the page for marked text, and turns a click on it back into a key.
+ *
+ * Three jobs, and they are separate on purpose:
+ *
+ *  1. MARK - every string the runtime produces gets its key appended in invisible characters.
+ *     This is the `decorate` hook, and it is the only thing that touches the runtime.
+ *  2. SCAN - as marked text arrives in the DOM, read the keys out, take the marks back OUT of
+ *     the node so nothing can copy them into a clipboard, and remember which element the keys
+ *     belong to.
+ *  3. POINT - while the modifier is held, outline whatever is under the cursor and swallow the
+ *     click, so ALT+clicking a "Delete" button opens the dialog rather than deleting anything.
+ *
+ * Authoring only. Nothing in a production build should ever import this.
+ */
+
+export type ModifierName = 'Alt' | 'Control' | 'Shift' | 'Meta';
+
+export type KeyPosition = {
+    key: string;
+    ns: string;
+    position: { x: number; y: number; width: number; height: number };
+};
+
+export type ObserverOptions = {
+    /** What to do with an armed click. The target is the element the keys were found on. */
+    onClick: (keys: MarkedKey[], target: HTMLElement) => void;
+    /** Held to arm it. All of them, if more than one. Default: Alt. */
+    keys?: ModifierName[];
+    /** Attributes whose value may be a translation. */
+    attributes?: string[];
+    /** Where to watch. Default: the whole document. */
+    root?: Element | Document;
+    /** A subtree to leave alone entirely - the editing dialog's own, for one. */
+    ignore?: (element: Element) => boolean;
+    highlightColor?: string;
+    highlightWidth?: number;
+};
+
+const MODIFIER_FLAG: Record<ModifierName, 'altKey' | 'ctrlKey' | 'shiftKey' | 'metaKey'> = {
+    Alt: 'altKey',
+    Control: 'ctrlKey',
+    Shift: 'shiftKey',
+    Meta: 'metaKey',
+};
+
+/** Where a translation plausibly lands other than in text. */
+const DEFAULT_ATTRIBUTES = ['title', 'placeholder', 'aria-label', 'alt', 'value', 'label'];
+
+/** Never worth walking into: their text is not for reading. */
+const SKIP_TAGS = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'TEXTAREA']);
+
+const HIGHLIGHT_CLASS = 'mg-observer-highlight';
+
+/**
+ * How many observers are watching, so a second one can say so.
+ *
+ * Two on the same document silently break each other: marks are taken OUT of a node as it is
+ * scanned, so whichever observer's mutation callback runs first absorbs them and the other
+ * registers nothing at all. ALT+click then does nothing, with no error to explain it.
+ *
+ * One page only ever has one. Where this bites is a hot reload, or a test that forgot to stop
+ * the previous instance - both of which look like the feature is broken rather than
+ * double-installed.
+ */
+let watching = 0;
+
+type Registered = {
+    element: HTMLElement;
+    /** Per node, because one element can hold several marked nodes and lose them separately. */
+    nodes: Map<Node, MarkedKey[]>;
+    outline?: HTMLElement;
+};
+
+export function createObserver(options: ObserverOptions) {
+    const armWith = options.keys ?? ['Alt'];
+    const attributes = options.attributes ?? DEFAULT_ATTRIBUTES;
+    const root = options.root ?? document;
+    /**
+     * Tech Blue, the brand accent.
+     *
+     * An outline is one of the few places the light blue is right: it sits on top of the page
+     * rather than under text, so its 2.14:1 against white does not matter - what matters is
+     * that it reads as ours. Pass highlightColor to override it on a page it disappears into.
+     */
+    const highlightColor = options.highlightColor ?? '#38bdf8';
+    const highlightWidth = options.highlightWidth ?? 2;
+
+    const registry = new Map<HTMLElement, Registered>();
+    const held = new Set<ModifierName>();
+
+    let mutations: MutationObserver | undefined;
+    let listeners: (() => void)[] = [];
+    let cursor: { x: number; y: number } | undefined;
+    let outlined: HTMLElement | undefined;
+
+    const ignored = (element: Element): boolean => Boolean(options.ignore?.(element)) || SKIP_TAGS.has(element.tagName);
+
+    const withinIgnored = (node: Node): boolean => {
+        let at: Node | null = node;
+        while (at) {
+            if (at.nodeType === Node.ELEMENT_NODE && ignored(at as Element)) return true;
+            at = at.parentNode;
+        }
+        return false;
+    };
+
+    // ---- 2. scan ----------------------------------------------------------------------
+
+    function register(element: HTMLElement, node: Node, keys: MarkedKey[]): void {
+        let entry = registry.get(element);
+        if (!entry) {
+            entry = { element, nodes: new Map() };
+            registry.set(element, entry);
+        }
+        entry.nodes.set(node, keys);
+    }
+
+    /**
+     * Reads the keys out and puts the visible text back.
+     *
+     * Stripping is not tidiness. Marks left in the DOM are copied by Ctrl+C, submitted in
+     * form values, and compared against by application code that has no idea they are there -
+     * and because they are invisible, the resulting bug looks like magic. Writing the node
+     * back triggers another mutation, which is harmless: the text is no longer marked, so the
+     * next pass skips it.
+     */
+    function absorb(node: Text | Attr): void {
+        const raw = node.nodeValue;
+        if (!raw || !isMarked(raw)) return;
+
+        const owner = node.nodeType === Node.ATTRIBUTE_NODE ? (node as Attr).ownerElement : node.parentElement;
+        if (!owner || withinIgnored(owner)) return;
+
+        const { text, keys } = readMarks(raw);
+        node.nodeValue = text;
+        if (keys.length) register(owner as HTMLElement, node, keys);
+    }
+
+    function scan(node: Node): void {
+        if (node.nodeType === Node.TEXT_NODE) {
+            absorb(node as Text);
+            return;
+        }
+        if (node.nodeType !== Node.ELEMENT_NODE && node.nodeType !== Node.DOCUMENT_NODE) return;
+        if (node.nodeType === Node.ELEMENT_NODE && ignored(node as Element)) return;
+
+        const elements = [node as Element, ...Array.from((node as Element).querySelectorAll?.('*') ?? [])];
+        for (const element of elements) {
+            if (element.nodeType !== Node.ELEMENT_NODE || ignored(element)) continue;
+            for (const name of attributes) {
+                const attribute = element.getAttributeNode?.(name);
+                if (attribute) absorb(attribute);
+            }
+        }
+
+        const walker = document.createTreeWalker(node, NodeFilter.SHOW_TEXT, {
+            acceptNode: text =>
+                isMarked(text.nodeValue ?? '') && !SKIP_TAGS.has(text.parentElement?.tagName ?? '')
+                    ? NodeFilter.FILTER_ACCEPT
+                    : NodeFilter.FILTER_REJECT,
+        });
+        const found: Text[] = [];
+        while (walker.nextNode()) found.push(walker.currentNode as Text);
+        for (const text of found) absorb(text);
+    }
+
+    /**
+     * Forgets what has left the page.
+     *
+     * Without this the registry holds every element the page has ever rendered - a leak that
+     * also makes findPositions() report boxes for text nobody can see.
+     */
+    function forget(): void {
+        for (const [element, entry] of registry) {
+            if (!element.isConnected) {
+                unoutline(element);
+                registry.delete(element);
+                continue;
+            }
+            for (const node of entry.nodes.keys()) {
+                const stillThere = node.nodeType === Node.ATTRIBUTE_NODE ? (node as Attr).ownerElement?.isConnected : node.isConnected;
+                if (!stillThere) entry.nodes.delete(node);
+            }
+            if (entry.nodes.size === 0) {
+                unoutline(element);
+                registry.delete(element);
+            }
+        }
+    }
+
+    // ---- 3. point ---------------------------------------------------------------------
+
+    function armed(): boolean {
+        return armWith.every(key => held.has(key));
+    }
+
+    function trackModifiers(event: MouseEvent | KeyboardEvent): void {
+        for (const name of Object.keys(MODIFIER_FLAG) as ModifierName[]) {
+            if (event[MODIFIER_FLAG[name]]) held.add(name);
+            else held.delete(name);
+        }
+    }
+
+    function registeredAt(x: number, y: number): HTMLElement | undefined {
+        for (const candidate of document.elementsFromPoint(x, y)) {
+            let at: Element | null = candidate;
+            while (at) {
+                if (ignored(at)) return undefined;
+                if (registry.has(at as HTMLElement)) return at as HTMLElement;
+                at = at.parentElement;
+            }
+        }
+        return undefined;
+    }
+
+    function outline(element: HTMLElement | undefined): void {
+        if (outlined === element) {
+            if (element) position(element);
+            return;
+        }
+        if (outlined) unoutline(outlined);
+        outlined = element;
+        if (element) position(element);
+    }
+
+    function position(element: HTMLElement): void {
+        const entry = registry.get(element);
+        if (!entry || !element.isConnected) return;
+
+        if (!entry.outline) {
+            const box = document.createElement('div');
+            box.className = HIGHLIGHT_CLASS;
+            Object.assign(box.style, {
+                position: 'fixed',
+                boxSizing: 'content-box',
+                pointerEvents: 'none',
+                zIndex: String(Number.MAX_SAFE_INTEGER),
+                borderStyle: 'solid',
+                borderRadius: '4px',
+                borderColor: highlightColor,
+                borderWidth: `${highlightWidth}px`,
+                contain: 'layout',
+            });
+            document.body.appendChild(box);
+            entry.outline = box;
+        }
+
+        const shape = element.getBoundingClientRect();
+        Object.assign(entry.outline.style, {
+            top: `${shape.top - highlightWidth}px`,
+            left: `${shape.left - highlightWidth}px`,
+            width: `${shape.width}px`,
+            height: `${shape.height}px`,
+        });
+    }
+
+    function unoutline(element: HTMLElement): void {
+        const entry = registry.get(element);
+        entry?.outline?.remove();
+        if (entry) entry.outline = undefined;
+        if (outlined === element) outlined = undefined;
+    }
+
+    function refresh(): void {
+        outline(armed() && cursor ? registeredAt(cursor.x, cursor.y) : undefined);
+    }
+
+    /**
+     * Swallows the page's own interaction while armed.
+     *
+     * ALT+clicking a "Delete patient" button has to open the dialog and nothing else, so the
+     * event is stopped in the capture phase - before the application's own listener - and on
+     * every mouse event, not only click: a hover handler that opens a menu would otherwise
+     * fire and cover the thing being clicked.
+     */
+    function swallow(event: MouseEvent): void {
+        trackModifiers(event);
+        if (!armed()) return;
+        const target = event.target as Element | null;
+        if (target && withinIgnored(target)) return;
+        event.stopPropagation();
+        event.preventDefault();
+    }
+
+    function onClick(event: MouseEvent): void {
+        swallow(event);
+        cursor = { x: event.clientX, y: event.clientY };
+        if (!armed()) return;
+
+        const element = registeredAt(event.clientX, event.clientY);
+        if (!element) return;
+
+        const keys = [...(registry.get(element)?.nodes.values() ?? [])].flat();
+        if (!keys.length) return;
+
+        outline(undefined);
+        options.onClick(keys, element);
+    }
+
+    function listen(): void {
+        const on = <K extends keyof DocumentEventMap>(type: K, handler: (event: DocumentEventMap[K]) => void, passive = false) => {
+            const wrapped = handler as EventListener;
+            document.addEventListener(type, wrapped, { capture: true, passive });
+            listeners.push(() => document.removeEventListener(type, wrapped, { capture: true }));
+        };
+
+        on('keydown', event => {
+            trackModifiers(event);
+            refresh();
+        });
+        on('keyup', event => {
+            trackModifiers(event);
+            refresh();
+        });
+        on('mousemove', event => {
+            trackModifiers(event);
+            cursor = { x: event.clientX, y: event.clientY };
+            refresh();
+        }, true);
+        on('scroll', () => refresh(), true);
+        on('click', onClick);
+        for (const type of ['mousedown', 'mouseup', 'mouseover', 'mouseout', 'mouseenter', 'mouseleave'] as const) {
+            on(type, swallow);
+        }
+        // A window that loses focus never sees the keyup, so the modifier would stay held.
+        const onBlur = () => {
+            held.clear();
+            refresh();
+        };
+        window.addEventListener('blur', onBlur);
+        listeners.push(() => window.removeEventListener('blur', onBlur));
+    }
+
+    // ---- the public surface -----------------------------------------------------------
+
+    return {
+        /**
+         * Pass as `decorate` to the runtime. Everything else follows from this.
+         *
+         * The namespace comes from the runtime, not from `props`: props hold what the caller
+         * asked with, which for most templates is nothing at all, while this is where the
+         * string was actually resolved from. Marking with the former is what made the dialog
+         * open on the default namespace with nothing in it.
+         */
+        mark: (result: string, props: TranslateProps, namespace: string): string =>
+            mark(result, { key: props.key, ns: namespace || undefined, defaultValue: props.defaultValue }),
+
+        run(): void {
+            if (mutations) return;
+
+            watching += 1;
+            if (watching > 1) {
+                console.warn(
+                    `Metaglotta: ${watching} in-context observers are running at once. They will take each other's marks and ALT+click will stop finding keys - stop the previous one.`
+                );
+            }
+
+            scan(root as Node);
+            listen();
+
+            mutations = new MutationObserver(records => {
+                let anythingRemoved = false;
+                for (const record of records) {
+                    if (record.type === 'characterData') scan(record.target);
+                    if (record.type === 'attributes') scan(record.target);
+                    if (record.type === 'childList') {
+                        record.addedNodes.forEach(node => scan(node));
+                        anythingRemoved ||= record.removedNodes.length > 0;
+                    }
+                }
+                // Swept by what is still connected rather than by what was reported: a node
+                // moved and a node deleted look the same in a mutation record, and only the
+                // DOM knows which happened.
+                if (anythingRemoved) forget();
+            });
+
+            mutations.observe(root as Node, {
+                childList: true,
+                subtree: true,
+                characterData: true,
+                attributes: true,
+                attributeFilter: attributes,
+            });
+        },
+
+        stop(): void {
+            if (mutations) watching -= 1;
+            mutations?.disconnect();
+            mutations = undefined;
+            for (const off of listeners) off();
+            listeners = [];
+            for (const element of [...registry.keys()]) unoutline(element);
+            registry.clear();
+            held.clear();
+            cursor = undefined;
+        },
+
+        /**
+         * Where a key is on screen, in viewport coordinates.
+         *
+         * This is what a screenshot's boxes are drawn from, so the order matters: sorted by
+         * position in the document, because the dialog labels them in the order it gets them
+         * and a reader expects the first box to be the first occurrence.
+         */
+        findPositions(key?: string, ns?: string): KeyPosition[] {
+            const matching = [...registry.values()].filter(entry => [...entry.nodes.values()].flat().some(found => matches(found, key, ns)));
+
+            matching.sort((a, b) =>
+                a.element.compareDocumentPosition(b.element) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1
+            );
+
+            const positions: KeyPosition[] = [];
+            for (const entry of matching) {
+                const shape = entry.element.getBoundingClientRect();
+                for (const found of [...entry.nodes.values()].flat()) {
+                    if (!matches(found, key, ns)) continue;
+                    positions.push({
+                        key: found.key,
+                        ns: found.ns ?? '',
+                        position: { x: shape.x, y: shape.y, width: shape.width, height: shape.height },
+                    });
+                }
+            }
+            return positions;
+        },
+
+        /** Outlines every place a key appears. Returns how to put it back. */
+        highlight(key?: string, ns?: string): { unhighlight: () => void } {
+            const elements = [...registry.values()]
+                .filter(entry => [...entry.nodes.values()].flat().some(found => matches(found, key, ns)))
+                .map(entry => entry.element);
+
+            for (const element of elements) position(element);
+            return {
+                unhighlight: () => {
+                    for (const element of elements) unoutline(element);
+                },
+            };
+        },
+
+        /**
+         * Hides the outlines and hands back how to restore them.
+         *
+         * For screenshots: the outlines are fixed-position divs on the body, so they would be
+         * captured over the very text being photographed.
+         */
+        hideOutlines(): () => void {
+            const hidden = [...registry.values()].map(entry => entry.outline).filter((box): box is HTMLElement => Boolean(box));
+            for (const box of hidden) box.style.visibility = 'hidden';
+            return () => {
+                for (const box of hidden) box.style.visibility = '';
+            };
+        },
+
+        /** Test seam. */
+        registeredCount: (): number => registry.size,
+    };
+}
+
+export type Observer = ReturnType<typeof createObserver>;
+
+/** Undefined on either side means "any", which is how the dialog asks for everything. */
+function matches(found: MarkedKey, key?: string, ns?: string): boolean {
+    if (key !== undefined && found.key !== key) return false;
+    if (ns !== undefined && (found.ns ?? '') !== ns) return false;
+    return true;
+}