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

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

@@ -0,0 +1,107 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, {
+  type ReactElement,
+  type Ref,
+  cloneElement,
+  forwardRef,
+  useCallback,
+  useLayoutEffect,
+  useState,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+import { addEventListener, combine } from '@dxos/async';
+import { useMergeRefs } from '@dxos/react-hooks';
+
+import { useSurface } from '../../hooks';
+
+export type SurfaceInfoProps = {
+  children: ReactElement<{ ref?: Ref<HTMLElement> }>;
+};
+
+/**
+ * Debug wrapper for surfaces.
+ */
+export const SurfaceInfo = forwardRef<HTMLElement, SurfaceInfoProps>(({ children }, forwardedRef) => {
+  const [rect, setRect] = useState<DOMRect | null>(null);
+  const [expand, setExpand] = useState(false);
+  const info = useSurface();
+
+  const [root, setRoot] = useState<HTMLElement | null>(null);
+  const measureRef = useCallback((node: HTMLElement | null) => setRoot(node), []);
+  const mergedRef = useMergeRefs([measureRef, forwardedRef]);
+  const childWithRef = cloneElement(children, { ref: mergedRef });
+
+  useLayoutEffect(() => {
+    if (!root) {
+      setRect(null);
+      return;
+    }
+
+    const measure = () => {
+      setRect(root.getBoundingClientRect());
+    };
+
+    const observer = new ResizeObserver(measure);
+    observer.observe(root);
+    measure();
+
+    return combine(
+      addEventListener(window, 'scroll', measure, true),
+      addEventListener(window, 'resize', measure),
+      () => {
+        observer.disconnect();
+      },
+    );
+  }, [root]);
+
+  const padding = 0;
+  return (
+    <>
+      {childWithRef}
+      {rect &&
+        createPortal(
+          <div
+            role='none'
+            className='z-[100] fixed flex flex-col-reverse scrollbar-none overflow-auto pointer-events-none'
+            style={{
+              top: rect.top + padding,
+              left: rect.left + padding,
+              width: rect.width - padding * 2,
+              height: rect.height - padding * 2,
+            }}
+          >
+            {expand ? (
+              <div
+                className='absolute inset-0 bg-deckSurface border border-green-500 cursor-pointer pointer-events-auto overflow-auto'
+                onPointerDown={(ev) => ev.stopPropagation()}
+                onClick={(ev) => {
+                  ev.stopPropagation();
+                  setExpand(false);
+                }}
+              >
+                <pre className='p-2 text-xs text-description font-mono'>{JSON.stringify({ info }, null, 2)}</pre>
+              </div>
+            ) : (
+              <span
+                className='absolute right-1 bottom-0 flex items-center p-1 text-green-500 opacity-80 hover:opacity-100 text-xl cursor-pointer pointer-events-auto'
+                title={info.id}
+                onPointerDown={(ev) => ev.stopPropagation()}
+                onClick={(ev) => {
+                  ev.stopPropagation();
+                  setExpand(true);
+                }}
+              >
+                ⓘ
+              </span>
+            )}
+          </div>,
+          // TODO(burdon): Create well-known element to gather all debug portals.
+          document.body,
+        )}
+    </>
+  );
+});

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,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './types';
+export { Surface } from './SurfaceComponent';
+export { isSurfaceAvailable as isAvailable } from './SurfaceComponent';
+export type { SurfaceContext as Root } from './context';

package/src/ui/components/surface/types.ts

@@ -0,0 +1,119 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import type { PropsWithChildren, ReactNode, RefCallback } from 'react';
+
+import type { MakeOptional, Position } from '@dxos/util';
+
+import type { ErrorBoundary } from '..';
+
+/**
+ * Props that are passed to the Surface component.
+ */
+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'];
+
+  /**
+   * 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<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 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 CoreProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
+  /**
+   * ID for debugging.
+   */
+  id: string;
+
+  /**
+   * Role defines how the data should be rendered.
+   */
+  role: string;
+
+  /**
+   * The data to be rendered by the surface.
+   * NOTE: This must be a stable value.
+   */
+  data: T;
+
+  /**
+   * If more than one component is resolved, the limit determines how many are rendered.
+   */
+  limit?: number | undefined;
+}>;
+
+// 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 ComponentFunction<T extends Record<string, any> = Record<string, any>> = (
+  props: ComponentProps<T>,
+) => ReactNode;
+
+/**
+ * Definition of when a React component surface should be rendered.
+ */
+export type ReactDefinition<T extends Record<string, any> = any> = Readonly<{
+  kind: 'react';
+  id: string;
+  role: string | string[];
+  position?: Position;
+  component: ComponentFunction<T>;
+  filter?: (data: Record<string, unknown>) => data is T;
+}>;
+
+/**
+ * Definition of when a Web Component surface should be rendered.
+ */
+export type WebComponentDefinition<T extends Record<string, any> = any> = Readonly<{
+  kind: 'web-component';
+  id: string;
+  role: string | string[];
+  position?: Position;
+  /**
+   * The tag name of the Web Component to render.
+   * The Web Component will receive the same props as React surfaces via properties/attributes.
+   */
+  tagName: string;
+  filter?: (data: Record<string, unknown>) => data is T;
+}>;
+
+/**
+ * Definition of when a surface (React or Web Component) should be rendered.
+ */
+export type Definition<T extends Record<string, any> = any> = ReactDefinition<T> | WebComponentDefinition<T>;
+
+/**
+ * Creates a React surface definition.
+ */
+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 createWeb = <T extends Record<string, any> = any>(
+  definition: Omit<WebComponentDefinition<T>, 'kind'>,
+): WebComponentDefinition<T> => ({ ...definition, kind: 'web-component' });

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.tsx

