@deephaven/iris-grid 1.22.1 → 1.22.2-alpha-pivot-builder.0730ba6.0

package/README.md

@@ -20,4 +20,299 @@ const model = await IrisGridModelFactory.makeModel(dh, table);
 
 // In your render function
 <IrisGrid dh={dh} model={model} />
-```
+```
+
+## Customizing the Table Options menu
+
+The Table Options sidebar (the gear menu on the right edge of the grid) is
+extensible. Plugin authors can hide built-in items, relabel or reorder
+them, and add their own items that open a custom configuration page —
+without forking `IrisGrid`.
+
+There is a single entry point: the `transformTableOptions` prop on
+`<IrisGrid>`. It is **opt-in** — it lives on the iris-grid-specific
+`IrisGridTableOptionsWidgetProps`, not on the generic
+`WidgetComponentProps` / `WidgetPanelProps`, so widgets that don't care
+about the Table Options menu never see it.
+
+- **Own the render site?** Pass `transformTableOptions` straight to
+  `<IrisGrid>`.
+- **A `WidgetMiddlewarePlugin` that doesn't render `<IrisGrid>`
+  yourself?** Thread the prop down the middleware chain via the
+  `Component` you wrap, composing your own transform on top of the one
+  you received (see [Publishing from middleware](#publishing-from-middleware)).
+  The panel hosts that ship with Deephaven (`IrisGridPanel`,
+  `GridWidgetPlugin`) accept `transformTableOptions` as a prop and
+  forward it to `<IrisGrid>`.
+
+### Writing a transform
+
+`transformTableOptions(defaults)` is a pure function that receives the
+built-in items (already filtered by what the current model supports) and
+returns the items to actually render. Use it to add, hide, relabel,
+reorder, or replace entries.
+
+```tsx
+import { OptionType, type OptionItem } from '@deephaven/iris-grid';
+
+const transformTableOptions = (defaults: readonly OptionItem[]) => [
+  // hide a built-in
+  ...defaults.filter(o => o.type !== OptionType.SELECT_DISTINCT),
+  // add a plugin item with its own page
+  {
+    type: 'plugin:my-plugin:column-inspector',
+    title: 'Column Inspector',
+    configPage: ColumnInspectorPage,
+  },
+];
+```
+
+Rules:
+
+- The transform should be referentially stable and side-effect-free
+  (it's called inside memoization). Memoize it with `useMemo` /
+  `useCallback` rather than rebuilding per render.
+- A throwing transform is logged once and treated as identity for that
+  render, so the menu degrades gracefully.
+- Items **without** a `configPage` MUST have a `type` matching an
+  existing `OptionType` enum value — those are rendered by the built-in
+  page switch.
+- Items **with** a `configPage` SHOULD use a namespaced key,
+  conventionally `plugin:<name>:<id>`, to avoid colliding with built-ins
+  or other plugins.
+
+### Implementing a `configPage`
+
+A `configPage` is a regular React component that receives
+`IrisGridTableOptionsPageProps`:
+
+```tsx
+import { type IrisGridTableOptionsPageProps } from '@deephaven/iris-grid';
+
+export function ColumnInspectorPage({
+  model,
+  viewState,
+  onBack,
+}: IrisGridTableOptionsPageProps): JSX.Element {
+  const hidden = new Set(viewState.hiddenColumns);
+  return (
+    <div>
+      <button type="button" onClick={onBack}>Back</button>
+      <pre>
+        {model.columns
+          .filter(c => !hidden.has(c.name))
+          .map(c => c.name)
+          .join('\n')}
+      </pre>
+    </div>
+  );
+}
+```
+
+`IrisGrid` wraps each `configPage` render in `PluginTableOptionsErrorBoundary`,
+so a throw inside your page shows a small inline fallback instead of
+unmounting the whole grid.
+
+The `viewState` prop is an `IrisGridViewState` — a curated, read-only snapshot
+of the grid's current view configuration (e.g. `viewState.hiddenColumns`). It's
+a small, stable subset of the grid's internal state; new fields are added
+additively as plugins need them.
+
+### Publishing from middleware
+
+When you're a `WidgetMiddlewarePlugin` and don't render `<IrisGrid>`
+yourself, you receive `transformTableOptions` as a prop and pass a
+composed transform down to the `Component` (or panel) you wrap. Run the
+upstream transform first so contributions compose, then layer your own
+changes on top.
+
+A `panelComponent` middleware should be built with `createPanelMiddleware`
+from `@deephaven/plugin`: you supply a body hook that may `inject` props onto
+the wrapped component and/or `wrap` the child in a wrapper element (both
+optional), and the factory owns the `React.forwardRef` ceremony and ref
+forwarding for you. That ref matters —
+golden-layout binds a ref to the registered panel to persist class-panel
+state (sorts, filters, column moves, etc.) into its `componentState`, and a
+middleware that swallowed it would silently break that persistence for every
+panel below it; the factory guarantees it can't be dropped. For the non-panel
+`component` path use `createWidgetMiddleware`, which is otherwise identical but
+takes no ref.
+
+```tsx
+import { useMemo } from 'react';
+import { createPanelMiddleware, type WidgetPanelProps } from '@deephaven/plugin';
+import {
+  type IrisGridTableOptionsWidgetProps,
+  type TableOptionsTransform,
+} from '@deephaven/iris-grid';
+
+function makeMyTransform(
+  upstream: TableOptionsTransform | undefined
+): TableOptionsTransform {
+  return defaults => {
+    const base = upstream != null ? upstream(defaults) : defaults;
+    return [...base, myPluginItem];
+  };
+}
+
+const MyMiddleware = createPanelMiddleware<
+  unknown,
+  WidgetPanelProps & IrisGridTableOptionsWidgetProps
+>(({ transformTableOptions }) => {
+  const composedTransform = useMemo(
+    () => makeMyTransform(transformTableOptions),
+    [transformTableOptions]
+  );
+  return { inject: { transformTableOptions: composedTransform } };
+}, 'MyMiddleware');
+```
+
+The body hook receives the incoming props (minus `Component`) and returns an
+optional `{ inject?, wrap? }`. Every incoming prop is forwarded to the wrapped
+component automatically; `inject` only adds or overrides the few props you
+actually change (here `transformTableOptions`), and `wrap` optionally nests the
+child (e.g. in a context provider). Both fields are optional — a pass-through
+middleware can return `{}`. The factory adds the `ref` plumbing on top.
+
+
+Composition rule: each middleware layer reads the `transformTableOptions`
+it was handed, runs that transform first, then layers its own changes on
+top — last writer wins for any given `OptionItem.type`.
+
+#### Model-aware menus
+
+The transform must stay **pure** — it only sees `defaults`, never the
+`IrisGridModel`. To make a menu react to model state (e.g. relabel an
+item once a pivot is active), take a **snapshot of the value you care
+about** from model events and fold it into the transform's identity:
+
+```tsx
+const [isPivot, setIsPivot] = useState(model.isPivot);
+useEffect(() => {
+  const handler = () => setIsPivot(model.isPivot);
+  model.addEventListener(SOME_MODEL_EVENT, handler);
+  return () => model.removeEventListener(SOME_MODEL_EVENT, handler);
+}, [model]);
+
+const composedTransform = useMemo(
+  () => makeMyTransform(transformTableOptions, isPivot),
+  [transformTableOptions, isPivot]
+);
+```
+
+Because `composedTransform`'s identity changes when the snapshot
+changes, `IrisGrid` re-runs it (its menu cache is keyed on
+`[defaults, transform]`). Keeping the snapshot in the dependency array —
+rather than reading `model.isPivot` inside the transform — is what keeps
+that memoization honest.
+
+To obtain the model when the host builds it for you, pass an
+`onModelChanged` callback to `IrisGridPanel` (called once the panel's
+model is ready).
+
+### Full example
+
+See the [`@deephaven/js-plugin-pivot-builder`](https://github.com/deephaven/deephaven-plugins/tree/main/plugins/pivot-builder)
+plugin for a working `WidgetMiddlewarePlugin` that replaces the default
+widget renderer and adds a `configPage`-backed "Rollup, Aggregate and Pivot"
+item to the Table Options sidebar.
+
+### Why the transform doesn't take the model
+
+The transform signature is `(defaults) => items` — it deliberately does
+**not** receive the `IrisGridModel` or grid state. State-aware menus
+(e.g. "relabel an item once a pivot is active", "show *Reset filters*
+only when filters exist") are implemented in the middleware: subscribe
+to model events, snapshot the value you need, and fold that snapshot
+into the transform's identity (see
+[Model-aware menus](#model-aware-menus)). The transform itself stays
+pure.
+
+This isn't just about keeping the public surface small — it's also
+what keeps menu memoization honest. `IrisGrid` caches the computed
+item list on `[defaults, transform]` (see `getCachedTransformedOptionItems`),
+both of which are stable values/refs. Adding a live `model` argument
+would break that: `IrisGridModel` is a long-lived mutable handle whose
+identity does not change when `isExpandable`, `filter`, `sorts`, or
+`isRollup` flip, so any plugin that read those fields would silently
+return stale items until something unrelated invalidated the cache.
+
+By passing a **curated snapshot of values** through the transform's
+closure instead, the memo key changes exactly when those values change
+and re-runs are driven by actual dependencies. Passing the model itself,
+or the full `IrisGrid` instance, is intentionally off the table: the
+surface is too large, too volatile, and (in the model's case)
+memoization-hostile.
+
+## Transforming the model
+
+Some plugins need more than a custom menu — they need to change the
+**model** the grid renders (e.g. wrap it in a proxy that can swap its
+inner model in response to a config page). For that there is a second,
+symmetric opt-in seam: the `transformModel` prop.
+
+Like `transformTableOptions`, it lives on an iris-grid-specific
+interface (`IrisGridModelWidgetProps`), not on the generic
+`WidgetComponentProps` / `WidgetPanelProps`, and is threaded down the
+middleware chain by the hosts that build the model for you
+(`IrisGridPanel`, `GridWidgetPlugin` / `useIrisGridModel`).
+
+```ts
+import { type IrisGridModelTransform } from '@deephaven/iris-grid';
+
+// (model: IrisGridModel) => IrisGridModel | Promise<IrisGridModel>
+const transformModel: IrisGridModelTransform = model =>
+  wrapInMyProxy(model);
+```
+
+The host builds the model from `fetch` as usual, then applies
+`transformModel` to whatever it built **before** handing it to
+`<IrisGrid>`. The returned model must be a drop-in for the input — the
+host owns its lifecycle and will `close()` whatever you return, so wrap
+rather than discard the model you were given. The transform may be async
+if it needs to await dependencies first.
+
+Rules:
+
+- `transformModel` must be **referentially stable**. It is applied when
+  the model is (re)built; an unstable transform would rebuild the model.
+  Memoize it with `useMemo` / `useCallback`.
+- It runs once per model build, not per render, so it is the right place
+  for one-time wrapping — not for per-render state.
+- This is why model construction stays in the host: the host keeps
+  ownership of `fetch`, error/loading state, and `close()`, while the
+  plugin only augments the result. A middleware using `transformModel`
+  can therefore render the wrapped `Component` and stay a **chained**
+  layer instead of taking over model construction and becoming terminal.
+
+### Publishing `transformModel` from middleware
+
+A middleware that needs both seams composes them the same way — run any
+upstream transform first, then layer your own — and returns both from its
+body hook's `inject`. Props you don't touch (here `transformTableOptions`)
+are forwarded automatically, so you only inject what you change:
+
+```tsx
+import { useMemo } from 'react';
+import { createPanelMiddleware, type WidgetPanelProps } from '@deephaven/plugin';
+import {
+  type IrisGridModelTransform,
+  type IrisGridModelWidgetProps,
+  type IrisGridTableOptionsWidgetProps,
+} from '@deephaven/iris-grid';
+
+const MyMiddleware = createPanelMiddleware<
+  unknown,
+  WidgetPanelProps & IrisGridModelWidgetProps & IrisGridTableOptionsWidgetProps
+>(({ transformModel }) => {
+  const composedModel = useMemo<IrisGridModelTransform>(
+    () => async model => {
+      const base = transformModel != null ? await transformModel(model) : model;
+      return wrapInMyProxy(base);
+    },
+    [transformModel]
+  );
+  return { inject: { transformModel: composedModel } };
+}, 'MyMiddleware');
+```
+

package/dist/AdvancedFilterCreator.js

@@ -48,23 +48,17 @@ class AdvancedFilterCreator extends PureComponent {
     this.handleFocusTrapEnd = this.handleFocusTrapEnd.bind(this);
     this.handleUpdateTimeout = this.handleUpdateTimeout.bind(this);
     this.focusTrapContainer = /*#__PURE__*/React.createRef();
-    var {
-      model,
-      column,
-      options
-    } = props;
-    var {
-      filterOperators,
-      invertSelection,
-      selectedValues
-    } = options;
+    var model = props.model,
+      column = props.column,
+      options = props.options;
+    var filterOperators = options.filterOperators,
+      invertSelection = options.invertSelection,
+      selectedValues = options.selectedValues;
 
     // can be null or an empty array
     var filterItems = (_options$filterItems$ = (_options$filterItems = options.filterItems) === null || _options$filterItems === void 0 ? void 0 : _options$filterItems.map(_ref => {
-      var {
-        selectedType,
-        value
-      } = _ref;
+      var selectedType = _ref.selectedType,
+        value = _ref.value;
       return {
         selectedType,
         value,
@@ -117,10 +111,9 @@ class AdvancedFilterCreator extends PureComponent {
     return this.handleFilterDelete.bind(this, index);
   }
   initValuesTable() {
-    var {
-      model,
-      column
-    } = this.props;
+    var _this$props = this.props,
+      model = _this$props.model,
+      column = _this$props.column;
     if (!model.isValuesTableAvailable) {
       log.debug('No values table for this model, just ignore');
       return;
@@ -158,10 +151,9 @@ class AdvancedFilterCreator extends PureComponent {
     }
   }
   handleAddAnd() {
-    var {
-      filterItems,
-      filterOperators
-    } = this.state;
+    var _this$state = this.state,
+      filterItems = _this$state.filterItems,
+      filterOperators = _this$state.filterOperators;
     filterItems = filterItems.concat(AdvancedFilterCreator.makeFilterItem());
     filterOperators = filterOperators.concat(FilterOperator.and);
     this.setState({
@@ -170,10 +162,9 @@ class AdvancedFilterCreator extends PureComponent {
     });
   }
   handleAddOr() {
-    var {
-      filterItems,
-      filterOperators
-    } = this.state;
+    var _this$state2 = this.state,
+      filterItems = _this$state2.filterItems,
+      filterOperators = _this$state2.filterOperators;
     filterItems = filterItems.concat(AdvancedFilterCreator.makeFilterItem());
     filterOperators = filterOperators.concat(FilterOperator.or);
     this.setState({
@@ -182,9 +173,7 @@ class AdvancedFilterCreator extends PureComponent {
     });
   }
   handleChangeFilterOperator(index, operator) {
-    var {
-      filterOperators
-    } = this.state;
+    var filterOperators = this.state.filterOperators;
     filterOperators = [...filterOperators];
     assertFilterOperatorValue(operator);
     filterOperators[index] = operator;
@@ -194,13 +183,9 @@ class AdvancedFilterCreator extends PureComponent {
     this.startUpdateTimer();
   }
   handleFilterChange(filterIndex, selectedType, value) {
-    var {
-      filterItems
-    } = this.state;
+    var filterItems = this.state.filterItems;
     filterItems = [...filterItems];
-    var {
-      key
-    } = filterItems[filterIndex];
+    var key = filterItems[filterIndex].key;
     filterItems[filterIndex] = {
       key,
       selectedType,
@@ -212,10 +197,9 @@ class AdvancedFilterCreator extends PureComponent {
     this.startUpdateTimer();
   }
   handleFilterDelete(filterIndex) {
-    var {
-      filterItems,
-      filterOperators
-    } = this.state;
+    var _this$state3 = this.state,
+      filterItems = _this$state3.filterItems,
+      filterOperators = _this$state3.filterOperators;
     filterItems = [...filterItems];
     filterOperators = [...filterOperators];
     if (filterIndex < filterItems.length) {
@@ -271,9 +255,7 @@ class AdvancedFilterCreator extends PureComponent {
     log.debug('Submitting and Closing Advanced Filter');
     this.stopUpdateTimer();
     this.sendUpdate();
-    var {
-      onDone
-    } = this.props;
+    var onDone = this.props.onDone;
     onDone();
     event.preventDefault();
   }
@@ -288,17 +270,13 @@ class AdvancedFilterCreator extends PureComponent {
    * @returns true If the add filter buttons should be shown, false otherwise
    */
   shouldShowAddFilter() {
-    var {
-      filterItems
-    } = this.state;
+    var filterItems = this.state.filterItems;
     if (filterItems.length === 0) {
       return false;
     }
     var filterItem = filterItems[filterItems.length - 1];
-    var {
-      selectedType,
-      value
-    } = filterItem;
+    var selectedType = filterItem.selectedType,
+      value = filterItem.value;
     return selectedType != null && selectedType.length > 0 && value != null && value.length > 0;
   }
 
@@ -309,13 +287,10 @@ class AdvancedFilterCreator extends PureComponent {
    */
   sortTable(direction) {
     var addToExisting = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
-    var {
-      column,
-      onSortChange
-    } = this.props;
-    var {
-      isSortable
-    } = this.state;
+    var _this$props2 = this.props,
+      column = _this$props2.column,
+      onSortChange = _this$props2.onSortChange;
+    var isSortable = this.state.isSortable;
     if (isSortable) {
       onSortChange(column, direction, addToExisting);
     }
@@ -331,26 +306,20 @@ class AdvancedFilterCreator extends PureComponent {
     }
   }
   sendUpdate() {
-    var {
-      filterItems,
-      filterOperators,
-      invertSelection,
-      selectedValues
-    } = this.state;
-    var {
-      column,
-      onFilterChange,
-      model,
-      tableUtils
-    } = this.props;
-    var {
-      formatter
-    } = model;
+    var _this$state4 = this.state,
+      filterItems = _this$state4.filterItems,
+      filterOperators = _this$state4.filterOperators,
+      invertSelection = _this$state4.invertSelection,
+      selectedValues = _this$state4.selectedValues;
+    var _this$props3 = this.props,
+      column = _this$props3.column,
+      onFilterChange = _this$props3.onFilterChange,
+      model = _this$props3.model,
+      tableUtils = _this$props3.tableUtils;
+    var formatter = model.formatter;
     var items = filterItems.filter(_ref2 => {
-      var {
-        selectedType,
-        value
-      } = _ref2;
+      var selectedType = _ref2.selectedType,
+        value = _ref2.value;
       return selectedType != null && value != null && value !== '';
     });
     var operators = filterOperators.filter((operator, i) => operator != null && filterItems[i].selectedType != null && filterItems[i].value != null && filterItems[i].value !== '').slice(0, items.length - 1);
@@ -367,28 +336,24 @@ class AdvancedFilterCreator extends PureComponent {
   }
   render() {
     var _this = this;
-    var {
-      column,
-      model,
-      sortDirection,
-      formatter,
-      tableUtils,
-      isMaximized,
-      onToggleMaximize
-    } = this.props;
-    var {
-      filterItems,
-      filterOperators,
-      invertSelection,
-      selectedValues,
-      valuesTable,
-      valuesTableError,
-      isSortable
-    } = this.state;
-    var {
-      dh,
-      isValuesTableAvailable
-    } = model;
+    var _this$props4 = this.props,
+      column = _this$props4.column,
+      model = _this$props4.model,
+      sortDirection = _this$props4.sortDirection,
+      formatter = _this$props4.formatter,
+      tableUtils = _this$props4.tableUtils,
+      isMaximized = _this$props4.isMaximized,
+      onToggleMaximize = _this$props4.onToggleMaximize;
+    var _this$state5 = this.state,
+      filterItems = _this$state5.filterItems,
+      filterOperators = _this$state5.filterOperators,
+      invertSelection = _this$state5.invertSelection,
+      selectedValues = _this$state5.selectedValues,
+      valuesTable = _this$state5.valuesTable,
+      valuesTableError = _this$state5.valuesTableError,
+      isSortable = _this$state5.isSortable;
+    var dh = model.dh,
+      isValuesTableAvailable = model.isValuesTableAvailable;
     var isBoolean = TableUtils.isBooleanType(column.type);
     var isDateType = TableUtils.isDateType(column.type);
     var filterTypes = this.getFilterTypes(column.type);
@@ -397,11 +362,9 @@ class AdvancedFilterCreator extends PureComponent {
     if (!isBoolean && filterTypes.length) {
       var _loop = function _loop(i) {
         var filterItem = filterItems[i];
-        var {
-          key,
-          selectedType,
-          value
-        } = filterItem;
+        var key = filterItem.key,
+          selectedType = filterItem.selectedType,
+          value = filterItem.value;
         var element = /*#__PURE__*/_jsx(AdvancedFilterCreatorFilterItem, {
           column: column,
           filterTypes: filterTypes,