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

package/dist/commands/box.js

@@ -1,272 +1,272 @@
-import { containerIndexById, layoutOf } from "../model/node.js";
-import { insertContainerStep, removeContainerStep, setLayoutStep } from "../model/step.js";
-import { createTransaction } from "../model/transaction.js";
-
-/**
- * The five user-visible box operations, as commands over the three container
- * steps (ADR-0007) — move/resize/setZ all become `setLayoutStep`, since intent
- * lives in `Transaction.origin`, not in a wider step vocabulary.
- *
- * None of these touch text selection: a box operation and a caret position are
- * orthogonal in this model, so every command here carries `state.selection`
- * through unchanged rather than requiring a `BoxSelection` type to exist yet.
- */
-
-/**
- * Adds a new container to the document.
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {import("../model/node.js").Container} container
- * @param {import("../model/node.js").BoxLayout | null} [layout]
- * @param {number} [index]  defaults to the end of the document
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-export function createBox(state, container, layout = null, index) {
-  const { doc, selection } = state;
-  const at = index ?? doc.content.length;
-
-  const tr = createTransaction(doc, selection, "format");
-  tr.step(insertContainerStep(at, container, layout));
-  if (!tr.changesDoc) {
-    return null;
-  }
-  return tr.build();
-}
-
-/**
- * Removes a container and its geometry together.
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {import("../model/node.js").NodeId} containerId
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-export function deleteBox(state, containerId) {
-  const { doc, selection } = state;
-  if (containerIndexById(doc, containerId) === -1) {
-    return null;
-  }
-  // `normalizeDoc` asserts a document holds at least one container and states
-  // explicitly that keeping it that way is the command layer's job — this is
-  // that job. Without the guard the assertion fires in dev and, worse, in
-  // production (where `devAssert` is a no-op) a zero-container document would
-  // reach the renderer.
-  if (doc.content.length === 1) {
-    return null;
-  }
-
-  const tr = createTransaction(doc, selection, "format");
-  tr.step(removeContainerStep(containerId));
-  if (!tr.changesDoc) {
-    return null;
-  }
-  return tr.build();
-}
-
-/**
- * Whether any key in `patch` differs from the container's current layout.
- *
- * Needed because `patchLayout` (model/node.js) always builds a fresh layout
- * object whether or not values changed, so `TransactionBuilder.changesDoc`
- * cannot tell a real move from a stationary one (mouse down, mouse up, no
- * movement) — that would write a spurious history entry.
- *
- * @param {import("../model/node.js").BoxLayout} current
- * @param {Partial<import("../model/node.js").BoxLayout>} patch
- * @returns {boolean}
- */
-function changesAnything(current, patch) {
-  return /** @type {import("../model/node.js").LayoutKey[]} */ (Object.keys(patch)).some(
-    (key) => current[key] !== patch[key],
-  );
-}
-
-/**
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {import("../model/node.js").NodeId} containerId
- * @param {Partial<import("../model/node.js").BoxLayout>} patch
- * @param {import("../model/transaction.js").TransactionOrigin} origin
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-function setLayout(state, containerId, patch, origin) {
-  const { doc, selection } = state;
-  const current = layoutOf(doc, containerId);
-  if (current === null) {
-    return null; // nothing to patch — this container is content, not a box
-  }
-
-  if (!changesAnything(current, patch)) {
-    return null;
-  }
-
-  // The patch keeps the operation's FULL key set — `{x,y}` for a move even when
-  // only x moved this frame. Narrowing it to just the differing keys looks
-  // tidier and is a real bug: `HistoryEngine` collapses a drag only while the
-  // key set stays identical, so one perfectly horizontal pointer move (y
-  // unchanged) would emit `{x}`, break the collapse, and split the drag into two
-  // undo entries mid-gesture. Dragging in a straight line is not an edge case.
-  //
-  // Emitting an unchanged key is harmless in both directions: applying it is
-  // idempotent, and `invertSetLayout` restores that key from `docBefore`, where
-  // it already held this value.
-  const tr = createTransaction(doc, selection, origin);
-  tr.step(setLayoutStep(containerId, patch));
-  return tr.build();
-}
-
-/**
- * Moves a box. `origin: "pointer"` — a drag calls this once per pointer move,
- * and `HistoryEngine` collapses a run of same-container, same-key-set
- * `SetLayoutStep`s from this origin into a single undo entry (ADR-0007).
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {import("../model/node.js").NodeId} containerId
- * @param {number} x
- * @param {number} y
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-export function moveBox(state, containerId, x, y) {
-  return setLayout(state, containerId, { x, y }, "pointer");
-}
-
-/**
- * Resizes a box. Same collapsing behaviour as `moveBox`, keyed on `{cx, cy}`
- * instead of `{x, y}` — a resize drag never collapses into a move drag or
- * vice versa, because the key sets differ.
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {import("../model/node.js").NodeId} containerId
- * @param {number} cx
- * @param {number} cy
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-export function resizeBox(state, containerId, cx, cy) {
-  return setLayout(state, containerId, { cx, cy }, "pointer");
-}
-
-/**
- * Moves a box to another page. Shares `moveBox`'s coalescing key set only
- * incidentally if a drag ever patches `page` alongside `x`/`y` in the same
- * step — ordinary page reassignment is a discrete action, so `origin:
- * "format"` (never coalesced), matching `setBoxZ` below.
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {import("../model/node.js").NodeId} containerId
- * @param {number} page
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-export function setBoxPage(state, containerId, page) {
-  return setLayout(state, containerId, { page }, "format");
-}
-
-/**
- * Reorders a box's stacking. A discrete action (a menu command or keyboard
- * shortcut, never a drag), so `origin: "format"` — never coalesced.
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {import("../model/node.js").NodeId} containerId
- * @param {number} z
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-export function setBoxZ(state, containerId, z) {
-  return setLayout(state, containerId, { z }, "format");
-}
-
-/**
- * @typedef {object} BoxTransformEntry
- * @property {import("../model/node.js").NodeId} containerId
- * @property {Partial<import("../model/node.js").BoxLayout>} patch
- */
-
-/**
- * The shared engine behind `transformBoxes`/`setBoxZOrder`: every entry in
- * one call becomes its OWN `setLayoutStep`, all in ONE transaction —
- * deliberately a NEW function rather than a change to `setLayout` above,
- * which `moveBox`/`resizeBox` must stay byte-identical to (HIST1/HIST5/
- * HIST6's `find` strings, and their monotonic `expectedMinBreaks` 9/8/7,
- * are measured against those two functions' current bodies).
- *
- * Unlike `setLayout` (one box, one step, skipped entirely when its patch
- * is a no-op), an entry here is never dropped individually just because
- * ITS OWN patch didn't change anything this frame — ADR-0018 Karar 2's
- * "transformBoxes bir karedeki HER girdiyi yazar" rule. A multi-box drag's
- * frame shape (step count, and each step's key set) has to stay identical
- * from frame to frame for `HistoryEngine.canCoalesce`'s `sameKeySet` check
- * to keep collapsing the gesture into one undo entry; dropping one entry
- * because it happened not to move this frame would shrink the step count
- * and split the drag mid-gesture — the exact bug `setLayout`'s own comment
- * already documents for a single box's unchanged key, generalized to N.
- *
- * The WHOLE call is a no-op (returns null) when nothing in the batch
- * changed, or when any entry names something that is not a box — writing
- * N-1 of N valid entries would silently narrow the gesture's own roster.
- *
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {BoxTransformEntry[]} entries
- * @param {import("../model/transaction.js").TransactionOrigin} origin
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-function transformLayouts(state, entries, origin) {
-  const { doc, selection } = state;
-
-  const current = entries.map((entry) => layoutOf(doc, entry.containerId));
-  if (current.some((layout) => layout === null)) {
-    return null;
-  }
-
-  const anyChanged = entries.some((entry, i) =>
-    changesAnything(/** @type {import("../model/node.js").BoxLayout} */ (current[i]), entry.patch),
-  );
-  if (!anyChanged) {
-    return null;
-  }
-
-  const tr = createTransaction(doc, selection, origin);
-  for (const entry of entries) {
-    tr.step(setLayoutStep(entry.containerId, entry.patch));
-  }
-  return tr.build();
-}
-
-/**
- * Moves/resizes N boxes in ONE transaction — the command a corner-handle
- * drag needs and `moveBox`/`resizeBox` cannot give: those write exactly
- * `{x,y}`/`{cx,cy}`, never a corner's full `{x,y,cx,cy}` in one step
- * (ADR-0018 Karar 2). `origin: "pointer"` — coalesces the same way a
- * single-box drag does, keyed on each step's own patch (see
- * `src/canvas/handles.js`'s `resizeKeys` for the fixed key set a given
- * handle's drag must keep writing for the whole gesture).
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {BoxTransformEntry[]} entries
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-export function transformBoxes(state, entries) {
-  return transformLayouts(state, entries, "pointer");
-}
-
-/**
- * `transformBoxes` for exactly one box — the corner-handle case itself.
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {import("../model/node.js").NodeId} containerId
- * @param {Partial<import("../model/node.js").BoxLayout>} patch
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-export function transformBox(state, containerId, patch) {
-  return transformBoxes(state, [{ containerId, patch }]);
-}
-
-/**
- * @typedef {object} BoxZOrderEntry
- * @property {import("../model/node.js").NodeId} containerId
- * @property {number} z
- */
-
-/**
- * Reorders N boxes' stacking in ONE transaction (a "bring to front" over a
- * multi-selection touches more than one box's z at once). `origin:
- * "format"` — a menu/keyboard action, never coalesced, matching the
- * existing single-box `setBoxZ`.
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {BoxZOrderEntry[]} entries
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-export function setBoxZOrder(state, entries) {
-  return transformLayouts(
-    state,
-    entries.map((entry) => ({ containerId: entry.containerId, patch: { z: entry.z } })),
-    "format",
-  );
-}
+import { containerIndexById, layoutOf } from "../model/node.js";
+import { insertContainerStep, removeContainerStep, setLayoutStep } from "../model/step.js";
+import { createTransaction } from "../model/transaction.js";
+
+/**
+ * The five user-visible box operations, as commands over the three container
+ * steps (ADR-0007) — move/resize/setZ all become `setLayoutStep`, since intent
+ * lives in `Transaction.origin`, not in a wider step vocabulary.
+ *
+ * None of these touch text selection: a box operation and a caret position are
+ * orthogonal in this model, so every command here carries `state.selection`
+ * through unchanged rather than requiring a `BoxSelection` type to exist yet.
+ */
+
+/**
+ * Adds a new container to the document.
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {import("../model/node.js").Container} container
+ * @param {import("../model/node.js").BoxLayout | null} [layout]
+ * @param {number} [index]  defaults to the end of the document
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+export function createBox(state, container, layout = null, index) {
+  const { doc, selection } = state;
+  const at = index ?? doc.content.length;
+
+  const tr = createTransaction(doc, selection, "format");
+  tr.step(insertContainerStep(at, container, layout));
+  if (!tr.changesDoc) {
+    return null;
+  }
+  return tr.build();
+}
+
+/**
+ * Removes a container and its geometry together.
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {import("../model/node.js").NodeId} containerId
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+export function deleteBox(state, containerId) {
+  const { doc, selection } = state;
+  if (containerIndexById(doc, containerId) === -1) {
+    return null;
+  }
+  // `normalizeDoc` asserts a document holds at least one container and states
+  // explicitly that keeping it that way is the command layer's job — this is
+  // that job. Without the guard the assertion fires in dev and, worse, in
+  // production (where `devAssert` is a no-op) a zero-container document would
+  // reach the renderer.
+  if (doc.content.length === 1) {
+    return null;
+  }
+
+  const tr = createTransaction(doc, selection, "format");
+  tr.step(removeContainerStep(containerId));
+  if (!tr.changesDoc) {
+    return null;
+  }
+  return tr.build();
+}
+
+/**
+ * Whether any key in `patch` differs from the container's current layout.
+ *
+ * Needed because `patchLayout` (model/node.js) always builds a fresh layout
+ * object whether or not values changed, so `TransactionBuilder.changesDoc`
+ * cannot tell a real move from a stationary one (mouse down, mouse up, no
+ * movement) — that would write a spurious history entry.
+ *
+ * @param {import("../model/node.js").BoxLayout} current
+ * @param {Partial<import("../model/node.js").BoxLayout>} patch
+ * @returns {boolean}
+ */
+function changesAnything(current, patch) {
+  return /** @type {import("../model/node.js").LayoutKey[]} */ (Object.keys(patch)).some(
+    (key) => current[key] !== patch[key],
+  );
+}
+
+/**
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {import("../model/node.js").NodeId} containerId
+ * @param {Partial<import("../model/node.js").BoxLayout>} patch
+ * @param {import("../model/transaction.js").TransactionOrigin} origin
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+function setLayout(state, containerId, patch, origin) {
+  const { doc, selection } = state;
+  const current = layoutOf(doc, containerId);
+  if (current === null) {
+    return null; // nothing to patch — this container is content, not a box
+  }
+
+  if (!changesAnything(current, patch)) {
+    return null;
+  }
+
+  // The patch keeps the operation's FULL key set — `{x,y}` for a move even when
+  // only x moved this frame. Narrowing it to just the differing keys looks
+  // tidier and is a real bug: `HistoryEngine` collapses a drag only while the
+  // key set stays identical, so one perfectly horizontal pointer move (y
+  // unchanged) would emit `{x}`, break the collapse, and split the drag into two
+  // undo entries mid-gesture. Dragging in a straight line is not an edge case.
+  //
+  // Emitting an unchanged key is harmless in both directions: applying it is
+  // idempotent, and `invertSetLayout` restores that key from `docBefore`, where
+  // it already held this value.
+  const tr = createTransaction(doc, selection, origin);
+  tr.step(setLayoutStep(containerId, patch));
+  return tr.build();
+}
+
+/**
+ * Moves a box. `origin: "pointer"` — a drag calls this once per pointer move,
+ * and `HistoryEngine` collapses a run of same-container, same-key-set
+ * `SetLayoutStep`s from this origin into a single undo entry (ADR-0007).
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {import("../model/node.js").NodeId} containerId
+ * @param {number} x
+ * @param {number} y
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+export function moveBox(state, containerId, x, y) {
+  return setLayout(state, containerId, { x, y }, "pointer");
+}
+
+/**
+ * Resizes a box. Same collapsing behaviour as `moveBox`, keyed on `{cx, cy}`
+ * instead of `{x, y}` — a resize drag never collapses into a move drag or
+ * vice versa, because the key sets differ.
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {import("../model/node.js").NodeId} containerId
+ * @param {number} cx
+ * @param {number} cy
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+export function resizeBox(state, containerId, cx, cy) {
+  return setLayout(state, containerId, { cx, cy }, "pointer");
+}
+
+/**
+ * Moves a box to another page. Shares `moveBox`'s coalescing key set only
+ * incidentally if a drag ever patches `page` alongside `x`/`y` in the same
+ * step — ordinary page reassignment is a discrete action, so `origin:
+ * "format"` (never coalesced), matching `setBoxZ` below.
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {import("../model/node.js").NodeId} containerId
+ * @param {number} page
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+export function setBoxPage(state, containerId, page) {
+  return setLayout(state, containerId, { page }, "format");
+}
+
+/**
+ * Reorders a box's stacking. A discrete action (a menu command or keyboard
+ * shortcut, never a drag), so `origin: "format"` — never coalesced.
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {import("../model/node.js").NodeId} containerId
+ * @param {number} z
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+export function setBoxZ(state, containerId, z) {
+  return setLayout(state, containerId, { z }, "format");
+}
+
+/**
+ * @typedef {object} BoxTransformEntry
+ * @property {import("../model/node.js").NodeId} containerId
+ * @property {Partial<import("../model/node.js").BoxLayout>} patch
+ */
+
+/**
+ * The shared engine behind `transformBoxes`/`setBoxZOrder`: every entry in
+ * one call becomes its OWN `setLayoutStep`, all in ONE transaction —
+ * deliberately a NEW function rather than a change to `setLayout` above,
+ * which `moveBox`/`resizeBox` must stay byte-identical to (HIST1/HIST5/
+ * HIST6's `find` strings, and their monotonic `expectedMinBreaks` 9/8/7,
+ * are measured against those two functions' current bodies).
+ *
+ * Unlike `setLayout` (one box, one step, skipped entirely when its patch
+ * is a no-op), an entry here is never dropped individually just because
+ * ITS OWN patch didn't change anything this frame — ADR-0018 Karar 2's
+ * "transformBoxes bir karedeki HER girdiyi yazar" rule. A multi-box drag's
+ * frame shape (step count, and each step's key set) has to stay identical
+ * from frame to frame for `HistoryEngine.canCoalesce`'s `sameKeySet` check
+ * to keep collapsing the gesture into one undo entry; dropping one entry
+ * because it happened not to move this frame would shrink the step count
+ * and split the drag mid-gesture — the exact bug `setLayout`'s own comment
+ * already documents for a single box's unchanged key, generalized to N.
+ *
+ * The WHOLE call is a no-op (returns null) when nothing in the batch
+ * changed, or when any entry names something that is not a box — writing
+ * N-1 of N valid entries would silently narrow the gesture's own roster.
+ *
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {BoxTransformEntry[]} entries
+ * @param {import("../model/transaction.js").TransactionOrigin} origin
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+function transformLayouts(state, entries, origin) {
+  const { doc, selection } = state;
+
+  const current = entries.map((entry) => layoutOf(doc, entry.containerId));
+  if (current.some((layout) => layout === null)) {
+    return null;
+  }
+
+  const anyChanged = entries.some((entry, i) =>
+    changesAnything(/** @type {import("../model/node.js").BoxLayout} */ (current[i]), entry.patch),
+  );
+  if (!anyChanged) {
+    return null;
+  }
+
+  const tr = createTransaction(doc, selection, origin);
+  for (const entry of entries) {
+    tr.step(setLayoutStep(entry.containerId, entry.patch));
+  }
+  return tr.build();
+}
+
+/**
+ * Moves/resizes N boxes in ONE transaction — the command a corner-handle
+ * drag needs and `moveBox`/`resizeBox` cannot give: those write exactly
+ * `{x,y}`/`{cx,cy}`, never a corner's full `{x,y,cx,cy}` in one step
+ * (ADR-0018 Karar 2). `origin: "pointer"` — coalesces the same way a
+ * single-box drag does, keyed on each step's own patch (see
+ * `src/canvas/handles.js`'s `resizeKeys` for the fixed key set a given
+ * handle's drag must keep writing for the whole gesture).
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {BoxTransformEntry[]} entries
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+export function transformBoxes(state, entries) {
+  return transformLayouts(state, entries, "pointer");
+}
+
+/**
+ * `transformBoxes` for exactly one box — the corner-handle case itself.
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {import("../model/node.js").NodeId} containerId
+ * @param {Partial<import("../model/node.js").BoxLayout>} patch
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+export function transformBox(state, containerId, patch) {
+  return transformBoxes(state, [{ containerId, patch }]);
+}
+
+/**
+ * @typedef {object} BoxZOrderEntry
+ * @property {import("../model/node.js").NodeId} containerId
+ * @property {number} z
+ */
+
+/**
+ * Reorders N boxes' stacking in ONE transaction (a "bring to front" over a
+ * multi-selection touches more than one box's z at once). `origin:
+ * "format"` — a menu/keyboard action, never coalesced, matching the
+ * existing single-box `setBoxZ`.
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {BoxZOrderEntry[]} entries
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+export function setBoxZOrder(state, entries) {
+  return transformLayouts(
+    state,
+    entries.map((entry) => ({ containerId: entry.containerId, patch: { z: entry.z } })),
+    "format",
+  );
+}