@dxos/react-ui-graph 0.8.4-main.422d1c7879 → 0.8.4-main.43cb759274

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 (116) hide show
  1. package/LICENSE +102 -5
  2. package/dist/lib/browser/{chunk-LKC455GK.mjs → chunk-EASNZZ7B.mjs} +1 -1
  3. package/dist/lib/browser/{chunk-LKC455GK.mjs.map → chunk-EASNZZ7B.mjs.map} +2 -2
  4. package/dist/lib/browser/index.mjs +1783 -496
  5. package/dist/lib/browser/index.mjs.map +4 -4
  6. package/dist/lib/browser/meta.json +1 -1
  7. package/dist/lib/browser/testing/index.mjs +1 -1
  8. package/dist/lib/browser/testing/index.mjs.map +2 -2
  9. package/dist/lib/node-esm/{chunk-JE4KZCUF.mjs → chunk-JSE2X4ML.mjs} +1 -1
  10. package/dist/lib/node-esm/{chunk-JE4KZCUF.mjs.map → chunk-JSE2X4ML.mjs.map} +2 -2
  11. package/dist/lib/node-esm/index.mjs +1783 -496
  12. package/dist/lib/node-esm/index.mjs.map +4 -4
  13. package/dist/lib/node-esm/meta.json +1 -1
  14. package/dist/lib/node-esm/testing/index.mjs +1 -1
  15. package/dist/lib/node-esm/testing/index.mjs.map +2 -2
  16. package/dist/types/src/components/Graph/Graph.d.ts +20 -2
  17. package/dist/types/src/components/Graph/Graph.d.ts.map +1 -1
  18. package/dist/types/src/components/Graph/Graph.stories.d.ts +3 -3
  19. package/dist/types/src/components/Graph/Graph.stories.d.ts.map +1 -1
  20. package/dist/types/src/components/Mesh/Mesh.d.ts.map +1 -1
  21. package/dist/types/src/components/Mesh/Mesh.stories.d.ts.map +1 -1
  22. package/dist/types/src/components/SVG/FPS.d.ts +20 -0
  23. package/dist/types/src/components/SVG/FPS.d.ts.map +1 -0
  24. package/dist/types/src/components/SVG/Grid.d.ts.map +1 -1
  25. package/dist/types/src/components/SVG/Markers.d.ts.map +1 -1
  26. package/dist/types/src/components/SVG/Root.d.ts +5 -1
  27. package/dist/types/src/components/SVG/Root.d.ts.map +1 -1
  28. package/dist/types/src/components/SVG/SVG.d.ts +3 -1
  29. package/dist/types/src/components/SVG/SVG.d.ts.map +1 -1
  30. package/dist/types/src/components/SVG/Svg.stories.d.ts.map +1 -1
  31. package/dist/types/src/fx/fx.stories.d.ts.map +1 -1
  32. package/dist/types/src/fx/pulsar.d.ts.map +1 -1
  33. package/dist/types/src/graph/markers.d.ts.map +1 -1
  34. package/dist/types/src/graph/projector/graph-bundle-projector.d.ts +47 -0
  35. package/dist/types/src/graph/projector/graph-bundle-projector.d.ts.map +1 -0
  36. package/dist/types/src/graph/projector/graph-cluster-projector.d.ts +65 -0
  37. package/dist/types/src/graph/projector/graph-cluster-projector.d.ts.map +1 -0
  38. package/dist/types/src/graph/projector/graph-drag.d.ts.map +1 -1
  39. package/dist/types/src/graph/projector/graph-force-projector.d.ts.map +1 -1
  40. package/dist/types/src/graph/projector/graph-forces.d.ts.map +1 -1
  41. package/dist/types/src/graph/projector/graph-hierarchical-projector.d.ts.map +1 -1
  42. package/dist/types/src/graph/projector/graph-lattice-projector.d.ts +23 -0
  43. package/dist/types/src/graph/projector/graph-lattice-projector.d.ts.map +1 -0
  44. package/dist/types/src/graph/projector/graph-plexus-projector.d.ts +67 -0
  45. package/dist/types/src/graph/projector/graph-plexus-projector.d.ts.map +1 -0
  46. package/dist/types/src/graph/projector/graph-plexus-projector.test.d.ts +2 -0
  47. package/dist/types/src/graph/projector/graph-plexus-projector.test.d.ts.map +1 -0
  48. package/dist/types/src/graph/projector/graph-projector.d.ts +8 -0
  49. package/dist/types/src/graph/projector/graph-projector.d.ts.map +1 -1
  50. package/dist/types/src/graph/projector/graph-radial-projector.d.ts +6 -0
  51. package/dist/types/src/graph/projector/graph-radial-projector.d.ts.map +1 -1
  52. package/dist/types/src/graph/projector/graph-relational-projector.d.ts.map +1 -1
  53. package/dist/types/src/graph/projector/graph-swarm-projector.d.ts +72 -0
  54. package/dist/types/src/graph/projector/graph-swarm-projector.d.ts.map +1 -0
  55. package/dist/types/src/graph/projector/index.d.ts +5 -0
  56. package/dist/types/src/graph/projector/index.d.ts.map +1 -1
  57. package/dist/types/src/graph/projector/projector.d.ts +10 -1
  58. package/dist/types/src/graph/projector/projector.d.ts.map +1 -1
  59. package/dist/types/src/graph/renderer/bullets.d.ts.map +1 -1
  60. package/dist/types/src/graph/renderer/graph-renderer.d.ts +41 -1
  61. package/dist/types/src/graph/renderer/graph-renderer.d.ts.map +1 -1
  62. package/dist/types/src/graph/renderer/index.d.ts +1 -0
  63. package/dist/types/src/graph/renderer/index.d.ts.map +1 -1
  64. package/dist/types/src/graph/renderer/labels.d.ts +33 -0
  65. package/dist/types/src/graph/renderer/labels.d.ts.map +1 -0
  66. package/dist/types/src/graph/renderer/renderer.d.ts +12 -1
  67. package/dist/types/src/graph/renderer/renderer.d.ts.map +1 -1
  68. package/dist/types/src/graph/types.d.ts +14 -0
  69. package/dist/types/src/graph/types.d.ts.map +1 -1
  70. package/dist/types/src/hooks/useGrid.d.ts.map +1 -1
  71. package/dist/types/src/hooks/useStateRef.d.ts.map +1 -1
  72. package/dist/types/src/hooks/useSvgContext.d.ts.map +1 -1
  73. package/dist/types/src/hooks/useZoom.d.ts.map +1 -1
  74. package/dist/types/src/stories/experimental.stories.d.ts +7 -0
  75. package/dist/types/src/stories/experimental.stories.d.ts.map +1 -0
  76. package/dist/types/src/stories/hooks.stories.d.ts.map +1 -1
  77. package/dist/types/src/testing/data.d.ts +1 -1
  78. package/dist/types/src/testing/data.d.ts.map +1 -1
  79. package/dist/types/src/testing/hooks.d.ts.map +1 -1
  80. package/dist/types/src/testing/model.d.ts.map +1 -1
  81. package/dist/types/src/util/events.d.ts.map +1 -1
  82. package/dist/types/src/util/fraction.d.ts.map +1 -1
  83. package/dist/types/src/util/points.d.ts.map +1 -1
  84. package/dist/types/src/util/scale.d.ts.map +1 -1
  85. package/dist/types/src/util/screen.d.ts.map +1 -1
  86. package/dist/types/src/util/vector.d.ts.map +1 -1
  87. package/dist/types/tsconfig.tsbuildinfo +1 -1
  88. package/package.json +19 -19
  89. package/src/components/Graph/Graph.stories.tsx +5 -5
  90. package/src/components/Graph/Graph.tsx +116 -21
  91. package/src/components/Mesh/Mesh.stories.tsx +6 -4
  92. package/src/components/Mesh/Mesh.tsx +43 -35
  93. package/src/components/SVG/FPS.tsx +91 -0
  94. package/src/components/SVG/Root.tsx +30 -4
  95. package/src/components/SVG/SVG.tsx +4 -1
  96. package/src/graph/projector/graph-bundle-projector.ts +210 -0
  97. package/src/graph/projector/graph-cluster-projector.ts +337 -0
  98. package/src/graph/projector/graph-force-projector.ts +6 -1
  99. package/src/graph/projector/graph-hierarchical-projector.ts +1 -0
  100. package/src/graph/projector/graph-lattice-projector.ts +86 -0
  101. package/src/graph/projector/graph-plexus-projector.test.ts +102 -0
  102. package/src/graph/projector/graph-plexus-projector.ts +309 -0
  103. package/src/graph/projector/graph-projector.ts +22 -1
  104. package/src/graph/projector/graph-radial-projector.ts +30 -2
  105. package/src/graph/projector/graph-relational-projector.ts +1 -0
  106. package/src/graph/projector/graph-swarm-projector.ts +373 -0
  107. package/src/graph/projector/index.ts +5 -0
  108. package/src/graph/projector/projector.ts +12 -3
  109. package/src/graph/renderer/graph-renderer.ts +289 -30
  110. package/src/graph/renderer/index.ts +1 -0
  111. package/src/graph/renderer/labels.ts +138 -0
  112. package/src/graph/renderer/renderer.ts +15 -4
  113. package/src/graph/types.ts +14 -0
  114. package/src/stories/experimental.stories.tsx +446 -0
  115. package/src/stories/hooks.stories.tsx +6 -1
  116. package/styles/graph.css +51 -2
