@dxos/plugin-explorer 0.8.4-main.406dc2a → 0.8.4-main.43cb759274

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

@@ -4,38 +4,34 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Key, Obj, Type } from '@dxos/echo';
+import { DXN, Key, Obj, Ref, Type } from '@dxos/echo';
+import { TestSchema } from '@dxos/echo/testing';
 import { invariant } from '@dxos/invariant';
 
 // TODO(burdon): Reconcile with @dxos/graph (i.e., common types).
 
 export const TreeNodeType = Schema.Struct({
-  id: Key.ObjectId,
-  children: Schema.mutable(Schema.Array(Key.ObjectId)),
+  id: Key.EntityId,
+  children: Schema.mutable(Schema.Array(Key.EntityId)),
   data: Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.Any })),
-  ref: Schema.optional(Type.Ref(Type.Expando)),
+  ref: Schema.optional(Ref.Ref(TestSchema.Expando)),
 }).pipe(Schema.mutable);
 
-export interface TreeNodeType extends Schema.Schema.Type<typeof TreeNodeType> {}
+export type TreeNodeType = Schema.Schema.Type<typeof TreeNodeType>;
 
 export const TreeType = Schema.Struct({
-  root: Key.ObjectId,
-  nodes: Schema.mutable(Schema.Record({ key: Key.ObjectId, value: TreeNodeType })),
-}).pipe(
-  Type.Obj({
-    typename: 'dxos.org/type/Tree',
-    version: '0.1.0',
-  }),
-);
+  root: Key.EntityId,
+  nodes: Schema.mutable(Schema.Record({ key: Key.EntityId, value: TreeNodeType })),
+}).pipe(Type.makeObject(DXN.make('org.dxos.type.tree', '0.1.0')));
 
