@dxos/app-framework 0.7.4 → 0.7.5-labs.071a3e2

package/src/plugins/helpers.ts

@@ -1,92 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { Context, type DisposeCallback } from '@dxos/context';
-import { raise } from '@dxos/debug';
-import { invariant } from '@dxos/invariant';
-
-import { type Plugin, type PluginDefinition } from './plugin-host';
-
-/**
- * Resolvers allow different instances of plugins to provide a particular capability.
- */
-export type PluginResolver<T> = (plugin: Plugin) => Plugin<T> | undefined;
-
-/**
- * Find a plugin by ID.
- */
-export const findPlugin = <T>(plugins: Plugin[], id: string): Plugin<T> | undefined => {
-  return plugins.find(
-    (plugin) => plugin.meta.id === id || (typeof plugin.meta.shortId === 'string' && plugin.meta.shortId === id),
-  ) as Plugin<T>;
-};
-
-/**
- * Find a plugin by ID, or raise an error if not found.
- */
-export const getPlugin = <T>(plugins: Plugin[], id: string): Plugin<T> => {
-  return findPlugin(plugins, id) ?? raise(new Error(`Plugin not found: ${id}`));
-};
-
-/**
- * Filter a list of plugins to only those that match a predicate.
- */
-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.
- *
- * @example
- * import { parseIntentPlugin, resolvePlugin } from '@dxos/app-framework';
- * const intentPlugin = resolvePlugin(plugins, parseIntentPlugin);
- */
-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

@@ -1,11 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-export * from './common';
-export * from './helpers';
-
-export * from './plugin-intent';
-export * from './plugin-host';
-export * from './plugin-settings';
-export * from './plugin-surface';

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

@@ -1,96 +0,0 @@
-//
-// 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

@@ -1,120 +0,0 @@
-//
-// 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/plugin-host/PluginContext.tsx

