@dxos/react-ui-graph 0.8.4-main.fffef41 → 0.9.0

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 (138) hide show
  1. package/LICENSE +102 -5
  2. package/README.md +5 -7
  3. package/dist/lib/browser/chunk-EASNZZ7B.mjs +52 -0
  4. package/dist/lib/browser/chunk-EASNZZ7B.mjs.map +7 -0
  5. package/dist/lib/browser/index.mjs +2729 -592
  6. package/dist/lib/browser/index.mjs.map +4 -4
  7. package/dist/lib/browser/meta.json +1 -1
  8. package/dist/lib/browser/testing/index.mjs +16 -16
  9. package/dist/lib/browser/testing/index.mjs.map +3 -3
  10. package/dist/lib/node-esm/chunk-JSE2X4ML.mjs +54 -0
  11. package/dist/lib/node-esm/chunk-JSE2X4ML.mjs.map +7 -0
  12. package/dist/lib/node-esm/index.mjs +2729 -592
  13. package/dist/lib/node-esm/index.mjs.map +4 -4
  14. package/dist/lib/node-esm/meta.json +1 -1
  15. package/dist/lib/node-esm/testing/index.mjs +16 -16
  16. package/dist/lib/node-esm/testing/index.mjs.map +3 -3
  17. package/dist/types/src/components/Graph/Graph.d.ts +23 -6
  18. package/dist/types/src/components/Graph/Graph.d.ts.map +1 -1
  19. package/dist/types/src/components/Graph/Graph.stories.d.ts +6 -6
  20. package/dist/types/src/components/Graph/Graph.stories.d.ts.map +1 -1
  21. package/dist/types/src/components/Mesh/Mesh.d.ts.map +1 -1
  22. package/dist/types/src/components/Mesh/Mesh.stories.d.ts.map +1 -1
  23. package/dist/types/src/components/SVG/FPS.d.ts +20 -0
  24. package/dist/types/src/components/SVG/FPS.d.ts.map +1 -0
  25. package/dist/types/src/components/SVG/Grid.d.ts.map +1 -1
  26. package/dist/types/src/components/SVG/Markers.d.ts.map +1 -1
  27. package/dist/types/src/components/SVG/Root.d.ts +8 -4
  28. package/dist/types/src/components/SVG/Root.d.ts.map +1 -1
  29. package/dist/types/src/components/SVG/SVG.d.ts +17 -18
  30. package/dist/types/src/components/SVG/SVG.d.ts.map +1 -1
  31. package/dist/types/src/components/SVG/Svg.stories.d.ts +1 -1
  32. package/dist/types/src/components/SVG/Svg.stories.d.ts.map +1 -1
  33. package/dist/types/src/fx/fx.stories.d.ts +3 -3
  34. package/dist/types/src/fx/fx.stories.d.ts.map +1 -1
  35. package/dist/types/src/fx/pulsar.d.ts.map +1 -1
  36. package/dist/types/src/graph/markers.d.ts.map +1 -1
  37. package/dist/types/src/graph/projector/graph-bundle-projector.d.ts +47 -0
  38. package/dist/types/src/graph/projector/graph-bundle-projector.d.ts.map +1 -0
  39. package/dist/types/src/graph/projector/graph-cluster-projector.d.ts +65 -0
  40. package/dist/types/src/graph/projector/graph-cluster-projector.d.ts.map +1 -0
  41. package/dist/types/src/graph/projector/graph-drag.d.ts.map +1 -1
  42. package/dist/types/src/graph/projector/graph-force-projector.d.ts +1 -1
  43. package/dist/types/src/graph/projector/graph-force-projector.d.ts.map +1 -1
  44. package/dist/types/src/graph/projector/graph-forces.d.ts.map +1 -1
  45. package/dist/types/src/graph/projector/graph-hierarchical-projector.d.ts +1 -1
  46. package/dist/types/src/graph/projector/graph-hierarchical-projector.d.ts.map +1 -1
  47. package/dist/types/src/graph/projector/graph-lattice-projector.d.ts +23 -0
  48. package/dist/types/src/graph/projector/graph-lattice-projector.d.ts.map +1 -0
  49. package/dist/types/src/graph/projector/graph-plexus-projector.d.ts +67 -0
  50. package/dist/types/src/graph/projector/graph-plexus-projector.d.ts.map +1 -0
  51. package/dist/types/src/graph/projector/graph-plexus-projector.test.d.ts +2 -0
  52. package/dist/types/src/graph/projector/graph-plexus-projector.test.d.ts.map +1 -0
  53. package/dist/types/src/graph/projector/graph-projector.d.ts +10 -2
  54. package/dist/types/src/graph/projector/graph-projector.d.ts.map +1 -1
  55. package/dist/types/src/graph/projector/graph-radial-projector.d.ts +7 -1
  56. package/dist/types/src/graph/projector/graph-radial-projector.d.ts.map +1 -1
  57. package/dist/types/src/graph/projector/graph-relational-projector.d.ts +1 -1
  58. package/dist/types/src/graph/projector/graph-relational-projector.d.ts.map +1 -1
  59. package/dist/types/src/graph/projector/graph-swarm-projector.d.ts +72 -0
  60. package/dist/types/src/graph/projector/graph-swarm-projector.d.ts.map +1 -0
  61. package/dist/types/src/graph/projector/index.d.ts +5 -0
  62. package/dist/types/src/graph/projector/index.d.ts.map +1 -1
  63. package/dist/types/src/graph/projector/projector.d.ts +10 -1
  64. package/dist/types/src/graph/projector/projector.d.ts.map +1 -1
  65. package/dist/types/src/graph/renderer/bullets.d.ts.map +1 -1
  66. package/dist/types/src/graph/renderer/graph-renderer.d.ts +41 -1
  67. package/dist/types/src/graph/renderer/graph-renderer.d.ts.map +1 -1
  68. package/dist/types/src/graph/renderer/index.d.ts +1 -0
  69. package/dist/types/src/graph/renderer/index.d.ts.map +1 -1
  70. package/dist/types/src/graph/renderer/labels.d.ts +33 -0
  71. package/dist/types/src/graph/renderer/labels.d.ts.map +1 -0
  72. package/dist/types/src/graph/renderer/renderer.d.ts +12 -1
  73. package/dist/types/src/graph/renderer/renderer.d.ts.map +1 -1
  74. package/dist/types/src/graph/types.d.ts +15 -1
  75. package/dist/types/src/graph/types.d.ts.map +1 -1
  76. package/dist/types/src/hooks/useGrid.d.ts.map +1 -1
  77. package/dist/types/src/hooks/useStateRef.d.ts.map +1 -1
  78. package/dist/types/src/hooks/useSvgContext.d.ts.map +1 -1
  79. package/dist/types/src/hooks/useZoom.d.ts.map +1 -1
  80. package/dist/types/src/stories/experimental.stories.d.ts +7 -0
  81. package/dist/types/src/stories/experimental.stories.d.ts.map +1 -0
  82. package/dist/types/src/stories/hooks.stories.d.ts +4 -3
  83. package/dist/types/src/stories/hooks.stories.d.ts.map +1 -1
  84. package/dist/types/src/testing/data.d.ts +5 -5
  85. package/dist/types/src/testing/data.d.ts.map +1 -1
  86. package/dist/types/src/testing/hooks.d.ts +2 -16
  87. package/dist/types/src/testing/hooks.d.ts.map +1 -1
  88. package/dist/types/src/testing/model.d.ts +4 -8
  89. package/dist/types/src/testing/model.d.ts.map +1 -1
  90. package/dist/types/src/util/events.d.ts.map +1 -1
  91. package/dist/types/src/util/fraction.d.ts +1 -1
  92. package/dist/types/src/util/fraction.d.ts.map +1 -1
  93. package/dist/types/src/util/points.d.ts.map +1 -1
  94. package/dist/types/src/util/scale.d.ts.map +1 -1
  95. package/dist/types/src/util/screen.d.ts.map +1 -1
  96. package/dist/types/src/util/vector.d.ts.map +1 -1
  97. package/dist/types/tsconfig.tsbuildinfo +1 -1
  98. package/package.json +33 -35
  99. package/src/components/Graph/Graph.stories.tsx +45 -39
  100. package/src/components/Graph/Graph.tsx +126 -23
  101. package/src/components/Mesh/Mesh.stories.tsx +8 -7
  102. package/src/components/Mesh/Mesh.tsx +43 -35
  103. package/src/components/SVG/FPS.tsx +91 -0
  104. package/src/components/SVG/Grid.tsx +1 -1
  105. package/src/components/SVG/Root.tsx +42 -9
  106. package/src/components/SVG/SVG.tsx +14 -3
  107. package/src/components/SVG/Svg.stories.tsx +4 -5
  108. package/src/fx/fx.stories.tsx +7 -8
  109. package/src/graph/projector/graph-bundle-projector.ts +210 -0
  110. package/src/graph/projector/graph-cluster-projector.ts +337 -0
  111. package/src/graph/projector/graph-drag.ts +0 -1
  112. package/src/graph/projector/graph-force-projector.ts +7 -3
  113. package/src/graph/projector/graph-hierarchical-projector.ts +4 -4
  114. package/src/graph/projector/graph-lattice-projector.ts +86 -0
  115. package/src/graph/projector/graph-plexus-projector.test.ts +102 -0
  116. package/src/graph/projector/graph-plexus-projector.ts +309 -0
  117. package/src/graph/projector/graph-projector.ts +24 -4
  118. package/src/graph/projector/graph-radial-projector.ts +31 -4
  119. package/src/graph/projector/graph-relational-projector.ts +4 -4
  120. package/src/graph/projector/graph-swarm-projector.ts +373 -0
  121. package/src/graph/projector/index.ts +5 -0
  122. package/src/graph/projector/projector.ts +12 -3
  123. package/src/graph/renderer/graph-renderer.ts +289 -31
  124. package/src/graph/renderer/index.ts +1 -0
  125. package/src/graph/renderer/labels.ts +138 -0
  126. package/src/graph/renderer/renderer.ts +15 -4
  127. package/src/graph/types.ts +15 -1
  128. package/src/stories/experimental.stories.tsx +446 -0
  129. package/src/stories/hooks.stories.tsx +21 -10
  130. package/src/testing/data.ts +14 -14
  131. package/src/testing/hooks.ts +3 -4
  132. package/src/testing/model.ts +6 -6
  133. package/src/util/fraction.ts +1 -1
  134. package/styles/graph.css +341 -43
  135. package/dist/lib/browser/chunk-XWA2XJDX.mjs +0 -955
  136. package/dist/lib/browser/chunk-XWA2XJDX.mjs.map +0 -7
  137. package/dist/lib/node-esm/chunk-3RLSFEEV.mjs +0 -957
  138. package/dist/lib/node-esm/chunk-3RLSFEEV.mjs.map +0 -7
