@dxos/plugin-explorer 0.8.4-main.fcfe5033a5 → 0.8.4-staging.60fe92afc8

package/src/components/Lattice/Lattice.tsx

@@ -0,0 +1,182 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { select } from 'd3';
+import React, { useEffect, useMemo, useRef } from 'react';
+
+import { Obj } from '@dxos/echo';
+import { type SpaceGraphNode } from '@dxos/schema';
+
+import { getNodeFillForObject } from '../../util/node-color';
+import { useContainerSize } from '../Tree/layout/useContainerSize';
+import { type TreeNode } from '../Tree/types';
+
+const TRANSITION_MS = 350;
+
+export type LatticeProps = {
+  /** Object nodes from the space graph (typically `model.graph.nodes` filtered to `type === 'object'`). */
+  nodes: SpaceGraphNode[];
+  /** Padding (in screen pixels) reserved around the lattice. */
+  padding?: number;
+  /** Mirrors the hover preview contract used by the other variants. */
+  onNodeHover?: (node: TreeNode<Obj.Unknown> | null, event?: MouseEvent) => void;
+};
+
+type LatticeCell = {
+  id: string;
+  label: string;
+  typename: string;
+  object: Obj.Unknown;
+};
+
+/**
+ * Renders objects as an SVG lattice that fits the container without scrolling.
+ * Each object is a rounded rect, colored by typename via the shared hue-hash used by every
+ * other variant. Cells are sorted by typename then label so objects of the same type cluster.
+ * Hover dispatches the standard preview event — there is no rendered label.
+ */
+export const Lattice = ({ nodes, padding = 16, onNodeHover }: LatticeProps) => {
+  const svgRef = useRef<SVGSVGElement | null>(null);
+  const { setRef, width, height } = useContainerSize();
+
+  const cells = useMemo<LatticeCell[]>(() => {
+    return nodes
+      .map((node): LatticeCell | undefined => {
+        const object = node.data?.object;
+        if (!object) {
+          return undefined;
+        }
+        const label = node.data?.label ?? Obj.getLabel(object) ?? node.id;
+        const typename = Obj.getTypename(object) ?? '(untyped)';
+        return { id: node.id, label, typename, object };
+      })
+      .filter((cell): cell is LatticeCell => cell !== undefined)
+      .sort((a, b) => a.typename.localeCompare(b.typename) || a.label.localeCompare(b.label));
+  }, [nodes]);
+
+  // Stable hover ref so the effect doesn't rebind handlers on every render.
+  const handleHoverRef = useRef<LatticeProps['onNodeHover']>(undefined);
+  handleHoverRef.current = onNodeHover;
+
+  useEffect(() => {
+    if (!svgRef.current || !width || !height) {
+      return;
+    }
+    renderLattice(svgRef.current, cells, {
+      width,
+      height,
+      padding,
+      onNodeHover: (n, e) => handleHoverRef.current?.(n, e),
+    });
+    // Clear any pinned preview when the lattice unmounts or re-renders, so the
+    // shared hover target doesn't keep pointing at a cell that no longer exists.
+    return () => {
+      handleHoverRef.current?.(null);
+    };
+  }, [cells, width, height, padding]);
+
+  return (
+    <div ref={setRef} className='dx-expander relative'>
+      {width > 0 && height > 0 && (
+        <svg
+          ref={svgRef}
+          xmlns='http://www.w3.org/2000/svg'
+          width={width}
+          height={height}
+          viewBox={`0 0 ${width} ${height}`}
+        />
+      )}
+    </div>
+  );
+};
+
+type RenderOptions = {
+  width: number;
+  height: number;
+  padding: number;
+  onNodeHover: (node: TreeNode<Obj.Unknown> | null, event?: MouseEvent) => void;
+};
+
+const renderLattice = (svgElement: SVGSVGElement, cells: LatticeCell[], options: RenderOptions) => {
+  const { width, height, padding, onNodeHover } = options;
+  const svg = select(svgElement);
+
+  if (!cells.length) {
+    onNodeHover(null);
+    svg.selectAll('g.dx-lattice-root').remove();
+    return;
+  }
+
+  // Columns ≈ √N so the grid stays as square as possible.
+  const count = cells.length;
+  const columns = Math.max(1, Math.ceil(Math.sqrt(count)));
+  const rows = Math.ceil(count / columns);
+
+  // Derive a cell size that fits both axes after reserving padding around the whole lattice.
+  const innerW = Math.max(0, width - 2 * padding);
+  const innerH = Math.max(0, height - 2 * padding);
+  const cellSize = Math.max(0, Math.min(innerW / columns, innerH / rows));
+  // Leave a little gutter between cells; the rect occupies the inner area.
+  const gutter = Math.max(2, cellSize * 0.12);
+  const rectSize = Math.max(0, cellSize - gutter);
+  const radius = Math.max(2, rectSize * 0.18);
+
+  // Center the lattice in the container.
+  const gridW = cellSize * columns;
+  const gridH = cellSize * rows;
+  const offsetX = (width - gridW) / 2;
+  const offsetY = (height - gridH) / 2;
+
+  const g = svg
+    .selectAll<SVGGElement, null>('g.dx-lattice-root')
+    .data([null])
+    .join('g')
+    .classed('dx-lattice-root', true);
+
+  type Positioned = LatticeCell & { x: number; y: number };
+  const positioned: Positioned[] = cells.map((cell, i) => ({
+    ...cell,
+    x: offsetX + (i % columns) * cellSize + gutter / 2,
+    y: offsetY + Math.floor(i / columns) * cellSize + gutter / 2,
+  }));
+
+  const node = g
+    .selectAll<SVGGElement, Positioned>('g.dx-lattice-cell')
+    .data(positioned, (d) => d.id)
+    .join(
+      (enter) => {
+        const ge = enter.append('g').classed('dx-lattice-cell', true).attr('opacity', 0);
+        ge.append('rect').style('cursor', 'pointer');
+        return ge;
+      },
+      (update) => update,
+      (exit) =>
+        exit
+          .each(function () {
+            select(this).interrupt();
+          })
+          .transition()
+          .duration(TRANSITION_MS)
+          .attr('opacity', 0)
+          .remove(),
+    );
+
+  node
+    .transition()
+    .duration(TRANSITION_MS)
+    .attr('opacity', 1)
+    .attr('transform', (d) => `translate(${d.x},${d.y})`);
+
+  node
+    .select<SVGRectElement>('rect')
+    .attr('width', rectSize)
+    .attr('height', rectSize)
+    .attr('rx', radius)
+    .attr('ry', radius)
+    .style('fill', (d) => getNodeFillForObject(d.object))
+    .on('pointerenter', (event: MouseEvent, d: Positioned) =>
+      onNodeHover({ id: d.id, label: d.label, data: d.object }, event),
+    )
+    .on('pointerleave', () => onNodeHover(null));
+};

