@dxos/app-framework 0.7.5-main.9d26e3a → 0.7.5-main.e9bb01b

package/src/{plugins/plugin-surface/SurfaceContext.ts → common/surface.ts}

@@ -2,12 +2,11 @@
 // Copyright 2023 DXOS.org
 //
 
-import { createContext, useContext, type JSX, type ForwardedRef, type PropsWithChildren, type ReactNode } from 'react';
+import { type JSX, type ForwardedRef, type PropsWithChildren, type ReactNode } from 'react';
 
-import { raise } from '@dxos/debug';
-import { type GuardedType, type MakeOptional } from '@dxos/util';
+import { type GuardedType, type MakeOptional, type Position } from '@dxos/util';
 
-import { type ErrorBoundary } from './ErrorBoundary';
+import { type ErrorBoundary } from '../react';
 
 /**
  * SurfaceProps are the props that are passed to the Surface component.
@@ -68,45 +67,15 @@ export type SurfaceComponent<T extends Record<string, any> = Record<string, unkn
   forwardedRef: ForwardedRef<HTMLElement>,
 ) => JSX.Element | null;
 
-/**
- * Determines the priority of the surface when multiple components are resolved.
- *
- * - `static` - The component is rendered in the order it was resolved.
- * - `hoist` - The component is rendered before `static` components.
- * - `fallback` - The component is rendered after `static` components.
- */
-export type SurfaceDisposition = 'static' | 'hoist' | 'fallback';
-
 /**
  * Definition of when a SurfaceComponent should be rendered.
  */
-export type SurfaceDefinition<T extends Record<string, any> = any> = {
+export type SurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
   id: string;
   role: string | string[];
-  disposition?: SurfaceDisposition;
+  position?: Position;
   filter?: (data: Record<string, unknown>) => data is T;
   component: SurfaceComponent<GuardedType<SurfaceDefinition<T>['filter']>>;
-};
+}>;
 
 export const createSurface = <T extends Record<string, any> = any>(definition: SurfaceDefinition<T>) => definition;
-
-/**
- * Surface debug info.
- * NOTE: Short-term measure to track perf issues.
- */
-export type DebugInfo = {
-  id: string;
-  created: number;
-  renderCount: number;
-} & Pick<SurfaceProps, 'role'>;
-
-export type SurfaceContextValue = {
-  surfaces: Record<string, SurfaceDefinition>;
-  debugInfo?: Map<string, DebugInfo>;
-};
-
-const SurfaceContext = createContext<SurfaceContextValue | undefined>(undefined);
-
-export const useSurfaceRoot = () => useContext(SurfaceContext) ?? raise(new Error('Missing SurfaceContext'));
-
-export const SurfaceProvider = SurfaceContext.Provider;

package/src/common/translations.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Schema as S } from '@effect/schema';
+
+export const ResourceKey = S.Union(S.String, S.Record({ key: S.String, value: S.Any }));
+export type ResourceKey = S.Schema.Type<typeof ResourceKey>;
+
+export const ResourceLanguage = S.Record({ key: S.String, value: ResourceKey });
+export type ResourceLanguage = S.Schema.Type<typeof ResourceLanguage>;
+
+/**
+ * A resource is a collection of translations for a language.
+ */
+export const Resource = S.Record({ key: S.String, value: ResourceLanguage });
+export type Resource = S.Schema.Type<typeof Resource>;

package/src/core/capabilities.test.ts

