@dxos/app-framework 0.7.5-labs.e27f9b9 → 0.7.5-main.2567c87

package/project.json

@@ -12,8 +12,7 @@
       "options": {
         "entryPoints": [
           "{projectRoot}/src/index.ts",
-          "{projectRoot}/src/testing/index.ts",
-          "{projectRoot}/src/worker.ts"
+          "{projectRoot}/src/testing/index.ts"
         ]
       }
     },
@@ -21,6 +20,7 @@
     "test": {}
   },
   "implicitDependencies": [
-    "esbuild"
+    "esbuild",
+    "node-std"
   ]
 }

package/src/App.tsx

@@ -11,7 +11,7 @@ import { create } from '@dxos/live-object';
 import { Capabilities, Events } from './common';
 import { PluginManager, type PluginManagerOptions, type Plugin } from './core';
 import { topologicalSort } from './helpers';
-import { ErrorBoundary, PluginManagerProvider, useCapabilities } from './react';
+import { ErrorBoundary, PluginManagerProvider } from './react';
 
 const ENABLED_KEY = 'dxos.org/app-framework/enabled';
 
@@ -96,27 +96,21 @@ export const createApp = ({
 
   setupDevtools(manager);
 
-  // TODO(wittjosiah): Factor out such that this could be called per surface role when attempting to render.
-  void manager.activate(Events.SetupSurfaces);
   void manager.activate(Events.Startup);
 
   return () => (
     <ErrorBoundary fallback={fallback}>
-      <PluginManagerProvider value={manager}>
-        <App placeholder={placeholder} state={state} />
-      </PluginManagerProvider>
+      <App placeholder={placeholder} manager={manager} state={state} />
     </ErrorBoundary>
   );
 };
 
 type AppProps = Required<Pick<CreateAppOptions, 'placeholder'>> & {
+  manager: PluginManager;
   state: { ready: boolean; error: unknown };
 };
 
-const App = ({ placeholder, state }: AppProps) => {
-  const reactContexts = useCapabilities(Capabilities.ReactContext);
-  const reactRoots = useCapabilities(Capabilities.ReactRoot);
-
+const App = ({ placeholder, manager, state }: AppProps) => {
   if (state.error) {
     // This trigger the error boundary to provide UI feedback for the startup error.
     throw state.error;
@@ -127,13 +121,18 @@ const App = ({ placeholder, state }: AppProps) => {
     return <>{placeholder}</>;
   }
 
+  const reactContexts = manager.context.requestCapabilities(Capabilities.ReactContext);
+  const reactRoots = manager.context.requestCapabilities(Capabilities.ReactRoot);
+
   const ComposedContext = composeContexts(reactContexts);
   return (
-    <ComposedContext>
-      {reactRoots.map(({ id, root: Component }) => (
-        <Component key={id} />
-      ))}
-    </ComposedContext>
+    <PluginManagerProvider value={manager}>
+      <ComposedContext>
+        {reactRoots.map(({ id, root: Component }) => (
+          <Component key={id} />
+        ))}
+      </ComposedContext>
+    </PluginManagerProvider>
   );
 };
 

package/src/common/capabilities.ts

@@ -2,16 +2,18 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Schema as S } from '@effect/schema';
 import { type FC, type PropsWithChildren } from 'react';
 
 import { type GraphBuilder } from '@dxos/app-graph';
-import { type ArtifactDefinition, type Tool } from '@dxos/artifact';
 import { type Space } from '@dxos/client-protocol';
+import { type S } from '@dxos/echo-schema';
 import { type RootSettingsStore } from '@dxos/local-storage';
+import { type DeepReadonly } from '@dxos/util';
 
 import { type FileInfo } from './file';
 import { type NodeSerializer } from './graph';
+import { type Layout } from './layout';
+import { type LayoutParts } from './navigation';
 import { type SurfaceDefinition } from './surface';
 import { type Resource } from './translations';
 import { defineCapability, type PluginManager } from '../core';
@@ -38,25 +40,13 @@ export namespace Capabilities {
     'dxos.org/app-framework/capability/intent-dispatcher',
   );
 
-  export type Layout = Readonly<{
-    mode: string;
-    dialogOpen: boolean;
-    sidebarOpen: boolean;
-    complementarySidebarOpen: boolean;
-    /**
-     * Identifiers of items which are currently active in the application.
-     */
-    active: string[];
-    /**
-     * Identifiers of items which were previously active in the application.
-     */
-    inactive: string[];
-    /**
-     * Identifier of the item which should be scrolled into view.
-     */
-    scrollIntoView: string | undefined;
-  }>;
-  export const Layout = defineCapability<Layout>('dxos.org/app-framework/capability/layout');
+  export const Layout = defineCapability<Readonly<Layout>>('dxos.org/app-framework/capability/layout');
+  export const MutableLayout = defineCapability<Layout>('dxos.org/app-framework/capability/layout');
+
+  export type MutableLocation = { active: LayoutParts; closed: string[] };
+  export type Location = DeepReadonly<MutableLocation>;
+  export const Location = defineCapability<Location>('dxos.org/app-framework/capability/location');
+  export const MutableLocation = defineCapability<MutableLocation>('dxos.org/app-framework/capability/location');
 
   export const Translations = defineCapability<Readonly<Resource[]>>('dxos.org/app-framework/capability/translations');
 
@@ -87,11 +77,6 @@ export namespace Capabilities {
   export type Metadata = Readonly<{ id: string; metadata: Record<string, any> }>;
   export const Metadata = defineCapability<Metadata>('dxos.org/app-framework/capability/metadata');
 
-  export const Tools = defineCapability<Tool[]>('dxos.org/app-framework/capability/tools');
-  export const ArtifactDefinition = defineCapability<ArtifactDefinition>(
-    'dxos.org/app-framework/capability/artifact-definition',
-  );
-
   export type FileUploader = (file: File, space: Space) => Promise<FileInfo | undefined>;
   export const FileUploader = defineCapability<FileUploader>('dxos.org/app-framework/capability/file-uploader');
 }

package/src/common/events.ts

@@ -15,16 +15,6 @@ export namespace Events {
   // Dependent Events
   //
 
-  /**
-   * Fired to load any newly available surfaces.
-   */
-  export const SetupSurfaces = defineEvent('dxos.org/app-framework/event/setup-surfaces');
-
-  /**
-   * Fired to load any newly available metadata.
-   */
-  export const SetupMetadata = defineEvent('dxos.org/app-framework/event/setup-metadata');
-
   /**
    * Fired before the intent dispatcher is activated.
    */
@@ -69,4 +59,5 @@ export namespace Events {
    */
   export const createStateEvent = (specifier: string) => defineEvent('dxos.org/app-framework/event/state', specifier);
   export const LayoutReady = createStateEvent(Capabilities.Layout.identifier);
+  export const LocationReady = createStateEvent(Capabilities.Location.identifier);
 }

package/src/common/file.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema as S } from '@effect/schema';
+import { S } from '@dxos/echo-schema';
 
 // TODO(burdon): See Accept attribute (uses MIME types).
 // E.g., 'image/*': ['.jpg', '.jpeg', '.png', '.gif'],

package/src/common/graph.ts

@@ -3,7 +3,7 @@
 //
 
 import type { Node } from '@dxos/app-graph';
-import { type MaybePromise, type Position } from '@dxos/util';
+import { type MaybePromise } from '@dxos/util';
 
 // TODO(wittjosiah): Factor out.
 export type SerializedNode = {
@@ -16,7 +16,7 @@ export type SerializedNode = {
 export type NodeSerializer<T = any> = {
   inputType: string;
   outputType: string;
-  position?: Position;
+  disposition?: 'hoist' | 'fallback';
 
   /**
    * Takes a node and serializes it into a format that can be stored.

package/src/common/index.ts

@@ -7,5 +7,6 @@ export * from './events';
 export * from './file';
 export * from './graph';
 export * from './layout';
+export * from './navigation';
 export * from './surface';
 export * from './translations';

package/src/common/layout.ts

@@ -2,223 +2,155 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Schema as S } from '@effect/schema';
+import { S } from '@dxos/echo-schema';
 
 import { Label } from '../plugin-intent';
 
-export const LAYOUT_PLUGIN = 'dxos.org/plugin/layout';
-export const LAYOUT_ACTION = `${LAYOUT_PLUGIN}/action`;
+//
+// Provides
+//
+
+export const Toast = S.Struct({
+  id: S.String,
+  title: S.optional(Label),
+  description: S.optional(Label),
+  icon: S.optional(S.String),
+  duration: S.optional(S.Number),
+  closeLabel: S.optional(Label),
+  actionLabel: S.optional(Label),
+  actionAlt: S.optional(Label),
+  // TODO(wittjosiah): Make class with customizable method?
+  onAction: S.optional(S.Any),
+});
+
+export type Toast = S.Schema.Type<typeof Toast>;
 
 /**
- * Expected payload for layout actions.
+ * Basic state provided by a layout plugin.
+ *
+ * Layout provides the state of global UI landmarks, such as the sidebar, dialog, and popover.
+ * Generally only one dialog or popover should be open at a time, a layout plugin should manage this.
+ * For other landmarks, such as toasts, rendering them in the layout prevents them from unmounting when navigating.
  */
-export namespace LayoutAction {
-  export const UPDATE_LAYOUT = `${LAYOUT_ACTION}/update-layout`;
-
-  /**
-   * Generic layout action.
-   */
-  export class UpdateLayout extends S.TaggedClass<UpdateLayout>()(UPDATE_LAYOUT, {
-    input: S.Struct({
-      part: S.String.annotations({ description: 'The part of the layout to mutate.' }),
-      subject: S.optional(S.Any.annotations({ description: 'The subject of the layout update.' })),
-      options: S.optional(
-        S.Record({ key: S.String, value: S.Any }).annotations({
-          description: 'Additional options for the layout action.',
-        }),
-      ),
-    }),
-    output: S.Void,
-  }) {}
 
-  //
-  // Common layout actions.
-  //
+const LayoutMode = S.Union(S.Literal('deck'), S.Literal('solo'), S.Literal('fullscreen'));
+export const isLayoutMode = (value: any): value is LayoutMode => S.is(LayoutMode)(value);
+export type LayoutMode = S.Schema.Type<typeof LayoutMode>;
+
+export const Layout = S.mutable(
+  S.Struct({
+    layoutMode: LayoutMode,
+
+    sidebarOpen: S.Boolean,
+    complementarySidebarOpen: S.Boolean,
+    /**
+     * @deprecated Data to be passed to the complementary sidebar Surface.
+     */
+    complementarySidebarContent: S.optional(S.Any),
+
+    dialogOpen: S.Boolean,
+    /**
+     * Data to be passed to the dialog Surface.
+     */
+    dialogContent: S.optional(S.Any),
+    // TODO(wittjosiah): Custom properties?
+    dialogBlockAlign: S.optional(S.Literal('start', 'center')),
+    dialogType: S.optional(S.Literal('default', 'alert')),
+
+    popoverOpen: S.Boolean,
+    /**
+     * Data to be passed to the popover Surface.
+     */
+    popoverContent: S.optional(S.Any),
+    popoverAnchorId: S.optional(S.String),
+
+    toasts: S.mutable(S.Array(Toast)),
+
+    /**
+     * The identifier of a component to scroll into view when it is mounted.
+     */
+    scrollIntoView: S.optional(S.String),
+  }),
+);
+
+export type Layout = S.Schema.Type<typeof Layout>;
 
-  // NOTE: These are layout actions which are currently in common use.
-  //  They constrain the generic layout action types to provide additional type safety.
-  //  However, they all follow the same generic structure and intent id.
-  //  This allows for plugins to update the layout without depending on a specific layout plugin.
-  //  The expectation is that other norms other than these will emerge over time.
+//
+// Intents
+//
 
-  export class SetLayoutMode extends S.TaggedClass<SetLayoutMode>()(UPDATE_LAYOUT, {
-    input: S.Struct({
-      part: S.Literal('mode').annotations({ description: 'Setting the layout mode.' }),
-      subject: S.optional(S.String.annotations({ description: 'Item which is the subject of the new layout mode.' })),
-      options: S.Union(
-        S.Struct({ mode: S.String.annotations({ description: 'The new layout mode.' }) }),
-        S.Struct({ revert: S.Boolean.annotations({ description: 'Revert to the previous layout mode.' }) }),
-      ),
-    }),
-    output: S.Void,
-  }) {}
+export const LAYOUT_PLUGIN = 'dxos.org/plugin/layout';
+export const LAYOUT_ACTION = `${LAYOUT_PLUGIN}/action`;
 
-  export class UpdateSidebar extends S.TaggedClass<UpdateSidebar>()(UPDATE_LAYOUT, {
+/**
+ * Expected payload for layout actions.
+ */
+export namespace LayoutAction {
+  export class SetLayout extends S.TaggedClass<SetLayout>()(`${LAYOUT_ACTION}/set-layout`, {
     input: S.Struct({
-      part: S.Literal('sidebar').annotations({ description: 'Updating the sidebar.' }),
-      subject: S.optional(S.String.annotations({ description: 'URI of the component to display in the sidebar.' })),
-      options: S.optional(
-        S.Struct({
-          state: S.Literal('closed', 'collapsed', 'expanded').annotations({
-            description: 'Whether the sidebar is closed, collapsed, or expanded.',
-          }),
-        }),
-      ),
+      /**
+       * Element to set the state of.
+       */
+      element: S.Literal('fullscreen', 'sidebar', 'complementary', 'dialog', 'popover', 'toast'),
+
+      /**
+       * Whether the element is on or off.
+       *
+       * If omitted, the element's state will be toggled or set based on other provided data.
+       * For example, if `component` is provided, the state will be set to `true`.
+       */
+      state: S.optional(S.Boolean),
+
+      /**
+       * Component to render in the dialog or popover.
+       */
+      component: S.optional(S.String),
+
+      /**
+       * Data to be passed to the dialog or popover Surface.
+       */
+      subject: S.optional(S.Any),
+
+      /**
+       * Anchor ID for the popover.
+       */
+      anchorId: S.optional(S.String),
+
+      // TODO(wittjosiah): Custom properties?
+
+      /**
+       * Block alignment for the dialog.
+       */
+      dialogBlockAlign: S.optional(S.Literal('start', 'center')),
+
+      /**
+       * Type of dialog.
+       */
+      dialogType: S.optional(S.Literal('default', 'alert')),
     }),
     output: S.Void,
   }) {}
 
-  export class UpdateComplementary extends S.TaggedClass<UpdateComplementary>()(UPDATE_LAYOUT, {
-    input: S.Struct({
-      part: S.Literal('complementary').annotations({ description: 'Updating the complementary sidebar.' }),
-      subject: S.optional(
-        S.String.annotations({ description: 'URI of the component to display in the complementary area.' }),
-      ),
-      options: S.optional(
-        S.Struct({
-          state: S.Literal('closed', 'collapsed', 'expanded').annotations({
-            description: 'Whether the complementary sidebar is closed, collapsed, or expanded.',
-          }),
-        }),
-      ),
-    }),
-    output: S.Void,
-  }) {}
+  // TODO(wittjosiah): Do all these need to be separate actions?
 
-  export class UpdateDialog extends S.TaggedClass<UpdateDialog>()(UPDATE_LAYOUT, {
-    input: S.Struct({
-      part: S.Literal('dialog').annotations({ description: 'Updating the dialog.' }),
-      subject: S.optional(S.String.annotations({ description: 'URI of the component to display in the dialog.' })),
-      options: S.Struct({
-        state: S.optional(S.Boolean.annotations({ description: 'Whether the dialog is open or closed.' })),
-        blockAlign: S.optional(
-          S.Literal('start', 'center').annotations({ description: 'The alignment of the dialog.' }),
-        ),
-        type: S.optional(S.Literal('default', 'alert').annotations({ description: 'The type of dialog.' })),
-        props: S.optional(
-          S.Record({ key: S.String, value: S.Any }).annotations({
-            description: 'Additional props for the dialog.',
-          }),
-        ),
+  export class SetLayoutMode extends S.TaggedClass<SetLayoutMode>()(`${LAYOUT_ACTION}/set-layout-mode`, {
+    input: S.Union(
+      S.Struct({
+        layoutMode: LayoutMode,
       }),
-    }),
-    output: S.Void,
-  }) {}
-
-  export class UpdatePopover extends S.TaggedClass<UpdatePopover>()(UPDATE_LAYOUT, {
-    input: S.Struct({
-      part: S.Literal('popover').annotations({ description: 'Updating the popover.' }),
-      subject: S.optional(S.String.annotations({ description: 'URI of the component to display in the popover.' })),
-      options: S.Struct({
-        anchorId: S.String.annotations({ description: 'The id of the element to anchor the popover to.' }),
-        state: S.optional(S.Boolean.annotations({ description: 'Whether the popover is open or closed.' })),
-        props: S.optional(
-          S.Record({ key: S.String, value: S.Any }).annotations({
-            description: 'Additional props for the popover.',
-          }),
-        ),
+      S.Struct({
+        revert: S.Literal(true),
       }),
-    }),
-    output: S.Void,
-  }) {}
-
-  export const Toast = S.Struct({
-    id: S.String.annotations({ description: 'The id of the toast.' }),
-    title: S.optional(Label.annotations({ description: 'The title of the toast.' })),
-    description: S.optional(Label.annotations({ description: 'The description of the toast.' })),
-    icon: S.optional(S.String.annotations({ description: 'The icon of the toast.' })),
-    duration: S.optional(S.Number.annotations({ description: 'The duration of the toast.' })),
-    closeLabel: S.optional(Label.annotations({ description: 'The label of the close button.' })),
-    actionLabel: S.optional(Label.annotations({ description: 'The label of the action button.' })),
-    actionAlt: S.optional(Label.annotations({ description: 'The alt text of the action button.' })),
-    onAction: S.optional(
-      S.Any.annotations({ description: 'The action to perform when the action button is clicked.' }),
     ),
-  });
-
-  export interface Toast extends Omit<S.Schema.Type<typeof Toast>, 'onAction'> {
-    onAction?: () => void;
-  }
-
-  export class AddToast extends S.TaggedClass<AddToast>()(UPDATE_LAYOUT, {
-    input: S.Struct({
-      part: S.Literal('toast').annotations({ description: 'Adding a toast.' }),
-      subject: Toast.annotations({ description: 'The toast to add.' }),
-    }),
-    output: S.Void,
-  }) {}
-
-  export class SwitchWorkspace extends S.TaggedClass<SwitchWorkspace>()(UPDATE_LAYOUT, {
-    input: S.Struct({
-      part: S.Literal('workspace').annotations({ description: 'Switching the workspace.' }),
-      subject: S.String.annotations({ description: 'The id of the workspace to switch to.' }),
-    }),
-    output: S.Void,
-  }) {}
-
-  export class Open extends S.TaggedClass<Open>()(UPDATE_LAYOUT, {
-    input: S.Struct({
-      part: S.Literal('main').annotations({ description: 'Opening an item in the main content area.' }),
-      subject: S.Array(S.String.annotations({ description: 'Ids of the items to open.' })),
-      options: S.optional(
-        S.Struct({
-          state: S.optional(S.Literal(true).annotations({ description: 'The items are being added.' })),
-          key: S.optional(
-            S.String.annotations({ description: 'If provided, will replace item with a matching key (id prefix).' }),
-          ),
-          scrollIntoView: S.optional(S.Boolean.annotations({ description: 'Scroll the items into view.' })),
-          pivotId: S.optional(S.String.annotations({ description: 'The id of the item to place new items next to.' })),
-          positioning: S.optional(
-            S.Union(
-              S.Literal('start').annotations({ description: 'The items are being added before the pivot item.' }),
-              S.Literal('end').annotations({ description: 'The items are being added after the pivot item.' }),
-            ),
-          ),
-        }),
-      ),
-    }),
-    output: S.Void,
-  }) {}
-
-  export class Set extends S.TaggedClass<Set>()(UPDATE_LAYOUT, {
-    input: S.Struct({
-      part: S.Literal('main').annotations({ description: 'Setting items in the main content area.' }),
-      subject: S.Array(S.String.annotations({ description: 'Ids of the items to set.' })),
-      options: S.Struct({
-        override: S.Literal(true).annotations({ description: 'Override the current items in the main content area.' }),
-      }),
-    }),
-    output: S.Void,
-  }) {}
-
-  export class Close extends S.TaggedClass<Close>()(UPDATE_LAYOUT, {
-    input: S.Struct({
-      part: S.Literal('main').annotations({ description: 'Closing items in the main content area.' }),
-      subject: S.Array(S.String.annotations({ description: 'Ids of the items to close.' })),
-      options: S.Struct({
-        state: S.Literal(false).annotations({ description: 'The items are being removed.' }),
-      }),
-    }),
-    output: S.Void,
-  }) {}
-
-  export class ScrollIntoView extends S.TaggedClass<ScrollIntoView>()(UPDATE_LAYOUT, {
-    input: S.Struct({
-      part: S.Literal('current').annotations({ description: 'Setting the current item' }),
-      subject: S.optional(S.String.annotations({ description: 'The id of the item to set as current.' })),
-      options: S.optional(
-        S.Record({ key: S.String, value: S.Any }).annotations({
-          description: 'Additional options for the scroll into view.',
-        }),
-      ),
-    }),
     output: S.Void,
   }) {}
 
-  export class Expose extends S.TaggedClass<Expose>()(UPDATE_LAYOUT, {
+  export class ScrollIntoView extends S.TaggedClass<ScrollIntoView>()(`${LAYOUT_ACTION}/scroll-into-view`, {
     input: S.Struct({
-      part: S.Literal('navigation').annotations({ description: 'Exposing an item in the navigation area.' }),
-      subject: S.String.annotations({ description: 'The id of the item to expose.' }),
+      id: S.optional(S.String),
+      // TODO(wittjosiah): Factor out to thread scroll into view action?
+      cursor: S.optional(S.String),
+      ref: S.optional(S.String),
     }),
     output: S.Void,
   }) {}