@dxos/app-framework 0.7.4 → 0.7.5-feature-compute.4d9d99a

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);
-      });
-  };
-}

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

@@ -1,49 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { type Context, createContext, useContext, type Provider } from 'react';
-import { useEffect } from 'react';
-
-import type { UnsubscribeCallback } from '@dxos/async';
-
-import type { Intent, IntentDispatcher, IntentResolver, IntentResult } from './intent';
-
-export type IntentExecution = {
-  intent: Intent;
-  result: IntentResult;
-};
-
-export type IntentContext = {
-  dispatch: IntentDispatcher;
-  undo: () => Promise<IntentResult | void>;
-  history: IntentExecution[][];
-  registerResolver: (pluginId: string, resolver: IntentResolver) => UnsubscribeCallback;
-};
-
-const IntentContext: Context<IntentContext> = createContext<IntentContext>({
-  dispatch: async () => ({}),
-  undo: async () => ({}),
-  history: [],
-  registerResolver: () => () => {},
-});
-
-/**
- * @deprecated Prefer granular hooks.
- */
-// TODO(burdon): Remove. Use useIntentDispatcher.
-export const useIntent = () => useContext(IntentContext);
-
-export const useIntentDispatcher = (): IntentDispatcher => {
-  const { dispatch } = useIntent();
-  return dispatch;
-};
-
-export const useIntentResolver = (plugin: string, resolver: IntentResolver) => {
-  const { registerResolver } = useIntent();
-  useEffect(() => {
-    return registerResolver(plugin, resolver);
-  }, [plugin, resolver]);
-};
-
-export const IntentProvider: Provider<IntentContext> = IntentContext.Provider;

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

@@ -1,151 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import React from 'react';
-
-import { create } from '@dxos/live-object';
-import { log } from '@dxos/log';
-
-import { type IntentContext, type IntentExecution, IntentProvider } from './IntentContext';
-import { isUndoable } from './helpers';
-import type { Intent, IntentResolver } from './intent';
-import IntentMeta from './meta';
-import {
-  IntentAction,
-  type IntentPluginProvides,
-  type IntentResolverProvides,
-  parseIntentResolverPlugin,
-} from './provides';
-import { filterPlugins, findPlugin } from '../helpers';
-import { type PluginDefinition } from '../plugin-host';
-
-const EXECUTION_LIMIT = 1000;
-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.
- */
-export const IntentPlugin = (): PluginDefinition<IntentPluginProvides> => {
-  const state = create<IntentContext>({
-    dispatch: async () => ({}),
-    undo: async () => ({}),
-    history: [],
-    registerResolver: () => () => {},
-  });
-
-  const dynamicResolvers = new Set<{ plugin: string; resolver: IntentResolver }>();
-
-  return {
-    meta: IntentMeta,
-    ready: async (plugins) => {
-      // Dispatch intent to associated plugin.
-      const dispatch = async (intent: Intent) => {
-        log('dispatch', { action: intent.action, intent });
-        if (intent.plugin) {
-          for (const entry of dynamicResolvers) {
-            if (entry.plugin === intent.plugin) {
-              const result = await entry.resolver(intent, plugins);
-              if (result) {
-                return result;
-              }
-            }
-          }
-
-          const plugin = findPlugin<IntentResolverProvides>(plugins, intent.plugin);
-          return plugin?.provides.intent.resolver(intent, plugins);
-        }
-
-        for (const entry of dynamicResolvers) {
-          const result = await entry.resolver(intent, plugins);
-          if (result) {
-            return result;
-          }
-        }
-
-        // Return resolved value from first plugin that handles the intent.
-        for (const plugin of filterPlugins(plugins, parseIntentResolverPlugin)) {
-          const result = await plugin.provides.intent.resolver(intent, plugins);
-          if (result) {
-            return result;
-          }
-        }
-
-        // https://vitejs.dev/guide/env-and-mode#env-variables
-        // TODO(wittjosiah): How to handle this more generically?
-        if (import.meta?.env?.DEV) {
-          log.warn('No plugin found to handle intent', intent);
-        }
-      };
-
-      // Sequentially dispatch array of invents.
-      const dispatchChain = async (intentOrArray: Intent | Intent[], depth = 0) => {
-        if (depth > EXECUTION_LIMIT) {
-          return {
-            error: new Error(
-              `Intent execution limit exceeded (${EXECUTION_LIMIT} iterations). This is likely due to an infinite loop within intent resolvers.`,
-            ),
-          };
-        }
-
-        const executionResults: IntentExecution[] = [];
-        const chain = Array.isArray(intentOrArray) ? intentOrArray : [intentOrArray];
-        for (const intent of chain) {
-          const { result: prevResult } = executionResults.at(-1) ?? {};
-          const data = intent.data ? { result: prevResult?.data, ...intent.data } : prevResult?.data;
-          const result = await dispatch({ ...intent, data });
-
-          if (!result || result?.error) {
-            break;
-          }
-
-          executionResults.push({ intent, result });
-
-          // TODO(wittjosiah): How does undo work with returned intents?
-          result?.intents?.forEach((intents) => {
-            void dispatchChain(intents, depth + 1);
-          });
-        }
-
-        state.history.push(executionResults);
-        if (state.history.length > HISTORY_LIMIT) {
-          state.history.splice(0, state.history.length - HISTORY_LIMIT);
-        }
-
-        if (isUndoable(executionResults)) {
-          void dispatch({ action: IntentAction.SHOW_UNDO, data: { results: executionResults } });
-        }
-
-        return executionResults.at(-1)?.result;
-      };
-
-      const undo = async () => {
-        const last = state.history.findLastIndex(isUndoable);
-        const chain =
-          last !== -1 &&
-          state.history[last]?.map(({ intent, result }): Intent => {
-            const data = result.undoable?.data ? { ...intent.data, ...result.undoable.data } : intent.data;
-            return { ...intent, data, undo: true };
-          });
-        if (chain) {
-          const result = await dispatchChain(chain);
-          state.history = state.history.filter((_, index) => index !== last);
-          return result;
-        }
-      };
-
-      state.dispatch = dispatchChain;
-      state.undo = undo;
-      state.registerResolver = (plugin, resolver) => {
-        const entry = { plugin, resolver };
-        dynamicResolvers.add(entry);
-        return () => dynamicResolvers.delete(entry);
-      };
-    },
-    provides: {
-      intent: state,
-      context: ({ children }) => <IntentProvider value={state}>{children}</IntentProvider>,
-    },
-  };
-};

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

