@dxos/app-framework 0.8.2-staging.7ac8446 → 0.8.2

package/src/plugin-settings/app-graph-builder.ts

@@ -2,121 +2,156 @@
 // Copyright 2025 DXOS.org
 //
 
-import { createExtension, type Node } from '@dxos/app-graph';
+import { Rx } from '@effect-rx/rx-react';
+import { Option, pipe } from 'effect';
+
+import { createExtension, ROOT_ID } from '@dxos/app-graph';
 import { type SettingsStore, type SettingsValue } from '@dxos/local-storage';
 import { isNonNullable } from '@dxos/util';
 
 import { SETTINGS_ID, SETTINGS_KEY, SETTINGS_PLUGIN, SettingsAction } from './actions';
 import { Capabilities } from '../common';
-import { contributes, type PluginMeta, type PluginsContext } from '../core';
+import { contributes, type PluginMeta, type PluginContext } from '../core';
 import { createIntent } from '../plugin-intent';
 
-export default (context: PluginsContext) =>
+export default (context: PluginContext) =>
   contributes(Capabilities.AppGraphBuilder, [
     createExtension({
       id: `${SETTINGS_PLUGIN}/action`,
-      filter: (node): node is Node<null> => node.id === 'root',
-      actions: () => [
-        {
-          id: SETTINGS_PLUGIN,
-          data: async () => {
-            const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher);
-            await dispatch(createIntent(SettingsAction.Open));
-          },
-          properties: {
-            label: ['open settings label', { ns: SETTINGS_PLUGIN }],
-            icon: 'ph--gear--regular',
-            keyBinding: {
-              macos: 'meta+,',
-              windows: 'alt+,',
-            },
-          },
-        },
-      ],
+      actions: (node) =>
+        Rx.make((get) =>
+          pipe(
+            get(node),
+            Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
+            Option.map(() => [
+              {
+                id: SETTINGS_PLUGIN,
+                data: async () => {
+                  const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
+                  await dispatch(createIntent(SettingsAction.Open));
+                },
+                properties: {
+                  label: ['open settings label', { ns: SETTINGS_PLUGIN }],
+                  icon: 'ph--gear--regular',
+                  disposition: 'menu',
+                  keyBinding: {
+                    macos: 'meta+,',
+                    windows: 'alt+,',
+                  },
+                },
+              },
+            ]),
+            Option.getOrElse(() => []),
+          ),
+        ),
     }),
     createExtension({
       id: `${SETTINGS_PLUGIN}/core`,
-      filter: (node): node is Node<null> => node.id === 'root',
-      connector: () => [
-        {
-          id: SETTINGS_ID,
-          type: SETTINGS_PLUGIN,
-          properties: {
-            label: ['app settings label', { ns: SETTINGS_PLUGIN }],
-            icon: 'ph--gear--regular',
-            disposition: 'pin-end',
-            position: 'hoist',
-            testId: 'treeView.appSettings',
-          },
-        },
-      ],
+      connector: (node) =>
+        Rx.make((get) =>
+          pipe(
+            get(node),
+            Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
+            Option.map(() => [
+              {
+                id: SETTINGS_ID,
+                type: SETTINGS_PLUGIN,
+                properties: {
+                  label: ['app settings label', { ns: SETTINGS_PLUGIN }],
+                  icon: 'ph--gear--regular',
+                  disposition: 'pin-end',
+                  position: 'hoist',
+                  testId: 'treeView.appSettings',
+                },
+              },
+            ]),
+            Option.getOrElse(() => []),
+          ),
+        ),
     }),
     createExtension({
       id: `${SETTINGS_PLUGIN}/core-plugins`,
-      filter: (node): node is Node<null> => node.id === SETTINGS_ID,
-      connector: () => {
-        const manager = context.requestCapability(Capabilities.PluginManager);
-        const [settingsStore] = context.requestCapabilities(Capabilities.SettingsStore);
-        return [
-          ...manager.plugins
-            .filter((plugin) => manager.core.includes(plugin.meta.id))
-            .map((plugin): [PluginMeta, SettingsStore<SettingsValue>] | null => {
-              const settings = settingsStore?.getStore(plugin.meta.id);
-              if (!settings) {
-                return null;
-              }
+      connector: (node) =>
+        Rx.make((get) =>
+          pipe(
+            get(node),
+            Option.flatMap((node) => (node.id !== SETTINGS_ID ? Option.none() : Option.some(node))),
+            Option.map(() => {
+              const manager = get(context.capability(Capabilities.PluginManager));
+              const [settingsStore] = get(context.capabilities(Capabilities.SettingsStore));
+              return [
+                ...manager.plugins
+                  .filter((plugin) => manager.core.includes(plugin.meta.id))
+                  .map((plugin): [PluginMeta, SettingsStore<SettingsValue>] | null => {
+                    const settings = settingsStore?.getStore(plugin.meta.id);
+                    if (!settings) {
+                      return null;
+                    }
 
-              return [plugin.meta, settings];
-            })
-            .filter(isNonNullable)
-            .map(([meta, settings]) => ({
-              id: `${SETTINGS_KEY}:${meta.id.replaceAll('/', ':')}`,
-              type: 'category',
-              data: settings,
-              properties: {
-                label: meta.name ?? meta.id,
-                icon: meta.icon ?? 'ph--circle--regular',
-              },
-            })),
+                    return [plugin.meta, settings];
+                  })
+                  .filter(isNonNullable)
+                  .map(([meta, settings]) => ({
+                    id: `${SETTINGS_KEY}:${meta.id.replaceAll('/', ':')}`,
+                    type: 'category',
+                    data: settings,
+                    properties: {
+                      label: meta.name ?? meta.id,
+                      icon: meta.icon ?? 'ph--circle--regular',
+                    },
+                  })),
 
-          {
-            id: `${SETTINGS_KEY}:custom-plugins`,
-            type: 'collection',
-            properties: {
-              label: ['custom plugins label', { ns: SETTINGS_PLUGIN }],
-              icon: 'ph--squares-four--regular',
-              role: 'branch',
-            },
-          },
-        ];
-      },
+                {
+                  id: `${SETTINGS_KEY}:custom-plugins`,
+                  type: 'category',
+                  properties: {
+                    label: ['custom plugins label', { ns: SETTINGS_PLUGIN }],
+                    icon: 'ph--squares-four--regular',
+                    role: 'branch',
+                    disposition: 'collection',
+                  },
+                },
+              ];
+            }),
+            Option.getOrElse(() => []),
+          ),
+        ),
     }),
     createExtension({
       id: `${SETTINGS_PLUGIN}/custom-plugins`,
-      filter: (node): node is Node<null> => node.id === `${SETTINGS_KEY}:custom-plugins`,
-      connector: () => {
-        const manager = context.requestCapability(Capabilities.PluginManager);
-        const [settingsStore] = context.requestCapabilities(Capabilities.SettingsStore);
-        return manager.plugins
-          .filter((plugin) => !manager.core.includes(plugin.meta.id))
-          .map((plugin): [PluginMeta, SettingsStore<SettingsValue>] | null => {
-            const settings = settingsStore?.getStore(plugin.meta.id);
-            if (!settings) {
-              return null;
-            }
+      connector: (node) =>
+        Rx.make((get) =>
+          pipe(
+            get(node),
+            Option.flatMap((node) =>
+              node.id !== `${SETTINGS_KEY}:custom-plugins` ? Option.none() : Option.some(node),
+            ),
+            Option.map(() => {
+              const manager = get(context.capability(Capabilities.PluginManager));
+              const [settingsStore] = get(context.capabilities(Capabilities.SettingsStore));
+              return manager.plugins
+                .filter((plugin) => !manager.core.includes(plugin.meta.id))
+                .map((plugin): [PluginMeta, SettingsStore<SettingsValue>] | null => {
+                  const settings = settingsStore?.getStore(plugin.meta.id);
+                  if (!settings) {
+                    return null;
+                  }
 
-            return [plugin.meta, settings];
-          })
-          .filter(isNonNullable)
-          .map(([meta, settings]) => ({
-            id: `${SETTINGS_KEY}:${meta.id.replaceAll('/', ':')}`,
-            type: 'category',
-            data: settings,
-            properties: {
-              label: meta.name ?? meta.id,
-              icon: meta.icon ?? 'ph--circle--regular',
-            },
-          }));
-      },
+                  return [plugin.meta, settings];
+                })
+                .filter(isNonNullable)
+                .map(([meta, settings]) => ({
+                  id: `${SETTINGS_KEY}:${meta.id.replaceAll('/', ':')}`,
+                  type: 'category',
+                  data: settings,
+                  properties: {
+                    label: meta.name ?? meta.id,
+                    icon: meta.icon ?? 'ph--circle--regular',
+                  },
+                }));
+            }),
+            Option.getOrElse(() => []),
+          ),
+        ),
     }),
   ]);

