@multiplatform.one/node-graph 7.7.2

package/src/model/history.ts

@@ -0,0 +1,153 @@
+/**
+ * The undo journal, design §4.5. `createHistory({ limit: 100, coalesceMs: 400 })`.
+ *
+ * The history holds COMMANDS; the caller holds the document. That is what lets
+ * a React controller keep the document in its own state and still get one undo
+ * per gesture, and it is why every method takes the current document rather
+ * than reading one it owns.
+ *
+ * A drag emits a `moveNodes` per frame, so coalescing is not a nicety: without
+ * it a two-second drag buries the stack under 120 entries. `setPositions` never
+ * coalesces, with anything, because auto-layout must stay separately undoable
+ * from the drag either side of it.
+ */
+
+import { applyCommand, invertCommand } from "./commands";
+import type { GraphCommand } from "./commands";
+import type { EdgeKindDefs, GraphDocument, NodeKindDefs } from "./document";
+
+export interface HistoryEntry<N extends NodeKindDefs, E extends EdgeKindDefs> {
+  readonly redo: GraphCommand<N, E>;
+  readonly undo: GraphCommand<N, E>;
+  /** When this entry was last written. Slides on every coalesce. */
+  readonly at: number;
+}
+
+export interface HistoryOptions {
+  readonly limit?: number;
+  readonly coalesceMs?: number;
+  /** Injected so a spec can drive time without a global fake clock. */
+  readonly now?: () => number;
+}
+
+export interface GraphHistory<N extends NodeKindDefs, E extends EdgeKindDefs> {
+  /** Apply the command, record it, return the new document. */
+  readonly commit: (doc: GraphDocument<N, E>, command: GraphCommand<N, E>) => GraphDocument<N, E>;
+  readonly undo: (doc: GraphDocument<N, E>) => GraphDocument<N, E>;
+  readonly redo: (doc: GraphDocument<N, E>) => GraphDocument<N, E>;
+  readonly canUndo: () => boolean;
+  readonly canRedo: () => boolean;
+  readonly depth: () => number;
+  readonly entries: () => readonly HistoryEntry<N, E>[];
+  readonly clear: () => void;
+}
+
+function movedIds(deltas: Readonly<Record<string, unknown>>): string[] {
+  return Object.keys(deltas).sort();
+}
+
+function sameIds(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((id, i) => id === b[i]);
+}
+
+function addDeltas(
+  a: Readonly<Record<string, { x: number; y: number }>>,
+  b: Readonly<Record<string, { x: number; y: number }>>,
+): Record<string, { x: number; y: number }> {
+  const out: Record<string, { x: number; y: number }> = {};
+  for (const [id, delta] of Object.entries(a)) out[id] = { ...delta };
+  for (const [id, delta] of Object.entries(b)) {
+    const prior = out[id];
+    out[id] = prior ? { x: prior.x + delta.x, y: prior.y + delta.y } : { ...delta };
+  }
+  return out;
+}
+
+export function createHistory<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  options: HistoryOptions = {},
+): GraphHistory<N, E> {
+  const limit = options.limit ?? 100;
+  const coalesceMs = options.coalesceMs ?? 400;
+  const now = options.now ?? (() => Date.now());
+
+  let past: HistoryEntry<N, E>[] = [];
+  let future: HistoryEntry<N, E>[] = [];
+
+  /**
+   * ONE gate. Returns the merged entry, or undefined to start a new one.
+   *
+   * Deliberately not a boolean predicate with the merge done elsewhere: two
+   * places encoding the same rule means either can be wrong while the other
+   * quietly covers for it, which is exactly what a mutation run found when this
+   * was split in two.
+   */
+  function coalesce(
+    command: GraphCommand<N, E>,
+    undo: GraphCommand<N, E>,
+    at: number,
+  ): HistoryEntry<N, E> | undefined {
+    const top = past[past.length - 1];
+    if (!top) return undefined;
+    // A redo stack means the user has undone past `top`. Folding a new command
+    // into an entry that is not currently applied would make the document and
+    // the journal disagree, so a pending redo always starts a fresh entry.
+    if (future.length > 0) return undefined;
+    // The window slides: it measures the gap since the LAST movement, not since
+    // the gesture began, so a slow drag is still one undo.
+    if (at - top.at > coalesceMs) return undefined;
+    // Only moveNodes, ever. setPositions is what auto-layout emits and it must
+    // stay separately undoable from the drag on either side of it.
+    if (command.t !== "moveNodes" || top.redo.t !== "moveNodes" || top.undo.t !== "moveNodes") {
+      return undefined;
+    }
+    if (undo.t !== "moveNodes") return undefined;
+    if (!sameIds(movedIds(command.deltas), movedIds(top.redo.deltas))) return undefined;
+    return {
+      // Deltas compose by addition. That is the whole reason `moveNodes`
+      // carries deltas rather than absolutes.
+      redo: { t: "moveNodes", deltas: addDeltas(top.redo.deltas, command.deltas) },
+      undo: { t: "moveNodes", deltas: addDeltas(top.undo.deltas, undo.deltas) },
+      at,
+    };
+  }
+
+  return {
+    commit(doc, command) {
+      const at = now();
+      const undo = invertCommand(doc, command);
+      const next = applyCommand(doc, command);
+      const merged = coalesce(command, undo, at);
+      if (merged) {
+        past[past.length - 1] = merged;
+        return next;
+      }
+      past.push({ redo: command, undo, at });
+      future = [];
+      if (past.length > limit) past = past.slice(past.length - limit);
+      return next;
+    },
+
+    undo(doc) {
+      const entry = past.pop();
+      if (!entry) return doc;
+      future.push(entry);
+      return applyCommand(doc, entry.undo);
+    },
+
+    redo(doc) {
+      const entry = future.pop();
+      if (!entry) return doc;
+      past.push(entry);
+      return applyCommand(doc, entry.redo);
+    },
+
+    canUndo: () => past.length > 0,
+    canRedo: () => future.length > 0,
+    depth: () => past.length,
+    entries: () => past,
+    clear() {
+      past = [];
+      future = [];
+    },
+  };
+}

