@dxos/app-framework 0.7.5-main.9cb18ac → 0.7.5-main.9d2a38b

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.tsx

@@ -0,0 +1,72 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { memo, forwardRef, Suspense, useMemo } from 'react';
+
+import { useDefaultValue } from '@dxos/react-hooks';
+import { byDisposition } from '@dxos/util';
+
+import { ErrorBoundary } from './ErrorBoundary';
+import { useCapabilities } from './useCapabilities';
+import { Capabilities, type SurfaceDefinition, type SurfaceProps } from '../common';
+import { type PluginsContext } from '../core';
+
+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(byDisposition);
+};
+
+/**
+ * @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, () => ({}));
+
+      const candidates = useMemo(() => {
+        const definitions = findCandidates(surfaces, { role, data });
+        return limit ? definitions.slice(0, limit) : definitions;
+      }, [surfaces, role, data, limit]);
+
+      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
+      );
+    },
+  ),
+);

package/src/react/index.ts

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

package/src/react/useCapabilities.ts

@@ -0,0 +1,39 @@
+//
+// 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/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,67 @@
+//
+// 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 AnyCapability, contributes, defineModule, definePlugin, PluginManager } from '../core';
+
+/**
+ * Wraps a story with a plugin manager.
+ */
+export const withPluginManager = ({
+  capabilities,
+  plugins = [],
+  core = plugins.map(({ meta }) => meta.id),
+  ...options
+}: CreateAppOptions & { capabilities?: AnyCapability[] } = {}): Decorator => {
+  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',
+      });
+    });
+  }
+
+  const App = createApp({ pluginManager });
+
+  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/tsconfig.json

@@ -8,7 +8,7 @@
       "ESNext"
     ],
     "module": "ESNext",
