@pixerate/editor-svelte 0.10.1 → 0.11.0

package/src/canvas/__tests__/canvas-multi-drag.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest';
+import { createCanvasMultiDrag } from '../createCanvasMultiDrag.svelte.js';
+import {
+	getMarqueeSelectionPreset,
+	handleDeselectOnEscape
+} from '../createCanvasSelection.svelte.js';
+import type { CanvasNode } from '../types.js';
+
+describe('createCanvasMultiDrag & Selection Helpers', () => {
+	const sampleNodes: CanvasNode[] = [
+		{ id: 'node-lead', position: { x: 100, y: 100 }, data: {} },
+		{ id: 'node-sub-1', position: { x: 100, y: 180 }, data: {} },
+		{ id: 'node-sub-2', position: { x: 100, y: 260 }, data: {} }
+	];
+
+	it('returns null and does not activate multi-drag if only 1 node is selected', () => {
+		const multiDrag = createCanvasMultiDrag();
+		const state = multiDrag.startMultiDrag('node-lead', ['node-lead'], sampleNodes);
+
+		expect(state).toBeNull();
+		expect(multiDrag.isMultiDrag).toBe(false);
+		expect(multiDrag.count).toBe(0);
+	});
+
+	it('computes relative follower offsets, stack fan-out, and rotational tilt for multi-selection', () => {
+		const multiDrag = createCanvasMultiDrag({
+			stackOffsetStepX: 5,
+			stackOffsetStepY: 6,
+			rotationAngles: [-2, 3]
+		});
+
+		const state = multiDrag.startMultiDrag(
+			'node-lead',
+			['node-lead', 'node-sub-1', 'node-sub-2'],
+			sampleNodes
+		);
+
+		expect(state).not.toBeNull();
+		expect(multiDrag.isMultiDrag).toBe(true);
+		expect(multiDrag.count).toBe(3);
+		expect(multiDrag.leadId).toBe('node-lead');
+
+		// Check follower 1
+		const f1 = multiDrag.getFollowerTransform('node-sub-1');
+		expect(f1.isFollower).toBe(true);
+		expect(f1.stackOffsetX).toBe(5);
+		expect(f1.stackOffsetY).toBe(6);
+		expect(f1.rotationDeg).toBe(-2);
+		expect(f1.zIndex).toBe(49); // baseZIndex (50) - 1
+
+		// Check follower 2
+		const f2 = multiDrag.getFollowerTransform('node-sub-2');
+		expect(f2.isFollower).toBe(true);
+		expect(f2.stackOffsetX).toBe(10);
+		expect(f2.stackOffsetY).toBe(12);
+		expect(f2.rotationDeg).toBe(3);
+		expect(f2.zIndex).toBe(48); // baseZIndex (50) - 2
+
+		// Non-follower check
+		const fLead = multiDrag.getFollowerTransform('node-lead');
+		expect(fLead.isFollower).toBe(false);
+	});
+
+	it('restores original positions upon drag cancellation', () => {
+		const multiDrag = createCanvasMultiDrag();
+		multiDrag.startMultiDrag(
+			'node-lead',
+			['node-lead', 'node-sub-1'],
+			sampleNodes
+		);
+
+		let restoredItems: any[] = [];
+		const restores = multiDrag.cancelMultiDrag((items) => {
+			restoredItems = items;
+		});
+
+		expect(restores).toHaveLength(1);
+		expect(restores[0].id).toBe('node-sub-1');
+		expect(restores[0].originalPosition).toEqual({ x: 100, y: 180 });
+		expect(restoredItems).toEqual(restores);
+		expect(multiDrag.isMultiDrag).toBe(false);
+	});
+
+	it('generates marquee selection preset with spacebar panning awareness', () => {
+		const normalPreset = getMarqueeSelectionPreset({ isSpacebarPanning: false });
+		expect(normalPreset.selectionOnDrag).toBe(true);
+		expect(normalPreset.panOnDrag).toEqual([1, 2]);
+
+		const panPreset = getMarqueeSelectionPreset({ isSpacebarPanning: true });
+		expect(panPreset.selectionOnDrag).toBe(false);
+		expect(panPreset.panOnDrag).toEqual([0, 1, 2]);
+	});
+
+	it('handles deselect on Escape key press', () => {
+		let deselected = false;
+		const handled = handleDeselectOnEscape(
+			{ key: 'Escape', code: 'Escape' } as KeyboardEvent,
+			() => {
+				deselected = true;
+			}
+		);
+
+		expect(handled).toBe(true);
+		expect(deselected).toBe(true);
+
+		const ignored = handleDeselectOnEscape(
+			{ key: 'Enter', code: 'Enter' } as KeyboardEvent,
+			() => {}
+		);
+		expect(ignored).toBe(false);
+	});
+});

