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

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);
+  });
+});

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

@@ -0,0 +1,287 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { Type } from '@dxos/echo';
+import { ObjectId, Ref, Expando } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import { live } from '@dxos/live-object';
+
+// TODO(burdon): Reconcile with @dxos/graph (i.e., common types).
+
+export const TreeNodeType = Schema.Struct({
+  id: ObjectId,
+  children: Schema.mutable(Schema.Array(ObjectId)),
+  data: Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.Any })),
+  ref: Schema.optional(Ref(Expando)), // TODO(burdon): Generic type?
+}).pipe(Schema.mutable);
+
+export interface TreeNodeType extends Schema.Schema.Type<typeof TreeNodeType> {}
+
+export const TreeType = Schema.Struct({
+  root: ObjectId,
+  nodes: Schema.mutable(Schema.Record({ key: ObjectId, value: TreeNodeType })),
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/Tree',
+    version: '0.1.0',
+  }),
+);
+
+export interface TreeType extends Schema.Schema.Type<typeof TreeType> {}
+
+/**
+ * Wrapper object for tree.
+ */
+export class Tree {
+  static create = (): TreeType => {
+    const id = ObjectId.random();
+    return live(TreeType, {
+      root: id,
+      nodes: {
+        [id]: {
+          id,
+          children: [],
+          data: { text: '' }, // TODO(burdon): Generic.
+        },
+      },
+    });
+  };
+
+  private _tree: TreeType;
+
+  constructor(tree?: TreeType) {
+    this._tree = tree ?? Tree.create();
+  }
+
+  get tree() {
+    return this._tree;
+  }
+
+  // TODO(burdon): Make reactive.
+  get size() {
+    return Object.keys(this._tree.nodes).length;
+  }
+
+  get root() {
+    return this.getNode(this._tree.root);
+  }
+
+  //
+  // Traversal
+  //
+
+  /**
+   * Recursively traverse the tree until the callback returns a value.
+   */
+  tranverse<T>(
+    callback: (node: TreeNodeType, depth: number) => T | void,
+    root: ObjectId = this._tree.root,
+    depth = 0,
+  ): T | void {
+    const node = this._tree.nodes[root];
+    const result = callback(node, depth);
+    if (result !== undefined) {
+      return result;
+    }
+
+    for (const childId of node.children) {
+      const result = this.tranverse(callback, childId, depth + 1);
+      if (result !== undefined) {
+        return result;
+      }
+    }
+  }
+
+  getNode(id: ObjectId): TreeNodeType {
+    const node = this._tree.nodes[id];
+    invariant(node);
+    return node;
+  }
+
+  /**
+   * Get the children of a node.
+   */
+  getChildNodes(node: TreeNodeType): Array<TreeNodeType> {
+    return node.children.map((id) => this.getNode(id));
+  }
+
+  /**
+   * Get the parent of a node.
+   */
+  getParent(node: TreeNodeType): TreeNodeType | null {
+    const parent = this.tranverse((n) => {
+      if (n.children.includes(node.id)) {
+        return n;
+      }
+    });
+
+    return parent ?? null;
+  }
+
+  /**
+   * Get the next node in the tree.
+   */
+  getNext(node: TreeNodeType, hierarchical = true): TreeNodeType | undefined {
+    if (hierarchical && node.children.length) {
+      // First child.
+      return this.getChildNodes(node)[0];
+    } else {
+      const parent = this.getParent(node);
+      if (parent) {
+        const idx = this.getChildNodes(parent).findIndex(({ id }) => id === node.id);
+        if (idx < parent.children.length - 1) {
+          // Next sibling.
+          return this.getNode(parent.children[idx + 1]);
+        } else {
+          // Get parent's next sibling.
+          return this.getNext(parent, false);
+        }
+      }
+    }
+  }
+
+  /**
+   * Get the previous node in the tree.
+   */
+  getPrevious(node: TreeNodeType, hierarchical = true): TreeNodeType | undefined {
+    const parent = this.getParent(node)!;
+    const idx = this.getChildNodes(parent).findIndex(({ id }) => id === node.id);
+    if (idx === 0) {
+      if (hierarchical) {
+        return parent;
+      }
+    } else {
+      const previous = this.getNode(parent.children[idx - 1]);
+      if (hierarchical && previous.children.length) {
+        return this.getLastDescendent(previous);
+      }
+
+      return previous;
+    }
+  }
+
+  /**
+   * Get the last descendent of a node.
+   */
+  getLastDescendent(node: TreeNodeType): TreeNodeType | undefined {
+    const children = this.getChildNodes(node);
+    const last = children.length ? children[children.length - 1] : undefined;
+    if (last) {
+      return this.getLastDescendent(last);
+    }
+
+    return node;
+  }
+
+  //
+  // Mutations
+  //
+
+  /**
+   * Clear tree.
+   */
+  clear(): void {
+    const root = this._tree.nodes[this._tree.root];
+    root.children.length = 0;
+    this._tree.nodes = {
+      [root.id]: root,
+    };
+  }
+
+  /**
+   * Add node.
+   */
+  addNode(parent: TreeNodeType, node?: TreeNodeType, index?: number): TreeNodeType {
+    if (!node) {
+      const id = ObjectId.random();
+      node = { id, children: [], data: { text: '' } }; // TODO(burdon): Generic.
+    }
+
+    this._tree.nodes[node.id] = node;
+    parent.children.splice(index ?? parent.children.length, 0, node.id);
+    return node;
+  }
+
+  /**
+   * Delete node.
+   */
+  deleteNode(parent: TreeNodeType, id: ObjectId): TreeNodeType | undefined {
+    const node = this._tree.nodes[id];
+    if (!node) {
+      return undefined;
+    }
+
+    delete this._tree.nodes[node.id];
+    const idx = parent.children.findIndex((child) => child === id);
+    if (idx !== -1) {
+      parent.children.splice(idx, 1);
+    }
+
+    return node;
+  }
+
+  /**
+   * Move child node.
+   */
+  moveNode(node: TreeNodeType, from: number, to: number): TreeNodeType | null {
+    invariant(from >= 0 && from < node.children.length);
+    invariant(to >= 0 && to < node.children.length);
+    if (from === to) {
+      return null;
+    }
+
+    const child = node.children[from];
+    node.children.splice(from, 1);
+    node.children.splice(to, 0, child);
+    return this.getNode(child);
+  }
+
+  /**
+   * Indent node.
+   */
+  indentNode(node: TreeNodeType): void {
+    const parent = this.getParent(node);
+    if (!parent) {
+      return;
+    }
+
+    const idx = parent.children.findIndex((child) => child === node.id);
+    if (idx < 1 || idx >= parent.children.length) {
+      return;
+    }
+
+    const previous = this.getNode(parent.children[idx - 1]);
+    parent.children.splice(idx, 1);
+    previous.children.push(node.id);
+  }
+
+  /**
+   * Unindent node.
+   */
+  unindentNode(node: TreeNodeType): void {
+    const parent = this.getParent(node);
+    if (!parent) {
+      return;
+    }
+
+    const ancestor = this.getParent(parent);
+    if (!ancestor) {
+      return;
+    }
+
+    // Remove node from parent.
+    const nodeIdx = parent.children.findIndex((id) => id === node.id);
+    const [_, ...rest] = parent.children.splice(nodeIdx, parent.children.length - nodeIdx);
+    parent.children.splice(nodeIdx, parent.children.length - nodeIdx);
+
+    // Add to ancestor.
+    const parentIdx = this.getChildNodes(ancestor).findIndex((n) => n.id === parent.id);
+    ancestor.children.splice(parentIdx + 1, 0, node.id);
+
+    // Transplant following siblings to current node.
+    node.children.push(...rest);
+  }
+}

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

