@dxos/app-framework 0.8.3 → 0.8.4-main.1068cf700f

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

@@ -1,333 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { Effect, Option, pipe, Ref } from 'effect';
-import { type Simplify } from 'effect/Types';
-
-import { live } from '@dxos/live-object';
-import { log } from '@dxos/log';
-import { byPosition, type MaybePromise, type Position, type GuardedType } from '@dxos/util';
-
-import { IntentAction } from './actions';
-import { CycleDetectedError, NoResolversError } from './errors';
-import {
-  createIntent,
-  type AnyIntent,
-  type AnyIntentChain,
-  type Intent,
-  type IntentChain,
-  type IntentData,
-  type IntentParams,
-  type IntentResultData,
-  type IntentSchema,
-  type Label,
-} from './intent';
-import { Events, Capabilities } from '../common';
-import { contributes, type PluginContext } from '../core';
-
-const EXECUTION_LIMIT = 100;
-const HISTORY_LIMIT = 100;
-
-/**
- * The return value of an intent effect.
- */
-export type IntentEffectResult<Input, Output> = {
-  /**
-   * 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?: Output;
-
-  /**
-   * If provided, the action will be undoable.
-   */
-  undoable?: {
-    /**
-     * Message to display to the user when indicating that the action can be undone.
-     */
-    message: Label;
-
-    /**
-     * Will be merged with the original intent data when firing the undo intent.
-     */
-    data?: Partial<Input>;
-  };
-
-  /**
-   * 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.
-   *
-   * Return caught error instead of throwing to trigger other intent to be triggered prior to returning the error.
-   */
-  error?: Error;
-
-  /**
-   * Other intent chains to be triggered.
-   */
-  intents?: AnyIntentChain[];
-};
-
-export type AnyIntentEffectResult = IntentEffectResult<any, any>;
-
-/**
- * The result of an intent dispatcher.
- */
-export type IntentDispatcherResult<Input, Output> = Pick<IntentEffectResult<Input, Output>, 'data' | 'error'>;
-
-/**
- * The implementation of an intent effect.
- */
-export type IntentEffectDefinition<Input, Output> = (
-  data: Input,
-  undo: boolean,
-) =>
-  | MaybePromise<IntentEffectResult<Input, Output> | void>
-  | Effect.Effect<IntentEffectResult<Input, Output> | void, Error>;
-
-/**
- * Intent resolver to match intents to their effects.
- */
-export type IntentResolver<Tag extends string, Fields extends IntentParams, Data = IntentData<Fields>> = Readonly<{
-  /**
-   * The schema of the intent to be resolved.
-   */
-  intent: IntentSchema<Tag, Fields>;
-
-  /**
-   * Hint to determine the order the resolvers are processed if multiple resolvers are defined for the same intent.
-   * Only one resolver will be used.
-   */
-  position?: Position;
-
-  /**
-   * Optional filter to determine if the resolver should be used.
-   */
-  filter?: (data: IntentData<Fields>) => data is Data;
-
-  /**
-   * The effect to be performed when the intent is resolved.
-   */
-  resolve: IntentEffectDefinition<GuardedType<IntentResolver<Tag, Fields, Data>['filter']>, IntentResultData<Fields>>;
-}>;
-
-export type AnyIntentResolver = IntentResolver<any, any, any>;
-
-/**
- * Creates an intent resolver to match intents to their effects.
- * @param schema Schema of the intent. Must be a tagged class with input and output schemas.
- * @param effect Effect to be performed when the intent is resolved.
- * @param params.disposition Determines the priority of the resolver when multiple are resolved.
- * @param params.filter Optional filter to determine if the resolver should be used.
- */
-export const createResolver = <Tag extends string, Fields extends IntentParams, Data = IntentData<Fields>>(
-  resolver: IntentResolver<Tag, Fields, Data>,
-) => resolver;
-
-/**
- * Invokes intents and returns the result.
- */
-export type PromiseIntentDispatcher = <Fields extends IntentParams>(
-  intent: IntentChain<any, any, any, Fields>,
-) => Promise<Simplify<IntentDispatcherResult<IntentData<Fields>, IntentResultData<Fields>>>>;
-
-/**
- * Creates an effect for intents.
- */
-export type IntentDispatcher = <Fields extends IntentParams>(
-  intent: IntentChain<any, any, any, Fields>,
-  depth?: number,
-) => Effect.Effect<
-  Simplify<Required<IntentDispatcherResult<IntentData<Fields>, IntentResultData<Fields>>>['data']>,
-  Error
->;
-
-type IntentResult<Tag extends string, Fields extends IntentParams> = IntentEffectResult<
-  IntentData<Fields>,
-  IntentResultData<Fields>
-> & {
-  _intent: Intent<Tag, Fields>;
-};
-
-export type AnyIntentResult = IntentResult<any, any>;
-
-/**
- * Invokes the most recent undoable intent with undo flags.
- */
-export type PromiseIntentUndo = () => Promise<IntentDispatcherResult<any, any>>;
-
-/**
- * Creates an effect which undoes the last intent.
- */
-export type IntentUndo = () => Effect.Effect<any, Error>;
-
-/**
- * Check if a chain of results is undoable.
- */
-const isUndoable = (historyEntry: AnyIntentResult[]): boolean =>
-  historyEntry.length > 0 && historyEntry.every(({ undoable }) => !!undoable);
-
-export type IntentContext = {
-  dispatch: IntentDispatcher;
-  dispatchPromise: PromiseIntentDispatcher;
-  undo: IntentUndo;
-  undoPromise: PromiseIntentUndo;
-};
-
-/**
- * Sets of an intent dispatcher.
- *
- * @param getResolvers A function that returns an array of available intent resolvers.
- * @param params.historyLimit The maximum number of intent results to keep in history.
- * @param params.executionLimit The maximum recursion depth of intent chains.
- */
-export const createDispatcher = (
-  getResolvers: () => AnyIntentResolver[],
-  { executionLimit = EXECUTION_LIMIT, historyLimit = HISTORY_LIMIT } = {},
-): IntentContext => {
-  const historyRef = Effect.runSync(Ref.make<AnyIntentResult[][]>([]));
-
-  const handleIntent = (intent: AnyIntent) =>
-    Effect.gen(function* () {
-      const candidates = getResolvers()
-        .filter((resolver) => resolver.intent._tag === intent.id)
-        .filter((resolver) => !resolver.filter || resolver.filter(intent.data))
-        .toSorted(byPosition);
-      if (candidates.length === 0) {
-        yield* Effect.fail(new NoResolversError(intent.id));
-      }
-
-      const effect = candidates[0].resolve(intent.data, intent.undo ?? false);
-      const result = Effect.isEffect(effect) ? yield* effect : yield* Effect.promise(async () => effect);
-      return { _intent: intent, ...result } as AnyIntentResult;
-    });
-
-  const dispatch: IntentDispatcher = (intentChain, depth = 0) => {
-    return Effect.gen(function* () {
-      if (depth > executionLimit) {
-        yield* Effect.fail(new CycleDetectedError());
-      }
-
-      const resultsRef = yield* Ref.make<AnyIntentResult[]>([]);
-      for (const intent of intentChain.all) {
-        const { data: prev } = (yield* resultsRef.get)[0] ?? {};
-        const result = yield* handleIntent({ ...intent, data: { ...intent.data, ...prev } });
-        yield* Ref.update(resultsRef, (results) => [result, ...results]);
-        if (result.intents) {
-          for (const intent of result.intents) {
-            // Returned intents are dispatched but not yielded into results, as such they cannot be undone.
-            // TODO(wittjosiah): Use higher execution concurrency?
-            yield* dispatch(intent, depth + 1);
-          }
-        }
-
-        if (result.error) {
-          // yield* dispatch(
-          //   createIntent(IntentAction.Track, {
-          //     intents: intentChain.all.map((i) => i.id),
-          //     error: result.error.message,
-          //   }),
-          // );
-          yield* Effect.fail(result.error);
-        }
-      }
-
-      // Track the intent chain.
-      // if (intentChain.all.some((intent) => intent.id !== IntentAction.Track._tag)) {
-      //   yield* dispatch(createIntent(IntentAction.Track, { intents: intentChain.all.map((i) => i.id) }));
-      // }
-
-      const results = yield* resultsRef.get;
-      const result = results[0];
-      yield* Ref.update(historyRef, (history) => {
-        const next = [...history, results];
-        if (next.length > historyLimit) {
-          next.splice(0, next.length - historyLimit);
-        }
-        return next;
-      });
-
-      if (result.undoable && isUndoable(results)) {
-        // TODO(wittjosiah): Is there a better way to handle showing undo for chains?
-        yield* pipe(
-          dispatch(createIntent(IntentAction.ShowUndo, { message: result.undoable.message })),
-          Effect.catchSome((err) =>
-            err instanceof NoResolversError ? Option.some(Effect.succeed(undefined)) : Option.none(),
-          ),
-        );
-      }
-
-      return result.data;
-    });
-  };
-
-  const dispatchPromise: PromiseIntentDispatcher = (intentChain) => {
-    return Effect.runPromise(dispatch(intentChain))
-      .then((data) => ({ data }))
-      .catch((error) => {
-        log.catch(error);
-        return { error };
-      });
-  };
-
-  const undo: IntentUndo = () => {
-    return Effect.gen(function* () {
-      const history = yield* historyRef.get;
-      const last = history.findLastIndex(isUndoable);
-      const result = last !== -1 ? history[last] : undefined;
-      if (result) {
-        const all = result.map(({ _intent, undoable }): AnyIntent => {
-          const data = _intent.data;
-          const undoData = undoable?.data ?? {};
-          return { ..._intent, data: { ...data, ...undoData }, undo: true } satisfies AnyIntent;
-        });
-        const intent = { first: all[0], last: all.at(-1)!, all } satisfies AnyIntentChain;
-        yield* Ref.update(historyRef, (h) => h.filter((_, index) => index !== last));
-        return yield* dispatch(intent);
-      }
-    });
-  };
-
-  const undoPromise: PromiseIntentUndo = () => {
-    return Effect.runPromise(undo())
-      .then((data) => ({ data }))
-      .catch((error) => ({ error }));
-  };
-
-  return { dispatch, dispatchPromise, undo, undoPromise };
-};
-
-const defaultEffect = () => Effect.fail(new Error('Intent runtime not ready'));
-const defaultPromise = () => Effect.runPromise(defaultEffect());
-
-export default (context: PluginContext) => {
-  const state = live<IntentContext>({
-    dispatch: defaultEffect,
-    dispatchPromise: defaultPromise,
-    undo: defaultEffect,
-    undoPromise: defaultPromise,
-  });
-
-  // TODO(wittjosiah): Make getResolver callback async and allow resolvers to be requested on demand.
-  const { dispatch, dispatchPromise, undo, undoPromise } = createDispatcher(() =>
-    context.getCapabilities(Capabilities.IntentResolver).flat(),
-  );
-
-  const manager = context.getCapability(Capabilities.PluginManager);
-  state.dispatch = (intentChain, depth) => {
-    return Effect.gen(function* () {
-      yield* manager._activate(Events.SetupIntentResolver);
-      return yield* dispatch(intentChain, depth);
-    });
-  };
-  state.dispatchPromise = async (intentChain) => {
-    await manager.activate(Events.SetupIntentResolver);
-    return await dispatchPromise(intentChain);
-  };
-  state.undo = undo;
-  state.undoPromise = undoPromise;
-
-  return contributes(Capabilities.IntentDispatcher, state);
-};

