@dxos/app-framework 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

package/src/common/plugin.ts

@@ -0,0 +1,364 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Command$ from '@effect/cli/Command';
+import * as Effect from 'effect/Effect';
+
+import { type Type } from '@dxos/echo';
+
+import { Capability as Capability$, Plugin as Plugin$ } from '../core';
+
+import { ActivationEvent } from './activation-event';
+import { Capability } from './capability';
+import { type Resource } from './translations';
+
+type PluginModuleOptions = Partial<
+  Pick<Plugin$.PluginModuleOptions, 'id' | 'activatesOn' | 'activatesBefore' | 'activatesAfter'>
+> &
+  Pick<Plugin$.PluginModuleOptions, 'activate'>;
+
+/**
+ * Helper functions for creating common plugin module patterns.
+ */
+export namespace Plugin {
+  // TODO(wittjosiah): Restrict type to only allow operation handlers.
+  export type OperationResolverModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes operation handlers.
+   *
+   * @param options Module options including the activate function and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addOperationResolverModule({
+   *     activate: (context) =>
+   *       Capability.contributes(Common.Capability.OperationResolver, [{
+   *         operation: MyOperation,
+   *         handler: (input) => Effect.succeed(...)
+   *       }])
+   *   })
+   * )
+   * ```
+   */
+  export function addOperationResolverModule<T = void>(
+    options: OperationResolverModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'operation-resolver',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupOperationResolver,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  // TODO(wittjosiah): Restrict type to only allow surfaces.
+  export type SurfaceModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes React surfaces.
+   *
+   * @param options Module options including the activate function and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addSurfaceModule({
+   *     activate: (context) =>
+   *       Capability.contributes(Common.Capability.ReactSurface, [
+   *         Common.createSurface({ id: `${meta.id}/my-surface`, ... })
+   *       ])
+   *   })
+   * )
+   * ```
+   */
+  export function addSurfaceModule<T = void>(
+    options: SurfaceModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'surfaces',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupReactSurface,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  // TODO(wittjosiah): Restrict type to only allow react roots.
+  export type ReactRootModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes a React root.
+   */
+  export function addReactRootModule<T = void>(
+    options: ReactRootModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'react-root',
+      activatesOn: options.activatesOn ?? ActivationEvent.Startup,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  // TODO(wittjosiah): Restrict type to only allow react contexts.
+  export type ReactContextModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes a React context.
+   */
+  export function addReactContextModule<T = void>(
+    options: ReactContextModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'react-context',
+      activatesOn: options.activatesOn ?? ActivationEvent.Startup,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  // TODO(wittjosiah): Restrict type to only allow app graph builders.
+  export type AppGraphModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes app graph builder extensions.
+   *
+   * @param options Module options including the activate function and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addAppGraphModule({
+   *     activate: Effect.fnUntraced(function* () {
+   *       const extensions = yield* GraphBuilder.createExtension({
+   *         id: meta.id,
+   *         match: NodeMatcher.whenRoot,
+   *         // All callbacks must return Effects.
+   *         actions: () => Effect.succeed([{
+   *           id: 'my-action',
+   *           // Action data returns Effect for automatic context access.
+   *           data: Effect.fnUntraced(function* () {
+   *             yield* Operation.invoke(MyOperation, { ... });
+   *           }),
+   *           properties: { label: 'My Action', icon: 'ph--icon' },
+   *         }]),
+   *         connector: (node, get) => Effect.succeed([{ id: 'child', ... }]),
+   *       });
+   *       return Capability.contributes(Common.Capability.AppGraphBuilder, extensions);
+   *     })
+   *   })
+   * )
+   * ```
+   */
+  export function addAppGraphModule<T = void>(
+    options: AppGraphModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'app-graph-builder',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupAppGraph,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  export type TranslationsModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
+    translations: Resource | Resource[];
+  };
+
+  /**
+   * Creates a module that contributes translations.
+   *
+   * @param options Module options including translations and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addTranslationsModule({
+   *     translations: translations
+   *   })
+   * )
+   * ```
+   */
+  export function addTranslationsModule<T = void>(
+    options: TranslationsModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: options?.id ?? 'translations',
+      activatesOn: options?.activatesOn ?? ActivationEvent.SetupTranslations,
+      activatesBefore: options?.activatesBefore,
+      activatesAfter: options?.activatesAfter,
+      activate: Effect.fnUntraced(function* () {
+        return Capability$.contributes(
+          Capability.Translations,
+          Array.isArray(options.translations) ? options.translations : ([options.translations] as Resource[]),
+        );
+      }),
+    });
+  }
+
+  export type MetadataModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
+    metadata: Capability.Metadata | Capability.Metadata[];
+  };
+
+  /**
+   * Creates a module that contributes metadata.
+   *
+   * @param options Module options including metadata and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addMetadataModule({
+   *     metadata: {
+   *       id: MyType.typename,
+   *       metadata: { icon: 'ph--icon', ... }
+   *     }
+   *   })
+   * )
+   * ```
+   */
+  export function addMetadataModule<T = void>(
+    options: MetadataModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: options.id ?? 'metadata',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupMetadata,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: Effect.fnUntraced(function* () {
+        return (Array.isArray(options.metadata) ? options.metadata : [options.metadata]).map((m) =>
+          Capability$.contributes(Capability.Metadata, m),
+        );
+      }),
+    });
+  }
+
+  // TODO(wittjosiah): Restrict type to only allow settings.
+  export type SettingsModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes settings.
+   */
+  export function addSettingsModule<T = void>(
+    options: SettingsModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'settings',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupSettings,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  // TODO(wittjosiah): Restrict type to only allow blueprint definitions.
+  export type BlueprintDefinitionModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes blueprint definitions.
+   *
+   * @param options Module options including the activate function and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addBlueprintDefinitionModule({
+   *     activate: (context) =>
+   *       Capability.contributes(Common.Capability.BlueprintDefinition, [
+   *         BlueprintDefinition.make({ key: 'my-blueprint', ... })
+   *       ])
+   *   })
+   * )
+   * ```
+   */
+  export function addBlueprintDefinitionModule<T = void>(
+    options: BlueprintDefinitionModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'blueprint-definition',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupArtifactDefinition,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  export type SchemaModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
+    schema: ReadonlyArray<Type.Entity.Any>;
+  };
+
+  /**
+   * Creates a module that contributes schemas.
+   *
+   * @param options Module options including schema array and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addSchemaModule({
+   *     schema: [MyType.Type, AnotherType.Type]
+   *   })
+   * )
+   * ```
+   */
+  export function addSchemaModule<T = void>(
+    options: SchemaModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: options.id ?? 'schema',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupSchema,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: Effect.fnUntraced(function* () {
+        return Capability$.contributes(Capability.Schema, options.schema);
+      }),
+    });
+  }
+
+  export type CommandModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
+    commands: ReadonlyArray<Command$.Command<any, any, any, any>>;
+  };
+
+  /**
+   * Creates a module that contributes CLI commands.
+   *
+   * @param options Module options including commands and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addCommandModule({
+   *     commands: [myCommand, anotherCommand]
+   *   })
+   * )
+   * ```
+   */
+  export function addCommandModule<T = void>(
+    options: CommandModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: options.id ?? 'cli-commands',
+      activatesOn: options.activatesOn ?? ActivationEvent.Startup,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: Effect.fnUntraced(function* () {
+        return options.commands.map((cmd) => Capability$.contributes(Capability.Command, cmd));
+      }),
+    });
+  }
+}