package/src/model/index.ts

@@ -0,0 +1,74 @@
+/**
+ * Model barrel — no React, no DOM, no `@xyflow`.
+ *
+ * Its own export condition (`@multiplatform.one/node-graph/model`), so a
+ * server, a CLI, a Frappe hook or the CI bench imports the model alone.
+ */
+
+export type {
+  DocumentProblem,
+  DocumentSchema,
+  EdgeId,
+  EdgeKindDefs,
+  GraphDocument,
+  GraphDocumentVersion,
+  GraphEdgeOf,
+  GraphNodeOf,
+  JsonPrimitive,
+  JsonValue,
+  NodeId,
+  NodeKindDefs,
+  PortId,
+  PortRef,
+  Rect,
+  Result,
+  Size,
+  Viewport,
+  XY,
+} from "./document";
+export type { GraphCommand } from "./commands";
+export { applyCommand, invertCommand } from "./commands";
+export type {
+  ConnectionCheck,
+  ConnectionContext,
+  ConnectionRule,
+  ConnectionVerdict,
+  DropOnlyRule,
+} from "./connect";
+export {
+  defaultDropRules,
+  defaultRules,
+  defineConnectionRule,
+  refuseCycle,
+  refuseDataTypeMismatch,
+  refuseDirection,
+  refuseDuplicate,
+  refusePortArity,
+  refuseSelfLoop,
+  validateConnection,
+  validateDrop,
+} from "./connect";
+export type { GraphHistory, HistoryEntry, HistoryOptions } from "./history";
+export { createHistory } from "./history";
+export type {
+  EdgeKindSpec,
+  GraphNodeField,
+  GraphNodeRenderProps,
+  GraphSchema,
+  GraphSchemaSpec,
+  NodeKindSpec,
+  PortSpec,
+} from "./schema";
+export {
+  clearGraphSchemas,
+  createGraphSchema,
+  getGraphSchema,
+  nodeKindSpec,
+  portArity,
+  registerGraphSchema,
+  resolvePorts,
+} from "./schema";
+export type { MarqueeMode, NodeRect } from "./select";
+export { nodeRects, rectContains, rectsOverlap, selectInMarquee, unionBounds } from "./select";
+export type { ParseOptions } from "./serialize";
+export { parseDocument, serializeDocument } from "./serialize";

