@cosmos.gl/graph 2.2.1 → 2.3.0

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

@@ -55,6 +55,11 @@ export declare class Points extends CoreModule {
     trackPointsByIndices(indices?: number[] | undefined): void;
     getTrackedPositionsMap(): Map<number, [number, number]>;
     getSampledPointPositionsMap(): Map<number, [number, number]>;
+    getSampledPoints(): {
+        indices: number[];
+        positions: number[];
+    };
+    getTrackedPositionsArray(): number[];
     private swapFbo;
     private rescaleInitialNodePositions;
 }

package/dist/variables.d.ts

@@ -1,9 +1,11 @@
 export declare const defaultPointColor = "#b3b3b3";
 export declare const defaultGreyoutPointOpacity: undefined;
 export declare const defaultGreyoutPointColor: undefined;
+export declare const defaultPointOpacity = 1;
 export declare const defaultPointSize = 4;
 export declare const defaultLinkColor = "#666666";
 export declare const defaultGreyoutLinkOpacity = 0.1;
+export declare const defaultLinkOpacity = 1;
 export declare const defaultLinkWidth = 1;
 export declare const defaultBackgroundColor = "#222222";
 export declare const defaultConfigValues: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmos.gl/graph",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "GPU-based force graph layout and rendering",
   "jsdelivr": "dist/index.min.js",
   "main": "dist/index.js",
@@ -53,6 +53,7 @@
     "@types/d3-selection": "^3.0.2",
     "@types/d3-transition": "^3.0.1",
     "@types/d3-zoom": "^3.0.1",
+    "@types/dompurify": "^3.0.5",
     "@typescript-eslint/eslint-plugin": "^5.30.5",
     "@typescript-eslint/parser": "^5.30.5",
     "@zerollup/ts-transform-paths": "^1.7.18",
@@ -84,6 +85,7 @@
     "d3-selection": "^3.0.0",
     "d3-transition": "^3.0.1",
     "d3-zoom": "^3.0.0",
+    "dompurify": "^3.2.6",
     "gl-bench": "^1.0.42",
     "gl-matrix": "^3.4.3",
     "random": "^4.1.0",

package/src/config.ts