@@ -12,8 +12,23 @@ import { type GraphLayout, type GraphLayoutEdge, type GraphLayoutNode } from '..
12
12
  import { createBullets } from './bullets';
13
13
  import { Renderer, type RendererOptions } from './renderer';
14
14
 
15
+ /**
16
+ * Replace the default `<circle>` with a custom node shape. Invoked once per
17
+ * entering node — append your own elements to the supplied `<g>`. Position and
18
+ * `attributes.node` callbacks are still applied by the renderer.
19
+ */
20
+ export type RenderNode<NodeData = any> = (group: D3Selection<SVGGElement>, node: GraphLayoutNode<NodeData>) => void;
21
+
15
22
  const createLine = line<Point>();
16
23
 
24
+ /** Duration for edge opacity transitions on enter / exit (ms). Matches node enter/exit timing. */
25
+ const EDGE_FADE_MS = 300;
26
+
27
+ /** Duration for node hide/show opacity transitions (ms). Matches the projector's tween
28
+ * duration so a cluster collapse/expand fades opacity over the same window the position
29
+ * is tweening toward / away from the parent group. */
30
+ const NODE_HIDE_MS = 500;
31
+
17
32
  export type LabelOptions<NodeData = any> = {
18
33
  text: (node: GraphLayoutNode<NodeData>, highlight?: boolean) => string | undefined;
19
34
  };
