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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) 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 +1787 -499
  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 +14 -14
  8. package/dist/lib/browser/testing/index.mjs.map +3 -3
  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 +1787 -499
  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 +14 -14
  15. package/dist/lib/node-esm/testing/index.mjs.map +3 -3
  16. package/dist/types/src/components/Graph/Graph.d.ts +22 -4
  17. package/dist/types/src/components/Graph/Graph.d.ts.map +1 -1
  18. package/dist/types/src/components/Graph/Graph.stories.d.ts +5 -5
  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 +1 -1
  31. package/dist/types/src/components/SVG/Svg.stories.d.ts.map +1 -1
  32. package/dist/types/src/fx/fx.stories.d.ts +3 -3
  33. package/dist/types/src/fx/fx.stories.d.ts.map +1 -1
  34. package/dist/types/src/fx/pulsar.d.ts.map +1 -1
  35. package/dist/types/src/graph/markers.d.ts.map +1 -1
  36. package/dist/types/src/graph/projector/graph-bundle-projector.d.ts +47 -0
  37. package/dist/types/src/graph/projector/graph-bundle-projector.d.ts.map +1 -0
  38. package/dist/types/src/graph/projector/graph-cluster-projector.d.ts +65 -0
  39. package/dist/types/src/graph/projector/graph-cluster-projector.d.ts.map +1 -0
  40. package/dist/types/src/graph/projector/graph-drag.d.ts.map +1 -1
  41. package/dist/types/src/graph/projector/graph-force-projector.d.ts.map +1 -1
  42. package/dist/types/src/graph/projector/graph-forces.d.ts.map +1 -1
  43. package/dist/types/src/graph/projector/graph-hierarchical-projector.d.ts.map +1 -1
  44. package/dist/types/src/graph/projector/graph-lattice-projector.d.ts +23 -0
  45. package/dist/types/src/graph/projector/graph-lattice-projector.d.ts.map +1 -0
  46. package/dist/types/src/graph/projector/graph-plexus-projector.d.ts +67 -0
  47. package/dist/types/src/graph/projector/graph-plexus-projector.d.ts.map +1 -0
  48. package/dist/types/src/graph/projector/graph-plexus-projector.test.d.ts +2 -0
  49. package/dist/types/src/graph/projector/graph-plexus-projector.test.d.ts.map +1 -0
  50. package/dist/types/src/graph/projector/graph-projector.d.ts +8 -0
  51. package/dist/types/src/graph/projector/graph-projector.d.ts.map +1 -1
  52. package/dist/types/src/graph/projector/graph-radial-projector.d.ts +6 -0
  53. package/dist/types/src/graph/projector/graph-radial-projector.d.ts.map +1 -1
  54. package/dist/types/src/graph/projector/graph-relational-projector.d.ts.map +1 -1
  55. package/dist/types/src/graph/projector/graph-swarm-projector.d.ts +72 -0
  56. package/dist/types/src/graph/projector/graph-swarm-projector.d.ts.map +1 -0
  57. package/dist/types/src/graph/projector/index.d.ts +5 -0
  58. package/dist/types/src/graph/projector/index.d.ts.map +1 -1
  59. package/dist/types/src/graph/projector/projector.d.ts +10 -1
  60. package/dist/types/src/graph/projector/projector.d.ts.map +1 -1
  61. package/dist/types/src/graph/renderer/bullets.d.ts.map +1 -1
  62. package/dist/types/src/graph/renderer/graph-renderer.d.ts +41 -1
  63. package/dist/types/src/graph/renderer/graph-renderer.d.ts.map +1 -1
  64. package/dist/types/src/graph/renderer/index.d.ts +1 -0
  65. package/dist/types/src/graph/renderer/index.d.ts.map +1 -1
  66. package/dist/types/src/graph/renderer/labels.d.ts +33 -0
  67. package/dist/types/src/graph/renderer/labels.d.ts.map +1 -0
  68. package/dist/types/src/graph/renderer/renderer.d.ts +12 -1
  69. package/dist/types/src/graph/renderer/renderer.d.ts.map +1 -1
  70. package/dist/types/src/graph/types.d.ts +14 -0
  71. package/dist/types/src/graph/types.d.ts.map +1 -1
  72. package/dist/types/src/hooks/useGrid.d.ts.map +1 -1
  73. package/dist/types/src/hooks/useStateRef.d.ts.map +1 -1
  74. package/dist/types/src/hooks/useSvgContext.d.ts.map +1 -1
  75. package/dist/types/src/hooks/useZoom.d.ts.map +1 -1
  76. package/dist/types/src/stories/experimental.stories.d.ts +7 -0
  77. package/dist/types/src/stories/experimental.stories.d.ts.map +1 -0
  78. package/dist/types/src/stories/hooks.stories.d.ts +1 -1
  79. package/dist/types/src/stories/hooks.stories.d.ts.map +1 -1
  80. package/dist/types/src/testing/data.d.ts +1 -1
  81. package/dist/types/src/testing/data.d.ts.map +1 -1
  82. package/dist/types/src/testing/hooks.d.ts.map +1 -1
  83. package/dist/types/src/testing/model.d.ts.map +1 -1
  84. package/dist/types/src/util/events.d.ts.map +1 -1
  85. package/dist/types/src/util/fraction.d.ts.map +1 -1
  86. package/dist/types/src/util/points.d.ts.map +1 -1
  87. package/dist/types/src/util/scale.d.ts.map +1 -1
  88. package/dist/types/src/util/screen.d.ts.map +1 -1
  89. package/dist/types/src/util/vector.d.ts.map +1 -1
  90. package/dist/types/tsconfig.tsbuildinfo +1 -1
  91. package/package.json +19 -26
  92. package/src/components/Graph/Graph.stories.tsx +21 -19
  93. package/src/components/Graph/Graph.tsx +115 -19
  94. package/src/components/Mesh/Mesh.stories.tsx +6 -5
  95. package/src/components/Mesh/Mesh.tsx +43 -35
  96. package/src/components/SVG/FPS.tsx +91 -0
  97. package/src/components/SVG/Root.tsx +30 -4
  98. package/src/components/SVG/SVG.tsx +4 -2
  99. package/src/components/SVG/Svg.stories.tsx +2 -3
  100. package/src/fx/fx.stories.tsx +5 -6
  101. package/src/graph/projector/graph-bundle-projector.ts +210 -0
  102. package/src/graph/projector/graph-cluster-projector.ts +337 -0
  103. package/src/graph/projector/graph-drag.ts +0 -1
  104. package/src/graph/projector/graph-force-projector.ts +6 -2
  105. package/src/graph/projector/graph-hierarchical-projector.ts +1 -1
  106. package/src/graph/projector/graph-lattice-projector.ts +86 -0
  107. package/src/graph/projector/graph-plexus-projector.test.ts +102 -0
  108. package/src/graph/projector/graph-plexus-projector.ts +309 -0
  109. package/src/graph/projector/graph-projector.ts +22 -2
  110. package/src/graph/projector/graph-radial-projector.ts +30 -3
  111. package/src/graph/projector/graph-relational-projector.ts +1 -1
  112. package/src/graph/projector/graph-swarm-projector.ts +373 -0
  113. package/src/graph/projector/index.ts +5 -0
  114. package/src/graph/projector/projector.ts +12 -3
  115. package/src/graph/renderer/graph-renderer.ts +289 -31
  116. package/src/graph/renderer/index.ts +1 -0
  117. package/src/graph/renderer/labels.ts +138 -0
  118. package/src/graph/renderer/renderer.ts +15 -4
  119. package/src/graph/types.ts +14 -0
  120. package/src/stories/experimental.stories.tsx +446 -0
  121. package/src/stories/hooks.stories.tsx +8 -3
  122. package/src/testing/data.ts +9 -9
  123. package/src/testing/hooks.ts +2 -3
  124. package/src/testing/model.ts +3 -3
  125. package/styles/graph.css +52 -3
