@sametalmdr/word-editor 0.2.0-alpha → 0.3.0-alpha

package/dist/selection/controller.js

@@ -1,315 +1,315 @@
-import { domToModel, modelToDom } from "./dom-map.js";
-import { positionsEqual } from "../model/position.js";
-
-/**
- * Bridges DOM selection and model selection in both directions.
- *
- * The DOM direction is filtered through four stages, in order (plan §3):
- *
- *   1. outside the editor entirely       → ignore
- *   2. it is an echo of our own write    → ignore
- *   3. an IME composition is in progress → ignore
- *   4. otherwise                         → **adopt**: translate both endpoints
- *      and hand the result to the caller, without ever calling the renderer.
- *
- * A DOM selection change is either something we caused or something the user
- * caused. Only the second kind should change anything — a click updates the
- * model's notion of where the cursor is, but it must not "apply" the way a
- * transaction does, because there is no document change to make. That
- * distinction is why `onAdopt` exists instead of just returning a value: it
- * marks the boundary past which `storedMarks` gets cleared (rule 2, decided by
- * `state/editor-state.js`'s `withSelection`) — a fired `onAdopt` means a real
- * cursor move, our own programmatic restores never reach it.
- *
- * @typedef {object} DomSelectionPoint
- * @property {import("./dom-map.js").MappableNode} node
- * @property {number} offset
- */
-
-/**
- * The minimal surface of `window.Selection` this module needs: four fields to
- * read the current selection, one method to set it. A fake satisfying this is
- * enough to test the whole class without a real DOM.
- * @typedef {object} DomSelectionLike
- * @property {import("./dom-map.js").MappableNode | null} anchorNode
- * @property {number} anchorOffset
- * @property {import("./dom-map.js").MappableNode | null} focusNode
- * @property {number} focusOffset
- * @property {(anchorNode: any, anchorOffset: number, focusNode: any, focusOffset: number) => void} setBaseAndExtent
- */
-
-/**
- * @param {DomSelectionLike} sel
- * @returns {DomSelectionPoint & { focusNode: any, focusOffset: number } | null}
- */
-function snapshot(sel) {
-  if (sel.anchorNode === null || sel.focusNode === null) {
-    return null;
-  }
-  return {
-    node: sel.anchorNode,
-    offset: sel.anchorOffset,
-    focusNode: sel.focusNode,
-    focusOffset: sel.focusOffset,
-  };
-}
-
-/**
- * @param {ReturnType<typeof snapshot>} a
- * @param {ReturnType<typeof snapshot>} b
- * @returns {boolean}
- */
-function snapshotsEqual(a, b) {
-  if (a === null || b === null) {
-    return false;
-  }
-  return (
-    a.node === b.node &&
-    a.offset === b.offset &&
-    a.focusNode === b.focusNode &&
-    a.focusOffset === b.focusOffset
-  );
-}
-
-/**
- * Walks `parentNode` rather than calling `.contains()`, so the same logic works
- * on the plain object trees the tests use and on real DOM nodes alike — the
- * same reasoning as `paragraphElementOf` in `dom-map.js`.
- * @param {import("./dom-map.js").MappableNode} root
- * @param {import("./dom-map.js").MappableNode | null} node
- * @returns {boolean}
- */
-function isInside(root, node) {
-  let current = node;
-  while (current !== null && current !== undefined) {
-    if (current === root) {
-      return true;
-    }
-    current = current.parentNode ?? null;
-  }
-  return false;
-}
-
-export class SelectionController {
-  /**
-   * @param {object} options
-   * @param {import("./dom-map.js").MappableNode} options.root
-   * @param {(id: import("../model/node.js").NodeId) => import("./dom-map.js").MappableNode | null} options.lookupParagraph
-   * @param {(selection: import("../model/position.js").Selection) => void} options.onAdopt
-   *   Called only for a real, user-driven selection change — never for our own
-   *   programmatic restores.
-   * @param {() => import("../canvas/mode-controller.js").Mode} [options.getMode]
-   *   Reads the current box/text mode (ADR-0024, P3b mode-merge). This turn it
-   *   is the READ connection only — no behaviour depends on it yet (the
-   *   click-router that routes a box-mode click away from the caret is parça 3).
-   *   Defaults to always-"text", which is exactly today's editor.html behaviour
-   *   (no mode controller -> the surface is only ever a text editor).
-   */
-  constructor({ root, lookupParagraph, onAdopt, getMode = () => "text" }) {
-    this.root = root;
-    this.lookupParagraph = lookupParagraph;
-    this.onAdopt = onAdopt;
-    this.getMode = getMode;
-
-    /** @type {import("../model/position.js").Selection | null} */
-    this.selection = null;
-    /** @type {ReturnType<typeof snapshot>} */
-    this.expectedDomSelection = null;
-    /** @type {boolean} */
-    this.isComposing = false;
-  }
-
-  /**
-   * The current box/text mode, read from the mode controller (ADR-0024). The
-   * READ connection only in P3b parça 1 — parça 3 is where this gates routing.
-   * @returns {import("../canvas/mode-controller.js").Mode}
-   */
-  get mode() {
-    return this.getMode();
-  }
-
-  /**
-   * @param {boolean} value
-   * @returns {void}
-   */
-  setComposing(value) {
-    this.isComposing = value;
-  }
-
-  /**
-   * Forgets everything about the previous document's selection — used when
-   * `loadDocument` swaps in an unrelated document on the SAME live instance
-   * (ADR-0027). Without this, `this.selection`/`expectedDomSelection` keep
-   * referencing the OLD document's node ids; `renderAndRestore`'s
-   * `restoreSelection` call is skipped whenever nothing is focused right
-   * after a fresh load (`readDomSelection()` returns null), so the stale
-   * value would otherwise survive silently — not crash-visible the way the
-   * renderer's id collision was, just wrong.
-   * @returns {void}
-   */
-  reset() {
-    this.selection = null;
-    this.expectedDomSelection = null;
-    this.isComposing = false;
-  }
-
-  /**
-   * Writes a model selection into the DOM and records it as ours, so the
-   * `selectionchange` it triggers is recognised and ignored rather than adopted.
-   *
-   * Skips the actual DOM write when the browser's selection already matches —
-   * cheap to check, and avoids a pointless `selectionchange`/scroll (plan §5).
-   * `this.selection` is still updated either way: as far as the controller is
-   * concerned, the model selection is now this value regardless of whether the
-   * DOM needed to catch up.
-   *
-   * The expectation flag is cleared on a microtask, not synchronously.
-   * `selectionchange` fires asynchronously in some browsers, so clearing it
-   * immediately after the synchronous `setBaseAndExtent` call risks the
-   * eventual event arriving after the flag is already gone and being
-   * misread as a user change. See ADR-0004 (input/IME strategy) for the
-   * browser-specific timing this works around.
-   *
-   * @param {import("../model/position.js").Selection} selection
-   * @param {DomSelectionLike} domSelection
-   * @returns {boolean} whether a DOM write actually happened
-   */
-  restoreSelection(selection, domSelection) {
-    this.selection = selection;
-
-    const anchor = modelToDom(selection.anchor, this.lookupParagraph);
-    const head = modelToDom(selection.head, this.lookupParagraph);
-    if (anchor === null || head === null) {
-      return false;
-    }
-
-    const target = {
-      node: anchor.node,
-      offset: anchor.offset,
-      focusNode: head.node,
-      focusOffset: head.offset,
-    };
-
-    if (snapshotsEqual(snapshot(domSelection), target)) {
-      return false;
-    }
-
-    this.expectedDomSelection = target;
-    domSelection.setBaseAndExtent(anchor.node, anchor.offset, head.node, head.offset);
-
-    queueMicrotask(() => {
-      this.expectedDomSelection = null;
-    });
-
-    return true;
-  }
-
-  /**
-   * The `selectionchange` handler's logic, decoupled from the real event so it
-   * can be driven directly in tests and by `attach()` alike.
-   * @param {DomSelectionLike} domSelection
-   * @returns {void}
-   */
-  handleSelectionChange(domSelection) {
-    const current = snapshot(domSelection);
-    if (current === null || !isInside(this.root, current.node)) {
-      return; // stage 1: outside the editor
-    }
-    if (this.isEcho(current)) {
-      return; // stage 2: an echo of our own write
-    }
-    if (this.isComposing) {
-      return; // stage 3: IME owns the DOM right now
-    }
-
-    // stage 4: adopt — a real, user-driven change.
-    const anchorPos = domToModel(current.node, current.offset);
-    const headPos = domToModel(current.focusNode, current.focusOffset);
-    if (anchorPos === null || headPos === null) {
-      return;
-    }
-
-    this.selection = { anchor: anchorPos, head: headPos };
-    this.onAdopt(this.selection);
-  }
-
-  /**
-   * Whether `current` is what we last asked the browser to set.
-   *
-   * The exact `{node, offset}` match is the common case and is checked first,
-   * with no `domToModel` calls at all. It is not the only case: `setBaseAndExtent`
-   * can come back normalized to a different but equivalent point — most likely
-   * when we target an empty paragraph's element container (offset 0, no text
-   * node to land on) and the browser reports the filler `<br>` instead of the
-   * `<p>`, or vice versa. Both describe the same character position, so without
-   * this fallback that echo would be misread as a real cursor move and clear
-   * `storedMarks` for no reason (rule 2 in `state/editor-state.js`).
-   *
-   * Only runs when there is something to compare against — the overwhelming
-   * majority of `selectionchange` events are genuine user moves with
-   * `expectedDomSelection` already `null`, and those never pay for a
-   * `domToModel` call here at all.
-   *
-   * ⚠ doğrulanmalı: exact normalization behaviour is browser-specific — see
-   * `docs/browser-matrix.md`.
-   *
-   * @param {Exclude<ReturnType<typeof snapshot>, null>} current
-   * @returns {boolean}
-   */
-  isEcho(current) {
-    const expected = this.expectedDomSelection;
-    if (expected === null) {
-      return false;
-    }
-    if (snapshotsEqual(current, expected)) {
-      return true;
-    }
-
-    const currentAnchor = domToModel(current.node, current.offset);
-    const currentHead = domToModel(current.focusNode, current.focusOffset);
-    const expectedAnchor = domToModel(expected.node, expected.offset);
-    const expectedHead = domToModel(expected.focusNode, expected.focusOffset);
-
-    if (
-      currentAnchor === null ||
-      currentHead === null ||
-      expectedAnchor === null ||
-      expectedHead === null
-    ) {
-      return false;
-    }
-
-    return positionsEqual(currentAnchor, expectedAnchor) && positionsEqual(currentHead, expectedHead);
-  }
-
-  /**
-   * Wires the real event. `document` — not the root element — because
-   * `selectionchange` only fires there (plan §3). Takes the target rather than
-   * reading a module-level global, so this stays SSR-safe and testable with a
-   * fake event target.
-   * @param {{ addEventListener: (type: string, listener: () => void) => void }} documentTarget
-   * @param {() => DomSelectionLike | null} getDomSelection
-   * @returns {void}
-   */
-  attach(documentTarget, getDomSelection) {
-    /** @type {() => void} */
-    this._listener = () => {
-      const sel = getDomSelection();
-      if (sel !== null) {
-        this.handleSelectionChange(sel);
-      }
-    };
-    documentTarget.addEventListener("selectionchange", this._listener);
-  }
-
-  /**
-   * @param {{ removeEventListener: (type: string, listener: () => void) => void }} documentTarget
-   * @returns {void}
-   */
-  detach(documentTarget) {
-    if (this._listener !== undefined) {
-      documentTarget.removeEventListener("selectionchange", this._listener);
-      this._listener = undefined;
-    }
-  }
-}
+import { domToModel, modelToDom } from "./dom-map.js";
+import { positionsEqual } from "../model/position.js";
+
+/**
+ * Bridges DOM selection and model selection in both directions.
+ *
+ * The DOM direction is filtered through four stages, in order (plan §3):
+ *
+ *   1. outside the editor entirely       → ignore
+ *   2. it is an echo of our own write    → ignore
+ *   3. an IME composition is in progress → ignore
+ *   4. otherwise                         → **adopt**: translate both endpoints
+ *      and hand the result to the caller, without ever calling the renderer.
+ *
+ * A DOM selection change is either something we caused or something the user
+ * caused. Only the second kind should change anything — a click updates the
+ * model's notion of where the cursor is, but it must not "apply" the way a
+ * transaction does, because there is no document change to make. That
+ * distinction is why `onAdopt` exists instead of just returning a value: it
+ * marks the boundary past which `storedMarks` gets cleared (rule 2, decided by
+ * `state/editor-state.js`'s `withSelection`) — a fired `onAdopt` means a real
+ * cursor move, our own programmatic restores never reach it.
+ *
+ * @typedef {object} DomSelectionPoint
+ * @property {import("./dom-map.js").MappableNode} node
+ * @property {number} offset
+ */
+
+/**
+ * The minimal surface of `window.Selection` this module needs: four fields to
+ * read the current selection, one method to set it. A fake satisfying this is
+ * enough to test the whole class without a real DOM.
+ * @typedef {object} DomSelectionLike
+ * @property {import("./dom-map.js").MappableNode | null} anchorNode
+ * @property {number} anchorOffset
+ * @property {import("./dom-map.js").MappableNode | null} focusNode
+ * @property {number} focusOffset
+ * @property {(anchorNode: any, anchorOffset: number, focusNode: any, focusOffset: number) => void} setBaseAndExtent
+ */
+
+/**
+ * @param {DomSelectionLike} sel
+ * @returns {DomSelectionPoint & { focusNode: any, focusOffset: number } | null}
+ */
+function snapshot(sel) {
+  if (sel.anchorNode === null || sel.focusNode === null) {
+    return null;
+  }
+  return {
+    node: sel.anchorNode,
+    offset: sel.anchorOffset,
+    focusNode: sel.focusNode,
+    focusOffset: sel.focusOffset,
+  };
+}
+
+/**
+ * @param {ReturnType<typeof snapshot>} a
+ * @param {ReturnType<typeof snapshot>} b
+ * @returns {boolean}
+ */
+function snapshotsEqual(a, b) {
+  if (a === null || b === null) {
+    return false;
+  }
+  return (
+    a.node === b.node &&
+    a.offset === b.offset &&
+    a.focusNode === b.focusNode &&
+    a.focusOffset === b.focusOffset
+  );
+}
+
+/**
+ * Walks `parentNode` rather than calling `.contains()`, so the same logic works
+ * on the plain object trees the tests use and on real DOM nodes alike — the
+ * same reasoning as `paragraphElementOf` in `dom-map.js`.
+ * @param {import("./dom-map.js").MappableNode} root
+ * @param {import("./dom-map.js").MappableNode | null} node
+ * @returns {boolean}
+ */
+function isInside(root, node) {
+  let current = node;
+  while (current !== null && current !== undefined) {
+    if (current === root) {
+      return true;
+    }
+    current = current.parentNode ?? null;
+  }
+  return false;
+}
+
+export class SelectionController {
+  /**
+   * @param {object} options
+   * @param {import("./dom-map.js").MappableNode} options.root
+   * @param {(id: import("../model/node.js").NodeId) => import("./dom-map.js").MappableNode | null} options.lookupParagraph
+   * @param {(selection: import("../model/position.js").Selection) => void} options.onAdopt
+   *   Called only for a real, user-driven selection change — never for our own
+   *   programmatic restores.
+   * @param {() => import("../canvas/mode-controller.js").Mode} [options.getMode]
+   *   Reads the current box/text mode (ADR-0024, P3b mode-merge). This turn it
+   *   is the READ connection only — no behaviour depends on it yet (the
+   *   click-router that routes a box-mode click away from the caret is parça 3).
+   *   Defaults to always-"text", which is exactly today's editor.html behaviour
+   *   (no mode controller -> the surface is only ever a text editor).
+   */
+  constructor({ root, lookupParagraph, onAdopt, getMode = () => "text" }) {
+    this.root = root;
+    this.lookupParagraph = lookupParagraph;
+    this.onAdopt = onAdopt;
+    this.getMode = getMode;
+
+    /** @type {import("../model/position.js").Selection | null} */
+    this.selection = null;
+    /** @type {ReturnType<typeof snapshot>} */
+    this.expectedDomSelection = null;
+    /** @type {boolean} */
+    this.isComposing = false;
+  }
+
+  /**
+   * The current box/text mode, read from the mode controller (ADR-0024). The
+   * READ connection only in P3b parça 1 — parça 3 is where this gates routing.
+   * @returns {import("../canvas/mode-controller.js").Mode}
+   */
+  get mode() {
+    return this.getMode();
+  }
+
+  /**
+   * @param {boolean} value
+   * @returns {void}
+   */
+  setComposing(value) {
+    this.isComposing = value;
+  }
+
+  /**
+   * Forgets everything about the previous document's selection — used when
+   * `loadDocument` swaps in an unrelated document on the SAME live instance
+   * (ADR-0027). Without this, `this.selection`/`expectedDomSelection` keep
+   * referencing the OLD document's node ids; `renderAndRestore`'s
+   * `restoreSelection` call is skipped whenever nothing is focused right
+   * after a fresh load (`readDomSelection()` returns null), so the stale
+   * value would otherwise survive silently — not crash-visible the way the
+   * renderer's id collision was, just wrong.
+   * @returns {void}
+   */
+  reset() {
+    this.selection = null;
+    this.expectedDomSelection = null;
+    this.isComposing = false;
+  }
+
+  /**
+   * Writes a model selection into the DOM and records it as ours, so the
+   * `selectionchange` it triggers is recognised and ignored rather than adopted.
+   *
+   * Skips the actual DOM write when the browser's selection already matches —
+   * cheap to check, and avoids a pointless `selectionchange`/scroll (plan §5).
+   * `this.selection` is still updated either way: as far as the controller is
+   * concerned, the model selection is now this value regardless of whether the
+   * DOM needed to catch up.
+   *
+   * The expectation flag is cleared on a microtask, not synchronously.
+   * `selectionchange` fires asynchronously in some browsers, so clearing it
+   * immediately after the synchronous `setBaseAndExtent` call risks the
+   * eventual event arriving after the flag is already gone and being
+   * misread as a user change. See ADR-0004 (input/IME strategy) for the
+   * browser-specific timing this works around.
+   *
+   * @param {import("../model/position.js").Selection} selection
+   * @param {DomSelectionLike} domSelection
+   * @returns {boolean} whether a DOM write actually happened
+   */
+  restoreSelection(selection, domSelection) {
+    this.selection = selection;
+
+    const anchor = modelToDom(selection.anchor, this.lookupParagraph);
+    const head = modelToDom(selection.head, this.lookupParagraph);
+    if (anchor === null || head === null) {
+      return false;
+    }
+
+    const target = {
+      node: anchor.node,
+      offset: anchor.offset,
+      focusNode: head.node,
+      focusOffset: head.offset,
+    };
+
+    if (snapshotsEqual(snapshot(domSelection), target)) {
+      return false;
+    }
+
+    this.expectedDomSelection = target;
+    domSelection.setBaseAndExtent(anchor.node, anchor.offset, head.node, head.offset);
+
+    queueMicrotask(() => {
+      this.expectedDomSelection = null;
+    });
+
+    return true;
+  }
+
+  /**
+   * The `selectionchange` handler's logic, decoupled from the real event so it
+   * can be driven directly in tests and by `attach()` alike.
+   * @param {DomSelectionLike} domSelection
+   * @returns {void}
+   */
+  handleSelectionChange(domSelection) {
+    const current = snapshot(domSelection);
+    if (current === null || !isInside(this.root, current.node)) {
+      return; // stage 1: outside the editor
+    }
+    if (this.isEcho(current)) {
+      return; // stage 2: an echo of our own write
+    }
+    if (this.isComposing) {
+      return; // stage 3: IME owns the DOM right now
+    }
+
+    // stage 4: adopt — a real, user-driven change.
+    const anchorPos = domToModel(current.node, current.offset);
+    const headPos = domToModel(current.focusNode, current.focusOffset);
+    if (anchorPos === null || headPos === null) {
+      return;
+    }
+
+    this.selection = { anchor: anchorPos, head: headPos };
+    this.onAdopt(this.selection);
+  }
+
+  /**
+   * Whether `current` is what we last asked the browser to set.
+   *
+   * The exact `{node, offset}` match is the common case and is checked first,
+   * with no `domToModel` calls at all. It is not the only case: `setBaseAndExtent`
+   * can come back normalized to a different but equivalent point — most likely
+   * when we target an empty paragraph's element container (offset 0, no text
+   * node to land on) and the browser reports the filler `<br>` instead of the
+   * `<p>`, or vice versa. Both describe the same character position, so without
+   * this fallback that echo would be misread as a real cursor move and clear
+   * `storedMarks` for no reason (rule 2 in `state/editor-state.js`).
+   *
+   * Only runs when there is something to compare against — the overwhelming
+   * majority of `selectionchange` events are genuine user moves with
+   * `expectedDomSelection` already `null`, and those never pay for a
+   * `domToModel` call here at all.
+   *
+   * ⚠ doğrulanmalı: exact normalization behaviour is browser-specific — see
+   * `docs/browser-matrix.md`.
+   *
+   * @param {Exclude<ReturnType<typeof snapshot>, null>} current
+   * @returns {boolean}
+   */
+  isEcho(current) {
+    const expected = this.expectedDomSelection;
+    if (expected === null) {
+      return false;
+    }
+    if (snapshotsEqual(current, expected)) {
+      return true;
+    }
+
+    const currentAnchor = domToModel(current.node, current.offset);
+    const currentHead = domToModel(current.focusNode, current.focusOffset);
+    const expectedAnchor = domToModel(expected.node, expected.offset);
+    const expectedHead = domToModel(expected.focusNode, expected.focusOffset);
+
+    if (
+      currentAnchor === null ||
+      currentHead === null ||
+      expectedAnchor === null ||
+      expectedHead === null
+    ) {
+      return false;
+    }
+
+    return positionsEqual(currentAnchor, expectedAnchor) && positionsEqual(currentHead, expectedHead);
+  }
+
+  /**
+   * Wires the real event. `document` — not the root element — because
+   * `selectionchange` only fires there (plan §3). Takes the target rather than
+   * reading a module-level global, so this stays SSR-safe and testable with a
+   * fake event target.
+   * @param {{ addEventListener: (type: string, listener: () => void) => void }} documentTarget
+   * @param {() => DomSelectionLike | null} getDomSelection
+   * @returns {void}
+   */
+  attach(documentTarget, getDomSelection) {
+    /** @type {() => void} */
+    this._listener = () => {
+      const sel = getDomSelection();
+      if (sel !== null) {
+        this.handleSelectionChange(sel);
+      }
+    };
+    documentTarget.addEventListener("selectionchange", this._listener);
+  }
+
+  /**
+   * @param {{ removeEventListener: (type: string, listener: () => void) => void }} documentTarget
+   * @returns {void}
+   */
+  detach(documentTarget) {
+    if (this._listener !== undefined) {
+      documentTarget.removeEventListener("selectionchange", this._listener);
+      this._listener = undefined;
+    }
+  }
+}