@dxos/app-framework 0.8.4-main.5ea62a8 → 0.8.4-main.72ec0f3

package/src/react/Surface.stories.tsx

@@ -2,98 +2,119 @@
 // Copyright 2025 DXOS.org
 //
 
-import '@dxos-theme';
-
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { useCallback, useState } from 'react';
+import React, { useCallback, useEffect, useState } from 'react';
 
 import { faker } from '@dxos/random';
-import { Button, List, ListItem } from '@dxos/react-ui';
-import { withLayout, withTheme } from '@dxos/storybook-utils';
+import { List, ListItem, Toolbar } from '@dxos/react-ui';
+import { withTheme } from '@dxos/react-ui/testing';
+import { getHashStyles, mx } from '@dxos/react-ui-theme';
 
 import { Capabilities, createSurface } from '../common';
-import { type PluginManager } from '../core';
-import { setupPluginManager } from '../testing';
+import { withPluginManager } from '../testing';
 
-import { PluginManagerProvider, usePluginManager } from './PluginManagerProvider';
+import { usePluginManager } from './PluginManagerProvider';
 import { Surface, useSurfaces } from './Surface';
 
-const randomColor = (): string => {
-  const hue = faker.number.int({ min: 0, max: 360 });
-  const saturation = faker.number.int({ min: 50, max: 90 });
-  const lightness = faker.number.int({ min: 40, max: 70 });
-  return `hsl(${hue}, ${saturation}%, ${lightness}%)`;
-};
-
-const Component = () => {
+const DefaultStory = () => {
+  const [selected, setSelected] = useState<string | undefined>();
   const manager = usePluginManager();
   const surfaces = useSurfaces();
-  const [picked, setPicked] = useState('test');
 
   const handleAdd = useCallback(() => {
-    const id = `test-${faker.number.int({ min: 0, max: 1_000_000 })}`;
-    const backgroundColor = randomColor();
+    const id = `test-${faker.number.int({ min: 0, max: 1_000 })}`;
+    const styles = getHashStyles(id);
 
     manager.context.contributeCapability({
       module: 'test',
       interface: Capabilities.ReactSurface,
       implementation: createSurface({
         id,
-        role: id,
+        role: 'item',
+        filter: (data): data is any => (data as any)?.id === id,
         component: () => (
-          <div className='flex-1' style={{ backgroundColor }}>
-            {id}
+          <div className={mx('flex justify-center items-center border rounded', styles.surface, styles.border)}>
+            <span className={mx('dx-tag font-mono text-lg', styles.text)}>{id}</span>
           </div>
         ),
       }),
     });
 
-    setPicked(id);
+    setSelected(id);
   }, [manager]);
 
-  const handlePick = useCallback(() => {
-    setPicked(faker.helpers.arrayElement(surfaces).id);
+  const handleSelect = useCallback(() => {
+    setSelected(faker.helpers.arrayElement(surfaces)?.id);
   }, [surfaces]);
 
+  const handleError = useCallback(() => {
+    manager.context.contributeCapability({
+      module: 'error',
+      interface: Capabilities.ReactSurface,
+      implementation: createSurface({
+        id: 'error',
+        role: 'item',
+        filter: (data): data is any => (data as any)?.id === 'error',
+        component: () => {
+          const [count, setCount] = useState(3);
+          useEffect(() => {
+            const interval = setInterval(() => {
+              setCount((count) => {
+                if (count <= 1) {
+                  clearInterval(interval);
+                }
+
+                return count - 1;
+              });
+            }, 1_000);
+            return () => clearInterval(interval);
+          }, []);
+
+          if (count <= 0) {
+            throw new Error('BANG!');
+          }
+
+          return (
+            <div className='flex justify-center items-center border border-roseFill rounded'>
+              <span className='font-mono'>Ticking... {count}</span>
+            </div>
+          );
+        },
+      }),
+    });
+
+    setSelected('error');
+  }, [manager]);
+
   return (
-    <div className='flex flex-col gap-2'>
-      <div className='flex gap-2'>
-        <Button onClick={handleAdd}>Add</Button>
-        <Button onClick={handlePick}>Pick</Button>
-      </div>
-      <div className='flex gap-2'>
-        <div className='flex-1'>
-          <List itemSizes='one'>
+    <div className='flex flex-col bs-full overflow-hidden'>
+      <Toolbar.Root>
+        <Toolbar.Button onClick={handleAdd}>Add</Toolbar.Button>
+        <Toolbar.Button onClick={handleSelect}>Pick</Toolbar.Button>
+        <Toolbar.Button onClick={handleError}>Error</Toolbar.Button>
+      </Toolbar.Root>
+      <div className='grid grid-cols-2 bs-full gap-4 overflow-hidden'>
+        <Surface role='item' data={selected ? { id: selected } : undefined} limit={1} />
+        <div className='overflow-y-auto bs-full'>
+          <List>
             {surfaces.map((surface) => (
               <ListItem.Root key={surface.id} id={surface.id}>
-                <ListItem.Heading classNames='grow pbs-2'>{surface.id}</ListItem.Heading>
+                <ListItem.Heading classNames='flex items-center'>{surface.id}</ListItem.Heading>
               </ListItem.Root>
             ))}
           </List>
         </div>
-        <div className='flex-1'>
-          <Surface role={picked} limit={1} />
-        </div>
       </div>
     </div>
   );
 };
 
-const DefaultStory = (props: { manager: PluginManager }) => {
-  return (
-    <PluginManagerProvider value={props.manager}>
-      <Component />
-    </PluginManagerProvider>
-  );
-};
-
 const meta = {
   title: 'sdk/app-framework/Surface',
   render: DefaultStory,
-  // NOTE: Intentionally not using withPluginManager to try to reduce surface area of the story.
-  decorators: [withTheme, withLayout()],
-  args: {
-    manager: setupPluginManager(),
+  decorators: [withTheme, withPluginManager({ capabilities: [] })],
+  parameters: {
+    layout: 'fullscreen',
   },
 } satisfies Meta<typeof DefaultStory>;
 

package/src/react/Surface.tsx

@@ -2,7 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { Fragment, Suspense, forwardRef, memo, useMemo } 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';
@@ -15,64 +23,87 @@ import { useCapabilities } from './useCapabilities';
 
 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);
-};
-
-/**
- * @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;
-};
-
 /**
  * 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/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,37 @@
+//
+// 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?
+export type SurfaceComponentProps<Subject extends Obj.Any = Obj.Any, Props = {}, Role extends string = string> = {
+  role?: Role;
+
+  /** The object being displayed. */
+  subject: Subject;
+} & Props;

package/src/{App.tsx → react/useApp.tsx}

@@ -2,22 +2,25 @@
 // Copyright 2025 DXOS.org
 //
 
-import { RegistryContext } from '@effect-rx/rx-react';
+import { RegistryContext } from '@effect-atom/atom-react';
 import { effect } from '@preact/signals-core';
-import React, { type FC, type PropsWithChildren, useCallback, useEffect, useMemo, useState } from 'react';
+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 { topologicalSort } from './helpers';
-import { ErrorBoundary, PluginManagerProvider, useCapabilities } from './react';
+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 CreateAppOptions = {
+export type UseAppOptions = {
   pluginManager?: PluginManager;
   pluginLoader?: PluginManagerOptions['pluginLoader'];
   plugins?: Plugin[];
@@ -27,6 +30,7 @@ export type CreateAppOptions = {
   fallback?: ErrorBoundary['props']['fallback'];
   cacheEnabled?: boolean;
   safeMode?: boolean;
+  debounce?: number;
 };
 
 /**
@@ -38,7 +42,7 @@ export type CreateAppOptions = {
  * const core = [LayoutPluginId];
  * const default = [MyPluginId];
  * const fallback = <div>Initializing Plugins...</div>;
- * const App = createApp({ plugins, core, default, fallback });
+ * const App = useApp({ plugins, core, default, fallback });
  * createRoot(document.getElementById('root')!).render(
  *   <StrictMode>
  *     <App />
@@ -56,29 +60,30 @@ export type CreateAppOptions = {
  */
 export const useApp = ({
   pluginManager,
-  pluginLoader: _pluginLoader,
-  plugins: _plugins,
-  core: _core,
-  defaults: _defaults,
+  pluginLoader: pluginLoaderParam,
+  plugins: pluginsParam,
+  core: coreParam,
+  defaults: defaultsParam,
   placeholder,
   fallback = DefaultFallback,
   cacheEnabled = false,
   safeMode = false,
-}: CreateAppOptions) => {
-  const plugins = useDefaultValue(_plugins, () => []);
-  const core = useDefaultValue(_core, () => plugins.map(({ meta }) => meta.id));
-  const defaults = useDefaultValue(_defaults, () => []);
+  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(
     () =>
-      _pluginLoader ??
+      pluginLoaderParam ??
       ((id: string) => {
         const plugin = plugins.find((plugin) => plugin.meta.id === id);
         invariant(plugin, `Plugin not found: ${id}`);
         return plugin;
       }),
-    [_pluginLoader, plugins],
+    [pluginLoaderParam, plugins],
   );
 
   const state = useMemo(() => live({ ready: false, error: null }), []);
@@ -112,6 +117,10 @@ export const useApp = ({
   }, [cacheEnabled, manager]);
 
   useEffect(() => {
+    setupDevtools(manager);
+  }, [manager]);
+
+  useAsyncEffect(async () => {
     manager.context.contributeCapability({
       interface: Capabilities.PluginManager,
       implementation: manager,
@@ -119,27 +128,21 @@ export const useApp = ({
     });
 
     manager.context.contributeCapability({
-      interface: Capabilities.RxRegistry,
+      interface: Capabilities.AtomRegistry,
       implementation: manager.registry,
-      module: 'dxos.org/app-framework/rx-registry',
+      module: 'dxos.org/app-framework/atom-registry',
     });
 
-    return () => {
-      manager.context.removeCapability(Capabilities.PluginManager, manager);
-      manager.context.removeCapability(Capabilities.RxRegistry, manager.registry);
-    };
-  }, [manager]);
-
-  useEffect(() => {
-    setupDevtools(manager);
-  }, [manager]);
-
-  useAsyncEffect(async () => {
     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(
@@ -147,7 +150,7 @@ export const useApp = ({
       <ErrorBoundary fallback={fallback}>
         <PluginManagerProvider value={manager}>
           <RegistryContext.Provider value={manager.registry}>
-            <App placeholder={placeholder} state={state} />
+            <App placeholder={placeholder} state={state} debounce={debounce} />
           </RegistryContext.Provider>
         </PluginManagerProvider>
       </ErrorBoundary>
@@ -156,124 +159,6 @@ export const useApp = ({
   );
 };
 
-const DELAY_PLACEHOLDER = 2_000;
-
-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.
- */
-const useLoading = (state: AppProps['state']) => {
-  const [stage, setStage] = useState<LoadingState>(LoadingState.Loading);
-  useEffect(() => {
-    const i = setInterval(() => {
-      setStage((tick) => {
-        switch (tick) {
-          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 tick;
-      });
-    }, DELAY_PLACEHOLDER);
-
-    return () => clearInterval(i);
-  }, []);
-
-  return stage;
-};
-
-type AppProps = Pick<CreateAppOptions, 'placeholder'> & {
-  state: { ready: boolean; error: unknown };
-};
-
-const App = ({ placeholder: Placeholder, state }: AppProps) => {
-  const reactContexts = useCapabilities(Capabilities.ReactContext);
-  const reactRoots = useCapabilities(Capabilities.ReactRoot);
-  const stage = useLoading(state);
-
-  if (state.error) {
-    // This triggers the error boundary to provide UI feedback for the startup error.
-    throw state.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>
-  );
-};
-
-// Default fallback does not use tailwind or theme.
-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>
-  );
-};
-
-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>
-    ));
-};
-
 const setupDevtools = (manager: PluginManager) => {
   (globalThis as any).composer ??= {};
   (globalThis as any).composer.manager = manager;

package/src/react/useCapabilities.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useRxValue } from '@effect-rx/rx-react';
+import { useAtomValue } from '@effect-atom/atom-react';
 
 import { invariant } from '@dxos/invariant';
 
@@ -16,7 +16,7 @@ import { usePluginManager } from './PluginManagerProvider';
  */
 export const useCapabilities = <T>(interfaceDef: InterfaceDef<T>) => {
   const manager = usePluginManager();
-  return useRxValue(manager.context.capabilities(interfaceDef));
+  return useAtomValue(manager.context.capabilities(interfaceDef));
 };
 
 /**