@dxos/react-ui-graph 0.8.4-main.d05539e30a → 0.8.4-main.d9fc60f731

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/dist/lib/browser/index.mjs +781 -43
  2. package/dist/lib/browser/index.mjs.map +4 -4
  3. package/dist/lib/browser/meta.json +1 -1
  4. package/dist/lib/node-esm/index.mjs +781 -43
  5. package/dist/lib/node-esm/index.mjs.map +4 -4
  6. package/dist/lib/node-esm/meta.json +1 -1
  7. package/dist/types/src/components/Graph/Graph.d.ts +15 -1
  8. package/dist/types/src/components/Graph/Graph.d.ts.map +1 -1
  9. package/dist/types/src/components/SVG/FPS.d.ts +20 -0
  10. package/dist/types/src/components/SVG/FPS.d.ts.map +1 -0
  11. package/dist/types/src/components/SVG/Root.d.ts.map +1 -1
  12. package/dist/types/src/components/SVG/SVG.d.ts +3 -1
  13. package/dist/types/src/components/SVG/SVG.d.ts.map +1 -1
  14. package/dist/types/src/graph/projector/graph-cluster-projector.d.ts +5 -0
  15. package/dist/types/src/graph/projector/graph-cluster-projector.d.ts.map +1 -1
  16. package/dist/types/src/graph/projector/graph-force-projector.d.ts.map +1 -1
  17. package/dist/types/src/graph/projector/graph-plexus-projector.d.ts +67 -0
  18. package/dist/types/src/graph/projector/graph-plexus-projector.d.ts.map +1 -0
  19. package/dist/types/src/graph/projector/graph-plexus-projector.test.d.ts +2 -0
  20. package/dist/types/src/graph/projector/graph-plexus-projector.test.d.ts.map +1 -0
  21. package/dist/types/src/graph/projector/graph-projector.d.ts +8 -0
  22. package/dist/types/src/graph/projector/graph-projector.d.ts.map +1 -1
  23. package/dist/types/src/graph/projector/graph-swarm-projector.d.ts +72 -0
  24. package/dist/types/src/graph/projector/graph-swarm-projector.d.ts.map +1 -0
  25. package/dist/types/src/graph/projector/index.d.ts +2 -0
  26. package/dist/types/src/graph/projector/index.d.ts.map +1 -1
  27. package/dist/types/src/graph/renderer/graph-renderer.d.ts +20 -0
  28. package/dist/types/src/graph/renderer/graph-renderer.d.ts.map +1 -1
  29. package/dist/types/src/graph/renderer/index.d.ts +1 -0
  30. package/dist/types/src/graph/renderer/index.d.ts.map +1 -1
  31. package/dist/types/src/graph/renderer/labels.d.ts +33 -0
  32. package/dist/types/src/graph/renderer/labels.d.ts.map +1 -0
  33. package/dist/types/src/stories/experimental.stories.d.ts +7 -0
  34. package/dist/types/src/stories/experimental.stories.d.ts.map +1 -0
  35. package/dist/types/tsconfig.tsbuildinfo +1 -1
  36. package/package.json +17 -17
  37. package/src/components/Graph/Graph.tsx +70 -2
  38. package/src/components/SVG/FPS.tsx +91 -0
  39. package/src/components/SVG/Root.tsx +2 -1
  40. package/src/components/SVG/SVG.tsx +4 -1
  41. package/src/graph/projector/graph-cluster-projector.ts +12 -0
  42. package/src/graph/projector/graph-force-projector.ts +1 -0
  43. package/src/graph/projector/graph-plexus-projector.test.ts +102 -0
  44. package/src/graph/projector/graph-plexus-projector.ts +309 -0
  45. package/src/graph/projector/graph-projector.ts +15 -1
  46. package/src/graph/projector/graph-swarm-projector.ts +373 -0
  47. package/src/graph/projector/index.ts +2 -0
  48. package/src/graph/renderer/graph-renderer.ts +116 -3
  49. package/src/graph/renderer/index.ts +1 -0
  50. package/src/graph/renderer/labels.ts +138 -0
  51. package/src/stories/experimental.stories.tsx +446 -0
  52. package/styles/graph.css +1 -1
