feat: DH-21476 Configurable TableOptions sidebar (#2688)

Pre-requisite for Pivot Builder.

### Summary:

This PR introduces new extension seams for `@deephaven/iris-grid`
(configurable Table Options sidebar + model transforms) as a
prerequisite for Pivot Builder, and includes related grid/model
robustness improvements (pending-operation scrim signaling, proxy-model
swap handling, header separator behavior, and shared remote-module
re-exports for plugins).

### Changes:

- Add `transformTableOptions` + plugin `configPage` support for the
IrisGrid Table Options sidebar, including ordering, duplicate detection,
and an error boundary for plugin pages.
- Add `transformModel` support so middleware/hosts can wrap or replace
the built `IrisGridModel` (sync/async), plus new model events to support
swap/loading workflows.
Improve grid behavior for pivot-like scenarios (runtime swapping of
renderer/metric calculator, model-changed signaling).

### Testing:
- Middleware chaining can be tested using the example table middleware
plugin - deephaven/deephaven-plugins#1365. The
plugin wraps all table widgets and panels in a context, adds a label
above the grid, and injects additional component props.
- Table Options menu manipulation and model transforms can be tested
using the Pivot Builder plugin -
deephaven/deephaven-plugins#1351.

The plugins have not been released yet, so they have to be served via
Vite proxy in dev mode for testing. Use this branch to test in DHE -
deephaven-ent/iris#4525.

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: vbabich

packages/code-studio/src/styleguide/Grids.tsx

@@ -15,7 +15,9 @@ import QuadrillionExample from './grid-examples/QuadrillionExample';
 import TreeExample from './grid-examples/TreeExample';
 import AsyncExample from './grid-examples/AsyncExample';
 import DataBarExample from './grid-examples/DataBarExample';
+import PluginErrorExample from './grid-examples/PluginErrorExample';
 import SampleSection from './SampleSection';
+import { SAMPLE_SECTION_E2E_IGNORE } from './constants';
 
 function Grids(): ReactElement {
   const dh = useApi();
@@ -84,6 +86,16 @@ function Grids(): ReactElement {
         <SampleSection name="grids-iris-spacious" component={Flex} height={500}>
           <IrisGrid model={irisGridSpaciousModel} density="spacious" />
         </SampleSection>
+        {/* e2e-only: exercises PluginTableOptionsErrorBoundary. Hidden from
+            the section-count snapshot test via SAMPLE_SECTION_E2E_IGNORE. */}
+        <SampleSection
+          name="grids-iris-plugin-error"
+          className={SAMPLE_SECTION_E2E_IGNORE}
+          component={Flex}
+          height={500}
+        >
+          <PluginErrorExample />
+        </SampleSection>
       </ThemeContext.Provider>
     </div>
   );

packages/code-studio/src/styleguide/grid-examples/PluginErrorExample.tsx

@@ -0,0 +1,52 @@
+import React, { type ReactElement, useState } from 'react';
+import { MockTreeGridModel } from '@deephaven/grid';
+import {
+  IrisGrid,
+  type OptionItem,
+  type TableOptionsTransform,
+} from '@deephaven/iris-grid';
+import { useApi } from '@deephaven/jsapi-bootstrap';
+import MockIrisGridTreeModel from '../MockIrisGridTreeModel';
+
+/**
+ * A plugin `configPage` that always throws, used to exercise
+ * `PluginTableOptionsErrorBoundary` from an e2e test.
+ */
+function ThrowingConfigPage(): ReactElement {
+  throw new Error('Intentional configPage error for error boundary test');
+}
+
+/**
+ * Appends a plugin Table Options item whose `configPage` throws on render so
+ * the sidebar error boundary fallback can be snapshotted in e2e tests.
+ */
+const transformTableOptionsWithError: TableOptionsTransform = (
+  defaults: readonly OptionItem[]
+) => [
+  ...defaults,
+  {
+    type: 'plugin:e2e:throwing-page',
+    title: 'Throwing Plugin Page',
+    configPage: ThrowingConfigPage,
+  },
+];
+
+/**
+ * An IrisGrid whose Table Options include a plugin page that throws on render,
+ * used to exercise `PluginTableOptionsErrorBoundary` from an e2e test.
+ */
+function PluginErrorExample(): ReactElement {
+  const dh = useApi();
+  const [model] = useState(
+    () => new MockIrisGridTreeModel(dh, new MockTreeGridModel())
+  );
+  return (
+    <IrisGrid
+      model={model}
+      density="regular"
+      transformTableOptions={transformTableOptionsWithError}
+    />
+  );
+}
+
+export default PluginErrorExample;

packages/dashboard-core-plugins/src/GridWidgetPlugin.test.tsx

@@ -61,3 +61,54 @@ it('mounts without crashing', async () => {
 
   expect(queryByText('MockIrisGrid')).toBeInTheDocument();
 });
+
+it('forwards the transformTableOptions prop to IrisGrid.transformTableOptions', async () => {
+  MockIrisGrid.mockClear();
+  const table = TestUtils.createMockProxy<DhType.Table>({ columns: [] });
+  const fetch = jest.fn(() => Promise.resolve(table));
+  const store = createMockStore();
+  const transformTableOptions = jest.fn(defaults => defaults);
+
+  const { queryByText } = render(
+    <Provider store={store}>
+      <ApiContext.Provider value={dh}>
+        <GridWidgetPlugin
+          fetch={fetch}
+          transformTableOptions={transformTableOptions}
+        />
+      </ApiContext.Provider>
+    </Provider>
+  );
+
+  await waitFor(() => expect(queryByText('MockIrisGrid')).toBeInTheDocument());
+
+  const { calls } = MockIrisGrid.mock;
+  expect(calls.length).toBeGreaterThan(0);
+  const lastProps = calls[calls.length - 1][0];
+  expect(lastProps.transformTableOptions).toBe(transformTableOptions);
+});
+
+it('applies transformModel to the model passed to IrisGrid', async () => {
+  MockIrisGrid.mockClear();
+  const table = TestUtils.createMockProxy<DhType.Table>({ columns: [] });
+  const fetch = jest.fn(() => Promise.resolve(table));
+  const store = createMockStore();
+  const transformedModel = TestUtils.createMockProxy({ columns: [] });
+  const transformModel = jest.fn(() => transformedModel);
+
+  const { queryByText } = render(
+    <Provider store={store}>
+      <ApiContext.Provider value={dh}>
+        <GridWidgetPlugin fetch={fetch} transformModel={transformModel} />
+      </ApiContext.Provider>
+    </Provider>
+  );
+
+  await waitFor(() => expect(queryByText('MockIrisGrid')).toBeInTheDocument());
+
+  expect(transformModel).toHaveBeenCalledTimes(1);
+  const { calls } = MockIrisGrid.mock;
+  expect(calls.length).toBeGreaterThan(0);
+  const lastProps = calls[calls.length - 1][0];
+  expect(lastProps.model).toBe(transformedModel);
+});

packages/dashboard-core-plugins/src/GridWidgetPlugin.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { type WidgetComponentProps } from '@deephaven/plugin';
 import { type dh as DhType } from '@deephaven/jsapi-types';
 import {
@@ -8,8 +8,12 @@ import {
   IrisGridCacheUtils,
   type IrisGridState,
   type IrisGridType,
+  type IrisGridViewProps,
   IrisGridUtils,
   isIrisGridTableModelTemplate,
+  type IrisGridModel,
+  type IrisGridTableOptionsWidgetProps,
+  type IrisGridModelWidgetProps,
 } from '@deephaven/iris-grid';
 import { useSelector } from 'react-redux';
 import { getSettings, type RootState } from '@deephaven/redux';
@@ -28,16 +32,46 @@ import { InputFilterEvent } from './events';
 import useGridLinker from './useGridLinker';
 import { useTablePlugin } from './useTablePlugin';
 
+/**
+ * Props that can only be supplied by IrisGrid-aware middleware wrapping
+ * `GridWidgetPlugin` (regular plugins receive only `WidgetComponentProps`).
+ * Grouped together so the middleware-only surface is explicit; the component
+ * depends on `Partial` of this so each prop stays optional.
+ */
+export type GridWidgetPluginMiddlewareProps = IrisGridTableOptionsWidgetProps &
+  IrisGridModelWidgetProps & {
+    /**
+     * View-concern overrides (theme, renderer, mouse handlers, metric
+     * calculator) forwarded as a single bag to `<IrisGrid>`. Lets a plugin
+     * contribute presentation without this host knowing each concern by name.
+     */
+    irisGridProps?: Partial<IrisGridViewProps>;
+    /** Called once the model is built, so middleware can observe it. */
+    onModelChanged?: (model: IrisGridModel) => void;
+  };
+
 export function GridWidgetPlugin({
   fetch,
-}: WidgetComponentProps<DhType.Table>): JSX.Element | null {
+  transformTableOptions,
+  transformModel,
+  irisGridProps,
+  onModelChanged,
+}: WidgetComponentProps<DhType.Table> &
+  Partial<GridWidgetPluginMiddlewareProps>): JSX.Element | null {
   const settings = useSelector(getSettings<RootState>);
   const { eventHub } = useLayoutManager();
 
-  const fetchResult = useIrisGridModel(fetch);
+  const fetchResult = useIrisGridModel(fetch, transformModel);
   const model =
     fetchResult.status === 'success' ? fetchResult.model : undefined;
 
+  // Notify observers (e.g. middleware) when the built model changes.
+  useEffect(() => {
+    if (model != null) {
+      onModelChanged?.(model);
+    }
+  }, [model, onModelChanged]);
+
   const dh = useApi();
   const irisGridUtils = useMemo(() => new IrisGridUtils(dh), [dh]);
 
@@ -171,6 +205,9 @@ export function GridWidgetPlugin({
       onContextMenu={onContextMenu}
       inputFilters={inputFilters}
       customFilters={customFilters}
+      transformTableOptions={transformTableOptions}
+      // eslint-disable-next-line react/jsx-props-no-spreading
+      {...irisGridProps}
       // eslint-disable-next-line react/jsx-props-no-spreading
       {...linkerProps}
       alwaysFetchColumns={alwaysFetchColumns}

packages/dashboard-core-plugins/src/panels/IrisGridPanel.test.tsx

@@ -60,9 +60,13 @@ function makeIrisGridPanelWrapper(
   user = TestUtils.REGULAR_USER,
   client = new (dh as any).Client(),
   workspace = {},
-  settings = { timeZone: 'America/New_York' }
+  settings = { timeZone: 'America/New_York' },
+  transformTableOptions:
+    | ((defaults: readonly any[]) => readonly any[])
+    | undefined = undefined,
+  transformModel: ((model: any) => any) | undefined = undefined
 ) {
-  return render(
+  const panel = (
     <IrisGridPanel
       makeModel={makeModel}
       metadata={metadata}
@@ -76,9 +80,11 @@ function makeIrisGridPanelWrapper(
       panelState={undefined}
       getDownloadWorker={() => undefined}
       loadPlugin={() => undefined}
-      theme={undefined}
+      transformTableOptions={transformTableOptions}
+      transformModel={transformModel}
     />
   );
+  return render(panel);
 }
 
 async function expectLoading(container) {
@@ -153,3 +159,88 @@ it('shows an error properly if table loading fails', async () => {
   );
   expect(msg).toBeTruthy();
 });
+
+it('forwards the transformTableOptions prop to IrisGrid.transformTableOptions', async () => {
+  MockIrisGrid.mockClear();
+  const transformTableOptions = jest.fn(defaults => defaults);
+  await act(() =>
+    makeIrisGridPanelWrapper(
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      transformTableOptions
+    )
+  );
+  const { calls } = MockIrisGrid.mock;
+  expect(calls.length).toBeGreaterThan(0);
+  const lastProps = calls[calls.length - 1][0];
+  expect(lastProps.transformTableOptions).toBe(transformTableOptions);
+});
+
+it('passes undefined transformTableOptions when the prop is omitted', async () => {
+  MockIrisGrid.mockClear();
+  await act(() => makeIrisGridPanelWrapper());
+  const { calls } = MockIrisGrid.mock;
+  expect(calls.length).toBeGreaterThan(0);
+  const lastProps = calls[calls.length - 1][0];
+  expect(lastProps.transformTableOptions).toBeUndefined();
+});
+
+it('applies transformModel to the built model before passing it to IrisGrid', async () => {
+  MockIrisGrid.mockClear();
+  const transformedModel = await makeMakeModel()();
+  const transformModel = jest.fn(() => transformedModel);
+  await act(() =>
+    makeIrisGridPanelWrapper(
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      transformModel
+    )
+  );
+  expect(transformModel).toHaveBeenCalledTimes(1);
+  const { calls } = MockIrisGrid.mock;
+  expect(calls.length).toBeGreaterThan(0);
+  const lastProps = calls[calls.length - 1][0];
+  expect(lastProps.model).toBe(transformedModel);
+});
+
+it('closes the base model if transformModel rejects', async () => {
+  MockIrisGrid.mockClear();
+  const baseModel = TestUtils.createMockProxy<any>({ close: jest.fn() });
+  const makeModel = jest.fn(() => Promise.resolve(baseModel));
+  const error = new Error('Transform failed');
+  const transformModel = jest.fn(() => Promise.reject(error));
+  const { container } = makeIrisGridPanelWrapper(
+    makeModel,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    transformModel
+  );
+  await expectNotLoading(container);
+  expect(transformModel).toHaveBeenCalledTimes(1);
+  expect(baseModel.close).toHaveBeenCalledTimes(1);
+});