@dxos/plugin-explorer 0.8.4-main.7ace549 → 0.8.4-main.8baae0fced

package/src/testing/relations.ts

@@ -0,0 +1,192 @@
+//
+// 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 '../components/Tree/layout';
+import { type TreeNode } from '../components/Tree/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) ?? [],
+    })),
+  };
+};
+
+export type GenerateOptions = {
+  spec?: TypeSpec[];
+  relations?: {
+    count: number;
+    kind: string;
+  };
+};
+
+const defaultGenerateTypes: TypeSpec[] = [
+  {
+    type: Organization.Organization,
+    count: 20,
+  },
+  {
+    type: Person.Person,
+    count: 20,
+  },
+  {
+    type: Pipeline.Pipeline,
+    count: 20,
+  },
+];
+
+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/translations.ts

@@ -4,27 +4,28 @@
 
 import { Type } from '@dxos/echo';
 import { type Resource } from '@dxos/react-ui';
-import { translations as componentsTranslations } from '@dxos/react-ui-components';
+import { translations as componentsTranslations } from '@dxos/react-ui-components/translations';
 
-import { meta } from './meta';
-import { Graph } from './types';
+import { meta } from '#meta';
+import { Graph } from '#types';
 
 export const translations = [
   {
     'en-US': {
       [Type.getTypename(Graph.Graph)]: {
-        'typename label': 'Explorer',
-        'typename label_zero': 'Explorers',
-        'typename label_one': 'Explorer',
-        'typename label_other': 'Explorers',
-        'object name placeholder': 'New explorer',
-        'rename object label': 'Rename explorer',
-        'delete object label': 'Delete explorer',
-        'object deleted label': 'Explorer deleted',
+        'typename.label': 'Explorer',
+        'typename.label_zero': 'Explorers',
+        'typename.label_one': 'Explorer',
+        'typename.label_other': 'Explorers',
+        'object-name.placeholder': 'New explorer',
+        'add-object.label': 'Add explorer',
+        'rename-object.label': 'Rename explorer',
+        'delete-object.label': 'Delete explorer',
+        'object-deleted.label': 'Explorer deleted',
       },
       [meta.id]: {
-        'plugin name': 'Explorer',
-        'object title label': 'Title',
+        'plugin.name': 'Explorer',
+        'object-title.label': 'Title',
       },
     },
   },

package/src/types/ExplorerAction.ts

@@ -4,14 +4,7 @@
 
 import * as Schema from 'effect/Schema';
 
-import { TypeInputOptionsAnnotation } from '@dxos/plugin-space/types';
-import { SpaceSchema } from '@dxos/react-client/echo';
-
-import { meta } from '../meta';
-
-import * as Graph from './Graph';
-
-const EXPLORER_ACTION = `${meta.id}/action`;
+import { TypeInputOptionsAnnotation } from '@dxos/plugin-space';
 
 export const GraphProps = Schema.Struct({
   name: Schema.optional(Schema.String),
@@ -21,17 +14,7 @@ export const GraphProps = Schema.Struct({
     TypeInputOptionsAnnotation.set({
       location: ['database', 'runtime'],
       kind: ['user'],
-      registered: ['registered'],
     }),
     Schema.optional,
   ),
 });
-
-export class CreateGraph extends Schema.TaggedClass<CreateGraph>()(`${EXPLORER_ACTION}/create-graph`, {
-  input: Schema.Struct({
-    space: SpaceSchema,
-  }).pipe(Schema.extend(GraphProps)),
-  output: Schema.Struct({
-    object: Graph.Graph,
-  }),
-}) {}

package/src/types/Graph.ts

@@ -4,30 +4,33 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Filter, Obj, Query, QueryAST, Ref, Type } from '@dxos/echo';
+import { Annotation, Filter, Obj, Query, QueryAST, Ref, Type, View } from '@dxos/echo';
 import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/internal';
-import { View, ViewAnnotation } from '@dxos/schema';
+import { ViewAnnotation } from '@dxos/schema';
 
 const GraphSchema = Schema.Struct({
   name: Schema.optional(Schema.String),
 
-  view: Type.Ref(View.View).pipe(FormInputAnnotation.set(false)),
+  view: Ref.Ref(View.View).pipe(FormInputAnnotation.set(false)),
 
   query: Schema.Struct({
     raw: Schema.optional(Schema.String),
     ast: QueryAST.Query,
-  }).pipe(Schema.mutable, FormInputAnnotation.set(false)),
+  }).pipe(FormInputAnnotation.set(false)),
 }).pipe(
-  Type.Obj({
-    typename: 'dxos.org/type/Graph',
-    version: '0.2.0',
+  Type.object({
+    typename: 'org.dxos.type.graph',
+    version: '0.1.0',
   }),
   LabelAnnotation.set(['name']),
-  ViewAnnotation.set(true),
+  ViewAnnotation.set(['view']),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--graph--regular',
+    hue: 'green',
+  }),
 );
 export interface Graph extends Schema.Schema.Type<typeof GraphSchema> {}
