@dxos/plugin-space 0.8.4-main.c4373fc → 0.8.4-main.c85a9c8dae

package/src/containers/SyncStatus/SyncStatus.tsx

@@ -0,0 +1,153 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { useEffect, useState } from 'react';
+
+import { StatusBar } from '@dxos/plugin-status-bar';
+import { EdgeStatus } from '@dxos/protocols/proto/dxos/client/services';
+import { type QueryEdgeStatusResponse } from '@dxos/protocols/proto/dxos/client/services';
+import { useClient } from '@dxos/react-client';
+import { useStream } from '@dxos/react-client/devtools';
+import { type SpaceSyncStateMap, getSyncSummary, useSyncState } from '@dxos/react-client/echo';
+import { Icon, Popover, useTranslation } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+import { Unit, type UnitFormat } from '@dxos/util';
+
+import { createClientSaveTracker, getIcon, getStatus } from '../../components';
+import { meta } from '../../meta';
+
+const SYNC_STALLED_TIMEOUT = 5_000;
+
+export const SyncStatus = () => {
+  const client = useClient();
+  const state = useSyncState();
+  const [saved, setSaved] = useState(true);
+  useEffect(() => createClientSaveTracker(client, (state) => setSaved(state === 'saved')), []);
+
+  return <SyncStatusIndicator state={state} saved={saved} />;
+};
+
+export const SyncStatusIndicator = ({ state, saved }: { state: SpaceSyncStateMap; saved: boolean }) => {
+  const { t } = useTranslation(meta.id);
+  const summary = getSyncSummary(state);
+  const offline = Object.values(state).length === 0;
+  const needsToUpload = summary.differentDocuments > 0 || summary.missingOnRemote > 0;
+  const needsToDownload = summary.differentDocuments > 0 || summary.missingOnLocal > 0;
+  const status = getStatus({ offline, saved, needsToUpload, needsToDownload });
+
+  const [classNames, setClassNames] = useState<string>();
+  useEffect(() => {
+    setClassNames(undefined);
+    if (offline || (!needsToUpload && !needsToDownload)) {
+      return;
+    }
+
+    const t = setTimeout(() => {
+      // TODO(wittjosiah): Use semantic color tokens.
+      setClassNames('text-orange-500');
+    }, SYNC_STALLED_TIMEOUT);
+    return () => clearTimeout(t);
+  }, [offline, needsToUpload, needsToDownload]);
+
+  const title = t(`${status} label`);
+  const icon = <Icon icon={getIcon(status)} classNames={classNames} />;
+
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <StatusBar.Item title={title}>{icon}</StatusBar.Item>
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Content>
+          <EdgeConnectionPopover />
+          <Popover.Arrow />
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+};
+
+const useEdgeStatus = (): EdgeStatus | undefined => {
+  const client = useClient();
+  const { status } = useStream(
+    () => client.services.services.EdgeAgentService!.queryEdgeStatus(),
+    {} as QueryEdgeStatusResponse,
+  );
+  return status;
+};
+
+const EdgeConnectionPopover = () => {
+  const status = useEdgeStatus();
+  const { t } = useTranslation(meta.id);
+
+  const isConnected = status?.state === EdgeStatus.ConnectionState.CONNECTED;
+
+  return (
+    <div className='min-w-[240px] p-2'>
+      {/* Connection Status Header */}
+      <div className='flex items-center gap-2 mb-2'>
+        <Icon
+          icon={isConnected ? 'ph--check-circle--regular' : 'ph--warning-circle--regular'}
+          classNames={mx(isConnected ? 'text-success-text' : 'text-error-text animate-pulse')}
+        />
+        <span className='font-medium text-sm'>
+          {isConnected ? t('sync edge connected label') : t('sync edge disconnected label')}
+        </span>
+      </div>
+
+      {/* Connection Details */}
+      {status?.state === EdgeStatus.ConnectionState.NOT_CONNECTED && (
+        <div className='flex items-center gap-2 text-sm text-description'>
+          <Icon icon='ph--cloud-x--regular' />
+          <span>{t('sync no connection label')}</span>
+        </div>
+      )}
+
+      {status?.state === EdgeStatus.ConnectionState.CONNECTED && (
+        <div className='space-y-2'>
+          {/* Latency */}
+          <div className='flex items-center justify-between text-sm'>
+            <div className='flex items-center gap-2 text-description'>
+              <Icon icon='ph--timer--regular' />
+              <span>{t('sync latency label')}</span>
+            </div>
+            <UnitValue value={status.rtt} format={Unit.Millisecond} />
+          </div>
+
+          {/* Upload Speed */}
+          <div className='flex items-center justify-between text-sm'>
+            <div className='flex items-center gap-2 text-description'>
+              <Icon icon='ph--arrow-up--regular' />
+              <span>{t('sync upload label')}</span>
+            </div>
+            <UnitValue value={status.rateBytesUp} format={Unit.Kilobyte} suffix='/s' />
+          </div>
+
+          {/* Download Speed */}
+          <div className='flex items-center justify-between text-sm'>
+            <div className='flex items-center gap-2 text-sm text-description'>
+              <Icon icon='ph--arrow-down--regular' />
+              <span>{t('sync download label')}</span>
+            </div>
+            <UnitValue value={status.rateBytesDown} format={Unit.Kilobyte} suffix='/s' />
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};
+
+// TODO(burdon): Factor out.
+const UnitValue = ({ value: input, format, suffix }: { value: number; format: UnitFormat; suffix?: string }) => {
+  const { formattedValue, unit } = format(input);
+  return (
+    <span className='font-mono'>
+      {formattedValue}
+      <span className='ms-1 text-subdued'>
+        {unit.symbol}
+        {suffix}
+      </span>
+    </span>
+  );
+};

package/src/containers/SyncStatus/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { SyncStatus } from './SyncStatus';
+
+export default SyncStatus;

package/src/containers/ViewEditor/ViewEditor.tsx

@@ -0,0 +1,103 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import React, { useCallback, useState } from 'react';
+
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { DXN, Filter, JsonSchema, Obj, Query, type QueryAST, Tag, Type } from '@dxos/echo';
+import { type View } from '@dxos/echo';
+import { type Mutable } from '@dxos/echo/internal';
+import { useClient } from '@dxos/react-client';
+import { getSpace, useQuery } from '@dxos/react-client/echo';
+import { useAsyncEffect } from '@dxos/react-ui';
+import { ViewEditor as NaturalViewEditor } from '@dxos/react-ui-form';
+import { ViewModel } from '@dxos/schema';
+
+import { resolveSchemaWithRegistry } from '../../helpers';
+import { useTypeOptions } from '../../hooks';
+import { SpaceOperation } from '../../types';
+
+export type ViewEditorProps = { view: View.View };
+
+export const ViewEditor = ({ view }: ViewEditorProps) => {
+  const { invokePromise } = useOperationInvoker();
+  const client = useClient();
+  const space = getSpace(view);
+  const [schema, setSchema] = useState<Schema.Schema.AnyNoContext>(() => Schema.Struct({}));
+  const tags = useQuery(space?.db, Filter.type(Tag.Tag));
+  const types = useTypeOptions({
+    space,
+    annotation: {
+      location: ['database', 'runtime'],
+      kind: ['user'],
+      registered: ['registered'],
+    },
+  });
+
+  useAsyncEffect(async () => {
+    if (!view?.query || !space) {
+      return;
+    }
+
+    const foundSchema = await resolveSchemaWithRegistry(space.db.schemaRegistry, view.query.ast);
+    if (foundSchema && foundSchema !== schema) {
+      setSchema(() => foundSchema);
+    }
+  }, [client, space, view, schema]);
+
+  const handleQueryChanged = useCallback(
+    async (newQuery: QueryAST.Query, target?: string) => {
+      if (!view || !space) {
+        return;
+      }
+
+      const queue = target && DXN.tryParse(target) ? target : undefined;
+      const query = queue ? Query.fromAst(newQuery).from({ queues: [queue] }) : Query.fromAst(newQuery);
+      Obj.change(view, (v) => {
+        v.query.ast = query.ast as Mutable<typeof query.ast>;
+      });
+      const newSchema = await resolveSchemaWithRegistry(space.db.schemaRegistry, query.ast);
+      if (!newSchema) {
+        return;
+      }
+
+      const newView = ViewModel.make({
+        query,
+        jsonSchema: JsonSchema.toJsonSchema(newSchema),
+      });
+      Obj.change(view, (v) => {
+        v.projection = Obj.getSnapshot(newView).projection as Mutable<typeof v.projection>;
+      });
+
+      setSchema(() => newSchema);
+    },
+    [view, schema],
+  );
+
+  const handleDelete = useCallback(
+    (fieldId: string) => {
+      void invokePromise(SpaceOperation.DeleteField, { view, fieldId });
+    },
+    [invokePromise, view],
+  );
+
+  if (!space || !schema) {
+    return null;
+  }
+
+  return (
+    <NaturalViewEditor
+      registry={space.db.schemaRegistry}
+      schema={schema}
+      view={view}
+      mode='tag'
+      db={space.db}
+      tags={tags}
+      types={types}
+      onQueryChanged={handleQueryChanged}
+      onDelete={Type.isMutable(schema) ? handleDelete : undefined}
+    />
+  );
+};

package/src/containers/ViewEditor/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { ViewEditor } from './ViewEditor';
+
+export default ViewEditor;

package/src/containers/index.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export type { CreateObjectDialogProps } from './CreateObjectDialog/CreateObjectDialog';
+
+export const CollectionArticle: ComponentType<any> = lazy(() => import('./CollectionArticle'));
+export const CollectionSection: ComponentType<any> = lazy(() => import('./CollectionSection'));
+export const CreateObjectDialog: ComponentType<any> = lazy(() => import('./CreateObjectDialog'));
+export const CreateSpaceDialog: ComponentType<any> = lazy(() => import('./CreateSpaceDialog'));
+export const InlineSyncStatus: ComponentType<any> = lazy(() => import('./InlineSyncStatus'));
+export const JoinDialog: ComponentType<any> = lazy(() => import('./JoinDialog'));
+export const MembersContainer: ComponentType<any> = lazy(() => import('./MembersContainer'));
+export const MenuFooter: ComponentType<any> = lazy(() => import('./MenuFooter'));
+export const ObjectCardStack: ComponentType<any> = lazy(() => import('./ObjectCardStack'));
+export const ObjectDetails: ComponentType<any> = lazy(() => import('./ObjectDetails'));
+export const ObjectRenamePopover: ComponentType<any> = lazy(() => import('./ObjectRenamePopover'));
+export const RecordArticle: ComponentType<any> = lazy(() => import('./RecordArticle'));
+export const SchemaContainer: ComponentType<any> = lazy(() => import('./SchemaContainer'));
+export const SmallPresenceLive: ComponentType<any> = lazy(() => import('./SmallPresenceLive'));
+export const SpacePluginSettings: ComponentType<any> = lazy(() => import('./SpacePluginSettings'));
+export const SpacePresence: ComponentType<any> = lazy(() => import('./SpacePresence'));
+export const SpaceRenamePopover: ComponentType<any> = lazy(() => import('./SpaceRenamePopover'));
+export const SpaceSettingsContainer: ComponentType<any> = lazy(() => import('./SpaceSettingsContainer'));
+export const SyncStatus: ComponentType<any> = lazy(() => import('./SyncStatus'));
+export const ViewEditor: ComponentType<any> = lazy(() => import('./ViewEditor'));

package/src/helpers/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './query';

package/src/helpers/query.test.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from 'vitest';
+
+import { evalQuery } from './query';
+
+describe('evalQuery', () => {
+  it('should evaluate a query string', () => {
+    const query = evalQuery('Query.select(Filter.type(Person.Person))');
+    expect(query.ast).toMatchInlineSnapshot(`
+      {
+        "filter": {
+          "id": undefined,
+          "props": {},
+          "type": "object",
+          "typename": "dxn:type:dxos.org/type/Person:0.1.0",
+        },
+        "type": "select",
+      }
+    `);
+  });
+});

package/src/helpers/query.ts

@@ -0,0 +1,166 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Array from 'effect/Array';
+import * as Effect from 'effect/Effect';
+import * as EffectFunction from 'effect/Function';
+import * as Match from 'effect/Match';
+import * as Option from 'effect/Option';
+import type * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { DXN, Filter, Key, Query, type QueryAST, type SchemaRegistry } from '@dxos/echo';
+import {
+  ReferenceAnnotationId,
+  type ReferenceAnnotationValue,
+  getTypeAnnotation,
+  unwrapOptional,
+} from '@dxos/echo/internal';
+import { runAndForwardErrors } from '@dxos/effect';
+import { log } from '@dxos/log';
+import { type Space } from '@dxos/react-client/echo';
+import { Person } from '@dxos/types';
+
+// TODO(wittjosiah): Factor out and add tests.
+// TODO(wittjosiah): Support arbitrary type imports.
+export const evalQuery = (queryString: string): Query.Any => {
+  const globals = { Query, Filter, Person };
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval
+    return new Function(...Object.keys(globals), `return ${queryString}`)(...Object.values(globals));
+  } catch (err) {
+    log.catch(err);
+    return Query.select(Filter.nothing());
+  }
+};
+
+export const resolveSchemaWithRegistry = (registry: SchemaRegistry.SchemaRegistry, query: QueryAST.Query) => {
+  const resolve = Effect.fn(function* (dxn: string) {
+    const typename = DXN.parse(dxn).asTypeDXN()?.type;
+    if (!typename) {
+      return Option.none();
+    }
+
+    const query = registry.query({ typename, location: ['database', 'runtime'] });
+    const schemas = yield* Effect.promise(() => query.run());
+    return Array.head(schemas);
+  });
+
+  return resolveSchema(query, resolve).pipe(
+    Effect.map((schema) => Option.getOrUndefined(schema)),
+    runAndForwardErrors,
+  );
+};
+
+const resolveSchema = (
+  query: QueryAST.Query,
+  resolve: (dxn: string) => Effect.Effect<Option.Option<Schema.Schema.AnyNoContext>>,
+): Effect.Effect<Option.Option<Schema.Schema.AnyNoContext>> => {
+  return Match.value(query).pipe(
+    Match.withReturnType<Effect.Effect<Option.Option<Schema.Schema.AnyNoContext>>>(),
+    // TODO(wittjosiah): Reconcile with filter match?
+    Match.when({ type: 'select' }, ({ filter }) =>
+      typenameFromFilter(filter).pipe(
+        Option.map((typename) => resolve(typename)),
+        Option.getOrElse(() => Effect.succeed(Option.none<Schema.Schema.AnyNoContext>())),
+      ),
+    ),
+    Match.when({ type: 'filter' }, ({ filter }) =>
+      typenameFromFilter(filter).pipe(
+        Option.map((typename) => resolve(typename)),
+        Option.getOrElse(() => Effect.succeed(Option.none<Schema.Schema.AnyNoContext>())),
+      ),
+    ),
+    Match.when({ type: 'reference-traversal' }, ({ anchor, property }) =>
+      resolveSchema(anchor, resolve).pipe(
+        Effect.map((base) =>
+          base.pipe(
+            Option.map((schema) => SchemaAST.getPropertySignatures(schema.ast)),
+            Option.flatMap((properties) => Array.findFirst(properties, (p) => p.name === property)),
+            Option.flatMap((property) =>
+              SchemaAST.getAnnotation<ReferenceAnnotationValue>(ReferenceAnnotationId)(unwrapOptional(property)),
+            ),
+            Option.map((annotation) => annotation.typename),
+          ),
+        ),
+        Effect.flatMap(
+          Option.match({
+            onNone: () => Effect.succeed(Option.none()),
+            onSome: (typename) => resolve(DXN.fromTypename(typename).toString()),
+          }),
+        ),
+      ),
+    ),
+    Match.when({ type: 'relation', filter: Match.defined }, ({ filter }) =>
+      typenameFromFilter(filter).pipe(
+        Option.map((typename) => resolve(typename)),
+        Option.getOrElse(() => Effect.succeed(Option.none<Schema.Schema.AnyNoContext>())),
+      ),
+    ),
+    Match.when({ type: 'relation-traversal' }, ({ anchor, direction }) =>
+      resolveSchema(anchor, resolve).pipe(
+        Effect.map((base) =>
+          base.pipe(
+            Option.map((schema) => getTypeAnnotation(schema)),
+            Option.flatMap((annotation) =>
+              Option.fromNullable(direction === 'source' ? annotation?.sourceSchema : annotation?.targetSchema),
+            ),
+          ),
+        ),
+        Effect.flatMap(
+          Option.match({
+            onNone: () => Effect.succeed(Option.none()),
+            onSome: (typename) => resolve(typename),
+          }),
+        ),
+      ),
+    ),
+    Match.when({ type: 'options' }, ({ query }) => resolveSchema(query, resolve)),
+    Match.orElse((_q) => {
+      // TODO(wittjosiah): Implement other cases.
+      return Effect.succeed(Option.none());
+    }),
+  );
+};
+
+const typenameFromFilter = (filter: QueryAST.Filter): Option.Option<string> =>
+  Match.value(filter).pipe(
+    Match.withReturnType<Option.Option<string>>(),
+    Match.when({ type: 'object' }, ({ typename }) => Option.fromNullable(typename)),
+    Match.when({ type: 'and' }, ({ filters }) =>
+      EffectFunction.pipe(filters, Array.map(typenameFromFilter), Array.findFirst(Option.isSome), Option.flatten),
+    ),
+    Match.when({ type: 'or' }, ({ filters }) =>
+      EffectFunction.pipe(filters, Array.map(typenameFromFilter), Array.findFirst(Option.isSome), Option.flatten),
+    ),
+    Match.orElse(() => Option.none()),
+  );
+
+// TODO(wittjosiah): Currently assumes from scope is at the top-level of the ast.
+export const getQueryTarget = (query: QueryAST.Query, space?: Space) => {
+  return Match.value(query).pipe(
+    Match.when({ type: 'from' }, ({ from }) => {
+      if (from._tag !== 'scope') {
+        return space?.db;
+      }
+      const result = Option.fromNullable(from.scope.queues).pipe(
+        Option.flatMap((queues) => Array.head(queues)),
+        Option.flatMap((queueDxn) => Option.fromNullable(DXN.tryParse(String(queueDxn)))),
+        Option.flatMap((parsed) => {
+          const q = parsed.asQueueDXN();
+          if (!q || !Key.ObjectId.isValid(q.queueId)) return Option.none();
+          return Option.fromNullable(space?.queues.get(parsed));
+        }),
+      );
+      // Skip query when a requested queue is not found (structurally invalid DXN or valid DXN
+      // referencing a queue not present in space.queues, e.g. not yet synced) to avoid 400 errors.
+      // TODO(wittjosiah): Can we handle this upstream?
+      if (from.scope.queues?.length && Option.isNone(result)) {
+        return undefined;
+      }
+      return Option.getOrElse(result, () => space?.db);
+    }),
+    Match.orElse(() => space?.db),
+  );
+};

package/src/hooks/index.ts

@@ -5,3 +5,4 @@
 export * from './useActiveSpace';
 export * from './useInputSurfaceLookup';
 export * from './usePath';
+export * from './useTypeOptions';

package/src/hooks/useActiveSpace.ts

@@ -2,13 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Capabilities, type PluginContext, useLayout } from '@dxos/app-framework';
+import { Capabilities, type CapabilityManager } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { useLayout } from '@dxos/app-toolkit/ui';
 import { ClientCapabilities } from '@dxos/plugin-client';
 import { parseId, useSpace } from '@dxos/react-client/echo';
 
-export const getActiveSpace = (context: PluginContext) => {
-  const client = context.getCapability(ClientCapabilities.Client);
-  const layout = context.getCapability(Capabilities.Layout);
+export const getActiveSpace = (capabilities: CapabilityManager.CapabilityManager) => {
+  const client = capabilities.get(ClientCapabilities.Client);
+  const registry = capabilities.get(Capabilities.AtomRegistry);
+  const layoutAtom = capabilities.get(AppCapabilities.Layout);
+  const layout = registry.get(layoutAtom);
   const { spaceId } = parseId(layout.workspace);
   return spaceId ? client.spaces.get(spaceId) : undefined;
 };

package/src/hooks/useInputSurfaceLookup.tsx

@@ -2,29 +2,25 @@
 // Copyright 2025 DXOS.org
 //
 
-import type * as Schema from 'effect/Schema';
 import React, { useCallback } from 'react';
 
-import { Surface, isSurfaceAvailable, usePluginManager } 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} />;
       }
-
-      return <Surface role='form-input' data={composedData} {...inputProps} />;
     },
     [pluginManager, baseData],
   );

package/src/hooks/usePath.ts

@@ -5,7 +5,7 @@
 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/useTypeOptions.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { type Space } from '@dxos/react-client/echo';
+import { useTranslation } from '@dxos/react-ui';
+
+import { type TypeInputOptions, getTypenames } from '../types';
+
+export const useTypeOptions = ({ space, annotation }: { space?: Space; annotation: TypeInputOptions }) => {
+  const { t } = useTranslation();
+  const typenames = getTypenames({ annotation, space });
+  return useMemo(
+    () =>
+      typenames
+        .map((typename) => ({
+          value: typename,
+          label: t('typename label', { ns: typename, defaultValue: typename }),
+        }))
+        .toSorted((a, b) => a.label.localeCompare(b.label)),
+    [t, typenames],
+  );
+};

package/src/index.ts

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

package/src/meta.ts

@@ -2,10 +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 meta: PluginMeta = {
+export const meta: Plugin.Meta = {
   id: 'dxos.org/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',
 };