@dxos/app-framework 0.8.4-main.bc674ce → 0.8.4-main.c351d160a8

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

@@ -3,47 +3,40 @@
 //
 
 import React, {
-  type Context,
   Fragment,
   type NamedExoticComponent,
   type RefAttributes,
   Suspense,
-  createContext,
   forwardRef,
   memo,
-  useContext,
   useEffect,
   useMemo,
   useRef,
 } from 'react';
 
-import { raise } from '@dxos/debug';
 import { log } from '@dxos/log';
+import { ErrorBoundary } from '@dxos/react-error-boundary';
 import { useDefaultValue } from '@dxos/react-hooks';
 import { byPosition } from '@dxos/util';
 
-import * as Common from '../common';
-import { type CapabilityManager } from '../core';
+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 { useCapabilities } from './useCapabilities';
+import { type Definition, type Props, type WebComponentDefinition } from './types';
 
 const DEFAULT_PLACEHOLDER = <Fragment />;
 
 const DEBUG = import.meta.env.VITE_DEBUG;
 
-export type SurfaceContext = Pick<Common.SurfaceProps, 'id' | 'role' | 'data'>;
-
-// TODO(burdon): Use @radix-ui/react-context
-const SurfaceContext: Context<SurfaceContext | undefined> = createContext<SurfaceContext | undefined>(undefined);
-
 /**
  * Wrapper component for rendering Web Component surfaces.
  * Handles creation, prop setting, and cleanup of Web Components.
  */
 const WebComponentWrapper = memo(
-  forwardRef<HTMLElement, Common.SurfaceProps & { definition: Common.WebComponentSurfaceDefinition }>(
+  forwardRef<HTMLElement, Props & { definition: WebComponentDefinition }>(
     ({ id, role, data, limit, definition, ...rest }, forwardedRef) => {
       const containerRef = useRef<HTMLDivElement>(null);
       const elementRef = useRef<HTMLElement | null>(null);
@@ -54,7 +47,9 @@ const WebComponentWrapper = memo(
 
       // Create element only once
       useEffect(() => {
-        if (!containerRef.current || elementRef.current) return;
+        if (!containerRef.current || elementRef.current) {
+          return;
+        }
 
         // Create the Web Component
         const element = document.createElement(definition.tagName);
@@ -91,7 +86,9 @@ const WebComponentWrapper = memo(
       // 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;
+        if (!element) {
+          return;
+        }
 
         // Update properties on the existing Web Component
         Object.assign(element, propsRef.current);
@@ -107,15 +104,16 @@ WebComponentWrapper.displayName = 'WebComponentWrapper';
 /**
  * Wrapper component that provides context for a surface.
  */
+// TODO(burdon): Allow DebugPlugin to provide different fallback using react-ui ErrorFallback.
 const SurfaceContextProvider = memo(
-  forwardRef<HTMLElement, Common.SurfaceProps & { definition: Common.SurfaceDefinition }>(
-    ({ id, role, data, limit, fallback = DefaultFallback, definition, ...rest }, forwardedRef) => {
+  forwardRef<HTMLElement, Props & { definition: Definition }>(
+    ({ id, role, data, limit, fallback = ErrorFallback, 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}>
+          <ErrorBoundary name='surface' resetKeys={[data]} FallbackComponent={fallback}>
             <SurfaceContext.Provider value={contextValue}>
               <WebComponentWrapper
                 id={id}
@@ -138,7 +136,7 @@ const SurfaceContextProvider = memo(
       const debug = DEBUG || '__DX_DEBUG__' in window;
       if (debug) {
         return (
-          <ErrorBoundary data={data} fallback={fallback}>
+          <ErrorBoundary name='surface' resetKeys={[data]} FallbackComponent={fallback}>
             <div role='none' className='contents' data-id={id} data-role={role}>
               <SurfaceContext.Provider value={contextValue}>
                 <SurfaceInfo ref={forwardedRef}>
@@ -151,7 +149,7 @@ const SurfaceContextProvider = memo(
       }
 
       return (
-        <ErrorBoundary data={data} fallback={fallback}>
+        <ErrorBoundary name='surface' resetKeys={[data]} FallbackComponent={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} />
@@ -165,15 +163,11 @@ const SurfaceContextProvider = memo(
 
 SurfaceContextProvider.displayName = 'SurfaceContextProvider';
 
-export const useSurface = (): SurfaceContext => {
-  const context = useContext(SurfaceContext) ?? raise(new Error('Missing SurfaceContext'));
-  return context;
-};
-
 /**
  * A surface is a named region of the screen that can be populated by plugins.
  */
-export const Surface: NamedExoticComponent<Common.SurfaceProps & RefAttributes<HTMLElement>> = memo(
+// TODO(burdon): Remove `ref` since relying on this would be error prone.
+export const SurfaceComponent: NamedExoticComponent<Props & RefAttributes<HTMLElement>> = memo(
   forwardRef(({ id: _id, role, data: dataProp, limit, placeholder = DEFAULT_PLACEHOLDER, ...rest }, forwardedRef) => {
     const data = useDefaultValue(dataProp, () => ({}));
 
@@ -211,12 +205,19 @@ export const Surface: NamedExoticComponent<Common.SurfaceProps & RefAttributes<H
   }),
 );
 
-Surface.displayName = 'Surface';
+SurfaceComponent.displayName = 'Surface';
 
-const findCandidates = (
-  surfaces: Common.SurfaceDefinition[],
-  { role, data }: Pick<Common.SurfaceProps, 'role' | 'data'>,
-) => {
+// TODO(burdon): Make user facing, with telemetry.
+const ErrorFallback = ({ error }: Props) => {
+  const { message } = error instanceof Error ? error : { message: String(error) };
+  return (
+    <div role='alert' data-testid='error-boundary-fallback'>
+      <h1 className='flex gap-2 text-sm mt-2 text-info-text'>{message}</h1>
+    </div>
+  );
+};
+
+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,
@@ -225,32 +226,11 @@ const findCandidates = (
     .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 (
-      <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(Common.Capability.ReactSurface);
+  const surfaces = useCapabilities(Capabilities.ReactSurface);
   return useMemo(() => surfaces.flat(), [surfaces]);
 };
 
@@ -259,9 +239,9 @@ export const useSurfaces = () => {
  */
 export const isSurfaceAvailable = (
   capabilityManager: CapabilityManager.CapabilityManager,
-  { role, data }: Pick<Common.SurfaceProps, 'role' | 'data'>,
+  { role, data }: Pick<Props, 'role' | 'data'>,
 ) => {
-  const surfaces = capabilityManager.getAll(Common.Capability.ReactSurface);
+  const surfaces = capabilityManager.getAll(Capabilities.ReactSurface);
   const candidates = findCandidates(surfaces.flat(), { role, data });
   return candidates.length > 0;
 };

package/src/{react → ui/components/Surface}/SurfaceInfo.tsx

@@ -16,7 +16,7 @@ import { createPortal } from 'react-dom';
 import { addEventListener, combine } from '@dxos/async';
 import { useMergeRefs } from '@dxos/react-hooks';
 
-import { useSurface } from './Surface';
+import { useSurface } from '../../hooks';
 
 export type SurfaceInfoProps = {
   children: ReactElement<{ ref?: Ref<HTMLElement> }>;
@@ -76,7 +76,7 @@ export const SurfaceInfo = forwardRef<HTMLElement, SurfaceInfoProps>(({ children
           >
             {expand ? (
               <div
-                className='absolute inset-0 bg-deckSurface border border-green-500 cursor-pointer pointer-events-auto overflow-auto'
+                className='absolute inset-0 bg-deck-surface border border-green-500 cursor-pointer pointer-events-auto overflow-auto'
                 onPointerDown={(ev) => ev.stopPropagation()}
                 onClick={(ev) => {
                   ev.stopPropagation();

package/src/ui/components/Surface/context.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Context, createContext } from 'react';
+
+import { type Props } from './types';
+
+export type SurfaceContext = Pick<Props, 'id' | 'role' | 'data'>;
+
+// TODO(burdon): Use @radix-ui/react-context
+export const SurfaceContext: Context<SurfaceContext | undefined> = createContext<SurfaceContext | undefined>(undefined);

package/src/ui/components/Surface/index.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// TODO(wittjosiah): Cleanup to avoid re-naming.
+import { SurfaceContext } from './context';
+import { SurfaceComponent, isSurfaceAvailable } from './SurfaceComponent';
+import { type Definition as SurfaceDefinition, create as createSurface, createWeb as createWebSurface } from './types';
+
+export namespace Surface {
+  export type Definition = SurfaceDefinition;
+  export const create = createSurface;
+  export const createWeb = createWebSurface;
+
+  export type Context = SurfaceContext;
+  export const Context = SurfaceContext;
+
+  export const Surface = SurfaceComponent;
+  export const isAvailable = isSurfaceAvailable;
+}

package/src/{common/surface.ts → ui/components/Surface/types.ts}

@@ -2,41 +2,39 @@
 // Copyright 2023 DXOS.org
 //
 
-import type { PropsWithChildren, ReactNode, RefCallback } from 'react';
+import type { FC, PropsWithChildren, ReactNode, RefCallback } from 'react';
 
 import type { MakeOptional, Position } from '@dxos/util';
 
-import type { ErrorBoundary } from '../react';
-
 /**
- * SurfaceProps are the props that are passed to the Surface component.
+ * Props that are passed to the Surface component.
  */
-export type SurfaceProps<T extends Record<string, any> = Record<string, unknown>> = {
+export type Props<T extends Record<string, any> = Record<string, unknown>> = {
   /**
    * If specified, the Surface will be wrapped in an error boundary.
    * The fallback component will be rendered if an error occurs.
    */
-  fallback?: ErrorBoundary['props']['fallback'];
+  fallback?: FC<{ error: Error; data?: any }>;
 
   /**
    * If specified, the Surface will be wrapped in a suspense boundary.
    * The placeholder component will be rendered while the surface component is loading.
    */
   placeholder?: ReactNode;
-} & MakeOptional<CoreSurfaceProps<T>, 'id' | 'data'> &
+} & MakeOptional<CoreProps<T>, 'id' | 'data'> &
   /**
    * Additional props to pass to the component.
    * These props are not used by Surface itself but may be used by components which resolve the surface.
    * Exclude known prop names to prevent overriding well-defined props.
    */
   {
-    [K in keyof Record<string, any>]: K extends keyof CoreSurfaceProps<T> | 'fallback' | 'placeholder' ? never : any;
+    [K in keyof Record<string, any>]: K extends keyof CoreProps<T> | 'fallback' | 'placeholder' ? never : any;
   };
 
 /**
  * NOTE: If `[key: string]: unknown` is included in shared types, when re-used other fields become unknown as well.
  */
-export type CoreSurfaceProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
+export type CoreProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
   /**
    * ID for debugging.
    */
@@ -59,33 +57,34 @@ export type CoreSurfaceProps<T extends Record<string, any> = Record<string, unkn
   limit?: number | undefined;
 }>;
 
-export type SurfaceComponentProps<T extends Record<string, any> = Record<string, any>> = CoreSurfaceProps<T> & {
+// TODO(burdon): Remove ref since relying on this would be error prone.
+export type ComponentProps<T extends Record<string, any> = Record<string, any>> = CoreProps<T> & {
   ref?: RefCallback<HTMLElement>;
 } & Record<string, any>;
 
 /**
  * React component used to render a surface once is has matched.
  */
-export type SurfaceComponent<T extends Record<string, any> = Record<string, any>> = (
-  props: SurfaceComponentProps<T>,
+export type ComponentFunction<T extends Record<string, any> = Record<string, any>> = (
+  props: ComponentProps<T>,
 ) => ReactNode;
 
 /**
- * Definition of when a React SurfaceComponent should be rendered.
+ * Definition of when a React component surface should be rendered.
  */
-export type ReactSurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+export type ReactDefinition<T extends Record<string, any> = any> = Readonly<{
   kind: 'react';
   id: string;
   role: string | string[];
   position?: Position;
-  component: SurfaceComponent<T>;
+  component: ComponentFunction<T>;
   filter?: (data: Record<string, unknown>) => data is T;
 }>;
 
 /**
  * Definition of when a Web Component surface should be rendered.
  */
-export type WebComponentSurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+export type WebComponentDefinition<T extends Record<string, any> = any> = Readonly<{
   kind: 'web-component';
   id: string;
   role: string | string[];
@@ -101,20 +100,18 @@ export type WebComponentSurfaceDefinition<T extends Record<string, any> = any> =
 /**
  * Definition of when a surface (React or Web Component) should be rendered.
  */
-export type SurfaceDefinition<T extends Record<string, any> = any> =
-  | ReactSurfaceDefinition<T>
-  | WebComponentSurfaceDefinition<T>;
+export type Definition<T extends Record<string, any> = any> = ReactDefinition<T> | WebComponentDefinition<T>;
 
 /**
  * Creates a React surface definition.
  */
-export const createSurface = <T extends Record<string, any> = any>(
-  definition: Omit<ReactSurfaceDefinition<T>, 'kind'>,
-): ReactSurfaceDefinition<T> => ({ ...definition, kind: 'react' });
+export const create = <T extends Record<string, any> = any>(
+  definition: Omit<ReactDefinition<T>, 'kind'>,
+): ReactDefinition<T> => ({ ...definition, kind: 'react' });
 
 /**
  * Creates a Web Component surface definition.
  */
-export const createWebSurface = <T extends Record<string, any> = any>(
-  definition: Omit<WebComponentSurfaceDefinition<T>, 'kind'>,
-): WebComponentSurfaceDefinition<T> => ({ ...definition, kind: 'web-component' });
+export const createWeb = <T extends Record<string, any> = any>(
+  definition: Omit<WebComponentDefinition<T>, 'kind'>,
+): WebComponentDefinition<T> => ({ ...definition, kind: 'web-component' });

package/src/ui/components/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './App';
+export * from './PluginManager';
+export * from './Surface';

package/src/ui/hooks/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './useApp';
+export * from './useCapabilities';
+export * from './useLoading';
+export * from './useOperationResolver';
+export * from './useSettingsState';
+export * from './useSurface';

package/src/ui/hooks/useApp.test.tsx

@@ -0,0 +1,159 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { assert, describe, it } from '@effect/vitest';
+import { render, waitFor } from '@testing-library/react';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { ActivationEvents, Capabilities } from '../../common';
+import { Capability, Plugin, PluginManager } from '../../core';
+import { useApp } from './useApp';
+
+const String = Capability.make<{ string: string }>('org.dxos.test.string');
+const testMeta = { id: 'org.dxos.plugin.test', name: 'Test' };
+
+const pluginLoader = (plugins: Plugin.Plugin[]) =>
+  Effect.fn(function* (id: string) {
+    const plugin = plugins.find((plugin) => plugin.meta.id === id);
+    if (!plugin) {
+      return yield* Effect.fail(new Error(`Plugin not found: ${id}`));
+    }
+    return plugin;
+  });
+
+const TestHost = ({ manager }: { manager: PluginManager.PluginManager }) => {
+  const App = useApp({ pluginManager: manager });
+  return <App />;
+};
+
+describe('useApp cleanup integration', () => {
+  it.effect('external manager is not shut down when useApp does not own it', () =>
+    Effect.gen(function* () {
+      const plugin = Plugin.define(testMeta).pipe(
+        Plugin.addModule({
+          id: 'Hello',
+          activatesOn: ActivationEvents.Startup,
+          activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+        }),
+        Plugin.make,
+      )();
+
+      const manager = PluginManager.make({
+        pluginLoader: pluginLoader([plugin]),
+        plugins: [plugin],
+      });
+
+      manager.capabilities.contribute({
+        interface: Capabilities.PluginManager,
+        implementation: manager,
+        module: 'org.dxos.app-framework.plugin-manager',
+      });
+      manager.capabilities.contribute({
+        interface: Capabilities.AtomRegistry,
+        implementation: manager.registry,
+        module: 'org.dxos.app-framework.atom-registry',
+      });
+
+      const view = yield* Effect.promise(() => Promise.resolve(render(<TestHost manager={manager} />)));
+      yield* Effect.promise(() =>
+        waitFor(() => {
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.PluginManager).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.AtomRegistry).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+          assert.isTrue(manager.getActive().length > 0);
+        }),
+      );
+
+      yield* Effect.promise(() => Promise.resolve(view.unmount()));
+      yield* Effect.promise(() =>
+        waitFor(() => {
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.PluginManager).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.AtomRegistry).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+          assert.isTrue(manager.getActive().length > 0);
+        }),
+      );
+
+      yield* manager.shutdown();
+
+      assert.strictEqual(manager.capabilities.getAll(Capabilities.PluginManager).length, 1);
+      assert.strictEqual(manager.capabilities.getAll(Capabilities.AtomRegistry).length, 1);
+      assert.strictEqual(manager.capabilities.getAll(String).length, 0);
+      assert.deepStrictEqual(manager.getActive(), []);
+    }),
+  );
+
+  it.effect('shutdown deactivates modules and clears bookkeeping', () =>
+    Effect.gen(function* () {
+      const plugin = Plugin.define(testMeta).pipe(
+        Plugin.addModule({
+          id: 'Hello',
+          activatesOn: ActivationEvents.Startup,
+          activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+        }),
+        Plugin.make,
+      )();
+
+      const manager = PluginManager.make({
+        pluginLoader: pluginLoader([plugin]),
+        plugins: [plugin],
+      });
+
+      manager.capabilities.contribute({
+        interface: Capabilities.PluginManager,
+        implementation: manager,
+        module: 'org.dxos.app-framework.plugin-manager',
+      });
+      manager.capabilities.contribute({
+        interface: Capabilities.AtomRegistry,
+        implementation: manager.registry,
+        module: 'org.dxos.app-framework.atom-registry',
+      });
+      yield* manager.activate(ActivationEvents.Startup);
+
+      assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+      assert.isTrue(manager.getActive().length > 0);
+
+      yield* manager.shutdown();
+
+      assert.strictEqual(manager.capabilities.getAll(String).length, 0);
+      assert.deepStrictEqual(manager.getActive(), []);
+      assert.deepStrictEqual(manager.getEventsFired(), []);
+    }),
+  );
+
+  it.effect('shutdown is idempotent when called multiple times', () =>
+    Effect.gen(function* () {
+      const plugin = Plugin.define(testMeta).pipe(
+        Plugin.addModule({
+          id: 'Hello',
+          activatesOn: ActivationEvents.Startup,
+          activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+        }),
+        Plugin.make,
+      )();
+
+      const manager = PluginManager.make({
+        pluginLoader: pluginLoader([plugin]),
+        plugins: [plugin],
+      });
+
+      manager.capabilities.contribute({
+        interface: Capabilities.PluginManager,
+        implementation: manager,
+        module: 'org.dxos.app-framework.plugin-manager',
+      });
+      yield* manager.activate(ActivationEvents.Startup);
+
+      yield* manager.shutdown();
+      assert.deepStrictEqual(manager.getActive(), []);
+
+      // Second shutdown should succeed without error.
+      const result = yield* manager.shutdown();
+      assert.isTrue(result);
+      assert.deepStrictEqual(manager.getActive(), []);
+    }),
+  );
+});