@dxos/app-framework 0.3.3-main.3806cc2

package/src/plugins/PluginHost/plugin.test.ts

@@ -0,0 +1,159 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { expect } from 'chai';
+import { type FC } from 'react';
+
+import { log } from '@dxos/log';
+import { describe, test } from '@dxos/test';
+
+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/PluginHost/plugin.ts

@@ -0,0 +1,82 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type FC, type 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>;
+};
+
+/**
+ * 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: {
+    /**
+     * 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;
+  };
+
+  /**
+   * 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>>;
+
+  /**
+   * 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.
+   */
+  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>;
+};

package/src/plugins/SurfacePlugin/ErrorBoundary.tsx

@@ -0,0 +1,45 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { Component, type FC, type PropsWithChildren } from 'react';
+
+type Props = PropsWithChildren<{ data?: any; fallback: FC<{ error: Error; reset: () => void }> }>;
+type State = { error: Error | undefined };
+
+/**
+ * Surface error boundary.
+ *
+ * For basic usage prefer providing a fallback component to `Surface`.
+ *
+ * For more information on error boundaries, see:
+ * https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary
+ */
+export class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { error: undefined };
+  }
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  override componentDidUpdate(prevProps: Props): void {
+    if (prevProps.data !== this.props.data) {
+      this.resetError();
+    }
+  }
+
+  override render() {
+    if (this.state.error) {
+      return <this.props.fallback error={this.state.error} reset={this.resetError} />;
+    }
+
+    return this.props.children;
+  }
+
+  private resetError() {
+    this.setState({ error: undefined });
+  }
+}

package/src/plugins/SurfacePlugin/Surface.tsx

@@ -0,0 +1,116 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import React, { type PropsWithChildren, type ReactNode } from 'react';
+import { createContext, useContext } from 'react';
+
+import { ErrorBoundary } from './ErrorBoundary';
+import { type SurfaceComponent, useSurface } from './SurfaceRootContext';
+
+/**
+ * Direction determines how multiple components are laid out.
+ */
+export type Direction = 'inline' | 'inline-reverse' | 'block' | 'block-reverse';
+
+export type SurfaceProps = {
+  /**
+   * 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.
+   */
+  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 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;
+};
+
+/**
+ * A surface is a named region of the screen that can be populated by plugins.
+ */
+export const Surface = ({ role, name = role, fallback, ...rest }: SurfaceProps) => {
+  const props = { role, name, fallback, ...rest };
+  const context = useContext(SurfaceContext);
+  const data = props.data ?? ((name && context?.surfaces?.[name]?.data) || {});
+
+  return (
+    <>
+      {fallback ? (
+        <ErrorBoundary data={data} fallback={fallback}>
+          <SurfaceResolver {...props} />
+        </ErrorBoundary>
+      ) : (
+        <SurfaceResolver {...props} />
+      )}
+    </>
+  );
+};
+
+const SurfaceContext = createContext<SurfaceProps | null>(null);
+
+const SurfaceResolver = (props: SurfaceProps) => {
+  const { components } = useSurface();
+  const parent = useContext(SurfaceContext);
+  const nodes = resolveNodes(components, props, parent);
+  const currentContext: SurfaceProps = {
+    ...props,
+    surfaces: {
+      ...((props.name && parent?.surfaces?.[props.name]?.surfaces) || {}),
+      ...props.surfaces,
+    },
+  };
+
+  return <SurfaceContext.Provider value={currentContext}>{nodes}</SurfaceContext.Provider>;
+};
+
+const resolveNodes = (
+  components: Record<string, SurfaceComponent>,
+  props: SurfaceProps,
+  context: SurfaceProps | null,
+): ReactNode[] => {
+  const data = {
+    ...((props.name && context?.surfaces?.[props.name]?.data) || {}),
+    ...props.data,
+  };
+
+  const nodes = Object.entries(components)
+    .map(([key, component]) => {
+      const result = component(data, props.role);
+      return result ? <Wrapper key={key}>{result}</Wrapper> : undefined;
+    })
+    .filter((Component): Component is JSX.Element => Boolean(Component));
+
+  return props.limit ? nodes.slice(0, props.limit) : nodes;
+};
+
+const Wrapper = ({ children }: PropsWithChildren) => <>{children}</>;