@@ -0,0 +1,41 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type GraphModel } from '@dxos/graph';
+
+export type TreeNode = {
+  id: string;
+  label?: string;
+  children?: TreeNode[];
+};
+
+export const mapGraphToTreeData = (model: GraphModel, maxDepth = 8): TreeNode | undefined => {
+  // TODO(burdon): Convert to common/graph.
+  // const mapNode = (node: N, depth = 0): TreeNode => {
+  //   const treeNode: TreeNode = {
+  //     id: model.idAccessor(node),
+  //     label: model.idAccessor(node).slice(0, 8),
+  //   };
+
+  //   const links = model.graph.links.filter((link) => link.source === treeNode.id);
+  //   if (depth < maxDepth) {
+  //     treeNode.children = links.map((link) =>
+  //       mapNode(model.graph.nodes.find((node) => model.idAccessor(node) === link.target)!, depth + 1),
+  //     );
+  //   }
+
+  //   return treeNode;
+  // };
+
+  let data: TreeNode | undefined;
+  // TODO(burdon): Selection model.
+  // if (model.selected) {
+  //   const node = model.graph.nodes.find((node) => model.idAccessor(node) === model.selected);
+  //   if (node) {
+  //     data = mapNode(node);
+  //   }
+  // }
+
+  return data;
+};

