@pixerate/editor-svelte 0.3.11 → 0.4.0

package/src/canvas/index.d.ts

@@ -0,0 +1,345 @@
+import type { Node, Edge, XYPosition, Rect, ColorMode } from '@xyflow/svelte';
+
+/**
+ * Generic node interface representing an element on the canvas.
+ */
+export type CanvasNode<
+  TData extends Record<string, any> = Record<string, any>,
+  TType extends string | undefined = string | undefined
+> = Node<TData, TType>;
+
+/**
+ * Generic edge interface representing a connection on the canvas.
+ */
+export type CanvasEdge<
+  TData extends Record<string, any> = Record<string, any>,
+  TType extends string | undefined = string | undefined
+> = Edge<TData, TType>;
+
+/**
+ * Differences computed between two graph states.
+ */
+export interface GraphDifferences<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+> {
+  changedNodes: TNode[];
+  changedEdges: TEdge[];
+  removedNodes: TNode[];
+  removedEdges: TEdge[];
+}
+
+/**
+ * Standard serialized clipboard payload for nodes and optional edges.
+ */
+export interface CanvasClipboardPayload<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+> {
+  version?: number;
+  nodes: TNode[];
+  edges?: TEdge[];
+}
+
+/**
+ * Options for Dagre graph layout.
+ */
+export interface CanvasLayoutOptions {
+  direction?: 'LR' | 'TB' | 'RL' | 'BT';
+  ranksep?: number;
+  nodesep?: number;
+  defaultNodeWidth?: number;
+  defaultNodeHeight?: number;
+}
+
+/**
+ * Options for keyboard shortcuts.
+ */
+export interface CanvasShortcutsOptions<TNode extends CanvasNode = CanvasNode> {
+  targetElement?: HTMLElement | Window;
+  onCopy?: () => void;
+  onCut?: () => void;
+  onPaste?: (event: ClipboardEvent) => void;
+  onDelete?: (selectedNodes: TNode[]) => void;
+  onDuplicate?: (selectedNodes: TNode[]) => void;
+  onSelectAll?: () => void;
+  onGroup?: (selectedNodes: TNode[]) => void;
+  onUngroup?: (selectedNodes: TNode[]) => void;
+  onZoomIn?: () => void;
+  onZoomOut?: () => void;
+  onFitView?: () => void;
+  onSearch?: () => void;
+  getSelectedNodes?: () => TNode[];
+}
+
+/**
+ * Docking and intersection callbacks.
+ */
+export interface CanvasDockingCallbacks<TNode extends CanvasNode = CanvasNode> {
+  onDockHover?: (dockTarget: TNode, draggedNode: TNode) => void;
+  onDockLeave?: (dockTarget: TNode, draggedNode: TNode) => void;
+  onDockDrop?: (dockTarget: TNode, draggedNode: TNode) => void;
+}
+
+/**
+ * Configuration options for SvelteFlow presets.
+ */
+export interface CanvasInteractionPresetConfig {
+  snapGrid?: [number, number];
+  panOnDrag?: number[] | boolean;
+  panOnScroll?: boolean;
+  selectionOnDrag?: boolean;
+  colorMode?: ColorMode;
+  multiSelectionKey?: string[];
+  minZoom?: number;
+  maxZoom?: number;
+}
+
+/**
+ * Pure calculation of graph differences between a current state and a baseline state.
+ */
+export declare function calculateGraphDifferences<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+>(
+  currentState: { nodes?: TNode[]; edges?: TEdge[] },
+  baselineState: { nodes?: TNode[]; edges?: TEdge[] }
+): GraphDifferences<TNode, TEdge>;
+
+/**
+ * Pure function to replace a node in a graph, optionally preserving its connected edges.
+ */
+export declare function replaceNodeInGraph<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+>(
+  nodes: TNode[],
+  edges: TEdge[],
+  oldNode: TNode,
+  newNode: TNode,
+  keepEdges?: boolean
+): { nodes: TNode[]; edges: TEdge[] };
+
+export interface CreateCanvasGraphOptions<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+> {
+  initialNodes?: TNode[];
+  initialEdges?: TEdge[];
+  onNodesChange?: (nodes: TNode[]) => void;
+  onEdgesChange?: (edges: TEdge[]) => void;
+  onSave?: () => void;
+  createEdge?: (
+    sourceId: string,
+    targetId: string,
+    options?: { label?: string; animated?: boolean; data?: any }
+  ) => TEdge;
+}
+
+/**
+ * Headless Svelte 5 rune managing canvas graph state and operations.
+ */
+export declare function createCanvasGraph<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+>(options?: CreateCanvasGraphOptions<TNode, TEdge>): {
+  nodes: TNode[];
+  edges: TEdge[];
+  setNodes(newNodes: TNode[], triggerCallback?: boolean): void;
+  setEdges(newEdges: TEdge[], triggerCallback?: boolean): void;
+  addNodeOrNodes(nodeOrNodesToAdd: TNode | TNode[], animateFromPosition?: XYPosition, save?: boolean): void;
+  addEdge(edgeToAdd: TEdge, save?: boolean): void;
+  addEdges(edgesToAdd: TEdge[], save?: boolean): void;
+  removeNodes(nodesToRemove: TNode[], save?: boolean): void;
+  removeEdges(edgesToRemove: TEdge[], save?: boolean): void;
+  replaceNode(oldNode: TNode, newNode: TNode, save?: boolean, keepEdges?: boolean): void;
+  addConnectedNodes(params: {
+    nodesToAdd: TNode[];
+    inboundNodes?: TNode[];
+    outboundNodes?: TNode[];
+    animatedEdges?: boolean;
+    animateFromPosition?: XYPosition;
+    inboundEdgeData?: any;
+    outboundEdgeData?: any;
+    getEdgeLabel?: (source: TNode, target: TNode) => string;
+  }): void;
+  animateNodePosition(
+    node: TNode,
+    targetPosition: XYPosition,
+    duration?: number,
+    easing?: (t: number) => number
+  ): void;
+  getDifferences(baseline: { nodes?: TNode[]; edges?: TEdge[] }): GraphDifferences<TNode, TEdge>;
+};
+
+/**
+ * Calculates upper-left flow coordinate for an element to be centered in the viewport.
+ */
+export declare function getCenteredNodePosition(
+  width?: number,
+  height?: number,
+  screenToFlowPosition?: (position: XYPosition) => XYPosition,
+  screenDimensions?: { width: number; height: number }
+): XYPosition;
+
+/**
+ * Updates positions of nodes so their collective bounding box is centered in the current viewport.
+ */
+export declare function centerNodes<TNode extends CanvasNode = CanvasNode>(
+  nodes: TNode[],
+  screenToFlowPosition: (position: XYPosition) => XYPosition,
+  getNodesBounds: (nodes: TNode[]) => Rect,
+  screenDimensions?: { width: number; height: number }
+): TNode[];
+
+/**
+ * Automatically calculates directed hierarchical layout of nodes and edges using Dagre.
+ */
+export declare function getLayoutedNodes<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+>(
+  nodes: TNode[],
+  edges: TEdge[],
+  getNodesBounds: (nodes: TNode[]) => Rect,
+  options?: CanvasLayoutOptions
+): TNode[];
+
+/**
+ * Checks if an event originated from a text input, textarea, contenteditable element, or rich editor.
+ */
+export declare function isEventFromTextInput(event: Event | { target: EventTarget | null }): boolean;
+
+/**
+ * Validates that an object conforms to minimal CanvasNode shape.
+ */
+export declare function isValidCanvasNode(obj: unknown): obj is CanvasNode;
+
+/**
+ * Checks if a string is a valid HTTP/HTTPS URL.
+ */
+export declare function isValidUrl(url: string): boolean;
+
+export interface CreateCanvasClipboardOptions<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+> {
+  onPasteNodes?: (nodes: TNode[], edges?: TEdge[]) => void | Promise<void>;
+  onPasteUrl?: (url: string, position?: XYPosition) => void;
+  onPasteText?: (text: string, position?: XYPosition) => void;
+  onPasteImage?: (blob: File) => void | Promise<void>;
+  screenToFlowPosition?: (position: XYPosition) => XYPosition;
+}
+
+/**
+ * Headless Svelte 5 rune managing canvas copy, cut, and paste interactions.
+ */
+export declare function createCanvasClipboard<
+  TNode extends CanvasNode = CanvasNode,
+  TEdge extends CanvasEdge = CanvasEdge
+>(options?: CreateCanvasClipboardOptions<TNode, TEdge>): {
+  copySelectedNodes(
+    selectedNodes: TNode[],
+    connectedEdges?: TEdge[],
+    event?: ClipboardEvent
+  ): boolean;
+  cutSelectedNodes(
+    selectedNodes: TNode[],
+    connectedEdges?: TEdge[],
+    onRemove?: (nodes: TNode[]) => void,
+    event?: ClipboardEvent
+  ): boolean;
+  handlePasteEvent(event: ClipboardEvent): Promise<boolean>;
+};
+
+export interface CreateCanvasDockingOptions<TNode extends CanvasNode = CanvasNode>
+  extends CanvasDockingCallbacks<TNode> {
+  isDockTarget?: (target: TNode) => boolean;
+  restorePositionOnDock?: boolean;
+  onSave?: () => void;
+}
+
+/**
+ * Headless Svelte 5 rune managing canvas node dragging, docking intersection, and connection tracking.
+ */
+export declare function createCanvasDocking<TNode extends CanvasNode = CanvasNode>(
+  options?: CreateCanvasDockingOptions<TNode>
+): {
+  readonly draggedNode: TNode | null;
+  readonly draggedInitialPosition: XYPosition | null;
+  readonly connectingHandle: string;
+  readonly connectingNode: TNode | null;
+  readonly isDragging: boolean;
+  handleNodeDragStart(params: {
+    targetNode: TNode | null;
+    event?: MouseEvent | TouchEvent;
+  }): void;
+  handleNodeDrag(
+    params: {
+      targetNode: TNode | null;
+      event?: MouseEvent | TouchEvent;
+    },
+    getIntersectingNodes: (node: TNode) => TNode[]
+  ): void;
+  handleNodeDragStop(
+    params: {
+      targetNode: TNode | null;
+      event?: MouseEvent | TouchEvent;
+    },
+    getIntersectingNodes: (node: TNode) => TNode[],
+    updateNodePosition?: (nodeId: string, position: XYPosition) => void
+  ): void;
+  handleConnectStart(
+    params: {
+      nodeId: string | null;
+      handleId?: string | null;
+      handleType: 'source' | 'target' | null;
+    },
+    getNode: (id: string) => TNode | undefined
+  ): void;
+  handleConnectEnd(): void;
+  reset(): void;
+};
+
+/**
+ * Attaches keyboard shortcut handlers for canvas interaction.
+ * Automatically ignores shortcuts when the user is typing into text inputs, textareas, or rich editors.
+ *
+ * @returns A cleanup function to remove event listeners.
+ */
+export declare function createCanvasShortcuts<TNode extends CanvasNode = CanvasNode>(
+  options: CanvasShortcutsOptions<TNode>
+): () => void;
+
+export interface CreateCanvasInteractionsOptions {
+  targetElement?: HTMLElement | Window;
+  onPanModeChange?: (active: boolean) => void;
+  onTrackpadDetected?: () => void;
+}
+
+/**
+ * Headless Svelte 5 rune managing canvas pan interactions (spacebar panning, trackpad pinch detection).
+ */
+export declare function createCanvasInteractions(
+  options?: CreateCanvasInteractionsOptions
+): {
+  readonly isSpacebarPanning: boolean;
+  readonly trackpadDetected: boolean;
+  attachListeners(target?: HTMLElement | Window): () => void;
+  destroy: () => void;
+};
+
+/**
+ * Default interaction configuration presets for SvelteFlow.
+ */
+export declare const defaultSvelteFlowPreset: CanvasInteractionPresetConfig;
+
+/**
+ * Miro-compatible interaction preset (middle/right drag to pan, left drag to select).
+ */
+export declare const miroCompatiblePreset: CanvasInteractionPresetConfig;
+
+/**
+ * Helper to ensure panels restore pointer events after selection rectangle releases.
+ */
+export declare function restorePanelPointerEvents(panelSelector?: string): void;