@@ -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, layoutRadial, updateNode } from './graph-radial-projector';
12
11
 
@@ -27,6 +26,7 @@ export class GraphHierarchicalProjector<
27
26
  });
28
27
 
29
28
  this.mergeData(graph);
29
+ this.emitUpdate('topology');
30
30
  const selected = this.selection?.getSelectedIds()[0];
31
31
  if (selected) {
32
32
  const node = this.layout.graph.nodes.find((node) => node.id === selected);
@@ -0,0 +1,86 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { type Graph } from '@dxos/graph';
6
+ import { log } from '@dxos/log';
7
+
8
+ import { type GraphLayoutNode } from '../types';
9
+ import { GraphRadialProjector, type GraphRadialProjectorOptions, updateNode } from './graph-radial-projector';
10
+
11
+ export type GraphLatticeProjectorOptions = GraphRadialProjectorOptions & {
12
+ /** Reserved space around the lattice (screen pixels). */
13
+ margin?: number;
14
+ /** Node radius used by `renderNode` consumers. Defaults to the force-graph default (6) so animations across variants don't resize nodes. */
15
+ radius?: number;
16
+ /** Sort key for cells; defaults to the node label / id. Same-typename nodes naturally cluster. */
17
+ sortBy?: (node: GraphLayoutNode) => string;
18
+ };
19
+
20
+ /**
21
+ * Lays out nodes as a square-as-possible grid that fits the container.
22
+ * Extends `GraphRadialProjector` to inherit the tween (`updateNode` + `animate`),
23
+ * so switching to / from this layout animates each node from its current
24
+ * position to the grid cell — and the initial mount can also "grow" from
25
+ * existing positions if seeded with a prior projector's layout.
26
+ */
27
+ export class GraphLatticeProjector<
28
+ NodeData = any,
29
+ Options extends GraphLatticeProjectorOptions = any,
30
+ > extends GraphRadialProjector<NodeData, Options> {
31
+ protected override onUpdate(graph?: Graph.Any) {
32
+ log('onUpdate', { graph: { nodes: graph?.nodes.length, edges: graph?.edges.length } });
33
+ this.mergeData(graph);
34
+ // Compute layout (assigns sx/sy/tx/ty + initial x/y) BEFORE emitting topology so the
35
+ // renderer's first render uses meaningful positions. animate() then tweens to target.
36
+ this.doLatticeLayout();
37
+ this.emitUpdate('topology');
38
+ this.animate();
39
+ }
40
+
41
+ private doLatticeLayout() {
42
+ if (!this.context.size) {
43
+ return;
44
+ }
45
+
46
+ const nodes = this.layout.graph.nodes;
47
+ const count = nodes.length;
48
+ if (!count) {
49
+ return;
50
+ }
51
+
52
+ const sortBy = this.options.sortBy ?? ((n: GraphLayoutNode) => (n.data as any)?.label ?? n.id);
53
+ nodes.sort((a, b) => sortBy(a).localeCompare(sortBy(b)));
54
+
55
+ // Columns ≈ √N so the grid stays as square as possible.
56
+ const columns = Math.max(1, Math.ceil(Math.sqrt(count)));
57
+ const rows = Math.ceil(count / columns);
58
+
59
+ const margin = this.options.margin ?? 16;
60
+ const { width, height } = this.context.size;
61
+ const innerW = Math.max(0, width - 2 * margin);
62
+ const innerH = Math.max(0, height - 2 * margin);
63
+ // Default radius matches the force-graph default (6) so cross-variant animations
64
+ // tween position only, not size. Consumers can pass a smaller `radius` for a
65
+ // denser matrix look.
66
+ const r = this.options.radius ?? 6;
67
+ // Cell size sets the spacing between nodes. Cap at a small multiple of `r`
68
+ // so the lattice stays tight rather than ballooning to fill the container;
69
+ // wide enough that edges crossing between non-adjacent cells remain visible
70
+ // in the gaps between nodes.
71
+ const fit = Math.min(innerW / columns, innerH / rows);
72
+ const cellSize = Math.max(0, Math.min(fit, r * 6));
73
+
74
+ // Center the lattice (SVG viewBox is centered at origin in `<SVG.Root>`).
75
+ const gridW = cellSize * columns;
76
+ const gridH = cellSize * rows;
77
+ const offsetX = -gridW / 2 + cellSize / 2;
78
+ const offsetY = -gridH / 2 + cellSize / 2;
79
+
80
+ nodes.forEach((node, i) => {
81
+ const tx = offsetX + (i % columns) * cellSize;
82
+ const ty = offsetY + Math.floor(i / columns) * cellSize;
83
+ updateNode(node, [tx, ty], r);
84
+ });
85
+ }
86
+ }
@@ -0,0 +1,102 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { describe, test } from 'vitest';
6
+
7
+ import { type Graph } from '@dxos/graph';
8
+
9
+ import { SVGContext } from '../../hooks';
10
+ import { type GraphLayoutEdge } from '../types';
11
+ import {
12
+ GraphPlexusProjector,
13
+ PLEXUS_NODE_TYPE_FOCUS,
14
+ PLEXUS_NODE_TYPE_OBJECT,
15
+ PLEXUS_NODE_TYPE_RELATION,
16
+ type PlexusRelation,
17
+ } from './graph-plexus-projector';
18
+
19
+ const makeContext = () => {
20
+ const context = new SVGContext({});
21
+ context.setSize({ width: 800, height: 600 });
22
+ return context;
23
+ };
24
+
25
+ // Mirrors plugin-explorer's relationOf: each relation/ref gets separate nodes for the outgoing
26
+ // (focus is source, `→`) and incoming (focus is target, `←`) directions.
27
+ const relationOf = (edge: GraphLayoutEdge, focusId: string): PlexusRelation | undefined => {
28
+ const outgoing = edge.source.id === focusId;
29
+ const incoming = edge.target.id === focusId;
30
+ if (!outgoing && !incoming) {
31
+ return undefined;
32
+ }
33
+ const direction = outgoing ? 'out' : 'in';
34
+ const arrow = outgoing ? '→' : '←';
35
+ if (edge.type === 'relation') {
36
+ return { key: `relation:${direction}:HasRelationship`, label: `HasRelationship ${arrow}` };
37
+ }
38
+ if (edge.type === 'ref') {
39
+ const property = (edge.data as any)?.property ?? 'references';
40
+ return { key: `ref:${direction}:${property}`, label: `${property} ${arrow}` };
41
+ }
42
+ return undefined;
43
+ };
44
+
45
+ const graph: Graph.Any = {
46
+ nodes: [{ id: 'p1' }, { id: 'org' }, { id: 'p2' }, { id: 'p3' }, { id: 'p4' }, { id: 'other' }] as any,
47
+ edges: [
48
+ // Outgoing ref from focus → grouped under "organization →".
49
+ { id: 'e1', type: 'ref', source: 'p1', target: 'org', data: { property: 'organization' } },
50
+ // Outgoing relations from focus → grouped under "HasRelationship →".
51
+ { id: 'e2', type: 'relation', source: 'p1', target: 'p2', data: {} },
52
+ { id: 'e3', type: 'relation', source: 'p1', target: 'p3', data: {} },
53
+ // Incoming relation to focus → separate "HasRelationship ←" node.
54
+ { id: 'e4', type: 'relation', source: 'p4', target: 'p1', data: {} },
55
+ // Edge NOT incident to focus → ignored.
56
+ { id: 'e5', type: 'ref', source: 'other', target: 'org', data: { property: 'organization' } },
57
+ ] as any,
58
+ };
59
+
60
+ describe('GraphPlexusProjector', () => {
61
+ test('fans the focus neighbourhood out by relation and direction', ({ expect }) => {
62
+ const projector = new GraphPlexusProjector(makeContext(), { focus: 'p1', relationOf });
63
+ projector.updateData(graph);
64
+
65
+ const nodes = projector.layout.graph.nodes;
66
+ const byType = (type: string) => nodes.filter((node) => node.type === type);
67
+
68
+ // Exactly one focus node.
69
+ const focus = byType(PLEXUS_NODE_TYPE_FOCUS);
70
+ expect(focus).toHaveLength(1);
71
+ expect(focus[0].id).toBe('p1');
72
+ expect(focus[0].x).toBe(0);
73
+ expect(focus[0].y).toBe(0);
74
+
75
+ // Three relation nodes: outgoing relation, incoming relation, outgoing ref.
76
+ const relations = byType(PLEXUS_NODE_TYPE_RELATION);
77
+ expect(relations.map((node) => node.label).sort()).toEqual([
78
+ 'HasRelationship ←',
79
+ 'HasRelationship →',
80
+ 'organization →',
81
+ ]);
82
+
83
+ // Four object leaves (org, p2, p3 outgoing; p4 incoming); the non-incident edge is excluded.
84
+ const objects = byType(PLEXUS_NODE_TYPE_OBJECT);
85
+ expect(objects.map((node) => node.id).sort()).toEqual(['org', 'p2', 'p3', 'p4']);
86
+ expect(nodes.find((node) => node.id === 'other')).toBeUndefined();
87
+
88
+ // Hierarchy edges: focus→relation (3) + relation→object (4) = 7.
89
+ const edges = projector.layout.graph.edges;
90
+ expect(edges).toHaveLength(7);
91
+ expect(edges.every((edge) => edge.type === 'hierarchy')).toBe(true);
92
+ });
93
+
94
+ test('degrades to a ring when the focus is absent', ({ expect }) => {
95
+ const projector = new GraphPlexusProjector(makeContext(), { focus: 'missing', relationOf });
96
+ projector.updateData(graph);
97
+
98
+ // All nodes laid out, no relation structure.
99
+ expect(projector.layout.graph.nodes).toHaveLength(graph.nodes.length);
100
+ expect(projector.layout.graph.edges).toHaveLength(0);
101
+ });
102
+ });
@@ -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 & {};
@@ -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 & {
@@ -31,10 +30,17 @@ export class GraphRadialProjector<
31
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
 
@@ -27,6 +26,7 @@ export class GraphRelationalProjector<
27
26
  });
28
27
 
29
28
  this.mergeData(graph);
29
+ this.emitUpdate('topology');
30
30
  const selected = this.selection?.getSelectedIds()[0];
31
31
  if (selected) {
32
32
  const node = this.layout.graph.nodes.find((node) => node.id === selected);