feat: DH-21757: WidgetPlugin support in deephaven.ui

plugins/ui/docs/architecture.md

@@ -163,6 +163,6 @@ A component that is created on the server side runs through a few steps before i
 
 1. [Element](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/deephaven/ui/elements/Element.py) - The basis for all UI components. Generally, a [FunctionElement](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/deephaven/ui/elements/FunctionElement.py) created by a script using the [@ui.component](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/deephaven/ui/components/make_component.py) decorator that does not run the function until it is rendered. The result can change depending on the context that it is rendered in (e.g., what "state" is set).
 2. [ElementMessageStream](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/deephaven/ui/object_types/ElementMessageStream.py) - The `ElementMessageStream` is responsible for rendering one instance of an element in a specific rendering context and handling the server-client communication. The element is rendered to create a [RenderedNode](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/deephaven/ui/renderer/RenderedNode.py), which is an immutable representation of a rendered document. The `RenderedNode` is then encoded into JSON using [NodeEncoder](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/deephaven/ui/renderer/NodeEncoder.py), which pulls out all the non-serializable objects (such as Tables) and maps them to exported objects, and all the callables to be mapped to commands that JSON-RPC can accept. This is the final representation of the document sent to the client and ultimately handled by the `WidgetHandler`.
-3. [DashboardPlugin](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/js/src/DashboardPlugin.tsx) - Client-side `DashboardPlugin` that listens for when a widget of type `Element` is opened and manages the `WidgetHandler` instances that are created for each widget.
-4. [WidgetHandler](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/js/src/WidgetHandler.tsx) - Uses JSON-RPC communication with an `ElementMessageStream` instance to set the initial state, then load the initial rendered document and associated exported objects. Listens for any changes and updates the document accordingly.
-5. [DocumentHandler](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/js/src/DocumentHandler.tsx) - Handles the root of a rendered document, laying out the appropriate panels or dashboard specified.
+3. [UIWidgetPlugin](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/js/src/UIWidgetPlugin.tsx) - Client-side `WidgetPlugin` that listens for when a widget of type `Element` is opened and manages the `WidgetHandler` instances that are created for each widget.
+4. [WidgetHandler](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/js/src/widget/WidgetHandler.tsx) - Uses JSON-RPC communication with an `ElementMessageStream` instance to set the initial state, then load the initial rendered document and associated exported objects. Listens for any changes and updates the document accordingly.
+5. [DocumentHandler](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/js/src/widget/DocumentHandler.tsx) - Handles the root of a rendered document, laying out the appropriate panels or dashboard specified.

plugins/ui/docs/components/dashboard.md

@@ -232,6 +232,25 @@ dash_holy_grail = ui.dashboard(
 )
 ```
 
+## Hiding Panel Headers
+
+By default, each panel in a dashboard displays a header bar with the panel title and controls. Setting `show_headers=False` removes all panel headers, giving a cleaner, borderless appearance useful for presentation-style dashboards.
+
+```python
+from deephaven import ui
+
+dash_no_headers = ui.dashboard(
+    ui.row(
+        ui.panel("A", title="A"),
+        ui.panel("B", title="B"),
+    ),
+    show_headers=False,
+)
+```
+
+> [!NOTE]
+> When `show_headers=False`, users will not be able to drag panels to rearrange the layout, since the header is the drag handle.
+
 ## Nested Dashboards
 
 Dashboards can be nested inside panels to create complex layouts with isolated drag-and-drop regions. Each nested dashboard creates its own independent layout that users can rearrange without affecting the parent dashboard.

plugins/ui/docs/components/uri.md

@@ -60,6 +60,28 @@ list_view = ui.list_view(
 )
 ```
 
+### Nesting a component from another query
+
+You can use `ui.resolve` to reference a `@ui.component` defined in another Persistent Query and nest it inside a panel in the current query. The resolved component is rendered by the web client, so the worker hosting the dashboard does not need to load the data or recompute the component.
+
+```py order=null
+from deephaven import ui
+
+# Resolve a ui widget defined in another persistent query
+remote_widget = ui.resolve("pq://DataServiceQuery/scope/my_widget")
+
+
+@ui.component
+def cross_query_dashboard():
+    return ui.row(
+        ui.panel(remote_widget, title="Remote Widget"),
+        ui.panel("Local Content", title="Local"),
+    )
+
+
+my_dashboard = ui.dashboard(cross_query_dashboard())
+```
+
 ## URI Encoding
 
 If your URI contains any special characters, such as spaces or slashes, you must encode the URI components using standard URL encoding. This is because URIs are often used in web contexts where special characters can cause issues. You can use Python's built-in `urllib.parse.quote` function to encode your URIs.

