@dxos/app-framework 0.3.3-main.0c081e6

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@dxos/app-framework",
+  "version": "0.3.3-main.0c081e6",
+  "description": "A framework for building applications from composible plugins.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "main": "dist/lib/node/index.cjs",
+  "browser": {
+    "./dist/lib/node/index.cjs": "./dist/lib/browser/index.mjs"
+  },
+  "types": "dist/types/src/index.d.ts",
+  "dependencies": {
+    "@preact/signals-react": "^1.3.6",
+    "deepsignal": "1.4.0-shallow.0",
+    "zod": "^3.19.1",
+    "@dxos/app-graph": "0.3.3-main.0c081e6",
+    "@dxos/async": "0.3.3-main.0c081e6",
+    "@dxos/debug": "0.3.3-main.0c081e6",
+    "@dxos/invariant": "0.3.3-main.0c081e6",
+    "@dxos/log": "0.3.3-main.0c081e6"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.21",
+    "react": "^18.2.0"
+  },
+  "peerDependencies": {
+    "react": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/project.json

@@ -0,0 +1,78 @@
+{
+  "sourceRoot": "packages/sdk/app-framework/src",
+  "projectType": "application",
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "options": {
+        "main": "packages/sdk/app-framework/src/index.ts",
+        "outputPath": "packages/sdk/app-framework/dist/types",
+        "tsConfig": "packages/sdk/app-framework/tsconfig.json"
+      },
+      "outputs": [
+        "{options.outputPath}"
+      ]
+    },
+    "compile": {
+      "executor": "@dxos/esbuild:build",
+      "options": {
+        "entryPoints": [
+          "packages/sdk/app-framework/src/index.ts"
+        ],
+        "outputPath": "packages/sdk/app-framework/dist/lib"
+      },
+      "outputs": [
+        "{options.outputPath}"
+      ]
+    },
+    "lint": {
+      "executor": "@nx/linter:eslint",
+      "options": {
+        "format": "unix",
+        "lintFilePatterns": [
+          "packages/sdk/app-framework/**/*.{ts,tsx,js,jsx}"
+        ],
+        "quiet": true
+      },
+      "outputs": [
+        "{options.outputFile}"
+      ]
+    },
+    "storybook": {
+      "configurations": {
+        "ci": {
+          "quiet": true
+        }
+      },
+      "executor": "@nx/storybook:storybook",
+      "options": {
+        "configDir": "packages/sdk/app-framework/.storybook"
+      }
+    },
+    "test": {
+      "executor": "@dxos/test:run",
+      "options": {
+        "ciEnvironments": [
+          "nodejs"
+        ],
+        "coveragePath": "coverage/packages/sdk/app-framework",
+        "outputPath": "tmp/mocha/packages/sdk/app-framework",
+        "resultsPath": "test-results/packages/sdk/app-framework",
+        "testPatterns": [
+          "packages/sdk/app-framework/src/**/*.test.{ts,js}"
+        ],
+        "watchPatterns": [
+          "packages/sdk/app-framework/src/**/*"
+        ]
+      },
+      "outputs": [
+        "{options.coveragePath}",
+        "{options.outputPath}",
+        "{options.resultsPath}"
+      ]
+    }
+  },
+  "implicitDependencies": [
+    "test"
+  ]
+}

package/src/App.tsx

@@ -0,0 +1,43 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React from 'react';
+
+import { invariant } from '@dxos/invariant';
+
+import { type BootstrapPluginsParams, PluginHost, SurfacePlugin, IntentPlugin } from './plugins';
+
+/**
+ * Expected usage is for this to be the entrypoint of the application.
+ * Initializes plugins and renders the root components.
+ *
+ * @example
+ * const fallback = <div>Initializing Plugins...</div>;
+ * const App = createApp({ plugins, fallback });
+ * createRoot(document.getElementById('root')!).render(
+ *   <StrictMode>
+ *     <App />
+ *   </StrictMode>,
+ * );
+ *
+ * @param params.plugins List of plugin definitions to initialize.
+ * @param params.fallback Fallback component to render while plugins are initializing.
+ */
+export const createApp = ({ plugins, fallback }: BootstrapPluginsParams) => {
+  const host = PluginHost({
+    plugins: [SurfacePlugin(), IntentPlugin(), ...plugins],
+    fallback,
+  });
+
+  invariant(host.provides?.context);
+  invariant(host.provides?.root);
+  const Context = host.provides.context;
+  const Root = host.provides.root;
+
+  return () => (
+    <Context>
+      <Root />
+    </Context>
+  );
+};

