@dxos/app-framework 0.3.9-main.cea1d3b → 0.3.9-main.d5f3fd3

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

@@ -1,3 +1,4 @@
+export * from './helpers';
 export * from './provides';
 export * from './ErrorBoundary';
 export * from './Surface';

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/app-framework",
-  "version": "0.3.9-main.cea1d3b",
+  "version": "0.3.9-main.d5f3fd3",
   "description": "A framework for building applications from composible plugins.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -16,12 +16,12 @@
     "@preact/signals-react": "^1.3.6",
     "deepsignal": "1.4.0-shallow.0",
     "zod": "^3.22.4",
-    "@dxos/app-graph": "0.3.9-main.cea1d3b",
-    "@dxos/async": "0.3.9-main.cea1d3b",
-    "@dxos/local-storage": "0.3.9-main.cea1d3b",
-    "@dxos/invariant": "0.3.9-main.cea1d3b",
-    "@dxos/log": "0.3.9-main.cea1d3b",
-    "@dxos/debug": "0.3.9-main.cea1d3b"
+    "@dxos/app-graph": "0.3.9-main.d5f3fd3",
+    "@dxos/debug": "0.3.9-main.d5f3fd3",
+    "@dxos/async": "0.3.9-main.d5f3fd3",
+    "@dxos/invariant": "0.3.9-main.d5f3fd3",
+    "@dxos/log": "0.3.9-main.d5f3fd3",
+    "@dxos/local-storage": "0.3.9-main.d5f3fd3"
   },
   "devDependencies": {
     "@types/react": "^18.0.21",

package/src/plugins/PluginHost/plugin.ts

@@ -45,7 +45,7 @@ export type Plugin<TProvides = {}> = {
     shortId?: string;
 
     /**
-     * Human readable name.
+     * Human-readable name.
      */
     name?: string;
 
@@ -54,6 +54,11 @@ export type Plugin<TProvides = {}> = {
      */
     description?: string;
 
+    /**
+     * Tags to help categorize the plugin.
+     */
+    tags?: string[];
+
     /**
      * Component to render icon for the plugin when displayed in a list.
      */

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.

package/dist/lib/node/chunk-YDKX45O3.cjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/plugins/SurfacePlugin/provides.ts", "../../../src/plugins/SurfacePlugin/SurfaceRootContext.tsx", "../../../src/plugins/SurfacePlugin/meta.ts"],
-  "sourcesContent": ["//\n// Copyright 2023 DXOS.org\n//\n\nimport { type SurfaceComponent, type SurfaceRootContext } from './SurfaceRootContext';\nimport { type Plugin } from '../PluginHost';\n\nexport type SurfaceProvides = {\n  surface: {\n    /**\n     * Used by the `Surface` resolver to find a component to render.\n     */\n    component: SurfaceComponent;\n  };\n};\n\nexport type SurfacePluginProvides = {\n  surface: SurfaceRootContext;\n};\n\nexport const parseRootSurfacePlugin = (plugin?: Plugin) =>\n  (plugin?.provides as any)?.surface?.components ? (plugin as Plugin<SurfacePluginProvides>) : undefined;\n\nexport const parseSurfacePlugin = (plugin?: Plugin) =>\n  (plugin?.provides as any)?.surface?.component ? (plugin as Plugin<SurfaceProvides>) : undefined;\n", "//\n// Copyright 2023 DXOS.org\n//\n\nimport { createContext, useContext, type Context, type Provider, type ReactNode, type ForwardedRef } from 'react';\n\nimport { type SurfaceProps } from './Surface';\n\n// TODO(wittjosiah): Factor out.\ntype WithRequiredProperty<Type, Key extends keyof Type> = Type & {\n  [Property in Key]-?: Type[Property];\n};\n\ntype SurfaceComponentProps = WithRequiredProperty<SurfaceProps, 'data'>;\n\n/**\n * Function which resolves a Surface.\n *\n * If a null value is returned, the rendering is deferred to other plugins.\n */\nexport type SurfaceComponent = (props: SurfaceComponentProps, forwardedRef: ForwardedRef<HTMLElement>) => ReactNode;\n\nexport type SurfaceRootContext = {\n  components: Record<string, SurfaceComponent>;\n};\n\nconst SurfaceRootContext: Context<SurfaceRootContext> = createContext<SurfaceRootContext>({ components: {} });\n\nexport const useSurface = () => useContext(SurfaceRootContext);\n\nexport const SurfaceProvider: Provider<SurfaceRootContext> = SurfaceRootContext.Provider;\n", "//\n// Copyright 2023 DXOS.org\n//\n\nconst SurfaceMeta = {\n  id: 'dxos.org/plugin/surface',\n};\n\nexport default SurfaceMeta;\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;ACIA,mBAA0G;ADgBnG,IAAMA,yBAAyB,CAACC,WACpCA,QAAQC,UAAkBC,SAASC,aAAcH,SAA2CI;AAExF,IAAMC,qBAAqB,CAACL,WAChCA,QAAQC,UAAkBC,SAASI,YAAaN,SAAqCI;ACExF,IAAMG,qBAAkDC,gDAAkC;EAAEL,YAAY,CAAC;AAAE,CAAA;AAEpG,IAAMM,aAAa,UAAMC,yBAAWH,kBAAAA;AAEpC,IAAMI,kBAAgDJ,mBAAmBK;AC1BhF,IAAMC,cAAc;EAClBC,IAAI;AACN;AAEA,IAAA,eAAeD;",
-  "names": ["parseRootSurfacePlugin", "plugin", "provides", "surface", "components", "undefined", "parseSurfacePlugin", "component", "SurfaceRootContext", "createContext", "useSurface", "useContext", "SurfaceProvider", "Provider", "SurfaceMeta", "id"]
-}