@dxos/app-framework 0.8.4-main.72ec0f3 → 0.8.4-main.74a063c4e0

package/src/common/surface.ts

@@ -1,88 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import type { ComponentType, PropsWithChildren, ReactNode } from 'react';
-
-import { type MakeOptional, type Position } from '@dxos/util';
-
-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>> = {
-  /**
-   * If specified, the Surface will be wrapped in an error boundary.
-   * The fallback component will be rendered if an error occurs.
-   */
-  fallback?: ErrorBoundary['props']['fallback'];
-
-  /**
-   * If specified, the Surface will be wrapped in a suspense boundary.
-   * 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.
-   * 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.
- */
-export type CoreSurfaceProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
-  /**
-   * ID for debugging.
-   */
-  id: string;
-
-  /**
-   * Role defines how the data should be rendered.
-   */
-  role: string;
-
-  /**
-   * The data to be rendered by the surface.
-   * NOTE: This must be a stable value.
-   */
-  data: T;
-
-  /**
-   * If more than one component is resolved, the limit determines how many are rendered.
-   */
-  limit?: number | undefined;
-}>;
-
-export type SurfaceComponentProps<T extends Record<string, any> = Record<string, any>> = CoreSurfaceProps<T> &
-  Record<string, any>;
-
-/**
- * React component used to render a surface once is has matched.
- */
-export type SurfaceComponent<T extends Record<string, any> = Record<string, any>> = ComponentType<
-  SurfaceComponentProps<T>
->;
-
-/**
- * Definition of when a SurfaceComponent should be rendered.
- */
-export type SurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
-  id: string;
-  role: string | string[];
-  position?: Position;
-  component: SurfaceComponent<T>;
-  filter?: (data: Record<string, unknown>) => data is T;
-}>;
-
-/**
- * Creates a surface definition.
- */
-export const createSurface = <T extends Record<string, any> = any>(
-  definition: SurfaceDefinition<T>,
-): SurfaceDefinition<T> => definition;

package/src/core/capabilities.test.ts

