@dxos/app-framework 0.8.4-main.84f28bd → 0.8.4-main.8baae0fced

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

@@ -0,0 +1,106 @@
+//
+// 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
+            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';

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: 'last' });
+    expect(def.position).toBe('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');
+  });
+});
+
+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' },
+    });
+  });
+});