package/src/components/Lattice/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './Lattice';

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

@@ -0,0 +1,144 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React, { useEffect, useMemo, useState } from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Query } from '@dxos/echo';
+import { ClientPlugin, initializeIdentity } from '@dxos/plugin-client/testing';
+import { corePlugins } from '@dxos/plugin-testing';
+import { random } from '@dxos/random';
+import { useSpaces } from '@dxos/react-client/echo';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { type ValueGenerator } from '@dxos/schema/testing';
+import { HasConnection, Organization, Person } from '@dxos/types';
+
+import { buildOrgHierarchy, connectionsToEdges, generateConnectedOrgs } from '../../testing';
+import { Tree, type TreeComponentProps } from './Tree';
+import { type TreeNode } from './types';
+
+const generator = random as any as ValueGenerator;
+
+random.seed(42);
+
+const DefaultStory = ({ variant = 'edge', tension }: { variant?: TreeComponentProps['variant']; tension?: number }) => {
+  const [space] = useSpaces();
+  const [{ data, edges }, setState] = useState<{ data?: TreeNode; edges: TreeComponentProps['edges'] }>({
+    data: undefined,
+    edges: [],
+  });
+  const [hovered, setHovered] = useState<TreeNode | null>(null);
+
+  useEffect(() => {
+    if (!space) {
+      return;
+    }
+    let cancelled = false;
+    void (async () => {
+      const orgs = await space.db.query(Query.type(Organization.Organization)).run();
+      if (cancelled || !orgs.length) {
+        return;
+      }
+      const connections = await space.db.query(Query.type(HasConnection.HasConnection)).run();
+      if (cancelled) {
+        return;
+      }
+      setState({
+        data: buildOrgHierarchy(orgs as any),
+        edges: connectionsToEdges(connections as any),
+      });
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [space]);
+
+  const slots = useMemo<TreeComponentProps['slots']>(
+    () => ({
+      node: 'fill-neutral-700 dark:fill-neutral-300',
+      path: 'stroke-orange-400/40 dark:stroke-orange-500/40',
+      text: 'fill-neutral-700 dark:fill-neutral-200 text-xs',
+    }),
+    [],
+  );
+
+  if (!space || !data) {
+    return <Loading data={{ space: !!space, data: !!data }} />;
+  }
+
+  return (
+    <div className='relative flex h-full w-full'>
+      <Tree
+        data={data}
+        edges={edges}
+        variant={variant}
+        slots={slots}
+        onNodeHover={setHovered}
+        // Pass-through; only `edge` variant uses `edges`/`onNodeHover`.
+      />
+      {hovered && (
+        <div className='pointer-events-none absolute left-2 top-2 rounded bg-neutral-900/80 px-2 py-1 text-xs text-white dark:bg-white/80 dark:text-neutral-900'>
+          {hovered.label ?? hovered.id}
+        </div>
+      )}
+    </div>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-explorer/components/EdgeBundling',
+  component: Tree as any,
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'fullscreen' }),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        ClientPlugin({
+          types: [Organization.Organization, Person.Person, HasConnection.HasConnection],
+          onClientInitialized: ({ client }) =>
+            Effect.gen(function* () {
+              const { personalSpace } = yield* initializeIdentity(client);
+              yield* Effect.promise(() =>
+                generateConnectedOrgs(personalSpace, generator, {
+                  organizationCount: 16,
+                  personCount: 24,
+                  connectionCount: 22,
+                }),
+              );
+              yield* Effect.promise(() => personalSpace.db.flush({ indexes: true }));
+            }),
+        }),
+      ],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    variant: 'edge',
+  },
+};
+
+export const Tidy: Story = {
+  args: {
+    variant: 'tidy',
+  },
+};
+
+export const Radial: Story = {
+  args: {
+    variant: 'radial',
+  },
+};

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

