@dxos/app-framework 0.6.14-main.2b6a0f3 → 0.6.14-main.f49f251

package/src/plugins/common/layout.ts

@@ -4,8 +4,8 @@
 
 import { z } from 'zod';
 
-import { type IntentData } from '../IntentPlugin';
-import type { Plugin } from '../PluginHost';
+import { type Plugin } from '../plugin-host';
+import { type IntentData } from '../plugin-intent';
 
 //
 // Provides
@@ -90,7 +90,10 @@ export const parseLayoutPlugin = (plugin: Plugin) => {
 // Intents
 //
 
-const LAYOUT_ACTION = 'dxos.org/plugin/layout';
+const LAYOUT_PLUGIN = 'dxos.org/plugin/layout';
+
+const LAYOUT_ACTION = `${LAYOUT_PLUGIN}/action`;
+
 export enum LayoutAction {
   SET_LAYOUT = `${LAYOUT_ACTION}/set-layout`,
   SET_LAYOUT_MODE = `${LAYOUT_ACTION}/set-layout-mode`,

package/src/plugins/common/metadata.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type Plugin } from '../PluginHost';
+import { type Plugin } from '../plugin-host';
 
 export type Metadata = Record<string, any>;
 

package/src/plugins/common/navigation.ts

@@ -5,8 +5,8 @@
 import { Schema as S } from '@effect/schema';
 import { z } from 'zod';
 
-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 = '+';
@@ -133,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/{PluginHost/PluginHost.tsx → plugin-host/HostPlugin.tsx}

@@ -9,9 +9,9 @@ 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 '../SurfacePlugin';
+import { ErrorBoundary } from '../plugin-surface';
 
-export type BootstrapPluginsParams = {
+export type HostPluginParams = {
   plugins: Record<string, () => Promise<PluginDefinition>>;
   // Ordered list of plugins.
   meta: PluginMeta[];
@@ -21,32 +21,33 @@ export type BootstrapPluginsParams = {
   placeholder?: ReactNode;
 };
 
-export type PluginHostProvides = {
+export type HostPluginProvides = {
   plugins: PluginContext;
 };
 
 export const parsePluginHost = (plugin: Plugin) =>
-  (plugin.provides as PluginHostProvides).plugins ? (plugin as Plugin<PluginHostProvides>) : undefined;
+  (plugin.provides as HostPluginProvides).plugins ? (plugin as Plugin<HostPluginProvides>) : undefined;
 
-const PLUGIN_HOST = 'dxos.org/plugin/host';
+const HOST_PLUGIN = 'dxos.org/plugin/host';
 
 /**
  * Bootstraps an application by initializing plugins and rendering root components.
  */
-export const PluginHost = ({
+export const HostPlugin = ({
   plugins,
   meta,
   core,
   defaults = [],
   fallback = DefaultFallback,
   placeholder = null,
-}: BootstrapPluginsParams): PluginDefinition<PluginHostProvides> => {
-  const state = new LocalStorageStore<PluginContext>(PLUGIN_HOST, {
+}: 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);
@@ -62,7 +63,7 @@ export const PluginHost = ({
 
   return {
     meta: {
-      id: PLUGIN_HOST,
+      id: HOST_PLUGIN,
       name: 'Plugin host',
     },
     provides: {

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

@@ -6,11 +6,11 @@ import React, { type JSX, type FC, type PropsWithChildren, type ReactNode, useEf
 
 import { log } from '@dxos/log';
 
+import { type HostPluginParams } from './HostPlugin';
 import { type PluginContext } from './PluginContext';
-import { type BootstrapPluginsParams } from './PluginHost';
 import { type Plugin, type PluginDefinition, type PluginProvides } from './plugin';
 
-export type PluginContainerProps = Pick<BootstrapPluginsParams, 'core'> & {
+export type PluginContainerProps = Pick<HostPluginParams, 'core'> & {
   plugins: Record<string, () => Promise<PluginDefinition>>;
   state: PluginContext;
   placeholder: ReactNode;

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

@@ -41,6 +41,7 @@ export type PluginContext = {
    * 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;
 };
 

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/{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.

package/src/plugins/plugin-settings/SettingsPlugin.tsx

@@ -0,0 +1,22 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { RootSettingsStore } from '@dxos/local-storage';
+
+import SettingsMeta from './meta';
+import { type SettingsPluginProvides } from './provides';
+import { type PluginDefinition } from '../plugin-host';
+
+export const SettingsPlugin = (): PluginDefinition<SettingsPluginProvides> => {
+  // Global settings singleton.
+  // TODO(burdon): Make settings storage extensible so that other plugins can decide the persistence of them.
+  const settingsStore = new RootSettingsStore();
+
+  return {
+    meta: SettingsMeta,
+    provides: {
+      settingsStore,
+    },
+  };
+};

package/src/plugins/plugin-settings/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { SettingsPlugin } from './SettingsPlugin';
+
+export * from './provides';
+
+export default SettingsPlugin;

package/src/plugins/plugin-settings/meta.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+const SettingsMeta = {
+  id: 'dxos.org/plugin/settings',
+};
+
+export default SettingsMeta;

package/src/plugins/plugin-settings/provides.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type SettingsStoreFactory, type SettingsValue } from '@dxos/local-storage';
+
+import { type Plugin } from '../plugin-host';
+
+export type SettingsProvides<T extends SettingsValue> = {
+  settings: T;
+};
+
+export type SettingsPluginProvides = {
+  settingsStore: SettingsStoreFactory;
+};
+
+export const parseSettingsPlugin = (plugin: Plugin) => {
+  return typeof (plugin.provides as any).settingsStore === 'object'
+    ? (plugin as Plugin<SettingsPluginProvides>)
+    : undefined;
+};
+
+const SETTINGS_PLUGIN = 'dxos.org/plugin/settings';
+
+const SETTINGS_ACTION = `${SETTINGS_PLUGIN}/action`;
+
+export enum SettingsAction {
+  OPEN = `${SETTINGS_ACTION}/open`,
+}

package/src/plugins/{SurfacePlugin → plugin-surface}/Surface.tsx

@@ -18,6 +18,7 @@ import React, {
 } from 'react';
 
 import { raise } from '@dxos/debug';
+import { log } from '@dxos/log';
 
 import { ErrorBoundary } from './ErrorBoundary';
 import { type SurfaceComponent, type SurfaceResult, useSurfaceRoot } from './SurfaceRootContext';
@@ -31,6 +32,11 @@ export type Direction = 'inline' | 'inline-reverse' | 'block' | 'block-reverse';
  * SurfaceProps are the props that are passed to the Surface component.
  */
 export type SurfaceProps = PropsWithChildren<{
+  /**
+   * Optional ID for debugging.
+   */
+  id?: string;
+
   /**
    * Role defines how the data should be rendered.
    */
@@ -82,40 +88,45 @@ export type SurfaceProps = PropsWithChildren<{
   [key: string]: unknown;
 }>;
 
+let count = 0;
+
 /**
  * A surface is a named region of the screen that can be populated by plugins.
  */
 export const Surface = memo(
-  forwardRef<HTMLElement, SurfaceProps>(({ role, name = role, fallback, placeholder, ...rest }, forwardedRef) => {
-    const props = { role, name, fallback, ...rest };
-    const { debugInfo } = useSurfaceRoot();
-
-    // Track debug info.
-    const [id] = useState<string>(Math.random().toString(36).slice(2));
-    useEffect(() => {
-      debugInfo?.set(id, { id, created: Date.now(), name, role, renderCount: 0 });
-      return () => {
-        debugInfo?.delete(id);
-      };
-    }, [id]);
-    if (debugInfo?.get(id)) {
-      debugInfo.get(id)!.renderCount++;
-    }
-
-    const context = useContext(SurfaceContext);
-    const data = props.data ?? ((name && context?.surfaces?.[name]?.data) || {});
-
-    const resolver = <SurfaceResolver {...props} ref={forwardedRef} />;
-    const suspense = placeholder ? <Suspense fallback={placeholder}>{resolver}</Suspense> : resolver;
-
-    return fallback ? (
-      <ErrorBoundary data={data} fallback={fallback}>
-        {suspense}
-      </ErrorBoundary>
-    ) : (
-      suspense
-    );
-  }),
+  forwardRef<HTMLElement, SurfaceProps>(
+    ({ id: _id, role, name = role, fallback, placeholder, ...rest }, forwardedRef) => {
+      const props = { role, name, fallback, ...rest };
+      const { debugInfo } = useSurfaceRoot();
+
+      // Track debug info.
+      const [id] = useState<string>(() => _id ?? `surface-${++count}`);
+      useEffect(() => {
+        debugInfo?.set(id, { id, created: Date.now(), name, role, renderCount: 0 });
+        return () => {
+          debugInfo?.delete(id);
+        };
+      }, [id]);
+
+      if (debugInfo?.get(id)) {
+        debugInfo.get(id)!.renderCount++;
+      }
+
+      const context = useContext(SurfaceContext);
+      const data = props.data ?? ((name && context?.surfaces?.[name]?.data) || {});
+
+      const resolver = <SurfaceResolver {...props} id={id} ref={forwardedRef} />;
+      const suspense = placeholder ? <Suspense fallback={placeholder}>{resolver}</Suspense> : resolver;
+
+      return fallback ? (
+        <ErrorBoundary data={data} fallback={fallback}>
+          {suspense}
+        </ErrorBoundary>
+      ) : (
+        suspense
+      );
+    },
+  ),
 );
 
 const SurfaceContext = createContext<SurfaceProps | undefined>(undefined);
@@ -123,6 +134,9 @@ const SurfaceContext = createContext<SurfaceProps | undefined>(undefined);
 export const useSurface = (): SurfaceProps =>
   useContext(SurfaceContext) ?? raise(new Error('Surface context not found'));
 
+/**
+ * Root surface component.
+ */
 const SurfaceResolver = forwardRef<HTMLElement, SurfaceProps>((props, forwardedRef) => {
   const { components } = useSurfaceRoot();
   const parent = useContext(SurfaceContext);
@@ -152,30 +166,30 @@ const resolveNodes = (
     ...props.data,
   };
 
-  const nodes = Object.entries(components)
+  const candidates = Object.entries(components)
     .map(([key, component]): [string, SurfaceResult] | undefined => {
+      // TODO(burdon): Avoid variable return types in plugin contract.
       const result = component({ ...props, data }, forwardedRef);
       if (!result || typeof result !== 'object') {
         return undefined;
       }
 
-      return 'node' in result ? [key, result] : isValidElement(result) ? [key, { node: result }] : undefined;
-    })
-    .filter((result): result is [string, SurfaceResult] => Boolean(result))
-    .sort(([, a], [, b]) => {
-      const aDisposition = a.disposition ?? 'default';
-      const bDisposition = b.disposition ?? 'default';
-      if (aDisposition === bDisposition) {
-        return 0;
-      } else if (aDisposition === 'hoist' || bDisposition === 'fallback') {
-        return -1;
-      } else if (bDisposition === 'hoist' || aDisposition === 'fallback') {
-        return 1;
+      // Normalize tuple.
+      if ('node' in result) {
+        return [key, result];
+      } else if (isValidElement(result)) {
+        return [key, { node: result }];
+      } else {
+        log.warn('invalid result', { result });
+        return undefined;
       }
-
-      return 0;
     })
-    .map(([key, result]) => <Fragment key={key}>{result.node}</Fragment>);
+    .filter((result): result is [string, SurfaceResult] => Boolean(result))
+    .sort(([, { disposition: a = 'default' }], [, { disposition: b = 'default' }]) => {
+      return a === b ? 0 : a === 'hoist' || b === 'fallback' ? -1 : b === 'hoist' || a === 'fallback' ? 1 : 0;
+    });
 
+  // TODO(burdon): Does this prematurely process the node?
+  const nodes = candidates.map(([key, result]) => <Fragment key={key}>{result.node}</Fragment>);
   return props.limit ? nodes.slice(0, props.limit) : nodes;
 };

package/src/plugins/{SurfacePlugin/plugin.tsx → plugin-surface/SurfacePlugin.tsx}

@@ -9,13 +9,13 @@ import { create } from '@dxos/echo-schema';
 import { SurfaceProvider, type SurfaceRootContext } from './SurfaceRootContext';
 import SurfaceMeta from './meta';
 import { parseSurfacePlugin, type SurfacePluginProvides } from './provides';
-import { type PluginDefinition } from '../PluginHost';
 import { filterPlugins } from '../helpers';
+import { type PluginDefinition } from '../plugin-host';
 
 /**
  * Provides a registry of surface components.
  */
-const SurfacePlugin = (): PluginDefinition<SurfacePluginProvides> => {
+export const SurfacePlugin = (): PluginDefinition<SurfacePluginProvides> => {
   const state = create<SurfaceRootContext>({ components: {}, debugInfo: new Map() });
 
   return {
@@ -31,5 +31,3 @@ const SurfacePlugin = (): PluginDefinition<SurfacePluginProvides> => {
     },
   };
 };
-
-export default SurfacePlugin;

package/src/plugins/{SurfacePlugin → plugin-surface}/index.ts

@@ -2,9 +2,13 @@
 // Copyright 2023 DXOS.org
 //
 
+import { SurfacePlugin } from './SurfacePlugin';
+
 export * from './helpers';
 export * from './provides';
 
 export * from './ErrorBoundary';
 export * from './Surface';
 export * from './SurfaceRootContext';
+
+export default SurfacePlugin;

package/src/plugins/{SurfacePlugin → plugin-surface}/provides.ts

@@ -3,8 +3,9 @@
 //
 
 import { type SurfaceComponent, type SurfaceRootContext } from './SurfaceRootContext';
-import { type Plugin } from '../PluginHost';
+import { type Plugin } from '../plugin-host';
 
+// TODO(burdon): Predicate based providers?
 export type SurfaceProvides = {
   surface: {
     /**