@@ -1,11 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { type IntentExecution } from './IntentContext';
-
-/**
- * Check if the chain of intents is undoable.
- */
-export const isUndoable = (chain: IntentExecution[]): boolean =>
-  chain.length > 0 && chain.every(({ result }) => result.undoable);

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

@@ -1,12 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { IntentPlugin } from './IntentPlugin';
-
-export * from './intent';
-export * from './provides';
-
-export * from './IntentContext';
-
-export default IntentPlugin;

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

@@ -1,101 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import type { MaybePromise } from '@dxos/util';
-
-import type { Plugin } from '../plugin-host';
-
-/**
- * Type of data returned from an intent.
- */
-export type IntentData<T extends Record<string, any> = Record<string, any>> = T & {
-  /**
-   * The data from the result of the previous intent.
-   */
-  // TODO(burdon): Chainable types? (see Effect hooks).
-  result?: any;
-};
-
-/**
- * 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;
-
-  /**
-   * Whether or not the intent is being undone.
-   */
-  undo?: boolean;
-
-  /**
-   * Any data needed to perform the desired action.
-   */
-  // TODO(burdon): Typed intents.
-  data?: IntentData;
-};
-
-export type IntentResult = {
-  /**
-   * The output of the action that was performed.
-   *
-   * If the intent is apart of a chain of intents, the data will be passed to the next intent.
-   */
-  data?: any;
-
-  /**
-   * If provided, the action will be undoable.
-   */
-  undoable?: {
-    /**
-     * Message to display to the user when indicating that the action can be undone.
-     */
-    message: string;
-
-    /**
-     * Will be merged with the original intent data when firing the undo intent.
-     */
-    data?: IntentData;
-  };
-
-  /**
-   * An error that occurred while performing the action.
-   *
-   * If the intent is apart of a chain of intents and an error occurs, the chain will be aborted.
-   */
-  error?: Error;
-
-  /**
-   * Other intent chains to be triggered.
-   */
-  intents?: Intent[][];
-};
-
-/**
- * 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.
- */
-// TODO(burdon): Generic/typed intents.
-export type IntentDispatcher = (intent: Intent | Intent[]) => Promise<IntentResult | void>;
-
-/**
- * Resolves an intent that was dispatched.
- * If the intent is not handled, nothing should be returned.
- *
- * @returns The result of the intent.
- */
-// TODO(burdon): All graph callback should use objects.
-export type IntentResolver = (intent: Intent, plugins: Plugin[]) => MaybePromise<IntentResult | void>;

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

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

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

@@ -1,38 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { type IntentContext } from './IntentContext';
-import { type IntentResolver } from './intent';
-import { type Plugin } from '../plugin-host';
-
-export type IntentResolverProvides = {
-  intent: {
-    resolver: IntentResolver;
-  };
-};
-
-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;
-
-//
-// Intents
-//
-
-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.
-   */
-  SHOW_UNDO = `${INTENT_ACTION}/show-undo`,
-}

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,29 +0,0 @@
-//
-// 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`,
-}