feat: ComboBox - @deephaven/jsapi-components (#2077)

Jsapi support for ComboBox. Includes some splitting out of existing
Picker logic to make code re-usable.

Should be testable with plugins PR
deephaven/deephaven-plugins#588
I have also deployed an alpha
[0.83.1-alpha-combobox.8](https://www.npmjs.com/package/@deephaven/components/v/0.83.1-alpha-combobox.8)
if you need it, although should only matter for types I think.

```python
from deephaven import empty_table, ui, time_table
import datetime


# Change this to test different data types
key_column="Timestamp"


initial_row_count=5 * 8760 # 5 years in hours

# Tick every 6 hours (makes it easier to test Timestamp filters for a whole day like `2024-01-02`)
_items = time_table("PT6H", start_time=datetime.datetime.now() - datetime.timedelta(hours=initial_row_count)).update([
    # Timestamp column also implicitly included in `time_table`
    "Int=new Integer(i)",
    "Long=new Long(i)",
    "BigInt=new java.math.BigInteger(``+i)",
    "String=new String(`a`+i * 1000)",
])


@ui.component
def ui_combo_box(items):
    value, set_value = ui.use_state("")

    combo = ui.combo_box(
        ui.item_table_source(
            items,
            key_column=key_column,
            label_column=key_column,
        ),
        label=key_column,
        on_selection_change=set_value,
        menu_trigger="focus",
        selected_key=value,
    )

    # Show current selection in a ui.text component
    text = ui.text("Selection: " + str(value))

    return combo, text


my_combo_box = ui_combo_box(_items)
```

There is a known issue with inconsistent open as you type for table data
sources.
#2115

resolves #2074

packages/components/src/spectrum/collections.ts

@@ -1,10 +1,16 @@
 export {
   ActionBar,
   type SpectrumActionBarProps as ActionBarProps,
+  // ComboBox is exported from ComboBox.tsx as a custom DH component. Re-exporting
+  // the Spectrum props type for upstream consumers that need to compose prop types.
+  type SpectrumComboBoxProps,
   // ListBox - we aren't planning to support this component
   MenuTrigger,
   type SpectrumMenuTriggerProps as MenuTriggerProps,
   // TableView - we aren't planning to support this component
+  // Picker is exported from Picker.tsx as a custom DH component. Re-exporting
+  // the Spectrum props type for upstream consumers that need to compose prop types.
+  type SpectrumPickerProps,
   TagGroup,
   type SpectrumTagGroupProps as TagGroupProps,
 } from '@adobe/react-spectrum';

packages/jsapi-components/src/spectrum/ComboBox.tsx

@@ -0,0 +1,38 @@
+import {
+  ComboBoxNormalized,
+  NormalizedItem,
+  SpectrumComboBoxProps,
+} from '@deephaven/components';
+import { useCallback } from 'react';
+import { PickerWithTableProps } from './PickerProps';
+import { usePickerProps } from './utils';
+
+export type ComboBoxProps = PickerWithTableProps<
+  SpectrumComboBoxProps<NormalizedItem>
+>;
+
+export function ComboBox(props: ComboBoxProps): JSX.Element {
+  const {
+    onInputChange: onInputChangeInternal,
+    onSearchTextChange,
+    ...pickerProps
+  } = usePickerProps<ComboBoxProps>(props);
+
+  const onInputChange = useCallback(
+    (value: string) => {
+      onInputChangeInternal?.(value);
+      onSearchTextChange(value);
+    },
+    [onInputChangeInternal, onSearchTextChange]
+  );
+
+  return (
+    <ComboBoxNormalized
+      // eslint-disable-next-line react/jsx-props-no-spreading
+      {...pickerProps}
+      onInputChange={onInputChange}
+    />
+  );
+}
+
+export default ComboBox;

packages/jsapi-components/src/spectrum/Picker.tsx

@@ -1,152 +1,14 @@
-import { useCallback, useEffect, useMemo, useState } from 'react';
-import {
-  ItemKey,
-  NormalizedItem,
-  NormalizedItemData,
-  NormalizedSection,
-  NormalizedSectionData,
-  PickerNormalized,
-  PickerProps as PickerBaseProps,
-  useSpectrumThemeProvider,
-} from '@deephaven/components';
-import { dh as DhType } from '@deephaven/jsapi-types';
-import { Settings } from '@deephaven/jsapi-utils';
-import Log from '@deephaven/log';
-import { PICKER_ITEM_HEIGHTS, PICKER_TOP_OFFSET } from '@deephaven/utils';
-import useFormatter from '../useFormatter';
-import useGetItemIndexByValue from '../useGetItemIndexByValue';
-import { useViewportData } from '../useViewportData';
-import { getItemKeyColumn } from './utils/itemUtils';
-import { useItemRowDeserializer } from './utils/useItemRowDeserializer';
+import { PickerNormalized } from '@deephaven/components';
+import { PickerProps } from './PickerProps';
+import { usePickerProps } from './utils';
 
-const log = Log.module('jsapi-components.Picker');
-
-export interface PickerProps extends Omit<PickerBaseProps, 'children'> {
-  table: DhType.Table;
-  /* The column of values to use as item keys. Defaults to the first column. */
-  keyColumn?: string;
-  /* The column of values to display as primary text. Defaults to the `keyColumn` value. */
-  labelColumn?: string;
-
-  /* The column of values to map to icons. */
-  iconColumn?: string;
-
-  settings?: Settings;
-}
-
-export function Picker({
-  table,
-  keyColumn: keyColumnName,
-  labelColumn: labelColumnName,
-  iconColumn: iconColumnName,
-  settings,
-  onChange,
-  onSelectionChange,
-  ...props
-}: PickerProps): JSX.Element {
-  const { scale } = useSpectrumThemeProvider();
-  const itemHeight = PICKER_ITEM_HEIGHTS[scale];
-
-  const { getFormattedString: formatValue } = useFormatter(settings);
-
-  // `null` is a valid value for `selectedKey` in controlled mode, so we check
-  // for explicit `undefined` to identify uncontrolled mode.
-  const isUncontrolled = props.selectedKey === undefined;
-  const [uncontrolledSelectedKey, setUncontrolledSelectedKey] = useState<
-    ItemKey | null | undefined
-  >(props.defaultSelectedKey);
-
-  const keyColumn = useMemo(
-    () => getItemKeyColumn(table, keyColumnName),
-    [keyColumnName, table]
-  );
-
-  const deserializeRow = useItemRowDeserializer({
-    table,
-    iconColumnName,
-    keyColumnName,
-    labelColumnName,
-    formatValue,
-  });
-
-  const getItemIndexByValue = useGetItemIndexByValue({
-    table,
-    columnName: keyColumn.name,
-    value: isUncontrolled ? uncontrolledSelectedKey : props.selectedKey,
-  });
-
-  const getInitialScrollPosition = useCallback(async () => {
-    const index = await getItemIndexByValue();
-
-    if (index == null) {
-      return null;
-    }
-
-    return index * itemHeight + PICKER_TOP_OFFSET;
-  }, [getItemIndexByValue, itemHeight]);
-
-  const { viewportData, onScroll, setViewport } = useViewportData<
-    NormalizedItemData | NormalizedSectionData,
-    DhType.Table
-  >({
-    reuseItemsOnTableResize: true,
-    table,
-    itemHeight,
-    deserializeRow,
-  });
-
-  const normalizedItems = viewportData.items as (
-    | NormalizedItem
-    | NormalizedSection
-  )[];
-
-  useEffect(
-    // Set viewport to include the selected item so that its data will load and
-    // the real `key` will be available to show the selection in the UI.
-    function setViewportFromSelectedKey() {
-      let isCanceled = false;
-
-      getItemIndexByValue()
-        .then(index => {
-          if (index == null || isCanceled) {
-            return;
-          }
-
-          setViewport(index);
-        })
-        .catch(err => {
-          log.error('Error setting viewport from selected key', err);
-        });
-
-      return () => {
-        isCanceled = true;
-      };
-    },
-    [getItemIndexByValue, settings, setViewport]
-  );
-
-  const onSelectionChangeInternal = useCallback(
-    (key: ItemKey | null): void => {
-      // If our component is uncontrolled, track the selected key internally
-      // so that we can scroll to the selected item if the user re-opens
-      if (isUncontrolled) {
-        setUncontrolledSelectedKey(key);
-      }
-
-      (onChange ?? onSelectionChange)?.(key);
-    },
-    [isUncontrolled, onChange, onSelectionChange]
-  );
+export function Picker(props: PickerProps): JSX.Element {
+  const pickerProps = usePickerProps<PickerProps>(props);
 
   return (
     <PickerNormalized
       // eslint-disable-next-line react/jsx-props-no-spreading
-      {...props}
-      normalizedItems={normalizedItems}
-      showItemIcons={iconColumnName != null}
-      getInitialScrollPosition={getInitialScrollPosition}
-      onChange={onSelectionChangeInternal}
-      onScroll={onScroll}
+      {...pickerProps}
     />
   );
 }

packages/jsapi-components/src/spectrum/PickerProps.ts

@@ -0,0 +1,27 @@
+import {
+  NormalizedItem,
+  PickerPropsT,
+  SpectrumPickerProps,
+} from '@deephaven/components';
+import { dh as DhType } from '@deephaven/jsapi-types';
+import { Settings } from '@deephaven/jsapi-utils';
+
+export type PickerWithTableProps<TProps> = Omit<
+  PickerPropsT<TProps>,
+  'children'
+> & {
+  table: DhType.Table;
+  /* The column of values to use as item keys. Defaults to the first column. */
+  keyColumn?: string;
+  /* The column of values to display as primary text. Defaults to the `keyColumn` value. */
+  labelColumn?: string;
+
+  /* The column of values to map to icons. */
+  iconColumn?: string;
+
+  settings?: Settings;
+};
+
+export type PickerProps = PickerWithTableProps<
+  SpectrumPickerProps<NormalizedItem>
+>;

packages/jsapi-components/src/spectrum/index.ts

@@ -1,2 +1,4 @@
+export * from './ComboBox';
 export * from './ListView';
 export * from './Picker';
+export * from './PickerProps';

packages/jsapi-components/src/spectrum/utils/index.ts

@@ -1,2 +1,3 @@
 export * from './itemUtils';
 export * from './useItemRowDeserializer';
+export * from './usePickerProps';

packages/jsapi-components/src/spectrum/utils/useItemRowDeserializer.ts

@@ -1,6 +1,7 @@
 import { useCallback, useMemo } from 'react';
 import { NormalizedItemData } from '@deephaven/components';
 import { dh } from '@deephaven/jsapi-types';
+import { assertNotNull } from '@deephaven/utils';
 import { getItemKeyColumn, getItemLabelColumn } from './itemUtils';
 
 function defaultFormatKey(value: unknown): string | number | boolean {
@@ -37,38 +38,52 @@ export function useItemRowDeserializer({
   labelColumnName,
   formatValue = defaultFormatValue,
 }: {
-  table: dh.Table;
+  table?: dh.Table | null;
   descriptionColumnName?: string;
   iconColumnName?: string;
   keyColumnName?: string;
   labelColumnName?: string;
   formatValue?: (value: unknown, columnType: string) => string;
 }): (row: dh.Row) => NormalizedItemData {
   const keyColumn = useMemo(
-    () => getItemKeyColumn(table, keyColumnName),
+    () => (table == null ? null : getItemKeyColumn(table, keyColumnName)),
     [keyColumnName, table]
   );
 
   const labelColumn = useMemo(
-    () => getItemLabelColumn(table, keyColumn, labelColumnName),
+    () =>
+      table == null || keyColumn == null
+        ? null
+        : getItemLabelColumn(table, keyColumn, labelColumnName),
     [keyColumn, labelColumnName, table]
   );
 
   const descriptionColumn = useMemo(
     () =>
-      descriptionColumnName == null
+      table == null || descriptionColumnName == null
         ? null
         : table.findColumn(descriptionColumnName),
     [descriptionColumnName, table]
   );
 
   const iconColumn = useMemo(
-    () => (iconColumnName == null ? null : table.findColumn(iconColumnName)),
+    () =>
+      table == null || iconColumnName == null
+        ? null
+        : table.findColumn(iconColumnName),
     [iconColumnName, table]
   );
 
   const deserializeRow = useCallback(
     (row: dh.Row): NormalizedItemData => {
+      // `deserializeRow` can be created on a null `table` which results in null
+      // `keyColumn` + `labelColumn`, but it should never actually be called.
+      // The assumption is that the `table` will eventually be non-null,
+      // `deserializeRow` will be recreated, and then applied to the non-null
+      // table.
+      assertNotNull(keyColumn, 'keyColumn cannot be null.');
+      assertNotNull(labelColumn, 'labelColumn cannot be null.');
+
       const key = defaultFormatKey(row.get(keyColumn));
       const content = formatValue(row.get(labelColumn), labelColumn.type);