@dxos/app-framework 0.9.0 → 0.9.1-main.c7dcc2e112

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';
@@ -22,6 +24,7 @@ import {
   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

@@ -6,25 +6,35 @@ import { describe, test } from 'vitest';
 
 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,50 +43,39 @@ 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 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: 'last' });
     expect(def.position).toBe('last');
   });
@@ -84,10 +83,9 @@ describe('create', () => {
 
 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 +93,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 +113,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' },
-    });
-  });
 });

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

@@ -2,16 +2,20 @@
 // Copyright 2023 DXOS.org
 //
 
-import type { FC, PropsWithChildren, ReactNode, RefCallback } from 'react';
+import type { FC, PropsWithChildren, ReactNode, Ref } from 'react';
 
+import type { DXN } from '@dxos/keys';
+import { log } from '@dxos/log';
 import type { MakeOptional, Position } from '@dxos/util';
 
 /**
- * A typed role token. Carries a role string for runtime dispatch plus a phantom
+ * A typed role token. Carries a role NSID 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}.
+ * Mint via {@link makeType}. The `role` field holds the bare NSID (e.g.
+ * `org.dxos.role.article`) — the dispatch key, `data-role` attribute value,
+ * and what `.role` comparisons inside matched components see.
  */
 export type RoleToken<TData> = {
   readonly role: string;
@@ -20,8 +24,8 @@ export type RoleToken<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.
+ * One entry in a {@link SurfaceFilter} — a role NSID plus the guard that
+ * validates the data shape when the Surface dispatcher is matching that role.
  */
 export type SurfaceBinding = {
   readonly role: string;
@@ -52,17 +56,61 @@ 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.
+ * Mints a typed role token. The NSID is validated at compile time via
+ * {@link DXN.Name}: the final segment must be camelCase (no hyphens).
+ * Dynamic NSIDs (template-literal / runtime strings) are validated at runtime.
+ *
+ * Identity is structural; all tokens with the same `role` string are
+ * interchangeable at runtime.
  */
-export const makeType = <TData>(role: string): RoleToken<TData> => ({ role });
+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,
+  ): RoleToken<TData>;
+} = <TData>(nsid: string): RoleToken<TData> => {
+  // Runtime guard for dynamic NSIDs that bypass the compile-time DXN.Name<T> check.
+  if (
+    typeof nsid !== 'string' ||
+    !/^[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(\.[a-zA-Z][a-zA-Z0-9]{0,62})$/.test(
+      nsid,
+    )
+  ) {
+    throw new Error(
+      `Invalid role NSID: "${nsid}". Must be a dotted name with a camelCase final segment (no hyphens in the last segment).`,
+    );
+  }
+  return { role: nsid };
+};
 
 /**
- * Props that are passed to the Surface component.
+ * Creates a {@link SurfaceFilter} from a role token and an optional guard.
+ *
+ * When `guard` is omitted the filter matches any data at the token's role
+ * (role-only dispatch). Pass a guard to add runtime data-shape validation on
+ * top of the role match.
  *
- * 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.
+ * This is the framework-level primitive; `@dxos/app-toolkit` builds richer
+ * domain-aware helpers (ECHO schema checks, literal matching, etc.) on top of it.
+ */
+export const makeFilter = <TData>(token: RoleToken<TData>, guard?: (data: TData) => boolean): SurfaceFilter<TData> => {
+  const boundGuard =
+    guard == null
+      ? () => true
+      : (data: unknown): boolean => {
+          try {
+            return guard(data as TData);
+          } catch (err) {
+            log.catch(err);
+            return false;
+          }
+        };
+  return { bindings: [{ role: token.role, guard: boundGuard }] };
+};
+
+/**
+ * Typed Surface consumer props — carries the role/data-shape contract via a
+ * {@link RoleToken}. The `type` prop is required; the string `role` prop has
+ * been removed from the consumer-facing API.
  */
 export type Props<T extends Record<string, any> = Record<string, unknown>> = {
   /**
@@ -76,22 +124,7 @@ export type Props<T extends Record<string, any> = Record<string, unknown>> = {
    * 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;
-  };
+} & MakeOptional<CoreProps<T>, 'id' | 'data'>;
 
 /**
  * Typed Surface consumer props — carries the role/data-shape contract via a
@@ -118,6 +151,8 @@ export type TypedProps<TToken extends RoleToken<any>> = {
 
 /**
  * NOTE: If `[key: string]: unknown` is included in shared types, when re-used other fields become unknown as well.
+ * The `type` prop is the only way to set the role; it is required here and
+ * optional in {@link Props} via MakeOptional.
  */
 export type CoreProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
   /**
@@ -126,12 +161,9 @@ export type CoreProps<T extends Record<string, any> = Record<string, unknown>> =
   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.
+   * The role token defining how the data should be rendered.
    */
-  role: string;
+  type: RoleToken<T>;
 
   /**
    * The data to be rendered by the surface.
@@ -146,9 +178,20 @@ export type CoreProps<T extends Record<string, any> = Record<string, unknown>> =
 }>;
 
 // 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>;
+export type ComponentProps<T extends Record<string, any> = Record<string, any>> = {
+  /**
+   * The resolved role NSID string (e.g. `org.dxos.role.article`). Present on
+   * matched components only — multi-role containers can branch on this value
+   * by comparing against a token's `.role` (e.g. `role === AppSurface.Section.role`).
+   */
+  role: string;
+  ref?: Ref<HTMLElement>;
+} & PropsWithChildren<{
+  id: string;
+  data: T;
+  limit?: number | undefined;
+}> &
+  Record<string, any>;
 
 /**
  * React component used to render a surface once is has matched.
@@ -163,6 +206,9 @@ export type ComponentFunction<T extends Record<string, any> = Record<string, any
  * 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).
+ *
+ * @internal The `role` field is populated by the framework from the filter
+ *   bindings and is not authored directly.
  */
 export type ReactDefinition<T extends Record<string, any> = any> = Readonly<{
   kind: 'react';
@@ -175,6 +221,9 @@ export type ReactDefinition<T extends Record<string, any> = any> = Readonly<{
 
 /**
  * Definition of when a Web Component surface should be rendered.
+ *
+ * @internal The `role` field is populated by the framework from the filter
+ *   bindings and is not authored directly.
  */
 export type WebComponentDefinition<T extends Record<string, any> = any> = Readonly<{
   kind: 'web-component';
@@ -250,41 +299,27 @@ const validateLocalId = (id: string): void => {
 };
 
 /**
- * Creates a React surface definition.
+ * Creates a React surface definition from a typed filter.
  */
 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> {
+export function create<T extends Record<string, any> = any>(definition: TypedReactDefinition<T>): ReactDefinition<T> {
   validateLocalId(definition.id);
-  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' };
+  const { id, filter, component, position } = definition;
+  const { role, guard } = expandBindings(filter);
+  return { kind: 'react', id, role, position, component, filter: guard };
 }
 
 /**
- * Creates a Web Component surface definition.
+ * Creates a Web Component surface definition from a typed filter.
  */
 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'>,
+  definition: TypedWebComponentDefinition<T>,
 ): WebComponentDefinition<T> {
   validateLocalId(definition.id);
-  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' };
+  const { id, filter, tagName, position } = definition;
+  const { role, guard } = expandBindings(filter);
+  return { kind: 'web-component', id, role, position, tagName, filter: guard };
 }

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

@@ -18,7 +18,7 @@ const testMeta = Plugin.makeMeta({ key: DXN.make('org.dxos.plugin.test'), name:
 
 const pluginLoader = (plugins: Plugin.Plugin[]) =>
   Effect.fn(function* (id: string) {
-    const plugin = plugins.find((plugin) => plugin.meta.id === id);
+    const plugin = plugins.find((plugin) => plugin.meta.profile.key === id);
     if (!plugin) {
       return yield* Effect.fail(new Error(`Plugin not found: ${id}`));
     }

package/src/ui/hooks/useApp.tsx

@@ -94,7 +94,7 @@ export type UseAppOptions = {
  * );
  *
  * @param params.pluginLoader A function which loads new plugins.
- * @param params.plugins All plugins available to the application. Plugins whose `meta.tags` includes `'system'` are treated as core (force-enabled, not user-toggleable).
+ * @param params.plugins All plugins available to the application. Plugins whose `meta.profile.tags` includes `'system'` are treated as core (force-enabled, not user-toggleable).
  * @param params.defaults Default plugins are enabled by default but can be disabled by the user.
  * @param params.cacheEnabled Whether to cache enabled plugins in localStorage.
  * @param params.safeMode Whether to enable safe mode, which disables optional plugins.
@@ -123,7 +123,7 @@ export const useApp = ({
       pluginLoaderProp ??
       ((id: string) =>
         Effect.sync(() => {
-          const plugin = plugins.find((plugin) => plugin.meta.id === id);
+          const plugin = plugins.find((plugin) => plugin.meta.profile.key === id);
           invariant(plugin, `Plugin not found: ${id}`);
           return { plugin };
         })),

package/src/ui/hooks/useCapabilities.ts

@@ -2,14 +2,18 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Atom, useAtomValue } from '@effect-atom/atom-react';
+import { Atom } from '@effect-atom/atom';
+import { useAtomValue } from '@effect-atom/atom-react';
 import { useCallback } from 'react';
 
 import { invariant } from '@dxos/invariant';
 
 import { Capabilities } from '../../common';
 import { type Capability } from '../../core';
-import { usePluginManager } from '../components';
+import { useOptionalPluginManager, usePluginManager } from '../components';
+
+/** Stable empty result for capability lookups made outside a plugin manager. */
+const emptyCapabilities = Atom.make(() => [] as const);
 
 /**
  * Hook to request capabilities from the plugin context.
@@ -32,6 +36,24 @@ export const useCapability = <T>(interfaceDef: Capability.InterfaceDef<T>) => {
   return capabilities[0];
 };
 
+/**
+ * Hook to request capabilities without requiring a plugin manager.
+ * @returns An array of capabilities, or an empty array when rendered outside a {@link PluginManagerProvider}.
+ */
+export const useOptionalCapabilities = <T>(interfaceDef: Capability.InterfaceDef<T>): readonly T[] => {
+  const manager = useOptionalPluginManager();
+  return useAtomValue(
+    manager ? manager.capabilities.atom(interfaceDef) : (emptyCapabilities as Atom.Atom<readonly T[]>),
+  );
+};
+
+/**
+ * Hook to request a single capability without requiring a plugin manager.
+ * @returns The first matching capability, or `undefined` when none is registered (or there is no plugin manager).
+ */
+export const useOptionalCapability = <T>(interfaceDef: Capability.InterfaceDef<T>): T | undefined =>
+  useOptionalCapabilities(interfaceDef)[0];
+
 /**
  * Hook to get the current value of an atom capability.
  * Automatically subscribes to changes.