@@ -1,136 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { Registry } from '@effect-atom/atom-react';
-import * as Effect from 'effect/Effect';
-import { describe, expect, it, onTestFinished } from 'vitest';
-
-import { PluginContext, defineCapability } from './capabilities';
-
-const defaultOptions = {
-  activate: () => Effect.succeed(false),
-  reset: () => Effect.succeed(false),
-};
-
-describe('PluginsContext', () => {
-  it('should return empty array if no capabilities are contributed', () => {
-    const registry = Registry.make();
-    const context = new PluginContext({ registry, ...defaultOptions });
-    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
-    expect(context.getCapabilities(interfaceDef)).toEqual([]);
-  });
-
-  it('should be able to contribute and request capabilities', () => {
-    const registry = Registry.make();
-    const context = new PluginContext({ registry, ...defaultOptions });
-    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
-    const implementation = { example: 'identifier' };
-    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
-    expect(context.getCapabilities(interfaceDef)).toEqual([implementation]);
-  });
-
-  it('should be able to remove capabilities', () => {
-    const registry = Registry.make();
-    const context = new PluginContext({ registry, ...defaultOptions });
-    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
-    const implementation = { example: 'identifier' };
-    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
-    expect(context.getCapabilities(interfaceDef)).toEqual([implementation]);
-    context.removeCapability(interfaceDef, implementation);
-    expect(context.getCapabilities(interfaceDef)).toEqual([]);
-  });
-
-  it('should be able to contribute and request multiple implementations', () => {
-    const registry = Registry.make();
-    const context = new PluginContext({ registry, ...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.getCapabilities(interfaceDef)).toEqual([implementation1, implementation2]);
-  });
-
-  it('should be able to request multiple capabilities', () => {
-    const registry = Registry.make();
-    const context = new PluginContext({ registry, ...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.getCapabilities(interfaceDef1)).toEqual([implementation1]);
-    expect(context.getCapabilities(interfaceDef2)).toEqual([implementation2]);
-  });
-
-  it('should be reactive', () => {
-    const registry = Registry.make();
-    const context = new PluginContext({ registry, ...defaultOptions });
-    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
-
-    let count = 0;
-    const cancel = registry.subscribe(context.capabilities(interfaceDef), () => {
-      count++;
-    });
-    onTestFinished(() => cancel());
-    expect(count).toEqual(0);
-
-    registry.get(context.capabilities(interfaceDef));
-    expect(count).toEqual(1);
-
-    const implementation = { example: 'identifier' };
-    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
-    expect(count).toEqual(2);
-
-    context.removeCapability(interfaceDef, implementation);
-    expect(count).toEqual(3);
-  });
-
-  it('should not be reactive to changes within the implementation', () => {
-    const registry = Registry.make();
-    const context = new PluginContext({ registry, ...defaultOptions });
-    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
-
-    let count = 0;
-    const cancel = registry.subscribe(context.capabilities(interfaceDef), () => {
-      count++;
-    });
-    onTestFinished(() => cancel());
-    expect(count).toEqual(0);
-
-    registry.get(context.capabilities(interfaceDef));
-    expect(count).toEqual(1);
-
-    const implementation = { example: 'identifier' };
-    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
-    expect(count).toEqual(2);
-
-    implementation.example = 'updated';
-    expect(count).toEqual(2);
-
-    const capabilities = context.getCapabilities(interfaceDef);
-    expect(capabilities).toEqual([implementation]);
-    expect(capabilities[0].example).toEqual('updated');
-    expect(count).toEqual(2);
-  });
-
-  it('should be able to wait for a capability', async () => {
-    const registry = Registry.make();
-    const context = new PluginContext({ registry, ...defaultOptions });
-    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
-
-    let capability: { example: string } | undefined;
-    const cancel = registry.subscribe(context.capabilities(interfaceDef), (capabilities) => {
-      capability = capabilities[0];
-    });
-    onTestFinished(() => cancel());
-    registry.get(context.capabilities(interfaceDef));
-    expect(capability).toBeUndefined();
-
-    const implementation = { example: 'identifier' };
-    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
-    expect(capability).toEqual(implementation);
-  });
-});

package/src/core/capabilities.ts

@@ -1,263 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { Atom, type Registry } from '@effect-atom/atom-react';
-import * as Effect from 'effect/Effect';
-
-import { Trigger } from '@dxos/async';
-import { invariant } from '@dxos/invariant';
-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;
-};
-
-export namespace InterfaceDef {
-  export type Implementation<I extends InterfaceDef<any>> = I extends InterfaceDef<infer T> ? T : never;
-}
-
-/**
- * Helper to define the interface of a capability.
- */
-export const defineCapability = <T>(identifier: string) => {
-  return { identifier } as InterfaceDef<T>;
-};
-
-/**
- * A unique string identifier with a Typescript type associated with it.
- * When a capability is contributed to the application an implementation of the interface is provided.
- */
-export type Capability<T> = {
-  /**
-   * The interface definition of the capability.
-   */
-  readonly interface: InterfaceDef<T>;
-
-  /**
-   * The implementation of the capability.
-   */
-  readonly implementation: T;
-
-  /**
-   * Called when the capability is deactivated.
-   */
-  readonly deactivate?: () => MaybePromise<void> | Effect.Effect<void, Error>;
-};
-
-export type AnyCapability = Capability<any>;
-
-type PluginsContextOptions = {
-  registry: Registry.Registry;
-  activate: (event: ActivationEvent) => Effect.Effect<boolean, Error>;
-  reset: (event: ActivationEvent) => Effect.Effect<boolean, Error>;
-};
-
-// 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 = <I extends InterfaceDef<any>>(
-  interfaceDef: I,
-  implementation: Capability<InterfaceDef.Implementation<I>>['implementation'],
-  deactivate?: Capability<InterfaceDef.Implementation<I>>['deactivate'],
-): Capability<I> => {
-  return {
-    interface: interfaceDef,
-    implementation,
-    deactivate,
-  } satisfies Capability<I>;
-};
-
-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);
-  };
-
-/**
- * Facilitates the dependency injection between [plugin modules](#pluginmodule) by allowing them contribute and request capabilities from each other.
- * It tracks the capabilities that are contributed in an in-memory live object.
- * This allows the application to subscribe to this state and incorporate plugins which are added dynamically.
- */
-export class PluginContext {
-  private readonly _registry: Registry.Registry;
-
-  private readonly _capabilityImpls = Atom.family<string, Atom.Writable<CapabilityImpl<unknown>[]>>(() => {
-    return Atom.make<CapabilityImpl<unknown>[]>([]).pipe(Atom.keepAlive);
-  });
-
-  readonly _capabilities = Atom.family<string, Atom.Atom<unknown[]>>((id: string) => {
-    return Atom.make((get) => {
-      const current = get(this._capabilityImpls(id));
-      return current.map((c) => c.implementation);
-    });
-  });
-
-  readonly _capability = Atom.family<string, Atom.Atom<unknown>>((id: string) => {
-    return Atom.make((get) => {
-      const current = get(this._capabilities(id));
-      invariant(current.length > 0, `No capability found for ${id}`);
-      return current[0];
-    });
-  });
-
-  /**
-   * 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({ registry, activate, reset }: PluginsContextOptions) {
-    this._registry = registry;
-    this.activate = activate;
-    this.reset = reset;
-  }
-
-  /**
-   * @internal
-   */
-  contributeCapability<T>({
-    module: moduleId,
-    interface: interfaceDef,
-    implementation,
-  }: {
-    module: string;
-    interface: InterfaceDef<T>;
-    implementation: T;
-  }): void {
-    const current = this._registry.get(this._capabilityImpls(interfaceDef.identifier));
-    const capability = new CapabilityImpl(moduleId, implementation);
-    if (current.includes(capability)) {
-      return;
-    }
-
-    this._registry.set(this._capabilityImpls(interfaceDef.identifier), [...current, capability]);
-    log('capability contributed', {
-      id: interfaceDef.identifier,
-      moduleId,
-      count: current.length,
-    });
-  }
-
-  /**
-   * @internal
-   */
-  removeCapability<T>(interfaceDef: InterfaceDef<T>, implementation: T): void {
-    const current = this._registry.get(this._capabilityImpls(interfaceDef.identifier));
-    if (current.length === 0) {
-      return;
-    }
-
-    const next = current.filter((c) => c.implementation !== implementation);
-    if (next.length !== current.length) {
-      this._registry.set(this._capabilityImpls(interfaceDef.identifier), next);
-      log('capability removed', { id: interfaceDef.identifier, count: current.length });
-    } else {
-      log.warn('capability not removed', { id: interfaceDef.identifier });
-    }
-  }
-
-  /**
-   * Get the Atom reference to the available capabilities for a given interface.
-   * Primarily useful for deriving other Atom values based on the capabilities or
-   * for subscribing to changes in the capabilities.
-   * @returns An atom reference to the available capabilities.
-   */
-  capabilities<T>(interfaceDef: InterfaceDef<T>): Atom.Atom<T[]> {
-    // NOTE: This the type-checking for capabilities is done at the time of contribution.
-    return this._capabilities(interfaceDef.identifier) as Atom.Atom<T[]>;
-  }
-
-  /**
-   * Get the Atom reference to the available capabilities for a given interface.
-   * Primarily useful for deriving other Atom values based on the capability or
-   * for subscribing to changes in the capability.
-   * @returns An atom reference to the available capability.
-   * @throws If no capability is found.
-   */
-  capability<T>(interfaceDef: InterfaceDef<T>): Atom.Atom<T> {
-    // NOTE: This the type-checking for capabilities is done at the time of contribution.
-    return this._capability(interfaceDef.identifier) as Atom.Atom<T>;
-  }
-
-  /**
-   * Get capabilities from the plugin context.
-   * @returns An array of capabilities.
-   */
-  getCapabilities<T>(interfaceDef: InterfaceDef<T>): T[] {
-    return this._registry.get(this.capabilities(interfaceDef));
-  }
-
-  /**
-   * Requests a single capability from the plugin context.
-   * @returns The capability.
-   * @throws If no capability is found.
-   */
-  getCapability<T>(interfaceDef: InterfaceDef<T>): T {
-    return this._registry.get(this.capability(interfaceDef));
-  }
-
-  /**
-   * Waits for a capability to be available.
-   * @returns The capability.
-   */
-  async waitForCapability<T>(interfaceDef: InterfaceDef<T>): Promise<T> {
-    const [capability] = this.getCapabilities(interfaceDef);
-    if (capability) {
-      return capability;
-    }
-
-    const trigger = new Trigger<T>();
-    const cancel = this._registry.subscribe(this.capabilities(interfaceDef), (capabilities) => {
-      if (capabilities.length > 0) {
-        trigger.wake(capabilities[0]);
-      }
-    });
-    const result = await trigger.wait();
-    cancel();
-    return result;
-  }
-
-  async activatePromise(event: ActivationEvent): Promise<boolean> {
-    return this.activate(event).pipe(Effect.runPromise);
-  }
-
-  async resetPromise(event: ActivationEvent): Promise<boolean> {
-    return this.reset(event).pipe(Effect.runPromise);
-  }
-}