-export interface GraphEncoded extends Schema.Schema.Encoded<typeof GraphSchema> {}
-export const Graph: Schema.Schema<Graph, GraphEncoded> = GraphSchema;
+export const Graph: Type.Obj<Graph> = GraphSchema as any;
 
 type MakeProps = Omit<Partial<Obj.MakeProps<typeof Graph>>, 'view'> & {
   view: View.View;
@@ -43,21 +46,3 @@ export const make = ({
 }: MakeProps): Graph => {
   return Obj.make(Graph, { name, view: Ref.make(view), query });
 };
-
-//
-// V1
-//
-
-export const GraphV1 = Schema.Struct({
-  name: Schema.optional(Schema.String),
-  query: Schema.Struct({
-    raw: Schema.optional(Schema.String),
-    ast: QueryAST.Query,
-  }).pipe(Schema.mutable),
-}).pipe(
-  Type.Obj({
-    typename: 'dxos.org/type/Graph',
-    version: '0.1.0',
-  }),
-  LabelAnnotation.set(['name']),
-);

package/src/typings.d.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+declare module '*.css' {
+  const content: undefined;
+  export default content;
+}

package/src/util/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './node-color';
+export * from './plot';

package/src/util/node-color.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Obj } from '@dxos/echo';
+import { getHashHue } from '@dxos/ui-theme';
+
+/**
+ * Returns the SVG `fill` value for a node, derived from its typename via the
+ * same hue-hash used by the force-directed renderer. Resolves to a Tailwind
+ * color token CSS variable so the value reads consistently across themes.
+ *
+ * Used by every variant of `ExplorerArticle` so nodes are colored consistently
+ * regardless of which layout is rendering them.
+ */
+export const getNodeFillForTypename = (typename: string | undefined): string => {
+  return `var(--color-${getHashHue(typename)}-400)`;
+};
+
+/** Convenience: derive the fill from an ECHO object's typename. */
+export const getNodeFillForObject = (object: Obj.Unknown | undefined): string => {
+  return getNodeFillForTypename(object && Obj.getTypename(object));
+};

package/src/{components → util}/plot.ts

@@ -4,12 +4,24 @@
 
 import type { ChannelValueSpec } from '@observablehq/plot';
 
-export type Point = { x: number; y: number };
-export type GeoLocation = { lat: number; lng: number };
-
 export type Accessor<T> = (object: any) => T;
 
+export type Point = {
+  x: number;
+  y: number;
+};
+
+export type GeoLocation = {
+  lat: number;
+  lng: number;
+};
+
 export const createAdapter = <T extends Record<string, any>>(
   prop: string,
   accessor: Accessor<T> | undefined,
-): ChannelValueSpec => (accessor ? { transform: (values) => values.map((value) => accessor(value)[prop]) } : prop);
+): ChannelValueSpec =>
+  accessor
+    ? {
+        transform: (values) => values.map((value) => accessor(value)[prop]),
+      }
+    : prop;

package/dist/lib/browser/ExplorerContainer-NOLLVUTE.mjs

@@ -1,50 +0,0 @@
-import {
-  useGraphModel
-} from "./chunk-2MKBRIUT.mjs";
-import {
-  D3ForceGraph
-} from "./chunk-6BVXZQPP.mjs";
-import "./chunk-J5LGTIGS.mjs";
-
-// src/components/ExplorerContainer.tsx
-import { useSignals as _useSignals } from "@preact-signals/safe-react/tracking";
-import React, { useCallback, useMemo, useState } from "react";
-import { QueryBuilder } from "@dxos/echo-query";
-import { useGlobalSearch } from "@dxos/plugin-search";
-import { getSpace } from "@dxos/react-client/echo";
-import { Toolbar } from "@dxos/react-ui";
-import { QueryEditor } from "@dxos/react-ui-components";
-import { StackItem } from "@dxos/react-ui-stack";
-var ExplorerContainer = ({ role, view }) => {
-  var _effect = _useSignals();
-  try {
-    const space = getSpace(view);
-    const [filter, setFilter] = useState();
-    const model = useGraphModel(space, filter);
-    const { match } = useGlobalSearch();
-    const builder = useMemo(() => new QueryBuilder(), []);
-    const handleChange = useCallback((value) => {
-      setFilter(builder.build(value).filter);
-    }, []);
-    const showToolbar = role === "article";
-    if (!space || !model) {
-      return null;
-    }
-    return /* @__PURE__ */ React.createElement(StackItem.Content, {
-      toolbar: showToolbar
-    }, showToolbar && /* @__PURE__ */ React.createElement(Toolbar.Root, null, /* @__PURE__ */ React.createElement(QueryEditor, {
-      db: space.db,
-      onChange: handleChange
-    })), /* @__PURE__ */ React.createElement(D3ForceGraph, {
-      model,
-      match
-    }));
-  } finally {
-    _effect.f();
-  }
-};
-var ExplorerContainer_default = ExplorerContainer;
-export {
-  ExplorerContainer_default as default
-};
-//# sourceMappingURL=ExplorerContainer-NOLLVUTE.mjs.map