@@ -0,0 +1,116 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from 'vitest';
+
+import { updateCounter } from '@dxos/echo-schema/testing';
+import { registerSignalsRuntime } from '@dxos/echo-signals';
+
+import { defineCapability, PluginsContext } from './capabilities';
+
+registerSignalsRuntime();
+
+const defaultOptions = {
+  activate: () => Promise.resolve(false),
+  reset: () => Promise.resolve(false),
+};
+
+describe('PluginsContext', () => {
+  it('should return empty array if no capabilities are contributed', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    expect(context.requestCapabilities(interfaceDef)).toEqual([]);
+  });
+
+  it('should be able to contribute and request capabilities', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation = { example: 'identifier' };
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    expect(context.requestCapabilities(interfaceDef)).toEqual([implementation]);
+  });
+
+  it('should be able to remove capabilities', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation = { example: 'identifier' };
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    expect(context.requestCapabilities(interfaceDef)).toEqual([implementation]);
+    context.removeCapability(interfaceDef, implementation);
+    expect(context.requestCapabilities(interfaceDef)).toEqual([]);
+  });
+
+  it('should be able to contribute and request multiple implementations', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation1 = { example: 'first' };
+    const implementation2 = { example: 'second' };
+    context.contributeCapability({ interface: interfaceDef, implementation: implementation1, module: 'test' });
+    context.contributeCapability({ interface: interfaceDef, implementation: implementation2, module: 'test' });
+    expect(context.requestCapabilities(interfaceDef)).toEqual([implementation1, implementation2]);
+  });
+
+  it('should be able to request multiple capabilities', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef1 = defineCapability<{ one: number }>('@dxos/app-framework/test/one');
+    const interfaceDef2 = defineCapability<{ two: number }>('@dxos/app-framework/test/two');
+    const implementation1 = { one: 1 };
+    const implementation2 = { two: 2 };
+    context.contributeCapability({ interface: interfaceDef1, implementation: implementation1, module: 'test' });
+    context.contributeCapability({ interface: interfaceDef2, implementation: implementation2, module: 'test' });
+    expect(context.requestCapabilities(interfaceDef1)).toEqual([implementation1]);
+    expect(context.requestCapabilities(interfaceDef2)).toEqual([implementation2]);
+  });
+
+  it('should be reactive', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+
+    using updates = updateCounter(() => {
+      context.requestCapabilities(interfaceDef);
+    });
+
+    expect(updates.count).toEqual(0);
+
+    const implementation = { example: 'identifier' };
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    expect(updates.count).toEqual(1);
+
+    context.removeCapability(interfaceDef, implementation);
+    expect(updates.count).toEqual(2);
+  });
+
+  it('should not be reactive to changes within the implementation', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+
+    using updates = updateCounter(() => {
+      context.requestCapabilities(interfaceDef);
+    });
+
+    expect(updates.count).toEqual(0);
+
+    const implementation = { example: 'identifier' };
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    expect(updates.count).toEqual(1);
+
+    implementation.example = 'updated';
+    expect(updates.count).toEqual(1);
+
+    const capabilities = context.requestCapabilities(interfaceDef);
+    expect(capabilities).toEqual([implementation]);
+    expect(capabilities[0].example).toEqual('updated');
+    expect(updates.count).toEqual(1);
+  });
+
+  it('should be able to wait for a capability', async () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation = { example: 'identifier' };
+    const promise = context.waitForCapability(interfaceDef);
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    const capability = await promise;
+    expect(capability).toEqual(implementation);
+  });
+});

package/src/core/capabilities.ts

