@dxos/app-framework 0.8.4-main.9be5663bfe → 0.8.4-main.abd8ff62ef

package/src/ui/components/Placeholder/Placeholder.tsx

@@ -0,0 +1,155 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type ReactNode, useEffect, useLayoutEffect, useRef } from 'react';
+
+import { ThemeProvider } from '@dxos/react-ui';
+import { defaultTx, mx } from '@dxos/ui-theme';
+
+import { type PlaceholderProps as PlaceholderSlotProps } from '../../hooks';
+
+declare global {
+  interface Window {
+    /**
+     * Driver injected by `@dxos/app-framework/vite-plugin`'s `bootLoaderPlugin`.
+     * Declared here so the {@link Placeholder} can dismiss the native-DOM
+     * loader once the React placeholder commits without each host having to
+     * re-declare the type.
+     */
+    __bootLoader?: {
+      status: (payload: {
+        event?: string;
+        module?: string;
+        humanized: string;
+        /**
+         * Optional `(index/total)` tick. When present, the loader replaces the
+         * current line in place ("Loading plugins (12/80)") instead of
+         * appending a new entry — keeps the visible log compact during long
+         * counted phases like plugin chunk-loading or module activation.
+         */
+        range?: { index: number; total: number };
+      }) => void;
+      progress: (fraction?: number) => void;
+      dismiss: () => void;
+    };
+  }
+}
+
+export type PlaceholderComponentProps = PlaceholderSlotProps & {
+  /**
+   * Brand mark rendered while the React tree settles. Pass either a static
+   * `ReactNode` (the framework wraps it in a sizing/animation div) or a
+   * render function that receives the precomputed `className` so the host
+   * can apply it directly to its logo (e.g. an SVG that accepts `className`
+   * — `composer-app` passes `(p) => <Composer {...p} />` from `@dxos/brand`).
+   */
+  logo?: ReactNode | ((props: { className: string }) => ReactNode);
+};
+
+/**
+ * React placeholder. The native-DOM boot loader is the visible UI through
+ * stages 0 (Loading) and 1 (FadeIn): we render `null` until `stage >= 2`
+ * (FadeOut) and instead feed activation progress + status into the still-
+ * alive boot loader. At stage 2 the loader dismisses and the React mark
+ * appears for the cross-fade to the real shell:
+ *
+ *   - composer-app fills `0 → 50%` from `getPlugins`'s per-chunk counter.
+ *   - this component fills `50 → 100%` from `useApp`'s
+ *     `startupProgress.progress` (`activated / total` modules) and pushes
+ *     the per-module status text to the loader's status line.
+ *   - at `stage >= 2` the boot loader is dismissed and the React mark
+ *     starts its `FadeOut → Done` shrink-and-fade.
+ *
+ * Stage progression (driven by `useApp`):
+ *   - `0` — Loading: native-DOM boot loader visible. Placeholder renders nothing.
+ *   - `1` — FadeIn: same — boot loader still owns the screen.
+ *   - `2` — FadeOut: boot loader dismissed, React mark visible at full opacity then shrinks.
+ */
+export const Placeholder = ({ stage = 1, progress, logo }: PlaceholderComponentProps) => {
+  // Used in tests to exercise the error boundary & reset dialog.
+  if (location.search === '?throw') {
+    throw new Error('Test error');
+  }
+
+  // Phase B: feed activation progress + status to the still-visible boot
+  // loader. Maps `[0, 1]` activation → `[0.5, 1]` of the ring; forwards
+  // the raw activation source (`event` / `module`) plus the pre-humanised
+  // label to `__bootLoader.status` so the loader gets to decide how to
+  // render and trace each transition (current default policy: "Activating
+  // <humanizedName>"; trace mode and timings track the structured fields).
+  // No-op once the loader has been dismissed (its `status()` early-returns
+  // when the boot DOM is gone). Skipping `stage >= 2` lets the dismissal
+  // run uncontended.
+  useEffect(() => {
+    if (stage >= 2) {
+      return;
+    }
+    const fraction = progress?.progress ?? 0;
+    window.__bootLoader?.progress(0.5 + fraction * 0.5);
+    if (progress?.humanizedName) {
+      window.__bootLoader?.status({
+        event: progress.event,
+        module: progress.module,
+        humanized: `Activating ${progress.humanizedName}`,
+      });
+    }
+  }, [stage, progress?.progress, progress?.event, progress?.module, progress?.humanizedName]);
+
+  // Hand off from the native-DOM boot loader once the placeholder starts
+  // fading out — keeping the loader visible through `stage 0` and `stage 1`
+  // means the ring stays the visible source of truth for activation
+  // progress. `useLayoutEffect` runs before the next paint so the loader
+  // DOM is removed in the same frame the cross-fade begins.
+  useLayoutEffect(() => {
+    if (stage >= 2) {
+      window.__bootLoader?.dismiss();
+    }
+  }, [stage]);
+
+  // Backstop for the fast-load path where `useLoading` can skip straight
+  // from stage 0 to `Done` (ready=true at the first debounce tick) — the
+  // stage-driven effect above never sees `stage >= 2`, so dismiss on
+  // unmount instead. The `stageRef` guard is what keeps StrictMode's
+  // synthetic mount → cleanup → remount cycle from prematurely dismissing
+  // the loader: the synthetic cleanup runs while `stageRef.current === 0`,
+  // skips the dismiss, and the real unmount (later, at stage `Done`)
+  // performs it.
+  const stageRef = useRef(stage);
+  stageRef.current = stage;
+  useEffect(() => {
+    return () => {
+      if (stageRef.current >= 3 /* Done */) {
+        window.__bootLoader?.dismiss();
+      }
+    };
+  }, []);
+
+  // Defer rendering anything until the FadeOut stage. The boot loader owns
+  // the screen during stages 0 and 1, so any DOM we render here would just
+  // sit invisibly behind it — and rendering null avoids paint cost during
+  // the longest part of the loading sequence (plugin activation).
+  if (stage < 2) {
+    return null;
+  }
+
+  const logoClassName = mx(
+    'h-[300px] w-[300px] scale-600 transition-all duration-500 ease-in-out filter grayscale opacity-0',
+    stage >= 1 && 'scale-100 grayscale-0 opacity-70',
+    stage >= 2 && 'scale-50 opacity-0',
+  );
+
+  return (
+    <ThemeProvider tx={defaultTx}>
+      <div role='none' className='relative dx-container h-dvh flex flex-col'>
+        <div role='none' className='flex flex-col grow justify-center items-center'>
+          {typeof logo === 'function' ? (
+            logo({ className: logoClassName })
+          ) : logo ? (
+            <div className={logoClassName}>{logo}</div>
+          ) : null}
+        </div>
+      </div>
+    </ThemeProvider>
+  );
+};

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

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './Placeholder';

