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

package/src/core/url-loader.ts

@@ -59,7 +59,7 @@ export type PreloadOptions = Options & {
  *
  * `url` is the URL of the plugin manifest (`plugin.json`), not the entry module.
  */
-export type RemotePluginEntry = {
+export type RemotePluginView = {
   id: string;
   url: string;
   /** Installed version string, e.g. `v1.0.0`. Populated after install from a community catalog entry. */
@@ -71,22 +71,26 @@ const defaultStorage = (): Storage => ({
   set: (key, value) => localStorage.setItem(key, value),
 });
 
-const getPersistedRemotePlugins = (storage: Storage, key: string): RemotePluginEntry[] => {
+const getPersistedRemotePlugins = (storage: Storage, key: string): RemotePluginView[] => {
   try {
     const parsed: unknown = JSON.parse(storage.get(key) ?? '[]');
     if (!Array.isArray(parsed)) {
       return [];
     }
     return parsed.filter(
-      (entry): entry is RemotePluginEntry =>
-        typeof entry === 'object' && entry !== null && typeof entry.id === 'string' && typeof entry.url === 'string',
+      (entry): entry is RemotePluginView =>
+        typeof entry === 'object' &&
+        entry !== null &&
+        typeof entry.id === 'string' &&
+        typeof entry.url === 'string' &&
+        (entry.version === undefined || typeof entry.version === 'string'),
     );
   } catch {
     return [];
   }
 };
 
-const persistRemotePlugin = (storage: Storage, key: string, entry: RemotePluginEntry): void => {
+const persistRemotePlugin = (storage: Storage, key: string, entry: RemotePluginView): void => {
   try {
     const entries = getPersistedRemotePlugins(storage, key).filter((existing) => existing.id !== entry.id);
     entries.push(entry);
@@ -132,7 +136,7 @@ export const isLocalUrl = (locator: string): boolean => {
  * Useful for UI code that needs to know which loaded plugins were installed from a URL
  * (e.g. to surface a tag on remote or localhost-hosted plugins).
  */
-export const getRemoteEntries = (options: Options = {}): readonly RemotePluginEntry[] => {
+export const getRemoteEntries = (options: Options = {}): readonly RemotePluginView[] => {
   const storage = options.storage ?? defaultStorage();
   const key = options.key ?? DEFAULT_KEY;
   return getPersistedRemotePlugins(storage, key);
@@ -196,14 +200,14 @@ const loadStylesheets = (
     }
     const cssUrls = manifest.assetUrls.filter((url) => url.endsWith('.css'));
     for (const url of cssUrls) {
-      const resolved = yield* cache.resolve(manifest.id, url);
-      if (document.querySelector(`link[data-dxos-plugin-id="${manifest.id}"][href="${resolved}"]`)) {
+      const resolved = yield* cache.resolve(manifest.key, url);
+      if (document.querySelector(`link[data-dxos-plugin-id="${manifest.key}"][href="${resolved}"]`)) {
         continue;
       }
       const link = document.createElement('link');
       link.rel = 'stylesheet';
       link.href = resolved;
-      link.dataset.dxosPluginId = manifest.id;
+      link.dataset.dxosPluginId = manifest.key;
       document.head.appendChild(link);
     }
   });
@@ -233,30 +237,30 @@ const loadFromManifest = (
       // plugin's host is offline, dropping the plugin from the runtime.
       const cachedUrls =
         manifest.assetUrls.indexOf(manifestUrl) === -1 ? [manifestUrl, ...manifest.assetUrls] : manifest.assetUrls;
-      yield* cache.cache(manifest.id, cachedUrls).pipe(wrapCacheError);
+      yield* cache.cache(manifest.key, cachedUrls).pipe(wrapCacheError);
     }
     const entryUrl = manifest.dev
       ? manifest.entryUrl
-      : yield* cache.resolve(manifest.id, manifest.entryUrl).pipe(wrapCacheError);
+      : yield* cache.resolve(manifest.key, manifest.entryUrl).pipe(wrapCacheError);
     const mod = yield* Effect.tryPromise({
       try: () => import(/* @vite-ignore */ entryUrl),
       catch: (cause) =>
         new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'import-failed' }, cause }),
     });
     const plugin = normalizePluginExport(mod);
-    if (!plugin.meta.id || !plugin.meta.name) {
+    if (!plugin.meta.profile.key || !plugin.meta.profile.name) {
       return yield* Effect.fail(
         new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'meta-missing' } }),
       );
     }
-    if (plugin.meta.id !== manifest.id) {
+    if (plugin.meta.profile.key !== manifest.key) {
       return yield* Effect.fail(
         new RemotePluginLoadError({
           context: {
             locator: manifestUrl,
             reason: 'meta-mismatch',
-            metaId: plugin.meta.id,
-            manifestId: manifest.id,
+            metaId: plugin.meta.profile.key,
+            manifestId: manifest.key,
           },
         }),
       );
@@ -337,7 +341,7 @@ export const make = (builtinPlugins: Plugin.Plugin[], options: Options = {}) =>
 
   return (locator: string): Effect.Effect<{ plugin: Plugin.Plugin; dev?: boolean }, RemotePluginLoadError> =>
     Effect.gen(function* () {
-      const builtin = builtinPlugins.find((plugin) => plugin.meta.id === locator);
+      const builtin = builtinPlugins.find((plugin) => plugin.meta.profile.key === locator);
       if (builtin) {
         return { plugin: builtin };
       }
@@ -351,13 +355,13 @@ export const make = (builtinPlugins: Plugin.Plugin[], options: Options = {}) =>
       // overlap (dev plugin takes the id slot for the session, original is
       // restored on uninstall or page reload).
       if (!manifest.dev) {
-        const duplicate = builtinPlugins.find((existing) => existing.meta.id === plugin.meta.id);
+        const duplicate = builtinPlugins.find((existing) => existing.meta.profile.key === plugin.meta.profile.key);
         if (duplicate) {
           return yield* Effect.fail(
-            new RemotePluginLoadError({ context: { locator, reason: 'duplicate-id', id: plugin.meta.id } }),
+            new RemotePluginLoadError({ context: { locator, reason: 'duplicate-id', id: plugin.meta.profile.key } }),
           );
         }
-        persistRemotePlugin(storage, key, { id: plugin.meta.id, url: locator });
+        persistRemotePlugin(storage, key, { id: plugin.meta.profile.key, url: locator });
       }
       return { plugin, dev: manifest.dev };
     });

package/src/index.ts

@@ -3,6 +3,7 @@
 //
 
 export * from './common';
+export * from './config';
 export * from './context';
 export * from './core';
 export * from './plugin-process-manager';

package/src/testing/harness.ts

@@ -17,7 +17,7 @@ import { ActivationEvent, type Capability, type CapabilityManager, type Plugin,
 
 export type TestAppOptions = {
   /**
-   * Plugins to register. Plugins whose `meta.tags` includes `'system'` are treated as core
+   * Plugins to register. Plugins whose `meta.profile.tags` includes `'system'` are treated as core
    * (force-enabled). For test convenience, plugins without a `'system'` tag are enabled by
    * default unless `enabled` is provided.
    */
@@ -97,7 +97,9 @@ const DEFAULT_TIMEOUT_MS = 5_000;
 export const createTestApp = async (opts: TestAppOptions): Promise<TestHarness> => {
   const {
     plugins,
-    enabled = plugins.filter(({ meta }) => !meta.tags?.includes('system')).map((plugin) => plugin.meta.id),
+    enabled = plugins
+      .filter(({ meta }) => !meta.profile.tags?.includes('system'))
+      .map((plugin) => plugin.meta.profile.key),
     setupEvents = [],
     autoStart = true,
     registerFrameworkCapabilities = true,
@@ -105,7 +107,7 @@ export const createTestApp = async (opts: TestAppOptions): Promise<TestHarness>
 
   const pluginLoader = (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/testing/react.test.tsx

@@ -16,6 +16,8 @@ import { render, renderSurface } from './react';
 
 const testMeta = Plugin.makeMeta({ key: DXN.make('org.dxos.plugin.test.reactHarness'), name: 'ReactHarnessTest' });
 
+const GreetingRole = Surface.makeType<{ message: string }>('org.dxos.test.role.greeting');
+
 const TestPlugin = Plugin.define(testMeta).pipe(
   Plugin.addModule({
     id: 'surfaces',
@@ -25,7 +27,7 @@ const TestPlugin = Plugin.define(testMeta).pipe(
         Capability.contributes(Capabilities.ReactSurface, [
           Surface.create<{ message: string }>({
             id: 'greeting',
-            role: 'greeting',
+            filter: Surface.makeFilter(GreetingRole),
             component: ({ data }) => <span data-testid='greeting'>hello {data.message}</span>,
           }),
         ]),
@@ -43,7 +45,7 @@ describe('testing/react', () => {
 
   test('renderSurface mounts a surface registered by a plugin', async ({ expect }) => {
     await using harness = await createTestApp({ plugins: [TestPlugin()] });
-    const view = renderSurface(harness, { role: 'greeting', data: { message: 'plugins' } });
+    const view = renderSurface(harness, { type: GreetingRole, data: { message: 'plugins' } });
     const node = await view.findByTestId('greeting');
     expect(node.textContent).toBe('hello plugins');
   });

package/src/testing/react.tsx

@@ -3,7 +3,7 @@
 //
 
 import { RegistryContext } from '@effect-atom/atom-react';
-import { render as rtlRender, type RenderOptions, type RenderResult } from '@testing-library/react';
+import { type RenderOptions, type RenderResult, render as rtlRender } from '@testing-library/react';
 import React, { type FC, Fragment, type PropsWithChildren, type ReactNode } from 'react';
 
 import { ContextProtocolProvider } from '@dxos/web-context-react';
@@ -13,6 +13,7 @@ import { PluginManagerContext } from '../context';
 import { topologicalSort } from '../helpers';
 import { PluginManagerProvider } from '../ui/components/PluginManager/PluginManagerProvider';
 import { SurfaceComponent } from '../ui/components/Surface/SurfaceComponent';
+import { type RoleToken } from '../ui/components/Surface/types';
 import { type TestHarness } from './harness';
 
 export type HarnessRenderOptions = Omit<RenderOptions, 'wrapper'> & {
@@ -34,26 +35,26 @@ export const render = (harness: TestHarness, ui: ReactNode, options?: HarnessRen
   return rtlRender(<>{ui}</>, { ...rest, wrapper: Wrapper });
 };
 
-export type RenderSurfaceProps = {
-  role: string;
-  data?: unknown;
+export type RenderSurfaceProps<TToken extends RoleToken<any>> = {
+  type: TToken;
+  data?: TToken extends RoleToken<infer D> ? D : never;
   limit?: number;
   fallback?: FC<{ error: Error; data?: any }>;
   placeholder?: ReactNode;
 };
 
 /**
- * Renders a `Surface` with the given role/data inside the harness provider tree.
+ * Renders a `Surface` with the given role token/data inside the harness provider tree.
  */
-export const renderSurface = (
+export const renderSurface = <TToken extends RoleToken<any>>(
   harness: TestHarness,
-  props: RenderSurfaceProps,
+  props: RenderSurfaceProps<TToken>,
   options?: HarnessRenderOptions,
 ): RenderResult => {
-  const { role, data, limit, fallback, placeholder } = props;
+  const { type, data, limit, fallback, placeholder } = props;
   return render(
     harness,
-    <SurfaceComponent role={role} data={data as any} limit={limit} fallback={fallback} placeholder={placeholder} />,
+    <SurfaceComponent type={type} data={data as any} limit={limit} fallback={fallback} placeholder={placeholder} />,
     options,
   );
 };

package/src/testing/service.ts

@@ -22,7 +22,7 @@ export const fromPlugins = (plugins: Plugin.Plugin[]) =>
 
       const pluginLoader = (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 };
         });
@@ -30,7 +30,7 @@ export const fromPlugins = (plugins: Plugin.Plugin[]) =>
       const manager = PluginManager.make({
         pluginLoader,
         plugins,
-        enabled: plugins.map((plugin) => plugin.meta.id),
+        enabled: plugins.map((plugin) => plugin.meta.profile.key),
       });
 
       manager.capabilities.contribute({

package/src/testing/withPluginManager.stories.tsx

@@ -12,12 +12,14 @@ import { Capability } from '../core';
 import { Surface } from '../ui';
 import { withPluginManager } from './withPluginManager';
 
+const MainRole = Surface.makeType<Record<string, never>>('org.dxos.test.role.main');
+
 const DefaultStory = () => {
   console.log('Render');
   return (
     <div>
       <div>Hello</div>
-      <Surface.Surface role='main' />
+      <Surface.Surface type={MainRole} />
     </div>
   );
 };
@@ -33,7 +35,7 @@ const meta = {
           Capabilities.ReactSurface,
           Surface.create({
             id: 'test',
-            role: 'main',
+            filter: Surface.makeFilter(MainRole),
             component: ({ role }) => <span>{JSON.stringify({ role })}</span>,
           }),
         ),

package/src/testing/withPluginManager.tsx

@@ -26,7 +26,9 @@ export const setupPluginManager = ({
 }: UseAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
   // Auto-enable every non-system plugin so stories don't have to spell out
   // enablement. System-tagged plugins are force-enabled by the manager.
-  const enabled = plugins.filter(({ meta }) => !meta.tags?.includes('system')).map(({ meta }) => meta.id);
+  const enabled = plugins
+    .filter(({ meta }) => !meta.profile.tags?.includes('system'))
+    .map(({ meta }) => meta.profile.key);
   const pluginManager = PluginManager.make({
     pluginLoader: () => raise(new Error('Not implemented')),
     plugins: [StoryPlugin, ...plugins],

package/src/ui/components/App/App.stories.tsx

@@ -50,9 +50,9 @@ const TestPlugin = Plugin.define<{ error?: boolean }>(
   Plugin.make,
 );
 
-type DefaultStoryProps = { plugins?: Plugin.Plugin[] };
+type StoryArgs = { plugins?: Plugin.Plugin[] };
 
-const DefaultStory = ({ plugins }: DefaultStoryProps) => {
+const DefaultStory = ({ plugins }: StoryArgs) => {
   const App = useApp({ plugins });
 
   return <App />;

package/src/ui/components/PluginManager/PluginManagerProvider.ts

@@ -16,6 +16,13 @@ const PluginManagerContext = createContext<PluginManager.PluginManager | undefin
 export const usePluginManager = (): PluginManager.PluginManager =>
   useContext(PluginManagerContext) ?? raise(new Error('Missing PluginManagerContext'));
 
+/**
+ * Get the plugin manager if present, or `undefined` when rendered outside a {@link PluginManagerProvider}
+ * (e.g. a standalone component story). Lets components treat plugin capabilities as a progressive
+ * enhancement rather than a hard requirement.
+ */
+export const useOptionalPluginManager = (): PluginManager.PluginManager | undefined => useContext(PluginManagerContext);
+
 /**
  * Context provider for a plugin manager.
  */

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

@@ -3,10 +3,11 @@
 //
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { forwardRef, useCallback, useEffect, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
 
 import { random } from '@dxos/random';
-import { List, ListItem, Panel, Toolbar } from '@dxos/react-ui';
+import { Panel, Toolbar } from '@dxos/react-ui';
+import { Listbox } from '@dxos/react-ui-list';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { type ColorStyles, getHashStyles, mx } from '@dxos/ui-theme';
 
@@ -14,23 +15,22 @@ import { Capabilities } from '../../../common';
 import { withPluginManager } from '../../../testing';
 import { usePluginManager } from '../PluginManager';
 import { SurfaceComponent, useSurfaces } from './SurfaceComponent';
-import { create } from './types';
+import { create, makeFilter, makeType } from './types';
+
+const ItemRole = makeType<{ id: string }>('org.dxos.test.role.item');
 
 type TestComponentProps = {
   id: string;
   styles: ColorStyles;
 };
 
-const TestComponent = forwardRef<HTMLDivElement, TestComponentProps>(({ styles, id }, forwardedRef) => {
+const TestComponent = ({ styles, id }: TestComponentProps) => {
   return (
-    <div
-      className={mx('flex justify-center items-center border rounded-sm', styles.surface, styles.border)}
-      ref={forwardedRef}
-    >
+    <div className={mx('flex justify-center items-center border rounded-sm', styles.surface, styles.border)}>
       <span className={mx('dx-tag font-mono text-lg', styles.text)}>{id}</span>
     </div>
   );
-});
+};
 
 const DefaultStory = () => {
   const manager = usePluginManager();
@@ -46,9 +46,8 @@ const DefaultStory = () => {
       interface: Capabilities.ReactSurface,
       implementation: create({
         id,
-        role: 'item',
-        filter: (data): data is any => (data as any)?.id === id,
-        component: ({ ref }) => <TestComponent id={id} styles={styles} ref={ref} />,
+        filter: makeFilter(ItemRole, (data) => data.id === id),
+        component: () => <TestComponent id={id} styles={styles} />,
       }),
     });
 
@@ -65,8 +64,7 @@ const DefaultStory = () => {
       interface: Capabilities.ReactSurface,
       implementation: create({
         id: 'error',
-        role: 'item',
-        filter: (data): data is any => (data as any)?.id === 'error',
+        filter: makeFilter(ItemRole, (data) => data.id === 'error'),
         component: () => {
           const [count, setCount] = useState(3);
           useEffect(() => {
@@ -113,15 +111,17 @@ const DefaultStory = () => {
         </Toolbar.Root>
       </Panel.Toolbar>
       <Panel.Content className='grid grid-cols-2 h-full gap-4 overflow-hidden'>
-        <SurfaceComponent role='item' data={selected ? { id: selected } : undefined} limit={1} ref={ref} />
+        <SurfaceComponent type={ItemRole} data={selected ? { id: selected } : undefined} limit={1} ref={ref} />
         <div className='overflow-y-auto h-full'>
-          <List>
-            {surfaces.map((surface) => (
-              <ListItem.Root key={surface.id} id={surface.id}>
-                <ListItem.Heading classNames='flex items-center'>{surface.id}</ListItem.Heading>
-              </ListItem.Root>
-            ))}
-          </List>
+          <Listbox.Root>
+            <Listbox.Content aria-label='Surfaces'>
+              {surfaces.map((surface) => (
+                <Listbox.Item key={surface.id} id={surface.id}>
+                  <Listbox.ItemLabel classNames='flex items-center'>{surface.id}</Listbox.ItemLabel>
+                </Listbox.Item>
+              ))}
+            </Listbox.Content>
+          </Listbox.Root>
         </div>
       </Panel.Content>
     </Panel.Root>