@dxos/app-framework 0.8.4-main.e8ec1fe → 0.8.4-main.ef1bc66f44

package/src/plugin-intent/intent.ts

@@ -1,154 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-
-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-intent/meta.ts

@@ -1,10 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { type PluginMeta } from '@dxos/app-framework';
-
-export const meta: PluginMeta = {
-  id: 'dxos.org/plugin/intent',
-  name: 'Intent',
-};

package/src/plugin-settings/SettingsPlugin.ts

@@ -1,34 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { Capabilities, Events } from '../common';
-import { contributes, defineModule, definePlugin, lazy } from '../core';
-
-import { meta } from './meta';
-import { translations } from './translations';
-
-export const SettingsPlugin = definePlugin(meta, () => [
-  defineModule({
-    id: `${meta.id}/module/store`,
-    activatesOn: Events.Startup,
-    activatesBefore: [Events.SetupSettings],
-    activatesAfter: [Events.SettingsReady],
-    activate: lazy(() => import('./store')),
-  }),
-  defineModule({
-    id: `${meta.id}/module/translations`,
-    activatesOn: Events.SetupTranslations,
-    activate: () => contributes(Capabilities.Translations, translations),
-  }),
-  defineModule({
-    id: `${meta.id}/module/intent-resolver`,
-    activatesOn: Events.SetupIntentResolver,
-    activate: lazy(() => import('./intent-resolver')),
-  }),
-  defineModule({
-    id: `${meta.id}/module/app-graph-builder`,
-    activatesOn: Events.SetupAppGraph,
-    activate: lazy(() => import('./app-graph-builder')),
-  }),
-]);

package/src/plugin-settings/actions.ts

