@worthy-ventures/metaglotta-observer

Traces rendered text back to the key that produced it, so ALT+clicking a string on the page can open the right translation.

Authoring only. Nothing in a production build should import this — it reaches it through @worthy-ventures/metaglotta-ngx, which loads the editor on demand, so a page nobody is editing never downloads any of it.

import { createObserver } from '@worthy-ventures/metaglotta-observer';

const observer = createObserver({
  onClick: (keys, target) => open(keys, target),
  keys: ['Alt'],
});

Three jobs, deliberately separate

1. Mark — every string the runtime produces gets its key appended in invisible characters. This is the runtime's decorate hook, and it is the only place the observer touches the runtime at all.
2. Scan — as marked text arrives in the DOM, read the keys out and take the marks back out of the node, so nothing can copy them into a clipboard. Remember which element they belonged 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.

Keeping them separate is what lets the marks disappear from the DOM before anyone can select them, while the key is still known for the element.

Options

| | | |---|---| | onClick | What to do with an armed click. Receives the keys and the element they were found on. | | keys | Modifiers held to arm it — all of them, if more than one. Default ['Alt']. | | attributes | Attributes whose value may be a translation (a title, a placeholder). | | root | Where to watch. Default: the whole document. | | ignore | A subtree to leave alone entirely — the editing dialog's own, for one. | | highlightColor, highlightWidth | The outline drawn while armed. |

ignore matters more than it looks: without it the observer marks the editor's own UI, and ALT+clicking inside the dialog re-opens the dialog on its own labels.

Marks

mark, unmark, isMarked, readMarks and forgetInterned are exported for the rare caller that needs to handle marked text itself. The marks are zero-width characters, so a marked string measures and renders identically to an unmarked one — but it is not equal to it, which is why anything comparing translated strings must read the marks off first.