@loradb/lora-graph-canvas 0.10.0 → 0.11.0

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/rafAnim.d.ts

@@ -8,6 +8,10 @@
  *  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;
 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/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<N, 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/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: Array<string | number>) => void;
+    afterLinkDelete?: (ids: Array<string | number>) => void;
+}
+export interface GraphDeleteGateApi<N extends NodeObject, 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: Array<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: Array<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: Array<string | number>, linkIds: Array<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<N, L>;

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<N, 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/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<N, L>;
     selection: SelectionApi;
     engine: GraphEngine<N, L> | null;
     mode: GraphMode;

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;