@dxos/app-framework 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

package/src/common/plugin.ts

@@ -1,364 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import type * as Command$ from '@effect/cli/Command';
-import * as Effect from 'effect/Effect';
-
-import { type Type } from '@dxos/echo';
-
-import { Capability as Capability$, Plugin as Plugin$ } from '../core';
-
-import { ActivationEvent } from './activation-event';
-import { Capability } from './capability';
-import { type Resource } from './translations';
-
-type PluginModuleOptions = Partial<
-  Pick<Plugin$.PluginModuleOptions, 'id' | 'activatesOn' | 'activatesBefore' | 'activatesAfter'>
-> &
-  Pick<Plugin$.PluginModuleOptions, 'activate'>;
-
-/**
- * Helper functions for creating common plugin module patterns.
- */
-export namespace Plugin {
-  // TODO(wittjosiah): Restrict type to only allow operation handlers.
-  export type OperationResolverModuleOptions = PluginModuleOptions;
-
-  /**
-   * Creates a module that contributes operation handlers.
-   *
-   * @param options Module options including the activate function and optional configuration
-   * @returns A function that can be used with Plugin.addModule() in a pipe chain
-   *
-   * @example
-   * ```ts
-   * Plugin.define(meta).pipe(
-   *   Common.Plugin.addOperationResolverModule({
-   *     activate: (context) =>
-   *       Capability.contributes(Common.Capability.OperationResolver, [{
-   *         operation: MyOperation,
-   *         handler: (input) => Effect.succeed(...)
-   *       }])
-   *   })
-   * )
-   * ```
-   */
-  export function addOperationResolverModule<T = void>(
-    options: OperationResolverModuleOptions,
-  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
-    return Plugin$.addModule({
-      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'operation-resolver',
-      activatesOn: options.activatesOn ?? ActivationEvent.SetupOperationResolver,
-      activatesBefore: options.activatesBefore,
-      activatesAfter: options.activatesAfter,
-      activate: options.activate,
-    });
-  }
-
-  // TODO(wittjosiah): Restrict type to only allow surfaces.
-  export type SurfaceModuleOptions = PluginModuleOptions;
-
-  /**
-   * Creates a module that contributes React surfaces.
-   *
-   * @param options Module options including the activate function and optional configuration
-   * @returns A function that can be used with Plugin.addModule() in a pipe chain
-   *
-   * @example
-   * ```ts
-   * Plugin.define(meta).pipe(
-   *   Common.Plugin.addSurfaceModule({
-   *     activate: (context) =>
-   *       Capability.contributes(Common.Capability.ReactSurface, [
-   *         Common.createSurface({ id: `${meta.id}/my-surface`, ... })
-   *       ])
-   *   })
-   * )
-   * ```
-   */
-  export function addSurfaceModule<T = void>(
-    options: SurfaceModuleOptions,
-  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
-    return Plugin$.addModule({
-      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'surfaces',
-      activatesOn: options.activatesOn ?? ActivationEvent.SetupReactSurface,
-      activatesBefore: options.activatesBefore,
-      activatesAfter: options.activatesAfter,
-      activate: options.activate,
-    });
-  }
-
-  // TODO(wittjosiah): Restrict type to only allow react roots.
-  export type ReactRootModuleOptions = PluginModuleOptions;
-
-  /**
-   * Creates a module that contributes a React root.
-   */
-  export function addReactRootModule<T = void>(
-    options: ReactRootModuleOptions,
-  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
-    return Plugin$.addModule({
-      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'react-root',
-      activatesOn: options.activatesOn ?? ActivationEvent.Startup,
-      activatesBefore: options.activatesBefore,
-      activatesAfter: options.activatesAfter,
-      activate: options.activate,
-    });
-  }
-
-  // TODO(wittjosiah): Restrict type to only allow react contexts.
-  export type ReactContextModuleOptions = PluginModuleOptions;
-
-  /**
-   * Creates a module that contributes a React context.
-   */
-  export function addReactContextModule<T = void>(
-    options: ReactContextModuleOptions,
-  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
-    return Plugin$.addModule({
-      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'react-context',
-      activatesOn: options.activatesOn ?? ActivationEvent.Startup,
-      activatesBefore: options.activatesBefore,
-      activatesAfter: options.activatesAfter,
-      activate: options.activate,
-    });
-  }
-
-  // TODO(wittjosiah): Restrict type to only allow app graph builders.
-  export type AppGraphModuleOptions = PluginModuleOptions;
-
-  /**
-   * Creates a module that contributes app graph builder extensions.
-   *
-   * @param options Module options including the activate function and optional configuration
-   * @returns A function that can be used with Plugin.addModule() in a pipe chain
-   *
-   * @example
-   * ```ts
-   * Plugin.define(meta).pipe(
-   *   Common.Plugin.addAppGraphModule({
-   *     activate: Effect.fnUntraced(function* () {
-   *       const extensions = yield* GraphBuilder.createExtension({
-   *         id: meta.id,
-   *         match: NodeMatcher.whenRoot,
-   *         // All callbacks must return Effects.
-   *         actions: () => Effect.succeed([{
-   *           id: 'my-action',
-   *           // Action data returns Effect for automatic context access.
-   *           data: Effect.fnUntraced(function* () {
-   *             yield* Operation.invoke(MyOperation, { ... });
-   *           }),
-   *           properties: { label: 'My Action', icon: 'ph--icon' },
-   *         }]),
-   *         connector: (node, get) => Effect.succeed([{ id: 'child', ... }]),
-   *       });
-   *       return Capability.contributes(Common.Capability.AppGraphBuilder, extensions);
-   *     })
-   *   })
-   * )
-   * ```
-   */
-  export function addAppGraphModule<T = void>(
-    options: AppGraphModuleOptions,
-  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
-    return Plugin$.addModule({
-      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'app-graph-builder',
-      activatesOn: options.activatesOn ?? ActivationEvent.SetupAppGraph,
-      activatesBefore: options.activatesBefore,
-      activatesAfter: options.activatesAfter,
-      activate: options.activate,
-    });
-  }
-
-  export type TranslationsModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
-    translations: Resource | Resource[];
-  };
-
-  /**
-   * Creates a module that contributes translations.
-   *
-   * @param options Module options including translations and optional configuration
-   * @returns A function that can be used with Plugin.addModule() in a pipe chain
-   *
-   * @example
-   * ```ts
-   * Plugin.define(meta).pipe(
-   *   Common.Plugin.addTranslationsModule({
-   *     translations: translations
-   *   })
-   * )
-   * ```
-   */
-  export function addTranslationsModule<T = void>(
-    options: TranslationsModuleOptions,
-  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
-    return Plugin$.addModule({
-      id: options?.id ?? 'translations',
-      activatesOn: options?.activatesOn ?? ActivationEvent.SetupTranslations,
-      activatesBefore: options?.activatesBefore,
-      activatesAfter: options?.activatesAfter,
-      activate: Effect.fnUntraced(function* () {
-        return Capability$.contributes(
-          Capability.Translations,
-          Array.isArray(options.translations) ? options.translations : ([options.translations] as Resource[]),
-        );
-      }),
-    });
-  }
-
-  export type MetadataModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
-    metadata: Capability.Metadata | Capability.Metadata[];
-  };
-
-  /**
-   * Creates a module that contributes metadata.
-   *
-   * @param options Module options including metadata and optional configuration
-   * @returns A function that can be used with Plugin.addModule() in a pipe chain
-   *
-   * @example
-   * ```ts
-   * Plugin.define(meta).pipe(
-   *   Common.Plugin.addMetadataModule({
-   *     metadata: {
-   *       id: MyType.typename,
-   *       metadata: { icon: 'ph--icon', ... }
-   *     }
-   *   })
-   * )
-   * ```
-   */
-  export function addMetadataModule<T = void>(
-    options: MetadataModuleOptions,
-  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
-    return Plugin$.addModule({
-      id: options.id ?? 'metadata',
-      activatesOn: options.activatesOn ?? ActivationEvent.SetupMetadata,
-      activatesBefore: options.activatesBefore,
-      activatesAfter: options.activatesAfter,
-      activate: Effect.fnUntraced(function* () {
-        return (Array.isArray(options.metadata) ? options.metadata : [options.metadata]).map((m) =>
-          Capability$.contributes(Capability.Metadata, m),
-        );
-      }),
-    });
-  }
-
-  // TODO(wittjosiah): Restrict type to only allow settings.
-  export type SettingsModuleOptions = PluginModuleOptions;
-
-  /**
-   * Creates a module that contributes settings.
-   */
-  export function addSettingsModule<T = void>(
-    options: SettingsModuleOptions,
-  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
-    return Plugin$.addModule({
-      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'settings',
-      activatesOn: options.activatesOn ?? ActivationEvent.SetupSettings,
-      activatesBefore: options.activatesBefore,
-      activatesAfter: options.activatesAfter,
-      activate: options.activate,
-    });
-  }
-
-  // TODO(wittjosiah): Restrict type to only allow blueprint definitions.
-  export type BlueprintDefinitionModuleOptions = PluginModuleOptions;
-
-  /**
-   * Creates a module that contributes blueprint definitions.
-   *
-   * @param options Module options including the activate function and optional configuration
-   * @returns A function that can be used with Plugin.addModule() in a pipe chain
-   *
-   * @example
-   * ```ts
-   * Plugin.define(meta).pipe(
-   *   Common.Plugin.addBlueprintDefinitionModule({
-   *     activate: (context) =>
-   *       Capability.contributes(Common.Capability.BlueprintDefinition, [
-   *         BlueprintDefinition.make({ key: 'my-blueprint', ... })
-   *       ])
-   *   })
-   * )
-   * ```
-   */
-  export function addBlueprintDefinitionModule<T = void>(
-    options: BlueprintDefinitionModuleOptions,
-  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
-    return Plugin$.addModule({
-      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'blueprint-definition',
-      activatesOn: options.activatesOn ?? ActivationEvent.SetupArtifactDefinition,
-      activatesBefore: options.activatesBefore,
-      activatesAfter: options.activatesAfter,
-      activate: options.activate,
-    });
-  }
-
-  export type SchemaModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
-    schema: ReadonlyArray<Type.Entity.Any>;
-  };
-
-  /**
-   * Creates a module that contributes schemas.
-   *
-   * @param options Module options including schema array and optional configuration
-   * @returns A function that can be used with Plugin.addModule() in a pipe chain
-   *
-   * @example
-   * ```ts
-   * Plugin.define(meta).pipe(
-   *   Common.Plugin.addSchemaModule({
-   *     schema: [MyType.Type, AnotherType.Type]
-   *   })
-   * )
-   * ```
-   */
-  export function addSchemaModule<T = void>(
-    options: SchemaModuleOptions,
-  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
-    return Plugin$.addModule({
-      id: options.id ?? 'schema',
-      activatesOn: options.activatesOn ?? ActivationEvent.SetupSchema,
-      activatesBefore: options.activatesBefore,
-      activatesAfter: options.activatesAfter,
-      activate: Effect.fnUntraced(function* () {
-        return Capability$.contributes(Capability.Schema, options.schema);
-      }),
-    });
-  }
-
-  export type CommandModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
-    commands: ReadonlyArray<Command$.Command<any, any, any, any>>;
-  };
-
-  /**
-   * Creates a module that contributes CLI commands.
-   *
-   * @param options Module options including commands and optional configuration
-   * @returns A function that can be used with Plugin.addModule() in a pipe chain
-   *
-   * @example
-   * ```ts
-   * Plugin.define(meta).pipe(
-   *   Common.Plugin.addCommandModule({
-   *     commands: [myCommand, anotherCommand]
-   *   })
-   * )
-   * ```
-   */
-  export function addCommandModule<T = void>(
-    options: CommandModuleOptions,
-  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
-    return Plugin$.addModule({
-      id: options.id ?? 'cli-commands',
-      activatesOn: options.activatesOn ?? ActivationEvent.Startup,
-      activatesBefore: options.activatesBefore,
-      activatesAfter: options.activatesAfter,
-      activate: Effect.fnUntraced(function* () {
-        return options.commands.map((cmd) => Capability$.contributes(Capability.Command, cmd));
-      }),
-    });
-  }
-}