@@ -0,0 +1,222 @@
+/**
+ * Interface definition for a capability.
+ */
+//
+// Copyright 2025 DXOS.org
+//
+
+import { effect, untracked } from '@preact/signals-core';
+import { type Effect } from 'effect';
+
+import { Trigger } from '@dxos/async';
+import { invariant } from '@dxos/invariant';
+import { create } from '@dxos/live-object';
+import { log } from '@dxos/log';
+import { type MaybePromise } from '@dxos/util';
+
+import { type ActivationEvent } from './events';
+
+const InterfaceDefTypeId: unique symbol = Symbol.for('InterfaceDefTypeId');
+
+/**
+ * The interface definition of a capability.
+ */
+export type InterfaceDef<T> = {
+  [InterfaceDefTypeId]: T;
+  identifier: string;
+};
+
+/**
+ * Helper to define the interface of a capability.
+ */
+export const defineCapability = <T>(identifier: string) => {
+  return { identifier } as InterfaceDef<T>;
+};
+
+/**
+ * Functionality contributed to the application by a plugin module.
+ */
+export type Capability<T> = {
+  /**
+   * The interface definition of the capability.
+   */
+  interface: InterfaceDef<T>;
+
+  /**
+   * The implementation of the capability.
+   */
+  implementation: T;
+
+  /**
+   * Called when the capability is deactivated.
+   */
+  deactivate?: () => MaybePromise<void> | Effect.Effect<void, Error>;
+};
+
+export type AnyCapability = Capability<any>;
+
+type PluginsContextOptions = {
+  activate: (event: ActivationEvent) => MaybePromise<boolean>;
+  reset: (event: ActivationEvent) => MaybePromise<boolean>;
+};
+
+// NOTE: This is implemented as a class to prevent it from being proxied by PluginManager state.
+class CapabilityImpl<T> {
+  constructor(
+    readonly moduleId: string,
+    readonly implementation: T,
+  ) {}
+}
+
+/**
+ * Helper to define the implementation of a capability.
+ */
+export const contributes = <T>(
+  interfaceDef: Capability<T>['interface'],
+  implementation: Capability<T>['implementation'],
+  deactivate?: Capability<T>['deactivate'],
+): Capability<T> => {
+  return { interface: interfaceDef, implementation, deactivate } satisfies Capability<T>;
+};
+
+type LoadCapability<T, U> = () => Promise<{ default: (props: T) => MaybePromise<Capability<U>> }>;
+type LoadCapabilities<T> = () => Promise<{ default: (props: T) => MaybePromise<AnyCapability[]> }>;
+// TODO(wittjosiah): Not having the array be `any` causes type errors when using the lazy capability.
+type LazyCapability<T, U> = (props?: T) => Promise<() => Promise<Capability<U> | AnyCapability[]>>;
+
+/**
+ * Helper to define a lazily loaded implementation of a capability.
+ */
+export const lazy =
+  <T, U>(c: LoadCapability<T, U> | LoadCapabilities<T>): LazyCapability<T, U> =>
+  async (props?: T) => {
+    const { default: getCapability } = await c();
+    return async () => getCapability(props as T);
+  };
+
+/**
+ * Context which is passed to plugins, allowing them to interact with each other.
+ */
+export class PluginsContext {
+  private readonly _definedCapabilities = new Map<string, CapabilityImpl<unknown>[]>();
+
+  /**
+   * Activates plugins based on the activation event.
+   * @param event The activation event.
+   * @returns Whether the activation was successful.
+   */
+  readonly activate: PluginsContextOptions['activate'];
+
+  /**
+   * Re-activates the modules that were activated by the event.
+   * @param event The activation event.
+   * @returns Whether the reset was successful.
+   */
+  readonly reset: PluginsContextOptions['reset'];
+
+  constructor({ activate, reset }: PluginsContextOptions) {
+    this.activate = activate;
+    this.reset = reset;
+  }
+
+  /**
+   * @internal
+   */
+  contributeCapability<T>({
+    module: moduleId,
+    interface: interfaceDef,
+    implementation,
+  }: {
+    module: string;
+    interface: InterfaceDef<T>;
+    implementation: T;
+  }) {
+    let current = this._definedCapabilities.get(interfaceDef.identifier);
+    if (!current) {
+      const object = create<{ value: CapabilityImpl<unknown>[] }>({ value: [] });
+      current = untracked(() => object.value);
+      this._definedCapabilities.set(interfaceDef.identifier, current);
+    }
+
+    current.push(new CapabilityImpl(moduleId, implementation));
+    log('capability contributed', {
+      id: interfaceDef.identifier,
+      moduleId,
+      count: untracked(() => current.length),
+    });
+  }
+
+  /**
+   * @internal
+   */
+  removeCapability<T>(interfaceDef: InterfaceDef<T>, implementation: T) {
+    const current = this._definedCapabilities.get(interfaceDef.identifier);
+    if (!current) {
+      return;
+    }
+
+    const index = current.findIndex((i) => i.implementation === implementation);
+    if (index !== -1) {
+      current.splice(index, 1);
+      log('capability removed', { id: interfaceDef.identifier, count: untracked(() => current.length) });
+    } else {
+      log.warn('capability not removed', { id: interfaceDef.identifier });
+    }
+  }
+
+  /**
+   * Requests capabilities from the plugin context.
+   * @returns An array of capabilities.
+   * @reactive
+   */
+  requestCapabilities<T, U extends T = T>(
+    interfaceDef: InterfaceDef<T>,
+    filter?: (capability: T, moduleId: string) => capability is U,
+  ): U[] {
+    let current = this._definedCapabilities.get(interfaceDef.identifier);
+    if (!current) {
+      const object = create<{ value: CapabilityImpl<unknown>[] }>({ value: [] });
+      current = untracked(() => object.value);
+      this._definedCapabilities.set(interfaceDef.identifier, current);
+    }
+
+    // NOTE: This the type-checking for capabilities is done at the time of contribution.
+    const capabilities = filter ? current.filter((c) => filter(c.implementation as T, c.moduleId)) : current;
+    return capabilities.map((c) => c.implementation) as U[];
+  }
+
+  /**
+   * Requests a single capability from the plugin context.
+   * @returns The capability.
+   * @throws If no capability is found.
+   * @reactive
+   */
+  requestCapability<T, U extends T = T>(
+    interfaceDef: InterfaceDef<T>,
+    filter?: (capability: T, moduleId: string) => capability is U,
+  ): U {
+    const capability = this.requestCapabilities(interfaceDef, filter)[0];
+    invariant(capability, `No capability found for ${interfaceDef.identifier}`);
+    return capability;
+  }
+
+  /**
+   * Waits for a capability to be contributed.
+   * @returns The capability.
+   */
+  async waitForCapability<T, U extends T = T>(
+    interfaceDef: InterfaceDef<T>,
+    filter?: (capability: T) => capability is U,
+  ): Promise<U> {
+    const trigger = new Trigger<U>();
+    const unsubscribe = effect(() => {
+      const capabilities = this.requestCapabilities(interfaceDef, filter);
+      if (capabilities[0]) {
+        trigger.wake(capabilities[0]);
+      }
+    });
+    const capability = await trigger.wait();
+    unsubscribe();
+    return capability;
+  }
+}

