@loradb/lora-graph-canvas 0.10.0

package/dist/hooks/useGraphClipboard.d.ts

@@ -0,0 +1,47 @@
+import { MutableRefObject } from 'react';
+import { GraphEngine } from '../engines/types';
+import { LinkObject, NodeObject } from '../types';
+import { GraphDataApi } from './useGraphData';
+import { SelectionApi } from './useGraphSelection';
+export interface UseGraphClipboardParams<N extends NodeObject, L extends LinkObject> {
+    enableClipboard: boolean;
+    dataApi: GraphDataApi<N, L>;
+    selection: SelectionApi;
+    setSelectedLinkIds: React.Dispatch<React.SetStateAction<Array<string | number>>>;
+    engineRef: MutableRefObject<GraphEngine<N, L> | null>;
+    lastCursorRef: MutableRefObject<{
+        x: number;
+        y: number;
+    } | null>;
+    onCopy?: (nodes: N[]) => void;
+    onCut?: (nodes: N[]) => void;
+    onPaste?: (nodes: N[]) => void;
+}
+export interface GraphClipboardApi<N extends NodeObject> {
+    /** Live "is clipboard non-empty" indicator — read once per render for
+     *  the selection panel chrome. The ref itself is also exposed for
+     *  callers that need to react on every keystroke. */
+    hasClipboard(): boolean;
+    copy(): N[];
+    cut(): N[];
+    paste(at?: {
+        x: number;
+        y: number;
+        z?: number;
+    }): N[];
+    duplicate(): N[];
+    addConnectedNode(opts?: {
+        at?: {
+            x: number;
+            y: number;
+            z?: number;
+        };
+        label?: string;
+    }): N | null;
+    togglePin(id: string | number): void;
+}
+/** Bundles the editing primitives that read from / write to a private
+ *  per-instance clipboard. The clipboard lives in a ref so writes don't
+ *  trigger re-renders, and the OS clipboard is intentionally not
+ *  touched — copy/paste shouldn't disturb the user's other apps. */
+export declare function useGraphClipboard<N extends NodeObject, L extends LinkObject>(params: UseGraphClipboardParams<N, L>): GraphClipboardApi<N>;

package/dist/hooks/useGraphData.d.ts

@@ -0,0 +1,42 @@
+import { GraphData, LinkObject, NodeObject } from '../types';
+export interface UseGraphDataOptions<N extends NodeObject, L extends LinkObject> {
+    /** Controlled data — when present, props win. */
+    controlled?: GraphData<N, L>;
+    /** Uncontrolled seed — used only on mount. */
+    defaultData?: GraphData<N, L>;
+    /** Fires for every mutation regardless of controlled/uncontrolled. */
+    onChange?: (next: GraphData<N, L>) => void;
+}
+export interface GraphDataApi<N extends NodeObject, L extends LinkObject> {
+    data: GraphData<N, L>;
+    setData(next: GraphData<N, L>): void;
+    addNode(node?: Partial<N> & {
+        id?: string | number;
+    }, opts?: {
+        at?: {
+            x: number;
+            y: number;
+            z?: number;
+        };
+    }): N;
+    addNodes(nodes: Array<Partial<N> & {
+        id?: string | number;
+    }>): N[];
+    updateNode(id: string | number, patch: Partial<N>): void;
+    removeNode(id: string | number): void;
+    removeNodes(ids: Array<string | number>): void;
+    addLink(link: {
+        source: string | number;
+        target: string | number;
+        id?: string | number;
+    } & Partial<L>): L;
+    addLinks(links: Array<{
+        source: string | number;
+        target: string | number;
+    } & Partial<L>>): L[];
+    removeLink(predicate: (l: L) => boolean): void;
+    clear(): void;
+}
+/** Owns the canonical `GraphData` for a `LoraGraphCanvas`. Supports
+ *  controlled and uncontrolled usage; mutators always notify `onChange`. */
+export declare function useGraphData<N extends NodeObject, L extends LinkObject>(opts: UseGraphDataOptions<N, L>): GraphDataApi<N, L>;

