@dxos/plugin-space 0.8.4-main.fffef41 → 0.9.0

package/src/capabilities/app-graph-builder/extensions/shared.ts

@@ -0,0 +1,192 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom } from '@effect-atom/atom-react';
+import * as Option from 'effect/Option';
+
+import { type Space, SpaceState, isSpace } from '@dxos/client/echo';
+import { type Operation } from '@dxos/compute';
+import { Annotation, Filter, Obj, Type } from '@dxos/echo';
+import { MigrationVersionAnnotation, Migrations } from '@dxos/migrations';
+import { type Node } from '@dxos/plugin-graph';
+import { type TreeData } from '@dxos/react-ui-list';
+import type { EchoViewRefPath } from '@dxos/schema';
+import { ViewAnnotation, getTypeURIFromQuery } from '@dxos/schema';
+import { type Label } from '@dxos/ui-types/translations';
+
+import { meta } from '#meta';
+
+export {
+  ACCEPT_ECHO_CLASS,
+  CACHEABLE_PROPS,
+  CAN_DROP_OBJECT,
+  blockInstructionCache,
+  buildCollectionPartials,
+  collectionPartialsCache,
+  createFactory,
+  createObjectNode,
+  getAcceptPersistenceKey,
+  getCollectionGraphNodePartials,
+  getDynamicLabel,
+  rearrangeCache,
+} from '@dxos/app-toolkit';
+
+//
+// Virtual Node Types
+//
+
+export const TYPES_SECTION_TYPE = `${meta.id}.types`;
+export const COLLECTIONS_SECTION_TYPE = `${meta.id}.collections`;
+export const TYPE_COLLECTION_TYPE = `${meta.id}.type-collection`;
+export const STATIC_SCHEMA_TYPE = `${meta.id}.static-schema`;
+
+//
+// Constants
+//
+
+/** Shared translation namespace descriptor. */
+export const META_NS: { ns: string } = { ns: meta.id };
+
+//
+// Stable Callbacks
+//
+
+export const BLOCK_REORDER_ABOVE = (_source: TreeData, instruction: any) => instruction.type === 'reorder-above';
+export const CAN_DROP_SPACE = (source: TreeData) => Obj.isObject(source.item.data) || isSpace(source.item.data);
+
+//
+// Caches (space-specific, not moved to app-toolkit)
+//
+
+export const spaceActionsCache = new Map<
+  string,
+  {
+    state: SpaceState;
+    hasPendingMigration: boolean;
+    migrating: boolean;
+    actions: Node.NodeArg<Node.ActionData<Operation.Service>>[];
+  }
+>();
+export const spaceRearrangeCache = new Map<string, (nextOrder: Space[]) => void>();
+
+//
+// Static Labels
+//
+
+export const ADD_VIEW_TO_SCHEMA_LABEL: Label = ['add-view-to-schema.label', META_NS];
+export const COPY_LINK_LABEL: Label = ['copy-link.label', META_NS];
+export const CREATE_OBJECT_IN_COLLECTION_LABEL: Label = ['create-object-in-collection.label', META_NS];
+export const CREATE_OBJECT_IN_SPACE_LABEL: Label = ['create-object-in-space.label', META_NS];
+export const EXPOSE_OBJECT_LABEL: Label = ['expose-object.label', META_NS];
+export const MIGRATE_SPACE_LABEL: Label = ['migrate-space.label', META_NS];
+export const NEW_TYPE_LABEL: Label = ['new-type.label', META_NS];
+export const REMOVE_FROM_COLLECTION_LABEL: Label = ['remove-from-collection.label', META_NS];
+export const RENAME_SPACE_LABEL: Label = ['rename-space.label', META_NS];
+export const SETTINGS_PANEL_LABEL: Label = ['settings-panel.label', META_NS];
+export const SNAPSHOT_BY_SCHEMA_LABEL: Label = ['snapshot-by-schema.label', META_NS];
+
+//
+// Helpers
+//
+
+export const checkPendingMigration = (space: Space) => {
+  return (
+    space.state.get() === SpaceState.SPACE_REQUIRES_MIGRATION ||
+    (space.state.get() === SpaceState.SPACE_READY &&
+      !!Migrations.targetVersion &&
+      Annotation.get(space.properties, MigrationVersionAnnotation).pipe(Option.getOrUndefined) !==
+        Migrations.targetVersion)
+  );
+};
+
+export const downloadBlob = async (blob: Blob, filename: string) => {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = filename;
+
+  document.body.appendChild(anchor);
+  anchor.click();
+
+  document.body.removeChild(anchor);
+  URL.revokeObjectURL(url);
+};
+
+//
+// View Index
+//
+
+/**
+ * Index of view objects grouped by their target type URI.
+ */
+export type ViewIndex = {
+  /** Type URIs that have at least one straightforward view targeting them. */
+  typeUrisWithViews: Set<string>;
+  /** View objects targeting a specific type URI. */
+  getViewsForTypeUri: (typeUri: string) => Obj.Any[];
+  /** True when the schema has `ViewAnnotation` and that path resolves non-null on `object`; false otherwise (no annotation, or null/undefined path — e.g. Kanban with unset `view`). */
+  isView: (object: Obj.Any) => boolean;
+};
+
+/**
+ * Builds an index of view objects by scanning view-annotated schemas and resolving the target
+ * type URI from each view's query AST. Only straightforward views whose query resolves to a
+ * type URI via getTypeURIFromQuery are included.
+ */
+// TODO(wittjosiah): Make reactive to schema registry changes (currently only object/view mutations trigger updates).
+export const buildViewIndex = (get: Atom.Context, space: Space, schemas: Type.AnyEntity[]): ViewIndex => {
+  const viewSchemas = schemas.filter((schema) => ViewAnnotation.has(schema));
+
+  const viewsByTypeUri = new Map<string, Obj.Any[]>();
+  // Object IDs whose `ViewAnnotation` path resolves to a non-null value.
+  // Used by `isView` to distinguish view instances from regular instances of
+  // the same schema (e.g. items-variant Kanban vs view-variant Kanban).
+  const viewObjectIds = new Set<string>();
+
+  if (viewSchemas.length > 0) {
+    const filter = Filter.or(...viewSchemas.map((schema) => Filter.type(schema)));
+    const viewObjects = get(space.db.query(filter).atom);
+
+    for (const viewObject of viewObjects) {
+      if (!Obj.isObject(viewObject)) {
+        continue;
+      }
+      const holderType = Obj.getType(viewObject);
+      const path = holderType
+        ? ViewAnnotation.get(Type.getSchema(holderType)).pipe(Option.getOrElse(() => [] as EchoViewRefPath))
+        : ([] as EchoViewRefPath);
+
+      if (path.length === 0) {
+        continue;
+      }
+
+      const viewSnapshot = get(Obj.atom(viewObject));
+      let holder: unknown = viewSnapshot;
+      for (const segment of path) {
+        holder =
+          holder == null || typeof holder !== 'object' ? undefined : (holder as Record<string, unknown>)[segment];
+      }
+      // Path resolved to a non-null value → this instance is a "view". Path
+      // resolved to null/undefined → it's a regular object that happens to
+      // be of a view-annotated schema.
+      if (holder != null) {
+        viewObjectIds.add(viewObject.id);
+      }
+
+      const viewTarget = holder != null ? get(Obj.atom(holder as Obj.Any)) : undefined;
+      const typeUri = getTypeURIFromQuery(viewTarget?.query?.ast);
+      if (typeUri) {
+        const existing = viewsByTypeUri.get(typeUri) ?? [];
+        existing.push(viewObject);
+        viewsByTypeUri.set(typeUri, existing);
+      }
+    }
+  }
+
+  return {
+    typeUrisWithViews: new Set(viewsByTypeUri.keys()),
+    getViewsForTypeUri: (typeUri) => viewsByTypeUri.get(typeUri) ?? [],
+    isView: (object) => viewObjectIds.has(object.id),
+  };
+};