package/src/common/surface.ts

@@ -2,16 +2,16 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type JSX, type ForwardedRef, type PropsWithChildren, type ReactNode } from 'react';
+import type { PropsWithChildren, ReactNode, RefCallback } from 'react';
 
-import { type GuardedType, type MakeOptional, type Position } from '@dxos/util';
+import type { MakeOptional, Position } from '@dxos/util';
 
-import { type ErrorBoundary } from '../react';
+import type { ErrorBoundary } from '../react';
 
 /**
  * SurfaceProps are the props that are passed to the Surface component.
  */
-export type SurfaceProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
+export type SurfaceProps<T extends Record<string, any> = Record<string, unknown>> = {
   /**
    * If specified, the Surface will be wrapped in an error boundary.
    * The fallback component will be rendered if an error occurs.
@@ -23,17 +23,20 @@ export type SurfaceProps<T extends Record<string, any> = Record<string, unknown>
    * The placeholder component will be rendered while the surface component is loading.
    */
   placeholder?: ReactNode;
-}> &
-  MakeOptional<CoreSurfaceProps<T>, 'id' | 'data'> & {
-    /**
-     * Additional props to pass to the component.
-     * These props are not used by Surface itself but may be used by components which resolve the surface.
-     */
-    [key: string]: unknown;
+} & MakeOptional<CoreSurfaceProps<T>, 'id' | 'data'> &
+  /**
+   * Additional props to pass to the component.
+   * These props are not used by Surface itself but may be used by components which resolve the surface.
+   * Exclude known prop names to prevent overriding well-defined props.
+   */
+  {
+    [K in keyof Record<string, any>]: K extends keyof CoreSurfaceProps<T> | 'fallback' | 'placeholder' ? never : any;
   };
 