package/src/model/schema.ts

@@ -0,0 +1,177 @@
+/**
+ * The schema, design §4.3.
+ *
+ * The union of node and edge kinds is generic over consumer-supplied kind maps.
+ * No declaration merging, no global mutable registry of TYPES — `edge.kind ===
+ * "error"` narrows `edge.data` because `E` says so, not because a `.d.ts`
+ * somewhere was merged into.
+ *
+ * `react` appears here as a TYPE-ONLY import. It is erased, so the model still
+ * carries no React at runtime, which is what `dom/importGraph.spec.ts` checks
+ * and what lets a server or the CI bench import `@multiplatform.one/node-graph/model`.
+ */
+
+import type { ComponentType } from "react";
+import type {
+  DocumentSchema,
+  EdgeKindDefs,
+  GraphNodeOf,
+  NodeId,
+  NodeKindDefs,
+  PortId,
+} from "./document";
+import type { ConnectionRule, DropOnlyRule } from "./connect";
+
+export interface PortSpec {
+  readonly id: PortId;
+  readonly side: "left" | "right" | "top" | "bottom";
+  readonly direction: "in" | "out";
+  readonly index?: number;
+  readonly label?: string;
+  /** Consumer-defined payload type name; connection rules read it. */
+  readonly dataType?: string;
+  /** Default: "many" on out, "one" on in. */
+  readonly arity?: "one" | "many";
+}
+
+/** Default arity, spelled once so the rules and the docs cannot drift apart. */
+export function portArity(port: PortSpec): "one" | "many" {
+  return port.arity ?? (port.direction === "out" ? "many" : "one");
+}
+
+export interface GraphNodeRenderProps<TData> {
+  readonly id: NodeId;
+  readonly data: TData;
+  readonly selected: boolean;
+  readonly dragging: boolean;
+  /**
+   * "overview" below `overviewZoom`. On the prop type from v1 on purpose: it is
+   * what stops the merged single-path edge layer being a breaking change for
+   * every custom node in v1.1 (design §5).
+   */
+  readonly renderMode: "detail" | "overview";
+  /** true on a touch surface: fields are display-only, taps route to the sheet. */
+  readonly readOnlyFields: boolean;
+  readonly ports: readonly PortSpec[];
+  /**
+   * The kind's own `NodeKindSpec.measure`.
+   *
+   * On the render props because the canvas seeds React Flow from it before
+   * first paint (design §5) and the BODY has to paint the same number. Without
+   * it a kind declaring a non-default width was seeded at one width and painted
+   * at the per-size default — measured in the MPO-191 knob fuzz, where a 240px
+   * kind painted 172 / 190 / 216.
+   */
+  readonly measure: { readonly width: number; readonly minHeight: number };
+  readonly setData: (patch: Partial<TData>) => void;
+}
+
+/**
+ * A field the native inspector edits. The widget set is milestone 2's to settle
+ * — this is the minimum `NodeKindSpec.fields` needs to exist.
+ */
+export interface GraphNodeField {
+  readonly key: string;
+  readonly label?: string;
+  readonly type: "text" | "number" | "boolean" | "select";
+  readonly options?: readonly { readonly value: string; readonly label: string }[];
+}
+
+export interface NodeKindSpec<TData> {
+  readonly kind: string;
+  readonly render: ComponentType<GraphNodeRenderProps<TData>>;
+  /** May be a function of data, so a switch node grows outputs without a new kind. */
+  readonly ports: readonly PortSpec[] | ((data: TData) => readonly PortSpec[]);
+  readonly defaultData: TData;
+  /** Width is fixed per kind; height is knob-driven and re-measured. */
+  readonly measure: { readonly width: number; readonly minHeight: number };
+  readonly intent?: string;
+  /** Fields the native inspector edits. Absent means no inspector. */
+  readonly fields?: readonly GraphNodeField[];
+}
+
+export interface EdgeKindSpec<TData> {
+  readonly kind: string;
+  readonly defaultData: TData;
+  /**
+   * Which painted appearance this kind draws as — one of the four in
+   * `src/edges/edgeKinds.ts`. A NAME, not a style: the model stays free of
+   * rendering, and one registered React Flow edge type switches on it.
+   * Absent falls back to the kind's own name.
+   */
+  readonly appearance?: string;
+}
+
+export interface GraphSchema<N extends NodeKindDefs, E extends EdgeKindDefs> extends DocumentSchema<
+  N,
+  E
+> {
+  readonly id: string;
+  readonly nodes: { readonly [K in keyof N & string]: NodeKindSpec<N[K]> };
+  readonly edges: { readonly [K in keyof E & string]: EdgeKindSpec<E[K]> };
+  /** The pointer-tick rules. `refuseCycle` cannot go here; that is a type. */
+  readonly rules: readonly ConnectionRule<N, E>[];
+  /** Rules that run once, on drop. */
+  readonly dropRules: readonly DropOnlyRule<N, E>[];
+}
+
+export interface GraphSchemaSpec<N extends NodeKindDefs, E extends EdgeKindDefs> {
+  readonly id: string;
+  readonly nodes: { readonly [K in keyof N & string]: NodeKindSpec<N[K]> };
+  readonly edges: { readonly [K in keyof E & string]: EdgeKindSpec<E[K]> };
+  readonly rules?: readonly ConnectionRule<N, E>[];
+  readonly dropRules?: readonly DropOnlyRule<N, E>[];
+}
+
+export function createGraphSchema<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  spec: GraphSchemaSpec<N, E>,
+): GraphSchema<N, E> {
+  return {
+    id: spec.id,
+    nodes: spec.nodes,
+    edges: spec.edges,
+    rules: spec.rules ?? [],
+    dropRules: spec.dropRules ?? [],
+  };
+}
+
+const registry = new Map<string, GraphSchema<never, never>>();
+
+/**
+ * `schema.id` is what crosses the bridge. A `render` is a `ComponentType` and
+ * cannot be JSON, so schemas register by id in a module BOTH the native screen
+ * and the DOM entry import. That constraint is what keeps nodes Tamagui: the
+ * body is written once, in the consumer's package, and renders inside the
+ * WebView against the real config, theme and hook.
+ */
+export function registerGraphSchema<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  schema: GraphSchema<N, E>,
+): void {
+  registry.set(schema.id, schema as unknown as GraphSchema<never, never>);
+}
+
+export function getGraphSchema(id: string): GraphSchema<never, never> | undefined {
+  return registry.get(id);
+}
+
+/** Test seam. Registering the same id twice is legal; leaking between specs is not. */
+export function clearGraphSchemas(): void {
+  registry.clear();
+}
+
+export function nodeKindSpec<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  schema: GraphSchema<N, E>,
+  kind: string,
+): NodeKindSpec<unknown> | undefined {
+  return (schema.nodes as Record<string, NodeKindSpec<unknown> | undefined>)[kind];
+}
+
+/** Resolves a node's ports, calling the `ports` function when the kind uses one. */
+export function resolvePorts<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  schema: GraphSchema<N, E>,
+  node: GraphNodeOf<N>,
+): readonly PortSpec[] {
+  const spec = nodeKindSpec(schema, node.kind);
+  if (!spec) return [];
+  return typeof spec.ports === "function" ? spec.ports(node.data) : spec.ports;
+}

