@dxos/plugin-explorer 0.8.2-main.fbd8ed0 → 0.8.2-staging.42af850

package/src/components/Graph/D3ForceGraph.tsx

@@ -0,0 +1,101 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { type FC, useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { getTypename } from '@dxos/echo-schema';
+import { SelectionModel } from '@dxos/graph';
+import { type ThemedClassName } from '@dxos/react-ui';
+import {
+  type GraphController,
+  GraphForceProjector,
+  type GraphLayoutNode,
+  type GraphProps,
+  SVG,
+  type SVGContext,
+} from '@dxos/react-ui-graph';
+import { getHashColor } from '@dxos/react-ui-theme';
+import { type SpaceGraphNode, type SpaceGraphModel, type SpaceGraphEdge } from '@dxos/schema';
+
+import '@dxos/react-ui-graph/styles/graph.css';
+
+export type D3ForceGraphProps = ThemedClassName<
+  {
+    model?: SpaceGraphModel;
+    match?: RegExp;
+    selection?: SelectionModel;
+    grid?: boolean;
+  } & Pick<GraphProps, 'drag'>
+>;
+
+export const D3ForceGraph: FC<D3ForceGraphProps> = ({ classNames, model, selection: _selection, grid, ...props }) => {
+  const context = useRef<SVGContext>(null);
+  const projector = useMemo<GraphForceProjector | undefined>(() => {
+    if (context.current) {
+      return new GraphForceProjector(context.current, {
+        attributes: {
+          linkForce: (edge) => {
+            // TODO(burdon): Check type (currently assumes Employee property).
+            // Edge shouldn't contribute to force if it's not active.
+            return edge.data?.object?.active !== false;
+          },
+        },
+        forces: {
+          point: {
+            strength: 0.01,
+          },
+        },
+      });
+    }
+  }, [context.current]);
+
+  const graph = useRef<GraphController>(null);
+  const selection = useMemo(() => _selection ?? new SelectionModel(), [_selection]);
+  useEffect(() => graph.current?.repaint(), [selection.selected.value]);
+
+  const handleSelect = useCallback<NonNullable<GraphProps['onSelect']>>(
+    (node) => {
+      if (selection.contains(node.id)) {
+        selection.remove(node.id);
+      } else {
+        selection.add(node.id);
+      }
+    },
+    [selection],
+  );
+
+  return (
+    <SVG.Root ref={context} classNames={classNames}>
+      <SVG.Markers />
+      {grid && <SVG.Grid axis />}
+      <SVG.Zoom extent={[1 / 2, 2]}>
+        <SVG.Graph<SpaceGraphNode, SpaceGraphEdge>
+          {...props}
+          ref={graph}
+          model={model}
+          projector={projector}
+          labels={{
+            text: (node) => {
+              return node.data?.data.label ?? node.id;
+            },
+          }}
+          attributes={{
+            node: (node: GraphLayoutNode<SpaceGraphNode>) => {
+              const obj = node.data?.data.object;
+              return {
+                data: {
+                  color: getHashColor(obj && getTypename(obj))?.color,
+                },
+                classes: {
+                  'dx-selected': selection.contains(node.id),
+                },
+              };
+            },
+          }}
+          onSelect={handleSelect}
+        />
+      </SVG.Zoom>
+    </SVG.Root>
+  );
+};

package/src/components/Graph/ForceGraph.stories.tsx

@@ -0,0 +1,64 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import '@dxos-theme';
+
+import { type Meta } from '@storybook/react';
+import React, { useEffect, useState } from 'react';
+
+import { faker } from '@dxos/random';
+import { useClient } from '@dxos/react-client';
+import { live } from '@dxos/react-client/echo';
+import { type Space } from '@dxos/react-client/echo';
+import { withClientProvider } from '@dxos/react-client/testing';
+import { DataType } from '@dxos/schema';
+import { type ValueGenerator } from '@dxos/schema/testing';
+import { withLayout, withTheme, render } from '@dxos/storybook-utils';
+
+import { ForceGraph } from './ForceGraph';
+import { generate } from './testing';
+import { useGraphModel } from '../../hooks';
+import { ViewType } from '../../types';
+
+const generator = faker as any as ValueGenerator;
+
+faker.seed(1);
+
+const DefaultStory = () => {
+  const client = useClient();
+  const [space, setSpace] = useState<Space>();
+  const [view, setView] = useState<ViewType>();
+  useEffect(() => {
+    const space = client.spaces.default;
+    void generate(space, generator);
+    const view = space.db.add(live(ViewType, { name: '', type: '' }));
+    setSpace(space);
+    setView(view);
+  }, []);
+
+  const model = useGraphModel(space);
+  if (!model || !space || !view) {
+    return null;
+  }
+
+  return <ForceGraph model={model} />;
+};
+
+const meta: Meta = {
+  title: 'plugins/plugin-explorer/ForceGraph',
+  component: ForceGraph,
+  render: render(DefaultStory),
+  decorators: [
+    withClientProvider({
+      createSpace: true,
+      types: [ViewType, DataType.HasRelationship, DataType.Organization, DataType.Project, DataType.Person],
+    }),
+    withTheme,
+    withLayout({ fullscreen: true }),
+  ],
+};
+
+export default meta;
+
+export const Default = {};

package/src/components/Graph/{Graph.tsx → ForceGraph.tsx}

@@ -3,30 +3,24 @@
 //
 
 import { forceLink, forceManyBody } from 'd3';
-import ForceGraph from 'force-graph';
+import NativeForceGraph from 'force-graph';
 import React, { type FC, useEffect, useRef } from 'react';
 import { useResizeDetector } from 'react-resize-detector';
 
-import { type Space } from '@dxos/client/echo';
 import { filterObjectsSync, type SearchResult } from '@dxos/plugin-search';
-import { useAsyncState } from '@dxos/react-ui';
+import { type SpaceGraphModel } from '@dxos/schema';
 
-import { SpaceGraphModel } from './graph-model';
+import { GraphAdapter } from './adapter';
 
-export type GraphProps = {
-  space: Space;
+export type ForceGraphProps = {
+  model?: SpaceGraphModel;
   match?: RegExp;
 };
 
-export const Graph: FC<GraphProps> = ({ space, match }) => {
+export const ForceGraph: FC<ForceGraphProps> = ({ model, match }) => {
   const { ref, width, height } = useResizeDetector({ refreshRate: 200 });
   const rootRef = useRef<HTMLDivElement>(null);
-  const forceGraph = useRef<ForceGraph>();
-
-  const [model] = useAsyncState(
-    async () => (space ? new SpaceGraphModel({ schema: true }).open(space) : undefined),
-    [space],
-  );
+  const forceGraph = useRef<NativeForceGraph>();
 
   const filteredRef = useRef<SearchResult[]>();
   filteredRef.current = filterObjectsSync(model?.objects ?? [], match);
@@ -35,17 +29,14 @@ export const Graph: FC<GraphProps> = ({ space, match }) => {
     if (rootRef.current) {
       // https://github.com/vasturiano/force-graph
       // https://github.com/vasturiano/3d-force-graph
-      forceGraph.current = new ForceGraph(rootRef.current)
+      forceGraph.current = new NativeForceGraph(rootRef.current)
+        // https://github.com/vasturiano/force-graph?tab=readme-ov-file#node-styling
         .nodeRelSize(6)
-        .nodeLabel((node: any) => {
-          if (node.type === 'schema') {
-            return node.data.typename;
-          }
-
-          return node.id;
-        })
+        .nodeLabel((node: any) => (node.type === 'schema' ? node.data.typename : node.data.label ?? node.id))
         .nodeAutoColorBy((node: any) => (node.type === 'schema' ? 'schema' : node.data.typename))
-        .linkColor(() => 'rgba(255,255,255,0.25)');
+
+        // https://github.com/vasturiano/force-graph?tab=readme-ov-file#link-styling
+        .linkAutoColorBy((link: any) => link.type);
     }
 
     return () => {
@@ -56,6 +47,7 @@ export const Graph: FC<GraphProps> = ({ space, match }) => {
 
   useEffect(() => {
     if (forceGraph.current && width && height && model) {
+      // https://github.com/vasturiano/force-graph?tab=readme-ov-file#container-layout
       forceGraph.current
         .pauseAnimation()
         .width(width)
@@ -63,17 +55,18 @@ export const Graph: FC<GraphProps> = ({ space, match }) => {
         .onEngineStop(() => {
           handleZoomToFit();
         })
+        .onNodeClick((node: any) => {
+          forceGraph.current?.emitParticle(node);
+        })
 
         // https://github.com/vasturiano/force-graph?tab=readme-ov-file#force-engine-d3-force-configuration
         // .d3Force('center', forceCenter().strength(0.9))
         .d3Force('link', forceLink().distance(160).strength(0.5))
         .d3Force('charge', forceManyBody().strength(-30))
-        // .d3AlphaDecay(0.0228)
-        // .d3VelocityDecay(0.4)
 
-        .graphData(model.graph)
+        .graphData(new GraphAdapter(model))
         .warmupTicks(100)
-        .cooldownTime(1000)
+        .cooldownTime(1_000)
         .resumeAnimation();
     }
   }, [model, width, height]);

package/src/components/Graph/adapter.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Graph } from '@dxos/graph';
+
+export type GraphNode = {
+  id?: string;
+};
+
+export type GraphLink = {
+  source?: string;
+  target?: string;
+};
+
+export type GraphData = {
+  nodes: GraphNode[];
+  links: GraphLink[];
+};
+
+export class GraphAdapter implements GraphData {
+  private readonly _nodes: GraphNode[] = [];
+  private readonly _links: GraphLink[] = [];
+
+  constructor(private readonly graph: Graph) {
+    this._nodes = graph.nodes.map((node) => ({
+      id: node.id,
+      type: node.type,
+      data: node.data,
+    }));
+
+    this._links = graph.edges.map((edge) => ({
+      type: edge.type,
+      source: edge.source,
+      target: edge.target,
+      data: edge.data,
+    }));
+  }
+
+  get nodes() {
+    return this._nodes;
+  }
+
+  get links() {
+    return this._links;
+  }
+}

package/src/components/Graph/index.ts

@@ -2,6 +2,5 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './graph-model';
-
-export * from './Graph';
+export * from './D3ForceGraph';
+export * from './ForceGraph';

package/src/components/Graph/testing.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type AnyLiveObject, live, type Space } from '@dxos/client/echo';
+import { Query, RelationSourceId, RelationTargetId } from '@dxos/echo-schema';
+import { DataType } from '@dxos/schema';
+import { createObjectFactory, type ValueGenerator, type TypeSpec } from '@dxos/schema/testing';
+import { range } from '@dxos/util';
+
+const getObject = (objects: AnyLiveObject[]) => objects[Math.floor(Math.random() * objects.length)];
+
+const defaultTypes: TypeSpec[] = [
+  { type: DataType.Organization, count: 5 },
+  { type: DataType.Project, count: 5 },
+  { type: DataType.Person, count: 10 },
+];
+
+export type GenerateOptions = {
+  spec?: TypeSpec[];
+  relations?: {
+    count: number;
+    kind: string;
+  };
+};
+
+const defaultRelations: GenerateOptions['relations'] = { count: 10, kind: 'friend' };
+
+/**
+ * @deprecated Use @dxos/schema.
+ */
+export const generate = async (
+  space: Space,
+  generator: ValueGenerator,
+  { spec = defaultTypes, relations = defaultRelations }: GenerateOptions = {},
+) => {
+  const createObjects = createObjectFactory(space.db, generator);
+  await createObjects(spec);
+
+  // Add relations between objects.
+  const { objects: contacts } = await space.db.query(Query.type(DataType.Person)).run();
+  for (const _ of range(relations.count)) {
+    const source = getObject(contacts);
+    const target = getObject(contacts);
+    if (source.id === target.id) {
+      continue;
+    }
+
+    space.db.add(
+      live(DataType.HasRelationship, {
+        kind: relations.kind,
+        [RelationSourceId]: source,
+        [RelationTargetId]: target,
+      }),
+    );
+  }
+};

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

@@ -7,13 +7,13 @@ import '@dxos-theme';
 import { type Meta } from '@storybook/react';
 import React, { type FC, useEffect, useState } from 'react';
 
-import { TreeType, Tree as TreeModel } from '@dxos/plugin-outliner/types';
 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 { Tree, type TreeComponentProps } from './Tree';
+import { TreeType, Tree as TreeModel } from './types';
 
 // TODO(burdon): Storybook for Graph/Tree/Plot (generics); incl. GraphModel.
 // TODO(burdon): Type for all Explorer components (Space, Object, Query, etc.) incl.

package/src/components/Tree/Tree.tsx

@@ -2,16 +2,15 @@
 // Copyright 2023 DXOS.org
 //
 
-import React, { useEffect, useState } from 'react';
-import { useResizeDetector } from 'react-resize-detector';
+import React, { useEffect, useRef, useState } from 'react';
 
 import { type Space } from '@dxos/client/echo';
-import { createSvgContext, SVG, SVGRoot } from '@dxos/gem-core';
 import { useAsyncState } from '@dxos/react-ui';
+import { SVG, type SVGContext } from '@dxos/react-ui-graph';
+import { SpaceGraphModel } from '@dxos/schema';
 
 import { HierarchicalEdgeBundling, RadialTree, TidyTree } from './layout';
 import { mapGraphToTreeData, type TreeNode } from './types';
-import { SpaceGraphModel } from '../Graph';
 
 // TODO(burdon): Create dge bundling graph using d3.hierarchy.
 // https://observablehq.com/@d3/hierarchical-edge-bundling?intent=fork
@@ -63,10 +62,7 @@ export type TreeComponentProps<N = unknown> = {
 
 // TODO(burdon): Label accessor.
 export const Tree = <N,>({ space, selected, variant = 'tidy', onNodeClick }: TreeComponentProps<N>) => {
-  const [model] = useAsyncState(
-    async () => (space ? new SpaceGraphModel().open(space, selected) : undefined),
-    [space, selected],
-  );
+  const [model] = useAsyncState(async () => (space ? new SpaceGraphModel().open(space) : undefined), [space, selected]);
 
   const [tree, setTree] = useState<TreeNode>();
   useEffect(() => {
@@ -76,11 +72,11 @@ export const Tree = <N,>({ space, selected, variant = 'tidy', onNodeClick }: Tre
     }, true);
   }, [model]);
 
-  const context = createSvgContext();
-  const { ref, width = 0, height = 0 } = useResizeDetector();
+  const context = useRef<SVGContext>(null);
 
   useEffect(() => {
-    if (width && height) {
+    if (context.current) {
+      const { width, height } = context.current.size!;
       const size = Math.min(width, height);
       const radius = size * 0.4;
       const options = {
@@ -98,17 +94,14 @@ export const Tree = <N,>({ space, selected, variant = 'tidy', onNodeClick }: Tre
 
       if (tree) {
         const renderer = renderers.get(variant);
-        renderer?.(context.ref.current!, tree, options);
+        renderer?.(context.current!.svg, tree, options);
       }
     }
-  }, [tree, width, height]);
+  }, [context.current, tree]);
 
-  // TODO(burdon): Provider should expand.
   return (
-    <div ref={ref} className='flex grow overflow-hidden' onClick={() => onNodeClick?.()}>
-      <SVGRoot context={context}>
-        <SVG />
-      </SVGRoot>
+    <div onClick={() => onNodeClick?.()}>
+      <SVG.Root ref={context} />
     </div>
   );
 };

package/src/components/Tree/testing/generator.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { ObjectId } from '@dxos/echo-schema';
+import { range } from '@dxos/util';
+
+import { Tree, type TreeNodeType } from '../types';
+
+type NumberOrNumberArray = number | number[];
+
+const random = (min: number, max: number) => Math.floor(Math.random() * (max - min + 1)) + min;
+
+/**
+ * Create hierarchical tree.
+ */
+export const createTree = (spec: NumberOrNumberArray[] = [], createText?: () => string): Tree => {
+  const tree = new Tree();
+  tree.root.data = { text: 'root' };
+
+  const createNodes = (parent: TreeNodeType, spec: NumberOrNumberArray = 0): TreeNodeType[] => {
+    const count = Array.isArray(spec) ? random(spec[0], spec[1]) : spec;
+    return range(count, (i) => ({
+      id: ObjectId.random(),
+      children: [],
+      data: {
+        text: createText?.() ?? [parent.data.text, i + 1].join('.'),
+      },
+    }));
+  };
+
+  const createChildNodes = (parent: TreeNodeType, [count = 0, ...rest]: NumberOrNumberArray[]): TreeNodeType => {
+    const nodes = createNodes(parent, count);
+    nodes.forEach((n) => tree.addNode(parent, n));
+    if (rest.length) {
+      for (const node of nodes) {
+        createChildNodes(node, rest);
+      }
+    }
+
+    return parent;
+  };
+
+  createChildNodes(tree.root, spec);
+  return tree;
+};

package/src/components/Tree/testing/index.ts

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

package/src/components/Tree/types/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './tree';
+export * from './types';

package/src/components/Tree/types/tree.test.ts

@@ -0,0 +1,133 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { live, makeRef } from '@dxos/live-object';
+import { faker } from '@dxos/random';
+import { DataType } from '@dxos/schema';
+
+import { type Tree } from './tree';
+import { createTree } from '../testing';
+
+faker.seed(0);
+
+const print = (tree: Tree) => {
+  let count = 0;
+  tree.tranverse((node, i) => {
+    console.log(''.padStart(i * 2, ' '), node.data);
+    count++;
+  });
+
+  return count;
+};
+
+describe('tree', () => {
+  test('tree', ({ expect }) => {
+    {
+      const tree = createTree();
+      let count = 0;
+      tree.tranverse(() => {
+        count++;
+      });
+      expect(count).to.eq(tree.size);
+      expect(count).to.eq(1);
+    }
+    {
+      const tree = createTree([10]);
+      let count = 0;
+      tree.tranverse(() => {
+        count++;
+      });
+      expect(count).to.eq(tree.size);
+      expect(count).to.eq(1 + 10);
+    }
+    {
+      const tree = createTree([10, 3, 1]);
+      let count = 0;
+      tree.tranverse(() => {
+        count++;
+      });
+      expect(count).to.eq(tree.size);
+      expect(count).to.eq(1 + 10 * (1 + 3 * (1 + 1))); // 71
+    }
+  });
+
+  test('tree navigation', ({ expect }) => {
+    const tree = createTree([2, 3, 1]);
+    expect(tree.getParent(tree.root)).to.be.null;
+
+    const nodes = tree.getChildNodes(tree.root);
+    expect(nodes).to.have.length(2);
+
+    const first = nodes[0];
+    expect(first.children).to.have.length(3);
+    const parent = tree.getParent(first);
+    expect(parent).to.eq(tree.root);
+
+    const [c1, c2, c3] = tree.getChildNodes(first);
+    expect(tree.getParent(c1)).to.eq(first);
+    expect(tree.getParent(c2)).to.eq(first);
+    expect(tree.getParent(c3)).to.eq(first);
+
+    const [g1] = tree.getChildNodes(c1);
+    expect(tree.getParent(g1)).to.eq(c1);
+  });
+
+  /**
+   *  root                       root                        root
+   *   └── 1                      └── 1                       └── 1
+   *       ├── 1.1                    ├── 1.1                     ├── 1.1
+   *       ├── 1.2 <- indent          │   ├── 1.2 <- unindent     ├── 1.2
+   *       ├── 1.3 <- indent          │   └── 1.3                 │   └── 1.3
+   *       ├── 1.4                    ├── 1.4                     ├── 1.4
+   *       └── 1.5                    └── 1.5                     └── 1.5
+   */
+  test('indent and unindent', async ({ expect }) => {
+    const tree = createTree([1, 5]);
+    const parent = tree.getNode(tree.root.children[0]);
+
+    {
+      const count = print(tree);
+      expect(count).to.eq(1 + 1 * (1 + 5));
+    }
+
+    // Indent
+    {
+      const child = tree.getChildNodes(parent);
+      tree.indentNode(child[1]);
+      tree.indentNode(child[2]);
+      expect(parent.children).to.have.length(3);
+      expect(child[0].children).to.have.length(2);
+    }
+
+    {
+      const count = print(tree);
+      expect(count).to.eq(1 + 1 * (1 + 5));
+    }
+
+    // Unindent
+    {
+      const child = tree.getChildNodes(parent);
+      const grandchild = tree.getChildNodes(child[0]);
+      tree.unindentNode(grandchild[0]);
+      expect(grandchild[0].children).to.have.length(1);
+      expect(parent.children).to.have.length(4);
+    }
+
+    {
+      const count = print(tree);
+      expect(count).to.eq(1 + 1 * (1 + 5));
+    }
+  });
+
+  test('task', ({ expect }) => {
+    const task = live(DataType.Task, { text: 'Test task.' });
+    expect(task.text).to.eq('Test task.');
+
+    const tree = createTree();
+    const node = tree.addNode(tree.root);
+    node.ref = makeRef(task);
+  });
+});