@dxos/app-framework 0.8.4-main.7ace549 → 0.8.4-main.937b3ca

package/src/react/Surface.stories.tsx

@@ -3,40 +3,51 @@
 //
 
 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 * as Common from '../common';
 import { withPluginManager } from '../testing';
 
 import { usePluginManager } from './PluginManagerProvider';
 import { Surface, useSurfaces } from './Surface';
 
+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({
+      interface: Common.Capability.ReactSurface,
+      implementation: Common.createSurface({
         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 +59,10 @@ const DefaultStory = () => {
   }, [surfaces]);
 
   const handleError = useCallback(() => {
-    manager.context.contributeCapability({
+    manager.capabilities.contribute({
       module: 'error',
-      interface: Capabilities.ReactSurface,
-      implementation: createSurface({
+      interface: Common.Capability.ReactSurface,
+      implementation: Common.createSurface({
         id: 'error',
         role: 'item',
         filter: (data): data is any => (data as any)?.id === 'error',
@@ -86,6 +97,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 +110,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) => (

package/src/react/Surface.tsx

@@ -3,62 +3,228 @@
 //
 
 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 { useDefaultValue } from '@dxos/react-hooks';
 import { byPosition } from '@dxos/util';
 
-import { Capabilities, type SurfaceDefinition, type SurfaceProps } from '../common';
-import { type PluginContext } from '../core';
+import * as Common from '../common';
+import { type CapabilityManager } from '../core';
 
 import { ErrorBoundary } from './ErrorBoundary';
+import { SurfaceInfo } from './SurfaceInfo';
 import { useCapabilities } from './useCapabilities';
 
 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);
+
 /**
- * A surface is a named region of the screen that can be populated by plugins.
+ * Wrapper component for rendering Web Component surfaces.
+ * Handles creation, prop setting, and cleanup of Web Components.
  */
-export const Surface: NamedExoticComponent<SurfaceProps & RefAttributes<HTMLElement>> = memo(
-  forwardRef(
-    (
-      { id: _id, role, data: dataParam, limit, fallback = DefaultFallback, placeholder = DEFAULT_PLACEHOLDER, ...rest },
-      forwardedRef,
-    ) => {
-      // 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 data = useDefaultValue(dataParam, () => ({}));
-
-      // 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;
-      const nodes = candidates.map(({ id, component: Component }) => (
-        <Component ref={forwardedRef} key={id} id={id} role={role} data={data} limit={limit} {...rest} />
-      ));
-
-      // TODO(burdon): Able to inject DOM properties into root (e.g., object.id).
-      const suspense = <Suspense fallback={placeholder}>{nodes}</Suspense>;
+const WebComponentWrapper = memo(
+  forwardRef<HTMLElement, Common.SurfaceProps & { definition: Common.WebComponentSurfaceDefinition }>(
+    ({ 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, Common.SurfaceProps & { definition: Common.SurfaceDefinition }>(
+    ({ 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}>
-          {suspense}
+          <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';
+
+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(
+  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: Common.SurfaceDefinition[],
+  { role, data }: Pick<Common.SurfaceProps, '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 }) => {
@@ -84,26 +250,18 @@ const DefaultFallback = ({ data, error, dev }: { data: any; error: Error; dev?:
  * @internal
  */
 export const useSurfaces = () => {
-  const surfaces = useCapabilities(Capabilities.ReactSurface);
+  const surfaces = useCapabilities(Common.Capability.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 = (context: PluginContext, { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
-  const surfaces = context.getCapabilities(Capabilities.ReactSurface);
+export const isSurfaceAvailable = (
+  capabilityManager: CapabilityManager.CapabilityManager,
+  { role, data }: Pick<Common.SurfaceProps, 'role' | 'data'>,
+) => {
+  const surfaces = capabilityManager.getAll(Common.Capability.ReactSurface);
   const candidates = findCandidates(surfaces.flat(), { role, data });
   return candidates.length > 0;
 };
-
-const findCandidates = (surfaces: SurfaceDefinition[], { role, data }: Pick<SurfaceProps, '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);
-};
-
-Surface.displayName = 'Surface';

package/src/react/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 './Surface';
+
+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/react/common.ts

@@ -2,12 +2,36 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Capabilities } from '../common';
+import { type Atom, RegistryContext, useAtomValue } from '@effect-atom/atom-react';
+import { useCallback, useContext } from 'react';
 
-import { useCapability } from './useCapabilities';
+import * as Common from '../common';
 
-export const useIntentDispatcher = () => useCapability(Capabilities.IntentDispatcher);
+import { useAtomCapability, useCapability } from './useCapabilities';
 
-export const useAppGraph = () => useCapability(Capabilities.AppGraph);
+export const useOperationInvoker = (): Common.Capability.OperationInvoker =>
+  useCapability(Common.Capability.OperationInvoker);
 
-export const useLayout = () => useCapability(Capabilities.Layout);
+export const useAppGraph = (): Common.Capability.AppGraph => useCapability(Common.Capability.AppGraph);
+
+export const useLayout = (): Common.Capability.Layout => useAtomCapability(Common.Capability.Layout);
+
+/**
+ * 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/react/index.ts

@@ -11,4 +11,4 @@ export * from './Surface';
 
 export * from './useApp';
 export * from './useCapabilities';
-export * from './useIntentResolver';
+export * from './useOperationResolver';

package/src/react/types.ts

@@ -2,37 +2,26 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as Schema from 'effect/Schema';
-
 import { type Obj } from '@dxos/echo';
 
-export const SurfaceCardRole = Schema.Literal(
-  'card',
-  'card--popover',
-  'card--intrinsic',
-  'card--extrinsic',
-  'card--transclusion',
-);
-
-export type SurfaceCardRole = Schema.Schema.Type<typeof SurfaceCardRole>;
+// TODO(burdon): Standardize PluginSettings and ObjectProperties.
+// TODO(burdon): Include attendableId?
+// TODO(burdon): companionTo?
 
-// TODO(burdon): Define all roles.
 export type SurfaceRole =
   | 'item'
   | 'article'
-  | 'complementary' // (for companion?)
+  | 'complementary' // Companion
   | 'section'
-  | SurfaceCardRole;
+  | 'card--content';
 
 /**
  * Base type for surface components.
  */
-// TODO(burdon): Standardize PluginSettings and ObjectProperties.
-// TODO(burdon): Include attendableId?
-// TODO(burdon): companionTo?
-export type SurfaceComponentProps<Subject extends Obj.Any = Obj.Any, Role extends string = string> = {
-  role?: Role;
+export type SurfaceComponentProps<Subject extends Obj.Unknown | undefined = Obj.Unknown, Props extends {} = {}> = {
+  /** WAI-ARIA role. */
+  role?: string;
 
   /** The primary object being displayed. */
   subject: Subject;
-};
+} & Props;