package/src/model/select.spec.ts

@@ -0,0 +1,220 @@
+/**
+ * Marquee selection, design §12.2.
+ *
+ * The interesting part is the oracle. The implementation compares intervals;
+ * the oracle below is written from the DEFINITION instead — partial is "not
+ * separated on either axis", full is "all four corners inside" — so a flipped
+ * comparison or an off-by-one on an edge shows up as a disagreement rather
+ * than as two copies of the same mistake. 500 seeded random rects, both modes.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { GraphDocument, Rect } from "./document";
+import { nodeRects, rectContains, rectsOverlap, selectInMarquee, unionBounds } from "./select";
+import type { NodeRect } from "./select";
+
+/** mulberry32. Seeded so a failure is reproducible from the test name alone. */
+function seeded(seed: number) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Written from the definition, not from the implementation. */
+function oracle(rects: readonly NodeRect[], marquee: Rect, mode: "partial" | "full"): string[] {
+  const inside = (x: number, y: number) =>
+    x >= marquee.x &&
+    x <= marquee.x + marquee.width &&
+    y >= marquee.y &&
+    y <= marquee.y + marquee.height;
+  return rects
+    .filter(({ rect }) => {
+      if (mode === "full") {
+        return (
+          inside(rect.x, rect.y) &&
+          inside(rect.x + rect.width, rect.y) &&
+          inside(rect.x, rect.y + rect.height) &&
+          inside(rect.x + rect.width, rect.y + rect.height)
+        );
+      }
+      // Separated on either axis means no overlap. Touching edges are
+      // separated: the overlap area is zero and a zero-area brush should not
+      // sweep up a node it has not actually covered.
+      const separated =
+        rect.x + rect.width <= marquee.x ||
+        marquee.x + marquee.width <= rect.x ||
+        rect.y + rect.height <= marquee.y ||
+        marquee.y + marquee.height <= rect.y;
+      return !separated;
+    })
+    .map(({ id }) => id);
+}
+
+function randomRects(count: number, seed: number): NodeRect[] {
+  const random = seeded(seed);
+  return Array.from({ length: count }, (_, i) => ({
+    id: `n${i}`,
+    rect: {
+      x: Math.round(random() * 800 - 400),
+      y: Math.round(random() * 800 - 400),
+      width: Math.round(random() * 160) + 1,
+      height: Math.round(random() * 120) + 1,
+    },
+  }));
+}
+
+describe("selectInMarquee matches a brute-force oracle", () => {
+  const rects = randomRects(500, 0x191);
+
+  for (const mode of ["partial", "full"] as const) {
+    it(`over 500 random rects and 60 marquees, ${mode}`, () => {
+      const random = seeded(0x4a4a);
+      for (let i = 0; i < 60; i++) {
+        const marquee: Rect = {
+          x: Math.round(random() * 800 - 400),
+          y: Math.round(random() * 800 - 400),
+          width: Math.round(random() * 500) + 1,
+          height: Math.round(random() * 500) + 1,
+        };
+        expect(selectInMarquee(rects, marquee, mode), JSON.stringify(marquee)).toEqual(
+          oracle(rects, marquee, mode),
+        );
+      }
+    });
+  }
+
+  it("finds fewer in full mode than in partial, on a marquee that clips", () => {
+    // Guards against the two modes silently becoming the same function.
+    const marquee: Rect = { x: -100, y: -100, width: 200, height: 200 };
+    const partial = selectInMarquee(rects, marquee, "partial");
+    const full = selectInMarquee(rects, marquee, "full");
+    expect(partial.length).toBeGreaterThan(full.length);
+    // No id twice, and full is a strict subset of partial.
+    expect(new Set(partial).size).toBe(partial.length);
+    for (const id of full) expect(partial).toContain(id);
+  });
+});
+
+describe("the edge cases the oracle exists to pin", () => {
+  const one: NodeRect[] = [{ id: "n", rect: { x: 0, y: 0, width: 10, height: 10 } }];
+
+  it("does not select a node the marquee only touches", () => {
+    expect(selectInMarquee(one, { x: 10, y: 0, width: 5, height: 10 }, "partial")).toEqual([]);
+  });
+
+  it("selects a node the marquee overlaps by one unit", () => {
+    expect(selectInMarquee(one, { x: 9, y: 0, width: 5, height: 10 }, "partial")).toEqual(["n"]);
+  });
+
+  it("counts an exactly-covering marquee as full", () => {
+    expect(selectInMarquee(one, { x: 0, y: 0, width: 10, height: 10 }, "full")).toEqual(["n"]);
+  });
+
+  it("does not count a marquee one unit short as full", () => {
+    expect(selectInMarquee(one, { x: 0, y: 0, width: 10, height: 9 }, "full")).toEqual([]);
+  });
+
+  it("keeps the input order, so selection is stable between drags", () => {
+    const many = randomRects(50, 7);
+    const marquee: Rect = { x: -400, y: -400, width: 900, height: 900 };
+    const selected = selectInMarquee(many, marquee, "partial");
+    expect(selected).toEqual(many.filter(({ id }) => selected.includes(id)).map(({ id }) => id));
+  });
+});
+
+describe("unionBounds", () => {
+  it("is the smallest rect covering them all", () => {
+    expect(
+      unionBounds([
+        { x: 0, y: 0, width: 10, height: 10 },
+        { x: 100, y: -20, width: 5, height: 5 },
+      ]),
+      // maxY is 0 + 10, not -20 + 5, so the height is 10 - (-20).
+    ).toEqual({ x: 0, y: -20, width: 105, height: 30 });
+  });
+
+  it("is a single rect's own bounds", () => {
+    const only = { x: 3, y: 4, width: 5, height: 6 };
+    expect(unionBounds([only])).toEqual(only);
+  });
+
+  it("is undefined for nothing, rather than a zero rect at the origin", () => {
+    // A zero rect at 0,0 is a REAL position, and a toolbar that centres on it
+    // would jump the viewport whenever the selection emptied.
+    expect(unionBounds([])).toBeUndefined();
+  });
+
+  it("matches an oracle over 200 random rects", () => {
+    const rects = randomRects(200, 0x55).map(({ rect }) => rect);
+    const minX = Math.min(...rects.map((r) => r.x));
+    const minY = Math.min(...rects.map((r) => r.y));
+    const maxX = Math.max(...rects.map((r) => r.x + r.width));
+    const maxY = Math.max(...rects.map((r) => r.y + r.height));
+    expect(unionBounds(rects)).toEqual({
+      x: minX,
+      y: minY,
+      width: maxX - minX,
+      height: maxY - minY,
+    });
+  });
+});
+
+describe("the predicates on their own", () => {
+  const a: Rect = { x: 0, y: 0, width: 10, height: 10 };
+
+  it("rectsOverlap is symmetric", () => {
+    const b: Rect = { x: 5, y: 5, width: 10, height: 10 };
+    expect(rectsOverlap(a, b)).toBe(true);
+    expect(rectsOverlap(b, a)).toBe(true);
+  });
+
+  it("rectContains is not", () => {
+    const inner: Rect = { x: 2, y: 2, width: 3, height: 3 };
+    expect(rectContains(a, inner)).toBe(true);
+    expect(rectContains(inner, a)).toBe(false);
+  });
+});
+
+describe("nodeRects", () => {
+  type Nodes = { readonly task: Record<string, never> };
+  type Edges = { readonly flow: Record<string, never> };
+
+  const doc: GraphDocument<Nodes, Edges> = {
+    version: 1,
+    nodes: [
+      {
+        id: "sized",
+        kind: "task",
+        position: { x: 10, y: 20 },
+        data: {},
+        size: { width: 190, height: 72 },
+      },
+      { id: "unsized", kind: "task", position: { x: 0, y: 0 }, data: {} },
+    ],
+    edges: [],
+  };
+
+  it("uses the node's own size when it has one", () => {
+    expect(nodeRects(doc, () => ({ width: 1, height: 1 }))[0].rect).toEqual({
+      x: 10,
+      y: 20,
+      width: 190,
+      height: 72,
+    });
+  });
+
+  it("falls back to the measurer for a node that has not been measured yet", () => {
+    // Nodes are seeded from `NodeKindSpec.measure` before first paint (design
+    // §5), but a document loaded from JSON may not carry a size at all.
+    expect(nodeRects(doc, () => ({ width: 172, height: 48 }))[1].rect).toEqual({
+      x: 0,
+      y: 0,
+      width: 172,
+      height: 48,
+    });
+  });
+});