@@ -1,79 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { createContext, useContext, useMemo } from 'react';
-
-import { raise } from '@dxos/debug';
-import { nonNullable } from '@dxos/util';
-
-import { type Plugin, type PluginMeta } from './plugin';
-import { findPlugin, resolvePlugin } from '../helpers';
-
-export type PluginContext = {
-  /**
-   * All plugins are ready.
-   */
-  ready: boolean;
-
-  /**
-   * Core plugins.
-   */
-  core: string[];
-
-  /**
-   * Ids of plugins which are enabled on this device.
-   */
-  enabled: string[];
-
-  /**
-   * Initialized and ready plugins.
-   */
-  plugins: Plugin[];
-
-  /**
-   * All available plugins.
-   * NOTE: This is metadata rather than just ids because it includes plugins which have not been fully loaded yet.
-   */
-  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 = createContext<PluginContext | undefined>(undefined);
-
-/**
- * Get all plugins.
- */
-export const usePlugins = (): PluginContext => useContext(PluginContext) ?? raise(new Error('Missing 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);
-};
-
-/**
- * Resolve a collection of plugins by predicate.
- */
-export const useResolvePlugins = <T,>(predicate: (plugin: Plugin) => Plugin<T> | undefined): Plugin<T>[] => {
-  const { plugins } = usePlugins();
-  return useMemo(() => plugins.map(predicate).filter(nonNullable), [plugins, predicate]);
-};
-
-export const PluginProvider = PluginContext.Provider;

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

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

package/src/plugins/plugin-host/plugin.test.ts

@@ -1,158 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { type FC } from 'react';
-import { describe, expect, test } from 'vitest';
-
-import { log } from '@dxos/log';
-
-import { type Plugin } from './plugin';
-
-// eslint-disable-next-line unused-imports/no-unused-vars
-export interface Interface<T> {
-  key: string;
-}
-
-type InterfaceDef<T> = {
-  key: Interface<T>;
-  impl: T;
-};
-
-export const provide = <T>(key: Interface<T>, impl: T): InterfaceDef<T> => ({ key, impl });
-
-export type PluginProps = {
-  provides?: InterfaceDef<any>[];
-};
-
-export class TestPlugin {
-  readonly _interfaces = new Map<string, any>();
-  constructor({ provides }: PluginProps) {
-    provides?.forEach(({ key, impl }) => this._interfaces.set(key.key, impl));
-  }
-
-  getInterface = <T>(key: Interface<T>): T | undefined => this._interfaces.get(key.key);
-}
-
-const getInterfaces = <T>(plugins: TestPlugin[], key: Interface<T>): T[] =>
-  plugins.map((plugin) => plugin.getInterface(key)).filter(Boolean) as any;
-
-//
-// Interfaces allow shared typesafe contracts between plugins.
-// The system might define common contracts (e.g., Printable); others would be defined by individual plugins.
-// This allows parts of the system to find interfaces across all plugins to enable loosely coupled actions
-// (separate from broadcast events) or requests for information.
-//
-
-export interface Printable {
-  print: (data: any | undefined) => void;
-}
-
-export const Printable: Interface<Printable> = { key: 'printable' };
-
-export interface Selectable {
-  selection: () => string | undefined;
-  select: (object?: { id: string | undefined }) => void;
-}
-
-export const Selectable: Interface<Selectable> = { key: 'selectable' };
-
-// NOTE: Would allow Stack to define a contract for plugins that have embeddable content.
-export type Section = FC<{ object: any; onSelect: (object: string | undefined) => void }>;
-
-export const Section: Interface<Section> = { key: 'list' };
-
-//
-// Plugin defs
-//
-
-// TODO(burdon): Tie to declarative manifest.
-// {
-//   Printable: { print: (data: any) => console.log(data) }
-// }
-//
-
-const plugin1 = new TestPlugin({
-  provides: [
-    provide(Printable, {
-      print: (data: any | undefined) => log(data),
-    }),
-
-    provide(Selectable, {
-      selection: () => undefined,
-      select: (data: any) => {}, // TODO(burdon): Update plugin state.
-    }),
-
-    // provide(Section, ({ object }) => <div>{JSON.stringify(object)}</div>),
-  ],
-});
-
-const plugin2 = new TestPlugin({
-  provides: [
-    provide(Printable, {
-      print: (data: any) => log(data),
-    }),
-  ],
-});
-
-const plugin3 = new TestPlugin({});
-
-describe('Plugins', () => {
-  const plugins = [plugin1, plugin2, plugin3];
-
-  test('invocation', () => {
-    // Invoke against all plugins that provide interface.
-    expect(getInterfaces(plugins, Printable)).to.have.length(2);
-    getInterfaces(plugins, Printable).forEach((i) => i.print({}));
-  });
-
-  test('symbols', () => {
-    const s1 = Symbol.for('s1');
-    const s2 = Symbol.for('s1');
-    expect(s1).to.be.eq(s2);
-
-    const map = new Map();
-    map.set(s1, true);
-    map.set(s2, false);
-    expect(map.get(s1)).to.be.false;
-  });
-
-  test('filter', () => {
-    type Provides1 = {
-      test1: {};
-    };
-
-    type Provides2 = {
-      test2: {};
-    };
-
-    const p1: Plugin<Provides1> = {
-      meta: { id: 'example.com/plugin/plugin-1' },
-      provides: {
-        test1: {},
-      },
-    };
-
-    const p2: Plugin<Provides2> = {
-      meta: { id: 'example.com/plugin/plugin-2' },
-      provides: {
-        test2: {},
-      },
-    };
-
-    const plugins: Plugin[] = [p1, p2];
-
-    const matching = plugins.filter((plugin) => true);
-    expect(matching).to.have.length(2);
-  });
-});
-
-// eslint-disable-next-line unused-imports/no-unused-vars
-// const StackContainer: FC<{}> = () => {
-//   const StackSection = plugin1.getInterface(Section)!;
-//   const selected = plugin1.getInterface(Selectable)?.selection();
-
-//   return (
-//     <StackSection object={selected} onSelect={(object) => plugin1.getInterface(Selectable)?.select({ id: object })} />
-//   );
-// };

package/src/plugins/plugin-host/plugin.ts

@@ -1,126 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import type { FC, PropsWithChildren } from 'react';
-
-/**
- * Capabilities provided by a plugin.
- * The base surface capabilities are always included.
- */
-export type PluginProvides<TProvides> = TProvides & {
-  /**
-   * React Context which is wrapped around the application to enable any hooks the plugin may provide.
-   */
-  context?: FC<PropsWithChildren>;
-
-  /*
-   * React component which is rendered at the root of the application.
-   */
-  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: PluginMeta;
-
-  /**
-   * Capabilities provided by the plugin.
-   */
-  provides: PluginProvides<TProvides>;
-};
-
-/**
- * Plugin definitions extend the base `Plugin` interface with additional lifecycle methods.
- */
-export type PluginDefinition<TProvides = {}, TInitializeProvides = {}> = Omit<Plugin, 'provides'> & {
-  /**
-   * Capabilities provided by the plugin.
-   */
-  provides?: Plugin<TProvides>['provides'];
-
-  /**
-   * Initialize any async behavior required by the plugin.
-   *
-   * @return Capabilities provided by the plugin which are merged with base capabilities.
-   */
-  initialize?: () => Promise<PluginProvides<TInitializeProvides> | void>;
-
-  /**
-   * Called once all plugins have been initialized.
-   * This is the place to do any initialization which requires other plugins to be ready.
-   *
-   * @param plugins All plugins which successfully initialized.
-   */
-  // TODO(wittjosiah): Rename `ready` to a verb?
-  ready?: (plugins: Plugin[]) => Promise<void>;
-
-  /**
-   * Called when the plugin is unloaded.
-   * This is the place to do any cleanup required by the plugin.
-   */
-  unload?: () => Promise<void>;
-};
-
-type LazyPlugin<T> = () => Promise<{ default: (props: T) => PluginDefinition }>;
-
-export namespace Plugin {
-  export const lazy = <T>(p: LazyPlugin<T>, props?: T) => {
-    return () =>
-      p().then(({ default: definition }) => {
-        return definition(props as T);
-      });
-  };
-}