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

package/dist/model/transaction.js

@@ -1,209 +1,209 @@
-import { normalizeDoc } from "./normalize.js";
-import { apply, dirtyParagraphIds } from "./step-apply.js";
-import { mapThroughSteps } from "./step-map.js";
-
-/**
- * One user-visible change. A transaction is the unit of undo, so everything that
- * should disappear on a single Ctrl+Z belongs in one of these — typing over a
- * selection is a delete *and* an insert, but one transaction.
- *
- * @typedef {object} Transaction
- * @property {import("./step.js").Step[]} steps
- * @property {import("./node.js").Doc} docBefore
- * @property {import("./node.js").Doc} doc  normalized result
- * @property {import("./position.js").Selection} selectionBefore
- * @property {import("./position.js").Selection} selectionAfter
- * @property {TransactionOrigin} origin
- * @property {number} timestamp
- * @property {import("./node.js").Marks | null | undefined} storedMarks
- *   `undefined` means "derive from the default rules"; an explicit value (or
- *   `null`) overrides them. See `state/editor-state.js`.
- * @property {number} [gestureId]
- *   ADR-0016 §1 / ADR-0018 Karar 3's pointer-gesture bracket id. Set only by
- *   a pointer drag or a keyboard nudge (both `origin: "pointer"`) via
- *   `setGesture`; `undefined` for every other origin. `HistoryEngine`
- *   compares this by equality across consecutive "pointer" transactions to
- *   decide whether they belong to the SAME user gesture — it never enters
- *   `Doc`'s own schema, never reaches `toJSON`, never reaches the clipboard
- *   (invariant #13): it lives on `Transaction`/`HistoryEntry` only.
- * @property {readonly string[]} [unverifiedAssumptions]
- *   The command-layer counterpart of `ImportReport.unverifiedAssumptions`
- *   (`io/ooxml/import.js`) — but DYNAMIC, not static: import's list is
- *   disclosed unconditionally on every document, this one is populated only
- *   when a command actually exercised a constant it could not verify from a
- *   primary source (ADR-0028: `commands/size.js`'s clamp ceiling, sourced
- *   only from a secondary reference). `undefined` when nothing was noted —
- *   same absent-vs-empty convention as `gestureId`. Same scope restriction:
- *   never model schema, never `toJSON`, never the clipboard.
- */
-
-/**
- * What produced the transaction. Drives undo coalescing, so it has to be set
- * honestly — `"input"` is only for ordinary typing, `"pointer"` is only for a
- * box drag (`commands/box.js`'s `moveBox`/`resizeBox`), each origin coalescing
- * under its own rule in `HistoryEngine.canCoalesce`.
- * @typedef {"input" | "paste" | "format" | "history" | "ime" | "pointer"} TransactionOrigin
- */
-
-/**
- * Accumulates steps against an evolving document.
- *
- * Commands naturally compute their ranges against the document they were handed,
- * but each step after the first must be expressed in coordinates *after* the
- * preceding steps. `map()` bridges that: hand it a position in the original
- * document and it returns the equivalent position now.
- */
-export class TransactionBuilder {
-  /**
-   * @param {import("./node.js").Doc} doc
-   * @param {import("./position.js").Selection} selection
-   * @param {TransactionOrigin} [origin]
-   */
-  constructor(doc, selection, origin = "input") {
-    /** @type {import("./node.js").Doc} */
-    this.docBefore = doc;
-    /** @type {import("./node.js").Doc} */
-    this.doc = doc;
-    /** @type {import("./step.js").Step[]} */
-    this.steps = [];
-    /** @type {import("./position.js").Selection} */
-    this.selectionBefore = selection;
-    /** @type {import("./position.js").Selection} */
-    this.selectionAfter = selection;
-    /** @type {TransactionOrigin} */
-    this.origin = origin;
-    /** @type {Set<import("./node.js").NodeId>} */
-    this.dirtyIds = new Set();
-    /** @type {import("./node.js").Marks | null | undefined} */
-    this.storedMarks = undefined;
-    /** @type {number | undefined} */
-    this.gestureId = undefined;
-    /** @type {string[] | undefined} */
-    this.unverifiedAssumptions = undefined;
-  }
-
-  /**
-   * Applies a step, expressed in *current* coordinates.
-   * @param {import("./step.js").Step} step
-   * @returns {this}
-   */
-  step(step) {
-    for (const id of dirtyParagraphIds(this.doc, step)) {
-      this.dirtyIds.add(id);
-    }
-    this.doc = apply(this.doc, step);
-    this.steps.push(step);
-    return this;
-  }
-
-  /**
-   * Translates a position from the original document into current coordinates.
-   * @param {import("./position.js").Position} pos
-   * @param {-1 | 1} [bias]
-   * @returns {import("./position.js").Position}
-   */
-  map(pos, bias = 1) {
-    return mapThroughSteps(this.docBefore, this.steps, pos, bias).pos;
-  }
-
-  /**
-   * @param {import("./position.js").Selection} selection
-   * @returns {this}
-   */
-  setSelection(selection) {
-    this.selectionAfter = selection;
-    return this;
-  }
-
-  /**
-   * Overrides the default `storedMarks` handling. Used by `toggleMark` on a
-   * collapsed selection, which changes no document content at all.
-   * @param {import("./node.js").Marks | null} marks
-   * @returns {this}
-   */
-  setStoredMarks(marks) {
-    this.storedMarks = marks;
-    return this;
-  }
-
-  /**
-   * Tags this transaction with the pointer-gesture bracket it belongs to
-   * (ADR-0016 §1, ADR-0018 Karar 3) — `HistoryEngine.canCoalesce` compares
-   * this by equality across consecutive `"pointer"` transactions to decide
-   * whether they are the SAME user gesture. Never model schema, never
-   * `toJSON`, never the clipboard (invariant #13) — `id` is minted by the
-   * caller's `IdFactory` before this is called; this method never mints one.
-   * @param {number} id
-   * @returns {this}
-   */
-  setGesture(id) {
-    this.gestureId = id;
-    return this;
-  }
-
-  /**
-   * Records that this transaction exercised a constant not verified from a
-   * primary source — the dynamic, command-layer counterpart of
-   * `ImportReport.unverifiedAssumptions`. Deduplicates identical messages
-   * (a range edit can clamp several segments against the same ceiling in one
-   * transaction; the caller should not have to track "already noted" itself).
-   * @param {string} message
-   * @returns {this}
-   */
-  noteUnverifiedAssumption(message) {
-    if (this.unverifiedAssumptions === undefined) {
-      this.unverifiedAssumptions = [];
-    }
-    if (!this.unverifiedAssumptions.includes(message)) {
-      this.unverifiedAssumptions.push(message);
-    }
-    return this;
-  }
-
-  /** @returns {boolean} */
-  get isEmpty() {
-    return this.steps.length === 0;
-  }
-
-  /**
-   * Whether the steps actually changed anything. A step can be a no-op — marking
-   * text that already carries the mark, deleting an empty range — and such a
-   * transaction must not reach the history stack, or Ctrl+Z would appear to do
-   * nothing.
-   * @returns {boolean}
-   */
-  get changesDoc() {
-    return this.doc !== this.docBefore;
-  }
-
-  /**
-   * @param {number} [timestamp]
-   * @returns {Transaction}
-   */
-  build(timestamp = Date.now()) {
-    return {
-      steps: this.steps,
-      docBefore: this.docBefore,
-      // Normalisation happens once, here — never between steps, so a step is
-      // free to leave empty or mergeable runs behind.
-      doc: normalizeDoc(this.doc, this.dirtyIds),
-      selectionBefore: this.selectionBefore,
-      selectionAfter: this.selectionAfter,
-      origin: this.origin,
-      timestamp,
-      storedMarks: this.storedMarks,
-      gestureId: this.gestureId,
-      unverifiedAssumptions: this.unverifiedAssumptions,
-    };
-  }
-}
-
-/**
- * @param {import("./node.js").Doc} doc
- * @param {import("./position.js").Selection} selection
- * @param {TransactionOrigin} [origin]
- * @returns {TransactionBuilder}
- */
-export function createTransaction(doc, selection, origin = "input") {
-  return new TransactionBuilder(doc, selection, origin);
-}
+import { normalizeDoc } from "./normalize.js";
+import { apply, dirtyParagraphIds } from "./step-apply.js";
+import { mapThroughSteps } from "./step-map.js";
+
+/**
+ * One user-visible change. A transaction is the unit of undo, so everything that
+ * should disappear on a single Ctrl+Z belongs in one of these — typing over a
+ * selection is a delete *and* an insert, but one transaction.
+ *
+ * @typedef {object} Transaction
+ * @property {import("./step.js").Step[]} steps
+ * @property {import("./node.js").Doc} docBefore
+ * @property {import("./node.js").Doc} doc  normalized result
+ * @property {import("./position.js").Selection} selectionBefore
+ * @property {import("./position.js").Selection} selectionAfter
+ * @property {TransactionOrigin} origin
+ * @property {number} timestamp
+ * @property {import("./node.js").Marks | null | undefined} storedMarks
+ *   `undefined` means "derive from the default rules"; an explicit value (or
+ *   `null`) overrides them. See `state/editor-state.js`.
+ * @property {number} [gestureId]
+ *   ADR-0016 §1 / ADR-0018 Karar 3's pointer-gesture bracket id. Set only by
+ *   a pointer drag or a keyboard nudge (both `origin: "pointer"`) via
+ *   `setGesture`; `undefined` for every other origin. `HistoryEngine`
+ *   compares this by equality across consecutive "pointer" transactions to
+ *   decide whether they belong to the SAME user gesture — it never enters
+ *   `Doc`'s own schema, never reaches `toJSON`, never reaches the clipboard
+ *   (invariant #13): it lives on `Transaction`/`HistoryEntry` only.
+ * @property {readonly string[]} [unverifiedAssumptions]
+ *   The command-layer counterpart of `ImportReport.unverifiedAssumptions`
+ *   (`io/ooxml/import.js`) — but DYNAMIC, not static: import's list is
+ *   disclosed unconditionally on every document, this one is populated only
+ *   when a command actually exercised a constant it could not verify from a
+ *   primary source (ADR-0028: `commands/size.js`'s clamp ceiling, sourced
+ *   only from a secondary reference). `undefined` when nothing was noted —
+ *   same absent-vs-empty convention as `gestureId`. Same scope restriction:
+ *   never model schema, never `toJSON`, never the clipboard.
+ */
+
+/**
+ * What produced the transaction. Drives undo coalescing, so it has to be set
+ * honestly — `"input"` is only for ordinary typing, `"pointer"` is only for a
+ * box drag (`commands/box.js`'s `moveBox`/`resizeBox`), each origin coalescing
+ * under its own rule in `HistoryEngine.canCoalesce`.
+ * @typedef {"input" | "paste" | "format" | "history" | "ime" | "pointer"} TransactionOrigin
+ */
+
+/**
+ * Accumulates steps against an evolving document.
+ *
+ * Commands naturally compute their ranges against the document they were handed,
+ * but each step after the first must be expressed in coordinates *after* the
+ * preceding steps. `map()` bridges that: hand it a position in the original
+ * document and it returns the equivalent position now.
+ */
+export class TransactionBuilder {
+  /**
+   * @param {import("./node.js").Doc} doc
+   * @param {import("./position.js").Selection} selection
+   * @param {TransactionOrigin} [origin]
+   */
+  constructor(doc, selection, origin = "input") {
+    /** @type {import("./node.js").Doc} */
+    this.docBefore = doc;
+    /** @type {import("./node.js").Doc} */
+    this.doc = doc;
+    /** @type {import("./step.js").Step[]} */
+    this.steps = [];
+    /** @type {import("./position.js").Selection} */
+    this.selectionBefore = selection;
+    /** @type {import("./position.js").Selection} */
+    this.selectionAfter = selection;
+    /** @type {TransactionOrigin} */
+    this.origin = origin;
+    /** @type {Set<import("./node.js").NodeId>} */
+    this.dirtyIds = new Set();
+    /** @type {import("./node.js").Marks | null | undefined} */
+    this.storedMarks = undefined;
+    /** @type {number | undefined} */
+    this.gestureId = undefined;
+    /** @type {string[] | undefined} */
+    this.unverifiedAssumptions = undefined;
+  }
+
+  /**
+   * Applies a step, expressed in *current* coordinates.
+   * @param {import("./step.js").Step} step
+   * @returns {this}
+   */
+  step(step) {
+    for (const id of dirtyParagraphIds(this.doc, step)) {
+      this.dirtyIds.add(id);
+    }
+    this.doc = apply(this.doc, step);
+    this.steps.push(step);
+    return this;
+  }
+
+  /**
+   * Translates a position from the original document into current coordinates.
+   * @param {import("./position.js").Position} pos
+   * @param {-1 | 1} [bias]
+   * @returns {import("./position.js").Position}
+   */
+  map(pos, bias = 1) {
+    return mapThroughSteps(this.docBefore, this.steps, pos, bias).pos;
+  }
+
+  /**
+   * @param {import("./position.js").Selection} selection
+   * @returns {this}
+   */
+  setSelection(selection) {
+    this.selectionAfter = selection;
+    return this;
+  }
+
+  /**
+   * Overrides the default `storedMarks` handling. Used by `toggleMark` on a
+   * collapsed selection, which changes no document content at all.
+   * @param {import("./node.js").Marks | null} marks
+   * @returns {this}
+   */
+  setStoredMarks(marks) {
+    this.storedMarks = marks;
+    return this;
+  }
+
+  /**
+   * Tags this transaction with the pointer-gesture bracket it belongs to
+   * (ADR-0016 §1, ADR-0018 Karar 3) — `HistoryEngine.canCoalesce` compares
+   * this by equality across consecutive `"pointer"` transactions to decide
+   * whether they are the SAME user gesture. Never model schema, never
+   * `toJSON`, never the clipboard (invariant #13) — `id` is minted by the
+   * caller's `IdFactory` before this is called; this method never mints one.
+   * @param {number} id
+   * @returns {this}
+   */
+  setGesture(id) {
+    this.gestureId = id;
+    return this;
+  }
+
+  /**
+   * Records that this transaction exercised a constant not verified from a
+   * primary source — the dynamic, command-layer counterpart of
+   * `ImportReport.unverifiedAssumptions`. Deduplicates identical messages
+   * (a range edit can clamp several segments against the same ceiling in one
+   * transaction; the caller should not have to track "already noted" itself).
+   * @param {string} message
+   * @returns {this}
+   */
+  noteUnverifiedAssumption(message) {
+    if (this.unverifiedAssumptions === undefined) {
+      this.unverifiedAssumptions = [];
+    }
+    if (!this.unverifiedAssumptions.includes(message)) {
+      this.unverifiedAssumptions.push(message);
+    }
+    return this;
+  }
+
+  /** @returns {boolean} */
+  get isEmpty() {
+    return this.steps.length === 0;
+  }
+
+  /**
+   * Whether the steps actually changed anything. A step can be a no-op — marking
+   * text that already carries the mark, deleting an empty range — and such a
+   * transaction must not reach the history stack, or Ctrl+Z would appear to do
+   * nothing.
+   * @returns {boolean}
+   */
+  get changesDoc() {
+    return this.doc !== this.docBefore;
+  }
+
+  /**
+   * @param {number} [timestamp]
+   * @returns {Transaction}
+   */
+  build(timestamp = Date.now()) {
+    return {
+      steps: this.steps,
+      docBefore: this.docBefore,
+      // Normalisation happens once, here — never between steps, so a step is
+      // free to leave empty or mergeable runs behind.
+      doc: normalizeDoc(this.doc, this.dirtyIds),
+      selectionBefore: this.selectionBefore,
+      selectionAfter: this.selectionAfter,
+      origin: this.origin,
+      timestamp,
+      storedMarks: this.storedMarks,
+      gestureId: this.gestureId,
+      unverifiedAssumptions: this.unverifiedAssumptions,
+    };
+  }
+}
+
+/**
+ * @param {import("./node.js").Doc} doc
+ * @param {import("./position.js").Selection} selection
+ * @param {TransactionOrigin} [origin]
+ * @returns {TransactionBuilder}
+ */
+export function createTransaction(doc, selection, origin = "input") {
+  return new TransactionBuilder(doc, selection, origin);
+}

