@multiplatform.one/node-graph 7.7.2

package/src/interaction/snapChanges.spec.ts

@@ -0,0 +1,273 @@
+/**
+ * The wiring, design §7.2: S1, S3, S5, S6 and S11. S10 is the guide layer's and
+ * lives in `react-flow/SnapGuides.spec.tsx`, because the component that renders
+ * it is the only thing that can be asked how many `<line>` elements it made.
+ *
+ * S2, S4, S7, S8 and S9 belong to the snapper itself and are in
+ * `snapAlignment.spec.ts`. This file is about everything the snapper is not
+ * allowed to know: which changes are a drag, when the index may be built, and
+ * how grid and alignment share the two axes.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import {
+  applySnapToChanges,
+  createSnapSession,
+  graphSnappingDefaults,
+  snapContextOptions,
+} from "./snapChanges";
+import type { SnapChange, SnapChangeNode, SnapContext } from "./snapChanges";
+import { buildSpatialHash } from "./spatialHash";
+import type { SpatialItem } from "./spatialHash";
+
+const node = (id: string, x: number, y: number, width = 100, height = 50): SnapChangeNode => ({
+  id,
+  position: { x, y },
+  initialWidth: width,
+  initialHeight: height,
+});
+
+const drag = (id: string, x: number, y: number): SnapChange => ({
+  type: "position",
+  id,
+  position: { x, y },
+  dragging: true,
+});
+
+/** Every change these tests read back is a drag, so a missing position is a bug. */
+function positionOf(change: SnapChange): { readonly x: number; readonly y: number } {
+  if (!change.position) throw new Error(`change ${change.id} lost its position`);
+  return change.position;
+}
+
+function context(overrides: Partial<SnapContext> & { nodes: readonly SnapChangeNode[] }) {
+  return {
+    zoom: 1,
+    session: createSnapSession(),
+    ...overrides,
+  } satisfies SnapContext;
+}
+
+describe("snapContextOptions: S11, motion settings do not disable snapping", () => {
+  it('leaves alignment on under animation: "none"', () => {
+    const options = snapContextOptions({ animation: "none" });
+    expect(options.alignment).toBe(true);
+    expect(options.animateGuides).toBe(false);
+  });
+
+  it("leaves alignment on under OS reduced motion", () => {
+    const options = snapContextOptions({ reducedMotion: true });
+    expect(options.alignment).toBe(true);
+    expect(options.animateGuides).toBe(false);
+  });
+
+  it("animates the guides when motion is allowed", () => {
+    expect(snapContextOptions({ animation: "quick" }).animateGuides).toBe(true);
+  });
+
+  it("still snaps end to end with motion off", () => {
+    const options = snapContextOptions({ animation: "none" });
+    const nodes = [node("a", 302, 0), node("c", 300, 400)];
+    const result = applySnapToChanges(
+      [drag("a", 302, 0)],
+      context({ nodes, alignment: options.alignment, grid: options.grid }),
+    );
+    expect(result.guides).toHaveLength(1);
+    expect(positionOf(result.changes[0])).toEqual({ x: 300, y: 0 });
+  });
+
+  it("takes the coarse threshold under a finger and the fine one otherwise", () => {
+    expect(snapContextOptions({ coarsePointer: true }).thresholdScreenPx).toBe(12);
+    expect(snapContextOptions({}).thresholdScreenPx).toBe(8);
+  });
+
+  it("ships with alignment on and the grid off", () => {
+    expect(graphSnappingDefaults.alignment).toBe(true);
+    expect(graphSnappingDefaults.grid).toBeNull();
+  });
+});
+
+describe("applySnapToChanges: S1, only a live drag is snapped", () => {
+  const nodes = [node("a", 302, 0), node("c", 300, 400)];
+
+  it("snaps a position change marked dragging", () => {
+    const result = applySnapToChanges([drag("a", 302, 0)], context({ nodes }));
+    expect(positionOf(result.changes[0])).toEqual({ x: 300, y: 0 });
+  });
+
+  it("carries the snap into the closing frame, so the node lands on the line", () => {
+    // React Flow's last change of a drag carries `dragging: false` AND the raw
+    // pointer position (`XYDrag` end -> `updateNodePositions(dragItems, false)`,
+    // system:2311). Leaving it alone puts the node back off the line the guide
+    // just promised, which is measured in Chrome and is why this is snapped.
+    const ctx = context({ nodes });
+    applySnapToChanges([drag("a", 302, 0)], ctx);
+    const result = applySnapToChanges(
+      [{ type: "position", id: "a", position: { x: 302, y: 0 }, dragging: false }],
+      ctx,
+    );
+    expect(positionOf(result.changes[0])).toEqual({ x: 300, y: 0 });
+    // The guides go with the drag, even though the position moved (S10).
+    expect(result.guides).toEqual([]);
+  });
+
+  it("leaves a dragging:false change alone when no drag was being snapped", () => {
+    // Not a release — someone else writing a position. A fresh session is the
+    // whole test for which of the two it is.
+    const changes: SnapChange[] = [
+      { type: "position", id: "a", position: { x: 302, y: 0 }, dragging: false },
+    ];
+    const result = applySnapToChanges(changes, context({ nodes }));
+    expect(result.changes).toBe(changes);
+    expect(result.guides).toEqual([]);
+  });
+
+  it("forgets the drag once it closes, so the next one indexes a fresh world", () => {
+    const ctx = context({ nodes });
+    applySnapToChanges([drag("a", 302, 0)], ctx);
+    applySnapToChanges(
+      [{ type: "position", id: "a", position: { x: 302, y: 0 }, dragging: false }],
+      ctx,
+    );
+    expect(ctx.session.key).toBeNull();
+    expect(ctx.session.index).toBeNull();
+  });
+
+  it("leaves a programmatic move alone — layout, undo and paste are not drags", () => {
+    const changes: SnapChange[] = [{ type: "position", id: "a", position: { x: 302, y: 0 } }];
+    expect(applySnapToChanges(changes, context({ nodes })).changes).toBe(changes);
+  });
+
+  it("passes select, dimensions and remove changes through untouched", () => {
+    const changes = [
+      { type: "select", id: "a", selected: true },
+      { type: "dimensions", id: "a", dimensions: { width: 100, height: 50 } },
+      { type: "remove", id: "a" },
+    ] as unknown as SnapChange[];
+    expect(applySnapToChanges(changes, context({ nodes })).changes).toBe(changes);
+  });
+
+  it("does nothing at all when both grid and alignment are off", () => {
+    const changes = [drag("a", 302, 0)];
+    const result = applySnapToChanges(changes, context({ nodes, alignment: false, grid: null }));
+    expect(result.changes).toBe(changes);
+    expect(result.guides).toEqual([]);
+  });
+});
+
+describe("applySnapToChanges: S3, the index is built once per drag", () => {
+  const nodes = [node("a", 0, 0), node("b", 300, 0), node("c", 600, 0), node("d", 900, 0)];
+
+  it("builds once across a 30-change drag", () => {
+    const buildIndex = vi.fn((items: readonly SpatialItem[]) => buildSpatialHash(items));
+    const ctx = context({ nodes, buildIndex });
+    for (let frame = 0; frame < 30; frame += 1) {
+      applySnapToChanges([drag("a", 100 + frame, 0)], ctx);
+    }
+    expect(buildIndex).toHaveBeenCalledTimes(1);
+  });
+
+  it("leaves the dragged node out of its own index", () => {
+    const buildIndex = vi.fn((items: readonly SpatialItem[]) => buildSpatialHash(items));
+    applySnapToChanges([drag("a", 100, 0)], context({ nodes, buildIndex }));
+    expect(buildIndex.mock.calls[0][0].map((item) => item.id)).toEqual(["b", "c", "d"]);
+  });
+
+  it("rebuilds for the NEXT drag, because the world moved in between", () => {
+    const buildIndex = vi.fn((items: readonly SpatialItem[]) => buildSpatialHash(items));
+    const ctx = context({ nodes, buildIndex });
+    applySnapToChanges([drag("a", 100, 0)], ctx);
+    applySnapToChanges(
+      [{ type: "position", id: "a", position: { x: 120, y: 0 }, dragging: false }],
+      ctx,
+    );
+    applySnapToChanges([drag("a", 130, 0)], ctx);
+    expect(buildIndex).toHaveBeenCalledTimes(2);
+  });
+
+  it("rebuilds when the dragged SET changes, or the new member snaps to itself", () => {
+    const buildIndex = vi.fn((items: readonly SpatialItem[]) => buildSpatialHash(items));
+    const ctx = context({ nodes, buildIndex });
+    applySnapToChanges([drag("a", 100, 0)], ctx);
+    applySnapToChanges([drag("a", 100, 0), drag("b", 400, 0)], ctx);
+    expect(buildIndex).toHaveBeenCalledTimes(2);
+    expect(buildIndex.mock.calls[1][0].map((item) => item.id)).toEqual(["c", "d"]);
+  });
+});
+
+describe("applySnapToChanges: S5, grid and alignment compose per axis", () => {
+  it("puts the node on the grid when no neighbour is in range", () => {
+    const nodes = [node("a", 309, 205)];
+    const result = applySnapToChanges([drag("a", 309, 205)], context({ nodes, grid: 16 }));
+    expect(positionOf(result.changes[0])).toEqual({ x: 304, y: 208 });
+    expect(result.guides).toEqual([]);
+  });
+
+  it("lets alignment override the axis a guide fired on, and only that one", () => {
+    const nodes = [node("a", 309, 205), node("c", 300, 600)];
+    const result = applySnapToChanges([drag("a", 309, 205)], context({ nodes, grid: 16 }));
+    // x aligned to the neighbour's left edge; y still on the grid.
+    expect(positionOf(result.changes[0])).toEqual({ x: 300, y: 208 });
+    expect(result.guides).toHaveLength(1);
+    expect(result.guides[0].axis).toBe("x");
+  });
+
+  it("keeps the raw position on an unsnapped axis when the grid is off", () => {
+    const nodes = [node("a", 305, 205), node("c", 300, 600)];
+    const result = applySnapToChanges([drag("a", 305, 205)], context({ nodes, grid: null }));
+    expect(positionOf(result.changes[0])).toEqual({ x: 300, y: 205 });
+  });
+
+  it("runs the grid FIRST, so a node the grid carried into range still aligns", () => {
+    // 309 is 9 from the neighbour's edge and outside an 8 px pull. The grid
+    // moves it to 304, which is 4 away, and alignment then takes it.
+    const nodes = [node("a", 309, 0), node("c", 300, 400)];
+    const loose = applySnapToChanges([drag("a", 309, 0)], context({ nodes, grid: null }));
+    expect(positionOf(loose.changes[0]).x).toBe(309);
+    const gridded = applySnapToChanges([drag("a", 309, 0)], context({ nodes, grid: 16 }));
+    expect(positionOf(gridded.changes[0]).x).toBe(300);
+  });
+});
+
+describe("applySnapToChanges: S6, a multi-select drag keeps its shape", () => {
+  const nodes = [
+    node("a", 100, 100),
+    node("b", 300, 100),
+    node("c", 500, 100),
+    node("anchor", 100, 400),
+  ];
+
+  it("moves every selected node by ONE delta", () => {
+    const changes = [drag("a", 102, 100), drag("b", 302, 100), drag("c", 502, 100)];
+    const result = applySnapToChanges(changes, context({ nodes }));
+    const positions = result.changes.map(positionOf);
+    expect(positions).toEqual([
+      { x: 100, y: 100 },
+      { x: 300, y: 100 },
+      { x: 500, y: 100 },
+    ]);
+  });
+
+  it("preserves the relative geometry whatever the delta is", () => {
+    const changes = [drag("a", 102, 100), drag("b", 302, 100), drag("c", 502, 100)];
+    const before = changes.map(positionOf);
+    const after = applySnapToChanges(changes, context({ nodes })).changes.map(positionOf);
+    for (let index = 1; index < before.length; index += 1) {
+      expect(after[index].x - after[0].x).toBe(before[index].x - before[0].x);
+      expect(after[index].y - after[0].y).toBe(before[index].y - before[0].y);
+    }
+  });
+
+  it("snaps the selection's BOUNDING BOX, not each node on its own", () => {
+    // `c`'s own left edge is 2 from the anchor's; the union's is 402 from it.
+    // A per-node snapper would move `c` and deform the selection.
+    // A NARROW anchor, so none of the union's three x lines lands near one of
+    // its three: a wide one puts its right edge under the union's, and the test
+    // would pass for the wrong reason.
+    const spread = [node("a", 100, 100), node("c", 502, 100), node("anchor", 500, 400, 20)];
+    const changes = [drag("a", 100, 100), drag("c", 502, 100)];
+    const result = applySnapToChanges(changes, context({ nodes: spread }));
+    expect(result.changes).toBe(changes);
+    expect(result.guides).toEqual([]);
+  });
+});