-// NOTE: If `[key: string]: unknown` is included in shared types, when re-used other fields become unknown as well.
-type CoreSurfaceProps<T extends Record<string, any> = Record<string, unknown>> = {
+/**
+ * NOTE: If `[key: string]: unknown` is included in shared types, when re-used other fields become unknown as well.
+ */
+export type CoreSurfaceProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
   /**
    * ID for debugging.
    */
@@ -46,6 +49,7 @@ type CoreSurfaceProps<T extends Record<string, any> = Record<string, unknown>> =
 
   /**
    * The data to be rendered by the surface.
+   * NOTE: This must be a stable value.
    */
   data: T;
 
@@ -53,34 +57,64 @@ type CoreSurfaceProps<T extends Record<string, any> = Record<string, unknown>> =
    * If more than one component is resolved, the limit determines how many are rendered.
    */
   limit?: number | undefined;
-};
+}>;
 
-type SurfaceComponentProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<
-  CoreSurfaceProps<T> & { [key: string]: unknown }
->;
+export type SurfaceComponentProps<T extends Record<string, any> = Record<string, any>> = CoreSurfaceProps<T> & {
+  ref?: RefCallback<HTMLElement>;
+} & Record<string, any>;
 
 /**
  * React component used to render a surface once is has matched.
  */
-export type SurfaceComponent<T extends Record<string, any> = Record<string, unknown>> = (
+export type SurfaceComponent<T extends Record<string, any> = Record<string, any>> = (
   props: SurfaceComponentProps<T>,
-  forwardedRef: ForwardedRef<HTMLElement>,
-) => JSX.Element | null;
+) => ReactNode;
 
 /**
- * Definition of when a SurfaceComponent should be rendered.
+ * Definition of when a React SurfaceComponent should be rendered.
  */
-export type SurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+export type ReactSurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+  kind: 'react';
   id: string;
   role: string | string[];
   position?: Position;
+  component: SurfaceComponent<T>;
   filter?: (data: Record<string, unknown>) => data is T;
