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

package/dist/canvas/overlay.js

@@ -1,149 +1,149 @@
-// The resize-handle / snap-guide overlay: a SEPARATE layer, never a child of
-// a page element (ADR-0018 §4.1/Karar 9). `handlePlacements`/
-// `guidePlacements` are pure (page-pt geometry -> client-px placements);
-// `Overlay` is the one class in this module that touches the DOM, and the
-// ONLY DOM writer in `src/canvas/` besides `CanvasController`.
-//
-// Measured constraint, not a style choice: `Renderer.decorationCounts`
-// assumes decorations occupy a FIXED PREFIX of every page element's own
-// child list, and `placeContainers` does index arithmetic against that
-// assumption (`src/render/renderer.js`'s `placeContainers`). Inserting a
-// handle/guide element as a page's child would desync that prefix on the
-// very next render — `Overlay` therefore writes into its OWN container
-// element, a sibling of the pages, never into one.
-//
-// `document` is INJECTED, never read from the global — `ssr-safety.test.js`
-// imports every file under `src/` with no `window`/`document` in scope, so
-// this is not a style preference, it is the only way this file can be
-// imported at all.
-
-import { handleRects } from "./handles.js";
-import { pageToClientRect, pageScale } from "./viewport.js";
-
-/**
- * @typedef {object} HandlePlacement
- * @property {string} name  one of `ALL_HANDLES` (handles.js)
- * @property {{left: number, top: number, width: number, height: number}} rect  client px
- */
-
-/**
- * @typedef {object} GuidePlacement
- * @property {"x" | "y"} axis
- * @property {number} position  client px — an "x" guide is a vertical line at this left offset, a "y" guide a horizontal line at this top offset
- */
-
-/**
- * Every resize handle a box currently offers, converted from page-pt
- * (`handles.js`'s `handleRects`) to client-px — the one bridge between the
- * canvas layer's own geometry and an actual positioned `<div>`.
- *
- * @param {import("../model/node.js").BoxLayout} layout
- * @param {import("./handles.js").HandleMetrics} metrics
- * @param {import("./viewport.js").PageRect} pageRect
- * @returns {HandlePlacement[]}
- */
-export function handlePlacements(layout, metrics, pageRect) {
-  return handleRects(layout, metrics).map((handle) => ({
-    name: handle.name,
-    rect: pageToClientRect(pageRect, handle.rect),
-  }));
-}
-
-/**
- * `snapAdjustment`'s guides (page-pt line positions, `snap.js`), converted
- * to client-px — the overlay draws each as a full-length line across
- * `pageRect`, so only the ONE offset perpendicular to the line matters.
- *
- * @param {import("./snap.js").SnapGuide[]} guides
- * @param {import("./viewport.js").PageRect} pageRect
- * @returns {GuidePlacement[]}
- */
-export function guidePlacements(guides, pageRect) {
-  const scale = pageScale(pageRect);
-  return guides.map((guide) => ({
-    axis: guide.axis,
-    position: guide.axis === "x" ? pageRect.left + guide.position * scale : pageRect.top + guide.position * scale,
-  }));
-}
-
-/**
- * The one DOM writer for handles and snap guides. Lives in its own
- * `container` element (a sibling of the page elements `Renderer` owns —
- * never a child of one, see this file's header). Handle elements are
- * REUSED across renders (matched by `name`) so a drag does not thrash the
- * DOM every frame; guide elements are cheap and simply rebuilt each call,
- * since they exist only while a drag is actively snapping.
- */
-export class Overlay {
-  /**
-   * @param {import("../render/dom.js").DocumentLike} documentTarget  injected, never the global
-   * @param {any} container  an element OUTSIDE every page — this class never touches a page element
-   */
-  constructor(documentTarget, container) {
-    this.document = documentTarget;
-    this.container = container;
-    /** @type {Map<string, any>} */
-    this.handleElements = new Map();
-    /** @type {any[]} */
-    this.guideElements = [];
-  }
-
-  /**
-   * @param {HandlePlacement[]} placements
-   * @returns {void}
-   */
-  syncHandles(placements) {
-    const seen = new Set();
-    for (const placement of placements) {
-      seen.add(placement.name);
-      let el = this.handleElements.get(placement.name);
-      if (el === undefined) {
-        el = this.document.createElement("div");
-        el.className = "word-editor-box-handle";
-        el.dataset.handle = placement.name;
-        this.container.appendChild(el);
-        this.handleElements.set(placement.name, el);
-      }
-      el.style.left = `${placement.rect.left}px`;
-      el.style.top = `${placement.rect.top}px`;
-      el.style.width = `${placement.rect.width}px`;
-      el.style.height = `${placement.rect.height}px`;
-    }
-    // A handle that no longer applies (e.g. the box degraded a kademe, or
-    // the selection changed) is removed rather than hidden — no handle
-    // this class ever creates should linger once `placements` stops naming it.
-    for (const [name, el] of this.handleElements) {
-      if (!seen.has(name)) {
-        this.container.removeChild(el);
-        this.handleElements.delete(name);
-      }
-    }
-  }
-
-  /**
-   * @param {GuidePlacement[]} placements
-   * @returns {void}
-   */
-  syncGuides(placements) {
-    for (const el of this.guideElements) {
-      this.container.removeChild(el);
-    }
-    this.guideElements = placements.map((placement) => {
-      const el = this.document.createElement("div");
-      el.className = `word-editor-snap-guide word-editor-snap-guide--${placement.axis}`;
-      if (placement.axis === "x") {
-        el.style.left = `${placement.position}px`;
-      } else {
-        el.style.top = `${placement.position}px`;
-      }
-      this.container.appendChild(el);
-      return el;
-    });
-  }
-
-  /** Removes every handle and guide element this instance owns. @returns {void} */
-  clear() {
-    this.syncHandles([]);
-    this.syncGuides([]);
-  }
-}
+// The resize-handle / snap-guide overlay: a SEPARATE layer, never a child of
+// a page element (ADR-0018 §4.1/Karar 9). `handlePlacements`/
+// `guidePlacements` are pure (page-pt geometry -> client-px placements);
+// `Overlay` is the one class in this module that touches the DOM, and the
+// ONLY DOM writer in `src/canvas/` besides `CanvasController`.
+//
+// Measured constraint, not a style choice: `Renderer.decorationCounts`
+// assumes decorations occupy a FIXED PREFIX of every page element's own
+// child list, and `placeContainers` does index arithmetic against that
+// assumption (`src/render/renderer.js`'s `placeContainers`). Inserting a
+// handle/guide element as a page's child would desync that prefix on the
+// very next render — `Overlay` therefore writes into its OWN container
+// element, a sibling of the pages, never into one.
+//
+// `document` is INJECTED, never read from the global — `ssr-safety.test.js`
+// imports every file under `src/` with no `window`/`document` in scope, so
+// this is not a style preference, it is the only way this file can be
+// imported at all.
+
+import { handleRects } from "./handles.js";
+import { pageToClientRect, pageScale } from "./viewport.js";
+
+/**
+ * @typedef {object} HandlePlacement
+ * @property {string} name  one of `ALL_HANDLES` (handles.js)
+ * @property {{left: number, top: number, width: number, height: number}} rect  client px
+ */
+
+/**
+ * @typedef {object} GuidePlacement
+ * @property {"x" | "y"} axis
+ * @property {number} position  client px — an "x" guide is a vertical line at this left offset, a "y" guide a horizontal line at this top offset
+ */
+
+/**
+ * Every resize handle a box currently offers, converted from page-pt
+ * (`handles.js`'s `handleRects`) to client-px — the one bridge between the
+ * canvas layer's own geometry and an actual positioned `<div>`.
+ *
+ * @param {import("../model/node.js").BoxLayout} layout
+ * @param {import("./handles.js").HandleMetrics} metrics
+ * @param {import("./viewport.js").PageRect} pageRect
+ * @returns {HandlePlacement[]}
+ */
+export function handlePlacements(layout, metrics, pageRect) {
+  return handleRects(layout, metrics).map((handle) => ({
+    name: handle.name,
+    rect: pageToClientRect(pageRect, handle.rect),
+  }));
+}
+
+/**
+ * `snapAdjustment`'s guides (page-pt line positions, `snap.js`), converted
+ * to client-px — the overlay draws each as a full-length line across
+ * `pageRect`, so only the ONE offset perpendicular to the line matters.
+ *
+ * @param {import("./snap.js").SnapGuide[]} guides
+ * @param {import("./viewport.js").PageRect} pageRect
+ * @returns {GuidePlacement[]}
+ */
+export function guidePlacements(guides, pageRect) {
+  const scale = pageScale(pageRect);
+  return guides.map((guide) => ({
+    axis: guide.axis,
+    position: guide.axis === "x" ? pageRect.left + guide.position * scale : pageRect.top + guide.position * scale,
+  }));
+}
+
+/**
+ * The one DOM writer for handles and snap guides. Lives in its own
+ * `container` element (a sibling of the page elements `Renderer` owns —
+ * never a child of one, see this file's header). Handle elements are
+ * REUSED across renders (matched by `name`) so a drag does not thrash the
+ * DOM every frame; guide elements are cheap and simply rebuilt each call,
+ * since they exist only while a drag is actively snapping.
+ */
+export class Overlay {
+  /**
+   * @param {import("../render/dom.js").DocumentLike} documentTarget  injected, never the global
+   * @param {any} container  an element OUTSIDE every page — this class never touches a page element
+   */
+  constructor(documentTarget, container) {
+    this.document = documentTarget;
+    this.container = container;
+    /** @type {Map<string, any>} */
+    this.handleElements = new Map();
+    /** @type {any[]} */
+    this.guideElements = [];
+  }
+
+  /**
+   * @param {HandlePlacement[]} placements
+   * @returns {void}
+   */
+  syncHandles(placements) {
+    const seen = new Set();
+    for (const placement of placements) {
+      seen.add(placement.name);
+      let el = this.handleElements.get(placement.name);
+      if (el === undefined) {
+        el = this.document.createElement("div");
+        el.className = "word-editor-box-handle";
+        el.dataset.handle = placement.name;
+        this.container.appendChild(el);
+        this.handleElements.set(placement.name, el);
+      }
+      el.style.left = `${placement.rect.left}px`;
+      el.style.top = `${placement.rect.top}px`;
+      el.style.width = `${placement.rect.width}px`;
+      el.style.height = `${placement.rect.height}px`;
+    }
+    // A handle that no longer applies (e.g. the box degraded a kademe, or
+    // the selection changed) is removed rather than hidden — no handle
+    // this class ever creates should linger once `placements` stops naming it.
+    for (const [name, el] of this.handleElements) {
+      if (!seen.has(name)) {
+        this.container.removeChild(el);
+        this.handleElements.delete(name);
+      }
+    }
+  }
+
+  /**
+   * @param {GuidePlacement[]} placements
+   * @returns {void}
+   */
+  syncGuides(placements) {
+    for (const el of this.guideElements) {
+      this.container.removeChild(el);
+    }
+    this.guideElements = placements.map((placement) => {
+      const el = this.document.createElement("div");
+      el.className = `word-editor-snap-guide word-editor-snap-guide--${placement.axis}`;
+      if (placement.axis === "x") {
+        el.style.left = `${placement.position}px`;
+      } else {
+        el.style.top = `${placement.position}px`;
+      }
+      this.container.appendChild(el);
+      return el;
+    });
+  }
+
+  /** Removes every handle and guide element this instance owns. @returns {void} */
+  clear() {
+    this.syncHandles([]);
+    this.syncGuides([]);
+  }
+}

