@dxos/app-framework 0.8.4-main.ae835ea → 0.8.4-main.bc674ce

package/src/components/useApp.tsx

@@ -1,164 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { RegistryContext } from '@effect-rx/rx-react';
-import { effect } from '@preact/signals-core';
-import React, { type FC, useCallback, useEffect, useMemo } from 'react';
-
-import { invariant } from '@dxos/invariant';
-import { live } from '@dxos/live-object';
-import { useAsyncEffect, useDefaultValue } from '@dxos/react-hooks';
-
-import { Capabilities, Events } from '../common';
-import { type Plugin, PluginManager, type PluginManagerOptions } from '../core';
-import { ErrorBoundary, PluginManagerProvider } from '../react';
-
-import { App } from './App';
-import { DefaultFallback } from './DefaultFallback';
-
-const ENABLED_KEY = 'dxos.org/app-framework/enabled';
-
-export type UseAppOptions = {
-  pluginManager?: PluginManager;
-  pluginLoader?: PluginManagerOptions['pluginLoader'];
-  plugins?: Plugin[];
-  core?: string[];
-  defaults?: string[];
-  placeholder?: FC<{ stage: number }>;
-  fallback?: ErrorBoundary['props']['fallback'];
-  cacheEnabled?: boolean;
-  safeMode?: boolean;
-  debounce?: number;
-};
-
-/**
- * Expected usage is for this to be the entrypoint of the application.
- * Initializes plugins and renders the root components.
- *
- * @example
- * const plugins = [LayoutPlugin(), MyPlugin()];
- * const core = [LayoutPluginId];
- * const default = [MyPluginId];
- * const fallback = <div>Initializing Plugins...</div>;
- * const App = useApp({ plugins, core, default, fallback });
- * createRoot(document.getElementById('root')!).render(
- *   <StrictMode>
- *     <App />
- *   </StrictMode>,
- * );
- *
- * @param params.pluginLoader A function which loads new plugins.
- * @param params.plugins All plugins available to the application.
- * @param params.core Core plugins which will always be enabled.
- * @param params.defaults Default plugins are enabled by default but can be disabled by the user.
- * @param params.placeholder Placeholder component to render during startup.
- * @param params.fallback Fallback component to render if an error occurs during startup.
- * @param params.cacheEnabled Whether to cache enabled plugins in localStorage.
- * @param params.safeMode Whether to enable safe mode, which disables optional plugins.
- */
-export const useApp = ({
-  pluginManager,
-  pluginLoader: _pluginLoader,
-  plugins: _plugins,
-  core: _core,
-  defaults: _defaults,
-  placeholder,
-  fallback = DefaultFallback,
-  cacheEnabled = false,
-  safeMode = false,
-  debounce = 0,
-}: UseAppOptions) => {
-  const plugins = useDefaultValue(_plugins, () => []);
-  const core = useDefaultValue(_core, () => plugins.map(({ meta }) => meta.id));
-  const defaults = useDefaultValue(_defaults, () => []);
-
-  // TODO(wittjosiah): Provide a custom plugin loader which supports loading via url.
-  const pluginLoader = useMemo(
-    () =>
-      _pluginLoader ??
-      ((id: string) => {
-        const plugin = plugins.find((plugin) => plugin.meta.id === id);
-        invariant(plugin, `Plugin not found: ${id}`);
-        return plugin;
-      }),
-    [_pluginLoader, plugins],
-  );
-
-  const state = useMemo(() => live({ ready: false, error: null }), []);
-  const cached: string[] = useMemo(() => JSON.parse(localStorage.getItem(ENABLED_KEY) ?? '[]'), []);
-  const enabled = useMemo(
-    () => (safeMode ? [] : cacheEnabled && cached.length > 0 ? cached : defaults),
-    [safeMode, cacheEnabled, cached, defaults],
-  );
-  const manager = useMemo(
-    () => pluginManager ?? new PluginManager({ pluginLoader, plugins, core, enabled }),
-    [pluginManager, pluginLoader, plugins, core, enabled],
-  );
-
-  useEffect(() => {
-    return manager.activation.on(({ event, state: _state, error }) => {
-      // Once the app is ready the first time, don't show the fallback again.
-      if (!state.ready && event === Events.Startup.id) {
-        state.ready = _state === 'activated';
-      }
-
-      if (error && !state.ready && !state.error) {
-        state.error = error;
-      }
-    });
-  }, [manager, state]);
-
-  useEffect(() => {
-    effect(() => {
-      cacheEnabled && localStorage.setItem(ENABLED_KEY, JSON.stringify(manager.enabled));
-    });
-  }, [cacheEnabled, manager]);
-
-  useEffect(() => {
-    setupDevtools(manager);
-  }, [manager]);
-
-  useAsyncEffect(async () => {
-    manager.context.contributeCapability({
-      interface: Capabilities.PluginManager,
-      implementation: manager,
-      module: 'dxos.org/app-framework/plugin-manager',
-    });
-
-    manager.context.contributeCapability({
-      interface: Capabilities.RxRegistry,
-      implementation: manager.registry,
-      module: 'dxos.org/app-framework/rx-registry',
-    });
-
-    await Promise.all([
-      // TODO(wittjosiah): Factor out such that this could be called per surface role when attempting to render.
-      manager.activate(Events.SetupReactSurface),
-      manager.activate(Events.Startup),
-    ]);
-
-    return () => {
-      manager.context.removeCapability(Capabilities.PluginManager, manager);
-      manager.context.removeCapability(Capabilities.RxRegistry, manager.registry);
-    };
-  }, [manager]);
-
-  return useCallback(
-    () => (
-      <ErrorBoundary fallback={fallback}>
-        <PluginManagerProvider value={manager}>
-          <RegistryContext.Provider value={manager.registry}>
-            <App placeholder={placeholder} state={state} debounce={debounce} />
-          </RegistryContext.Provider>
-        </PluginManagerProvider>
-      </ErrorBoundary>
-    ),
-    [fallback, manager, placeholder, state],
-  );
-};
-
-const setupDevtools = (manager: PluginManager) => {
-  (globalThis as any).composer ??= {};
-  (globalThis as any).composer.manager = manager;
-};