-  component: SurfaceComponent<GuardedType<SurfaceDefinition<T>['filter']>>;
 }>;
 
 /**
- * Creates a surface definition.
+ * Definition of when a Web Component surface should be rendered.
+ */
+export type WebComponentSurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+  kind: 'web-component';
+  id: string;
+  role: string | string[];
+  position?: Position;
+  /**
+   * The tag name of the Web Component to render.
+   * The Web Component will receive the same props as React surfaces via properties/attributes.
+   */
+  tagName: string;
+  filter?: (data: Record<string, unknown>) => data is T;
+}>;
+
+/**
+ * Definition of when a surface (React or Web Component) should be rendered.
+ */
+export type SurfaceDefinition<T extends Record<string, any> = any> =
+  | ReactSurfaceDefinition<T>
+  | WebComponentSurfaceDefinition<T>;
+
+/**
+ * Creates a React surface definition.
  */
 export const createSurface = <T extends Record<string, any> = any>(
-  definition: SurfaceDefinition<T>,
-): SurfaceDefinition<T> => definition;
+  definition: Omit<ReactSurfaceDefinition<T>, 'kind'>,
+): ReactSurfaceDefinition<T> => ({ ...definition, kind: 'react' });
+
+/**
+ * Creates a Web Component surface definition.
+ */
+export const createWebSurface = <T extends Record<string, any> = any>(
+  definition: Omit<WebComponentSurfaceDefinition<T>, 'kind'>,
+): WebComponentSurfaceDefinition<T> => ({ ...definition, kind: 'web-component' });

package/src/common/translations.ts

@@ -2,7 +2,27 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
+
+/**
+ * A Label represents translatable text - either a simple string or a tuple of [key, options].
+ */
+export const Label = Schema.Union(
+  Schema.String,
+  Schema.mutable(
+    Schema.Tuple(
+      Schema.String,
+      Schema.mutable(
+        Schema.Struct({
+          ns: Schema.String,
+          count: Schema.optional(Schema.Number),
+          defaultValue: Schema.optional(Schema.String),
+        }),
+      ),
+    ),
+  ),
+);
+export type Label = Schema.Schema.Type<typeof Label>;
 
 export const ResourceKey = Schema.Union(Schema.String, Schema.Record({ key: Schema.String, value: Schema.Any }));
 export type ResourceKey = Schema.Schema.Type<typeof ResourceKey>;

package/src/context.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@dxos/web-context';
+
+import { type PluginManager } from './core';
+
+export const PluginManagerContext = createContext<PluginManager.PluginManager>('dxos.org/app-framework/plugin-manager');

package/src/core/{events.ts → activation-event.ts}

@@ -16,7 +16,7 @@ export type ActivationEvent = {
 /**
  * An activation event that can be a single event, or a combination of events.
  */
-export type ActivationEvents =
+export type Events =
   | ActivationEvent
   | { type: 'one-of'; events: ActivationEvent[] }
   | { type: 'all-of'; events: ActivationEvent[] };
@@ -24,7 +24,7 @@ export type ActivationEvents =
 /**
  * Helper to define an activation event.
  */
-export const defineEvent = (id: string, specifier?: string) => {
+export const make = (id: string, specifier?: string) => {
   return { id, specifier } as ActivationEvent;
 };
 
@@ -46,16 +46,16 @@ export const allOf = (...events: ActivationEvent[]) => ({ type: 'all-of' as cons
 /**
  * Helper to check if an activation event is a one-of event.
  */
-export const isOneOf = (events: ActivationEvents): events is { type: 'one-of'; events: ActivationEvent[] } =>
+export const isOneOf = (events: Events): events is { type: 'one-of'; events: ActivationEvent[] } =>
   'type' in events && events.type === 'one-of';
 
 /**
  * Helper to check if an activation event is an all-of event.
  */
-export const isAllOf = (events: ActivationEvents): events is { type: 'all-of'; events: ActivationEvent[] } =>
+export const isAllOf = (events: Events): events is { type: 'all-of'; events: ActivationEvent[] } =>
   'type' in events && events.type === 'all-of';
 
 /**
  * Helper to get the events from an activation event.
  */
-export const getEvents = (events: ActivationEvents) => ('type' in events ? events.events : [events]);
+export const getEvents = (events: Events) => ('type' in events ? events.events : [events]);