@@ -40,17 +55,39 @@ export type GraphRendererOptions<NodeData = any, EdgeData = any> = RendererOptio
40
55
  labels?: LabelOptions<NodeData>;
41
56
  subgraphs?: boolean;
42
57
  attributes?: AttributesOptions<NodeData>;
58
+ /**
59
+ * Override the default `<circle>` node shape. When set, the renderer appends
60
+ * whatever this callback creates instead. Use for lattice rects, custom icons, etc.
61
+ */
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;
43
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;
44
84
  onNodeClick?: (node: GraphLayoutNode<NodeData>, event: MouseEvent) => void;
45
85
  onNodePointerEnter?: (node: GraphLayoutNode<NodeData>, event: MouseEvent) => void;
86
+ /** Fires on pointerleave from a node hit-target. Pair with `onNodePointerEnter` to clear hover state. */
87
+ onNodePointerLeave?: (node: GraphLayoutNode<NodeData>, event: MouseEvent) => void;
46
88
  onLinkClick?: (link: GraphLayoutEdge<NodeData, EdgeData>, event: MouseEvent) => void;
47
89
  }>;
48
90
 
49
- // TODO(burdon): Perf
50
- // - Leaking JS event listeners.
51
- // - Don't update unless data changes.
52
- // - Cache subgraph components in layout.
53
-
54
91
  /**
55
92
  * Renders the Graph layout.
56
93
  */
@@ -58,7 +95,26 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
58
95
  GraphLayout<NodeData, EdgeData>,
59
96
  GraphRendererOptions<NodeData, EdgeData>
