@pixerate/editor-svelte 0.4.0 → 0.5.1

package/src/canvas/createCanvasTrajectory.ts

@@ -0,0 +1,188 @@
+import { cubicOut } from 'svelte/easing';
+import type { XYPosition } from '@xyflow/svelte';
+import type {
+	CanvasNode,
+	FanOutTrajectoryOptions,
+	NodeTransition,
+	TrajectoryFunction,
+	TrajectoryPoint
+} from './types.js';
+
+/**
+ * Standard linear trajectory: straight line interpolation with linear scale & opacity progression.
+ */
+export const linearTrajectory: TrajectoryFunction = (
+	origin: XYPosition,
+	target: XYPosition,
+	progress: number
+): TrajectoryPoint => {
+	return {
+		position: {
+			x: origin.x + (target.x - origin.x) * progress,
+			y: origin.y + (target.y - origin.y) * progress
+		},
+		scale: progress,
+		opacity: Math.min(1, progress * 1.5)
+	};
+};
+
+/**
+ * Creates a fan-out trajectory where nodes arc outward from origin to target.
+ * Matches the curved distribution shown in multi-node branching diagrams.
+ */
+export function createFanOutTrajectory(options: FanOutTrajectoryOptions = {}): TrajectoryFunction {
+	const {
+		curvature = 0.4,
+		startScale = 0,
+		endScale = 1,
+		startOpacity = 0,
+		endOpacity = 1
+	} = options;
+
+	return (
+		origin: XYPosition,
+		target: XYPosition,
+		progress: number,
+		index: number,
+		total: number
+	): TrajectoryPoint => {
+		const dx = target.x - origin.x;
+		const dy = target.y - origin.y;
+
+		// Normalized index from -1 (top) to +1 (bottom)
+		const normIndex = total > 1 ? (index - (total - 1) / 2) / ((total - 1) / 2) : 0;
+
+		// Perpendicular control point offset to create smooth fan arc
+		const midX = origin.x + dx * 0.4;
+		const midY = origin.y + dy * 0.1 - normIndex * Math.abs(dx) * 0.15 * curvature;
+
+		// Quadratic Bezier interpolation: B(t) = (1-t)^2 * P0 + 2(1-t)t * P1 + t^2 * P2
+		const t = progress;
+		const oneMinusT = 1 - t;
+
+		const x = oneMinusT * oneMinusT * origin.x + 2 * oneMinusT * t * midX + t * t * target.x;
+		const y = oneMinusT * oneMinusT * origin.y + 2 * oneMinusT * t * midY + t * t * target.y;
+
+		const scale = startScale + (endScale - startScale) * progress;
+		const opacity = startOpacity + (endOpacity - startOpacity) * progress;
+
+		return {
+			position: { x, y },
+			scale,
+			opacity
+		};
+	};
+}
+
+/**
+ * Creates a custom quadratic Bezier trajectory with a specified or dynamically calculated control point.
+ */
+export function createBezierTrajectory(
+	getControlPoint: (origin: XYPosition, target: XYPosition) => XYPosition
+): TrajectoryFunction {
+	return (origin: XYPosition, target: XYPosition, progress: number): TrajectoryPoint => {
+		const cp = getControlPoint(origin, target);
+		const t = progress;
+		const oneMinusT = 1 - t;
+
+		const x = oneMinusT * oneMinusT * origin.x + 2 * oneMinusT * t * cp.x + t * t * target.x;
+		const y = oneMinusT * oneMinusT * origin.y + 2 * oneMinusT * t * cp.y + t * t * target.y;
+
+		return {
+			position: { x, y },
+			scale: progress,
+			opacity: progress
+		};
+	};
+}
+
+/**
+ * Coordinates and animates multiple node transitions simultaneously with zero per-frame array allocations.
+ * Directly mutates node positions and data (scale, opacity) in-place during the animation loop.
+ */
+export function runMultiNodeTransition<TNode extends CanvasNode = CanvasNode>(
+	transitions: NodeTransition<TNode>[],
+	options: {
+		defaultDuration?: number;
+		defaultEasing?: (t: number) => number;
+		onUpdate?: () => void;
+		onComplete?: () => void;
+	} = {}
+): () => void {
+	if (transitions.length === 0) {
+		options.onComplete?.();
+		return () => {};
+	}
+
+	const { defaultDuration = 400, defaultEasing = cubicOut, onUpdate, onComplete } = options;
+
+	let isCancelled = false;
+	const startTime = Date.now();
+
+	const items = transitions.map((tr, i) => ({
+		...tr,
+		index: tr.index ?? i,
+		total: tr.total ?? transitions.length,
+		duration: tr.duration ?? defaultDuration,
+		easing: tr.easing ?? defaultEasing,
+		delay: tr.delay ?? 0,
+		trajectory: tr.trajectory ?? linearTrajectory
+	}));
+
+	function frame() {
+		if (isCancelled) return;
+
+		const now = Date.now();
+		let allCompleted = true;
+
+		for (let i = 0; i < items.length; i++) {
+			const item = items[i];
+			const elapsed = now - (startTime + item.delay);
+
+			if (elapsed < 0) {
+				allCompleted = false;
+				continue;
+			}
+
+			const rawProgress = item.duration <= 0 ? 1 : Math.min(elapsed / item.duration, 1);
+			const progress = item.duration <= 0 ? 1 : item.easing(rawProgress);
+
+			const point = item.trajectory(item.from, item.to, progress, item.index, item.total);
+
+			// Direct in-place mutation avoids array reconstruction during RAF
+			item.node.position = { ...point.position };
+
+			if (point.scale !== undefined || point.opacity !== undefined) {
+				if (!item.node.data) {
+					item.node.data = {} as any;
+				}
+				if (point.scale !== undefined) {
+					(item.node.data as any).scale = point.scale;
+				}
+				if (point.opacity !== undefined) {
+					(item.node.data as any).opacity = point.opacity;
+				}
+			}
+
+			if (rawProgress < 1) {
+				allCompleted = false;
+			}
+		}
+
+		onUpdate?.();
+
+		if (!allCompleted) {
+			if (typeof requestAnimationFrame !== 'undefined') {
+				requestAnimationFrame(frame);
+			}
+		} else {
+			onComplete?.();
+		}
+	}
+
+	frame();
+
+	return () => {
+		isCancelled = true;
+	};
+}

