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

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' },
+    });
+  });
+});

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

@@ -0,0 +1,269 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import type { FC, PropsWithChildren, ReactNode, RefCallback } from 'react';
+
+import type { MakeOptional, Position } from '@dxos/util';
+
+/**
+ * A typed role token. Carries a role string for runtime dispatch plus a phantom
+ * data type so consumers using `type={SomeToken}` and providers using
+ * `AppSurface.object(SomeToken, ...)` share a single type-level contract.
+ *
+ * Mint via {@link makeType}.
+ */
+export type RoleToken<TData> = {
+  readonly role: string;
+  /** Covariant phantom; never accessed at runtime. */
+  readonly _phantom?: TData;
+};
+
+/**
+ * One entry in a {@link SurfaceFilter} — a role plus the guard that validates
+ * the data shape when the Surface dispatcher is matching that role.
+ */
+export type SurfaceBinding = {
+  readonly role: string;
+  readonly guard: (data: unknown) => boolean;
+};
+
+/**
+ * Typed filter binding for {@link create}. Combines one or more `(role, guard)`
+ * pairs so a provider can register against multiple roles while keeping the
+ * role and its data shape in a single expression.
+ */
+export type SurfaceFilter<TData> = {
+  readonly bindings: ReadonlyArray<SurfaceBinding>;
+  /** Covariant phantom; never accessed at runtime. */
+  readonly _phantom?: TData;
+};
+
+/**
+ * Narrow data type carried by a role token.
+ */
+export type TokenData<T> = T extends RoleToken<infer D> ? D : never;
+
+/**
+ * Runtime guard for {@link SurfaceFilter}. Distinguishes new-style filter
+ * bindings from legacy predicate filters.
+ */
+export const isSurfaceFilter = (value: unknown): value is SurfaceFilter<any> =>
+  typeof value === 'object' && value !== null && Array.isArray((value as { bindings?: unknown }).bindings);
+
+/**
+ * Mints a typed role token. Identity is structural; all tokens with the same
+ * `role` string are interchangeable at runtime.
+ */
+export const makeType = <TData>(role: string): RoleToken<TData> => ({ role });
+
+/**
+ * Props that are passed to the Surface component.
+ *
+ * The role can be provided either as a string via `role` or as a typed
+ * {@link RoleToken} via `type`. The typed form narrows `data` to the token's
+ * declared shape.
+ */
+export type Props<T extends Record<string, any> = Record<string, unknown>> = {
+  /**
+   * If specified, the Surface will be wrapped in an error boundary.
+   * The fallback component will be rendered if an error occurs.
+   */
+  fallback?: FC<{ error: Error; data?: any }>;
+
+  /**
+   * If specified, the Surface will be wrapped in a suspense boundary.
+   * The placeholder component will be rendered while the surface component is loading.
+   */
+  placeholder?: ReactNode;
+} & MakeOptional<CoreProps<T>, 'id' | 'data' | 'role'> & {
+    /**
+     * Explicitly disallow `type` on the untyped Props overload — if the caller
+     * provides `type={AppSurface.X}`, TypeScript must route to the typed
+     * overload (where `data` is narrowed by the token). Without this, the
+     * catch-all index signature below would accept any `type` value and mask
+     * the typed overload entirely.
+     */
+    type?: undefined;
+  } /**
+   * Additional props to pass to the component.
+   * These props are not used by Surface itself but may be used by components which resolve the surface.
+   * Exclude known prop names to prevent overriding well-defined props.
+   */ & {
+    [K in keyof Record<string, any>]: K extends keyof CoreProps<T> | 'fallback' | 'placeholder' | 'type' ? never : any;
+  };
+
+/**
+ * Typed Surface consumer props — carries the role/data-shape contract via a
+ * {@link RoleToken}. Available as a typed overload of the Surface component so
+ * ad-hoc `type` fields on arbitrary spread props don't conflict with the
+ * untyped consumer form.
+ */
+export type TypedProps<TToken extends RoleToken<any>> = {
+  fallback?: FC<{ error: Error; data?: any }>;
+  placeholder?: ReactNode;
+  id?: string;
+  type: TToken;
+  data?: TokenData<TToken>;
+  limit?: number | undefined;
+} & {
+  /**
+   * Additional pass-through props. Known prop names are excluded so the
+   * catch-all doesn't widen `data` / `type` / etc. to `any` at the intersection.
+   */
+  [K in keyof Record<string, any>]: K extends 'fallback' | 'placeholder' | 'id' | 'type' | 'data' | 'limit'
+    ? never
+    : any;
+};
+
+/**
+ * NOTE: If `[key: string]: unknown` is included in shared types, when re-used other fields become unknown as well.
+ */
+export type CoreProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
+  /**
+   * ID for debugging.
+   */
+  id: string;
+
+  /**
+   * Role defines how the data should be rendered. For new code, prefer the
+   * typed overload of the Surface component which takes a {@link RoleToken}
+   * via the `type` prop instead — it enforces a role/data contract at compile
+   * time.
+   */
+  role: string;
+
+  /**
+   * The data to be rendered by the surface.
+   * NOTE: This must be a stable value.
+   */
+  data: T;
+
+  /**
+   * If more than one component is resolved, the limit determines how many are rendered.
+   */
+  limit?: number | undefined;
+}>;
+
+// TODO(burdon): Remove ref since relying on this would be error prone.
+export type ComponentProps<T extends Record<string, any> = Record<string, any>> = CoreProps<T> & {
+  ref?: RefCallback<HTMLElement>;
+} & Record<string, any>;
+
+/**
+ * React component used to render a surface once is has matched.
+ */
+export type ComponentFunction<T extends Record<string, any> = Record<string, any>> = (
+  props: ComponentProps<T>,
+) => ReactNode;
+
+/**
+ * Definition of when a React component surface should be rendered.
+ *
+ * The optional `filter` receives the consumer-supplied `role` as its second
+ * argument so a single definition can encode role-specific guards (used by the
+ * {@link SurfaceFilter}-based `create` overload).
+ */
+export type ReactDefinition<T extends Record<string, any> = any> = Readonly<{
+  kind: 'react';
+  id: string;
+  role: string | string[];
+  position?: Position;
+  component: ComponentFunction<T>;
+  filter?: (data: Record<string, unknown>, role?: string) => data is T;
+}>;
+
+/**
+ * Definition of when a Web Component surface should be rendered.
+ */
+export type WebComponentDefinition<T extends Record<string, any> = any> = Readonly<{
+  kind: 'web-component';
+  id: string;
+  role: string | string[];
+  position?: Position;
+  /**
+   * The tag name of the Web Component to render.
+   * The Web Component will receive the same props as React surfaces via properties/attributes.
+   */
+  tagName: string;
+  filter?: (data: Record<string, unknown>, role?: string) => data is T;
+}>;
+
+/**
+ * Definition of when a surface (React or Web Component) should be rendered.
+ */
+export type Definition<T extends Record<string, any> = any> = ReactDefinition<T> | WebComponentDefinition<T>;
+
+/**
+ * Typed React surface definition — role is derived from the filter's bindings.
+ */
+export type TypedReactDefinition<T extends Record<string, any> = any> = Readonly<{
+  id: string;
+  filter: SurfaceFilter<T>;
+  component: ComponentFunction<T>;
+  position?: Position;
+}>;
+
+/**
+ * Typed Web Component surface definition.
+ */
+export type TypedWebComponentDefinition<T extends Record<string, any> = any> = Readonly<{
+  id: string;
+  filter: SurfaceFilter<T>;
+  tagName: string;
+  position?: Position;
+}>;
+
+const expandBindings = <T extends Record<string, any>>(
+  filter: SurfaceFilter<T>,
+): { role: string | string[]; guard: (data: Record<string, unknown>, role?: string) => data is T } => {
+  const bindings = filter.bindings;
+  const roles = Array.from(new Set(bindings.map((binding) => binding.role)));
+  const guard = (data: Record<string, unknown>, role?: string): data is T => {
+    if (role != null) {
+      // Multiple bindings may share a role (e.g. via `oneOf` of same-role filters);
+      // the role matches if ANY of them passes.
+      return bindings.some((entry) => entry.role === role && entry.guard(data));
+    }
+    return bindings.some((entry) => entry.guard(data));
+  };
+  return { role: roles.length === 1 ? roles[0] : roles, guard };
+};
+
+/**
+ * Creates a React surface definition.
+ */
+export function create<T extends Record<string, any> = any>(definition: TypedReactDefinition<T>): ReactDefinition<T>;
+export function create<T extends Record<string, any> = any>(
+  definition: Omit<ReactDefinition<T>, 'kind'>,
+): ReactDefinition<T>;
+export function create<T extends Record<string, any> = any>(
+  definition: TypedReactDefinition<T> | Omit<ReactDefinition<T>, 'kind'>,
+): ReactDefinition<T> {
+  if (isSurfaceFilter(definition.filter)) {
+    const { id, filter, component, position } = definition as TypedReactDefinition<T>;
+    const { role, guard } = expandBindings(filter);
+    return { kind: 'react', id, role, position, component, filter: guard };
+  }
+  return { ...(definition as Omit<ReactDefinition<T>, 'kind'>), kind: 'react' };
+}
+
+/**
+ * Creates a Web Component surface definition.
+ */
+export function createWeb<T extends Record<string, any> = any>(
+  definition: TypedWebComponentDefinition<T>,
+): WebComponentDefinition<T>;
+export function createWeb<T extends Record<string, any> = any>(
+  definition: Omit<WebComponentDefinition<T>, 'kind'>,
+): WebComponentDefinition<T>;
+export function createWeb<T extends Record<string, any> = any>(
+  definition: TypedWebComponentDefinition<T> | Omit<WebComponentDefinition<T>, 'kind'>,
+): WebComponentDefinition<T> {
+  if (isSurfaceFilter(definition.filter)) {
+    const { id, filter, tagName, position } = definition as TypedWebComponentDefinition<T>;
+    const { role, guard } = expandBindings(filter);
+    return { kind: 'web-component', id, role, position, tagName, filter: guard };
+  }
+  return { ...(definition as Omit<WebComponentDefinition<T>, 'kind'>), kind: 'web-component' };
+}