package/src/canvas/__tests__/canvas-node-sync.svelte.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { flushSync } from 'svelte';
+import { Position } from '@xyflow/svelte';
+import {
+	preserveNodeMeasurements,
+	normalizeNodeHandles,
+	createCanvasNodeSync,
+	type HandleConfig
+} from '../createCanvasNodeSync.svelte.js';
+import type { CanvasNode } from '../types.js';
+
+describe('createCanvasNodeSync & Node Measurement Caching', () => {
+	it('preserves measured dimensions from existing nodes to newly created nodes', () => {
+		const existingNodes: CanvasNode[] = [
+			{
+				id: 'node-1',
+				position: { x: 100, y: 100 },
+				data: {},
+				measured: { width: 280, height: 160 }
+			} as any,
+			{
+				id: 'node-2',
+				position: { x: 200, y: 200 },
+				data: {}
+			} as any
+		];
+
+		const freshNodes: CanvasNode[] = [
+			{ id: 'node-1', position: { x: 100, y: 100 }, data: { title: 'Updated' } } as any,
+			{ id: 'node-2', position: { x: 200, y: 200 }, data: { title: 'Fresh' } } as any,
+			{ id: 'node-3', position: { x: 300, y: 300 }, data: { title: 'Brand New' } } as any
+		];
+
+		const preserved = preserveNodeMeasurements(freshNodes, existingNodes);
+
+		expect((preserved[0] as any).measured).toEqual({ width: 280, height: 160 });
+		expect((preserved[1] as any).measured).toBeUndefined();
+		expect((preserved[2] as any).measured).toBeUndefined();
+	});
+
+	it('normalizes node handles to prevent xyflow forceInitialRender selection flash', () => {
+		const rawNode: CanvasNode = {
+			id: 'node-1',
+			position: { x: 0, y: 0 },
+			data: {}
+		};
+
+		const defaultHandles: HandleConfig[] = [
+			{ id: null, type: 'target', position: Position.Left, x: 0, y: 50, width: 12, height: 12 },
+			{ id: null, type: 'source', position: Position.Right, x: 260, y: 50, width: 12, height: 12 }
+		];
+
+		const normalized = normalizeNodeHandles(rawNode, defaultHandles);
+
+		expect((normalized as any).handles).toHaveLength(2);
+		expect((normalized as any).handles[0].position).toBe(Position.Left);
+		expect((normalized as any).handles[1].position).toBe(Position.Right);
+	});
+
+	it('synchronizes domain items to nodes and edges while caching measurements across ticks', () => {
+		let domainItems = [
+			{ id: 'item-1', name: 'Task 1', dependencies: [] },
+			{ id: 'item-2', name: 'Task 2', dependencies: ['item-1'] }
+		];
+
+		let sync: ReturnType<typeof createCanvasNodeSync<any>>;
+
+		const cleanup = $effect.root(() => {
+			sync = createCanvasNodeSync({
+				items: () => domainItems,
+				toNode: (item) => ({
+					id: item.id,
+					position: { x: 10, y: 20 },
+					data: { label: item.name }
+				}),
+				toEdges: (items) =>
+					items.flatMap((item) =>
+						item.dependencies.map((depId) => ({
+							id: `edge-${depId}-${item.id}`,
+							source: depId,
+							target: item.id
+						}))
+					),
+				defaultHandles: () => [
+					{ id: 'in', type: 'target', position: Position.Left },
+					{ id: 'out', type: 'source', position: Position.Right }
+				]
+			});
+		});
+
+		flushSync();
+
+		expect(sync!.nodes).toHaveLength(2);
+		expect(sync!.edges).toHaveLength(1);
+		expect(sync!.edges[0].id).toBe('edge-item-1-item-2');
+		expect((sync!.nodes[0] as any).handles).toHaveLength(2);
+
+		// Simulate xyflow measuring node-1
+		sync!.updateNodeMeasurements('item-1', 250, 120);
+		expect((sync!.nodes[0] as any).measured).toEqual({ width: 250, height: 120 });
+
+		cleanup();
+	});
+});