package/src/ui/components/PluginManager/PluginManagerContext.stories.tsx

@@ -38,7 +38,9 @@ const CountStatus = () => {
     }
   }, [counter]);
 
-  if (!manager) return null;
+  if (!manager) {
+    return null;
+  }
 
   const isEven = count % 2 === 0;
 
@@ -170,7 +172,7 @@ const DefaultStory = () => {
 };
 
 const meta = {
-  title: 'sdk/app-framework/PluginManagerContext',
+  title: 'sdk/app-framework/components/PluginManagerContext',
   render: DefaultStory,
   decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
   parameters: {

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

@@ -129,7 +129,7 @@ const DefaultStory = () => {
 };
 
 const meta = {
-  title: 'sdk/app-framework/Surface',
+  title: 'sdk/app-framework/components/Surface',
   render: DefaultStory,
   decorators: [withTheme(), withLayout({ layout: 'fullscreen' }), withPluginManager({ capabilities: [] })],
   parameters: {

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

@@ -27,7 +27,14 @@ import { usePluginManager } from '../PluginManager/PluginManagerProvider';
 import { SurfaceContext } from './context';
 import { SurfaceInfo } from './SurfaceInfo';
 import { useSurfaceProfilerCallback } from './SurfaceProfilerContext';
-import { type Definition, type Props, type WebComponentDefinition } from './types';
+import {
+  type Definition,
+  type Props,
+  type RoleToken,
+  type TokenData,
+  type TypedProps,
+  type WebComponentDefinition,
+} from './types';
 
 const DEBUG = import.meta.env.VITE_DEBUG;
 
@@ -38,7 +45,7 @@ const DEFAULT_PLACEHOLDER = <Fragment />;
  * Handles creation, prop setting, and cleanup of Web Components.
  */
 const WebComponentWrapper = memo(
-  forwardRef<HTMLElement, Props & { definition: WebComponentDefinition }>(
+  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);
@@ -108,7 +115,7 @@ WebComponentWrapper.displayName = 'WebComponentWrapper';
  */
 // TODO(burdon): Allow DebugPlugin to provide different fallback using react-ui ErrorFallback.
 const SurfaceContextProvider = memo(
-  forwardRef<HTMLElement, Props & { definition: Definition }>(
+  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();
@@ -177,43 +184,53 @@ 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: NamedExoticComponent<Props & 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;
-    }
+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;
+      }
 
-    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>
-    );
-  }),
-);
+      // 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';
 
@@ -227,12 +244,12 @@ const ErrorFallback = ({ error }: Props) => {
   );
 };
 