package/dist/platform/capabilities.js

@@ -1,25 +1,25 @@
-/**
- * @typedef {object} Capabilities
- * @property {boolean} indexedDB
- * @property {boolean} compressionStream
- * @property {boolean} decompressionStream
- * @property {boolean} fileSystemAccess
- * @property {boolean} dom
- */
-
-/**
- * Detects platform capabilities without touching any global at import time.
- * Every check is lazy — it only runs when this function is called.
- * @returns {Capabilities}
- */
-export function detectCapabilities() {
-  return {
-    indexedDB: typeof indexedDB !== "undefined",
-    compressionStream: typeof CompressionStream !== "undefined",
-    decompressionStream: typeof DecompressionStream !== "undefined",
-    fileSystemAccess:
-      typeof window !== "undefined" &&
-      typeof (/** @type {any} */ (window).showOpenFilePicker) === "function",
-    dom: typeof document !== "undefined",
-  };
-}
+/**
+ * @typedef {object} Capabilities
+ * @property {boolean} indexedDB
+ * @property {boolean} compressionStream
+ * @property {boolean} decompressionStream
+ * @property {boolean} fileSystemAccess
+ * @property {boolean} dom
+ */
+
+/**
+ * Detects platform capabilities without touching any global at import time.
+ * Every check is lazy — it only runs when this function is called.
+ * @returns {Capabilities}
+ */
+export function detectCapabilities() {
+  return {
+    indexedDB: typeof indexedDB !== "undefined",
+    compressionStream: typeof CompressionStream !== "undefined",
+    decompressionStream: typeof DecompressionStream !== "undefined",
+    fileSystemAccess:
+      typeof window !== "undefined" &&
+      typeof (/** @type {any} */ (window).showOpenFilePicker) === "function",
+    dom: typeof document !== "undefined",
+  };
+}