package/src/interaction/snapChanges.ts

@@ -0,0 +1,292 @@
+/**
+ * Snapping wired into `onNodesChange`, design §7.2 rules S1, S3, S5, S6 and S11.
+ *
+ * Pure, and deliberately structural about its inputs: it names no `@xyflow`
+ * type, so it runs under Node and the boundary in `react-flow/xy.ts` stays the
+ * only import site. `SnapChange` and `SnapChangeNode` are the shape React Flow
+ * happens to hand us, written down rather than imported.
+ *
+ * The three decisions worth reading before changing anything here:
+ *
+ *  - **A live drag only (S1).** A programmatic move — layout, undo, paste — is
+ *    never snapped, or a relayout fights itself.
+ *
+ *    S1's wording says `dragging === true` and nothing else. Taken literally
+ *    that undoes every snap at the moment of release, and it was MEASURED
+ *    doing so in Chrome on `NodeGraph/Snapping → ZoomThreshold`: mid-drag the
+ *    node sat at the aligned 370 with a guide painted, and on mouseup it
+ *    jumped back off the line. The mechanism is `XYDrag`'s `end` handler
+ *    (`@xyflow/system/dist/esm/index.js:2311-2316`) calling
+ *    `updateNodePositions(dragItems, false)`, which re-emits the position
+ *    XYDrag derived from the raw pointer (`:2154`, `x - dragItem.distance.x`).
+ *    Those drag items never saw our rewrite, so the closing frame is the
+ *    unsnapped one and it is also the frame the document commits.
+ *
+ *    So the rule as built is: a position change is snapped when it belongs to
+ *    a LIVE drag — `dragging: true`, or the `dragging: false` frame that
+ *    closes a drag this session was already snapping. A change with `dragging`
+ *    undefined is still never snapped, and neither is a `dragging: false`
+ *    change with no live session, which is what a stray programmatic set looks
+ *    like. That keeps S1's intent and makes the snap survive the mouse button
+ *    coming up.
+ *  - **The index is a drag, not a frame (S3).** It is built once, on the first
+ *    dragging change, from every node NOT in the dragged set, and lives in a
+ *    `SnapSession` the caller owns. Rebuilding it per frame is the difference
+ *    between a query and a re-scan of the whole graph 120 times a second.
+ *  - **Grid first, alignment per axis (S5).** The grid runs on the union rect,
+ *    then alignment runs from THERE, and an axis keeps its grid value unless a
+ *    guide fired on it. Running alignment from the raw pointer instead would
+ *    make a node the grid carried into range fail to align, which reads as the
+ *    snap being flaky rather than as two rules composing.
+ */
+
+import type { NodeId, Rect, XY } from "../model/document";
+import { unionBounds } from "../model/select";
+import {
+  alignmentThreshold,
+  defaultCandidateRadius,
+  defaultSnapThresholdPx,
+  snapToAlignment,
+} from "./snapAlignment";
+import type { PositionedNode, SnapGuide } from "./snapAlignment";
+import { buildSpatialHash } from "./spatialHash";
+import type { SpatialHash, SpatialItem } from "./spatialHash";
+
+/** Alignment on, grid off — React Flow's own `snapToGrid` defaults off too. */
+export const graphSnappingDefaults = {
+  alignment: true,
+  grid: null,
+} as const;
+
+export interface GraphSnappingOptions {
+  /**
+   * Design §7.2. Off per node via `node.locked`, which React Flow enforces
+   * upstream by refusing to drag a locked node at all.
+   */
+  readonly alignment?: boolean;
+  /** Flow units, or `null` for no grid. */
+  readonly grid?: number | null;
+  /** SCREEN px. Divided by the zoom before use (S2). */
+  readonly thresholdScreenPx?: number;
+}
+
+/** The subset of a React Flow node change this reads. */
+export interface SnapChange {
+  readonly type: string;
+  readonly id?: NodeId;
+  readonly position?: XY;
+  readonly dragging?: boolean;
+}
+
+/** The subset of a React Flow node this reads, seeded or measured. */
+export interface SnapChangeNode {
+  readonly id: NodeId;
+  readonly position: XY;
+  readonly measured?: { readonly width?: number | null; readonly height?: number | null };
+  readonly width?: number | null;
+  readonly height?: number | null;
+  readonly initialWidth?: number | null;
+  readonly initialHeight?: number | null;
+}
+
+/**
+ * The drag's memory. The caller holds one (a ref) and hands it back every
+ * frame; nothing here is global, so two canvases on one page cannot share an
+ * index built from the other's nodes.
+ */
+export interface SnapSession {
+  index: SpatialHash | null;
+  nodes: ReadonlyMap<NodeId, PositionedNode> | null;
+  /** The dragged id set this index was built against. */
+  key: string | null;
+  /** Diagnostic: how many times the index was built. One per drag. */
+  builds: number;
+}
+
+export interface SnapContext {
+  readonly nodes: readonly SnapChangeNode[];
+  readonly zoom: number;
+  readonly session: SnapSession;
+  readonly alignment?: boolean;
+  readonly grid?: number | null;
+  readonly thresholdScreenPx?: number;
+  readonly radius?: number;
+  /** Test seam. The spy that proves S3, and nothing else uses it. */
+  readonly buildIndex?: (items: readonly SpatialItem[]) => SpatialHash;
+}
+
+export interface SnapChangesResult<C> {
+  /** The input array itself when nothing moved, so React sees no new work. */
+  readonly changes: readonly C[];
+  readonly guides: readonly SnapGuide[];
+}
+
+export function createSnapSession(): SnapSession {
+  return { index: null, nodes: null, key: null, builds: 0 };
+}
+
+export function resetSnapSession(session: SnapSession): void {
+  session.index = null;
+  session.nodes = null;
+  session.key = null;
+}
+
+/**
+ * S11, stated as code: motion settings reach `animateGuides` and nothing else.
+ *
+ * Snapping is not motion. `animation: "none"` and OS reduced-motion turn off
+ * the guide's fade; a canvas where the node stops aligning because someone
+ * turned animations off is a different, worse editor.
+ */
+export function snapContextOptions(input: {
+  readonly snapping?: GraphSnappingOptions;
+  readonly animation?: string | null;
+  readonly reducedMotion?: boolean;
+  readonly coarsePointer?: boolean;
+}): {
+  readonly alignment: boolean;
+  readonly grid: number | null;
+  readonly thresholdScreenPx: number;
+  readonly animateGuides: boolean;
+} {
+  const { snapping, animation, reducedMotion, coarsePointer } = input;
+  return {
+    alignment: snapping?.alignment ?? graphSnappingDefaults.alignment,
+    grid: snapping?.grid ?? graphSnappingDefaults.grid,
+    thresholdScreenPx:
+      snapping?.thresholdScreenPx ??
+      (coarsePointer ? defaultSnapThresholdPx.coarse : defaultSnapThresholdPx.fine),
+    animateGuides: animation !== "none" && !reducedMotion,
+  };
+}
+
+/** Measured wins, then a document-set size, then the pre-paint seed (design §5). */
+export function snapNodeRect(node: SnapChangeNode): Rect {
+  const width = node.measured?.width ?? node.width ?? node.initialWidth ?? 0;
+  const height = node.measured?.height ?? node.height ?? node.initialHeight ?? 0;
+  return { x: node.position.x, y: node.position.y, width, height };
+}
+
+function isDragFrame(change: SnapChange): boolean {
+  return change.type === "position" && change.dragging === true && change.position !== undefined;
+}
+
+/** The closing frame of a drag we were already snapping. See the note above. */
+function isDragEnd(change: SnapChange): boolean {
+  return change.type === "position" && change.dragging === false && change.position !== undefined;
+}
+
+function snapToGrid(value: number, grid: number | null): number {
+  if (grid === null || !Number.isFinite(grid) || grid <= 0) return value;
+  return Math.round(value / grid) * grid;
+}
+
+export function applySnapToChanges<C extends SnapChange>(
+  changes: readonly C[],
+  context: SnapContext,
+): SnapChangesResult<C> {
+  const alignment = context.alignment ?? graphSnappingDefaults.alignment;
+  const grid = context.grid ?? graphSnappingDefaults.grid;
+  const session = context.session;
+
+  // A drag that ended takes its index with it: by the next one the world has
+  // moved, and a stale index aligns to where a node used to be. The reset is
+  // at the BOTTOM, because the closing frame is snapped with that same index.
+  const ending = changes.some(isDragEnd);
+  // `key !== null` is the whole test for "we were snapping this drag". A
+  // `dragging: false` change arriving without one is not a release, it is
+  // someone else's position write.
+  const closable = ending && session.key !== null;
+  const isSnappable = (change: SnapChange) =>
+    isDragFrame(change) || (closable && isDragEnd(change));
+
+  const dragging = changes.filter(isSnappable);
+  if (dragging.length === 0) {
+    if (ending) resetSnapSession(session);
+    return { changes, guides: [] };
+  }
+  if (!alignment && grid === null) {
+    if (ending) resetSnapSession(session);
+    return { changes, guides: [] };
+  }
+
+  const sizes = new Map(context.nodes.map((node) => [node.id, node]));
+  const draggedIds: NodeId[] = [];
+  const rects: Rect[] = [];
+  for (const change of dragging) {
+    const id = change.id;
+    if (id === undefined) continue;
+    draggedIds.push(id);
+    const known = sizes.get(id);
+    const size = known ? snapNodeRect(known) : { width: 0, height: 0 };
+    // The proposed position, not the node's last committed one: the union has
+    // to be where the pointer is putting the selection this frame.
+    const proposed = change.position as XY;
+    rects.push({ x: proposed.x, y: proposed.y, width: size.width, height: size.height });
+  }
+  const union = unionBounds(rects);
+  if (!union) {
+    if (ending) resetSnapSession(session);
+    return { changes, guides: [] };
+  }
+
+  const gridded: Rect = { ...union, x: snapToGrid(union.x, grid), y: snapToGrid(union.y, grid) };
+
+  let position: XY = { x: gridded.x, y: gridded.y };
+  let guides: readonly SnapGuide[] = [];
+
+  if (alignment) {
+    const key = [...draggedIds].sort().join(" ");
+    if (session.index === null || session.nodes === null || session.key !== key) {
+      const dragged = new Set(draggedIds);
+      const items: SpatialItem[] = [];
+      const live = new Map<NodeId, PositionedNode>();
+      for (const node of context.nodes) {
+        if (dragged.has(node.id)) continue;
+        const item = { id: node.id, rect: snapNodeRect(node) };
+        items.push(item);
+        live.set(node.id, item);
+      }
+      session.index = (context.buildIndex ?? buildSpatialHash)(items);
+      session.nodes = live;
+      session.key = key;
+      session.builds += 1;
+    }
+    const result = snapToAlignment({
+      ids: draggedIds,
+      rect: gridded,
+      nodes: session.nodes,
+      index: session.index,
+      thresholdFlowUnits: alignmentThreshold({
+        thresholdScreenPx: context.thresholdScreenPx ?? defaultSnapThresholdPx.fine,
+        zoom: context.zoom,
+      }),
+      radius: context.radius ?? defaultCandidateRadius,
+    });
+    guides = result.guides;
+    // Per axis, and only where a guide fired (S5).
+    if (guides.some((guide) => guide.axis === "x"))
+      position = { ...position, x: result.position.x };
+    if (guides.some((guide) => guide.axis === "y"))
+      position = { ...position, y: result.position.y };
+  }
+
+  // The guides go the moment the drag does (S10). The POSITION still moves, or
+  // the node would jump off the line the guide just promised it.
+  const visible = ending ? [] : guides;
+  const dx = position.x - union.x;
+  const dy = position.y - union.y;
+  if (dx === 0 && dy === 0) {
+    if (ending) resetSnapSession(session);
+    return { changes, guides: visible };
+  }
+
+  // ONE delta, applied to every member, so the selection cannot deform (S6).
+  const next = changes.map((change) => {
+    if (!isSnappable(change)) return change;
+    const from = change.position as XY;
+    return { ...change, position: { x: from.x + dx, y: from.y + dy } };
+  });
+  if (ending) resetSnapSession(session);
+  return { changes: next, guides: visible };
+}