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

package/dist/index.js

@@ -1,63 +1,63 @@
-import { createEditingHost } from "./editor/editing-host.js";
-import { createIdFactory } from "./model/ids.js";
-import { createEmptyDoc } from "./state/editor-state.js";
-
-/**
- * @typedef {object} EditorOptions
- * @property {HTMLElement} container  the element the editor mounts into. Its
- *   `ownerDocument` supplies the DOM factory and the live selection — no global
- *   `window`/`document` is read (invariant #5).
- * @property {import("./model/node.js").Doc} [doc]  an initial document (e.g.
- *   from `importDocx`). Omitted → a one-empty-paragraph document.
- * @property {(state: import("./state/editor-state.js").EditorState) => void} [onChange]
- */
-
-/**
- * @typedef {object} Editor
- * @property {() => void} destroy
- * @property {(doc: import("./model/node.js").Doc) => void} loadDocument
- * @property {(media: Map<string, string> | null | undefined) => void} setMedia
- * @property {() => import("./state/editor-state.js").EditorState} getState
- */
-
-/**
- * Creates a framework-agnostic, per-box-contenteditable editor mounted into
- * `container` (ADR-0022). This is the EditorFacade of ARCHITECTURE §4: it
- * assembles the already-written editing modules (via `createEditingHost`) and
- * wires them to the real DOM with event delegation, then hands back a small
- * imperative handle. No `window`/`document`/`navigator` is touched at import
- * time — only here, and only through `container.ownerDocument` (invariant #5).
- * @param {EditorOptions} options
- * @returns {Editor}
- */
-export function createEditor(options) {
-  const { container, doc, onChange } = options;
-  const document = container.ownerDocument;
-
-  const ids = createIdFactory();
-  const host = createEditingHost({
-    root: container,
-    document,
-    doc: doc ?? createEmptyDoc(ids),
-    ids,
-    getDomSelection: () => document.getSelection(),
-    onChange,
-  });
-
-  // Delegation (ADR-0022 D2): input events on the container root, selectionchange
-  // on the document — never per-box.
-  host.attach(container, document);
-
-  return {
-    getState: host.getState,
-    loadDocument(nextDoc) {
-      host.loadDocument(nextDoc);
-    },
-    setMedia(media) {
-      host.setMedia(media);
-    },
-    destroy() {
-      host.detach();
-    },
-  };
-}
+import { createEditingHost } from "./editor/editing-host.js";
+import { createIdFactory } from "./model/ids.js";
+import { createEmptyDoc } from "./state/editor-state.js";
+
+/**
+ * @typedef {object} EditorOptions
+ * @property {HTMLElement} container  the element the editor mounts into. Its
+ *   `ownerDocument` supplies the DOM factory and the live selection — no global
+ *   `window`/`document` is read (invariant #5).
+ * @property {import("./model/node.js").Doc} [doc]  an initial document (e.g.
+ *   from `importDocx`). Omitted → a one-empty-paragraph document.
+ * @property {(state: import("./state/editor-state.js").EditorState) => void} [onChange]
+ */
+
+/**
+ * @typedef {object} Editor
+ * @property {() => void} destroy
+ * @property {(doc: import("./model/node.js").Doc) => void} loadDocument
+ * @property {(media: Map<string, string> | null | undefined) => void} setMedia
+ * @property {() => import("./state/editor-state.js").EditorState} getState
+ */
+
+/**
+ * Creates a framework-agnostic, per-box-contenteditable editor mounted into
+ * `container` (ADR-0022). This is the EditorFacade of ARCHITECTURE §4: it
+ * assembles the already-written editing modules (via `createEditingHost`) and
+ * wires them to the real DOM with event delegation, then hands back a small
+ * imperative handle. No `window`/`document`/`navigator` is touched at import
+ * time — only here, and only through `container.ownerDocument` (invariant #5).
+ * @param {EditorOptions} options
+ * @returns {Editor}
+ */
+export function createEditor(options) {
+  const { container, doc, onChange } = options;
+  const document = container.ownerDocument;
+
+  const ids = createIdFactory();
+  const host = createEditingHost({
+    root: container,
+    document,
+    doc: doc ?? createEmptyDoc(ids),
+    ids,
+    getDomSelection: () => document.getSelection(),
+    onChange,
+  });
+
+  // Delegation (ADR-0022 D2): input events on the container root, selectionchange
+  // on the document — never per-box.
+  host.attach(container, document);
+
+  return {
+    getState: host.getState,
+    loadDocument(nextDoc) {
+      host.loadDocument(nextDoc);
+    },
+    setMedia(media) {
+      host.setMedia(media);
+    },
+    destroy() {
+      host.detach();
+    },
+  };
+}