-export interface TreeType extends Schema.Schema.Type<typeof TreeType> {}
+export type TreeType = Type.InstanceType<typeof TreeType>;
 
 /**
  * Wrapper object for tree.
  */
 export class Tree {
   static create = (): TreeType => {
-    const id = Key.ObjectId.random();
+    const id = Key.EntityId.random();
     return Obj.make(TreeType, {
       root: id,
       nodes: {
@@ -76,7 +72,7 @@ export class Tree {
    */
   tranverse<T>(
     callback: (node: TreeNodeType, depth: number) => T | void,
-    root: Key.ObjectId = this._tree.root,
+    root: Key.EntityId = this._tree.root,
     depth = 0,
   ): T | void {
     const node = this._tree.nodes[root];
@@ -93,7 +89,7 @@ export class Tree {
     }
   }
 
-  getNode(id: Key.ObjectId): TreeNodeType {
+  getNode(id: Key.EntityId): TreeNodeType {
     const node = this._tree.nodes[id];
     invariant(node);
     return node;
@@ -184,9 +180,11 @@ export class Tree {
   clear(): void {
     const root = this._tree.nodes[this._tree.root];
     root.children.length = 0;
-    this._tree.nodes = {
-      [root.id]: root,
-    };
+    Obj.update(this._tree, (obj) => {
+      obj.nodes = {
+        [root.id]: root,
+      };
+    });
   }
 
   /**
@@ -194,28 +192,35 @@ export class Tree {
    */
   addNode(parent: TreeNodeType, node?: TreeNodeType, index?: number): TreeNodeType {
     if (!node) {
-      const id = Key.ObjectId.random();
+      const id = Key.EntityId.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);
+    const nodeToAdd = node;
+    Obj.update(this._tree, (obj) => {
+      obj.nodes[nodeToAdd.id] = nodeToAdd;
+      parent.children.splice(index ?? parent.children.length, 0, nodeToAdd.id);
+    });
     return node;
   }
 
   /**
    * Delete node.
    */
-  deleteNode(parent: TreeNodeType, id: Key.ObjectId): TreeNodeType | undefined {
+  deleteNode(parent: TreeNodeType, id: Key.EntityId): TreeNodeType | undefined {
     const node = this._tree.nodes[id];
     if (!node) {
       return undefined;
     }
 
-    delete this._tree.nodes[node.id];
+    Obj.update(this._tree, (obj) => {
+      delete obj.nodes[node.id];
+    });
     const idx = parent.children.findIndex((child) => child === id);
     if (idx !== -1) {
-      parent.children.splice(idx, 1);
+      Obj.update(this._tree, () => {
+        parent.children.splice(idx, 1);
+      });
     }
 
     return node;
@@ -232,8 +237,10 @@ export class Tree {
     }
 
     const child = node.children[from];
-    node.children.splice(from, 1);
-    node.children.splice(to, 0, child);
+    Obj.update(this._tree, () => {
+      node.children.splice(from, 1);
+      node.children.splice(to, 0, child);
+    });
     return this.getNode(child);
   }
 
@@ -252,8 +259,10 @@ export class Tree {
     }
 
     const previous = this.getNode(parent.children[idx - 1]);
-    parent.children.splice(idx, 1);
-    previous.children.push(node.id);
+    Obj.update(this._tree, () => {
+      parent.children.splice(idx, 1);
+      previous.children.push(node.id);
+    });
   }
 
   /**
@@ -270,16 +279,23 @@ export class Tree {
       return;
     }
 
-    // Remove node from parent.
+    // Remove node from parent and get following siblings.
     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);
+    let rest: Key.EntityId[] = [];
+    Obj.update(this._tree, () => {
+      const removed = parent.children.splice(nodeIdx, parent.children.length - nodeIdx);
+      rest = removed.slice(1); // Skip the node itself.
+    });
 
     // Add to ancestor.
     const parentIdx = this.getChildNodes(ancestor).findIndex((n) => n.id === parent.id);
-    ancestor.children.splice(parentIdx + 1, 0, node.id);
+    Obj.update(this._tree, () => {
+      ancestor.children.splice(parentIdx + 1, 0, node.id);
+    });
 
     // Transplant following siblings to current node.
-    node.children.push(...rest);
+    Obj.update(this._tree, () => {
+      node.children.push(...rest);
+    });
   }
 }

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

@@ -2,40 +2,49 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type GraphModel } from '@dxos/graph';
+import { type Key } from '@dxos/echo';
 
-export type TreeNode = {
+import { type TreeType } from './tree';
+
+/**
+ * In-memory tree shape used by the d3 layouts.
+ * `data` carries through to layout callbacks (e.g. hover/inspect) — typically an ECHO object on leaves.
+ */
+export type TreeNode<TData = unknown> = {
   id: string;
   label?: string;
-  children?: TreeNode[];
+  data?: TData;
+  children?: TreeNode<TData>[];
 };
 
-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),
-  //     );
-  //   }
+/**
+ * Convert an ECHO `TreeType` (id-keyed node map) into a nested `TreeNode` hierarchy.
+ * Returns `undefined` if the root id is missing — the tree is then incomplete and shouldn't render.
+ */
+export const treeTypeToTreeNode = (
+  tree: TreeType,
+  rootId: Key.EntityId = tree.root,
+  visited: Set<string> = new Set(),
+): TreeNode | undefined => {
+  const node = tree.nodes[rootId];
+  if (!node) {
+    return undefined;
+  }
+  if (visited.has(rootId)) {
+    return { id: rootId, label: labelOf(node), data: node.data };
+  }
+  visited.add(rootId);
 
-  //   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 {
+    id: rootId,
+    label: labelOf(node),
+    data: node.data,
+    children: node.children
+      .map((childId) => treeTypeToTreeNode(tree, childId, visited))
+      .filter((c): c is TreeNode => Boolean(c)),
+  };
+};
 
-  return data;
+const labelOf = (node: { data: Record<string, any> }): string | undefined => {
+  return typeof node.data?.text === 'string' ? node.data.text : undefined;
 };

package/src/components/index.ts

@@ -2,11 +2,8 @@
 // Copyright 2023 DXOS.org
 //
 
-import { lazy } from 'react';
-
-export const ExplorerContainer = lazy(() => import('./ExplorerContainer'));
-
 export * from './Chart';
 export * from './Globe';
 export * from './Graph';
+export * from './Lattice';
 export * from './Tree';

package/src/containers/ExplorerArticle/ExplorerArticle.stories.tsx

@@ -0,0 +1,152 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Filter, Query, 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 { useQuery, useSpaces } from '@dxos/react-client/echo';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { ViewModel } from '@dxos/schema';
+import { type ValueGenerator, createObjectFactory, createRelationFactory } from '@dxos/schema/testing';
+import { HasConnection, HasRelationship, Organization, Person, Pipeline } from '@dxos/types';
+
+import { Graph } from '../../types';
+import { ExplorerArticle, type ExplorerArticleVariant } from './ExplorerArticle';
+
+const generator = random as any as ValueGenerator;
+
+random.seed(7);
+
+type DefaultStoryProps = { variant: ExplorerArticleVariant };
+
+const DefaultStory = ({ variant }: DefaultStoryProps) => {
+  const [space] = useSpaces();
+  const [graph] = useQuery(space?.db, Filter.type(Graph.Graph));
+  if (!space || !graph) {
+    return <Loading data={{ space: !!space, graph: !!graph }} />;
+  }
+
+  return <ExplorerArticle role='article' subject={graph as any} attendableId={graph.id} variant={variant} />;
+};
+
+const meta: Meta<DefaultStoryProps> = {
+  title: 'plugins/plugin-explorer/containers/ExplorerArticle',
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'fullscreen' }),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        StorybookPlugin({}),
+        ClientPlugin({
+          types: [
+            Graph.Graph,
+            HasRelationship.HasRelationship,
+            Organization.Organization,
+            Person.Person,
+            Pipeline.Pipeline,
+            View.View,
+          ],
+          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 },
+                ]),
+              );
+              // Denser HasRelationship graph so the plexus variant shows multiple relation
+              // groups (organization ref + relationships) fanning out from a focused person.
+              yield* Effect.promise(() =>
+                createRelationFactory(
+                  personalSpace.db,
+                  generator,
+                )([
+                  { type: HasRelationship.HasRelationship, count: 40, data: { kind: 'friend' } },
+                  { type: HasConnection.HasConnection, count: 20, data: { kind: 'vendor' } },
+                ]),
+              );
+
+              const { view } = yield* Effect.promise(() =>
+                ViewModel.makeFromDatabase({
+                  db: personalSpace.db,
+                  typename: Type.getTypename(Graph.Graph),
+                }),
+              );
+
+              const graph = personalSpace.db.add(
+                Graph.make({
+                  name: 'Root',
+                  view,
+                  query: {
+                    ast: Query.select(Filter.everything()).ast,
+                  },
+                }),
+              );
+
+              yield* Effect.promise(() => personalSpace.db.flush({ indexes: true }));
+              return graph;
+            }),
+        }),
+        PreviewPlugin(),
+      ],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Force: Story = {
+  args: {
+    variant: 'force',
+  },
+};
+
+export const Cluster: Story = {
+  args: {
+    variant: 'cluster',
+  },
+};
+
+export const Bundle: Story = {
+  args: {
+    variant: 'bundle',
+  },
+};
+
+export const Plexus: Story = {
+  args: {
+    variant: 'plexus',
+  },
+};
+
+export const Lattice: Story = {
+  args: {
+    variant: 'lattice',
+  },
+};
+
+export const Swarm: Story = {
+  args: {
+    variant: 'swarm',
+  },
+};

