@worthy-ventures/metaglotta-observer 1.0.0

package/src/marks.ts

@@ -0,0 +1,128 @@
+/**
+ * Carrying a key inside the string it produced.
+ *
+ * The problem: a click lands on a DOM node, and nothing about that node says which
+ * translation key rendered it. The string may have been interpolated into a text node,
+ * concatenated with another, put in a `title` attribute, or handed to a chart library - 938
+ * call sites in these applications do the last one, and no amount of framework integration
+ * can follow a string somebody put in a canvas.
+ *
+ * So the key travels WITH the string, written in characters that occupy no space: a zero-width
+ * non-joiner for 0 and a zero-width joiner for 1. Appended to the rendered text, they are
+ * invisible, they survive concatenation and interpolation, and they can be read back out of
+ * `textContent` wherever the string ended up.
+ *
+ * Two things make that practical rather than merely clever:
+ *
+ *  - Keys are INTERNED. Encoding `{"k":"appointment_payment_amount_mismatch","n":"reception"}`
+ *    would add ~500 invisible characters to a string of thirty, and the DOM would be mostly
+ *    marks. Instead each distinct key gets a number, and only the number is encoded - one to
+ *    three digits. The table lives in this module for the life of the page, which is exactly
+ *    as long as the marks in the DOM do.
+ *  - Each byte is written as NINE characters, eight bits and a trailing zero. That makes an
+ *    encoded run a multiple of nine, which is how a run of marks is told apart from the odd
+ *    zero-width character that turns up in real text (Persian and Hindi both use them, and
+ *    emoji sequences are full of joiners).
+ */
+
+/** 0 and 1. Zero-width, so they render as nothing at all. */
+const ZERO = '‌';
+const ONE = '‍';
+
+/** Between two encoded numbers, when two marked strings ended up in one node. */
+const SEPARATOR = '\n';
+
+const BITS_PER_BYTE = 9;
+
+const RUN = new RegExp(`(?:[${ZERO}${ONE}]{${BITS_PER_BYTE}})+`, 'g');
+
+/**
+ * Keys seen this page, so only an index has to be encoded.
+ *
+ * Module-level and never pruned, which is right: an entry costs a string, and a mark in the
+ * DOM is only meaningful while the page that wrote it is still open.
+ */
+const interned: string[] = [];
+
+function intern(value: string): number {
+    const existing = interned.indexOf(value);
+    if (existing !== -1) return existing;
+    interned.push(value);
+    return interned.length - 1;
+}
+
+/**
+ * ASCII only, deliberately.
+ *
+ * What gets encoded is never the key itself - it is an index and a separator, so digits and
+ * one newline. That means no TextEncoder, which jsdom does not always provide, and no
+ * multi-byte handling to get wrong. The key's own characters live in the interning table,
+ * where they are just a JavaScript string.
+ */
+function encodeText(text: string): string {
+    let bits = '';
+    for (let at = 0; at < text.length; at += 1) {
+        bits += (text.charCodeAt(at) & 0x7f).toString(2).padStart(8, '0') + '0';
+    }
+    return [...bits].map(bit => (bit === '1' ? ONE : ZERO)).join('');
+}
+
+function decodeText(marks: string): string {
+    let text = '';
+    for (let at = 0; at + BITS_PER_BYTE <= marks.length; at += BITS_PER_BYTE) {
+        const bits = [...marks.slice(at, at + 8)].map(character => (character === ONE ? '1' : '0')).join('');
+        text += String.fromCharCode(parseInt(bits, 2));
+    }
+    return text;
+}
+
+export type MarkedKey = { key: string; ns?: string; defaultValue?: string };
+
+/** What a marked string carries: an index into the table, or several. */
+export function mark(text: string, key: MarkedKey): string {
+    return text + encodeText(String(intern(JSON.stringify([key.key, key.ns ?? '', key.defaultValue ?? '']))) + SEPARATOR);
+}
+
+/** Whether a string is worth decoding, cheaply enough to run on every text node. */
+export function isMarked(text: string): boolean {
+    return text.includes(ZERO) || text.includes(ONE);
+}
+
+/** The text as a person sees it, with the marks taken out. */
+export function unmark(text: string): string {
+    return text.replace(RUN, '');
+}
+
+/**
+ * The keys a string carries, and the string without them.
+ *
+ * Anything that does not decode to a known index is ignored rather than reported: real text
+ * contains zero-width characters for its own reasons, and a run that happens to be a multiple
+ * of nine is a coincidence this must survive rather than a message.
+ */
+export function readMarks(text: string): { text: string; keys: MarkedKey[] } {
+    const keys: MarkedKey[] = [];
+
+    for (const run of text.match(RUN) ?? []) {
+        for (const encoded of decodeText(run).split(SEPARATOR)) {
+            if (!encoded) continue;
+            const index = Number(encoded);
+            if (!Number.isInteger(index) || index < 0 || index >= interned.length) continue;
+
+            try {
+                const [key, ns, defaultValue] = JSON.parse(interned[index]!) as [string, string, string];
+                keys.push({ key, ns: ns || undefined, defaultValue: defaultValue || undefined });
+            } catch {
+                // An entry this module wrote cannot fail to parse; if it somehow does, the
+                // right answer is one fewer key rather than a broken page.
+            }
+        }
+    }
+
+    return { text: unmark(text), keys };
+}
+
+/** Test seam: the table is a module global by design, and lives as long as the page. */
+export function forgetInterned(): void {
+    interned.length = 0;
+}

