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

package/src/plugin-intent/intent.ts

@@ -0,0 +1,146 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Schema as S } from '@effect/schema';
+
+export type IntentParams = {
+  readonly input: S.Schema.All;
+  readonly output: S.Schema.All;
+};
+
+export type IntentData<Fields extends IntentParams> =
+  S.Schema.Type<S.Struct<Fields>> extends { readonly input: any } ? S.Schema.Type<S.Struct<Fields>>['input'] : any;
+
+export type IntentResultData<Fields extends IntentParams> =
+  S.Schema.Type<S.Struct<Fields>> extends { readonly output: any } ? S.Schema.Type<S.Struct<Fields>>['output'] : any;
+
+export type IntentSchema<Tag extends string, Fields extends IntentParams> = S.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>;
+
+  /**
+   * Module ID.
+   * If specified, the intent will be sent explicitly to the plugin module.
+   * Otherwise, the intent will be sent to all plugins, in order and the first to resolve a non-null value will be used.
+   */
+  module?: string;
+
+  /**
+   * 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, 'module' | '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 _ = S.validateSync(schema.fields.input as S.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, 'module' | '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 = S.Union(
+  S.String,
+  S.mutable(S.Tuple(S.String, S.mutable(S.Struct({ ns: S.String, count: S.optional(S.Number) })))),
+);
+export type Label = S.Schema.Type<typeof Label>;

package/src/plugin-settings/SettingsPlugin.ts

@@ -0,0 +1,35 @@
+//
+// 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 }, [
+    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.SetupIntents,
+      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

@@ -0,0 +1,27 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Schema as S } from '@effect/schema';
+
+export const SETTINGS_PLUGIN = 'dxos.org/plugin/settings';
+export const SETTINGS_ACTION = `${SETTINGS_PLUGIN}/action`;
+export const SETTINGS_ID = 'dxos:settings';
+export const SETTINGS_KEY = 'settings';
+
+export namespace SettingsAction {
+  export class Open extends S.TaggedClass<Open>()(`${SETTINGS_ACTION}/open`, {
+    input: S.Struct({
+      plugin: S.optional(S.String),
+    }),
+    output: S.Void,
+  }) {}
+
+  export class OpenPluginRegistry extends S.TaggedClass<OpenPluginRegistry>()(
+    `${SETTINGS_ACTION}/open-plugin-registry`,
+    {
+      input: S.Void,
+      output: S.Void,
+    },
+  ) {}
+}

package/src/plugin-settings/app-graph-builder.ts

@@ -0,0 +1,122 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createExtension, type Node } from '@dxos/app-graph';
+import { type SettingsStore, type SettingsValue } from '@dxos/local-storage';
+import { nonNullable } from '@dxos/util';
+
+import { SETTINGS_ID, SETTINGS_KEY, SETTINGS_PLUGIN, SettingsAction } from './actions';
+import { Capabilities } from '../common';
+import { contributes, type PluginMeta, type PluginsContext } from '../core';
+import { createIntent } from '../plugin-intent';
+
+export default (context: PluginsContext) =>
+  contributes(Capabilities.AppGraphBuilder, [
+    createExtension({
+      id: `${SETTINGS_PLUGIN}/action`,
+      filter: (node): node is Node<null> => node.id === 'root',
+      actions: () => [
+        {
+          id: SETTINGS_PLUGIN,
+          data: async () => {
+            const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher);
+            await dispatch(createIntent(SettingsAction.Open));
+          },
+          properties: {
+            label: ['open settings label', { ns: SETTINGS_PLUGIN }],
+            icon: 'ph--gear--regular',
+            keyBinding: {
+              macos: 'meta+,',
+              windows: 'alt+,',
+            },
+          },
+        },
+      ],
+    }),
+    createExtension({
+      id: `${SETTINGS_PLUGIN}/core`,
+      filter: (node): node is Node<null> => node.id === 'root',
+      connector: () => [
+        {
+          id: SETTINGS_ID,
+          type: SETTINGS_PLUGIN,
+          properties: {
+            label: ['app settings label', { ns: SETTINGS_PLUGIN }],
+            icon: 'ph--gear--regular',
+            disposition: 'pin-end',
+            position: 'fallback',
+            testId: 'treeView.appSettings',
+          },
+        },
+      ],
+    }),
+    createExtension({
+      id: `${SETTINGS_PLUGIN}/core-plugins`,
+      filter: (node): node is Node<null> => node.id === SETTINGS_ID,
+      connector: () => {
+        const manager = context.requestCapability(Capabilities.PluginManager);
+        const [settingsStore] = context.requestCapabilities(Capabilities.SettingsStore);
+        return [
+          ...manager.plugins
+            .filter((plugin) => manager.core.includes(plugin.meta.id))
+            .map((plugin): [PluginMeta, SettingsStore<SettingsValue>] | null => {
+              const settings = settingsStore?.getStore(plugin.meta.id);
+              if (!settings) {
+                return null;
+              }
+
+              return [plugin.meta, settings];
+            })
+            .filter(nonNullable)
+            .map(([meta, settings]) => ({
+              id: `${SETTINGS_KEY}:${meta.id.replaceAll('/', ':')}`,
+              type: 'category',
+              data: settings,
+              properties: {
+                label: meta.name ?? meta.id,
+                icon: meta.icon ?? 'ph--circle--regular',
+              },
+            })),
+
+          {
+            id: `${SETTINGS_KEY}:custom-plugins`,
+            type: 'collection',
+            properties: {
+              label: ['custom plugins label', { ns: SETTINGS_PLUGIN }],
+              icon: 'ph--squares-four--regular',
+              role: 'branch',
+            },
+          },
+        ];
+      },
+    }),
+    createExtension({
+      id: `${SETTINGS_PLUGIN}/custom-plugins`,
+      filter: (node): node is Node<null> => node.id === `${SETTINGS_KEY}:custom-plugins`,
+      connector: () => {
+        const manager = context.requestCapability(Capabilities.PluginManager);
+        const [settingsStore] = context.requestCapabilities(Capabilities.SettingsStore);
+        return manager.plugins
+          .filter((plugin) => !manager.core.includes(plugin.meta.id))
+          .map((plugin): [PluginMeta, SettingsStore<SettingsValue>] | null => {
+            const settings = settingsStore?.getStore(plugin.meta.id);
+            if (!settings) {
+              return null;
+            }
+
+            return [plugin.meta, settings];
+          })
+          .filter(nonNullable)
+          .map(([meta, settings]) => ({
+            id: `${SETTINGS_KEY}:${meta.id.replaceAll('/', ':')}`,
+            type: 'category',
+            data: settings,
+            properties: {
+              label: meta.name ?? meta.id,
+              icon: meta.icon ?? 'ph--circle--regular',
+            },
+          }));
+      },
+    }),
+  ]);

package/src/plugin-settings/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './actions';
+export * from './SettingsPlugin';

package/src/plugin-settings/intent-resolver.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { pipe } from 'effect';
+
+import { SETTINGS_ID, SETTINGS_KEY, SettingsAction } from './actions';
+import { Capabilities, LayoutAction } from '../common';
+import { contributes } from '../core';
+import { createResolver, createIntent, chain } from '../plugin-intent';
+
+export default () =>
+  contributes(
+    Capabilities.IntentResolver,
+    createResolver({
+      intent: SettingsAction.Open,
+      resolve: ({ plugin }) => {
+        return {
+          intents: [
+            pipe(
+              createIntent(LayoutAction.SwitchWorkspace, { part: 'workspace', subject: SETTINGS_ID }),
+              chain(LayoutAction.Open, { part: 'main', subject: [`${SETTINGS_KEY}:${plugin.replaceAll('/', ':')}`] }),
+            ),
+          ],
+        };
+      },
+    }),
+  );

package/src/plugin-settings/store.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { RootSettingsStore } from '@dxos/local-storage';
+
+import { Capabilities } from '../common';
+import { contributes, type PluginsContext } from '../core';
+
+export default (context: PluginsContext) => {
+  // TODO(wittjosiah): This should subscribe to capabilities and create stores for newly added settings objects.
+  const allSettings = context.requestCapabilities(Capabilities.Settings);
+  const settingsStore = new RootSettingsStore();
+
+  allSettings.forEach((setting) => {
+    settingsStore.createStore(setting as any);
+  });
+
+  return contributes(Capabilities.SettingsStore, settingsStore);
+};

package/src/plugin-settings/translations.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { SETTINGS_PLUGIN } from './actions';
+
+export default [
+  {
+    'en-US': {
+      [SETTINGS_PLUGIN]: {
+        'open settings label': 'Open settings',
+        'app settings label': 'Settings',
+        'custom plugins label': 'Plugins',
+      },
+    },
+  },
+];

package/src/react/IntentContext.tsx

@@ -0,0 +1,34 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Context, createContext, useContext, type Provider, useEffect } from 'react';
+
+import { raise } from '@dxos/debug';
+import { pick } from '@dxos/util';
+
+import { usePluginManager } from './PluginManagerProvider';
+import { Capabilities } from '../common';
+import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
+
+const IntentContext: Context<IntentContext | undefined> = createContext<IntentContext | undefined>(undefined);
+
+export const useIntentDispatcher = (): Pick<IntentContext, 'dispatch' | 'dispatchPromise'> => {
+  const context = useContext(IntentContext) ?? raise(new Error('IntentContext not found'));
+  return pick(context, ['dispatch', 'dispatchPromise']);
+};
+
+export const useIntentResolver = (module: string, resolver: AnyIntentResolver) => {
+  const manager = usePluginManager();
+  useEffect(() => {
+    manager.context.contributeCapability({
+      module,
+      interface: Capabilities.IntentResolver,
+      implementation: resolver,
+    });
+
+    return () => manager.context.removeCapability(Capabilities.IntentResolver, resolver);
+  }, [module, resolver]);
+};
+
+export const IntentProvider: Provider<IntentContext | undefined> = IntentContext.Provider;

package/src/react/PluginManagerProvider.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { createContext, useContext } from 'react';
+
+import { raise } from '@dxos/debug';
+
+import { type PluginManager } from '../core';
+
+const PluginManagerContext = createContext<PluginManager | undefined>(undefined);
+
+/**
+ * Get the plugin manager.
+ */
+export const usePluginManager = (): PluginManager =>
+  useContext(PluginManagerContext) ?? raise(new Error('Missing PluginManagerContext'));
+
+/**
+ * Context provider for a plugin manager.
+ */
+export const PluginManagerProvider = PluginManagerContext.Provider;