package/src/capabilities/app-graph-builder/extensions/spaces.ts

@@ -0,0 +1,378 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import {
+  AppCapabilities,
+  AppNodeMatcher,
+  getActiveSpace,
+  getPersonalSpace,
+  isExemplarSpace,
+  isPersonalSpace,
+} from '@dxos/app-toolkit';
+import { type Space, SpaceState } from '@dxos/client/echo';
+import { Operation } from '@dxos/compute';
+import { Filter, Obj } from '@dxos/echo';
+import { Migrations } from '@dxos/migrations';
+import { ClientCapabilities } from '@dxos/plugin-client';
+import { CreateAtom, Graph, GraphBuilder, Node, NodeMatcher } from '@dxos/plugin-graph';
+import { SpaceArchive } from '@dxos/protocols/proto/dxos/client/services';
+import { Expando } from '@dxos/schema';
+
+import { meta } from '#meta';
+import { SpaceOperation } from '#operations';
+import { SPACE_TYPE, SpaceCapabilities } from '#types';
+
+import { SHARED, getSpaceDisplayName } from '../../../util';
+import {
+  CACHEABLE_PROPS,
+  CAN_DROP_SPACE,
+  CREATE_OBJECT_IN_SPACE_LABEL,
+  MIGRATE_SPACE_LABEL,
+  RENAME_SPACE_LABEL,
+  checkPendingMigration,
+  spaceActionsCache,
+  spaceRearrangeCache,
+} from './shared';
+
+//
+// Extension Factory
+//
+
+/** Creates space-related extensions: primary actions, space nodes, and space actions. */
+export const createSpaceExtensions = Effect.fnUntraced(function* () {
+  const capabilities = yield* Capability.Service;
+
+  return yield* Effect.all([
+    GraphBuilder.createExtension({
+      id: 'primaryActions',
+      position: 'first',
+      match: NodeMatcher.whenRoot,
+      actions: () =>
+        Effect.succeed([
+          Node.makeAction({
+            id: SpaceOperation.OpenCreateSpace.meta.key,
+            data: () => Operation.invoke(SpaceOperation.OpenCreateSpace),
+            properties: {
+              label: ['create-space.label', { ns: meta.id }],
+              icon: 'ph--plus--regular',
+              testId: 'spacePlugin.createSpace',
+              disposition: 'menu',
+            },
+          }),
+          Node.makeAction({
+            id: SpaceOperation.Join.meta.key,
+            data: () => Operation.invoke(SpaceOperation.Join, {}),
+            properties: {
+              label: ['join-space.label', { ns: meta.id }],
+              icon: 'ph--sign-in--regular',
+              testId: 'spacePlugin.joinSpace',
+              disposition: 'menu',
+            },
+          }),
+          Node.makeAction({
+            id: SpaceOperation.OpenImportSpace.meta.key,
+            data: () => Operation.invoke(SpaceOperation.OpenImportSpace),
+            properties: {
+              label: ['import-space.label', { ns: meta.id }],
+              icon: 'ph--upload--regular',
+              testId: 'spacePlugin.importSpace',
+            },
+          }),
+          Node.makeAction({
+            id: `${SpaceOperation.ExportSpace.meta.key}.binary`,
+            data: Effect.fnUntraced(function* () {
+              const client = yield* Capability.get(ClientCapabilities.Client);
+              const space = getActiveSpace(client, capabilities) ?? getPersonalSpace(client);
+              if (space) {
+                yield* Operation.invoke(SpaceOperation.ExportSpace, { space, format: SpaceArchive.Format.BINARY });
+              }
+            }),
+            properties: {
+              label: ['export-space-binary.label', { ns: meta.id }],
+              icon: 'ph--download--regular',
+              testId: 'spacePlugin.exportSpaceBinary',
+            },
+          }),
+          Node.makeAction({
+            id: `${SpaceOperation.ExportSpace.meta.key}.json`,
+            data: Effect.fnUntraced(function* () {
+              const client = yield* Capability.get(ClientCapabilities.Client);
+              const space = getActiveSpace(client, capabilities) ?? getPersonalSpace(client);
+              if (space) {
+                yield* Operation.invoke(SpaceOperation.ExportSpace, { space, format: SpaceArchive.Format.JSON });
+              }
+            }),
+            properties: {
+              label: ['export-space-json.label', { ns: meta.id }],
+              icon: 'ph--download--regular',
+              testId: 'spacePlugin.exportSpaceJson',
+            },
+          }),
+          Node.makeAction({
+            id: SpaceOperation.OpenMembers.meta.key,
+            data: Effect.fnUntraced(function* () {
+              const client = yield* Capability.get(ClientCapabilities.Client);
+              const space = getActiveSpace(client, capabilities) ?? getPersonalSpace(client);
+              if (space) {
+                yield* Operation.invoke(SpaceOperation.OpenMembers, { space });
+              }
+            }),
+            properties: {
+              label: ['share-space.label', { ns: meta.id }],
+              icon: 'ph--users--regular',
+              testId: 'spacePlugin.shareSpace',
+              keyBinding: {
+                macos: 'meta+.',
+                windows: 'alt+.',
+              },
+            },
+          }),
+          Node.makeAction({
+            id: SpaceOperation.OpenSettings.meta.key,
+            data: Effect.fnUntraced(function* () {
+              const client = yield* Capability.get(ClientCapabilities.Client);
+              const space = getActiveSpace(client, capabilities) ?? getPersonalSpace(client);
+              if (space) {
+                yield* Operation.invoke(SpaceOperation.OpenSettings, { space });
+              }
+            }),
+            properties: {
+              label: ['open-current-space-settings.label', { ns: meta.id }],
+              icon: 'ph--faders--regular',
+              keyBinding: {
+                macos: 'meta+shift+,',
+                windows: 'ctrl+shift+,',
+              },
+            },
+          }),
+        ]),
+    }),
+
+    GraphBuilder.createExtension({
+      id: 'spaces',
+      match: NodeMatcher.whenRoot,
+      connector: (_node, get) => {
+        const client = capabilities.get(ClientCapabilities.Client);
+        const stateAtom = capabilities.get(SpaceCapabilities.State);
+        const ephemeralAtom = capabilities.get(SpaceCapabilities.EphemeralState);
+        const spacesAtom = CreateAtom.fromObservable(client.spaces);
+
+        const spaces = get(spacesAtom);
+        const personalSpace = getPersonalSpace(client);
+
+        if (!spaces || !personalSpace) {
+          return Effect.succeed([]);
+        }
+
+        const settingsAtom = capabilities.get(SpaceCapabilities.Settings);
+        const settings = get(settingsAtom);
+        const state = get(stateAtom);
+        const ephemeralState = get(ephemeralAtom);
+
+        try {
+          const [spacesOrder] = get(personalSpace.db.query(Filter.type(Expando.Expando, { key: SHARED })).atom);
+          const { graph } = capabilities.get(AppCapabilities.AppGraph);
+
+          const spacesOrderSnapshot = spacesOrder ? get(Obj.atom(spacesOrder)) : undefined;
+          const order: string[] = (spacesOrderSnapshot as any)?.order ?? [];
+          const orderMap = new Map(order.map((id, index) => [id, index]));
+
+          const spaceStates = spaces.map((space) => get(CreateAtom.fromObservable(space.state)));
+
+          spaces.forEach((space) => {
+            if (space.state.get() === SpaceState.SPACE_READY) {
+              get(Obj.atom(space.properties));
+            }
+          });
+
+          return Effect.succeed(
+            [
+              ...spaces
+                .filter((space) => orderMap.has(space.id))
+                .sort((sortA, sortB) => orderMap.get(sortA.id)! - orderMap.get(sortB.id)!),
+              ...spaces.filter((space) => !orderMap.has(space.id)),
+            ]
+              .filter((space, idx) => spaceStates[idx] !== SpaceState.SPACE_INACTIVE)
+              .filter((space) => space.tags.length === 0 || isPersonalSpace(space) || isExemplarSpace(space))
+              .map((space) =>
+                constructSpaceNode({
+                  space,
+                  navigable: ephemeralState.navigableCollections,
+                  personal: isPersonalSpace(space),
+                  namesCache: state.spaceNames,
+                  graph,
+                  spacesOrder,
+                }),
+              ),
+          );
+        } catch {
+          return Effect.succeed([]);
+        }
+      },
+      // TODO(graph-path-ids): Resolver temporarily disabled; redesign needed for path-based IDs.
+      // resolver: (id, get) => { ... },
+    }),
+
+    GraphBuilder.createExtension({
+      id: 'actions',
+      match: AppNodeMatcher.whenSpace,
+      actions: (space, get) => {
+        const [client] = get(capabilities.atom(ClientCapabilities.Client));
+        const ephemeralAtom = capabilities.get(SpaceCapabilities.EphemeralState);
+        const ephemeralState = get(ephemeralAtom);
+
+        if (!client) {
+          return Effect.succeed([]);
+        }
+
+        // Recompute actions when a migration completes (state transition or versionProperty stamp).
+        get(CreateAtom.fromObservable(space.state));
+        if (space.state.get() === SpaceState.SPACE_READY) {
+          get(Obj.atom(space.properties));
+        }
+
+        return Effect.succeed(
+          constructSpaceActions({
+            space,
+            migrating: ephemeralState.sdkMigrationRunning[space.id],
+          }),
+        );
+      },
+    }),
+  ]);
+});
+
+//
+// Helpers
+//
+
+/** Builds an app-graph node for a space, including settings children and optional rearrange handler. */
+const constructSpaceNode = ({
+  space,
+  navigable = false,
+  personal,
+  namesCache,
+  graph,
+  spacesOrder,
+}: {
+  space: Space;
+  navigable?: boolean;
+  personal?: boolean;
+  namesCache?: Record<string, string>;
+  graph?: Graph.ExpandableGraph;
+  spacesOrder?: Obj.Any;
+}) => {
+  const hasPendingMigration = checkPendingMigration(space);
+
+  let onRearrange: ((nextOrder: Space[]) => void) | undefined;
+  if (graph && spacesOrder) {
+    onRearrange = spaceRearrangeCache.get(space.id);
+    if (!onRearrange) {
+      onRearrange = (nextOrder: Space[]) => {
+        Graph.sortEdges(
+          graph,
+          Node.RootId,
+          'outbound',
+          nextOrder.map(({ id }) => id),
+        );
+
+        Obj.update(spacesOrder, (spacesOrder: any) => {
+          spacesOrder.order = nextOrder.map(({ id }) => id);
+        });
+      };
+      spaceRearrangeCache.set(space.id, onRearrange);
+    }
+  }
+
+  return Node.make({
+    id: space.id,
+    type: SPACE_TYPE,
+    cacheable: CACHEABLE_PROPS,
+    data: space,
+    properties: {
+      label: getSpaceDisplayName(space, { personal, namesCache }),
+      description: space.state.get() === SpaceState.SPACE_READY && space.properties.description,
+      hue: space.state.get() === SpaceState.SPACE_READY && space.properties.hue,
+      icon:
+        space.state.get() === SpaceState.SPACE_READY && space.properties.icon
+          ? `ph--${space.properties.icon}--regular`
+          : undefined,
+      iconHue: space.state.get() === SpaceState.SPACE_READY && space.properties.iconHue,
+      disabled: !navigable || space.state.get() !== SpaceState.SPACE_READY || hasPendingMigration,
+      disposition: 'workspace',
+      testId: 'spacePlugin.space',
+      onRearrange,
+      canDrop: CAN_DROP_SPACE,
+    },
+  });
+};
+
+/** Builds the action list for a space node (migrate, create object, rename). */
+const constructSpaceActions = ({ space, migrating }: { space: Space; migrating?: boolean }) => {
+  const state = space.state.get();
+  const hasPendingMigration = checkPendingMigration(space);
+  const isMigrating = migrating || Migrations.running(space);
+
+  const cached = spaceActionsCache.get(space.id);
+  if (
+    cached &&
+    cached.state === state &&
+    cached.hasPendingMigration === hasPendingMigration &&
+    cached.migrating === isMigrating
+  ) {
+    return cached.actions;
+  }
+
+  const actions: Node.NodeArg<Node.ActionData<Operation.Service>>[] = [];
+
+  if (hasPendingMigration) {
+    actions.push(
+      Node.make({
+        id: SpaceOperation.Migrate.meta.key,
+        type: Node.ActionGroupType,
+        data: () => Operation.invoke(SpaceOperation.Migrate, { space }),
+        properties: {
+          label: MIGRATE_SPACE_LABEL,
+          icon: 'ph--database--regular',
+          disposition: 'list-item-primary',
+          disabled: isMigrating,
+        },
+      }),
+    );
+  }
+
+  if (state === SpaceState.SPACE_READY && !hasPendingMigration) {
+    actions.push(
+      Node.makeAction({
+        id: SpaceOperation.OpenCreateObject.meta.key,
+        data: () => Operation.invoke(SpaceOperation.OpenCreateObject, { target: space.db }),
+        properties: {
+          label: CREATE_OBJECT_IN_SPACE_LABEL,
+          icon: 'ph--plus--regular',
+          disposition: 'list-item-primary',
+          testId: 'spacePlugin.createObject',
+        },
+      }),
+      Node.makeAction({
+        id: SpaceOperation.Rename.meta.key,
+        data: (params?: Node.InvokeProps) =>
+          Operation.invoke(SpaceOperation.Rename, { space, caller: `${params?.caller}:${params?.parent?.id}` }),
+        properties: {
+          label: RENAME_SPACE_LABEL,
+          icon: 'ph--pencil-simple-line--regular',
+          keyBinding: {
+            macos: 'shift+F6',
+            windows: 'shift+F6',
+          },
+        },
+      }),
+    );
+  }
+
+  spaceActionsCache.set(space.id, { state, hasPendingMigration, migrating: isMigrating, actions });
+  return actions;
+};

package/src/capabilities/app-graph-builder/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const AppGraphBuilder = Capability.lazy('AppGraphBuilder', () => import('./app-graph-builder'));