@@ -9,12 +9,26 @@ import { log } from '@dxos/log';
9
9
 
10
10
  import { type D3Callable, type D3Selection, type Point, getCircumferencePoints } from '../../util';
11
11
  import { type GraphLayout, type GraphLayoutEdge, type GraphLayoutNode } from '../types';
12
-
13
12
  import { createBullets } from './bullets';
14
13
  import { Renderer, type RendererOptions } from './renderer';
15
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
+
16
22
  const createLine = line<Point>();
17
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
+
18
32
  export type LabelOptions<NodeData = any> = {
19
33
  text: (node: GraphLayoutNode<NodeData>, highlight?: boolean) => string | undefined;
20
34
  };
@@ -41,17 +55,39 @@ export type GraphRendererOptions<NodeData = any, EdgeData = any> = RendererOptio
41
55
  labels?: LabelOptions<NodeData>;
42
56
  subgraphs?: boolean;
43
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;
44
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;
45
84
  onNodeClick?: (node: GraphLayoutNode<NodeData>, event: MouseEvent) => void;
46
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;
47
88
  onLinkClick?: (link: GraphLayoutEdge<NodeData, EdgeData>, event: MouseEvent) => void;
48
89
  }>;
49
90
 
50
- // TODO(burdon): Perf
51
- // - Leaking JS event listeners.
52
- // - Don't update unless data changes.
53
- // - Cache subgraph components in layout.
54
-
55
91
  /**
56
92
  * Renders the Graph layout.
57
93
  */