package/src/core/capabilities.test.ts

@@ -1,136 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { Registry } from '@effect-rx/rx-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 { type Registry, Rx } from '@effect-rx/rx-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.
-   */
-  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>, T = InterfaceDef.Implementation<I>>(
-  interfaceDef: I,
-  implementation: T,
-  deactivate?: Capability<InterfaceDef.Implementation<I>>['deactivate'],
-): Capability<I> => {
-  return {
-    interface: interfaceDef,
-    implementation: implementation as any, // NOTE: Added to allow providing readonly 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 = Rx.family<string, Rx.Writable<CapabilityImpl<unknown>[]>>(() => {
-    return Rx.make<CapabilityImpl<unknown>[]>([]).pipe(Rx.keepAlive);
-  });
-
-  readonly _capabilities = Rx.family<string, Rx.Rx<unknown[]>>((id: string) => {
-    return Rx.make((get) => {
-      const current = get(this._capabilityImpls(id));
-      return current.map((c) => c.implementation);
-    });
-  });
-
-  readonly _capability = Rx.family<string, Rx.Rx<unknown>>((id: string) => {
-    return Rx.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 Rx reference to the available capabilities for a given interface.
-   * Primarily useful for deriving other Rx values based on the capabilities or
-   * for subscribing to changes in the capabilities.
-   * @returns An Rx reference to the available capabilities.
-   */
-  capabilities<T>(interfaceDef: InterfaceDef<T>): Rx.Rx<T[]> {
-    // NOTE: This the type-checking for capabilities is done at the time of contribution.
-    return this._capabilities(interfaceDef.identifier) as Rx.Rx<T[]>;
-  }
-
-  /**
-   * Get the Rx reference to the available capabilities for a given interface.
-   * Primarily useful for deriving other Rx values based on the capability or
-   * for subscribing to changes in the capability.
-   * @returns An Rx reference to the available capability.
-   * @throws If no capability is found.
-   */
-  capability<T>(interfaceDef: InterfaceDef<T>): Rx.Rx<T> {
-    // NOTE: This the type-checking for capabilities is done at the time of contribution.
-    return this._capability(interfaceDef.identifier) as Rx.Rx<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);
-  }
-}