package/src/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './plugins';
+
+export * from './App';

package/src/plugins/IntentPlugin/IntentContext.tsx

@@ -0,0 +1,17 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Context, createContext, useContext, type Provider } from 'react';
+
+import { type DispatchIntent } from './intent';
+
+export type IntentContext = {
+  dispatch: DispatchIntent;
+};
+
+const IntentContext: Context<IntentContext> = createContext<IntentContext>({ dispatch: async () => {} });
+
+export const useIntent = () => useContext(IntentContext);
+
+export const IntentProvider: Provider<IntentContext> = IntentContext.Provider;

package/src/plugins/IntentPlugin/IntentPlugin.tsx

@@ -0,0 +1,69 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { deepSignal } from 'deepsignal/react';
+import React from 'react';
+
+import { type IntentContext, IntentProvider } from './IntentContext';
+import { type Intent } from './intent';
+import { type PluginDefinition, type Plugin } from '../PluginHost';
+import { filterPlugins, findPlugin } from '../helpers';
+
+export type IntentResolverProvides = {
+  intent: {
+    resolver: (intent: Intent, plugins: Plugin[]) => any;
+  };
+};
+
+export type IntentPluginProvides = {
+  intent: IntentContext;
+};
+
+export const parseIntentPlugin = (plugin: Plugin) =>
+  (plugin.provides as any).intent?.dispatch ? (plugin as Plugin<IntentPluginProvides>) : undefined;
+
+export const parseIntentResolverPlugin = (plugin: Plugin) =>
+  (plugin.provides as any).intent?.resolver ? (plugin as Plugin<IntentResolverProvides>) : undefined;
+
+/**
+ * Allows plugins to register intent handlers and routes sent intents to the appropriate plugin.
+ * Inspired by https://developer.android.com/reference/android/content/Intent.
+ */
+export const IntentPlugin = (): PluginDefinition<IntentPluginProvides> => {
+  const state = deepSignal<IntentContext>({ dispatch: async () => {} });
+
+  return {
+    meta: {
+      id: 'dxos.org/plugin/intent',
+    },
+    ready: async (plugins) => {
+      // Dispatch intent to associated plugin.
+      const dispatch = (intent: Intent) => {
+        if (intent.plugin) {
+          const plugin = findPlugin<IntentResolverProvides>(plugins, intent.plugin);
+          return plugin?.provides.intent.resolver(intent, plugins);
+        }
+
+        // Return resolved value from first plugin that handles the intent.
+        return filterPlugins(plugins, parseIntentResolverPlugin).reduce((acc, plugin) => {
+          return acc ?? plugin.provides.intent.resolver(intent, plugins);
+        }, undefined);
+      };
+
+      // Sequentially dispatch array of invents.
+      state.dispatch = async (intentOrArray) => {
+        let result: any = null;
+        for (const intent of Array.isArray(intentOrArray) ? intentOrArray : [intentOrArray]) {
+          const data = intent.data ? { ...result, ...intent.data } : result;
+          result = await dispatch({ ...intent, data });
+        }
+        return result;
+      };
+    },
+    provides: {
+      intent: state,
+      context: ({ children }) => <IntentProvider value={state}>{children}</IntentProvider>,
+    },
+  };
+};

package/src/plugins/IntentPlugin/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './intent';
+export * from './IntentContext';
+export * from './IntentPlugin';

package/src/plugins/IntentPlugin/intent.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+/**
+ * An intent is an abstract description of an operation to be performed.
+ * Intents allow actions to be performed across plugins.
+ */
+export type Intent = {
+  /**
+   * Plugin ID.
+   * If specified, the intent will be sent explicitly to the plugin.
+   * Otherwise, the intent will be sent to all plugins, in order and the first to resolve a non-null value will be used.
+   */
+  plugin?: string;
+
+  /**
+   * The action to perform.
+   */
+  action: string;
+
+  /**
+   * Any data needed to perform the desired action.
+   */
+  data?: any;
+};
+
+/**
+ * Trigger one or more intents to be sent.
+ * If multiple intents are specified, the result of each will be merged with the data to the next.
+ *
+ * @returns The result of the last intent.
+ */
+export type DispatchIntent = (intent: Intent | Intent[]) => Promise<any>;

