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

package/dist/model/position.js

@@ -1,283 +1,283 @@
-import { locateParagraph, paragraphLength } from "./node.js";
-
-/**
- * A place between two characters. `offset` indexes into the paragraph's
- * concatenated text — *not* a run index plus an intra-run offset. That choice is
- * what makes positions survive `normalize()` untouched: merging or dropping runs
- * never moves a character, so it never moves an offset. See ADR-0002.
- *
- * `path` is `[containerId, paragraphId]` since the container refactor
- * (ADR-0007). It was `[paragraphId]` in P1, and ADR-0002 kept it an array
- * precisely so this could grow — `paragraphIdOf` reads the *last* element and
- * did not have to change.
- *
- * @typedef {object} Position
- * @property {import("./node.js").NodeId[]} path
- * @property {number} offset
- */
-
-/**
- * `anchor` is where the selection started, `head` where it is now — direction
- * matters for shift+arrow, so this is not a from/to pair.
- * @typedef {object} Selection
- * @property {Position} anchor
- * @property {Position} head
- */
-
-/**
- * Where a position lands inside a paragraph's runs.
- *
- * Run boundaries are **left-biased**: at the seam between run `i` and run `i+1`
- * the position resolves to the end of run `i`, so `offsetInRun` may equal the
- * run's length. This matches the left-biased mark inheritance in
- * `commands/marks.js` — typing right after bold text continues bold.
- *
- * @typedef {object} ResolvedPosition
- * @property {number} containerIndex
- * @property {import("./node.js").Container} container
- * @property {number} paraIndex
- * @property {import("./node.js").Paragraph} para
- * @property {number} runIndex
- * @property {number} offsetInRun
- */
-
-/**
- * @param {import("./node.js").NodeId} containerId
- * @param {import("./node.js").NodeId} paragraphId
- * @param {number} offset
- * @returns {Position}
- */
-export function createPosition(containerId, paragraphId, offset) {
-  return { path: [containerId, paragraphId], offset };
-}
-
-/**
- * Same place, different offset. Preferred over rebuilding with
- * `createPosition` when a step moves a position *within* its own paragraph:
- * it carries the whole path forward, so it cannot silently drop the container.
- * @param {Position} pos
- * @param {number} offset
- * @returns {Position}
- */
-export function withOffset(pos, offset) {
-  return { path: pos.path.slice(), offset };
-}
-
-/**
- * The paragraph a position lives in. Reads the **last** path element, so it is
- * independent of how deep the path is — unchanged from P1 across the container
- * refactor (ADR-0007).
- * @param {Position} pos
- * @returns {import("./node.js").NodeId}
- */
-export function paragraphIdOf(pos) {
-  return pos.path[pos.path.length - 1];
-}
-
-/**
- * The container a position lives in.
- * @param {Position} pos
- * @returns {import("./node.js").NodeId}
- */
-export function containerIdOf(pos) {
-  return pos.path[0];
-}
-
-/**
- * @param {Position} a
- * @param {Position} b
- * @returns {boolean}
- */
-export function positionsEqual(a, b) {
-  return (
-    a.offset === b.offset &&
-    a.path.length === b.path.length &&
-    a.path.every((id, i) => id === b.path[i])
-  );
-}
-
-/**
- * @param {Position} a
- * @param {Position} b
- * @returns {boolean}
- */
-export function samePara(a, b) {
-  return paragraphIdOf(a) === paragraphIdOf(b);
-}
-
-/**
- * @param {Position} a
- * @param {Position} b
- * @returns {boolean}
- */
-export function sameContainer(a, b) {
-  return containerIdOf(a) === containerIdOf(b);
-}
-
-/**
- * Drills a position down to a run. Returns null when the paragraph is gone —
- * callers must decide whether that is a bug or a stale position.
- * @param {import("./node.js").Doc} doc
- * @param {Position} pos
- * @returns {ResolvedPosition | null}
- */
-export function resolve(doc, pos) {
-  const found = locateParagraph(doc, paragraphIdOf(pos));
-  if (found === null) {
-    return null;
-  }
-  const { containerIndex, container, paraIndex, para } = found;
-
-  let acc = 0;
-  for (let runIndex = 0; runIndex < para.content.length; runIndex += 1) {
-    const end = acc + para.content[runIndex].text.length;
-    // `<=` rather than `<` is the left bias: a position at a seam belongs to the
-    // run that ends there.
-    if (pos.offset <= end) {
-      return { containerIndex, container, paraIndex, para, runIndex, offsetInRun: pos.offset - acc };
-    }
-    acc = end;
-  }
-
-  const lastIndex = para.content.length - 1;
-  return {
-    containerIndex,
-    container,
-    paraIndex,
-    para,
-    runIndex: lastIndex,
-    offsetInRun: para.content[lastIndex].text.length,
-  };
-}
-
-/**
- * Document order: container index first, then paragraph index within it, then
- * offset. Returns null when either paragraph is missing.
- *
- * Note this orders *across* containers even though a text selection may not span
- * them (see `isSingleContainer`) — comparison is also used for things like
- * ordering two independent anchors, where cross-container order is meaningful.
- *
- * @param {import("./node.js").Doc} doc
- * @param {Position} a
- * @param {Position} b
- * @returns {-1 | 0 | 1 | null}
- */
-export function comparePositions(doc, a, b) {
-  const aId = paragraphIdOf(a);
-  const bId = paragraphIdOf(b);
-
-  if (aId === bId) {
-    if (a.offset === b.offset) {
-      return 0;
-    }
-    return a.offset < b.offset ? -1 : 1;
-  }
-
-  const aAt = locateParagraph(doc, aId);
-  const bAt = locateParagraph(doc, bId);
-  if (aAt === null || bAt === null) {
-    return null;
-  }
-  if (aAt.containerIndex !== bAt.containerIndex) {
-    return aAt.containerIndex < bAt.containerIndex ? -1 : 1;
-  }
-  return aAt.paraIndex < bAt.paraIndex ? -1 : 1;
-}
-
-/**
- * Clamps `offset` into the paragraph. Returns null when the paragraph is gone.
- * @param {import("./node.js").Doc} doc
- * @param {Position} pos
- * @returns {Position | null}
- */
-export function clampPosition(doc, pos) {
-  const found = locateParagraph(doc, paragraphIdOf(pos));
-  if (found === null) {
-    return null;
-  }
-  const max = paragraphLength(found.para);
-  if (pos.offset >= 0 && pos.offset <= max) {
-    return pos;
-  }
-  return { path: pos.path.slice(), offset: Math.max(0, Math.min(pos.offset, max)) };
-}
-
-/**
- * @param {Position} anchor
- * @param {Position} head
- * @returns {Selection}
- */
-export function createSelection(anchor, head) {
-  return { anchor, head };
-}
-
-/**
- * @param {Position} pos
- * @returns {Selection}
- */
-export function collapsedSelection(pos) {
-  return { anchor: pos, head: pos };
-}
-
-/**
- * @param {Selection} sel
- * @returns {boolean}
- */
-export function isCollapsed(sel) {
-  return positionsEqual(sel.anchor, sel.head);
-}
-
-/**
- * @param {Selection} a
- * @param {Selection} b
- * @returns {boolean}
- */
-export function selectionsEqual(a, b) {
-  return positionsEqual(a.anchor, b.anchor) && positionsEqual(a.head, b.head);
-}
-
-/**
- * The selection as an ordered range. Returns null when either endpoint's
- * paragraph is missing.
- * @param {import("./node.js").Doc} doc
- * @param {Selection} sel
- * @returns {{ from: Position, to: Position } | null}
- */
-export function selectionRange(doc, sel) {
-  const order = comparePositions(doc, sel.anchor, sel.head);
-  if (order === null) {
-    return null;
-  }
-  return order <= 0
-    ? { from: sel.anchor, to: sel.head }
-    : { from: sel.head, to: sel.anchor };
-}
-
-/**
- * True when both endpoints sit in the same paragraph. Drives the `DeleteStep`
- * single-paragraph rule.
- *
- * Also drives `input/composition.js`'s rejection of multi-paragraph
- * composing ranges (P1.9a, ADR-0004 §2).
- * @param {Selection} sel
- * @returns {boolean}
- */
-export function isSingleParagraph(sel) {
-  return samePara(sel.anchor, sel.head);
-}
-
-/**
- * True when both endpoints sit in the same container.
- *
- * ADR-0007 makes this an **invariant** for text selections, not merely a
- * question: a text selection may not span two boxes. On a canvas the boxes have
- * no meaningful document order between them, so "select from box A into box B"
- * has no sensible meaning; selecting whole boxes is a `BoxSelection` instead.
- * Commands assert this rather than trying to handle the cross-container case.
- * @param {Selection} sel
- * @returns {boolean}
- */
-export function isSingleContainer(sel) {
-  return sameContainer(sel.anchor, sel.head);
-}
+import { locateParagraph, paragraphLength } from "./node.js";
+
+/**
+ * A place between two characters. `offset` indexes into the paragraph's
+ * concatenated text — *not* a run index plus an intra-run offset. That choice is
+ * what makes positions survive `normalize()` untouched: merging or dropping runs
+ * never moves a character, so it never moves an offset. See ADR-0002.
+ *
+ * `path` is `[containerId, paragraphId]` since the container refactor
+ * (ADR-0007). It was `[paragraphId]` in P1, and ADR-0002 kept it an array
+ * precisely so this could grow — `paragraphIdOf` reads the *last* element and
+ * did not have to change.
+ *
+ * @typedef {object} Position
+ * @property {import("./node.js").NodeId[]} path
+ * @property {number} offset
+ */
+
+/**
+ * `anchor` is where the selection started, `head` where it is now — direction
+ * matters for shift+arrow, so this is not a from/to pair.
+ * @typedef {object} Selection
+ * @property {Position} anchor
+ * @property {Position} head
+ */
+
+/**
+ * Where a position lands inside a paragraph's runs.
+ *
+ * Run boundaries are **left-biased**: at the seam between run `i` and run `i+1`
+ * the position resolves to the end of run `i`, so `offsetInRun` may equal the
+ * run's length. This matches the left-biased mark inheritance in
+ * `commands/marks.js` — typing right after bold text continues bold.
+ *
+ * @typedef {object} ResolvedPosition
+ * @property {number} containerIndex
+ * @property {import("./node.js").Container} container
+ * @property {number} paraIndex
+ * @property {import("./node.js").Paragraph} para
+ * @property {number} runIndex
+ * @property {number} offsetInRun
+ */
+
+/**
+ * @param {import("./node.js").NodeId} containerId
+ * @param {import("./node.js").NodeId} paragraphId
+ * @param {number} offset
+ * @returns {Position}
+ */
+export function createPosition(containerId, paragraphId, offset) {
+  return { path: [containerId, paragraphId], offset };
+}
+
+/**
+ * Same place, different offset. Preferred over rebuilding with
+ * `createPosition` when a step moves a position *within* its own paragraph:
+ * it carries the whole path forward, so it cannot silently drop the container.
+ * @param {Position} pos
+ * @param {number} offset
+ * @returns {Position}
+ */
+export function withOffset(pos, offset) {
+  return { path: pos.path.slice(), offset };
+}
+
+/**
+ * The paragraph a position lives in. Reads the **last** path element, so it is
+ * independent of how deep the path is — unchanged from P1 across the container
+ * refactor (ADR-0007).
+ * @param {Position} pos
+ * @returns {import("./node.js").NodeId}
+ */
+export function paragraphIdOf(pos) {
+  return pos.path[pos.path.length - 1];
+}
+
+/**
+ * The container a position lives in.
+ * @param {Position} pos
+ * @returns {import("./node.js").NodeId}
+ */
+export function containerIdOf(pos) {
+  return pos.path[0];
+}
+
+/**
+ * @param {Position} a
+ * @param {Position} b
+ * @returns {boolean}
+ */
+export function positionsEqual(a, b) {
+  return (
+    a.offset === b.offset &&
+    a.path.length === b.path.length &&
+    a.path.every((id, i) => id === b.path[i])
+  );
+}
+
+/**
+ * @param {Position} a
+ * @param {Position} b
+ * @returns {boolean}
+ */
+export function samePara(a, b) {
+  return paragraphIdOf(a) === paragraphIdOf(b);
+}
+
+/**
+ * @param {Position} a
+ * @param {Position} b
+ * @returns {boolean}
+ */
+export function sameContainer(a, b) {
+  return containerIdOf(a) === containerIdOf(b);
+}
+
+/**
+ * Drills a position down to a run. Returns null when the paragraph is gone —
+ * callers must decide whether that is a bug or a stale position.
+ * @param {import("./node.js").Doc} doc
+ * @param {Position} pos
+ * @returns {ResolvedPosition | null}
+ */
+export function resolve(doc, pos) {
+  const found = locateParagraph(doc, paragraphIdOf(pos));
+  if (found === null) {
+    return null;
+  }
+  const { containerIndex, container, paraIndex, para } = found;
+
+  let acc = 0;
+  for (let runIndex = 0; runIndex < para.content.length; runIndex += 1) {
+    const end = acc + para.content[runIndex].text.length;
+    // `<=` rather than `<` is the left bias: a position at a seam belongs to the
+    // run that ends there.
+    if (pos.offset <= end) {
+      return { containerIndex, container, paraIndex, para, runIndex, offsetInRun: pos.offset - acc };
+    }
+    acc = end;
+  }
+
+  const lastIndex = para.content.length - 1;
+  return {
+    containerIndex,
+    container,
+    paraIndex,
+    para,
+    runIndex: lastIndex,
+    offsetInRun: para.content[lastIndex].text.length,
+  };
+}
+
+/**
+ * Document order: container index first, then paragraph index within it, then
+ * offset. Returns null when either paragraph is missing.
+ *
+ * Note this orders *across* containers even though a text selection may not span
+ * them (see `isSingleContainer`) — comparison is also used for things like
+ * ordering two independent anchors, where cross-container order is meaningful.
+ *
+ * @param {import("./node.js").Doc} doc
+ * @param {Position} a
+ * @param {Position} b
+ * @returns {-1 | 0 | 1 | null}
+ */
+export function comparePositions(doc, a, b) {
+  const aId = paragraphIdOf(a);
+  const bId = paragraphIdOf(b);
+
+  if (aId === bId) {
+    if (a.offset === b.offset) {
+      return 0;
+    }
+    return a.offset < b.offset ? -1 : 1;
+  }
+
+  const aAt = locateParagraph(doc, aId);
+  const bAt = locateParagraph(doc, bId);
+  if (aAt === null || bAt === null) {
+    return null;
+  }
+  if (aAt.containerIndex !== bAt.containerIndex) {
+    return aAt.containerIndex < bAt.containerIndex ? -1 : 1;
+  }
+  return aAt.paraIndex < bAt.paraIndex ? -1 : 1;
+}
+
+/**
+ * Clamps `offset` into the paragraph. Returns null when the paragraph is gone.
+ * @param {import("./node.js").Doc} doc
+ * @param {Position} pos
+ * @returns {Position | null}
+ */
+export function clampPosition(doc, pos) {
+  const found = locateParagraph(doc, paragraphIdOf(pos));
+  if (found === null) {
+    return null;
+  }
+  const max = paragraphLength(found.para);
+  if (pos.offset >= 0 && pos.offset <= max) {
+    return pos;
+  }
+  return { path: pos.path.slice(), offset: Math.max(0, Math.min(pos.offset, max)) };
+}
+
+/**
+ * @param {Position} anchor
+ * @param {Position} head
+ * @returns {Selection}
+ */
+export function createSelection(anchor, head) {
+  return { anchor, head };
+}
+
+/**
+ * @param {Position} pos
+ * @returns {Selection}
+ */
+export function collapsedSelection(pos) {
+  return { anchor: pos, head: pos };
+}
+
+/**
+ * @param {Selection} sel
+ * @returns {boolean}
+ */
+export function isCollapsed(sel) {
+  return positionsEqual(sel.anchor, sel.head);
+}
+
+/**
+ * @param {Selection} a
+ * @param {Selection} b
+ * @returns {boolean}
+ */
+export function selectionsEqual(a, b) {
+  return positionsEqual(a.anchor, b.anchor) && positionsEqual(a.head, b.head);
+}
+
+/**
+ * The selection as an ordered range. Returns null when either endpoint's
+ * paragraph is missing.
+ * @param {import("./node.js").Doc} doc
+ * @param {Selection} sel
+ * @returns {{ from: Position, to: Position } | null}
+ */
+export function selectionRange(doc, sel) {
+  const order = comparePositions(doc, sel.anchor, sel.head);
+  if (order === null) {
+    return null;
+  }
+  return order <= 0
+    ? { from: sel.anchor, to: sel.head }
+    : { from: sel.head, to: sel.anchor };
+}
+
+/**
+ * True when both endpoints sit in the same paragraph. Drives the `DeleteStep`
+ * single-paragraph rule.
+ *
+ * Also drives `input/composition.js`'s rejection of multi-paragraph
+ * composing ranges (P1.9a, ADR-0004 §2).
+ * @param {Selection} sel
+ * @returns {boolean}
+ */
+export function isSingleParagraph(sel) {
+  return samePara(sel.anchor, sel.head);
+}
+
+/**
+ * True when both endpoints sit in the same container.
+ *
+ * ADR-0007 makes this an **invariant** for text selections, not merely a
+ * question: a text selection may not span two boxes. On a canvas the boxes have
+ * no meaningful document order between them, so "select from box A into box B"
+ * has no sensible meaning; selecting whole boxes is a `BoxSelection` instead.
+ * Commands assert this rather than trying to handle the cross-container case.
+ * @param {Selection} sel
+ * @returns {boolean}
+ */
+export function isSingleContainer(sel) {
+  return sameContainer(sel.anchor, sel.head);
+}