package/src/hooks/index.ts

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

package/src/hooks/useGraphModel.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useEffect, useState } from 'react';
+
+import { type Filter, type Space } from '@dxos/client/echo';
+import { SpaceGraphModel, type SpaceGraphModelOptions } from '@dxos/schema';
+
+// TODO(burdon): Factor out.
+export const useGraphModel = (
+  space: Space | undefined,
+  filter?: Filter.Any | undefined,
+  options?: SpaceGraphModelOptions,
+): SpaceGraphModel | undefined => {
+  const [model, setModel] = useState<SpaceGraphModel | undefined>(undefined);
+  useEffect(() => {
+    if (!space) {
+      void model?.close();
+      setModel(undefined);
+      return;
+    }
+
+    // TODO(burdon): Does this need to be a dependency?
+    if (!model) {
+      const model = new SpaceGraphModel().setFilter(filter).setOptions(options);
+      void model.open(space);
+      setModel(model);
+    } else {
+      model.setFilter(filter).setOptions(options);
+    }
+  }, [space, filter, options]);
+
+  return model;
+};

package/src/index.ts

@@ -2,8 +2,8 @@
 // Copyright 2023 DXOS.org
 //
 
-// TODO(burdon): Factor out.
 export * from './components';
+export * from './hooks';
+export * from './meta';
 
 export * from './ExplorerPlugin';
-export * from './meta';

package/src/meta.ts

@@ -11,7 +11,7 @@ export const meta: PluginMeta = {
   name: 'Explorer',
   description: 'Install this plugin to view a hypergraph of all objects inside of your Space.',
   icon: 'ph--graph--regular',
-  source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/experimental/plugin-explorer',
-  tags: ['experimental'],
+  source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-explorer',
+  tags: ['labs'],
   screenshots: ['https://dxos.network/plugin-details-explorer-dark.png'],
 };

package/src/types/schema.ts

@@ -2,13 +2,15 @@
 // Copyright 2024 DXOS.org
 //
 
-import { S, TypedObject } from '@dxos/echo-schema';
+import { Schema } from 'effect';
+
+import { TypedObject } from '@dxos/echo-schema';
 
 // TODO(burdon): Clashes with sdk/view.
 export class ViewType extends TypedObject({
   typename: 'dxos.org/type/ExplorerView',
   version: '0.1.0',
 })({
-  name: S.optional(S.String),
-  type: S.String,
+  name: Schema.optional(Schema.String),
+  type: Schema.String,
 }) {}

package/src/types/types.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { S } from '@dxos/echo-schema';
+import { Schema } from 'effect';
 
 import { ViewType } from './schema';
 import { EXPLORER_PLUGIN } from '../meta';
@@ -10,11 +10,11 @@ import { EXPLORER_PLUGIN } from '../meta';
 export namespace ExplorerAction {
   const EXPLORER_ACTION = `${EXPLORER_PLUGIN}/action`;
 
-  export class Create extends S.TaggedClass<Create>()(`${EXPLORER_ACTION}/create`, {
-    input: S.Struct({
-      name: S.optional(S.String),
+  export class Create extends Schema.TaggedClass<Create>()(`${EXPLORER_ACTION}/create`, {
+    input: Schema.Struct({
+      name: Schema.optional(Schema.String),
     }),
-    output: S.Struct({
+    output: Schema.Struct({
       object: ViewType,
     }),
   }) {}