@cosmos.gl/graph 2.4.0 → 2.6.0

package/.github/SECURITY.md

@@ -10,4 +10,10 @@ If you have discovered a security vulnerability in this project, please report i
 
 Please disclose it at [security advisory](https://github.com/cosmograph-org/cosmos/security/advisories/new).
 
-This project is maintained by a team of volunteers on a reasonable-effort basis. As such, please give us at least 90 days to work on a fix before public exposure.
+This project is maintained by a team of volunteers on a reasonable-effort basis. As such, please give us at least 90 days to work on a fix before public exposure.
+
+## Escalation
+
+If you do not receive an acknowledgement of your report within 6 business days, or if you cannot find a private security contact for the project, you may escalate to the OpenJS Foundation CNA at `security@lists.openjsf.org`.
+
+If the project acknowledges your report but does not provide any further response or engagement within 14 days, escalation is also appropriate.

package/dist/config.d.ts

@@ -27,13 +27,15 @@ export interface GraphConfigInterface {
      * in the format `[red, green, blue, alpha]` where each value is a number between 0 and 255.
      * Default value: '#b3b3b3'
      */
+    pointDefaultColor?: string | [number, number, number, number];
+    /** @deprecated Use `pointDefaultColor` instead */
     pointColor?: string | [number, number, number, number];
     /**
      * The color to use for points when they are greyed out (when selection is active).
      * This can be either a hex color string (e.g., '#b3b3b3') or an array of RGBA values
      * in the format `[red, green, blue, alpha]` where each value is a number between 0 and 255.
      *
-     * If not provided, the color will be the same as the `pointColor`,
+     * If not provided, the color will be the same as the point's original color,
      * but darkened or lightened depending on the background color.
      *
      * If `pointGreyoutOpacity` is also defined, it will override the alpha/opacity component
@@ -74,6 +76,11 @@ export interface GraphConfigInterface {
      * Default value: `auto`
      */
     hoveredPointCursor?: string;
+    /**
+     * Cursor style to use when hovering over a link
+     * Default value: `auto`
+     */
+    hoveredLinkCursor?: string;
     /**
      * Turns ring rendering around a point on hover on / off
      * Default value: `false`
@@ -127,6 +134,19 @@ export interface GraphConfigInterface {
      * Default value: `1`
     */
     linkWidth?: number;
+    /**
+     * The color to use for links when they are hovered.
+     * This can be either a hex color string (e.g., '#ff3333') or an array of RGBA values
+     * in the format `[red, green, blue, alpha]` where each value is a number between 0 and 255.
+     * Default value: `undefined`
+     */
+    hoveredLinkColor?: string | [number, number, number, number];
+    /**
+     * Number of pixels to add to the link width when hovered.
+     * The hovered width is calculated as: originalWidth + hoveredLinkWidthIncrease
+     * Default value: `5`
+     */
+    hoveredLinkWidthIncrease?: number;
     /**
      * Scale factor for the link width.
      * Default value: `1`
@@ -289,9 +309,15 @@ export interface GraphConfigInterface {
     onSimulationPause?: () => void;
     /**
      * Callback function that will be called when the simulation is restarted.
+     * @deprecated Use `onSimulationUnpause` instead. This callback will be removed in a future version.
      * Default value: `undefined`
      */
     onSimulationRestart?: () => void;
+    /**
+     * Callback function that will be called when the simulation is unpaused.
+     * Default value: `undefined`
+     */
+    onSimulationUnpause?: () => void;
     /**
      * Callback function that will be called on every canvas click.
      * If clicked on a point, its index will be passed as the first argument,
@@ -300,6 +326,28 @@ export interface GraphConfigInterface {
      * Default value: `undefined`
      */
     onClick?: (index: number | undefined, pointPosition: [number, number] | undefined, event: MouseEvent) => void;
+    /**
+     * Callback function that will be called when a point is clicked.
+     * The point index will be passed as the first argument,
+     * position as the second argument and the corresponding mouse event as the third argument:
+     * `(index: number, pointPosition: [number, number], event: MouseEvent) => void`.
+     * Default value: `undefined`
+     */
+    onPointClick?: (index: number, pointPosition: [number, number], event: MouseEvent) => void;
+    /**
+     * Callback function that will be called when a link is clicked.
+     * The link index will be passed as the first argument and the corresponding mouse event as the second argument:
+     * `(linkIndex: number, event: MouseEvent) => void`.
+     * Default value: `undefined`
+     */
+    onLinkClick?: (linkIndex: number, event: MouseEvent) => void;
+    /**
+     * Callback function that will be called when the background (empty space) is clicked.
+     * The mouse event will be passed as the first argument:
+     * `(event: MouseEvent) => void`.
+     * Default value: `undefined`
+     */
+    onBackgroundClick?: (event: MouseEvent) => void;
     /**
      * Callback function that will be called when mouse movement happens.
      * If the mouse moves over a point, its index will be passed as the first argument,
@@ -326,6 +374,20 @@ export interface GraphConfigInterface {
      * Default value: `undefined`
      */
     onPointMouseOut?: (event: MouseEvent | D3ZoomEvent<HTMLCanvasElement, undefined> | D3DragEvent<HTMLCanvasElement, undefined, Hovered> | undefined) => void;
+    /**
+     * Callback function that will be called when the mouse moves over a link.
+     * The link index will be passed as the first argument:
+     * `(linkIndex: number) => void`.
+     * Default value: `undefined`
+     */
+    onLinkMouseOver?: (linkIndex: number) => void;
+    /**
+     * Callback function that will be called when the mouse moves out of a link.
+     * The event will be passed as the first argument:
+     * `(event: MouseEvent | D3ZoomEvent<HTMLCanvasElement, undefined> | D3DragEvent<HTMLCanvasElement, undefined, Hovered> | undefined) => void`.
+     * Default value: `undefined`
+     */
+    onLinkMouseOut?: (event: MouseEvent | D3ZoomEvent<HTMLCanvasElement, undefined> | D3DragEvent<HTMLCanvasElement, undefined, Hovered> | undefined) => void;
     /**
      * Callback function that will be called when zooming or panning starts.
      * First argument is a D3 Zoom Event and second indicates whether
@@ -485,12 +547,14 @@ export declare class GraphConfig implements GraphConfigInterface {
     backgroundColor: string;
     spaceSize: number;
     pointColor: string;
+    pointDefaultColor: undefined;
     pointGreyoutOpacity: undefined;
     pointGreyoutColor: undefined;
     pointSize: number;
     pointOpacity: number;
     pointSizeScale: number;
     hoveredPointCursor: string;
+    hoveredLinkCursor: string;
     renderHoveredPointRing: boolean;
     hoveredPointRingColor: string;
     focusedPointRingColor: string;
@@ -500,6 +564,8 @@ export declare class GraphConfig implements GraphConfigInterface {
     linkGreyoutOpacity: number;
     linkWidth: number;
     linkWidthScale: number;
+    hoveredLinkColor: undefined;
+    hoveredLinkWidthIncrease: number;
     renderLinks: boolean;
     curvedLinks: boolean;
     curvedLinkSegments: number;
@@ -529,10 +595,16 @@ export declare class GraphConfig implements GraphConfigInterface {
     onSimulationEnd: GraphConfigInterface['onSimulationEnd'];
     onSimulationPause: GraphConfigInterface['onSimulationPause'];
     onSimulationRestart: GraphConfigInterface['onSimulationRestart'];
+    onSimulationUnpause: GraphConfigInterface['onSimulationUnpause'];
     onClick: GraphConfigInterface['onClick'];
+    onPointClick: GraphConfigInterface['onPointClick'];
+    onLinkClick: GraphConfigInterface['onLinkClick'];
+    onBackgroundClick: GraphConfigInterface['onBackgroundClick'];
     onMouseMove: GraphConfigInterface['onMouseMove'];
     onPointMouseOver: GraphConfigInterface['onPointMouseOver'];
     onPointMouseOut: GraphConfigInterface['onPointMouseOut'];
+    onLinkMouseOver: GraphConfigInterface['onLinkMouseOver'];
+    onLinkMouseOut: GraphConfigInterface['onLinkMouseOut'];
     onZoomStart: GraphConfigInterface['onZoomStart'];
     onZoom: GraphConfigInterface['onZoom'];
     onZoomEnd: GraphConfigInterface['onZoomEnd'];

package/dist/index.d.ts

@@ -24,12 +24,12 @@ export declare class Graph {
     private fpsMonitor;
     private currentEvent;
     /**
-     * The value of `_findHoveredPointExecutionCount` is incremented by 1 on each animation frame.
-     * When the counter reaches 2 (or more), it is reset to 0 and the `findHoveredPoint` method is executed.
+     * The value of `_findHoveredItemExecutionCount` is incremented by 1 on each animation frame.
+     * When the counter reaches MAX_HOVER_DETECTION_DELAY (default 4), it is reset to 0 and the `findHoveredPoint` or `findHoveredLine` method is executed.
      */
-    private _findHoveredPointExecutionCount;
+    private _findHoveredItemExecutionCount;
     /**
-     * If the mouse is not on the Canvas, the `findHoveredPoint` method will not be executed.
+     * If the mouse is not on the Canvas, the `findHoveredPoint` or `findHoveredLine` method will not be executed.
      */
     private _isMouseOnCanvas;
     /**
@@ -237,6 +237,24 @@ export declare class Graph {
      * Example: `new Float32Array([1, 0.4, 0.3])` sets the force coefficient for point 0 to 1, point 1 to 0.4, and point 2 to 0.3.
      */
     setPointClusterStrength(clusterStrength: Float32Array): void;
+    /**
+     * Sets which points are pinned (fixed) in position.
+     *
+     * Pinned points:
+     * - Do not move due to physics forces (gravity, repulsion, link forces, etc.)
+     * - Still participate in force calculations (other nodes are attracted to/repelled by them)
+     * - Can still be dragged by the user if `enableDrag` is true
+     *
+     * @param {number[] | null} pinnedIndices - Array of point indices to pin. Set to `[]` or `null` to unpin all points.
+     * @example
+     *   // Pin points 0 and 5
+     *   graph.setPinnedPoints([0, 5])
+     *
+     *   // Unpin all points
+     *   graph.setPinnedPoints([])
+     *   graph.setPinnedPoints(null)
+     */
+    setPinnedPoints(pinnedIndices: number[] | null): void;
     /**
      * Renders the graph.
      *
@@ -443,11 +461,19 @@ export declare class Graph {
      */
     start(alpha?: number): void;
     /**
-     * Pause the simulation.
+     * Pause the simulation. When paused, the simulation stops running
+     * and can be resumed using the unpause method.
      */
     pause(): void;
     /**
-     * Restart the simulation.
+     * Unpause the simulation. This method resumes a paused
+     * simulation and continues its execution.
+     */
+    unpause(): void;
+    /**
+     * Restart/Resume the simulation. This method unpauses a paused
+     * simulation and resumes its execution.
+     * @deprecated Use `unpause()` instead. This method will be removed in a future version.
      */
     restart(): void;
     /**
@@ -486,7 +512,9 @@ export declare class Graph {
     private resizeCanvas;
     private setZoomTransformByPointPositions;
     private updateZoomDragBehaviors;
+    private findHoveredItem;
     private findHoveredPoint;
+    private findHoveredLine;
     private updateCanvasCursor;
     private addAttribution;
 }