@dxos/app-framework 0.8.4-main.7ace549 → 0.8.4-main.937b3ca

package/src/common/capability.ts

@@ -0,0 +1,343 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Command$ from '@effect/cli/Command';
+import { Atom, type Registry } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import type * as Layer$ from 'effect/Layer';
+import type * as ManagedRuntime$ from 'effect/ManagedRuntime';
+import type * as Schema$ from 'effect/Schema';
+import type { FC, PropsWithChildren } from 'react';
+
+import type { AiModelResolver as AiModelResolver$, AiService as AiService$ } from '@dxos/ai';
+import type { BuilderExtensions, GraphBuilder } from '@dxos/app-graph';
+import type { GenericToolkit } from '@dxos/assistant';
+import type { Blueprint } from '@dxos/blueprints';
+import type { Database, Type } from '@dxos/echo';
+import type { FunctionDefinition } from '@dxos/functions';
+import type { OperationInvoker as OperationInvoker$, OperationResolver as OperationResolver$ } from '@dxos/operation';
+import type { AnchoredTo } from '@dxos/types';
+
+import { Capability as Capability$, type PluginManager as PluginManager$ } from '../core';
+import type {
+  HistoryTracker as HistoryTracker$,
+  UndoMapping as UndoMapping$,
+  UndoRegistry as UndoRegistry$,
+} from '../plugin-operation';
+
+import type { FileInfo } from './file';
+import type { NodeSerializer } from './graph';
+import type { SurfaceDefinition } from './surface';
+import type { Resource } from './translations';
+
+export namespace Capability {
+  // TODO(burdon): Sort.
+
+  /**
+   * @category Capability
+   */
+  export const Null = Capability$.make<null>('dxos.org/app-framework/capability/null');
+
+  /**
+   * @category Capability
+   */
+  export const PluginManager = Capability$.make<PluginManager$.PluginManager>(
+    'dxos.org/app-framework/capability/plugin-manager',
+  );
+
+  /**
+   * @category Capability
+   */
+  export const AtomRegistry = Capability$.make<Registry.Registry>('dxos.org/app-framework/capability/atom-registry');
+
+  export type ReactContext = Readonly<{
+    id: string;
+    dependsOn?: string[];
+    context: FC<PropsWithChildren>;
+  }>;
+
+  /**
+   * @category Capability
+   */
+  export const ReactContext = Capability$.make<ReactContext>('dxos.org/app-framework/capability/react-context');
+
+  export type ReactRoot = Readonly<{ id: string; root: FC<PropsWithChildren> }>;
+
+  /**
+   * @category Capability
+   */
+  export const ReactRoot = Capability$.make<ReactRoot>('dxos.org/app-framework/capability/react-root');
+
+  /**
+   * Surface definitions that can be either React components or Web Components.
+   */
+  export type ReactSurface = SurfaceDefinition | readonly SurfaceDefinition[];
+
+  /**
+   * @category Capability
+   */
+  export const ReactSurface = Capability$.make<ReactSurface>('dxos.org/app-framework/common/react-surface');
+
+  export type Layout = Readonly<{
+    mode: string;
+    dialogOpen: boolean;
+    sidebarOpen: boolean;
+    complementarySidebarOpen: boolean;
+    /**
+     * The id of the active workspace, where a workspace is a set of active items.
+     */
+    workspace: string;
+    /**
+     * Identifiers of items which are currently active in the application.
+     */
+    active: string[];
+    /**
+     * Identifiers of items which were previously active in the application.
+     */
+    inactive: string[];
+    /**
+     * Identifier of the item which should be scrolled into view.
+     */
+    scrollIntoView: string | undefined;
+  }>;
+
+  /**
+   * Layout capability - provides reactive access to the current layout state.
+   * Use `useAtomValue(layoutAtom)` in React or `registry.get(layoutAtom)` in Effects.
+   * @category Capability
+   */
+  export const Layout = Capability$.make<Atom.Atom<Layout>>('dxos.org/app-framework/capability/layout');
+
+  /**
+   * @category Capability
+   */
+  export const Translations = Capability$.make<Readonly<Resource[]>>('dxos.org/app-framework/capability/translations');
+
+  export type AppGraph = Readonly<{
+    graph: GraphBuilder.GraphBuilder['graph'];
+    explore: typeof GraphBuilder.explore;
+  }>;
+
+  /**
+   * @category Capability
+   */
+  export const AppGraph = Capability$.make<AppGraph>('dxos.org/app-framework/capability/app-graph');
+
+  /**
+   * @category Capability
+   */
+  export const AppGraphBuilder = Capability$.make<BuilderExtensions>(
+    'dxos.org/app-framework/capability/app-graph-builder',
+  );
+
+  /**
+   * @category Capability
+   */
+  export const AppGraphSerializer = Capability$.make<NodeSerializer[]>(
+    'dxos.org/app-framework/capability/app-graph-serializer',
+  );
+
+  // TODO(wittjosiah): The generics caused type inference issues for schemas when contributing settings.
+  // export type Settings = Parameters<RootSettingsStore['createStore']>[0];
+  // export type Settings<T extends SettingsValue = SettingsValue> = SettingsProps<T>;
+  export type Settings = {
+    prefix: string;
+    schema: Schema$.Schema.All;
+    atom: Atom.Writable<any>;
+  };
+
+  /**
+   * Type guard to check if a value is a Settings object.
+   */
+  export const isSettings = (value: unknown): value is Settings =>
+    typeof value === 'object' &&
+    value !== null &&
+    'prefix' in value &&
+    typeof (value as Settings).prefix === 'string' &&
+    'atom' in value &&
+    Atom.isAtom(value.atom) &&
+    Atom.isWritable(value.atom);
+
+  /**
+   * @category Capability
+   */
+  export const Settings = Capability$.make<Settings>('dxos.org/app-framework/capability/settings');
+
+  export type Metadata = Readonly<{
+    id: string;
+    metadata: Record<string, any>;
+  }>;
+
+  /**
+   * @category Capability
+   */
+  export const Metadata = Capability$.make<Metadata>('dxos.org/app-framework/capability/metadata');
+
+  export type Schema = ReadonlyArray<Type.Entity.Any>;
+
+  /**
+   * @category Capability
+   */
+  export const Schema = Capability$.make<Schema>('dxos.org/app-framework/capability/schema');
+
+  export type Toolkit = GenericToolkit.GenericToolkit;
+
+  /**
+   * @category Capability
+   */
+  export const Toolkit = Capability$.make<Toolkit>('dxos.org/app-framework/capability/ai-toolkit');
+
+  /**
+   * @category Capability
+   */
+  export const BlueprintDefinition = Capability$.make<Blueprint.Blueprint>(
+    'dxos.org/app-framework/capability/blueprint-definition',
+  );
+
+  export type AiServiceLayer = Layer$.Layer<AiService$.AiService>;
+  export const AiServiceLayer = Capability$.make<AiServiceLayer>(
+    'dxos.org/app-framework/capability/ai-service-factory',
+  );
+
+  /**
+   * Plugins can contribute them to provide model resolvers.
+   */
+  export const AiModelResolver = Capability$.make<Layer$.Layer<AiModelResolver$.AiModelResolver>>(
+    'dxos.org/app-framework/capability/ai-model-resolver',
+  );
+
+  /**
+   * @category Capability
+   */
+  export const Functions = Capability$.make<FunctionDefinition.Any[]>('dxos.org/app-framework/capability/functions');
+
+  export type FileUploader = (db: Database.Database, file: File) => Promise<FileInfo | undefined>;
+
+  /**
+   * @category Capability
+   */
+  export const FileUploader = Capability$.make<FileUploader>('dxos.org/app-framework/capability/file-uploader');
+
+  export type AnchorSort = {
+    key: string;
+    sort: (anchorA: AnchoredTo.AnchoredTo, anchorB: AnchoredTo.AnchoredTo) => number;
+  };
+
+  /**
+   * @category Capability
+   */
+  export const AnchorSort = Capability$.make<AnchorSort>('dxos.org/app-framework/capability/anchor-sort');
+
+  export type AnyCommand = Command$.Command<any, any, any, any>;
+
+  /**
+   * @category Capability
+   */
+  export const Command = Capability$.make<AnyCommand>('dxos.org/app-framework/capability/command');
+
+  /**
+   * @category Capability
+   */
+  export const Layer = Capability$.make<Layer$.Layer<any, any, any>>('dxos.org/app-framework/capability/layer');
+
+  export type ManagedRuntime = ManagedRuntime$.ManagedRuntime<any, any>;
+
+  /**
+   * @category Capability
+   */
+  export const ManagedRuntime = Capability$.make<ManagedRuntime>('dxos.org/app-framework/capability/managed-runtime');
+
+  //
+  // Operation System Capabilities
+  //
+
+  export type OperationResolver = OperationResolver$.OperationResolver<any, any, any, any>;
+
+  /**
+   * Handler registration for operations - contributed by plugins.
+   * @category Capability
+   */
+  export const OperationResolver = Capability$.make<OperationResolver[]>(
+    'dxos.org/app-framework/capability/operation-resolver',
+  );
+
+  export type UndoMapping = UndoMapping$.UndoMapping;
+
+  /**
+   * Undo mapping registration - contributed by plugins.
+   * @category Capability
+   */
+  export const UndoMapping = Capability$.make<UndoMapping[]>('dxos.org/app-framework/capability/undo-mapping');
+
+  export type OperationInvoker = OperationInvoker$.OperationInvoker;
+
+  /**
+   * Operation invoker - provided by OperationPlugin.
+   * @category Capability
+   */
+  export const OperationInvoker = Capability$.make<OperationInvoker>(
+    'dxos.org/app-framework/capability/operation-invoker',
+  );
+
+  export type UndoRegistry = UndoRegistry$.UndoRegistry;
+
+  /**
+   * Undo registry - provided by OperationPlugin.
+   * @category Capability
+   */
+  export const UndoRegistry = Capability$.make<UndoRegistry>('dxos.org/app-framework/capability/undo-registry');
+
+  export type HistoryTracker = HistoryTracker$.HistoryTracker;
+
+  /**
+   * History tracker - provided by OperationPlugin.
+   * @category Capability
+   */
+  export const HistoryTracker = Capability$.make<HistoryTracker>('dxos.org/app-framework/capability/history-tracker');
+
+  //
+  // Atom Capability Helpers
+  //
+
+  /**
+   * Get the current value of an atom capability.
+   * @example const settings = yield* Common.Capability.getAtomValue(ThreadCapabilities.Settings);
+   */
+  export const getAtomValue = <T>(
+    atomCapability: Capability$.InterfaceDef<Atom.Atom<T>>,
+  ): Effect.Effect<T, Error, Capability$.Service> =>
+    Effect.gen(function* () {
+      const registry = yield* Capability$.get(AtomRegistry);
+      const atom = yield* Capability$.get(atomCapability);
+      return registry.get(atom);
+    });
+
+  /**
+   * Update an atom capability value (requires writable atom).
+   * @example yield* Common.Capability.updateAtomValue(ThreadCapabilities.Settings, (s) => ({ ...s, foo: true }));
+   */
+  export const updateAtomValue = <T>(
+    atomCapability: Capability$.InterfaceDef<Atom.Writable<T>>,
+    fn: (current: T) => T,
+  ): Effect.Effect<void, Error, Capability$.Service> =>
+    Effect.gen(function* () {
+      const registry = yield* Capability$.get(AtomRegistry);
+      const atom = yield* Capability$.get(atomCapability);
+      registry.set(atom, fn(registry.get(atom)));
+    });
+
+  /**
+   * Subscribe to an atom capability.
+   * @example const unsubscribe = yield* Common.Capability.subscribeAtom(ThreadCapabilities.Settings, (value) => ...);
+   */
+  export const subscribeAtom = <T>(
+    atomCapability: Capability$.InterfaceDef<Atom.Atom<T>>,
+    callback: (value: T) => void,
+  ): Effect.Effect<() => void, Error, Capability$.Service> =>
+    Effect.gen(function* () {
+      const registry = yield* Capability$.get(AtomRegistry);
+      const atom = yield* Capability$.get(atomCapability);
+      return registry.subscribe(atom, () => callback(registry.get(atom)));
+    });
+}

