@dxos/react-ui-graph 0.8.4-main.84f28bd → 0.8.4-main.8baae0fced

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 (134) 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 +1965 -560
  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 +1965 -560
  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 +9 -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 +20 -11
  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 +9 -5
  23. package/dist/types/src/components/Mesh/Mesh.stories.d.ts.map +1 -1
  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 +8 -4
  27. package/dist/types/src/components/SVG/Root.d.ts.map +1 -1
  28. package/dist/types/src/components/SVG/SVG.d.ts +14 -17
  29. package/dist/types/src/components/SVG/SVG.d.ts.map +1 -1
  30. package/dist/types/src/components/SVG/Svg.stories.d.ts +11 -9
  31. package/dist/types/src/components/SVG/Svg.stories.d.ts.map +1 -1
  32. package/dist/types/src/components/SVG/Zoom.d.ts.map +1 -1
  33. package/dist/types/src/fx/fx.stories.d.ts +16 -15
  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 +60 -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 +1 -1
  42. package/dist/types/src/graph/projector/graph-drag.d.ts.map +1 -1
  43. package/dist/types/src/graph/projector/graph-force-projector.d.ts +2 -2
  44. package/dist/types/src/graph/projector/graph-force-projector.d.ts.map +1 -1
  45. package/dist/types/src/graph/projector/graph-forces.d.ts.map +1 -1
  46. package/dist/types/src/graph/projector/graph-hierarchical-projector.d.ts +2 -2
  47. package/dist/types/src/graph/projector/graph-hierarchical-projector.d.ts.map +1 -1
  48. package/dist/types/src/graph/projector/graph-lattice-projector.d.ts +23 -0
  49. package/dist/types/src/graph/projector/graph-lattice-projector.d.ts.map +1 -0
  50. package/dist/types/src/graph/projector/graph-projector.d.ts +4 -4
  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 +8 -2
  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 +2 -2
  55. package/dist/types/src/graph/projector/graph-relational-projector.d.ts.map +1 -1
  56. package/dist/types/src/graph/projector/index.d.ts +3 -0
  57. package/dist/types/src/graph/projector/index.d.ts.map +1 -1
  58. package/dist/types/src/graph/projector/projector.d.ts +10 -1
  59. package/dist/types/src/graph/projector/projector.d.ts.map +1 -1
  60. package/dist/types/src/graph/renderer/bullets.d.ts.map +1 -1
  61. package/dist/types/src/graph/renderer/graph-renderer.d.ts +22 -2
  62. package/dist/types/src/graph/renderer/graph-renderer.d.ts.map +1 -1
  63. package/dist/types/src/graph/renderer/renderer.d.ts +12 -1
  64. package/dist/types/src/graph/renderer/renderer.d.ts.map +1 -1
  65. package/dist/types/src/graph/types.d.ts +15 -1
  66. package/dist/types/src/graph/types.d.ts.map +1 -1
  67. package/dist/types/src/hooks/useGrid.d.ts.map +1 -1
  68. package/dist/types/src/hooks/useStateRef.d.ts.map +1 -1
  69. package/dist/types/src/hooks/useSvgContext.d.ts.map +1 -1
  70. package/dist/types/src/hooks/useZoom.d.ts.map +1 -1
  71. package/dist/types/src/stories/hooks.stories.d.ts +14 -9
  72. package/dist/types/src/stories/hooks.stories.d.ts.map +1 -1
  73. package/dist/types/src/testing/data.d.ts +5 -5
  74. package/dist/types/src/testing/data.d.ts.map +1 -1
  75. package/dist/types/src/testing/hooks.d.ts +2 -16
  76. package/dist/types/src/testing/hooks.d.ts.map +1 -1
  77. package/dist/types/src/testing/model.d.ts +4 -8
  78. package/dist/types/src/testing/model.d.ts.map +1 -1
  79. package/dist/types/src/util/events.d.ts.map +1 -1
  80. package/dist/types/src/util/fraction.d.ts +1 -1
  81. package/dist/types/src/util/fraction.d.ts.map +1 -1
  82. package/dist/types/src/util/index.d.ts +2 -2
  83. package/dist/types/src/util/index.d.ts.map +1 -1
  84. package/dist/types/src/util/points.d.ts.map +1 -1
  85. package/dist/types/src/util/scale.d.ts.map +1 -1
  86. package/dist/types/src/util/screen.d.ts +1 -1
  87. package/dist/types/src/util/screen.d.ts.map +1 -1
  88. package/dist/types/src/util/vector.d.ts +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 +33 -35
  92. package/src/components/Graph/Graph.stories.tsx +73 -69
  93. package/src/components/Graph/Graph.tsx +60 -25
  94. package/src/components/Mesh/Mesh.stories.tsx +16 -13
  95. package/src/components/Mesh/Mesh.tsx +44 -36
  96. package/src/components/SVG/Grid.tsx +2 -2
  97. package/src/components/SVG/Markers.tsx +1 -1
  98. package/src/components/SVG/Root.tsx +41 -9
  99. package/src/components/SVG/SVG.tsx +13 -4
  100. package/src/components/SVG/Svg.stories.tsx +23 -19
  101. package/src/components/SVG/Zoom.tsx +1 -1
  102. package/src/fx/fx.stories.tsx +18 -15
  103. package/src/graph/projector/graph-bundle-projector.ts +210 -0
  104. package/src/graph/projector/graph-cluster-projector.ts +325 -0
  105. package/src/graph/projector/graph-drag.ts +1 -1
  106. package/src/graph/projector/graph-force-projector.ts +8 -4
  107. package/src/graph/projector/graph-forces.ts +1 -1
  108. package/src/graph/projector/graph-hierarchical-projector.ts +5 -4
  109. package/src/graph/projector/graph-lattice-projector.ts +86 -0
  110. package/src/graph/projector/graph-projector.ts +12 -5
  111. package/src/graph/projector/graph-radial-projector.ts +33 -5
  112. package/src/graph/projector/graph-relational-projector.ts +5 -4
  113. package/src/graph/projector/index.ts +3 -0
  114. package/src/graph/projector/projector.ts +13 -4
  115. package/src/graph/renderer/bullets.ts +1 -1
  116. package/src/graph/renderer/graph-renderer.ts +178 -32
  117. package/src/graph/renderer/renderer.ts +16 -5
  118. package/src/graph/types.ts +15 -1
  119. package/src/hooks/useStateRef.ts +1 -1
  120. package/src/hooks/useZoom.ts +1 -1
  121. package/src/stories/hooks.stories.tsx +49 -37
  122. package/src/testing/data.ts +14 -14
  123. package/src/testing/hooks.ts +5 -5
  124. package/src/testing/model.ts +6 -6
  125. package/src/util/fraction.ts +1 -1
  126. package/src/util/index.ts +2 -2
  127. package/src/util/screen.test.ts +1 -1
  128. package/src/util/screen.ts +1 -1
  129. package/src/util/vector.ts +1 -1
  130. package/styles/graph.css +341 -43
  131. package/dist/lib/browser/chunk-4C5Z5DAE.mjs +0 -979
  132. package/dist/lib/browser/chunk-4C5Z5DAE.mjs.map +0 -7
  133. package/dist/lib/node-esm/chunk-AK6HNA4R.mjs +0 -981
  134. package/dist/lib/node-esm/chunk-AK6HNA4R.mjs.map +0 -7