package/dist/hooks/useGraphEngine.d.ts

@@ -0,0 +1,23 @@
+import { GraphEngine } from '../engines/types';
+import { GraphData, GraphMode, LinkObject, LoraGraphCanvasProps, NodeObject } from '../types';
+interface UseGraphEngineParams<N extends NodeObject, L extends LinkObject> {
+    mount: HTMLElement | null;
+    mode: GraphMode;
+    width: number;
+    height: number;
+    data: GraphData<N, L>;
+    props: LoraGraphCanvasProps<N, L>;
+    /** Whether the engine should be paused. */
+    paused: boolean;
+    /** Duration (ms) of the camera + node-z tween when switching modes.
+     *  0 disables the animation. */
+    modeTransitionMs?: number;
+}
+/** Owns the kapsule engine lifecycle. The engine is created once on
+ *  mount and survives mode changes — `mode` flips flow through
+ *  `engine.setMode()` so the nodes smoothly move between 2D (z pinned
+ *  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 {};

package/dist/hooks/useGraphForces.d.ts

@@ -0,0 +1,12 @@
+import { GraphEngine } from '../engines/types';
+import { LinkObject, LoraGraphCanvasProps, NodeObject } from '../types';
+export interface UseGraphForcesParams<N extends NodeObject, L extends LinkObject> {
+    engine: GraphEngine<N, L> | null;
+    collideNodes: NonNullable<LoraGraphCanvasProps<N, L>["collideNodes"]>;
+    beeswarm: NonNullable<LoraGraphCanvasProps<N, L>["beeswarm"]>;
+    nodeRelSize?: number;
+}
+/** Drive optional d3-force-3d forces (collide + beeswarm) onto the
+ *  active engine. These are deliberately kept as separate effects in
+ *  one hook so the simulation knobs can be toggled independently. */
+export declare function useGraphForces<N extends NodeObject, L extends LinkObject>(params: UseGraphForcesParams<N, L>): void;

package/dist/hooks/useGraphKeybindings.d.ts

@@ -0,0 +1,27 @@
+import { GraphEngine } from '../engines/types';
+import { GraphMode, LinkObject, NodeObject, ToolId } from '../types';
+import { GraphDataApi } from './useGraphData';
+import { SelectionApi } from './useGraphSelection';
+export interface UseGraphKeybindingsParams<N extends NodeObject, L extends LinkObject> {
+    engine: GraphEngine<N, L> | null;
+    dataApi: GraphDataApi<N, L>;
+    selection: SelectionApi;
+    mode: GraphMode;
+    setMode: (next: GraphMode) => void;
+    selectedLinkIds: Array<string | number>;
+    setSelectedLinkIds: React.Dispatch<React.SetStateAction<Array<string | number>>>;
+    setLinkSourceId: React.Dispatch<React.SetStateAction<string | number | null>>;
+    setActiveTool: React.Dispatch<React.SetStateAction<ToolId>>;
+    enableClipboard: boolean;
+    copy: () => unknown;
+    cut: () => unknown;
+    paste: () => unknown;
+    duplicate: () => unknown;
+    addConnectedNode: () => unknown;
+    togglePin: (id: string | number) => void;
+}
+/** Global keyboard shortcuts for the canvas. The listener is bound once
+ *  per mount; live state is read through a ref so we avoid the
+ *  re-binding churn that would otherwise happen on every selection
+ *  change. */
+export declare function useGraphKeybindings<N extends NodeObject, L extends LinkObject>(params: UseGraphKeybindingsParams<N, L>): void;

package/dist/hooks/useGraphSelection.d.ts