package/src/plugins/SurfacePlugin/SurfacePlugin.tsx

@@ -0,0 +1,53 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { deepSignal, shallow } from 'deepsignal/react';
+import React from 'react';
+
+import { type SurfaceComponent, SurfaceProvider, type SurfaceRootContext } from './SurfaceRootContext';
+import type { Plugin, PluginDefinition } from '../PluginHost';
+import { filterPlugins } from '../helpers';
+
+export type SurfaceProvides = {
+  surface: {
+    /**
+     * Used by the `Surface` resolver to find a component to render.
+     */
+    component: SurfaceComponent;
+  };
+};
+
+export type SurfacePluginProvides = {
+  surface: SurfaceRootContext;
+};
+
+export const parseRootSurfacePlugin = (plugin?: Plugin) =>
+  (plugin?.provides as any)?.surface?.components ? (plugin as Plugin<SurfacePluginProvides>) : undefined;
+
+export const parseSurfacePlugin = (plugin?: Plugin) =>
+  (plugin?.provides as any)?.surface?.component ? (plugin as Plugin<SurfaceProvides>) : undefined;
+
+/**
+ * Provides a registry of surface components.
+ */
+export const SurfacePlugin = (): PluginDefinition<SurfacePluginProvides> => {
+  const state = deepSignal<SurfaceRootContext>({ components: {} });
+
+  return {
+    meta: {
+      id: 'dxos.org/plugin/surface',
+    },
+    ready: async (plugins) => {
+      state.components = shallow(
+        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>,
+    },
+  };
+};

package/src/plugins/SurfacePlugin/SurfaceRootContext.tsx

@@ -0,0 +1,22 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { createContext, useContext, type Context, type Provider, type ReactNode } from 'react';
+
+/**
+ * Function which resolves a Surface.
+ *
+ * If a null value is returned, the rendering is deferred to other plugins.
+ */
+export type SurfaceComponent = (data: Record<string, unknown>, role?: string) => ReactNode;
+
+export type SurfaceRootContext = {
+  components: Record<string, SurfaceComponent>;
+};
+
+const SurfaceRootContext: Context<SurfaceRootContext> = createContext<SurfaceRootContext>({ components: {} });
+
+export const useSurface = () => useContext(SurfaceRootContext);
+
+export const SurfaceProvider: Provider<SurfaceRootContext> = SurfaceRootContext.Provider;

package/src/plugins/SurfacePlugin/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './ErrorBoundary';
+export * from './Surface';
+export * from './SurfacePlugin';
+export * from './SurfaceRootContext';

package/src/plugins/common/graph.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import type { Graph, Node } from '@dxos/app-graph';
+import type { UnsubscribeCallback } from '@dxos/async';
+
+import type { Plugin } from '../PluginHost';
+
+/**
+ * Provides for a plugin that exposes the application graph.
+ */
+export type GraphPluginProvides = {
+  graph: Graph;
+};
+
+export type GraphBuilderProvides = {
+  graph: {
+    builder: (params: { parent: Node; plugins: Plugin[] }) => UnsubscribeCallback | void;
+  };
+};
+
+/**
+ * Type guard for graph plugins.
+ */
+export const parseGraphPlugin = (plugin: Plugin) =>
+  (plugin.provides as any).graph?.root ? (plugin as Plugin<GraphPluginProvides>) : undefined;
+
+/**
+ * Type guard for graph builder plugins.
+ */
+export const parseGraphBuilderPlugin = (plugin: Plugin) =>
+  (plugin.provides as any).graph?.builder ? (plugin as Plugin<GraphBuilderProvides>) : undefined;

package/src/plugins/common/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './graph';
+export * from './layout';
+export * from './translations';

package/src/plugins/common/layout.ts

@@ -0,0 +1,102 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { z } from 'zod';
+
+import type { Plugin } from '../PluginHost';
+
+//
+// Provides
+//
+
+/**
+ * Basic state provided by a layout plugin.
+ */
+export const Layout = z.object({
+  fullscreen: z.boolean(),
+  sidebarOpen: z.boolean(),
+  complementarySidebarOpen: z.boolean(),
+
+  dialogContent: z.any().optional().describe('Data to be passed to the dialog Surface.'),
+  dialogOpen: z.boolean(),
+
+  popoverAnchorId: z.string().optional(),
+  popoverContent: z.any().optional().describe('Data to be passed to the popover Surface.'),
+  popoverOpen: z.boolean(),
+
+  // TODO(wittjosiah): Array?
+  active: z.string().optional().describe('Id of the currently active item.'),
+  // TODO(wittjosiah): History?
+  previous: z.string().optional(),
+});
+
+export type Layout = z.infer<typeof Layout>;
+
+/**
+ * Provides for a plugin that can manage the app layout.
+ */
+export type LayoutProvides = {
+  layout: Readonly<Layout>;
+};
+
+/**
+ * Type guard for layout plugins.
+ */
+export const parseLayoutPlugin = (plugin: Plugin) => {
+  const { success } = Layout.safeParse((plugin.provides as any).layout);
+  return success ? (plugin as Plugin<LayoutProvides>) : undefined;
+};
+
+//
+// Intents
+//
+
+const LAYOUT_ACTION = 'dxos.org/plugin/intent';
+// TODO(wittjosiah): Consider consolidating some action types (e.g. toggle).
+export enum LayoutAction {
+  TOGGLE_FULLSCREEN = `${LAYOUT_ACTION}/toggle-fullscreen`,
+  TOGGLE_SIDEBAR = `${LAYOUT_ACTION}/toggle-sidebar`,
+  TOGGLE_COMPLEMENTARY_SIDEBAR = `${LAYOUT_ACTION}/toggle-complementary-sidebar`,
+  OPEN_DIALOG = `${LAYOUT_ACTION}/open-dialog`,
+  CLOSE_DIALOG = `${LAYOUT_ACTION}/close-dialog`,
+  OPEN_POPOVER = `${LAYOUT_ACTION}/open-popover`,
+  CLOSE_POPOVER = `${LAYOUT_ACTION}/close-popover`,
+  ACTIVATE = `${LAYOUT_ACTION}/activate`,
+}
+
+/**
+ * Expected payload for layout actions.
+ */
+export namespace LayoutAction {
+  export type ToggleFullscreen = {
+    state?: boolean;
+  };
+
+  export type ToggleSidebar = {
+    state?: boolean;
+  };
+
+  export type ToggleComplementarySidebar = {
+    state?: boolean;
+  };
+
+  export type OpenDialog = {
+    component: string;
+    subject: any;
+  };
+
+  export type CloseDialog = {};
+
+  export type OpenPopover = {
+    anchorId: string;
+    component: string;
+    subject: any;
+  };
+
+  export type ClosePopover = {};
+
+  export type Activate = {
+    id: string;
+  };
+}

package/src/plugins/common/translations.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { z } from 'zod';
+
+import type { Plugin } from '../PluginHost';
+
+export const ResourceKey = z.union([z.string(), z.record(z.any())]);
+export type ResourceKey = z.infer<typeof ResourceKey>;
+
+export const ResourceLanguage = z.record(ResourceKey);
+export type ResourceLanguage = z.infer<typeof ResourceLanguage>;
+
+/**
+ * A resource is a collection of translations for a language.
+ */
+export const Resource = z.record(ResourceLanguage);
+export type Resource = z.infer<typeof Resource>;
+
+/**
+ * Provides for a plugin that exposes translations.
+ */
+export type TranslationsProvides = {
+  translations: Readonly<Resource[]>;
+};
+
+/**
+ * Type guard for translation plugins.
+ */
+export const parseTranslationsPlugin = (plugin: Plugin) => {
+  const { success } = z.array(Resource).safeParse((plugin.provides as any).translations);
+  return success ? (plugin as Plugin<TranslationsProvides>) : undefined;
+};