feat: Picker Component (#1821)

Supports deephaven/deephaven-plugins#292

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

@@ -0,0 +1,51 @@
+import React from 'react';
+import { Picker } from '@deephaven/components';
+import { vsPerson } from '@deephaven/icons';
+import { Flex, Icon, Item, Text } from '@adobe/react-spectrum';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import { sampleSectionIdAndClasses } from './utils';
+
+function PersonIcon(): JSX.Element {
+ return (
+ <Icon>
+ <FontAwesomeIcon icon={vsPerson} />
+ </Icon>
+ );
+}
+
+export function Pickers(): JSX.Element {
+ return (
+ // eslint-disable-next-line react/jsx-props-no-spreading
+ <div {...sampleSectionIdAndClasses('pickers')}>
+ <h2 className="ui-title">Pickers</h2>
+
+ <Flex gap={14}>
+ <Picker label="Single Child" tooltip={{ placement: 'bottom-end' }}>
+ <Item>Aaa</Item>
+ </Picker>
+
+ <Picker label="Mixed Children Types" tooltip>
+ {/* eslint-disable react/jsx-curly-brace-presence */}
+ {'String 1'}
+ {'String 2'}
+ {'String 3'}
+ {''}
+ {'Some really long text that should get truncated'}
+ {/* eslint-enable react/jsx-curly-brace-presence */}
+ {444}
+ {999}
+ {true}
+ {false}
+ <Item>Item Aaa</Item>
+ <Item>Item Bbb</Item>
+ <Item textValue="Complex Ccc">
+ <PersonIcon />
+ <Text>Complex Ccc</Text>
+ </Item>
+ </Picker>
+ </Flex>
+ </div>
+ );
+}
+
+export default Pickers;

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

@@ -30,6 +30,7 @@ import { HIDE_FROM_E2E_TESTS_CLASS } from './utils';
 import { GoldenLayout } from './GoldenLayout';
 import { RandomAreaPlotAnimation } from './RandomAreaPlotAnimation';
 import SpectrumComparison from './SpectrumComparison';
+import Pickers from './Pickers';
 
 const stickyProps = {
  position: 'sticky',
@@ -111,6 +112,7 @@ function StyleGuide(): React.ReactElement {
  <ContextMenus />
  <DropdownMenus />
  <Navigations />
+ <Pickers />
  <Tooltips />
  <Icons />
  <Editors />

packages/components/src/index.ts

@@ -48,6 +48,7 @@ export { default as SelectValueList } from './SelectValueList';
 export * from './SelectValueList';
 export * from './shortcuts';
 export { default as SocketedButton } from './SocketedButton';
+export * from './spectrum';
 export * from './SpectrumUtils';
 export * from './TableViewEmptyState';
 export * from './TextWithTooltip';

packages/components/src/spectrum/index.ts

@@ -0,0 +1 @@
+export * from './picker';

packages/components/src/spectrum/picker/Picker.tsx

@@ -0,0 +1,104 @@
+import { useMemo } from 'react';
+import { Item, Picker as SpectrumPicker } from '@adobe/react-spectrum';
+import { Tooltip } from '../../popper';
+import {
+ NormalizedSpectrumPickerProps,
+ normalizePickerItemList,
+ normalizeTooltipOptions,
+ PickerItem,
+ PickerItemKey,
+ TooltipOptions,
+} from './PickerUtils';
+import { PickerItemContent } from './PickerItemContent';
+
+export type PickerProps = {
+ children: PickerItem | PickerItem[];
+ /** Can be set to true or a TooltipOptions to enable item tooltips */
+ tooltip?: boolean | TooltipOptions;
+ /** The currently selected key in the collection (controlled). */
+ selectedKey?: PickerItemKey | null;
+ /** The initial selected key in the collection (uncontrolled). */
+ defaultSelectedKey?: PickerItemKey;
+ /**
+ * Handler that is called when the selection change.
+ * Note that under the hood, this is just an alias for Spectrum's
+ * `onSelectionChange`. We are renaming for better consistency with other
+ * components.
+ */
+ onChange?: (key: PickerItemKey) => void;
+ /**
+ * Handler that is called when the selection changes.
+ * @deprecated Use `onChange` instead
+ */
+ onSelectionChange?: (key: PickerItemKey) => void;
+} /*
+ * Support remaining SpectrumPickerProps.
+ * Note that `selectedKey`, `defaultSelectedKey`, and `onSelectionChange` are
+ * re-defined above to account for boolean types which aren't included in the
+ * React `Key` type, but are actually supported by the Spectrum Picker component.
+ */ & Omit<
+ NormalizedSpectrumPickerProps,
+ | 'children'
+ | 'items'
+ | 'onSelectionChange'
+ | 'selectedKey'
+ | 'defaultSelectedKey'
+>;
+
+/**
+ * Picker component for selecting items from a list of items. Items can be
+ * provided via the `items` prop or as children. Each item can be a string,
+ * number, boolean, or a Spectrum <Item> element. The remaining props are just
+ * pass through props for the Spectrum Picker component.
+ * See https://react-spectrum.adobe.com/react-spectrum/Picker.html
+ */
+export function Picker({
+ children,
+ tooltip,
+ defaultSelectedKey,
+ selectedKey,
+ onChange,
+ onSelectionChange,
+ ...spectrumPickerProps
+}: PickerProps): JSX.Element {
+ const normalizedItems = useMemo(
+ () => normalizePickerItemList(children),
+ [children]
+ );
+
+ const tooltipOptions = useMemo(
+ () => normalizeTooltipOptions(tooltip),
+ [tooltip]
+ );
+
+ return (
+ <SpectrumPicker
+ // eslint-disable-next-line react/jsx-props-no-spreading
+ {...spectrumPickerProps}
+ items={normalizedItems}
+ // Type assertions are necessary for `selectedKey`, `defaultSelectedKey`,
+ // and `onSelectionChange` due to Spectrum types not accounting for
+ // `boolean` keys
+ selectedKey={selectedKey as NormalizedSpectrumPickerProps['selectedKey']}
+ defaultSelectedKey={
+ defaultSelectedKey as NormalizedSpectrumPickerProps['defaultSelectedKey']
+ }
+ // `onChange` is just an alias for `onSelectionChange`
+ onSelectionChange={
+ (onChange ??
+ onSelectionChange) as NormalizedSpectrumPickerProps['onSelectionChange']
+ }
+ >
+ {({ content, textValue }) => (
+ <Item textValue={textValue === '' ? 'Empty' : textValue}>
+ <PickerItemContent>{content}</PickerItemContent>
+ {tooltipOptions == null || content === '' ? null : (
+ <Tooltip options={tooltipOptions}>{content}</Tooltip>
+ )}
+ </Item>
+ )}
+ </SpectrumPicker>
+ );
+}
+
+export default Picker;

packages/components/src/spectrum/picker/PickerItemContent.tsx

@@ -0,0 +1,31 @@
+import { isValidElement, ReactNode } from 'react';
+import { Text } from '@adobe/react-spectrum';
+import stylesCommon from '../../SpectrumComponent.module.scss';
+
+export interface PickerItemContentProps {
+ children: ReactNode;
+}
+
+/**
+ * Picker item content. Text content will be wrapped in a Spectrum Text
+ * component with ellipsis overflow handling.
+ */
+export function PickerItemContent({
+ children: content,
+}: PickerItemContentProps): JSX.Element {
+ if (isValidElement(content)) {
+ return content;
+ }
+
+ if (content === '') {
+ // Prevent the item height from collapsing when the content is empty
+ // eslint-disable-next-line no-param-reassign
+ content = <>&nbsp;</>;
+ }
+
+ return (
+ <Text UNSAFE_className={stylesCommon.spectrumEllipsis}>{content}</Text>
+ );
+}
+
+export default PickerItemContent;

packages/components/src/spectrum/picker/PickerUtils.test.tsx

@@ -0,0 +1,142 @@
+import React from 'react';
+import { Item, Text } from '@adobe/react-spectrum';
+import {
+ NormalizedPickerItem,
+ normalizeTooltipOptions,
+ normalizePickerItemList,
+ PickerItem,
+} from './PickerUtils';
+import type { PickerProps } from './Picker';
+
+beforeEach(() => {
+ expect.hasAssertions();
+});
+
+/* eslint-disable react/jsx-key */
+const expectedNormalizations = new Map<PickerItem, NormalizedPickerItem>([
+ [
+ 999,
+ {
+ content: '999',
+ key: 999,
+ textValue: '999',
+ },
+ ],
+ [
+ true,
+ {
+ content: 'true',
+ key: true,
+ textValue: 'true',
+ },
+ ],
+ [
+ false,
+ {
+ content: 'false',
+ key: false,
+ textValue: 'false',
+ },
+ ],
+ [
+ '',
+ {
+ content: '',
+ key: '',
+ textValue: '',
+ },
+ ],
+ [
+ 'String',
+ {
+ content: 'String',
+ key: 'String',
+ textValue: 'String',
+ },
+ ],
+ [
+ <Item>Single string child no textValue</Item>,
+ {
+ content: 'Single string child no textValue',
+ key: 'Single string child no textValue',
+ textValue: 'Single string child no textValue',
+ },
+ ],
+ [
+ <Item>
+ <span>No textValue</span>
+ </Item>,
+ {
+ content: <span>No textValue</span>,
+ key: '',
+ textValue: '',
+ },
+ ],
+ [
+ <Item textValue="textValue">Single string</Item>,
+ {
+ content: 'Single string',
+ key: 'Single string',
+ textValue: 'textValue',
+ },
+ ],
+ [
+ <Item key="explicit.key" textValue="textValue">
+ Explicit key
+ </Item>,
+ {
+ content: 'Explicit key',
+ key: 'explicit.key',
+ textValue: 'textValue',
+ },
+ ],
+ [
+ <Item textValue="textValue">
+ <i>i</i>
+ <Text>Complex</Text>
+ </Item>,
+ {
+ content: [<i>i</i>, <Text>Complex</Text>],
+ key: 'textValue',
+ textValue: 'textValue',
+ },
+ ],
+]);
+/* eslint-enable react/jsx-key */
+
+const mixedItems = [...expectedNormalizations.keys()];
+
+const children = {
+ empty: [] as PickerProps['children'],
+ single: mixedItems[0] as PickerProps['children'],
+ mixed: mixedItems as PickerProps['children'],
+};
+
+describe('normalizePickerItemList', () => {
+ it.each([children.empty, children.single, children.mixed])(
+ 'should return normalized picker items: %s',
+ given => {
+ const childrenArray = Array.isArray(given) ? given : [given];
+
+ const expected = childrenArray.map(item =>
+ expectedNormalizations.get(item)
+ );
+
+ const actual = normalizePickerItemList(given);
+ expect(actual).toEqual(expected);
+ }
+ );
+});
+
+describe('normalizeTooltipOptions', () => {
+ it.each([
+ [undefined, null],
+ [null, null],
+ [false, null],
+ [true, { placement: 'top-start' }],
+ [{ placement: 'bottom-end' }, { placement: 'bottom-end' }],
+ ] as const)('should return: %s', (options, expected) => {
+ const actual = normalizeTooltipOptions(options);
+ expect(actual).toEqual(expected);
+ });
+});