60
97
  > {
98
+ // First render of this instance — used to clear DOM left behind by a previous
99
+ // renderer pointing at the same `<g>` (e.g. when the consumer swaps projectors
100
+ // and a new renderer is constructed for the same SVG root). Without this, the
101
+ // previous variant's node shapes (e.g. circles) would persist as d3.join sees
102
+ // them in the `update` set instead of `enter`.
103
+ #firstRender = true;
104
+
61
105
  override render(layout: GraphLayout<NodeData, EdgeData>) {
106
+ // The SVG group ref is unset between mount cycles and before the container has sized;
107
+ // skip the render rather than throw — the projector will emit again on the next tick.
108
+ if (!this.root) {
109
+ return;
110
+ }
111
+
112
+ if (this.#firstRender) {
113
+ this.#firstRender = false;
114
+ // Drop any DOM left by a prior renderer so this render's `renderNode` runs from scratch.
115
+ this.root.replaceChildren();
116
+ }
117
+
62
118
  log('render', layout);
63
119
 
64
120
  const root = select(this.root);
@@ -145,7 +201,8 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
145
201
  .selectAll('g.dx-edges')
146
202
  .data([{ id: 'edges' }], (d: any) => d.id)
147
203
  .join('g')
148
- .classed('dx-edges', true);
204
+ .classed('dx-edges', true)
205
+ .style('opacity', this.options.edgeOpacity != null ? String(this.options.edgeOpacity) : null);
149
206
 
150
207
  const nodeGroup = root
151
208
  .selectAll('g.dx-nodes')
@@ -165,10 +222,13 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
165
222
  enter
166
223
  .append('g')
167
224
  .attr('data-id', (d) => d.id)
168
- .attr('opacity', 1)
225
+ // Initial opacity matches `hidden` so a node that enters already-collapsed is
226
+ // invisible from the first frame; updateNode's named 'hide' transition then
227
+ // handles any subsequent toggles.
228
+ .attr('opacity', (d) => (d.hidden ? 0 : 1))
169
229
  .classed('dx-node', true)
170
230
  .call(createNode, this.options),
171
- (update) => update.call(updateNode, this.options),
231
+ (update) => update,
172
232
  (exit) => {
173
233
  // Fade out.
174
234
  return exit
@@ -181,6 +241,9 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
181
241
  });
182
242
  },
183
243
  )
244
+ // Apply update (transform / attributes / labels) to enter+update so the first render
245
+ // also populates `data-*` attributes and transforms — not just subsequent ticks.
246
+ .call(updateNode, this.options)
184
247
  .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
185
248
 
186
249
  //
@@ -197,17 +260,79 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
197
260
  .attr('data-id', (d) => d.id)
198
261
  .classed('dx-edge', true)
199
262
  .call(createEdge, this.options),
200
- (update) => update.call(updateEdge, this.options, nodeGroup).each((d) => {}),
201
- (exit) => exit.remove(),
263
+ (update) => update,
264
+ // Exit fade: edges removed by a topology change (e.g. variant switch from cluster
265
+ // back to force replaces hierarchy edges with data edges) ease out rather than pop.
266
+ (exit) =>
267
+ exit
268
+ .transition()
269
+ .ease(easeCubicOut)
270
+ .duration(EDGE_FADE_MS)
271
+ .attr('opacity', 0)
272
+ .on('end', function () {
273
+ select(this).remove();
274
+ }),
202
275
  )
276
+ // Apply edge updates (paths / attributes) to enter+update — see note on nodes above.
277
+ .call(updateEdge, this.options, nodeGroup)
203
278
  .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
204
279
  }
205
280
 