package/dist/input/beforeinput.js

@@ -1,224 +1,224 @@
-import { isDev } from "../dev.js";
-import { createSelection, paragraphIdOf } from "../model/position.js";
-import { domToModel } from "../selection/dom-map.js";
-import {
-  deleteBackward,
-  deleteExplicitRange,
-  deleteForward,
-  deleteSelection,
-  insertText,
-  splitParagraph,
-} from "../commands/text.js";
-import { toggleMark } from "../commands/marks.js";
-
-/**
- * `beforeinput` → command dispatch. ARCHITECTURE.md §3.3: one
- * `contenteditable="true"` surface, `beforeinput` caught and
- * `preventDefault()`-ed, no exceptions but composition.
- *
- * **Default rule: unconditional `preventDefault()`, then dispatch.** An
- * inputType outside our scope is not left to the browser either — if it were,
- * the DOM would drift from the model, which is the one thing this whole
- * architecture exists to prevent (ARCHITECTURE.md §2). It gets `preventDefault()`
- * and nothing else.
- *
- * @typedef {object} StaticRangeLike
- * @property {import("../selection/dom-map.js").MappableNode} startContainer
- * @property {number} startOffset
- * @property {import("../selection/dom-map.js").MappableNode} endContainer
- * @property {number} endOffset
- */
-
-/**
- * The minimal surface of a real `InputEvent` this module needs.
- * @typedef {object} InputEventLike
- * @property {string} inputType
- * @property {string | null} [data]
- * @property {() => void} preventDefault
- * @property {() => StaticRangeLike[]} [getTargetRanges]
- */
-
-/**
- * @typedef {object} BeforeInputContext
- * @property {() => import("../state/editor-state.js").EditorState} getState
- * @property {(tr: import("../model/transaction.js").Transaction) => void} dispatch
- * @property {import("../history/history.js").HistoryEngine} history
- * @property {import("../model/ids.js").IdFactory} ids
- */
-
-/**
- * `insertCompositionText` / `insertFromComposition` are the one exception to
- * "always preventDefault": doing so breaks IME in Chrome mid-composition.
- * This module does not touch the model for these at all.
- *
- * `input/composition.js` (P1.9a, ADR-0004) owns this path; the early return
- * below is what keeps it free for `CompositionController` to drive via the
- * real `compositionstart`/`compositionupdate`/`compositionend` events, which
- * this module never listens for.
- */
-const COMPOSITION_INPUT_TYPES = new Set(["insertCompositionText", "insertFromComposition"]);
-
-/** Sentinel: a recognised inputType that is out of scope for P1. Distinguishes "known no-op" from "never heard of it" — only the latter warns. */
-const NOOP = Symbol("noop");
-
-/**
- * Reads `getTargetRanges()` and translates its first range to a model
- * selection — but only when both endpoints resolve and land in the **same**
- * paragraph. `DeleteStep` cannot span paragraphs (commands/text.js §2.5), so a
- * range that does is not a smaller problem to solve here — it is ignored, and
- * the caller falls back to `deleteBackward`/`deleteForward`, whose own
- * paragraph-merge handling is exactly the multi-paragraph case anyway.
- * @param {InputEventLike} event
- * @returns {import("../model/position.js").Selection | null}
- */
-function resolveTargetRange(event) {
-  const ranges = event.getTargetRanges?.() ?? [];
-  if (ranges.length === 0) {
-    return null;
-  }
-
-  const range = ranges[0];
-  const from = domToModel(range.startContainer, range.startOffset);
-  const to = domToModel(range.endContainer, range.endOffset);
-  if (from === null || to === null) {
-    return null;
-  }
-  if (paragraphIdOf(from) !== paragraphIdOf(to)) {
-    return null;
-  }
-
-  return createSelection(from, to);
-}
-
-/**
- * Builds a delete handler that prefers the browser's own range and falls back
- * to one of our grapheme-aware commands when `getTargetRanges()` is absent,
- * unresolvable, or spans paragraphs.
- *
- * `warnOnFallback` marks the fallback as a **scope cut** rather than the
- * intended behaviour. For `deleteContentBackward`/`Forward` and `deleteContent`,
- * falling back to a single grapheme (or the current selection) *is* the
- * designed behaviour — that is exactly the "getTargetRanges() → Intl.Segmenter
- * → code unit" chain the plan specifies for character-level deletion. But for
- * the word/line types (`deleteWordBackward`, `deleteSoftLineForward`, …), the
- * user asked to delete a whole word or line; silently deleting one grapheme
- * instead is a real degradation, not the intended path, and would otherwise
- * pass with no visible trace. ⚠ doğrulanmalı — see docs/browser-matrix.md.
- *
- * @param {(state: import("../state/editor-state.js").EditorState) => import("../model/transaction.js").Transaction | null} fallback
- * @param {{ warnOnFallback?: boolean }} [options]
- * @returns {(event: InputEventLike, context: BeforeInputContext) => import("../model/transaction.js").Transaction | null}
- */
-function deleteWithFallback(fallback, options = {}) {
-  const warnOnFallback = options.warnOnFallback === true;
-  return (event, context) => {
-    const state = context.getState();
-    const range = resolveTargetRange(event);
-    if (range !== null) {
-      return deleteExplicitRange(state, range);
-    }
-    if (warnOnFallback && isDev()) {
-      // eslint-disable-next-line no-console -- intentional DEV-only diagnostic
-      console.warn(
-        `word-editor: no usable getTargetRanges() for "${event.inputType}" — ` +
-          `falling back to a single grapheme instead of the requested word/line`,
-      );
-    }
-    return fallback(state);
-  };
-}
-
-/** @type {Record<string, ((event: InputEventLike, context: BeforeInputContext) => import("../model/transaction.js").Transaction | null) | typeof NOOP>} */
-const HANDLERS = {
-  insertText: (event, context) => insertText(context.getState(), event.data ?? ""),
-
-  insertParagraph: (event, context) => splitParagraph(context.getState(), context.ids),
-  // No soft line break in P1 — Shift+Enter behaves exactly like Enter, which is
-  // predictable rather than silently dropped.
-  insertLineBreak: (event, context) => splitParagraph(context.getState(), context.ids),
-
-  // The paste event, not beforeinput, is the reliable source of clipboard data
-  // (input/clipboard.js, task 16) — these exist here only to be prevented.
-  insertFromPaste: NOOP,
-  insertFromPasteAsQuotation: NOOP,
-
-  deleteContentBackward: deleteWithFallback(deleteBackward),
-  deleteContentForward: deleteWithFallback(deleteForward),
-  deleteContent: deleteWithFallback(deleteSelection),
-  deleteWordBackward: deleteWithFallback(deleteBackward, { warnOnFallback: true }),
-  deleteWordForward: deleteWithFallback(deleteForward, { warnOnFallback: true }),
-  deleteSoftLineBackward: deleteWithFallback(deleteBackward, { warnOnFallback: true }),
-  deleteSoftLineForward: deleteWithFallback(deleteForward, { warnOnFallback: true }),
-  deleteHardLineBackward: deleteWithFallback(deleteBackward, { warnOnFallback: true }),
-  deleteHardLineForward: deleteWithFallback(deleteForward, { warnOnFallback: true }),
-  deleteEntireSoftLine: deleteWithFallback(deleteSelection, { warnOnFallback: true }),
-
-  // The deletion happens here; writing the cut text to the clipboard is
-  // input/clipboard.js's `cut` handler's job (task 16).
-  deleteByCut: (event, context) => deleteSelection(context.getState(), "input"),
-
-  historyUndo: (event, context) => context.history.undo(context.getState()),
-  historyRedo: (event, context) => context.history.redo(context.getState()),
-
-  formatBold: (event, context) => toggleMark(context.getState(), "bold"),
-  formatItalic: (event, context) => toggleMark(context.getState(), "italic"),
-  formatUnderline: (event, context) => toggleMark(context.getState(), "underline"),
-
-  insertReplacementText: NOOP, // spellcheck="false" in P1 — see ADR-0004
-  insertFromDrop: NOOP,
-  deleteByDrag: NOOP,
-
-  // Out of scope for P1 (ARCHITECTURE.md §9 / the plan's explicit non-goals).
-  insertOrderedList: NOOP,
-  insertUnorderedList: NOOP,
-  insertHorizontalRule: NOOP,
-  insertLink: NOOP,
-  formatStrikeThrough: NOOP,
-  formatSuperscript: NOOP,
-  formatSubscript: NOOP,
-  formatJustifyCenter: NOOP,
-  formatJustifyFull: NOOP,
-  formatJustifyLeft: NOOP,
-  formatJustifyRight: NOOP,
-  formatIndent: NOOP,
-  formatOutdent: NOOP,
-  formatRemove: NOOP,
-  formatSetBlockTextDirection: NOOP,
-  formatBackColor: NOOP,
-  formatFontColor: NOOP,
-  formatFontName: NOOP,
-};
-
-/**
- * The `beforeinput` listener. Call with the real event (or a test double
- * satisfying `InputEventLike`) and the pieces of editor state it needs to
- * reach.
- * @param {InputEventLike} event
- * @param {BeforeInputContext} context
- * @returns {void}
- */
-export function handleBeforeInput(event, context) {
-  if (COMPOSITION_INPUT_TYPES.has(event.inputType)) {
-    return; // input/composition.js owns this path; touch nothing here.
-  }
-
-  event.preventDefault();
-
-  const handler = HANDLERS[event.inputType];
-
-  if (handler === undefined) {
-    if (isDev()) {
-      // eslint-disable-next-line no-console -- intentional DEV-only diagnostic
-      console.warn(`word-editor: unhandled beforeinput inputType "${event.inputType}"`);
-    }
-    return;
-  }
-  if (handler === NOOP) {
-    return;
-  }
-
-  const tr = handler(event, context);
-  if (tr !== null) {
-    context.dispatch(tr);
-  }
-}
+import { isDev } from "../dev.js";
+import { createSelection, paragraphIdOf } from "../model/position.js";
+import { domToModel } from "../selection/dom-map.js";
+import {
+  deleteBackward,
+  deleteExplicitRange,
+  deleteForward,
+  deleteSelection,
+  insertText,
+  splitParagraph,
+} from "../commands/text.js";
+import { toggleMark } from "../commands/marks.js";
+
+/**
+ * `beforeinput` → command dispatch. ARCHITECTURE.md §3.3: one
+ * `contenteditable="true"` surface, `beforeinput` caught and
+ * `preventDefault()`-ed, no exceptions but composition.
+ *
+ * **Default rule: unconditional `preventDefault()`, then dispatch.** An
+ * inputType outside our scope is not left to the browser either — if it were,
+ * the DOM would drift from the model, which is the one thing this whole
+ * architecture exists to prevent (ARCHITECTURE.md §2). It gets `preventDefault()`
+ * and nothing else.
+ *
+ * @typedef {object} StaticRangeLike
+ * @property {import("../selection/dom-map.js").MappableNode} startContainer
+ * @property {number} startOffset
+ * @property {import("../selection/dom-map.js").MappableNode} endContainer
+ * @property {number} endOffset
+ */
+
+/**
+ * The minimal surface of a real `InputEvent` this module needs.
+ * @typedef {object} InputEventLike
+ * @property {string} inputType
+ * @property {string | null} [data]
+ * @property {() => void} preventDefault
+ * @property {() => StaticRangeLike[]} [getTargetRanges]
+ */
+
+/**
+ * @typedef {object} BeforeInputContext
+ * @property {() => import("../state/editor-state.js").EditorState} getState
+ * @property {(tr: import("../model/transaction.js").Transaction) => void} dispatch
+ * @property {import("../history/history.js").HistoryEngine} history
+ * @property {import("../model/ids.js").IdFactory} ids
+ */
+
+/**
+ * `insertCompositionText` / `insertFromComposition` are the one exception to
+ * "always preventDefault": doing so breaks IME in Chrome mid-composition.
+ * This module does not touch the model for these at all.
+ *
+ * `input/composition.js` (P1.9a, ADR-0004) owns this path; the early return
+ * below is what keeps it free for `CompositionController` to drive via the
+ * real `compositionstart`/`compositionupdate`/`compositionend` events, which
+ * this module never listens for.
+ */
+const COMPOSITION_INPUT_TYPES = new Set(["insertCompositionText", "insertFromComposition"]);
+
+/** Sentinel: a recognised inputType that is out of scope for P1. Distinguishes "known no-op" from "never heard of it" — only the latter warns. */
+const NOOP = Symbol("noop");
+
+/**
+ * Reads `getTargetRanges()` and translates its first range to a model
+ * selection — but only when both endpoints resolve and land in the **same**
+ * paragraph. `DeleteStep` cannot span paragraphs (commands/text.js §2.5), so a
+ * range that does is not a smaller problem to solve here — it is ignored, and
+ * the caller falls back to `deleteBackward`/`deleteForward`, whose own
+ * paragraph-merge handling is exactly the multi-paragraph case anyway.
+ * @param {InputEventLike} event
+ * @returns {import("../model/position.js").Selection | null}
+ */
+function resolveTargetRange(event) {
+  const ranges = event.getTargetRanges?.() ?? [];
+  if (ranges.length === 0) {
+    return null;
+  }
+
+  const range = ranges[0];
+  const from = domToModel(range.startContainer, range.startOffset);
+  const to = domToModel(range.endContainer, range.endOffset);
+  if (from === null || to === null) {
+    return null;
+  }
+  if (paragraphIdOf(from) !== paragraphIdOf(to)) {
+    return null;
+  }
+
+  return createSelection(from, to);
+}
+
+/**
+ * Builds a delete handler that prefers the browser's own range and falls back
+ * to one of our grapheme-aware commands when `getTargetRanges()` is absent,
+ * unresolvable, or spans paragraphs.
+ *
+ * `warnOnFallback` marks the fallback as a **scope cut** rather than the
+ * intended behaviour. For `deleteContentBackward`/`Forward` and `deleteContent`,
+ * falling back to a single grapheme (or the current selection) *is* the
+ * designed behaviour — that is exactly the "getTargetRanges() → Intl.Segmenter
+ * → code unit" chain the plan specifies for character-level deletion. But for
+ * the word/line types (`deleteWordBackward`, `deleteSoftLineForward`, …), the
+ * user asked to delete a whole word or line; silently deleting one grapheme
+ * instead is a real degradation, not the intended path, and would otherwise
+ * pass with no visible trace. ⚠ doğrulanmalı — see docs/browser-matrix.md.
+ *
+ * @param {(state: import("../state/editor-state.js").EditorState) => import("../model/transaction.js").Transaction | null} fallback
+ * @param {{ warnOnFallback?: boolean }} [options]
+ * @returns {(event: InputEventLike, context: BeforeInputContext) => import("../model/transaction.js").Transaction | null}
+ */
+function deleteWithFallback(fallback, options = {}) {
+  const warnOnFallback = options.warnOnFallback === true;
+  return (event, context) => {
+    const state = context.getState();
+    const range = resolveTargetRange(event);
+    if (range !== null) {
+      return deleteExplicitRange(state, range);
+    }
+    if (warnOnFallback && isDev()) {
+      // eslint-disable-next-line no-console -- intentional DEV-only diagnostic
+      console.warn(
+        `word-editor: no usable getTargetRanges() for "${event.inputType}" — ` +
+          `falling back to a single grapheme instead of the requested word/line`,
+      );
+    }
+    return fallback(state);
+  };
+}
+
+/** @type {Record<string, ((event: InputEventLike, context: BeforeInputContext) => import("../model/transaction.js").Transaction | null) | typeof NOOP>} */
+const HANDLERS = {
+  insertText: (event, context) => insertText(context.getState(), event.data ?? ""),
+
+  insertParagraph: (event, context) => splitParagraph(context.getState(), context.ids),
+  // No soft line break in P1 — Shift+Enter behaves exactly like Enter, which is
+  // predictable rather than silently dropped.
+  insertLineBreak: (event, context) => splitParagraph(context.getState(), context.ids),
+
+  // The paste event, not beforeinput, is the reliable source of clipboard data
+  // (input/clipboard.js, task 16) — these exist here only to be prevented.
+  insertFromPaste: NOOP,
+  insertFromPasteAsQuotation: NOOP,
+
+  deleteContentBackward: deleteWithFallback(deleteBackward),
+  deleteContentForward: deleteWithFallback(deleteForward),
+  deleteContent: deleteWithFallback(deleteSelection),
+  deleteWordBackward: deleteWithFallback(deleteBackward, { warnOnFallback: true }),
+  deleteWordForward: deleteWithFallback(deleteForward, { warnOnFallback: true }),
+  deleteSoftLineBackward: deleteWithFallback(deleteBackward, { warnOnFallback: true }),
+  deleteSoftLineForward: deleteWithFallback(deleteForward, { warnOnFallback: true }),
+  deleteHardLineBackward: deleteWithFallback(deleteBackward, { warnOnFallback: true }),
+  deleteHardLineForward: deleteWithFallback(deleteForward, { warnOnFallback: true }),
+  deleteEntireSoftLine: deleteWithFallback(deleteSelection, { warnOnFallback: true }),
+
+  // The deletion happens here; writing the cut text to the clipboard is
+  // input/clipboard.js's `cut` handler's job (task 16).
+  deleteByCut: (event, context) => deleteSelection(context.getState(), "input"),
+
+  historyUndo: (event, context) => context.history.undo(context.getState()),
+  historyRedo: (event, context) => context.history.redo(context.getState()),
+
+  formatBold: (event, context) => toggleMark(context.getState(), "bold"),
+  formatItalic: (event, context) => toggleMark(context.getState(), "italic"),
+  formatUnderline: (event, context) => toggleMark(context.getState(), "underline"),
+
+  insertReplacementText: NOOP, // spellcheck="false" in P1 — see ADR-0004
+  insertFromDrop: NOOP,
+  deleteByDrag: NOOP,
+
+  // Out of scope for P1 (ARCHITECTURE.md §9 / the plan's explicit non-goals).
+  insertOrderedList: NOOP,
+  insertUnorderedList: NOOP,
+  insertHorizontalRule: NOOP,
+  insertLink: NOOP,
+  formatStrikeThrough: NOOP,
+  formatSuperscript: NOOP,
+  formatSubscript: NOOP,
+  formatJustifyCenter: NOOP,
+  formatJustifyFull: NOOP,
+  formatJustifyLeft: NOOP,
+  formatJustifyRight: NOOP,
+  formatIndent: NOOP,
+  formatOutdent: NOOP,
+  formatRemove: NOOP,
+  formatSetBlockTextDirection: NOOP,
+  formatBackColor: NOOP,
+  formatFontColor: NOOP,
+  formatFontName: NOOP,
+};
+
+/**
+ * The `beforeinput` listener. Call with the real event (or a test double
+ * satisfying `InputEventLike`) and the pieces of editor state it needs to
+ * reach.
+ * @param {InputEventLike} event
+ * @param {BeforeInputContext} context
+ * @returns {void}
+ */
+export function handleBeforeInput(event, context) {
+  if (COMPOSITION_INPUT_TYPES.has(event.inputType)) {
+    return; // input/composition.js owns this path; touch nothing here.
+  }
+
+  event.preventDefault();
+
+  const handler = HANDLERS[event.inputType];
+
+  if (handler === undefined) {
+    if (isDev()) {
+      // eslint-disable-next-line no-console -- intentional DEV-only diagnostic
+      console.warn(`word-editor: unhandled beforeinput inputType "${event.inputType}"`);
+    }
+    return;
+  }
+  if (handler === NOOP) {
+    return;
+  }
+
+  const tr = handler(event, context);
+  if (tr !== null) {
+    context.dispatch(tr);
+  }
+}