@dxos/plugin-explorer 0.8.4-main.fd6878d → 0.9.0

package/src/components/Lattice/Lattice.stories.tsx

@@ -0,0 +1,104 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom, useAtomValue } from '@effect-atom/atom-react';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React, { useMemo } from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Type, View } from '@dxos/echo';
+import { ClientPlugin, initializeIdentity } from '@dxos/plugin-client/testing';
+import { PreviewPlugin } from '@dxos/plugin-preview/testing';
+import { StorybookPlugin, 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 SpaceGraphNode, ViewModel } from '@dxos/schema';
+import { type ValueGenerator, createObjectFactory, createRelationFactory } from '@dxos/schema/testing';
+import { HasRelationship, Organization, Person, Pipeline } from '@dxos/types';
+
+import { useGraphModel } from '#hooks';
+import { Graph } from '#types';
+
+import { Lattice } from './Lattice';
+
+const generator = random as any as ValueGenerator;
+
+random.seed(7);
+
+const EMPTY_ATOM = Atom.make<{ nodes: SpaceGraphNode[] }>({ nodes: [] });
+
+const DefaultStory = () => {
+  const [space] = useSpaces();
+  const model = useGraphModel(space?.db);
+  const graphSnapshot = useAtomValue((model?.graphAtom ?? EMPTY_ATOM) as typeof EMPTY_ATOM);
+  const nodes = useMemo(() => graphSnapshot.nodes.filter((node) => node.type === 'object'), [graphSnapshot]);
+
+  if (!space || !model) {
+    return <Loading data={{ space: !!space, model: !!model }} />;
+  }
+
+  return <Lattice nodes={nodes} />;
+};
+
+const meta: Meta<typeof DefaultStory> = {
+  title: 'plugins/plugin-explorer/components/Lattice',
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'fullscreen' }),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        StorybookPlugin({}),
+        ClientPlugin({
+          types: [
+            Graph.Graph,
+            View.View,
+            HasRelationship.HasRelationship,
+            Organization.Organization,
+            Pipeline.Pipeline,
+            Person.Person,
+          ],
+          onClientInitialized: ({ client }) =>
+            Effect.gen(function* () {
+              const { personalSpace } = yield* initializeIdentity(client);
+              yield* Effect.promise(() =>
+                createObjectFactory(
+                  personalSpace.db,
+                  generator,
+                )([
+                  { type: Organization.Organization, count: 20 },
+                  { type: Person.Person, count: 30 },
+                  { type: Pipeline.Pipeline, count: 10 },
+                ]),
+              );
+              yield* Effect.promise(() =>
+                createRelationFactory(
+                  personalSpace.db,
+                  generator,
+                )([{ type: HasRelationship.HasRelationship, count: 20, data: { kind: 'friend' } }]),
+              );
+              const { view } = yield* Effect.promise(() =>
+                ViewModel.makeFromDatabase({ db: personalSpace.db, typename: Type.getTypename(Graph.Graph) }),
+              );
+              personalSpace.db.add(Graph.make({ name: 'Test', view }));
+              yield* Effect.promise(() => personalSpace.db.flush({ indexes: true }));
+            }),
+        }),
+        PreviewPlugin(),
+      ],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof DefaultStory>;
+
+export const Default: Story = {};

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

@@ -2,68 +2,56 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos-theme';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
 
-import { type Meta } from '@storybook/react-vite';
-import React, { type FC, useEffect, useState } from 'react';
-
-import { faker } from '@dxos/random';
-import { useClient } from '@dxos/react-client';
-import { type ClientRepeatedComponentProps, ClientRepeater } from '@dxos/react-client/testing';
-import { withLayout, withTheme } from '@dxos/storybook-utils';
+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';
-
-// 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';
 
-faker.seed(1);
+random.seed(1);
 
-const Story: FC<ClientRepeatedComponentProps & { type?: TreeComponentProps<any>['variant'] }> = ({ type }) => {
-  const client = useClient();
-  const space = client.spaces.default;
-  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} />;
 };
 
-export const Tidy = {
-  args: {
-    type: 'tidy',
+const meta: Meta<StoryArgs> = {
+  title: 'plugins/plugin-explorer/components/Tree',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
   },
 };
 
-export const Radial = {
+export default meta;
+
+type Story = StoryObj<StoryArgs>;
+
+export const Tidy: Story = {
   args: {
-    type: 'radial',
+    variant: 'tidy',
   },
 };
 
-export const Edge = {
+export const Radial: Story = {
   args: {
-    type: 'edge',
+    variant: 'radial',
   },
 };
 
-const meta: Meta = {
-  title: 'plugins/plugin-explorer/Tree',
-  component: Tree,
-  render: () => <ClientRepeater component={Story} types={[TreeType]} createSpace />,
-  decorators: [withTheme, withLayout({ fullscreen: true })],
-  parameters: {
-    layout: 'fullscreen',
+export const Edge: Story = {
+  args: {
+    variant: 'edge',
   },
 };
-
-export default meta;