@@ -59,7 +95,26 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
59
95
  GraphLayout<NodeData, EdgeData>,
60
96
  GraphRendererOptions<NodeData, EdgeData>
61
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
+
62
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
+
63
118
  log('render', layout);
64
119
 
65
120
  const root = select(this.root);
@@ -146,7 +201,8 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
146
201
  .selectAll('g.dx-edges')
147
202
  .data([{ id: 'edges' }], (d: any) => d.id)
148
203
  .join('g')
149
- .classed('dx-edges', true);
204
+ .classed('dx-edges', true)
205
+ .style('opacity', this.options.edgeOpacity != null ? String(this.options.edgeOpacity) : null);
150
206
 
151
207
  const nodeGroup = root
152
208
  .selectAll('g.dx-nodes')
@@ -166,10 +222,13 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
166
222
  enter
167
223
  .append('g')
168
224
  .attr('data-id', (d) => d.id)
169
- .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))
170
229
  .classed('dx-node', true)
171
230
  .call(createNode, this.options),
172
- (update) => update.call(updateNode, this.options),
231
+ (update) => update,
173
232
  (exit) => {
174
233
  // Fade out.
175
234
  return exit
@@ -182,6 +241,9 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
182
241
  });
183
242
  },
184
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)
185
247
  .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
186
248
 
187
249
  //
@@ -198,17 +260,79 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
198
260
  .attr('data-id', (d) => d.id)
199
261
  .classed('dx-edge', true)
200
262
  .call(createEdge, this.options),
201
- (update) => update.call(updateEdge, this.options, nodeGroup).each((d) => {}),
202
- (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
+ }),
203
275
  )
276
+ // Apply edge updates (paths / attributes) to enter+update — see note on nodes above.
277
+ .call(updateEdge, this.options, nodeGroup)
204
278
  .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
205
279
  }
