@dxos/app-framework 0.8.4-main.e8ec1fe → 0.8.4-main.ef1bc66f44

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/{react → ui/components}/App.tsx

@@ -4,25 +4,23 @@
 
 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';
+import { Capabilities } from '../../common';
+import { topologicalSort } from '../../helpers';
+import { LoadingState, type UseAppOptions, useCapabilities, useLoading } from '../hooks';
 
 export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
-  state: { ready: boolean; error: unknown };
+  ready: boolean;
+  error: unknown;
 };
 
-export const App = ({ placeholder: Placeholder, state, debounce }: AppProps) => {
+export const App = ({ placeholder: Placeholder, ready, error, debounce }: AppProps) => {
   const reactContexts = useCapabilities(Capabilities.ReactContext);
   const reactRoots = useCapabilities(Capabilities.ReactRoot);
-  const stage = useLoading(state, debounce);
+  const stage = useLoading(ready, debounce);
 
-  if (state.error) {
+  if (error) {
     // This triggers the error boundary to provide UI feedback for the startup error.
-    throw state.error;
+    throw error;
   }
 
   // TODO(wittjosiah): Consider using Suspense instead.

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';

package/src/{react/Surface.stories.tsx → ui/components/surface/SurfaceComponent.stories.tsx}

@@ -3,40 +3,52 @@
 //
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { useCallback, useEffect, useState } from 'react';
+import React, { forwardRef, useCallback, useEffect, useRef, useState } from 'react';
 
 import { faker } from '@dxos/random';
 import { List, ListItem, Toolbar } from '@dxos/react-ui';
 import { withTheme } from '@dxos/react-ui/testing';
-import { getHashStyles, mx } from '@dxos/react-ui-theme';
+import { type ColorStyles, getHashStyles, mx } from '@dxos/ui-theme';
 
-import { Capabilities, createSurface } from '../common';
-import { withPluginManager } from '../testing';
+import { Capabilities } from '../../../common';
+import { withPluginManager } from '../../../testing';
+import { usePluginManager } from '../PluginManagerProvider';
 
-import { usePluginManager } from './PluginManagerProvider';
-import { Surface, useSurfaces } from './Surface';
+import { Surface, useSurfaces } from './SurfaceComponent';
+import { create } from './types';
+
+type TestComponentProps = {
+  id: string;
+  styles: ColorStyles;
+};
+
+const TestComponent = forwardRef<HTMLDivElement, TestComponentProps>(({ styles, id }, forwardedRef) => {
+  return (
+    <div
+      className={mx('flex justify-center items-center border rounded', styles.surface, styles.border)}
+      ref={forwardedRef}
+    >
+      <span className={mx('dx-tag font-mono text-lg', styles.text)}>{id}</span>
+    </div>
+  );
+});
 
 const DefaultStory = () => {
-  const [selected, setSelected] = useState<string | undefined>();
   const manager = usePluginManager();
   const surfaces = useSurfaces();
+  const [selected, setSelected] = useState<string | undefined>();
 
   const handleAdd = useCallback(() => {
     const id = `test-${faker.number.int({ min: 0, max: 1_000 })}`;
     const styles = getHashStyles(id);
-
-    manager.context.contributeCapability({
+    manager.capabilities.contribute({
       module: 'test',
       interface: Capabilities.ReactSurface,
-      implementation: createSurface({
+      implementation: create({
         id,
         role: 'item',
         filter: (data): data is any => (data as any)?.id === id,
-        component: () => (
-          <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>
-        ),
+        component: ({ ref }) => <TestComponent id={id} styles={styles} ref={ref} />,
       }),
     });
 
@@ -48,10 +60,10 @@ const DefaultStory = () => {
   }, [surfaces]);
 
   const handleError = useCallback(() => {
-    manager.context.contributeCapability({
+    manager.capabilities.contribute({
       module: 'error',
       interface: Capabilities.ReactSurface,
-      implementation: createSurface({
+      implementation: create({
         id: 'error',
         role: 'item',
         filter: (data): data is any => (data as any)?.id === 'error',
@@ -86,6 +98,11 @@ const DefaultStory = () => {
     setSelected('error');
   }, [manager]);
 
+  const ref = useRef<HTMLElement>(null);
+  useEffect(() => {
+    console.log(ref.current);
+  }, [ref]);
+
   return (
     <div className='flex flex-col bs-full overflow-hidden'>
       <Toolbar.Root>
@@ -94,7 +111,7 @@ const DefaultStory = () => {
         <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} />
+        <Surface role='item' data={selected ? { id: selected } : undefined} limit={1} ref={ref} />
         <div className='overflow-y-auto bs-full'>
           <List>
             {surfaces.map((surface) => (
@@ -112,7 +129,7 @@ const DefaultStory = () => {
 const meta = {
   title: 'sdk/app-framework/Surface',
   render: DefaultStory,
-  decorators: [withTheme, withPluginManager({ capabilities: [] })],
+  decorators: [withTheme(), withPluginManager({ capabilities: [] })],
   parameters: {
     layout: 'fullscreen',
   },

package/src/ui/components/surface/SurfaceComponent.tsx

@@ -0,0 +1,262 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, {
+  Fragment,
+  type NamedExoticComponent,
+  type RefAttributes,
+  Suspense,
+  forwardRef,
+  memo,
+  useEffect,
+  useMemo,
+  useRef,
+} from 'react';
+
+import { log } from '@dxos/log';
+import { useDefaultValue } from '@dxos/react-hooks';
+import { ScrollArea } from '@dxos/react-ui';
+import { byPosition } from '@dxos/util';
+
+import { Capabilities } from '../../../common';
+import { type CapabilityManager } from '../../../core';
+import { useCapabilities } from '../../hooks';
+import { ErrorBoundary } from '../ErrorBoundary';
+
+import { SurfaceContext } from './context';
+import { SurfaceInfo } from './SurfaceInfo';
+import { type Definition, type Props, type WebComponentDefinition } from './types';
+
+const DEFAULT_PLACEHOLDER = <Fragment />;
+
+const DEBUG = import.meta.env.VITE_DEBUG;
+
+/**
+ * Wrapper component for rendering Web Component surfaces.
+ * Handles creation, prop setting, and cleanup of Web Components.
+ */
+const WebComponentWrapper = memo(
+  forwardRef<HTMLElement, Props & { definition: WebComponentDefinition }>(
+    ({ id, role, data, limit, definition, ...rest }, forwardedRef) => {
+      const containerRef = useRef<HTMLDivElement>(null);
+      const elementRef = useRef<HTMLElement | null>(null);
+      const propsRef = useRef({ id, role, data, limit, ...rest });
+
+      // Update props ref on every render
+      propsRef.current = { id, role, data, limit, ...rest };
+
+      // Create element only once
+      useEffect(() => {
+        if (!containerRef.current || elementRef.current) {
+          return;
+        }
+
+        // Create the Web Component
+        const element = document.createElement(definition.tagName);
+        elementRef.current = element;
+
+        // Set initial properties on the Web Component
+        Object.assign(element, propsRef.current);
+
+        // Append to container
+        containerRef.current.appendChild(element);
+
+        // Setup ref forwarding if provided
+        if (typeof forwardedRef === 'function') {
+          forwardedRef(element);
+        } else if (forwardedRef) {
+          forwardedRef.current = element;
+        }
+
+        // Cleanup on unmount to prevent memory leaks
+        return () => {
+          if (elementRef.current && containerRef.current?.contains(elementRef.current)) {
+            containerRef.current.removeChild(elementRef.current);
+          }
+          if (typeof forwardedRef === 'function') {
+            forwardedRef(null);
+          } else if (forwardedRef) {
+            forwardedRef.current = null;
+          }
+          elementRef.current = null;
+        };
+      }, [definition.tagName, forwardedRef]);
+
+      // Update props on existing element without recreating it
+      // This runs on every render to ensure all props (including those in `rest`) are kept up to date
+      useEffect(() => {
+        const element = elementRef.current;
+        if (!element) {
+          return;
+        }
+
+        // Update properties on the existing Web Component
+        Object.assign(element, propsRef.current);
+      });
+
+      return <div ref={containerRef} />;
+    },
+  ),
+);
+
+WebComponentWrapper.displayName = 'WebComponentWrapper';
+
+/**
+ * Wrapper component that provides context for a surface.
+ */
+const SurfaceContextProvider = memo(
+  forwardRef<HTMLElement, Props & { definition: Definition }>(
+    ({ id, role, data, limit, fallback = DefaultFallback, definition, ...rest }, forwardedRef) => {
+      const contextValue = useMemo(() => ({ id, role, data }), [id, role, data]);
+
+      // Handle Web Component surfaces
+      if (definition.kind === 'web-component') {
+        return (
+          <ErrorBoundary data={data} fallback={fallback}>
+            <SurfaceContext.Provider value={contextValue}>
+              <WebComponentWrapper
+                id={id}
+                role={role}
+                data={data}
+                limit={limit}
+                definition={definition}
+                ref={forwardedRef}
+                {...rest}
+              />
+            </SurfaceContext.Provider>
+          </ErrorBoundary>
+        );
+      }
+
+      // Handle React component surfaces
+      const Component = definition.component;
+
+      // TODO(burdon): Remove from production build?
+      const debug = DEBUG || '__DX_DEBUG__' in window;
+      if (debug) {
+        return (
+          <ErrorBoundary data={data} fallback={fallback}>
+            <div role='none' className='contents' data-id={id} data-role={role}>
+              <SurfaceContext.Provider value={contextValue}>
+                <SurfaceInfo ref={forwardedRef}>
+                  <Component id={id} role={role} data={data} limit={limit} {...rest} />
+                </SurfaceInfo>
+              </SurfaceContext.Provider>
+            </div>
+          </ErrorBoundary>
+        );
+      }
+
+      return (
+        <ErrorBoundary data={data} fallback={fallback}>
+          <div role='none' className='contents' data-id={id} data-role={role}>
+            <SurfaceContext.Provider value={contextValue}>
+              <Component id={id} role={role} data={data} limit={limit} {...rest} ref={forwardedRef} />
+            </SurfaceContext.Provider>
+          </div>
+        </ErrorBoundary>
+      );
+    },
+  ),
+);
+
+SurfaceContextProvider.displayName = 'SurfaceContextProvider';
+
+/**
+ * A surface is a named region of the screen that can be populated by plugins.
+ */
+// TODO(burdon): Remove ref since relying on this would be error prone.
+export const Surface: NamedExoticComponent<Props & RefAttributes<HTMLElement>> = memo(
+  forwardRef(({ id: _id, role, data: dataProp, limit, placeholder = DEFAULT_PLACEHOLDER, ...rest }, forwardedRef) => {
+    const data = useDefaultValue(dataProp, () => ({}));
+
+    // 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 anyway.
+    //   In the future, it would be nice to be able to bucket the surface contributions by role.
+    const surfaces = useSurfaces();
+
+    // 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;
+    if (DEBUG && candidates.length === 0) {
+      log.warn('no candidates for surface', { role, data });
+      return null;
+    }
+
+    return (
+      <Suspense fallback={placeholder}>
+        {candidates.map((definition) => (
+          <SurfaceContextProvider
+            key={definition.id}
+            id={definition.id}
+            role={role}
+            data={data}
+            limit={limit}
+            definition={definition}
+            ref={forwardedRef}
+            {...rest}
+          />
+        ))}
+      </Suspense>
+    );
+  }),
+);
+
+Surface.displayName = 'Surface';
+
+const findCandidates = (surfaces: Definition[], { role, data }: Pick<Props, '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);
+};
+
+// 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 (
+      <ScrollArea.Root orientation='vertical'>
+        <ScrollArea.Viewport classNames='p-4 gap-4'>
+          <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>
+        </ScrollArea.Viewport>
+      </ScrollArea.Root>
+    );
+  }
+
+  return (
+    <ScrollArea.Root orientation='vertical'>
+      <ScrollArea.Viewport classNames='p-4 gap-4 border border-roseFill'>
+        <h1 className='flex gap-2 text-sm mbs-2 text-errorText'>{error.message}</h1>
+        <pre className='overflow-x-auto text-xs text-description'>{error.stack}</pre>
+        <pre className='overflow-x-auto text-xs text-description'>{JSON.stringify(data, null, 2)}</pre>
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};
+
+/**
+ * @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 = (
+  capabilityManager: CapabilityManager.CapabilityManager,
+  { role, data }: Pick<Props, 'role' | 'data'>,
+) => {
+  const surfaces = capabilityManager.getAll(Capabilities.ReactSurface);
+  const candidates = findCandidates(surfaces.flat(), { role, data });
+  return candidates.length > 0;
+};