@cosmos.gl/graph 3.0.0-beta.5 → 3.0.0-beta.7

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { Device } from '@luma.gl/core';
-import { GraphConfig, GraphConfigInterface } from './config';
+import { GraphConfigInterface, GraphConfig } from './config';
 import { GraphData } from './modules/GraphData';
 export declare class Graph {
-    config: GraphConfig;
+    /** Current graph configuration. Always fully populated with default values for any unset properties. */
+    config: GraphConfigInterface;
     graph: GraphData;
     /** Promise that resolves when the graph is fully initialized and ready to use */
     readonly ready: Promise<void>;
@@ -80,7 +81,12 @@ export declare class Graph {
     private isForceCenterUpdateNeeded;
     private isPointImageSizesUpdateNeeded;
     private _isDestroyed;
-    constructor(div: HTMLDivElement, config?: GraphConfigInterface, devicePromise?: Promise<Device>);
+    /**
+     * Create a new Graph instance.
+     * @param div - Container element for the graph canvas.
+     * @param config - Optional configuration. Unset properties use default values.
+     */
+    constructor(div: HTMLDivElement, config?: GraphConfig, devicePromise?: Promise<Device>);
     /**
      * Returns the current simulation progress
      */
@@ -95,10 +101,24 @@ export declare class Graph {
      */
     get maxPointSize(): number;
     /**
-     * Set or update Cosmos configuration. The changes will be applied in real time.
-     * @param config Cosmos configuration object.
+     * Apply a new configuration. Changes take effect immediately.
+     *
+     * **Important:** Every call fully resets the configuration to defaults first,
+     * then applies the provided values on top. Properties not included in `config`
+     * will revert to their default values — they are not preserved from the previous call.
+     *
+     * @param config - Configuration object. Only include the properties you want to set.
      */
-    setConfig(config: Partial<GraphConfigInterface>): void;
+    setConfig(config: GraphConfig): void;
+    /**
+     * Partially updates the graph configuration. Only the provided properties
+     * will be changed; all other properties retain their current values.
+     *
+     * Properties set to `undefined` will be reset to their default values.
+     *
+     * @param config - A partial configuration object with the properties to update.
+     */
+    setConfigPartial(config: GraphConfig): void;
     /**
      * Sets the positions for the graph points.
      *
@@ -115,7 +135,7 @@ export declare class Graph {
      *
      * @param {Float32Array} pointColors - 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 represented in RGBA format.
-     * Example: `new Float32Array([255, 0, 0, 1, 0, 255, 0, 1])` sets the first point to red and the second point to green.
+     * Example: `new Float32Array([1, 0, 0, 1, 0, 1, 0, 1])` sets the first point to red and the second point to green.
     */
     setPointColors(pointColors: Float32Array): void;
     /**
@@ -190,7 +210,7 @@ export declare class Graph {
      *
      * @param {Float32Array} linkColors - 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.
-     * Example: `new Float32Array([255, 0, 0, 1, 0, 255, 0, 1])` sets the first link to red and the second link to green.
+     * Example: `new Float32Array([1, 0, 0, 1, 0, 1, 0, 1])` sets the first link to red and the second link to green.
      */
     setLinkColors(linkColors: Float32Array): void;
     /**
@@ -299,20 +319,23 @@ export declare class Graph {
      * @param duration Duration of the animation transition in milliseconds (`700` by default).
      * @param scale Scale value to zoom in or out (`3` by default).
      * @param canZoomOut Set to `false` to prevent zooming out from the point (`true` by default).
+     * @param enableSimulation Whether to run the simulation during the zoom transition (`true` by default).
      */
-    zoomToPointByIndex(index: number, duration?: number, scale?: number, canZoomOut?: boolean): void;
+    zoomToPointByIndex(index: number, duration?: number, scale?: number, canZoomOut?: boolean, enableSimulation?: boolean): void;
     /**
      * Zoom the view in or out to the specified zoom level.
      * @param value Zoom level
      * @param duration Duration of the zoom in/out transition.
+     * @param enableSimulation Whether to run the simulation during the zoom transition (`true` by default).
      */
-    zoom(value: number, duration?: number): void;
+    zoom(value: number, duration?: number, enableSimulation?: boolean): void;
     /**
      * Zoom the view in or out to the specified zoom level.
      * @param value Zoom level
      * @param duration Duration of the zoom in/out transition.
+     * @param enableSimulation Whether to run the simulation during the zoom transition (`true` by default).
      */
-    setZoomLevel(value: number, duration?: number): void;
+    setZoomLevel(value: number, duration?: number, enableSimulation?: boolean): void;
     /**
      * Get zoom level.
      * @returns Zoom level value of the view.
@@ -325,29 +348,32 @@ export declare class Graph {
     getPointPositions(): number[];
     /**
      * Get current X and Y coordinates of the clusters.
-     * @returns Array of point cluster.
+     * @returns Array of cluster positions in `[x0, y0, x1, y1, ...]` order. Do not mutate the returned array.
      */
-    getClusterPositions(): number[];
+    getClusterPositions(): Readonly<number[]>;
     /**
      * Center and zoom in/out the view to fit all points in the scene.
      * @param duration Duration of the center and zoom in/out animation in milliseconds (`250` by default).
      * @param padding Padding around the viewport in percentage (`0.1` by default).
+     * @param enableSimulation Whether to run the simulation during the zoom transition (`true` by default).
      */
-    fitView(duration?: number, padding?: number): void;
+    fitView(duration?: number, padding?: number, enableSimulation?: boolean): void;
     /**
      * Center and zoom in/out the view to fit points by their indices in the scene.
      * @param indices Point indices to fit in the view.
      * @param duration Duration of the center and zoom in/out animation in milliseconds (`250` by default).
      * @param padding Padding around the viewport in percentage (`0.1` by default).
+     * @param enableSimulation Whether to run the simulation during the zoom transition (`true` by default).
      */
-    fitViewByPointIndices(indices: number[], duration?: number, padding?: number): void;
+    fitViewByPointIndices(indices: number[], duration?: number, padding?: number, enableSimulation?: boolean): void;
     /**
      * Center and zoom in/out the view to fit points by their positions in the scene.
      * @param positions Flat array of point coordinates as `[x0, y0, x1, y1, ...]`.
      * @param duration Duration of the center and zoom in/out animation in milliseconds (`250` by default).
      * @param padding Padding around the viewport in percentage (`0.1` by default).
+     * @param enableSimulation Whether to run the simulation during the zoom transition (`true` by default).
      */
-    fitViewByPointPositions(positions: number[], duration?: number, padding?: number): void;
+    fitViewByPointPositions(positions: number[], duration?: number, padding?: number, enableSimulation?: boolean): void;
     /**
      * Sets the zoom transform so that the given point positions fit in the viewport, with optional animation.
      *
@@ -355,8 +381,9 @@ export declare class Graph {
      * @param duration Animation duration in milliseconds. Default `250`.
      * @param scale Optional scale factor; if omitted, scale is chosen to fit the positions.
      * @param padding Padding around the viewport as a fraction (e.g. `0.1` = 10%). Default `0.1`.
+     * @param enableSimulation Whether to run the simulation during the zoom transition (`true` by default).
      */
-    setZoomTransformByPointPositions(positions: Float32Array, duration?: number, scale?: number, padding?: number): void;
+    setZoomTransformByPointPositions(positions: Float32Array, duration?: number, scale?: number, padding?: number, enableSimulation?: boolean): void;
     /**
      * Get points indices inside a rectangular area.
      * @param selection - Array of two corner points `[[left, top], [right, bottom]]`.
@@ -365,15 +392,6 @@ export declare class Graph {
      * @returns A Float32Array containing the indices of points inside a rectangular area.
      */
     getPointsInRect(selection: [[number, number], [number, number]]): Float32Array;
-    /**
-     * Get points indices inside a rectangular area.
-     * @param selection - Array of two corner points `[[left, top], [right, bottom]]`.
-     * The `left` and `right` coordinates should be from 0 to the width of the canvas.
-     * The `top` and `bottom` coordinates should be from 0 to the height of the canvas.
-     * @returns A Float32Array containing the indices of points inside a rectangular area.
-     * @deprecated Use `getPointsInRect` instead. This method will be removed in a future version.
-     */
-    getPointsInRange(selection: [[number, number], [number, number]]): Float32Array;
     /**
      * Get points indices inside a polygon area.
      * @param polygonPath - Array of points `[[x1, y1], [x2, y2], ..., [xn, yn]]` that defines the polygon.
@@ -386,13 +404,6 @@ export declare class Graph {
      * The `left` and `right` coordinates should be from 0 to the width of the canvas.
      * The `top` and `bottom` coordinates should be from 0 to the height of the canvas. */
     selectPointsInRect(selection: [[number, number], [number, number]] | null): void;
-    /** Select points inside a rectangular area.
-     * @param selection - Array of two corner points `[[left, top], [right, bottom]]`.
-     * The `left` and `right` coordinates should be from 0 to the width of the canvas.
-     * The `top` and `bottom` coordinates should be from 0 to the height of the canvas.
-     * @deprecated Use `selectPointsInRect` instead. This method will be removed in a future version.
-     */
-    selectPointsInRange(selection: [[number, number], [number, number]] | null): void;
     /** Select points inside a polygon area.
      * @param polygonPath - Array of points `[[x1, y1], [x2, y2], ..., [xn, yn]]` that defines the polygon.
      * The coordinates should be from 0 to the width/height of the canvas.
@@ -484,6 +495,24 @@ export declare class Graph {
         indices: number[];
         positions: number[];
     };
+    /**
+     * For the links that are currently visible on the screen, get a sample of link indices with their midpoint coordinates and angle.
+     * The resulting number of links will depend on the `linkSamplingDistance` configuration property,
+     * and the sampled links will be evenly distributed (one link per grid cell, based on link midpoint in screen space).
+     * Each value is [x, y, angle]: position in data space; angle in radians for screen-space rotation (0 = right, positive = clockwise, e.g. for CSS rotation).
+     */
+    getSampledLinkPositionsMap(): Map<number, [number, number, number]>;
+    /**
+     * For the links that are currently visible on the screen, get a sample of link indices, midpoint positions, and angles.
+     * The resulting number of links will depend on the `linkSamplingDistance` configuration property,
+     * and the sampled links will be evenly distributed.
+     * Positions are in data space; angles are in radians for screen-space rotation (0 = right, positive = clockwise, e.g. for CSS rotation).
+     */
+    getSampledLinks(): {
+        indices: number[];
+        positions: number[];
+        angles: number[];
+    };
     /**
      * Gets the X-axis of rescaling function.
      *
@@ -518,12 +547,6 @@ export declare class Graph {
      * 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;
     /**
      * Run one step of the simulation manually.
      * Works even when the simulation is paused.
@@ -534,7 +557,9 @@ export declare class Graph {
      */
     destroy(): void;
     /**
-     * Updates and recreates the graph visualization based on pending changes.
+     * Applies pending data changes (positions, colors, sizes, shapes, links, forces, clusters)
+     * to the graph visualization. Call this after setting data via methods like `setPointPositions`,
+     * `setPointColors`, `setLinks`, etc. if you need to apply changes without calling `render()`.
      */
     create(): void;
     /**
@@ -549,6 +574,16 @@ export declare class Graph {
      * @returns An array of tuple positions
      */
     pair(pointPositions: number[]): [number, number][];
+    /**
+     * Restores init-only fields (`enableSimulation`, `initialZoomLevel`, `randomSeed`, `attribution`)
+     * to their pre-update values, preventing runtime changes via setConfig/setConfigPartial.
+     */
+    private preserveInitOnlyFields;
+    /**
+     * Compares the previous config snapshot with the current `this.config` and
+     * applies any necessary side effects (updating renderers, store, behaviors, etc.).
+     */
+    private updateStateFromConfig;
     /**
      * Ensures device is initialized before executing a method.
      * If device is not ready, queues the method to run after initialization.
@@ -619,6 +654,7 @@ export declare class Graph {
     private updateCanvasCursor;
     private addAttribution;
 }
-export type { GraphConfigInterface } from './config';
+export type { GraphConfig } from './config';
 export { PointShape } from './modules/GraphData';
+export * from './variables';
 export * from './helper';