package/src/canvas/index.ts

@@ -0,0 +1,46 @@
+// Types
+export * from './types.js';
+
+// Graph management rune & pure functions
+export {
+	createCanvasGraph,
+	calculateGraphDifferences,
+	replaceNodeInGraph,
+	type CreateCanvasGraphOptions
+} from './createCanvasGraph.svelte.js';
+
+// Layout calculations
+export {
+	getLayoutedNodes,
+	getCenteredNodePosition,
+	centerNodes
+} from './createCanvasLayout.js';
+
+// Clipboard rune & helpers
+export {
+	createCanvasClipboard,
+	isEventFromTextInput,
+	isValidCanvasNode,
+	isValidUrl,
+	type CreateCanvasClipboardOptions
+} from './createCanvasClipboard.svelte.js';
+
+// Docking & drag interactions rune
+export {
+	createCanvasDocking,
+	type CreateCanvasDockingOptions
+} from './createCanvasDocking.svelte.js';
+
+// Shortcuts manager
+export {
+	createCanvasShortcuts
+} from './createCanvasShortcuts.js';
+
+// Interaction modes & presets
+export {
+	createCanvasInteractions,
+	defaultSvelteFlowPreset,
+	miroCompatiblePreset,
+	restorePanelPointerEvents,
+	type CreateCanvasInteractionsOptions
+} from './createCanvasInteractions.svelte.js';

