@dxos/app-framework 0.3.6 → 0.3.7-main.0bad7ea

package/src/plugins/SurfacePlugin/Surface.tsx

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-import React, { type FC, type PropsWithChildren, type ReactNode } from 'react';
+import React, { forwardRef, type FC, type ReactNode, Fragment, type ForwardedRef, type PropsWithChildren } from 'react';
 import { createContext, useContext } from 'react';
 
 import { ErrorBoundary } from './ErrorBoundary';
@@ -13,7 +13,7 @@ import { type SurfaceComponent, useSurface } from './SurfaceRootContext';
  */
 export type Direction = 'inline' | 'inline-reverse' | 'block' | 'block-reverse';
 
-export type SurfaceProps = {
+export type SurfaceProps = PropsWithChildren<{
   /**
    * Role defines how the data should be rendered.
    */
@@ -56,35 +56,43 @@ export type SurfaceProps = {
    * NOTE: This is not yet implemented.
    */
   direction?: Direction;
-};
+
+  /**
+   * 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;
+}>;
 
 /**
  * A surface is a named region of the screen that can be populated by plugins.
  */
-export const Surface = ({ role, name = role, fallback, ...rest }: SurfaceProps) => {
-  const props = { role, name, fallback, ...rest };
-  const context = useContext(SurfaceContext);
-  const data = props.data ?? ((name && context?.surfaces?.[name]?.data) || {});
-
-  return (
-    <>
-      {fallback ? (
-        <ErrorBoundary data={data} fallback={fallback}>
-          <SurfaceResolver {...props} />
-        </ErrorBoundary>
-      ) : (
-        <SurfaceResolver {...props} />
-      )}
-    </>
-  );
-};
+export const Surface = forwardRef<HTMLElement, SurfaceProps>(
+  ({ role, name = role, fallback, ...rest }, forwardedRef) => {
+    const props = { role, name, fallback, ...rest };
+    const context = useContext(SurfaceContext);
+    const data = props.data ?? ((name && context?.surfaces?.[name]?.data) || {});
+
+    return (
+      <>
+        {fallback ? (
+          <ErrorBoundary data={data} fallback={fallback}>
+            <SurfaceResolver {...props} ref={forwardedRef} />
+          </ErrorBoundary>
+        ) : (
+          <SurfaceResolver {...props} ref={forwardedRef} />
+        )}
+      </>
+    );
+  },
+);
 
 const SurfaceContext = createContext<SurfaceProps | null>(null);
 
-const SurfaceResolver = (props: SurfaceProps) => {
+const SurfaceResolver = forwardRef<HTMLElement, SurfaceProps>((props, forwardedRef) => {
   const { components } = useSurface();
   const parent = useContext(SurfaceContext);
-  const nodes = resolveNodes(components, props, parent);
+  const nodes = resolveNodes(components, props, parent, forwardedRef);
   const currentContext: SurfaceProps = {
     ...props,
     surfaces: {
@@ -98,12 +106,13 @@ const SurfaceResolver = (props: SurfaceProps) => {
       {nodes.length > 0 ? nodes : props.contentFallback ? <props.contentFallback /> : null}
     </SurfaceContext.Provider>
   );
-};
+});
 
 const resolveNodes = (
   components: Record<string, SurfaceComponent>,
   props: SurfaceProps,
   context: SurfaceProps | null,
+  forwardedRef: ForwardedRef<HTMLElement>,
 ): ReactNode[] => {
   const data = {
     ...((props.name && context?.surfaces?.[props.name]?.data) || {}),
@@ -112,12 +121,10 @@ const resolveNodes = (
 
   const nodes = Object.entries(components)
     .map(([key, component]) => {
-      const result = component(data, props.role);
-      return result ? <Wrapper key={key}>{result}</Wrapper> : undefined;
+      const result = component({ ...props, data }, forwardedRef);
+      return result ? <Fragment key={key}>{result}</Fragment> : undefined;
     })
     .filter((Component): Component is JSX.Element => Boolean(Component));
 
   return props.limit ? nodes.slice(0, props.limit) : nodes;
 };
-
-const Wrapper = ({ children }: PropsWithChildren) => <>{children}</>;

package/src/plugins/SurfacePlugin/SurfaceRootContext.tsx

@@ -2,14 +2,23 @@
 // Copyright 2023 DXOS.org
 //
 
-import { createContext, useContext, type Context, type Provider, type ReactNode } from 'react';
+import { createContext, useContext, type Context, type Provider, type ReactNode, type ForwardedRef } from 'react';
+
+import { type SurfaceProps } from './Surface';
+
+// TODO(wittjosiah): Factor out.
+type WithRequiredProperty<Type, Key extends keyof Type> = Type & {
+  [Property in Key]-?: Type[Property];
+};
+
+type SurfaceComponentProps = WithRequiredProperty<SurfaceProps, 'data'>;
 
 /**
  * Function which resolves a Surface.
  *
  * If a null value is returned, the rendering is deferred to other plugins.
  */
-export type SurfaceComponent = (data: Record<string, unknown>, role?: string) => ReactNode;
+export type SurfaceComponent = (props: SurfaceComponentProps, forwardedRef: ForwardedRef<HTMLElement>) => ReactNode;
 
 export type SurfaceRootContext = {
   components: Record<string, SurfaceComponent>;

package/src/plugins/SurfacePlugin/index.ts

@@ -2,7 +2,8 @@
 // Copyright 2023 DXOS.org
 //
 
+export * from './provides';
+
 export * from './ErrorBoundary';
 export * from './Surface';
-export * from './SurfacePlugin';
 export * from './SurfaceRootContext';

package/src/plugins/SurfacePlugin/meta.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+const SurfaceMeta = {
+  id: 'dxos.org/plugin/surface',
+};
+
+export default SurfaceMeta;

package/src/plugins/SurfacePlugin/plugin.tsx

@@ -0,0 +1,36 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { deepSignal, shallow } from 'deepsignal/react';
+import React from 'react';
+
+import { SurfaceProvider, type SurfaceRootContext } from './SurfaceRootContext';
+import SurfaceMeta from './meta';
+import { parseSurfacePlugin, type SurfacePluginProvides } from './provides';
+import type { PluginDefinition } from '../PluginHost';
+import { filterPlugins } from '../helpers';
+
+/**
+ * Provides a registry of surface components.
+ */
+const SurfacePlugin = (): PluginDefinition<SurfacePluginProvides> => {
+  const state = deepSignal<SurfaceRootContext>({ components: {} });
+
+  return {
+    meta: SurfaceMeta,
+    ready: async (plugins) => {
+      state.components = shallow(
+        filterPlugins(plugins, parseSurfacePlugin).reduce((acc, plugin) => {
+          return { ...acc, [plugin.meta.id]: plugin.provides.surface.component };
+        }, {}),
+      );
+    },
+    provides: {
+      surface: state,
+      context: ({ children }) => <SurfaceProvider value={state}>{children}</SurfaceProvider>,
+    },
+  };
+};
+
+export default SurfacePlugin;

package/src/plugins/SurfacePlugin/provides.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type SurfaceComponent, type SurfaceRootContext } from './SurfaceRootContext';
+import { type Plugin } from '../PluginHost';
+
+export type SurfaceProvides = {
+  surface: {
+    /**
+     * Used by the `Surface` resolver to find a component to render.
+     */
+    component: SurfaceComponent;
+  };
+};
+
+export type SurfacePluginProvides = {
+  surface: SurfaceRootContext;
+};
+
+export const parseRootSurfacePlugin = (plugin?: Plugin) =>
+  (plugin?.provides as any)?.surface?.components ? (plugin as Plugin<SurfacePluginProvides>) : undefined;
+
+export const parseSurfacePlugin = (plugin?: Plugin) =>
+  (plugin?.provides as any)?.surface?.component ? (plugin as Plugin<SurfaceProvides>) : undefined;

package/tsconfig.json

@@ -26,6 +26,9 @@
     {
       "path": "../../common/invariant"
     },
+    {
+      "path": "../../common/local-storage"
+    },
     {
       "path": "../../common/log"
     },

package/dist/types/src/plugins/IntentPlugin/IntentPlugin.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"IntentPlugin.d.ts","sourceRoot":"","sources":["../../../../../src/plugins/IntentPlugin/IntentPlugin.tsx"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAGnE,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE;QACN,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,GAAG,CAAC;KACtD,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,aAAa,CAAC;CACvB,CAAC;AAEF,eAAO,MAAM,iBAAiB,WAAY,MAAM,6CACkD,CAAC;AAEnG,eAAO,MAAM,yBAAyB,WAAY,MAAM,+CAC4C,CAAC;AAErG;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAO,iBAAiB,oBAAoB,CAuCpE,CAAC"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"SurfacePlugin.d.ts","sourceRoot":"","sources":["../../../../../src/plugins/SurfacePlugin/SurfacePlugin.tsx"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,gBAAgB,EAAmB,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACvG,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAG9D,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE;QACP;;WAEG;QACH,SAAS,EAAE,gBAAgB,CAAC;KAC7B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,kBAAkB,CAAC;CAC7B,CAAC;AAEF,eAAO,MAAM,sBAAsB,YAAa,MAAM,8CACkD,CAAC;AAEzG,eAAO,MAAM,kBAAkB,YAAa,MAAM,wCAC+C,CAAC;AAElG;;GAEG;AACH,eAAO,MAAM,aAAa,QAAO,iBAAiB,qBAAqB,CAmBtE,CAAC"}

package/src/plugins/SurfacePlugin/SurfacePlugin.tsx

@@ -1,53 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { deepSignal, shallow } from 'deepsignal/react';
-import React from 'react';
-
-import { type SurfaceComponent, SurfaceProvider, type SurfaceRootContext } from './SurfaceRootContext';
-import type { Plugin, PluginDefinition } from '../PluginHost';
-import { filterPlugins } from '../helpers';
-
-export type SurfaceProvides = {
-  surface: {
-    /**
-     * Used by the `Surface` resolver to find a component to render.
-     */
-    component: SurfaceComponent;
-  };
-};
-
-export type SurfacePluginProvides = {
-  surface: SurfaceRootContext;
-};
-
-export const parseRootSurfacePlugin = (plugin?: Plugin) =>
-  (plugin?.provides as any)?.surface?.components ? (plugin as Plugin<SurfacePluginProvides>) : undefined;
-
-export const parseSurfacePlugin = (plugin?: Plugin) =>
-  (plugin?.provides as any)?.surface?.component ? (plugin as Plugin<SurfaceProvides>) : undefined;
-
-/**
- * Provides a registry of surface components.
- */
-export const SurfacePlugin = (): PluginDefinition<SurfacePluginProvides> => {
-  const state = deepSignal<SurfaceRootContext>({ components: {} });
-
-  return {
-    meta: {
-      id: 'dxos.org/plugin/surface',
-    },
-    ready: async (plugins) => {
-      state.components = shallow(
-        filterPlugins(plugins, parseSurfacePlugin).reduce((acc, plugin) => {
-          return { ...acc, [plugin.meta.id]: plugin.provides.surface.component };
-        }, {}),
-      );
-    },
-    provides: {
-      surface: state,
-      context: ({ children }) => <SurfaceProvider value={state}>{children}</SurfaceProvider>,
-    },
-  };
-};