@@ -0,0 +1,215 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { RegistryContext } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as PubSub from 'effect/PubSub';
+import * as Queue from 'effect/Queue';
+import React, { type FC, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { runAndForwardErrors } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { useAsyncEffect, useDefaultValue } from '@dxos/react-hooks';
+import { ContextProtocolProvider } from '@dxos/web-context-react';
+
+import { ActivationEvents, Capabilities } from '../../common';
+import { PluginManagerContext } from '../../context';
+import { type ActivationEvent, type Plugin, PluginManager } from '../../core';
+import { App } from '../components/App';
+import { DefaultFallback } from '../components/DefaultFallback';
+import { ErrorBoundary } from '../components/ErrorBoundary';
+import { PluginManagerProvider } from '../components/PluginManagerProvider';
+
+const ENABLED_KEY = 'dxos.org/app-framework/enabled';
+
+export type UseAppOptions = {
+  pluginManager?: PluginManager.PluginManager;
+  pluginLoader?: PluginManager.ManagerOptions['pluginLoader'];
+  plugins?: Plugin.Plugin[];
+  core?: string[];
+  defaults?: string[];
+  /**
+   * Additional activation events to fire before startup.
+   * These are fired alongside SetupReactSurface before the Startup event.
+   */
+  setupEvents?: ActivationEvent.ActivationEvent[];
+  placeholder?: FC<{ stage: number }>;
+  fallback?: ErrorBoundary['props']['fallback'];
+  cacheEnabled?: boolean;
+  safeMode?: boolean;
+  debounce?: number;
+  timeout?: number;
+};
+
+/**
+ * Expected usage is for this to be the entrypoint of the application.
+ * Initializes plugins and renders the root components.
+ *
+ * @example
+ * const plugins = [LayoutPlugin(), MyPlugin()];
+ * const core = [LayoutPluginId];
+ * const default = [MyPluginId];
+ * const fallback = <div>Initializing Plugins...</div>;
+ * const App = useApp({ plugins, core, default, fallback });
+ * createRoot(document.getElementById('root')!).render(
+ *   <StrictMode>
+ *     <App />
+ *   </StrictMode>,
+ * );
+ *
+ * @param params.pluginLoader A function which loads new plugins.
+ * @param params.plugins All plugins available to the application.
+ * @param params.core Core plugins which will always be enabled.
+ * @param params.defaults Default plugins are enabled by default but can be disabled by the user.
+ * @param params.placeholder Placeholder component to render during startup.
+ * @param params.fallback Fallback component to render if an error occurs during startup.
+ * @param params.cacheEnabled Whether to cache enabled plugins in localStorage.
+ * @param params.safeMode Whether to enable safe mode, which disables optional plugins.
+ */
+export const useApp = ({
+  pluginManager,
+  pluginLoader: pluginLoaderProp,
+  plugins: pluginsProp,
+  core: coreProp,
+  defaults: defaultsProp,
+  setupEvents: setupEventsProp,
+  placeholder,
+  fallback = DefaultFallback,
+  cacheEnabled = false,
+  safeMode = false,
+  debounce = 0,
+  timeout = 30_000,
+}: UseAppOptions) => {
+  const plugins = useDefaultValue(pluginsProp, () => []);
+  const core = useDefaultValue(coreProp, () => plugins.map(({ meta }) => meta.id));
+  const defaults = useDefaultValue(defaultsProp, () => []);
+  const setupEvents = useDefaultValue(setupEventsProp, () => []);
+
+  // TODO(wittjosiah): Provide a custom plugin loader which supports loading via url.
+  const pluginLoader = useMemo(
+    () =>
+      pluginLoaderProp ??
+      ((id: string) =>
+        Effect.sync(() => {
+          const plugin = plugins.find((plugin) => plugin.meta.id === id);
+          invariant(plugin, `Plugin not found: ${id}`);
+          return plugin;
+        })),
+    [pluginLoaderProp, plugins],
+  );
+
+  const readyRef = useRef(false);
+  const [ready, setReady] = useState(false);
+  const errorRef = useRef<unknown>(null);
+  const [error, setError] = useState<unknown>(null);
+  // TODO(wittjosiah): Migrate to Atom.kvs for isomorphic storage.
+  const cached: string[] = useMemo(() => JSON.parse(localStorage.getItem(ENABLED_KEY) ?? '[]'), []);
+  const enabled = useMemo(
+    () => (safeMode ? [] : cacheEnabled && cached.length > 0 ? cached : defaults),
+    [safeMode, cacheEnabled, cached, defaults],
+  );
+  const manager = useMemo(
+    () => pluginManager ?? PluginManager.make({ pluginLoader, plugins, core, enabled }),
+    [pluginManager, pluginLoader, plugins, core, enabled],
+  );
+
+  useEffect(() => {
+    if (!cacheEnabled) {
+      return;
+    }
+    return manager.registry.subscribe(manager.enabled, (value) => {
+      localStorage.setItem(ENABLED_KEY, JSON.stringify(value));
+    });
+  }, [cacheEnabled, manager]);
+
+  useEffect(() => {
+    setupDevtools(manager);
+  }, [manager]);
+
+  useAsyncEffect(async () => {
+    manager.capabilities.contribute({
+      interface: Capabilities.PluginManager,
+      implementation: manager,
+      module: 'dxos.org/app-framework/plugin-manager',
+    });
+
+    manager.capabilities.contribute({
+      interface: Capabilities.AtomRegistry,
+      implementation: manager.registry,
+      module: 'dxos.org/app-framework/atom-registry',
+    });
+
+    const fiber = Effect.gen(function* () {
+      const queue = yield* PubSub.subscribe(manager.activation);
+      const listener = yield* Effect.forkDaemon(
+        Queue.take(queue).pipe(
+          Effect.tap(({ event, state, error: error$ }) =>
+            Effect.sync(() => {
+              if (event === ActivationEvents.Startup.id && state === 'activated') {
+                clearTimeout(timeoutId);
+                setReady(true);
+                readyRef.current = true;
+              }
+              if (error$ && !readyRef.current) {
+                setError(error$);
+                errorRef.current = error$;
+              }
+            }),
+          ),
+          Effect.forever,
+        ),
+      );
+
+      yield* Effect.all([
+        ...setupEvents.map((event) => manager.activate(event)),
+        manager.activate(ActivationEvents.SetupReactSurface),
+        manager.activate(ActivationEvents.Startup),
+      ]);
+
+      return yield* Fiber.join(listener);
+    }).pipe(Effect.scoped, Effect.runFork);
+
+    // Set up a timeout for startup.
+    const timeoutId = setTimeout(() => {
+      if (!readyRef.current && !errorRef.current) {
+        log.warn('startup timeout diagnostic', {
+          eventsFired: manager.getEventsFired(),
+          activeModules: manager.getActive(),
+          pendingReset: manager.getPendingReset(),
+        });
+        void runAndForwardErrors(Fiber.interrupt(fiber));
+        setError(new Error(`Startup timed out after ${timeout}ms`));
+      }
+    }, timeout);
+
+    return () => {
+      clearTimeout(timeoutId);
+      void runAndForwardErrors(Fiber.interrupt(fiber));
+      manager.capabilities.remove(Capabilities.PluginManager, manager);
+      manager.capabilities.remove(Capabilities.AtomRegistry, manager.registry);
+    };
+  }, [manager]);
+
+  return useCallback(
+    () => (
+      <ErrorBoundary fallback={fallback}>
+        <PluginManagerProvider value={manager}>
+          <ContextProtocolProvider value={manager} context={PluginManagerContext}>
+            <RegistryContext.Provider value={manager.registry}>
+              <App placeholder={placeholder} ready={ready} error={error} debounce={debounce} />
+            </RegistryContext.Provider>
+          </ContextProtocolProvider>
+        </PluginManagerProvider>
+      </ErrorBoundary>
+    ),
+    [fallback, manager, placeholder, ready, error],
+  );
+};
+
+const setupDevtools = (manager: PluginManager.PluginManager) => {
+  (globalThis as any).composer ??= {};
+  (globalThis as any).composer.manager = manager;
+};

package/src/ui/hooks/useCapabilities.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom, useAtomValue } from '@effect-atom/atom-react';
+import { useCallback } from 'react';
+
+import { invariant } from '@dxos/invariant';
+
+import { Capabilities } from '../../common';
+import { type Capability } from '../../core';
+import { usePluginManager } from '../components/PluginManagerProvider';
+
+/**
+ * Hook to request capabilities from the plugin context.
+ * @returns An array of capabilities.
+ */
+export const useCapabilities = <T>(interfaceDef: Capability.InterfaceDef<T>) => {
+  const manager = usePluginManager();
+  return useAtomValue(manager.capabilities.atom(interfaceDef));
+};
+
+/**
+ * Hook to request a capability from the plugin context.
+ * @returns The capability.
+ * @throws If no capability is found.
+ */
+export const useCapability = <T>(interfaceDef: Capability.InterfaceDef<T>) => {
+  const capabilities = useCapabilities(interfaceDef);
+  invariant(capabilities.length > 0, `No capability found for ${interfaceDef.identifier}`);
+  return capabilities[0];
+};
+
+/**
+ * Hook to get the current value of an atom capability.
+ * Automatically subscribes to changes.
+ * @example const settings = useAtomCapability(ThreadCapabilities.Settings);
+ */
+export const useAtomCapability = <T>(atomCapability: Capability.InterfaceDef<Atom.Atom<T>>): T => {
+  const atom = useCapability(atomCapability);
+  return useAtomValue(atom);
+};
+
+/**
+ * Hook to get value and updater for an atom capability.
+ * Returns [currentValue, updateFn] similar to useState.
+ * @example const [settings, updateSettings] = useAtomCapabilityState(ThreadCapabilities.Settings);
+ */
+export const useAtomCapabilityState = <T>(
+  atomCapability: Capability.InterfaceDef<Atom.Writable<T>>,
+): [T, (fn: (current: T) => T) => void] => {
+  const registry = useCapability(Capabilities.AtomRegistry);
+  const atom = useCapability(atomCapability);
+  const value = useAtomValue(atom);
+  const update = useCallback(
+    (fn: (current: T) => T) => {
+      registry.set(atom, fn(registry.get(atom)));
+    },
+    [registry, atom],
+  );
+  return [value, update];
+};
+
+/**
+ * Hook to get the operation invoker capability.
+ */
+export const useOperationInvoker = (): Capabilities.OperationInvoker => useCapability(Capabilities.OperationInvoker);