package/src/playground/debug/Debug.tsx

@@ -1,49 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { useAtomValue } from '@effect-atom/atom-react';
-import * as Effect from 'effect/Effect';
-import React from 'react';
-
-import { SyntaxHighlighter } from '@dxos/react-ui-syntax-highlighter';
-
-import * as Common from '../../common';
-import { Capability } from '../../core';
-import { usePluginManager } from '../../react';
-
-export const Debug = () => {
-  const manager = usePluginManager();
-  const core = useAtomValue(manager.core);
-  const enabled = useAtomValue(manager.enabled);
-  const active = useAtomValue(manager.active);
-  const pendingReset = useAtomValue(manager.pendingReset);
-  const eventsFired = useAtomValue(manager.eventsFired);
-
-  const object = {
-    core,
-    enabled,
-    active,
-    pendingReset,
-    eventsFired,
-  };
-
-  return (
-    <SyntaxHighlighter language='json' classNames='text-xs opacity-75 rounded'>
-      {JSON.stringify(object, undefined, 2)}
-    </SyntaxHighlighter>
-  );
-};
-
-export default Capability.makeModule(() =>
-  Effect.succeed(
-    Capability.contributes(
-      Common.Capability.ReactSurface,
-      Common.createSurface({
-        id: 'dxos.org/test/debug/main',
-        role: 'secondary',
-        component: Debug,
-      }),
-    ),
-  ),
-);