package/src/plugins/PluginHost/PluginContext.tsx

@@ -0,0 +1,45 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Context, type Provider, createContext, useContext } from 'react';
+
+import { type Plugin, type PluginDefinition } from './plugin';
+import { findPlugin, resolvePlugin } from '../helpers';
+
+export type PluginContext = {
+  ready: boolean;
+  initializing: PluginDefinition[];
+  loading: PluginDefinition[];
+  plugins: Plugin[];
+};
+
+const PluginContext: Context<PluginContext> = createContext<PluginContext>({
+  ready: false,
+  initializing: [],
+  loading: [],
+  plugins: [],
+});
+
+/**
+ * Get all plugins.
+ */
+export const usePlugins = (): PluginContext => useContext(PluginContext);
+
+/**
+ * Get a plugin by ID.
+ */
+export const usePlugin = <T,>(id: string): Plugin<T> | undefined => {
+  const { plugins } = usePlugins();
+  return findPlugin<T>(plugins, id);
+};
+
+/**
+ * Resolve a plugin by predicate.
+ */
+export const useResolvePlugin = <T,>(predicate: (plugin: Plugin) => Plugin<T> | undefined): Plugin<T> | undefined => {
+  const { plugins } = usePlugins();
+  return resolvePlugin(plugins, predicate);
+};
+
+export const PluginProvider: Provider<PluginContext> = PluginContext.Provider;

package/src/plugins/PluginHost/PluginHost.tsx

