@loradb/lora-graph-canvas 0.10.1 → 0.11.1

package/README.md

@@ -114,6 +114,37 @@ import { LoraGraphCanvas, darkTheme } from "@loradb/lora-graph-canvas";
 
 Two presets are exported: `lightTheme` and `darkTheme`.
 
+## Confirm-before-delete
+
+Gate every node / link removal — keyboard, toolbar, context menu,
+selection panel, cut, and the imperative `removeNode` / `removeLink`
+handle methods — through an async guard:
+
+```tsx
+<LoraGraphCanvas
+  onBeforeNodeDelete={(nodes, { source }) =>
+    source === "imperative"
+      ? true                                // trust your own code
+      : openMyConfirmDialog(nodes)          // returns Promise<boolean>
+  }
+  onBeforeLinkDelete={(links) => openMyConfirmDialog([], links)}
+  onNodeDeleted={(nodes, { source }) => analytics.track("nodes.removed", {
+    n: nodes.length,
+    source,
+  })}
+/>
+```
+
+The guard receives every item in the batch (one selection-wide call,
+not per-item), the originating `source` (`"keyboard" | "toolbar" |
+"contextMenu" | "selectionPanel" | "cut" | "imperative"`), and may
+return either a boolean or a `Promise<boolean>`. A thrown error is
+treated as a cancel — your host won't silently destroy data.
+
+When no guard is wired, deletion happens immediately as before; the
+imperative methods become `Promise<boolean>` but resolve on the same
+tick.
+
 ## Performance knobs
 
 For large graphs, cap `cooldownTicks` (default ∞) and increase

package/dist/LoraGraphCanvas.stories.d.ts

@@ -21,3 +21,4 @@ export declare const Beeswarm: Story;
 export declare const EmitParticle: Story;
 export declare const RandomGraphStory: Story;
 export declare const LabeledStory: Story;
+export declare const ConfirmDeleteStory: Story;

package/dist/engines/createEngineUnified.d.ts

@@ -4,6 +4,25 @@ export interface UnifiedEngine<N extends NodeObject = NodeObject, L extends Link
     /** Switch presentation mode in place. Animates the camera + the
      *  per-node z constraints; does not destroy the engine. */
     setMode(mode: GraphMode, durationMs?: number): void;
+    /** First-load reveal that runs concurrently with the force
+     *  simulation: every animation frame, recompute the bbox-fitted
+     *  pose and ease the camera toward it via a critically-damped
+     *  spring. The spring's time constant is tuned by node count
+     *  (small graphs settle in ~200 ms; large graphs ease over ~900 ms
+     *  so we don't over-react to early ticks where the bbox is still
+     *  exploding outward). Cancels on user interaction, on
+     *  `onEngineStop`, or after `maxDurationMs`. Padding is in CSS
+     *  pixels and reserved on every side of the viewport.
+     *
+     *  Use on initial mount only — calling this on a graph the user
+     *  has already explored will yank their camera. */
+    introFollow(opts?: {
+        padding?: number;
+        maxDurationMs?: number;
+        /** Optional time-constant override (seconds). If omitted, derived
+         *  from node count via a perf-tier-style log scale. */
+        tauSeconds?: number;
+    }): void;
 }
 export declare function createEngineUnified<N extends NodeObject, L extends LinkObject>(mount: HTMLElement, opts: CreateEngineOptions<N, L> & {
     initialMode: GraphMode;

package/dist/engines/rafAnim.d.ts

@@ -8,6 +8,17 @@
  *  the animation at the current frame (no further `step` invocations).
  *  Returns null when running in an environment without
  *  `requestAnimationFrame` (jsdom in unit tests). */
-export declare function runAnim(durationMs: number, step: (t: number) => void, onDone?: () => void): () => void;
+export declare function runAnim(durationMs: number, step: (t: number) => void, onDone?: () => void, ease?: (t: number) => number): () => void;
+/** Open-ended RAF loop. Unlike `runAnim` there's no fixed duration —
+ *  `step(dt)` receives the seconds elapsed since the previous frame
+ *  (capped at 1/30 s so a tab-switch doesn't deliver a giant dt that
+ *  blows past spring targets) and decides for itself when it has
+ *  converged. Returning `true` from `step` stops the loop the same way
+ *  the returned `cancel()` would. */
+export declare function runFollow(step: (dtSeconds: number) => boolean | void): () => void;
 export declare function easeOutQuad(t: number): number;
+/** Smoother S-curve — slow start, fast middle, slow end. Reads as
+ *  more "cinematic" than easeOutQuad for longer cross-mode camera
+ *  tweens where the user is watching the whole motion. */
+export declare function easeInOutCubic(t: number): number;
 export declare function lerp(a: number, b: number, t: number): number;

package/dist/engines/types.d.ts

@@ -70,6 +70,31 @@ export interface GraphEngine<N extends NodeObject = NodeObject, L extends LinkOb
         zoom?: number;
         durationMs?: number;
     }): void;