package/src/plugin-intent/intent.ts

@@ -1,154 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { Schema } from 'effect';
-
-export type IntentParams = {
-  readonly input: Schema.Schema.All;
-  readonly output: Schema.Schema.All;
-};
-
-export type IntentData<Fields extends IntentParams> =
-  Schema.Schema.Type<Schema.Struct<Fields>> extends { readonly input: any }
-    ? Schema.Schema.Type<Schema.Struct<Fields>>['input']
-    : any;
-
-export type IntentResultData<Fields extends IntentParams> =
-  Schema.Schema.Type<Schema.Struct<Fields>> extends { readonly output: any }
-    ? Schema.Schema.Type<Schema.Struct<Fields>>['output']
-    : any;
-
-export type IntentSchema<Tag extends string, Fields extends IntentParams> = Schema.TaggedClass<any, Tag, Fields>;
-
-/**
- * An intent is an abstract description of an operation to be performed.
- * Intents allow actions to be performed across plugins.
- */
-export type Intent<Tag extends string, Fields extends IntentParams> = {
-  _schema: IntentSchema<Tag, Fields>;
-
-  /**
-   * The id of the intent.
-   */
-  id: Tag;
-
-  /**
-   * Any data needed to perform the desired action.
-   */
-  data: IntentData<Fields>;
-
-  /**
-   * Whether or not the intent is being undone.
-   */
-  undo?: boolean;
-};
-
-export type AnyIntent = Intent<any, any>;
-
-/**
- * Chain of intents to be executed together.
- * The result of each intent is merged into the next intent's input data.
- */
-export type IntentChain<
-  FirstTag extends string,
-  LastTag extends string,
-  FirstFields extends IntentParams,
-  LastFields extends IntentParams,
-> = {
-  first: Intent<FirstTag, FirstFields>;
-  last: Intent<LastTag, LastFields>;
-  all: AnyIntent[];
-};
-
-export type AnyIntentChain = IntentChain<any, any, any, any>;
-
-/**
- * Creates a typed intent.
- * @param schema Schema of the intent. Must be a tagged class with input and output schemas.
- * @param data Data fulfilling the input schema of the intent.
- * @param params.plugin Optional plugin ID to send the intent to.
- * @param params.undo Optional flag to indicate that the intent is being undone. Generally not set manually.
- */
-export const createIntent = <Tag extends string, Fields extends IntentParams>(
-  schema: IntentSchema<Tag, Fields>,
-  data: IntentData<Fields> = {},
-  params: Pick<AnyIntent, 'undo'> = {},
-): IntentChain<Tag, Tag, Fields, Fields> => {
-  // The output of validateSync breaks proxy objects so this is just used for validation.
-  // TODO(wittjosiah): Is there a better way to make theses types align?
-  const _ = Schema.validateSync(schema.fields.input as Schema.Schema<any, any, unknown>)(data);
-  const intent = {
-    ...params,
-    _schema: schema,
-    id: schema._tag,
-    data,
-  } satisfies Intent<Tag, Fields>;
-
-  return {
-    first: intent,
-    last: intent,
-    all: [intent],
-  };
-};
-
-// TODO(wittjosiah): Add a function for mapping the output of one intent to the input of another.
-
-/**
- * Chain two intents together.
- *
- * NOTE: Chaining of intents depends on the data inputs and outputs being structs.
- */
-export const chain =
-  <
-    FirstTag extends string,
-    NextTag extends string,
-    FirstFields extends IntentParams,
-    LastFields extends IntentParams,
-    NextFields extends IntentParams,
-  >(
-    schema: IntentSchema<NextTag, NextFields>,
-    data: Omit<IntentData<NextFields>, keyof IntentResultData<LastFields>> = {},
-    params: Pick<AnyIntent, 'undo'> = {},
-  ) =>
-  (
-    intent: IntentChain<FirstTag, any, FirstFields, LastFields>,
-  ): IntentChain<FirstTag, NextTag, FirstFields, NextFields> => {
-    const intents = 'all' in intent ? intent.all : [intent];
-    const first = intents[0];
-    const last = {
-      ...params,
-      _schema: schema,
-      id: schema._tag,
-      data,
-    } satisfies Intent<NextTag, NextFields>;
-
-    return {
-      first,
-      last,
-      all: [...intents, last],
-    };
-  };
-
-//
-// Intents
-//
-
-// NOTE: Should maintain compatibility with `i18next` (and @dxos/react-ui).
-// TODO(wittjosiah): Making this immutable breaks type compatibility.
-export const Label = Schema.Union(
-  Schema.String,
-  Schema.mutable(
-    Schema.Tuple(
-      Schema.String,
-      Schema.mutable(
-        Schema.Struct({
-          ns: Schema.String,
-          count: Schema.optional(Schema.Number),
-          defaultValue: Schema.optional(Schema.String),
-        }),
-      ),
-    ),
-  ),
-);
-export type Label = Schema.Schema.Type<typeof Label>;