package/src/react/Surface.stories.tsx

@@ -0,0 +1,96 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import '@dxos-theme';
+
+import React, { useCallback, useState } from 'react';
+
+import { faker } from '@dxos/random';
+import { Button, List, ListItem } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/storybook-utils';
+
+import { PluginManagerProvider, usePluginManager } from './PluginManagerProvider';
+import { Surface, useSurfaces } from './Surface';
+import { Capabilities, createSurface } from '../common';
+import { type PluginManager } from '../core';
+import { setupPluginManager } from '../testing';
+
+const randomColor = (): string => {
+  const hue = faker.number.int({ min: 0, max: 360 });
+  const saturation = faker.number.int({ min: 50, max: 90 });
+  const lightness = faker.number.int({ min: 40, max: 70 });
+  return `hsl(${hue}, ${saturation}%, ${lightness}%)`;
+};
+
+const Story = () => {
+  const manager = usePluginManager();
+  const surfaces = useSurfaces();
+  const [picked, setPicked] = useState('test');
+
+  const handleAdd = useCallback(() => {
+    const id = `test-${faker.number.int({ min: 0, max: 1_000_000 })}`;
+    const backgroundColor = randomColor();
+
+    manager.context.contributeCapability({
+      module: 'test',
+      interface: Capabilities.ReactSurface,
+      implementation: createSurface({
+        id,
+        role: id,
+        component: () => (
+          <div className='flex-1' style={{ backgroundColor }}>
+            {id}
+          </div>
+        ),
+      }),
+    });
+
+    setPicked(id);
+  }, [manager]);
+
+  const handlePick = useCallback(() => {
+    setPicked(faker.helpers.arrayElement(surfaces).id);
+  }, [surfaces]);
+
+  return (
+    <div className='flex flex-col gap-2'>
+      <div className='flex gap-2'>
+        <Button onClick={handleAdd}>Add</Button>
+        <Button onClick={handlePick}>Pick</Button>
+      </div>
+      <div className='flex gap-2'>
+        <div className='flex-1'>
+          <List itemSizes='one'>
+            {surfaces.map((surface) => (
+              <ListItem.Root key={surface.id} id={surface.id}>
+                <ListItem.Heading classNames='grow pbs-2'>{surface.id}</ListItem.Heading>
+              </ListItem.Root>
+            ))}
+          </List>
+        </div>
+        <div className='flex-1'>
+          <Surface role={picked} limit={1} />
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default {
+  title: 'sdk/app-framework/Surface',
+  render: ({ manager }: { manager: PluginManager }) => {
+    return (
+      <PluginManagerProvider value={manager}>
+        <Story />
+      </PluginManagerProvider>
+    );
+  },
+  // NOTE: Intentionally not using withPluginManager to try to reduce surface area of the story.
+  decorators: [withTheme, withLayout({ tooltips: true })],
+  args: {
+    manager: setupPluginManager(),
+  },
+};
+
+export const Default = {};

package/src/react/Surface.tsx

@@ -0,0 +1,75 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { memo, forwardRef, Suspense, useMemo } from 'react';
+
+import { useDefaultValue } from '@dxos/react-hooks';
+import { byPosition } from '@dxos/util';
+
+import { ErrorBoundary } from './ErrorBoundary';
+import { useCapabilities } from './useCapabilities';
+import { Capabilities, type SurfaceDefinition, type SurfaceProps } from '../common';
+import { type PluginsContext } from '../core';
+
+/**
+ * @internal
+ */
+export const useSurfaces = () => {
+  const surfaces = useCapabilities(Capabilities.ReactSurface);
+  return useMemo(() => surfaces.flat(), [surfaces]);
+};
+
+const findCandidates = (surfaces: SurfaceDefinition[], { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
+  return Object.values(surfaces)
+    .filter((definition) =>
+      Array.isArray(definition.role) ? definition.role.includes(role) : definition.role === role,
+    )
+    .filter(({ filter }) => (filter ? filter(data ?? {}) : true))
+    .toSorted(byPosition);
+};
+
+/**
+ * @returns `true` if there is a contributed surface which matches the specified role & data, `false` otherwise.
+ */
+export const isSurfaceAvailable = (context: PluginsContext, { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
+  const surfaces = context.requestCapabilities(Capabilities.ReactSurface);
+  const candidates = findCandidates(surfaces.flat(), { role, data });
+  return candidates.length > 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, data: _data, limit, fallback, placeholder, ...rest }, forwardedRef) => {
+      // TODO(wittjosiah): This will make all surfaces depend on a single signal.
+      //   This isn't ideal because it means that any change to the data will cause all surfaces to re-render.
+      //   This effectively means that plugin modules which contribute surfaces need to all be activated at startup.
+      //   This should be fine for now because it's how it worked prior to capabilities api anyways.
+      //   In the future, it would be nice to be able to bucket the surface contributions by role.
+      const surfaces = useSurfaces();
+      const data = useDefaultValue(_data, () => ({}));
+
+      // NOTE: Memoizing the candidates makes the surface not re-render based on reactivity within data.
+      const definitions = findCandidates(surfaces, { role, data });
+      const candidates = limit ? definitions.slice(0, limit) : definitions;
+      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
+      );
+    },
+  ),
+);
+
+Surface.displayName = 'Surface';

package/src/react/common.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useCapability } from './useCapabilities';
+import { Capabilities } from '../common';
+
+export const useIntentDispatcher = () => useCapability(Capabilities.IntentDispatcher);
+
+export const useAppGraph = () => useCapability(Capabilities.AppGraph);
+
+export const useLayout = () => useCapability(Capabilities.Layout);

package/src/react/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './common';
+export * from './ErrorBoundary';
+export * from './PluginManagerProvider';
+export * from './Surface';
+export * from './useCapabilities';
+export * from './useIntentResolver';