package/src/canvas/index.d.ts

@@ -95,6 +95,123 @@ export interface CanvasInteractionPresetConfig {
   maxZoom?: number;
 }
 
+/**
+ * Parametric point returned by a trajectory evaluation.
+ */
+export interface TrajectoryPoint {
+  position: XYPosition;
+  scale?: number;
+  opacity?: number;
+}
+
+/**
+ * Trajectory evaluation function determining path, scale, and opacity over time t in [0, 1].
+ */
+export type TrajectoryFunction = (
+  origin: XYPosition,
+  target: XYPosition,
+  progress: number,
+  index: number,
+  total: number
+) => TrajectoryPoint;
+
+/**
+ * Options for fan-out trajectory generator.
+ */
+export interface FanOutTrajectoryOptions {
+  curvature?: number;
+  spreadAngle?: number;
+  startScale?: number;
+  endScale?: number;
+  startOpacity?: number;
+  endOpacity?: number;
+}
+
+/**
+ * Single node animation transition definition.
+ */
+export interface NodeTransition<TNode extends CanvasNode = CanvasNode> {
+  node: TNode;
+  from: XYPosition;
+  to: XYPosition;
+  trajectory?: TrajectoryFunction;
+  delay?: number;
+  duration?: number;
+  easing?: (t: number) => number;
+  index?: number;
+  total?: number;
+}
+
+/**
+ * Displacement axis / direction.
+ */
+export type DisplacementDirection = 'right' | 'left' | 'down' | 'up' | 'vertical';
+
+/**
+ * Options for directional displacement calculation.
+ */
+export interface DirectionalDisplacementOptions {
+  direction?: DisplacementDirection;
+  gap?: number;
+  spreadSiblingLanes?: boolean;
+  siblingTolerance?: number;
+  minY?: number;
+}
+
+/**
+ * Options for Dagre reflow displacement calculation.
+ */
+export interface ReflowDisplacementOptions extends CanvasLayoutOptions {
+  anchorNodeId: string;
+}
+
+/**
+ * Snapshot of canvas graph state prior to node explosion, enabling exact reversibility.
+ */
+export interface ExplosionSnapshot<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+> {
+  parentId: string;
+  childNodeIds: string[];
+  childEdgeIds: string[];
+  displacedNodes: { id: string; originalPosition: XYPosition }[];
+  timestamp: number;
+}
+
+/**
+ * Options for exploding a node.
+ */
+export interface ExplodeNodeOptions<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+> {
+  childNodes: TNode[];
+  childEdges?: TEdge[];
+  connectParentToChildren?: boolean | 'first' | 'all';
+  connectChildrenToDownstream?: boolean;
+  displacementStrategy?: 'directional' | 'dagre' | 'none';
+  directionalOptions?: DirectionalDisplacementOptions;
+  reflowOptions?: Partial<ReflowDisplacementOptions>;
+  trajectory?: TrajectoryFunction;
+  duration?: number;
+  staggerDelay?: number;
+  easing?: (t: number) => number;
+  onComplete?: () => void;
+}
+
+/**
+ * Options for collapsing an exploded node.
+ */
+export interface CollapseNodeOptions {
+  duration?: number;
+  staggerDelay?: number;
+  easing?: (t: number) => number;
+  trajectory?: TrajectoryFunction;
+  onComplete?: () => void;
+}
+
+
 /**
  * Pure calculation of graph differences between a current state and a baseline state.
  */