206
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
+
207
328
  /**
208
329
  * Trigger path bullets.
209
330
  * @param node
210
331
  */
211
332
  fireBullet(node: GraphLayoutNode<NodeData>) {
333
+ if (!this.root) {
334
+ return;
335
+ }
212
336
  select(this.root).selectAll('g.dx-edges').selectAll('path').call(createBullets(this.root, node.id));
213
337
  }
214
338
  }
@@ -218,21 +342,45 @@ export class GraphRenderer<NodeData = any, EdgeData = any> extends Renderer<
218
342
  * @param group
219
343
  * @param options
220
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
+
221
360
  const createNode: D3Callable = <Data>(group: D3Selection, options: GraphRendererOptions<Data>) => {
222
- // Circle.
223
- 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');
224
369
 
225
370
  // Drag.
226
371
  // TODO(burdon): Update when layout changes.
227
372
  if (options.drag) {
228
- circle.call(options.drag);
373
+ hitTarget.call(options.drag);
229
374
  }
230
375
 
231
- // 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.
232
381
  if (options.onNodeClick) {
233
- group.on('click', (event: MouseEvent) => {
234
- const node = select<SVGElement, GraphLayoutNode<Data>>(event.target as SVGGElement).datum();
235
- options.onNodeClick(node, event);
382
+ group.on('click', (event: MouseEvent, d: GraphLayoutNode<Data>) => {
383
+ options.onNodeClick(d, event);
236
384
  });
237
385
  }
238
386
 
@@ -245,26 +393,36 @@ const createNode: D3Callable = <Data>(group: D3Selection, options: GraphRenderer
245
393
  }
246
394
 
247
395
  // Hover.
248
- if (options.onNodePointerEnter) {
249
- circle.on('pointerenter', function (event: PointerEvent) {
250
- const node = select<any, GraphLayoutNode<Data>>(this.parentElement).datum();
251
- 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
+ }
252
410
  });
253
411
 
254
- group.attr('data-hover', 'handled'); // TODO(burdon): ???
255
- } else if (options.highlight !== false) {
256
- circle.on('pointerenter', function () {
412
+ group.attr('data-hover', 'handled');
413
+ } else if (options.highlight !== false && !useCustom) {
414
+ hitTarget.on('pointerenter', function () {
257
415
  select(this.closest('g.dx-node')).raise();
258
416
  if (options.labels) {
259
- select(this.parentElement).classed('dx-active', true).classed('dx-highlight', true);
417
+ select(this.parentElement).classed('dx-node-active', true).classed('dx-highlight', true);
260
418
  }
261
419
  });
262
420
 
263
421
  group.on('pointerleave', function () {
264
422
  if (options.labels) {
265
- select(this).classed('dx-active', false);
423
+ select(this).classed('dx-node-active', false);
266
424
  setTimeout(() => {
267
- if (!select(this).classed('dx-active')) {
425
+ if (!select(this).classed('dx-node-active')) {
268
426
  select(this).classed('dx-highlight', false);
269
427
  }
270
428
  }, 300);
@@ -286,6 +444,24 @@ const updateNode: D3Callable = <NodeData = any, EdgeData = any>(
286
444
  return d.x != null && d.y != null ? `translate(${d.x},${d.y})` : undefined;
287
445
  });
288
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
+
289
465
  // Custom attributes.
290
466
  if (options.attributes?.node) {
291
467
  try {
@@ -311,8 +487,10 @@ const updateNode: D3Callable = <NodeData = any, EdgeData = any>(
311
487
  ? (group.transition(options.transition()) as unknown as D3Selection)
312
488
  : group;
313
489
 
314
- // Update circles.
315
- 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
+ }
316
494
 
317
495
  // Update labels.
318
496
  if (options.labels) {
@@ -424,7 +602,11 @@ const updateEdge: D3Callable = <NodeData = any, EdgeData = any>(
424
602
 
425
603
  groupOrTransition.selectAll<SVGPathElement, GraphLayoutEdge<NodeData, EdgeData>>('path').attr('d', function () {
426
604
  // NOTE: `d` is stale after layout is switched so get the datum from the parent element.
427
- 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;
428
610
  if (!source.initialized || !target.initialized) {
429
611
  return;
430
612
  }
@@ -433,6 +615,82 @@ const updateEdge: D3Callable = <NodeData = any, EdgeData = any>(
433
615
  });
434
616
  };
435
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
+
436
694
  // TODO(burdon): Factor out.
437
695
 
438
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
  }
@@ -19,7 +19,7 @@ export const defaultIdAccessor: IdAccessor = (node: any) => {
19
19
  return node.id;
20
20
  };
21
21
 
22
- export const emptyGraph: Graph = {
22
+ export const emptyGraph: Graph.Any = {
23
23
  nodes: [],
24
24
  edges: [],
25
25
  };
@@ -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
  };