package/src/{react → ui/hooks}/useLoading.tsx

@@ -4,8 +4,6 @@
 
 import { useEffect, useState } from 'react';
 
-import { type AppProps } from './App';
-
 export enum LoadingState {
   Loading = 0,
   FadeIn = 1,
@@ -23,7 +21,7 @@ export enum LoadingState {
  * 2: Fade-out  - Fade out the loading animation.
  * 3: Done      - Remove the placeholder.
  */
-export const useLoading = (state: AppProps['state'], debounce = 0) => {
+export const useLoading = (ready: boolean, debounce = 0) => {
   const [stage, setStage] = useState<LoadingState>(LoadingState.Loading);
   useEffect(() => {
     if (!debounce) {
@@ -34,7 +32,7 @@ export const useLoading = (state: AppProps['state'], debounce = 0) => {
       setStage((stage) => {
         switch (stage) {
           case LoadingState.Loading: {
-            if (!state.ready) {
+            if (!ready) {
               return LoadingState.FadeIn;
             } else {
               clearInterval(i);
@@ -43,7 +41,7 @@ export const useLoading = (state: AppProps['state'], debounce = 0) => {
           }
 
           case LoadingState.FadeIn: {
-            if (state.ready) {
+            if (ready) {
               return LoadingState.FadeOut;
             }
             break;
@@ -63,7 +61,7 @@ export const useLoading = (state: AppProps['state'], debounce = 0) => {
   }, [debounce]);
 
   if (!debounce) {
-    return state.ready ? LoadingState.Done : LoadingState.Loading;
+    return ready ? LoadingState.Done : LoadingState.Loading;
   }
 
   return stage;

package/src/ui/hooks/useOperationResolver.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useEffect, useMemo } from 'react';
+
+import { Capabilities } from '../../common';
+import { usePluginManager } from '../components/PluginManagerProvider';
+
+/**
+ * Hook to dynamically register an operation resolver (handler) within a React component.
+ * The resolver is added when the component mounts and removed when it unmounts.
+ *
+ * @example
+ * ```tsx
+ * const scrollHandler = useMemo(() => OperationResolver.make({
+ *   operation: LayoutOperation.ScrollIntoView,
+ *   handler: (input) => Effect.sync(() => {
+ *     // Handle scroll
+ *   }),
+ * }), [deps]);
+ *
+ * useOperationResolver(meta.id, scrollHandler);
+ * ```
+ */
+export const useOperationResolver = (module: string, resolver: Capabilities.OperationResolver) => {
+  const manager = usePluginManager();
+  // Wrap single resolver in array as the capability expects an array.
+  const resolverArray = useMemo(() => [resolver], [resolver]);
+
+  useEffect(() => {
+    manager.capabilities.contribute({
+      module,
+      interface: Capabilities.OperationResolver,
+      implementation: resolverArray,
+    });
+
+    return () => manager.capabilities.remove(Capabilities.OperationResolver, resolverArray);
+  }, [module, resolverArray]);
+};

package/src/ui/hooks/useSettingsState.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom, RegistryContext, useAtomValue } from '@effect-atom/atom-react';
+import { useCallback, useContext } from 'react';
+
+/**
+ * Hook to read and update a settings atom.
+ * Returns the current value and an update function.
+ */
+export const useSettingsState = <T>(
+  atom: Atom.Writable<T>,
+): { settings: T; updateSettings: (fn: (current: T) => T) => void } => {
+  const registry = useContext(RegistryContext);
+  const settings = useAtomValue(atom);
+
+  const updateSettings = useCallback(
+    (fn: (current: T) => T) => {
+      registry.set(atom, fn(registry.get(atom)));
+    },
+    [registry, atom],
+  );
+
+  return { settings, updateSettings };
+};

package/src/ui/hooks/useSurface.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useContext } from 'react';
+
+import { raise } from '@dxos/debug';
+
+import { SurfaceContext } from '../components/surface/context';
+
+export const useSurface = (): SurfaceContext => {
+  return useContext(SurfaceContext) ?? raise(new Error('Missing SurfaceContext'));
+};

package/src/ui/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './components';
+export * from './hooks';
+export * as Surface from './components/surface';