@dxos/app-framework 0.7.5-main.499c70c → 0.7.5-main.5ae2ba8

package/src/plugin-settings/intent-resolver.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { pipe } from 'effect';
+
+import { SETTINGS_ID, SETTINGS_KEY, SettingsAction } from './actions';
+import { Capabilities, LayoutAction } from '../common';
+import { contributes } from '../core';
+import { createResolver, createIntent, chain } from '../plugin-intent';
+
+export default () =>
+  contributes(
+    Capabilities.IntentResolver,
+    createResolver({
+      intent: SettingsAction.Open,
+      resolve: ({ plugin }) => {
+        const openSettings = createIntent(LayoutAction.SwitchWorkspace, { part: 'workspace', subject: SETTINGS_ID });
+        return {
+          intents: [
+            plugin
+              ? pipe(
+                  openSettings,
+                  chain(LayoutAction.Open, {
+                    part: 'main',
+                    subject: [`${SETTINGS_KEY}:${plugin.replaceAll('/', ':')}`],
+                  }),
+                )
+              : openSettings,
+          ],
+        };
+      },
+    }),
+  );

package/src/plugin-settings/store.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { effect } from '@preact/signals-core';
+
+import { RootSettingsStore } from '@dxos/local-storage';
+
+import { Capabilities } from '../common';
+import { contributes, type PluginsContext } from '../core';
+
+export default (context: PluginsContext) => {
+  const settingsStore = new RootSettingsStore();
+
+  let previous: Capabilities.Settings[] = [];
+  const unsubscribe = effect(() => {
+    const allSettings = context.requestCapabilities(Capabilities.Settings);
+    const added = allSettings.filter((setting) => !previous.includes(setting));
+    const removed = previous.filter((setting) => !allSettings.includes(setting));
+    previous = allSettings;
+    added.forEach((setting) => {
+      settingsStore.createStore(setting as any);
+    });
+    removed.forEach((setting) => {
+      settingsStore.removeStore(setting.prefix);
+    });
+  });
+
+  return contributes(Capabilities.SettingsStore, settingsStore, () => unsubscribe());
+};

package/src/plugin-settings/translations.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { SETTINGS_PLUGIN } from './actions';
+
+export default [
+  {
+    'en-US': {
+      [SETTINGS_PLUGIN]: {
+        'open settings label': 'Open settings',
+        'app settings label': 'Settings',
+        'custom plugins label': 'Plugins',
+      },
+    },
+  },
+];

package/src/{plugins/plugin-intent → react}/IntentContext.tsx

@@ -7,7 +7,9 @@ import { type Context, createContext, useContext, type Provider, useEffect } fro
 import { raise } from '@dxos/debug';
 import { pick } from '@dxos/util';
 
-import { type AnyIntentResolver, type IntentContext } from './intent-dispatcher';
+import { usePluginManager } from './PluginManagerProvider';
+import { Capabilities } from '../common';
+import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
 
 const IntentContext: Context<IntentContext | undefined> = createContext<IntentContext | undefined>(undefined);
 
@@ -16,11 +18,17 @@ export const useIntentDispatcher = (): Pick<IntentContext, 'dispatch' | 'dispatc
   return pick(context, ['dispatch', 'dispatchPromise']);
 };
 
-export const useIntentResolver = (pluginId: string, resolver: AnyIntentResolver) => {
-  const { registerResolver } = useContext(IntentContext) ?? raise(new Error('IntentContext not found'));
+export const useIntentResolver = (module: string, resolver: AnyIntentResolver) => {
+  const manager = usePluginManager();
   useEffect(() => {
-    return registerResolver(pluginId, resolver);
-  }, [pluginId, resolver]);
+    manager.context.contributeCapability({
+      module,
+      interface: Capabilities.IntentResolver,
+      implementation: resolver,
+    });
+
+    return () => manager.context.removeCapability(Capabilities.IntentResolver, resolver);
+  }, [module, resolver]);
 };
 
 export const IntentProvider: Provider<IntentContext | undefined> = IntentContext.Provider;

package/src/react/PluginManagerProvider.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { createContext, useContext } from 'react';
+
+import { raise } from '@dxos/debug';
+
+import { type PluginManager } from '../core';
+
+const PluginManagerContext = createContext<PluginManager | undefined>(undefined);
+
+/**
+ * Get the plugin manager.
+ */
+export const usePluginManager = (): PluginManager =>
+  useContext(PluginManagerContext) ?? raise(new Error('Missing PluginManagerContext'));
+
+/**
+ * Context provider for a plugin manager.
+ */
+export const PluginManagerProvider = PluginManagerContext.Provider;

