@dxos/app-framework 0.7.4 → 0.7.5-feature-compute.4d9d99a

package/src/common/layout.ts

@@ -0,0 +1,157 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { S } from '@dxos/echo-schema';
+
+import { Label } from '../plugin-intent';
+
+//
+// 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>;
+
+/**
+ * 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.
+ */
+
+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>;
+
+//
+// Intents
+//
+
+export const LAYOUT_PLUGIN = 'dxos.org/plugin/layout';
+export const LAYOUT_ACTION = `${LAYOUT_PLUGIN}/action`;
+
+/**
+ * Expected payload for layout actions.
+ */
+export namespace LayoutAction {
+  export class SetLayout extends S.TaggedClass<SetLayout>()(`${LAYOUT_ACTION}/set-layout`, {
+    input: S.Struct({
+      /**
+       * 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,
+  }) {}
+
+  // TODO(wittjosiah): Do all these need to be separate actions?
+
+  export class SetLayoutMode extends S.TaggedClass<SetLayoutMode>()(`${LAYOUT_ACTION}/set-layout-mode`, {
+    input: S.Union(
+      S.Struct({
+        layoutMode: LayoutMode,
+      }),
+      S.Struct({
+        revert: S.Literal(true),
+      }),
+    ),
+    output: S.Void,
+  }) {}
+
+  export class ScrollIntoView extends S.TaggedClass<ScrollIntoView>()(`${LAYOUT_ACTION}/scroll-into-view`, {
+    input: S.Struct({
+      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,
+  }) {}
+}

package/src/{plugins/common → common}/navigation.ts

@@ -3,13 +3,9 @@
 //
 
 import { Schema as S } from '@effect/schema';
-import { z } from 'zod';
 
 import { pick } from '@dxos/util';
 
-import { type Plugin } from '../plugin-host';
-import { type IntentData } from '../plugin-intent';
-
 // NOTE(thure): These are chosen from RFC 1738’s `safe` characters: http://www.faqs.org/rfcs/rfc1738.html
 export const SLUG_LIST_SEPARATOR = '+';
 export const SLUG_ENTRY_SEPARATOR = '_';
@@ -39,7 +35,14 @@ export type LayoutParts = S.Schema.Type<typeof LayoutPartsSchema>;
 const LayoutCoordinateSchema = S.mutable(S.Struct({ part: LayoutPartSchema, entryId: S.String }));
 export type LayoutCoordinate = S.Schema.Type<typeof LayoutCoordinateSchema>;
 
-const PartAdjustmentSchema = S.Union(S.Literal('increment-start'), S.Literal('increment-end'), S.Literal('solo'));
+const PartAdjustmentSchema = S.Union(
+  S.Literal('increment-start'),
+  S.Literal('increment-end'),
+  S.Literal('pin-start'),
+  S.Literal('pin-end'),
+  S.Literal('close'),
+  S.Literal('solo'),
+);
 export type PartAdjustment = S.Schema.Type<typeof PartAdjustmentSchema>;
 
 const LayoutAdjustmentSchema = S.mutable(
@@ -48,8 +51,8 @@ const LayoutAdjustmentSchema = S.mutable(
 export type LayoutAdjustment = S.Schema.Type<typeof LayoutAdjustmentSchema>;
 
 /** @deprecated */
-export const ActiveParts = z.record(z.string(), z.union([z.string(), z.array(z.string())]));
-export type ActiveParts = z.infer<typeof ActiveParts>;
+export const ActiveParts = S.Record({ key: S.String, value: S.Union(S.String, S.mutable(S.Array(S.String))) });
+export type ActiveParts = S.Schema.Type<typeof ActiveParts>;
 
 // TODO(burdon): Where should this go?
 export type LayoutContainerProps<T> = T & { role?: string; coordinate?: LayoutCoordinate };
@@ -79,19 +82,6 @@ export const isLayoutAdjustment = (value: unknown): value is LayoutAdjustment =>
   return S.is(LayoutAdjustmentSchema)(value);
 };
 
-export const parseNavigationPlugin = (plugin: Plugin): Plugin<LocationProvides> | undefined => {
-  const location = (plugin.provides as any)?.location;
-  if (!location) {
-    return undefined;
-  }
-
-  if (S.is(LocationProvidesSchema)({ location })) {
-    return plugin as Plugin<LocationProvides>;
-  }
-
-  return undefined;
-};
-
 /**
  * Utilities.
  */
@@ -135,51 +125,75 @@ export const partLength = (layout: LayoutParts | undefined, part: LayoutPart | u
 // Intents
 //
 
-const NAVIGATION_PLUGIN = 'dxos.org/plugin/navigation';
-
-const NAVIGATION_ACTION = `${NAVIGATION_PLUGIN}/action`;
-
-export enum NavigationAction {
-  OPEN = `${NAVIGATION_ACTION}/open`,
-  ADD_TO_ACTIVE = `${NAVIGATION_ACTION}/add-to-active`,
-  SET = `${NAVIGATION_ACTION}/set`,
-  ADJUST = `${NAVIGATION_ACTION}/adjust`,
-  CLOSE = `${NAVIGATION_ACTION}/close`,
-  EXPOSE = `${NAVIGATION_ACTION}/expose`,
-}
+export const NAVIGATION_PLUGIN = 'dxos.org/plugin/navigation';
+export const NAVIGATION_ACTION = `${NAVIGATION_PLUGIN}/action`;
 
 /**
  * Expected payload for navigation actions.
  */
+// TODO(wittjosiah): These seem to be too deck-specific.
 export namespace NavigationAction {
   /**
    * An additive overlay to apply to `location.active` (i.e. the result is a union of previous active and the argument)
    */
-  export type Open = IntentData<{ activeParts: ActiveParts }>;
+  export class Open extends S.TaggedClass<Open>()(`${NAVIGATION_ACTION}/open`, {
+    input: S.Struct({
+      activeParts: ActiveParts,
+      noToggle: S.optional(S.Boolean),
+    }),
+    output: S.Struct({
+      open: S.Array(S.String),
+    }),
+  }) {}
 
   /**
    * Payload for adding an item to the active items.
    */
-  export type AddToActive = IntentData<{
-    part: LayoutPart;
-    id: string;
-    scrollIntoView?: boolean;
-    pivotId?: string;
-    positioning?: 'start' | 'end';
-  }>;
+  export class AddToActive extends S.TaggedClass<AddToActive>()(`${NAVIGATION_ACTION}/add-to-active`, {
+    input: S.Struct({
+      id: S.String,
+      part: LayoutPartSchema,
+      scrollIntoView: S.optional(S.Boolean),
+      pivotId: S.optional(S.String),
+      positioning: S.optional(S.Literal('start', 'end')),
+    }),
+    output: S.Void,
+  }) {}
 
   /**
-   * A subtractive overlay to apply to `location.active` (i.e. the result is a subtraction from the previous active of the argument)
+   * The active parts to directly set, to be used when working with URLs or restoring a specific state.
    */
-  export type Close = IntentData<{ activeParts: ActiveParts; noToggle?: boolean }>;
+  export class Set extends S.TaggedClass<Set>()(`${NAVIGATION_ACTION}/set`, {
+    input: S.Struct({
+      activeParts: ActiveParts,
+    }),
+    output: S.Void,
+  }) {}
 
   /**
-   * The active parts to directly set, to be used when working with URLs or restoring a specific state.
+   * A subtractive overlay to apply to `location.active` (i.e. the result is a subtraction from the previous active of the argument)
    */
-  export type Set = IntentData<{ activeParts: ActiveParts }>;
+  export class Close extends S.TaggedClass<Close>()(`${NAVIGATION_ACTION}/close`, {
+    input: S.Struct({
+      activeParts: ActiveParts,
+      noToggle: S.optional(S.Boolean),
+    }),
+    output: S.Void,
+  }) {}
 
   /**
    * An atomic transaction to apply to `location.active`, describing which element to (attempt to) move to which location.
    */
-  export type Adjust = IntentData<LayoutAdjustment>;
+  export class Adjust extends S.TaggedClass<Adjust>()(`${NAVIGATION_ACTION}/adjust`, {
+    input: LayoutAdjustmentSchema,
+    output: S.Void,
+  }) {}
+
+  // TODO(wittjosiah): This action seems unrelated to the others.
+  export class Expose extends S.TaggedClass<Expose>()(`${NAVIGATION_ACTION}/expose`, {
+    input: S.Struct({
+      id: S.String,
+    }),
+    output: S.Void,
+  }) {}
 }

package/src/common/surface.ts

@@ -0,0 +1,81 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type JSX, type ForwardedRef, type PropsWithChildren, type ReactNode } from 'react';
+
+import { type GuardedType, type MakeOptional, type Disposition } from '@dxos/util';
+
+import { type ErrorBoundary } from '../react';
+
+/**
+ * SurfaceProps are the props that are passed to the Surface component.
+ */
+export type SurfaceProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
+  /**
+   * 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 specified, the Surface will be wrapped in a suspense boundary.
+   * The placeholder component will be rendered while the surface component is loading.
+   */
+  placeholder?: ReactNode;
+}> &
+  MakeOptional<CoreSurfaceProps<T>, 'id' | 'data'> & {
+    /**
+     * Additional props to pass to the component.
+     * These props are not used by Surface itself but may be used by components which resolve the surface.
+     */
+    [key: string]: unknown;
+  };
+
+// NOTE: If `[key: string]: unknown` is included in shared types, when re-used other fields become unknown as well.
+type CoreSurfaceProps<T extends Record<string, any> = Record<string, unknown>> = {
+  /**
+   * ID for debugging.
+   */
+  id: string;
+
+  /**
+   * Role defines how the data should be rendered.
+   */
+  role: string;
+
+  /**
+   * The data to be rendered by the surface.
+   */
+  data: T;
+
+  /**
+   * If more than one component is resolved, the limit determines how many are rendered.
+   */
+  limit?: number | undefined;
+};
+
+type SurfaceComponentProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<
+  CoreSurfaceProps<T> & { [key: string]: unknown }
+>;
+
+/**
+ * React component used to render a surface once is has matched.
+ */
+export type SurfaceComponent<T extends Record<string, any> = Record<string, unknown>> = (
+  props: SurfaceComponentProps<T>,
+  forwardedRef: ForwardedRef<HTMLElement>,
+) => JSX.Element | null;
+
+/**
+ * Definition of when a SurfaceComponent should be rendered.
+ */
+export type SurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+  id: string;
+  role: string | string[];
+  disposition?: Disposition;
+  filter?: (data: Record<string, unknown>) => data is T;
+  component: SurfaceComponent<GuardedType<SurfaceDefinition<T>['filter']>>;
+}>;
+
+export const createSurface = <T extends Record<string, any> = any>(definition: SurfaceDefinition<T>) => definition;

package/src/common/translations.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { z } from 'zod';
+
+// TODO(burdon): Replace zod with effect.
+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>;

package/src/core/capabilities.test.ts

@@ -0,0 +1,116 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from 'vitest';
+
+import { updateCounter } from '@dxos/echo-schema/testing';
+import { registerSignalsRuntime } from '@dxos/echo-signals';
+
+import { defineCapability, PluginsContext } from './capabilities';
+
+registerSignalsRuntime();
+
+const defaultOptions = {
+  activate: () => Promise.resolve(false),
+  reset: () => Promise.resolve(false),
+};
+
+describe('PluginsContext', () => {
+  it('should return empty array if no capabilities are contributed', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    expect(context.requestCapabilities(interfaceDef)).toEqual([]);
+  });
+
+  it('should be able to contribute and request capabilities', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation = { example: 'identifier' };
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    expect(context.requestCapabilities(interfaceDef)).toEqual([implementation]);
+  });
+
+  it('should be able to remove capabilities', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation = { example: 'identifier' };
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    expect(context.requestCapabilities(interfaceDef)).toEqual([implementation]);
+    context.removeCapability(interfaceDef, implementation);
+    expect(context.requestCapabilities(interfaceDef)).toEqual([]);
+  });
+
+  it('should be able to contribute and request multiple implementations', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation1 = { example: 'first' };
+    const implementation2 = { example: 'second' };
+    context.contributeCapability({ interface: interfaceDef, implementation: implementation1, module: 'test' });
+    context.contributeCapability({ interface: interfaceDef, implementation: implementation2, module: 'test' });
+    expect(context.requestCapabilities(interfaceDef)).toEqual([implementation1, implementation2]);
+  });
+
+  it('should be able to request multiple capabilities', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef1 = defineCapability<{ one: number }>('@dxos/app-framework/test/one');
+    const interfaceDef2 = defineCapability<{ two: number }>('@dxos/app-framework/test/two');
+    const implementation1 = { one: 1 };
+    const implementation2 = { two: 2 };
+    context.contributeCapability({ interface: interfaceDef1, implementation: implementation1, module: 'test' });
+    context.contributeCapability({ interface: interfaceDef2, implementation: implementation2, module: 'test' });
+    expect(context.requestCapabilities(interfaceDef1)).toEqual([implementation1]);
+    expect(context.requestCapabilities(interfaceDef2)).toEqual([implementation2]);
+  });
+
+  it('should be reactive', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+
+    using updates = updateCounter(() => {
+      context.requestCapabilities(interfaceDef);
+    });
+
+    expect(updates.count).toEqual(0);
+
+    const implementation = { example: 'identifier' };
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    expect(updates.count).toEqual(1);
+
+    context.removeCapability(interfaceDef, implementation);
+    expect(updates.count).toEqual(2);
+  });
+
+  it('should not be reactive to changes within the implementation', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+
+    using updates = updateCounter(() => {
+      context.requestCapabilities(interfaceDef);
+    });
+
+    expect(updates.count).toEqual(0);
+
+    const implementation = { example: 'identifier' };
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    expect(updates.count).toEqual(1);
+
+    implementation.example = 'updated';
+    expect(updates.count).toEqual(1);
+
+    const capabilities = context.requestCapabilities(interfaceDef);
+    expect(capabilities).toEqual([implementation]);
+    expect(capabilities[0].example).toEqual('updated');
+    expect(updates.count).toEqual(1);
+  });
+
+  it('should be able to wait for a capability', async () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation = { example: 'identifier' };
+    const promise = context.waitForCapability(interfaceDef);
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    const capability = await promise;
+    expect(capability).toEqual(implementation);
+  });
+});