package/dist/react/index.js

@@ -1,21 +1,21 @@
-import { createElement, useEffect, useRef } from "react";
-import { createEditor } from "../index.js";
-
-/**
- * Thin React wrapper around createEditor(). Holds no internal state of its
- * own — the editor instance is the single source of truth.
- * @returns {import("react").ReactElement}
- */
-export function WordEditor() {
-  const containerRef = useRef(/** @type {HTMLDivElement | null} */ (null));
-
-  useEffect(() => {
-    if (!containerRef.current) {
-      return undefined;
-    }
-    const editor = createEditor({ container: containerRef.current });
-    return () => editor.destroy();
-  }, []);
-
-  return createElement("div", { ref: containerRef });
-}
+import { createElement, useEffect, useRef } from "react";
+import { createEditor } from "../index.js";
+
+/**
+ * Thin React wrapper around createEditor(). Holds no internal state of its
+ * own — the editor instance is the single source of truth.
+ * @returns {import("react").ReactElement}
+ */
+export function WordEditor() {
+  const containerRef = useRef(/** @type {HTMLDivElement | null} */ (null));
+
+  useEffect(() => {
+    if (!containerRef.current) {
+      return undefined;
+    }
+    const editor = createEditor({ container: containerRef.current });
+    return () => editor.destroy();
+  }, []);
+
+  return createElement("div", { ref: containerRef });
+}