@dxos/app-framework 0.8.4-main.67995b8 → 0.8.4-main.72ec0f3

package/src/plugin-settings/app-graph-builder.ts

@@ -2,36 +2,39 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Rx } from '@effect-rx/rx-react';
-import { Option, pipe } from 'effect';
+import { Atom } from '@effect-atom/atom-react';
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
 
-import { createExtension, ROOT_ID } from '@dxos/app-graph';
+import { ROOT_ID, createExtension } from '@dxos/app-graph';
 import { type SettingsStore, type SettingsValue } from '@dxos/local-storage';
 import { isNonNullable } from '@dxos/util';
 
-import { SETTINGS_ID, SETTINGS_KEY, SETTINGS_PLUGIN, SettingsAction } from './actions';
 import { Capabilities } from '../common';
-import { contributes, type PluginMeta, type PluginContext } from '../core';
+import { type PluginContext, type PluginMeta, contributes } from '../core';
 import { createIntent } from '../plugin-intent';
 
+import { SETTINGS_ID, SETTINGS_KEY, SettingsAction } from './actions';
+import { meta } from './meta';
+
 export default (context: PluginContext) =>
   contributes(Capabilities.AppGraphBuilder, [
     createExtension({
-      id: `${SETTINGS_PLUGIN}/action`,
+      id: `${meta.id}/action`,
       actions: (node) =>
-        Rx.make((get) =>
-          pipe(
+        Atom.make((get) =>
+          Function.pipe(
             get(node),
             Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
             Option.map(() => [
               {
-                id: SETTINGS_PLUGIN,
+                id: meta.id,
                 data: async () => {
                   const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
                   await dispatch(createIntent(SettingsAction.Open));
                 },
                 properties: {
-                  label: ['open settings label', { ns: SETTINGS_PLUGIN }],
+                  label: ['open settings label', { ns: meta.id }],
                   icon: 'ph--gear--regular',
                   disposition: 'menu',
                   keyBinding: {
@@ -46,18 +49,18 @@ export default (context: PluginContext) =>
         ),
     }),
     createExtension({
-      id: `${SETTINGS_PLUGIN}/core`,
+      id: `${meta.id}/core`,
       connector: (node) =>
-        Rx.make((get) =>
-          pipe(
+        Atom.make((get) =>
+          Function.pipe(
             get(node),
             Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
             Option.map(() => [
               {
                 id: SETTINGS_ID,
-                type: SETTINGS_PLUGIN,
+                type: meta.id,
                 properties: {
-                  label: ['app settings label', { ns: SETTINGS_PLUGIN }],
+                  label: ['app settings label', { ns: meta.id }],
                   icon: 'ph--gear--regular',
                   disposition: 'pin-end',
                   position: 'hoist',
@@ -70,10 +73,10 @@ export default (context: PluginContext) =>
         ),
     }),
     createExtension({
-      id: `${SETTINGS_PLUGIN}/core-plugins`,
+      id: `${meta.id}/core-plugins`,
       connector: (node) =>
-        Rx.make((get) =>
-          pipe(
+        Atom.make((get) =>
+          Function.pipe(
             get(node),
             Option.flatMap((node) => (node.id !== SETTINGS_ID ? Option.none() : Option.some(node))),
             Option.map(() => {
@@ -105,7 +108,7 @@ export default (context: PluginContext) =>
                   id: `${SETTINGS_KEY}:custom-plugins`,
                   type: 'category',
                   properties: {
-                    label: ['custom plugins label', { ns: SETTINGS_PLUGIN }],
+                    label: ['custom plugins label', { ns: meta.id }],
                     icon: 'ph--squares-four--regular',
                     role: 'branch',
                     disposition: 'collection',
@@ -118,10 +121,10 @@ export default (context: PluginContext) =>
         ),
     }),
     createExtension({
-      id: `${SETTINGS_PLUGIN}/custom-plugins`,
+      id: `${meta.id}/custom-plugins`,
       connector: (node) =>
-        Rx.make((get) =>
-          pipe(
+        Atom.make((get) =>
+          Function.pipe(
             get(node),
             Option.flatMap((node) =>
               node.id !== `${SETTINGS_KEY}:custom-plugins` ? Option.none() : Option.some(node),

package/src/plugin-settings/intent-resolver.ts

@@ -2,12 +2,13 @@
 // Copyright 2025 DXOS.org
 //
 
-import { pipe } from 'effect';
+import * as Function from 'effect/Function';
 
-import { SETTINGS_ID, SETTINGS_KEY, SettingsAction } from './actions';
 import { Capabilities, LayoutAction } from '../common';
 import { contributes } from '../core';
-import { createResolver, createIntent, chain } from '../plugin-intent';
+import { chain, createIntent, createResolver } from '../plugin-intent';
+
+import { SETTINGS_ID, SETTINGS_KEY, SettingsAction } from './actions';
 
 export default () =>
   contributes(
@@ -19,7 +20,7 @@ export default () =>
         return {
           intents: [
             plugin
-              ? pipe(
+              ? Function.pipe(
                   openSettings,
                   chain(LayoutAction.Open, {
                     part: 'main',

package/src/plugin-settings/meta.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type PluginMeta } from '@dxos/app-framework';
+
+export const meta: PluginMeta = {
+  id: 'dxos.org/plugin/settings',
+  name: 'Settings',
+};

package/src/plugin-settings/store.ts

@@ -5,14 +5,14 @@
 import { RootSettingsStore } from '@dxos/local-storage';
 
 import { Capabilities } from '../common';
-import { contributes, type PluginContext } from '../core';
+import { type PluginContext, contributes } from '../core';
 
 export default (context: PluginContext) => {
-  // TODO(wittjosiah): Replace with rx?
+  // TODO(wittjosiah): Replace with atom?
   const settingsStore = new RootSettingsStore();
 
   let previous: Capabilities.Settings[] = [];
-  const registry = context.getCapability(Capabilities.RxRegistry);
+  const registry = context.getCapability(Capabilities.AtomRegistry);
   const cancel = registry.subscribe(
     context.capabilities(Capabilities.Settings),
     (allSettings) => {

package/src/plugin-settings/translations.ts

@@ -1,15 +1,15 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2025 DXOS.org
 //
 
-import { type Resource } from '@dxos/react-ui';
+import { type Resource } from '../common';
 
-import { SETTINGS_PLUGIN } from './actions';
+import { meta } from './meta';
 
 export const translations = [
   {
     'en-US': {
-      [SETTINGS_PLUGIN]: {
+      [meta.id]: {
         'open settings label': 'Open settings',
         'app settings label': 'Settings',
         'custom plugins label': 'Plugins',

package/src/react/App.stories.tsx

@@ -0,0 +1,33 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { useApp } from './useApp';
+
+const DefaultStory = () => {
+  const App = useApp({
+    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/react/App.tsx

@@ -0,0 +1,59 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+
+import { Capabilities } from '../common';
+import { topologicalSort } from '../helpers';
+
+import { type UseAppOptions } from './useApp';
+import { useCapabilities } from './useCapabilities';
+import { LoadingState, useLoading } from './useLoading';
+
+export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
+  state: { ready: boolean; error: unknown };
+};
+
+export const App = ({ placeholder: Placeholder, state, debounce }: AppProps) => {
+  const reactContexts = useCapabilities(Capabilities.ReactContext);
+  const reactRoots = useCapabilities(Capabilities.ReactRoot);
+  const stage = useLoading(state, debounce);
+
+  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>
+  );
+};
+
+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/react/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/react/ErrorBoundary.tsx

@@ -2,38 +2,40 @@
 // Copyright 2023 DXOS.org
 //
 
-import React, { Component, type FC, type PropsWithChildren } from 'react';
+import React, { Component, type FC, type PropsWithChildren, type ReactNode } from 'react';
 
-type Props = PropsWithChildren<{ data?: any; fallback: FC<{ data?: any; error: Error; reset: () => void }> }>;
-type State = { error: Error | undefined };
+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`.
  *
- * For more information on error boundaries, see:
- * https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary
+ * Ref: https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary
  */
-export class ErrorBoundary extends Component<Props, State> {
-  constructor(props: Props) {
-    super(props);
-    this.state = { error: undefined };
-  }
-
+export class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
   static getDerivedStateFromError(error: Error): { error: Error } {
     return { error };
   }
 
-  override componentDidUpdate(prevProps: Props): void {
+  override state = { error: undefined };
+
+  override componentDidUpdate(prevProps: ErrorBoundaryProps): void {
     if (prevProps.data !== this.props.data) {
       this.resetError();
     }
   }
 
-  override render(): string | number | boolean | React.JSX.Element | Iterable<React.ReactNode> | null | undefined {
+  override render(): ReactNode {
     if (this.state.error) {
-      return <this.props.fallback data={this.props.data} error={this.state.error} reset={this.resetError} />;
+      const Fallback = this.props.fallback ?? DefaultFallback;
+      return <Fallback data={this.props.data} error={this.state.error} />;
     }
 
     return this.props.children;
@@ -43,3 +45,12 @@ export class ErrorBoundary extends Component<Props, State> {
     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/react/IntentContext.tsx

@@ -2,15 +2,16 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type Context, createContext, useContext, type Provider, useEffect } from 'react';
+import { type Context, type Provider, createContext, useContext, useEffect } from 'react';
 
 import { raise } from '@dxos/debug';
 import { pick } from '@dxos/util';
 
-import { usePluginManager } from './PluginManagerProvider';
 import { Capabilities } from '../common';
 import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
 
+import { usePluginManager } from './PluginManagerProvider';
+
 const IntentContext: Context<IntentContext | undefined> = createContext<IntentContext | undefined>(undefined);
 
 export const useIntentDispatcher = (): Pick<IntentContext, 'dispatch' | 'dispatchPromise'> => {

package/src/react/Surface.stories.tsx

@@ -2,95 +2,124 @@
 // Copyright 2025 DXOS.org
 //
 
-import '@dxos-theme';
-
-import React, { useCallback, useState } from 'react';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+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 { PluginManagerProvider, usePluginManager } from './PluginManagerProvider';
-import { Surface, useSurfaces } from './Surface';
 import { Capabilities, createSurface } from '../common';
-import { type PluginManager } from '../core';
-import { setupPluginManager } from '../testing';
-
-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}%)`;
-};
+import { withPluginManager } from '../testing';
 
-const Story = () => {
+import { usePluginManager } from './PluginManagerProvider';
+import { Surface, useSurfaces } from './Surface';
+
+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>
   );
 };
 
-export default {
+const meta = {
   title: 'sdk/app-framework/Surface',
-  render: ({ manager }: { manager: PluginManager }) => {
-    return (
-      <PluginManagerProvider value={manager}>
-        <Story />
-      </PluginManagerProvider>
-    );
-  },
-  // NOTE: Intentionally not using withPluginManager to try to reduce surface area of the story.
-  decorators: [withTheme, withLayout()],
-  args: {
-    manager: setupPluginManager(),
+  render: DefaultStory,
+  decorators: [withTheme, withPluginManager({ capabilities: [] })],
+  parameters: {
+    layout: 'fullscreen',
   },
-};
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
 
-export const Default = {};
+export const Default: Story = {};