@dxos/plugin-explorer 0.8.4-main.72ec0f3 → 0.8.4-main.765dc60934

package/src/components/Tree/Tree.stories.tsx

@@ -3,73 +3,55 @@
 //
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { useEffect, useState } from 'react';
+import React, { useMemo } from 'react';
 
-import { faker } from '@dxos/random';
-import { useClient } from '@dxos/react-client';
-import { type ClientRepeatedComponentProps, ClientRepeater } from '@dxos/react-client/testing';
-import { withTheme } from '@dxos/react-ui/testing';
+import { random } from '@dxos/random';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
 
+import { createTree } from './testing';
 import { Tree, type TreeComponentProps } from './Tree';
-import { Tree as TreeModel, TreeType } from './types';
+import { treeTypeToTreeNode } from './types';
 
-// TODO(burdon): Storybook for Graph/Tree/Plot (generics); incl. GraphModel.
-// TODO(burdon): Type for all Explorer components (Space, Object, Query, etc.) incl.
+random.seed(1);
 
-faker.seed(1);
+type StoryArgs = Pick<TreeComponentProps, 'variant'>;
 
-type ComponentProps = ClientRepeatedComponentProps & { type?: TreeComponentProps<any>['variant'] };
-
-const Component = ({ type }: ComponentProps) => {
-  const client = useClient();
-  const space = client.spaces.default;
-  const [object, setObject] = useState<TreeType>();
-  useEffect(() => {
-    setTimeout(() => {
-      const tree = space.db.add(TreeModel.create());
-      setObject(tree);
-    });
-  }, []);
-
-  if (!object) {
-    return null;
+const DefaultStory = ({ variant }: StoryArgs) => {
+  const data = useMemo(() => treeTypeToTreeNode(createTree([3, [2, 4], [1, 3]]).tree), []);
+  if (!data) {
+    return <Loading />;
   }
 
-  return <Tree space={space} selected={object?.id} variant={type} />;
+  return <Tree data={data} variant={variant} />;
 };
 
-const DefaultStory = () => {
-  return <ClientRepeater component={Component} types={[TreeType]} createSpace />;
-};
-
-const meta = {
-  title: 'plugins/plugin-explorer/Tree',
-  component: Tree as any,
+const meta: Meta<StoryArgs> = {
+  title: 'plugins/plugin-explorer/components/Tree',
   render: DefaultStory,
-  decorators: [withTheme],
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
   parameters: {
     layout: 'fullscreen',
   },
-} satisfies Meta<typeof DefaultStory>;
+};
 
 export default meta;
 
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<StoryArgs>;
 
 export const Tidy: Story = {
   args: {
-    type: 'tidy',
+    variant: 'tidy',
   },
 };
 
 export const Radial: Story = {
   args: {
-    type: 'radial',
+    variant: 'radial',
   },
 };
 
 export const Edge: Story = {
   args: {
-    type: 'edge',
+    variant: 'edge',
   },
 };

package/src/components/Tree/Tree.tsx

@@ -2,106 +2,80 @@
 // Copyright 2023 DXOS.org
 //
 
-import React, { useEffect, useRef, useState } from 'react';
+import React, { useMemo } from 'react';
 
-import { type Space } from '@dxos/client/echo';
-import { useAsyncState } from '@dxos/react-ui';
-import { SVG, type SVGContext } from '@dxos/react-ui-graph';
-import { SpaceGraphModel } from '@dxos/schema';
+import { type ThemedClassName } from '@dxos/react-ui';
 
-import { HierarchicalEdgeBundling, RadialTree, TidyTree } from './layout';
-import { type TreeNode, mapGraphToTreeData } from './types';
-
-// TODO(burdon): Create dge bundling graph using d3.hierarchy.
-// https://observablehq.com/@d3/hierarchical-edge-bundling?intent=fork
-
-type Renderer = (svg: SVGSVGElement, data: any, options: any) => void;
+import { type BundleEdge, HierarchicalEdgeBundling, RadialTree, TidyTree, type TreeLayoutSlots } from './layout';
+import { type TreeNode } from './types';
 
 export type LayoutVariant = 'tidy' | 'radial' | 'edge';
 
-// TODO(burdon): Remove slots?
-export type TreeLayoutSlots = {
-  node?: string;
-  path?: string;
-  text?: string;
-};
-
-export type TreeOptions = {
-  label: (d: any) => string;
-
-  slots?: TreeLayoutSlots;
-  radius?: number;
-
-  width: number;
-  height: number;
-  margin?: number;
-
-  padding?: number;
-  // Radius of nodes.
-  r?: number;
-};
-
-export const defaultTreeLayoutSlots: TreeLayoutSlots = {
-  node: 'fill-blue-600',
-  path: 'fill-none stroke-blue-400 stroke-[0.5px]',
-  text: 'stroke-[0.5px] stroke-neutral-700 text-xs', // TODO(burdon): Create box instead of halo.
-};
-
-const renderers = new Map<LayoutVariant, Renderer>([
-  ['tidy', TidyTree],
-  ['radial', RadialTree],
-  ['edge', HierarchicalEdgeBundling],
-]);
-
-export type TreeComponentProps<N = unknown> = {
-  space: Space;
-  selected?: string;
+export type TreeComponentProps = ThemedClassName<{
+  data: TreeNode;
+  /** Optional edges for the `edge` variant (hierarchical edge bundling). */
+  edges?: BundleEdge[];
   variant?: LayoutVariant;
-  onNodeClick?: (node?: N) => void;
-};
-
-// TODO(burdon): Label accessor.
-export const Tree = <N,>({ space, selected, variant = 'tidy', onNodeClick }: TreeComponentProps<N>) => {
-  const [model] = useAsyncState(async () => (space ? new SpaceGraphModel().open(space) : undefined), [space, selected]);
-
-  const [tree, setTree] = useState<TreeNode>();
-  useEffect(() => {
-    return model?.subscribe(() => {
-      const tree = mapGraphToTreeData(model);
-      setTree(tree);
-    }, true);
-  }, [model]);
-
-  const context = useRef<SVGContext>(null);
-
-  useEffect(() => {
-    if (context.current?.size) {
-      const { width, height } = context.current.size;
-      const size = Math.min(width, height);
-      const radius = size * 0.4;
-      const options = {
-        // TODO(burdon): Type.
-        label: (d: any) => d.label ?? d.id,
-        width,
-        height,
-        radius,
-        marginLeft: (width - radius * 2) / 2,
-        marginRight: (width - radius * 2) / 2,
-        marginTop: (height - radius * 2) / 2,
-        marginBottom: (height - radius * 2) / 2,
-        slots: defaultTreeLayoutSlots,
-      };
-
-      if (tree) {
-        const renderer = renderers.get(variant);
-        renderer?.(context.current!.svg, tree, options);
-      }
+  label?: (node: TreeNode) => string;
+  slots?: TreeLayoutSlots;
+  initialCollapsed?: Iterable<string>;
+  onNodeClick?: (node: TreeNode) => void;
+  onNodeHover?: (node: TreeNode | null, event?: MouseEvent) => void;
+}>;
+
+/**
+ * Tree visualization wrapping the three layout variants.
+ * - `tidy`   — horizontal tidy tree (collapsible)
+ * - `radial` — radial tree         (collapsible)
+ * - `edge`   — hierarchical edge bundling (`edges` connect leaves)
+ */
+export const Tree = ({
+  classNames,
+  data,
+  edges,
+  variant = 'tidy',
+  label,
+  slots,
+  initialCollapsed,
+  onNodeClick,
+  onNodeHover,
+}: TreeComponentProps) => {
+  return useMemo(() => {
+    switch (variant) {
+      case 'tidy':
+        return (
+          <TidyTree
+            classNames={classNames}
+            data={data}
+            label={label}
+            slots={slots}
+            initialCollapsed={initialCollapsed}
+            onNodeClick={onNodeClick}
+          />
+        );
+      case 'radial':
+        return (
+          <RadialTree
+            classNames={classNames}
+            data={data}
+            label={label}
+            slots={slots}
+            initialCollapsed={initialCollapsed}
+            onNodeClick={onNodeClick}
+            onNodeHover={onNodeHover}
+          />
+        );
+      case 'edge':
+        return (
+          <HierarchicalEdgeBundling
+            classNames={classNames}
+            data={data}
+            edges={edges ?? []}
+            label={label}
+            slots={slots}
+            onNodeHover={onNodeHover}
+          />
+        );
     }
-  }, [context.current, tree]);
-
-  return (
-    <div onClick={() => onNodeClick?.()}>
-      <SVG.Root ref={context} />
-    </div>
-  );
+  }, [variant, classNames, data, edges, label, slots, initialCollapsed, onNodeClick, onNodeHover]);
 };

package/src/components/Tree/index.ts

@@ -3,3 +3,6 @@
 //
 
 export * from './Tree';
+export * from './layout';
+export * from './space-graph-adapter';
+export { type TreeNode, treeTypeToTreeNode } from './types';

package/src/components/Tree/layout/HierarchicalEdgeBundling.tsx

@@ -0,0 +1,277 @@
+//
+// Copyright 2023 DXOS.org
+// Copyright 2024 Observable, Inc.
+//
+
+import { cluster, curveBundle, hierarchy, lineRadial, select } from 'd3';
+import type { HierarchyNode } from 'd3-hierarchy';
+import React, { useEffect, useMemo, useRef } from 'react';
+
+import { type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { type TreeNode } from '../types';
+import { type TreeLayoutSlots, defaultTreeLayoutSlots } from './slots';
+import { useContainerSize } from './useContainerSize';
+
+const TRANSITION_MS = 350;
+
+/** A directed edge between two leaves of the hierarchy, identified by node id. */
+export type BundleEdge = {
+  source: string;
+  target: string;
+  kind?: string;
+};
+
+export type HierarchicalEdgeBundlingProps = ThemedClassName<{
+  /** Hierarchical data; leaves are the connectable entities. */
+  data: TreeNode;
+  /** Edges between leaves (by id). Bundled through the hierarchy. */
+  edges?: BundleEdge[];
+  /** Label accessor for leaf nodes. */
+  label?: (d: TreeNode) => string;
+  /** Padding (in screen pixels) reserved around the radial layout. */
+  padding?: number;
+  /** Bundling tension; 0 = straight, 1 = maximally bundled. */
+  tension?: number;
+  slots?: TreeLayoutSlots;
+  /**
+   * Called when the user hovers a leaf node (with the event so callers can dispatch
+   * `DxAnchorActivate` for previews). Receives `null` on leave.
+   */
+  onNodeHover?: (node: TreeNode | null, event?: MouseEvent) => void;
+}>;
+
+/**
+ * Hierarchical edge bundling.
+ * https://observablehq.com/@d3/hierarchical-edge-bundling?intent=fork
+ *
+ * Leaves are placed on a circle, grouped by their parent in the hierarchy.
+ * Edges between leaves are drawn as bundled curves that route through their lowest common ancestor.
+ */
+export const HierarchicalEdgeBundling = ({
+  classNames,
+  data,
+  edges = [],
+  label = (d) => d.label ?? d.id,
+  padding = 120,
+  tension = 0.85,
+  slots = defaultTreeLayoutSlots,
+  onNodeHover,
+}: HierarchicalEdgeBundlingProps) => {
+  const svgRef = useRef<SVGSVGElement | null>(null);
+  const { setRef, width, height } = useContainerSize();
+
+  const root = useMemo(() => buildBundleHierarchy(data, edges), [data, edges]);
+
+  // Stable hover ref so the effect doesn't rebind handlers on every render.
+  const handleHoverRef = useRef<(node: TreeNode | null, event?: MouseEvent) => void>(() => {});
+  handleHoverRef.current = (node, event) => onNodeHover?.(node, event);
+
+  useEffect(() => {
+    if (!svgRef.current || !width || !height) {
+      return;
+    }
+
+    const radius = Math.max(0, Math.min(width, height) / 2 - padding);
+    renderBundling(svgRef.current, root, {
+      radius,
+      label,
+      slots,
+      tension,
+      onNodeHover: (n, e) => handleHoverRef.current(n, e),
+    });
+  }, [root, width, height, padding, tension, label, slots]);
+
+  return (
+    <div ref={setRef} className={mx('dx-expander relative', classNames)}>
+      {width > 0 && height > 0 && (
+        <svg
+          ref={svgRef}
+          xmlns='http://www.w3.org/2000/svg'
+          width={width}
+          height={height}
+          viewBox={`${-width / 2} ${-height / 2} ${width} ${height}`}
+        />
+      )}
+    </div>
+  );
+};
+
+type BundleHierarchy = HierarchyNode<TreeNode> & {
+  outgoing?: Array<[BundleHierarchy, BundleHierarchy, BundleEdge]>;
+  incoming?: Array<[BundleHierarchy, BundleHierarchy, BundleEdge]>;
+  pathEl?: SVGPathElement | null;
+  text?: SVGTextElement | null;
+};
+
+/**
+ * Build the bundling hierarchy from data + edges.
+ * Edges connect leaves (by id); the cluster layout places leaves on the circle.
+ */
+const buildBundleHierarchy = (data: TreeNode, edges: BundleEdge[]): BundleHierarchy => {
+  const root = hierarchy<TreeNode>(data) as BundleHierarchy;
+  const byId = new Map<string, BundleHierarchy>();
+  for (const node of root.descendants() as BundleHierarchy[]) {
+    byId.set(node.data.id, node);
+    node.outgoing = [];
+    node.incoming = [];
+  }
+
+  for (const edge of edges) {
+    const source = byId.get(edge.source);
+    const target = byId.get(edge.target);
+    if (!source || !target || source === target) {
+      continue;
+    }
+    source.outgoing!.push([source, target, edge]);
+    target.incoming!.push([source, target, edge]);
+  }
+
+  return root;
+};
+
+type RenderOptions = {
+  radius: number;
+  tension: number;
+  label: (d: TreeNode) => string;
+  slots: TreeLayoutSlots;
+  onNodeHover: (node: TreeNode | null, event?: MouseEvent) => void;
+};
+
+const renderBundling = (svgElement: SVGSVGElement, root: BundleHierarchy, options: RenderOptions) => {
+  const { radius, tension, label, slots, onNodeHover } = options;
+  const svg = select(svgElement);
+
+  // Degenerate root (no descendants yet): clear any previously rendered bundle so a stale
+  // graph doesn't linger after the hierarchy empties out, then no-op.
+  if (!root.children?.length) {
+    svg.selectAll('g.dx-bundle-root').remove();
+    return;
+  }
+
+  cluster<TreeNode>().size([2 * Math.PI, radius])(root);
+
+  const g = svg.selectAll<SVGGElement, null>('g.dx-bundle-root').data([null]).join('g').classed('dx-bundle-root', true);
+
+  const linksLayer = g
+    .selectAll<SVGGElement, null>('g.dx-bundle-links')
+    .data([null])
+    .join('g')
+    .classed('dx-bundle-links', true);
+
+  const nodesLayer = g
+    .selectAll<SVGGElement, null>('g.dx-bundle-nodes')
+    .data([null])
+    .join('g')
+    .classed('dx-bundle-nodes', true);
+
+  const line = lineRadial<any>()
+    .curve(curveBundle.beta(tension))
+    .radius((d: any) => d.y)
+    .angle((d: any) => d.x);
+
+  // Each edge: route through the lowest common ancestor via hierarchy.path().
+  const leaves = root.leaves() as BundleHierarchy[];
+  const flatEdges = leaves.flatMap((leaf) => leaf.outgoing ?? []);
+
+  const paths = linksLayer
+    .selectAll<SVGPathElement, any>('path')
+    .data(flatEdges, (d: any) => `${d[0].data.id}->${d[1].data.id}`)
+    .join(
+      (enter) =>
+        enter
+          .append('path')
+          .attr('class', slots.path ?? '')
+          .attr('fill', 'none')
+          .attr('opacity', 0),
+      (update) => update,
+      (exit) =>
+        exit
+          .each(function () {
+            select(this).interrupt();
+          })
+          .transition()
+          .duration(TRANSITION_MS)
+          .attr('opacity', 0)
+          .remove(),
+    );
+
+  paths
+    .each(function (d: any) {
+      d[0].pathEl = this;
+    })
+    .transition()
+    .duration(TRANSITION_MS)
+    .attr('opacity', 1)
+    .attr('d', ([s, t]) => line(s.path(t)));
+
+  // Render leaf labels along the perimeter.
+  const labels = nodesLayer
+    .selectAll<SVGGElement, any>('g.dx-bundle-leaf')
+    .data(leaves, (d: any) => d.data.id)
+    .join(
+      (enter) => {
+        const ge = enter.append('g').classed('dx-bundle-leaf', true).attr('opacity', 0);
+        ge.append('text').attr('dy', '0.32em').attr('paint-order', 'stroke').style('cursor', 'pointer');
+        return ge;
+      },
+      (update) => update,
+      (exit) =>
+        exit
+          .each(function () {
+            select(this).interrupt();
+          })
+          .transition()
+          .duration(TRANSITION_MS)
+          .attr('opacity', 0)
+          .remove(),
+    );
+
+  labels
+    .transition()
+    .duration(TRANSITION_MS)
+    .attr('opacity', 1)
+    .attr('transform', (d: any) => `rotate(${(d.x * 180) / Math.PI - 90}) translate(${d.y},0)`);
+
+  labels
+    .select<SVGTextElement>('text')
+    .attr('class', slots.text ?? '')
+    .attr('x', (d: any) => (d.x < Math.PI ? 6 : -6))
+    .attr('text-anchor', (d: any) => (d.x < Math.PI ? 'start' : 'end'))
+    .attr('transform', (d: any) => (d.x >= Math.PI ? 'rotate(180)' : null))
+    .each(function (d: BundleHierarchy) {
+      d.text = this;
+    })
+    .text((d: any) => label(d.data))
+    .on('pointerenter', function (event: MouseEvent, d: BundleHierarchy) {
+      onNodeHover(d.data, event);
+      hover(linksLayer, leaves, d, true);
+    })
+    .on('pointerleave', function (event: MouseEvent, d: BundleHierarchy) {
+      onNodeHover(null);
+      hover(linksLayer, leaves, d, false);
+    });
+};
+
+const hover = (linksLayer: any, leaves: BundleHierarchy[], focused: BundleHierarchy, on: boolean) => {
+  const outgoing = new Set((focused.outgoing ?? []).map(([, t]) => t));
+  const incoming = new Set((focused.incoming ?? []).map(([s]) => s));
+
+  (linksLayer.selectAll('path') as any)
+    .classed('dx-bundle-out', (d: any) => on && d[0] === focused)
+    .classed('dx-bundle-in', (d: any) => on && d[1] === focused)
+    .classed('dx-bundle-dim', (d: any) => on && d[0] !== focused && d[1] !== focused);
+
+  for (const leaf of leaves) {
+    if (!leaf.text) {
+      continue;
+    }
+    select(leaf.text)
+      .classed('dx-bundle-focused', on && leaf === focused)
+      .classed('dx-bundle-out-text', on && outgoing.has(leaf))
+      .classed('dx-bundle-in-text', on && incoming.has(leaf));
+  }
+};
+
+export default HierarchicalEdgeBundling;