@dxos/app-framework 0.8.4-main.f9ba587 → 0.8.4-main.fffef41

package/src/react/Surface.tsx

@@ -2,76 +2,108 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { memo, forwardRef, Suspense, useMemo, Fragment } from 'react';
+import React, {
+  Fragment,
+  type NamedExoticComponent,
+  type RefAttributes,
+  Suspense,
+  forwardRef,
+  memo,
+  useMemo,
+} from 'react';
 
 import { useDefaultValue } from '@dxos/react-hooks';
 import { byPosition } from '@dxos/util';
 
-import { ErrorBoundary } from './ErrorBoundary';
-import { useCapabilities } from './useCapabilities';
 import { Capabilities, type SurfaceDefinition, type SurfaceProps } from '../common';
 import { type PluginContext } from '../core';
 
-const DEFAULT_PLACEHOLDER = <Fragment />;
-
-/**
- * @internal
- */
-export const useSurfaces = () => {
-  const surfaces = useCapabilities(Capabilities.ReactSurface);
-  return useMemo(() => surfaces.flat(), [surfaces]);
-};
-
-const findCandidates = (surfaces: SurfaceDefinition[], { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
-  return Object.values(surfaces)
-    .filter((definition) =>
-      Array.isArray(definition.role) ? definition.role.includes(role) : definition.role === role,
-    )
-    .filter(({ filter }) => (filter ? filter(data ?? {}) : true))
-    .toSorted(byPosition);
-};
+import { ErrorBoundary } from './ErrorBoundary';
+import { useCapabilities } from './useCapabilities';
 
-/**
- * @returns `true` if there is a contributed surface which matches the specified role & data, `false` otherwise.
- */
-export const isSurfaceAvailable = (context: PluginContext, { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
-  const surfaces = context.getCapabilities(Capabilities.ReactSurface);
-  const candidates = findCandidates(surfaces.flat(), { role, data });
-  return candidates.length > 0;
-};
+const DEFAULT_PLACEHOLDER = <Fragment />;
 
 /**
  * A surface is a named region of the screen that can be populated by plugins.
  */
-export const Surface = memo(
-  forwardRef<HTMLElement, SurfaceProps>(
-    ({ id: _id, role, data: _data, limit, fallback, placeholder = DEFAULT_PLACEHOLDER, ...rest }, forwardedRef) => {
+export const Surface: NamedExoticComponent<SurfaceProps & RefAttributes<HTMLElement>> = memo(
+  forwardRef(
+    (
+      { id: _id, role, data: dataParam, limit, fallback = DefaultFallback, placeholder = DEFAULT_PLACEHOLDER, ...rest },
+      forwardedRef,
+    ) => {
       // TODO(wittjosiah): This will make all surfaces depend on a single signal.
       //   This isn't ideal because it means that any change to the data will cause all surfaces to re-render.
       //   This effectively means that plugin modules which contribute surfaces need to all be activated at startup.
-      //   This should be fine for now because it's how it worked prior to capabilities api anyways.
+      //   This should be fine for now because it's how it worked prior to capabilities api anyway.
       //   In the future, it would be nice to be able to bucket the surface contributions by role.
       const surfaces = useSurfaces();
-      const data = useDefaultValue(_data, () => ({}));
+      const data = useDefaultValue(dataParam, () => ({}));
 
       // NOTE: Memoizing the candidates makes the surface not re-render based on reactivity within data.
       const definitions = findCandidates(surfaces, { role, data });
       const candidates = limit ? definitions.slice(0, limit) : definitions;
-      const nodes = candidates.map(({ component: Component, id }) => (
+      const nodes = candidates.map(({ id, component: Component }) => (
         <Component ref={forwardedRef} key={id} id={id} role={role} data={data} limit={limit} {...rest} />
       ));
 
+      // TODO(burdon): Able to inject DOM properties into root (e.g., object.id).
       const suspense = <Suspense fallback={placeholder}>{nodes}</Suspense>;
 
-      return fallback ? (
+      return (
         <ErrorBoundary data={data} fallback={fallback}>
           {suspense}
         </ErrorBoundary>
-      ) : (
-        suspense
       );
     },
   ),
 );
 
+// TODO(burdon): Make user facing, with telemetry.
+// TODO(burdon): Change based on dev/prod mode; infer subject type, id.
+const DefaultFallback = ({ data, error, dev }: { data: any; error: Error; dev?: boolean }) => {
+  if (dev) {
+    return (
+      <div className='flex flex-col gap-4 p-4 is-full overflow-y-auto'>
+        <h1 className='flex gap-2 text-sm mbs-2'>{error.message}</h1>
+        <pre className='overflow-auto text-xs text-description'>{JSON.stringify(data, null, 2)}</pre>
+      </div>
+    );
+  }
+
+  return (
+    <div className='flex flex-col gap-4 p-4 is-full overflow-y-auto border border-roseFill'>
+      <h1 className='flex gap-2 text-sm mbs-2 text-rose-500'>{error.message}</h1>
+      <pre className='overflow-auto text-xs text-description'>{error.stack}</pre>
+      <pre className='overflow-auto text-xs text-description'>{JSON.stringify(data, null, 2)}</pre>
+    </div>
+  );
+};
+
+/**
+ * @internal
+ */
+export const useSurfaces = () => {
+  const surfaces = useCapabilities(Capabilities.ReactSurface);
+  return useMemo(() => surfaces.flat(), [surfaces]);
+};
+
+/**
+ * @returns `true` if there is a contributed surface which matches the specified role & data, `false` otherwise.
+ */
+export const isSurfaceAvailable = (context: PluginContext, { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
+  const surfaces = context.getCapabilities(Capabilities.ReactSurface);
+  const candidates = findCandidates(surfaces.flat(), { role, data });
+  return candidates.length > 0;
+};
+
+const findCandidates = (surfaces: SurfaceDefinition[], { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
+  return Object.values(surfaces)
+    .filter((definition) =>
+      Array.isArray(definition.role) ? definition.role.includes(role) : definition.role === role,
+    )
+    .filter(({ filter }) => (filter ? filter(data ?? {}) : true))
+    .toSorted(byPosition);
+};
+
 Surface.displayName = 'Surface';

package/src/react/common.ts

@@ -2,9 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useCapability } from './useCapabilities';
 import { Capabilities } from '../common';
 
+import { useCapability } from './useCapabilities';
+
 export const useIntentDispatcher = () => useCapability(Capabilities.IntentDispatcher);
 
 export const useAppGraph = () => useCapability(Capabilities.AppGraph);

package/src/react/index.ts

@@ -3,8 +3,12 @@
 //
 
 export * from './common';
+export * from './types';
+
 export * from './ErrorBoundary';
 export * from './PluginManagerProvider';
 export * from './Surface';
+
+export * from './useApp';
 export * from './useCapabilities';
 export * from './useIntentResolver';

package/src/react/types.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { type Obj } from '@dxos/echo';
+
+export const SurfaceCardRole = Schema.Literal(
+  'card',
+  'card--popover',
+  'card--intrinsic',
+  'card--extrinsic',
+  'card--transclusion',
+);
+
+export type SurfaceCardRole = Schema.Schema.Type<typeof SurfaceCardRole>;
+
+// TODO(burdon): Define all roles.
+export type SurfaceRole =
+  | 'item'
+  | 'article'
+  | 'complementary' // (for companion?)
+  | 'section'
+  | SurfaceCardRole;
+
+/**
+ * Base type for surface components.
+ */
+// TODO(burdon): Standardize PluginSettings and ObjectProperties.
+// TODO(burdon): Include attendableId?
+// TODO(burdon): companionTo?
+export type SurfaceComponentProps<Subject extends Obj.Any = Obj.Any, Role extends string = string> = {
+  role?: Role;
+
+  /** The primary object being displayed. */
+  subject: Subject;
+};

package/src/react/useApp.tsx

@@ -0,0 +1,165 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { RegistryContext } from '@effect-atom/atom-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 { App } from './App';
+import { DefaultFallback } from './DefaultFallback';
+import { ErrorBoundary } from './ErrorBoundary';
+import { PluginManagerProvider } from './PluginManagerProvider';
+
+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: pluginLoaderParam,
+  plugins: pluginsParam,
+  core: coreParam,
+  defaults: defaultsParam,
+  placeholder,
+  fallback = DefaultFallback,
+  cacheEnabled = false,
+  safeMode = false,
+  debounce = 0,
+}: UseAppOptions) => {
+  const plugins = useDefaultValue(pluginsParam, () => []);
+  const core = useDefaultValue(coreParam, () => plugins.map(({ meta }) => meta.id));
+  const defaults = useDefaultValue(defaultsParam, () => []);
+
+  // TODO(wittjosiah): Provide a custom plugin loader which supports loading via url.
+  const pluginLoader = useMemo(
+    () =>
+      pluginLoaderParam ??
+      ((id: string) => {
+        const plugin = plugins.find((plugin) => plugin.meta.id === id);
+        invariant(plugin, `Plugin not found: ${id}`);
+        return plugin;
+      }),
+    [pluginLoaderParam, 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.AtomRegistry,
+      implementation: manager.registry,
+      module: 'dxos.org/app-framework/atom-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.AtomRegistry, 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/react/useCapabilities.ts

@@ -2,20 +2,21 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useRxValue } from '@effect-rx/rx-react';
+import { useAtomValue } from '@effect-atom/atom-react';
 
 import { invariant } from '@dxos/invariant';
 
-import { usePluginManager } from './PluginManagerProvider';
 import { type InterfaceDef } from '../core';
 
+import { usePluginManager } from './PluginManagerProvider';
+
 /**
  * Hook to request capabilities from the plugin context.
  * @returns An array of capabilities.
  */
 export const useCapabilities = <T>(interfaceDef: InterfaceDef<T>) => {
   const manager = usePluginManager();
-  return useRxValue(manager.context.capabilities(interfaceDef));
+  return useAtomValue(manager.context.capabilities(interfaceDef));
 };
 
 /**

package/src/react/useLoading.tsx

@@ -0,0 +1,70 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useEffect, useState } from 'react';
+
+import { type AppProps } from './App';
+
+export enum LoadingState {
+  Loading = 0,
+  FadeIn = 1,
+  FadeOut = 2,
+  Done = 3,
+}
+
+/**
+ * To avoid "flashing" the placeholder, we wait a period of time before starting the loading animation.
+ * If loading completes during this time the placehoder is not shown, otherwise is it displayed for a minimum period of time.
+ *
+ * States:
+ * 0: Loading   - Wait for a period of time before starting the loading animation.
+ * 1: Fade-in   - Display a loading animation.
+ * 2: Fade-out  - Fade out the loading animation.
+ * 3: Done      - Remove the placeholder.
+ */
+export const useLoading = (state: AppProps['state'], debounce = 0) => {
+  const [stage, setStage] = useState<LoadingState>(LoadingState.Loading);
+  useEffect(() => {
+    if (!debounce) {
+      return;
+    }
+
+    const i = setInterval(() => {
+      setStage((stage) => {
+        switch (stage) {
+          case LoadingState.Loading: {
+            if (!state.ready) {
+              return LoadingState.FadeIn;
+            } else {
+              clearInterval(i);
+              return LoadingState.Done;
+            }
+          }
+
+          case LoadingState.FadeIn: {
+            if (state.ready) {
+              return LoadingState.FadeOut;
+            }
+            break;
+          }
+
+          case LoadingState.FadeOut: {
+            clearInterval(i);
+            return LoadingState.Done;
+          }
+        }
+
+        return stage;
+      });
+    }, debounce);
+
+    return () => clearInterval(i);
+  }, [debounce]);
+
+  if (!debounce) {
+    return state.ready ? LoadingState.Done : LoadingState.Loading;
+  }
+
+  return stage;
+};

package/src/testing/withPluginManager.stories.tsx

@@ -2,15 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
-import { withTheme, type Meta } from '@dxos/storybook-utils';
+import { withTheme } from '@dxos/react-ui/testing';
 
-import { withPluginManager } from './withPluginManager';
 import { Capabilities, createSurface } from '../common';
 import { contributes } from '../core';
 import { Surface } from '../react';
 
+import { withPluginManager } from './withPluginManager';
+
 const DefaultStory = () => {
   console.log('Render');
   return (
@@ -21,7 +23,7 @@ const DefaultStory = () => {
   );
 };
 
-const meta: Meta = {
+const meta = {
   title: 'sdk/app-framework/withPluginManager',
   render: DefaultStory,
   decorators: [
@@ -39,8 +41,10 @@ const meta: Meta = {
       ],
     }),
   ],
-};
+} satisfies Meta<typeof DefaultStory>;
 
 export default meta;
 
-export const Default = {};
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/testing/withPluginManager.tsx

@@ -2,29 +2,24 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Decorator } from '@storybook/react';
+import { type Decorator, type StoryContext } from '@storybook/react';
 import React, { useEffect, useMemo } from 'react';
 
 import { raise } from '@dxos/debug';
+import { useAsyncEffect } from '@dxos/react-hooks';
+import { type MaybeProvider, getProviderValue } from '@dxos/util';
 
-import { useApp, type CreateAppOptions } from '../App';
 import { Capabilities, Events } from '../common';
 import {
-  contributes,
-  defineModule,
-  definePlugin,
   type ActivationEvent,
   type AnyCapability,
-  PluginManager,
   type PluginContext,
+  PluginManager,
+  contributes,
+  defineModule,
+  definePlugin,
 } from '../core';
-
-// TODO(burdon): Factor out (use consistently in plugin framework?)
-export type Provider<C, R> = (context: C) => R;
-export type ProviderOrValue<C, R> = Provider<C, R> | R;
-export const getValue = <C, R>(providerOrValue: ProviderOrValue<C, R>, context: C): R => {
-  return typeof providerOrValue === 'function' ? (providerOrValue as Provider<C, R>)(context) : providerOrValue;
-};
+import { type UseAppOptions, useApp } from '../react';
 
 /**
  * @internal
@@ -34,16 +29,16 @@ export const setupPluginManager = ({
   plugins = [],
   core = plugins.map(({ meta }) => meta.id),
   ...options
-}: CreateAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
+}: UseAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
   const pluginManager = new PluginManager({
     pluginLoader: () => raise(new Error('Not implemented')),
-    plugins: [storyPlugin(), ...plugins],
-    core: [STORY_PLUGIN, ...core],
+    plugins: [StoryPlugin(), ...plugins],
+    core: [StoryPlugin.meta.id, ...core],
     ...options,
   });
 
   if (capabilities) {
-    getValue(capabilities, pluginManager.context).forEach((capability) => {
+    getProviderValue(capabilities, pluginManager.context).forEach((capability) => {
       pluginManager.context.contributeCapability({
         interface: capability.interface,
         implementation: capability.implementation,
@@ -55,18 +50,25 @@ export const setupPluginManager = ({
   return pluginManager;
 };
 
-export type WithPluginManagerOptions = CreateAppOptions & {
-  capabilities?: ProviderOrValue<PluginContext, AnyCapability[]>;
+export type WithPluginManagerOptions = UseAppOptions & {
+  /** @deprecated */
+  capabilities?: MaybeProvider<AnyCapability[], PluginContext>;
+  /** @deprecated */
   fireEvents?: (ActivationEvent | string)[];
 };
 
+export type WithPluginManagerInitializer<Args = void> =
+  | WithPluginManagerOptions
+  | ((context: StoryContext<Args>) => WithPluginManagerOptions);
+
 /**
  * Wraps a story with a plugin manager.
  * NOTE: This builds up and tears down the plugin manager on every render.
  */
-export const withPluginManager = (options: WithPluginManagerOptions = {}): Decorator => {
+export const withPluginManager = <Args,>(init: WithPluginManagerInitializer<Args> = {}): Decorator => {
   return (Story, context) => {
-    const pluginManager = useMemo(() => setupPluginManager(options), [options]);
+    const options = typeof init === 'function' ? init(context as any) : init;
+    const pluginManager = useMemo(() => setupPluginManager(options), [init]);
 
     // Set-up root capability.
     useEffect(() => {
@@ -86,12 +88,8 @@ export const withPluginManager = (options: WithPluginManagerOptions = {}): Decor
     }, [pluginManager, context]);
 
     // Fire events.
-    useEffect(() => {
-      const timeout = setTimeout(async () => {
-        await Promise.all(options.fireEvents?.map((event) => pluginManager.activate(event)) ?? []);
-      });
-
-      return () => clearTimeout(timeout);
+    useAsyncEffect(async () => {
+      await Promise.all(options.fireEvents?.map((event) => pluginManager.activate(event)) ?? []);
     }, [pluginManager]);
 
     // Create app.
@@ -101,10 +99,13 @@ export const withPluginManager = (options: WithPluginManagerOptions = {}): Decor
   };
 };
 
+const storyMeta = {
+  id: 'dxos.org/app-framework/story',
+  name: 'Story',
+};
+
 // No-op plugin to ensure there exists at least one plugin for the startup event.
 // This is necessary because `createApp` expects the startup event to complete before the app is ready.
-const STORY_PLUGIN = 'dxos.org/app-framework/story';
-const storyPlugin = () =>
-  definePlugin({ id: STORY_PLUGIN, name: 'Story' }, [
-    defineModule({ id: STORY_PLUGIN, activatesOn: Events.Startup, activate: () => [] }),
-  ]);
+const StoryPlugin = definePlugin(storyMeta, () => [
+  defineModule({ id: storyMeta.id, activatesOn: Events.Startup, activate: () => [] }),
+]);