force-graph 1.49.5 → 1.50.0

package/dist/force-graph.mjs

@@ -418,6 +418,11 @@ var CanvasForceGraph = Kapsule({
       triggerUpdate: false
     },
     // in link length ratio per frame
+    linkDirectionalParticleOffset: {
+      "default": 0,
+      triggerUpdate: false
+    },
+    // starting position offset along the link's length, like a pre-delay. Values between [0, 1]
     linkDirectionalParticleWidth: {
       "default": 4,
       triggerUpdate: false
@@ -425,6 +430,9 @@ var CanvasForceGraph = Kapsule({
     linkDirectionalParticleColor: {
       triggerUpdate: false
     },
+    linkDirectionalParticleCanvasObject: {
+      triggerUpdate: false
+    },
     globalScale: {
       "default": 1,
       triggerUpdate: false
@@ -746,6 +754,7 @@ var CanvasForceGraph = Kapsule({
       function paintPhotons() {
         var getNumPhotons = accessorFn(state.linkDirectionalParticles);
         var getSpeed = accessorFn(state.linkDirectionalParticleSpeed);
+        var getOffset = accessorFn(state.linkDirectionalParticleOffset);
         var getDiameter = accessorFn(state.linkDirectionalParticleWidth);
         var getVisibility = accessorFn(state.linkVisibility);
         var getColor = accessorFn(state.linkDirectionalParticleColor || state.linkColor);
@@ -759,6 +768,7 @@ var CanvasForceGraph = Kapsule({
           if (!start || !end || !start.hasOwnProperty('x') || !end.hasOwnProperty('x')) return; // skip invalid link
 
           var particleSpeed = getSpeed(link);
+          var particleOffset = Math.abs(getOffset(link));
           var photons = link.__photons || [];
           var photonR = Math.max(0, getDiameter(link) / 2) / Math.sqrt(state.globalScale);
           var photonColor = getColor(link) || 'rgba(0,0,0,0.28)';
@@ -771,7 +781,7 @@ var CanvasForceGraph = Kapsule({
           photons.forEach(function (photon) {
             var singleHop = !!photon.__singleHop;
             if (!photon.hasOwnProperty('__progressRatio')) {
-              photon.__progressRatio = singleHop ? 0 : cyclePhotonIdx / numCyclePhotons;
+              photon.__progressRatio = singleHop ? 0 : (cyclePhotonIdx + particleOffset) / numCyclePhotons;
             }
             !singleHop && cyclePhotonIdx++; // increase regular photon index
 
@@ -791,9 +801,13 @@ var CanvasForceGraph = Kapsule({
               x: start.x + (end.x - start.x) * photonPosRatio || 0,
               y: start.y + (end.y - start.y) * photonPosRatio || 0
             };
-            ctx.beginPath();
-            ctx.arc(coords.x, coords.y, photonR, 0, 2 * Math.PI, false);
-            ctx.fill();
+            if (state.linkDirectionalParticleCanvasObject) {
+              state.linkDirectionalParticleCanvasObject(coords.x, coords.y, link, ctx, state.globalScale);
+            } else {
+              ctx.beginPath();
+              ctx.arc(coords.x, coords.y, photonR, 0, 2 * Math.PI, false);
+              ctx.fill();
+            }
           });
           if (needsCleanup) {
             // remove expired single hop photons
@@ -945,7 +959,7 @@ var DRAG_CLICK_TOLERANCE_PX = 5; // How many px can a node be accidentally dragg
 // Expose config from forceGraph
 var bindFG = linkKapsule('forceGraph', CanvasForceGraph);
 var bindBoth = linkKapsule(['forceGraph', 'shadowGraph'], CanvasForceGraph);
-var linkedProps = Object.assign.apply(Object, _toConsumableArray(['nodeColor', 'nodeAutoColorBy', 'nodeCanvasObject', 'nodeCanvasObjectMode', 'linkColor', 'linkAutoColorBy', 'linkLineDash', 'linkWidth', 'linkCanvasObject', 'linkCanvasObjectMode', 'linkDirectionalArrowLength', 'linkDirectionalArrowColor', 'linkDirectionalArrowRelPos', 'linkDirectionalParticles', 'linkDirectionalParticleSpeed', 'linkDirectionalParticleWidth', 'linkDirectionalParticleColor', 'dagMode', 'dagLevelDistance', 'dagNodeFilter', 'onDagError', 'd3AlphaMin', 'd3AlphaDecay', 'd3VelocityDecay', 'warmupTicks', 'cooldownTicks', 'cooldownTime', 'onEngineTick', 'onEngineStop'].map(function (p) {
+var linkedProps = Object.assign.apply(Object, _toConsumableArray(['nodeColor', 'nodeAutoColorBy', 'nodeCanvasObject', 'nodeCanvasObjectMode', 'linkColor', 'linkAutoColorBy', 'linkLineDash', 'linkWidth', 'linkCanvasObject', 'linkCanvasObjectMode', 'linkDirectionalArrowLength', 'linkDirectionalArrowColor', 'linkDirectionalArrowRelPos', 'linkDirectionalParticles', 'linkDirectionalParticleSpeed', 'linkDirectionalParticleOffset', 'linkDirectionalParticleWidth', 'linkDirectionalParticleColor', 'linkDirectionalParticleCanvasObject', 'dagMode', 'dagLevelDistance', 'dagNodeFilter', 'onDagError', 'd3AlphaMin', 'd3AlphaDecay', 'd3VelocityDecay', 'warmupTicks', 'cooldownTicks', 'cooldownTime', 'onEngineTick', 'onEngineStop'].map(function (p) {
   return _defineProperty({}, p, bindFG.linkProp(p));
 })).concat(_toConsumableArray(['nodeRelSize', 'nodeId', 'nodeVal', 'nodeVisibility', 'linkSource', 'linkTarget', 'linkVisibility', 'linkCurvature'].map(function (p) {
   return _defineProperty({}, p, bindBoth.linkProp(p));
@@ -1539,6 +1553,9 @@ var forceGraph = Kapsule({
 
     // Handle click/touch events on nodes/links
     container.addEventListener('pointerup', function (ev) {
+      if (!state.isPointerPressed) {
+        return; // don't trigger click events if pointer is not pressed on the canvas
+      }
       state.isPointerPressed = false;
       if (state.isPointerDragging) {
         state.isPointerDragging = false;

package/example/dag-yarn/index.html

@@ -65,7 +65,7 @@
       .d3AlphaDecay(0.02)
       .d3VelocityDecay(0.3);
 
-    fetch('//unpkg.com/d3@5.9.7/yarn.lock')
+    fetch('//cdn.jsdelivr.net/npm/d3@5.9.7/yarn.lock')
       .then(r => r.text())
       .then(text => {
         const yarnlock = _yarnpkg_lockfile.parse(text);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "force-graph",
-  "version": "1.49.5",
+  "version": "1.50.0",
   "description": "2D force-directed graph rendered on HTML5 canvas",
   "type": "module",
   "unpkg": "dist/force-graph.min.js",
@@ -59,24 +59,24 @@
     "d3-scale-chromatic": "1 - 3",
     "d3-selection": "2 - 3",
     "d3-zoom": "2 - 3",
-    "float-tooltip": "^1.6",
+    "float-tooltip": "^1.7",
     "index-array-by": "1",
     "kapsule": "^1.16",
     "lodash-es": "4"
   },
   "devDependencies": {
-    "@babel/core": "^7.26.9",
-    "@babel/preset-env": "^7.26.9",
+    "@babel/core": "^7.28.0",
+    "@babel/preset-env": "^7.28.0",
     "@rollup/plugin-babel": "^6.0.4",
-    "@rollup/plugin-commonjs": "^28.0.3",
-    "@rollup/plugin-node-resolve": "^16.0.0",
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-terser": "^0.4.4",
-    "postcss": "^8.5.3",
+    "postcss": "^8.5.6",
     "rimraf": "^6.0.1",
-    "rollup": "^4.34.9",
-    "rollup-plugin-dts": "^6.1.1",
+    "rollup": "^4.44.1",
+    "rollup-plugin-dts": "^6.2.1",
     "rollup-plugin-postcss": "^4.0.2",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.3"
   },
   "engines": {
     "node": ">=12"

package/src/canvas-force-graph.js

@@ -78,8 +78,10 @@ export default Kapsule({
     linkDirectionalArrowRelPos: { default: 0.5, triggerUpdate: false, onChange: notifyRedraw }, // value between 0<>1 indicating the relative pos along the (exposed) line
     linkDirectionalParticles: { default: 0, triggerUpdate: false, onChange: updDataPhotons }, // animate photons travelling in the link direction
     linkDirectionalParticleSpeed: { default: 0.01, triggerUpdate: false }, // in link length ratio per frame
+    linkDirectionalParticleOffset: { default: 0, triggerUpdate: false }, // starting position offset along the link's length, like a pre-delay. Values between [0, 1]
     linkDirectionalParticleWidth: { default: 4, triggerUpdate: false },
     linkDirectionalParticleColor: { triggerUpdate: false },
+    linkDirectionalParticleCanvasObject: { triggerUpdate: false },
     globalScale: { default: 1, triggerUpdate: false },
     d3AlphaMin: { default: 0, triggerUpdate: false},
     d3AlphaDecay: { default: 0.0228, triggerUpdate: false, onChange(alphaDecay, state) { state.forceLayout.alphaDecay(alphaDecay) }},
@@ -365,6 +367,7 @@ export default Kapsule({
       function paintPhotons() {
         const getNumPhotons = accessorFn(state.linkDirectionalParticles);
         const getSpeed = accessorFn(state.linkDirectionalParticleSpeed);
+        const getOffset = accessorFn(state.linkDirectionalParticleOffset);
         const getDiameter = accessorFn(state.linkDirectionalParticleWidth);
         const getVisibility = accessorFn(state.linkVisibility);
         const getColor = accessorFn(state.linkDirectionalParticleColor || state.linkColor);
@@ -382,6 +385,7 @@ export default Kapsule({
           if (!start || !end || !start.hasOwnProperty('x') || !end.hasOwnProperty('x')) return; // skip invalid link
 
           const particleSpeed = getSpeed(link);
+          const particleOffset = Math.abs(getOffset(link));
           const photons = link.__photons || [];
           const photonR = Math.max(0, getDiameter(link) / 2) / Math.sqrt(state.globalScale);
           const photonColor = getColor(link) || 'rgba(0,0,0,0.28)';
@@ -399,7 +403,7 @@ export default Kapsule({
             const singleHop = !!photon.__singleHop;
 
             if (!photon.hasOwnProperty('__progressRatio')) {
-              photon.__progressRatio = singleHop ? 0 : cyclePhotonIdx / numCyclePhotons;
+              photon.__progressRatio = singleHop ? 0 : (cyclePhotonIdx + particleOffset) / numCyclePhotons;
             }
 
             !singleHop && cyclePhotonIdx++; // increase regular photon index
@@ -424,9 +428,13 @@ export default Kapsule({
                 y: start.y + (end.y - start.y) * photonPosRatio || 0
               };
 
-            ctx.beginPath();
-            ctx.arc(coords.x, coords.y, photonR, 0, 2 * Math.PI, false);
-            ctx.fill();
+            if(state.linkDirectionalParticleCanvasObject) {
+              state.linkDirectionalParticleCanvasObject(coords.x, coords.y, link, ctx, state.globalScale);
+            } else {
+              ctx.beginPath();
+              ctx.arc(coords.x, coords.y, photonR, 0, 2 * Math.PI, false);
+              ctx.fill();
+            }
           });
 
           if (needsCleanup) {

package/src/force-graph.js

@@ -36,8 +36,10 @@ const linkedProps = Object.assign(
     'linkDirectionalArrowRelPos',
     'linkDirectionalParticles',
     'linkDirectionalParticleSpeed',
+    'linkDirectionalParticleOffset',
     'linkDirectionalParticleWidth',
     'linkDirectionalParticleColor',
+    'linkDirectionalParticleCanvasObject',
     'dagMode',
     'dagLevelDistance',
     'dagNodeFilter',
@@ -547,6 +549,10 @@ export default Kapsule({
 
     // Handle click/touch events on nodes/links
     container.addEventListener('pointerup', ev => {
+      if (!state.isPointerPressed) {
+        return; // don't trigger click events if pointer is not pressed on the canvas
+      }
+
       state.isPointerPressed = false;
       if (state.isPointerDragging) {
         state.isPointerDragging = false;

package/src/index.d.ts

@@ -29,6 +29,7 @@ type CanvasCustomRenderMode = 'replace' | 'before' | 'after';
 export type CanvasCustomRenderModeFn<T> = (obj: T) => CanvasCustomRenderMode | any;
 export type CanvasCustomRenderFn<T> = (obj: T, canvasContext: CanvasRenderingContext2D, globalScale: number) => void;
 export type CanvasPointerAreaPaintFn<T> = (obj: T, paintColor: string, canvasContext: CanvasRenderingContext2D, globalScale: number) => void;
+export type CanvasLinkParticleRenderFn<L> = (x: number, y: number, link: L, canvasContext: CanvasRenderingContext2D, globalScale: number) => void;
 
 type DagMode = 'td' | 'bu' | 'lr' | 'rl' | 'radialout' | 'radialin';
 
@@ -110,10 +111,14 @@ export declare class ForceGraphGeneric<ChainableInstance, N extends NodeObject =
   linkDirectionalParticles(numParticlesAccessor: LinkAccessor<number, N, L>): ChainableInstance;
   linkDirectionalParticleSpeed(): LinkAccessor<number, N, L>;
   linkDirectionalParticleSpeed(relDistancePerFrameAccessor: LinkAccessor<number, N, L>): ChainableInstance;
+  linkDirectionalParticleOffset(): LinkAccessor<number, N, L>;
+  linkDirectionalParticleOffset(relOffset: LinkAccessor<number, N, L>): ChainableInstance;
   linkDirectionalParticleWidth(): LinkAccessor<number, N, L>;
   linkDirectionalParticleWidth(widthAccessor: LinkAccessor<number, N, L>): ChainableInstance;
   linkDirectionalParticleColor(): LinkAccessor<string, N, L>;
   linkDirectionalParticleColor(colorAccessor: LinkAccessor<string, N, L>): ChainableInstance;
+  linkDirectionalParticleCanvasObject(): CanvasLinkParticleRenderFn<L>;
+  linkDirectionalParticleCanvasObject(renderFn: CanvasLinkParticleRenderFn<L>): ChainableInstance;
   emitParticle(link: L): ChainableInstance;
   linkPointerAreaPaint(): CanvasPointerAreaPaintFn<L>;
   linkPointerAreaPaint(renderFn: CanvasPointerAreaPaintFn<L>): ChainableInstance;