@cocorof/graphier 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,310 @@
+import { CSSProperties } from 'react';
+import { ForwardRefExoticComponent } from 'react';
+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 * as THREE from 'three';
+
+/** Smoothly animate camera to a new position/target using ease-out */
+export declare function animateCamera(camera: THREE.PerspectiveCamera, controls: OrbitControls, targetPos: CameraTarget, targetLookAt: CameraTarget, duration: number): void;
+
+export declare type BackgroundClickHandler = () => void;
+
+/** Build adjacency map from links */
+export declare function buildAdjacencyMapFromLinks(links: GraphLink[]): Map<string, string[]>;
+
+/**
+ * Build a subgraph of N-hop neighborhood around a center node.
+ * Uses budget-based pruning: all hop 0-1 nodes are kept,
+ * then top nodes by `val` for remaining hops.
+ */
+export declare function buildSubgraph(data: GraphData, centerNodeId: string, adjacencyMap: Map<string, string[]>, options?: SubgraphOptions): SubgraphResult;
+
+declare interface CameraTarget {
+    x: number;
+    y: number;
+    z: number;
+}
+
+export declare const celestial: ThemeConfig;
+
+/** BFS to find nodes within N hops of a root node */
+export declare function computeHighlightSet(rootId: string, adjacencyMap: Map<string, string[]>, maxHops: number): Map<string, number>;
+
+export declare interface ConnectionGroup {
+    title: string;
+    type: string;
+    nodes: GraphNode[];
+}
+
+export declare const DEFAULT_LAYOUT: Required<LayoutConfig>;
+
+export declare const DEFAULT_STYLE: Required<StyleConfig>;
+
+export declare interface GraphData {
+    nodes: GraphNode[];
+    links: GraphLink[];
+}
+
+export declare interface GraphLink {
+    /** Source node id */
+    source: string;
+    /** Target node id */
+    target: string;
+    /** Relationship type — maps to theme colors (e.g. "follows", "owns") */
+    type?: string;
+    /** Edge weight (default: 1) */
+    weight?: number;
+    /** User-defined extra data */
+    [key: string]: unknown;
+}
+
+/**
+ * Core graph data types — domain-agnostic.
+ * Users provide any `type` string ("person", "server", "repo", etc.)
+ * and the theme system maps them to colors automatically.
+ */
+export declare interface GraphNode {
+    /** Unique identifier */
+    id: string;
+    /** Node category — maps to theme colors (e.g. "person", "repo") */
+    type?: string;
+    /** Display label (falls back to id) */
+    label?: string;
+    /** Size weight — higher values render larger (default: 1) */
+    val?: number;
+    /** Grouping key for color auto-assignment (alternative to type) */
+    group?: string;
+    /** User-defined extra data (accessible in callbacks) */
+    [key: string]: unknown;
+}
+
+/**
+ * Layout engine configuration.
+ */
+export declare interface LayoutConfig {
+    /** Layout algorithm (currently only "force-3d") */
+    type?: "force-3d";
+    /** Many-body charge strength — "auto" adapts to graph size, or provide a number (default: "auto") */
+    charge?: "auto" | number;
+    /** Link distance — "auto" adapts to graph size, or provide a number (default: "auto") */
+    linkDistance?: "auto" | number;
+    /** Alpha decay rate — "auto" adapts to graph size (default: "auto") */
+    alphaDecay?: "auto" | number;
+    /** Velocity damping 0..1 (default: 0.4) */
+    velocityDecay?: number;
+    /** Convergence threshold — simulation stops when alpha drops below this (default: 0.005) */
+    settledThreshold?: number;
+}
+
+export declare type LinkEventHandler = (link: GraphLink) => void;
+
+export declare const minimal: ThemeConfig;
+
+export declare const neon: ThemeConfig;
+
+export declare const NetworkGraph3D: ForwardRefExoticComponent<NetworkGraph3DProps & RefAttributes<NetworkGraph3DRef>>;
+
+export declare interface NetworkGraph3DProps {
+    /** Graph data: nodes and links */
+    data: GraphData;
+    /** Single-click on a node (null = background click / deselect) */
+    onNodeClick?: NullableNodeEventHandler;
+    /** Double-click on a node */
+    onNodeDoubleClick?: NodeEventHandler;
+    /** Hover on a node (null = hover out) */
+    onNodeHover?: NullableNodeEventHandler;
+    /** Currently selected node ID (controlled mode) */
+    selectedNodeId?: string | null;
+    /** Number of hops to highlight around selected node (default: 3) */
+    highlightHops?: number;
+    /** Theme configuration or preset name */
+    theme?: ThemeConfig | string;
+    /** Visual style overrides */
+    style?: StyleConfig;
+    /** Force layout configuration */
+    layout?: LayoutConfig;
+    /** WebGL renderer configuration */
+    renderer?: RendererConfig;
+    /** Custom label text formatter */
+    labelFormatter?: (node: GraphNode) => string;
+    /** Custom node size accessor (overrides node.val) */
+    nodeValueAccessor?: (node: GraphNode) => number;
+}
+
+export declare interface NetworkGraph3DRef {
+    /** Animate camera to position, looking at target */
+    cameraPosition(pos: {
+        x: number;
+        y: number;
+        z: number;
+    }, lookAt: {
+        x: number;
+        y: number;
+        z: number;
+    }, duration?: number): void;
+    /** Zoom to fit all nodes in view */
+    zoomToFit(duration?: number, padding?: number): void;
+    /** Zoom in toward center */
+    zoomIn(): void;
+    /** Zoom out from center */
+    zoomOut(): void;
+    /** Focus camera on a specific node */
+    focusNode(nodeId: string, duration?: number): void;
+    /**
+     * Incrementally add nodes and links without full rebuild.
+     * Existing node positions are preserved; new nodes spawn near their neighbors.
+     * Returns the number of new nodes actually added (deduped by ID).
+     */
+    appendData(nodes: GraphNode[], links: GraphLink[]): number;
+    /** Access the Three.js scene */
+    getScene(): THREE.Scene | null;
+    /** Access the Three.js renderer */
+    getRenderer(): THREE.WebGLRenderer | null;
+    /** Access the Three.js camera */
+    getCamera(): THREE.PerspectiveCamera | null;
+    /** Capture a screenshot as a Blob */
+    screenshot(): Promise<Blob | null>;
+}
+
+export declare function NodeDetailPanel(props: NodeDetailPanelProps): JSX_2.Element;
+
+export declare interface NodeDetailPanelProps {
+    node: GraphNode;
+    data: GraphData;
+    adjacencyMap?: Map<string, string[]>;
+    onClose: () => void;
+    onNodeNavigate: (node: GraphNode) => void;
+    theme?: ThemeConfig | string;
+    labelFormatter?: (node: GraphNode) => string;
+    maxHops?: number;
+    maxNodes?: number;
+    renderNodeMeta?: (node: GraphNode) => ReactNode;
+    groupConnections?: (directNeighbors: GraphNode[], links: GraphLink[]) => ConnectionGroup[];
+    connectionLabel?: (node: GraphNode) => string;
+    connectionSecondary?: (node: GraphNode) => ReactNode;
+    modal?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+
+export declare type NodeEventHandler = (node: GraphNode) => void;
+
+export declare type NullableNodeEventHandler = (node: GraphNode | null) => void;
+
+/** Runtime node with layout positions (internal) */
+export declare interface PositionedNode extends GraphNode {
+    x?: number;
+    y?: number;
+    z?: number;
+}
+
+export declare interface RendererConfig {
+    /** WebGL antialiasing (default: false for performance) */
+    antialias?: boolean;
+    /** Max device pixel ratio (default: 1.5) */
+    pixelRatioMax?: number;
+}
+
+export declare interface ResolvedTheme {
+    nodeColor(type?: string): string;
+    nodeColorBright(type?: string): string;
+    linkColor(type?: string): string;
+    backgroundColor: string;
+}
+
+export declare function resolveTheme(theme?: ThemeConfig | string): ResolvedTheme;
+
+export declare interface StyleConfig {
+    /** Minimum node sphere radius (default: 1) */
+    nodeMinSize?: number;
+    /** Maximum node sphere radius (default: 15) */
+    nodeMaxSize?: number;
+    /** Edge line opacity 0..1 (default: 0.15) */
+    edgeOpacity?: number;
+    /** Bloom glow strength (default: 0.6) */
+    bloomStrength?: number;
+    /** Bloom glow radius (default: 0.1) */
+    bloomRadius?: number;
+    /** Bloom brightness threshold (default: 0.1) */
+    bloomThreshold?: number;
+    /** Show background star field (default: true) */
+    starField?: boolean;
+    /** Exponential fog density (default: 0.0006, 0 = disabled) */
+    fogDensity?: number;
+    /** Auto-orbit camera rotation (default: false) */
+    autoOrbit?: boolean;
+    /** Label text scale multiplier (default: 1.0) */
+    labelScale?: number;
+    /** Label visibility distance threshold 0..1 (default: 0.8) */
+    labelThreshold?: number;
+    /** Show labels at all (default: true) */
+    showLabels?: boolean;
+    /** Maximum visible labels at once (default: 150) */
+    maxLabels?: number;
+    /** Edge line width multiplier (default: 1.0). Note: WebGL limits linewidth to 1 on most platforms. */
+    edgeWidthScale?: number;
+}
+
+export declare interface SubgraphOptions {
+    maxHops?: number;
+    maxNodes?: number;
+}
+
+export declare interface SubgraphResult {
+    nodes: GraphNode[];
+    links: GraphLink[];
+    /** Map of node ID → hop distance from center */
+    hops: Map<string, number>;
+}
+
+export declare function SubgraphView2D(props: SubgraphView2DProps): JSX_2.Element;
+
+export declare interface SubgraphView2DProps {
+    /** Full graph data */
+    data: GraphData;
+    /** Center node ID to build subgraph around */
+    centerNodeId: string;
+    /** Max hops from center (default: 3) */
+    maxHops?: number;
+    /** Max nodes in subgraph (default: 250) */
+    maxNodes?: number;
+    /** Theme config or preset name */
+    theme?: ThemeConfig | string;
+    /** Click on a node */
+    onNodeClick?: (node: GraphNode) => void;
+    /** Hover on a node */
+    onNodeHover?: (node: GraphNode | null) => void;
+    /** Custom label formatter */
+    labelFormatter?: (node: GraphNode) => string;
+    /** Container style overrides */
+    style?: CSSProperties;
+    /** Container class name */
+    className?: string;
+}
+
+/**
+ * Theme configuration — controls all visual appearance.
+ */
+export declare interface ThemeConfig {
+    /** Node colors by type string (e.g. { person: "#58a6ff", repo: "#3fb950" }) */
+    nodeColors?: Record<string, string>;
+    /** Brighter node colors for highlights (auto-generated if omitted) */
+    nodeColorsBright?: Record<string, string>;
+    /** Edge colors by type string (e.g. { follows: "#8b949e" }) */
+    linkColors?: Record<string, string>;
+    /** Fallback color for unmapped node types */
+    defaultNodeColor?: string;
+    /** Fallback color for unmapped link types */
+    defaultLinkColor?: string;
+    /** Scene background color */
+    backgroundColor?: string;
+    /** Color palette for auto-assignment when type has no explicit mapping */
+    palette?: string[];
+}
+
+/** Compute camera position to fit all nodes in view */
+export declare function zoomToFitPositions(camera: THREE.PerspectiveCamera, controls: OrbitControls, positions: Float32Array, duration: number, padding: number): void;
+
+export { }