-const findCandidates = (surfaces: Definition[], { role, data }: Pick<Props, 'role' | 'data'>) => {
+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 ?? {}) : true))
+    .filter(({ filter }) => (filter ? filter(data ?? {}, role) : true))
     .toSorted(byPosition);
 };
 
@@ -255,12 +272,32 @@ 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.
  */
-export const isSurfaceAvailable = (
+export function isSurfaceAvailable<TToken extends RoleToken<any>>(
   capabilityManager: CapabilityManager.CapabilityManager,
-  { role, data }: Pick<Props, 'role' | 'data'>,
-) => {
+  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, data });
+  const candidates = findCandidates(surfaces.flat(), {
+    role: effectiveRole,
+    data: data as Props['data'],
+  });
   return candidates.length > 0;
-};
+}

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

@@ -12,7 +12,18 @@ import {
   useSurfaceProfilerEntries,
   useSurfaceProfilerStats,
 } from './SurfaceProfilerContext';
-import { type Definition as SurfaceDefinition, create as createSurface, createWeb as createWebSurface } from './types';
+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;
@@ -25,6 +36,14 @@ export namespace Surface {
   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;

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

@@ -0,0 +1,126 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { type CapabilityManager } from '../../../core';
+import { isSurfaceAvailable } from './SurfaceComponent';
+import { type RoleToken, type SurfaceFilter, create, isSurfaceFilter, 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('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);
+  });
+});
+
+describe('isSurfaceFilter', () => {
+  test('distinguishes filter objects from predicate functions', ({ expect }) => {
+    const filter: SurfaceFilter<Record<string, any>> = { bindings: [{ role: 'r', guard: () => true }] };
+    expect(isSurfaceFilter(filter)).toBe(true);
+    expect(isSurfaceFilter(() => true)).toBe(false);
+    expect(isSurfaceFilter({})).toBe(false);
+    expect(isSurfaceFilter(null)).toBe(false);
+  });
+});
+
+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 def = create({ id: 'typed-single', filter, component: () => null });
+    expect(def.role).toBe('article');
+    expect(def.filter!({ subject: 'ok' }, 'article')).toBe(true);
+    expect(def.filter!({ subject: 'no' }, 'article')).toBe(false);
+  });
+
+  test('expands a multi-binding SurfaceFilter into a role array with role-scoped guards', ({ expect }) => {
+    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' },
+      ],
+    };
+    const def = create({ id: 'typed-multi', filter, component: () => null });
+    expect(def.role).toEqual(['article', 'section']);
+    // 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);
+    // 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: 'fallback' });
+    expect(def.position).toBe('fallback');
+  });
+});
+
+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');
+  });
+});
+
+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 capabilityManager = { getAll: () => [] } as unknown as CapabilityManager.CapabilityManager;
+
+  test('typed overload accepts data matching the token contract', () => {
+    // No error — data has all required fields.
+    isSurfaceAvailable(capabilityManager, {
+      type: sectionToken,
+      data: { attendableId: 'id', subject: 'x' },
+    });
+  });
+
+  test('typed overload rejects data missing required fields', () => {
+    // @ts-expect-error — `data` is missing `attendableId` required by the token.
+    isSurfaceAvailable(capabilityManager, { type: sectionToken, data: { subject: 'x' } });
+  });
+
+  test('typed overload rejects data with wrong field type', () => {
+    // @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' },
+    });
+  });
+});