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

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`,
-}

package/src/plugins/plugin-surface/Surface.tsx

@@ -1,195 +0,0 @@
-//
-// Copyright 2022 DXOS.org
-//
-
-import React, {
-  Fragment,
-  type ForwardedRef,
-  type PropsWithChildren,
-  type ReactNode,
-  Suspense,
-  createContext,
-  forwardRef,
-  isValidElement,
-  memo,
-  useContext,
-  useEffect,
-  useState,
-} from 'react';
-
-import { raise } from '@dxos/debug';
-import { log } from '@dxos/log';
-
-import { ErrorBoundary } from './ErrorBoundary';
-import { type SurfaceComponent, type SurfaceResult, useSurfaceRoot } from './SurfaceRootContext';
-
-/**
- * Direction determines how multiple components are laid out.
- */
-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.
-   */
-  role?: string;
-
-  /**
-   * Names allow nested surfaces to be specified in the parent context, similar to a slot.
-   * Defaults to the value of `role` if not specified.
-   */
-  name?: string;
-
-  /**
-   * The data to be rendered by the surface.
-   */
-  data?: Record<string, unknown>;
-
-  /**
-   * Configure nested surfaces (indexed by the surface's `name`).
-   */
-  surfaces?: Record<string, Pick<SurfaceProps, 'data' | 'surfaces'>>;
-
-  /**
-   * If specified, the Surface will be wrapped in an error boundary.
-   * The fallback component will be rendered if an error occurs.
-   */
-  fallback?: ErrorBoundary['props']['fallback'];
-
-  /**
-   * If specified, the Surface will be wrapped in a suspense boundary.
-   * The placeholder component will be rendered while the surface component is loading.
-   */
-  placeholder?: ReactNode;
-
-  /**
-   * If more than one component is resolved, the limit determines how many are rendered.
-   */
-  limit?: number | undefined;
-
-  /**
-   * If more than one component is resolved, the direction determines how they are laid out.
-   * NOTE: This is not yet implemented.
-   */
-  direction?: Direction;
-
-  /**
-   * Additional props to pass to the component.
-   * These props are not used by Surface itself but may be used by components which resolve the surface.
-   */
-  [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>(
-    ({ 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);
-
-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);
-  const nodes = resolveNodes(components, props, parent, forwardedRef);
-  const currentContext: SurfaceProps = {
-    ...props,
-    surfaces: {
-      ...((props.name && parent?.surfaces?.[props.name]?.surfaces) || {}),
-      ...props.surfaces,
-    },
-  };
-
-  return <SurfaceContext.Provider value={currentContext}>{nodes}</SurfaceContext.Provider>;
-});
-
-/**
- * Resolve surface nodes from across all component.
- */
-const resolveNodes = (
-  components: Record<string, SurfaceComponent>,
-  props: SurfaceProps,
-  context: SurfaceProps | undefined,
-  forwardedRef: ForwardedRef<HTMLElement>,
-): ReactNode[] => {
-  const data = {
-    ...((props.name && context?.surfaces?.[props.name]?.data) || {}),
-    ...props.data,
-  };
-
-  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;
-      }
-
-      // 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;
-      }
-    })
-    .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/plugin-surface/SurfacePlugin.tsx

@@ -1,33 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import React from 'react';
-
-import { create } from '@dxos/live-object';
-
-import { SurfaceProvider, type SurfaceRootContext } from './SurfaceRootContext';
-import SurfaceMeta from './meta';
-import { parseSurfacePlugin, type SurfacePluginProvides } from './provides';
-import { filterPlugins } from '../helpers';
-import { type PluginDefinition } from '../plugin-host';
-
-/**
- * Provides a registry of surface components.
- */
-export const SurfacePlugin = (): PluginDefinition<SurfacePluginProvides> => {
-  const state = create<SurfaceRootContext>({ components: {}, debugInfo: new Map() });
-
-  return {
-    meta: SurfaceMeta,
-    ready: async (plugins) => {
-      state.components = filterPlugins(plugins, parseSurfacePlugin).reduce((acc, plugin) => {
-        return { ...acc, [plugin.meta.id]: plugin.provides.surface.component };
-      }, {});
-    },
-    provides: {
-      surface: state,
-      context: ({ children }) => <SurfaceProvider value={state}>{children}</SurfaceProvider>,
-    },
-  };
-};