package/src/playground/debug/plugin.ts

@@ -1,16 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Common from '../../common';
-import { Capability, Plugin } from '../../core';
-
-const Debug = Capability.lazy('Debug', () => import('./Debug'));
-
-export const DebugPlugin = Plugin.define({ id: 'dxos.org/test/plugin-debug', name: 'Debug' }).pipe(
-  Plugin.addModule({
-    activatesOn: Common.ActivationEvent.Startup,
-    activate: Debug,
-  }),
-  Plugin.make,
-);

package/src/playground/generator/Main.tsx

@@ -1,80 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { useAtomValue } from '@effect-atom/atom-react';
-import * as Effect from 'effect/Effect';
-import React, { useCallback } from 'react';
-
-import { IconButton, List, ListItem } from '@dxos/react-ui';
-
-import * as Common from '../../common';
-import { Capability } from '../../core';
-import { usePluginManager } from '../../react';
-
-const Item = ({
-  id,
-  disabled,
-  onRemove,
-}: {
-  id: string;
-  disabled: boolean;
-  onRemove: (id: string) => Promise<void>;
-}) => {
-  const handleRemove = useCallback(() => onRemove(id), [onRemove]);
-
-  return (
-    <ListItem.Root key={id} id={id}>
-      <ListItem.Heading classNames='grow pbs-2'>{id}</ListItem.Heading>
-      <ListItem.Endcap>
-        <IconButton
-          iconOnly
-          variant='ghost'
-          icon='ph--x--regular'
-          label='Remove'
-          disabled={disabled}
-          onClick={handleRemove}
-        />
-      </ListItem.Endcap>
-    </ListItem.Root>
-  );
-};
-
-export const Main = () => {
-  const manager = usePluginManager();
-  const plugins = useAtomValue(manager.plugins);
-  const core = useAtomValue(manager.core);
-
-  const handleRemove = useCallback(
-    async (id: string) => {
-      await manager.remove(id);
-    },
-    [manager],
-  );
-
-  return (
-    <List itemSizes='one'>
-      {plugins.map((plugin) => (
-        <Item
-          key={plugin.meta.id}
-          id={plugin.meta.id}
-          disabled={core.includes(plugin.meta.id)}
-          onRemove={handleRemove}
-        />
-      ))}
-    </List>
-  );
-};
-
-export default Capability.makeModule(() =>
-  Effect.succeed(
-    Capability.contributes(
-      Common.Capability.ReactSurface,
-      Common.createSurface({
-        id: 'dxos.org/test/generator/main',
-        role: 'primary',
-        component: Main,
-      }),
-    ),
-  ),
-);

