@loradb/lora-graph-canvas 0.11.0 → 0.11.2

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

@@ -9,6 +9,13 @@
  *  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, 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

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

@@ -7,7 +7,7 @@ import { SelectionApi } from './useGraphSelection';
 export interface UseGraphClipboardParams<N extends NodeObject, L extends LinkObject> {
     enableClipboard: boolean;
     dataApi: GraphDataApi<N, L>;
-    deleteGate: GraphDeleteGateApi<N, L>;
+    deleteGate: GraphDeleteGateApi<L>;
     selection: SelectionApi;
     setSelectedLinkIds: React.Dispatch<React.SetStateAction<Array<string | number>>>;
     engineRef: MutableRefObject<GraphEngine<N, L> | null>;

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

@@ -12,27 +12,27 @@ export interface UseGraphDeleteGateParams<N extends NodeObject, L extends LinkOb
     }) => 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;
+    afterNodeDelete?: (ids: ReadonlyArray<string | number>) => void;
+    afterLinkDelete?: (ids: ReadonlyArray<string | number>) => void;
 }
-export interface GraphDeleteGateApi<N extends NodeObject, L extends LinkObject> {
+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: Array<string | number>, source: DeletionSource) => Promise<boolean>;
+    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: Array<string | number> | ((l: L) => boolean), source: DeletionSource) => Promise<boolean>;
+    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: Array<string | number>, linkIds: Array<string | number>, source: DeletionSource) => Promise<boolean>;
+    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<N, L>;
+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

@@ -7,7 +7,7 @@ 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>;
+    deleteGate: GraphDeleteGateApi<L>;
     selection: SelectionApi;
     mode: GraphMode;
     setMode: (next: GraphMode) => void;

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

@@ -7,7 +7,7 @@ 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>;
+    deleteGate: GraphDeleteGateApi<L>;
     selection: SelectionApi;
     engine: GraphEngine<N, L> | null;
     mode: GraphMode;
@@ -17,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;