@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
@@ -0,0 +1,309 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { cluster as d3Cluster, hierarchy, linkRadial } from 'd3';
6
+
7
+ import { type Graph } from '@dxos/graph';
8
+ import { log } from '@dxos/log';
9
+
10
+ import { type GraphLayoutEdge, type GraphLayoutNode } from '../types';
11
+ import {
12
+ GraphRadialProjector,
13
+ type GraphRadialProjectorOptions,
14
+ layoutRadial,
15
+ updateNode,
16
+ } from './graph-radial-projector';
17
+
18
+ /** Display info for a relation group. */
19
+ export type PlexusRelation = {
20
+ /** Stable grouping key — edges sharing a key fan out from the same relation node. */
21
+ key: string;
22
+ /** Human-readable label rendered on the relation node. */
23
+ label: string;
24
+ };
25
+
26
+ export type GraphPlexusProjectorOptions = GraphRadialProjectorOptions & {
27
+ /** Id of the focused node placed at the centre. When unset the layout falls back to a plain ring. */
28
+ focus?: string;
29
+ /** Reserved space around the outer ring (screen pixels). Default 100. */
30
+ margin?: number;
31
+ /** Radius for object leaf nodes — the base size shared by all non-focus nodes. Default 5. */
32
+ leafRadius?: number;
33
+ /** Radius for the synthetic relation nodes. Defaults to the leaf radius. */
34
+ relationRadius?: number;
35
+ /** Radius for the focused centre node. Defaults to double the leaf radius. */
36
+ focusRadius?: number;
37
+ /**
38
+ * Classify an edge incident to the focus into a relation group. Return `undefined` to
39
+ * ignore the edge (e.g. when the focus is not one of the edge's endpoints). The neighbour
40
+ * placed under the relation is the edge endpoint that is NOT the focus, so both sides of a
41
+ * relation are supported: classify outgoing edges (focus is source) and incoming edges
42
+ * (focus is target) under different keys to get a separate relation node for each side.
43
+ * Mirrors the `groupOf` callback used by the cluster / bundle projectors — all ECHO
44
+ * knowledge stays in the consumer.
45
+ */
46
+ relationOf?: (edge: GraphLayoutEdge, focusId: string) => PlexusRelation | undefined;
47
+ };
48
+
49
+ const RELATION_PREFIX = '__plexus_relation__:';
50
+ const HIER_EDGE_PREFIX = '__plexus_hier__:';
51
+
52
+ /** Node type tags so consumer renderers can distinguish the three kinds of node. */
53
+ export const PLEXUS_NODE_TYPE_FOCUS = 'plexus-focus';
54
+ export const PLEXUS_NODE_TYPE_RELATION = 'plexus-relation';
55
+ export const PLEXUS_NODE_TYPE_OBJECT = 'plexus-object';
56
+
57
+ /**
58
+ * Standard d3 radial link generator — `curveBumpRadial` (same as the cluster projector).
59
+ * Relies on `dx-edge path { fill: none }` from graph.css.
60
+ */
61
+ const linkPath = linkRadial<any, any>()
62
+ .angle((d: any) => d.x)
63
+ .radius((d: any) => d.y);
64
+
65
+ /**
66
+ * Cartesian → d3-radial polar. d3 measures angle clockwise from "up" (the -y direction).
67
+ * Inverse of `[cos(a - π/2) * r, sin(a - π/2) * r]`.
68
+ */
69
+ const cartesianToPolar = (x: number, y: number): { angle: number; radius: number } => ({
70
+ angle: Math.atan2(x, -y),
71
+ radius: Math.hypot(x, y),
72
+ });
73
+
74
+ /**
75
+ * Focus-centric radial layout. A single focused object sits at the centre; its immediate
76
+ * neighbourhood fans out around it, grouped by the relation that connects each neighbour
77
+ * to the focus:
78
+ *
79
+ * - **Focus** (depth 0) — the focused data node, at the origin.
80
+ * - **Relation nodes** (depth 1) — synthetic group nodes (one per `relationOf` key) on an
81
+ * inner ring.
82
+ * - **Object nodes** (depth 2) — the neighbours reached through each relation, on the
83
+ * outer ring.
84
+ *
85
+ * Built on the same `d3.cluster` machinery as `GraphClusterProjector`: the synthesized
86
+ * `focus → relation → object` hierarchy is laid out radially and each hierarchy edge gets
87
+ * a `linkRadial` `path` recomputed from current cartesian endpoints every tick, so curves
88
+ * track moving nodes during a cross-focus (or cross-variant) tween.
89
+ *
90
+ * Focus itself is owned by the consumer (passed via `options.focus`); re-focusing is a
91
+ * matter of recreating the projector with the new focus and the previous layout as `prev`,
92
+ * which makes persistent nodes animate into their new positions.
93
+ */
94
+ export class GraphPlexusProjector<
95
+ NodeData = any,
96
+ Options extends GraphPlexusProjectorOptions = any,
97
+ > extends GraphRadialProjector<NodeData, Options> {
98
+ // Full node / edge snapshots taken right after mergeData — doPlexusLayout reads from
99
+ // these because it overwrites layout.graph with the filtered focus-centric view.
100
+ #dataNodes: GraphLayoutNode<NodeData>[] = [];
101
+ #dataEdges: GraphLayoutEdge<NodeData>[] = [];
102
+
103
+ protected override onUpdate(graph?: Graph.Any) {
104
+ log('onUpdate', { graph: { nodes: graph?.nodes.length, edges: graph?.edges.length } });
105
+ this.mergeData(graph);
106
+ this.#dataNodes = [...this.layout.graph.nodes];
107
+ this.#dataEdges = [...this.layout.graph.edges];
108
+ this.doPlexusLayout();
109
+ this.emitUpdate('topology');
110
+ this.animate();
111
+ }
112
+
113
+ /**
114
+ * Recompute each hierarchy edge's `path` from current cartesian endpoints so curves track
115
+ * moving nodes during the tween (identical strategy to the cluster projector).
116
+ */
117
+ protected override onTickFrame(_t: number): void {
118
+ for (const edge of this.layout.graph.edges) {
119
+ if (edge.type !== 'hierarchy') {
120
+ continue;
121
+ }
122
+ const { source, target } = edge;
123
+ const s = cartesianToPolar(source.x ?? 0, source.y ?? 0);
124
+ const t = cartesianToPolar(target.x ?? 0, target.y ?? 0);
125
+ edge.path = linkPath({ source: { x: s.angle, y: s.radius }, target: { x: t.angle, y: t.radius } });
126
+ }
127
+ }
128
+
129
+ private doPlexusLayout() {
130
+ if (!this.context.size) {
131
+ return;
132
+ }
133
+
134
+ const dataNodes = this.#dataNodes;
135
+ if (!dataNodes.length) {
136
+ return;
137
+ }
138
+
139
+ const focusId = this.options.focus;
140
+ const focusNode = focusId ? dataNodes.find((node) => node.id === focusId) : undefined;
141
+
142
+ // No focus (or it dropped out of the graph): degrade to a plain ring of all nodes so the
143
+ // surface is never blank. In practice the consumer dispatches to the bundle projector
144
+ // when there is no focus, so this is just a safety net.
145
+ if (!focusNode) {
146
+ const radial = layoutRadial(
147
+ 0,
148
+ 0,
149
+ Math.min(this.context.size.width, this.context.size.height) / 2 - (this.options.margin ?? 100),
150
+ dataNodes.length,
151
+ );
152
+ dataNodes.forEach((node, index) => updateNode(node, radial(index), this.options.leafRadius ?? 5));
153
+ this.layout.graph.nodes = dataNodes;
154
+ this.layout.graph.edges = [];
155
+ this.animate();
156
+ return;
157
+ }
158
+
159
+ const relationOf = this.options.relationOf ?? defaultRelationOf;
160
+
161
+ // Group neighbours by relation. A neighbour reachable through more than one relation is
162
+ // placed once (first relation wins) — keeps hierarchy ids unique for v1.
163
+ type Group = { id: string; label: string; leaves: GraphLayoutNode<NodeData>[] };
164
+ const groups = new Map<string, Group>();
165
+ const placed = new Set<string>([focusId!]);
166
+ for (const edge of this.#dataEdges) {
167
+ const relation = relationOf(edge, focusId!);
168
+ if (!relation) {
169
+ continue;
170
+ }
171
+ const neighbour = edge.source.id === focusId ? edge.target : edge.source;
172
+ if (placed.has(neighbour.id)) {
173
+ continue;
174
+ }
175
+ placed.add(neighbour.id);
176
+ let group = groups.get(relation.key);
177
+ if (!group) {
178
+ group = { id: `${RELATION_PREFIX}${relation.key}`, label: relation.label, leaves: [] };
179
+ groups.set(relation.key, group);
180
+ }
181
+ group.leaves.push(neighbour);
182
+ }
183
+
184
+ // Synthesize the focus → relation → object hierarchy.
185
+ type HierNode = {
186
+ id: string;
187
+ parent?: string;
188
+ node?: GraphLayoutNode<NodeData>;
189
+ relationLabel?: string;
190
+ };
191
+ const items: HierNode[] = [{ id: focusId!, node: focusNode }];
192
+ for (const group of groups.values()) {
193
+ items.push({ id: group.id, parent: focusId, relationLabel: group.label });
194
+ for (const leaf of group.leaves) {
195
+ items.push({ id: leaf.id, parent: group.id, node: leaf });
196
+ }
197
+ }
198
+
199
+ const childrenByParent = new Map<string, HierNode[]>();
200
+ for (const item of items) {
201
+ if (item.parent) {
202
+ const list = childrenByParent.get(item.parent) ?? [];
203
+ list.push(item);
204
+ childrenByParent.set(item.parent, list);
205
+ }
206
+ }
207
+
208
+ const root = hierarchy<HierNode>({ id: focusId!, node: focusNode }, (d) => childrenByParent.get(d.id) ?? []);
209
+
210
+ const { width, height } = this.context.size;
211
+ const margin = this.options.margin ?? 100;
212
+ const ringRadius = Math.max(0, Math.min(width, height) / 2 - margin);
213
+
214
+ d3Cluster<HierNode>()
215
+ .size([2 * Math.PI, ringRadius])
216
+ .separation((a: any, b: any) => (a.parent === b.parent ? 1 : 2) / Math.max(1, a.depth))(root);
217
+
218
+ // All non-focus nodes share the leaf radius; the focus is double.
219
+ const leafR = this.options.leafRadius ?? 5;
220
+ const relationR = this.options.relationRadius ?? leafR;
221
+ const focusR = this.options.focusRadius ?? leafR * 2;
222
+
223
+ // Reuse synthetic relation stubs from the previous pass so their current x/y becomes the
224
+ // tween start instead of snapping to the origin first.
225
+ const prevStubsById = new Map<string, GraphLayoutNode<NodeData>>();
226
+ for (const node of this.layout.graph.nodes) {
227
+ if (node.type === PLEXUS_NODE_TYPE_RELATION) {
228
+ prevStubsById.set(node.id, node);
229
+ }
230
+ }
231
+
232
+ const relationStubs = new Map<string, GraphLayoutNode<NodeData>>();
233
+ root.each((d: any) => {
234
+ const angle = d.x;
235
+ const radius = d.y;
236
+ const x = Math.cos(angle - Math.PI / 2) * radius;
237
+ const y = Math.sin(angle - Math.PI / 2) * radius;
238
+ const id = d.data.id;
239
+
240
+ if (id === focusId) {
241
+ // Real focus node at the centre.
242
+ updateNode(focusNode, [x, y], focusR);
243
+ (focusNode as any).type = PLEXUS_NODE_TYPE_FOCUS;
244
+ focusNode.hidden = false;
245
+ } else if (d.data.node) {
246
+ // Real object leaf.
247
+ updateNode(d.data.node, [x, y], leafR);
248
+ (d.data.node as any).type = PLEXUS_NODE_TYPE_OBJECT;
249
+ d.data.node.hidden = false;
250
+ } else {
251
+ // Synthetic relation node.
252
+ const stub = prevStubsById.get(id) ?? ({ id, x: 0, y: 0 } as GraphLayoutNode<NodeData>);
253
+ updateNode(stub, [x, y], relationR);
254
+ stub.type = PLEXUS_NODE_TYPE_RELATION;
255
+ stub.label = d.data.relationLabel;
256
+ relationStubs.set(id, stub);
257
+ }
258
+ });
259
+
260
+ // Compose the rendered node list: relations first, then leaves, focus last (drawn on top).
261
+ const nextNodes: GraphLayoutNode<NodeData>[] = [];
262
+ for (const stub of relationStubs.values()) {
263
+ nextNodes.push(stub);
264
+ }
265
+ for (const group of groups.values()) {
266
+ for (const leaf of group.leaves) {
267
+ nextNodes.push(leaf);
268
+ }
269
+ }
270
+ nextNodes.push(focusNode);
271
+ this.layout.graph.nodes = nextNodes;
272
+
273
+ // Build hierarchy edges (focus → relation, relation → object). Paths are filled by
274
+ // onTickFrame from current cartesian positions.
275
+ const edges: GraphLayoutEdge<NodeData>[] = [];
276
+ root.links().forEach((link: any) => {
277
+ const sid = link.source.data.id;
278
+ const tid = link.target.data.id;
279
+ const sourceNode = sid === focusId ? focusNode : (link.source.data.node ?? relationStubs.get(sid));
280
+ const targetNode = link.target.data.node ?? relationStubs.get(tid);
281
+ if (!sourceNode || !targetNode) {
282
+ return;
283
+ }
284
+ edges.push({
285
+ id: `${HIER_EDGE_PREFIX}${sid}->${tid}`,
286
+ type: 'hierarchy',
287
+ source: sourceNode,
288
+ target: targetNode,
289
+ data: undefined,
290
+ });
291
+ });
292
+ this.layout.graph.edges = edges;
293
+
294
+ // Seed initial paths so the topology emit has correct geometry to enter into the DOM.
295
+ this.onTickFrame(0);
296
+ }
297
+ }
298
+
299
+ /** Fallback grouping: every edge incident to the focus becomes a relation keyed by edge type + direction. */
300
+ const defaultRelationOf = (edge: GraphLayoutEdge, focusId: string): PlexusRelation | undefined => {
301
+ const outgoing = edge.source.id === focusId;
302
+ const incoming = edge.target.id === focusId;
303
+ if (!outgoing && !incoming) {
304
+ return undefined;
305
+ }
306
+ const type = edge.type ?? 'edge';
307
+ const arrow = outgoing ? '→' : '←';
308
+ return { key: `${type}:${outgoing ? 'out' : 'in'}`, label: `${type} ${arrow}` };
309
+ };
@@ -6,7 +6,6 @@ import { type Graph, type SelectionModel } from '@dxos/graph';
6
6
 