@@ -343,3 +460,114 @@ export declare const miroCompatiblePreset: CanvasInteractionPresetConfig;
  * Helper to ensure panels restore pointer events after selection rectangle releases.
  */
 export declare function restorePanelPointerEvents(panelSelector?: string): void;
+
+/**
+ * Standard linear trajectory: straight line interpolation with linear scale & opacity progression.
+ */
+export declare const linearTrajectory: TrajectoryFunction;
+
+/**
+ * Creates a fan-out trajectory where nodes arc outward from origin to target.
+ */
+export declare function createFanOutTrajectory(options?: FanOutTrajectoryOptions): TrajectoryFunction;
+
+/**
+ * Creates a custom quadratic Bezier trajectory with a specified or dynamically calculated control point.
+ */
+export declare function createBezierTrajectory(
+  getControlPoint: (origin: XYPosition, target: XYPosition) => XYPosition
+): TrajectoryFunction;
+
+/**
+ * Coordinates and animates multiple node transitions simultaneously with zero per-frame array allocations.
+ */
+export declare function runMultiNodeTransition<TNode extends CanvasNode = CanvasNode>(
+  transitions: NodeTransition<TNode>[],
+  options?: {
+    defaultDuration?: number;
+    defaultEasing?: (t: number) => number;
+    onUpdate?: () => void;
+    onComplete?: () => void;
+  }
+): () => void;
+
+/**
+ * Calculates a bounding rectangle for a set of nodes.
+ */
+export declare function computeNodesBoundingBox<TNode extends CanvasNode = CanvasNode>(
+  nodes: TNode[],
+  defaultWidth?: number,
+  defaultHeight?: number
+): Rect;
+
+/**
+ * Pure directional displacement calculation.
+ */
+export declare function calculateDirectionalDisplacement<TNode extends CanvasNode = CanvasNode>(params: {
+  existingNodes: TNode[];
+  originNode: TNode;
+  childNodes: TNode[];
+  getNodesBounds?: (nodes: TNode[]) => Rect;
+  options?: DirectionalDisplacementOptions;
+}): Map<string, XYPosition>;
+
+/**
+ * Pure hierarchical Dagre reflow displacement calculation.
+ */
+export declare function calculateReflowDisplacement<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+>(params: {
+  existingNodes: TNode[];
+  existingEdges: TEdge[];
+  originNode: TNode;
+  childNodes: TNode[];
+  childEdges?: TEdge[];
+  getNodesBounds?: (nodes: TNode[]) => Rect;
+  options?: CanvasLayoutOptions;
+}): Map<string, XYPosition>;
+
+export interface CanvasGraphTarget<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+> {
+  nodes: TNode[];
+  edges: TEdge[];
+  setNodes: (nodes: TNode[], triggerCallback?: boolean) => void;
+  setEdges: (edges: TEdge[], triggerCallback?: boolean) => void;
+  addNodeOrNodes: (nodes: TNode | TNode[], animateFrom?: XYPosition, save?: boolean) => void;
+  addEdges: (edges: TEdge[], save?: boolean) => void;
+  removeNodes: (nodes: TNode[], save?: boolean) => void;
+  removeEdges: (edges: TEdge[], save?: boolean) => void;
+  createEdge?: (sourceId: string, targetId: string, options?: any) => TEdge;
+  onSave?: () => void;
+}
+
+export interface CreateCanvasExplosionOptions<TNode extends CanvasNode = CanvasNode> {
+  getNodesBounds?: (nodes: TNode[]) => Rect;
+  onSave?: () => void;
+}
+
+/**
+ * Headless Svelte 5 rune managing canvas node explosion, spatial layout displacement,
+ * coordinated multi-node animation paths, and reversible collapsing.
+ */
+export declare function createCanvasExplosion<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+>(
+  graph: CanvasGraphTarget<TNode, TEdge>,
+  options?: CreateCanvasExplosionOptions<TNode>
+): {
+  readonly explodedNodeIds: string[];
+  isExploded(nodeId: string): boolean;
+  explodeNode(parentId: string, explodeOptions: ExplodeNodeOptions<TNode, TEdge>): boolean;
+  collapseNode(parentId: string, collapseOptions?: CollapseNodeOptions): boolean;
+  toggleExplode(
+    parentId: string,
+    explodeOptions: ExplodeNodeOptions<TNode, TEdge>,
+    collapseOptions?: CollapseNodeOptions
+  ): boolean;
+  getSnapshot(parentId: string): ExplosionSnapshot<TNode, TEdge> | undefined;
+};
+