package/src/plugin-settings/SettingsPlugin.ts

@@ -1,35 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { SETTINGS_PLUGIN } from './actions';
-import translations from './translations';
-import { Capabilities, Events } from '../common';
-import { contributes, defineModule, definePlugin, lazy } from '../core';
-
-// TODO(wittjosiah): Add options to exclude some modules.
-export const SettingsPlugin = () =>
-  definePlugin({ id: SETTINGS_PLUGIN, name: 'Settings' }, [
-    defineModule({
-      id: `${SETTINGS_PLUGIN}/module/store`,
-      activatesOn: Events.Startup,
-      activatesBefore: [Events.SetupSettings],
-      activatesAfter: [Events.SettingsReady],
-      activate: lazy(() => import('./store')),
-    }),
-    defineModule({
-      id: `${SETTINGS_PLUGIN}/module/translations`,
-      activatesOn: Events.SetupTranslations,
-      activate: () => contributes(Capabilities.Translations, translations),
-    }),
-    defineModule({
-      id: `${SETTINGS_PLUGIN}/module/intent-resolver`,
-      activatesOn: Events.SetupIntentResolver,
-      activate: lazy(() => import('./intent-resolver')),
-    }),
-    defineModule({
-      id: `${SETTINGS_PLUGIN}/module/app-graph-builder`,
-      activatesOn: Events.SetupAppGraph,
-      activate: lazy(() => import('./app-graph-builder')),
-    }),
-  ]);

package/src/plugin-settings/actions.ts

@@ -1,29 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { Schema } from 'effect';
-
-export const SETTINGS_PLUGIN = 'dxos.org/plugin/settings';
-export const SETTINGS_ACTION = `${SETTINGS_PLUGIN}/action`;
-// TODO(wittjosiah): This is a hack to prevent the previous deck from being set for pinned items.
-//  Ideally this should be worked into the data model in a generic way.
-export const SETTINGS_ID = '!dxos:settings';
-export const SETTINGS_KEY = 'settings';
-
-export namespace SettingsAction {
-  export class Open extends Schema.TaggedClass<Open>()(`${SETTINGS_ACTION}/open`, {
-    input: Schema.Struct({
-      plugin: Schema.optional(Schema.String),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class OpenPluginRegistry extends Schema.TaggedClass<OpenPluginRegistry>()(
-    `${SETTINGS_ACTION}/open-plugin-registry`,
-    {
-      input: Schema.Void,
-      output: Schema.Void,
-    },
-  ) {}
-}