plugins/ui/docs/snapshots/1d8b6032316168e0cd14ff061a00e0d5.json

@@ -0,0 +1 @@
+{"file":"components/dashboard.md","objects":{"dash_no_headers":{"type":"deephaven.ui.Dashboard","data":{"document":{"props":{"showHeaders":false,"children":{"__dhElemName":"deephaven.ui.components.Row","props":{"children":[{"__dhElemName":"deephaven.ui.components.Panel","props":{"title":"A","direction":"column","alignItems":"start","gap":"size-100","overflow":"auto","padding":"size-100","children":"A"}},{"__dhElemName":"deephaven.ui.components.Panel","props":{"title":"B","direction":"column","alignItems":"start","gap":"size-100","overflow":"auto","padding":"size-100","children":"B"}}]}}},"__dhElemName":"deephaven.ui.components.Dashboard"},"state":"{}"}}}}

plugins/ui/docs/snapshots/5ef4aa2cf2eb0aa5430fcfe3100c6ff7.json

@@ -0,0 +1 @@
+{"file":"components/uri.md","objects":{"remote_widget":{"type":"deephaven.ui.Element","data":{"document":{"props":{"uri":"pq://DataServiceQuery/scope/my_widget"},"__dhElemName":"deephaven.ui.elements.UriElement"},"state":"{}"}},"my_dashboard":{"type":"deephaven.ui.Dashboard","data":{"document":{"props":{"showHeaders":true,"children":{"__dhElemName":"__main__.cross_query_dashboard","props":{"children":{"__dhElemName":"deephaven.ui.components.Row","props":{"children":[{"__dhElemName":"deephaven.ui.components.Panel","props":{"title":"Remote Widget","direction":"column","alignItems":"start","gap":"size-100","overflow":"auto","padding":"size-100","children":{"__dhElemName":"deephaven.ui.elements.UriElement","props":{"uri":"pq://DataServiceQuery/scope/my_widget"}}}},{"__dhElemName":"deephaven.ui.components.Panel","props":{"title":"Local","direction":"column","alignItems":"start","gap":"size-100","overflow":"auto","padding":"size-100","children":"Local Content"}}]}}}}},"__dhElemName":"deephaven.ui.components.Dashboard"},"state":"{}"}}}}

plugins/ui/src/deephaven/ui/components/dashboard.py

@@ -4,15 +4,20 @@
 from ..elements import DashboardElement, FunctionElement
 
 
-def dashboard(element: FunctionElement) -> DashboardElement:
+def dashboard(
+    element: FunctionElement,
+    *,
+    show_headers: bool = True,
+) -> DashboardElement:
     """
     A dashboard is the container for an entire layout.
 
     Args:
         element: Element to render as the dashboard.
                  The element should render a layout that contains 1 root column or row.
+        show_headers: Whether to show headers on the dashboard panels. Defaults to True.
 
     Returns:
         The rendered dashboard.
     """
-    return DashboardElement(element)
+    return DashboardElement(element, show_headers=show_headers)

plugins/ui/src/deephaven/ui/elements/DashboardElement.py

@@ -8,5 +8,14 @@
 
 
 class DashboardElement(BaseElement):
-    def __init__(self, element: FunctionElement):
-        super().__init__("deephaven.ui.components.Dashboard", element)
+    def __init__(
+        self,
+        element: FunctionElement,
+        *,
+        show_headers: bool = True,
+    ):
+        super().__init__(
+            "deephaven.ui.components.Dashboard",
+            element,
+            show_headers=show_headers,
+        )

plugins/ui/src/js/__mocks__/@deephaven/plugin.js

@@ -1,8 +1,12 @@
 // Mock @deephaven/plugin package
+const React = require('react');
 const PluginActual = jest.requireActual('@deephaven/plugin');
 
 module.exports = {
   ...PluginActual,
   useDashboardPlugins: jest.fn(() => []),
+  // Mock usePersistentState to behave like useState.
+  // The real implementation requires FiberProvider which is internal to Dashboard.
+  usePersistentState: (initialState, _config) => React.useState(initialState),
   __esModule: true,
 };

plugins/ui/src/js/package.json

