@cyvest/cyvest-vis 3.2.0 → 4.1.0

package/README.md

@@ -1,14 +1,17 @@
 # @cyvest/cyvest-vis
 
-React components for visualizing Cyvest investigations using XYFlow + D3 layouts.
+React components for visualizing Cyvest investigations using React Flow + D3 force layouts.
 
-## What it does
+## Features
 
-- Renders observables, relationships, checks, and containers as an interactive graph.
-- Uses `@cyvest/cyvest-js` helpers for level colors, graph data, and schema-safe types.
-- Ships CJS, ESM, and type definitions for React 18+ projects.
+- **Two visualization modes**: Observables graph (force-directed) and Investigation graph (hierarchical Dagre layout)
+- **Interactive force simulation**: Drag nodes, adjust forces in real-time
+- **Professional SVG icons**: Clean icons for all observable types (IPs, domains, emails, files, threats, etc.)
+- **Level-aware styling**: Nodes colored by security level (SAFE, INFORMATIVE, SUSPICIOUS, MALICIOUS)
+- **Responsive design**: Works at any size with zoom, pan, and minimap controls
+- Uses `@cyvest/cyvest-js` for types, colors, and graph data extraction
 
-## Install & build
+## Installation
 
 ```bash
 pnpm install          # from repo root
@@ -23,20 +26,129 @@ pnpm --filter @cyvest/cyvest-vis test
 
 ## Usage
 
+### Basic Usage
+
 ```tsx
 import { CyvestGraph } from "@cyvest/cyvest-vis";
 import type { CyvestInvestigation } from "@cyvest/cyvest-js";
 
