@heyramzi/ui 1.54.1 → 2.0.0

package/src/canvas/headless/break-apart.ts

@@ -0,0 +1,244 @@
+// Break apart: a drawn figure's cards become real cards. Pure over a parsed tree, so a
+// browser, a CLI and a server run the same code.
+
+import type { CanvasOp } from "../ops/ops.js";
+import { sanitizeFigureSvg } from "./svg-figure.js";
+import { PEN_HEX } from "../pen/colors.js";
+import type { PenColor } from "../pen/types.js";
+import {
+  isEl,
+  translateOf,
+  union,
+  viewBoxOf,
+  boxOfEl,
+  type Box,
+  type FigureChild,
+  type FigureEl,
+} from "./figure-geometry.js";
+import { findPieces } from "./break-apart-pieces.js";
+import { NOTE_BODY_PX, NOTE_TITLE_PX, round1 } from "./break-apart-style.js";
+import {
+  addCards,
+  addEdges,
+  addFrames,
+  addShapes,
+  freshId,
+  linksOf,
+  placeBadges,
+  startPlan,
+  type Plan,
+  type PlanSource,
+} from "./break-apart-plan.js";
+
+// =========================
+// TYPES
+// =========================
+
+/** What the tree reader needs from a DOM node, so no global `Element` is named here. */
+export type DomLike = {
+  nodeType: number;
+  localName?: string;
+  textContent: string | null;
+  attributes?: ArrayLike<{ name: string; value: string }>;
+  childNodes?: ArrayLike<DomLike>;
+};
+
+export type BreakApartInput = PlanSource & {
+  /** The parsed `<svg>` root of the figure's markup, unsanitized: `data-pins` is read from it. */
+  tree: FigureEl;
+};
+
+export type BreakApartResult = {
+  ops: CanvasOp[];
+  cards: number;
+  edges: number;
+  /** Bare rectangles and number marks that became shapes. */
+  shapes: number;
+  /** Rectangles drawn round cards that became frames. */
+  frames: number;
+  /** The figure stays, smaller, because it still has panels or chrome. */
+  remains: boolean;
+};
+
+const TEXT_NODE = 3;
+const ELEMENT_NODE = 1;
+/** Space between the drawing and the caption set under it. */
+const CAPTION_GAP = 8;
+
+// =========================
+// TREE
+// =========================
+
+/** Read a DOM element (or any node shaped like one) into a tree. */
+export function treeFromElement(el: DomLike): FigureEl {
+  const attrs: Record<string, string> = {};
+  for (const attr of Array.from(el.attributes ?? [])) attrs[attr.name] = attr.value;
+  const children: FigureChild[] = [];
+  for (const child of Array.from(el.childNodes ?? [])) {
+    if (child.nodeType === TEXT_NODE) children.push(child.textContent ?? "");
+    else if (child.nodeType === ELEMENT_NODE) children.push(treeFromElement(child));
+  }
+  return { tag: el.localName ?? "", attrs, children };
+}
+
+function escapeText(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function serialize(child: FigureChild): string {
+  if (typeof child === "string") return escapeText(child);
+  const attrs = Object.entries(child.attrs)
+    .map(([name, value]) => ` ${name}="${value.replace(/&/g, "&amp;").replace(/"/g, "&quot;")}"`)
+    .join("");
+  return `<${child.tag}${attrs}>${child.children.map(serialize).join("")}</${child.tag}>`;
+}
+
+// =========================
+// WHAT IS LEFT
+// =========================
+
+function prune(el: FigureEl, removed: Set<FigureChild>): FigureEl {
+  const children: FigureChild[] = [];
+  for (const child of el.children) {
+    if (removed.has(child)) continue;
+    if (isEl(child) && child.tag === "g") {
+      const kept = prune(child, removed);
+      // A group left with no shape, only whitespace, is gone.
+      if (kept.children.some((c) => (isEl(c) ? true : c.trim() !== ""))) children.push(kept);
+      continue;
+    }
+    children.push(child);
+  }
+  return { ...el, children };
+}
+
+/** The ink left once the cards are out: drawable shapes and text, ignoring defs. */
+function leftover(el: FigureEl): Box | null {
+  let box: Box | null = null;
+  for (const child of el.children) {
+    if (!isEl(child) || child.tag === "defs" || child.tag === "title" || child.tag === "desc")
+      continue;
+    if (child.tag === "g") {
+      const shift = translateOf(child) ?? { x: 0, y: 0 };
+      const inner = leftover(child);
+      if (inner) {
+        box = union(box, {
+          x1: inner.x1 + shift.x,
+          y1: inner.y1 + shift.y,
+          x2: inner.x2 + shift.x,
+          y2: inner.y2 + shift.y,
+        });
+      }
+      continue;
+    }
+    box = union(box, boxOfEl(child, { x: 0, y: 0 }));
+  }
+  return box;
+}
+
+/** Nothing is left to draw: the figure goes, and its title and caption stay as text above and below the pieces. */
+function replaceWithText(plan: Plan) {
+  const { node, taken, ops, drawing, scale, artTop } = plan;
+  ops.push({ kind: "removeNode", nodeId: node.id });
+  const accent = node.data.accent as string | undefined;
+  const color = (Object.keys(PEN_HEX) as PenColor[]).find((c) => c === accent) ?? "ink";
+  const textWidth = Math.round(plan.artWidth);
+  const words: [string, number, number][] = [
+    [String(node.data.label ?? ""), NOTE_TITLE_PX, node.position.y],
+    [
+      String(node.data.caption ?? ""),
+      NOTE_BODY_PX,
+      Math.round(node.position.y + artTop + (drawing.y2 - drawing.y1) * scale + CAPTION_GAP),
+    ],
+  ];
+  for (const [i, [text, fontSize, y]] of words.entries()) {
+    if (!text) continue;
+    ops.push({
+      kind: "addNode",
+      node: {
+        id: freshId(`${node.id}-text-${i === 0 ? "title" : "caption"}`, taken),
+        type: "text",
+        position: { x: node.position.x, y },
+        data: { text, color, fontSize, fixedWidth: true },
+        width: textWidth,
+        height: Math.round(fontSize * 1.4),
+        ...(node.parentId ? { parentId: node.parentId } : {}),
+      },
+    });
+  }
+}
+
+/** The figure keeps its height, so its caption stays under the pieces; only the sides shrink. */
+function shrinkFigure(plan: Plan, rest: FigureEl, ink: Box) {
+  const { node, drawing, scale, ops } = plan;
+  const crop: Box = {
+    x1: Math.max(ink.x1, drawing.x1),
+    y1: drawing.y1,
+    x2: Math.min(ink.x2, drawing.x2),
+    y2: drawing.y2,
+  };
+  const cropW = crop.x2 - crop.x1;
+  const cropH = crop.y2 - crop.y1;
+  const markup = sanitizeFigureSvg(
+    serialize({
+      ...rest,
+      attrs: {
+        ...rest.attrs,
+        viewBox: `${round1(crop.x1)} ${round1(crop.y1)} ${round1(cropW)} ${round1(cropH)}`,
+      },
+    }),
+  );
+  const width = Math.round(cropW * scale);
+  const board = node.data.board as { w?: number } | undefined;
+  ops.push({
+    kind: "patchNode",
+    nodeId: node.id,
+    data: { svg: markup ?? "", ...(board?.w ? { board: { ...board, w: width } } : {}) },
+    width,
+    style: { width },
+  });
+  const shift = {
+    x: Math.round(node.position.x + (crop.x1 - drawing.x1) * scale),
+    y: Math.round(node.position.y + (crop.y1 - drawing.y1) * scale),
+  };
+  if (shift.x !== node.position.x || shift.y !== node.position.y) {
+    ops.push({ kind: "moveNode", nodeId: node.id, position: shift });
+  }
+}
+
+// =========================
+// BREAK APART
+// =========================
+
+/** Ops that swap a figure for cards, links, shapes and frames, or null with none in it. The rest stays as a smaller figure. */
+export function breakApartFigure(input: BreakApartInput): BreakApartResult | null {
+  const { node, tree } = input;
+  const drawing = viewBoxOf(tree);
+  const artWidth = input.art?.width ?? node.width;
+  if (!drawing || !artWidth) return null;
+  const pieces = findPieces(tree, drawing);
+  if (!pieces) return null;
+
+  const plan = startPlan(input, pieces, drawing, artWidth);
+  addFrames(plan);
+  addShapes(plan);
+  const links = linksOf(plan);
+  const linkLabels = placeBadges(plan, links);
+  addCards(plan);
+  addEdges(plan, links, linkLabels);
+
+  const counts = {
+    cards: plan.cards.length,
+    edges: links.length,
+    shapes: plan.shapes,
+    frames: plan.loose.frames.length,
+  };
+  const rest = prune(tree, plan.removed);
+  const ink = leftover(rest);
+  if (!ink) {
+    replaceWithText(plan);
+    return { ops: plan.ops, ...counts, remains: false };
+  }
+  shrinkFigure(plan, rest, ink);
+  return { ops: plan.ops, ...counts, remains: true };
+}

package/src/canvas/headless/canvas-cleanup.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, it } from "vite-plus/test";
+import { sortParentsFirst, stripCallbacks } from "./canvas-cleanup.js";
+import { makeNode } from "../test-utils.js";
+import type { CanvasNode } from "../types.js";
+
+/** Read serialized data as a loose record: these tests exercise legacy fields
+ * that are no longer part of any per-type shape but must survive the denylist. */
+function loose(node: { data: unknown }): Record<string, unknown> {
+  return node.data as Record<string, unknown>;
+}
+
+function makeImageNode(overrides: Partial<CanvasNode> = {}): CanvasNode {
+  return makeNode({
+    id: "img-1",
+    type: "image",
+    position: { x: 100, y: 200 },
+    data: {
+      label: "Image",
+      nodeType: "image",
+      imageUrl: "https://storage.example.com/diagram-images/abc123.avif",
+      imageWidth: 800,
+      imageHeight: 600,
+      // Callback that should be stripped
+      onDelete: () => {},
+    } as Record<string, unknown> & { onDelete: () => void },
+    ...overrides,
+  });
+}
+
+describe("stripCallbacks", () => {
+  it("preserves data fields it has never heard of (no silent allowlist loss)", () => {
+    const nodes = [
+      makeImageNode({
+        data: {
+          label: "Image",
+          nodeType: "image",
+          someFutureField: { nested: true },
+          anotherNewFlag: "keep-me",
+        } as Record<string, unknown> & Record<string, unknown>,
+      }),
+    ];
+    const result = stripCallbacks(nodes);
+    expect((result[0].data as Record<string, unknown>).someFutureField).toEqual({ nested: true });
+    expect((result[0].data as Record<string, unknown>).anotherNewFlag).toBe("keep-me");
+  });
+
+  it("preserves labelFr for bilingual nodes", () => {
+    const nodes: CanvasNode[] = [
+      {
+        id: "n-1",
+        type: "agent",
+        position: { x: 0, y: 0 },
+        data: {
+          label: "Delivery PM Agent",
+          labelFr: "Agent PM Livraison",
+          nodeType: "agent",
+          descriptionFr: "Description en français",
+        } satisfies Record<string, unknown>,
+      },
+    ];
+    const result = stripCallbacks(nodes);
+
+    expect(result[0].data.label).toBe("Delivery PM Agent");
+    expect(result[0].data.labelFr).toBe("Agent PM Livraison");
+    expect(result[0].data.descriptionFr).toBe("Description en français");
+  });
+
+  it("preserves editable node-specific fields during autosave serialization", () => {
+    const nodes: CanvasNode[] = [
+      {
+        id: "space-1",
+        type: "space",
+        position: { x: 0, y: 0 },
+        data: {
+          label: "Delivery",
+          nodeType: "space",
+          spaceChildren: [
+            {
+              id: "list-1",
+              type: "list",
+              label: "Implementation",
+              statuses: [{ name: "In progress", color: "blue" }],
+            },
+          ],
+        } as Record<string, unknown>,
+      },
+      {
+        id: "pw-1",
+        type: "pains-wishes",
+        position: { x: 100, y: 0 },
+        data: {
+          label: "Customer fit",
+          nodeType: "pains-wishes",
+          pains: [{ id: "pain-1", text: "Manual reporting" }],
+          wishes: [{ id: "wish-1", text: "Faster onboarding" }],
+        },
+      },
+      {
+        id: "mindmap-1",
+        type: "mindmap",
+        position: { x: 200, y: 0 },
+        data: {
+          label: "Launch plan",
+          nodeType: "mindmap",
+          leftChildCount: 2,
+          rightChildCount: 3,
+          note: "Needs owner",
+          status: "doing",
+          url: "https://example.com/brief",
+          expanded: false,
+        } as Record<string, unknown>,
+      },
+    ];
+
+    const result = stripCallbacks(nodes);
+
+    expect(loose(result[0]).spaceChildren).toEqual(loose(nodes[0]).spaceChildren);
+    expect(loose(result[1]).pains).toEqual(loose(nodes[1]).pains);
+    expect(loose(result[1]).wishes).toEqual(loose(nodes[1]).wishes);
+    // Derived mindmap counts are runtime-only and must NOT persist.
+    expect(result[2].data).not.toHaveProperty("leftChildCount");
+    expect(result[2].data).not.toHaveProperty("rightChildCount");
+    expect(loose(result[2]).note).toBe("Needs owner");
+    expect(loose(result[2]).status).toBe("doing");
+    expect(loose(result[2]).url).toBe("https://example.com/brief");
+    expect(loose(result[2]).expanded).toBe(false);
+  });
+
+  it("image node survives full round-trip (create -> serialize -> deserialize)", () => {
+    const imageNode: CanvasNode = {
+      id: "img-rt",
+      type: "image",
+      position: { x: 50, y: 100 },
+      style: { width: 400, height: 300 },
+      data: {
+        label: "Image",
+        nodeType: "image",
+        imageUrl: "https://storage.example.com/diagram-images/hash123.avif",
+        imageWidth: 1200,
+        imageHeight: 900,
+        onDelete: () => {},
+        locale: "en",
+      } as Record<string, unknown> & { onDelete: () => void; locale: string },
+    };
+
+    // Serialize (what happens on save / after move)
+    const serialized = stripCallbacks([imageNode]);
+
+    // Verify all critical fields survived
+    expect(serialized[0].type).toBe("image");
+    expect(loose(serialized[0]).imageUrl).toBe(
+      "https://storage.example.com/diagram-images/hash123.avif",
+    );
+    expect(loose(serialized[0]).imageWidth).toBe(1200);
+    expect(loose(serialized[0]).imageHeight).toBe(900);
+    expect(serialized[0].style).toEqual({ width: 400, height: 300 });
+    // Runtime-only fields must be gone
+    expect(serialized[0].data).not.toHaveProperty("onDelete");
+    expect(serialized[0].data).not.toHaveProperty("locale");
+  });
+});
+
+describe("sortParentsFirst", () => {
+  // Array order is paint order, so a reshuffle sends ink behind the card it was drawn over.
+  it("keeps roots in their saved order and puts each child after its parent", () => {
+    const nodes = [
+      { id: "table" },
+      { id: "frame" },
+      { id: "card", parentId: "frame" },
+      { id: "stroke" },
+      { id: "note", parentId: "frame" },
+    ];
+    expect(sortParentsFirst(nodes).map((n) => n.id)).toEqual([
+      "table",
+      "frame",
+      "card",
+      "note",
+      "stroke",
+    ]);
+  });
+});

