@heyramzi/ui 1.54.1 → 2.0.0

package/src/canvas/lod/lod-mode.svelte.ts

@@ -0,0 +1,30 @@
+import { untrack } from "svelte";
+
+// One flag per canvas: a card reading it re-renders when it flips, not on every zoom frame.
+
+/** Below this zoom a card is a box. */
+export const LOW_BELOW = 0.4;
+/** Back to the full card above this. The gap stops a zoom held at the line from swapping every card each frame. */
+export const FULL_ABOVE = 0.46;
+
+type ZoomSource = { viewport: { zoom: number } };
+
+const modes = new WeakMap<object, { low: boolean }>();
+
+/** The shared flag for one canvas's store. The first card to ask starts the one effect that keeps it. */
+export function lodMode(store: ZoomSource): { readonly low: boolean } {
+  const known = modes.get(store);
+  if (known) return known;
+  const mode = $state({ low: store.viewport.zoom < LOW_BELOW });
+  modes.set(store, mode);
+  $effect.root(() => {
+    $effect(() => {
+      const zoom = store.viewport.zoom;
+      untrack(() => {
+        if (mode.low && zoom > FULL_ABOVE) mode.low = false;
+        else if (!mode.low && zoom < LOW_BELOW) mode.low = true;
+      });
+    });
+  });
+  return mode;
+}

package/src/canvas/lod/lod-switch.svelte