-export function InvestigationView({ investigation }: { investigation: CyvestInvestigation }) {
+function InvestigationView({ investigation }: { investigation: CyvestInvestigation }) {
   return (
     <CyvestGraph
       investigation={investigation}
-      height={520}
+      height={600}
       showViewToggle
-      onNodeClick={(id) => console.log("Selected", id)}
+      onNodeClick={(id) => console.log("Selected:", id)}
     />
   );
 }
 ```
 
-Props include `height`, `width`, `showViewToggle`, `onNodeClick`, and optional control over zoom/pan behaviour. See `src/components` for more advanced hooks and utilities.
+### Components
+
+#### `CyvestGraph`
+
+Main component with toggle between Observables and Investigation views.
+
+```tsx
+<CyvestGraph
+  investigation={investigation}
+  height={600}
+  width="100%"
+  initialView="observables"  // or "investigation"
+  showViewToggle={true}
+  onNodeClick={(nodeId) => {}}
+/>
+```
+
+#### `ObservablesGraph`
+
+Force-directed graph showing all observables and their relationships.
+
+```tsx
+import { ObservablesGraph } from "@cyvest/cyvest-vis";
+
+<ObservablesGraph
+  investigation={investigation}
+  height={600}
+  width="100%"
+  showControls={true}  // Show force layout controls
+  forceConfig={{
+    chargeStrength: -200,
+    linkDistance: 80,
+    collisionRadius: 45,
+  }}
+  onNodeClick={(nodeId) => {}}
+  onNodeDoubleClick={(nodeId) => {}}
+/>
+```
+
+#### `InvestigationGraph`
+
+Hierarchical graph showing root → containers → checks structure.
+
+```tsx
+import { InvestigationGraph } from "@cyvest/cyvest-vis";
+
+<InvestigationGraph
+  investigation={investigation}
+  height={600}
+  width="100%"
+  onNodeClick={(nodeId, nodeType) => {
+    // nodeType: "root" | "check" | "container"
+  }}
+/>
+```
+
+### Custom Icons
+
+Access icon components for custom UIs:
+
+```tsx
+import { getObservableIcon, getInvestigationIcon, GlobeIcon, MailIcon } from "@cyvest/cyvest-vis";
+
+// Get icon by observable type
+const Icon = getObservableIcon("ipv4-addr"); // Returns GlobeIcon
+<Icon size={24} color="#3b82f6" />
+
+// Or use icons directly
+<GlobeIcon size={16} color="currentColor" />
+<MailIcon size={16} color="#ef4444" />
+```
+
+Available icons: `GlobeIcon`, `DomainIcon`, `LinkIcon`, `MailIcon`, `EnvelopeIcon`, `FileIcon`, `HashIcon`, `UserIcon`, `IdCardIcon`, `GearIcon`, `AppIcon`, `RegistryIcon`, `ThreatActorIcon`, `BugIcon`, `SwordIcon`, `TargetIcon`, `AlertIcon`, `FlaskIcon`, `CertificateIcon`, `WifiIcon`, `WorldIcon`, `QuestionIcon`, `CheckIcon`, `BoxIcon`, `CrosshairIcon`
+
+## Types
+
+```tsx
+import type {
+  CyvestGraphProps,
+  ObservablesGraphProps,
+  InvestigationGraphProps,
+  ForceLayoutConfig,
+  ObservableNodeData,
+  InvestigationNodeData,
+  InvestigationNodeType,
+} from "@cyvest/cyvest-vis";
+```
+
+### Force Layout Configuration
+
+```tsx
+interface ForceLayoutConfig {
+  chargeStrength: number;   // Repulsion strength (default: -200)
+  linkDistance: number;     // Target link distance (default: 80)
+  centerStrength: number;   // Center pull strength (default: 0.05)
+  collisionRadius: number;  // Node collision radius (default: 45)
+  iterations: number;       // Iterations for static layout (default: 300)
+}
+```
+
+## Peer Dependencies
+
+- React 19+
+- React DOM 19+
+
+## License
+
+See repository root for license information.

package/dist/index.d.mts

@@ -1,21 +1,121 @@
 import React from 'react';
 import * as _cyvest_cyvest_js from '@cyvest/cyvest-js';
+import { Level } from '@cyvest/cyvest-js';
 
+/**
+ * Shape types for observable nodes.
+ * In the current design, all non-root nodes are circles.
+ */
+type ObservableShape = "circle" | "rectangle";
+/**
+ * Data attached to observable graph nodes.
+ */
+interface ObservableNodeData extends Record<string, unknown> {
+    /** Display label (may be truncated) */
+    label: string;
+    /** Full observable value */
+    fullValue: string;
+    /** Observable type (e.g., "domain-name", "ipv4-addr") */
+    observableType: string;
+    /** Security level */
+    level: Level;
+    /** Numeric score */
+    score: number;
+    /** Shape for this node type */
+    shape: ObservableShape;
+    /** Whether this is the root observable */
+    isRoot: boolean;
+    /** Whether the observable is whitelisted */
+    whitelisted: boolean;
+    /** Whether the observable is internal */
+    internal: boolean;
+}
+/**
+ * Data attached to observable graph edges.
+ */
+interface ObservableEdgeData extends Record<string, unknown> {
+    /** Relationship type (e.g., "related-to") */
+    relationshipType: string;
+    /** Whether this is a bidirectional relationship */
+    bidirectional: boolean;
+}
+/**
+ * Node types for the investigation graph view.
+ */
+type InvestigationNodeType = "root" | "check" | "container";
+/**
+ * Data attached to investigation graph nodes.
+ */
+interface InvestigationNodeData extends Record<string, unknown> {
+    /** Display label */
+    label: string;
+    /** Node type (root, check, or container) */
+    nodeType: InvestigationNodeType;
+    /** Security level */
+    level: Level;
+    /** Numeric score */
+    score: number;
+    /** Description (for checks) */
+    description?: string;
+    /** Path (for containers) */
+    path?: string;
+}
 /**
  * Configuration options for d3-force layout.
  */
 interface ForceLayoutConfig {
-    /** Strength of the charge force (repulsion). Default: -300 */
+    /** Strength of the charge force (repulsion). Default: -200 */
     chargeStrength: number;
-    /** Target distance between linked nodes. Default: 100 */
+    /** Target distance between linked nodes. Default: 80 */
     linkDistance: number;
-    /** Strength of the centering force. Default: 0.1 */
+    /** Strength of the centering force. Default: 0.05 */
     centerStrength: number;
-    /** Strength of the collision force. Default: 30 */
+    /** Radius for collision detection. Default: 40 */
     collisionRadius: number;
-    /** Number of simulation iterations. Default: 300 */
+    /** Number of simulation iterations (for static layout). Default: 300 */
     iterations: number;
 }
+/**
+ * Default force layout configuration.
+ * Tuned for good visual separation and smooth animations.
+ */
+declare const DEFAULT_FORCE_CONFIG: ForceLayoutConfig;
+/**
+ * Props for the ObservablesGraph component.
+ */
+interface ObservablesGraphProps {
+    /** The Cyvest investigation to visualize */
+    investigation: _cyvest_cyvest_js.CyvestInvestigation;
+    /** Height of the graph container */
+    height?: number | string;
+    /** Width of the graph container */
+    width?: number | string;
+    /** Force layout configuration */
+    forceConfig?: Partial<ForceLayoutConfig>;
+    /** Callback when a node is clicked */
+    onNodeClick?: (nodeId: string) => void;
+    /** Callback when a node is double-clicked */
+    onNodeDoubleClick?: (nodeId: string) => void;
+    /** Custom class name for the container */
+    className?: string;
+    /** Whether to show the force controls panel */
+    showControls?: boolean;
+}
+/**
+ * Props for the InvestigationGraph component.
+ */
+interface InvestigationGraphProps {
+    /** The Cyvest investigation to visualize */
+    investigation: _cyvest_cyvest_js.CyvestInvestigation;
+    /** Height of the graph container */
+    height?: number | string;
+    /** Width of the graph container */
+    width?: number | string;
+    /** Callback when a node is clicked */
+    onNodeClick?: (nodeId: string, nodeType: InvestigationNodeType) => void;
+    /** Custom class name for the container */
+    className?: string;
+}
 /**
  * Props for the CyvestGraph component (combined view).
  */
@@ -45,4 +145,54 @@ interface CyvestGraphProps {
  */
 declare const CyvestGraph: React.FC<CyvestGraphProps>;
 
-export { CyvestGraph, type CyvestGraphProps, type ForceLayoutConfig };
+/**
+ * ObservablesGraph component - displays observables as a force-directed graph.
+ * Uses iterative d3-force simulation for smooth, interactive layout.
+ */
+
+/**
+ * ObservablesGraph component.
+ * Displays all observables from an investigation as a force-directed graph.
+ * Wraps the inner component with ReactFlowProvider for hook access.
+ */
+declare const ObservablesGraph: React.FC<ObservablesGraphProps>;
+
+/**
+ * InvestigationGraph component - displays investigation structure with Dagre layout.
+ * Shows root observable, checks, and containers in a hierarchical view.
+ */
+
+/**
+ * InvestigationGraph component.
+ * Displays investigation structure with horizontal Dagre layout.
+ */
+declare const InvestigationGraph: React.FC<InvestigationGraphProps>;
+
+/**
+ * Professional SVG icons for the visualization components.
+ * Hand-crafted icons optimized for small sizes and clear recognition.
+ */
+
+interface IconProps {
+    size?: number;
+    color?: string;
+    className?: string;
+}
+/**
+ * Map observable types to icon components
+ */
+declare const OBSERVABLE_ICON_MAP: Record<string, React.FC<IconProps>>;
+/**
+ * Map investigation node types to icons
+ */
+declare const INVESTIGATION_ICON_MAP: Record<string, React.FC<IconProps>>;
+/**
+ * Get the icon component for an observable type.
+ */
+declare function getObservableIcon(observableType: string): React.FC<IconProps>;
+/**
+ * Get the icon component for an investigation node type.
+ */
+declare function getInvestigationIcon(nodeType: string): React.FC<IconProps>;
+
+export { CyvestGraph, type CyvestGraphProps, DEFAULT_FORCE_CONFIG, type ForceLayoutConfig, INVESTIGATION_ICON_MAP, type IconProps, InvestigationGraph, type InvestigationGraphProps, type InvestigationNodeData, type InvestigationNodeType, OBSERVABLE_ICON_MAP, type ObservableEdgeData, type ObservableNodeData, type ObservableShape, ObservablesGraph, type ObservablesGraphProps, getInvestigationIcon, getObservableIcon };

package/dist/index.d.ts

@@ -1,21 +1,121 @@
 import React from 'react';
 import * as _cyvest_cyvest_js from '@cyvest/cyvest-js';
+import { Level } from '@cyvest/cyvest-js';
 
+/**
+ * Shape types for observable nodes.
+ * In the current design, all non-root nodes are circles.
+ */
+type ObservableShape = "circle" | "rectangle";
+/**
+ * Data attached to observable graph nodes.
+ */
+interface ObservableNodeData extends Record<string, unknown> {
+    /** Display label (may be truncated) */
+    label: string;
+    /** Full observable value */
+    fullValue: string;
+    /** Observable type (e.g., "domain-name", "ipv4-addr") */
+    observableType: string;
+    /** Security level */
+    level: Level;
+    /** Numeric score */
+    score: number;
+    /** Shape for this node type */
+    shape: ObservableShape;
+    /** Whether this is the root observable */
+    isRoot: boolean;
+    /** Whether the observable is whitelisted */
+    whitelisted: boolean;
+    /** Whether the observable is internal */
+    internal: boolean;
+}
+/**
+ * Data attached to observable graph edges.
+ */
+interface ObservableEdgeData extends Record<string, unknown> {
+    /** Relationship type (e.g., "related-to") */
+    relationshipType: string;
+    /** Whether this is a bidirectional relationship */
+    bidirectional: boolean;
+}
+/**
+ * Node types for the investigation graph view.
+ */
+type InvestigationNodeType = "root" | "check" | "container";
+/**
+ * Data attached to investigation graph nodes.
+ */
+interface InvestigationNodeData extends Record<string, unknown> {
+    /** Display label */
+    label: string;
+    /** Node type (root, check, or container) */
+    nodeType: InvestigationNodeType;
+    /** Security level */
+    level: Level;
+    /** Numeric score */
+    score: number;
+    /** Description (for checks) */
+    description?: string;
+    /** Path (for containers) */
+    path?: string;
+}
 /**
  * Configuration options for d3-force layout.
  */
 interface ForceLayoutConfig {
-    /** Strength of the charge force (repulsion). Default: -300 */
+    /** Strength of the charge force (repulsion). Default: -200 */
     chargeStrength: number;
-    /** Target distance between linked nodes. Default: 100 */
+    /** Target distance between linked nodes. Default: 80 */
     linkDistance: number;
-    /** Strength of the centering force. Default: 0.1 */
+    /** Strength of the centering force. Default: 0.05 */
     centerStrength: number;
-    /** Strength of the collision force. Default: 30 */
+    /** Radius for collision detection. Default: 40 */
     collisionRadius: number;
-    /** Number of simulation iterations. Default: 300 */
+    /** Number of simulation iterations (for static layout). Default: 300 */
     iterations: number;
 }
+/**
+ * Default force layout configuration.
+ * Tuned for good visual separation and smooth animations.
+ */
+declare const DEFAULT_FORCE_CONFIG: ForceLayoutConfig;
+/**
+ * Props for the ObservablesGraph component.
+ */
+interface ObservablesGraphProps {
+    /** The Cyvest investigation to visualize */
+    investigation: _cyvest_cyvest_js.CyvestInvestigation;
+    /** Height of the graph container */
+    height?: number | string;
+    /** Width of the graph container */
+    width?: number | string;
+    /** Force layout configuration */
+    forceConfig?: Partial<ForceLayoutConfig>;
+    /** Callback when a node is clicked */
+    onNodeClick?: (nodeId: string) => void;
+    /** Callback when a node is double-clicked */
+    onNodeDoubleClick?: (nodeId: string) => void;
+    /** Custom class name for the container */
+    className?: string;
+    /** Whether to show the force controls panel */
+    showControls?: boolean;
+}
+/**
+ * Props for the InvestigationGraph component.
+ */
+interface InvestigationGraphProps {
+    /** The Cyvest investigation to visualize */
+    investigation: _cyvest_cyvest_js.CyvestInvestigation;
+    /** Height of the graph container */
+    height?: number | string;
+    /** Width of the graph container */
+    width?: number | string;
+    /** Callback when a node is clicked */
+    onNodeClick?: (nodeId: string, nodeType: InvestigationNodeType) => void;
+    /** Custom class name for the container */
+    className?: string;
+}
 /**
  * Props for the CyvestGraph component (combined view).
  */
@@ -45,4 +145,54 @@ interface CyvestGraphProps {
  */
 declare const CyvestGraph: React.FC<CyvestGraphProps>;
 
-export { CyvestGraph, type CyvestGraphProps, type ForceLayoutConfig };
+/**
+ * ObservablesGraph component - displays observables as a force-directed graph.
+ * Uses iterative d3-force simulation for smooth, interactive layout.
+ */
+
+/**
+ * ObservablesGraph component.
+ * Displays all observables from an investigation as a force-directed graph.
+ * Wraps the inner component with ReactFlowProvider for hook access.
+ */
+declare const ObservablesGraph: React.FC<ObservablesGraphProps>;
+
+/**
+ * InvestigationGraph component - displays investigation structure with Dagre layout.
+ * Shows root observable, checks, and containers in a hierarchical view.
+ */
+
+/**
+ * InvestigationGraph component.
+ * Displays investigation structure with horizontal Dagre layout.
+ */
+declare const InvestigationGraph: React.FC<InvestigationGraphProps>;
+
+/**
+ * Professional SVG icons for the visualization components.
+ * Hand-crafted icons optimized for small sizes and clear recognition.
+ */
+
+interface IconProps {
+    size?: number;
+    color?: string;
+    className?: string;
+}
+/**
+ * Map observable types to icon components
+ */
+declare const OBSERVABLE_ICON_MAP: Record<string, React.FC<IconProps>>;
+/**
+ * Map investigation node types to icons
+ */
+declare const INVESTIGATION_ICON_MAP: Record<string, React.FC<IconProps>>;
+/**
+ * Get the icon component for an observable type.
+ */
+declare function getObservableIcon(observableType: string): React.FC<IconProps>;
+/**
+ * Get the icon component for an investigation node type.
+ */
+declare function getInvestigationIcon(nodeType: string): React.FC<IconProps>;
+
+export { CyvestGraph, type CyvestGraphProps, DEFAULT_FORCE_CONFIG, type ForceLayoutConfig, INVESTIGATION_ICON_MAP, type IconProps, InvestigationGraph, type InvestigationGraphProps, type InvestigationNodeData, type InvestigationNodeType, OBSERVABLE_ICON_MAP, type ObservableEdgeData, type ObservableNodeData, type ObservableShape, ObservablesGraph, type ObservablesGraphProps, getInvestigationIcon, getObservableIcon };