package/src/react/Surface.stories.tsx

@@ -0,0 +1,96 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import '@dxos-theme';
+
+import React, { useCallback, useState } from 'react';
+
+import { faker } from '@dxos/random';
+import { Button, List, ListItem } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/storybook-utils';
+
+import { PluginManagerProvider, usePluginManager } from './PluginManagerProvider';
+import { Surface, useSurfaces } from './Surface';
+import { Capabilities, createSurface } from '../common';
+import { type PluginManager } from '../core';
+import { setupPluginManager } from '../testing';
+
+const randomColor = (): string => {
+  const hue = faker.number.int({ min: 0, max: 360 });
+  const saturation = faker.number.int({ min: 50, max: 90 });
+  const lightness = faker.number.int({ min: 40, max: 70 });
+  return `hsl(${hue}, ${saturation}%, ${lightness}%)`;
+};
+
+const Story = () => {
+  const manager = usePluginManager();
+  const surfaces = useSurfaces();
+  const [picked, setPicked] = useState('test');
+
+  const handleAdd = useCallback(() => {
+    const id = `test-${faker.number.int({ min: 0, max: 1_000_000 })}`;
+    const backgroundColor = randomColor();
+
+    manager.context.contributeCapability({
+      module: 'test',
+      interface: Capabilities.ReactSurface,
+      implementation: createSurface({
+        id,
+        role: id,
+        component: () => (
+          <div className='flex-1' style={{ backgroundColor }}>
+            {id}
+          </div>
+        ),
+      }),
+    });
+
+    setPicked(id);
+  }, [manager]);
+
+  const handlePick = useCallback(() => {
+    setPicked(faker.helpers.arrayElement(surfaces).id);
+  }, [surfaces]);
+
+  return (
+    <div className='flex flex-col gap-2'>
+      <div className='flex gap-2'>
+        <Button onClick={handleAdd}>Add</Button>
+        <Button onClick={handlePick}>Pick</Button>
+      </div>
+      <div className='flex gap-2'>
+        <div className='flex-1'>
+          <List itemSizes='one'>
+            {surfaces.map((surface) => (
+              <ListItem.Root key={surface.id} id={surface.id}>
+                <ListItem.Heading classNames='grow pbs-2'>{surface.id}</ListItem.Heading>
+              </ListItem.Root>
+            ))}
+          </List>
+        </div>
+        <div className='flex-1'>
+          <Surface role={picked} limit={1} />
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default {
+  title: 'sdk/app-framework/Surface',
+  render: ({ manager }: { manager: PluginManager }) => {
+    return (
+      <PluginManagerProvider value={manager}>
+        <Story />
+      </PluginManagerProvider>
+    );
+  },
+  // NOTE: Intentionally not using withPluginManager to try to reduce surface area of the story.
+  decorators: [withTheme, withLayout({ tooltips: true })],
+  args: {
+    manager: setupPluginManager(),
+  },
+};
+
+export const Default = {};

package/src/react/Surface.tsx

@@ -0,0 +1,75 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { memo, forwardRef, Suspense, useMemo } from 'react';
+
+import { useDefaultValue } from '@dxos/react-hooks';
+import { byPosition } from '@dxos/util';
+
+import { ErrorBoundary } from './ErrorBoundary';
+import { useCapabilities } from './useCapabilities';
+import { Capabilities, type SurfaceDefinition, type SurfaceProps } from '../common';
+import { type PluginsContext } from '../core';
+
+/**
+ * @internal
+ */
+export const useSurfaces = () => {
+  const surfaces = useCapabilities(Capabilities.ReactSurface);
+  return useMemo(() => surfaces.flat(), [surfaces]);
+};
+
+const findCandidates = (surfaces: SurfaceDefinition[], { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
+  return Object.values(surfaces)
+    .filter((definition) =>
+      Array.isArray(definition.role) ? definition.role.includes(role) : definition.role === role,
+    )
+    .filter(({ filter }) => (filter ? filter(data ?? {}) : true))
+    .toSorted(byPosition);
+};
+
+/**
+ * @returns `true` if there is a contributed surface which matches the specified role & data, `false` otherwise.
+ */
+export const isSurfaceAvailable = (context: PluginsContext, { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
+  const surfaces = context.requestCapabilities(Capabilities.ReactSurface);
+  const candidates = findCandidates(surfaces.flat(), { role, data });
+  return candidates.length > 0;
+};
+
+/**
+ * A surface is a named region of the screen that can be populated by plugins.
+ */
+export const Surface = memo(
+  forwardRef<HTMLElement, SurfaceProps>(
+    ({ id: _id, role, data: _data, limit, fallback, placeholder, ...rest }, forwardedRef) => {
+      // 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 anyways.
+      //   In the future, it would be nice to be able to bucket the surface contributions by role.
+      const surfaces = useSurfaces();
+      const data = useDefaultValue(_data, () => ({}));
+
+      // 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;
+      const nodes = candidates.map(({ component: Component, id }) => (
+        <Component ref={forwardedRef} key={id} id={id} role={role} data={data} limit={limit} {...rest} />
+      ));
+
+      const suspense = placeholder ? <Suspense fallback={placeholder}>{nodes}</Suspense> : nodes;
+
+      return fallback ? (
+        <ErrorBoundary data={data} fallback={fallback}>
+          {suspense}
+        </ErrorBoundary>
+      ) : (
+        suspense
+      );
+    },
+  ),
+);
+
+Surface.displayName = 'Surface';

package/src/react/common.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useCapability } from './useCapabilities';
+import { Capabilities } from '../common';
+
+export const useIntentDispatcher = () => useCapability(Capabilities.IntentDispatcher);
+
+export const useAppGraph = () => useCapability(Capabilities.AppGraph);
+
+export const useLayout = () => useCapability(Capabilities.Layout);

package/src/react/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './common';
+export * from './ErrorBoundary';
+export * from './PluginManagerProvider';
+export * from './Surface';
+export * from './useCapabilities';
+export * from './useIntentResolver';

package/src/react/useCapabilities.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { computed } from '@preact/signals-core';
+import { useMemo } from 'react';
+
+import { usePluginManager } from './PluginManagerProvider';
+import { type InterfaceDef } from '../core';
+
+/**
+ * Hook to request capabilities from the plugin context.
+ * @returns An array of capabilities.
+ */
+export const useCapabilities = <T, U extends T = T>(
+  interfaceDef: InterfaceDef<T>,
+  filter?: (capability: T, moduleId: string) => capability is U,
+) => {
+  const manager = usePluginManager();
+  const signal = useMemo(
+    () => computed(() => manager.context.requestCapabilities(interfaceDef, filter)),
+    [interfaceDef],
+  );
+
+  return signal.value;
+};
+
+/**
+ * Hook to request a capability from the plugin context.
+ * @returns The capability.
+ * @throws If no capability is found.
+ */
+export const useCapability = <T, U extends T = T>(
+  interfaceDef: InterfaceDef<T>,
+  filter?: (capability: T, moduleId: string) => capability is U,
+) => {
+  const manager = usePluginManager();
+  const signal = useMemo(() => computed(() => manager.context.requestCapability(interfaceDef, filter)), [interfaceDef]);
+  return signal.value;
+};

package/src/react/useIntentResolver.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useEffect } from 'react';
+
+import { Capabilities } from '../common';
+import { type AnyIntentResolver } from '../plugin-intent';
+import { usePluginManager } from '../react';
+
+export const useIntentResolver = (module: string, resolver: AnyIntentResolver) => {
+  const manager = usePluginManager();
+  useEffect(() => {
+    manager.context.contributeCapability({
+      module,
+      interface: Capabilities.IntentResolver,
+      implementation: resolver,
+    });
+
+    return () => manager.context.removeCapability(Capabilities.IntentResolver, resolver);
+  }, [module, resolver]);
+};

package/src/testing/index.ts

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

package/src/testing/withPluginManager.stories.tsx

@@ -0,0 +1,47 @@
+//
+// Copyright 2025 DXOS.org
+
+//
+
+import React from 'react';
+
+import { withTheme, type Meta } from '@dxos/storybook-utils';
+
+import { withPluginManager } from './withPluginManager';
+import { Capabilities, createSurface } from '../common';
+import { contributes } from '../core';
+import { Surface } from '../react';
+
+const Render = () => {
+  console.log('Render');
+  return (
+    <div>
+      <div>Hello</div>
+      <Surface role='main' />
+    </div>
+  );
+};
+
+const meta: Meta = {
+  title: 'sdk/app-framework/withPluginManager',
+  render: Render,
+  decorators: [
+    withTheme,
+    withPluginManager({
+      capabilities: [
+        contributes(
+          Capabilities.ReactSurface,
+          createSurface({
+            id: 'test',
+            role: 'main',
+            component: ({ role }) => <span>{JSON.stringify({ role })}</span>,
+          }),
+        ),
+      ],
+    }),
+  ],
+};
+
+export default meta;
+
+export const Default = {};

package/src/testing/withPluginManager.tsx

@@ -0,0 +1,91 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Decorator } from '@storybook/react';
+import React, { useEffect } from 'react';
+
+import { raise } from '@dxos/debug';
+
+import { createApp, type CreateAppOptions } from '../App';
+import { Capabilities, Events } from '../common';
+import {
+  type ActivationEvent,
+  type AnyCapability,
+  contributes,
+  defineModule,
+  definePlugin,
+  PluginManager,
+} from '../core';
+
+/**
+ * @internal
+ */
+export const setupPluginManager = ({
+  capabilities,
+  plugins = [],
+  core = plugins.map(({ meta }) => meta.id),
+  ...options
+}: CreateAppOptions & { capabilities?: AnyCapability[] } = {}) => {
+  const pluginManager = new PluginManager({
+    pluginLoader: () => raise(new Error('Not implemented')),
+    plugins: [StoryPlugin(), ...plugins],
+    core: [STORY_PLUGIN, ...core],
+    ...options,
+  });
+
+  if (capabilities) {
+    capabilities.forEach((capability) => {
+      pluginManager.context.contributeCapability({
+        interface: capability.interface,
+        implementation: capability.implementation,
+        module: 'story',
+      });
+    });
+  }
+
+  return pluginManager;
+};
+
+export type WithPluginManagerOptions = CreateAppOptions & {
+  capabilities?: AnyCapability[];
+  fireEvents?: (ActivationEvent | string)[];
+};
+
+/**
+ * Wraps a story with a plugin manager.
+ */
+export const withPluginManager = (options: WithPluginManagerOptions = {}): Decorator => {
+  const pluginManager = setupPluginManager(options);
+  const App = createApp({ pluginManager });
+
+  options.fireEvents?.forEach((event) => {
+    void pluginManager.activate(event);
+  });
+
+  return (Story, context) => {
+    useEffect(() => {
+      const capability = contributes(Capabilities.ReactRoot, {
+        id: context.id,
+        root: () => <Story />,
+      });
+
+      pluginManager.context.contributeCapability({
+        ...capability,
+        module: 'dxos.org/app-framework/withPluginManager',
+      });
+
+      return () => pluginManager.context.removeCapability(capability.interface, capability.implementation);
+    }, []);
+
+    return <App />;
+  };
+};
+
+// No-op plugin to ensure there exists at least one plugin for the startup event.
+// This is necessary because `createApp` expects the startup event to complete before the app is ready.
+const STORY_PLUGIN = 'dxos.org/app-framework/story';
+const StoryPlugin = () =>
+  definePlugin({ id: STORY_PLUGIN }, [
+    defineModule({ id: STORY_PLUGIN, activatesOn: Events.Startup, activate: () => [] }),
+  ]);

package/src/worker.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// Entrypoint for using plugins in workers runtimes (e.g. Cloudflare Workers, etc.)
+// Excludes all frontend code & dependencies (e.g. localStorage, React, etc.)
+
+export * from './core';
+// NOTE: Common includes browser capabilities but they are types only.
+export * from './common';
+export * from './plugin-intent';

package/tsconfig.json

@@ -1,15 +1,6 @@
 {
   "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "esModuleInterop": true,
-    "jsx": "react",
-    "lib": [
-      "DOM",
-      "ESNext"
-    ],
-    "module": "ESNext",
-    "outDir": "dist"
-  },
+  "compilerOptions": {},
   "exclude": [
     "/node_modules/"
   ],
@@ -20,9 +11,6 @@
     {
       "path": "../../common/async"
     },
-    {
-      "path": "../../common/context"
-    },
     {
       "path": "../../common/debug"
     },
@@ -35,18 +23,36 @@
     {
       "path": "../../common/log"
     },
+    {
+      "path": "../../common/random"
+    },
+    {
+      "path": "../../common/storybook-utils"
+    },
     {
       "path": "../../common/util"
     },
     {
       "path": "../../core/echo/echo-schema"
     },
+    {
+      "path": "../../core/echo/echo-signals"
+    },
     {
       "path": "../../core/echo/live-object"
     },
+    {
+      "path": "../../experimental/artifact"
+    },
     {
       "path": "../../ui/primitives/react-hooks"
     },
+    {
+      "path": "../../ui/react-ui"
+    },
+    {
+      "path": "../../ui/react-ui-syntax-highlighter"
+    },
     {
       "path": "../app-graph"
     },