281
+ /**
282
+ * Fast positions-only update. Skips enter/exit, attribute callbacks, label sizing,
283
+ * and the subgraph hull pass; just writes `transform` per node and `d` per edge.
284
+ * Called per simulation tick / animation frame.
285
+ */
286
+ override applyPositions(layout: GraphLayout<NodeData, EdgeData>) {
287
+ if (!this.root) {
288
+ return;
289
+ }
290
+
291
+ const root = select(this.root);
292
+
293
+ // Transforms only — no attribute callback, no label measurement.
294
+ const applyNode = this.options.applyNode;
295
+ root
296
+ .select('g.dx-nodes')
297
+ .selectAll<SVGGElement, GraphLayoutNode<NodeData>>('g.dx-node')
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
+ );
308
+
309
+ // Edge geometry — either precomputed (`edge.path`) or derived from endpoint positions.
310
+ root
311
+ .select('g.dx-edges')
312
+ .selectAll<SVGGElement, GraphLayoutEdge<NodeData, EdgeData>>('g.dx-edge')
313
+ .selectAll<SVGPathElement, GraphLayoutEdge<NodeData, EdgeData>>('path')
314
+ .attr('d', function () {
315
+ // NOTE: `d` is stale after layout is switched so get the datum from the parent element.
316
+ const edge = select(this.parentElement).datum() as GraphLayoutEdge<NodeData, EdgeData>;
317
+ if (edge.path) {
318
+ return edge.path;
319
+ }
320
+ const { source, target } = edge;
321
+ if (!source.initialized || !target.initialized) {
322
+ return null;
323
+ }
324
+ return createLine(getCircumferencePoints([source.x, source.y], [target.x, target.y], source.r, target.r));
325
+ });
326
+ }
327
+
206
328
  /**
207
329
  * Trigger path bullets.
208
330
  * @param node
209
331
  */
210
332
  fireBullet(node: GraphLayoutNode<NodeData>) {
333
+ if (!this.root) {
334
+ return;
335
+ }
211
336
  select(this.root).selectAll('g.dx-edges').selectAll('path').call(createBullets(this.root, node.id));
212
337
  }
213
338
  }
@@ -217,21 +342,45 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
217
342
  * @param group
218
343
  * @param options
219
344
  */