+    /** Translate the view by world-space delta. Moves camera AND
+     *  lookAt by the same vector so the orbit / view direction is
+     *  preserved (a true "pan" rather than an orbit step). In 2D the
+     *  z component is ignored — the top-down camera is locked to a
+     *  constant height. */
+    panBy(delta: {
+        x?: number;
+        y?: number;
+        z?: number;
+    }, durationMs?: number): void;
+    /** Jump the view to a world coordinate, preserving the current
+     *  viewing direction. Differs from `focusOn` in that it accepts a
+     *  raw coordinate rather than a node-style target and doesn't
+     *  re-tighten the zoom. Useful for "go to coordinates" UI. */
+    goTo(target: {
+        x: number;
+        y: number;
+        z?: number;
+    }, opts?: {
+        durationMs?: number;
+    }): void;
+    /** Fit the camera to a subset of nodes. Same camera math as `fit()`
+     *  but the bbox is computed over `nodeIds` instead of the whole
+     *  graph. Falls back to a full fit when `nodeIds` is empty. */
+    fitToNodes(nodeIds: ReadonlyArray<string | number>, durationMs?: number, padding?: number): void;
     /** Snapshot the current camera so it can be restored later. */
     getCameraState(): CameraState;
     /** Restore a snapshot produced by `getCameraState`. */

package/dist/hooks/useGraphClipboard.d.ts

@@ -2,10 +2,12 @@ import { MutableRefObject } from 'react';
 import { GraphEngine } from '../engines/types';
 import { LinkObject, NodeObject } from '../types';
 import { GraphDataApi } from './useGraphData';
