@dxos/plugin-explorer 0.8.4-main.422d1c7879 → 0.8.4-main.43cb759274

package/src/plugin.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const ExplorerPlugin = Plugin.lazy(meta, () => import('#plugin'));

package/src/{components/Tree/testing → testing}/generator.ts

@@ -5,7 +5,7 @@
 import { Key, Obj } from '@dxos/echo';
 import { range } from '@dxos/util';
 
-import { Tree, type TreeNodeType } from '../types';
+import { Tree, type TreeNodeType } from '../components/Tree/types';
 
 type NumberOrNumberArray = number | number[];
 
@@ -16,14 +16,14 @@ 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' };
   });
 
   const createNodes = (parent: TreeNodeType, spec: NumberOrNumberArray = 0): TreeNodeType[] => {
     const count = Array.isArray(spec) ? random(spec[0], spec[1]) : spec;
     return range(count, (i) => ({
-      id: Key.ObjectId.random(),
+      id: Key.EntityId.random(),
       children: [],
       data: {
         text: createText?.() ?? [parent.data.text, i + 1].join('.'),

package/src/testing/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// Eager re-export of `ExplorerPlugin`. See `@dxos/plugin-testing/src/core.ts` for the rationale.
+export * from '../ExplorerPlugin';
+
+export * from './generator';
+export * from './relations';

package/src/testing/relations.ts

@@ -0,0 +1,117 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Space } from '@dxos/client/echo';
+import { Obj, Query, Relation } from '@dxos/echo';
+import {
+  type RelationSpec,
+  type TypeSpec,
+  type ValueGenerator,
+  createObjectFactory,
+  createRelationFactory,
+} from '@dxos/schema/testing';
+import { HasConnection, Organization, Person } from '@dxos/types';
+
+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'];
+
+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 `createRelationFactory` to wire HasConnection relations (Org→Org) between them, spreading
+ * the connections across the available kinds.
+ */
+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 },
+  ];
+
+  await createObjectFactory(space.db, generator)(specs);
+
+  // Distribute the requested connections evenly across the connection kinds.
+  const relationSpecs: RelationSpec[] = CONNECTION_KINDS.map((kind, index) => ({
+    type: HasConnection.HasConnection,
+    count:
+      Math.floor(connectionCount / CONNECTION_KINDS.length) +
+      (index < connectionCount % CONNECTION_KINDS.length ? 1 : 0),
+    data: { kind },
+  }));
+  const connections = await createRelationFactory(space.db, generator)(relationSpecs);
+
+  const organizations = await space.db.query(Query.type(Organization.Organization)).run();
+  const people = await space.db.query(Query.type(Person.Person)).run();
+  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) ?? [],
+    })),
+  };
+};
+
+/**
+ * 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,7 +4,7 @@
 
 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';

package/src/types/ExplorerAction.ts

@@ -4,7 +4,7 @@
 
 import * as Schema from 'effect/Schema';
 
-import { TypeInputOptionsAnnotation } from '@dxos/plugin-space/types';
+import { TypeInputOptionsAnnotation } from '@dxos/plugin-space';
 
 export const GraphProps = Schema.Struct({
   name: Schema.optional(Schema.String),

package/src/types/Graph.ts

@@ -4,33 +4,25 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Annotation, Filter, Obj, Query, QueryAST, Ref, Type } from '@dxos/echo';
-import { View } from '@dxos/echo';
+import { DXN, Annotation, Filter, Obj, Query, QueryAST, Ref, Type, View } from '@dxos/echo';
 import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/internal';
 import { ViewAnnotation } from '@dxos/schema';
 
 const GraphSchema = Schema.Struct({
   name: Schema.optional(Schema.String),
-
   view: Ref.Ref(View.View).pipe(FormInputAnnotation.set(false)),
-
   query: Schema.Struct({
     raw: Schema.optional(Schema.String),
     ast: QueryAST.Query,
   }).pipe(FormInputAnnotation.set(false)),
 }).pipe(
-  Type.object({
-    typename: 'org.dxos.type.graph',
-    version: '0.1.0',
-  }),
   LabelAnnotation.set(['name']),
-  ViewAnnotation.set(true),
-  Annotation.IconAnnotation.set({
-    icon: 'ph--graph--regular',
-    hue: 'green',
-  }),
+  ViewAnnotation.set(['view']),
+  Annotation.IconAnnotation.set({ icon: 'ph--graph--regular', hue: 'green' }),
+  Type.makeObject(DXN.make('org.dxos.type.graph', '0.1.0')),
 );
-export interface Graph extends Schema.Schema.Type<typeof GraphSchema> {}
+// TODO(wittjosiah): Try to clean up this type inference.
+export interface Graph extends Type.InstanceType<typeof GraphSchema> {}
 export const Graph: Type.Obj<Graph> = GraphSchema as any;
 
 type MakeProps = Omit<Partial<Obj.MakeProps<typeof Graph>>, 'view'> & {

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/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+//
+// Copyright 2026 DXOS.org
+//
+
+declare module '*.mdl?raw' {
+  const content: string;
+  export default content;
+}

package/dist/lib/browser/chunk-LSUP47BZ.mjs

@@ -1,24 +0,0 @@
-// src/meta.ts
-import { trim } from "@dxos/util";
-var meta = {
-  id: "org.dxos.plugin.explorer",
-  name: "Explorer",
-  description: trim`
-    Interactive hypergraph visualization that reveals relationships between objects in your workspace.
-    Navigate complex data structures and discover connections through a dynamic network view.
-  `,
-  icon: "ph--graph--regular",
-  iconHue: "green",
-  source: "https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-explorer",
-  tags: [
-    "labs"
-  ],
-  screenshots: [
-    "https://dxos.network/plugin-details-explorer-dark.png"
-  ]
-};
-
-export {
-  meta
-};
-//# sourceMappingURL=chunk-LSUP47BZ.mjs.map

package/dist/lib/browser/chunk-LSUP47BZ.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/meta.ts"],
-  "sourcesContent": ["//\n// Copyright 2023 DXOS.org\n//\n\nimport { type Plugin } from '@dxos/app-framework';\nimport { trim } from '@dxos/util';\n\nexport const meta: Plugin.Meta = {\n  id: 'org.dxos.plugin.explorer',\n  name: 'Explorer',\n  description: trim`\n    Interactive hypergraph visualization that reveals relationships between objects in your workspace.\n    Navigate complex data structures and discover connections through a dynamic network view.\n  `,\n  icon: 'ph--graph--regular',\n  iconHue: 'green',\n  source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-explorer',\n  tags: ['labs'],\n  screenshots: ['https://dxos.network/plugin-details-explorer-dark.png'],\n};\n"],
-  "mappings": ";AAKA,SAASA,YAAY;AAEd,IAAMC,OAAoB;EAC/BC,IAAI;EACJC,MAAM;EACNC,aAAaC;;;;EAIbC,MAAM;EACNC,SAAS;EACTC,QAAQ;EACRC,MAAM;IAAC;;EACPC,aAAa;IAAC;;AAChB;",
-  "names": ["trim", "meta", "id", "name", "description", "trim", "icon", "iconHue", "source", "tags", "screenshots"]
-}