@dxos/app-framework 0.9.0 → 0.9.1-staging.ee54ba693a

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

@@ -4,6 +4,7 @@
 
 import { useAtomValue } from '@effect-atom/atom-react';
 import React, {
+  type FC,
   Fragment,
   type NamedExoticComponent,
   Profiler,
@@ -19,11 +20,11 @@ import 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 { Position } from '@dxos/util';
 
 import { Capabilities } from '../../../common';
 import { type CapabilityManager } from '../../../core';
-import { usePluginManager } from '../PluginManager/PluginManagerProvider';
+import { usePluginManager } from '../PluginManager';
 import { SurfaceContext } from './context';
 import { SurfaceInfo } from './SurfaceInfo';
 import { useSurfaceProfilerCallback } from './SurfaceProfilerContext';
@@ -36,7 +37,7 @@ import {
   type WebComponentDefinition,
 } from './types';
 
-const DEBUG = import.meta.env.VITE_DEBUG;
+const DEBUG = import.meta.env?.VITE_DEBUG;
 
 const DEFAULT_PLACEHOLDER = <Fragment />;
 
@@ -44,78 +45,95 @@ const DEFAULT_PLACEHOLDER = <Fragment />;
  * Wrapper component for rendering Web Component surfaces.
  * Handles creation, prop setting, and cleanup of Web Components.
  */
+type WebComponentWrapperProps = {
+  id?: string;
+  role: string;
+  data?: Record<string, any>;
+  limit?: number;
+  definition: WebComponentDefinition;
+  [key: string]: any;
+};
+
 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;
-        }
+  forwardRef<HTMLElement, WebComponentWrapperProps>(({ 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;
+      // 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);
+      // Set initial properties on the Web Component
+      Object.assign(element, propsRef.current);
 
-        // Append to container
-        containerRef.current.appendChild(element);
+      // Append to container
+      containerRef.current.appendChild(element);
 
-        // Setup ref forwarding if provided
+      // 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(element);
+          forwardedRef(null);
         } 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;
+          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);
-      });
+      // Update properties on the existing Web Component
+      Object.assign(element, propsRef.current);
+    });
 
-      return <div ref={containerRef} />;
-    },
-  ),
+    return <div ref={containerRef} />;
+  }),
 );
 
 WebComponentWrapper.displayName = 'WebComponentWrapper';
 
+type SurfaceContextProviderProps = {
+  id: string;
+  role: string;
+  data?: Record<string, any>;
+  limit?: number;
+  fallback?: FC<{ error: Error; data?: any }>;
+  definition: Definition;
+  [key: string]: any;
+};
+
 /**
  * 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 }>(
+  forwardRef<HTMLElement, SurfaceContextProviderProps>(
     ({ id, role, data, limit, fallback = ErrorFallback, definition, ...rest }, forwardedRef) => {
       const contextValue = useMemo(() => ({ id, role, data }), [id, role, data]);
       const onProfilerRender = useSurfaceProfilerCallback();
@@ -182,11 +200,13 @@ SurfaceContextProvider.displayName = 'SurfaceContextProvider';
 
 /**
  * A surface is a named region of the screen that can be populated by plugins.
+ * The `type` prop is a {@link RoleToken} that defines which region and its
+ * associated data contract.
  */
 // 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) => {