7
7
  import { type SVGContext } from '../../hooks';
8
8
  import { type GraphLayout, type GraphLayoutNode, emptyGraph } from '../types';
9
-
10
9
  import { Projector, type ProjectorOptions } from './projector';
11
10
 
12
11
  export type GraphProjectorOptions = ProjectorOptions & {};
@@ -15,7 +14,7 @@ export type GraphProjectorOptions = ProjectorOptions & {};
15
14
  * Base class for graph projectors.
16
15
  */
17
16
  export abstract class GraphProjector<NodeData = any, Options extends GraphProjectorOptions = any> extends Projector<
18
- Graph,
17
+ Graph.Any,
19
18
  GraphLayout<NodeData>,
20
19
  Options
21
20
  > {
@@ -60,7 +59,7 @@ export abstract class GraphProjector<NodeData = any, Options extends GraphProjec
60
59
  * Merge external data with internal representation (e.g., so force properties like position are preserved).
61
60
  * @param data
62
61
  */
63
- protected mergeData(data: Graph = emptyGraph) {
62
+ protected mergeData(data: Graph.Any = emptyGraph) {
64
63
  // Merge nodes.
65
64
  const nodes: GraphLayoutNode[] = data.nodes.map((node) => {
66
65
  let current: GraphLayoutNode = this._layout.graph.nodes.find((n) => n.id === this.options.idAccessor(node));
@@ -71,13 +70,23 @@ export abstract class GraphProjector<NodeData = any, Options extends GraphProjec
71
70
  }
72
71
 
73
72
  current.data = node;
73
+ // `hidden` is a transient flag set by the cluster projector to fade
74
+ // collapsed leaves. Reset it on every merge so that (a) switching
75
+ // away from cluster to another projector — which inherits the
76
+ // previous layout via `prev` — doesn't carry forward stale hidden
77
+ // flags, and (b) the cluster projector itself re-applies the flag
78
+ // each `doClusterLayout` pass.
79
+ current.hidden = false;
74
80
  return current;
75
81
  });
76
82
 
77
- // Replace edges.
83
+ // Replace edges. Preserve `type` so projectors can classify edges by their source
84
+ // semantics (e.g. the plexus projector groups by relation vs ref); projectors that
85
+ // synthesize their own edges (bundle, cluster) overwrite this downstream.
78
86
  const edges = data.edges
79
87
  .map((edge) => ({
80
88
  id: edge.id,
89
+ type: (edge as { type?: string }).type,
81
90
  source: nodes.find((n) => n.id === edge.source),
82
91
  target: nodes.find((n) => n.id === edge.target),
83
92
  data: edge.data,
@@ -96,5 +105,16 @@ export abstract class GraphProjector<NodeData = any, Options extends GraphProjec
96
105
  this.reset();
97
106
  }
98
107
 
108
+ /**
109
+ * Optional projector-owned click intercept. The Graph component invokes this BEFORE
110
+ * forwarding to the consumer's `onSelect`, so projectors can implement built-in
111
+ * interactions (e.g. cluster collapse) without each consumer wiring them. Returning
112
+ * `true` indicates the click was handled — consumer's `onSelect` is suppressed.
113
+ * Default no-op returns `false` so consumer handlers still run.
114
+ */
115
+ handleNodeClick(_node: GraphLayoutNode<NodeData>, _event: MouseEvent): boolean {
116
+ return false;
117
+ }
118
+
99
119
  abstract findNode(x: number, y: number, radius: number): GraphLayoutNode<NodeData> | undefined;
100
120
  }
@@ -9,7 +9,6 @@ import { log } from '@dxos/log';
9
9
 
10
10
  import { type Point } from '../../util';
11
11
  import { type GraphLayoutNode } from '../types';
12
-
13
12
  import { GraphProjector, type GraphProjectorOptions } from './graph-projector';
14
13
 
15
14
  export type GraphRadialProjectorOptions = GraphProjectorOptions & {
@@ -28,13 +27,20 @@ export class GraphRadialProjector<
28
27
  return undefined;
29
28
  }
30
29
 
31
- protected override onUpdate(graph?: Graph) {
30
+ protected override onUpdate(graph?: Graph.Any) {
32
31
  log('onUpdate', { graph: { nodes: graph?.nodes.length, edges: graph?.edges.length } });
33
32
  this.mergeData(graph);
33
+ // Bind enter/exit once before the tween starts; subsequent animate frames emit 'positions'.
34
+ this.emitUpdate('topology');
34
35
  this.doRadialLayout();
35
36
  }
36
37
 
37
38
  protected animate() {
39
+ // Cancel any in-flight tween so a fresh onUpdate doesn't race against the
40
+ // previous timer (both would be mutating x/y at different rates).
41
+ this._timer?.stop();
42
+ this._timer = undefined;
43
+
38
44
  const start = Date.now();
39
45
  if (this.options.duration) {
40
46
  this._timer = timer(() => {
@@ -47,17 +53,38 @@ export class GraphRadialProjector<
47
53
  node.r = node.sr + (node.tr - node.sr) * d;
48
54
  });
49
55
 
50
- this.emitUpdate();
56
+ // Subclass hook: derived projectors (e.g. cluster) can mutate edge.path
57
+ // here so curves track moving endpoints during the tween. The renderer's
58
+ // applyPositions reads edge.path fresh each frame.
59
+ this.onTickFrame(d);
60
+
61
+ // Tween frames only mutate `x/y/r`; emit 'positions' so the renderer can fast-path.
62
+ this.emitUpdate('positions');
51
63
  if (t >= 1) {
52
64
  this._timer.stop();
53
65
  this._timer = undefined;
54
66
  }
55
67
  });
56
68
  } else {
57
- this.emitUpdate();
69
+ // No duration: snap nodes to their target. Without this the layout would
70
+ // sit at `sx/sy/sr` (= previous positions) and never reach the new target.
71
+ this.layout.graph.nodes.forEach((node: any) => {
72
+ node.x = node.tx;
73
+ node.y = node.ty;
74
+ node.r = node.tr;
75
+ });
76
+ this.onTickFrame(1);
77
+ this.emitUpdate('positions');
58
78
  }
59
79
  }
60
80
 
81
+ /**
82
+ * Per-frame hook called after node x/y/r are interpolated and before the
83
+ * 'positions' emit. Subclasses override to update edge geometry (`edge.path`)
84
+ * so curves stay glued to moving endpoints. `t` is the eased progress in [0, 1].
85
+ */
86
+ protected onTickFrame(t: number): void {}
87
+
61
88
  protected override async onStop() {
62
89
  this._timer?.stop();
63
90
  this._timer = undefined;
@@ -6,7 +6,6 @@ import { type Graph } from '@dxos/graph';
6
6
  import { log } from '@dxos/log';
7
7
 
8
8
  import { type GraphLayoutNode } from '../types';
9
-
10
9
  import { type GraphProjectorOptions } from './graph-projector';
11
10
  import { GraphRadialProjector, layoutHorizontal, layoutRadial, updateNode } from './graph-radial-projector';
12
11
 
@@ -20,14 +19,15 @@ export class GraphRelationalProjector<
20
19
  NodeData = any,
21
20
  Options extends GraphRelationalProjectorOptions = any,
22
21
  > extends GraphRadialProjector<NodeData, Options> {
23
- protected override onUpdate(graph?: Graph) {
22
+ protected override onUpdate(graph?: Graph.Any) {
24
23
  log('onUpdate', {
25
24
  graph: { nodes: graph?.nodes.length, edges: graph?.edges.length },
26
- selection: this.selection?.selected.value,
25
+ selection: this.selection?.getSelectedIds(),
27
26
  });
28
27
 
29
28
  this.mergeData(graph);
30
- const selected = this.selection?.selected.value?.[0];
29
+ this.emitUpdate('topology');
30
+ const selected = this.selection?.getSelectedIds()[0];
31
31
  if (selected) {
32
32
  const node = this.layout.graph.nodes.find((node) => node.id === selected);
33
33
  if (node) {