@dxos/app-framework 0.6.13 → 0.6.14-main.1366248

package/src/plugins/common/navigation.ts

@@ -2,12 +2,11 @@
 // Copyright 2024 DXOS.org
 //
 
+import { Schema as S } from '@effect/schema';
 import { z } from 'zod';
 
-import { S } from '@dxos/echo-schema';
-
-import type { IntentData } from '../IntentPlugin';
-import type { Plugin } from '../PluginHost';
+import { type Plugin } from '../plugin-host';
+import { type IntentData } from '../plugin-intent';
 
 // NOTE(thure): These are chosen from RFC 1738’s `safe` characters: http://www.faqs.org/rfcs/rfc1738.html
 export const SLUG_LIST_SEPARATOR = '+';
@@ -19,7 +18,6 @@ export const SLUG_COLLECTION_INDICATOR = '';
 const LayoutEntrySchema = S.mutable(S.Struct({ id: S.String, path: S.optional(S.String) }));
 export type LayoutEntry = S.Schema.Type<typeof LayoutEntrySchema>;
 
-// TODO(Zan): Consider making solo it's own part. It's not really a function of the 'main' part?
 // TODO(Zan): Consider renaming the 'main' part to 'deck' part now that we are throwing out the old layout plugin.
 // TODO(Zan): Extend to all strings?
 const LayoutPartSchema = S.Union(
@@ -31,7 +29,9 @@ const LayoutPartSchema = S.Union(
 );
 export type LayoutPart = S.Schema.Type<typeof LayoutPartSchema>;
 
-const LayoutPartsSchema = S.partial(S.mutable(S.Record(LayoutPartSchema, S.mutable(S.Array(LayoutEntrySchema)))));
+const LayoutPartsSchema = S.partial(
+  S.mutable(S.Record({ key: LayoutPartSchema, value: S.mutable(S.Array(LayoutEntrySchema)) })),
+);
 export type LayoutParts = S.Schema.Type<typeof LayoutPartsSchema>;
 
 const LayoutCoordinateSchema = S.mutable(S.Struct({ part: LayoutPartSchema, entryId: S.String }));
@@ -52,14 +52,6 @@ export type ActiveParts = z.infer<typeof ActiveParts>;
 // TODO(burdon): Where should this go?
 export type LayoutContainerProps<T> = T & { role?: string; coordinate?: LayoutCoordinate };
 
-/**
- * Basic state provided by a navigation plugin.
- */
-export const Attention = z.object({
-  attended: z.set(z.string()).optional().describe('Ids of items which have focus.'),
-});
-export type Attention = z.infer<typeof Attention>;
-
 /**
  * Provides for a plugin that can manage the app navigation.
  */
@@ -141,7 +133,10 @@ export const partLength = (layout: LayoutParts | undefined, part: LayoutPart | u
 // Intents
 //
 
-const NAVIGATION_ACTION = 'dxos.org/plugin/navigation';
+const NAVIGATION_PLUGIN = 'dxos.org/plugin/navigation';
+
+const NAVIGATION_ACTION = `${NAVIGATION_PLUGIN}/action`;
+
 export enum NavigationAction {
   OPEN = `${NAVIGATION_ACTION}/open`,
   ADD_TO_ACTIVE = `${NAVIGATION_ACTION}/add-to-active`,

package/src/plugins/common/translations.ts

@@ -4,8 +4,9 @@
 
 import { z } from 'zod';
 
-import type { Plugin } from '../PluginHost';
+import { type Plugin } from '../plugin-host';
 
+// TODO(burdon): Replace zed with effect.
 export const ResourceKey = z.union([z.string(), z.record(z.any())]);
 export type ResourceKey = z.infer<typeof ResourceKey>;
 
@@ -26,13 +27,6 @@ export type TranslationsProvides = {
   translations: Readonly<Resource[]>;
 };
 
-// TODO(wittjosiah): Add TranslationsProvides.
-// export type TranslationsProvides = {
-//   translations: {
-//     t: TFunction;
-//   };
-// };
-
 /**
  * Type guard for translation plugins.
  */

package/src/plugins/helpers.ts

@@ -2,14 +2,16 @@
 // Copyright 2023 DXOS.org
 //
 
+import { Context, type DisposeCallback } from '@dxos/context';
 import { raise } from '@dxos/debug';
+import { invariant } from '@dxos/invariant';
 
-import { type Plugin } from './PluginHost';
+import { type Plugin, type PluginDefinition } from './plugin-host';
 
 /**
- * Define a plugin
+ * Resolvers allow different instances of plugins to provide a particular capability.
  */
-export const definePlugin = <TProvides>(plugin: Plugin<TProvides>): Plugin<TProvides> => plugin;
+export type PluginResolver<T> = (plugin: Plugin) => Plugin<T> | undefined;
 
 /**
  * Find a plugin by ID.
@@ -30,10 +32,8 @@ export const getPlugin = <T>(plugins: Plugin[], id: string): Plugin<T> => {
 /**
  * Filter a list of plugins to only those that match a predicate.
  */
-export const filterPlugins = <T>(
-  plugins: Plugin[],
-  predicate: (plugin: Plugin) => Plugin<T> | undefined,
-): Plugin<T>[] => plugins.map((plugin) => predicate(plugin)).filter((plugin): plugin is Plugin<T> => !!plugin);
+export const filterPlugins = <T>(plugins: Plugin[], predicate: PluginResolver<T>): Plugin<T>[] =>
+  plugins.map((plugin) => predicate(plugin)).filter((plugin): plugin is Plugin<T> => !!plugin);
 
 /**
  * Resolves a plugin by predicate.
@@ -42,7 +42,51 @@ export const filterPlugins = <T>(
  * import { parseIntentPlugin, resolvePlugin } from '@dxos/app-framework';
  * const intentPlugin = resolvePlugin(plugins, parseIntentPlugin);
  */
-export const resolvePlugin = <T>(
-  plugins: Plugin[],
-  predicate: (plugin: Plugin) => Plugin<T> | undefined,
-): Plugin<T> | undefined => filterPlugins(plugins, predicate)[0];
+export const resolvePlugin = <T>(plugins: Plugin[], predicate: PluginResolver<T>): Plugin<T> | undefined =>
+  filterPlugins(plugins, predicate)[0];
+
+class PluginContext {
+  // TODO(burdon): Use Resource (@dima)?
+  public readonly ctx = new Context();
+
+  private _plugins?: Plugin[];
+
+  init(plugins: Plugin[]) {
+    this._plugins = plugins;
+  }
+
+  getPlugin<T>(id: string): Plugin<T> {
+    invariant(this._plugins);
+    return getPlugin(this._plugins, id);
+  }
+
+  resolvePlugin<T>(resolver: PluginResolver<T>): Plugin<T>;
+  resolvePlugin<T>(resolver: PluginResolver<T>, required = false): Plugin<T> | undefined {
+    invariant(this._plugins, 'context not initialized');
+    const plugin = resolvePlugin(this._plugins, resolver);
+    if (required && !plugin) {
+      // TODO(burdon): Resolver should have a name.
+      throw new Error('Plugin not found.');
+    }
+
+    return plugin;
+  }
+
+  onDispose(cb: DisposeCallback) {
+    this.ctx.onDispose(cb);
+  }
+
+  dispose() {
+    void this.ctx.dispose();
+  }
+}
+
+/**
+ * Plugin helper with dependency injection and life-cycle support.
+ */
+export const definePlugin = <Provides>(
+  cb: (context: PluginContext) => PluginDefinition<Provides>,
+): (() => PluginDefinition<Provides>) => {
+  const context = new PluginContext();
+  return () => cb(context);
+};

package/src/plugins/index.ts

@@ -5,6 +5,7 @@
 export * from './common';
 export * from './helpers';
 
-export * from './IntentPlugin';
-export * from './PluginHost';
-export * from './SurfacePlugin';
+export * from './plugin-intent';
+export * from './plugin-host';
+export * from './plugin-settings';
+export * from './plugin-surface';

package/src/plugins/plugin-host/HostPlugin.tsx

@@ -0,0 +1,96 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { type ReactNode } from 'react';
+
+import { LocalStorageStore } from '@dxos/local-storage';
+
+import { PluginContainer } from './PluginContainer';
+import { type PluginContext, PluginProvider } from './PluginContext';
+import { type Plugin, type PluginDefinition, type PluginMeta } from './plugin';
+import { ErrorBoundary } from '../plugin-surface';
+
+export type HostPluginParams = {
+  plugins: Record<string, () => Promise<PluginDefinition>>;
+  // Ordered list of plugins.
+  meta: PluginMeta[];
+  core: string[];
+  defaults?: string[];
+  fallback?: ErrorBoundary['props']['fallback'];
+  placeholder?: ReactNode;
+};
+
+export type HostPluginProvides = {
+  plugins: PluginContext;
+};
+
+export const parsePluginHost = (plugin: Plugin) =>
+  (plugin.provides as HostPluginProvides).plugins ? (plugin as Plugin<HostPluginProvides>) : undefined;
+
+const HOST_PLUGIN = 'dxos.org/plugin/host';
+
+/**
+ * Bootstraps an application by initializing plugins and rendering root components.
+ */
+export const HostPlugin = ({
+  plugins,
+  meta,
+  core,
+  defaults = [],
+  fallback = DefaultFallback,
+  placeholder = null,
+}: HostPluginParams): PluginDefinition<HostPluginProvides> => {
+  const state = new LocalStorageStore<PluginContext>(HOST_PLUGIN, {
+    ready: false,
+    core,
+    enabled: [...defaults],
+    plugins: [],
+    available: meta.filter(({ id }) => !core.includes(id)),
+    // TODO(burdon): Functions should not be part of the settings type.
+    setPlugin: (id: string, enabled: boolean) => {
+      if (enabled) {
+        state.values.enabled.push(id);
+      } else {
+        const index = state.values.enabled.findIndex((enabled) => enabled === id);
+        index !== -1 && state.values.enabled.splice(index, 1);
+      }
+    },
+  });
+
+  // Register and load values.
+  state.prop({ key: 'enabled', type: LocalStorageStore.json<string[]>() });
+
+  return {
+    meta: {
+      id: HOST_PLUGIN,
+      name: 'Plugin host',
+    },
+    provides: {
+      plugins: state.values,
+      context: ({ children }) => {
+        return <PluginProvider value={state.values}>{children}</PluginProvider>;
+      },
+      root: () => {
+        return (
+          <ErrorBoundary fallback={fallback}>
+            <PluginContainer plugins={plugins} core={core} state={state.values} placeholder={placeholder} />
+          </ErrorBoundary>
+        );
+      },
+    },
+  };
+};
+
+/**
+ * Fallback does not use tailwind or theme.
+ */
+const DefaultFallback = ({ error }: { error: Error }) => {
+  return (
+    <div style={{ padding: '1rem' }}>
+      {/* TODO(wittjosiah): Link to docs for replacing default. */}
+      <h1 style={{ fontSize: '1.2rem', fontWeight: 700, margin: '0.5rem 0' }}>{error.message}</h1>
+      <pre>{error.stack}</pre>
+    </div>
+  );
+};

package/src/plugins/plugin-host/PluginContainer.tsx

@@ -0,0 +1,120 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { type JSX, type FC, type PropsWithChildren, type ReactNode, useEffect, useState } from 'react';
+
+import { log } from '@dxos/log';
+
+import { type HostPluginParams } from './HostPlugin';
+import { type PluginContext } from './PluginContext';
+import { type Plugin, type PluginDefinition, type PluginProvides } from './plugin';
+
+export type PluginContainerProps = Pick<HostPluginParams, 'core'> & {
+  plugins: Record<string, () => Promise<PluginDefinition>>;
+  state: PluginContext;
+  placeholder: ReactNode;
+};
+
+/**
+ * Root component initializes plugins.
+ */
+export const PluginContainer = ({ plugins: definitions, core, state, placeholder }: PluginContainerProps) => {
+  const [error, setError] = useState<unknown>();
+
+  useEffect(() => {
+    log('initializing plugins', { enabled: state.enabled });
+    const t = setTimeout(async () => {
+      try {
+        const enabledIds = [...core, ...state.enabled];
+        const enabled = await Promise.all(
+          enabledIds
+            .map((id) => definitions[id])
+            // If local storage indicates a plugin is enabled, but it is not available, ignore it.
+            .filter((definition): definition is () => Promise<PluginDefinition> => Boolean(definition))
+            .map((definition) => definition()),
+        );
+
+        const plugins = await Promise.all(
+          enabled.map(async (definition) => {
+            const plugin = await initializePlugin(definition).catch((err) => {
+              log.error('Failed to initialize plugin:', { id: definition.meta.id, err });
+            });
+
+            log('initialized', { plugin: definition.meta.id });
+            return plugin;
+          }),
+        );
+
+        const initialized = plugins.filter((plugin): plugin is Plugin => Boolean(plugin));
+        log('plugins initialized', { plugins: initialized });
+
+        await Promise.all(enabled.map((plugin) => plugin.ready?.(initialized)));
+        log('plugins ready', { plugins: initialized });
+
+        state.plugins = initialized;
+        state.ready = true;
+      } catch (err) {
+        setError(err);
+      }
+    });
+
+    return () => {
+      clearTimeout(t);
+      state.ready = false;
+      // TODO(wittjosiah): Does this ever need to be called prior to having dynamic plugins?
+      // void Promise.all(enabled.map((definition) => definition.unload?.()));
+    };
+  }, []);
+
+  if (error) {
+    throw error;
+  }
+
+  if (!state.ready) {
+    return <>{placeholder}</>;
+  }
+
+  const ComposedContext = composeContext(state.plugins);
+
+  return <ComposedContext>{rootComponents(state.plugins)}</ComposedContext>;
+};
+
+/**
+ * Resolve a `PluginDefinition` into a fully initialized `Plugin`.
+ */
+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>
+  ));
+};