package/src/plugin-settings/store.ts

@@ -2,29 +2,32 @@
 // 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';
+import { contributes, type PluginContext } from '../core';
 
-export default (context: PluginsContext) => {
+export default (context: PluginContext) => {
+  // TODO(wittjosiah): Replace with rx?
   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);
-    });
-  });
+  const registry = context.getCapability(Capabilities.RxRegistry);
+  const cancel = registry.subscribe(
+    context.capabilities(Capabilities.Settings),
+    (allSettings) => {
+      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);
+      });
+    },
+    { immediate: true },
+  );
 
-  return contributes(Capabilities.SettingsStore, settingsStore, () => unsubscribe());
+  return contributes(Capabilities.SettingsStore, settingsStore, () => cancel());
 };

package/src/react/ErrorBoundary.tsx

@@ -21,7 +21,7 @@ export class ErrorBoundary extends Component<Props, State> {
     this.state = { error: undefined };
   }
 
-  static getDerivedStateFromError(error: Error) {
+  static getDerivedStateFromError(error: Error): { error: Error } {
     return { error };
   }
 
@@ -31,7 +31,7 @@ export class ErrorBoundary extends Component<Props, State> {
     }
   }
 
-  override render() {
+  override render(): string | number | boolean | React.JSX.Element | Iterable<React.ReactNode> | null | undefined {
     if (this.state.error) {
       return <this.props.fallback data={this.props.data} error={this.state.error} reset={this.resetError} />;
     }
@@ -39,7 +39,7 @@ export class ErrorBoundary extends Component<Props, State> {
     return this.props.children;
   }
 
-  private resetError() {
+  private resetError(): void {
     this.setState({ error: undefined });
   }
 }

package/src/react/Surface.stories.tsx

@@ -87,7 +87,7 @@ export default {
     );
   },
   // NOTE: Intentionally not using withPluginManager to try to reduce surface area of the story.
-  decorators: [withTheme, withLayout({ tooltips: true })],
+  decorators: [withTheme, withLayout()],
   args: {
     manager: setupPluginManager(),
   },

package/src/react/Surface.tsx

@@ -10,7 +10,7 @@ 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';
+import { type PluginContext } from '../core';
 
 const DEFAULT_PLACEHOLDER = <Fragment />;
 
@@ -34,8 +34,8 @@ const findCandidates = (surfaces: SurfaceDefinition[], { role, data }: Pick<Surf
 /**
  * @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);
+export const isSurfaceAvailable = (context: PluginContext, { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
+  const surfaces = context.getCapabilities(Capabilities.ReactSurface);
   const candidates = findCandidates(surfaces.flat(), { role, data });
   return candidates.length > 0;
 };

package/src/react/useCapabilities.ts

@@ -2,8 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-import { computed } from '@preact/signals-core';
-import { useMemo } from 'react';
+import { useRxValue } from '@effect-rx/rx-react';
+
+import { invariant } from '@dxos/invariant';
 
 import { usePluginManager } from './PluginManagerProvider';
 import { type InterfaceDef } from '../core';
@@ -12,17 +13,9 @@ 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,
-) => {
+export const useCapabilities = <T>(interfaceDef: InterfaceDef<T>) => {
   const manager = usePluginManager();
-  const signal = useMemo(
-    () => computed(() => manager.context.requestCapabilities(interfaceDef, filter)),
-    [interfaceDef],
-  );
-
-  return signal.value;
+  return useRxValue(manager.context.capabilities(interfaceDef));
 };
 
 /**
@@ -30,11 +23,8 @@ export const useCapabilities = <T, U extends T = T>(
  * @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;
+export const useCapability = <T>(interfaceDef: InterfaceDef<T>) => {
+  const capabilities = useCapabilities(interfaceDef);
+  invariant(capabilities.length > 0, `No capability found for ${interfaceDef.identifier}`);
+  return capabilities[0];
 };

package/src/testing/withPluginManager.stories.tsx

@@ -1,6 +1,5 @@
 //
 // Copyright 2025 DXOS.org
-
 //
 
 import React from 'react';

package/src/testing/withPluginManager.tsx

@@ -3,21 +3,29 @@
 //
 
 import { type Decorator } from '@storybook/react';
-import React, { useEffect } from 'react';
+import React, { useEffect, useMemo } from 'react';
 
 import { raise } from '@dxos/debug';
 
-import { createApp, type CreateAppOptions } from '../App';
+import { useApp, type CreateAppOptions } from '../App';
 import { Capabilities, Events } from '../common';
 import {
-  type ActivationEvent,
-  type AnyCapability,
   contributes,
   defineModule,
   definePlugin,
+  type ActivationEvent,
+  type AnyCapability,
   PluginManager,
+  type PluginContext,
 } from '../core';
 
+// TODO(burdon): Factor out (use consistently in plugin framework?)
+export type Provider<C, R> = (context: C) => R;
+export type ProviderOrValue<C, R> = Provider<C, R> | R;
+export const getValue = <C, R>(providerOrValue: ProviderOrValue<C, R>, context: C): R => {
+  return typeof providerOrValue === 'function' ? (providerOrValue as Provider<C, R>)(context) : providerOrValue;
+};
+
 /**
  * @internal
  */
@@ -26,7 +34,7 @@ export const setupPluginManager = ({
   plugins = [],
   core = plugins.map(({ meta }) => meta.id),
   ...options
-}: CreateAppOptions & { capabilities?: AnyCapability[] } = {}) => {
+}: CreateAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
   const pluginManager = new PluginManager({
     pluginLoader: () => raise(new Error('Not implemented')),
     plugins: [StoryPlugin(), ...plugins],
@@ -35,7 +43,7 @@ export const setupPluginManager = ({
   });
 
   if (capabilities) {
-    capabilities.forEach((capability) => {
+    getValue(capabilities, pluginManager.context).forEach((capability) => {
       pluginManager.context.contributeCapability({
         interface: capability.interface,
         implementation: capability.implementation,
@@ -48,22 +56,19 @@ export const setupPluginManager = ({
 };
 
 export type WithPluginManagerOptions = CreateAppOptions & {
-  capabilities?: AnyCapability[];
+  capabilities?: ProviderOrValue<PluginContext, AnyCapability[]>;
   fireEvents?: (ActivationEvent | string)[];
 };
 
 /**
  * Wraps a story with a plugin manager.
+ * NOTE: This builds up and tears down the plugin manager on every render.
  */
 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) => {
+    const pluginManager = useMemo(() => setupPluginManager(options), [options]);
+
+    // Set-up root capability.
     useEffect(() => {
       const capability = contributes(Capabilities.ReactRoot, {
         id: context.id,
@@ -75,8 +80,22 @@ export const withPluginManager = (options: WithPluginManagerOptions = {}): Decor
         module: 'dxos.org/app-framework/withPluginManager',
       });
 
-      return () => pluginManager.context.removeCapability(capability.interface, capability.implementation);
-    }, []);
+      return () => {
+        pluginManager.context.removeCapability(capability.interface, capability.implementation);
+      };
+    }, [pluginManager, context]);
+
+    // Fire events.
+    useEffect(() => {
+      const timeout = setTimeout(async () => {
+        await Promise.all(options.fireEvents?.map((event) => pluginManager.activate(event)) ?? []);
+      });
+
+      return () => clearTimeout(timeout);
+    }, [pluginManager]);
+
+    // Create app.
+    const App = useApp({ pluginManager });
 
     return <App />;
   };

package/tsconfig.json

@@ -7,59 +7,7 @@
   "include": [
     "src"
   ],
-  "references": [
-    {
-      "path": "../../common/async"
-    },
-    {
-      "path": "../../common/debug"
-    },
-    {
-      "path": "../../common/invariant"
-    },
-    {
-      "path": "../../common/local-storage"
-    },
-    {
-      "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"
-    },
-    {
-      "path": "../client-protocol"
-    }
-  ],
+  "references": [],
   "ts-node": {
     "compilerOptions": {
       "module": "CommonJS"

package/typedoc/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

package/typedoc/assets/hierarchy.js

@@ -0,0 +1 @@
+window.hierarchyData = "eJyrVirKzy8pVrKKjtVRKkpNy0lNLsnMzytWsqqurQUAmx4Kpg=="