@cosmos.gl/graph 2.4.0 → 2.6.0

package/dist/modules/GraphData/index.d.ts

@@ -24,6 +24,7 @@ export declare class GraphData {
     inputPointClusters: (number | undefined)[] | undefined;
     inputClusterPositions: (number | undefined)[] | undefined;
     inputClusterStrength: Float32Array | undefined;
+    inputPinnedPoints: number[] | undefined;
     pointPositions: Float32Array | undefined;
     pointColors: Float32Array | undefined;
     pointSizes: Float32Array | undefined;

package/dist/modules/Lines/index.d.ts

@@ -1,17 +1,25 @@
+import { default as regl } from 'regl';
 import { CoreModule } from '../core-module';
 export declare class Lines extends CoreModule {
+    linkIndexFbo: regl.Framebuffer2D | undefined;
+    hoveredLineIndexFbo: regl.Framebuffer2D | undefined;
     private drawCurveCommand;
+    private hoveredLineIndexCommand;
     private pointsBuffer;
     private colorBuffer;
     private widthBuffer;
     private arrowBuffer;
     private curveLineGeometry;
     private curveLineBuffer;
+    private linkIndexBuffer;
+    private quadBuffer;
     initPrograms(): void;
     draw(): void;
+    updateLinkIndexFbo(): void;
     updatePointsBuffer(): void;
     updateColor(): void;
     updateWidth(): void;
     updateArrow(): void;
     updateCurveLineGeometry(): void;
+    findHoveredLine(): void;
 }

package/dist/modules/Points/index.d.ts

@@ -39,6 +39,8 @@ export declare class Points extends CoreModule {
     private trackedIndices;
     private selectedTexture;
     private greyoutStatusTexture;
+    private pinnedStatusTexture;
+    private pinnedStatusFbo;
     private sizeTexture;
     private trackedIndicesTexture;
     private polygonPathTexture;
@@ -51,6 +53,7 @@ export declare class Points extends CoreModule {
     initPrograms(): void;
     updateColor(): void;
     updateGreyoutStatus(): void;
+    updatePinnedStatus(): void;
     updateSize(): void;
     updateShape(): void;
     updateImageIndices(): void;

package/dist/modules/Store/index.d.ts

@@ -1,6 +1,13 @@
 import { mat3 } from 'gl-matrix';
+import { GraphConfigInterface } from '../../config';
 export declare const ALPHA_MIN = 0.001;
 export declare const MAX_POINT_SIZE = 64;
+/**
+ * Maximum number of executions to delay before performing hover detection.
+ * This threshold prevents excessive hover detection calls for performance optimization.
+ * The `findHoveredItem` method will skip actual detection until this count is reached.
+ */
+export declare const MAX_HOVER_DETECTION_DELAY = 4;
 export type Hovered = {
     index: number;
     position: [number, number];
@@ -24,14 +31,17 @@ export declare class Store {
     hoveredPoint: Hovered | undefined;
     focusedPoint: Focused | undefined;
     draggingPointIndex: number | undefined;
+    hoveredLinkIndex: number | undefined;
     adjustedSpaceSize: number;
     isSpaceKeyPressed: boolean;
     div: HTMLDivElement | undefined;
     webglMaxTextureSize: number;
     hoveredPointRingColor: number[];
     focusedPointRingColor: number[];
+    hoveredLinkColor: number[];
     greyoutPointColor: number[];
     isDarkenGreyout: boolean;
+    isLinkHoveringEnabled: boolean;
     private alphaTarget;
     private scalePointX;
     private scalePointY;
@@ -53,9 +63,11 @@ export declare class Store {
     updateScreenSize(width: number, height: number): void;
     scaleX(x: number): number;
     scaleY(y: number): number;
-    setHoveredPointRingColor(color: string): void;
-    setFocusedPointRingColor(color: string): void;
+    setHoveredPointRingColor(color: string | [number, number, number, number]): void;
+    setFocusedPointRingColor(color: string | [number, number, number, number]): void;
     setGreyoutPointColor(color: string | [number, number, number, number] | undefined): void;
+    updateLinkHoveringEnabled(config: Pick<GraphConfigInterface, 'onLinkClick' | 'onLinkMouseOver' | 'onLinkMouseOut'>): void;
+    setHoveredLinkColor(color?: string | [number, number, number, number]): void;
     setFocusedPoint(index?: number): void;
     addAlpha(decay: number): number;
     private alphaDecay;

package/dist/modules/core-module.d.ts

@@ -9,5 +9,6 @@ export declare class CoreModule {
     readonly store: Store;
     readonly data: GraphData;
     readonly points: Points | undefined;
+    _debugRandomNumber: number;
     constructor(reglInstance: regl.Regl, config: GraphConfigInterface, store: Store, data: GraphData, points?: Points);
 }

package/dist/stories/beginners/link-hovering/data-generator.d.ts

@@ -0,0 +1,19 @@
+interface Point {
+    id: number;
+}
+interface Link {
+    source: number;
+    target: number;
+}
+interface NetworkData {
+    pointPositions: Float32Array;
+    pointColors: Float32Array;
+    pointSizes: Float32Array;
+    links: Float32Array;
+    linkColors: Float32Array;
+    linkWidths: Float32Array;
+    points: Point[];
+    connections: Link[];
+}
+export declare function generateData(pointCount?: number): NetworkData;
+export {};

package/dist/stories/beginners/link-hovering/index.d.ts

@@ -0,0 +1,5 @@
+import { Graph } from '../../..';
+export declare const linkHovering: () => {
+    div: HTMLDivElement;
+    graph: Graph;
+};

package/dist/stories/beginners/pinned-points/data-gen.d.ts

@@ -0,0 +1,5 @@
+export declare function generateData(numNodes?: number): {
+    pointPositions: Float32Array;
+    links: Float32Array;
+    pointColors: Float32Array;
+};

package/dist/stories/beginners/pinned-points/index.d.ts

@@ -0,0 +1,5 @@
+import { Graph } from '../../..';
+export declare const pinnedPoints: () => {
+    graph: Graph;
+    div: HTMLDivElement;
+};

package/dist/stories/beginners.stories.d.ts

@@ -6,4 +6,6 @@ export declare const QuickStart: Story;
 export declare const BasicSetUp: Story;
 export declare const PointLabels: Story;
 export declare const RemovePoints: Story;
+export declare const LinkHovering: Story;
+export declare const PinnedPoints: Story;
 export default meta;

package/dist/variables.d.ts

@@ -13,18 +13,21 @@ export declare const defaultConfigValues: {
     spaceSize: number;
     pointSizeScale: number;
     linkWidthScale: number;
-    arrowSizeScale: number;
+    linkArrowsSizeScale: number;
     renderLinks: boolean;
     curvedLinks: boolean;
     curvedLinkSegments: number;
     curvedLinkWeight: number;
     curvedLinkControlPointDistance: number;
-    arrowLinks: boolean;
+    linkArrows: boolean;
     linkVisibilityDistanceRange: number[];
     linkVisibilityMinTransparency: number;
     hoveredPointCursor: string;
+    hoveredLinkCursor: string;
     renderHoveredPointRing: boolean;
     hoveredPointRingColor: string;
+    hoveredLinkColor: undefined;
+    hoveredLinkWidthIncrease: number;
     focusedPointRingColor: string;
     focusedPointIndex: undefined;
     useClassicQuadtree: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmos.gl/graph",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "GPU-based force graph layout and rendering",
   "jsdelivr": "dist/index.min.js",
   "main": "dist/index.js",

package/src/config.ts

@@ -44,6 +44,9 @@ 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];
 
   /**
@@ -51,7 +54,7 @@ export interface GraphConfigInterface {
    * 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
@@ -98,6 +101,12 @@ export interface GraphConfigInterface {
    */
   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`
@@ -158,6 +167,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`
@@ -324,9 +346,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.
@@ -339,6 +367,40 @@ export interface GraphConfigInterface {
     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,
@@ -374,6 +436,22 @@ export interface GraphConfigInterface {
    */
   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
@@ -540,12 +618,18 @@ export class GraphConfig implements GraphConfigInterface {
   public backgroundColor = defaultBackgroundColor
   public spaceSize = defaultConfigValues.spaceSize
   public pointColor = defaultPointColor
+  // TODO: When pointColor is removed, change this to:
+  // public pointDefaultColor = defaultPointColor
+  // Currently undefined to allow fallback to deprecated pointColor via nullish coalescing
+  // in GraphData.updatePointColor() (see: this._config.pointDefaultColor ?? this._config.pointColor)
+  public pointDefaultColor = undefined
   public pointGreyoutOpacity = defaultGreyoutPointOpacity
   public pointGreyoutColor = defaultGreyoutPointColor
   public pointSize = defaultPointSize
   public pointOpacity = defaultPointOpacity
   public pointSizeScale = defaultConfigValues.pointSizeScale
   public hoveredPointCursor = defaultConfigValues.hoveredPointCursor
+  public hoveredLinkCursor = defaultConfigValues.hoveredLinkCursor
   public renderHoveredPointRing = defaultConfigValues.renderHoveredPointRing
   public hoveredPointRingColor = defaultConfigValues.hoveredPointRingColor
   public focusedPointRingColor = defaultConfigValues.focusedPointRingColor
@@ -555,13 +639,15 @@ export class GraphConfig implements GraphConfigInterface {
   public linkGreyoutOpacity = defaultGreyoutLinkOpacity
   public linkWidth = defaultLinkWidth
   public linkWidthScale = defaultConfigValues.linkWidthScale
+  public hoveredLinkColor = defaultConfigValues.hoveredLinkColor
+  public hoveredLinkWidthIncrease = defaultConfigValues.hoveredLinkWidthIncrease
   public renderLinks = defaultConfigValues.renderLinks
   public curvedLinks = defaultConfigValues.curvedLinks
   public curvedLinkSegments = defaultConfigValues.curvedLinkSegments
   public curvedLinkWeight = defaultConfigValues.curvedLinkWeight
   public curvedLinkControlPointDistance = defaultConfigValues.curvedLinkControlPointDistance
-  public linkArrows = defaultConfigValues.arrowLinks
-  public linkArrowsSizeScale = defaultConfigValues.arrowSizeScale
+  public linkArrows = defaultConfigValues.linkArrows
+  public linkArrowsSizeScale = defaultConfigValues.linkArrowsSizeScale
   public scaleLinksOnZoom = defaultConfigValues.scaleLinksOnZoom
   public linkVisibilityDistanceRange = defaultConfigValues.linkVisibilityDistanceRange
   public linkVisibilityMinTransparency = defaultConfigValues.linkVisibilityMinTransparency
@@ -586,11 +672,17 @@ export class GraphConfig implements GraphConfigInterface {
   public onSimulationEnd: GraphConfigInterface['onSimulationEnd'] = undefined
   public onSimulationPause: GraphConfigInterface['onSimulationPause'] = undefined
   public onSimulationRestart: GraphConfigInterface['onSimulationRestart'] = undefined
+  public onSimulationUnpause: GraphConfigInterface['onSimulationUnpause'] = undefined
 
   public onClick: GraphConfigInterface['onClick'] = undefined
+  public onPointClick: GraphConfigInterface['onPointClick'] = undefined
+  public onLinkClick: GraphConfigInterface['onLinkClick'] = undefined
+  public onBackgroundClick: GraphConfigInterface['onBackgroundClick'] = undefined
   public onMouseMove: GraphConfigInterface['onMouseMove'] = undefined
   public onPointMouseOver: GraphConfigInterface['onPointMouseOver'] = undefined
   public onPointMouseOut: GraphConfigInterface['onPointMouseOut'] = undefined
+  public onLinkMouseOver: GraphConfigInterface['onLinkMouseOver'] = undefined
+  public onLinkMouseOut: GraphConfigInterface['onLinkMouseOut'] = undefined
   public onZoomStart: GraphConfigInterface['onZoomStart'] = undefined
   public onZoom: GraphConfigInterface['onZoom'] = undefined
   public onZoomEnd: GraphConfigInterface['onZoomEnd'] = undefined