@@ -2,7 +2,7 @@
2
2
  // Copyright 2024 DXOS.org
3
3
  //
4
4
 
5
- import { geoPath, select, type GeoStream } from 'd3';
5
+ import { type GeoStream, geoPath, select } from 'd3';
6
6
  import { useEffect } from 'react';
7
7
  import { feature, mesh } from 'topojson-client';
8
8
  import { type GeometryCollection, type GeometryObject, type Objects, type Topology } from 'topojson-specification';
@@ -20,43 +20,51 @@ export const Mesh = ({ radius = 16, value = 0.5 }: MeshProps) => {
20
20
  const { svg, size } = useSvgContext();
21
21
 
22
22
  useEffect(() => {
23
- if (size) {
24
- // TODO(burdon): Resize doesn't trigger.
25
- const topology = hexTopology(size, radius, value);
26
- const projection = hexProjection(radius);
27
- const path = geoPath().projection(projection);
28
-
29
- select(svg)
30
- .append('g')
31
- .attr('class', 'hexagon')
32
- .selectAll('path')
33
- .data(topology.objects.hexagons.geometries)
34
- .enter()
35
- .append('path')
36
- .attr('d', (d) => path(feature(topology, d)))
37
- .attr('class', (d) => ((d.properties as Custom)?.fill ? 'fill' : null));
38
- // .on('mousedown', mousedown)
39
- // .on('mousemove', mousemove)
40
- // .on('mouseup', mouseup);
41
-
42
- select(svg).append('path').datum(mesh(topology, topology.objects.hexagons)).attr('class', 'mesh').attr('d', path);
43
-
44
- const redraw = (border: any) => {
45
- border.attr(
46
- 'd',
47
- path(
48
- mesh(
49
- topology,
50
- topology.objects.hexagons,
51
- (a, b) => (a.properties as Custom).fill !== (b.properties as Custom).fill,
52
- ),
23
+ if (!size) {
24
+ return;
25
+ }
26
+
27
+ const topology = hexTopology(size, radius, value);
28
+ const projection = hexProjection(radius);
29
+ const path = geoPath().projection(projection);
30
+
31
+ // Replace the previous render: idempotent join on a single keyed root group, then
32
+ // recreate the inner layers. Without this the effect re-runs (e.g. animating `value`
33
+ // or on resize) appended new groups on top of the old ones instead of replacing them.
34
+ const root = select(svg)
35
+ .selectAll<SVGGElement, null>('g.dx-mesh-root')
36
+ .data([null])
37
+ .join('g')
38
+ .classed('dx-mesh-root', true);
39
+ root.selectAll('*').remove();
40
+
41
+ root
42
+ .append('g')
43
+ .attr('class', 'hexagon')
44
+ .selectAll('path')
45
+ .data(topology.objects.hexagons.geometries)
46
+ .enter()
47
+ .append('path')
48
+ .attr('d', (d) => path(feature(topology, d)))
49
+ .attr('class', (d) => ((d.properties as Custom)?.fill ? 'fill' : null));
50
+
51
+ root.append('path').datum(mesh(topology, topology.objects.hexagons)).attr('class', 'mesh').attr('d', path);
52
+
53
+ const redraw = (border: any) => {
54
+ border.attr(
55
+ 'd',
56
+ path(
57
+ mesh(
58
+ topology,
59
+ topology.objects.hexagons,
60
+ (a, b) => (a.properties as Custom).fill !== (b.properties as Custom).fill,
53
61
  ),
54
- );
55
- };
62
+ ),
63
+ );
64
+ };
56
65
 
57
- select(svg).append('path').attr('class', 'border').call(redraw);
58
- }
59
- }, [svg, size, value]);
66
+ root.append('path').attr('class', 'border').call(redraw);
67
+ }, [svg, size, value, radius]);
60
68
 
