@dxos/plugin-space 0.8.4-main.f9ba587 → 0.8.4-main.fcfe5033a5

package/src/hooks/useInputSurfaceLookup.tsx

@@ -2,29 +2,25 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Schema } from 'effect';
 import React, { useCallback } from 'react';
 
-import { usePluginManager, isSurfaceAvailable, Surface } from '@dxos/app-framework';
-import { type InputProps } from '@dxos/react-ui-form';
+import { Surface, usePluginManager } from '@dxos/app-framework/ui';
+import { type FormFieldProvider } from '@dxos/react-ui-form';
 
-// TODO(ZaymonFC): Move this if you find yourself needing it elsewhere.
 /**
  * Creates a surface input component based on plugin context.
  * @param baseData Additional data that will be merged with form data and passed to the surface.
  * This allows providing more context to the surface than what's available from the form itself.
  */
-export const useInputSurfaceLookup = (baseData?: Record<string, any>) => {
+// TODO(burdon): Factor out?
+export const useInputSurfaceLookup = (baseData?: Record<string, any>): FormFieldProvider => {
   const pluginManager = usePluginManager();
-
-  return useCallback(
-    ({ prop, schema, inputProps }: { prop: string; schema: Schema.Schema<any>; inputProps: InputProps }) => {
-      const composedData = { prop, schema, ...baseData };
-      if (!isSurfaceAvailable(pluginManager.context, { role: 'form-input', data: composedData })) {
-        return undefined;
+  return useCallback<FormFieldProvider>(
+    ({ schema, prop, fieldProps }) => {
+      const data = { prop, schema, ...baseData };
+      if (Surface.isAvailable(pluginManager.capabilities, { role: 'form-input', data })) {
+        return <Surface.Surface role='form-input' data={data} {...(fieldProps as Record<string, any>)} />;
       }
-
-      return <Surface role='form-input' data={composedData} {...inputProps} />;
     },
     [pluginManager, baseData],
   );

package/src/hooks/usePath.ts

@@ -2,10 +2,10 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Option } from 'effect';
+import * as Option from 'effect/Option';
 import { useEffect, useState } from 'react';
 
-import { type ReadableGraph } from '@dxos/plugin-graph';
+import { Graph } from '@dxos/plugin-graph';
 
 /**
  * React hook to get a path from the graph.
@@ -16,9 +16,9 @@ import { type ReadableGraph } from '@dxos/plugin-graph';
  * @returns Path if found, undefined otherwise.
  */
 // TODO(wittjosiah): Factor out.
-export const usePath = (graph: ReadableGraph, id?: string, timeout?: number): Option.Option<string[]> => {
+export const usePath = (graph: Graph.ReadableGraph, id?: string, timeout?: number): Option.Option<string[]> => {
   const [pathState, setPathState] = useState<Option.Option<string[]>>(
-    id ? graph.getPath({ target: id }) : Option.none(),
+    id ? Graph.getPath(graph, { target: id }) : Option.none(),
   );
 
   useEffect(() => {
@@ -33,7 +33,7 @@ export const usePath = (graph: ReadableGraph, id?: string, timeout?: number): Op
     // Set timeout did not seem to effectively not block the UI thread.
     const frame = requestAnimationFrame(async () => {
       try {
-        const path = await graph.waitForPath({ target: id }, { timeout });
+        const path = await Graph.waitForPath(graph, { target: id }, { timeout });
         if (path) {
           setPathState(Option.some(path));
         }

package/src/hooks/useRelatedObjects.ts

@@ -0,0 +1,79 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { type Database, Entity, Filter, Obj, Ref, Relation } from '@dxos/echo';
+import { useQuery } from '@dxos/react-client/echo';
+import { isNonNullable } from '@dxos/util';
+
+/**
+ * Returns objects related to `subject` via direct references and/or relations.
+ * Returns an empty array when `subject` is undefined.
+ */
+// TODO(burdon): Factor out (make more generally useful -- e.g., in cards).
+// TODO(wittjosiah): This is a hack. ECHO needs to have a back reference index to easily query for related objects.
+export const useRelatedObjects = (
+  db?: Database.Database,
+  subject?: Obj.Unknown,
+  options: {
+    references?: boolean;
+    relations?: boolean;
+  } = {},
+) => {
+  const objects = useQuery(db, Filter.everything());
+  return useMemo(() => {
+    if (!subject) {
+      return [];
+    }
+
+    const related: Entity.Unknown[] = [];
+
+    // TODO(burdon): Change Person => Organization to relations.
+    if (options.references) {
+      const getReferences = (obj: Entity.Unknown): Ref.Unknown[] => {
+        return Object.getOwnPropertyNames(obj)
+          .map((name) => obj[name as keyof Obj.Unknown])
+          .filter((value) => Ref.isRef(value)) as Ref.Unknown[];
+      };
+
+      const references = getReferences(subject);
+      const referenceTargets = references.map((ref) => ref.target).filter(isNonNullable);
+      const referenceSources = objects.filter((obj) => {
+        const refs = getReferences(obj);
+        return refs.some((ref) => ref.target === subject);
+      });
+
+      related.push(...referenceTargets, ...referenceSources);
+    }
+
+    if (options.relations) {
+      // TODO(dmaretskyi): Workaround until https://github.com/dxos/dxos/pull/10100 lands.
+      const isValidRelation = (obj: Relation.Unknown) => {
+        try {
+          return Relation.isRelation(obj) && Relation.getSource(obj) && Relation.getTarget(obj);
+        } catch {
+          return false;
+        }
+      };
+
+      const relations = objects.filter(Relation.isRelation).filter((obj) => isValidRelation(obj));
+      const targetObjects = relations
+        .filter((relation) => Relation.getTarget(relation) === subject)
+        .map((relation) => Relation.getSource(relation));
+      const sourceObjects = relations
+        .filter((relation) => Relation.getSource(relation) === subject)
+        .map((relation) => Relation.getTarget(relation));
+
+      related.push(...targetObjects, ...sourceObjects);
+    }
+
+    return (
+      Array.from(new Set(related))
+        // TODO(burdon): Configure.
+        .filter((obj) => Entity.getTypename(obj) !== 'org.dxos.type.text')
+        .filter((obj) => Entity.getTypename(obj) !== 'org.dxos.type.assistant.chat')
+    );
+  }, [subject, objects, options.references, options.relations]);
+};

package/src/index.ts

@@ -2,11 +2,10 @@
 // Copyright 2023 DXOS.org
 //
 
-export { SpaceCapabilities } from './capabilities';
-export { SpaceEvents } from './events';
+export { SpaceCapabilities, SpaceEvents } from './types';
 
 export * from './components';
-export * from './hooks';
 export * from './meta';
-export * from './SpacePlugin';
 export * from './util';
+
+export * from './SpacePlugin';

package/src/meta.ts

@@ -2,12 +2,15 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
+import { trim } from '@dxos/util';
 
-export const SPACE_PLUGIN = 'dxos.org/plugin/space';
-
-export const meta: PluginMeta = {
-  id: SPACE_PLUGIN,
+export const meta: Plugin.Meta = {
+  id: 'org.dxos.plugin.space',
   name: 'Spaces',
+  description: trim`
+    Core workspace container system for organizing and sharing collaborative environments.
+    Create, manage, and share spaces with granular access control and invitation management.
+  `,
   icon: 'ph--planet--regular',
 };

package/src/operations/add-object.ts

@@ -0,0 +1,82 @@
+// Copyright 2025 DXOS.org
+
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { getCollectionsPath, getObjectPath, getTypePath } from '@dxos/app-toolkit';
+import { Database, Obj, View } from '@dxos/echo';
+import { Collection } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { Operation } from '@dxos/operation';
+import { ObservabilityOperation } from '@dxos/plugin-observability/operations';
+import { CollectionModel, ViewAnnotation, getTypenameFromQuery } from '@dxos/schema';
+
+import { SpaceOperation } from './definitions';
+
+const handler: Operation.WithHandler<typeof SpaceOperation.AddObject> = SpaceOperation.AddObject.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const target = input.target as any;
+      const object = input.object as Obj.Unknown;
+      const db = Database.isDatabase(target) ? target : Obj.getDatabase(target);
+      invariant(db, 'Database not found.');
+
+      yield* CollectionModel.add({
+        object,
+        target: Database.isDatabase(target) ? undefined : target,
+        hidden: input.hidden,
+      }).pipe(Effect.provide(Database.layer(db)));
+
+      const typename = Obj.getTypename(object)!;
+      yield* Operation.schedule(ObservabilityOperation.SendEvent, {
+        name: 'space.object.add',
+        properties: {
+          spaceId: db.spaceId,
+          objectId: object.id,
+          typename: Obj.getTypename(object),
+        },
+      });
+
+      const [schema] = db.schemaRegistry.query({ typename, location: ['runtime'] }).runSync();
+      const isViewSchema = schema !== undefined && ViewAnnotation.get(schema).pipe(Option.getOrElse(() => false));
+      const view = isViewSchema
+        ? yield* Effect.promise(() => (object as Obj.Any).view.load() as Promise<View.View>)
+        : undefined;
+      const viewTargetTypename = view ? getTypenameFromQuery(view.query.ast) : undefined;
+      const subject = getSubjectPathForNewObject({
+        spaceId: db.spaceId,
+        objectId: object.id,
+        nodeId: input.targetNodeId,
+        typename,
+        viewTargetTypename,
+      });
+
+      return {
+        id: Obj.getDXN(object).toString(),
+        subject: [subject],
+        object,
+      };
+    }),
+  ),
+);
+export default handler;
+
+const getSubjectPathForNewObject = (props: {
+  spaceId: string;
+  objectId: string;
+  nodeId?: string;
+  typename: string;
+  viewTargetTypename?: string;
+}): string => {
+  const { nodeId, typename, viewTargetTypename, spaceId, objectId } = props;
+  if (typeof nodeId === 'string') {
+    return `${nodeId}/${objectId}`;
+  }
+  if (typename === Collection.Collection.typename) {
+    return getCollectionsPath(spaceId, objectId);
+  }
+  if (viewTargetTypename) {
+    return getTypePath(spaceId, viewTargetTypename, objectId);
+  }
+  return getObjectPath(spaceId, typename, objectId);
+};

package/src/operations/add-relation.ts

@@ -0,0 +1,25 @@
+// Copyright 2025 DXOS.org
+
+import * as Effect from 'effect/Effect';
+
+import { Database, Relation } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { SpaceOperation } from './definitions';
+
+const handler: Operation.WithHandler<typeof SpaceOperation.AddRelation> = SpaceOperation.AddRelation.pipe(
+  Operation.withHandler((input) =>
+    Effect.sync(() => {
+      const db = input.db as Database.Database;
+      const relation = db.add(
+        Relation.make(input.schema, {
+          [Relation.Source]: input.source,
+          [Relation.Target]: input.target,
+          ...input.fields,
+        }),
+      );
+      return { relation };
+    }),
+  ),
+);
+export default handler;

package/src/operations/add-schema.ts

@@ -0,0 +1,51 @@
+// Copyright 2025 DXOS.org
+
+import * as Effect from 'effect/Effect';
+
+import { Capability, Plugin } from '@dxos/app-framework';
+import { Obj } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+import { ObservabilityOperation } from '@dxos/plugin-observability/operations';
+
+import { SpaceEvents, SpaceCapabilities } from '../types';
+import { SpaceOperation } from './definitions';
+
+const handler: Operation.WithHandler<typeof SpaceOperation.AddSchema> = SpaceOperation.AddSchema.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const db = input.db;
+      const schemas = yield* Effect.promise(() => db.schemaRegistry.register([input.schema]));
+      const schema = schemas[0];
+      Obj.change(schema.persistentSchema, (obj) => {
+        if (input.name) {
+          obj.name = input.name;
+        }
+        if (input.typename) {
+          obj.typename = input.typename;
+        }
+        if (input.version) {
+          obj.version = input.version;
+        }
+      });
+
+      yield* Plugin.activate(SpaceEvents.SchemaAdded);
+      const onSchemaAdded = yield* Capability.getAll(SpaceCapabilities.OnSchemaAdded);
+      yield* Effect.all(
+        onSchemaAdded.map((callback) => callback({ db, schema, show: input.show })),
+        { concurrency: 'unbounded' },
+      );
+
+      yield* Operation.schedule(ObservabilityOperation.SendEvent, {
+        name: 'space.schema.add',
+        properties: {
+          spaceId: db.spaceId,
+          objectId: schema.id,
+          typename: schema.typename,
+        },
+      });
+
+      return { id: schema.id, object: schema.persistentSchema, schema };
+    }),
+  ),
+);
+export default handler;

package/src/operations/close.ts

@@ -0,0 +1,16 @@
+// Copyright 2025 DXOS.org
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/operation';
+
+import { SpaceOperation } from './definitions';
+
+const handler: Operation.WithHandler<typeof SpaceOperation.Close> = SpaceOperation.Close.pipe(
+  Operation.withHandler((input) =>
+    Effect.promise(async () => {
+      await input.space.close();
+    }),
+  ),
+);
+export default handler;

package/src/operations/create.ts

@@ -0,0 +1,59 @@
+// Copyright 2025 DXOS.org
+
+import * as Effect from 'effect/Effect';
+
+import { Capability, Plugin } from '@dxos/app-framework';
+import { Collection, Obj, Ref } from '@dxos/echo';
+import { Migrations } from '@dxos/migrations';
+import { Operation } from '@dxos/operation';
+import { ClientCapabilities } from '@dxos/plugin-client/types';
+import { ObservabilityOperation } from '@dxos/plugin-observability/operations';
+import { EdgeReplicationSetting } from '@dxos/protocols/proto/dxos/echo/metadata';
+import { iconValues } from '@dxos/react-ui-pickers/icons';
+import { hues } from '@dxos/ui-theme';
+
+import { SpaceEvents, SpaceCapabilities } from '../types';
+import { SpaceOperation } from './definitions';
+import { SpaceOperationConfig } from './helpers';
+
+const handler: Operation.WithHandler<typeof SpaceOperation.Create> = SpaceOperation.Create.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ name, hue: hue_, icon: icon_, edgeReplication }) {
+      const client = yield* Capability.get(ClientCapabilities.Client);
+      const hue = hue_ ?? hues[Math.floor(Math.random() * hues.length)];
+      const icon = icon_ ?? iconValues[Math.floor(Math.random() * iconValues.length)];
+      const space = yield* Effect.promise(() => client.spaces.create({ name, hue, icon }));
+      if (edgeReplication) {
+        yield* Effect.promise(() => space.internal.setEdgeReplicationPreference(EdgeReplicationSetting.ENABLED));
+      }
+      yield* Effect.promise(() => space.waitUntilReady());
+
+      const collection = Obj.make(Collection.Collection, { objects: [] });
+      Obj.change(space.properties, (obj) => {
+        obj[Collection.Collection.typename] = Ref.make(collection);
+        if (Migrations.versionProperty) {
+          obj[Migrations.versionProperty] = Migrations.targetVersion;
+        }
+      });
+
+      yield* Plugin.activate(SpaceEvents.SpaceCreated);
+      const onCreateSpaceCallbacks = yield* Capability.getAll(SpaceCapabilities.OnCreateSpace);
+      yield* Effect.all(
+        onCreateSpaceCallbacks.map((onCreateSpace) =>
+          onCreateSpace({ space, isDefault: false, rootCollection: collection }),
+        ),
+      );
+
+      const { observability } = yield* Capability.get(SpaceOperationConfig);
+      if (observability) {
+        yield* Operation.schedule(ObservabilityOperation.SendEvent, {
+          name: 'space.create',
+          properties: { spaceId: space.id },
+        });
+      }
+
+      return { id: space.id, subject: [space.id], space };
+    }),
+  ),
+);
+export default handler;