@dxos/plugin-explorer 0.8.4-main.74a063c4e0 → 0.8.4-main.765dc60934

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

@@ -16,7 +16,7 @@ const random = (min: number, max: number) => Math.floor(Math.random() * (max - m
  */
 export const createTree = (spec: NumberOrNumberArray[] = [], createText?: () => string): Tree => {
   const tree = new Tree();
-  Obj.change(tree.tree, () => {
+  Obj.update(tree.tree, () => {
     tree.root.data = { text: 'root' };
   });
 

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

@@ -128,7 +128,7 @@ describe('tree', () => {
 
     const tree = createTree();
     const node = tree.addNode(tree.root);
-    Obj.change(tree.tree, () => {
+    Obj.update(tree.tree, () => {
       node.ref = Ref.make(task);
     });
   });

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

@@ -185,7 +185,7 @@ export class Tree {
   clear(): void {
     const root = this._tree.nodes[this._tree.root];
     root.children.length = 0;
-    Obj.change(this._tree, (obj) => {
+    Obj.update(this._tree, (obj) => {
       obj.nodes = {
         [root.id]: root,
       };
@@ -202,7 +202,7 @@ export class Tree {
     }
 
     const nodeToAdd = node;
-    Obj.change(this._tree, (obj) => {
+    Obj.update(this._tree, (obj) => {
       obj.nodes[nodeToAdd.id] = nodeToAdd;
       parent.children.splice(index ?? parent.children.length, 0, nodeToAdd.id);
     });
@@ -218,12 +218,12 @@ export class Tree {
       return undefined;
     }
 
-    Obj.change(this._tree, (obj) => {
+    Obj.update(this._tree, (obj) => {
       delete obj.nodes[node.id];
     });
     const idx = parent.children.findIndex((child) => child === id);
     if (idx !== -1) {
-      Obj.change(this._tree, () => {
+      Obj.update(this._tree, () => {
         parent.children.splice(idx, 1);
       });
     }
@@ -242,7 +242,7 @@ export class Tree {
     }
 
     const child = node.children[from];
-    Obj.change(this._tree, () => {
+    Obj.update(this._tree, () => {
       node.children.splice(from, 1);
       node.children.splice(to, 0, child);
     });
@@ -264,7 +264,7 @@ export class Tree {
     }
 
     const previous = this.getNode(parent.children[idx - 1]);
-    Obj.change(this._tree, () => {
+    Obj.update(this._tree, () => {
       parent.children.splice(idx, 1);
       previous.children.push(node.id);
     });
@@ -287,19 +287,19 @@ export class Tree {
     // Remove node from parent and get following siblings.
     const nodeIdx = parent.children.findIndex((id) => id === node.id);
     let rest: Key.ObjectId[] = [];
-    Obj.change(this._tree, () => {
+    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);
-    Obj.change(this._tree, () => {
+    Obj.update(this._tree, () => {
       ancestor.children.splice(parentIdx + 1, 0, node.id);
     });
 
     // Transplant following siblings to current node.
-    Obj.change(this._tree, () => {
+    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.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/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',
+  },
+};

package/src/containers/ExplorerArticle/ExplorerArticle.tsx

@@ -0,0 +1,153 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+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 { ForceGraph } from '#components';
+import { HierarchicalEdgeBundling, RadialTree, spaceGraphToHierarchy, type TreeNode } from '#components';
+import { useGraphModel } from '#hooks';
+
+/** Visualization variants exposed by `ExplorerArticle`. */
+export type ExplorerArticleVariant = 'force' | 'cluster' | 'bundle';
+
+const VARIANTS: { value: ExplorerArticleVariant; icon: string; label: string }[] = [
+  {
+    value: 'force',
+    icon: 'ph--graph--regular',
+    label: 'Force-directed',
+  },
+  {
+    value: 'cluster',
+    icon: 'ph--asterisk-simple--regular',
+    label: 'Radial cluster',
+  },
+  {
+    value: 'bundle',
+    icon: 'ph--circles-three-plus--regular',
+    label: 'Edge bundling',
+  },
+];
+
+export type ExplorerArticleProps = AppSurface.ObjectArticleProps<View.View>;
+
+export const ExplorerArticle = ({ role, subject, variant }: ExplorerArticleProps) => {
+  const [view] = useObject(subject);
+  const db = view && Obj.getDatabase(view);
+  const [filter, setFilter] = useState<Filter.Any>();
+  const model = useGraphModel(db, filter);
+
+  const builder = useMemo(() => new QueryBuilder(), []);
+  const handleChange = useCallback<NonNullable<QueryEditorProps['onChange']>>((value) => {
+    setFilter(builder.build(value).filter);
+  }, []);
+
+  // The `variant` prop is the initial value; user can toggle via the toolbar tabs.
+  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);
+    }
+  }, []);
+
+  const handleHoverPreview = useCallback((node: TreeNode | null, event?: MouseEvent) => {
+    if (!node || !event) {
+      return;
+    }
+    const obj = node.data;
+    if (!obj || !Obj.isObject(obj)) {
+      return;
+    }
+    const dxn = Obj.getDXN(obj)?.toString();
+    if (!dxn) {
+      return;
+    }
+    const target = event.target as HTMLElement;
+    target.dispatchEvent(
+      new DxAnchorActivate({
+        dxn,
+        label: Obj.getLabel(obj) ?? dxn,
+        trigger: target,
+        kind: 'card',
+      }),
+    );
+  }, []);
+
+  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 variant={selected} model={model} onNodeHover={handleHoverPreview} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+const isVariant = (value: unknown): value is ExplorerArticleVariant =>
+  value === 'force' || value === 'cluster' || value === 'bundle';
+
+type VisualizationProps = {
+  variant: ExplorerArticleVariant;
+  model: NonNullable<ReturnType<typeof useGraphModel>>;
+  onNodeHover?: (node: TreeNode | null, event?: MouseEvent) => void;
+};
+
+const Visualization = ({ variant, model, onNodeHover }: VisualizationProps) => {
+  if (variant === 'force') {
+    // ForceGraph subscribes to model.graphAtom internally; don't re-render the wrapper on every tick.
+    return (
+      <ForceGraph
+        model={model}
+        onInspect={(node, event) => onNodeHover?.({ id: node.id, data: node.data?.data?.object }, event)}
+      />
+    );
+  }
+
+  return <HierarchyVisualization variant={variant} model={model} onNodeHover={onNodeHover} />;
+};
+
+/**
+ * Read from the model's reactive graph atom so the hierarchy is rebuilt as objects/relations stream in.
+ */
+const HierarchyVisualization = ({ variant, model, onNodeHover }: VisualizationProps) => {
+  // Capture the atom snapshot so the memo's dep list explicitly tracks each push from the atom.
+  const graphSnapshot = useAtomValue(model.graphAtom);
+  const { tree, edges } = useMemo(() => spaceGraphToHierarchy(model), [model, graphSnapshot]);
+  if (variant === 'cluster') {
+    return <RadialTree data={tree} cluster onNodeHover={onNodeHover} />;
+  }
+
+  return <HierarchicalEdgeBundling data={tree} edges={edges} onNodeHover={onNodeHover} />;
+};

package/src/containers/ExplorerArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export { ExplorerArticle as default } from './ExplorerArticle';

package/src/containers/index.ts

@@ -4,4 +4,4 @@
 
 import { type ComponentType, lazy } from 'react';
 
-export const ExplorerContainer: ComponentType<any> = lazy(() => import('./ExplorerContainer'));
+export const ExplorerArticle: ComponentType<any> = lazy(() => import('./ExplorerArticle'));