@cyvest/cyvest-vis 5.4.1 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +57 -50
  2. package/dist/index.cjs +537 -637
  3. package/dist/index.d.cts +49 -60
  4. package/dist/index.d.ts +49 -60
  5. package/dist/index.js +541 -636
  6. package/dist/styles.css +29 -86
  7. package/package.json +10 -10
package/dist/index.d.cts CHANGED
@@ -1,8 +1,7 @@
1
1
  import React from 'react';
2
- import { CyvestInvestigation, Level, RelationshipDirection } from '@cyvest/cyvest-js';
3
- import { Core, NodeSingular, EdgeSingular, LayoutOptions } from 'cytoscape';
2
+ import { CyvestInvestigation, RelationshipDirection, Level } from '@cyvest/cyvest-js';
3
+ import { EdgeSingular, NodeSingular, Core, ElementDefinition, Position, LayoutOptions } from 'cytoscape';
4
4
 
5
- type CyvestViewMode = "observables" | "investigation";
6
5
  interface CyvestThemeTokens {
7
6
  background: string;
8
7
  gridColor: string;
@@ -14,22 +13,39 @@ interface CyvestThemeTokens {
14
13
  edgeColor: string;
15
14
  edgeSelectedColor: string;
16
15
  fontFamily: string;
16
+ /** Default fill for internal observable nodes. */
17
+ nodeSurface: string;
18
+ /** Root node fill. */
19
+ rootSurface: string;
20
+ /** Icon/text color used on the root node. */
21
+ rootText: string;
22
+ /** Primary icon stroke color. */
23
+ iconColor: string;
24
+ /** Muted icon stroke color (non-root nodes). */
25
+ iconMutedColor: string;
26
+ /** Color that level-based backgrounds are mixed toward. */
27
+ levelSurfaceMix: string;
28
+ /** Mix ratio (0-1) toward {@link levelSurfaceMix}. */
29
+ levelSurfaceMixRatio: number;
17
30
  }
18
31
  declare const DEFAULT_CYVEST_THEME: CyvestThemeTokens;
19
- type CyvestElkDirection = "RIGHT" | "LEFT" | "UP" | "DOWN";
20
- interface CyvestElkOptions {
21
- algorithm?: string;
22
- direction?: CyvestElkDirection;
23
- spacingNodeNode?: number;
24
- spacingEdgeNode?: number;
25
- spacingBetweenLayers?: number;
32
+ declare const DARK_CYVEST_THEME: CyvestThemeTokens;
33
+ interface CyvestForceOptions {
34
+ linkDistance?: number;
35
+ linkStrength?: number;
36
+ chargeStrength?: number;
37
+ collisionPadding?: number;
38
+ radialStep?: number;
39
+ radialStrength?: number;
40
+ centerStrength?: number;
41
+ iterations?: number;
26
42
  padding?: number;
27
43
  fit?: boolean;
28
44
  animate?: boolean;
29
- extra?: Record<string, string | number | boolean>;
45
+ animationDuration?: number;
30
46
  }
31
47
  interface CyNodeSelectEvent {
32
- view: CyvestViewMode;
48
+ view: "observables";
33
49
  nodeId: string;
34
50
  nodeType: string;
35
51
  label: string;
@@ -37,7 +53,7 @@ interface CyNodeSelectEvent {
37
53
  element: NodeSingular;
38
54
  }
39
55
  interface CyEdgeSelectEvent {
40
- view: CyvestViewMode;
56
+ view: "observables";
41
57
  edgeId: string;
42
58
  sourceId: string;
43
59
  targetId: string;
@@ -51,29 +67,21 @@ interface CyvestBaseViewProps {
51
67
  width?: number | string;
52
68
  className?: string;
53
69
  theme?: Partial<CyvestThemeTokens>;
70
+ /** Keep the d3-force simulation active and reheat it while nodes are dragged. */
71
+ physics?: boolean;
54
72
  onCyReady?: (cy: Core) => void;
55
73
  onNodeSelect?: (event: CyNodeSelectEvent) => void;
56
74
  onEdgeSelect?: (event: CyEdgeSelectEvent) => void;
57
75
  }
58
76
  interface CyvestObservablesViewProps extends CyvestBaseViewProps {
59
- layout?: CyvestElkOptions;
60
- showToolbar?: boolean;
61
- maxLabelLength?: number;
62
- }
63
- interface CyvestInvestigationViewProps extends CyvestBaseViewProps {
64
- layout?: CyvestElkOptions;
77
+ layout?: CyvestForceOptions;
65
78
  showToolbar?: boolean;
66
79
  maxLabelLength?: number;
67
80
  }
68
81
  interface CyvestGraphProps extends CyvestBaseViewProps {
69
- initialView?: CyvestViewMode;
70
- showViewToggle?: boolean;
71
- onViewChange?: (view: CyvestViewMode) => void;
72
82
  showToolbar?: boolean;
73
- observablesLayout?: CyvestElkOptions;
74
- investigationLayout?: CyvestElkOptions;
75
- maxObservableLabelLength?: number;
76
- maxInvestigationLabelLength?: number;
83
+ layout?: CyvestForceOptions;
84
+ maxLabelLength?: number;
77
85
  }
78
86
  interface ObservableCyNodeData extends Record<string, unknown> {
79
87
  id: string;
@@ -86,7 +94,7 @@ interface ObservableCyNodeData extends Record<string, unknown> {
86
94
  isRoot: boolean;
87
95
  whitelisted: boolean;
88
96
  internal: boolean;
89
- shape: "ellipse" | "round-rectangle" | "rectangle";
97
+ shape: "ellipse" | "round-rectangle" | "rectangle" | "diamond";
90
98
  width: number;
91
99
  height: number;
92
100
  borderWidth: number;
@@ -104,53 +112,34 @@ interface ObservableCyEdgeData extends Record<string, unknown> {
104
112
  sourceArrowShape: "none" | "triangle";
105
113
  targetArrowShape: "none" | "triangle";
106
114
  }
107
- type InvestigationCyNodeType = "root" | "tag" | "check";
108
- interface InvestigationCyNodeData extends Record<string, unknown> {
109
- id: string;
110
- nodeType: InvestigationCyNodeType;
111
- labelShort: string;
112
- labelFull: string;
113
- level: Level;
114
- score: number;
115
- borderColor: string;
116
- fillColor: string;
117
- icon: string;
118
- width: number;
119
- height: number;
120
- shape: "round-rectangle";
121
- borderWidth: number;
122
- }
123
- interface InvestigationCyEdgeData extends Record<string, unknown> {
124
- id: string;
125
- relationshipType: string;
126
- color: string;
127
- width: number;
128
- sourceArrowShape: "none" | "triangle";
129
- targetArrowShape: "none" | "triangle";
130
- }
131
115
 
116
+ /** Render the observable relationship graph for a Cyvest investigation. */
132
117
  declare const CyvestGraph: React.FC<CyvestGraphProps>;
133
118
 
134
119
  declare const CyvestObservablesView: React.FC<CyvestObservablesViewProps>;
135
120
 
136
- declare const CyvestInvestigationView: React.FC<CyvestInvestigationViewProps>;
137
-
138
121
  interface IconRenderOptions {
139
122
  color?: string;
140
123
  }
141
- type IconName = "globe" | "domain" | "link" | "mail" | "file" | "hash" | "flask" | "question" | "crosshair" | "check" | "tag";
124
+ type IconName = "globe" | "domain" | "link" | "mail" | "file" | "hash" | "flask" | "question" | "finding";
142
125
  declare const OBSERVABLE_ICON_NAME_MAP: Record<string, IconName>;
143
- declare const INVESTIGATION_ICON_NAME_MAP: Record<InvestigationCyNodeType, IconName>;
144
126
  declare function getObservableIconSvg(observableType: string, options?: IconRenderOptions): string;
145
- declare function getInvestigationIconSvg(nodeType: InvestigationCyNodeType, options?: IconRenderOptions): string;
146
127
 
147
128
  declare function truncateLabel(value: string, maxLength?: number, truncateMiddle?: boolean): string;
148
129
 
149
130
  declare function getLevelColor(level: Level): string;
131
+ /** Mix `hex` toward `target` by `ratio` (0 = hex, 1 = target). */
132
+ declare function mixHexColor(hex: string, target: string, ratio: number): string;
150
133
  declare function lightenHexColor(hex: string, ratio: number): string;
151
- declare function getLevelBackgroundColor(level: Level): string;
134
+ declare function getLevelBackgroundColor(level: Level, theme?: Partial<CyvestThemeTokens>): string;
152
135
 
153
- declare function getDefaultElkOptions(view: CyvestViewMode): CyvestElkOptions;
154
- declare function createElkLayout(view: CyvestViewMode, overrides?: CyvestElkOptions): LayoutOptions;
136
+ interface ForceSimulationController {
137
+ reheat: () => void;
138
+ stop: () => void;
139
+ }
140
+ declare function getDefaultForceOptions(): Required<CyvestForceOptions>;
141
+ declare function computeForcePositions(elements: ElementDefinition[], overrides?: CyvestForceOptions): Record<string, Position>;
142
+ declare function startForceSimulation(cy: Core, overrides?: CyvestForceOptions): ForceSimulationController;
143
+ declare function createForceLayout(elements: ElementDefinition[], overrides?: CyvestForceOptions): LayoutOptions;
155
144
 
156
- export { type CyEdgeSelectEvent, type CyNodeSelectEvent, type CyvestBaseViewProps, type CyvestElkDirection, type CyvestElkOptions, CyvestGraph, type CyvestGraphProps, CyvestInvestigationView, type CyvestInvestigationViewProps, CyvestObservablesView, type CyvestObservablesViewProps, type CyvestThemeTokens, type CyvestViewMode, DEFAULT_CYVEST_THEME, INVESTIGATION_ICON_NAME_MAP, type IconRenderOptions, type InvestigationCyEdgeData, type InvestigationCyNodeData, type InvestigationCyNodeType, OBSERVABLE_ICON_NAME_MAP, type ObservableCyEdgeData, type ObservableCyNodeData, createElkLayout, getDefaultElkOptions, getInvestigationIconSvg, getLevelBackgroundColor, getLevelColor, getObservableIconSvg, lightenHexColor, truncateLabel };
145
+ export { type CyEdgeSelectEvent, type CyNodeSelectEvent, type CyvestBaseViewProps, type CyvestForceOptions, CyvestGraph, type CyvestGraphProps, CyvestObservablesView, type CyvestObservablesViewProps, type CyvestThemeTokens, DARK_CYVEST_THEME, DEFAULT_CYVEST_THEME, type ForceSimulationController, type IconRenderOptions, OBSERVABLE_ICON_NAME_MAP, type ObservableCyEdgeData, type ObservableCyNodeData, computeForcePositions, createForceLayout, getDefaultForceOptions, getLevelBackgroundColor, getLevelColor, getObservableIconSvg, lightenHexColor, mixHexColor, startForceSimulation, truncateLabel };
package/dist/index.d.ts CHANGED
@@ -1,8 +1,7 @@
1
1
  import React from 'react';
2
- import { CyvestInvestigation, Level, RelationshipDirection } from '@cyvest/cyvest-js';
3
- import { Core, NodeSingular, EdgeSingular, LayoutOptions } from 'cytoscape';
2
+ import { CyvestInvestigation, RelationshipDirection, Level } from '@cyvest/cyvest-js';
3
+ import { EdgeSingular, NodeSingular, Core, ElementDefinition, Position, LayoutOptions } from 'cytoscape';
4
4
 
5
- type CyvestViewMode = "observables" | "investigation";
6
5
  interface CyvestThemeTokens {
7
6
  background: string;
8
7
  gridColor: string;
@@ -14,22 +13,39 @@ interface CyvestThemeTokens {
14
13
  edgeColor: string;
15
14
  edgeSelectedColor: string;
16
15
  fontFamily: string;
16
+ /** Default fill for internal observable nodes. */
17
+ nodeSurface: string;
18
+ /** Root node fill. */
19
+ rootSurface: string;
20
+ /** Icon/text color used on the root node. */
21
+ rootText: string;
22
+ /** Primary icon stroke color. */
23
+ iconColor: string;
24
+ /** Muted icon stroke color (non-root nodes). */
25
+ iconMutedColor: string;
26
+ /** Color that level-based backgrounds are mixed toward. */
27
+ levelSurfaceMix: string;
28
+ /** Mix ratio (0-1) toward {@link levelSurfaceMix}. */
29
+ levelSurfaceMixRatio: number;
17
30
  }
18
31
  declare const DEFAULT_CYVEST_THEME: CyvestThemeTokens;
19
- type CyvestElkDirection = "RIGHT" | "LEFT" | "UP" | "DOWN";
20
- interface CyvestElkOptions {
21
- algorithm?: string;
22
- direction?: CyvestElkDirection;
23
- spacingNodeNode?: number;
24
- spacingEdgeNode?: number;
25
- spacingBetweenLayers?: number;
32
+ declare const DARK_CYVEST_THEME: CyvestThemeTokens;
33
+ interface CyvestForceOptions {
34
+ linkDistance?: number;
35
+ linkStrength?: number;
36
+ chargeStrength?: number;
37
+ collisionPadding?: number;
38
+ radialStep?: number;
39
+ radialStrength?: number;
40
+ centerStrength?: number;
41
+ iterations?: number;
26
42
  padding?: number;
27
43
  fit?: boolean;
28
44
  animate?: boolean;
29
- extra?: Record<string, string | number | boolean>;
45
+ animationDuration?: number;
30
46
  }
31
47
  interface CyNodeSelectEvent {
32
- view: CyvestViewMode;
48
+ view: "observables";
33
49
  nodeId: string;
34
50
  nodeType: string;
35
51
  label: string;
@@ -37,7 +53,7 @@ interface CyNodeSelectEvent {
37
53
  element: NodeSingular;
38
54
  }
39
55
  interface CyEdgeSelectEvent {
40
- view: CyvestViewMode;
56
+ view: "observables";
41
57
  edgeId: string;
42
58
  sourceId: string;
43
59
  targetId: string;
@@ -51,29 +67,21 @@ interface CyvestBaseViewProps {
51
67
  width?: number | string;
52
68
  className?: string;
53
69
  theme?: Partial<CyvestThemeTokens>;
70
+ /** Keep the d3-force simulation active and reheat it while nodes are dragged. */
71
+ physics?: boolean;
54
72
  onCyReady?: (cy: Core) => void;
55
73
  onNodeSelect?: (event: CyNodeSelectEvent) => void;
56
74
  onEdgeSelect?: (event: CyEdgeSelectEvent) => void;
57
75
  }
58
76
  interface CyvestObservablesViewProps extends CyvestBaseViewProps {
59
- layout?: CyvestElkOptions;
60
- showToolbar?: boolean;
61
- maxLabelLength?: number;
62
- }
63
- interface CyvestInvestigationViewProps extends CyvestBaseViewProps {
64
- layout?: CyvestElkOptions;
77
+ layout?: CyvestForceOptions;
65
78
  showToolbar?: boolean;
66
79
  maxLabelLength?: number;
67
80
  }
68
81
  interface CyvestGraphProps extends CyvestBaseViewProps {
69
- initialView?: CyvestViewMode;
70
- showViewToggle?: boolean;
71
- onViewChange?: (view: CyvestViewMode) => void;
72
82
  showToolbar?: boolean;
73
- observablesLayout?: CyvestElkOptions;
74
- investigationLayout?: CyvestElkOptions;
75
- maxObservableLabelLength?: number;
76
- maxInvestigationLabelLength?: number;
83
+ layout?: CyvestForceOptions;
84
+ maxLabelLength?: number;
77
85
  }
78
86
  interface ObservableCyNodeData extends Record<string, unknown> {
79
87
  id: string;
@@ -86,7 +94,7 @@ interface ObservableCyNodeData extends Record<string, unknown> {
86
94
  isRoot: boolean;
87
95
  whitelisted: boolean;
88
96
  internal: boolean;
89
- shape: "ellipse" | "round-rectangle" | "rectangle";
97
+ shape: "ellipse" | "round-rectangle" | "rectangle" | "diamond";
90
98
  width: number;
91
99
  height: number;
92
100
  borderWidth: number;
@@ -104,53 +112,34 @@ interface ObservableCyEdgeData extends Record<string, unknown> {
104
112
  sourceArrowShape: "none" | "triangle";
105
113
  targetArrowShape: "none" | "triangle";
106
114
  }
107
- type InvestigationCyNodeType = "root" | "tag" | "check";
108
- interface InvestigationCyNodeData extends Record<string, unknown> {
109
- id: string;
110
- nodeType: InvestigationCyNodeType;
111
- labelShort: string;
112
- labelFull: string;
113
- level: Level;
114
- score: number;
115
- borderColor: string;
116
- fillColor: string;
117
- icon: string;
118
- width: number;
119
- height: number;
120
- shape: "round-rectangle";
121
- borderWidth: number;
122
- }
123
- interface InvestigationCyEdgeData extends Record<string, unknown> {
124
- id: string;
125
- relationshipType: string;
126
- color: string;
127
- width: number;
128
- sourceArrowShape: "none" | "triangle";
129
- targetArrowShape: "none" | "triangle";
130
- }
131
115
 
116
+ /** Render the observable relationship graph for a Cyvest investigation. */
132
117
  declare const CyvestGraph: React.FC<CyvestGraphProps>;
133
118
 
134
119
  declare const CyvestObservablesView: React.FC<CyvestObservablesViewProps>;
135
120
 
136
- declare const CyvestInvestigationView: React.FC<CyvestInvestigationViewProps>;
137
-
138
121
  interface IconRenderOptions {
139
122
  color?: string;
140
123
  }
141
- type IconName = "globe" | "domain" | "link" | "mail" | "file" | "hash" | "flask" | "question" | "crosshair" | "check" | "tag";
124
+ type IconName = "globe" | "domain" | "link" | "mail" | "file" | "hash" | "flask" | "question" | "finding";
142
125
  declare const OBSERVABLE_ICON_NAME_MAP: Record<string, IconName>;
143
- declare const INVESTIGATION_ICON_NAME_MAP: Record<InvestigationCyNodeType, IconName>;
144
126
  declare function getObservableIconSvg(observableType: string, options?: IconRenderOptions): string;
145
- declare function getInvestigationIconSvg(nodeType: InvestigationCyNodeType, options?: IconRenderOptions): string;
146
127
 
147
128
  declare function truncateLabel(value: string, maxLength?: number, truncateMiddle?: boolean): string;
148
129
 
149
130
  declare function getLevelColor(level: Level): string;
131
+ /** Mix `hex` toward `target` by `ratio` (0 = hex, 1 = target). */
132
+ declare function mixHexColor(hex: string, target: string, ratio: number): string;
150
133
  declare function lightenHexColor(hex: string, ratio: number): string;
151
- declare function getLevelBackgroundColor(level: Level): string;
134
+ declare function getLevelBackgroundColor(level: Level, theme?: Partial<CyvestThemeTokens>): string;
152
135
 
153
- declare function getDefaultElkOptions(view: CyvestViewMode): CyvestElkOptions;
154
- declare function createElkLayout(view: CyvestViewMode, overrides?: CyvestElkOptions): LayoutOptions;
136
+ interface ForceSimulationController {
137
+ reheat: () => void;
138
+ stop: () => void;
139
+ }
140
+ declare function getDefaultForceOptions(): Required<CyvestForceOptions>;
141
+ declare function computeForcePositions(elements: ElementDefinition[], overrides?: CyvestForceOptions): Record<string, Position>;
142
+ declare function startForceSimulation(cy: Core, overrides?: CyvestForceOptions): ForceSimulationController;
143
+ declare function createForceLayout(elements: ElementDefinition[], overrides?: CyvestForceOptions): LayoutOptions;
155
144
 
156
- export { type CyEdgeSelectEvent, type CyNodeSelectEvent, type CyvestBaseViewProps, type CyvestElkDirection, type CyvestElkOptions, CyvestGraph, type CyvestGraphProps, CyvestInvestigationView, type CyvestInvestigationViewProps, CyvestObservablesView, type CyvestObservablesViewProps, type CyvestThemeTokens, type CyvestViewMode, DEFAULT_CYVEST_THEME, INVESTIGATION_ICON_NAME_MAP, type IconRenderOptions, type InvestigationCyEdgeData, type InvestigationCyNodeData, type InvestigationCyNodeType, OBSERVABLE_ICON_NAME_MAP, type ObservableCyEdgeData, type ObservableCyNodeData, createElkLayout, getDefaultElkOptions, getInvestigationIconSvg, getLevelBackgroundColor, getLevelColor, getObservableIconSvg, lightenHexColor, truncateLabel };
145
+ export { type CyEdgeSelectEvent, type CyNodeSelectEvent, type CyvestBaseViewProps, type CyvestForceOptions, CyvestGraph, type CyvestGraphProps, CyvestObservablesView, type CyvestObservablesViewProps, type CyvestThemeTokens, DARK_CYVEST_THEME, DEFAULT_CYVEST_THEME, type ForceSimulationController, type IconRenderOptions, OBSERVABLE_ICON_NAME_MAP, type ObservableCyEdgeData, type ObservableCyNodeData, computeForcePositions, createForceLayout, getDefaultForceOptions, getLevelBackgroundColor, getLevelColor, getObservableIconSvg, lightenHexColor, mixHexColor, startForceSimulation, truncateLabel };