@@ -29,6 +29,7 @@
     "update-dh-packages": "node ../../../../tools/update-dh-packages.mjs"
   },
   "devDependencies": {
+    "@deephaven/test-utils": "^1.8.0",
     "@types/memoizee": "^0.4.5",
     "@types/react": "^18.0.0",
     "react": "^18.0.0",

plugins/ui/src/js/src/DashboardPlugin.tsx

@@ -1,24 +1,19 @@
 import React, { useCallback, useEffect, useMemo, useState } from 'react';
-import { nanoid } from 'nanoid';
 import {
   type DashboardPluginComponentProps,
   LayoutManagerContext,
   LayoutUtils,
   PanelEvent,
   useListener,
   useDashboardPluginData,
-  emitCreateDashboard,
   type WidgetDescriptor,
-  type PanelOpenEventDetail,
   DEFAULT_DASHBOARD_ID,
   useDashboardPanel,
 } from '@deephaven/dashboard';
 import Log from '@deephaven/log';
 import { DeferredApiBootstrap } from '@deephaven/jsapi-bootstrap';
-import { type dh } from '@deephaven/jsapi-types';
 import { ErrorBoundary } from '@deephaven/components';
 import { useDebouncedCallback } from '@deephaven/react-hooks';
-import styles from './styles.scss?inline';
 import {
   type ReadonlyWidgetData,
   type WidgetDataUpdate,
@@ -27,11 +22,6 @@ import {
 import PortalPanel from './layout/PortalPanel';
 import PortalPanelManager from './layout/PortalPanelManager';
 import DashboardWidgetHandler from './widget/DashboardWidgetHandler';
-import {
-  getPreservedData,
-  DASHBOARD_ELEMENT,
-  WIDGET_ELEMENT,
-} from './widget/WidgetUtils';
 import { usePanelId } from './layout/ReactPanelContext';
 
 const PLUGIN_NAME = '@deephaven/js-plugin-ui.DashboardPlugin';
@@ -63,6 +53,13 @@ interface WidgetWrapper {
   data?: ReadonlyWidgetData;
 }
 
+/**
+ * Handle legacy behaviour of an open widget being saved with the dashboard.
+ *
+ * Now UIWidgetPlugin is responsible for opening widgets in the dashboard.
+ * @param props Dashboard plugin props
+ * @returns Dashboard plugin content, which is responsible for handling legacy behaviour of an open widget being saved with the dashboard
+ */
 function InnerDashboardPlugin(
   props: DashboardPluginComponentProps
 ): JSX.Element | null {
@@ -78,66 +75,6 @@ function InnerDashboardPlugin(
     ReadonlyMap<WidgetId, WidgetWrapper>
   >(new Map());
 
-  const handleWidgetOpen = useCallback(
-    ({ widgetId, widget }: { widgetId: string; widget: WidgetDescriptor }) => {
-      log.debug('Opening widget with ID', widgetId, widget);
-      setWidgetMap(prevWidgetMap => {
-        const newWidgetMap = new Map(prevWidgetMap);
-        const oldWidget = newWidgetMap.get(widgetId);
-        newWidgetMap.set(widgetId, {
-          id: widgetId,
-          widget,
-          data: getPreservedData(oldWidget?.data),
-        });
-        return newWidgetMap;
-      });
-    },
-    []
-  );
-
-  const handleDashboardOpen = useCallback(
-    ({
-      widget,
-      dashboardId,
-    }: {
-      widget: WidgetDescriptor;
-      dashboardId: string;
-    }) => {
-      const { name: title } = widget;
-      log.debug('Emitting create dashboard event for', dashboardId, widget);
-      emitCreateDashboard(layout.eventHub, {
-        pluginId: PLUGIN_NAME,
-        title: title ?? 'Untitled',
-        data: { openWidgets: { [dashboardId]: { descriptor: widget } } },
-      });
-    },
-    [layout.eventHub]
-  );
-
-  const handlePanelOpen = useCallback(
-    ({
-      panelId: widgetId = nanoid(),
-      widget,
-    }: PanelOpenEventDetail<dh.Widget>) => {
-      const { type } = widget;
-
-      switch (type) {
-        case WIDGET_ELEMENT: {
-          handleWidgetOpen({ widgetId, widget });
-          break;
-        }
-        case DASHBOARD_ELEMENT: {
-          handleDashboardOpen({ widget, dashboardId: widgetId });
-          break;
-        }
-        default: {
-          break;
-        }
-      }
-    },
-    [handleDashboardOpen, handleWidgetOpen]
-  );
-
   useEffect(
     function loadInitialPluginData() {
       if (initialPluginData == null) {
@@ -203,8 +140,6 @@ function InnerDashboardPlugin(
     });
   }, []);
 
-  // TODO: We need to change up the event system for how objects are opened, since in this case it could be opening multiple panels
-  useListener(layout.eventHub, PanelEvent.OPEN, handlePanelOpen);
   useListener(layout.eventHub, PanelEvent.CLOSE, handlePanelClose);
 
   const sendPluginDataUpdate = useCallback(
@@ -282,12 +217,18 @@ function InnerDashboardPlugin(
 
   return (
     <LayoutManagerContext.Provider value={layout}>
-      <style>{styles}</style>
       <PortalPanelManager>{widgetHandlers}</PortalPanelManager>
     </LayoutManagerContext.Provider>
   );
 }
 
+/**
+ * Dashboard plugin that registers the PortalPanel type for deephaven.ui
+ *
+ * It's also responsible for handling legacy behaviour, for old dashboards that may have opened a deephaven.ui widget previously.
+ * @param props Dashboard plugin props
+ * @returns Dashboard plugin
+ */
 export function DashboardPlugin(
   props: DashboardPluginComponentProps
 ): JSX.Element | null {

plugins/ui/src/js/src/UIComponent.tsx

@@ -0,0 +1,66 @@
+import React, { useCallback, useMemo } from 'react';
+import { type UriVariableDescriptor } from '@deephaven/jsapi-bootstrap';
+import type { dh } from '@deephaven/jsapi-types';
+import {
+  usePersistentState,
+  type WidgetComponentProps,
+} from '@deephaven/plugin';
+import { nanoid } from 'nanoid';
+import { type WidgetData, type WidgetDataUpdate } from './widget/WidgetTypes';
+import WidgetHandler from './widget/WidgetHandler';
+
+type UIComponentProps = WidgetComponentProps<dh.Widget> & {
+  // Might be loading a URI resolved widget...
+  uri?: UriVariableDescriptor;
+};
+
+export function UIComponent(props: UIComponentProps): JSX.Element | null {
+  const { metadata: widgetDescriptor, uri, __dhId } = props;
+
+  const [widgetData, setWidgetData] = usePersistentState<
+    WidgetData | undefined
+  >(undefined, { type: 'UIComponentWidgetData', version: 1 });
+
+  const id = useMemo(
+    () => __dhId ?? widgetDescriptor?.id ?? nanoid(),
+    [__dhId, widgetDescriptor]
+  );
+
+  const handleDataChange = useCallback(
+    (data: WidgetDataUpdate) => {
+      setWidgetData(oldData => ({ ...oldData, ...data }));
+    },
+    [setWidgetData]
+  );
+
+  const descriptor = uri ?? widgetDescriptor;
+  if (descriptor == null) {
+    throw new Error('No widget descriptor');
+  }
+
+  const renderEmptyDocument = useCallback(
+    () => (
+      // Single-panel or first-time-load case. Returning a fragment causes
+      // `getRootChildren` to wrap it in a `DefaultPanelContent`, which renders
+      // a `LoadingOverlay` while the widget status is `loading`.
+      // eslint-disable-next-line react/jsx-no-useless-fragment
+      <></>
+    ),
+    // We only want to update this callback when the descriptor changes, not
+    // every time the widgetData (panelIds) changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [descriptor]
+  );
+
+  return (
+    <WidgetHandler
+      widgetDescriptor={descriptor}
+      initialData={widgetData}
+      onDataChange={handleDataChange}
+      renderEmptyDocument={renderEmptyDocument}
+      id={id}
+    />
+  );
+}
+
+export default UIComponent;

plugins/ui/src/js/src/UIWidget.tsx

@@ -0,0 +1,19 @@
+import type { dh } from '@deephaven/jsapi-types';
+import { type WidgetComponentProps } from '@deephaven/plugin';
+import UIComponent from './UIComponent';
+import PortalPanel from './layout/PortalPanel';
+
+type UIWidgetProps = WidgetComponentProps<dh.Widget>;
+
+export function UIWidget(props: UIWidgetProps): JSX.Element | null {
+  const { metadata: widgetDescriptor } = props;
+  if (widgetDescriptor?.type === PortalPanel.displayName) {
+    // PortalPanel was used by the legacy DashboardPlugin to render elements. We just ignore them here.
+    return null;
+  }
+
+  // eslint-disable-next-line react/jsx-props-no-spreading
+  return <UIComponent {...props} />;
+}
+
+export default UIWidget;

plugins/ui/src/js/src/UIWidgetPlugin.ts

@@ -0,0 +1,16 @@
+import { type WidgetPlugin, PluginType } from '@deephaven/plugin';
+import { vsGraph } from '@deephaven/icons';
+import type { dh } from '@deephaven/jsapi-types';
+import { DASHBOARD_ELEMENT, WIDGET_ELEMENT } from './widget/WidgetUtils';
+import PortalPanel from './layout/PortalPanel';
+import UIWidget from './UIWidget';
+
+export const UIWidgetPlugin: WidgetPlugin<dh.Widget> = {
+  name: '@deephaven/js-plugin-ui',
+  type: PluginType.WIDGET_PLUGIN,
+  supportedTypes: [WIDGET_ELEMENT, DASHBOARD_ELEMENT, PortalPanel.displayName],
+  component: UIWidget,
+  icon: vsGraph,
+};
+
+export default UIWidgetPlugin;