61
69
  return null;
62
70
  };
@@ -5,9 +5,9 @@
5
5
  import React from 'react';
6
6
 
7
7
  import { type ThemedClassName } from '@dxos/react-ui';
8
- import { mx } from '@dxos/react-ui-theme';
8
+ import { mx } from '@dxos/ui-theme';
9
9
 
10
- import { useGrid, type GridOptions } from '../../hooks';
10
+ import { type GridOptions, useGrid } from '../../hooks';
11
11
 
12
12
  export type GridProps = ThemedClassName<GridOptions>;
13
13
 
@@ -16,7 +16,7 @@ export type MarkersProps = {
16
16
  * SVG markers wrapper.
17
17
  */
18
18
  export const Markers = ({ arrowSize, className }: MarkersProps) => {
19
- const ref = useRef();
19
+ const ref = useRef(null);
20
20
  useEffect(() => {
21
21
  select(ref.current).call(createMarkers({ arrowSize }));
22
22
  }, [ref]);
@@ -3,26 +3,58 @@
3
3
  //
4
4
 
5
5
  import { select } from 'd3';
6
- import React, { forwardRef, type PropsWithChildren, useEffect, useMemo, useImperativeHandle } from 'react';
7
- import { useResizeDetector } from 'react-resize-detector';
6
+ import React, {
7
+ type ComponentPropsWithoutRef,
8
+ type PropsWithChildren,
9
+ forwardRef,
10
+ useEffect,
11
+ useImperativeHandle,
12
+ useMemo,
13
+ useState,
14
+ } from 'react';
8
15
 
9
16
  import { type ThemedClassName } from '@dxos/react-ui';
10
- import { mx } from '@dxos/react-ui-theme';
17
+ import { composableProps, mx } from '@dxos/ui-theme';
11
18
 
12
19
  import { SVGContext, type SVGContextOptions, SVGContextProvider } from '../../hooks';
13
20
 
14
- export type RootProps = ThemedClassName<PropsWithChildren<SVGContextOptions>>;
21
+ export type RootProps = ThemedClassName<PropsWithChildren<SVGContextOptions & ComponentPropsWithoutRef<'div'>>>;
15
22
 
16
23
  /**
17
24
  * Makes the SVG context available to child nodes.
18
25
  * Automatically resizes the SVG element, which expands to fit the container.
26
+ *
27
+ * NOTE: Uses `ResizeObserver` directly rather than `react-resize-detector` — the latter's
28
+ * `useResizeDetector` was flaky in our Storybook environment (sometimes never fired its
29
+ * initial measurement), leaving the SVG stuck at `opacity-0` with no rendered content.
19
30
  */
20
- export const Root = forwardRef<SVGContext, RootProps>(({ classNames, children, ...props }, ref) => {
21
- const { ref: containerRef, width = 0, height = 0 } = useResizeDetector({ refreshRate: 200 });
31
+ export const Root = forwardRef<SVGContext, RootProps>(({ children, scale, centered, ...props }, ref) => {
32
+ const [container, setContainer] = useState<HTMLDivElement | null>(null);
33
+ const [size, setSize] = useState<{ width: number; height: number }>({ width: 0, height: 0 });
34
+
35
+ useEffect(() => {
36
+ if (!container) {
37
+ return;
38
+ }
39
+ const rect = container.getBoundingClientRect();
40
+ setSize({ width: rect.width, height: rect.height });
41
+ const observer = new ResizeObserver((entries) => {
42
+ const entry = entries[0];
43
+ if (!entry) {
44
+ return;
45
+ }
46
+ const { width, height } = entry.contentRect;
47
+ setSize((prev) => (prev.width === width && prev.height === height ? prev : { width, height }));
48
+ });
49
+ observer.observe(container);
50
+ return () => observer.disconnect();
51
+ }, [container]);
52
+
53
+ const { width, height } = size;
22
54
 
23
55
  const context = useMemo<SVGContext>(() => {
24
- return new SVGContext(props);
25
- }, [props.scale, props.centered]);
56
+ return new SVGContext({ scale, centered });
57
+ }, [scale, centered]);
26
58
 
27
59
  useImperativeHandle(ref, () => context, [context]);
28
60
 
@@ -41,7 +73,7 @@ export const Root = forwardRef<SVGContext, RootProps>(({ classNames, children, .
41
73
 
42
74
  return (
43
75
  <SVGContextProvider value={context}>
44
- <div ref={containerRef} className={mx('grid grow overflow-hidden', classNames)}>
76
+ <div {...composableProps(props, { classNames: 'dx-expander' })} ref={setContainer}>
45
77
  <svg
46
78
  xmlns='http://www.w3.org/2000/svg'
47
79
  ref={context.ref}
@@ -6,16 +6,25 @@ import { type PropsWithChildren } from 'react';
6
6
 
7
7
  import { type ThemedClassName } from '@dxos/react-ui';
8
8
 
9
+ import { Graph, type GraphProps as SVGGraphProps } from '../Graph';
10
+ import { Mesh, type MeshProps as SVGMeshProps } from '../Mesh';
9
11
  import { Grid, type GridProps as SVGGridProps } from './Grid';
10
12
  import { Markers, type MarkersProps as SVGMarkersProps } from './Markers';
11
13
  import { Root, type RootProps as SVGRootProps } from './Root';
12
- import { Zoom, type ZoomProps as SVGZoomProps } from './Zoom';
13
- import { Graph, type GraphProps as SVGGraphProps } from '../Graph';
14
- import { Mesh, type MeshProps as SVGMeshProps } from '../Mesh';
14
+ import { type ZoomProps as SVGZoomProps, Zoom } from './Zoom';
15
15
 
16
16
  export type SVGProps = PropsWithChildren<ThemedClassName>;
17
17
 
18
- export const SVG = {
18
+ type SVG = {
19
+ Root: typeof Root;
20
+ Grid: typeof Grid;
21
+ Markers: typeof Markers;
22
+ Mesh: typeof Mesh;
23
+ Zoom: typeof Zoom;
24
+ Graph: typeof Graph;
25
+ };
26
+
27
+ export const SVG: SVG = {
19
28
  Root,
20
29
  Grid,
21
30
  Markers,
@@ -2,32 +2,21 @@
2
2
  // Copyright 2022 DXOS.org
3
3
  //
4
4
 
5
- import '@dxos-theme';
5
+ import '../../../styles/graph.css';
6
6
 
7
+ import { type Meta, type StoryObj } from '@storybook/react-vite';
7
8
  import React, { useRef } from 'react';
8
9
 
9
- import { type Meta, withLayout, withTheme } from '@dxos/storybook-utils';
10
+ import { withLayout, withTheme } from '@dxos/react-ui/testing';
10
11
 
12
+ import { type SVGContext, useGrid, useZoom } from '../../hooks';
11
13
  import { SVG } from './SVG';
12
- import { useGrid, useZoom, type SVGContext } from '../../hooks';
13
-
14
- import '../../../styles/graph.css';
15
14
 
16
15
  type ComponentProps = {
17
16
  grid?: boolean;
18
17
  zoom?: boolean;
19
18
  };
20
19
 
21
- const DefaultStory = (props: ComponentProps) => {
22
- const context = useRef<SVGContext>(null);
23
-
24
- return (
25
- <SVG.Root ref={context}>
26
- <Component {...props} />
27
- </SVG.Root>
28
- );
29
- };
30
-
31
20
  const Component = (options: ComponentProps) => {
32
21
  const grid = useGrid({ visible: options.grid, axis: true });
33
22
  const zoom = useZoom({ enabled: options.zoom });
@@ -42,15 +31,30 @@ const Component = (options: ComponentProps) => {
42
31
  );
43
32
  };
44
33
 
45
- const meta: Meta<typeof Component> = {
34
+ const DefaultStory = (props: ComponentProps) => {
35
+ const context = useRef<SVGContext>(null);
36
+
37
+ return (
38
+ <SVG.Root ref={context}>
39
+ <Component {...props} />
40
+ </SVG.Root>
41
+ );
42
+ };
43
+
44
+ const meta = {
46
45
  title: 'ui/react-ui-graph/SVGRoot',
47
46
  render: DefaultStory,
48
- decorators: [withTheme, withLayout({ fullscreen: true })],
49
- };
47
+ decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
48
+ parameters: {
49
+ layout: 'fullscreen',
50
+ },
51
+ } satisfies Meta<typeof DefaultStory>;
50
52
 
51
53
  export default meta;
52
54
 
53
- export const Default = {
55
+ type Story = StoryObj<typeof meta>;
56
+
57
+ export const Default: Story = {
54
58
  args: {
55
59
  grid: true,
56
60
  },
@@ -4,7 +4,7 @@
4
4
 
5
5
  import React, { type ReactNode, memo, useMemo } from 'react';
6
6
 
7
- import { useZoom, type ZoomExtent } from '../../hooks';
7
+ import { type ZoomExtent, useZoom } from '../../hooks';
8
8
 
9
9
  export type ZoomProps = {
10
10
  extent?: ZoomExtent;
@@ -2,20 +2,18 @@
2
2
  // Copyright 2025 DXOS.org
3
3
  //
4
4
 
5
- import '@dxos-theme';
5
+ import '../../styles/graph.css';
6
6
 
7
- import { type Meta } from '@storybook/react-vite';
7
+ import { type Meta, type StoryObj } from '@storybook/react-vite';
8
8
  import { select } from 'd3';
9
9
  import React, { type FC, useEffect, useMemo, useRef } from 'react';
10
10
 
11
- import { withLayout, withTheme } from '@dxos/storybook-utils';
11
+ import { withLayout, withTheme } from '@dxos/react-ui/testing';
12
12
 
13
- import { Pulsar } from './pulsar';
14
13
  import { SVG } from '../components';
15
14
  import { useGrid, useZoom } from '../hooks';
16
15
  import { type D3Callable } from '../util';
17
-
18
- import '../../styles/graph.css';
16
+ import { Pulsar } from './pulsar';
19
17
 
20
18
  type Datum = {
21
19
  x: number;
@@ -23,11 +21,11 @@ type Datum = {
23
21
  r: number;
24
22
  };
25
23
 
26
- type StoryProps = {
24
+ type DefaultStoryProps = {
27
25
  count: number;
28
26
  } & Pulsar.Options;
29
27
 
30
- const DefaultStory = (props: StoryProps) => {
28
+ const DefaultStory = (props: DefaultStoryProps) => {
31
29
  return (
32
30
  <SVG.Root>
33
31
  <StoryComponent {...props} />
@@ -35,7 +33,7 @@ const DefaultStory = (props: StoryProps) => {
35
33
  );
36
34
  };
37
35
 
38
- const StoryComponent: FC<StoryProps> = ({ count = 1, ...options }) => {
36
+ const StoryComponent: FC<DefaultStoryProps> = ({ count = 1, ...options }) => {
39
37
  const items = useMemo<Datum[]>(
40
38
  () =>
41
39
  Array.from({ length: count }, () => {
@@ -53,7 +51,7 @@ const StoryComponent: FC<StoryProps> = ({ count = 1, ...options }) => {
53
51
  const grid = useGrid({ axis: true, grid: false });
54
52
  const zoom = useZoom();
55
53
 
56
- const root = useRef<SVGGElement>();
54
+ const root = useRef<SVGGElement>(null);
57
55
  useEffect(() => {
58
56
  select(root.current)
59
57
  .selectAll('g')
@@ -92,21 +90,26 @@ const createNode: D3Callable<SVGGElement, Datum> = (group, classNames, options)
92
90
  });
93
91
  };
94
92
 
95
- const meta: Meta = {
93
+ const meta = {
96
94
  title: 'ui/react-ui-graph/fx',
97
95
  render: DefaultStory,
98
- decorators: [withTheme, withLayout({ fullscreen: true })],
99
- };
96
+ decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
97
+ parameters: {
98
+ layout: 'fullscreen',
99
+ },
100
+ } satisfies Meta<typeof DefaultStory>;
100
101
 
101
102
  export default meta;
102
103
 
103
- export const DefaultPulse = {
104
+ type Story = StoryObj<typeof meta>;
105
+
106
+ export const DefaultPulse: Story = {
104
107
  args: {
105
108
  count: 20,
106
109
  },
107
110
  };
108
111
 
109
- export const RapidPulse = {
112
+ export const RapidPulse: Story = {
110
113
  args: {
111
114
  count: 20,
112
115
  duration: 1_000,
@@ -0,0 +1,210 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { type HierarchyNode, cluster as d3Cluster, curveBundle, hierarchy, lineRadial } 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 { GraphRadialProjector, type GraphRadialProjectorOptions, updateNode } from './graph-radial-projector';
12
+
13
+ export type GraphBundleProjectorOptions = GraphRadialProjectorOptions & {
14
+ /** Reserved space around the bundle (screen pixels). */
15
+ margin?: number;
16
+ /** Radius for leaf nodes. Default 4. */
17
+ leafRadius?: number;
18
+ /**
19
+ * Group key for each node — synthetic intermediate nodes are created per unique key
20
+ * to give the bundling layout a routing point (lowest common ancestor) for edges
21
+ * between leaves in different groups. Return `undefined` to attach the node directly
22
+ * to the root (all such leaves bundle through the root).
23
+ */
24
+ groupOf?: (node: GraphLayoutNode) => string | undefined;
25
+ /** Bundling tension passed to `d3.curveBundle.beta`. 0 = straight chord, 1 = max bundled. */
26
+ tension?: number;
27
+ };
28
+
29
+ const ROOT_ID = '__bundle_root__';
30
+ const GROUP_PREFIX = '__bundle_group__:';
31
+
32
+ /**
33
+ * Cartesian → d3-radial polar. d3 measures angle clockwise from "up" (the -y direction).
34
+ * Inverse of `[cos(a - π/2) * r, sin(a - π/2) * r]`.
35
+ */
36
+ const cartesianToPolar = (x: number, y: number): { angle: number; radius: number } => ({
37
+ angle: Math.atan2(x, -y),
38
+ radius: Math.hypot(x, y),
39
+ });
40
+
41
+ type PolarPoint = { angle: number; radius: number };
42
+
43
+ /**
44
+ * Hierarchical edge bundling — Holten 2006 / d3 observable notebook
45
+ * (https://observablehq.com/@d3/hierarchical-edge-bundling).
46
+ *
47
+ * Synthesizes the same root → group → leaf hierarchy as `GraphClusterProjector`, runs
48
+ * d3.cluster to give every node a polar position, but renders ONLY the leaves
49
+ * (root + groups are routing anchors, not visible nodes). Each data edge is replaced
50
+ * with a curve generated by `lineRadial(curveBundle.beta(tension))` over the polar
51
+ * positions of `source.path(target)` — i.e. the chain of ancestors through the lowest
52
+ * common ancestor.
53
+ *
54
+ * Per-frame `onTickFrame` refreshes the leaf endpoints (first + last point of every
55
+ * path) from current cartesian positions so the curves stay glued to leaves during a
56
+ * cross-variant tween (force → bundle, lattice → bundle). Internal ancestor positions
57
+ * are fixed at d3.cluster's final polar layout, which means during the tween curves
58
+ * route through the destination "pivot points" while the leaf endpoints catch up —
59
+ * visually the bundle "snaps into shape" as the leaves arrive.
60
+ */
61
+ export class GraphBundleProjector<
62
+ NodeData = any,
63
+ Options extends GraphBundleProjectorOptions = any,
64
+ > extends GraphRadialProjector<NodeData, Options> {
65
+ // Per-edge polar point arrays. Points 0 and N-1 are the source / target leaves and are
66
+ // overwritten from current cartesian on every tick; intermediate points stay fixed at
67
+ // their cluster-layout polar coordinates.
68
+ #edgePoints = new Map<string, PolarPoint[]>();
69
+ #lineGen = lineRadial<PolarPoint>()
70
+ .radius((d) => d.radius)
71
+ .angle((d) => d.angle);
72
+
73
+ protected override onUpdate(graph?: Graph.Any) {
74
+ log('onUpdate', { graph: { nodes: graph?.nodes.length, edges: graph?.edges.length } });
75
+ this.mergeData(graph);
76
+ this.doBundleLayout();
77
+ this.emitUpdate('topology');
78
+ this.animate();
79
+ }
80
+
81
+ /**
82
+ * Refresh leaf endpoint polar values from current cartesian so the curve tracks
83
+ * its endpoints during the tween. Internal hierarchy positions stay constant.
84
+ */
85
+ protected override onTickFrame(_t: number): void {
86
+ for (const edge of this.layout.graph.edges) {
87
+ if (edge.type !== 'bundle') {
88
+ continue;
89
+ }
90
+ const points = this.#edgePoints.get(edge.id);
91
+ if (!points || points.length < 2) {
92
+ continue;
93
+ }
94
+ const s = cartesianToPolar(edge.source.x ?? 0, edge.source.y ?? 0);
95
+ const t = cartesianToPolar(edge.target.x ?? 0, edge.target.y ?? 0);
96
+ points[0] = { angle: s.angle, radius: s.radius };
97
+ points[points.length - 1] = { angle: t.angle, radius: t.radius };
98
+ edge.path = this.#lineGen(points) ?? undefined;
99
+ }
100
+ }
101
+
102
+ private doBundleLayout() {
103
+ if (!this.context.size) {
104
+ return;
105
+ }
106
+ const dataNodes = [...this.layout.graph.nodes];
107
+ if (!dataNodes.length) {
108
+ return;
109
+ }
110
+
111
+ const groupOf = this.options.groupOf;
112
+
113
+ // Synthesize root → groups → leaves hierarchy so d3.cluster gives every node
114
+ // (including the routing-only internal ones) a polar coordinate.
115
+ type HierNode = { id: string; parent?: string; node?: GraphLayoutNode<NodeData> };
116
+ const items: HierNode[] = [{ id: ROOT_ID }];
117
+ const groupIds = new Map<string, string>();
118
+ for (const node of dataNodes) {
119
+ const key = groupOf?.(node);
120
+ let parent = ROOT_ID;
121
+ if (key !== undefined) {
122
+ let groupId = groupIds.get(key);
123
+ if (!groupId) {
124
+ groupId = `${GROUP_PREFIX}${key}`;
125
+ groupIds.set(key, groupId);
126
+ items.push({ id: groupId, parent: ROOT_ID });
127
+ }
128
+ parent = groupId;
129
+ }
130
+ items.push({ id: node.id, parent, node });
131
+ }
132
+
133
+ const childrenByParent = new Map<string, HierNode[]>();
134
+ for (const item of items) {
135
+ if (item.parent) {
136
+ const list = childrenByParent.get(item.parent) ?? [];
137
+ list.push(item);
138
+ childrenByParent.set(item.parent, list);
139
+ }
140
+ }
141
+
142
+ const root = hierarchy<HierNode>({ id: ROOT_ID }, (d) => childrenByParent.get(d.id) ?? []);
143
+
144
+ const { width, height } = this.context.size;
145
+ const margin = this.options.margin ?? 120;
146
+ const ringRadius = Math.max(0, Math.min(width, height) / 2 - margin);
147
+
148
+ d3Cluster<HierNode>()
149
+ .size([2 * Math.PI, ringRadius])
150
+ .separation((a: any, b: any) => (a.parent === b.parent ? 1 : 2) / Math.max(1, a.depth))(root);
151
+
152
+ const leafR = this.options.leafRadius ?? 4;
153
+
154
+ // Re-bake the line generator with the configured tension. d3 curve factories return
155
+ // a new curve when `.beta` is called, so this must happen whenever options change.
156
+ const tension = this.options.tension ?? 0.85;
157
+ this.#lineGen = lineRadial<PolarPoint>()
158
+ .curve(curveBundle.beta(tension))
159
+ .radius((d) => d.radius)
160
+ .angle((d) => d.angle);
161
+
162
+ // Index hierarchy nodes by data id for fast lookup when building edge paths.
163
+ const hierById = new Map<string, HierarchyNode<HierNode>>();
164
+ root.each((d) => {
165
+ hierById.set(d.data.id, d);
166
+ });
167
+
168
+ // Position the leaf data nodes (cartesian); internal nodes stay layout-only.
169
+ root.leaves().forEach((d: any) => {
170
+ const angle = d.x;
171
+ const radius = d.y;
172
+ const x = Math.cos(angle - Math.PI / 2) * radius;
173
+ const y = Math.sin(angle - Math.PI / 2) * radius;
174
+ if (d.data.node) {
175
+ updateNode(d.data.node, [x, y], leafR);
176
+ }
177
+ });
178
+ this.layout.graph.nodes = dataNodes;
179
+
180
+ // Build bundle edges. `mergeData` already populated `layout.graph.edges` with data
181
+ // edges referencing the leaf GraphLayoutNodes — keep those references (so node
182
+ // animations & hover wiring continue to work) and enhance each with a routed path
183
+ // through the hierarchy.
184
+ this.#edgePoints.clear();
185
+ const incomingEdges = [...this.layout.graph.edges];
186
+ const bundleEdges: GraphLayoutEdge<NodeData>[] = [];
187
+ for (const edge of incomingEdges) {
188
+ const sourceHier = hierById.get(edge.source.id);
189
+ const targetHier = hierById.get(edge.target.id);
190
+ if (!sourceHier || !targetHier || sourceHier === targetHier) {
191
+ continue;
192
+ }
193
+ // hierarchy.path returns [source, ...up to LCA, ...down to target] (inclusive endpoints).
194
+ const pathNodes = sourceHier.path(targetHier);
195
+ const points: PolarPoint[] = pathNodes.map((n: any) => ({ angle: n.x, radius: n.y }));
196
+ this.#edgePoints.set(edge.id, points);
197
+ bundleEdges.push({
198
+ id: edge.id,
199
+ type: 'bundle',
200
+ source: edge.source,
201
+ target: edge.target,
202
+ data: edge.data,
203
+ });
204
+ }
205
+ this.layout.graph.edges = bundleEdges;
206
+
207
+ // Seed initial paths so the topology emit has correct geometry to enter into the DOM.
208
+ this.onTickFrame(0);
209
+ }
210
+ }