+  forwardRef<HTMLElement, TypedProps<RoleToken<any>>>(
+    ({ id: _id, 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.
@@ -195,10 +215,10 @@ export const SurfaceComponent = memo(
       //   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;
+      const effectiveRole = type?.role;
       if (effectiveRole == null) {
         if (DEBUG) {
-          log.warn('Surface has neither `role` nor `type` prop', { id: _id });
+          log.warn('Surface is missing required `type` prop', { id: _id });
         }
         return null;
       }
@@ -230,12 +250,12 @@ export const SurfaceComponent = memo(
     },
   ),
 ) as (<TToken extends RoleToken<any>>(props: TypedProps<TToken> & RefAttributes<HTMLElement>) => React.ReactNode) &
-  NamedExoticComponent<Props & RefAttributes<HTMLElement>>;
+  NamedExoticComponent<TypedProps<RoleToken<any>> & RefAttributes<HTMLElement>>;
 
 SurfaceComponent.displayName = 'Surface';
 
 // TODO(burdon): Make user facing, with telemetry.
-const ErrorFallback = ({ error }: Props) => {
+const ErrorFallback = ({ error }: { error: Error }) => {
   const { message } = error instanceof Error ? error : { message: String(error) };
   return (
     <div role='alert' data-testid='error-boundary-fallback'>
@@ -250,7 +270,7 @@ const findCandidates = (surfaces: Definition[], { role, data }: { role: string;
       Array.isArray(definition.role) ? definition.role.includes(role) : definition.role === role,
     )
     .filter(({ filter }) => (filter ? filter(data ?? {}, role) : true))
-    .toSorted(byPosition);
+    .toSorted(Position.compare);
 };
 
 /**
@@ -261,7 +281,7 @@ export const useSurfaces = () => {
   const surfacesByModule = useAtomValue(manager.capabilities.atomByModule(Capabilities.ReactSurface));
   return useMemo(() => {
     const result: Definition[] = [];
-    for (const [moduleId, surfaces] of Object.entries(surfacesByModule)) {
+    for (const [_moduleId, surfaces] of Object.entries(surfacesByModule)) {
       for (const def of surfaces.flat()) {
         result.push(def);
       }
@@ -273,31 +293,22 @@ export const useSurfaces = () => {
 /**
  * @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.
+ * Typed: pass a `type` role token and `data` is constrained to the token's
+ * declared contract (e.g. `AppSurface.Section` requires `attendableId`).
  */
 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 },
+  args: { type: TToken; data?: TokenData<TToken> },
 ): boolean {
-  const effectiveRole = role ?? type?.role;
+  const effectiveRole = args.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'],
+    data: args.data as Props['data'],
   });
   return candidates.length > 0;
 }

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

@@ -4,8 +4,8 @@
 
 import React, {
   type Context,
-  type PropsWithChildren,
   type ProfilerOnRenderCallback,
+  type PropsWithChildren,
   createContext,
   useContext,
   useMemo,

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

@@ -4,9 +4,11 @@
 
 import { type Context, createContext } from 'react';
 
-import { type Props } from './types';
+export type SurfaceContext = {
+  id?: string;
+  /** The resolved role NSID (e.g. `org.dxos.role.article`). */
+  role: string;
+  data?: Record<string, any>;
+};
 
-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

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+import type { DXN } from '@dxos/keys';
+
 // TODO(wittjosiah): Cleanup to avoid re-naming.
 import { SurfaceContext } from './context';
 import { SurfaceComponent, isSurfaceAvailable } from './SurfaceComponent';
@@ -13,15 +15,16 @@ import {
   useSurfaceProfilerStats,
 } from './SurfaceProfilerContext';
 import {
-  type Definition as SurfaceDefinition,
-  type RoleToken as SurfaceRoleToken,
   type SurfaceBinding as SurfaceBindingType,
+  type Definition as SurfaceDefinition,
   type SurfaceFilter as SurfaceFilterType,
+  type RoleToken as SurfaceRoleToken,
   type TokenData as SurfaceTokenData,
   type TypedProps as SurfaceTypedProps,
   create as createSurface,
   createWeb as createWebSurface,
   isSurfaceFilter as isSurfaceFilterFn,
+  makeFilter as makeFilterFn,
   makeType as makeTypeFn,
 } from './types';
 
@@ -41,7 +44,15 @@ export namespace Surface {
   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;
+
+  /** Mints a typed role token. The NSID is validated at compile time via {@link DXN.Name}. */
+  export const makeType: {
+    <TData = unknown, T extends string = string>(
+      nsid: [DXN.Name<T>] extends [never] ? `Invalid NSID "${T}": final segment must be camelCase (no hyphens)` : T,
+    ): SurfaceRoleToken<TData>;
+  } = makeTypeFn;
+
+  export const makeFilter = makeFilterFn;
   export const isFilter = isSurfaceFilterFn;
 
   export const ProfilerProvider = SurfaceProfilerProvider;

package/src/ui/components/Surface/types.test.ts

@@ -4,27 +4,39 @@
 
 import { describe, test } from 'vitest';
 
+import { Position } from '@dxos/util';
+
 import { type CapabilityManager } from '../../../core';
 import { isSurfaceAvailable } from './SurfaceComponent';
-import { type RoleToken, type SurfaceFilter, create, isSurfaceFilter, makeType } from './types';
+import { type RoleToken, type SurfaceFilter, create, isSurfaceFilter, makeFilter, makeType } from './types';
 
 describe('Surface.makeType', () => {
-  test('creates a role token carrying the role string', ({ expect }) => {
-    const token = makeType<{ subject: string }>('test-role');
-    expect(token.role).toBe('test-role');
+  test('creates a role token with the given NSID', ({ expect }) => {
+    const token = makeType<{ subject: string }>('org.dxos.test.role.testRole');
+    expect(token.role).toBe('org.dxos.test.role.testRole');
   });
 
   test('tokens with the same role are independent objects (identity-by-role)', ({ expect }) => {
-    const a = makeType<{ x: number }>('shared');
-    const b = makeType<{ x: number }>('shared');
-    expect(a).not.toBe(b);
-    expect(a.role).toBe(b.role);
+    const tokenOne = makeType<{ x: number }>('org.dxos.test.role.shared');
+    const tokenTwo = makeType<{ x: number }>('org.dxos.test.role.shared');
+    expect(tokenOne).not.toBe(tokenTwo);
+    expect(tokenOne.role).toBe(tokenTwo.role);
+  });
+
+  test('throws on invalid NSID at runtime (hyphenated final segment)', ({ expect }) => {
+    expect(() => makeType('org.dxos.test.role.bad-name' as any)).toThrow();
+  });
+
+  test('throws on single-segment NSID', ({ expect }) => {
+    expect(() => makeType('article' as any)).toThrow();
   });
 });
 
 describe('isSurfaceFilter', () => {
   test('distinguishes filter objects from predicate functions', ({ expect }) => {
-    const filter: SurfaceFilter<Record<string, any>> = { bindings: [{ role: 'r', guard: () => true }] };
+    const filter: SurfaceFilter<Record<string, any>> = {
+      bindings: [{ role: 'org.dxos.test.role.r', guard: () => true }],
+    };
     expect(isSurfaceFilter(filter)).toBe(true);
     expect(isSurfaceFilter(() => true)).toBe(false);
     expect(isSurfaceFilter({})).toBe(false);
@@ -33,61 +45,49 @@ describe('isSurfaceFilter', () => {
 });
 
 describe('create', () => {
-  test('accepts the legacy { role, filter } shape', ({ expect }) => {
-    const def = create({
-      id: 'legacy',
-      role: 'article',
-      filter: (data): data is { x: number } => typeof (data as any).x === 'number',
-      component: () => null,
-    });
-    expect(def.kind).toBe('react');
-    expect(def.role).toBe('article');
-    expect(def.filter!({ x: 1 })).toBe(true);
-    expect(def.filter!({})).toBe(false);
-  });
-
   test('expands a single-binding SurfaceFilter into a role string', ({ expect }) => {
-    const filter: SurfaceFilter<Record<string, any>> = {
-      bindings: [{ role: 'article', guard: (d) => (d as any).subject === 'ok' }],
-    };
+    const token = makeType<Record<string, any>>('org.dxos.test.role.article');
+    const filter = makeFilter(token, (data) => data.subject === 'ok');
     const def = create({ id: 'typedSingle', filter, component: () => null });
-    expect(def.role).toBe('article');
-    expect(def.filter!({ subject: 'ok' }, 'article')).toBe(true);
-    expect(def.filter!({ subject: 'no' }, 'article')).toBe(false);
+    expect(def.role).toBe('org.dxos.test.role.article');
+    expect(def.filter!({ subject: 'ok' }, 'org.dxos.test.role.article')).toBe(true);
+    expect(def.filter!({ subject: 'no' }, 'org.dxos.test.role.article')).toBe(false);
   });
 
   test('expands a multi-binding SurfaceFilter into a role array with role-scoped guards', ({ expect }) => {
+    const tokenA = makeType<Record<string, any>>('org.dxos.test.role.article');
+    const tokenB = makeType<Record<string, any>>('org.dxos.test.role.section');
     const filter: SurfaceFilter<Record<string, any>> = {
       bindings: [
-        { role: 'article', guard: (d) => (d as any).subject === 'a' },
-        { role: 'section', guard: (d) => (d as any).subject === 's' },
+        { role: tokenA.role, guard: (data) => (data as any).subject === 'a' },
+        { role: tokenB.role, guard: (data) => (data as any).subject === 's' },
       ],
     };
     const def = create({ id: 'typedMulti', filter, component: () => null });
-    expect(def.role).toEqual(['article', 'section']);
+    expect(def.role).toEqual([tokenA.role, tokenB.role]);
     // Role-specific guard.
-    expect(def.filter!({ subject: 'a' }, 'article')).toBe(true);
-    expect(def.filter!({ subject: 'a' }, 'section')).toBe(false);
-    expect(def.filter!({ subject: 's' }, 'section')).toBe(true);
-    expect(def.filter!({ subject: 's' }, 'article')).toBe(false);
+    expect(def.filter!({ subject: 'a' }, tokenA.role)).toBe(true);
+    expect(def.filter!({ subject: 'a' }, tokenB.role)).toBe(false);
+    expect(def.filter!({ subject: 's' }, tokenB.role)).toBe(true);
+    expect(def.filter!({ subject: 's' }, tokenA.role)).toBe(false);
     // Without role, any binding may match.
     expect(def.filter!({ subject: 'a' })).toBe(true);
     expect(def.filter!({ subject: 'unknown' })).toBe(false);
   });
 
   test('passes position through untouched', ({ expect }) => {
-    const filter: SurfaceFilter<Record<string, any>> = { bindings: [{ role: 'r', guard: () => true }] };
-    const def = create({ id: 'pos', filter, component: () => null, position: 'last' });
-    expect(def.position).toBe('last');
+    const token = makeType<Record<string, any>>('org.dxos.test.role.r');
+    const filter: SurfaceFilter<Record<string, any>> = { bindings: [{ role: token.role, guard: () => true }] };
+    const def = create({ id: 'pos', filter, component: () => null, position: Position.last });
+    expect(def.position).toBe(Position.last);
   });
 });
 
 describe('role token typing', () => {
   test('makeType preserves TData through token use-sites', ({ expect }) => {
-    // Type-level smoke test: if TS compiles, we're fine. The `RoleToken<T>`
-    // phantom should not impose a runtime constraint.
-    const token: RoleToken<{ subject: number }> = makeType('numeric');
-    expect(token.role).toBe('numeric');
+    // Type-level smoke test: if TS compiles, we're fine.
+    const token: RoleToken<{ subject: number }> = makeType('org.dxos.test.role.numeric');
+    expect(token.role).toBe('org.dxos.test.role.numeric');
   });
 });
 
@@ -95,7 +95,7 @@ describe('isSurfaceAvailable typing', () => {
   // These tests double as static assertions: the `@ts-expect-error` comments
   // fail to compile if the surrounding expression typechecks, so they verify
   // the typed overload narrows `data` to the token's declared contract.
-  const sectionToken = makeType<{ attendableId: string; subject: string }>('section');
+  const sectionToken = makeType<{ attendableId: string; subject: string }>('org.dxos.test.role.section');
   const capabilityManager = { getAll: () => [] } as unknown as CapabilityManager.CapabilityManager;
 
   test('typed overload accepts data matching the token contract', () => {
@@ -115,12 +115,4 @@ describe('isSurfaceAvailable typing', () => {
     // @ts-expect-error — `attendableId` must be a string, not a number.
     isSurfaceAvailable(capabilityManager, { type: sectionToken, data: { attendableId: 123, subject: 'x' } });
   });
-
-  test('legacy overload accepts loose data when `role` is a string', () => {
-    // No error — legacy overload's `data` is untyped (`Record<string, unknown>`).
-    isSurfaceAvailable(capabilityManager, {
-      role: 'article',
-      data: { anything: 'goes' },
-    });
-  });
 });