@worthy-ventures/metaglotta-observer 1.0.0

package/dist-esm/observer.js

@@ -0,0 +1,405 @@
+import { isMarked, mark, readMarks } from './marks.js';
+const MODIFIER_FLAG = {
+    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;
+export function createObserver(options) {
+    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();
+    const held = new Set();
+    let mutations;
+    let listeners = [];
+    let cursor;
+    let outlined;
+    const ignored = (element) => Boolean(options.ignore?.(element)) || SKIP_TAGS.has(element.tagName);
+    const withinIgnored = (node) => {
+        let at = node;
+        while (at) {
+            if (at.nodeType === Node.ELEMENT_NODE && ignored(at))
+                return true;
+            at = at.parentNode;
+        }
+        return false;
+    };
+    // ---- 2. scan ----------------------------------------------------------------------
+    function register(element, node, keys) {
+        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) {
+        const raw = node.nodeValue;
+        if (!raw || !isMarked(raw))
+            return;
+        const owner = node.nodeType === Node.ATTRIBUTE_NODE ? node.ownerElement : node.parentElement;
+        if (!owner || withinIgnored(owner))
+            return;
+        const { text, keys } = readMarks(raw);
+        node.nodeValue = text;
+        if (keys.length)
+            register(owner, node, keys);
+    }
+    function scan(node) {
+        if (node.nodeType === Node.TEXT_NODE) {
+            absorb(node);
+            return;
+        }
+        if (node.nodeType !== Node.ELEMENT_NODE && node.nodeType !== Node.DOCUMENT_NODE)
+            return;
+        if (node.nodeType === Node.ELEMENT_NODE && ignored(node))
+            return;
+        const elements = [node, ...Array.from(node.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 = [];
+        while (walker.nextNode())
+            found.push(walker.currentNode);
+        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() {
+        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.ownerElement?.isConnected : node.isConnected;
+                if (!stillThere)
+                    entry.nodes.delete(node);
+            }
+            if (entry.nodes.size === 0) {
+                unoutline(element);
+                registry.delete(element);
+            }
+        }
+    }
+    // ---- 3. point ---------------------------------------------------------------------
+    function armed() {
+        return armWith.every(key => held.has(key));
+    }
+    function trackModifiers(event) {
+        for (const name of Object.keys(MODIFIER_FLAG)) {
+            if (event[MODIFIER_FLAG[name]])
+                held.add(name);
+            else
+                held.delete(name);
+        }
+    }
+    function registeredAt(x, y) {
+        for (const candidate of document.elementsFromPoint(x, y)) {
+            let at = candidate;
+            while (at) {
+                if (ignored(at))
+                    return undefined;
+                if (registry.has(at))
+                    return at;
+                at = at.parentElement;
+            }
+        }
+        return undefined;
+    }
+    function outline(element) {
+        if (outlined === element) {
+            if (element)
+                position(element);
+            return;
+        }
+        if (outlined)
+            unoutline(outlined);
+        outlined = element;
+        if (element)
+            position(element);
+    }
+    function position(element) {
+        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) {
+        const entry = registry.get(element);
+        entry?.outline?.remove();
+        if (entry)
+            entry.outline = undefined;
+        if (outlined === element)
+            outlined = undefined;
+    }
+    function refresh() {
+        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) {
+        trackModifiers(event);
+        if (!armed())
+            return;
+        const target = event.target;
+        if (target && withinIgnored(target))
+            return;
+        event.stopPropagation();
+        event.preventDefault();
+    }
+    function onClick(event) {
+        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() {
+        const on = (type, handler, passive = false) => {
+            const wrapped = handler;
+            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']) {
+            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, props, namespace) => mark(result, { key: props.key, ns: namespace || undefined, defaultValue: props.defaultValue }),
+        run() {
+            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);
+            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 || (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, {
+                childList: true,
+                subtree: true,
+                characterData: true,
+                attributes: true,
+                attributeFilter: attributes,
+            });
+        },
+        stop() {
+            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, ns) {
+            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 = [];
+            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, ns) {
+            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() {
+            const hidden = [...registry.values()].map(entry => entry.outline).filter((box) => Boolean(box));
+            for (const box of hidden)
+                box.style.visibility = 'hidden';
+            return () => {
+                for (const box of hidden)
+                    box.style.visibility = '';
+            };
+        },
+        /** Test seam. */
+        registeredCount: () => registry.size,
+    };
+}
+/** Undefined on either side means "any", which is how the dialog asks for everything. */
+function matches(found, key, ns) {
+    if (key !== undefined && found.key !== key)
+        return false;
+    if (ns !== undefined && (found.ns ?? '') !== ns)
+        return false;
+    return true;
+}
+//# sourceMappingURL=observer.js.map

package/dist-esm/observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../src/observer.ts"],"names":[],"mappings":"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"}

package/dist-esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@worthy-ventures/metaglotta-observer",
+    "version": "1.0.0",
+    "description": "Traces rendered text back to the translation key that produced it, for in-context editing. Authoring only - never in a production bundle.",
+    "license": "MIT",
+    "main": "dist/index.js",
+    "module": "dist-esm/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist-esm/index.js",
+            "require": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist/**/*",
+        "dist-esm/**/*",
+        "src/**/*",
+        "README.md"
+    ],
+    "sideEffects": false,
+    "scripts": {
+        "build": "npm run clean && tsc -p tsconfig.build.json && tsc -p tsconfig.esm.json && node -e \"require('fs').writeFileSync('dist-esm/package.json', JSON.stringify({type:'module'}))\"",
+        "test": "jest -c jest.config.js",
+        "clean": "rimraf dist dist-esm coverage"
+    },
+    "dependencies": {
+        "@worthy-ventures/metaglotta-runtime": "1.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { createObserver } from './observer.js';
+export type { KeyPosition, ModifierName, Observer, ObserverOptions } from './observer.js';
+export { mark, unmark, isMarked, readMarks, forgetInterned } from './marks.js';
+export type { MarkedKey } from './marks.js';

package/src/marks.test.ts

@@ -0,0 +1,125 @@
+import { forgetInterned, isMarked, mark, readMarks, unmark } from './marks.js';
+
+/**
+ * The marks are the whole trick, so they are tested harder than anything else here.
+ *
+ * If they are wrong the failure is not a crash - it is ALT+click opening the dialog on the
+ * wrong key, or a page whose text has invisible junk in it that copies into somebody's
+ * clipboard. Both are quiet.
+ */
+describe('marks', () => {
+    beforeEach(() => forgetInterned());
+
+    it('leaves the visible text exactly as it was', () => {
+        const marked = mark('Hello Ada', { key: 'greeting' });
+        expect(unmark(marked)).toBe('Hello Ada');
+        expect(marked.startsWith('Hello Ada')).toBe(true);
+    });
+
+    it('adds nothing a person can see', () => {
+        const marked = mark('Hello', { key: 'greeting' });
+        // Zero-width characters only, and no visible character beyond the text itself.
+        expect(marked.replace(/[‌‍]/g, '')).toBe('Hello');
+    });
+
+    it('reads the key back', () => {
+        const { keys } = readMarks(mark('Hello', { key: 'greeting' }));
+        expect(keys).toEqual([{ key: 'greeting', ns: undefined, defaultValue: undefined }]);
+    });
+
+    it('carries the namespace and the default value', () => {
+        const { keys } = readMarks(mark('Hello', { key: 'greeting', ns: 'login', defaultValue: 'Hi' }));
+        expect(keys).toEqual([{ key: 'greeting', ns: 'login', defaultValue: 'Hi' }]);
+    });
+
+    it('reads the text back without them', () => {
+        expect(readMarks(mark('Hello Ada', { key: 'greeting' })).text).toBe('Hello Ada');
+    });
+
+    /** Two strings interpolated into one text node is the commonest template there is. */
+    it('reads both keys when two marked strings were joined', () => {
+        const joined = mark('Hello', { key: 'greeting' }) + ' ' + mark('Ada', { key: 'name' });
+        const { text, keys } = readMarks(joined);
+
+        expect(text).toBe('Hello Ada');
+        expect(keys.map(k => k.key)).toEqual(['greeting', 'name']);
+    });
+
+    it('reads both when they were joined with nothing between them', () => {
+        const joined = mark('Hello', { key: 'a' }) + mark('Ada', { key: 'b' });
+        expect(readMarks(joined).keys.map(k => k.key)).toEqual(['a', 'b']);
+    });
+
+    /**
+     * The interning is what makes this usable rather than a curiosity: the encoded form is an
+     * index, so a long key costs the same as a short one and the DOM does not fill up with
+     * marks.
+     */
+    it('costs the same however long the key is', () => {
+        const short = mark('x', { key: 'a' });
+        const long = mark('x', { key: 'appointment_payment_amount_mismatch', ns: 'reception', defaultValue: 'A very long default value indeed' });
+
+        expect(long.length).toBe(short.length);
+    });
+
+    it('gives the same key the same index twice', () => {
+        expect(mark('x', { key: 'a' })).toBe(mark('x', { key: 'a' }));
+    });
+
+    it('tells two keys apart even past the first ten', () => {
+        const marked = Array.from({ length: 40 }, (_, i) => mark('x', { key: `key_${i}` }));
+        const read = marked.map(m => readMarks(m).keys[0]!.key);
+
+        expect(read).toEqual(Array.from({ length: 40 }, (_, i) => `key_${i}`));
+    });
+
+    it('handles a key that is not ASCII', () => {
+        const { keys } = readMarks(mark('x', { key: 'κλειδί', ns: 'ελληνικά' }));
+        expect(keys).toEqual([{ key: 'κλειδί', ns: 'ελληνικά', defaultValue: undefined }]);
+    });
+
+    it('marks an empty string, which is what the pipe renders for a missing key', () => {
+        const marked = mark('', { key: 'nowhere' });
+        expect(unmark(marked)).toBe('');
+        expect(readMarks(marked).keys.map(k => k.key)).toEqual(['nowhere']);
+    });
+
+    describe('text that was never marked', () => {
+        it('is not mistaken for marked', () => {
+            expect(isMarked('Hello Ada')).toBe(false);
+            expect(readMarks('Hello Ada')).toEqual({ text: 'Hello Ada', keys: [] });
+        });
+
+        /**
+         * Zero-width characters occur in real text - Persian and Hindi use the non-joiner,
+         * and every multi-person emoji is held together by joiners. A run of them is only a
+         * message if it decodes to an index this module actually handed out.
+         */
+        it('survives a zero-width joiner that came from real content', () => {
+            const family = '👨‍👩‍👧';
+            expect(readMarks(family).keys).toEqual([]);
+        });
+
+        it('survives a Persian non-joiner', () => {
+            expect(readMarks('می‌خواهم').keys).toEqual([]);
+        });
+
+        it('ignores a run that decodes to an index nobody handed out', () => {
+            // 27 characters: a well-formed run of three bytes that is not in the table.
+            const forged = '‍'.repeat(27);
+            expect(readMarks(forged).keys).toEqual([]);
+        });
+    });
+
+    it('knows a marked string from an unmarked one', () => {
+        expect(isMarked(mark('Hello', { key: 'a' }))).toBe(true);
+        expect(isMarked('Hello')).toBe(false);
+        expect(isMarked('')).toBe(false);
+    });
+
+    /** The marks must come out of anything shown to a person - a screenshot caption, a diff. */
+    it('strips every run, not just the first', () => {
+        const joined = mark('a', { key: 'a' }) + mark('b', { key: 'b' });
+        expect(unmark(joined)).toBe('ab');
+    });
+});