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

package/dist/selection/dom-map.js

@@ -1,334 +1,334 @@
-import { createPosition, paragraphIdOf } from "../model/position.js";
-
-/**
- * Two-way mapping between DOM selection endpoints and model positions.
- *
- * Everything here works on a **minimal node interface** — `nodeType`, `data`,
- * `childNodes`, `parentNode`, `dataset` — and never calls a DOM method. Real
- * elements satisfy it, and so do plain object trees, which is what the tests
- * use. It also keeps our DOM surface small enough to reason about.
- *
- * @typedef {object} MappableNode
- * @property {number} nodeType
- * @property {string} [data]  text content, for text nodes
- * @property {ArrayLike<MappableNode>} [childNodes]
- * @property {MappableNode | null} [parentNode]
- * @property {Record<string, string | undefined>} [dataset]
- */
-
-/**
- * A DOM selection endpoint: a container plus an offset that means "character
- * offset" in a text node and "index among children" in an element.
- * @typedef {object} DomPoint
- * @property {MappableNode} node
- * @property {number} offset
- */
-
-const TEXT_NODE = 3;
-
-/**
- * The dataset key carrying a paragraph's node id (`data-we-id` in markup).
- * The renderer writes it; this module is the only thing that reads it.
- */
-export const PARAGRAPH_ID_KEY = "weId";
-
-/**
- * The dataset key carrying a container's node id (`data-we-container-id`).
- * A model position needs both halves of its path, and the container half is not
- * derivable from the paragraph element alone.
- */
-export const CONTAINER_ID_KEY = "weContainerId";
-
-/**
- * @param {MappableNode} node
- * @returns {boolean}
- */
-function isText(node) {
-  return node.nodeType === TEXT_NODE;
-}
-
-/**
- * @param {MappableNode} node
- * @returns {string}
- */
-function textOf(node) {
-  return node.data ?? "";
-}
-
-/**
- * @param {MappableNode} node
- * @returns {ArrayLike<MappableNode>}
- */
-function childrenOf(node) {
-  return node.childNodes ?? [];
-}
-
-/**
- * The paragraph element a node lives in, found by walking up to the nearest
- * ancestor carrying a paragraph id.
- *
- * Walking `parentNode` rather than using `closest()` is deliberate: during
- * composition the browser inserts text nodes we never created, and this has to
- * work from those too.
- *
- * @param {MappableNode | null | undefined} node
- * @returns {MappableNode | null}
- */
-export function paragraphElementOf(node) {
-  let current = node ?? null;
-  while (current !== null && current !== undefined) {
-    if (current.dataset?.[PARAGRAPH_ID_KEY] !== undefined) {
-      return current;
-    }
-    current = current.parentNode ?? null;
-  }
-  return null;
-}
-
-/**
- * @param {MappableNode} paragraphElement
- * @returns {number | null}
- */
-export function paragraphIdOfElement(paragraphElement) {
-  const raw = paragraphElement.dataset?.[PARAGRAPH_ID_KEY];
-  if (raw === undefined) {
-    return null;
-  }
-  const id = Number(raw);
-  return Number.isFinite(id) ? id : null;
-}
-
-/**
- * The container element a node lives in — the box, in canvas terms. Same
- * upward walk as `paragraphElementOf`, and for the same reason: it has to work
- * from nodes the browser created during composition.
- * @param {MappableNode | null | undefined} node
- * @returns {MappableNode | null}
- */
-export function containerElementOf(node) {
-  let current = node ?? null;
-  while (current !== null && current !== undefined) {
-    if (current.dataset?.[CONTAINER_ID_KEY] !== undefined) {
-      return current;
-    }
-    current = current.parentNode ?? null;
-  }
-  return null;
-}
-
-/**
- * @param {MappableNode} containerElement
- * @returns {number | null}
- */
-export function containerIdOfElement(containerElement) {
-  const raw = containerElement.dataset?.[CONTAINER_ID_KEY];
-  if (raw === undefined) {
-    return null;
-  }
-  const id = Number(raw);
-  return Number.isFinite(id) ? id : null;
-}
-
-/**
- * Every text node under `node`, in document order.
- * @param {MappableNode} node
- * @returns {MappableNode[]}
- */
-export function textNodesOf(node) {
-  /** @type {MappableNode[]} */
-  const out = [];
-  /** @param {MappableNode} current */
-  function walk(current) {
-    if (isText(current)) {
-      out.push(current);
-      return;
-    }
-    const children = childrenOf(current);
-    for (let i = 0; i < children.length; i += 1) {
-      walk(children[i]);
-    }
-  }
-  walk(node);
-  return out;
-}
-
-/**
- * Total text length under a node.
- * @param {MappableNode} node
- * @returns {number}
- */
-function textLengthOf(node) {
-  if (isText(node)) {
-    return textOf(node).length;
-  }
-  let total = 0;
-  const children = childrenOf(node);
-  for (let i = 0; i < children.length; i += 1) {
-    total += textLengthOf(children[i]);
-  }
-  return total;
-}
-
-/**
- * Character offset of a DOM boundary point within `paragraphElement`.
- *
- * The walk accumulates *text length* in document order, which is why stray nodes
- * the browser inserted do not throw it off: the model's offsets are defined over
- * the same characters.
- *
- * @param {MappableNode} paragraphElement
- * @param {MappableNode} container
- * @param {number} containerOffset
- * @returns {number | null} null when `container` is not inside the paragraph
- */
-export function boundaryOffset(paragraphElement, container, containerOffset) {
-  let acc = 0;
-  let found = false;
-
-  /** @param {MappableNode} node */
-  function visit(node) {
-    if (found) {
-      return;
-    }
-
-    if (node === container) {
-      if (isText(node)) {
-        acc += clamp(containerOffset, 0, textOf(node).length);
-      } else {
-        // In an element the offset counts children, so everything in the first
-        // `containerOffset` of them lies before the boundary.
-        const children = childrenOf(node);
-        const upTo = clamp(containerOffset, 0, children.length);
-        for (let i = 0; i < upTo; i += 1) {
-          acc += textLengthOf(children[i]);
-        }
-      }
-      found = true;
-      return;
-    }
-
-    if (isText(node)) {
-      acc += textOf(node).length;
-      return;
-    }
-
-    const children = childrenOf(node);
-    for (let i = 0; i < children.length && !found; i += 1) {
-      visit(children[i]);
-    }
-  }
-
-  visit(paragraphElement);
-  return found ? acc : null;
-}
-
-/**
- * DOM selection endpoint to model position.
- * @param {MappableNode} node
- * @param {number} domOffset
- * @returns {import("../model/position.js").Position | null} null when the point
- *   is outside the editor
- */
-export function domToModel(node, domOffset) {
-  const paragraphElement = paragraphElementOf(node);
-  if (paragraphElement === null) {
-    return null;
-  }
-
-  const id = paragraphIdOfElement(paragraphElement);
-  if (id === null) {
-    return null;
-  }
-
-  // A paragraph outside any container is not addressable — the model has no
-  // one-level path any more, so refusing here is better than inventing an id.
-  const containerElement = containerElementOf(paragraphElement);
-  if (containerElement === null) {
-    return null;
-  }
-  const containerId = containerIdOfElement(containerElement);
-  if (containerId === null) {
-    return null;
-  }
-
-  const offset = boundaryOffset(paragraphElement, node, domOffset);
-  if (offset === null) {
-    return null;
-  }
-
-  return createPosition(containerId, id, offset);
-}
-
-/**
- * Model position to DOM selection endpoint.
- *
- * **Left-biased at a run seam**, matching `resolve()` in `model/position.js`: an
- * offset that is both the end of one text node and the start of the next
- * resolves to the end of the first. Both directions must agree on this or the
- * caret drifts by a character — `domToModel` accumulates the same way, so they
- * do.
- *
- * An empty paragraph has no text nodes at all (the renderer emits a filler
- * `<br>`), so the endpoint becomes the paragraph element itself at offset 0 —
- * which `domToModel` maps straight back to 0.
- *
- * @param {import("../model/position.js").Position} pos
- * @param {(id: import("../model/node.js").NodeId) => MappableNode | null} lookup
- * @returns {DomPoint | null}
- */
-export function modelToDom(pos, lookup) {
-  const paragraphElement = lookup(paragraphIdOf(pos));
-  if (paragraphElement === null || paragraphElement === undefined) {
-    return null;
-  }
-
-  let acc = 0;
-  for (const textNode of textNodesOf(paragraphElement)) {
-    const length = textOf(textNode).length;
-    if (pos.offset <= acc + length) {
-      return { node: textNode, offset: pos.offset - acc };
-    }
-    acc += length;
-  }
-
-  return { node: paragraphElement, offset: 0 };
-}
-
-/**
- * Looks paragraph elements up by scanning a root. The renderer keeps a map for
- * this; use the scan as a fallback, or in tests.
- * @param {MappableNode} root
- * @returns {(id: import("../model/node.js").NodeId) => MappableNode | null}
- */
-export function createParagraphLookup(root) {
-  return (id) => {
-    /** @type {MappableNode | null} */
-    let found = null;
-    /** @param {MappableNode} node */
-    function walk(node) {
-      if (found !== null) {
-        return;
-      }
-      if (paragraphIdOfElement(node) === id) {
-        found = node;
-        return;
-      }
-      const children = childrenOf(node);
-      for (let i = 0; i < children.length && found === null; i += 1) {
-        walk(children[i]);
-      }
-    }
-    walk(root);
-    return found;
-  };
-}
-
-/**
- * @param {number} value
- * @param {number} min
- * @param {number} max
- * @returns {number}
- */
-function clamp(value, min, max) {
-  return Math.max(min, Math.min(value, max));
-}
+import { createPosition, paragraphIdOf } from "../model/position.js";
+
+/**
+ * Two-way mapping between DOM selection endpoints and model positions.
+ *
+ * Everything here works on a **minimal node interface** — `nodeType`, `data`,
+ * `childNodes`, `parentNode`, `dataset` — and never calls a DOM method. Real
+ * elements satisfy it, and so do plain object trees, which is what the tests
+ * use. It also keeps our DOM surface small enough to reason about.
+ *
+ * @typedef {object} MappableNode
+ * @property {number} nodeType
+ * @property {string} [data]  text content, for text nodes
+ * @property {ArrayLike<MappableNode>} [childNodes]
+ * @property {MappableNode | null} [parentNode]
+ * @property {Record<string, string | undefined>} [dataset]
+ */
+
+/**
+ * A DOM selection endpoint: a container plus an offset that means "character
+ * offset" in a text node and "index among children" in an element.
+ * @typedef {object} DomPoint
+ * @property {MappableNode} node
+ * @property {number} offset
+ */
+
+const TEXT_NODE = 3;
+
+/**
+ * The dataset key carrying a paragraph's node id (`data-we-id` in markup).
+ * The renderer writes it; this module is the only thing that reads it.
+ */
+export const PARAGRAPH_ID_KEY = "weId";
+
+/**
+ * The dataset key carrying a container's node id (`data-we-container-id`).
+ * A model position needs both halves of its path, and the container half is not
+ * derivable from the paragraph element alone.
+ */
+export const CONTAINER_ID_KEY = "weContainerId";
+
+/**
+ * @param {MappableNode} node
+ * @returns {boolean}
+ */
+function isText(node) {
+  return node.nodeType === TEXT_NODE;
+}
+
+/**
+ * @param {MappableNode} node
+ * @returns {string}
+ */
+function textOf(node) {
+  return node.data ?? "";
+}
+
+/**
+ * @param {MappableNode} node
+ * @returns {ArrayLike<MappableNode>}
+ */
+function childrenOf(node) {
+  return node.childNodes ?? [];
+}
+
+/**
+ * The paragraph element a node lives in, found by walking up to the nearest
+ * ancestor carrying a paragraph id.
+ *
+ * Walking `parentNode` rather than using `closest()` is deliberate: during
+ * composition the browser inserts text nodes we never created, and this has to
+ * work from those too.
+ *
+ * @param {MappableNode | null | undefined} node
+ * @returns {MappableNode | null}
+ */
+export function paragraphElementOf(node) {
+  let current = node ?? null;
+  while (current !== null && current !== undefined) {
+    if (current.dataset?.[PARAGRAPH_ID_KEY] !== undefined) {
+      return current;
+    }
+    current = current.parentNode ?? null;
+  }
+  return null;
+}
+
+/**
+ * @param {MappableNode} paragraphElement
+ * @returns {number | null}
+ */
+export function paragraphIdOfElement(paragraphElement) {
+  const raw = paragraphElement.dataset?.[PARAGRAPH_ID_KEY];
+  if (raw === undefined) {
+    return null;
+  }
+  const id = Number(raw);
+  return Number.isFinite(id) ? id : null;
+}
+
+/**
+ * The container element a node lives in — the box, in canvas terms. Same
+ * upward walk as `paragraphElementOf`, and for the same reason: it has to work
+ * from nodes the browser created during composition.
+ * @param {MappableNode | null | undefined} node
+ * @returns {MappableNode | null}
+ */
+export function containerElementOf(node) {
+  let current = node ?? null;
+  while (current !== null && current !== undefined) {
+    if (current.dataset?.[CONTAINER_ID_KEY] !== undefined) {
+      return current;
+    }
+    current = current.parentNode ?? null;
+  }
+  return null;
+}
+
+/**
+ * @param {MappableNode} containerElement
+ * @returns {number | null}
+ */
+export function containerIdOfElement(containerElement) {
+  const raw = containerElement.dataset?.[CONTAINER_ID_KEY];
+  if (raw === undefined) {
+    return null;
+  }
+  const id = Number(raw);
+  return Number.isFinite(id) ? id : null;
+}
+
+/**
+ * Every text node under `node`, in document order.
+ * @param {MappableNode} node
+ * @returns {MappableNode[]}
+ */
+export function textNodesOf(node) {
+  /** @type {MappableNode[]} */
+  const out = [];
+  /** @param {MappableNode} current */
+  function walk(current) {
+    if (isText(current)) {
+      out.push(current);
+      return;
+    }
+    const children = childrenOf(current);
+    for (let i = 0; i < children.length; i += 1) {
+      walk(children[i]);
+    }
+  }
+  walk(node);
+  return out;
+}
+
+/**
+ * Total text length under a node.
+ * @param {MappableNode} node
+ * @returns {number}
+ */
+function textLengthOf(node) {
+  if (isText(node)) {
+    return textOf(node).length;
+  }
+  let total = 0;
+  const children = childrenOf(node);
+  for (let i = 0; i < children.length; i += 1) {
+    total += textLengthOf(children[i]);
+  }
+  return total;
+}
+
+/**
+ * Character offset of a DOM boundary point within `paragraphElement`.
+ *
+ * The walk accumulates *text length* in document order, which is why stray nodes
+ * the browser inserted do not throw it off: the model's offsets are defined over
+ * the same characters.
+ *
+ * @param {MappableNode} paragraphElement
+ * @param {MappableNode} container
+ * @param {number} containerOffset
+ * @returns {number | null} null when `container` is not inside the paragraph
+ */
+export function boundaryOffset(paragraphElement, container, containerOffset) {
+  let acc = 0;
+  let found = false;
+
+  /** @param {MappableNode} node */
+  function visit(node) {
+    if (found) {
+      return;
+    }
+
+    if (node === container) {
+      if (isText(node)) {
+        acc += clamp(containerOffset, 0, textOf(node).length);
+      } else {
+        // In an element the offset counts children, so everything in the first
+        // `containerOffset` of them lies before the boundary.
+        const children = childrenOf(node);
+        const upTo = clamp(containerOffset, 0, children.length);
+        for (let i = 0; i < upTo; i += 1) {
+          acc += textLengthOf(children[i]);
+        }
+      }
+      found = true;
+      return;
+    }
+
+    if (isText(node)) {
+      acc += textOf(node).length;
+      return;
+    }
+
+    const children = childrenOf(node);
+    for (let i = 0; i < children.length && !found; i += 1) {
+      visit(children[i]);
+    }
+  }
+
+  visit(paragraphElement);
+  return found ? acc : null;
+}
+
+/**
+ * DOM selection endpoint to model position.
+ * @param {MappableNode} node
+ * @param {number} domOffset
+ * @returns {import("../model/position.js").Position | null} null when the point
+ *   is outside the editor
+ */
+export function domToModel(node, domOffset) {
+  const paragraphElement = paragraphElementOf(node);
+  if (paragraphElement === null) {
+    return null;
+  }
+
+  const id = paragraphIdOfElement(paragraphElement);
+  if (id === null) {
+    return null;
+  }
+
+  // A paragraph outside any container is not addressable — the model has no
+  // one-level path any more, so refusing here is better than inventing an id.
+  const containerElement = containerElementOf(paragraphElement);
+  if (containerElement === null) {
+    return null;
+  }
+  const containerId = containerIdOfElement(containerElement);
+  if (containerId === null) {
+    return null;
+  }
+
+  const offset = boundaryOffset(paragraphElement, node, domOffset);
+  if (offset === null) {
+    return null;
+  }
+
+  return createPosition(containerId, id, offset);
+}
+
+/**
+ * Model position to DOM selection endpoint.
+ *
+ * **Left-biased at a run seam**, matching `resolve()` in `model/position.js`: an
+ * offset that is both the end of one text node and the start of the next
+ * resolves to the end of the first. Both directions must agree on this or the
+ * caret drifts by a character — `domToModel` accumulates the same way, so they
+ * do.
+ *
+ * An empty paragraph has no text nodes at all (the renderer emits a filler
+ * `<br>`), so the endpoint becomes the paragraph element itself at offset 0 —
+ * which `domToModel` maps straight back to 0.
+ *
+ * @param {import("../model/position.js").Position} pos
+ * @param {(id: import("../model/node.js").NodeId) => MappableNode | null} lookup
+ * @returns {DomPoint | null}
+ */
+export function modelToDom(pos, lookup) {
+  const paragraphElement = lookup(paragraphIdOf(pos));
+  if (paragraphElement === null || paragraphElement === undefined) {
+    return null;
+  }
+
+  let acc = 0;
+  for (const textNode of textNodesOf(paragraphElement)) {
+    const length = textOf(textNode).length;
+    if (pos.offset <= acc + length) {
+      return { node: textNode, offset: pos.offset - acc };
+    }
+    acc += length;
+  }
+
+  return { node: paragraphElement, offset: 0 };
+}
+
+/**
+ * Looks paragraph elements up by scanning a root. The renderer keeps a map for
+ * this; use the scan as a fallback, or in tests.
+ * @param {MappableNode} root
+ * @returns {(id: import("../model/node.js").NodeId) => MappableNode | null}
+ */
+export function createParagraphLookup(root) {
+  return (id) => {
+    /** @type {MappableNode | null} */
+    let found = null;
+    /** @param {MappableNode} node */
+    function walk(node) {
+      if (found !== null) {
+        return;
+      }
+      if (paragraphIdOfElement(node) === id) {
+        found = node;
+        return;
+      }
+      const children = childrenOf(node);
+      for (let i = 0; i < children.length && found === null; i += 1) {
+        walk(children[i]);
+      }
+    }
+    walk(root);
+    return found;
+  };
+}
+
+/**
+ * @param {number} value
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(value, max));
+}