@dxos/app-framework 0.7.5-main.9d26e3a → 0.7.5-main.b19bfc8

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/index.ts

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

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,
-  }) {}
-}

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

@@ -1,62 +0,0 @@
-//
-// Copyright 2022 DXOS.org
-//
-
-import React, { Suspense, forwardRef, memo, useEffect, useId, useMemo } from 'react';
-
-import { useDefaultValue } from '@dxos/react-hooks';
-
-import { ErrorBoundary } from './ErrorBoundary';
-import { type SurfaceProps, useSurfaceRoot } from './SurfaceContext';
-
-/**
- * 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, data: _data, limit, fallback, placeholder, ...rest }, forwardedRef) => {
-      const { surfaces, debugInfo } = useSurfaceRoot();
-      const data = useDefaultValue(_data, () => ({}));
-
-      // Track debug info.
-      const reactId = useId();
-      const id = _id ?? reactId;
-      useEffect(() => {
-        debugInfo?.set(id, { id, created: Date.now(), role, renderCount: 0 });
-        return () => {
-          debugInfo?.delete(id);
-        };
-      }, [id]);
-
-      if (debugInfo?.get(id)) {
-        debugInfo.get(id)!.renderCount++;
-      }
-
-      const candidates = useMemo(() => {
-        const definitions = Object.values(surfaces)
-          .filter((definition) =>
-            Array.isArray(definition.role) ? definition.role.includes(role) : definition.role === role,
-          )
-          .filter(({ filter }) => (filter ? filter(data) : true))
-          .toSorted(({ disposition: a = 'static' }, { disposition: b = 'static' }) => {
-            return a === b ? 0 : a === 'hoist' || b === 'fallback' ? -1 : b === 'hoist' || a === 'fallback' ? 1 : 0;
-          });
-        return limit ? definitions.slice(0, limit) : definitions;
-      }, [surfaces, role, data, limit]);
-
-      const nodes = candidates.map(({ component: Component, id }) => (
-        <Component ref={forwardedRef} key={id} id={id} role={role} data={data} limit={limit} {...rest} />
-      ));
-
-      const suspense = placeholder ? <Suspense fallback={placeholder}>{nodes}</Suspense> : nodes;
-
-      return fallback ? (
-        <ErrorBoundary data={data} fallback={fallback}>
-          {suspense}
-        </ErrorBoundary>
-      ) : (
-        suspense
-      );
-    },
-  ),
-);

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

@@ -1,45 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import React from 'react';
-
-import { create } from '@dxos/live-object';
-
-import { SurfaceProvider, type SurfaceContextValue } from './SurfaceContext';
-import SurfaceMeta from './meta';
-import { parseSurfacePlugin, type SurfacePluginProvides, type SurfaceDefinitions } 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<SurfaceContextValue>({ surfaces: {}, debugInfo: new Map() });
-
-  return {
-    meta: SurfaceMeta,
-    ready: async (context) => {
-      state.surfaces = filterPlugins(context.plugins, parseSurfacePlugin).reduce(
-        (acc, plugin) => reduceSurfaces(plugin.provides.surface.definitions(context), acc),
-        {},
-      );
-    },
-    provides: {
-      surface: state,
-      context: ({ children }) => <SurfaceProvider value={state}>{children}</SurfaceProvider>,
-    },
-  };
-};
-
-const reduceSurfaces = (
-  definitions: SurfaceDefinitions,
-  surfaces: SurfaceContextValue['surfaces'] = {},
-): SurfaceContextValue['surfaces'] => {
-  if (Array.isArray(definitions)) {
-    return definitions.reduce((acc, definition) => reduceSurfaces(definition, acc), surfaces);
-  }
-
-  return { ...surfaces, [definitions.id]: definitions };
-};

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

@@ -1,22 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-/**
- * Checks if the given data is an object and not null.
- *
- * Useful inside surface component resolvers as a type guard.
- *
- * @example
- * ```ts
- *  const old =
- *    data.content &&
- *      typeof data.content === 'object' &&
- *      'id' in data.content &&
- *      typeof data.content.id === 'string';
- *
- *  // becomes
- *  const new = isObject(data.content) && typeof data.content.id === 'string';
- * ```
- */
-export const isObject = (data: unknown): data is { [key: string]: unknown } => !!data && typeof data === 'object';

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

@@ -1,14 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { SurfacePlugin } from './SurfacePlugin';
-
-export * from './helpers';
-export * from './provides';
-
-export * from './ErrorBoundary';
-export * from './Surface';
-export * from './SurfaceContext';
-
-export default SurfacePlugin;

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

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

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

@@ -1,27 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { type SurfaceDefinition, type SurfaceContextValue } from './SurfaceContext';
-import { type HostContext, type Plugin } from '../plugin-host';
-
-export type SurfaceDefinitions = SurfaceDefinition | SurfaceDefinition[] | SurfaceDefinitions[];
-
-export type SurfaceProvides = {
-  surface: {
-    /**
-     * Used by the `Surface` resolver to find a component to render.
-     */
-    definitions: (context: HostContext) => SurfaceDefinitions;
-  };
-};
-
-export type SurfacePluginProvides = {
-  surface: SurfaceContextValue;
-};
-
-export const parseRootSurfacePlugin = (plugin?: Plugin) =>
-  (plugin?.provides as any)?.surface?.surfaces ? (plugin as Plugin<SurfacePluginProvides>) : undefined;
-
-export const parseSurfacePlugin = (plugin?: Plugin) =>
-  (plugin?.provides as any)?.surface?.definitions ? (plugin as Plugin<SurfaceProvides>) : undefined;