package/src/playground/generator/Toolbar.tsx

@@ -1,57 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { useAtomValue } from '@effect-atom/atom-react';
-import * as Effect from 'effect/Effect';
-import React, { useCallback } from 'react';
-
-import { Button } from '@dxos/react-ui';
-
-import * as Common from '../../common';
-import { Capability, type Plugin } from '../../core';
-import { useCapabilities, useOperationInvoker, usePluginManager } from '../../react';
-
-import { Number, createAlertOperation, createPluginId } from './generator';
-
-export const Toolbar = () => {
-  const manager = usePluginManager();
-  const plugins = useAtomValue(manager.plugins);
-  const { invokePromise } = useOperationInvoker();
-
-  const handleAdd = useCallback(async () => {
-    const id = createPluginId(Math.random().toString(16).substring(2, 8));
-    await manager.add(id);
-  }, [manager]);
-
-  const count = useCapabilities(Number).reduce((acc: number, curr: number) => acc + curr, 0);
-
-  const generatorPlugins = plugins.filter((plugin: Plugin.Plugin) =>
-    plugin.meta.id.startsWith('dxos.org/test/generator/'),
-  );
-
-  return (
-    <>
-      <Button onClick={handleAdd}>Add</Button>
-      <div className='flex items-center'>Count: {count}</div>
-      {generatorPlugins.map((plugin: Plugin.Plugin) => (
-        <Button key={plugin.meta.id} onClick={() => invokePromise(createAlertOperation(plugin.meta.id))}>
-          {plugin.meta.id.replace('dxos.org/test/generator/', '')}
-        </Button>
-      ))}
-    </>
-  );
-};
-
-export default Capability.makeModule(() =>
-  Effect.succeed(
-    Capability.contributes(
-      Common.Capability.ReactSurface,
-      Common.createSurface({
-        id: 'dxos.org/test/generator/toolbar',
-        role: 'toolbar',
-        component: Toolbar,
-      }),
-    ),
-  ),
-);