package/dist/lib/browser/ExplorerContainer-NOLLVUTE.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/components/ExplorerContainer.tsx"],
-  "sourcesContent": ["//\n// Copyright 2023 DXOS.org\n//\n\nimport React, { useCallback, useMemo, useState } from 'react';\n\nimport { type Filter } from '@dxos/echo';\nimport { QueryBuilder } from '@dxos/echo-query';\nimport { useGlobalSearch } from '@dxos/plugin-search';\nimport { getSpace } from '@dxos/react-client/echo';\nimport { Toolbar } from '@dxos/react-ui';\nimport { QueryEditor, type QueryEditorProps } from '@dxos/react-ui-components';\nimport { StackItem } from '@dxos/react-ui-stack';\nimport { type View } from '@dxos/schema';\n\nimport { useGraphModel } from '../hooks';\n\nimport { D3ForceGraph } from './Graph';\n\ntype ExplorerContainerProps = {\n  role: string;\n  view: View.View;\n};\n\nconst ExplorerContainer = ({ role, view }: ExplorerContainerProps) => {\n  const space = getSpace(view);\n  const [filter, setFilter] = useState<Filter.Any>();\n  const model = useGraphModel(space, filter);\n  const { match } = useGlobalSearch();\n\n  const builder = useMemo(() => new QueryBuilder(), []);\n  const handleChange = useCallback<NonNullable<QueryEditorProps['onChange']>>((value) => {\n    setFilter(builder.build(value).filter);\n  }, []);\n\n  const showToolbar = role === 'article';\n\n  if (!space || !model) {\n    return null;\n  }\n\n  return (\n    <StackItem.Content toolbar={showToolbar}>\n      {showToolbar && (\n        <Toolbar.Root>\n          <QueryEditor db={space.db} onChange={handleChange} />\n        </Toolbar.Root>\n      )}\n      <D3ForceGraph model={model} match={match} />\n    </StackItem.Content>\n  );\n};\n\nexport default ExplorerContainer;\n"],
-  "mappings": ";;;;;;;;;;AAIA,OAAOA,SAASC,aAAaC,SAASC,gBAAgB;AAGtD,SAASC,oBAAoB;AAC7B,SAASC,uBAAuB;AAChC,SAASC,gBAAgB;AACzB,SAASC,eAAe;AACxB,SAASC,mBAA0C;AACnD,SAASC,iBAAiB;AAY1B,IAAMC,oBAAoB,CAAC,EAAEC,MAAMC,KAAI,MAA0B;;;AAC/D,UAAMC,QAAQC,SAASF,IAAAA;AACvB,UAAM,CAACG,QAAQC,SAAAA,IAAaC,SAAAA;AAC5B,UAAMC,QAAQC,cAAcN,OAAOE,MAAAA;AACnC,UAAM,EAAEK,MAAK,IAAKC,gBAAAA;AAElB,UAAMC,UAAUC,QAAQ,MAAM,IAAIC,aAAAA,GAAgB,CAAA,CAAE;AACpD,UAAMC,eAAeC,YAAuD,CAACC,UAAAA;AAC3EX,gBAAUM,QAAQM,MAAMD,KAAAA,EAAOZ,MAAM;IACvC,GAAG,CAAA,CAAE;AAEL,UAAMc,cAAclB,SAAS;AAE7B,QAAI,CAACE,SAAS,CAACK,OAAO;AACpB,aAAO;IACT;AAEA,WACE,sBAAA,cAACY,UAAUC,SAAO;MAACC,SAASH;OACzBA,eACC,sBAAA,cAACI,QAAQC,MAAI,MACX,sBAAA,cAACC,aAAAA;MAAYC,IAAIvB,MAAMuB;MAAIC,UAAUZ;SAGzC,sBAAA,cAACa,cAAAA;MAAapB;MAAcE;;;;;AAGlC;AAEA,IAAA,4BAAeV;",
-  "names": ["React", "useCallback", "useMemo", "useState", "QueryBuilder", "useGlobalSearch", "getSpace", "Toolbar", "QueryEditor", "StackItem", "ExplorerContainer", "role", "view", "space", "getSpace", "filter", "setFilter", "useState", "model", "useGraphModel", "match", "useGlobalSearch", "builder", "useMemo", "QueryBuilder", "handleChange", "useCallback", "value", "build", "showToolbar", "StackItem", "Content", "toolbar", "Toolbar", "Root", "QueryEditor", "db", "onChange", "D3ForceGraph"]
-}