package/src/canvas/types.ts

@@ -0,0 +1,96 @@
+import type { Node, Edge, XYPosition, Rect, ColorMode, Position } from '@xyflow/svelte';
+
+/**
+ * Generic node interface representing an element on the canvas.
+ */
+export type CanvasNode<
+	TData extends Record<string, any> = Record<string, any>,
+	TType extends string | undefined = string | undefined
+> = Node<TData, TType>;
+
+/**
+ * Generic edge interface representing a connection on the canvas.
+ */
+export type CanvasEdge<
+	TData extends Record<string, any> = Record<string, any>,
+	TType extends string | undefined = string | undefined
+> = Edge<TData, TType>;
+
+/**
+ * Differences computed between two graph states.
+ */
+export interface GraphDifferences<
+	TNode extends CanvasNode = CanvasNode,
+	TEdge extends CanvasEdge = CanvasEdge
+> {
+	changedNodes: TNode[];
+	changedEdges: TEdge[];
+	removedNodes: TNode[];
+	removedEdges: TEdge[];
+}
+
+/**
+ * Standard serialized clipboard payload for nodes and optional edges.
+ */
+export interface CanvasClipboardPayload<
+	TNode extends CanvasNode = CanvasNode,
+	TEdge extends CanvasEdge = CanvasEdge
+> {
+	version?: number;
+	nodes: TNode[];
+	edges?: TEdge[];
+}
+
+/**
+ * Options for Dagre graph layout.
+ */
+export interface CanvasLayoutOptions {
+	direction?: 'LR' | 'TB' | 'RL' | 'BT';
+	ranksep?: number;
+	nodesep?: number;
+	defaultNodeWidth?: number;
+	defaultNodeHeight?: number;
+}
+
+/**
+ * Options for keyboard shortcuts.
+ */
+export interface CanvasShortcutsOptions<TNode extends CanvasNode = CanvasNode> {
+	targetElement?: HTMLElement | Window;
+	onCopy?: () => void;
+	onCut?: () => void;
+	onPaste?: (event: ClipboardEvent) => void;
+	onDelete?: (selectedNodes: TNode[]) => void;
+	onDuplicate?: (selectedNodes: TNode[]) => void;
+	onSelectAll?: () => void;
+	onGroup?: (selectedNodes: TNode[]) => void;
+	onUngroup?: (selectedNodes: TNode[]) => void;
+	onZoomIn?: () => void;
+	onZoomOut?: () => void;
+	onFitView?: () => void;
+	onSearch?: () => void;
+	getSelectedNodes?: () => TNode[];
+}
+
+/**
+ * Docking and intersection callbacks.
+ */
+export interface CanvasDockingCallbacks<TNode extends CanvasNode = CanvasNode> {
+	onDockHover?: (dockTarget: TNode, draggedNode: TNode) => void;
+	onDockLeave?: (dockTarget: TNode, draggedNode: TNode) => void;
+	onDockDrop?: (dockTarget: TNode, draggedNode: TNode) => void;
+}
+
+/**
+ * Configuration options for SvelteFlow presets.
+ */
+export interface CanvasInteractionPresetConfig {
+	snapGrid?: [number, number];
+	panOnDrag?: number[] | boolean;
+	panOnScroll?: boolean;
+	selectionOnDrag?: boolean;
+	colorMode?: ColorMode;
+	multiSelectionKey?: string[];
+	minZoom?: number;
+	maxZoom?: number;
+}