+import { GraphDeleteGateApi } from './useGraphDeleteGate';
 import { SelectionApi } from './useGraphSelection';
 export interface UseGraphClipboardParams<N extends NodeObject, L extends LinkObject> {
     enableClipboard: boolean;
     dataApi: GraphDataApi<N, L>;
+    deleteGate: GraphDeleteGateApi<L>;
     selection: SelectionApi;
     setSelectedLinkIds: React.Dispatch<React.SetStateAction<Array<string | number>>>;
     engineRef: MutableRefObject<GraphEngine<N, L> | null>;
@@ -23,7 +25,11 @@ export interface GraphClipboardApi<N extends NodeObject> {
      *  callers that need to react on every keystroke. */
     hasClipboard(): boolean;
     copy(): N[];
-    cut(): N[];
+    /** Async because cut funnels through the host's delete guard — if the
+     *  guard rejects, the cut becomes a no-op (clipboard untouched, nodes
+     *  not removed). Callers that fire-and-forget can ignore the
+     *  promise. */
+    cut(): Promise<N[]>;
     paste(at?: {
         x: number;
         y: number;

package/dist/hooks/useGraphData.d.ts

@@ -24,7 +24,7 @@ export interface GraphDataApi<N extends NodeObject, L extends LinkObject> {
     }>): N[];
     updateNode(id: string | number, patch: Partial<N>): void;
     removeNode(id: string | number): void;
-    removeNodes(ids: Array<string | number>): void;
+    removeNodes(ids: ReadonlyArray<string | number>): void;
     addLink(link: {
         source: string | number;
         target: string | number;

package/dist/hooks/useGraphDeleteGate.d.ts

@@ -0,0 +1,38 @@
+import { DeletionGuard, DeletionSource, LinkObject, NodeObject } from '../types';
+import { GraphDataApi } from './useGraphData';
+export interface UseGraphDeleteGateParams<N extends NodeObject, L extends LinkObject> {
+    dataApi: GraphDataApi<N, L>;
+    beforeNode?: DeletionGuard<N>;
+    beforeLink?: DeletionGuard<L>;
+    onNodeDeleted?: (nodes: N[], ctx: {
+        source: DeletionSource;
+    }) => void;
+    onLinkDeleted?: (links: L[], ctx: {
+        source: DeletionSource;
+    }) => void;
+    /** Called after a successful node delete so the caller can clear its
+     *  own selection / hover state. Skipped if the guard rejected. */
+    afterNodeDelete?: (ids: ReadonlyArray<string | number>) => void;
+    afterLinkDelete?: (ids: ReadonlyArray<string | number>) => void;
+}
+export interface GraphDeleteGateApi<L extends LinkObject> {
+    /** Resolves the selected node ids against current data, runs the guard,
+     *  and removes them. Returns `false` if the guard rejected or nothing
+     *  matched. */
+    requestNodeDelete: (ids: ReadonlyArray<string | number>, source: DeletionSource) => Promise<boolean>;
+    /** Same, for links. Accepts either an id list or a predicate so context
+     *  menus that hold the link reference can still target it precisely
+     *  (links sometimes lack an id). */
+    requestLinkDelete: (target: ReadonlyArray<string | number> | ((l: L) => boolean), source: DeletionSource) => Promise<boolean>;
+    /** Convenience: run node + link guards in sequence. Used by the
+     *  "delete selection" sites (toolbar / selection panel / keyboard)
+     *  where a mixed selection is common. Each guard fires independently;
+     *  rejecting one doesn't cancel the other. Returns true if anything
+     *  was actually deleted. */
+    requestMixedDelete: (nodeIds: ReadonlyArray<string | number>, linkIds: ReadonlyArray<string | number>, source: DeletionSource) => Promise<boolean>;
+}
+/** Single chokepoint for every gated delete in the canvas. Centralising
+ *  here keeps the guard semantics (batched calls, post-delete callbacks,
+ *  selection cleanup) consistent across keyboard, toolbar, context menu,
+ *  selection panel, and imperative paths. */
+export declare function useGraphDeleteGate<N extends NodeObject, L extends LinkObject>(params: UseGraphDeleteGateParams<N, L>): GraphDeleteGateApi<L>;

package/dist/hooks/useGraphEngine.d.ts

@@ -1,4 +1,4 @@
-import { GraphEngine } from '../engines/types';
+import { UnifiedEngine } from '../engines/createEngineUnified';
 import { GraphData, GraphMode, LinkObject, LoraGraphCanvasProps, NodeObject } from '../types';
 interface UseGraphEngineParams<N extends NodeObject, L extends LinkObject> {
     mount: HTMLElement | null;
@@ -19,5 +19,5 @@ interface UseGraphEngineParams<N extends NodeObject, L extends LinkObject> {
  *  to 0, top-down camera) and 3D (z released, orbit camera). The
  *  engine is destroyed only when the host element changes or the
  *  component unmounts. */
-export declare function useGraphEngine<N extends NodeObject, L extends LinkObject>(params: UseGraphEngineParams<N, L>): GraphEngine<N, L> | null;
+export declare function useGraphEngine<N extends NodeObject, L extends LinkObject>(params: UseGraphEngineParams<N, L>): UnifiedEngine<N, L> | null;
 export {};

package/dist/hooks/useGraphKeybindings.d.ts

@@ -1,10 +1,13 @@
+import { RefObject } from 'react';
 import { GraphEngine } from '../engines/types';
 import { GraphMode, LinkObject, NodeObject, ToolId } from '../types';
 import { GraphDataApi } from './useGraphData';
+import { GraphDeleteGateApi } from './useGraphDeleteGate';
 import { SelectionApi } from './useGraphSelection';
 export interface UseGraphKeybindingsParams<N extends NodeObject, L extends LinkObject> {
     engine: GraphEngine<N, L> | null;
     dataApi: GraphDataApi<N, L>;
+    deleteGate: GraphDeleteGateApi<L>;
     selection: SelectionApi;
     mode: GraphMode;
     setMode: (next: GraphMode) => void;
@@ -19,6 +22,10 @@ export interface UseGraphKeybindingsParams<N extends NodeObject, L extends LinkO
     duplicate: () => unknown;
     addConnectedNode: () => unknown;
     togglePin: (id: string | number) => void;
+    /** Host element. Bindings only fire while focus is inside this
+     *  element — otherwise hitting `f` while typing into a sibling text
+     *  field on the page would trigger the canvas fit shortcut. */
+    hostRef: RefObject<HTMLElement | null>;
 }
 /** Global keyboard shortcuts for the canvas. The listener is bound once
  *  per mount; live state is read through a ref so we avoid the

package/dist/hooks/useGraphSelection.d.ts

@@ -3,12 +3,21 @@ export interface UseGraphSelectionOptions {
     onChange?: (selectedIds: Array<string | number>) => void;
 }
 export interface SelectionApi {
-    selected: Array<string | number>;
+    /** Selected ids as a stable array. Identity flips on every mutation
+     *  so it can drive React effect dep arrays. Backed by the same `Set`
+     *  as `selectedSet`. */
+    selected: ReadonlyArray<string | number>;
+    /** O(1)-membership view of the same selection. Wrappers that test
+     *  `selectedSet.has(id)` on every node/link must read this instead
+     *  of the array — `selected.includes(id)` is O(N) and on a 10k
+     *  selection the kapsule digest paid that cost per node per
+     *  frame. */
+    selectedSet: ReadonlySet<string | number>;
     isSelected(id: string | number): boolean;
     toggle(id: string | number, opts?: {
         additive?: boolean;
     }): void;
-    set(ids: Array<string | number>): void;
+    set(ids: ReadonlyArray<string | number> | ReadonlySet<string | number>): void;
     clear(): void;
 }
 export declare function useGraphSelection(opts: UseGraphSelectionOptions): SelectionApi;

package/dist/hooks/useImperativeGraphHandle.d.ts

@@ -1,11 +1,13 @@
 import { GraphEngine } from '../engines/types';
 import { GraphMode, LinkObject, LoraGraphCanvasHandle, NodeObject } from '../types';
 import { GraphDataApi } from './useGraphData';
+import { GraphDeleteGateApi } from './useGraphDeleteGate';
 import { SelectionApi } from './useGraphSelection';
 import { GraphClipboardApi } from './useGraphClipboard';
 export interface UseImperativeGraphHandleParams<N extends NodeObject, L extends LinkObject> {
     ref: React.Ref<LoraGraphCanvasHandle<N, L>>;
     dataApi: GraphDataApi<N, L>;
+    deleteGate: GraphDeleteGateApi<L>;
     selection: SelectionApi;
     engine: GraphEngine<N, L> | null;
     mode: GraphMode;
@@ -15,8 +17,18 @@ export interface UseImperativeGraphHandleParams<N extends NodeObject, L extends
     exportJSON: () => string;
     importJSON: (json: string) => void;
     downloadJSON: (filename?: string) => void;
+    /** Live link selection — needed for fitToSelection to expand into
+     *  link endpoints. */
+    selectedLinkIds: Array<string | number>;
 }
 /** Hooks `useImperativeHandle` to expose the canvas's full
  *  programmatic API surface to consumers via a forwardRef. Kept as a
- *  hook so the main component file stays focused on rendering. */
+ *  hook so the main component file stays focused on rendering.
+ *
+ *  Live state (selection, link selection, data, engine) is read inside
+ *  the handle methods via a ref so the handle object identity doesn't
+ *  churn on every click. Without this, every selection change rebuilt
+ *  the whole handle and any host holding `ref.current` saw a fresh set
+ *  of method identities each click — defeating downstream memoisation
+ *  on the host side. */
 export declare function useImperativeGraphHandle<N extends NodeObject, L extends LinkObject>(params: UseImperativeGraphHandleParams<N, L>): void;

package/dist/hooks/useMarqueeAndCursor.d.ts

@@ -8,6 +8,11 @@ export interface MarqueeRect {
     x1: number;
     y1: number;
     additive: boolean;
+    /** Live count of nodes inside the rectangle. Updated on rAF
+     *  throttle during drag — cheap to compute (one graph2Screen per
+     *  node) but we still coalesce by frame so a 5k-node graph doesn't
+     *  re-render the host 60×/s. Undefined while inactive. */
+    count?: number;
 }
 export interface UseMarqueeAndCursorParams<N extends NodeObject, L extends LinkObject> {
     mount: HTMLDivElement | null;

package/dist/hooks/usePrefersReducedMotion.d.ts

@@ -0,0 +1,10 @@
+/** Track the user's `prefers-reduced-motion` media query. Returns
+ *  `true` when the user has asked the OS to minimise non-essential
+ *  motion — our camera tweens (intro zoom, mode transition, focus
+ *  fly-in) skip the animation in that case and snap directly to the
+ *  final state.
+ *
+ *  Re-reads on media-query change so we react when the user flips the
+ *  setting mid-session. Returns `false` in non-browser environments
+ *  (SSR / jsdom without matchMedia) so animations play by default. */
+export declare function usePrefersReducedMotion(): boolean;