package/src/ui/components/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './App';
+export * from './Placeholder';
+export * from './PluginManager';
+export * from './Surface';

package/src/ui/hooks/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './useApp';
+export * from './useCapabilities';
+export * from './useLoading';
+export * from './useSettingsState';
+export * from './useSurface';

package/src/ui/hooks/useApp.test.tsx

@@ -0,0 +1,159 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { assert, describe, it } from '@effect/vitest';
+import { render, waitFor } from '@testing-library/react';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { ActivationEvents, Capabilities } from '../../common';
+import { Capability, Plugin, PluginManager } from '../../core';
+import { useApp } from './useApp';
+
+const String = Capability.make<{ string: string }>('org.dxos.test.string');
+const testMeta = { id: 'org.dxos.plugin.test', name: 'Test' };
+
+const pluginLoader = (plugins: Plugin.Plugin[]) =>
+  Effect.fn(function* (id: string) {
+    const plugin = plugins.find((plugin) => plugin.meta.id === id);
+    if (!plugin) {
+      return yield* Effect.fail(new Error(`Plugin not found: ${id}`));
+    }
+    return plugin;
+  });
+
+const TestHost = ({ manager }: { manager: PluginManager.PluginManager }) => {
+  const App = useApp({ pluginManager: manager });
+  return <App />;
+};
+
+describe('useApp cleanup integration', () => {
+  it.effect('external manager is not shut down when useApp does not own it', () =>
+    Effect.gen(function* () {
+      const plugin = Plugin.define(testMeta).pipe(
+        Plugin.addModule({
+          id: 'Hello',
+          activatesOn: ActivationEvents.Startup,
+          activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+        }),
+        Plugin.make,
+      )();
+
+      const manager = PluginManager.make({
+        pluginLoader: pluginLoader([plugin]),
+        plugins: [plugin],
+      });
+
+      manager.capabilities.contribute({
+        interface: Capabilities.PluginManager,
+        implementation: manager,
+        module: 'org.dxos.app-framework.plugin-manager',
+      });
+      manager.capabilities.contribute({
+        interface: Capabilities.AtomRegistry,
+        implementation: manager.registry,
+        module: 'org.dxos.app-framework.atom-registry',
+      });
+
+      const view = yield* Effect.promise(() => Promise.resolve(render(<TestHost manager={manager} />)));
+      yield* Effect.promise(() =>
+        waitFor(() => {
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.PluginManager).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.AtomRegistry).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+          assert.isTrue(manager.getActive().length > 0);
+        }),
+      );
+
+      yield* Effect.promise(() => Promise.resolve(view.unmount()));
+      yield* Effect.promise(() =>
+        waitFor(() => {
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.PluginManager).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.AtomRegistry).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+          assert.isTrue(manager.getActive().length > 0);
+        }),
+      );
+
+      yield* manager.shutdown();
+
+      assert.strictEqual(manager.capabilities.getAll(Capabilities.PluginManager).length, 1);
+      assert.strictEqual(manager.capabilities.getAll(Capabilities.AtomRegistry).length, 1);
+      assert.strictEqual(manager.capabilities.getAll(String).length, 0);
+      assert.deepStrictEqual(manager.getActive(), []);
+    }),
+  );
+
+  it.effect('shutdown deactivates modules and clears bookkeeping', () =>
+    Effect.gen(function* () {
+      const plugin = Plugin.define(testMeta).pipe(
+        Plugin.addModule({
+          id: 'Hello',
+          activatesOn: ActivationEvents.Startup,
+          activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+        }),
+        Plugin.make,
+      )();
+
+      const manager = PluginManager.make({
+        pluginLoader: pluginLoader([plugin]),
+        plugins: [plugin],
+      });
+
+      manager.capabilities.contribute({
+        interface: Capabilities.PluginManager,
+        implementation: manager,
+        module: 'org.dxos.app-framework.plugin-manager',
+      });
+      manager.capabilities.contribute({
+        interface: Capabilities.AtomRegistry,
+        implementation: manager.registry,
+        module: 'org.dxos.app-framework.atom-registry',
+      });
+      yield* manager.activate(ActivationEvents.Startup);
+
+      assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+      assert.isTrue(manager.getActive().length > 0);
+
+      yield* manager.shutdown();
+
+      assert.strictEqual(manager.capabilities.getAll(String).length, 0);
+      assert.deepStrictEqual(manager.getActive(), []);
+      assert.deepStrictEqual(manager.getEventsFired(), []);
+    }),
+  );
+
+  it.effect('shutdown is idempotent when called multiple times', () =>
+    Effect.gen(function* () {
+      const plugin = Plugin.define(testMeta).pipe(
+        Plugin.addModule({
+          id: 'Hello',
+          activatesOn: ActivationEvents.Startup,
+          activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+        }),
+        Plugin.make,
+      )();
+
+      const manager = PluginManager.make({
+        pluginLoader: pluginLoader([plugin]),
+        plugins: [plugin],
+      });
+
+      manager.capabilities.contribute({
+        interface: Capabilities.PluginManager,
+        implementation: manager,
+        module: 'org.dxos.app-framework.plugin-manager',
+      });
+      yield* manager.activate(ActivationEvents.Startup);
+
+      yield* manager.shutdown();
+      assert.deepStrictEqual(manager.getActive(), []);
+
+      // Second shutdown should succeed without error.
+      const result = yield* manager.shutdown();
+      assert.isTrue(result);
+      assert.deepStrictEqual(manager.getActive(), []);
+    }),
+  );
+});