package/dist/canvas/snap.js

@@ -1,132 +1,132 @@
-// Which occupants a drag can snap against, and by how much to correct a
-// proposed drop position toward the nearest matching edge (ADR-0018 §6,
-// §9/Karar 9). No src/, DOM, or history import — pure data in, data out.
-//
-// Target set is CLOSED (ADR-0015, ADR-0018 §6.1): editable boxes UNION
-// decorations. `pageOccupants` is called with NO `kind` filter here — the
-// same "one definition of is-this-a-box-or-a-decoration" file hit-test.js
-// filters TO boxes only, this file deliberately does not. A decoration
-// cannot be selected or moved, but it is a legitimate snap target — being a
-// target is not the same as being selectable.
-//
-// `rectLines` (geometry.js) is the ONLY place the six snap lines are
-// computed — this file never recomputes left/centerX/right/top/centerY/
-// bottom itself (ADR-0018 §9's "TEK tanım" rule).
-
-import { pageOccupants } from "./page.js";
-import { rectLines } from "./geometry.js";
-
-/**
- * @typedef {object} SnapGuide
- * @property {"x" | "y"} axis
- * @property {number} position  pt — where the guide line runs, at the matched target edge
- */
-
-/**
- * @typedef {object} SnapResult
- * @property {number} dx  pt — add to the drag's own raw delta on this axis; 0 when nothing snapped
- * @property {number} dy  pt
- * @property {SnapGuide[]} guides  0, 1, or 2 entries — one per axis that actually snapped
- */
-
-/**
- * Every occupant on `page` that a drag may snap against, except the box(es)
- * currently being dragged. No `kind` filter — a decoration is excluded from
- * SELECTION (ADR-0015) but not from this set (ADR-0018 §6.1's closed
- * target-set decision: "hedef olmak ≠ seçilebilmek").
- *
- * @param {import("../model/node.js").Doc} doc
- * @param {number} page
- * @param {import("../model/node.js").NodeId[]} [excludeIds]  the box(es) being dragged — never snap a box against itself
- * @returns {import("./page.js").PageOccupant[]}
- */
-export function snapTargets(doc, page, excludeIds = []) {
-  const exclude = new Set(excludeIds);
-  return pageOccupants(doc, page).filter((occupant) => !exclude.has(occupant.id));
-}
-
-/**
- * @param {number} threshold
- * @returns {void}
- */
-export function requireSnapThreshold(threshold) {
-  if (typeof threshold !== "number" || !Number.isFinite(threshold)) {
-    throw new TypeError(`snapAdjustment: threshold must be a finite number, got ${JSON.stringify(threshold)}`);
-  }
-}
-
-/**
- * The single closest (targetLine, draggedLine) pair on one axis, within
- * `threshold`. No priority between targets (ADR-0018 §6.1) — every line of
- * every target is a candidate on equal footing; the smallest distance wins,
- * a tie broken by the smaller `NodeId` (determinism, not meaning).
- *
- * @param {number[]} draggedLines  this axis's 3 candidate lines on the dragged rect
- * @param {import("./page.js").PageOccupant[]} targets
- * @param {(lines: import("./geometry.js").SnapLines) => number[]} axisLinesOf
- * @param {number} threshold
- * @returns {{delta: number, position: number} | null}
- */
-function bestAxisMatch(draggedLines, targets, axisLinesOf, threshold) {
-  /** @type {{delta: number, distance: number, position: number, targetId: number} | null} */
-  let best = null;
-  for (const target of targets) {
-    const targetLines = axisLinesOf(rectLines(target.rect));
-    for (const targetLine of targetLines) {
-      for (const draggedLine of draggedLines) {
-        const delta = targetLine - draggedLine;
-        const distance = Math.abs(delta);
-        if (distance > threshold) {
-          continue;
-        }
-        const better =
-          best === null || distance < best.distance || (distance === best.distance && target.id < best.targetId);
-        if (better) {
-          best = { delta, distance, position: targetLine, targetId: target.id };
-        }
-      }
-    }
-  }
-  return best === null ? null : { delta: best.delta, position: best.position };
-}
-
-/**
- * The correction to ADD to a drag's own raw {dx, dy} so the dragged rect's
- * nearest edge lands exactly on the nearest matching target edge, on EACH
- * axis independently (ADR-0018 §6.2 — x may snap while y does not, or vice
- * versa). `draggedRect` is the box's PROPOSED rect for this frame (its
- * anchor already moved by the drag's own raw delta), not the anchor itself.
- *
- * @param {import("./geometry.js").Rect} draggedRect
- * @param {import("./page.js").PageOccupant[]} targets  from `snapTargets`
- * @param {number} threshold  pt — injected, no default (ADR-0018 §6.3, Ö4 unmeasured)
- * @returns {SnapResult}
- */
-export function snapAdjustment(draggedRect, targets, threshold) {
-  requireSnapThreshold(threshold);
-  const dragged = rectLines(draggedRect);
-
-  const xMatch = bestAxisMatch(
-    [dragged.left, dragged.centerX, dragged.right],
-    targets,
-    (lines) => [lines.left, lines.centerX, lines.right],
-    threshold,
-  );
-  const yMatch = bestAxisMatch(
-    [dragged.top, dragged.centerY, dragged.bottom],
-    targets,
-    (lines) => [lines.top, lines.centerY, lines.bottom],
-    threshold,
-  );
-
-  /** @type {SnapGuide[]} */
-  const guides = [];
-  if (xMatch !== null) {
-    guides.push({ axis: "x", position: xMatch.position });
-  }
-  if (yMatch !== null) {
-    guides.push({ axis: "y", position: yMatch.position });
-  }
-
-  return { dx: xMatch === null ? 0 : xMatch.delta, dy: yMatch === null ? 0 : yMatch.delta, guides };
-}
+// Which occupants a drag can snap against, and by how much to correct a
+// proposed drop position toward the nearest matching edge (ADR-0018 §6,
+// §9/Karar 9). No src/, DOM, or history import — pure data in, data out.
+//
+// Target set is CLOSED (ADR-0015, ADR-0018 §6.1): editable boxes UNION
+// decorations. `pageOccupants` is called with NO `kind` filter here — the
+// same "one definition of is-this-a-box-or-a-decoration" file hit-test.js
+// filters TO boxes only, this file deliberately does not. A decoration
+// cannot be selected or moved, but it is a legitimate snap target — being a
+// target is not the same as being selectable.
+//
+// `rectLines` (geometry.js) is the ONLY place the six snap lines are
+// computed — this file never recomputes left/centerX/right/top/centerY/
+// bottom itself (ADR-0018 §9's "TEK tanım" rule).
+
+import { pageOccupants } from "./page.js";
+import { rectLines } from "./geometry.js";
+
+/**
+ * @typedef {object} SnapGuide
+ * @property {"x" | "y"} axis
+ * @property {number} position  pt — where the guide line runs, at the matched target edge
+ */
+
+/**
+ * @typedef {object} SnapResult
+ * @property {number} dx  pt — add to the drag's own raw delta on this axis; 0 when nothing snapped
+ * @property {number} dy  pt
+ * @property {SnapGuide[]} guides  0, 1, or 2 entries — one per axis that actually snapped
+ */
+
+/**
+ * Every occupant on `page` that a drag may snap against, except the box(es)
+ * currently being dragged. No `kind` filter — a decoration is excluded from
+ * SELECTION (ADR-0015) but not from this set (ADR-0018 §6.1's closed
+ * target-set decision: "hedef olmak ≠ seçilebilmek").
+ *
+ * @param {import("../model/node.js").Doc} doc
+ * @param {number} page
+ * @param {import("../model/node.js").NodeId[]} [excludeIds]  the box(es) being dragged — never snap a box against itself
+ * @returns {import("./page.js").PageOccupant[]}
+ */
+export function snapTargets(doc, page, excludeIds = []) {
+  const exclude = new Set(excludeIds);
+  return pageOccupants(doc, page).filter((occupant) => !exclude.has(occupant.id));
+}
+
+/**
+ * @param {number} threshold
+ * @returns {void}
+ */
+export function requireSnapThreshold(threshold) {
+  if (typeof threshold !== "number" || !Number.isFinite(threshold)) {
+    throw new TypeError(`snapAdjustment: threshold must be a finite number, got ${JSON.stringify(threshold)}`);
+  }
+}
+
+/**
+ * The single closest (targetLine, draggedLine) pair on one axis, within
+ * `threshold`. No priority between targets (ADR-0018 §6.1) — every line of
+ * every target is a candidate on equal footing; the smallest distance wins,
+ * a tie broken by the smaller `NodeId` (determinism, not meaning).
+ *
+ * @param {number[]} draggedLines  this axis's 3 candidate lines on the dragged rect
+ * @param {import("./page.js").PageOccupant[]} targets
+ * @param {(lines: import("./geometry.js").SnapLines) => number[]} axisLinesOf
+ * @param {number} threshold
+ * @returns {{delta: number, position: number} | null}
+ */
+function bestAxisMatch(draggedLines, targets, axisLinesOf, threshold) {
+  /** @type {{delta: number, distance: number, position: number, targetId: number} | null} */
+  let best = null;
+  for (const target of targets) {
+    const targetLines = axisLinesOf(rectLines(target.rect));
+    for (const targetLine of targetLines) {
+      for (const draggedLine of draggedLines) {
+        const delta = targetLine - draggedLine;
+        const distance = Math.abs(delta);
+        if (distance > threshold) {
+          continue;
+        }
+        const better =
+          best === null || distance < best.distance || (distance === best.distance && target.id < best.targetId);
+        if (better) {
+          best = { delta, distance, position: targetLine, targetId: target.id };
+        }
+      }
+    }
+  }
+  return best === null ? null : { delta: best.delta, position: best.position };
+}
+
+/**
+ * The correction to ADD to a drag's own raw {dx, dy} so the dragged rect's
+ * nearest edge lands exactly on the nearest matching target edge, on EACH
+ * axis independently (ADR-0018 §6.2 — x may snap while y does not, or vice
+ * versa). `draggedRect` is the box's PROPOSED rect for this frame (its
+ * anchor already moved by the drag's own raw delta), not the anchor itself.
+ *
+ * @param {import("./geometry.js").Rect} draggedRect
+ * @param {import("./page.js").PageOccupant[]} targets  from `snapTargets`
+ * @param {number} threshold  pt — injected, no default (ADR-0018 §6.3, Ö4 unmeasured)
+ * @returns {SnapResult}
+ */
+export function snapAdjustment(draggedRect, targets, threshold) {
+  requireSnapThreshold(threshold);
+  const dragged = rectLines(draggedRect);
+
+  const xMatch = bestAxisMatch(
+    [dragged.left, dragged.centerX, dragged.right],
+    targets,
+    (lines) => [lines.left, lines.centerX, lines.right],
+    threshold,
+  );
+  const yMatch = bestAxisMatch(
+    [dragged.top, dragged.centerY, dragged.bottom],
+    targets,
+    (lines) => [lines.top, lines.centerY, lines.bottom],
+    threshold,
+  );
+
+  /** @type {SnapGuide[]} */
+  const guides = [];
+  if (xMatch !== null) {
+    guides.push({ axis: "x", position: xMatch.position });
+  }
+  if (yMatch !== null) {
+    guides.push({ axis: "y", position: yMatch.position });
+  }
+
+  return { dx: xMatch === null ? 0 : xMatch.delta, dy: yMatch === null ? 0 : yMatch.delta, guides };
+}