package/src/canvas/createCanvasMultiDrag.svelte.ts

@@ -0,0 +1,175 @@
+import type { XYPosition } from '@xyflow/svelte';
+import type { CanvasNode } from './types.js';
+
+export interface MultiDragFollowerOffset {
+	deltaX: number;
+	deltaY: number;
+	originalPosition: XYPosition;
+	stackOffsetX: number;
+	stackOffsetY: number;
+	rotationDeg: number;
+}
+
+export interface MultiDragState {
+	leadId: string;
+	offsets: Record<string, MultiDragFollowerOffset>;
+	count: number;
+}
+
+export interface CreateCanvasMultiDragOptions {
+	/**
+	 * Base horizontal fan-out offset per stacked follower card (default: 4px).
+	 */
+	stackOffsetStepX?: number;
+	/**
+	 * Base vertical fan-out offset per stacked follower card (default: 4px).
+	 */
+	stackOffsetStepY?: number;
+	/**
+	 * Alternating angular tilt in degrees for follower cards (default: [-2, 2.5, -3, 3]).
+	 */
+	rotationAngles?: number[];
+	/**
+	 * Base z-index for stacked cards during active dragging (default: 50).
+	 */
+	baseZIndex?: number;
+}
+
+export interface FollowerTransform {
+	isFollower: boolean;
+	stackOffsetX: number;
+	stackOffsetY: number;
+	rotationDeg: number;
+	zIndex: number;
+}
+
+/**
+ * Headless Svelte 5 rune orchestrating multi-node drag operations with stacked visual fanning,
+ * dynamic z-index layering, and position restoration.
+ */
+export function createCanvasMultiDrag(options: CreateCanvasMultiDragOptions = {}) {
+	const stepX = options.stackOffsetStepX ?? 4;
+	const stepY = options.stackOffsetStepY ?? 4;
+	const angles = options.rotationAngles ?? [-2, 2.5, -3, 3];
+	const baseZIndex = options.baseZIndex ?? 50;
+
+	let dragState = $state<MultiDragState | null>(null);
+
+	function startMultiDrag(
+		leadNodeId: string,
+		selectedNodeIds: string[] | Set<string>,
+		nodes: CanvasNode[] | Map<string, CanvasNode>
+	): MultiDragState | null {
+		const selectedSet =
+			selectedNodeIds instanceof Set ? selectedNodeIds : new Set(selectedNodeIds);
+
+		if (selectedSet.size <= 1 || !selectedSet.has(leadNodeId)) {
+			dragState = null;
+			return null;
+		}
+
+		const nodeMap =
+			nodes instanceof Map ? nodes : new Map(nodes.map((n) => [n.id, n]));
+
+		const leadNode = nodeMap.get(leadNodeId);
+		if (!leadNode) {
+			dragState = null;
+			return null;
+		}
+
+		const leadPos = leadNode.position ?? { x: 0, y: 0 };
+		const offsets: Record<string, MultiDragFollowerOffset> = {};
+		let followerIndex = 0;
+
+		for (const id of selectedSet) {
+			if (id === leadNodeId) continue;
+			const follower = nodeMap.get(id);
+			const fPos = follower?.position ?? { x: 0, y: 0 };
+
+			const angle = angles[followerIndex % angles.length];
+			offsets[id] = {
+				deltaX: fPos.x - leadPos.x,
+				deltaY: fPos.y - leadPos.y,
+				originalPosition: { ...fPos },
+				stackOffsetX: (followerIndex + 1) * stepX,
+				stackOffsetY: (followerIndex + 1) * stepY,
+				rotationDeg: angle
+			};
+			followerIndex++;
+		}
+
+		const state: MultiDragState = {
+			leadId: leadNodeId,
+			offsets,
+			count: selectedSet.size
+		};
+
+		dragState = state;
+		return state;
+	}
+
+	function getFollowerTransform(nodeId: string): FollowerTransform {
+		if (!dragState || !(nodeId in dragState.offsets)) {
+			return {
+				isFollower: false,
+				stackOffsetX: 0,
+				stackOffsetY: 0,
+				rotationDeg: 0,
+				zIndex: 0
+			};
+		}
+
+		const offset = dragState.offsets[nodeId];
+		const followerKeys = Object.keys(dragState.offsets);
+		const index = followerKeys.indexOf(nodeId);
+
+		return {
+			isFollower: true,
+			stackOffsetX: offset.stackOffsetX,
+			stackOffsetY: offset.stackOffsetY,
+			rotationDeg: offset.rotationDeg,
+			zIndex: baseZIndex - (index + 1)
+		};
+	}
+
+	function cancelMultiDrag(
+		applyRestore?: (restores: { id: string; originalPosition: XYPosition }[]) => void
+	): { id: string; originalPosition: XYPosition }[] {
+		if (!dragState) return [];
+
+		const restores = Object.entries(dragState.offsets).map(([id, offset]) => ({
+			id,
+			originalPosition: { ...offset.originalPosition }
+		}));
+
+		if (applyRestore) {
+			applyRestore(restores);
+		}
+
+		dragState = null;
+		return restores;
+	}
+
+	function commitMultiDrag(): void {
+		dragState = null;
+	}
+
+	return {
+		get dragState() {
+			return dragState;
+		},
+		get isMultiDrag() {
+			return Boolean(dragState && dragState.count > 1);
+		},
+		get count() {
+			return dragState ? dragState.count : 0;
+		},
+		get leadId() {
+			return dragState?.leadId ?? null;
+		},
+		startMultiDrag,
+		getFollowerTransform,
+		cancelMultiDrag,
+		commitMultiDrag
+	};
+}