@@ -0,0 +1,14 @@
+export interface UseGraphSelectionOptions {
+    mode?: "none" | "single" | "multi";
+    onChange?: (selectedIds: Array<string | number>) => void;
+}
+export interface SelectionApi {
+    selected: Array<string | number>;
+    isSelected(id: string | number): boolean;
+    toggle(id: string | number, opts?: {
+        additive?: boolean;
+    }): void;
+    set(ids: Array<string | number>): void;
+    clear(): void;
+}
+export declare function useGraphSelection(opts: UseGraphSelectionOptions): SelectionApi;

package/dist/hooks/useHoverState.d.ts

@@ -0,0 +1,67 @@
+import { MutableRefObject } from 'react';
+import { Accessor, LinkObject, NodeObject } from '../types';
+export interface UseHoverStateParams<N extends NodeObject, L extends LinkObject> {
+    highlightNeighborsOnHover: boolean;
+    nodeLabel?: Accessor<string | HTMLElement, N>;
+    linkLabel?: Accessor<string | HTMLElement, L>;
+    onNodeHover?: (node: N | null, previousNode: N | null) => void;
+    onLinkHover?: (link: L | null, previousLink: L | null) => void;
+}
+export interface HoverState<N extends NodeObject, L extends LinkObject> {
+    /** Debounced hovered-node id — drives label visibility / highlight
+     *  pipeline. Keeps a 250 ms grace period after mouseleave so labels
+     *  stay readable while the cursor moves to them. */
+    hoverNodeId: string | number | null;
+    /** Debounced hovered-link id — companion to `hoverNodeId`. */
+    hoverLinkId: string | number | null;
+    /** Live (non-debounced) hovered-node id — updated synchronously from
+     *  the kapsule's `onNodeHover` before the grace timer is even
+     *  scheduled. Read this (not `hoverNodeId`) from interactions that
+     *  need to know whether the cursor is *currently* over a node, e.g.
+     *  the marquee hook's shift+mousedown guard. Reading the debounced
+     *  value there would tell us "still hovering A" for 250 ms after the
+     *  cursor moved off A, which is long enough that the next shift+drag
+     *  would never start a marquee. */
+    liveHoverNodeIdRef: MutableRefObject<string | number | null>;
+    /** Live (non-debounced) hovered-link id — same contract as
+     *  `liveHoverNodeIdRef`, used so neighbour-link hits don't get
+     *  swallowed during the label-grace window. */
+    liveHoverLinkIdRef: MutableRefObject<string | number | null>;
+    /** Set of node ids that should currently render with neighbour-
+     *  highlight styling (the hovered node plus its `_neighbors`). */
+    highlightedNodeIds: ReadonlySet<string | number>;
+    /** Set of link ids that should currently render with neighbour-
+     *  highlight styling (links touching the hovered node). */
+    highlightedLinkIds: ReadonlySet<string | number>;
+    /** Set of node ids whose label should currently be drawn for the
+     *  hover affordance (hovered node + neighbours when highlighting is
+     *  on; just the hovered node otherwise; empty when nothing hovered).
+     *  Memoised so referential equality bails the renderer's no-op
+     *  frames out cheaply. */
+    hoveredNodeSet: ReadonlySet<string | number>;
+    /** Sibling of `hoveredNodeSet` for the link-label renderer. */
+    hoveredLinkSet: ReadonlySet<string | number>;
+    /** Current hover-tooltip content. `null` when no hover. */
+    tooltipContent: string | HTMLElement | null;
+    /** Callback to wire into `engineProps.onNodeHover`. */
+    handleNodeHover: (node: N | null, prev: N | null) => void;
+    /** Callback to wire into `engineProps.onLinkHover`. */
+    handleLinkHover: (link: L | null, prev: L | null) => void;
+    /** Pin the node-hover state to the given node for the duration of
+     *  a drag. The kapsule fires `onNodeHover(null)` on mousedown of a
+     *  drag gesture; without this pin, the grace timer would clear
+     *  `highlightedNodeIds` + `highlightedLinkIds` mid-drag and the
+     *  neighbour labels would vanish. Call `pinHover(node)` from the
+     *  drag-start handler and `pinHover(null)` from drag-end. Calling
+     *  with a node also forces the hover state to that node so a drag
+     *  begun without a preceding hover lights up the right
+     *  neighbours. */
+    pinHover: (node: N | null) => void;
+}
+/** Owns the hover-driven state that the canvas reacts to: the
+ *  debounced ids for label visibility, the live refs for gesture
+ *  guards, the neighbour-highlight sets, and the hover-tooltip
+ *  content. Pulled out of `LoraGraphCanvas` so the live-vs-debounced
+ *  split is a first-class contract instead of a tangle of useState +
+ *  useRef calls in the canvas body. */
+export declare function useHoverState<N extends NodeObject, L extends LinkObject>(params: UseHoverStateParams<N, L>): HoverState<N, L>;

