feat: usePanelRegistration hook (#1208)

resolves #1207

Author: bmingles

packages/dashboard/src/DashboardPlugin.ts

@@ -1,4 +1,10 @@
-import { Component, ComponentType } from 'react';
+import {
+  Component,
+  ComponentType,
+  ForwardRefExoticComponent,
+  PropsWithoutRef,
+  RefAttributes,
+} from 'react';
 import { ConnectedComponent } from 'react-redux';
 import GoldenLayout from '@deephaven/golden-layout';
 import type {
@@ -8,6 +14,34 @@ import type {
 } from '@deephaven/golden-layout';
 import PanelManager from './PanelManager';
 
+/**
+ * Alias for the return type of React.forwardRef()
+ */
+export type ForwardRefComponentType<P, R> = ForwardRefExoticComponent<
+  PropsWithoutRef<P> & RefAttributes<R>
+>;
+
+/**
+ * Panel components can provide static props that provide meta data about the
+ * panel.
+ */
+export interface PanelStaticMetaData {
+  /**
+   * Should be set to the same name as the component type.
+   * @deprecated Use `displayName` instead.
+   */
+  COMPONENT?: string;
+
+  /** Title of the panel. */
+  TITLE?: string;
+}
+
+/**
+ * Panels defined as functional components have to use React.forwardRef.
+ */
+export type PanelFunctionComponentType<P, R> = ForwardRefComponentType<P, R> &
+  PanelStaticMetaData;
+
 export type WrappedComponentType<
   P extends PanelProps,
   C extends ComponentType<P>
@@ -16,7 +50,12 @@ export type WrappedComponentType<
 export type PanelComponentType<
   P extends PanelProps = PanelProps,
   C extends ComponentType<P> = ComponentType<P>
-> = ComponentType<P> | WrappedComponentType<P, C>;
+> = (
+  | ComponentType<P>
+  | WrappedComponentType<P, C>
+  | PanelFunctionComponentType<P, unknown>
+) &
+  PanelStaticMetaData;
 
 export function isWrappedComponent<
   P extends PanelProps,

packages/dashboard/src/layout/index.ts

@@ -3,3 +3,4 @@ export { default as LayoutUtils } from './LayoutUtils';
 export { default as GLPropTypes } from './GLPropTypes';
 
 export * from './hooks';
+export { default as usePanelRegistration } from './usePanelRegistration';

packages/dashboard/src/layout/usePanelRegistration.test.tsx

@@ -0,0 +1,87 @@
+/* eslint-disable max-classes-per-file */
+import React from 'react';
+import { renderHook } from '@testing-library/react-hooks';
+import usePanelRegistration from './usePanelRegistration';
+import { PanelProps } from '../DashboardPlugin';
+
+/* eslint-disable react/prefer-stateless-function */
+class ClassCOMPONENT extends React.Component<PanelProps> {
+  static COMPONENT = 'ClassCOMPONENT';
+}
+class ClassDisplayName extends React.Component<PanelProps> {
+  static displayName = 'ClassDisplayName';
+}
+class ClassNoName extends React.Component<PanelProps> {}
+/* eslint-enable react/prefer-stateless-function */
+
+function FnCOMPONENT() {
+  return null;
+}
+FnCOMPONENT.COMPONENT = 'FnCOMPONENT';
+function FnDisplayName() {
+  return null;
+}
+FnDisplayName.displayName = 'FnDisplayName';
+function FnNoName() {
+  return null;
+}
+
+const deregister = jest.fn();
+const registerComponent = jest.fn();
+const hydrate = jest.fn();
+const dehydrate = jest.fn();
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  registerComponent.mockReturnValue(deregister);
+});
+
+it.each([
+  [ClassCOMPONENT.COMPONENT, ClassCOMPONENT],
+  [ClassDisplayName.displayName, ClassDisplayName],
+  [FnCOMPONENT.COMPONENT, FnCOMPONENT],
+  [FnDisplayName.displayName, FnDisplayName],
+])(
+  'should register components with COMPONENT or displayName attributes and deregister on unmount: "%s"',
+  (_label, ComponentType) => {
+    const { unmount } = renderHook(() =>
+      usePanelRegistration(registerComponent, ComponentType, hydrate, dehydrate)
+    );
+
+    const name =
+      'COMPONENT' in ComponentType
+        ? ComponentType.COMPONENT
+        : ComponentType.displayName;
+
+    expect(registerComponent).toHaveBeenCalledWith(
+      name,
+      ComponentType,
+      hydrate,
+      dehydrate
+    );
+
+    expect(deregister).not.toHaveBeenCalled();
+
+    unmount();
+
+    expect(deregister).toHaveBeenCalled();
+  }
+);
+
+it.each([
+  ['MockClassNoName', ClassNoName],
+  ['MockFnNoName', FnNoName],
+])(
+  'should throw an error if no COMPONENT or displayName attribute exists: "%s"',
+  (_label, ComponentType) => {
+    const { result } = renderHook(() =>
+      usePanelRegistration(registerComponent, ComponentType, hydrate, dehydrate)
+    );
+
+    expect(result.error).toEqual(
+      new Error(
+        'ComponentType must have a `COMPONENT` or `displayName` attribute.'
+      )
+    );
+  }
+);

packages/dashboard/src/layout/usePanelRegistration.ts

@@ -0,0 +1,47 @@
+import React from 'react';
+import {
+  DashboardPluginComponentProps,
+  PanelComponentType,
+  PanelDehydrateFunction,
+  PanelHydrateFunction,
+  PanelProps,
+} from '../DashboardPlugin';
+
+/**
+ * Registers a given panel component. Also runs a `useEffect` that will
+ * automatically de-register then panel on unmount.
+ * @param registerComponent
+ * @param ComponentType
+ * @param hydrate
+ * @param dehydrate
+ */
+export default function usePanelRegistration<
+  P extends PanelProps,
+  C extends React.ComponentType<P>
+>(
+  registerComponent: DashboardPluginComponentProps['registerComponent'],
+  ComponentType: PanelComponentType<P, C>,
+  hydrate?: PanelHydrateFunction<P>,
+  dehydrate?: PanelDehydrateFunction
+) {
+  const name = ComponentType.COMPONENT ?? ComponentType.displayName;
+
+  if (name == null) {
+    throw new Error(
+      'ComponentType must have a `COMPONENT` or `displayName` attribute.'
+    );
+  }
+
+  React.useEffect(() => {
+    const deregister = registerComponent(
+      name,
+      ComponentType,
+      hydrate,
+      dehydrate
+    );
+
+    return () => {
+      deregister();
+    };
+  }, [ComponentType, dehydrate, hydrate, name, registerComponent]);
+}