package/src/core/events.ts

@@ -0,0 +1,58 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * An event which activates a plugin module.
+ */
+export type ActivationEvent = {
+  id: string;
+  specifier?: string;
+};
+
+/**
+ * An activation event that can be a single event, or a combination of events.
+ */
+export type ActivationEvents =
+  | ActivationEvent
+  | { type: 'one-of'; events: ActivationEvent[] }
+  | { type: 'all-of'; events: ActivationEvent[] };
+
+/**
+ * Helper to define an activation event.
+ */
+export const defineEvent = (id: string, specifier?: string) => {
+  return { id, specifier } as ActivationEvent;
+};
+
+/**
+ * Helper to create an activation event key.
+ */
+export const eventKey = (event: ActivationEvent) => (event.specifier ? `${event.id}:${event.specifier}` : event.id);
+
+/**
+ * Helper to create an activation event that triggers when any of the given events are activated.
+ */
+export const oneOf = (...events: ActivationEvent[]) => ({ type: 'one-of' as const, events });
+
+/**
+ * Helper to create an activation event that triggers when all of the given events are activated.
+ */
+export const allOf = (...events: ActivationEvent[]) => ({ type: 'all-of' as const, events });
+
+/**
+ * Helper to check if an activation event is a one-of event.
+ */
+export const isOneOf = (events: ActivationEvents): 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[] } =>
+  '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]);

package/src/core/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './capabilities';
+export * from './events';
+export * from './manager';
+export * from './plugin';