-    "outDir": "dist"
+    "outDir": "./dist/types"
   },
   "exclude": [
     "/node_modules/"
@@ -35,18 +35,30 @@
     {
       "path": "../../common/log"
     },
+    {
+      "path": "../../common/storybook-utils"
+    },
     {
       "path": "../../common/util"
     },
     {
       "path": "../../core/echo/echo-schema"
     },
+    {
+      "path": "../../core/echo/echo-signals"
+    },
     {
       "path": "../../core/echo/live-object"
     },
     {
       "path": "../../ui/primitives/react-hooks"
     },
+    {
+      "path": "../../ui/react-ui"
+    },
+    {
+      "path": "../../ui/react-ui-syntax-highlighter"
+    },
     {
       "path": "../app-graph"
     },

package/dist/lib/browser/chunk-3E7RY3CE.mjs

@@ -1,72 +0,0 @@
-// packages/sdk/app-framework/src/plugins/helpers.ts
-import { Context } from "@dxos/context";
-import { raise } from "@dxos/debug";
-import { invariant } from "@dxos/invariant";
-var __dxlog_file = "/home/runner/work/dxos/dxos/packages/sdk/app-framework/src/plugins/helpers.ts";
-var findPlugin = (plugins, id) => {
-  return plugins.find((plugin) => plugin.meta.id === id || typeof plugin.meta.shortId === "string" && plugin.meta.shortId === id);
-};
-var getPlugin = (plugins, id) => {
-  return findPlugin(plugins, id) ?? raise(new Error(`Plugin not found: ${id}`));
-};
-var filterPlugins = (plugins, predicate) => plugins.map((plugin) => predicate(plugin)).filter((plugin) => !!plugin);
-var resolvePlugin = (plugins, predicate) => filterPlugins(plugins, predicate)[0];
-var PluginContext = class {
-  constructor() {
-    // TODO(burdon): Use Resource (@dima)?
-    this.ctx = new Context(void 0, {
-      F: __dxlog_file,
-      L: 50
-    });
-  }
-  init(plugins) {
-    this._plugins = plugins;
-  }
-  getPlugin(id) {
-    invariant(this._plugins, void 0, {
-      F: __dxlog_file,
-      L: 59,
-      S: this,
-      A: [
-        "this._plugins",
-        ""
-      ]
-    });
-    return getPlugin(this._plugins, id);
-  }
-  resolvePlugin(resolver, required = false) {
-    invariant(this._plugins, "context not initialized", {
-      F: __dxlog_file,
-      L: 65,
-      S: this,
-      A: [
-        "this._plugins",
-        "'context not initialized'"
-      ]
-    });
-    const plugin = resolvePlugin(this._plugins, resolver);
-    if (required && !plugin) {
-      throw new Error("Plugin not found.");
-    }
-    return plugin;
-  }
-  onDispose(cb) {
-    this.ctx.onDispose(cb);
-  }
-  dispose() {
-    void this.ctx.dispose();
-  }
-};
-var definePlugin = (cb) => {
-  const context = new PluginContext();
-  return () => cb(context);
-};
-
-export {
-  findPlugin,
-  getPlugin,
-  filterPlugins,
-  resolvePlugin,
-  definePlugin
-};
-//# sourceMappingURL=chunk-3E7RY3CE.mjs.map

package/dist/lib/browser/chunk-3E7RY3CE.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/plugins/helpers.ts"],
-  "sourcesContent": ["//\n// Copyright 2023 DXOS.org\n//\n\nimport { Context, type DisposeCallback } from '@dxos/context';\nimport { raise } from '@dxos/debug';\nimport { invariant } from '@dxos/invariant';\n\nimport { type Plugin, type PluginDefinition } from './plugin-host';\n\n/**\n * Resolvers allow different instances of plugins to provide a particular capability.\n */\nexport type PluginResolver<T> = (plugin: Plugin) => Plugin<T> | undefined;\n\n/**\n * Find a plugin by ID.\n */\nexport const findPlugin = <T>(plugins: Plugin[], id: string): Plugin<T> | undefined => {\n  return plugins.find(\n    (plugin) => plugin.meta.id === id || (typeof plugin.meta.shortId === 'string' && plugin.meta.shortId === id),\n  ) as Plugin<T>;\n};\n\n/**\n * Find a plugin by ID, or raise an error if not found.\n */\nexport const getPlugin = <T>(plugins: Plugin[], id: string): Plugin<T> => {\n  return findPlugin(plugins, id) ?? raise(new Error(`Plugin not found: ${id}`));\n};\n\n/**\n * Filter a list of plugins to only those that match a predicate.\n */\nexport const filterPlugins = <T>(plugins: Plugin[], predicate: PluginResolver<T>): Plugin<T>[] =>\n  plugins.map((plugin) => predicate(plugin)).filter((plugin): plugin is Plugin<T> => !!plugin);\n\n/**\n * Resolves a plugin by predicate.\n *\n * @example\n * import { parseIntentPlugin, resolvePlugin } from '@dxos/app-framework';\n * const intentPlugin = resolvePlugin(plugins, parseIntentPlugin);\n */\nexport const resolvePlugin = <T>(plugins: Plugin[], predicate: PluginResolver<T>): Plugin<T> | undefined =>\n  filterPlugins(plugins, predicate)[0];\n\nclass PluginContext {\n  // TODO(burdon): Use Resource (@dima)?\n  public readonly ctx = new Context();\n\n  private _plugins?: Plugin[];\n\n  init(plugins: Plugin[]) {\n    this._plugins = plugins;\n  }\n\n  getPlugin<T>(id: string): Plugin<T> {\n    invariant(this._plugins);\n    return getPlugin(this._plugins, id);\n  }\n\n  resolvePlugin<T>(resolver: PluginResolver<T>): Plugin<T>;\n  resolvePlugin<T>(resolver: PluginResolver<T>, required = false): Plugin<T> | undefined {\n    invariant(this._plugins, 'context not initialized');\n    const plugin = resolvePlugin(this._plugins, resolver);\n    if (required && !plugin) {\n      // TODO(burdon): Resolver should have a name.\n      throw new Error('Plugin not found.');\n    }\n\n    return plugin;\n  }\n\n  onDispose(cb: DisposeCallback) {\n    this.ctx.onDispose(cb);\n  }\n\n  dispose() {\n    void this.ctx.dispose();\n  }\n}\n\n/**\n * Plugin helper with dependency injection and life-cycle support.\n */\nexport const definePlugin = <Provides>(\n  cb: (context: PluginContext) => PluginDefinition<Provides>,\n): (() => PluginDefinition<Provides>) => {\n  const context = new PluginContext();\n  return () => cb(context);\n};\n"],
-  "mappings": ";AAIA,SAASA,eAAqC;AAC9C,SAASC,aAAa;AACtB,SAASC,iBAAiB;;AAYnB,IAAMC,aAAa,CAAIC,SAAmBC,OAAAA;AAC/C,SAAOD,QAAQE,KACb,CAACC,WAAWA,OAAOC,KAAKH,OAAOA,MAAO,OAAOE,OAAOC,KAAKC,YAAY,YAAYF,OAAOC,KAAKC,YAAYJ,EAAAA;AAE7G;AAKO,IAAMK,YAAY,CAAIN,SAAmBC,OAAAA;AAC9C,SAAOF,WAAWC,SAASC,EAAAA,KAAOJ,MAAM,IAAIU,MAAM,qBAAqBN,EAAAA,EAAI,CAAA;AAC7E;AAKO,IAAMO,gBAAgB,CAAIR,SAAmBS,cAClDT,QAAQU,IAAI,CAACP,WAAWM,UAAUN,MAAAA,CAAAA,EAASQ,OAAO,CAACR,WAAgC,CAAC,CAACA,MAAAA;AAShF,IAAMS,gBAAgB,CAAIZ,SAAmBS,cAClDD,cAAcR,SAASS,SAAAA,EAAW,CAAA;AAEpC,IAAMI,gBAAN,MAAMA;EAAN;AAEkBC;eAAM,IAAIlB,QAAAA,QAAAA;;;;;EAI1BmB,KAAKf,SAAmB;AACtB,SAAKgB,WAAWhB;EAClB;EAEAM,UAAaL,IAAuB;AAClCH,cAAU,KAAKkB,UAAQ,QAAA;;;;;;;;;AACvB,WAAOV,UAAU,KAAKU,UAAUf,EAAAA;EAClC;EAGAW,cAAiBK,UAA6BC,WAAW,OAA8B;AACrFpB,cAAU,KAAKkB,UAAU,2BAAA;;;;;;;;;AACzB,UAAMb,SAASS,cAAc,KAAKI,UAAUC,QAAAA;AAC5C,QAAIC,YAAY,CAACf,QAAQ;AAEvB,YAAM,IAAII,MAAM,mBAAA;IAClB;AAEA,WAAOJ;EACT;EAEAgB,UAAUC,IAAqB;AAC7B,SAAKN,IAAIK,UAAUC,EAAAA;EACrB;EAEAC,UAAU;AACR,SAAK,KAAKP,IAAIO,QAAO;EACvB;AACF;AAKO,IAAMC,eAAe,CAC1BF,OAAAA;AAEA,QAAMG,UAAU,IAAIV,cAAAA;AACpB,SAAO,MAAMO,GAAGG,OAAAA;AAClB;",
-  "names": ["Context", "raise", "invariant", "findPlugin", "plugins", "id", "find", "plugin", "meta", "shortId", "getPlugin", "Error", "filterPlugins", "predicate", "map", "filter", "resolvePlugin", "PluginContext", "ctx", "init", "_plugins", "resolver", "required", "onDispose", "cb", "dispose", "definePlugin", "context"]
-}