@@ -4,9 +4,11 @@ import {
   defaultPointColor,
   defaultGreyoutPointOpacity,
   defaultGreyoutPointColor,
+  defaultPointOpacity,
   defaultPointSize,
   defaultLinkColor,
   defaultGreyoutLinkOpacity,
+  defaultLinkOpacity,
   defaultLinkWidth,
   defaultBackgroundColor,
   defaultConfigValues,
@@ -74,6 +76,15 @@ export interface GraphConfigInterface {
    * Default value: `4`
   */
   pointSize?: number;
+
+  /**
+   * Universal opacity value applied to all points.
+   * This value multiplies with individual point alpha values (if set via setPointColors).
+   * Useful for dynamically controlling opacity of all points without updating individual RGBA arrays.
+   * Default value: `1.0`
+   */
+  pointOpacity?: number;
+
   /**
    * Scale factor for the point size.
    * Default value: `1`
@@ -128,6 +139,14 @@ export interface GraphConfigInterface {
    */
   linkColor?: string | [number, number, number, number];
 
+  /**
+   * Universal opacity value applied to all links.
+   * This value multiplies with individual link alpha values (if set via setLinkColors).
+   * Useful for dynamically controlling opacity of all links without updating individual RGBA arrays.
+   * Default value: `1.0`
+   */
+  linkOpacity?: number;
+
   /**
    * Greyed out link opacity value when the selection is active.
    * Default value: `0.1`
@@ -517,6 +536,7 @@ export class GraphConfig implements GraphConfigInterface {
   public pointGreyoutOpacity = defaultGreyoutPointOpacity
   public pointGreyoutColor = defaultGreyoutPointColor
   public pointSize = defaultPointSize
+  public pointOpacity = defaultPointOpacity
   public pointSizeScale = defaultConfigValues.pointSizeScale
   public hoveredPointCursor = defaultConfigValues.hoveredPointCursor
   public renderHoveredPointRing = defaultConfigValues.renderHoveredPointRing
@@ -524,6 +544,7 @@ export class GraphConfig implements GraphConfigInterface {
   public focusedPointRingColor = defaultConfigValues.focusedPointRingColor
   public focusedPointIndex = defaultConfigValues.focusedPointIndex
   public linkColor = defaultLinkColor
+  public linkOpacity = defaultLinkOpacity
   public linkGreyoutOpacity = defaultGreyoutLinkOpacity
   public linkWidth = defaultLinkWidth
   public linkWidthScale = defaultConfigValues.linkWidthScale

package/src/helper.ts

@@ -1,5 +1,6 @@
 import { color as d3Color } from 'd3-color'
 import regl from 'regl'
+import DOMPurify from 'dompurify'
 
 export const isFunction = <T>(a: T): boolean => typeof a === 'function'
 export const isArray = <T>(a: unknown | T[]): a is T[] => Array.isArray(a)
@@ -50,3 +51,24 @@ export function clamp (num: number, min: number, max: number): number {
 export function isNumber (value: number | undefined | null | typeof NaN): boolean {
   return value !== undefined && value !== null && !Number.isNaN(value)
 }
+
+/**
+ * Sanitizes HTML content to prevent XSS attacks using DOMPurify
+ *
+ * This function is used internally to sanitize HTML content before setting innerHTML,
+ * such as in attribution text. It uses a safe default configuration that allows
+ * only common safe HTML elements and attributes.
+ *
+ * @param html The HTML string to sanitize
+ * @param options Optional DOMPurify configuration options to override defaults
+ * @returns Sanitized HTML string safe for innerHTML usage
+ */
+export function sanitizeHtml (html: string, options?: DOMPurify.Config): string {
+  return DOMPurify.sanitize(html, {
+    // Default configuration: allow common safe HTML elements and attributes
+    ALLOWED_TAGS: ['a', 'b', 'i', 'em', 'strong', 'span', 'div', 'p', 'br'],
+    ALLOWED_ATTR: ['href', 'target', 'class', 'id', 'style'],
+    ALLOW_DATA_ATTR: false,
+    ...options,
+  })
+}

package/src/index.ts

@@ -5,7 +5,7 @@ import { D3ZoomEvent } from 'd3-zoom'
 import { D3DragEvent } from 'd3-drag'
 import regl from 'regl'
 import { GraphConfig, GraphConfigInterface } from '@/graph/config'
-import { getRgbaColor, readPixels } from '@/graph/helper'
+import { getRgbaColor, readPixels, sanitizeHtml } from '@/graph/helper'
 import { ForceCenter } from '@/graph/modules/ForceCenter'
 import { ForceGravity } from '@/graph/modules/ForceGravity'
 import { ForceLink, LinkDirection } from '@/graph/modules/ForceLink'
@@ -322,6 +322,17 @@ export class Graph {
     this._needsPointColorUpdate = true
   }
 
+  /**
+   * Gets the current colors of the graph points.
+   *
+   * @returns {Float32Array} A Float32Array representing the colors of points in the format [r1, g1, b1, a1, r2, g2, b2, a2, ..., rn, gn, bn, an],
+   * where each color is in RGBA format. Returns an empty Float32Array if no point colors are set.
+   */
+  public getPointColors (): Float32Array {
+    if (this._isDestroyed) return new Float32Array()
+    return this.graph.pointColors ?? new Float32Array()
+  }
+
   /**
    * Sets the sizes for the graph points.
    *
@@ -335,6 +346,17 @@ export class Graph {
     this._needsPointSizeUpdate = true
   }
 
+  /**
+   * Gets the current sizes of the graph points.
+   *
+   * @returns {Float32Array} A Float32Array representing the sizes of points in the format [size1, size2, ..., sizen],
+   * where `n` is the index of the point. Returns an empty Float32Array if no point sizes are set.
+   */
+  public getPointSizes (): Float32Array {
+    if (this._isDestroyed) return new Float32Array()
+    return this.graph.pointSizes ?? new Float32Array()
+  }
+
   /**
    * Sets the links for the graph.
    *
@@ -367,6 +389,17 @@ export class Graph {
     this._needsLinkColorUpdate = true
   }
 
+  /**
+   * Gets the current colors of the graph links.
+   *
+   * @returns {Float32Array} A Float32Array representing the colors of links in the format [r1, g1, b1, a1, r2, g2, b2, a2, ..., rn, gn, bn, an],
+   * where each color is in RGBA format. Returns an empty Float32Array if no link colors are set.
+   */
+  public getLinkColors (): Float32Array {
+    if (this._isDestroyed) return new Float32Array()
+    return this.graph.linkColors ?? new Float32Array()
+  }
+
   /**
    * Sets the widths for the graph links.
    *
@@ -380,6 +413,17 @@ export class Graph {
     this._needsLinkWidthUpdate = true
   }
 
+  /**
+   * Gets the current widths of the graph links.
+   *
+   * @returns {Float32Array} A Float32Array representing the widths of links in the format [width1, width2, ..., widthn],
+   * where `n` is the index of the link. Returns an empty Float32Array if no link widths are set.
+   */
+  public getLinkWidths (): Float32Array {
+    if (this._isDestroyed) return new Float32Array()
+    return this.graph.linkWidths ?? new Float32Array()
+  }
+
   /**
    * Sets the arrows for the graph links.
    *
@@ -882,6 +926,17 @@ export class Graph {
     return this.points.getTrackedPositionsMap()
   }
 
+  /**
+   * Get current X and Y coordinates of the tracked points as an array.
+   * @returns Array of point positions in the format [x1, y1, x2, y2, ..., xn, yn] for tracked points only.
+   * The positions are ordered by the tracking indices (same order as provided to trackPointPositionsByIndices).
+   * Returns an empty array if no points are being tracked.
+   */
+  public getTrackedPointPositionsArray (): number[] {
+    if (this._isDestroyed || !this.points) return []
+    return this.points.getTrackedPositionsArray()
+  }
+
   /**
    * For the points that are currently visible on the screen, get a sample of point indices with their coordinates.
    * The resulting number of points will depend on the `pointSamplingDistance` configuration property,
@@ -893,6 +948,17 @@ export class Graph {
     return this.points.getSampledPointPositionsMap()
   }
 
+  /**
+   * For the points that are currently visible on the screen, get a sample of point indices and positions.
+   * The resulting number of points will depend on the `pointSamplingDistance` configuration property,
+   * and the sampled points will be evenly distributed.
+   * @returns An object containing arrays of point indices and positions.
+   */
+  public getSampledPoints (): { indices: number[]; positions: number[] } {
+    if (this._isDestroyed || !this.points) return { indices: [], positions: [] }
+    return this.points.getSampledPoints()
+  }
+
   /**
    * Gets the X-axis of rescaling function.
    *
@@ -920,10 +986,15 @@ export class Graph {
   public start (alpha = 1): void {
     if (this._isDestroyed) return
     if (!this.graph.pointsNumber) return
-    this.store.isSimulationRunning = true
+
+    // Only start the simulation if alpha > 0
+    if (alpha > 0) {
+      this.store.isSimulationRunning = true
+      this.store.simulationProgress = 0
+      this.config.onSimulationStart?.()
+    }
+
     this.store.alpha = alpha
-    this.store.simulationProgress = 0
-    this.config.onSimulationStart?.()
     this.stopFrames()
     this.frame()
   }
@@ -1330,7 +1401,12 @@ export class Graph {
       font-size: 0.7rem;
       font-family: inherit;
     `
-    this.attributionDivElement.innerHTML = this.config.attribution
+    // Sanitize the attribution HTML content to prevent XSS attacks
+    // Use more permissive settings for attribution since it's controlled by the library user
+    this.attributionDivElement.innerHTML = sanitizeHtml(this.config.attribution, {
+      ALLOWED_TAGS: ['a', 'b', 'i', 'em', 'strong', 'span', 'div', 'p', 'br', 'img'],
+      ALLOWED_ATTR: ['href', 'target', 'class', 'id', 'style', 'src', 'alt', 'title'],
+    })
     this.store.div?.appendChild(this.attributionDivElement)
   }
 }

package/src/modules/Lines/draw-curve-line.frag

@@ -5,6 +5,7 @@ varying vec2 pos;
 varying float arrowLength;
 varying float useArrow;
 varying float smoothing;
+varying float arrowWidthFactor;
 
 float map(float value, float min1, float max1, float min2, float max2) {
   return min2 + (value - min1) * (max2 - min2) / (max1 - min1);
@@ -17,7 +18,7 @@ void main() {
   if (useArrow > 0.5) {
     float end_arrow = 0.5 + arrowLength / 2.0;
     float start_arrow = end_arrow - arrowLength;
-    float arrowWidthDelta = 0.25;
+    float arrowWidthDelta = arrowWidthFactor / 2.0;
     float linkOpacity = rgbaColor.a * smoothstep(0.5 - arrowWidthDelta, 0.5 - arrowWidthDelta - smoothing / 2.0, abs(pos.y));
     float arrowOpacity = 1.0;
     if (pos.x > start_arrow && pos.x < start_arrow + arrowLength) {

package/src/modules/Lines/draw-curve-line.vert

@@ -15,6 +15,7 @@ uniform float spaceSize;
 uniform vec2 screenSize;
 uniform vec2 linkVisibilityDistanceRange;
 uniform float linkVisibilityMinTransparency;
+uniform float linkOpacity;
 uniform float greyoutOpacity;
 uniform float curvedWeight;
 uniform float curvedLinkControlPointDistance;
@@ -27,6 +28,7 @@ varying vec2 pos;
 varying float arrowLength;
 varying float useArrow;
 varying float smoothing;
+varying float arrowWidthFactor;
 
 float map(float value, float min1, float max1, float min2, float max2) {
   return min2 + (value - min1) * (max2 - min2) / (max1 - min1);
@@ -95,9 +97,11 @@ void main() {
   float linkWidth = width * widthScale;
   float k = 2.0;
   // Arrow width is proportionally larger than the line width
-  float arrowWidth = max(5.0, linkWidth * k);
+  float arrowWidth = linkWidth * k;
   arrowWidth *= arrowSizeScale;
 
+  float arrowWidthDifference = arrowWidth - linkWidth;
+
   // Calculate arrow width in pixels
   float arrowWidthPx = calculateArrowWidth(arrowWidth);
 
@@ -108,9 +112,11 @@ void main() {
 
   useArrow = arrow;
   if (useArrow > 0.5) {
-    linkWidth *= 2.0;
+    linkWidth += arrowWidthDifference;
   }
 
+  arrowWidthFactor = arrowWidthDifference / linkWidth;
+
   // Calculate final link width in pixels with smoothing
   float linkWidthPx = calculateLinkWidth(linkWidth);
   float smoothingPx = 0.5 / transformationMatrix[0][0];
@@ -120,7 +126,7 @@ void main() {
   // Calculate final color with opacity based on link distance
   vec3 rgbColor = color.rgb;
   // Adjust opacity based on link distance
-  float opacity = color.a * max(linkVisibilityMinTransparency, map(linkDistPx, linkVisibilityDistanceRange.g, linkVisibilityDistanceRange.r, 0.0, 1.0));
+  float opacity = color.a * linkOpacity * max(linkVisibilityMinTransparency, map(linkDistPx, linkVisibilityDistanceRange.g, linkVisibilityDistanceRange.r, 0.0, 1.0));
 
   // Apply greyed out opacity if either endpoint is greyed out
   if (greyoutStatusA.r > 0.0 || greyoutStatusB.r > 0.0) {

package/src/modules/Lines/index.ts

@@ -69,6 +69,7 @@ export class Lines extends CoreModule {
           screenSize: () => store.screenSize,
           linkVisibilityDistanceRange: () => config.linkVisibilityDistanceRange,
           linkVisibilityMinTransparency: () => config.linkVisibilityMinTransparency,
+          linkOpacity: () => config.linkOpacity,
           greyoutOpacity: () => config.linkGreyoutOpacity,
           scaleLinksOnZoom: () => config.scaleLinksOnZoom,
           maxPointSize: () => store.maxPointSize,

package/src/modules/Points/draw-highlighted.vert

@@ -14,6 +14,7 @@ uniform bool scalePointsOnZoom;
 uniform float pointIndex;
 uniform float maxPointSize;
 uniform vec4 color;
+uniform float universalPointOpacity;
 uniform float greyoutOpacity;
 uniform bool darkenGreyout;
 uniform vec4 backgroundColor;
@@ -41,7 +42,7 @@ void main () {
   vec4 pointPosition = texture2D(positionsTexture, textureCoordinates / pointsTextureSize);
 
   rgbColor = color.rgb;
-  pointOpacity = color.a;
+  pointOpacity = color.a * universalPointOpacity;
   vec4 greyoutStatus = texture2D(pointGreyoutStatusTexture, textureCoordinates / pointsTextureSize);
   if (greyoutStatus.r > 0.0) {
     if (greyoutColor[0] != -1.0) {

package/src/modules/Points/draw-points.vert

@@ -15,6 +15,7 @@ uniform float sizeScale;
 uniform float spaceSize;
 uniform vec2 screenSize;
 uniform float greyoutOpacity;
+uniform float pointOpacity;
 uniform vec4 greyoutColor;
 uniform vec4 backgroundColor;
 uniform bool scalePointsOnZoom;
@@ -51,7 +52,7 @@ void main() {
   gl_PointSize = calculatePointSize(size * sizeScale);
 
   rgbColor = color.rgb;
-  alpha = color.a;
+  alpha = color.a * pointOpacity;
 
   // Adjust alpha of selected points
   vec4 greyoutStatus = texture2D(pointGreyoutStatus, (textureCoords + 0.5) / pointsTextureSize);

package/src/modules/Points/index.ts

@@ -232,6 +232,7 @@ export class Points extends CoreModule {
           transformationMatrix: () => store.transform,
           spaceSize: () => store.adjustedSpaceSize,
           screenSize: () => store.screenSize,
+          pointOpacity: () => config.pointOpacity,
           greyoutOpacity: () => config.pointGreyoutOpacity ?? -1,
           greyoutColor: () => store.greyoutPointColor,
           backgroundColor: () => store.backgroundColor,
@@ -412,6 +413,7 @@ export class Points extends CoreModule {
           scalePointsOnZoom: () => config.scalePointsOnZoom,
           maxPointSize: () => store.maxPointSize,
           pointGreyoutStatusTexture: () => this.greyoutStatusFbo,
+          universalPointOpacity: () => config.pointOpacity,
           greyoutOpacity: () => config.pointGreyoutOpacity ?? -1,
           darkenGreyout: () => store.darkenGreyout,
           backgroundColor: () => store.backgroundColor,
@@ -695,6 +697,47 @@ export class Points extends CoreModule {
     return positions
   }
 
+  public getSampledPoints (): { indices: number[]; positions: number[] } {
+    const indices: number[] = []
+    const positions: number[] = []
+    if (!this.sampledPointsFbo) return { indices, positions }
+
+    this.clearSampledPointsFboCommand?.()
+    this.fillSampledPointsFboCommand?.()
+    const pixels = readPixels(this.reglInstance, this.sampledPointsFbo as regl.Framebuffer2D)
+
+    for (let i = 0; i < pixels.length / 4; i++) {
+      const index = pixels[i * 4]
+      const isNotEmpty = !!pixels[i * 4 + 1]
+      const x = pixels[i * 4 + 2]
+      const y = pixels[i * 4 + 3]
+
+      if (isNotEmpty && index !== undefined && x !== undefined && y !== undefined) {
+        indices.push(index)
+        positions.push(x, y)
+      }
+    }
+
+    return { indices, positions }
+  }
+
+  public getTrackedPositionsArray (): number[] {
+    const positions: number[] = []
+    if (!this.trackedIndices) return positions
+    positions.length = this.trackedIndices.length * 2
+    const pixels = readPixels(this.reglInstance, this.trackedPositionsFbo as regl.Framebuffer2D)
+    for (let i = 0; i < pixels.length / 4; i += 1) {
+      const x = pixels[i * 4]
+      const y = pixels[i * 4 + 1]
+      const index = this.trackedIndices[i]
+      if (x !== undefined && y !== undefined && index !== undefined) {
+        positions[i * 2] = x
+        positions[i * 2 + 1] = y
+      }
+    }
+    return positions
+  }
+
   private swapFbo (): void {
     const temp = this.previousPositionFbo
     this.previousPositionFbo = this.currentPositionFbo

package/src/stories/2. configuration.mdx

@@ -13,6 +13,7 @@ import { Meta } from "@storybook/blocks";
 | pointGreyoutOpacity | Greyed out point opacity value when the selection is active | `undefined` |
 | pointGreyoutColor | Greyed out point color value when the selection is active | `undefined` |
 | pointSize | The default size value to use for points when no point sizes are provided or if the size value in the array is `undefined` or `null` | `4` |
+| pointOpacity | Universal opacity value applied to all points. This value multiplies with individual point alpha values (if set via setPointColors). Useful for dynamically controlling opacity of all points without updating individual RGBA arrays. | `1.0` |
 | pointSizeScale | Scale factor for the point size | `1` |
 | hoveredPointCursor | Cursor style to use when hovering over a point | `auto` |
 | renderHoveredPointRing | Turns ring rendering around a point on hover on / off | `false` |
@@ -21,6 +22,7 @@ import { Meta } from "@storybook/blocks";
 | focusedPointIndex | Set focus on a point by index. A ring will be highlighted around the focused point. When set to `undefined`, no point is focused. | `undefined` |
 | renderLinks | Turns link rendering on / off | `true` |
 | linkColor | The default color to use for links when no link colors are provided, or if the color value in the array is `undefined` or `null`. This can be either a hex color string (e.g., '#666666') or an array of RGBA values in the format `[red, green, blue, alpha]` where each value is a number between 0 and 255 | `#666666` |
+| linkOpacity | Universal opacity value applied to all links. This value multiplies with individual link alpha values (if set via setLinkColors). Useful for dynamically controlling opacity of all links without updating individual RGBA arrays. | `1.0` |
 | linkGreyoutOpacity | Greyed out link opacity value when the selection is active | `0.1` |
 | linkWidth | The default width value to use for links when no link widths are provided or if the width value in the array is `undefined` or `null` | `1` |
 | linkWidthScale | Scale factor for the link width | `1` |