package/dist/lib/browser/chunk-2MKBRIUT.mjs

@@ -1,31 +0,0 @@
-// src/hooks/useGraphModel.ts
-import { useEffect, useState } from "react";
-import { SpaceGraphModel } from "@dxos/schema";
-var useGraphModel = (space, filter, options, queue) => {
-  const [model, setModel] = useState(void 0);
-  useEffect(() => {
-    if (!space) {
-      void model?.close();
-      setModel(void 0);
-      return;
-    }
-    if (!model || model.queue !== queue) {
-      const model2 = new SpaceGraphModel().setFilter(filter).setOptions(options);
-      void model2.open(space, queue);
-      setModel(model2);
-    } else {
-      model.setFilter(filter).setOptions(options);
-    }
-  }, [
-    space,
-    filter,
-    options,
-    queue
-  ]);
-  return model;
-};
-
-export {
-  useGraphModel
-};
-//# sourceMappingURL=chunk-2MKBRIUT.mjs.map

package/dist/lib/browser/chunk-2MKBRIUT.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/hooks/useGraphModel.ts"],
-  "sourcesContent": ["//\n// Copyright 2023 DXOS.org\n//\n\nimport { useEffect, useState } from 'react';\n\nimport { type Filter, type Queue, type Space } from '@dxos/client/echo';\nimport { SpaceGraphModel, type SpaceGraphModelOptions } from '@dxos/schema';\n\n// TODO(burdon): Factor out.\nexport const useGraphModel = (\n  space: Space | undefined,\n  filter?: Filter.Any | undefined,\n  options?: SpaceGraphModelOptions,\n  queue?: Queue,\n): SpaceGraphModel | undefined => {\n  const [model, setModel] = useState<SpaceGraphModel | undefined>(undefined);\n  useEffect(() => {\n    if (!space) {\n      void model?.close();\n      setModel(undefined);\n      return;\n    }\n\n    // TODO(burdon): Does this need to be a dependency?\n    if (!model || model.queue !== queue) {\n      const model = new SpaceGraphModel().setFilter(filter).setOptions(options);\n      void model.open(space, queue);\n      setModel(model);\n    } else {\n      model.setFilter(filter).setOptions(options);\n    }\n  }, [space, filter, options, queue]);\n\n  return model;\n};\n"],
-  "mappings": ";AAIA,SAASA,WAAWC,gBAAgB;AAGpC,SAASC,uBAAoD;AAGtD,IAAMC,gBAAgB,CAC3BC,OACAC,QACAC,SACAC,UAAAA;AAEA,QAAM,CAACC,OAAOC,QAAAA,IAAYC,SAAsCC,MAAAA;AAChEC,YAAU,MAAA;AACR,QAAI,CAACR,OAAO;AACV,WAAKI,OAAOK,MAAAA;AACZJ,eAASE,MAAAA;AACT;IACF;AAGA,QAAI,CAACH,SAASA,MAAMD,UAAUA,OAAO;AACnC,YAAMC,SAAQ,IAAIM,gBAAAA,EAAkBC,UAAUV,MAAAA,EAAQW,WAAWV,OAAAA;AACjE,WAAKE,OAAMS,KAAKb,OAAOG,KAAAA;AACvBE,eAASD,MAAAA;IACX,OAAO;AACLA,YAAMO,UAAUV,MAAAA,EAAQW,WAAWV,OAAAA;IACrC;EACF,GAAG;IAACF;IAAOC;IAAQC;IAASC;GAAM;AAElC,SAAOC;AACT;",
-  "names": ["useEffect", "useState", "SpaceGraphModel", "useGraphModel", "space", "filter", "options", "queue", "model", "setModel", "useState", "undefined", "useEffect", "close", "SpaceGraphModel", "setFilter", "setOptions", "open"]
-}