@@ -3,76 +3,55 @@
 //
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { useEffect, useState } from 'react';
+import React, { useMemo } from 'react';
 
-import { invariant } from '@dxos/invariant';
 import { random } from '@dxos/random';
-import { useClient } from '@dxos/react-client';
-import { type ClientRepeatedComponentProps, ClientRepeater } from '@dxos/react-client/testing';
-import { withLayout, withTheme } from '@dxos/react-ui/testing';
-import { withRegistry } from '@dxos/storybook-utils';
+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';
-
-// TODO(burdon): Storybook for Graph/Tree/Plot (generics); incl. GraphModel.
-// TODO(burdon): Type for all Explorer components (Space, Object, Query, etc.) incl.
+import { treeTypeToTreeNode } from './types';
 
 random.seed(1);
 
-type ComponentProps = ClientRepeatedComponentProps & { type?: TreeComponentProps<any>['variant'] };
-
-const Component = ({ type }: ComponentProps) => {
-  const client = useClient();
-  const space = client.spaces.get()[0];
-  invariant(space, 'Tree story requires at least one space');
-  const [object, setObject] = useState<TreeType>();
-  useEffect(() => {
-    setTimeout(() => {
-      const tree = space.db.add(TreeModel.create());
-      setObject(tree);
-    });
-  }, []);
+type StoryArgs = Pick<TreeComponentProps, 'variant'>;
 
-  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 = {
+const meta: Meta<StoryArgs> = {
   title: 'plugins/plugin-explorer/components/Tree',
-  component: Tree as any,
   render: DefaultStory,
-  decorators: [withRegistry, withTheme(), withLayout()],
+  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,111 +2,80 @@
 // Copyright 2023 DXOS.org
 //
 
-import { RegistryContext } from '@effect-atom/atom-react';
-import React, { useContext, 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 registry = useContext(RegistryContext);
-  const [model] = useAsyncState(
-    async () => (space ? new SpaceGraphModel(registry).open(space.db) : undefined),
-    [space, selected, registry],
-  );
-
-  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 className='grow' 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,5 @@
 //
 
 export * from './Tree';
+export * from './layout';
+export { type TreeNode, treeTypeToTreeNode } from './types';