package/src/canvas/index.ts

@@ -44,3 +44,25 @@ export {
 	restorePanelPointerEvents,
 	type CreateCanvasInteractionsOptions
 } from './createCanvasInteractions.svelte.js';
+
+// Trajectory calculation & multi-node transitions
+export {
+	linearTrajectory,
+	createFanOutTrajectory,
+	createBezierTrajectory,
+	runMultiNodeTransition
+} from './createCanvasTrajectory.js';
+
+// Spatial layout displacement
+export {
+	computeNodesBoundingBox,
+	calculateDirectionalDisplacement,
+	calculateReflowDisplacement
+} from './createCanvasDisplacement.js';
+
+// Node explosion & collapse rune
+export {
+	createCanvasExplosion,
+	type CanvasGraphTarget,
+	type CreateCanvasExplosionOptions
+} from './createCanvasExplosion.svelte.js';

package/src/canvas/types.ts

@@ -94,3 +94,120 @@ export interface CanvasInteractionPresetConfig {
 	minZoom?: number;
 	maxZoom?: number;
 }
+
+/**
+ * Parametric point returned by a trajectory evaluation.
+ */
+export interface TrajectoryPoint {
+	position: XYPosition;
+	scale?: number;
+	opacity?: number;
+}
+
+/**
+ * Trajectory evaluation function determining path, scale, and opacity over time t in [0, 1].
+ */
+export type TrajectoryFunction = (
+	origin: XYPosition,
+	target: XYPosition,
+	progress: number,
+	index: number,
+	total: number
+) => TrajectoryPoint;
+
+/**
+ * Options for fan-out trajectory generator.
+ */
+export interface FanOutTrajectoryOptions {
+	curvature?: number;
+	spreadAngle?: number;
+	startScale?: number;
+	endScale?: number;
+	startOpacity?: number;
+	endOpacity?: number;
+}
+
+/**
+ * Single node animation transition definition.
+ */
+export interface NodeTransition<TNode extends CanvasNode = CanvasNode> {
+	node: TNode;
+	from: XYPosition;
+	to: XYPosition;
+	trajectory?: TrajectoryFunction;
+	delay?: number;
+	duration?: number;
+	easing?: (t: number) => number;
+	index?: number;
+	total?: number;
+}
+
+/**
+ * Displacement axis / direction.
+ */
+export type DisplacementDirection = 'right' | 'left' | 'down' | 'up' | 'vertical';
+
+/**
+ * Options for directional displacement calculation.
+ */
+export interface DirectionalDisplacementOptions {
+	direction?: DisplacementDirection;
+	gap?: number;
+	spreadSiblingLanes?: boolean;
+	siblingTolerance?: number;
+	minY?: number;
+}
+
+/**
+ * Options for Dagre reflow displacement calculation.
+ */
+export interface ReflowDisplacementOptions extends CanvasLayoutOptions {
+	anchorNodeId: string;
+}
+
+/**
+ * Snapshot of canvas graph state prior to node explosion, enabling exact reversibility.
+ */
+export interface ExplosionSnapshot<
+	TNode extends CanvasNode = CanvasNode,
+	TEdge extends CanvasEdge = CanvasEdge
+> {
+	parentId: string;
+	childNodeIds: string[];
+	childEdgeIds: string[];
+	displacedNodes: { id: string; originalPosition: XYPosition }[];
+	timestamp: number;
+}
+
+/**
+ * Options for exploding a node.
+ */
+export interface ExplodeNodeOptions<
+	TNode extends CanvasNode = CanvasNode,
+	TEdge extends CanvasEdge = CanvasEdge
+> {
+	childNodes: TNode[];
+	childEdges?: TEdge[];
+	connectParentToChildren?: boolean | 'first' | 'all';
+	connectChildrenToDownstream?: boolean;
+	displacementStrategy?: 'directional' | 'dagre' | 'none';
+	directionalOptions?: DirectionalDisplacementOptions;
+	reflowOptions?: Partial<ReflowDisplacementOptions>;
+	trajectory?: TrajectoryFunction;
+	duration?: number;
+	staggerDelay?: number;
+	easing?: (t: number) => number;
+	onComplete?: () => void;
+}
+
+/**
+ * Options for collapsing an exploded node.
+ */
+export interface CollapseNodeOptions {
+	duration?: number;
+	staggerDelay?: number;
+	easing?: (t: number) => number;
+	trajectory?: TrajectoryFunction;
+	onComplete?: () => void;
+}
+