package/dist/hooks/useImperativeGraphHandle.d.ts

@@ -0,0 +1,22 @@
+import { GraphEngine } from '../engines/types';
+import { GraphMode, LinkObject, LoraGraphCanvasHandle, NodeObject } from '../types';
+import { GraphDataApi } from './useGraphData';
+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>;
+    selection: SelectionApi;
+    engine: GraphEngine<N, L> | null;
+    mode: GraphMode;
+    setMode: (next: GraphMode) => void;
+    setPaused: React.Dispatch<React.SetStateAction<boolean>>;
+    clipboard: GraphClipboardApi<N>;
+    exportJSON: () => string;
+    importJSON: (json: string) => void;
+    downloadJSON: (filename?: string) => void;
+}
+/** 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. */
+export declare function useImperativeGraphHandle<N extends NodeObject, L extends LinkObject>(params: UseImperativeGraphHandleParams<N, L>): void;

package/dist/hooks/useLabelRenderer.d.ts

@@ -0,0 +1,47 @@
+import { Accessor, GraphMode, LoraGraphTheme, NodeObject } from '../types';
+export interface UseLabelRendererParams<N extends NodeObject> {
+    mode: GraphMode;
+    showLabels: boolean;
+    selectedNodeSet: ReadonlySet<string | number>;
+    /** Nodes the cursor is currently over (plus optional neighbours). Drawn
+     *  with the default caption styling so the hover affordance is visible
+     *  without competing with the accent-coloured selection pill. */
+    hoveredNodeSet?: ReadonlySet<string | number>;
+    accentColor: string;
+    hostNodeCanvasObject?: (n: N, ctx: CanvasRenderingContext2D, globalScale: number) => void;
+    hostNodeThreeObject?: (n: N) => unknown;
+    nodeLabel?: Accessor<string | HTMLElement, N>;
+    nodeVal?: Accessor<number, N>;
+    nodeRelSize?: number;
+    theme?: Partial<LoraGraphTheme>;
+    /** Live nodes list. Required for the 2D post-render pass so labels
+     *  can be drawn after all node circles have been painted. Stored in
+     *  a ref internally, so identity changes here don't churn the
+     *  renderer's outputs. */
+    nodes?: ReadonlyArray<N>;
+}
+export interface NodeLabelRenderer<N> {
+    /** 2D mode: kept undefined now — labels draw in `renderFramePost`
+     *  so they sit above all node circles, not just the one they're
+     *  attached to. The kapsule's `nodeCanvasObject` callback ran
+     *  inline with each node's circle paint, so a label drawn early
+     *  could be obscured by a circle drawn after. */
+    canvasObject: ((n: N, ctx: CanvasRenderingContext2D, scale: number) => void) | undefined;
+    /** 3D mode: returns an Object3D containing a billboarded text
+     *  sprite, positioned below the kapsule's default sphere. Used as
+     *  `nodeThreeObject` with `nodeThreeObjectExtend: true` so we
+     *  augment rather than replace the default rendering. */
+    threeObject: ((n: N) => unknown) | undefined;
+    /** 2D mode: walks the node list at the end of every frame and
+     *  draws each visible label on top of everything the kapsule has
+     *  already painted. Wired into the kapsule's `onRenderFramePost`
+     *  callback by `LoraGraphCanvas`. Receives the same world-space
+     *  canvas transform as the inline accessor would have, so the
+     *  drawing math is identical — just the layering changes. */
+    renderFramePost: ((ctx: CanvasRenderingContext2D, globalScale: number) => void) | undefined;
+}
+/** Build the optional `nodeCanvasObject` that draws a small themed pill
+ *  with each node's label beneath it. Returns `undefined` when neither
+ *  the global `showLabels` flag nor any selection demands labels — that
+ *  way the engine prop bag skips the binding entirely on hot paths. */
+export declare function useLabelRenderer<N extends NodeObject>(params: UseLabelRendererParams<N>): NodeLabelRenderer<N>;