@@ -0,0 +1,200 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { deepSignal, shallow } from 'deepsignal/react';
+import React, { useEffect, type FC, type PropsWithChildren, type ReactNode } from 'react';
+
+import { log } from '@dxos/log';
+
+import { type PluginContext, PluginProvider } from './PluginContext';
+import { type Plugin, type PluginDefinition, type PluginProvides } from './plugin';
+
+export type BootstrapPluginsParams = {
+  plugins: PluginDefinition[];
+  fallback?: ReactNode | FC<Omit<PluginContext, 'ready'>>;
+};
+
+export type PluginHostProvides = {
+  plugins: PluginContext;
+};
+
+export const parsePluginHost = (plugin: Plugin) =>
+  (plugin.provides as PluginHostProvides).plugins ? (plugin as Plugin<PluginHostProvides>) : undefined;
+
+/**
+ * Bootstraps an application by initializing plugins and rendering root components.
+ */
+export const PluginHost = ({
+  plugins: definitions,
+  fallback,
+}: BootstrapPluginsParams): PluginDefinition<PluginHostProvides> => {
+  const state = deepSignal<PluginContext>({ ready: false, initializing: [], loading: [], plugins: [] });
+
+  return {
+    meta: {
+      id: 'dxos.org/plugin/host',
+    },
+    provides: {
+      plugins: state,
+      context: ({ children }) => <PluginProvider value={state}>{children}</PluginProvider>,
+      root: () => {
+        useEffect(() => {
+          log('initializing plugins', { definitions });
+          const timeout = setTimeout(async () => {
+            state.initializing = shallow(definitions);
+            const plugins = await Promise.all(
+              definitions.map(async (definition) => {
+                const plugin = await initializePlugin(definition).catch((err) => {
+                  console.error('Failed to initialize plugin:', definition.meta.id, err);
+                  return undefined;
+                });
+                state.initializing = shallow(state.initializing.filter((plugin) => plugin !== definition));
+                return plugin;
+              }),
+            ).then((plugins) => plugins.filter((plugin): plugin is Plugin => Boolean(plugin)));
+
+            log('plugins initialized', { plugins });
+            state.loading = shallow(definitions);
+            await Promise.all(
+              definitions.map(async (pluginDefinition) => {
+                await pluginDefinition.ready?.(plugins);
+                state.loading = shallow(state.loading.filter((plugin) => plugin !== pluginDefinition));
+              }),
+            );
+
+            log('plugins ready', { plugins });
+            state.plugins = shallow(plugins);
+            state.ready = true;
+          });
+
+          return () => {
+            clearTimeout(timeout);
+            state.ready = false;
+            void Promise.all(definitions.map((definition) => definition.unload?.()));
+          };
+        }, []);
+
+        if (!state.ready) {
+          if (typeof fallback === 'function') {
+            const FallbackComponent = fallback;
+            return (
+              <FallbackComponent initializing={state.initializing} loading={state.loading} plugins={state.plugins} />
+            );
+          }
+          return <>{fallback ?? null}</>;
+        }
+
+        const ComposedContext = composeContext(state.plugins);
+
+        return <ComposedContext>{rootComponents(state.plugins)}</ComposedContext>;
+      },
+    },
+  };
+};
+
+/**
+ * Resolve a `PluginDefinition` into a fully initialized `Plugin`.
+ */
+export const initializePlugin = async <T, U>(pluginDefinition: PluginDefinition<T, U>): Promise<Plugin<T & U>> => {
+  const provides = await pluginDefinition.initialize?.();
+  return {
+    ...pluginDefinition,
+    provides: {
+      ...pluginDefinition.provides,
+      ...provides,
+    } as PluginProvides<T & U>,
+  };
+};
+
+const rootComponents = (plugins: Plugin[]) => {
+  return plugins
+    .map((plugin) => {
+      const Component = plugin.provides.root;
+      if (Component) {
+        return <Component key={plugin.meta.id} />;
+      } else {
+        return null;
+      }
+    })
+    .filter((node): node is JSX.Element => Boolean(node));
+};
+
+const composeContext = (plugins: Plugin[]) => {
+  return compose(plugins.map((p) => p.provides.context!).filter(Boolean));
+};
+
+const compose = (contexts: FC<PropsWithChildren>[]) => {
+  return [...contexts].reduce((Acc, Next) => ({ children }) => (
+    <Acc>
+      <Next>{children}</Next>
+    </Acc>
+  ));
+};
+// export const PluginHost = ({ plugins: definitions, fallback }: BootstrapPluginsParams): PluginDefinition => {
+//   // const state = deepSignal<PluginContext>({ ready: false, initializing: [], loading: [], plugins: [] });
+
+//   return {
+//     meta: {
+//       id: 'dxos.org/plugin/host',
+//     },
+//     provides: {
+//       // plugins: state,
+//       // context: ({ children }) => <PluginProvider value={state}>{children}</PluginProvider>,
+//       root: () => {
+//         const [plugins, setPlugins] = useState<Plugin[]>();
+//         const [initializing, setInitializing] = useState<PluginDefinition[]>([]);
+//         const [loading, setLoading] = useState<PluginDefinition[]>([]);
+//         useEffect(() => {
+//           log('initializing plugins', { definitions });
+//           const timeout = setTimeout(async () => {
+//             setInitializing(definitions);
+//             const plugins = await Promise.all(
+//               definitions.map(async (definition) => {
+//                 const plugin = await initializePlugin(definition).catch((err) => {
+//                   console.error('Failed to initialize plugin:', definition.meta.id, err);
+//                   return undefined;
+//                 });
+//                 setInitializing((initializing) => initializing.filter((plugin) => plugin !== definition));
+//                 return plugin;
+//               }),
+//             ).then((plugins) => plugins.filter((plugin): plugin is Plugin => Boolean(plugin)));
+
+//             log('plugins initialized', { plugins });
+//             setLoading(definitions);
+//             await Promise.all(
+//               definitions.map(async (pluginDefinition) => {
+//                 await pluginDefinition.ready?.(plugins);
+//                 setLoading((loading) => loading.filter((plugin) => plugin !== pluginDefinition));
+//               }),
+//             );
+
+//             log('plugins ready', { plugins });
+//             setPlugins(plugins);
+//           });
+
+//           return () => {
+//             clearTimeout(timeout);
+//             void Promise.all(definitions.map((definition) => definition.unload?.()));
+//           };
+//         }, []);
+
+//         if (!plugins) {
+//           if (typeof fallback === 'function') {
+//             const FallbackComponent = fallback;
+//             return <FallbackComponent initializing={initializing} loading={loading} />;
+//           }
+//           return <>{fallback ?? null}</>;
+//         }
+
+//         const ComposedContext = composeContext(plugins);
+
+//         return (
+//           <PluginProvider value={{ plugins, initializing, loading, ready: true }}>
+//             <ComposedContext>{rootComponents(plugins)}</ComposedContext>
+//           </PluginProvider>
+//         );
+//       },
+//     },
+//   };
+// };

package/src/plugins/PluginHost/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './plugin';
+export * from './PluginContext';
+export * from './PluginHost';