feat: DH-19146: ElementPlugin mapping hook (#2477)

Will also need deephaven/deephaven-plugins#1201
for the plugin side, but this implements a hook that pulls the necessary
mapping for element plugins

Author: jnumainville

package-lock.json

@@ -13,6 +13,7 @@ export const PluginType = Object.freeze({
   WIDGET_PLUGIN: 'WidgetPlugin',
   TABLE_PLUGIN: 'TablePlugin',
   THEME_PLUGIN: 'ThemePlugin',
+  ELEMENT_PLUGIN: 'ElementPlugin',
 });
 
 /**
@@ -238,12 +239,35 @@ export function isThemePlugin(plugin: PluginModule): plugin is ThemePlugin {
   return 'type' in plugin && plugin.type === PluginType.THEME_PLUGIN;
 }
 
+export type ElementName = string;
+
+/** A mapping of element names to their React components. */
+export type ElementPluginMappingDefinition = Record<
+  ElementName,
+  React.ComponentType
+>;
+
+export type ElementMap = ReadonlyMap<ElementName, React.ComponentType>;
+
+/** An element plugin is used by deephaven.ui to render custom components
+ * The mapping contains the element names as keys and the React components as values.
+ */
+export interface ElementPlugin extends Plugin {
+  type: typeof PluginType.ELEMENT_PLUGIN;
+  mapping: ElementPluginMappingDefinition;
+}
+
+export function isElementPlugin(plugin: PluginModule): plugin is ElementPlugin {
+  return 'type' in plugin && plugin.type === PluginType.ELEMENT_PLUGIN;
+}
+
 export function isPlugin(plugin: unknown): plugin is Plugin {
   return (
     isDashboardPlugin(plugin as PluginModule) ||
     isAuthPlugin(plugin as PluginModule) ||
     isTablePlugin(plugin as PluginModule) ||
     isThemePlugin(plugin as PluginModule) ||
-    isWidgetPlugin(plugin as PluginModule)
+    isWidgetPlugin(plugin as PluginModule) ||
+    isElementPlugin(plugin as PluginModule)
   );
 }

packages/plugin/src/PluginTypes.ts

@@ -4,6 +4,7 @@ import { type ThemeData } from '@deephaven/components';
 import { dhTruck, vsPreview } from '@deephaven/icons';
 import {
   type DashboardPlugin,
+  type ElementPlugin,
   type PluginModule,
   PluginType,
   type ThemePlugin,
@@ -13,6 +14,7 @@ import {
   pluginSupportsType,
   getIconForPlugin,
   getThemeDataFromPlugins,
+  getPluginsElementMap,
 } from './PluginUtils';
 
 function TestWidget() {
@@ -32,6 +34,23 @@ const dashboardPlugin: DashboardPlugin = {
   component: TestWidget,
 };
 
+const ElementPluginOne: ElementPlugin = {
+  name: 'test-element-plugin-one',
+  type: PluginType.ELEMENT_PLUGIN,
+  mapping: {
+    'test-element-one': TestWidget,
+    'test-element-two': TestWidget,
+  },
+};
+
+const ElementPluginTwo: ElementPlugin = {
+  name: 'test-element-plugin-two',
+  type: PluginType.ELEMENT_PLUGIN,
+  mapping: {
+    'test-element-three': TestWidget,
+  },
+};
+
 test('pluginSupportsType', () => {
   expect(pluginSupportsType(widgetPlugin, 'test-widget')).toBe(true);
   expect(pluginSupportsType(widgetPlugin, 'test-widget-two')).toBe(true);
@@ -170,3 +189,32 @@ describe('getThemeDataFromPlugins', () => {
     expect(actual).toEqual(expected);
   });
 });
+
+describe('getElementPluginMap', () => {
+  it('should return a mapping of element plugins', () => {
+    const pluginMap = new Map<string, PluginModule>([
+      [ElementPluginOne.name, ElementPluginOne],
+      [ElementPluginTwo.name, ElementPluginTwo],
+      [dashboardPlugin.name, dashboardPlugin],
+      [widgetPlugin.name, widgetPlugin],
+    ]);
+
+    const elementMapping = getPluginsElementMap(pluginMap);
+
+    expect(elementMapping.size).toBe(3);
+    expect(elementMapping.get('test-element-one')).toBe(TestWidget);
+    expect(elementMapping.get('test-element-two')).toBe(TestWidget);
+    expect(elementMapping.get('test-element-three')).toBe(TestWidget);
+  });
+
+  it('should return an empty map if no element plugins are present', () => {
+    const pluginMap = new Map<string, PluginModule>([
+      [widgetPlugin.name, widgetPlugin],
+      [dashboardPlugin.name, dashboardPlugin],
+    ]);
+
+    const elementMapping = getPluginsElementMap(pluginMap);
+
+    expect(elementMapping.size).toBe(0);
+  });
+});

packages/plugin/src/PluginUtils.test.tsx

@@ -9,6 +9,9 @@ import {
   type PluginModuleMap,
   type ThemePlugin,
   isThemePlugin,
+  isElementPlugin,
+  type ElementPlugin,
+  type ElementMap,
 } from './PluginTypes';
 
 const log = Log.module('@deephaven/plugin.PluginUtils');
@@ -76,3 +79,21 @@ export function getThemeDataFromPlugins(
     })
     .flat();
 }
+
+/**
+ * Get a mapping of element names to their React components from the given plugin map.
+ * @param pluginMap The plugin map to extract element plugins from.
+ * @returns A Map of element names to their React components.
+ */
+export function getPluginsElementMap(pluginMap: PluginModuleMap): ElementMap {
+  const elementPluginEntries = [...pluginMap.entries()].filter(
+    (entry): entry is [string, ElementPlugin] =>
+      isElementPlugin(entry[1]) && entry[1].mapping != null
+  );
+
+  log.debug('Getting element plugin mapping', elementPluginEntries);
+
+  return new Map(
+    elementPluginEntries.flatMap(([, plugin]) => Object.entries(plugin.mapping))
+  );
+}

packages/plugin/src/PluginUtils.tsx

@@ -8,3 +8,4 @@ export * from './usePlugins';
 export * from './WidgetView';
 export * from './PersistentStateContext';
 export * from './usePersistentState';
+export * from './usePluginsElementMap';

packages/plugin/src/index.ts

@@ -0,0 +1,28 @@
+import { renderHook } from '@testing-library/react-hooks';
+import { TestUtils } from '@deephaven/test-utils';
+import type { PluginModuleMap } from './PluginTypes';
+import { usePluginsElementMap } from './usePluginsElementMap';
+import { getPluginsElementMap } from './PluginUtils';
+import { usePlugins } from './usePlugins';
+
+jest.mock('./PluginUtils');
+jest.mock('./usePlugins');
+
+const { asMock } = TestUtils;
+
+const mockElementPluginMapping = new Map<
+  string,
+  React.ComponentType<unknown>
+>();
+
+const mockPlugins: PluginModuleMap = new Map();
+
+it('should return element plugin mapping from plugins context', () => {
+  asMock(getPluginsElementMap).mockReturnValue(mockElementPluginMapping);
+  asMock(usePlugins).mockReturnValue(mockPlugins);
+
+  const { result } = renderHook(() => usePluginsElementMap());
+
+  expect(getPluginsElementMap).toHaveBeenCalledWith(mockPlugins);
+  expect(result.current).toEqual(mockElementPluginMapping);
+});

packages/plugin/src/usePluginsElementMap.test.ts

@@ -0,0 +1,22 @@
+import { useMemo } from 'react';
+import { usePlugins } from './usePlugins';
+import { getPluginsElementMap } from './PluginUtils';
+import type { ElementMap } from './PluginTypes';
+
+/**
+ * Get all ElementPlugin elements from the plugins context
+ * @returns ElementPlugin mapping as a Map of plugin name to component type
+ */
+export function usePluginsElementMap(): ElementMap {
+  // Get all plugins from the context
+  const plugins = usePlugins();
+
+  const elementPlugins = useMemo(
+    () => getPluginsElementMap(plugins),
+    [plugins]
+  );
+
+  return elementPlugins;
+}
+
+export default usePluginsElementMap;