package/src/observer.test.ts

@@ -0,0 +1,522 @@
+import { forgetInterned } from './marks.js';
+import { createObserver, type Observer } from './observer.js';
+
+/**
+ * The observer, against a real DOM.
+ *
+ * jsdom does the useful half here - text nodes, attributes, MutationObserver, TreeWalker are
+ * all real. What it does not do is lay anything out, so getBoundingClientRect returns zeros
+ * and elementsFromPoint returns nothing; those two are stubbed per test, and every assertion
+ * that depends on them says so.
+ */
+
+type Clicked = { keys: { key: string; ns?: string; defaultValue?: string }[]; target: HTMLElement };
+
+let observer: Observer | undefined;
+let clicks: Clicked[];
+
+/** A macrotask: MutationObserver callbacks are microtasks, one hop is enough. */
+const settle = () => new Promise(resolve => setTimeout(resolve, 0));
+
+function start(options: Partial<Parameters<typeof createObserver>[0]> = {}): Observer {
+    clicks = [];
+    observer = createObserver({
+        onClick: (keys, target) => clicks.push({ keys, target }),
+        ...options,
+    });
+    observer.run();
+    return observer;
+}
+
+/**
+ * What the runtime would have produced for this key.
+ *
+ * The namespace is a separate argument because that is how the runtime supplies it - it is
+ * where the string was resolved from, which is not something the caller's props know.
+ */
+function rendered(text: string, key: string, ns = ''): string {
+    return observer!.mark(text, { key } as never, ns);
+}
+
+beforeEach(() => {
+    document.body.innerHTML = '';
+    forgetInterned();
+});
+
+afterEach(() => {
+    observer?.stop();
+    observer = undefined;
+    document.body.innerHTML = '';
+});
+
+/**
+ * Two observers on one document take each other's marks: the first to scan a node strips
+ * them, so the second registers nothing and ALT+click quietly stops working. It cannot happen
+ * with one bootstrap; it happens constantly with a hot reload or a test that forgot to stop.
+ */
+describe('more than one at a time', () => {
+    it('says so rather than failing silently', () => {
+        const warnings: unknown[] = [];
+        const warn = jest.spyOn(console, 'warn').mockImplementation(message => warnings.push(message));
+        const first = createObserver({ onClick: () => undefined });
+        const second = createObserver({ onClick: () => undefined });
+        try {
+            first.run();
+            expect(warnings).toHaveLength(0);
+
+            second.run();
+            expect(String(warnings[0])).toContain('observers are running at once');
+        } finally {
+            first.stop();
+            second.stop();
+            warn.mockRestore();
+        }
+    });
+
+    it('counts down again, so a stopped one is not held against the next', () => {
+        const warnings: unknown[] = [];
+        const warn = jest.spyOn(console, 'warn').mockImplementation(message => warnings.push(message));
+        try {
+            const first = createObserver({ onClick: () => undefined });
+            first.run();
+            first.stop();
+
+            const second = createObserver({ onClick: () => undefined });
+            second.run();
+            second.stop();
+
+            expect(warnings).toHaveLength(0);
+        } finally {
+            warn.mockRestore();
+        }
+    });
+});
+
+describe('scanning', () => {
+    it('finds a key in text that was already on the page', async () => {
+        const o = createObserver({ onClick: () => undefined });
+        const span = document.createElement('span');
+        span.textContent = o.mark('Hello', { key: 'greeting' } as never, '');
+        document.body.appendChild(span);
+
+        o.run();
+        try {
+            expect(o.registeredCount()).toBe(1);
+            expect(o.findPositions('greeting')).toHaveLength(1);
+        } finally {
+            o.stop();
+        }
+    });
+
+    it('finds a key in text added afterwards', async () => {
+        const o = start();
+        const span = document.createElement('span');
+        span.textContent = rendered('Hello', 'greeting');
+        document.body.appendChild(span);
+
+        await settle();
+
+        expect(o.registeredCount()).toBe(1);
+    });
+
+    /**
+     * The marks must not stay in the DOM. They are copied by Ctrl+C, submitted inside form
+     * values, and compared against by code that cannot see them - and an invisible character
+     * causing `if (text === 'Save')` to fail is about as hard a bug as there is.
+     */
+    it('takes the marks back out of the node', async () => {
+        start();
+        const span = document.createElement('span');
+        span.textContent = rendered('Hello', 'greeting');
+        document.body.appendChild(span);
+
+        await settle();
+
+        expect(span.textContent).toBe('Hello');
+        expect(document.body.textContent).toBe('Hello');
+    });
+
+    it('reads a key out of an attribute', async () => {
+        const o = start();
+        const input = document.createElement('input');
+        input.setAttribute('placeholder', rendered('Your name', 'name_placeholder'));
+        document.body.appendChild(input);
+
+        await settle();
+
+        expect(input.getAttribute('placeholder')).toBe('Your name');
+        expect(o.findPositions('name_placeholder')).toHaveLength(1);
+    });
+
+    it('registers both keys when one element holds two', async () => {
+        const o = start();
+        const span = document.createElement('span');
+        span.append(document.createTextNode(rendered('Hello', 'greeting')), document.createTextNode(rendered('Ada', 'name')));
+        document.body.appendChild(span);
+
+        await settle();
+
+        expect(o.registeredCount()).toBe(1);
+        expect(o.findPositions('greeting')).toHaveLength(1);
+        expect(o.findPositions('name')).toHaveLength(1);
+        expect(o.findPositions()).toHaveLength(2);
+    });
+
+    it('leaves unmarked text alone', async () => {
+        const o = start();
+        document.body.innerHTML = '<span>Just text</span>';
+
+        await settle();
+
+        expect(o.registeredCount()).toBe(0);
+        expect(document.body.textContent).toBe('Just text');
+    });
+
+    it('does not walk into a subtree it was told to ignore', async () => {
+        const dialog = document.createElement('div');
+        dialog.id = 'the-dialog';
+        const o = start({ ignore: element => element.id === 'the-dialog' });
+
+        dialog.textContent = rendered('Hello', 'greeting');
+        document.body.appendChild(dialog);
+        await settle();
+
+        expect(o.registeredCount()).toBe(0);
+    });
+
+    it('ignores text inside a script tag', async () => {
+        const o = start();
+        const script = document.createElement('script');
+        // Not executable: jsdom runs a bare <script>, and the marked text is not JavaScript.
+        script.type = 'text/plain';
+        script.textContent = rendered('Hello', 'greeting');
+        document.body.appendChild(script);
+
+        await settle();
+
+        expect(o.registeredCount()).toBe(0);
+    });
+
+    /** Stripping writes the node, which is itself a mutation. It must not feed itself. */
+    it('settles rather than looping when it strips a node', async () => {
+        const o = start();
+        const span = document.createElement('span');
+        span.textContent = rendered('Hello', 'greeting');
+        document.body.appendChild(span);
+
+        await settle();
+        await settle();
+        await settle();
+
+        expect(span.textContent).toBe('Hello');
+        expect(o.registeredCount()).toBe(1);
+    });
+
+    it('picks up text that replaced other text', async () => {
+        const o = start();
+        const span = document.createElement('span');
+        span.textContent = rendered('Hello', 'greeting');
+        document.body.appendChild(span);
+        await settle();
+
+        span.textContent = rendered('Γεια', 'greeting');
+        await settle();
+
+        expect(span.textContent).toBe('Γεια');
+        expect(o.findPositions('greeting')).toHaveLength(1);
+    });
+});
+
+describe('forgetting', () => {
+    it('drops an element that left the page', async () => {
+        const o = start();
+        const span = document.createElement('span');
+        span.textContent = rendered('Hello', 'greeting');
+        document.body.appendChild(span);
+        await settle();
+        expect(o.registeredCount()).toBe(1);
+
+        span.remove();
+        await settle();
+
+        expect(o.registeredCount()).toBe(0);
+        expect(o.findPositions('greeting')).toHaveLength(0);
+    });
+
+    it('keeps an element that was only moved', async () => {
+        const o = start();
+        const holder = document.createElement('div');
+        const span = document.createElement('span');
+        span.textContent = rendered('Hello', 'greeting');
+        holder.appendChild(span);
+        document.body.appendChild(holder);
+        await settle();
+
+        const elsewhere = document.createElement('div');
+        document.body.appendChild(elsewhere);
+        elsewhere.appendChild(span);
+        await settle();
+
+        expect(o.registeredCount()).toBe(1);
+    });
+
+    it('forgets everything when stopped', async () => {
+        const o = start();
+        const span = document.createElement('span');
+        span.textContent = rendered('Hello', 'greeting');
+        document.body.appendChild(span);
+        await settle();
+
+        o.stop();
+
+        expect(o.registeredCount()).toBe(0);
+    });
+});
+
+describe('pointing', () => {
+    /** jsdom lays nothing out, so what is under the cursor has to be declared. */
+    function pointAt(element: Element | undefined): void {
+        document.elementsFromPoint = () => (element ? [element] : []);
+    }
+
+    function span(text: string, key: string): HTMLElement {
+        const el = document.createElement('span');
+        el.textContent = rendered(text, key);
+        document.body.appendChild(el);
+        return el;
+    }
+
+    async function armedOver(element: Element): Promise<void> {
+        pointAt(element);
+        document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Alt', altKey: true, bubbles: true }));
+        document.dispatchEvent(new MouseEvent('mousemove', { altKey: true, clientX: 5, clientY: 5, bubbles: true }));
+        await settle();
+    }
+
+    it('reports the keys when an armed click lands on marked text', async () => {
+        start();
+        const el = span('Hello', 'greeting');
+        await settle();
+        await armedOver(el);
+
+        el.dispatchEvent(new MouseEvent('click', { altKey: true, clientX: 5, clientY: 5, bubbles: true, cancelable: true }));
+
+        expect(clicks).toHaveLength(1);
+        expect(clicks[0]!.keys.map(k => k.key)).toEqual(['greeting']);
+        expect(clicks[0]!.target).toBe(el);
+    });
+
+    it('does nothing on a plain click', async () => {
+        start();
+        const el = span('Hello', 'greeting');
+        await settle();
+        pointAt(el);
+
+        el.dispatchEvent(new MouseEvent('click', { clientX: 5, clientY: 5, bubbles: true, cancelable: true }));
+
+        expect(clicks).toHaveLength(0);
+    });
+
+    /**
+     * The whole point of swallowing: ALT+clicking "Delete patient" must open the dialog and
+     * delete nothing. The application's own listener has to never see the event.
+     */
+    it('keeps an armed click away from the page’s own handler', async () => {
+        start();
+        const el = span('Delete patient', 'delete_patient');
+        await settle();
+        let handled = 0;
+        el.addEventListener('click', () => (handled += 1));
+        await armedOver(el);
+
+        const event = new MouseEvent('click', { altKey: true, clientX: 5, clientY: 5, bubbles: true, cancelable: true });
+        el.dispatchEvent(event);
+
+        expect(handled).toBe(0);
+        expect(event.defaultPrevented).toBe(true);
+        expect(clicks).toHaveLength(1);
+    });
+
+    it('lets a plain click through to the page', async () => {
+        start();
+        const el = span('Delete patient', 'delete_patient');
+        await settle();
+        let handled = 0;
+        el.addEventListener('click', () => (handled += 1));
+        pointAt(el);
+
+        el.dispatchEvent(new MouseEvent('click', { clientX: 5, clientY: 5, bubbles: true, cancelable: true }));
+
+        expect(handled).toBe(1);
+    });
+
+    it('does not swallow clicks inside a subtree it was told to ignore', async () => {
+        const dialog = document.createElement('div');
+        dialog.id = 'the-dialog';
+        const button = document.createElement('button');
+        dialog.appendChild(button);
+        document.body.appendChild(dialog);
+
+        start({ ignore: element => element.id === 'the-dialog' });
+        let handled = 0;
+        button.addEventListener('click', () => (handled += 1));
+
+        document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Alt', altKey: true, bubbles: true }));
+        button.dispatchEvent(new MouseEvent('click', { altKey: true, bubbles: true, cancelable: true }));
+
+        expect(handled).toBe(1);
+    });
+
+    it('ignores an armed click on unmarked text', async () => {
+        start();
+        const plain = document.createElement('span');
+        plain.textContent = 'Just text';
+        document.body.appendChild(plain);
+        await settle();
+        await armedOver(plain);
+
+        plain.dispatchEvent(new MouseEvent('click', { altKey: true, clientX: 5, clientY: 5, bubbles: true, cancelable: true }));
+
+        expect(clicks).toHaveLength(0);
+    });
+
+    it('finds the marked ancestor when the click lands on a child', async () => {
+        start();
+        const outer = document.createElement('div');
+        outer.textContent = rendered('Hello', 'greeting');
+        const inner = document.createElement('b');
+        outer.appendChild(inner);
+        document.body.appendChild(outer);
+        await settle();
+        await armedOver(inner);
+
+        inner.dispatchEvent(new MouseEvent('click', { altKey: true, clientX: 5, clientY: 5, bubbles: true, cancelable: true }));
+
+        expect(clicks).toHaveLength(1);
+        expect(clicks[0]!.target).toBe(outer);
+    });
+
+    /** A window that loses focus never sees the keyup, so the modifier would stay held. */
+    it('disarms when the window loses focus', async () => {
+        start();
+        const el = span('Hello', 'greeting');
+        await settle();
+        await armedOver(el);
+
+        window.dispatchEvent(new Event('blur'));
+        el.dispatchEvent(new MouseEvent('click', { altKey: true, clientX: 5, clientY: 5, bubbles: true, cancelable: true }));
+
+        // altKey on the event re-arms it before the check, which is correct: the modifier IS
+        // down. What blur must not do is leave a stale outline behind.
+        expect(document.querySelectorAll('.mg-observer-highlight')).toHaveLength(0);
+    });
+
+    it('stops listening when stopped', async () => {
+        const o = start();
+        const el = span('Hello', 'greeting');
+        await settle();
+        await armedOver(el);
+        o.stop();
+
+        el.dispatchEvent(new MouseEvent('click', { altKey: true, clientX: 5, clientY: 5, bubbles: true, cancelable: true }));
+
+        expect(clicks).toHaveLength(0);
+    });
+
+    it('outlines what is under the cursor while armed, and removes it after', async () => {
+        start();
+        const el = span('Hello', 'greeting');
+        await settle();
+
+        await armedOver(el);
+        expect(document.querySelectorAll('.mg-observer-highlight')).toHaveLength(1);
+
+        pointAt(undefined);
+        document.dispatchEvent(new KeyboardEvent('keyup', { key: 'Alt', altKey: false, bubbles: true }));
+        await settle();
+
+        expect(document.querySelectorAll('.mg-observer-highlight')).toHaveLength(0);
+    });
+});
+
+describe('positions and highlights', () => {
+    function laidOut(element: HTMLElement, box: { x: number; y: number; width: number; height: number }): void {
+        element.getBoundingClientRect = () => ({ ...box, top: box.y, left: box.x, right: box.x + box.width, bottom: box.y + box.height, toJSON: () => ({}) }) as DOMRect;
+    }
+
+    it('reports a box per place the key appears, in document order', async () => {
+        const o = start();
+        const first = document.createElement('span');
+        const second = document.createElement('span');
+        first.textContent = rendered('Hello', 'greeting');
+        second.textContent = rendered('Hello again', 'greeting');
+        document.body.append(first, second);
+        await settle();
+
+        laidOut(first, { x: 10, y: 20, width: 30, height: 40 });
+        laidOut(second, { x: 50, y: 60, width: 70, height: 80 });
+
+        const positions = o.findPositions('greeting');
+
+        expect(positions).toHaveLength(2);
+        expect(positions[0]!.position).toEqual({ x: 10, y: 20, width: 30, height: 40 });
+        expect(positions[1]!.position).toEqual({ x: 50, y: 60, width: 70, height: 80 });
+    });
+
+    it('reports the namespace it was marked with', async () => {
+        const o = start();
+        const el = document.createElement('span');
+        el.textContent = rendered('Sign in', 'title', 'login');
+        document.body.appendChild(el);
+        await settle();
+
+        expect(o.findPositions('title', 'login')).toHaveLength(1);
+        expect(o.findPositions('title', 'other')).toHaveLength(0);
+        expect(o.findPositions('title')[0]!.ns).toBe('login');
+    });
+
+    it('names no key when asked for none, which is how the gallery asks for everything', async () => {
+        const o = start();
+        const el = document.createElement('span');
+        el.append(document.createTextNode(rendered('a', 'first')), document.createTextNode(rendered('b', 'second')));
+        document.body.appendChild(el);
+        await settle();
+
+        expect(o.findPositions().map(p => p.key).sort()).toEqual(['first', 'second']);
+    });
+
+    it('outlines every place a key appears, and puts it back', async () => {
+        const o = start();
+        const first = document.createElement('span');
+        const second = document.createElement('span');
+        first.textContent = rendered('Hello', 'greeting');
+        second.textContent = rendered('Hello again', 'greeting');
+        document.body.append(first, second);
+        await settle();
+
+        const shown = o.highlight('greeting');
+        expect(document.querySelectorAll('.mg-observer-highlight')).toHaveLength(2);
+
+        shown.unhighlight();
+        expect(document.querySelectorAll('.mg-observer-highlight')).toHaveLength(0);
+    });
+
+    /**
+     * The outlines are fixed-position divs on the body, so a screenshot would capture them
+     * over the very text being photographed.
+     */
+    it('hides the outlines for a screenshot and restores them', async () => {
+        const o = start();
+        const el = document.createElement('span');
+        el.textContent = rendered('Hello', 'greeting');
+        document.body.appendChild(el);
+        await settle();
+        o.highlight('greeting');
+
+        const restore = o.hideOutlines();
+        expect([...document.querySelectorAll<HTMLElement>('.mg-observer-highlight')].every(box => box.style.visibility === 'hidden')).toBe(true);
+
+        restore();
+        expect([...document.querySelectorAll<HTMLElement>('.mg-observer-highlight')].every(box => box.style.visibility === '')).toBe(true);
+    });
+});