@dxos/plugin-explorer 0.8.4-main.e8ec1fe → 0.8.4-main.effb148878

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

@@ -0,0 +1,142 @@
+//
+// 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 '../../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: '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<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',
+  },
+};
+
+/**
+ * Lattice: every object as a cell in a square-as-possible CSS grid, sorted by typename so
+ * objects of the same type cluster together. Each cell is colored by its typename.
+ */
+export const Lattice: Story = {
+  args: {
+    variant: 'lattice',
+  },
+};
+
+export const Swarm: Story = {
+  args: {
+    variant: 'swarm',
+  },
+};

package/src/containers/ExplorerArticle/ExplorerArticle.tsx

@@ -0,0 +1,112 @@
+//
+// 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';
+// Side-effect import: Visualization drives `SVG.Graph` directly. Without the CSS the
+// `g.dx-edge path` rules — including `fill: none` — never reach the bundle and SVG
+// defaults (stroke: none, fill: black) make every edge invisible.
+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>;
+
+/**
+ * Thin wrapper: owns the query editor, the variant toggle, and the DxAnchor preview
+ * dispatch. The actual rendering — SVG projector swaps and the swarm canvas — lives in
+ * `Visualization`.
+ */
+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);
+    }
+  }, []);
+
+  const handleHover = useCallback((node: TreeNode | null, event?: MouseEvent) => {
+    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 variant={selected} model={model} onNodeHover={handleHover} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};