avoid-nodes-edge 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,202 @@
+import { Node, Edge, NodeChange } from '@xyflow/react';
+import * as zustand from 'zustand';
+
+/**
+ * React Flow integration for libavoid-js: route edges so they avoid nodes (excluding group nodes).
+ * Use AvoidRouter.load() once, then AvoidRouter.getInstance().routeAll(nodes, edges).
+ */
+
+type AvoidRoute = {
+    path: string;
+    labelX: number;
+    labelY: number;
+};
+type AvoidRouterOptions = {
+    shapeBufferDistance?: number;
+    idealNudgingDistance?: number;
+    edgeRounding?: number;
+    diagramGridSize?: number;
+    shouldSplitEdgesNearHandle?: boolean;
+};
+type HandlePosition = "left" | "right" | "top" | "bottom";
+/**
+ * AvoidRouter: routes diagram edges around nodes using libavoid-js (WASM).
+ * Use static load() once, then getInstance().routeAll(nodes, edges).
+ */
+declare class AvoidRouter {
+    private static lib;
+    private static instance;
+    static load(wasmUrl?: string): Promise<boolean>;
+    private static loadOnce;
+    static getInstance(): AvoidRouter;
+    routeAll(nodes: Node[], edges: Edge[], options?: AvoidRouterOptions): Record<string, AvoidRoute>;
+    private getNodeBounds;
+    private getNodeBoundsAbsolute;
+    private getHandlePosition;
+    private getHandlePoint;
+    private snapToGrid;
+    private polylineToPath;
+    private cleanup;
+}
+declare function loadAvoidRouter(): Promise<boolean>;
+declare function routeAll(nodes: Node[], edges: Edge[], options?: AvoidRouterOptions): Record<string, AvoidRoute>;
+
+interface AvoidRoutesState {
+    loaded: boolean;
+    routes: Record<string, AvoidRoute>;
+    setLoaded: (loaded: boolean) => void;
+    setRoutes: (routes: Record<string, AvoidRoute>) => void;
+}
+declare const useAvoidRoutesStore: zustand.UseBoundStore<zustand.StoreApi<AvoidRoutesState>>;
+interface AvoidRouterActions {
+    resetRouting: () => void;
+    updateRoutesForNodeId: (nodeId: string) => void;
+}
+declare const useAvoidRouterActionsStore: zustand.UseBoundStore<zustand.StoreApi<{
+    actions: AvoidRouterActions;
+    setActions: (a: AvoidRouterActions) => void;
+}>>;
+
+type Position = "left" | "right" | "top" | "bottom";
+interface UseAvoidNodesPathParams {
+    id: string;
+    sourceX: number;
+    sourceY: number;
+    targetX: number;
+    targetY: number;
+    sourcePosition?: Position;
+    targetPosition?: Position;
+    points?: {
+        x: number;
+        y: number;
+    }[];
+    borderRadius?: number;
+    offset?: number;
+}
+/**
+ * Returns [path, labelX, labelY, wasRouted] for an avoid-nodes edge.
+ * Reads from the avoid store (set by the worker); falls back to straight/smooth-step.
+ */
+declare function useAvoidNodesPath(params: UseAvoidNodesPathParams): [path: string, labelX: number, labelY: number, wasRouted: boolean];
+
+/**
+ * useAvoidNodesRouterFromWorker
+ * ---------------------------------------------------------------------------
+ * Routes edges around nodes using a Web Worker running WASM.
+ *
+ * How it works:
+ * 1. On load, sends ALL nodes + edges to the worker ("reset").
+ * 2. On drag/resize, sends ONLY that node ("updateNodes") — much faster.
+ * 3. On add/remove, does a full reset (graph structure changed).
+ * 4. On settings change (spacing, rounding), does a full reset.
+ *
+ * The worker batches rapid changes (debounce) so dragging doesn't flood it.
+ */
+
+interface UseAvoidNodesRouterOptions {
+    shouldSplitEdgesNearHandle?: boolean;
+    edgeToEdgeSpacing?: number;
+    edgeToNodeSpacing?: number;
+    edgeRounding?: number;
+    diagramGridSize?: number;
+}
+interface UseAvoidNodesRouterResult {
+    updateRoutingOnNodesChange: (changes: NodeChange<Node>[]) => void;
+    resetRouting: () => void;
+    refreshRouting: () => void;
+    updateRoutingForNodeIds: (nodeIds: string[]) => void;
+}
+/**
+ * Drop-in replacement for useAvoidNodesRouter — same API, but all heavy
+ * routing calculations happen on a separate thread so the UI stays smooth.
+ */
+declare function useAvoidNodesRouterFromWorker(nodes: Node[], edges: Edge[], options?: UseAvoidNodesRouterOptions): UseAvoidNodesRouterResult;
+
+/**
+ * Message types for the avoid-router Web Worker.
+ * Main thread posts commands; worker posts back 'loaded' and 'routed'.
+ */
+
+/** Commands the main thread can send to the worker */
+type AvoidRouterWorkerCommand = {
+    command: "reset";
+    nodes: Node[];
+    edges: Edge[];
+    options?: AvoidRouterOptions;
+} | {
+    command: "change";
+    cell: Node | Edge;
+} | {
+    command: "remove";
+    id: string;
+} | {
+    command: "add";
+    cell: Node | Edge;
+} | {
+    command: "route";
+    nodes: Node[];
+    edges: Edge[];
+    options?: AvoidRouterOptions;
+} | {
+    command: "updateNodes";
+    nodes: Node[];
+} | {
+    command: "close";
+};
+/** Messages the worker sends back to the main thread */
+type AvoidRouterWorkerResponse = {
+    command: "loaded";
+    success: boolean;
+} | {
+    command: "routed";
+    routes: Record<string, AvoidRoute>;
+};
+
+interface UseAvoidWorkerOptions {
+    create?: boolean;
+    onRouted?: (routes: Record<string, AvoidRoute>) => void;
+    onLoaded?: (success: boolean) => void;
+}
+interface UseAvoidWorkerResult {
+    workerLoaded: boolean;
+    post: (cmd: AvoidRouterWorkerCommand) => void;
+    close: () => void;
+}
+/**
+ * Creates the avoid-router Web Worker and waits for it to load WASM.
+ * WASM loads exclusively in the worker thread — never on the main thread.
+ */
+declare function useAvoidWorker(options?: UseAvoidWorkerOptions): UseAvoidWorkerResult;
+
+/**
+ * Listener for avoid-router Web Worker messages.
+ * Syncs "loaded" / "routed" into the avoid store.
+ */
+interface AttachAvoidWorkerListenerOptions {
+    onRouted?: (routes: Record<string, {
+        path: string;
+        labelX: number;
+        labelY: number;
+    }>) => void;
+    onLoaded?: (success: boolean) => void;
+}
+/**
+ * Attach a message listener to an avoid-router worker so the app stays in sync.
+ * @returns Cleanup function (removeEventListener).
+ */
+declare function attachAvoidWorkerListener(worker: Worker, options?: AttachAvoidWorkerListenerOptions): () => void;
+
+/** Log web worker / routing messages in development. */
+declare const DEV_LOG_WEB_WORKER_MESSAGES = false;
+/**
+ * Debounce (ms) before routing runs after diagram changes.
+ * 10 ms merges drag events into a single update.
+ * For larger diagrams (500+ nodes) use ~50-100 ms.
+ */
+declare const DEBOUNCE_ROUTING_MS = 0;
+/** Whether edges start at handle border (true) or center (false). */
+declare const SHOULD_START_EDGE_AT_HANDLE_BORDER = true;
+/** Default border radius (px) for routed path corners. */
+declare const EDGE_BORDER_RADIUS = 0;
+
+export { type AttachAvoidWorkerListenerOptions, type AvoidRoute, AvoidRouter, type AvoidRouterActions, type AvoidRouterOptions, type AvoidRouterWorkerCommand, type AvoidRouterWorkerResponse, type AvoidRoutesState, DEBOUNCE_ROUTING_MS, DEV_LOG_WEB_WORKER_MESSAGES, EDGE_BORDER_RADIUS, type HandlePosition, type Position, SHOULD_START_EDGE_AT_HANDLE_BORDER, type UseAvoidNodesPathParams, type UseAvoidNodesRouterOptions, type UseAvoidNodesRouterResult, type UseAvoidWorkerOptions, type UseAvoidWorkerResult, attachAvoidWorkerListener, loadAvoidRouter, routeAll, useAvoidNodesPath, useAvoidNodesRouterFromWorker, useAvoidRouterActionsStore, useAvoidRoutesStore, useAvoidWorker };

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+import { Node, Edge, NodeChange } from '@xyflow/react';
+import * as zustand from 'zustand';
+
+/**
+ * React Flow integration for libavoid-js: route edges so they avoid nodes (excluding group nodes).
+ * Use AvoidRouter.load() once, then AvoidRouter.getInstance().routeAll(nodes, edges).
+ */
+
+type AvoidRoute = {
+    path: string;
+    labelX: number;
+    labelY: number;
+};
+type AvoidRouterOptions = {
+    shapeBufferDistance?: number;
+    idealNudgingDistance?: number;
+    edgeRounding?: number;
+    diagramGridSize?: number;
+    shouldSplitEdgesNearHandle?: boolean;
+};
+type HandlePosition = "left" | "right" | "top" | "bottom";
+/**
+ * AvoidRouter: routes diagram edges around nodes using libavoid-js (WASM).
+ * Use static load() once, then getInstance().routeAll(nodes, edges).
+ */
+declare class AvoidRouter {
+    private static lib;
+    private static instance;
+    static load(wasmUrl?: string): Promise<boolean>;
+    private static loadOnce;
+    static getInstance(): AvoidRouter;
+    routeAll(nodes: Node[], edges: Edge[], options?: AvoidRouterOptions): Record<string, AvoidRoute>;
+    private getNodeBounds;
+    private getNodeBoundsAbsolute;
+    private getHandlePosition;
+    private getHandlePoint;
+    private snapToGrid;
+    private polylineToPath;
+    private cleanup;
+}
+declare function loadAvoidRouter(): Promise<boolean>;
+declare function routeAll(nodes: Node[], edges: Edge[], options?: AvoidRouterOptions): Record<string, AvoidRoute>;
+
+interface AvoidRoutesState {
+    loaded: boolean;
+    routes: Record<string, AvoidRoute>;
+    setLoaded: (loaded: boolean) => void;
+    setRoutes: (routes: Record<string, AvoidRoute>) => void;
+}
+declare const useAvoidRoutesStore: zustand.UseBoundStore<zustand.StoreApi<AvoidRoutesState>>;
+interface AvoidRouterActions {
+    resetRouting: () => void;
+    updateRoutesForNodeId: (nodeId: string) => void;
+}
+declare const useAvoidRouterActionsStore: zustand.UseBoundStore<zustand.StoreApi<{
+    actions: AvoidRouterActions;
+    setActions: (a: AvoidRouterActions) => void;
+}>>;
+
+type Position = "left" | "right" | "top" | "bottom";
+interface UseAvoidNodesPathParams {
+    id: string;
+    sourceX: number;
+    sourceY: number;
+    targetX: number;
+    targetY: number;
+    sourcePosition?: Position;
+    targetPosition?: Position;
+    points?: {
+        x: number;
+        y: number;
+    }[];
+    borderRadius?: number;
+    offset?: number;
+}
+/**
+ * Returns [path, labelX, labelY, wasRouted] for an avoid-nodes edge.
+ * Reads from the avoid store (set by the worker); falls back to straight/smooth-step.
+ */
+declare function useAvoidNodesPath(params: UseAvoidNodesPathParams): [path: string, labelX: number, labelY: number, wasRouted: boolean];
+
+/**
+ * useAvoidNodesRouterFromWorker
+ * ---------------------------------------------------------------------------
+ * Routes edges around nodes using a Web Worker running WASM.
+ *
+ * How it works:
+ * 1. On load, sends ALL nodes + edges to the worker ("reset").
+ * 2. On drag/resize, sends ONLY that node ("updateNodes") — much faster.
+ * 3. On add/remove, does a full reset (graph structure changed).
+ * 4. On settings change (spacing, rounding), does a full reset.
+ *
+ * The worker batches rapid changes (debounce) so dragging doesn't flood it.
+ */
+
+interface UseAvoidNodesRouterOptions {
+    shouldSplitEdgesNearHandle?: boolean;
+    edgeToEdgeSpacing?: number;
+    edgeToNodeSpacing?: number;
+    edgeRounding?: number;
+    diagramGridSize?: number;
+}
+interface UseAvoidNodesRouterResult {
+    updateRoutingOnNodesChange: (changes: NodeChange<Node>[]) => void;
+    resetRouting: () => void;
+    refreshRouting: () => void;
+    updateRoutingForNodeIds: (nodeIds: string[]) => void;
+}
+/**
+ * Drop-in replacement for useAvoidNodesRouter — same API, but all heavy
+ * routing calculations happen on a separate thread so the UI stays smooth.
+ */
+declare function useAvoidNodesRouterFromWorker(nodes: Node[], edges: Edge[], options?: UseAvoidNodesRouterOptions): UseAvoidNodesRouterResult;
+
+/**
+ * Message types for the avoid-router Web Worker.
+ * Main thread posts commands; worker posts back 'loaded' and 'routed'.
+ */
+
+/** Commands the main thread can send to the worker */
+type AvoidRouterWorkerCommand = {
+    command: "reset";
+    nodes: Node[];
+    edges: Edge[];
+    options?: AvoidRouterOptions;
+} | {
+    command: "change";
+    cell: Node | Edge;
+} | {
+    command: "remove";
+    id: string;
+} | {
+    command: "add";
+    cell: Node | Edge;
+} | {
+    command: "route";
+    nodes: Node[];
+    edges: Edge[];
+    options?: AvoidRouterOptions;
+} | {
+    command: "updateNodes";
+    nodes: Node[];
+} | {
+    command: "close";
+};
+/** Messages the worker sends back to the main thread */
+type AvoidRouterWorkerResponse = {
+    command: "loaded";
+    success: boolean;
+} | {
+    command: "routed";
+    routes: Record<string, AvoidRoute>;
+};
+
+interface UseAvoidWorkerOptions {
+    create?: boolean;
+    onRouted?: (routes: Record<string, AvoidRoute>) => void;
+    onLoaded?: (success: boolean) => void;
+}
+interface UseAvoidWorkerResult {
+    workerLoaded: boolean;
+    post: (cmd: AvoidRouterWorkerCommand) => void;
+    close: () => void;
+}
+/**
+ * Creates the avoid-router Web Worker and waits for it to load WASM.
+ * WASM loads exclusively in the worker thread — never on the main thread.
+ */
+declare function useAvoidWorker(options?: UseAvoidWorkerOptions): UseAvoidWorkerResult;
+
+/**
+ * Listener for avoid-router Web Worker messages.
+ * Syncs "loaded" / "routed" into the avoid store.
+ */
+interface AttachAvoidWorkerListenerOptions {
+    onRouted?: (routes: Record<string, {
+        path: string;
+        labelX: number;
+        labelY: number;
+    }>) => void;
+    onLoaded?: (success: boolean) => void;
+}
+/**
+ * Attach a message listener to an avoid-router worker so the app stays in sync.
+ * @returns Cleanup function (removeEventListener).
+ */
+declare function attachAvoidWorkerListener(worker: Worker, options?: AttachAvoidWorkerListenerOptions): () => void;
+
+/** Log web worker / routing messages in development. */
+declare const DEV_LOG_WEB_WORKER_MESSAGES = false;
+/**
+ * Debounce (ms) before routing runs after diagram changes.
+ * 10 ms merges drag events into a single update.
+ * For larger diagrams (500+ nodes) use ~50-100 ms.
+ */
+declare const DEBOUNCE_ROUTING_MS = 0;
+/** Whether edges start at handle border (true) or center (false). */
+declare const SHOULD_START_EDGE_AT_HANDLE_BORDER = true;
+/** Default border radius (px) for routed path corners. */
+declare const EDGE_BORDER_RADIUS = 0;
+
+export { type AttachAvoidWorkerListenerOptions, type AvoidRoute, AvoidRouter, type AvoidRouterActions, type AvoidRouterOptions, type AvoidRouterWorkerCommand, type AvoidRouterWorkerResponse, type AvoidRoutesState, DEBOUNCE_ROUTING_MS, DEV_LOG_WEB_WORKER_MESSAGES, EDGE_BORDER_RADIUS, type HandlePosition, type Position, SHOULD_START_EDGE_AT_HANDLE_BORDER, type UseAvoidNodesPathParams, type UseAvoidNodesRouterOptions, type UseAvoidNodesRouterResult, type UseAvoidWorkerOptions, type UseAvoidWorkerResult, attachAvoidWorkerListener, loadAvoidRouter, routeAll, useAvoidNodesPath, useAvoidNodesRouterFromWorker, useAvoidRouterActionsStore, useAvoidRoutesStore, useAvoidWorker };