@dxos/plugin-explorer 0.8.4-main.72ec0f3 → 0.8.4-main.765dc60934

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

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Key } from '@dxos/echo';
+import { Key, Obj } from '@dxos/echo';
 import { range } from '@dxos/util';
 
 import { Tree, type TreeNodeType } from '../types';
@@ -16,7 +16,9 @@ const random = (min: number, max: number) => Math.floor(Math.random() * (max - m
  */
 export const createTree = (spec: NumberOrNumberArray[] = [], createText?: () => string): Tree => {
   const tree = new Tree();
-  tree.root.data = { text: 'root' };
+  Obj.update(tree.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;

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

@@ -3,3 +3,4 @@
 //
 
 export * from './generator';
+export * from './relations';

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

@@ -0,0 +1,182 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Space } from '@dxos/client/echo';
+import { Obj, Query, Relation } from '@dxos/echo';
+import { type TypeSpec, type ValueGenerator, createObjectFactory } from '@dxos/schema/testing';
+import { HasConnection, HasRelationship, Organization, Person, Pipeline } from '@dxos/types';
+import { range } from '@dxos/util';
+
+import { type BundleEdge } from '../layout';
+import { type TreeNode } from '../types';
+
+const SECTORS = ['Technology', 'Finance', 'Research', 'Media'];
+const CONNECTION_KINDS = ['partner', 'investor', 'vendor', 'customer'];
+
+const pick = <T>(arr: readonly T[], rng = Math.random): T => arr[Math.floor(rng() * arr.length)];
+
+export type ConnectedOrgsResult = {
+  organizations: Obj.Any[];
+  people: Obj.Any[];
+  connections: Obj.Any[];
+};
+
+export type ConnectedOrgsOptions = {
+  organizationCount?: number;
+  personCount?: number;
+  connectionCount?: number;
+};
+
+/**
+ * Populate a space with Organizations, People, and HasConnection relations between organizations.
+ * Uses `createObjectFactory` to generate Org/Person properties from their `GeneratorAnnotation`s,
+ * then layers manual HasConnection relations on top — the connection schema is fixed
+ * (Org→Org) so it isn't a fit for the generator's reference inference.
+ */
+export const generateConnectedOrgs = async (
+  space: Space,
+  generator: ValueGenerator,
+  { organizationCount = 12, personCount = 24, connectionCount = 18 }: ConnectedOrgsOptions = {},
+): Promise<ConnectedOrgsResult> => {
+  const specs: TypeSpec[] = [
+    { type: Organization.Organization, count: organizationCount },
+    // Person has a Ref to Organization — generator fills it from objects already in db.
+    { type: Person.Person, count: personCount },
+  ];
+
+  const factory = createObjectFactory(space.db, generator);
+  await factory(specs);
+
+  const organizations = await space.db.query(Query.type(Organization.Organization)).run();
+  const people = await space.db.query(Query.type(Person.Person)).run();
+
+  const connections: Obj.Any[] = [];
+  const seen = new Set<string>();
+  for (let i = 0; i < connectionCount && organizations.length >= 2; i++) {
+    const source = pick(organizations);
+    const target = pick(organizations);
+    if (source.id === target.id) {
+      continue;
+    }
+    const key = `${source.id}->${target.id}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+
+    const relation = Relation.make(HasConnection.HasConnection, {
+      [Relation.Source]: source as any,
+      [Relation.Target]: target as any,
+      kind: pick(CONNECTION_KINDS),
+    });
+    connections.push(space.db.add(relation as any));
+  }
+
+  await space.db.flush();
+  return { organizations, people, connections };
+};
+
+/**
+ * Build a TreeNode hierarchy: Root → Sector → Organization (leaf).
+ * Organizations are deterministically bucketed into `SECTORS` so the demo has visible groups.
+ */
+export const buildOrgHierarchy = (organizations: Obj.Any[], sectors: readonly string[] = SECTORS): TreeNode => {
+  // Avoid modulo-by-zero / missing-bucket crashes when the caller passes an empty sectors list.
+  const activeSectors = sectors.length > 0 ? sectors : ['Uncategorized'];
+  const buckets = new Map<string, TreeNode[]>();
+  for (const sector of activeSectors) {
+    buckets.set(sector, []);
+  }
+  for (let i = 0; i < organizations.length; i++) {
+    const org = organizations[i] as any;
+    const sector = activeSectors[i % activeSectors.length];
+    buckets.get(sector)!.push({
+      id: org.id,
+      label: org.name ?? org.id.slice(0, 6),
+    });
+  }
+
+  return {
+    id: 'root',
+    label: 'Organizations',
+    children: activeSectors.map((sector) => ({
+      id: `sector:${sector}`,
+      label: sector,
+      children: buckets.get(sector) ?? [],
+    })),
+  };
+};
+
+const defaultGenerateTypes: TypeSpec[] = [
+  { type: Organization.Organization, count: 20 },
+  { type: Person.Person, count: 20 },
+  { type: Pipeline.Pipeline, count: 20 },
+];
+
+export type GenerateOptions = {
+  spec?: TypeSpec[];
+  relations?: {
+    count: number;
+    kind: string;
+  };
+};
+
+const defaultGenerateRelations: NonNullable<GenerateOptions['relations']> = {
+  kind: 'friend',
+  count: 10,
+};
+
+/**
+ * Populate a space with a mixed dataset (Orgs, Pipelines, People) plus
+ * `HasRelationship` edges between random pairs of People.
+ *
+ * Used by the force-directed and canvas-force graph stories that want a
+ * heterogeneous typed dataset without caring about the precise shape of relations.
+ */
+export const generate = async (
+  space: Space,
+  generator: ValueGenerator,
+  { spec = defaultGenerateTypes, relations = defaultGenerateRelations }: GenerateOptions = {},
+) => {
+  const createObjects = createObjectFactory(space.db, generator);
+  await createObjects(spec);
+
+  const contacts: Obj.Any[] = await space.db.query(Query.type(Person.Person)).run();
+  if (contacts.length < 2 || relations.count <= 0) {
+    return;
+  }
+  for (const _ of range(relations.count)) {
+    const source = pick(contacts);
+    const target = pick(contacts);
+    if (source.id !== target.id) {
+      space.db.add(
+        Relation.make(HasRelationship.HasRelationship, {
+          [Relation.Source]: source as any,
+          [Relation.Target]: target as any,
+          kind: relations.kind,
+        }) as any,
+      );
+    }
+  }
+};
+
+/**
+ * Convert HasConnection relations into bundle edges between organization ids.
+ */
+export const connectionsToEdges = (connections: Obj.Any[]): BundleEdge[] => {
+  return connections
+    .map((relation): BundleEdge | undefined => {
+      const source = Relation.getSource(relation as any) as any;
+      const target = Relation.getTarget(relation as any) as any;
+      if (!source?.id || !target?.id) {
+        return undefined;
+      }
+      return {
+        source: source.id,
+        target: target.id,
+        kind: (relation as any).kind,
+      };
+    })
+    .filter((e): e is BundleEdge => Boolean(e));
+};

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

@@ -5,14 +5,13 @@
 import { describe, test } from 'vitest';
 
 import { Obj, Ref } from '@dxos/echo';
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 import { Task } from '@dxos/types';
 
 import { createTree } from '../testing';
-
 import { type Tree } from './tree';
 
-faker.seed(0);
+random.seed(0);
 
 const print = (tree: Tree) => {
   let count = 0;
@@ -129,6 +128,8 @@ describe('tree', () => {
 
     const tree = createTree();
     const node = tree.addNode(tree.root);
-    node.ref = Ref.make(task);
+    Obj.update(tree.tree, () => {
+      node.ref = Ref.make(task);
+    });
   });
 });

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

@@ -4,7 +4,8 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Key, Obj, Type } from '@dxos/echo';
+import { 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).
@@ -13,7 +14,7 @@ export const TreeNodeType = Schema.Struct({
   id: Key.ObjectId,
   children: Schema.mutable(Schema.Array(Key.ObjectId)),
   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> {}
@@ -22,8 +23,8 @@ 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',
+  Type.object({
+    typename: 'org.dxos.type.tree',
     version: '0.1.0',
   }),
 );
@@ -184,9 +185,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,
+      };
+    });
   }
 
   /**
@@ -198,8 +201,11 @@ export class Tree {
       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;
   }
 
@@ -212,10 +218,14 @@ export class Tree {
       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 +242,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 +264,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 +284,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.ObjectId[] = [];
+    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.ObjectId = 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,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type ComponentType, lazy } from 'react';
-
 export * from './Chart';
 export * from './Globe';
 export * from './Graph';
 export * from './Tree';
-
-export const ExplorerContainer: ComponentType<any> = lazy(() => import('./ExplorerContainer'));

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

@@ -0,0 +1,119 @@
+//
+// 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 } from '@dxos/schema/testing';
+import { HasRelationship, Organization, Person, Pipeline } from '@dxos/types';
+
+import { generate } from '../../components/Tree/testing';
+import { Graph } from '../../types';
+import { ExplorerArticle, type ExplorerArticleVariant } from './ExplorerArticle';
+
+const generator = random as any as ValueGenerator;
+
+random.seed(7);
+
+type StoryArgs = { variant: ExplorerArticleVariant };
+
+const DefaultStory = ({ variant }: StoryArgs) => {
+  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<StoryArgs> = {
+  title: 'plugins/plugin-explorer/containers/ExplorerArticle',
+  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(() => generate(personalSpace, generator));
+              const { view } = yield* Effect.promise(() =>
+                ViewModel.makeFromDatabase({ db: personalSpace.db, typename: Type.getTypename(Graph.Graph) }),
+              );
+              const graph = personalSpace.db.add(
+                Graph.make({
+                  name: 'Test',
+                  view,
+                  query: { raw: '', 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<StoryArgs>;
+
+/**
+ * Default force-directed view (the production layout).
+ */
+export const Force: Story = {
+  args: {
+    variant: 'force',
+  },
+};
+
+/**
+ * Radial cluster: every object on the perimeter, grouped by its schema, all under
+ * a single database root. Inspired by https://observablehq.com/@d3/radial-cluster.
+ */
+export const Cluster: Story = {
+  args: {
+    variant: 'cluster',
+  },
+};
+
+/**
+ * Hierarchical edge bundling: same hierarchy as `cluster`, with bundled curves
+ * routed through the lowest common ancestor for every relation / ref in the space.
+ * Inspired by https://observablehq.com/@d3/hierarchical-edge-bundling.
+ */
+export const Bundle: Story = {
+  args: {
+    variant: 'bundle',
+  },
+};