@@ -0,0 +1,140 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { useStore } from "@xyflow/svelte";
+import SideHandles from "../chrome/side-handles.svelte";
+import { lodMode } from "./lod-mode.svelte.js";
+import { renderAll } from "./render-all.svelte.js";
+
+// Zoomed out, a card is a box at its measured size, so no arrow moves.
+// Never measured, selected, dragged or exported: full.
+
+// =========================
+// TYPES
+// =========================
+interface Props {
+	id: string;
+	selected?: boolean;
+	dragging?: boolean;
+	/** A CSS colour: the card's own, for the box's border and icon well. */
+	tone: string;
+	title: string;
+	/** The full card. */
+	children: Snippet;
+}
+
+// =========================
+// PROPS
+// =========================
+let { id, selected = false, dragging = false, tone, title, children }: Props = $props();
+
+// =========================
+// STATE
+// =========================
+const store = useStore();
+const mode = lodMode(store);
+let probe = $state<HTMLElement>();
+// xyflow keeps the size of a card that scrolled away, so it comes back as a box.
+let size = $state<{ width: number; height: number } | null>(measured());
+// Plain on purpose: only the observer below reads it.
+let boxed = false;
+
+// =========================
+// DERIVED
+// =========================
+let simple = $derived(mode.low && size !== null && !selected && !dragging && !renderAll.on);
+
+// =========================
+// EFFECTS
+// =========================
+// Sizes the simple box from the full card. The observer's first call carries it, so a mount forces no layout.
+$effect(() => {
+	const node = probe?.closest<HTMLElement>(".svelte-flow__node");
+	if (!node) return;
+	const observer = new ResizeObserver(([entry]) => {
+		if (boxed) return;
+		const box = entry.borderBoxSize[0];
+		const width = Math.round(box.inlineSize);
+		const height = Math.round(box.blockSize);
+		if (width && height && (width !== size?.width || height !== size?.height)) size = { width, height };
+	});
+	observer.observe(node);
+	return () => observer.disconnect();
+});
+
+// Set after the render that swaps the box in, so the read above never sees the box's own size.
+$effect(() => {
+	boxed = simple;
+});
+
+// =========================
+// FUNCTIONS
+// =========================
+function measured(): { width: number; height: number } | null {
+	const known = store.nodeLookup.get(id)?.measured;
+	return known?.width && known.height ? { width: known.width, height: known.height } : null;
+}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<span class="cv-lod-probe" bind:this={probe} hidden></span>
+{#if simple && size}
+	<div class="cv-lod-box" style="width: {size.width}px; height: {size.height}px; --cv-lod-tone: {tone}" data-lod="simple">
+		<span class="cv-lod-well"></span>
+		<span class="cv-lod-title">{title}</span>
+	</div>
+	<SideHandles class="cv-lod-handle" />
+{:else}
+	{@render children()}
+{/if}
+
+<!-- =========================== -->
+<!-- STYLES -->
+<!-- =========================== -->
+<style>
+:global([data-cv-every-card] .svelte-flow__node) {
+	animation: none;
+}
+
+/* A dot on a zoomed-out box is too small to link from; unpainted, it keeps its place for the links. */
+:global(.cv-lod-handle) {
+	visibility: hidden;
+}
+
+/* The architecture card's own frame and layout (architecture-node.svelte), so selecting a card doesn't change how it looks. */
+.cv-lod-box {
+	position: relative;
+	box-sizing: border-box;
+	display: flex;
+	align-items: flex-start;
+	gap: 10px;
+	overflow: hidden;
+	padding: var(--card-pad, 12px);
+	border: 1px solid color-mix(in oklab, var(--cv-lod-tone) 20%, transparent);
+	border-radius: var(--card-radius, 12px);
+	background: var(--card, var(--cv-chrome-surface, #fff));
+	color: var(--cv-ink, var(--foreground, #1a1a1f));
+	contain: strict;
+}
+
+/* The icon well, without the icon. */
+.cv-lod-well {
+	flex: none;
+	width: 32px;
+	height: 32px;
+	border-radius: 9999px;
+	background: color-mix(in oklab, var(--cv-lod-tone) 10%, transparent);
+}
+
+.cv-lod-title {
+	overflow: hidden;
+	font-size: 14px;
+	font-weight: 500;
+	line-height: 1.25;
+	overflow-wrap: anywhere;
+}
+</style>

package/src/canvas/lod/render-all.svelte.ts

@@ -0,0 +1,52 @@
+import { tick } from "svelte";
+
+// An export reads the page's markup, so it holds this open: every card is drawn in full until it lets go.
+
+const hold = $state({ count: 0 });
+
+/** True while something needs every card drawn in full. */
+export const renderAll = {
+  get on(): boolean {
+    return hold.count > 0;
+  },
+};
+
+const frame = () => new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+// Arrows draw a beat after their cards, once the cards are measured, so they are counted too.
+const DRAWN = ".svelte-flow__node, .svelte-flow__edge";
+const SETTLE_FRAMES = 8;
+const GIVE_UP_MS = 4000;
+/** The page's card fade-in is switched off under this attribute, so a card that remounts is captured solid. */
+export const EVERY_CARD_ATTR = "data-cv-every-card";
+
+/** Runs `use` with every card drawn in full. Waits until the number of cards and arrows on the page holds still. */
+export async function withEveryCard<T>(root: ParentNode, use: () => Promise<T>): Promise<T> {
+  hold.count += 1;
+  const marked = root instanceof Element ? root : null;
+  marked?.setAttribute(EVERY_CARD_ATTR, "");
+  try {
+    await tick();
+    const start = performance.now();
+    let last = -1;
+    let still = 0;
+    while (still < SETTLE_FRAMES && performance.now() - start < GIVE_UP_MS) {
+      await frame();
+      const now = root.querySelectorAll(DRAWN).length;
+      still = now === last ? still + 1 : 0;
+      last = now;
+    }
+    // A fade that began before the switch-off still has to land.
+    if ("getAnimations" in root) {
+      const running = (root as Element).getAnimations({ subtree: true });
+      await Promise.race([
+        Promise.allSettled(running.map((animation) => animation.finished)),
+        new Promise((resolve) => setTimeout(resolve, 1000)),
+      ]);
+    }
+    await frame();
+    return await use();
+  } finally {
+    hold.count -= 1;
+    if (hold.count === 0) marked?.removeAttribute(EVERY_CARD_ATTR);
+  }
+}

package/src/canvas/ops/arrange.ts

@@ -0,0 +1,108 @@
+// Align, distribute and stack as pure maths, so the editor and the CLI place
+// nodes the same way.
+
+export interface ArrangeItem {
+  id: string;
+  position: { x: number; y: number };
+  width: number;
+  height: number;
+}
+
+export type Axis = "horizontal" | "vertical";
+
+export type Positions = Map<string, { x: number; y: number }>;
+
+export const ALIGNMENTS = [
+  "left",
+  "right",
+  "top",
+  "bottom",
+  "center-horizontal",
+  "center-vertical",
+] as const;
+
+export type Alignment = (typeof ALIGNMENTS)[number];
+
+// =========================
+// ALIGN
+// =========================
+
+/** "center-horizontal" puts the centres on one vertical axis, as tldraw named it. */
+export function alignPositions(items: readonly ArrangeItem[], alignment: Alignment): Positions {
+  const moved: Positions = new Map();
+  if (items.length < 2) return moved;
+  const left = Math.min(...items.map((item) => item.position.x));
+  const top = Math.min(...items.map((item) => item.position.y));
+  const right = Math.max(...items.map((item) => item.position.x + item.width));
+  const bottom = Math.max(...items.map((item) => item.position.y + item.height));
+
+  for (const item of items) {
+    const { x, y } = item.position;
+    const next = { x, y };
+    if (alignment === "left") next.x = left;
+    else if (alignment === "right") next.x = right - item.width;
+    else if (alignment === "top") next.y = top;
+    else if (alignment === "bottom") next.y = bottom - item.height;
+    else if (alignment === "center-horizontal") next.x = (left + right) / 2 - item.width / 2;
+    else next.y = (top + bottom) / 2 - item.height / 2;
+    if (next.x !== x || next.y !== y) moved.set(item.id, next);
+  }
+  return moved;
+}
+
+// =========================
+// DISTRIBUTE AND STACK
+// =========================
+
+function along(axis: Axis) {
+  const horizontal = axis === "horizontal";
+  return {
+    start: (item: ArrangeItem) => (horizontal ? item.position.x : item.position.y),
+    size: (item: ArrangeItem) => (horizontal ? item.width : item.height),
+    place: (item: ArrangeItem, at: number) =>
+      horizontal ? { x: at, y: item.position.y } : { x: item.position.x, y: at },
+  };
+}
+
+function inOrder(items: readonly ArrangeItem[], axis: Axis): ArrangeItem[] {
+  const { start } = along(axis);
+  return [...items].sort((a, b) => start(a) - start(b));
+}
+
+/** Space the boxes so every gap matches. The first and last stay where they are. */
+export function distributePositions(items: readonly ArrangeItem[], axis: Axis): Positions {
+  const moved: Positions = new Map();
+  if (items.length < 3) return moved;
+  const { start, size, place } = along(axis);
+  const sorted = inOrder(items, axis);
+  const first = sorted[0];
+  const last = sorted[sorted.length - 1];
+  if (!first || !last) return moved;
+  const span = start(last) + size(last) - start(first);
+  const used = sorted.reduce((sum, item) => sum + size(item), 0);
+  const gap = (span - used) / (sorted.length - 1);
+
+  let cursor = start(first);
+  for (const item of sorted) {
+    if (cursor !== start(item)) moved.set(item.id, place(item, cursor));
+    cursor += size(item) + gap;
+  }
+  return moved;
+}
+
+/** Put the boxes in a row or a column, `gap` apart, in the order they sit now. The first stays put. */
+export function stackPositions(items: readonly ArrangeItem[], axis: Axis, gap: number): Positions {
+  const moved: Positions = new Map();
+  if (items.length < 2) return moved;
+  const { start, size, place } = along(axis);
+  const sorted = inOrder(items, axis);
+  const first = sorted[0];
+  if (!first) return moved;
+
+  let cursor = start(first);
+  for (const item of sorted) {
+    if (cursor !== start(item)) moved.set(item.id, place(item, cursor));
+    cursor += size(item) + gap;
+  }
+  return moved;
+}

package/src/canvas/ops/ops.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vite-plus/test";
+import { z } from "zod";
+import type { OpDefinition } from "../plugin.js";
+import { CanvasOpError, applyOps, canvasOpSchema } from "./ops.js";
+
+const board = () => ({
+  nodes: [
+    { id: "a", type: "box", position: { x: 0, y: 0 }, data: { label: "A" } },
+    { id: "b", type: "box", position: { x: 10, y: 10 }, data: { label: "B" } },
+  ],
+  edges: [],
+});
+
+describe("applyOps", () => {
+  it("adds a parented node with its extent and rejects a duplicate id", () => {
+    const next = applyOps(board(), [
+      { kind: "addNode", node: { id: "c", type: "box", data: {}, parentId: "a" } },
+    ]);
+    expect(next.nodes.at(-1)).toMatchObject({ id: "c", parentId: "a", extent: "parent" });
+    expect(() =>
+      applyOps(board(), [{ kind: "addNode", node: { id: "a", type: "box", data: {} } }]),
+    ).toThrow(CanvasOpError);
+  });
+
+  it("merges a data patch and keeps the other fields", () => {
+    const next = applyOps(board(), [{ kind: "patchNode", nodeId: "a", data: { note: "x" } }]);
+    expect(next.nodes[0].data).toEqual({ label: "A", note: "x" });
+  });
+
+  it("removes a node with its edges", () => {
+    const withEdge = {
+      ...board(),
+      edges: [{ id: "e", source: "a", target: "b" }],
+    };
+    const next = applyOps(withEdge, [{ kind: "removeNode", nodeId: "a" }]);
+    expect(next.nodes.map((n) => n.id)).toEqual(["b"]);
+    expect(next.edges).toEqual([]);
+  });
+
+  it("re-points an edge with patchEdge and rejects a missing endpoint", () => {
+    const withEdge = { ...board(), edges: [{ id: "e", source: "a", target: "b" }] };
+    const next = applyOps(withEdge, [{ kind: "patchEdge", edgeId: "e", patch: { target: "a" } }]);
+    expect(next.edges[0]).toMatchObject({ id: "e", source: "a", target: "a" });
+    expect(() =>
+      applyOps(withEdge, [{ kind: "patchEdge", edgeId: "e", patch: { target: "gone" } }]),
+    ).toThrow(CanvasOpError);
+    expect(() =>
+      applyOps(withEdge, [{ kind: "patchEdge", edgeId: "e", patch: { source: "gone" } }]),
+    ).toThrow(CanvasOpError);
+  });
+
+  it("detaches a node with setParent null", () => {
+    const next = applyOps(board(), [
+      { kind: "setParent", nodeId: "b", parentId: "a" },
+      { kind: "setParent", nodeId: "b", parentId: null },
+    ]);
+    expect(next.nodes[1]).not.toHaveProperty("parentId");
+  });
+
+  it("names the op index on an error", () => {
+    try {
+      applyOps(board(), [
+        { kind: "moveNode", nodeId: "a", position: { x: 1, y: 1 } },
+        { kind: "removeNode", nodeId: "zzz" },
+      ]);
+      expect.unreachable();
+    } catch (e) {
+      expect((e as CanvasOpError).opIndex).toBe(1);
+    }
+  });
+
+  it("throws on a kind nobody registered", () => {
+    expect(() => applyOps(board(), [{ kind: "nope" }])).toThrow(/Unknown op kind/);
+  });
+
+  it("runs a plugin op beside the core ones", () => {
+    const rename = z.object({ kind: z.literal("rename"), nodeId: z.string(), label: z.string() });
+    const def: OpDefinition<z.infer<typeof rename>> = {
+      kind: "rename",
+      schema: rename,
+      apply: (state, op) => {
+        state.nodes = state.nodes.map((n) =>
+          n.id === op.nodeId ? { ...n, data: { ...(n.data as object), label: op.label } } : n,
+        );
+      },
+    };
+    const next = applyOps(board(), [{ kind: "rename", nodeId: "b", label: "Beta" }], [def]);
+    expect(next.nodes[1].data).toEqual({ label: "Beta" });
+  });
+});
+
+describe("canvasOpSchema", () => {
+  it("rejects an empty edge patch", () => {
+    expect(canvasOpSchema.safeParse({ kind: "patchEdge", edgeId: "e", patch: {} }).success).toBe(
+      false,
+    );
+  });
+});