@dxos/app-framework 0.3.8-next.f4e0086 → 0.3.9-main.27aafd0

package/dist/types/src/plugins/SurfacePlugin/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/plugins/SurfacePlugin/index.ts"],"names":[],"mappings":"AAIA,cAAc,YAAY,CAAC;AAE3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/plugins/SurfacePlugin/index.ts"],"names":[],"mappings":"AAIA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAE3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC"}

package/dist/types/src/plugins/common/graph.d.ts

@@ -4,7 +4,7 @@ import type { Plugin } from '../PluginHost';
 /**
  * Provides for a plugin that exposes the application graph.
  */
-export type GraphPluginProvides = {
+export type GraphProvides = {
     graph: Graph;
 };
 export type GraphBuilderProvides = {
@@ -18,7 +18,7 @@ export type GraphBuilderProvides = {
 /**
  * Type guard for graph plugins.
  */
-export declare const parseGraphPlugin: (plugin: Plugin) => Plugin<GraphPluginProvides> | undefined;
+export declare const parseGraphPlugin: (plugin: Plugin) => Plugin<GraphProvides> | undefined;
 /**
  * Type guard for graph builder plugins.
  */

package/dist/types/src/plugins/common/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../../../src/plugins/common/graph.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE;QACL,OAAO,EAAE,CAAC,MAAM,EAAE;YAAE,MAAM,EAAE,IAAI,CAAC;YAAC,OAAO,EAAE,MAAM,EAAE,CAAA;SAAE,KAAK,mBAAmB,GAAG,IAAI,CAAC;KACtF,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,WAAY,MAAM,4CAC6C,CAAC;AAE7F;;GAEG;AACH,eAAO,MAAM,uBAAuB,WAAY,MAAM,6CAC0C,CAAC"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../../../src/plugins/common/graph.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE;QACL,OAAO,EAAE,CAAC,MAAM,EAAE;YAAE,MAAM,EAAE,IAAI,CAAC;YAAC,OAAO,EAAE,MAAM,EAAE,CAAA;SAAE,KAAK,mBAAmB,GAAG,IAAI,CAAC;KACtF,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,WAAY,MAAM,sCACuC,CAAC;AAEvF;;GAEG;AACH,eAAO,MAAM,uBAAuB,WAAY,MAAM,6CAC0C,CAAC"}

package/dist/types/src/plugins/common/layout.d.ts

@@ -15,27 +15,27 @@ export declare const Layout: z.ZodObject<{
     active: z.ZodOptional<z.ZodString>;
     previous: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    dialogContent?: any;
-    popoverAnchorId?: string | undefined;
-    popoverContent?: any;
-    active?: string | undefined;
-    previous?: string | undefined;
     fullscreen: boolean;
     sidebarOpen: boolean;
     complementarySidebarOpen: boolean;
     dialogOpen: boolean;
     popoverOpen: boolean;
-}, {
     dialogContent?: any;
     popoverAnchorId?: string | undefined;
     popoverContent?: any;
     active?: string | undefined;
     previous?: string | undefined;
+}, {
     fullscreen: boolean;
     sidebarOpen: boolean;
     complementarySidebarOpen: boolean;
     dialogOpen: boolean;
     popoverOpen: boolean;
+    dialogContent?: any;
+    popoverAnchorId?: string | undefined;
+    popoverContent?: any;
+    active?: string | undefined;
+    previous?: string | undefined;
 }>;
 export type Layout = z.infer<typeof Layout>;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/app-framework",
-  "version": "0.3.8-next.f4e0086",
+  "version": "0.3.9-main.27aafd0",
   "description": "A framework for building applications from composible plugins.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -15,13 +15,13 @@
     "@phosphor-icons/react": "^2.0.5",
     "@preact/signals-react": "^1.3.6",
     "deepsignal": "1.4.0-shallow.0",
-    "zod": "^3.19.1",
-    "@dxos/app-graph": "0.3.8-next.f4e0086",
-    "@dxos/async": "0.3.8-next.f4e0086",
-    "@dxos/debug": "0.3.8-next.f4e0086",
-    "@dxos/invariant": "0.3.8-next.f4e0086",
-    "@dxos/local-storage": "0.3.8-next.f4e0086",
-    "@dxos/log": "0.3.8-next.f4e0086"
+    "zod": "^3.22.4",
+    "@dxos/app-graph": "0.3.9-main.27aafd0",
+    "@dxos/invariant": "0.3.9-main.27aafd0",
+    "@dxos/async": "0.3.9-main.27aafd0",
+    "@dxos/debug": "0.3.9-main.27aafd0",
+    "@dxos/local-storage": "0.3.9-main.27aafd0",
+    "@dxos/log": "0.3.9-main.27aafd0"
   },
   "devDependencies": {
     "@types/react": "^18.0.21",

package/project.json

@@ -2,42 +2,15 @@
   "sourceRoot": "packages/sdk/app-framework/src",
   "projectType": "application",
   "targets": {
-    "build": {
-      "executor": "@nx/js:tsc",
-      "options": {
-        "main": "packages/sdk/app-framework/src/index.ts",
-        "outputPath": "packages/sdk/app-framework/dist/types",
-        "tsConfig": "packages/sdk/app-framework/tsconfig.json"
-      },
-      "outputs": [
-        "{options.outputPath}"
-      ]
-    },
+    "build": {},
     "compile": {
-      "executor": "@dxos/esbuild:build",
       "options": {
         "entryPoints": [
           "packages/sdk/app-framework/src/index.ts"
-        ],
-        "outputPath": "packages/sdk/app-framework/dist/lib"
-      },
-      "outputs": [
-        "{options.outputPath}"
-      ]
-    },
-    "lint": {
-      "executor": "@nx/linter:eslint",
-      "options": {
-        "format": "unix",
-        "lintFilePatterns": [
-          "packages/sdk/app-framework/**/*.{ts,tsx,js,jsx}"
-        ],
-        "quiet": true
-      },
-      "outputs": [
-        "{options.outputFile}"
-      ]
+        ]
+      }
     },
+    "lint": {},
     "storybook": {
       "configurations": {
         "ci": {
@@ -50,26 +23,11 @@
       }
     },
     "test": {
-      "executor": "@dxos/test:run",
       "options": {
         "ciEnvironments": [
           "nodejs"
-        ],
-        "coveragePath": "coverage/packages/sdk/app-framework",
-        "outputPath": "tmp/mocha/packages/sdk/app-framework",
-        "resultsPath": "test-results/packages/sdk/app-framework",
-        "testPatterns": [
-          "packages/sdk/app-framework/src/**/*.test.{ts,js}"
-        ],
-        "watchPatterns": [
-          "packages/sdk/app-framework/src/**/*"
         ]
-      },
-      "outputs": [
-        "{options.coveragePath}",
-        "{options.outputPath}",
-        "{options.resultsPath}"
-      ]
+      }
     }
   },
   "implicitDependencies": [

package/src/plugins/SurfacePlugin/Surface.tsx

@@ -2,11 +2,19 @@
 // Copyright 2022 DXOS.org
 //
 
-import React, { forwardRef, type FC, type ReactNode, Fragment, type ForwardedRef, type PropsWithChildren } from 'react';
+import React, {
+  forwardRef,
+  type FC,
+  type ReactNode,
+  Fragment,
+  type ForwardedRef,
+  type PropsWithChildren,
+  isValidElement,
+} from 'react';
 import { createContext, useContext } from 'react';
 
 import { ErrorBoundary } from './ErrorBoundary';
-import { type SurfaceComponent, useSurface } from './SurfaceRootContext';
+import { type SurfaceComponent, useSurface, type SurfaceResult } from './SurfaceRootContext';
 
 /**
  * Direction determines how multiple components are laid out.
@@ -43,6 +51,8 @@ export type SurfaceProps = PropsWithChildren<{
 
   /**
    * If specified, this will render if no plugin can offer renderable content for the surface.
+   *
+   * @deprecated Provide a component with `disposition: 'fallback'` instead.
    */
   contentFallback?: FC<{}>;
 
@@ -120,11 +130,30 @@ const resolveNodes = (
   };
 
   const nodes = Object.entries(components)
-    .map(([key, component]) => {
+    .map(([key, component]): [string, SurfaceResult] | undefined => {
       const result = component({ ...props, data }, forwardedRef);
-      return result ? <Fragment key={key}>{result}</Fragment> : undefined;
+      if (!result || typeof result !== 'object') {
+        return undefined;
+      }
+
+      return 'node' in result ? [key, result] : isValidElement(result) ? [key, { node: result }] : undefined;
+    })
+    .filter((result): result is [string, SurfaceResult] => Boolean(result))
+    .sort(([, a], [, b]) => {
+      const aDisposition = a.disposition ?? 'default';
+      const bDisposition = b.disposition ?? 'default';
+
+      if (aDisposition === bDisposition) {
+        return 0;
+      } else if (aDisposition === 'hoist' || bDisposition === 'fallback') {
+        return -1;
+      } else if (bDisposition === 'hoist' || aDisposition === 'fallback') {
+        return 1;
+      }
+
+      return 0;
     })
-    .filter((Component): Component is JSX.Element => Boolean(Component));
+    .map(([key, result]) => <Fragment key={key}>{result.node}</Fragment>);
 
   return props.limit ? nodes.slice(0, props.limit) : nodes;
 };

package/src/plugins/SurfacePlugin/SurfaceRootContext.tsx

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { createContext, useContext, type Context, type Provider, type ReactNode, type ForwardedRef } from 'react';
+import { createContext, useContext, type Context, type Provider, type ForwardedRef } from 'react';
 
 import { type SurfaceProps } from './Surface';
 
@@ -13,12 +13,25 @@ type WithRequiredProperty<Type, Key extends keyof Type> = Type & {
 
 type SurfaceComponentProps = WithRequiredProperty<SurfaceProps, 'data'>;
 
+/**
+ * Determines the priority of the surface when multiple components are resolved.
+ */
+export type SurfaceDisposition = 'hoist' | 'fallback';
+
+export type SurfaceResult = {
+  node: JSX.Element;
+  disposition?: SurfaceDisposition;
+};
+
 /**
  * Function which resolves a Surface.
  *
  * If a null value is returned, the rendering is deferred to other plugins.
  */
-export type SurfaceComponent = (props: SurfaceComponentProps, forwardedRef: ForwardedRef<HTMLElement>) => ReactNode;
+export type SurfaceComponent = (
+  props: SurfaceComponentProps,
+  forwardedRef: ForwardedRef<HTMLElement>,
+) => JSX.Element | SurfaceResult | null;
 
 export type SurfaceRootContext = {
   components: Record<string, SurfaceComponent>;

package/src/plugins/SurfacePlugin/helpers.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+/**
+ * Checks if the given data is an object and not null.
+ *
+ * Useful inside surface component resolvers as a type guard.
+ *
+ * @example
+ * ```ts
+ *  const old =
+ *    data.content &&
+ *      typeof data.content === 'object' &&
+ *      'id' in data.content &&
+ *      typeof data.content.id === 'string';
+ *
+ *  // becomes
+ *  const new = isObject(data.content) && typeof data.content.id === 'string';
+ * ```
+ */
+export const isObject = (data: unknown): data is { [key: string]: unknown } => !!data && typeof data === 'object';

package/src/plugins/SurfacePlugin/index.ts

@@ -2,6 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
+export * from './helpers';
 export * from './provides';
 
 export * from './ErrorBoundary';

package/src/plugins/common/graph.ts

@@ -10,7 +10,7 @@ import type { Plugin } from '../PluginHost';
 /**
  * Provides for a plugin that exposes the application graph.
  */
-export type GraphPluginProvides = {
+export type GraphProvides = {
   graph: Graph;
 };
 
@@ -24,7 +24,7 @@ export type GraphBuilderProvides = {
  * Type guard for graph plugins.
  */
 export const parseGraphPlugin = (plugin: Plugin) =>
-  (plugin.provides as any).graph?.root ? (plugin as Plugin<GraphPluginProvides>) : undefined;
+  (plugin.provides as any).graph?.root ? (plugin as Plugin<GraphProvides>) : undefined;
 
 /**
  * Type guard for graph builder plugins.