package/src/containers/ExplorerArticle/ExplorerArticle.tsx

@@ -0,0 +1,120 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { type Filter, Obj, type View } from '@dxos/echo';
+import { QueryBuilder } from '@dxos/echo-query';
+import { useObject } from '@dxos/react-client/echo';
+import { DxAnchorActivate, Icon, Panel, Toolbar } from '@dxos/react-ui';
+import { QueryEditor, type QueryEditorProps } from '@dxos/react-ui-components';
+import '@dxos/react-ui-graph/styles/graph.css';
+
+import { type TreeNode } from '#components';
+import { useGraphModel } from '#hooks';
+
+import { type ExplorerArticleVariant, VARIANTS, isVariant } from './variants';
+import { Visualization } from './Visualization';
+
+export type { ExplorerArticleVariant } from './variants';
+
+export type ExplorerArticleProps = AppSurface.ObjectArticleProps<View.View>;
+
+export const ExplorerArticle = ({ role, subject, variant }: ExplorerArticleProps) => {
+  const [view] = useObject(subject);
+  const [filter, setFilter] = useState<Filter.Any>();
+
+  const db = view && Obj.getDatabase(view);
+  const model = useGraphModel(db, filter);
+
+  const builder = useMemo(() => new QueryBuilder(), []);
+  const handleChange = useCallback<NonNullable<QueryEditorProps['onChange']>>(
+    (value) => {
+      setFilter(builder.build(value).filter);
+    },
+    [builder],
+  );
+
+  const [selected, setSelected] = useState<ExplorerArticleVariant>(isVariant(variant) ? variant : 'force');
+  useEffect(() => {
+    if (isVariant(variant)) {
+      setSelected(variant);
+    }
+  }, [variant]);
+
+  const handleVariantChange = useCallback((value: string) => {
+    if (isVariant(value)) {
+      setSelected(value);
+    }
+  }, []);
+
+  // Dismiss the preview popover. The dxn/label/trigger fields are placeholders ignored on
+  // `state: false`.
+  const handleDismiss = useCallback(() => {
+    document.defaultView?.dispatchEvent(
+      new DxAnchorActivate({ dxn: '', label: '', trigger: document.body, state: false }),
+    );
+  }, []);
+
+  const handleHover = useCallback((node: TreeNode | null, event?: MouseEvent) => {
+    // Pointer left the node/label: keep the popover open so it can be hovered/interacted with.
+    // The popover is dismissed only on an explicit click on the component surface (handleDismiss).
+    if (!node || !event) {
+      return;
+    }
+    const obj = node.data;
+    if (!obj || !Obj.isObject(obj)) {
+      return;
+    }
+    const dxn = Obj.getURI(obj);
+    if (!dxn) {
+      return;
+    }
+
+    const target = event.target as HTMLElement;
+    target.dispatchEvent(
+      new DxAnchorActivate({
+        dxn,
+        kind: 'card',
+        trigger: target,
+        label: Obj.getLabel(obj) ?? dxn,
+      }),
+    );
+  }, []);
+
+  const showToolbar = role === 'article';
+
+  if (!db || !model) {
+    return null;
+  }
+
+  return (
+    <Panel.Root role={role}>
+      {showToolbar && (
+        <Panel.Toolbar asChild>
+          <Toolbar.Root>
+            <QueryEditor db={db} onChange={handleChange} />
+            <Toolbar.ToggleGroup type='single' value={selected} onValueChange={handleVariantChange}>
+              {VARIANTS.map(({ value, icon, label }) => (
+                <Toolbar.ToggleGroupItem key={value} value={value} aria-label={label} title={label}>
+                  <Icon icon={icon} size={4} />
+                </Toolbar.ToggleGroupItem>
+              ))}
+            </Toolbar.ToggleGroup>
+          </Toolbar.Root>
+        </Panel.Toolbar>
+      )}
+      <Panel.Content>
+        <Visualization
+          classNames='bg-base-surface'
+          variant={selected}
+          model={model}
+          onNodeHover={handleHover}
+          onSurfaceClick={handleDismiss}
+        />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};