package/src/playground/generator/generator.ts

@@ -1,48 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Effect from 'effect/Effect';
-import * as Schema from 'effect/Schema';
-
-import { Operation, OperationResolver } from '@dxos/operation';
-
-import * as Common from '../../common';
-import { ActivationEvent, Capability, Plugin } from '../../core';
-
-export const Number = Capability.make<number>('dxos.org/test/generator/number');
-
-export const CountEvent = ActivationEvent.make('dxos.org/test/generator/count');
-
-export const createPluginId = (id: string) => `dxos.org/test/generator/${id}`;
-
-export const createAlertOperation = (id: string) =>
-  Operation.make({
-    meta: { key: `${createPluginId(id)}/operation/alert`, name: 'Alert' },
-    schema: { input: Schema.Void, output: Schema.Void },
-  });
-
-export const createNumberPlugin = (id: string) => {
-  const number = Math.floor(Math.random() * 100);
-  const AlertOperation = createAlertOperation(id);
-
-  return Plugin.define({ id, name: `Plugin ${id}` }).pipe(
-    Plugin.addModule({
-      id: 'Main',
-      activatesOn: CountEvent,
-      activate: () => Effect.succeed(Capability.contributes(Number, number)),
-    }),
-    Common.Plugin.addOperationResolverModule({
-      activate: () =>
-        Effect.succeed(
-          Capability.contributes(Common.Capability.OperationResolver, [
-            OperationResolver.make({
-              operation: AlertOperation,
-              handler: () => Effect.sync(() => window.alert(JSON.stringify({ number }))),
-            }),
-          ]),
-        ),
-    }),
-    Plugin.make,
-  )();
-};

package/src/playground/generator/index.ts

@@ -1,6 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-export * from './plugin';
-export * from './generator';

package/src/playground/generator/plugin.ts

@@ -1,21 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Common from '../../common';
-import { Capability, Plugin } from '../../core';
-
-const Main = Capability.lazy('Main', () => import('./Main'));
-const Toolbar = Capability.lazy('Toolbar', () => import('./Toolbar'));
-
-export const GeneratorPlugin = Plugin.define({ id: 'dxos.org/test/generator', name: 'Generator' }).pipe(
-  Plugin.addModule({
-    activatesOn: Common.ActivationEvent.Startup,
-    activate: Main,
-  }),
-  Plugin.addModule({
-    activatesOn: Common.ActivationEvent.Startup,
-    activate: Toolbar,
-  }),
-  Plugin.make,
-);

package/src/playground/layout/Layout.tsx

@@ -1,37 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Effect from 'effect/Effect';
-import React from 'react';
-
-import * as Common from '../../common';
-import { Capability } from '../../core';
-import { Surface } from '../../react';
-
-export const Layout = () => {
-  return (
-    <div className='flex flex-col gap-2'>
-      <div className='flex gap-2'>
-        <Surface role='toolbar' />
-      </div>
-      <div className='flex gap-2'>
-        <div className='flex-1'>
-          <Surface role='primary' limit={1} />
-        </div>
-        <div className='flex-1'>
-          <Surface role='secondary' limit={1} />
-        </div>
-      </div>
-    </div>
-  );
-};
-
-export default Capability.makeModule(() =>
-  Effect.succeed(
-    Capability.contributes(Common.Capability.ReactRoot, {
-      id: 'dxos.org/test/layout/root',
-      root: Layout,
-    }),
-  ),
-);