345
+ const SHAPE_CLASS = 'dx-shape';
346
+
347
+ const renderCustomShape = <Data>(group: D3Selection, options: GraphRendererOptions<Data>) => {
348
+ group.each(function (d) {
349
+ const g = select<SVGGElement, GraphLayoutNode<Data>>(this);
350
+ // Clear any previous custom shape so subsequent renders pick up updated
351
+ // node.r / node.data without leaving stale elements behind.
352
+ g.selectAll(`.${SHAPE_CLASS}`).remove();
353
+ // Wrap the consumer's drawing in a `<g class="dx-shape">` so we have a
354
+ // stable selector for the cleanup above.
355
+ const shapeGroup = g.append('g').classed(SHAPE_CLASS, true);
356
+ options.renderNode!(shapeGroup, d);
357
+ });
358
+ };
359
+
220
360
  const createNode: D3Callable = <Data>(group: D3Selection, options: GraphRendererOptions<Data>) => {
221
- // Circle.
222
- const circle = group.append('circle');
361
+ // Custom node shape: consumer appends its own elements (e.g. <rect>) and the
362
+ // renderer skips the default <circle>. Drag/hover handlers attach to the
363
+ // wrapping <g> so the custom shape acts as the hit target.
364
+ const useCustom = !!options.renderNode;
365
+ if (useCustom) {
366
+ renderCustomShape(group, options);
367
+ }
368
+ const hitTarget = useCustom ? group : group.append('circle');
223
369
 
224
370
  // Drag.
225
371
  // TODO(burdon): Update when layout changes.
226
372
  if (options.drag) {
227
- circle.call(options.drag);
373
+ hitTarget.call(options.drag);
228
374
  }
229
375
 
230
- // Click.
376
+ // Click. d3 invokes `on` listeners as `(event, datum)` where datum is the bound data on
377
+ // the listener's host element (the dx-node `<g>`). Use it directly — reading from
378
+ // `event.target` returned undefined for the inner circle / text (which don't inherit
379
+ // __data__), and `this` plus `select(this).datum()` was producing inconsistent results
380
+ // across HMR reloads.
231
381
  if (options.onNodeClick) {
232
- group.on('click', (event: MouseEvent) => {
233
- const node = select<SVGElement, GraphLayoutNode<Data>>(event.target as SVGGElement).datum();
234
- options.onNodeClick(node, event);
382
+ group.on('click', (event: MouseEvent, d: GraphLayoutNode<Data>) => {
383
+ options.onNodeClick(d, event);
235
384
  });
236
385
  }
237
386
 
@@ -244,26 +393,36 @@ const createNode: D3Callable = <Data>(group: D3Selection, options: GraphRenderer
244
393
  }
245
394
 
246
395
  // Hover.
247
- if (options.onNodePointerEnter) {
248
- circle.on('pointerenter', function (event: PointerEvent) {
249
- const node = select<any, GraphLayoutNode<Data>>(this.parentElement).datum();
250
- options.onNodePointerEnter(node, event);
396
+ if (options.onNodePointerEnter || options.onNodePointerLeave || options.highlightOnHover) {
397
+ hitTarget.on('pointerenter', function (event: PointerEvent) {
398
+ const node = select<any, GraphLayoutNode<Data>>(useCustom ? this : this.parentElement).datum();
399
+ options.onNodePointerEnter?.(node, event);
400
+ if (options.highlightOnHover) {
401
+ applyHoverHighlight((this as Element).closest('g.dx-graph') as SVGGElement | null, node.id);
402
+ }
403
+ });
404
+ hitTarget.on('pointerleave', function (event: PointerEvent) {
405
+ const node = select<any, GraphLayoutNode<Data>>(useCustom ? this : this.parentElement).datum();
406
+ options.onNodePointerLeave?.(node, event);
407
+ if (options.highlightOnHover) {
408
+ applyHoverHighlight((this as Element).closest('g.dx-graph') as SVGGElement | null, null);
409
+ }
251
410
  });
252
411
 
253
- group.attr('data-hover', 'handled'); // TODO(burdon): ???
254
- } else if (options.highlight !== false) {
255
- circle.on('pointerenter', function () {
412
+ group.attr('data-hover', 'handled');
413
+ } else if (options.highlight !== false && !useCustom) {
414
+ hitTarget.on('pointerenter', function () {
256
415
  select(this.closest('g.dx-node')).raise();
257
416
  if (options.labels) {
258
- select(this.parentElement).classed('dx-active', true).classed('dx-highlight', true);
417
+ select(this.parentElement).classed('dx-node-active', true).classed('dx-highlight', true);
259
418
  }
260
419
  });
261
420
 
262
421
  group.on('pointerleave', function () {
263
422
  if (options.labels) {
264
- select(this).classed('dx-active', false);
423
+ select(this).classed('dx-node-active', false);
265
424
  setTimeout(() => {
266
- if (!select(this).classed('dx-active')) {
425
+ if (!select(this).classed('dx-node-active')) {
267
426
  select(this).classed('dx-highlight', false);
268
427
  }
269
428
  }, 300);
@@ -285,6 +444,24 @@ const updateNode: D3Callable = <NodeData = any, EdgeData = any>(
285
444
  return d.x != null && d.y != null ? `translate(${d.x},${d.y})` : undefined;
286
445
  });
287
446
 
447
+ // Hidden state: drive pointer-events + the hover opacity via the `dx-hidden` class;
448
+ // tween the actual opacity attribute on a named transition so it doesn't fight the
449
+ // CSS hover transition (different namespaces, different durations).
450
+ group.classed('dx-hidden', (d) => d.hidden ?? false);
451
+ group
452
+ .transition('hide')
453
+ .ease(easeCubicOut)
454
+ .duration(NODE_HIDE_MS)
455
+ .attr('opacity', (d) => (d.hidden ? 0 : 1));
456
+
457
+ // Re-run the custom shape on every full render so a topology / data update
458
+ // refreshes geometry (e.g. lattice node.r changes on resize, fill changes on
459
+ // typename change). The cheap fast path (`applyPositions`) doesn't touch
460
+ // shapes, so this only runs on the rarer topology-emit code path.
461
+ if (options.renderNode) {
462
+ renderCustomShape(group, options);
463
+ }
464
+
288
465
  // Custom attributes.
289
466
  if (options.attributes?.node) {
290
467
  try {
@@ -310,8 +487,10 @@ const updateNode: D3Callable = <NodeData = any, EdgeData = any>(
310
487
  ? (group.transition(options.transition()) as unknown as D3Selection)
311
488
  : group;
312
489
 
313
- // Update circles.
314
- groupOrTransition.select<SVGCircleElement>('circle').attr('r', (d) => d.r ?? 16);
490
+ // Update circles. Skipped when the consumer supplied a custom node shape.
491
+ if (!options.renderNode) {
492
+ groupOrTransition.select<SVGCircleElement>('circle').attr('r', (d) => d.r ?? 16);
493
+ }
315
494
 
316
495
  // Update labels.
317
496
  if (options.labels) {
@@ -423,7 +602,11 @@ const updateEdge: D3Callable = <NodeData = any, EdgeData = any>(
423
602
 
424
603
  groupOrTransition.selectAll<SVGPathElement, GraphLayoutEdge<NodeData, EdgeData>>('path').attr('d', function () {
425
604
  // NOTE: `d` is stale after layout is switched so get the datum from the parent element.
426
- const { source, target } = select(this.parentElement).datum() as GraphLayoutEdge<NodeData, EdgeData>;
605
+ const edge = select(this.parentElement).datum() as GraphLayoutEdge<NodeData, EdgeData>;
606
+ if (edge.path) {
607
+ return edge.path;
608
+ }
609
+ const { source, target } = edge;
427
610
  if (!source.initialized || !target.initialized) {
428
611
  return;
429
612
  }
@@ -432,6 +615,82 @@ const updateEdge: D3Callable = <NodeData = any, EdgeData = any>(
432
615
  });
433
616
  };
434
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
+
435
694
  // TODO(burdon): Factor out.
436
695
 
437
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
+ };
@@ -4,8 +4,6 @@
4
4
 
5
5
  import { type RefObject } from 'react';
6
6
 
7
- import { invariant } from '@dxos/invariant';
8
-
9
7
  import { type SVGContext } from '../../hooks';
10
8
  import { type IdAccessor, defaultIdAccessor } from '../types';
11
9
 
@@ -36,8 +34,12 @@ export abstract class Renderer<LAYOUT, OPTIONS extends RendererOptions> {
36
34
  return this._context;
37
35
  }
38
36
 
39
- get root(): SVGGElement {
40
- invariant(this._root.current, 'SVG root is not initialized');
37
+ /**
38
+ * Returns the SVG group root if mounted.
39
+ * The ref may be null between mount/unmount cycles or before the SVG container has sized.
40
+ * Callers should treat null as "skip this render" rather than as an error.
41
+ */
42
+ get root(): SVGGElement | null {
41
43
  return this._root.current;
42
44
  }
43
45
 
@@ -46,4 +48,13 @@ export abstract class Renderer<LAYOUT, OPTIONS extends RendererOptions> {
46
48
  }
47
49
 
48
50
  abstract render(layout: LAYOUT): void;
51
+
52
+ /**
53
+ * Fast path invoked when only positions changed.
54
+ * Default falls back to a full `render`; subclasses can override to skip
55
+ * enter/exit joins and attribute callbacks for per-tick updates.
56
+ */
57
+ applyPositions(layout: LAYOUT): void {
58
+ this.render(layout);
59
+ }
49
60
  }
@@ -45,6 +45,14 @@ export type GraphLayoutNode<NodeData = any> = {
45
45
  type?: string;
46
46
  order?: number;
47
47
  data?: NodeData;
48
+ /** Human-readable label. Synthetic nodes (e.g. cluster root / group) carry this so
49
+ * consumer renderNode callbacks can label them without parsing internal id formats. */
50
+ label?: string;
51
+ /** When true the node remains in the layout but is rendered with opacity 0 and no
52
+ * pointer events — used by the cluster's collapse animation so hidden leaves can
53
+ * tween to their parent's position rather than popping out, and tween back when the
54
+ * parent is re-expanded. */
55
+ hidden?: boolean;
48
56
  x?: number;
49
57
  y?: number;
50
58
  r?: number;
@@ -65,6 +73,12 @@ export type GraphLayoutEdge<NodeData = any, EdgeData = any> = {
65
73
  target: GraphLayoutNode<NodeData>;
66
74
  data?: EdgeData;
67
75
  linkForce?: boolean;
76
+ /**
77
+ * Precomputed SVG `d` attribute. When set, the renderer uses this instead of
78
+ * deriving a straight-line path from `source/target` positions. Lets projectors
79
+ * own edge geometry (e.g. radial elbows, bundled curves) without renderer changes.
80
+ */
81
+ path?: string;
68
82
  classes?: {
69
83
  path?: string;
70
84
  };