package/dist/hooks/useLinkLabelRenderer.d.ts

@@ -0,0 +1,56 @@
+import { Accessor, GraphMode, LinkObject, LoraGraphTheme } from '../types';
+export interface UseLinkLabelRendererParams<L extends LinkObject> {
+    mode: GraphMode;
+    showLabels: boolean;
+    selectedLinkSet: ReadonlySet<string | number>;
+    /** Links to render labels for on hover (e.g. the directly-hovered
+     *  link, or neighbour links of a hovered node). Styled like the
+     *  default caption so the selected pill still stands out. */
+    hoveredLinkSet?: ReadonlySet<string | number>;
+    accentColor: string;
+    hostLinkCanvasObject?: (l: L, ctx: CanvasRenderingContext2D, globalScale: number) => void;
+    hostLinkThreeObject?: (l: L) => unknown;
+    hostLinkPositionUpdate?: ((obj: unknown, coords: {
+        start: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        end: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }, link: L) => void | boolean | null) | null;
+    linkLabel?: Accessor<string | HTMLElement, L>;
+    theme?: Partial<LoraGraphTheme>;
+}
+export interface LinkLabelRenderer<L> {
+    /** 2D: `linkCanvasObject` drawing the label along the link. */
+    canvasObject: ((l: L, ctx: CanvasRenderingContext2D, scale: number) => void) | undefined;
+    /** 3D: `linkThreeObject` returning a sprite for the label. */
+    threeObject: ((l: L) => unknown) | undefined;
+    /** 3D: `linkPositionUpdate` placing the sprite at the midpoint of
+     *  the link each frame. Returns `true` so the kapsule's default
+     *  link tube/line update still runs (we're additive, not
+     *  replacing). */
+    positionUpdate: ((obj: unknown, coords: {
+        start: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        end: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }, link: L) => boolean) | undefined;
+}
+/** Draw a label *along* each link (rotated to match the link's
+ *  bearing, font auto-sized to fit between the endpoint margins).
+ *  Mirrors the canonical force-graph link-label snippet, themed for
+ *  selection. Returns `undefined` when nothing demands a label so the
+ *  engine prop bag skips the binding entirely on hot paths. 2D only —
+ *  the 3D variant lives in `useLinkLabelRenderer3D`. */
+export declare function useLinkLabelRenderer<L extends LinkObject>(params: UseLinkLabelRendererParams<L>): LinkLabelRenderer<L>;

package/dist/hooks/useMarqueeAndCursor.d.ts

