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

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?.({ plugins: 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,12 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { HostPlugin } from './HostPlugin';
-
-export * from './plugin';
-
-export * from './HostPlugin';
-export * from './PluginContext';
-
-export default HostPlugin;

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,133 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import type { FC, PropsWithChildren } from 'react';
-
-/**
- * Application context to be provided to plugin callbacks.
- */
-export type HostContext = {
-  plugins: Plugin[];
-};
-
-/**
- * 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?: (context: HostContext) => 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);
-      });
-  };
-}

package/src/plugins/plugin-intent/IntentPlugin.tsx

@@ -1,75 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { Effect } from 'effect';
-import React from 'react';
-
-import { create } from '@dxos/live-object';
-
-import { IntentProvider } from './IntentContext';
-import { createDispatcher, type AnyIntentResolver, type IntentContext } from './intent-dispatcher';
-import IntentMeta from './meta';
-import { type IntentPluginProvides, type ResolverDefinitions, parseIntentResolverPlugin } from './provides';
-import { filterPlugins } from '../helpers';
-import { type PluginDefinition } from '../plugin-host';
-
-const defaultEffect = () => Effect.fail(new Error('Intent runtime not ready'));
-const defaultPromise = () => Effect.runPromise(defaultEffect());
-
-/**
- * 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 = create<IntentContext>({
-    dispatch: defaultEffect,
-    dispatchPromise: defaultPromise,
-    undo: defaultEffect,
-    undoPromise: defaultPromise,
-    registerResolver: () => () => {},
-  });
-
-  return {
-    meta: IntentMeta,
-    ready: async ({ plugins }) => {
-      const resolvers = Object.fromEntries(
-        filterPlugins(plugins, parseIntentResolverPlugin).map((plugin): [string, AnyIntentResolver[]] => {
-          const resolvers = reduceResolvers(
-            plugin.provides.intent.resolvers({
-              plugins,
-              dispatch: (intent) => state.dispatch(intent),
-              dispatchPromise: (intent) => state.dispatchPromise(intent),
-              undo: () => state.undo(),
-              undoPromise: () => state.undoPromise(),
-              registerResolver: (id, resolver) => state.registerResolver(id, resolver),
-            }),
-          );
-          return [plugin.meta.id, resolvers];
-        }),
-      );
-      const { dispatch, dispatchPromise, undo, undoPromise, registerResolver } = createDispatcher(resolvers);
-
-      state.dispatch = dispatch;
-      state.dispatchPromise = dispatchPromise;
-      state.undo = undo;
-      state.undoPromise = undoPromise;
-      state.registerResolver = registerResolver;
-    },
-    provides: {
-      intent: state,
-      context: ({ children }) => <IntentProvider value={state}>{children}</IntentProvider>,
-    },
-  };
-};
-
-const reduceResolvers = (
-  definitions: ResolverDefinitions,
-  resolvers: AnyIntentResolver[] = [],
-): AnyIntentResolver[] => {
-  if (Array.isArray(definitions)) {
-    return definitions.reduce((acc: AnyIntentResolver[], definition) => reduceResolvers(definition, acc), resolvers);
-  }
-
-  return [...resolvers, definitions];
-};

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

@@ -1,11 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-export const INTENT_PLUGIN = 'dxos.org/plugin/intent';
-
-const IntentMeta = {
-  id: INTENT_PLUGIN,
-};
-
-export default IntentMeta;

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

@@ -1,26 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { type IntentContext, type AnyIntentResolver } from './intent-dispatcher';
-import { type HostContext, type Plugin } from '../plugin-host';
-
-type Context = HostContext & IntentContext;
-
-export type ResolverDefinitions = AnyIntentResolver | AnyIntentResolver[] | ResolverDefinitions[];
-
-export type IntentResolverProvides = {
-  intent: {
-    resolvers: (context: Context) => ResolverDefinitions;
-  };
-};
-
-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?.resolvers ? (plugin as Plugin<IntentResolverProvides>) : undefined;

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

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

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

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

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

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

@@ -1,34 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { S } from '@dxos/echo-schema';
-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;
-};
-
-export const SETTINGS_PLUGIN = 'dxos.org/plugin/settings';
-export const SETTINGS_ACTION = `${SETTINGS_PLUGIN}/action`;
-
-export namespace SettingsAction {
-  export class Open extends S.TaggedClass<Open>()(`${SETTINGS_ACTION}/open`, {
-    input: S.Struct({
-      plugin: S.optional(S.String),
-    }),
-    output: S.Void,
-  }) {}
-}