package/src/plugins/{PluginHost → plugin-host}/PluginContext.tsx

@@ -2,11 +2,12 @@
 // Copyright 2024 DXOS.org
 //
 
-import { type Context, type Provider, createContext, useContext, useMemo } from 'react';
+import { createContext, useContext, useMemo } from 'react';
 
+import { raise } from '@dxos/debug';
 import { nonNullable } from '@dxos/util';
 
-import { type Plugin } from './plugin';
+import { type Plugin, type PluginMeta } from './plugin';
 import { findPlugin, resolvePlugin } from '../helpers';
 
 export type PluginContext = {
@@ -32,30 +33,24 @@ export type PluginContext = {
 
   /**
    * All available plugins.
+   * NOTE: This is metadata rather than just ids because it includes plugins which have not been fully loaded yet.
    */
-  // This is metadata rather then just ids because it includes plugins which have not been fully loaded yet.
-  available: Plugin['meta'][];
+  available: PluginMeta[];
 
   /**
    * Mark plugin as enabled.
    * Requires reload to take effect.
    */
+  // TODO(burdon): Functions should not be part of the settings type.
   setPlugin: (id: string, enabled: boolean) => void;
 };
 
-const PluginContext: Context<PluginContext> = createContext<PluginContext>({
-  ready: false,
-  core: [],
-  enabled: [],
-  plugins: [],
-  available: [],
-  setPlugin: () => {},
-});
+const PluginContext = createContext<PluginContext | undefined>(undefined);
 
 /**
  * Get all plugins.
  */
-export const usePlugins = (): PluginContext => useContext(PluginContext);
+export const usePlugins = (): PluginContext => useContext(PluginContext) ?? raise(new Error('Missing PluginContext'));
 
 /**
  * Get a plugin by ID.
@@ -81,4 +76,4 @@ export const useResolvePlugins = <T,>(predicate: (plugin: Plugin) => Plugin<T> |
   return useMemo(() => plugins.map(predicate).filter(nonNullable), [plugins, predicate]);
 };
 
-export const PluginProvider: Provider<PluginContext> = PluginContext.Provider;
+export const PluginProvider = PluginContext.Provider;

package/src/plugins/{PluginHost → plugin-host}/index.ts

@@ -3,5 +3,6 @@
 //
 
 export * from './plugin';
+
+export * from './HostPlugin';
 export * from './PluginContext';
-export * from './PluginHost';

package/src/plugins/{PluginHost → plugin-host}/plugin.test.ts

@@ -2,11 +2,10 @@
 // Copyright 2023 DXOS.org
 //
 
-import { expect } from 'chai';
 import { type FC } from 'react';
+import { describe, expect, test } from 'vitest';
 
 import { log } from '@dxos/log';
-import { describe, test } from '@dxos/test';
 
 import { type Plugin } from './plugin';
 

package/src/plugins/{PluginHost → plugin-host}/plugin.ts

@@ -2,7 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
-import type { IconProps } from '@phosphor-icons/react';
 import type { FC, PropsWithChildren } from 'react';
 
 /**
@@ -21,60 +20,61 @@ export type PluginProvides<TProvides> = TProvides & {
   root?: FC<PropsWithChildren>;
 };
 
+export type PluginMeta = {
+  /**
+   * Globally unique ID.
+   *
+   * Expected to be in the form of a valid URL.
+   *
+   * @example dxos.org/plugin/example
+   */
+  id: string;
+
+  /**
+   * Short ID for use in URLs.
+   *
+   * NOTE: This is especially experimental and likely to change.
+   */
+  // TODO(wittjosiah): How should these be managed?
+  shortId?: string;
+
+  /**
+   * Human-readable name.
+   */
+  name?: string;
+
+  /**
+   * Short description of plugin functionality.
+   */
+  description?: string;
+
+  /**
+   * URL of home page.
+   */
+  homePage?: string;
+
+  /**
+   * URL of source code.
+   */
+  source?: string;
+
+  /**
+   * Tags to help categorize the plugin.
+   */
+  tags?: string[];
+
+  /**
+   * A grep-able symbol string which can be resolved to an icon asset by @ch-ui/icons, via @ch-ui/vite-plugin-icons.
+   */
+  icon?: string;
+};
+
 /**
  * A unit of containment of modular functionality that can be provided to an application.
  * Plugins provide things like components, state, actions, etc. to the application.
  */
 export type Plugin<TProvides = {}> = {
-  meta: {
-    /**
-     * Globally unique ID.
-     *
-     * Expected to be in the form of a valid URL.
-     *
-     * @example dxos.org/plugin/example
-     */
-    id: string;
-
-    /**
-     * Short ID for use in URLs.
-     *
-     * NOTE: This is especially experimental and likely to change.
-     */
-    // TODO(wittjosiah): How should these be managed?
-    shortId?: string;
-
-    /**
-     * Human-readable name.
-     */
-    name?: string;
-
-    /**
-     * Short description of plugin functionality.
-     */
-    description?: string;
-
-    /**
-     * URL of home page.
-     */
-    homePage?: string;
-
-    /**
-     * Tags to help categorize the plugin.
-     */
-    tags?: string[];
-
-    /**
-     * Component to render icon for the plugin when displayed in a list.
-     * @deprecated
-     */
-    iconComponent?: FC<IconProps>;
-
-    /**
-     * A grep-able symbol string which can be resolved to an icon asset by @ch-ui/icons, via @ch-ui/vite-plugin-icons.
-     */
-    iconSymbol?: string;
-  };
+  meta: PluginMeta;
 
   /**
    * Capabilities provided by the plugin.
@@ -114,8 +114,6 @@ export type PluginDefinition<TProvides = {}, TInitializeProvides = {}> = Omit<Pl
   unload?: () => Promise<void>;
 };
 
-export const pluginMeta = (meta: Plugin['meta']) => meta;
-
 type LazyPlugin<T> = () => Promise<{ default: (props: T) => PluginDefinition }>;
 
 export namespace Plugin {

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

@@ -17,8 +17,8 @@ import {
   parseIntentResolverPlugin,
   IntentAction,
 } from './provides';
-import type { PluginDefinition } from '../PluginHost';
 import { filterPlugins, findPlugin } from '../helpers';
+import { type PluginDefinition } from '../plugin-host';
 
 const EXECUTION_LIMIT = 1000;
 const HISTORY_LIMIT = 100;
@@ -27,7 +27,7 @@ const HISTORY_LIMIT = 100;
  * Allows plugins to register intent handlers and routes sent intents to the appropriate plugin.
  * Inspired by https://developer.android.com/reference/android/content/Intent.
  */
-const IntentPlugin = (): PluginDefinition<IntentPluginProvides> => {
+export const IntentPlugin = (): PluginDefinition<IntentPluginProvides> => {
   const state = create<IntentContext>({
     dispatch: async () => ({}),
     undo: async () => ({}),
@@ -54,8 +54,7 @@ const IntentPlugin = (): PluginDefinition<IntentPluginProvides> => {
           }
 
           const plugin = findPlugin<IntentResolverProvides>(plugins, intent.plugin);
-          const result = plugin?.provides.intent.resolver(intent, plugins);
-          return result;
+          return plugin?.provides.intent.resolver(intent, plugins);
         }
 
         for (const entry of dynamicResolvers) {
@@ -150,5 +149,3 @@ const IntentPlugin = (): PluginDefinition<IntentPluginProvides> => {
     },
   };
 };
-
-export default IntentPlugin;

package/src/plugins/{IntentPlugin → plugin-intent}/index.ts

@@ -2,7 +2,11 @@
 // Copyright 2023 DXOS.org
 //
 
+import { IntentPlugin } from './IntentPlugin';
+
 export * from './intent';
 export * from './provides';
 
 export * from './IntentContext';
+
+export default IntentPlugin;

package/src/plugins/{IntentPlugin → plugin-intent}/intent.ts

@@ -4,7 +4,7 @@
 
 import type { MaybePromise } from '@dxos/util';
 
-import type { Plugin } from '../PluginHost';
+import type { Plugin } from '../plugin-host';
 
 export type IntentData<T extends Record<string, any> = Record<string, any>> = T & {
   /**

package/src/plugins/{IntentPlugin → plugin-intent}/provides.ts

@@ -4,7 +4,7 @@
 
 import { type IntentContext } from './IntentContext';
 import { type IntentResolver } from './intent';
-import { type Plugin } from '../PluginHost';
+import { type Plugin } from '../plugin-host';
 
 export type IntentResolverProvides = {
   intent: {
@@ -26,7 +26,10 @@ export const parseIntentResolverPlugin = (plugin: Plugin) =>
 // Intents
 //
 
-const INTENT_ACTION = 'dxos.org/plugin/intent';
+const INTENT_PLUGIN = 'dxos.org/plugin/intent';
+
+const INTENT_ACTION = `${INTENT_PLUGIN}/action`;
+
 export enum IntentAction {
   /**
    * Fired after an intent is dispatched if the intent is undoable.