@@ -0,0 +1,59 @@
+import { MutableRefObject } from 'react';
+import { GraphEngine } from '../engines/types';
+import { LinkObject, NodeObject } from '../types';
+import { SelectionApi } from './useGraphSelection';
+export interface MarqueeRect {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    additive: boolean;
+}
+export interface UseMarqueeAndCursorParams<N extends NodeObject, L extends LinkObject> {
+    mount: HTMLDivElement | null;
+    /** Trampoline to the live engine — read inside event handlers so we
+     *  always pick up the current engine after a 2D↔3D remount. */
+    engineRef: MutableRefObject<GraphEngine<N, L> | null>;
+    selection: SelectionApi;
+    nodes: ReadonlyArray<N>;
+    links: ReadonlyArray<L>;
+    setSelectedLinkIds: React.Dispatch<React.SetStateAction<Array<string | number>>>;
+    /** Live (non-debounced) hover state from the kapsule's
+     *  `onNodeHover`. Used at shift+mousedown time to decide between
+     *  "shift+click to add to selection" (a node is under the cursor →
+     *  let the click fall through to the kapsule) and "shift+drag to
+     *  marquee" (background → start a rectangle).
+     *
+     *  Must be a ref, not a state value: the host applies a grace-period
+     *  debounce to `hoverNodeId` so labels can persist while the cursor
+     *  briefly leaves a node. Reading a debounced value here would tell
+     *  us "still hovering A" for 250ms after the cursor has actually
+     *  moved away — long enough that the user's next shift+drag would
+     *  be wrongly treated as a click-falling-through-to-A, and no
+     *  marquee would start. */
+    liveHoverNodeIdRef: MutableRefObject<string | number | null>;
+}
+export interface UseMarqueeAndCursorResult {
+    marquee: MarqueeRect | null;
+    /** Last screen-space cursor position over the mount element. Used by
+     *  paste-at-cursor. */
+    lastCursorRef: MutableRefObject<{
+        x: number;
+        y: number;
+    } | null>;
+}
+/** Wires up the canvas-level pointer behaviour that lives outside the
+ *  kapsule:
+ *
+ *  - Shift+drag draws a marquee rectangle. Nodes whose projected screen
+ *    coordinates land inside the rectangle get selected on release.
+ *  - The last cursor position over the mount is tracked into a ref so
+ *    paste-at-cursor knows where to drop new nodes.
+ *  - Any wheel / touch / mousedown on the canvas interrupts an in-flight
+ *    focus animation.
+ *
+ *  The effect mounts once per mount element. Live data is read through a
+ *  ref so the listener identity stays stable across data mutations —
+ *  re-binding ResizeObserver + window listeners on every change would
+ *  otherwise glitch the marquee gesture mid-drag. */
+export declare function useMarqueeAndCursor<N extends NodeObject, L extends LinkObject>(params: UseMarqueeAndCursorParams<N, L>): UseMarqueeAndCursorResult;

package/dist/hooks/usePerfTierDefaults.d.ts

@@ -0,0 +1,13 @@
+import { GraphMode, LinkObject, LoraGraphCanvasProps, NodeObject } from '../types';
+export interface UsePerfTierDefaultsParams {
+    profile: LoraGraphCanvasProps["performanceProfile"];
+    nodeCount: number;
+    linkCount: number;
+    mode: GraphMode;
+}
+/** Pick a perf tier from the live node + link count (or the host's
+ *  explicit override) and turn it into a partial prop bag pre-filling
+ *  perf knobs (cooldownTicks, ngraph layout in 3D, lower mesh
+ *  resolutions, etc). The bag is spread *before* `props` so anything
+ *  the host sets explicitly always wins. */
+export declare function usePerfTierDefaults<N extends NodeObject, L extends LinkObject>(params: UsePerfTierDefaultsParams): Partial<LoraGraphCanvasProps<N, L>>;

package/dist/hooks/useResizeObserver.d.ts

@@ -0,0 +1,7 @@
+import { RefObject } from 'react';
+/** Reports the content rect of `ref.current`. Returns null on the
+ *  initial render. Re-fires whenever the observed element resizes. */
+export declare function useResizeObserver(ref: RefObject<HTMLElement | null>): {
+    width: number;
+    height: number;
+} | null;

package/dist/hooks/useShiftHeld.d.ts

@@ -0,0 +1,5 @@
+/** Track whether Shift is currently held. In 3D mode this lets us
+ *  disable the Three.js navigation controls while the user is drawing a
+ *  marquee — otherwise OrbitControls / TrackballControls would also
+ *  process the same drag and pan the camera. */
+export declare function useShiftHeld(): boolean;