@cocorof/graphier 1.3.3 → 1.4.0

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
 import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
+import { RefObject } from 'react';
 import * as THREE from 'three';
 
 /** Smoothly animate camera to a new position/target using ease-out */
@@ -66,6 +67,29 @@ export declare interface GraphLink {
     [key: string]: unknown;
 }
 
+export declare function GraphMinimap({ graphRef, width, height, backgroundColor, viewportColor, dotRadius, fps, padding, className, style, }: GraphMinimapProps): JSX_2.Element;
+
+export declare interface GraphMinimapProps {
+    /** Ref to the NetworkGraph3D instance to mirror */
+    graphRef: RefObject<NetworkGraph3DRef | null>;
+    /** Canvas CSS width in px (default: 200) */
+    width?: number;
+    /** Canvas CSS height in px (default: 140) */
+    height?: number;
+    /** Background fill (default: transparent) */
+    backgroundColor?: string;
+    /** Viewport rectangle stroke color (default: "#94a3b8") */
+    viewportColor?: string;
+    /** Dot radius in px (default: 1.5) */
+    dotRadius?: number;
+    /** Redraw rate in frames per second (default: 15) */
+    fps?: number;
+    /** Fraction of canvas kept as padding around the graph (default: 0.08) */
+    padding?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+
 /**
  * Core graph data types — domain-agnostic.
  * Users provide any `type` string ("person", "server", "repo", etc.)
@@ -86,6 +110,20 @@ export declare interface GraphNode {
     [key: string]: unknown;
 }
 
+/** Raw per-frame node buffers for lightweight overlays (e.g. minimap) */
+export declare interface GraphSnapshot {
+    /** xyz triplets, one per node (live buffer — do not mutate) */
+    positions: Float32Array;
+    /** Node count */
+    count: number;
+    /** rgb triplets per node from the instanced mesh (live buffer) */
+    colors: Float32Array | null;
+    /** 1 = hidden by the visibility filter (live buffer) */
+    hidden: Uint8Array | null;
+    /** Index of the selected node, -1 if none */
+    selectedIndex: number;
+}
+
 /**
  * Layout engine configuration.
  */
@@ -109,6 +147,21 @@ export declare interface LayoutConfig {
      * (default: "auto")
      */
     spreadFactor?: "auto" | number;
+    /**
+     * Layout dimensionality (default: 3).
+     * 2 = flat Obsidian-style plane: the simulation runs in 2D (z is locked
+     * to 0), the camera is locked to pan/zoom (no rotation), and dragging
+     * stays on the plane.
+     */
+    dimensions?: 2 | 3;
+    /**
+     * Pull nodes that share the same key toward a common centroid so
+     * categories form visible clusters ("type" reads node.type, "group"
+     * reads node.group). null/undefined = off (default).
+     */
+    clusterBy?: "type" | "group" | null;
+    /** Cluster attraction strength 0..1 (default: 0.05). */
+    clusterStrength?: number;
 }
 
 /** Layout settled callback */
@@ -164,6 +217,25 @@ export declare interface NetworkGraph3DProps {
     labelFormatter?: (node: GraphNode) => string;
     /** Custom node size accessor (overrides node.val) */
     nodeValueAccessor?: (node: GraphNode) => number;
+    /**
+     * Client-side filter: IDs of nodes to keep visible. Hidden nodes (and
+     * their edges/labels) vanish WITHOUT re-running the force layout —
+     * positions are preserved, so toggling filters never reheats the graph.
+     * null/undefined shows everything.
+     */
+    visibleNodeIds?: ReadonlySet<string> | string[] | null;
+    /**
+     * Client-side edge filter: return false to hide a link (e.g. by type).
+     * Same reheat-free mechanism as visibleNodeIds — collapsed segments,
+     * simulation untouched. null/undefined shows all edges.
+     */
+    linkVisibility?: ((link: GraphLink) => boolean) | null;
+    /** Fly the camera to a node on single-click (default: true) */
+    clickToFocus?: boolean;
+    /** Highlight a node's neighborhood on hover when nothing is selected (default: false) */
+    hoverHighlight?: boolean;
+    /** Hops highlighted around the hovered node (default: 1) */
+    hoverHighlightHops?: number;
 }
 
 export declare interface NetworkGraph3DRef {
@@ -201,6 +273,12 @@ export declare interface NetworkGraph3DRef {
     captureScreenshot(): string | null;
     /** Re-run force layout from current positions (useful after changing spreadFactor) */
     reheatLayout(): void;
+    /** Pan the camera to world (x, y), keeping the current zoom (2D-friendly) */
+    panTo(x: number, y: number, duration?: number): void;
+    /** Node position/color/visibility buffers for overlays like GraphMinimap */
+    getGraphSnapshot(): GraphSnapshot | null;
+    /** Current camera footprint on the z=0 plane (meaningful in 2D mode) */
+    getViewportRect(): ViewportRect | null;
 }
 
 export declare function NodeDetailPanel(props: NodeDetailPanelProps): JSX_2.Element;
@@ -237,6 +315,8 @@ export declare type NullableLinkEventHandler = (link: GraphLink | null) => void;
 
 export declare type NullableNodeEventHandler = (node: GraphNode | null) => void;
 
+export declare const paper: ThemeConfig;
+
 /** Runtime node with layout positions (internal) */
 export declare interface PositionedNode extends GraphNode {
     x?: number;
@@ -262,6 +342,10 @@ export declare interface ResolvedTheme {
     nodeColorBright(type?: string): string;
     linkColor(type?: string): string;
     backgroundColor: string;
+    /** True when the background is light — flips highlight/dim direction */
+    isLight: boolean;
+    /** Whether edges should use additive blending (dark backgrounds only) */
+    additiveEdges: boolean;
 }
 
 export declare function resolveTheme(theme?: ThemeConfig | string): ResolvedTheme;
@@ -357,6 +441,20 @@ export declare interface ThemeConfig {
     backgroundColor?: string;
     /** Color palette for auto-assignment when type has no explicit mapping */
     palette?: string[];
+    /**
+     * Edge blend mode. "additive" glows on dark backgrounds; "normal" is
+     * required for light backgrounds (additive lines vanish on white).
+     * Default: "additive" on dark backgrounds, "normal" on light ones.
+     */
+    blending?: "additive" | "normal";
+}
+
+/** Camera frustum footprint on the z=0 plane (world units) */
+export declare interface ViewportRect {
+    cx: number;
+    cy: number;
+    halfW: number;
+    halfH: number;
 }
 
 /** Compute camera position to fit all nodes in view */