@heyramzi/ui 1.54.2 → 2.0.0

package/src/canvas/README.md

@@ -0,0 +1,236 @@
+# @heyramzi/ui/canvas
+
+A canvas for Svelte 5 and SvelteKit, built on [@xyflow/svelte](https://svelteflow.dev). Cards and arrows from xyflow, a hand-drawing pen on top, and a plugin API for your own card types.
+
+Strokes, text and shapes are ordinary xyflow nodes. So undo, copy and save work with no extra code. The same ops run on a server or in a CLI, with no browser.
+
+MIT. It runs on any domain and costs nothing per install.
+
+## What's in it
+
+- **Pen layer.** Freehand strokes (perfect-freehand), a highlighter, an eraser, plain text, and rectangle, ellipse and diamond shapes. Colours are token names, so a board drawn in light mode reads fine in dark.
+- **Tool bar.** A floating bar with the tools, undo and redo. Pick from 6 colours and 3 brush sizes. Keys: V, H, P, M, E, T, R, O, D.
+- **Plugin API.** Register your own card types, ops and layout passes. One registry builds xyflow's `nodeTypes` for you.
+- **Ops.** 8 core ops (`addNode`, `removeNode`, `patchNode`, `moveNode`, `setParent`, `addEdge`, `removeEdge`, `patchEdge`) as plain functions over nodes and edges. Zod checks every one.
+- **Undo history.** `createCanvasDispatcher` wraps each edit in a transaction. A whole pen stroke is one undo step.
+- **Headless.** Everything that doesn't need a DOM, for servers and CLIs.
+
+## Install
+
+```sh
+npm install @heyramzi/ui @xyflow/svelte svelte
+```
+
+Peers: `svelte` ^5.57.2 and `@xyflow/svelte` ^1.7.0. The canvas is the one subpath whose peer you add yourself.
+
+The package ships Svelte source, so your app needs `@sveltejs/vite-plugin-svelte`. A SvelteKit app has it already.
+
+## Use it in SvelteKit
+
+Drop this in `src/routes/+page.svelte`.
+
+```svelte
+<script lang="ts">
+  import { Background, SvelteFlow, type Edge, type Node } from "@xyflow/svelte";
+  import "@xyflow/svelte/dist/style.css";
+  import { createCanvasDispatcher, createRegistry } from "@heyramzi/ui/canvas";
+  import { penUiPlugin } from "@heyramzi/ui/canvas/pen/ui.js";
+  import type { PenColor } from "@heyramzi/ui/canvas/pen/index.js";
+  import {
+    brushSize,
+    DEFAULT_BRUSH_LEVEL,
+    isDrawingTool,
+    type CanvasTool,
+  } from "@heyramzi/ui/canvas/ui/tools.js";
+  import CanvasToolbar from "@heyramzi/ui/canvas/ui/CanvasToolbar.svelte";
+  import PenLayer from "@heyramzi/ui/canvas/ui/PenLayer.svelte";
+
+  const registry = createRegistry([penUiPlugin]);
+
+  let nodes = $state.raw<Node[]>([]);
+  let edges = $state.raw<Edge[]>([]);
+  let tool = $state<CanvasTool>("select");
+  let color = $state<PenColor>("ink");
+  let level = $state(DEFAULT_BRUSH_LEVEL);
+
+  const history = createCanvasDispatcher({
+    getState: () => ({ nodes, edges }),
+    setState: (next) => {
+      nodes = next.nodes;
+      edges = next.edges;
+    },
+    // Save here. It fires once per commit, undo and redo.
+    onMutated: () => {},
+    opDefinitions: [...registry.ops.values()],
+  });
+
+  const labels = {
+    toolbar: "Canvas tools",
+    style: "Style",
+    tools: {
+      select: "Select", hand: "Hand", pen: "Pen", highlighter: "Highlighter",
+      eraser: "Eraser", text: "Text", rectangle: "Rectangle", ellipse: "Ellipse",
+      diamond: "Diamond", shapes: "Shapes",
+    },
+    colors: { ink: "Ink", red: "Red", blue: "Blue", green: "Green", amber: "Amber", violet: "Violet" },
+    sizes: ["Small", "Medium", "Large"],
+    undo: "Undo",
+    redo: "Redo",
+  } as const;
+</script>
+
+<div style="height: 100vh">
+  <SvelteFlow bind:nodes bind:edges nodeTypes={registry.nodeTypes()} fitView>
+    <Background />
+    {#if isDrawingTool(tool)}
+      <PenLayer
+        {tool}
+        {color}
+        size={brushSize(tool, level)}
+        {nodes}
+        commit={(ops) => history.dispatch(ops)}
+        startGesture={() => {
+          history.begin();
+          return history.commit;
+        }}
+      />
+    {/if}
+    <CanvasToolbar
+      bind:tool
+      bind:color
+      bind:level
+      {labels}
+      canUndo={history.canUndo}
+      canRedo={history.canRedo}
+      onUndo={history.undo}
+      onRedo={history.redo}
+    />
+  </SvelteFlow>
+</div>
+```
+
+Pick the pen tool, drag, and you've drawn a stroke. Press undo and it's gone. The whole gesture is one step.
+
+`PenLayer` and `CanvasToolbar` both read xyflow's store, so they go inside `<SvelteFlow>`. The tool bar takes a `labels` object because the package has no i18n. Pass your own strings.
+
+Components import by path:
+
+- `@heyramzi/ui/canvas/ui/CanvasToolbar.svelte`
+- `@heyramzi/ui/canvas/ui/PenLayer.svelte`
+- `@heyramzi/ui/canvas/ui/canvas-grid.svelte`, a dot grid that fades as you zoom out
+
+The tool bar's styles read your theme tokens (`--card`, `--border`, `--foreground`, `--ring`) and fall back to plain colours when you have none.
+
+## The plugin API
+
+A plugin is a name plus node kinds, ops and layout passes. Write it once for the server, then add the Svelte component for the browser. That's how the pen does it: `penPlugin` has no DOM, and `penUiPlugin` adds the renderers.
+
+```ts
+// invoice-plugin.ts, safe on a server
+import { z } from "zod";
+import { definePlugin, patchData, type OpState } from "@heyramzi/ui/canvas";
+
+const setTotal = z.object({
+  kind: z.literal("setTotal"),
+  nodeId: z.string().min(1),
+  total: z.number(),
+});
+
+function applySetTotal(state: OpState, op: z.infer<typeof setTotal>, opIndex: number) {
+  patchData(state, op.nodeId, opIndex, () => ({ total: op.total }));
+}
+
+export const invoicePlugin = definePlugin({
+  id: "invoice",
+  nodes: [
+    {
+      type: "invoice",
+      label: "Invoice",
+      size: { width: 240 },
+      palette: { group: "Billing", order: 1 },
+      createData: () => ({ total: 0 }),
+    },
+  ],
+  ops: [
+    { kind: "setTotal", schema: setTotal, apply: applySetTotal },
+  ],
+});
+```
+
+```ts
+// invoice-ui.ts, browser only
+import { definePlugin } from "@heyramzi/ui/canvas";
+import InvoiceCard from "./InvoiceCard.svelte";
+import { invoicePlugin } from "./invoice-plugin";
+
+export const invoiceUiPlugin = definePlugin({
+  ...invoicePlugin,
+  nodes: (invoicePlugin.nodes ?? []).map((kind) => ({ ...kind, component: InvoiceCard })),
+});
+```
+
+Then `createRegistry([penUiPlugin, invoiceUiPlugin])` gives you:
+
+- `nodeTypes()`, the map xyflow wants.
+- `ops`, to pass as `opDefinitions` to the dispatcher or `applyOps`.
+- `parseOp(input)`, which checks one op against its kind's schema.
+- `pickLayout(data)`, the first layout pass whose `matches` says yes.
+- `contentSizedTypes()` and `layoutOwnedTypes()`, so a layout knows which heights the DOM owns.
+
+A node type or op kind can have only one owner. If a second plugin claims one, `createRegistry` throws and names both.
+
+A node kind can also set `validParents` (which containers it may sit in) and `sizing`. A layout pass is `{ id, matches, run }`, and `run` returns the new nodes and edges.
+
+## The pen
+
+A stroke is a node with `type: "stroke"`. Its `data` holds the simplified points, a colour token, a size and a tool. Text is `"text"` and a shape is `"shape"`. They're real nodes, so the eraser, selection, copy and your save code treat them like cards.
+
+The pen is `PenOverlay` (or `PenLayer` inside xyflow), and it needs 2 callbacks from you:
+
+- `commit(ops)` receives `addNode` and `removeNode` ops. Send them to `history.dispatch`.
+- `startGesture()` opens an undo transaction and returns the function that closes it. A stroke is a single history step.
+
+The eraser removes whole strokes, never part of one. A swipe across a big shape doesn't wipe it.
+
+The pen has 6 colours: `ink`, `red`, `blue`, `green`, `amber` and `violet`. `pen.css` maps them to CSS variables with a light and a dark value. Dark mode applies under a `.dark` class on an ancestor or on `.svelte-flow`.
+
+## Headless ops
+
+Import from `@heyramzi/ui/canvas` on a server, in a worker or in a CLI. The root export touches no DOM.
+
+```ts
+import { applyOps, createRegistry, type RawCanvasData } from "@heyramzi/ui/canvas";
+import { penPlugin } from "@heyramzi/ui/canvas/pen/index.js";
+import { compilePenMark, penMarkSchema } from "@heyramzi/ui/canvas/headless/index.js";
+
+const registry = createRegistry([penPlugin]);
+
+let board: RawCanvasData = { nodes: [], edges: [] };
+
+// Ops from a request body or a CLI flag. An unknown kind or a bad shape throws.
+const ops = [
+  { kind: "addShape", shape: "rectangle", box: { x: 0, y: 0, width: 200, height: 120 }, label: "Intake" },
+  { kind: "addText", at: { x: 20, y: 160 }, text: "Where leads land" },
+].map((op) => registry.parseOp(op));
+
+board = applyOps(board, ops, [...registry.ops.values()]);
+```
+
+`applyOps` is pure. It returns a new board and never edits the one you pass. A bad op throws a `CanvasOpError` with the index of the op that failed, so you know which one in a list of 57.
+
+For a whole drawing in one call, write pen marks as JSON. There are 3 kinds: `stroke`, `text` and `shape`. They compile to the same nodes the pen tool draws.
+
+```ts
+const marks = penMarkSchema.array().parse(JSON.parse(input));
+const frames = new Map(); // frame id to { x, y }, if a mark uses `in`
+const nodes = marks.map((mark, i) => compilePenMark(mark, i, frames));
+board = { ...board, nodes: [...board.nodes, ...nodes] };
+```
+
+A mark with no `id` gets `pen-<n>` from its place in the list. Run the same file twice and you get the same ids.
+
+The root export also has the pure helpers the editor uses: edge anchors, alignment, snap guides, fit-to-viewport, table layout, SVG figure sanitising and the sketch (rough.js) geometry. Import what you need.
+
+## Develop
+
+Tests run in jsdom, so no browser. From the repo root, `pnpm --filter @heyramzi/ui test` runs them and `pnpm --filter @heyramzi/ui check` typechecks.

package/src/canvas/card/card-frame.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { getDiagramEditorContext } from "../editor/editor-context.js";
+import { isLocked } from "../editor/lock.js";
+import { userHeightOf, type CardResize } from "./resize.js";
+import ResizeHandles from "./resize-handles.svelte";
+import "./card.css";
+
+// The frame every card sits in: it keeps the saved height as a floor and draws the grips
+// on a selected card. A card whose policy is `false` has neither.
+
+// =========================
+// TYPES
+// =========================
+interface Props {
+	id: string;
+	data?: unknown;
+	selected?: boolean;
+	/** How this card type resizes, or false when its size isn't the person's to set. */
+	resize: CardResize | false;
+	children: Snippet;
+}
+
+// =========================
+// PROPS
+// =========================
+let { id, data, selected = false, resize, children }: Props = $props();
+
+// =========================
+// STATE
+// =========================
+const editor = getDiagramEditorContext();
+let frame = $state<HTMLElement>();
+
+// =========================
+// DERIVED
+// =========================
+let floor = $derived(userHeightOf(data));
+// A box card is sized by the node itself, so it needs no frame.
+let framed = $derived(!!resize && resize.store !== "box");
+let grips = $derived(!!resize && !!editor && selected && !isLocked({ data }));
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- The grips come first, so a link dot on the same edge stays on top of them. -->
+{#if resize && grips}
+	<ResizeHandles {id} {resize} {frame} />
+{/if}
+
+{#if framed}
+	<div class="cv-card-frame" bind:this={frame} style:--cv-card-h={floor > 0 ? `${floor}px` : undefined}>
+		{@render children()}
+	</div>
+{:else}
+	{@render children()}
+{/if}

package/src/canvas/card/card.css

@@ -0,0 +1,39 @@
+/* The card frame and its resize hit areas. Handle looks come from chrome.css. */
+
+/* A one-row grid: at least the saved height, growing with the content.
+   `min-height: 100%` shows a live drag at once. No position, so grips still anchor to the node. */
+.cv-card-frame {
+  display: grid;
+  grid-template-rows: minmax(var(--cv-card-h, 0px), auto);
+  min-height: 100%;
+}
+
+/* A drag drops the saved floor, so the card can shrink as well as grow. */
+.cv-card-frame[data-resizing] {
+  grid-template-rows: auto;
+}
+
+/* The edges are hit areas only, a finger wide at every zoom. */
+.svelte-flow .svelte-flow__resize-control.line.cv-edge {
+  border-width: 0;
+  background: transparent;
+}
+
+.svelte-flow .svelte-flow__resize-control.line.cv-edge:is(.left, .right) {
+  width: calc(10px * var(--canvas-unzoom, 1));
+}
+
+.svelte-flow .svelte-flow__resize-control.line.cv-edge:is(.top, .bottom) {
+  height: calc(10px * var(--canvas-unzoom, 1));
+}
+
+/* A text card's side grips are sideways-moving pills near the top of the edge, since the middle belongs to the connection dot. */
+.svelte-flow .svelte-flow__resize-control.handle.cv-grip-x {
+  top: calc(22px * var(--canvas-unzoom, 1)) !important;
+  /* Above the card's own positioned content, or half the pill hides behind it. */
+  z-index: 3;
+  width: 8px;
+  height: 20px;
+  border-radius: 9999px;
+  cursor: ew-resize;
+}

package/src/canvas/card/resize-handles.svelte

@@ -0,0 +1,119 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { NodeResizeControl, ResizeControlVariant, useSvelteFlow } from "@xyflow/svelte";
+import { getDiagramEditorContext } from "../editor/editor-context.js";
+import {
+	DEFAULT_MAX_WIDTH,
+	DEFAULT_MIN_HEIGHT,
+	DEFAULT_MIN_WIDTH,
+	keptHeight,
+	type CardResize,
+} from "./resize.js";
+import "./card.css";
+
+// The grips of a selected card. One drag is one undo step: width, kept height and extra data close together.
+
+// =========================
+// TYPES
+// =========================
+interface Props {
+	id: string;
+	resize: CardResize;
+	/** The framed element, read for the height its content needs. */
+	frame?: HTMLElement;
+}
+
+// =========================
+// CONSTANTS
+// =========================
+const CORNERS = ["top-left", "top-right", "bottom-left", "bottom-right"] as const;
+const EDGES = ["left", "right", "top", "bottom"] as const;
+const SIDES = ["left", "right"] as const;
+
+// =========================
+// PROPS
+// =========================
+let { id, resize, frame }: Props = $props();
+
+// =========================
+// STATE
+// =========================
+const editor = getDiagramEditorContext();
+const { updateNode } = useSvelteFlow();
+let endGesture: (() => void) | null = null;
+// The height the content needs, read when a drag starts.
+let contentHeight = $state(DEFAULT_MIN_HEIGHT);
+
+// =========================
+// DERIVED
+// =========================
+let both = $derived(resize.axes === "both");
+let ratio = $derived(resize.axes === "ratio");
+let direction = $derived(both || ratio ? undefined : ("horizontal" as const));
+let box = $derived(resize.store === "box");
+let minWidth = $derived(resize.minWidth ?? DEFAULT_MIN_WIDTH);
+let maxWidth = $derived(resize.maxWidth ?? DEFAULT_MAX_WIDTH);
+let minHeight = $derived(both && !box ? contentHeight : (resize.minHeight ?? DEFAULT_MIN_HEIGHT));
+
+// =========================
+// FUNCTIONS
+// =========================
+function measureContent() {
+	if (!frame) return;
+	// With the saved floor dropped, the frame is as tall as the content needs.
+	frame.setAttribute("data-resizing", "");
+	contentHeight = Math.max(DEFAULT_MIN_HEIGHT, Math.ceil(frame.offsetHeight));
+}
+
+function start() {
+	endGesture = editor?.startGesture() ?? null;
+	if (both && !box) measureContent();
+}
+
+function finish(size: { width: number; height: number }) {
+	frame?.removeAttribute("data-resizing");
+	const width = Math.round(size.width);
+	if (!box) {
+		editor?.setNodeWidth(id, width);
+		const patch: Record<string, unknown> = { ...resize.extraData?.({ width, height: size.height }) };
+		// A text card keeps growing with its words, and an image's height follows its width.
+		if (both) patch.userHeight = keptHeight(size.height, contentHeight);
+		if (Object.keys(patch).length > 0) editor?.patchNodeData(id, patch);
+		// The drag gave the node a height; the content and the saved floor size it from here.
+		updateNode(id, { height: undefined });
+	}
+	endGesture?.();
+	endGesture = null;
+}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+{#snippet control(position: (typeof CORNERS)[number] | (typeof EDGES)[number], variant: ResizeControlVariant)}
+	<NodeResizeControl
+		nodeId={id}
+		{position}
+		{variant}
+		{minWidth}
+		{maxWidth}
+		{minHeight}
+		keepAspectRatio={ratio}
+		resizeDirection={direction}
+		class={variant === ResizeControlVariant.Line ? "cv-edge" : direction ? "cv-grip cv-grip-x" : "cv-grip"}
+		onResizeStart={start}
+		onResizeEnd={(_, size) => finish(size)}
+	/>
+{/snippet}
+
+<!-- A text card moves only sideways, so it gets a grip on each side edge and no corners. -->
+{#each both || ratio ? EDGES : SIDES as edge (edge)}
+	{#if !ratio}
+		{@render control(edge, ResizeControlVariant.Line)}
+	{/if}
+{/each}
+{#each direction ? SIDES : CORNERS as grip (grip)}
+	{@render control(grip, ResizeControlVariant.Handle)}
+{/each}

package/src/canvas/card/resize.ts

@@ -0,0 +1,33 @@
+// How a card resizes. The host names one policy per card type; the frame and the handles read it.
+
+/** `both` saves `data.userHeight` as a floor. `width` is a text card. `ratio` keeps an image's shape. */
+export type CardResizeAxes = "both" | "width" | "ratio";
+
+/** Where the size lives. `content` cards size their own height; a `box` card has its size only on the node. */
+export type CardResizeStore = "content" | "box";
+
+export type CardResize = {
+  axes: CardResizeAxes;
+  /** Defaults to `content`. */
+  store?: CardResizeStore;
+  minWidth?: number;
+  maxWidth?: number;
+  minHeight?: number;
+  /** Extra data a finished resize writes with the size, in the same undo step. */
+  extraData?: (size: { width: number; height: number }) => Record<string, unknown>;
+};
+
+export const DEFAULT_MIN_WIDTH = 120;
+export const DEFAULT_MAX_WIDTH = 2400;
+export const DEFAULT_MIN_HEIGHT = 40;
+
+/** The saved floor height of a card, or 0 when its content sets the height. */
+export function userHeightOf(data: unknown): number {
+  const value = (data as { userHeight?: unknown } | null | undefined)?.userHeight;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/** The height a finished drag keeps: the dragged one, never under what the content needs. */
+export function keptHeight(dragged: number, content: number): number {
+  return Math.max(Math.round(dragged), Math.ceil(content));
+}

package/src/canvas/chrome/chrome-zoom.svelte

@@ -0,0 +1,120 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { useConnection, useStore } from "@xyflow/svelte";
+import { untrack } from "svelte";
+
+// A root `--canvas-unzoom` restyled every card per zoom frame. It lives only on nodes showing chrome: selected, hovered, or all while a link is dragged.
+
+// =========================
+// CONSTANTS
+// =========================
+const MIN_ZOOM = 0.05;
+const NODE = ".svelte-flow__node";
+
+// =========================
+// STATE
+// =========================
+const store = useStore();
+const connection = useConnection();
+
+// Plain collections: they change on selection and hover, never per frame, and nothing reads them reactively.
+const selected = new Set<HTMLElement>();
+let hovered: HTMLElement | null = null;
+
+// =========================
+// DERIVED
+// =========================
+let unzoom = $derived(String(1 / Math.max(store.viewport.zoom, MIN_ZOOM)));
+let linking = $derived(connection.current.inProgress);
+
+// =========================
+// FUNCTIONS
+// =========================
+const paint = (node: HTMLElement | null, value = unzoom) => node?.style.setProperty("--canvas-unzoom", value);
+
+function paintShowing(value: string) {
+	for (const node of selected) {
+		if (node.isConnected) paint(node, value);
+		else selected.delete(node);
+	}
+	paint(hovered, value);
+}
+
+// Chrome that belongs to one card (grips, quick-add) hides while several are selected: see chrome.css.
+function flagMulti() {
+	store.domNode?.toggleAttribute("data-cv-multi", selected.size > 1);
+}
+
+function track(node: HTMLElement) {
+	if (node.classList.contains("selected")) {
+		if (!selected.has(node)) {
+			selected.add(node);
+			paint(node);
+		}
+	} else selected.delete(node);
+	flagMulti();
+}
+
+// =========================
+// EFFECTS
+// =========================
+$effect(() => {
+	paintShowing(unzoom);
+});
+
+$effect(() => {
+	const root = store.domNode;
+	if (!root) return;
+	if (linking) {
+		root.dataset.cvLinking = "";
+		const value = unzoom;
+		for (const node of root.querySelectorAll<HTMLElement>(NODE)) paint(node, value);
+		return () => delete root.dataset.cvLinking;
+	}
+});
+
+function watch(root: HTMLElement) {
+	const over = (event: PointerEvent) => {
+		const node = (event.target as Element | null)?.closest<HTMLElement>(NODE) ?? null;
+		if (node === hovered) return;
+		hovered = node;
+		paint(node);
+	};
+	root.addEventListener("pointerover", over, { passive: true });
+
+	// A node picks up or loses the `selected` class when the selection changes, and arrives selected when pasted or created.
+	for (const node of root.querySelectorAll<HTMLElement>(`${NODE}.selected`)) track(node);
+	const classes = new MutationObserver((records) => {
+		for (const record of records) {
+			const node = record.target as HTMLElement;
+			if (node.matches(NODE)) track(node);
+		}
+	});
+	classes.observe(root, { attributes: true, attributeFilter: ["class"], subtree: true });
+	const arrivals = new MutationObserver((records) => {
+		for (const record of records) {
+			for (const added of record.addedNodes) {
+				if (added instanceof HTMLElement && added.matches(NODE)) track(added);
+			}
+		}
+	});
+	const layer = root.querySelector(".svelte-flow__nodes");
+	if (layer) arrivals.observe(layer, { childList: true });
+
+	return () => {
+		root.removeEventListener("pointerover", over);
+		classes.disconnect();
+		arrivals.disconnect();
+		selected.clear();
+		root.removeAttribute("data-cv-multi");
+	};
+}
+
+$effect(() => {
+	const root = store.domNode;
+	if (!root) return;
+	return untrack(() => watch(root));
+});
+</script>