package/src/canvas/headless/canvas-cleanup.ts

@@ -0,0 +1,102 @@
+import type { CanvasEdge, CanvasNode } from "../types.js";
+
+/**
+ * Data fields that exist only at runtime and must never persist. The tree child
+ * counts are recomputed on load; saved, they froze stale values.
+ */
+const RUNTIME_DATA_FIELDS = new Set([
+  "leftChildCount",
+  "rightChildCount",
+  // Injected at render time by locale-aware hosts (deck slides); the persisted
+  // document stays locale-neutral.
+  "locale",
+]);
+
+function persistentData(source: CanvasNode["data"] | undefined): CanvasNode["data"] {
+  const data: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(source ?? {})) {
+    if (RUNTIME_DATA_FIELDS.has(key)) continue;
+    if (typeof value === "function" || value === undefined) continue;
+    data[key] = value;
+  }
+  return data;
+}
+
+/** Strip runtime-only content from nodes for serialization. */
+// Top-level fields are an allowlist, dropping SvelteFlow's runtime state. Data
+// fields keep everything but functions and RUNTIME_DATA_FIELDS, so new fields survive saves.
+export function stripCallbacks<N extends CanvasNode>(nodes: N[]): N[] {
+  return nodes.map((n) => {
+    // Rebuilt field-by-field; `N` is a subtype of the shape rebuilt here, so the
+    // narrowing back to `N` is the one place the type can't follow.
+    const result = {
+      id: n.id,
+      type: n.type,
+      position: n.position,
+      data: persistentData(n.data),
+    } as N;
+    if (n.parentId) result.parentId = n.parentId;
+    if (n.extent) result.extent = n.extent;
+    if (n.style) result.style = n.style;
+    if (typeof n.width === "number") result.width = n.width;
+    if (typeof n.height === "number") result.height = n.height;
+    if (typeof n.zIndex === "number") result.zIndex = n.zIndex;
+    return result;
+  });
+}
+
+/**
+ * Remove edges that reference nodes not present in the node list.
+ */
+export function removeOrphanedEdges<E extends CanvasEdge>(edges: E[], nodeIds: Set<string>): E[] {
+  return edges.filter((edge) => nodeIds.has(edge.source) && nodeIds.has(edge.target));
+}
+
+/**
+ * Parents before children, as SvelteFlow needs. Roots keep their order,
+ * because array order is paint order and flipping it buries new ink.
+ */
+export function sortParentsFirst<T extends { id: string; parentId?: string }>(nodes: T[]): T[] {
+  const idSet = new Set(nodes.map((n) => n.id));
+  const roots: T[] = [];
+  const childrenOf = new Map<string, T[]>();
+
+  for (const n of nodes) {
+    if (!n.parentId || !idSet.has(n.parentId)) {
+      roots.push(n);
+    } else {
+      const siblings = childrenOf.get(n.parentId) ?? [];
+      siblings.push(n);
+      childrenOf.set(n.parentId, siblings);
+    }
+  }
+
+  const sorted: T[] = [];
+  const stack = roots.toReversed();
+  for (let node = stack.pop(); node !== undefined; node = stack.pop()) {
+    sorted.push(node);
+    const children = childrenOf.get(node.id);
+    if (children) {
+      for (let i = children.length - 1; i >= 0; i--) {
+        stack.push(children[i]);
+      }
+    }
+  }
+
+  return sorted;
+}
+
+/**
+ * Fix broken parentId references by clearing parentId/extent
+ * when the referenced parent no longer exists.
+ */
+export function fixBrokenParentIds<N extends CanvasNode>(nodes: N[]): N[] {
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  return nodes.map((node) => {
+    if (node.parentId && !nodeIds.has(node.parentId)) {
+      const { parentId: _, extent: __, ...rest } = node;
+      return rest as unknown as N;
+    }
+    return node;
+  });
+}