package/src/common/collaboration.ts

@@ -4,15 +4,28 @@
 
 import * as Schema from 'effect/Schema';
 
+import { Operation } from '@dxos/operation';
 import { ContentBlock } from '@dxos/types';
 
-export namespace CollaborationActions {
-  export class AcceptProposal extends Schema.TaggedClass<AcceptProposal>()('collaboration/accept-proposal', {
-    input: Schema.Struct({
-      subject: Schema.Any,
-      anchor: Schema.String,
-      proposal: ContentBlock.Proposal,
-    }),
-    output: Schema.Void,
-  }) {}
+import { Capability } from '../core';
+
+const COLLABORATION_OPERATION = 'dxos.org/app-framework/collaboration/operation';
+
+export namespace CollaborationOperation {
+  export const AcceptProposal = Operation.make({
+    meta: {
+      key: `${COLLABORATION_OPERATION}/accept-proposal`,
+      name: 'Accept Proposal',
+      description: 'Accept a proposal from a collaborator.',
+    },
+    services: [Capability.Service],
+    schema: {
+      input: Schema.Struct({
+        subject: Schema.Any,
+        anchor: Schema.String,
+        proposal: ContentBlock.Proposal,
+      }),
+      output: Schema.Void,
+    },
+  });
 }

package/src/common/graph.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import type { Node } from '@dxos/app-graph';
+import { type Node } from '@dxos/app-graph';
 import { type MaybePromise, type Position } from '@dxos/util';
 
 // TODO(wittjosiah): Factor out.
@@ -21,7 +21,7 @@ export type NodeSerializer<T = any> = {
   /**
    * Takes a node and serializes it into a format that can be stored.
    */
-  serialize: (node: Node<T>) => MaybePromise<SerializedNode>;
+  serialize: (node: Node.Node<T>) => MaybePromise<SerializedNode>;
 
   /**
    * Takes a serialized node and deserializes it into the application.

package/src/common/index.ts

@@ -2,11 +2,12 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './capabilities';
+export * from './activation-event';
+export * from './capability';
 export * from './collaboration';
-export * from './events';
 export * from './file';
 export * from './graph';
-export * from './layout';
+export * from './operations';
+export * from './plugin';
 export * from './surface';
 export * from './translations';