package/src/canvas/createCanvasNodeSync.svelte.ts

@@ -0,0 +1,150 @@
+import { untrack } from 'svelte';
+import type { Position } from '@xyflow/svelte';
+import type { CanvasNode, CanvasEdge } from './types.js';
+
+export interface HandleConfig {
+	id?: string | null;
+	type: 'source' | 'target';
+	position: Position;
+	x?: number;
+	y?: number;
+	width?: number;
+	height?: number;
+}
+
+export interface NodeMeasurement {
+	width: number;
+	height: number;
+}
+
+/**
+ * Preserves cached .measured dimensions from existing nodes to newly constructed nodes.
+ * Resolves measurements without subscribing to reactive updates on the existing collection.
+ */
+export function preserveNodeMeasurements<TNode extends CanvasNode = CanvasNode>(
+	newNodes: TNode[],
+	existingNodes: TNode[] | Map<string, TNode>
+): TNode[] {
+	const map =
+		existingNodes instanceof Map
+			? existingNodes
+			: new Map(existingNodes.map((n) => [n.id, n]));
+
+	for (const node of newNodes) {
+		const prev = map.get(node.id);
+		if (prev && (prev as any).measured) {
+			(node as any).measured = { ...(prev as any).measured };
+		}
+	}
+	return newNodes;
+}
+
+/**
+ * Pre-populates handle geometry on a node to prevent @xyflow/system's getNodesInside
+ * from evaluating `forceInitialRender = !node.internals.handleBounds` and triggering
+ * a false full-canvas selection on the first frame of marquee drag-selection.
+ */
+export function normalizeNodeHandles<TNode extends CanvasNode = CanvasNode>(
+	node: TNode,
+	handles: HandleConfig[] = []
+): TNode {
+	(node as any).handles = handles;
+	return node;
+}
+
+export interface CreateCanvasNodeSyncOptions<
+	TItem,
+	TNode extends CanvasNode = CanvasNode,
+	TEdge extends CanvasEdge = CanvasEdge
+> {
+	/**
+	 * Reactive getter returning raw domain items.
+	 */
+	items: () => TItem[];
+	/**
+	 * Factory function converting a domain item into a CanvasNode.
+	 */
+	toNode: (
+		item: TItem,
+		index: number,
+		context: { existingNode?: TNode; prevNodesMap: Map<string, TNode> }
+	) => TNode;
+	/**
+	 * Optional factory function converting domain items and generated nodes into CanvasEdges.
+	 */
+	toEdges?: (items: TItem[], nodes: TNode[]) => TEdge[];
+	/**
+	 * Optional default handle configuration provider for connectable nodes.
+	 */
+	defaultHandles?: (node: TNode) => HandleConfig[] | undefined;
+}
+
+/**
+ * Headless Svelte 5 rune that synchronizes reactive domain items with SvelteFlow nodes/edges,
+ * automatically untracking previous node reads, caching .measured dimensions, and normalizing
+ * handle bounds to prevent Svelte 5 effect_update_depth_exceeded and marquee drag flashes.
+ */
+export function createCanvasNodeSync<
+	TItem,
+	TNode extends CanvasNode = CanvasNode,
+	TEdge extends CanvasEdge = CanvasEdge
+>(options: CreateCanvasNodeSyncOptions<TItem, TNode, TEdge>) {
+	let nodes = $state<TNode[]>([]);
+	let edges = $state<TEdge[]>([]);
+
+	$effect.pre(() => {
+		const rawItems = options.items();
+
+		// Untrack the read of current nodes to avoid recursive effect loops
+		const existingNodesMap = untrack(() => new Map(nodes.map((n) => [n.id, n])));
+
+		const newNodes = rawItems.map((item, index) => {
+			const existing = existingNodesMap.get((item as any)?.id);
+			const node = options.toNode(item, index, {
+				existingNode: existing,
+				prevNodesMap: existingNodesMap
+			});
+
+			// Automatically preserve measured dimensions if available
+			if (existing && (existing as any).measured && !(node as any).measured) {
+				(node as any).measured = { ...(existing as any).measured };
+			}
+
+			// Pre-populate handles if provided
+			if (options.defaultHandles && !(node as any).handles) {
+				const handles = options.defaultHandles(node);
+				if (handles) {
+					(node as any).handles = handles;
+				}
+			}
+
+			return node;
+		});
+
+		const newEdges = options.toEdges ? options.toEdges(rawItems, newNodes) : [];
+
+		nodes = newNodes;
+		edges = newEdges;
+	});
+
+	return {
+		get nodes() {
+			return nodes;
+		},
+		set nodes(value: TNode[]) {
+			nodes = value;
+		},
+		get edges() {
+			return edges;
+		},
+		set edges(value: TEdge[]) {
+			edges = value;
+		},
+		updateNodeMeasurements(id: string, width: number, height: number) {
+			const node = nodes.find((n) => n.id === id);
+			if (node) {
+				(node as any).measured = { width, height };
+			}
+		}
+	};
+}

