@dxos/app-framework 0.8.3 → 0.8.4-main.1068cf700f

package/src/testing/withPluginManager.tsx

@@ -2,29 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Decorator } from '@storybook/react';
+import { type Decorator, type StoryContext } from '@storybook/react';
+import * as Effect from 'effect/Effect';
 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,
-} 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 { ActivationEvents, Capabilities } from '../common';
+import { type ActivationEvent, Capability, type CapabilityManager, Plugin, PluginManager } from '../core';
+import { type UseAppOptions, useApp } from '../ui';
 
 /**
  * @internal
@@ -34,17 +22,17 @@ export const setupPluginManager = ({
   plugins = [],
   core = plugins.map(({ meta }) => meta.id),
   ...options
-}: CreateAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
-  const pluginManager = new PluginManager({
+}: UseAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
+  const pluginManager = PluginManager.make({
     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) => {
-      pluginManager.context.contributeCapability({
+    getProviderValue(capabilities, pluginManager.capabilities).forEach((capability) => {
+      pluginManager.capabilities.contribute({
         interface: capability.interface,
         implementation: capability.implementation,
         module: 'story',
@@ -55,43 +43,46 @@ export const setupPluginManager = ({
   return pluginManager;
 };
 
-export type WithPluginManagerOptions = CreateAppOptions & {
-  capabilities?: ProviderOrValue<PluginContext, AnyCapability[]>;
-  fireEvents?: (ActivationEvent | string)[];
+export type WithPluginManagerOptions = UseAppOptions & {
+  /** @deprecated */
+  capabilities?: MaybeProvider<Capability.Any[], CapabilityManager.CapabilityManager>;
+  /** @deprecated */
+  fireEvents?: (ActivationEvent.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(() => {
-      const capability = contributes(Capabilities.ReactRoot, {
+      const capability = Capability.contributes(Capabilities.ReactRoot, {
         id: context.id,
         root: () => <Story />,
       });
 
-      pluginManager.context.contributeCapability({
+      pluginManager.capabilities.contribute({
         ...capability,
         module: 'dxos.org/app-framework/withPluginManager',
       });
 
       return () => {
-        pluginManager.context.removeCapability(capability.interface, capability.implementation);
+        pluginManager.capabilities.remove(capability.interface, capability.implementation);
       };
     }, [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 +92,18 @@ 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 = Plugin.define(storyMeta).pipe(
+  Plugin.addModule({
+    id: 'Story',
+    activatesOn: ActivationEvents.Startup,
+    activate: () => Effect.succeed([]),
+  }),
+  Plugin.make,
+)();

package/src/ui/components/App.stories.tsx

@@ -0,0 +1,62 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { ActivationEvents, Capabilities } from '../../common';
+import { Capability, Plugin } from '../../core';
+import { useApp } from '../hooks';
+
+// Minimal plugin that contributes a ReactRoot.
+const TestPlugin = Plugin.define({
+  id: 'dxos.org/plugin/test',
+  name: 'Test Plugin',
+}).pipe(
+  Plugin.addModule({
+    id: 'TestMain',
+    activatesOn: ActivationEvents.Startup,
+    activate: () =>
+      Effect.succeed([
+        Capability.contributes(Capabilities.ReactRoot, {
+          id: 'dxos.org/plugin/test/root',
+          root: () => (
+            <div className='fixed inset-0 flex items-center justify-center text-2xl'>App Started Successfully!</div>
+          ),
+        }),
+      ]),
+  }),
+  Plugin.make,
+);
+
+const plugins = [TestPlugin()];
+const core = [TestPlugin.meta.id];
+
+const DefaultStory = () => {
+  const App = useApp({
+    plugins,
+    core,
+    placeholder: () => <div className='fixed inset-0 flex items-center justify-center'>Loading...</div>,
+  });
+
+  return <App />;
+};
+
+const meta = {
+  title: 'sdk/app-framework/App',
+  render: DefaultStory,
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/ui/components/App.tsx

@@ -0,0 +1,57 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+
+import { Capabilities } from '../../common';
+import { topologicalSort } from '../../helpers';
+import { LoadingState, type UseAppOptions, useCapabilities, useLoading } from '../hooks';
+
+export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
+  ready: boolean;
+  error: unknown;
+};
+
+export const App = ({ placeholder: Placeholder, ready, error, debounce }: AppProps) => {
+  const reactContexts = useCapabilities(Capabilities.ReactContext);
+  const reactRoots = useCapabilities(Capabilities.ReactRoot);
+  const stage = useLoading(ready, debounce);
+
+  if (error) {
+    // This triggers the error boundary to provide UI feedback for the startup error.
+    throw error;
+  }
+
+  // TODO(wittjosiah): Consider using Suspense instead.
+  if (stage < LoadingState.Done) {
+    if (!Placeholder) {
+      return null;
+    }
+
+    return <Placeholder stage={stage} />;
+  }
+
+  const ComposedContext = composeContexts(reactContexts);
+  return (
+    <ComposedContext>
+      {reactRoots.map(({ id, root: Component }) => (
+        <Component key={id} />
+      ))}
+    </ComposedContext>
+  );
+};
+
+const composeContexts = (contexts: Capabilities.ReactContext[]) => {
+  if (contexts.length === 0) {
+    return ({ children }: PropsWithChildren) => <>{children}</>;
+  }
+
+  return topologicalSort(contexts)
+    .map(({ context }) => context)
+    .reduce((Acc, Next) => ({ children }) => (
+      <Acc>
+        <Next>{children}</Next>
+      </Acc>
+    ));
+};

package/src/ui/components/DefaultFallback.tsx

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+/**
+ * NOTE: Default fallback should not use tailwind or theme.
+ */
+export const DefaultFallback = ({ error }: { error: Error }) => {
+  return (
+    <div
+      style={{
+        margin: '1rem',
+        padding: '1rem',
+        overflow: 'hidden',
+        border: '4px solid teal',
+        borderRadius: '1rem',
+      }}
+    >
+      {/* TODO(wittjosiah): Link to docs for replacing default. */}
+      <h1 style={{ margin: '0.5rem 0', fontSize: '1.2rem' }}>ERROR: {error.message}</h1>
+      <pre style={{ overflow: 'auto', fontSize: '1rem', whiteSpace: 'pre-wrap', color: '#888888' }}>{error.stack}</pre>
+    </div>
+  );
+};

package/src/ui/components/ErrorBoundary.tsx

@@ -0,0 +1,56 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { Component, type FC, type PropsWithChildren, type ReactNode } from 'react';
+
+type State = {
+  error: Error | undefined;
+};
+
+export type ErrorBoundaryProps = PropsWithChildren<{
+  data?: any;
+  fallback?: FC<{ data?: any; error: Error }>;
+}>;
+
+/**
+ * Surface error boundary.
+ * For basic usage prefer providing a fallback component to `Surface`.
+ *
+ * Ref: https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
+  static getDerivedStateFromError(error: Error): { error: Error } {
+    return { error };
+  }
+
+  override state = { error: undefined };
+
+  override componentDidUpdate(prevProps: ErrorBoundaryProps): void {
+    if (prevProps.data !== this.props.data) {
+      this.resetError();
+    }
+  }
+
+  override render(): ReactNode {
+    if (this.state.error) {
+      const Fallback = this.props.fallback ?? DefaultFallback;
+      return <Fallback data={this.props.data} error={this.state.error} />;
+    }
+
+    return this.props.children;
+  }
+
+  private resetError(): void {
+    this.setState({ error: undefined });
+  }
+}
+
+const DefaultFallback: NonNullable<ErrorBoundaryProps['fallback']> = ({ data, error }) => {
+  return (
+    <div className='flex flex-col gap-2 overflow-hidden border border-red-500 rounded-sm'>
+      <h1 className='p-2'>ERROR: {error.message}</h1>
+      <pre className='p-2 overflow-y-auto text-sm text-subdued'>{JSON.stringify(data, null, 2)}</pre>
+    </div>
+  );
+};

package/src/ui/components/PluginManagerContext.stories.tsx

@@ -0,0 +1,183 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom, useAtomValue } from '@effect-atom/atom-react';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React, { useEffect, useMemo, useState } from 'react';
+
+import { withTheme } from '@dxos/react-ui/testing';
+import { useWebComponentContext } from '@dxos/web-context-react';
+
+import { ActivationEvents, Capabilities } from '../../common';
+import { PluginManagerContext } from '../../context';
+import { Capability, Plugin } from '../../core';
+import { useApp } from '../hooks';
+
+// Define the Counter capability
+const Counter = Capability.make<{ count: number; increment: () => void }>('example/counter');
+
+const CountStatus = () => {
+  const manager = useWebComponentContext(PluginManagerContext);
+  const capabilitiesAtom = useMemo(
+    () => manager?.capabilities.atom(Counter) ?? Atom.make<{ count: number; increment: () => void }[]>([]),
+    [manager],
+  );
+  const capabilities = useAtomValue(capabilitiesAtom);
+  const counter = (capabilities as any)[0];
+  const [count, setCount] = useState(counter?.count ?? 0);
+
+  useEffect(() => {
+    if (!counter) {
+      return;
+    }
+    setCount(counter.count);
+    if ('subscribe' in counter && typeof counter.subscribe === 'function') {
+      return counter.subscribe(() => setCount(counter.count));
+    }
+  }, [counter]);
+
+  if (!manager) return null;
+
+  const isEven = count % 2 === 0;
+
+  return (
+    <div
+      className={`mt-4 px-4 py-2 rounded-full text-sm font-medium transition-colors ${
+        isEven
+          ? 'bg-emerald-100 text-emerald-800 dark:bg-emerald-900/30 dark:text-emerald-400'
+          : 'bg-amber-100 text-amber-800 dark:bg-amber-900/30 dark:text-amber-400'
+      }`}
+    >
+      Status: {isEven ? 'Even' : 'Odd'}
+    </div>
+  );
+};
+
+// A component that consumes the PluginManager via web context
+const CounterComponent = () => {
+  // Use the web-context hook to get the PluginManager
+  const manager = useWebComponentContext(PluginManagerContext);
+  const capabilitiesAtom = useMemo(
+    () => manager?.capabilities.atom(Counter) ?? Atom.make<{ count: number; increment: () => void }[]>([]),
+    [manager],
+  );
+  const capabilities = useAtomValue(capabilitiesAtom);
+  const counter = (capabilities as any)[0];
+  const [count, setCount] = useState(counter?.count ?? 0);
+
+  useEffect(() => {
+    if (!counter) {
+      return;
+    }
+    setCount(counter.count);
+    if ('subscribe' in counter && typeof counter.subscribe === 'function') {
+      return counter.subscribe(() => setCount(counter.count));
+    }
+  }, [counter]);
+
+  if (!manager) {
+    return <div className='p-4 text-red-500'>Error: Context not found</div>;
+  }
+
+  return (
+    <div className='flex flex-col items-center justify-center h-screen bg-neutral-100 dark:bg-neutral-900 text-neutral-900 dark:text-white'>
+      <div className='p-8 bg-white dark:bg-neutral-800 rounded-lg shadow-xl border border-neutral-200 dark:border-neutral-700 max-w-md w-full'>
+        <h2 className='text-2xl font-bold mb-6 text-center text-primary-600 dark:text-primary-400'>
+          Web Context Counter
+        </h2>
+
+        <div className='flex flex-col items-center gap-6'>
+          <div className='text-6xl font-mono font-bold tabular-nums tracking-tighter'>{count}</div>
+
+          <button
+            className='px-6 py-3 bg-primary-600 hover:bg-primary-700 text-white font-semibold rounded-full transition-colors shadow-md active:transform active:scale-95'
+            onClick={() => {
+              const counter = manager.capabilities.get(Counter);
+              counter.increment();
+            }}
+          >
+            Increment
+          </button>
+
+          <CountStatus />
+        </div>
+
+        <div className='mt-8 pt-4 border-bs border-neutral-200 dark:border-neutral-700 text-center'>
+          <p className='text-sm text-neutral-500 dark:text-neutral-400'>
+            This component accesses the <code>PluginManager</code> via <code>useWebComponentContext</code>.
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+// Plugin that provides the Counter capability and renders the UI
+const CounterPlugin = Plugin.define({
+  id: 'dxos.org/plugin/counter',
+  name: 'Counter Plugin',
+}).pipe(
+  Plugin.addModule({
+    id: 'CounterMain',
+    activatesOn: ActivationEvents.Startup,
+    activate: () => {
+      const listeners = new Set<() => void>();
+      const counter = {
+        count: 0,
+        increment: () => {
+          counter.count++;
+          listeners.forEach((listener) => listener());
+        },
+        subscribe: (listener: () => void) => {
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+      };
+
+      return Effect.succeed([
+        // Contribute the state/logic
+        Capability.contributes(Counter, counter),
+
+        // Contribute the UI
+        Capability.contributes(Capabilities.ReactRoot, {
+          id: 'dxos.org/plugin/counter/root',
+          root: CounterComponent,
+        }),
+      ]);
+    },
+  }),
+  Plugin.make,
+)();
+
+const plugins = [CounterPlugin];
+const core = ['dxos.org/plugin/counter'];
+const placeholder = () => (
+  <div className='flex h-screen items-center justify-center p-4 text-lg text-neutral-500'>
+    Initializing Application...
+  </div>
+);
+
+const DefaultStory = () => {
+  const App = useApp({
+    plugins,
+    core,
+    placeholder,
+  });
+
+  return <App />;
+};
+
+const meta = {
+  title: 'sdk/app-framework/PluginManagerContext',
+  render: DefaultStory,
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta;
+
+export default meta;
+
+export const Default: StoryObj<typeof meta> = {};

package/src/{react → ui/components}/PluginManagerProvider.ts

@@ -6,14 +6,14 @@ import { createContext, useContext } from 'react';
 
 import { raise } from '@dxos/debug';
 
-import { type PluginManager } from '../core';
+import { type PluginManager } from '../../core';
 
-const PluginManagerContext = createContext<PluginManager | undefined>(undefined);
+const PluginManagerContext = createContext<PluginManager.PluginManager | undefined>(undefined);
 
 /**
  * Get the plugin manager.
  */
-export const usePluginManager = (): PluginManager =>
+export const usePluginManager = (): PluginManager.PluginManager =>
   useContext(PluginManagerContext) ?? raise(new Error('Missing PluginManagerContext'));
 
 /**

package/src/ui/components/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './App';
+export * from './DefaultFallback';
+export * from './ErrorBoundary';
+export * from './PluginManagerProvider';