package/src/canvas/headless/edge-anchors.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vite-plus/test";
+import { bestAnchors, sideDetour, type Rect } from "./edge-anchors.js";
+
+const box = (x: number, y: number): Rect => ({ x, y, width: 200, height: 80 });
+
+describe("bestAnchors", () => {
+  it("joins a box to the one below it, bottom to top, never round the side", () => {
+    const { source, target } = bestAnchors(box(0, 0), box(20, 300));
+    expect([source.side, target.side]).toEqual(["bottom", "top"]);
+    expect(source).toMatchObject({ x: 100, y: 80 });
+    expect(target).toMatchObject({ x: 120, y: 300 });
+  });
+
+  it("joins a box to the one above it, top to bottom", () => {
+    const { source, target } = bestAnchors(box(0, 300), box(0, 0));
+    expect([source.side, target.side]).toEqual(["top", "bottom"]);
+    const partial = bestAnchors(box(100, 300), box(0, 0));
+    expect([partial.source.side, partial.target.side]).toEqual(["top", "bottom"]);
+  });
+
+  it("meets right to left when the target is beside it", () => {
+    const { source, target } = bestAnchors(box(0, 0), box(500, 30));
+    expect([source.side, target.side]).toEqual(["right", "left"]);
+    expect(source.x).toBe(200);
+    expect(source.y).toBe(40);
+    expect(target.x).toBe(500);
+  });
+
+  it("meets left to right when the target is to the left", () => {
+    const { source, target } = bestAnchors(box(500, 0), box(0, 0));
+    expect([source.side, target.side]).toEqual(["left", "right"]);
+  });
+
+  it("takes the axis with the wider gap, not the wider centre offset", () => {
+    // 240px apart sideways, 400px apart vertically: the column wins.
+    const { source } = bestAnchors(box(0, 0), box(440, 480));
+    expect(source.side).toBe("bottom");
+  });
+
+  it("joins overlapping boxes by the side, not through the middle", () => {
+    const { source, target } = bestAnchors(box(0, 0), box(10, 10));
+    expect([source.side, target.side]).toEqual(["right", "right"]);
+  });
+});
+
+describe("sideDetour", () => {
+  const at = (
+    side: "left" | "right" | "top" | "bottom",
+    a: [number, number],
+    b: [number, number],
+  ) => ({
+    source: { x: a[0], y: a[1], side },
+    target: { x: b[0], y: b[1], side },
+  });
+
+  it("runs past the further right edge, plus the margin", () => {
+    const anchors = at("right", [200, 40], [220, 340]);
+    expect(sideDetour(anchors)).toBe(260);
+    expect(sideDetour(anchors, 10)).toBe(230);
+  });
+
+  it("runs past the further left edge, minus the margin", () => {
+    expect(sideDetour(at("left", [0, 40], [200, 340]))).toBe(-40);
+  });
+
+  it("runs past the higher top or lower bottom edge", () => {
+    expect(sideDetour(at("top", [100, 50], [300, 20]))).toBe(-20);
+    expect(sideDetour(at("bottom", [100, 50], [300, 20]))).toBe(90);
+  });
+});