@dxos/app-framework 0.8.4-main.84f28bd → 0.8.4-main.a4bbb77

package/src/plugin-intent/actions.ts

@@ -5,15 +5,13 @@
 import { Schema } from 'effect';
 
 import { Label } from './intent';
-
-export const INTENT_PLUGIN = 'dxos.org/plugin/intent';
-export const INTENT_ACTION = `${INTENT_PLUGIN}/action`;
+import { meta } from './meta';
 
 export namespace IntentAction {
   /**
    * Log an intent.
    */
-  export class Track extends Schema.TaggedClass<Track>()(`${INTENT_ACTION}/track`, {
+  export class Track extends Schema.TaggedClass<Track>()(`${meta.id}/action/track`, {
     input: Schema.Struct({
       intents: Schema.Array(Schema.String),
       error: Schema.optional(Schema.String),
@@ -24,7 +22,7 @@ export namespace IntentAction {
   /**
    * Fired after an intent is dispatched if the intent is undoable.
    */
-  export class ShowUndo extends Schema.TaggedClass<ShowUndo>()(`${INTENT_ACTION}/show-undo`, {
+  export class ShowUndo extends Schema.TaggedClass<ShowUndo>()(`${meta.id}/action/show-undo`, {
     input: Schema.Struct({
       message: Label,
     }),

package/src/plugin-intent/errors.ts

@@ -28,6 +28,7 @@ export class NoResolversError extends BaseError {
   }
 }
 
+// TODO(burdon): Detect loops.
 export class CycleDetectedError extends BaseError {
   constructor(context?: Record<string, any>) {
     super(

package/src/plugin-intent/index.ts

@@ -3,6 +3,7 @@
 //
 
 export * from './actions';
+export * from './errors';
 export * from './intent';
 export * from './intent-dispatcher';
 export * from './IntentPlugin';

package/src/plugin-intent/intent-dispatcher.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema, Effect, Fiber, pipe } from 'effect';
+import { Effect, Fiber, Schema, pipe } from 'effect';
 import { describe, expect, test } from 'vitest';
 
 import { chain, createIntent } from './intent';

package/src/plugin-intent/intent-dispatcher.ts

@@ -2,17 +2,19 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Effect, Option, pipe, Ref } from 'effect';
+import { Effect, Option, Ref, pipe } from 'effect';
 import { type Simplify } from 'effect/Types';
 
 import { live } from '@dxos/live-object';
 import { log } from '@dxos/log';
-import { byPosition, type MaybePromise, type Position, type GuardedType } from '@dxos/util';
+import { type GuardedType, type MaybePromise, type Position, byPosition } from '@dxos/util';
+
+import { Capabilities, Events } from '../common';
+import { type PluginContext, contributes } from '../core';
 
 import { IntentAction } from './actions';
 import { CycleDetectedError, NoResolversError } from './errors';
 import {
-  createIntent,
   type AnyIntent,
   type AnyIntentChain,
   type Intent,
@@ -22,9 +24,8 @@ import {
   type IntentResultData,
   type IntentSchema,
   type Label,
+  createIntent,
 } from './intent';
-import { Events, Capabilities } from '../common';
-import { contributes, type PluginContext } from '../core';
 
 const EXECUTION_LIMIT = 100;
 const HISTORY_LIMIT = 100;
@@ -196,7 +197,7 @@ export const createDispatcher = (
         .filter((resolver) => !resolver.filter || resolver.filter(intent.data))
         .toSorted(byPosition);
       if (candidates.length === 0) {
-        yield* Effect.fail(new NoResolversError(intent.id));
+        return yield* Effect.fail(new NoResolversError(intent.id));
       }
 
       const effect = candidates[0].resolve(intent.data, intent.undo ?? false);
@@ -207,7 +208,7 @@ export const createDispatcher = (
   const dispatch: IntentDispatcher = (intentChain, depth = 0) => {
     return Effect.gen(function* () {
       if (depth > executionLimit) {
-        yield* Effect.fail(new CycleDetectedError());
+        return yield* Effect.fail(new CycleDetectedError());
       }
 
       const resultsRef = yield* Ref.make<AnyIntentResult[]>([]);
@@ -230,7 +231,7 @@ export const createDispatcher = (
           //     error: result.error.message,
           //   }),
           // );
-          yield* Effect.fail(result.error);
+          return yield* Effect.fail(result.error);
         }
       }
 

package/src/plugin-intent/meta.ts

@@ -0,0 +1,10 @@
+//
+// 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

@@ -2,34 +2,33 @@
 // 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, name: 'Settings' }, [
-    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.SetupIntentResolver,
-      activate: lazy(() => import('./intent-resolver')),
-    }),
-    defineModule({
-      id: `${SETTINGS_PLUGIN}/module/app-graph-builder`,
-      activatesOn: Events.SetupAppGraph,
-      activate: lazy(() => import('./app-graph-builder')),
-    }),
-  ]);
+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

@@ -4,26 +4,22 @@
 
 import { Schema } from 'effect';
 
-export const SETTINGS_PLUGIN = 'dxos.org/plugin/settings';
-export const SETTINGS_ACTION = `${SETTINGS_PLUGIN}/action`;
-// TODO(wittjosiah): This is a hack to prevent the previous deck from being set for pinned items.
-//  Ideally this should be worked into the data model in a generic way.
+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>()(`${SETTINGS_ACTION}/open`, {
+  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>()(
-    `${SETTINGS_ACTION}/open-plugin-registry`,
-    {
-      input: Schema.Void,
-      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

@@ -5,19 +5,21 @@
 import { Rx } from '@effect-rx/rx-react';
 import { Option, pipe } from 'effect';
 
-import { createExtension, ROOT_ID } from '@dxos/app-graph';
+import { ROOT_ID, createExtension } from '@dxos/app-graph';
 import { type SettingsStore, type SettingsValue } from '@dxos/local-storage';
 import { isNonNullable } from '@dxos/util';
 
-import { SETTINGS_ID, SETTINGS_KEY, SETTINGS_PLUGIN, SettingsAction } from './actions';
 import { Capabilities } from '../common';
-import { contributes, type PluginMeta, type PluginContext } from '../core';
+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: `${SETTINGS_PLUGIN}/action`,
+      id: `${meta.id}/action`,
       actions: (node) =>
         Rx.make((get) =>
           pipe(
@@ -25,13 +27,13 @@ export default (context: PluginContext) =>
             Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
             Option.map(() => [
               {
-                id: SETTINGS_PLUGIN,
+                id: meta.id,
                 data: async () => {
                   const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
                   await dispatch(createIntent(SettingsAction.Open));
                 },
                 properties: {
-                  label: ['open settings label', { ns: SETTINGS_PLUGIN }],
+                  label: ['open settings label', { ns: meta.id }],
                   icon: 'ph--gear--regular',
                   disposition: 'menu',
                   keyBinding: {
@@ -46,7 +48,7 @@ export default (context: PluginContext) =>
         ),
     }),
     createExtension({
-      id: `${SETTINGS_PLUGIN}/core`,
+      id: `${meta.id}/core`,
       connector: (node) =>
         Rx.make((get) =>
           pipe(
@@ -55,9 +57,9 @@ export default (context: PluginContext) =>
             Option.map(() => [
               {
                 id: SETTINGS_ID,
-                type: SETTINGS_PLUGIN,
+                type: meta.id,
                 properties: {
-                  label: ['app settings label', { ns: SETTINGS_PLUGIN }],
+                  label: ['app settings label', { ns: meta.id }],
                   icon: 'ph--gear--regular',
                   disposition: 'pin-end',
                   position: 'hoist',
@@ -70,7 +72,7 @@ export default (context: PluginContext) =>
         ),
     }),
     createExtension({
-      id: `${SETTINGS_PLUGIN}/core-plugins`,
+      id: `${meta.id}/core-plugins`,
       connector: (node) =>
         Rx.make((get) =>
           pipe(
@@ -105,7 +107,7 @@ export default (context: PluginContext) =>
                   id: `${SETTINGS_KEY}:custom-plugins`,
                   type: 'category',
                   properties: {
-                    label: ['custom plugins label', { ns: SETTINGS_PLUGIN }],
+                    label: ['custom plugins label', { ns: meta.id }],
                     icon: 'ph--squares-four--regular',
                     role: 'branch',
                     disposition: 'collection',
@@ -118,7 +120,7 @@ export default (context: PluginContext) =>
         ),
     }),
     createExtension({
-      id: `${SETTINGS_PLUGIN}/custom-plugins`,
+      id: `${meta.id}/custom-plugins`,
       connector: (node) =>
         Rx.make((get) =>
           pipe(

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

@@ -4,10 +4,11 @@
 
 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';
+import { chain, createIntent, createResolver } from '../plugin-intent';
+
+import { SETTINGS_ID, SETTINGS_KEY, SettingsAction } from './actions';
 
 export default () =>
   contributes(

package/src/plugin-settings/meta.ts

@@ -0,0 +1,10 @@
+//
+// 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

@@ -5,7 +5,7 @@
 import { RootSettingsStore } from '@dxos/local-storage';
 
 import { Capabilities } from '../common';
-import { contributes, type PluginContext } from '../core';
+import { type PluginContext, contributes } from '../core';
 
 export default (context: PluginContext) => {
   // TODO(wittjosiah): Replace with rx?

package/src/plugin-settings/translations.ts

@@ -1,15 +1,15 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2025 DXOS.org
 //
 
 import { type Resource } from '@dxos/react-ui';
 
-import { SETTINGS_PLUGIN } from './actions';
+import { meta } from './meta';
 
 export const translations = [
   {
     'en-US': {
-      [SETTINGS_PLUGIN]: {
+      [meta.id]: {
         'open settings label': 'Open settings',
         'app settings label': 'Settings',
         'custom plugins label': 'Plugins',

package/src/react/ErrorBoundary.tsx

@@ -2,38 +2,40 @@
 // Copyright 2023 DXOS.org
 //
 
-import React, { Component, type FC, type PropsWithChildren } from 'react';
+import React, { Component, type FC, type PropsWithChildren, type ReactNode } from 'react';
 
-type Props = PropsWithChildren<{ data?: any; fallback: FC<{ data?: any; error: Error; reset: () => void }> }>;
-type State = { error: Error | undefined };
+type State = {
+  error: Error | undefined;
+};
+
+export type ErrorBoundaryProps = PropsWithChildren<{
+  data?: any;
+  fallback?: FC<{ data?: any; error: Error }>;
+}>;
 
 /**
  * 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
+ * Ref: 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 };
-  }
-
+export class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
   static getDerivedStateFromError(error: Error): { error: Error } {
     return { error };
   }
 
-  override componentDidUpdate(prevProps: Props): void {
+  override state = { error: undefined };
+
+  override componentDidUpdate(prevProps: ErrorBoundaryProps): void {
     if (prevProps.data !== this.props.data) {
       this.resetError();
     }
   }
 
-  override render(): string | number | boolean | React.JSX.Element | Iterable<React.ReactNode> | null | undefined {
+  override render(): ReactNode {
     if (this.state.error) {
-      return <this.props.fallback data={this.props.data} error={this.state.error} reset={this.resetError} />;
+      const Fallback = this.props.fallback ?? DefaultFallback;
+      return <Fallback data={this.props.data} error={this.state.error} />;
     }
 
     return this.props.children;
@@ -43,3 +45,10 @@ export class ErrorBoundary extends Component<Props, State> {
     this.setState({ error: undefined });
   }
 }
+
+const DefaultFallback: NonNullable<ErrorBoundaryProps['fallback']> = ({ data, error }) => (
+  <div className='flex flex-col gap-2 overflow-hidden border border-red-500 rounded-sm'>
+    <pre className='whitespace-pre-wrap font-sm text-xs p-2'>ERROR: {error.message}</pre>
+    <pre className='whitespace-pre-wrap font-sm text-xs p-2 text-subdued'>{JSON.stringify(data, null, 2)}</pre>
+  </div>
+);

package/src/react/IntentContext.tsx

@@ -2,15 +2,16 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type Context, createContext, useContext, type Provider, useEffect } from 'react';
+import { type Context, type Provider, createContext, useContext, 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';
 
+import { usePluginManager } from './PluginManagerProvider';
+
 const IntentContext: Context<IntentContext | undefined> = createContext<IntentContext | undefined>(undefined);
 
 export const useIntentDispatcher = (): Pick<IntentContext, 'dispatch' | 'dispatchPromise'> => {

package/src/react/Surface.stories.tsx

@@ -2,20 +2,20 @@
 // Copyright 2025 DXOS.org
 //
 
-import '@dxos-theme';
-
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 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 { withTheme } from '@dxos/react-ui/testing';
 
-import { PluginManagerProvider, usePluginManager } from './PluginManagerProvider';
-import { Surface, useSurfaces } from './Surface';
 import { Capabilities, createSurface } from '../common';
 import { type PluginManager } from '../core';
 import { setupPluginManager } from '../testing';
 
+import { PluginManagerProvider, usePluginManager } from './PluginManagerProvider';
+import { Surface, useSurfaces } from './Surface';
+
 const randomColor = (): string => {
   const hue = faker.number.int({ min: 0, max: 360 });
   const saturation = faker.number.int({ min: 50, max: 90 });
@@ -23,7 +23,7 @@ const randomColor = (): string => {
   return `hsl(${hue}, ${saturation}%, ${lightness}%)`;
 };
 
-const Story = () => {
+const Component = () => {
   const manager = usePluginManager();
   const surfaces = useSurfaces();
   const [picked, setPicked] = useState('test');
@@ -77,20 +77,25 @@ const Story = () => {
   );
 };
 
-export default {
+const DefaultStory = (props: { manager: PluginManager }) => {
+  return (
+    <PluginManagerProvider value={props.manager}>
+      <Component />
+    </PluginManagerProvider>
+  );
+};
+
+const meta = {
   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()],
+  render: DefaultStory,
+  decorators: [withTheme],
   args: {
     manager: setupPluginManager(),
   },
-};
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
 
-export const Default = {};
+export const Default: Story = {};

package/src/react/Surface.tsx

@@ -2,16 +2,25 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { memo, forwardRef, Suspense, useMemo, Fragment } from 'react';
+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 { ErrorBoundary } from './ErrorBoundary';
-import { useCapabilities } from './useCapabilities';
 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 />;
 
 /**
@@ -43,8 +52,8 @@ export const isSurfaceAvailable = (context: PluginContext, { role, data }: Pick<
 /**
  * A surface is a named region of the screen that can be populated by plugins.
  */
-export const Surface = memo(
-  forwardRef<HTMLElement, SurfaceProps>(
+export const Surface: NamedExoticComponent<SurfaceProps & RefAttributes<HTMLElement>> = memo(
+  forwardRef(
     ({ id: _id, role, data: _data, limit, fallback, 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.

package/src/react/common.ts

@@ -2,9 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useCapability } from './useCapabilities';
 import { Capabilities } from '../common';
 
+import { useCapability } from './useCapabilities';
+
 export const useIntentDispatcher = () => useCapability(Capabilities.IntentDispatcher);
 
 export const useAppGraph = () => useCapability(Capabilities.AppGraph);

package/src/react/useCapabilities.ts

@@ -6,9 +6,10 @@ import { useRxValue } from '@effect-rx/rx-react';
 
 import { invariant } from '@dxos/invariant';
 
-import { usePluginManager } from './PluginManagerProvider';
 import { type InterfaceDef } from '../core';
 
+import { usePluginManager } from './PluginManagerProvider';
+
 /**
  * Hook to request capabilities from the plugin context.
  * @returns An array of capabilities.

package/src/testing/withPluginManager.stories.tsx

@@ -2,15 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
-import { withTheme, type Meta } from '@dxos/storybook-utils';
+import { withTheme } from '@dxos/react-ui/testing';
 
-import { withPluginManager } from './withPluginManager';
 import { Capabilities, createSurface } from '../common';
 import { contributes } from '../core';
 import { Surface } from '../react';
 
+import { withPluginManager } from './withPluginManager';
+
 const DefaultStory = () => {
   console.log('Render');
   return (
@@ -21,7 +23,7 @@ const DefaultStory = () => {
   );
 };
 
-const meta: Meta = {
+const meta = {
   title: 'sdk/app-framework/withPluginManager',
   render: DefaultStory,
   decorators: [
@@ -39,8 +41,10 @@ const meta: Meta = {
       ],
     }),
   ],
-};
+} satisfies Meta<typeof DefaultStory>;
 
 export default meta;
 
-export const Default = {};
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};