package/src/canvas/createCanvasSelection.svelte.ts

@@ -0,0 +1,51 @@
+import type { CanvasInteractionPresetConfig } from './types.js';
+
+export interface CanvasSelectionOptions {
+	/**
+	 * Whether spacebar panning is currently active (suspends marquee selection).
+	 */
+	isSpacebarPanning?: boolean;
+	/**
+	 * Selection mode: 'partial' (default) selects nodes intersected by selection box,
+	 * 'full' requires nodes to be fully enclosed.
+	 */
+	selectionMode?: 'partial' | 'full';
+	/**
+	 * Additional keys that trigger multi-selection (default: ['Shift', 'Meta']).
+	 */
+	multiSelectionKey?: string[];
+}
+
+/**
+ * Generates an interaction preset configured for left-click marquee drag-selection
+ * while preserving middle-mouse and spacebar panning.
+ */
+export function getMarqueeSelectionPreset(
+	options: CanvasSelectionOptions = {}
+): CanvasInteractionPresetConfig {
+	const isSpacebarPanning = options.isSpacebarPanning ?? false;
+
+	return {
+		snapGrid: [25, 25],
+		panOnDrag: isSpacebarPanning ? [0, 1, 2] : [1, 2],
+		panOnScroll: false,
+		selectionOnDrag: !isSpacebarPanning,
+		colorMode: 'system' as any,
+		multiSelectionKey: options.multiSelectionKey ?? ['Shift', 'Meta'],
+		selectionMode: (options.selectionMode ?? 'partial') as any
+	};
+}
+
+/**
+ * Keyboard listener helper to deselect nodes on Escape.
+ */
+export function handleDeselectOnEscape(
+	event: KeyboardEvent,
+	onDeselect: () => void
+): boolean {
+	if (event.key === 'Escape' || event.code === 'Escape') {
+		onDeselect();
+		return true;
+	}
+	return false;
+}