@dxos/app-framework 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

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

@@ -0,0 +1,303 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import React, {
+  Fragment,
+  type NamedExoticComponent,
+  Profiler,
+  type RefAttributes,
+  Suspense,
+  forwardRef,
+  memo,
+  useEffect,
+  useMemo,
+  useRef,
+} from 'react';
+
+import { log } from '@dxos/log';
+import { ErrorBoundary } from '@dxos/react-error-boundary';
+import { useDefaultValue } from '@dxos/react-hooks';
+import { byPosition } from '@dxos/util';
+
+import { Capabilities } from '../../../common';
+import { type CapabilityManager } from '../../../core';
+import { usePluginManager } from '../PluginManager/PluginManagerProvider';
+import { SurfaceContext } from './context';
+import { SurfaceInfo } from './SurfaceInfo';
+import { useSurfaceProfilerCallback } from './SurfaceProfilerContext';
+import {
+  type Definition,
+  type Props,
+  type RoleToken,
+  type TokenData,
+  type TypedProps,
+  type WebComponentDefinition,
+} from './types';
+
+const DEBUG = import.meta.env.VITE_DEBUG;
+
+const DEFAULT_PLACEHOLDER = <Fragment />;
+
+/**
+ * Wrapper component for rendering Web Component surfaces.
+ * Handles creation, prop setting, and cleanup of Web Components.
+ */
+const WebComponentWrapper = memo(
+  forwardRef<HTMLElement, Omit<Props, 'role'> & { role: string; 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.
+ */
+// TODO(burdon): Allow DebugPlugin to provide different fallback using react-ui ErrorFallback.
+const SurfaceContextProvider = memo(
+  forwardRef<HTMLElement, Omit<Props, 'role'> & { role: string; definition: Definition }>(
+    ({ id, role, data, limit, fallback = ErrorFallback, definition, ...rest }, forwardedRef) => {
+      const contextValue = useMemo(() => ({ id, role, data }), [id, role, data]);
+      const onProfilerRender = useSurfaceProfilerCallback();
+      const profilerId = `surface/${id}/${role}`;
+
+      // Handle Web Component surfaces
+      if (definition.kind === 'web-component') {
+        return (
+          <ErrorBoundary name='surface' resetKeys={[data]} FallbackComponent={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 name='surface' resetKeys={[data]} FallbackComponent={fallback}>
+            <div role='none' className='contents' data-id={id} data-role={role}>
+              <SurfaceContext.Provider value={contextValue}>
+                <SurfaceInfo ref={forwardedRef}>
+                  {onProfilerRender && !profilerId.includes('org.dxos.plugin.debug') ? (
+                    <Profiler id={profilerId} onRender={onProfilerRender}>
+                      <Component id={id} role={role} data={data} limit={limit} {...rest} />
+                    </Profiler>
+                  ) : (
+                    <Component id={id} role={role} data={data} limit={limit} {...rest} />
+                  )}
+                </SurfaceInfo>
+              </SurfaceContext.Provider>
+            </div>
+          </ErrorBoundary>
+        );
+      }
+
+      return (
+        <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} />
+            </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 SurfaceComponent = memo(
+  forwardRef<HTMLElement, Props & { type?: RoleToken<any> }>(
+    ({ id: _id, role, type, 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();
+
+      const effectiveRole = role ?? type?.role;
+      if (effectiveRole == null) {
+        if (DEBUG) {
+          log.warn('Surface has neither `role` nor `type` prop', { id: _id });
+        }
+        return null;
+      }
+
+      // NOTE: Memoizing the candidates makes the surface not re-render based on reactivity within data.
+      const definitions = findCandidates(surfaces, { role: effectiveRole, data });
+      const candidates = limit ? definitions.slice(0, limit) : definitions;
+      if (DEBUG && candidates.length === 0) {
+        log.warn('no candidates for surface', { role: effectiveRole, data });
+        return null;
+      }
+
+      return (
+        <Suspense fallback={placeholder}>
+          {candidates.map((definition) => (
+            <SurfaceContextProvider
+              key={definition.id}
+              id={definition.id}
+              role={effectiveRole}
+              data={data}
+              limit={limit}
+              definition={definition}
+              ref={forwardedRef}
+              {...rest}
+            />
+          ))}
+        </Suspense>
+      );
+    },
+  ),
+) as (<TToken extends RoleToken<any>>(props: TypedProps<TToken> & RefAttributes<HTMLElement>) => React.ReactNode) &
+  NamedExoticComponent<Props & RefAttributes<HTMLElement>>;
+
+SurfaceComponent.displayName = 'Surface';
+
+// 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 }: { role: string; data: Props['data'] }) => {
+  return Object.values(surfaces)
+    .filter((definition) =>
+      Array.isArray(definition.role) ? definition.role.includes(role) : definition.role === role,
+    )
+    .filter(({ filter }) => (filter ? filter(data ?? {}, role) : true))
+    .toSorted(byPosition);
+};
+
+/**
+ * @internal
+ */
+export const useSurfaces = () => {
+  const manager = usePluginManager();
+  const surfacesByModule = useAtomValue(manager.capabilities.atomByModule(Capabilities.ReactSurface));
+  return useMemo(() => {
+    const result: Definition[] = [];
+    for (const [moduleId, surfaces] of Object.entries(surfacesByModule)) {
+      for (const def of surfaces.flat()) {
+        result.push({ ...def, id: `${moduleId}.${def.id}` });
+      }
+    }
+    return result;
+  }, [surfacesByModule]);
+};
+
+/**
+ * @returns `true` if there is a contributed surface which matches the specified role & data, `false` otherwise.
+ *
+ * Two overloads:
+ * - Typed: pass a `type` role token and `data` is constrained to the token's
+ *   declared contract (e.g. `AppSurface.Section` requires `attendableId`).
+ * - Legacy: pass a string `role` and `data` is untyped.
+ */
+export function isSurfaceAvailable<TToken extends RoleToken<any>>(
+  capabilityManager: CapabilityManager.CapabilityManager,
+  args: { type: TToken; data?: TokenData<TToken>; role?: never },
+): boolean;
+export function isSurfaceAvailable(
+  capabilityManager: CapabilityManager.CapabilityManager,
+  args: Pick<Props, 'role' | 'data'> & { type?: undefined },
+): boolean;
+export function isSurfaceAvailable(
+  capabilityManager: CapabilityManager.CapabilityManager,
+  { role, type, data }: { role?: string; type?: RoleToken<any>; data?: unknown },
+): boolean {
+  const effectiveRole = role ?? type?.role;
+  if (effectiveRole == null) {
+    return false;
+  }
+  const surfaces = capabilityManager.getAll(Capabilities.ReactSurface);
+  const candidates = findCandidates(surfaces.flat(), {
+    role: effectiveRole,
+    data: data as Props['data'],
+  });
+  return candidates.length > 0;
+}

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-deck-surface 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/SurfaceProfilerContext.tsx

@@ -0,0 +1,207 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, {
+  type Context,
+  type PropsWithChildren,
+  type ProfilerOnRenderCallback,
+  createContext,
+  useContext,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from 'react';
+
+const MAX_ENTRIES = 500;
+
+/**
+ * Single profiler record captured from React Profiler onRender callback.
+ */
+export type SurfaceProfilerEntry = {
+  id: string;
+  phase: 'mount' | 'update' | 'nested-update';
+  actualDuration: number;
+  baseDuration: number;
+  startTime: number;
+  commitTime: number;
+  timestamp: number;
+};
+
+/**
+ * Aggregated stats for a single profiled surface.
+ */
+export type SurfaceProfilerStats = {
+  id: string;
+  mountCount: number;
+  updateCount: number;
+  totalRenders: number;
+  avgActualDuration: number;
+  maxActualDuration: number;
+  avgBaseDuration: number;
+  lastActualDuration: number;
+  lastCommitTime: number;
+};
+
+/**
+ * Store that collects profiler entries and notifies subscribers.
+ */
+class SurfaceProfilerStore {
+  private _entries: SurfaceProfilerEntry[] = [];
+  private _listeners = new Set<() => void>();
+  private _snapshot: readonly SurfaceProfilerEntry[] = [];
+  private _pendingNotify = false;
+
+  /** Records an entry and schedules a deferred notification to avoid re-render loops. */
+  record(entry: SurfaceProfilerEntry) {
+    this._entries.push(entry);
+    if (this._entries.length > MAX_ENTRIES) {
+      this._entries = this._entries.slice(-MAX_ENTRIES);
+    }
+    this._snapshot = [...this._entries];
+    this._scheduleNotify();
+  }
+
+  clear() {
+    this._entries = [];
+    this._snapshot = [];
+    this._notifySync();
+  }
+
+  subscribe = (listener: () => void) => {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  };
+
+  getSnapshot = (): readonly SurfaceProfilerEntry[] => {
+    return this._snapshot;
+  };
+
+  /**
+   * Defers notification to the next animation frame to break the
+   * Profiler onRender → record → notify → re-render → onRender loop.
+   */
+  private _scheduleNotify() {
+    if (!this._pendingNotify) {
+      this._pendingNotify = true;
+      requestAnimationFrame(() => {
+        this._pendingNotify = false;
+        this._notifySync();
+      });
+    }
+  }
+
+  private _notifySync() {
+    for (const listener of this._listeners) {
+      listener();
+    }
+  }
+}
+
+type SurfaceProfilerContextValue = {
+  store: SurfaceProfilerStore;
+};
+
+const SurfaceProfilerContext: Context<SurfaceProfilerContextValue | undefined> = createContext<
+  SurfaceProfilerContextValue | undefined
+>(undefined);
+
+/**
+ * Provider that collects React Profiler data from Surface components.
+ */
+export const SurfaceProfilerProvider = ({ children }: PropsWithChildren) => {
+  const storeRef = useRef<SurfaceProfilerStore>(null);
+  if (!storeRef.current) {
+    storeRef.current = new SurfaceProfilerStore();
+  }
+  return (
+    <SurfaceProfilerContext.Provider value={{ store: storeRef.current }}>{children}</SurfaceProfilerContext.Provider>
+  );
+};
+
+/**
+ * Returns a stable onRender callback for use with React Profiler.
+ */
+export const useSurfaceProfilerCallback = (): ProfilerOnRenderCallback | undefined => {
+  const store = useContext(SurfaceProfilerContext)?.store;
+  return useMemo<ProfilerOnRenderCallback | undefined>(() => {
+    if (!store) {
+      return undefined;
+    }
+    return (id, phase, actualDuration, baseDuration, startTime, commitTime) => {
+      store.record({
+        id,
+        phase,
+        actualDuration,
+        baseDuration,
+        startTime,
+        commitTime,
+        timestamp: Date.now(),
+      });
+    };
+  }, [store]);
+};
+
+/**
+ * Returns all profiler entries reactively.
+ */
+export const useSurfaceProfilerEntries = (): readonly SurfaceProfilerEntry[] => {
+  const context = useContext(SurfaceProfilerContext);
+  return useSyncExternalStore(context?.store.subscribe ?? noop, context?.store.getSnapshot ?? emptySnapshot);
+};
+
+/**
+ * Returns aggregated stats grouped by surface id.
+ */
+export const useSurfaceProfilerStats = (): SurfaceProfilerStats[] => {
+  const entries = useSurfaceProfilerEntries();
+  const statsMap = new Map<string, SurfaceProfilerStats>();
+
+  for (const entry of entries) {
+    let stats = statsMap.get(entry.id);
+    if (!stats) {
+      stats = {
+        id: entry.id,
+        mountCount: 0,
+        updateCount: 0,
+        totalRenders: 0,
+        avgActualDuration: 0,
+        maxActualDuration: 0,
+        avgBaseDuration: 0,
+        lastActualDuration: 0,
+        lastCommitTime: 0,
+      };
+      statsMap.set(entry.id, stats);
+    }
+
+    if (entry.phase === 'mount') {
+      stats.mountCount++;
+    } else {
+      stats.updateCount++;
+    }
+    stats.totalRenders++;
+    stats.avgActualDuration =
+      (stats.avgActualDuration * (stats.totalRenders - 1) + entry.actualDuration) / stats.totalRenders;
+    stats.avgBaseDuration =
+      (stats.avgBaseDuration * (stats.totalRenders - 1) + entry.baseDuration) / stats.totalRenders;
+    stats.maxActualDuration = Math.max(stats.maxActualDuration, entry.actualDuration);
+    stats.lastActualDuration = entry.actualDuration;
+    stats.lastCommitTime = entry.commitTime;
+  }
+
+  return [...statsMap.values()].sort((a, b) => b.maxActualDuration - a.maxActualDuration);
+};
+
+/**
+ * Clears all collected profiler entries.
+ */
+export const useSurfaceProfilerClear = (): (() => void) | undefined => {
+  const store = useContext(SurfaceProfilerContext)?.store;
+  return useMemo(() => (store ? () => store.clear() : undefined), [store]);
+};
+
+const noop = () => () => {};
+const EMPTY_SNAPSHOT: readonly SurfaceProfilerEntry[] = [];
+const emptySnapshot = () => EMPTY_SNAPSHOT;

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,54 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// TODO(wittjosiah): Cleanup to avoid re-naming.
+import { SurfaceContext } from './context';
+import { SurfaceComponent, isSurfaceAvailable } from './SurfaceComponent';
+import {
+  SurfaceProfilerProvider,
+  useSurfaceProfilerCallback,
+  useSurfaceProfilerClear,
+  useSurfaceProfilerEntries,
+  useSurfaceProfilerStats,
+} from './SurfaceProfilerContext';
+import {
+  type Definition as SurfaceDefinition,
+  type RoleToken as SurfaceRoleToken,
+  type SurfaceBinding as SurfaceBindingType,
+  type SurfaceFilter as SurfaceFilterType,
+  type TokenData as SurfaceTokenData,
+  type TypedProps as SurfaceTypedProps,
+  create as createSurface,
+  createWeb as createWebSurface,
+  isSurfaceFilter as isSurfaceFilterFn,
+  makeType as makeTypeFn,
+} 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;
+
+  export type RoleToken<TData> = SurfaceRoleToken<TData>;
+  export type Binding = SurfaceBindingType;
+  export type Filter<TData> = SurfaceFilterType<TData>;
+  export type TokenData<T> = SurfaceTokenData<T>;
+  export type TypedProps<TToken extends SurfaceRoleToken<any>> = SurfaceTypedProps<TToken>;
+  export const makeType = makeTypeFn;
+  export const isFilter = isSurfaceFilterFn;
+
+  export const ProfilerProvider = SurfaceProfilerProvider;
+  export const useProfilerCallback = useSurfaceProfilerCallback;
+  export const useProfilerEntries = useSurfaceProfilerEntries;
+  export const useProfilerStats = useSurfaceProfilerStats;
+  export const useProfilerClear = useSurfaceProfilerClear;
+}
+
+export type { SurfaceProfilerEntry, SurfaceProfilerStats } from './SurfaceProfilerContext';