@@ -1,25 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-
-import { meta } from './meta';
-
-// TODO(burdon): Document.
-export const SETTINGS_ID = '!dxos:settings';
-export const SETTINGS_KEY = 'settings';
-
-export namespace SettingsAction {
-  export class Open extends Schema.TaggedClass<Open>()(`${meta.id}/open`, {
-    input: Schema.Struct({
-      plugin: Schema.optional(Schema.String),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class OpenPluginRegistry extends Schema.TaggedClass<OpenPluginRegistry>()(`${meta.id}/open-plugin-registry`, {
-    input: Schema.Void,
-    output: Schema.Void,
-  }) {}
-}

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

@@ -1,160 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { Atom } from '@effect-atom/atom-react';
-import * as Function from 'effect/Function';
-import * as Option from 'effect/Option';
-
-import { ROOT_ID, createExtension } from '@dxos/app-graph';
-import { type SettingsStore, type SettingsValue } from '@dxos/local-storage';
-import { isNonNullable } from '@dxos/util';
-
-import { Capabilities } from '../common';
-import { type PluginContext, type PluginMeta, contributes } from '../core';
-import { createIntent } from '../plugin-intent';
-
-import { SETTINGS_ID, SETTINGS_KEY, SettingsAction } from './actions';
-import { meta } from './meta';
-
-export default (context: PluginContext) =>
-  contributes(Capabilities.AppGraphBuilder, [
-    createExtension({
-      id: `${meta.id}/action`,
-      actions: (node) =>
-        Atom.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
-            Option.map(() => [
-              {
-                id: meta.id,
-                data: async () => {
-                  const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
-                  await dispatch(createIntent(SettingsAction.Open));
-                },
-                properties: {
-                  label: ['open settings label', { ns: meta.id }],
-                  icon: 'ph--gear--regular',
-                  disposition: 'menu',
-                  keyBinding: {
-                    macos: 'meta+,',
-                    windows: 'alt+,',
-                  },
-                },
-              },
-            ]),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-    createExtension({
-      id: `${meta.id}/core`,
-      connector: (node) =>
-        Atom.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
-            Option.map(() => [
-              {
-                id: SETTINGS_ID,
-                type: meta.id,
-                properties: {
-                  label: ['app settings label', { ns: meta.id }],
-                  icon: 'ph--gear--regular',
-                  disposition: 'pin-end',
-                  position: 'hoist',
-                  testId: 'treeView.appSettings',
-                },
-              },
-            ]),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-    createExtension({
-      id: `${meta.id}/core-plugins`,
-      connector: (node) =>
-        Atom.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.id !== SETTINGS_ID ? Option.none() : Option.some(node))),
-            Option.map(() => {
-              const manager = get(context.capability(Capabilities.PluginManager));
-              const [settingsStore] = get(context.capabilities(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(isNonNullable)
-                  .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: 'category',
-                  properties: {
-                    label: ['custom plugins label', { ns: meta.id }],
-                    icon: 'ph--squares-four--regular',
-                    role: 'branch',
-                    disposition: 'collection',
-                  },
-                },
-              ];
-            }),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-    createExtension({
-      id: `${meta.id}/custom-plugins`,
-      connector: (node) =>
-        Atom.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) =>
-              node.id !== `${SETTINGS_KEY}:custom-plugins` ? Option.none() : Option.some(node),
-            ),
-            Option.map(() => {
-              const manager = get(context.capability(Capabilities.PluginManager));
-              const [settingsStore] = get(context.capabilities(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(isNonNullable)
-                .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',
-                  },
-                }));
-            }),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-  ]);

package/src/plugin-settings/index.ts

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

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

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

package/src/plugin-settings/meta.ts

@@ -1,10 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { type PluginMeta } from '@dxos/app-framework';
-
-export const meta: PluginMeta = {
-  id: 'dxos.org/plugin/settings',
-  name: 'Settings',
-};

package/src/plugin-settings/store.ts

@@ -1,33 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { RootSettingsStore } from '@dxos/local-storage';
-
-import { Capabilities } from '../common';
-import { type PluginContext, contributes } from '../core';
-
-export default (context: PluginContext) => {
-  // TODO(wittjosiah): Replace with atom?
-  const settingsStore = new RootSettingsStore();
-
-  let previous: Capabilities.Settings[] = [];
-  const registry = context.getCapability(Capabilities.AtomRegistry);
-  const cancel = registry.subscribe(
-    context.capabilities(Capabilities.Settings),
-    (allSettings) => {
-      const added = allSettings.filter((setting) => !previous.includes(setting));
-      const removed = previous.filter((setting) => !allSettings.includes(setting));
-      previous = allSettings;
-      added.forEach((setting) => {
-        settingsStore.createStore(setting as any);
-      });
-      removed.forEach((setting) => {
-        settingsStore.removeStore(setting.prefix);
-      });
-    },
-    { immediate: true },
-  );
-
-  return contributes(Capabilities.SettingsStore, settingsStore, () => cancel());
-};

package/src/plugin-settings/translations.ts

@@ -1,19 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { type Resource } from '../common';
-
-import { meta } from './meta';
-
-export const translations = [
-  {
-    'en-US': {
-      [meta.id]: {
-        'open settings label': 'Open settings',
-        'app settings label': 'Settings',
-        'custom plugins label': 'Plugins',
-      },
-    },
-  },
-] as const satisfies Resource[];

package/src/react/App.stories.tsx

@@ -1,33 +0,0 @@
-//
-// Copyright 2022 DXOS.org
-//
-
-import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React from 'react';
-
-import { withTheme } from '@dxos/react-ui/testing';
-
-import { useApp } from './useApp';
-
-const DefaultStory = () => {
-  const App = useApp({
-    placeholder: () => <div className='fixed inset-0 flex items-center justify-center'>Loading...</div>,
-  });
-
-  return <App />;
-};
-
-const meta = {
-  title: 'sdk/app-framework/App',
-  render: DefaultStory,
-  decorators: [withTheme],
-  parameters: {
-    layout: 'fullscreen',
-  },
-} satisfies Meta;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {};

package/src/react/IntentContext.tsx

@@ -1,35 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { type Context, type Provider, createContext, useContext, useEffect } from 'react';
-
-import { raise } from '@dxos/debug';
-import { pick } from '@dxos/util';
-
-import { Capabilities } from '../common';
-import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
-
-import { usePluginManager } from './PluginManagerProvider';
-
-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/Surface.tsx

@@ -1,109 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import React, {
-  Fragment,
-  type NamedExoticComponent,
-  type RefAttributes,
-  Suspense,
-  forwardRef,
-  memo,
-  useMemo,
-} from 'react';
-
-import { useDefaultValue } from '@dxos/react-hooks';
-import { byPosition } from '@dxos/util';
-
-import { Capabilities, type SurfaceDefinition, type SurfaceProps } from '../common';
-import { type PluginContext } from '../core';
-
-import { ErrorBoundary } from './ErrorBoundary';
-import { useCapabilities } from './useCapabilities';
-
-const DEFAULT_PLACEHOLDER = <Fragment />;
-
-/**
- * A surface is a named region of the screen that can be populated by plugins.
- */
-export const Surface: NamedExoticComponent<SurfaceProps & RefAttributes<HTMLElement>> = memo(
-  forwardRef(
-    (
-      { id: _id, role, data: dataParam, limit, fallback = DefaultFallback, placeholder = DEFAULT_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 anyway.
-      //   In the future, it would be nice to be able to bucket the surface contributions by role.
-      const surfaces = useSurfaces();
-      const data = useDefaultValue(dataParam, () => ({}));
-
-      // 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(({ id, component: Component }) => (
-        <Component ref={forwardedRef} key={id} id={id} role={role} data={data} limit={limit} {...rest} />
-      ));
-
-      // TODO(burdon): Able to inject DOM properties into root (e.g., object.id).
-      const suspense = <Suspense fallback={placeholder}>{nodes}</Suspense>;
-
-      return (
-        <ErrorBoundary data={data} fallback={fallback}>
-          {suspense}
-        </ErrorBoundary>
-      );
-    },
-  ),
-);
-
-// TODO(burdon): Make user facing, with telemetry.
-// TODO(burdon): Change based on dev/prod mode; infer subject type, id.
-const DefaultFallback = ({ data, error, dev }: { data: any; error: Error; dev?: boolean }) => {
-  if (dev) {
-    return (
-      <div className='flex flex-col gap-4 p-4 is-full overflow-y-auto'>
-        <h1 className='flex gap-2 text-sm mbs-2'>{error.message}</h1>
-        <pre className='overflow-auto text-xs text-description'>{JSON.stringify(data, null, 2)}</pre>
-      </div>
-    );
-  }
-
-  return (
-    <div className='flex flex-col gap-4 p-4 is-full overflow-y-auto border border-roseFill'>
-      <h1 className='flex gap-2 text-sm mbs-2 text-rose-500'>{error.message}</h1>
-      <pre className='overflow-auto text-xs text-description'>{error.stack}</pre>
-      <pre className='overflow-auto text-xs text-description'>{JSON.stringify(data, null, 2)}</pre>
-    </div>
-  );
-};
-
-/**
- * @internal
- */
-export const useSurfaces = () => {
-  const surfaces = useCapabilities(Capabilities.ReactSurface);
-  return useMemo(() => surfaces.flat(), [surfaces]);
-};
-
-/**
- * @returns `true` if there is a contributed surface which matches the specified role & data, `false` otherwise.
- */
-export const isSurfaceAvailable = (context: PluginContext, { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
-  const surfaces = context.getCapabilities(Capabilities.ReactSurface);
-  const candidates = findCandidates(surfaces.flat(), { role, data });
-  return candidates.length > 0;
-};
-
-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);
-};
-
-Surface.displayName = 'Surface';

package/src/react/common.ts

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