@worthy-ventures/metaglotta-observer 1.0.0

package/dist/index.d.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/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.forgetInterned = exports.readMarks = exports.isMarked = exports.unmark = exports.mark = exports.createObserver = void 0;
+var observer_js_1 = require("./observer.js");
+Object.defineProperty(exports, "createObserver", { enumerable: true, get: function () { return observer_js_1.createObserver; } });
+var marks_js_1 = require("./marks.js");
+Object.defineProperty(exports, "mark", { enumerable: true, get: function () { return marks_js_1.mark; } });
+Object.defineProperty(exports, "unmark", { enumerable: true, get: function () { return marks_js_1.unmark; } });
+Object.defineProperty(exports, "isMarked", { enumerable: true, get: function () { return marks_js_1.isMarked; } });
+Object.defineProperty(exports, "readMarks", { enumerable: true, get: function () { return marks_js_1.readMarks; } });
+Object.defineProperty(exports, "forgetInterned", { enumerable: true, get: function () { return marks_js_1.forgetInterned; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6CAA+C;AAAtC,6GAAA,cAAc,OAAA;AAEvB,uCAA+E;AAAtE,gGAAA,IAAI,OAAA;AAAE,kGAAA,MAAM,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAAE,qGAAA,SAAS,OAAA;AAAE,0GAAA,cAAc,OAAA"}

package/dist/marks.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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).
+ */
+export type MarkedKey = {
+    key: string;
+    ns?: string;
+    defaultValue?: string;
+};
+/** What a marked string carries: an index into the table, or several. */
+export declare function mark(text: string, key: MarkedKey): string;
+/** Whether a string is worth decoding, cheaply enough to run on every text node. */
+export declare function isMarked(text: string): boolean;
+/** The text as a person sees it, with the marks taken out. */
+export declare function unmark(text: string): string;
+/**
+ * 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 declare function readMarks(text: string): {
+    text: string;
+    keys: MarkedKey[];
+};
+/** Test seam: the table is a module global by design, and lives as long as the page. */
+export declare function forgetInterned(): void;

package/dist/marks.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mark = mark;
+exports.isMarked = isMarked;
+exports.unmark = unmark;
+exports.readMarks = readMarks;
+exports.forgetInterned = forgetInterned;
+/** 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 = [];
+function intern(value) {
+    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) {
+    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) {
+    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;
+}
+/** What a marked string carries: an index into the table, or several. */
+function mark(text, key) {
+    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. */
+function isMarked(text) {
+    return text.includes(ZERO) || text.includes(ONE);
+}
+/** The text as a person sees it, with the marks taken out. */
+function unmark(text) {
+    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.
+ */
+function readMarks(text) {
+    const keys = [];
+    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]);
+                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. */
+function forgetInterned() {
+    interned.length = 0;
+}
+//# sourceMappingURL=marks.js.map

package/dist/marks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"marks.js","sourceRoot":"","sources":["../src/marks.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;AAwDH,oBAEC;AAGD,4BAEC;AAGD,wBAEC;AASD,8BAoBC;AAGD,wCAEC;AApGD,6DAA6D;AAC7D,MAAM,IAAI,GAAG,GAAG,CAAC;AACjB,MAAM,GAAG,GAAG,GAAG,CAAC;AAEhB,iFAAiF;AACjF,MAAM,SAAS,GAAG,IAAI,CAAC;AAEvB,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC,OAAO,IAAI,GAAG,GAAG,KAAK,aAAa,KAAK,EAAE,GAAG,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,QAAQ,GAAa,EAAE,CAAC;AAE9B,SAAS,MAAM,CAAC,KAAa;IACzB,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACzC,IAAI,QAAQ,KAAK,CAAC,CAAC;QAAE,OAAO,QAAQ,CAAC;IACrC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,UAAU,CAAC,IAAY;IAC5B,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC;QACzC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC;IAC5E,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC7B,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,aAAa,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,IAAI,aAAa,EAAE,CAAC;QACvE,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,SAAS,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrG,IAAI,IAAI,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAID,yEAAyE;AACzE,SAAgB,IAAI,CAAC,IAAY,EAAE,GAAc;IAC7C,OAAO,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AAC1H,CAAC;AAED,oFAAoF;AACpF,SAAgB,QAAQ,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACrD,CAAC;AAED,8DAA8D;AAC9D,SAAgB,MAAM,CAAC,IAAY;IAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,IAAY;IAClC,MAAM,IAAI,GAAgB,EAAE,CAAC;IAE7B,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;QACtC,KAAK,MAAM,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;YACrD,IAAI,CAAC,OAAO;gBAAE,SAAS;YACvB,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;YAC9B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,IAAI,QAAQ,CAAC,MAAM;gBAAE,SAAS;YAEhF,IAAI,CAAC;gBACD,MAAM,CAAC,GAAG,EAAE,EAAE,EAAE,YAAY,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAE,CAA6B,CAAC;gBACzF,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,SAAS,EAAE,YAAY,EAAE,YAAY,IAAI,SAAS,EAAE,CAAC,CAAC;YACrF,CAAC;YAAC,MAAM,CAAC;gBACL,2EAA2E;gBAC3E,2DAA2D;YAC/D,CAAC;QACL,CAAC;IACL,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC;AAED,wFAAwF;AACxF,SAAgB,cAAc;IAC1B,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AACxB,CAAC"}

package/dist/observer.d.ts

@@ -0,0 +1,77 @@
+import type { TranslateProps } from '@worthy-ventures/metaglotta-runtime';
+import { 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;
+};
+export declare function createObserver(options: ObserverOptions): {
+    /**
+     * 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;
+    run(): void;
+    stop(): void;
+    /**
+     * 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[];
+    /** Outlines every place a key appears. Returns how to put it back. */
+    highlight(key?: string, ns?: string): {
+        unhighlight: () => void;
+    };
+    /**
+     * 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;
+    /** Test seam. */
+    registeredCount: () => number;
+};
+export type Observer = ReturnType<typeof createObserver>;