@@ -0,0 +1,373 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { type Timer, timer } from 'd3';
6
+
7
+ import { type Graph } from '@dxos/graph';
8
+ import { log } from '@dxos/log';
9
+
10
+ import { type GraphLayoutNode } from '../types';
11
+ import { GraphProjector, type GraphProjectorOptions } from './graph-projector';
12
+
13
+ // Boids swarming simulation rendered through the react-ui-graph SVG renderer.
14
+ // Mirrors the canvas Swarm component's tick (alignment / cohesion / separation)
15
+ // but mutates `x/y` on `GraphLayoutNode` instances directly and emits 'positions'
16
+ // each frame so `GraphRenderer.applyPositions` can fast-path SVG transforms,
17
+ // exactly like `GraphForceProjector`.
18
+ //
19
+ // https://en.wikipedia.org/wiki/Boids
20
+
21
+ const SWARMMATE_RADIUS = 60;
22
+ const SEPARATION_DISTANCE = 30;
23
+
24
+ /** Per-frame state stored on a layout node by the projector. */
25
+ export type SwarmNode = GraphLayoutNode & {
26
+ vx?: number;
27
+ vy?: number;
28
+ ax?: number;
29
+ ay?: number;
30
+ /**
31
+ * Shallow ring buffer of recent absolute positions (oldest first). One position is
32
+ * pushed per tick BEFORE integration, so after a tick the most recent entry is the
33
+ * pre-tick position. Cleared whenever the boid wraps a viewBox edge so the trail
34
+ * doesn't streak across the canvas.
35
+ */
36
+ history?: Array<{ x: number; y: number }>;
37
+ };
38
+
39
+ export type GraphSwarmProjectorOptions = GraphProjectorOptions & {
40
+ /** Initial spread (px) of new boids around the origin. */
41
+ spawnRadius?: number;
42
+ /** Hard cap on per-tick velocity. */
43
+ maxVelocity?: number;
44
+ /** Per-force weights — match Swarm's normalisation (divided by 100 on apply). */
45
+ alignment?: number;
46
+ cohesion?: number;
47
+ separation?: number;
48
+ /** Pixel radius (in SVG model coords) of the invisible repel zone tracking the pointer. 0 disables. */
49
+ cursorRepel?: number;
50
+ /** Avoidance force weight (divided by 10 on apply, matching canvas Swarm). */
51
+ avoidance?: number;
52
+ /**
53
+ * Number of previous positions retained per boid (one per simulation tick). The visible
54
+ * tail spans roughly `trailLength * maxVelocity` pixels — at 60 fps a value of 30 is
55
+ * about a half-second streak. Dense per-tick sampling avoids the "snap" artifact a
56
+ * coarser sample interval introduces when only the head moves between samples.
57
+ */
58
+ trailLength?: number;
59
+ };
60
+
61
+ const DEFAULTS: Required<
62
+ Pick<
63
+ GraphSwarmProjectorOptions,
64
+ | 'spawnRadius'
65
+ | 'maxVelocity'
66
+ | 'alignment'
67
+ | 'cohesion'
68
+ | 'separation'
69
+ | 'cursorRepel'
70
+ | 'avoidance'
71
+ | 'trailLength'
72
+ >
73
+ > = {
74
+ spawnRadius: 200,
75
+ maxVelocity: 1.2,
76
+ alignment: 3,
77
+ cohesion: 3,
78
+ separation: 3,
79
+ cursorRepel: 120,
80
+ avoidance: 3,
81
+ trailLength: 30,
82
+ };
83
+
84
+ /**
85
+ * Boids projector. One simulation timer (d3 `timer`) drives the tick; nodes are
86
+ * the boids, with `vx/vy/ax/ay` carried alongside `x/y`. Edges are kept in the
87
+ * layout so the renderer still draws them between connected boids, but they do
88
+ * NOT exert a link force — boid motion is governed purely by alignment, cohesion
89
+ * and separation, with viewBox-wrap at the SVG bounds.
90
+ */
91
+ export class GraphSwarmProjector<NodeData = any> extends GraphProjector<NodeData, GraphSwarmProjectorOptions> {
92
+ #timer?: Timer;
93
+ /** Cursor in SVG model coordinates, or null when the pointer is outside the surface. */
94
+ #cursor: { x: number; y: number } | null = null;
95
+
96
+ override findNode(): GraphLayoutNode<NodeData> | undefined {
97
+ // Boids have no spatial index — drag isn't supported in this variant.
98
+ return undefined;
99
+ }
100
+
101
+ /**
102
+ * Tell the projector where the pointer is, in SVG model coordinates (the same space
103
+ * `node.x/y` live in — center origin, post-zoom). Pass `null` (or omit args) on
104
+ * pointer-leave to disable cursor avoidance.
105
+ */
106
+ setCursor(x?: number | null, y?: number | null): void {
107
+ if (x == null || y == null) {
108
+ this.#cursor = null;
109
+ } else {
110
+ this.#cursor = { x, y };
111
+ }
112
+ }
113
+
114
+ protected override onUpdate(graph?: Graph.Any): void {
115
+ log('onUpdate', { graph: { nodes: graph?.nodes.length, edges: graph?.edges.length } });
116
+ this.mergeData(graph);
117
+ this.initializeNodes();
118
+ // Bind enter/exit once before motion starts; subsequent ticks emit 'positions'.
119
+ this.emitUpdate('topology');
120
+ }
121
+
122
+ protected override async onStart(): Promise<void> {
123
+ this.startTimer();
124
+ }
125
+
126
+ protected override async onStop(): Promise<void> {
127
+ this.stopTimer();
128
+ }
129
+
130
+ protected override onRefresh(): void {
131
+ if (!this.#timer) {
132
+ this.startTimer();
133
+ }
134
+ }
135
+
136
+ #opt<K extends keyof typeof DEFAULTS>(key: K): number {
137
+ return (this.options[key] as number | undefined) ?? DEFAULTS[key];
138
+ }
139
+
140
+ private initializeNodes(): void {
141
+ const spawnRadius = this.#opt('spawnRadius');
142
+ const maxVelocity = this.#opt('maxVelocity');
143
+ for (const node of this.layout.graph.nodes as SwarmNode[]) {
144
+ if (!node.initialized) {
145
+ const theta = Math.random() * 2 * Math.PI;
146
+ const r = Math.random() * spawnRadius;
147
+ node.x = Math.cos(theta) * r;
148
+ node.y = Math.sin(theta) * r;
149
+ // Random initial velocity bounded by maxVelocity.
150
+ const phi = Math.random() * 2 * Math.PI;
151
+ const speed = (0.3 + Math.random() * 0.7) * maxVelocity;
152
+ node.vx = Math.cos(phi) * speed;
153
+ node.vy = Math.sin(phi) * speed;
154
+ node.ax = 0;
155
+ node.ay = 0;
156
+ node.initialized = true;
157
+ } else {
158
+ // Make sure velocity / acceleration exist on nodes inherited from a prior layout.
159
+ node.vx ??= 0;
160
+ node.vy ??= 0;
161
+ node.ax ??= 0;
162
+ node.ay ??= 0;
163
+ }
164
+ // Default render radius — matches the force projector default.
165
+ node.r ??= 6;
166
+ // Reset the trail history. On fresh entry (`prev` from force/lattice/...) the field
167
+ // is undefined; on re-entry from a prior swarm session the layout node is reused and
168
+ // still carries stale absolute positions which would draw the tail back to wherever
169
+ // the boid was last time. Seed with the current position so the tail grows from the
170
+ // boid's actual starting point.
171
+ node.history = [{ x: node.x ?? 0, y: node.y ?? 0 }];
172
+ }
173
+ }
174
+
175
+ private startTimer(): void {
176
+ this.stopTimer();
177
+ this.#timer = timer(() => this.tick());
178
+ }
179
+
180
+ private stopTimer(): void {
181
+ this.#timer?.stop();
182
+ this.#timer = undefined;
183
+ }
184
+
185
+ /**
186
+ * One simulation step. Modeled on `tick` in Swarm.tsx, but operating in the
187
+ * SVG centered-origin coordinate space and writing to `node.x/y` directly so
188
+ * the existing `GraphRenderer.applyPositions` reads them unchanged.
189
+ */
190
+ private tick(): void {
191
+ const size = this.context.size;
192
+ if (!size) {
193
+ return;
194
+ }
195
+ const { width, height } = size;
196
+ // SVG.Root with `centered: true` (the default) uses a viewBox where origin is
197
+ // the center and bounds are [-w/2, w/2] x [-h/2, h/2].
198
+ const halfW = width / 2;
199
+ const halfH = height / 2;
200
+
201
+ const nodes = this.layout.graph.nodes as SwarmNode[];
202
+ const maxVelocity = this.#opt('maxVelocity');
203
+ // Match Swarm's force normalisation so weight semantics line up across variants.
204
+ const alignmentW = this.#opt('alignment') / 100;
205
+ const cohesionW = this.#opt('cohesion') / 100;
206
+ const separationW = this.#opt('separation') / 100;
207
+ const avoidanceW = this.#opt('avoidance') / 10;
208
+ const cursorRepel = this.#opt('cursorRepel');
209
+ const cursor = cursorRepel > 0 ? this.#cursor : null;
210
+
211
+ // Two-pass per tick: (1) compute acceleration from neighbours, (2) integrate.
212
+ for (const b1 of nodes) {
213
+ let ax = 0;
214
+ let ay = 0;
215
+ let alignX = 0;
216
+ let alignY = 0;
217
+ let alignActive = false;
218
+ let cohX = 0;
219
+ let cohY = 0;
220
+ let cohActive = false;
221
+ let sepX = 0;
222
+ let sepY = 0;
223
+ let sepActive = false;
224
+ let avoidX = 0;
225
+ let avoidY = 0;
226
+ let avoidActive = false;
227
+
228
+ // Cursor repulsion: when the cursor is within the repel zone, push the boid
229
+ // directly away. Mirrors the canvas Swarm's `repel` (treats the cursor as a
230
+ // SwarmObstacle with radius = cursorRepel).
231
+ if (cursor) {
232
+ const dx = cursor.x - (b1.x ?? 0);
233
+ const dy = cursor.y - (b1.y ?? 0);
234
+ const distSq = dx * dx + dy * dy;
235
+ if (distSq > 0 && distSq < cursorRepel * cursorRepel) {
236
+ const dist = Math.sqrt(distSq);
237
+ // Inverse-distance push, matching the canvas variant's `diff.scaleTo(-1 / distance)`.
238
+ avoidX = (-dx / dist) * (1 / dist);
239
+ avoidY = (-dy / dist) * (1 / dist);
240
+ avoidActive = true;
241
+ }
242
+ }
243
+
244
+ // Mirror the canvas variant: while a boid is being avoided, ignore swarmmate
245
+ // forces so it commits fully to escaping the cursor.
246
+ if (!avoidActive) {
247
+ for (const b2 of nodes) {
248
+ if (b1 === b2) {
249
+ continue;
250
+ }
251
+
252
+ const dx = (b2.x ?? 0) - (b1.x ?? 0);
253
+ const dy = (b2.y ?? 0) - (b1.y ?? 0);
254
+ const distSq = dx * dx + dy * dy;
255
+ if (distSq === 0) {
256
+ continue;
257
+ }
258
+ const dist = Math.sqrt(distSq);
259
+
260
+ if (dist < SEPARATION_DISTANCE) {
261
+ // Push away — inverse-distance weighting matches the canvas variant.
262
+ sepX += (-dx / dist) * (1 / dist);
263
+ sepY += (-dy / dist) * (1 / dist);
264
+ sepActive = true;
265
+ }
266
+ if (dist < SWARMMATE_RADIUS) {
267
+ cohX += dx;
268
+ cohY += dy;
269
+ cohActive = true;
270
+ alignX += b2.vx ?? 0;
271
+ alignY += b2.vy ?? 0;
272
+ alignActive = true;
273
+ }
274
+ }
275
+ }
276
+
277
+ const applyForce = (fx: number, fy: number, weight: number, active: boolean): void => {
278
+ if (!active || weight === 0) {
279
+ return;
280
+ }
281
+ // Steer = target_velocity - current_velocity, then truncate to weight.
282
+ const len = Math.sqrt(fx * fx + fy * fy);
283
+ if (len === 0) {
284
+ return;
285
+ }
286
+ const sx = (fx * maxVelocity) / len - (b1.vx ?? 0);
287
+ const sy = (fy * maxVelocity) / len - (b1.vy ?? 0);
288
+ const slen = Math.sqrt(sx * sx + sy * sy);
289
+ if (slen > weight) {
290
+ ax += (sx * weight) / slen;
291
+ ay += (sy * weight) / slen;
292
+ } else {
293
+ ax += sx;
294
+ ay += sy;
295
+ }
296
+ };
297
+
298
+ applyForce(alignX, alignY, alignmentW, alignActive);
299
+ applyForce(cohX, cohY, cohesionW, cohActive);
300
+ applyForce(sepX, sepY, separationW, sepActive);
301
+ applyForce(avoidX, avoidY, avoidanceW, avoidActive);
302
+
303
+ b1.ax = ax;
304
+ b1.ay = ay;
305
+ }
306
+
307
+ // Integrate + viewBox-wrap + trail bookkeeping.
308
+ const trailLength = Math.max(0, Math.round(this.#opt('trailLength')));
309
+ for (const b of nodes) {
310
+ let vx = (b.vx ?? 0) + (b.ax ?? 0);
311
+ let vy = (b.vy ?? 0) + (b.ay ?? 0);
312
+ const vlen = Math.sqrt(vx * vx + vy * vy);
313
+ if (vlen > maxVelocity) {
314
+ vx = (vx * maxVelocity) / vlen;
315
+ vy = (vy * maxVelocity) / vlen;
316
+ }
317
+ b.vx = vx;
318
+ b.vy = vy;
319
+
320
+ // Push the pre-integration position into history every tick. Dense sampling means
321
+ // the path-end shifts by a sub-pixel amount per frame — the curve evolves
322
+ // continuously and the tail-end gradient stop tracks smoothly, avoiding the snap
323
+ // / flicker a sparser sample interval would introduce.
324
+ if (trailLength > 0) {
325
+ const history = b.history ?? (b.history = []);
326
+ history.push({ x: b.x ?? 0, y: b.y ?? 0 });
327
+ if (history.length > trailLength) {
328
+ history.splice(0, history.length - trailLength);
329
+ }
330
+ }
331
+
332
+ let x = (b.x ?? 0) + vx;
333
+ let y = (b.y ?? 0) + vy;
334
+ // Wrap at the centered viewBox edges so boids leaving one side reappear on the opposite.
335
+ // On wrap we clear the trail so the line doesn't streak across the canvas (matches
336
+ // the canvas Swarm's wrap-aware trail rendering, but simpler).
337
+ let wrapped = false;
338
+ if (x > halfW) {
339
+ x -= width;
340
+ wrapped = true;
341
+ } else if (x < -halfW) {
342
+ x += width;
343
+ wrapped = true;
344
+ }
345
+ if (y > halfH) {
346
+ y -= height;
347
+ wrapped = true;
348
+ } else if (y < -halfH) {
349
+ y += height;
350
+ wrapped = true;
351
+ }
352
+ if (wrapped && b.history) {
353
+ b.history.length = 0;
354
+ }
355
+ b.x = x;
356
+ b.y = y;
357
+ }
358
+
359
+ // Edge geometry: quadratic Bézier with control at the origin so every edge bends
360
+ // toward the center — visually echoing the bundle projector's centre-routed
361
+ // curves while staying cheap to compute. The renderer's `applyPositions` reads
362
+ // `edge.path` directly when present.
363
+ for (const edge of this.layout.graph.edges) {
364
+ const sx = edge.source.x ?? 0;
365
+ const sy = edge.source.y ?? 0;
366
+ const tx = edge.target.x ?? 0;
367
+ const ty = edge.target.y ?? 0;
368
+ edge.path = `M ${sx} ${sy} Q 0 0 ${tx} ${ty}`;
369
+ }
370
+
371
+ this.emitUpdate('positions');
372
+ }
373
+ }
@@ -9,6 +9,8 @@ export * from './graph-projector';
9
9
  export * from './graph-force-projector';
10
10
  export * from './graph-hierarchical-projector';
11
11
  export * from './graph-lattice-projector';
12
+ export * from './graph-plexus-projector';
12
13
  export * from './graph-relational-projector';
13
14
  export * from './graph-radial-projector';
15
+ export * from './graph-swarm-projector';
14
16
  export * from './projector';
@@ -60,7 +60,27 @@ export type GraphRendererOptions<NodeData = any, EdgeData = any> = RendererOptio
60
60
  * whatever this callback creates instead. Use for lattice rects, custom icons, etc.
61
61
  */
62
62
  renderNode?: RenderNode<NodeData>;
63
+ /**
64
+ * Per-tick per-node callback invoked from `applyPositions` AFTER the dx-node group's
65
+ * transform is updated. Use it to keep node-local SVG (trail paths, gradient axes,
66
+ * per-frame decorations) in sync with the node's current position. The group is the
67
+ * dx-node `<g>` (head at 0,0 in local coords); the node is the live layout node.
68
+ * Runs only on the positions fast-path; full `render` calls don't invoke it.
69
+ */
70
+ applyNode?: (group: SVGGElement, node: GraphLayoutNode<NodeData>) => void;
71
+ /**
72
+ * Opacity applied to the `dx-edges` group. Set < 1 to dim edges relative to nodes
73
+ * (e.g. swarm trails over routing edges). Default is the inherited group opacity.
74
+ */
75
+ edgeOpacity?: number;
63
76
  transition?: () => any;
77
+ /**
78
+ * On node pointerenter, color outgoing edges orange, incoming edges sky-blue, dim
79
+ * unrelated edges, and stroke connected nodes / dim unrelated ones. Cleared on
80
+ * pointerleave. Designed for the bundle variant; harmless for variants where the
81
+ * topology doesn't carry meaningful direction.
82
+ */
83
+ highlightOnHover?: boolean;
64
84
  onNodeClick?: (node: GraphLayoutNode<NodeData>, event: MouseEvent) => void;
65
85
  onNodePointerEnter?: (node: GraphLayoutNode<NodeData>, event: MouseEvent) => void;
66
86
  /** Fires on pointerleave from a node hit-target. Pair with `onNodePointerEnter` to clear hover state. */
@@ -181,7 +201,8 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
181
201
  .selectAll('g.dx-edges')
182
202
  .data([{ id: 'edges' }], (d: any) => d.id)
183
203
  .join('g')
184
- .classed('dx-edges', true);
204
+ .classed('dx-edges', true)
205
+ .style('opacity', this.options.edgeOpacity != null ? String(this.options.edgeOpacity) : null);
185
206
 
186
207
  const nodeGroup = root
187
208
  .selectAll('g.dx-nodes')
@@ -270,10 +291,20 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
270
291
  const root = select(this.root);
271
292
 
272
293
  // Transforms only — no attribute callback, no label measurement.
294
+ const applyNode = this.options.applyNode;
273
295
  root
274
296
  .select('g.dx-nodes')
275
297
  .selectAll<SVGGElement, GraphLayoutNode<NodeData>>('g.dx-node')
276
- .attr('transform', (d) => (d.x != null && d.y != null ? `translate(${d.x},${d.y})` : null));
298
+ .attr('transform', (d) => (d.x != null && d.y != null ? `translate(${d.x},${d.y})` : null))
299
+ .each(
300
+ applyNode
301
+ ? function (d) {
302
+ // Per-tick consumer hook (e.g. swarm trail). Group transform is already up to date,
303
+ // so node-local coords land in the same frame as the head position.
304
+ applyNode(this, d);
305
+ }
306
+ : () => {},
307
+ );
277
308
 
278
309
  // Edge geometry — either precomputed (`edge.path`) or derived from endpoint positions.
279
310
  root
@@ -362,14 +393,20 @@ const createNode: D3Callable = <Data>(group: D3Selection, options: GraphRenderer
362
393
  }
363
394
 
364
395
  // Hover.
365
- if (options.onNodePointerEnter || options.onNodePointerLeave) {
396
+ if (options.onNodePointerEnter || options.onNodePointerLeave || options.highlightOnHover) {
366
397
  hitTarget.on('pointerenter', function (event: PointerEvent) {
367
398
  const node = select<any, GraphLayoutNode<Data>>(useCustom ? this : this.parentElement).datum();
368
399
  options.onNodePointerEnter?.(node, event);
400
+ if (options.highlightOnHover) {
401
+ applyHoverHighlight((this as Element).closest('g.dx-graph') as SVGGElement | null, node.id);
402
+ }
369
403
  });
370
404
  hitTarget.on('pointerleave', function (event: PointerEvent) {
371
405
  const node = select<any, GraphLayoutNode<Data>>(useCustom ? this : this.parentElement).datum();
372
406
  options.onNodePointerLeave?.(node, event);
407
+ if (options.highlightOnHover) {
408
+ applyHoverHighlight((this as Element).closest('g.dx-graph') as SVGGElement | null, null);
409
+ }
373
410
  });
374
411
 
375
412
  group.attr('data-hover', 'handled');
@@ -578,6 +615,82 @@ const updateEdge: D3Callable = <NodeData = any, EdgeData = any>(
578
615
  });
579
616
  };
580
617
 
618
+ /**
619
+ * Hover-driven directional highlight: when `focusedId` is set, paint outgoing edges
620
+ * orange, incoming edges sky-blue, dim unrelated edges, stroke connected nodes, and
621
+ * dim unrelated nodes. When `focusedId` is null, clear every inline override so the
622
+ * graph returns to its default styling.
623
+ */
624
+ const applyHoverHighlight = (root: SVGGElement | null, focusedId: string | null) => {
625
+ if (!root) {
626
+ return;
627
+ }
628
+ const r = select(root);
629
+ const on = focusedId != null;
630
+
631
+ const outgoing = new Set<string>();
632
+ const incoming = new Set<string>();
633
+ if (on) {
634
+ r.select('g.dx-edges')
635
+ .selectAll<SVGGElement, GraphLayoutEdge>('g.dx-edge')
636
+ .each((edge) => {
637
+ if (edge.source.id === focusedId) {
638
+ outgoing.add(edge.target.id);
639
+ }
640
+ if (edge.target.id === focusedId) {
641
+ incoming.add(edge.source.id);
642
+ }
643
+ });
644
+ }
645
+
646
+ r.select('g.dx-edges')
647
+ .selectAll<SVGGElement, GraphLayoutEdge>('g.dx-edge')
648
+ .each(function (edge) {
649
+ // Visible edge path — exclude the wider transparent click target when present.
650
+ const path = select(this).select<SVGPathElement>('path:not(.dx-click)');
651
+ if (!on) {
652
+ path.style('stroke', null).style('stroke-width', null).style('opacity', null);
653
+ return;
654
+ }
655
+ if (edge.source.id === focusedId) {
656
+ path.style('stroke', 'var(--color-orange-500)').style('stroke-width', '1.5px').style('opacity', null);
657
+ } else if (edge.target.id === focusedId) {
658
+ path.style('stroke', 'var(--color-sky-500)').style('stroke-width', '1.5px').style('opacity', null);
659
+ } else {
660
+ path.style('stroke', null).style('stroke-width', null).style('opacity', '0.8');
661
+ }
662
+ });
663
+
664
+ r.select('g.dx-nodes')
665
+ .selectAll<SVGGElement, GraphLayoutNode>('g.dx-node')
666
+ .each(function (node) {
667
+ const groupSel = select(this);
668
+ const shape = groupSel.select<SVGGraphicsElement>('circle, rect');
669
+ // Hidden nodes (e.g. cluster-collapsed leaves) are kept invisible via the
670
+ // group's `opacity` attribute — set by `updateNode`. style.opacity would
671
+ // override that attribute, so leave hidden nodes alone.
672
+ if (node.hidden) {
673
+ return;
674
+ }
675
+ if (!on) {
676
+ groupSel.style('opacity', null);
677
+ shape.style('stroke', null).style('stroke-width', null);
678
+ return;
679
+ }
680
+ const connected = outgoing.has(node.id) || incoming.has(node.id);
681
+ if (node.id === focusedId) {
682
+ groupSel.style('opacity', null);
683
+ shape.style('stroke', null).style('stroke-width', null);
684
+ } else if (connected) {
685
+ groupSel.style('opacity', null);
686
+ shape.style('stroke', 'var(--color-orange-400)').style('stroke-width', '2.5px');
687
+ } else {
688
+ groupSel.style('opacity', '0.4');
689
+ shape.style('stroke', null).style('stroke-width', null);
690
+ }
691
+ });
692
+ };
693
+
581
694
  // TODO(burdon): Factor out.
582
695
 
583
696
  const applyClasses = (el: D3Selection, classes: Record<string, boolean>) => {
@@ -3,5 +3,6 @@
3
3
  //
4
4
 
5
5
  export * from './graph-renderer';
6
+ export * from './labels';
6
7
  export * from './linker';
7
8
  export * from './renderer';
@@ -0,0 +1,138 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { type D3Selection } from '../../util';
6
+ import { type GraphLayoutNode } from '../types';
7
+
8
+ export type LabelOptionsBase = {
9
+ /**
10
+ * Delay before fading the label in (ms). Default 0. Pair with the projector's tween
11
+ * duration so labels appear after the layout settles.
12
+ */
13
+ delay?: number;
14
+ /** Fade-in duration (ms). Default 200. */
15
+ duration?: number;
16
+ /** Radial offset from the node center (px). Default 4. */
17
+ offset?: number;
18
+ /** Additional CSS class(es) to set on the text element. */
19
+ className?: string;
20
+ };
21
+
22
+ const DEFAULT_DURATION = 200;
23
+ const DEFAULT_OFFSET = 4;
24
+
25
+ /** Read the target (post-tween) position from a node. Falls back to current x/y on entry. */
26
+ const getTarget = (node: GraphLayoutNode): { x: number; y: number } => {
27
+ const tx = (node as any).tx;
28
+ const ty = (node as any).ty;
29
+ return { x: tx ?? node.x ?? 0, y: ty ?? node.y ?? 0 };
30
+ };
31
+
32
+ /**
33
+ * Append a radial leaf label outside the node ring, oriented outward toward the TARGET
34
+ * position so the label rotates with the layout tween rather than the pre-tween position.
35
+ * Used by cluster + bundle variants for typename-grouped leaves.
36
+ */
37
+ export const appendRadialLeafLabel = (
38
+ group: D3Selection<SVGGElement>,
39
+ node: GraphLayoutNode,
40
+ label: string,
41
+ r: number,
42
+ options: LabelOptionsBase = {},
43
+ ): void => {
44
+ if (!label) {
45
+ return;
46
+ }
47
+ const { delay = 0, duration = DEFAULT_DURATION, offset = DEFAULT_OFFSET, className = 'dx-cluster-label' } = options;
48
+ const { x: targetX, y: targetY } = getTarget(node);
49
+ const angleDeg = (Math.atan2(targetY, targetX) * 180) / Math.PI;
50
+ const flipped = angleDeg > 90 || angleDeg < -90;
51
+ group
52
+ .append('text')
53
+ .attr('class', className)
54
+ .attr('dy', '0.32em')
55
+ .attr('transform', `rotate(${flipped ? angleDeg + 180 : angleDeg})`)
56
+ .attr('x', flipped ? -(r + offset) : r + offset)
57
+ .attr('text-anchor', flipped ? 'end' : 'start')
58
+ .attr('opacity', 0)
59
+ .style('cursor', 'pointer')
60
+ .text(label)
61
+ .transition()
62
+ .delay(delay)
63
+ .duration(duration)
64
+ .attr('opacity', 1);
65
+ };
66
+
67
+ /**
68
+ * Append a radial group label inside the node ring (anchored toward center), oriented along
69
+ * the TARGET radial direction. Mirrors `appendRadialLeafLabel` but anchored on the opposite
70
+ * side so leaf and group labels don't collide.
71
+ */
72
+ export const appendRadialGroupLabel = (
73
+ group: D3Selection<SVGGElement>,
74
+ node: GraphLayoutNode,
75
+ label: string,
76
+ r: number,
77
+ options: LabelOptionsBase = {},
78
+ ): void => {
79
+ if (!label) {
80
+ return;
81
+ }
82
+ const {
83
+ delay = 0,
84
+ duration = DEFAULT_DURATION,
85
+ offset = DEFAULT_OFFSET,
86
+ className = 'dx-cluster-label dx-cluster-label-group',
87
+ } = options;
88
+ const { x: targetX, y: targetY } = getTarget(node);
89
+ const angleDeg = (Math.atan2(targetY, targetX) * 180) / Math.PI;
90
+ const flipped = angleDeg > 90 || angleDeg < -90;
91
+ group
92
+ .append('text')
93
+ .attr('class', className)
94
+ .attr('dy', '0.32em')
95
+ .attr('transform', `rotate(${flipped ? angleDeg + 180 : angleDeg})`)
96
+ .attr('x', flipped ? r + offset : -(r + offset))
97
+ .attr('text-anchor', flipped ? 'start' : 'end')
98
+ .attr('opacity', 0)
99
+ .style('pointer-events', 'none')
100
+ .text(label)
101
+ .transition()
102
+ .delay(delay)
103
+ .duration(duration)
104
+ .attr('opacity', 1);
105
+ };
106
+
107
+ /**
108
+ * Append a centered root label above the node. Used by the cluster variant for the synthetic
109
+ * root circle so the database / collection name reads from above the ring.
110
+ */
111
+ export const appendRootLabel = (
112
+ group: D3Selection<SVGGElement>,
113
+ label: string,
114
+ r: number,
115
+ options: LabelOptionsBase = {},
116
+ ): void => {
117
+ if (!label) {
118
+ return;
119
+ }
120
+ const {
121
+ delay = 0,
122
+ duration = DEFAULT_DURATION,
123
+ offset = 6,
124
+ className = 'dx-cluster-label dx-cluster-label-root',
125
+ } = options;
126
+ group
127
+ .append('text')
128
+ .attr('class', className)
129
+ .attr('text-anchor', 'middle')
130
+ .attr('y', -(r + offset))
131
+ .attr('opacity', 0)
132
+ .style('pointer-events', 'none')
133
+ .text(label)
134
+ .transition()
135
+ .delay(delay)
136
+ .duration(duration)
137
+ .attr('opacity', 1);
138
+ };