@leafygreen-ui/combobox 1.0.2 → 1.2.0

package/src/Combobox.types.ts

@@ -5,8 +5,28 @@ import { Either } from '@leafygreen-ui/lib';
  * Prop Enums & Types
  */
 
+export const ComboboxElement = {
+  Input: 'Input',
+  ClearButton: 'ClearButton',
+  FirstChip: 'FirstChip',
+  LastChip: 'LastChip',
+  MiddleChip: 'MiddleChip',
+  Combobox: 'Combobox',
+  Menu: 'Menu',
+} as const;
+export type ComboboxElement =
+  typeof ComboboxElement[keyof typeof ComboboxElement];
+
+/**
+ * Prop types
+ */
+
 export const ComboboxSize = {
-  default: 'default',
+  // TODO: add XSmall & Small variants after the refresh
+  // XSmall: 'xsmall',
+  // Small: 'small',
+  Default: 'default',
+  Large: 'large',
 } as const;
 export type ComboboxSize = typeof ComboboxSize[keyof typeof ComboboxSize];
 
@@ -16,12 +36,13 @@ export const TrunctationLocation = {
   end: 'end',
   none: 'none',
 } as const;
-export type TrunctationLocation = typeof TrunctationLocation[keyof typeof TrunctationLocation];
+export type TrunctationLocation =
+  typeof TrunctationLocation[keyof typeof TrunctationLocation];
 
 export const Overflow = {
   expandY: 'expand-y',
   expandX: 'expand-x',
-  scrollY: 'scroll-x',
+  scrollX: 'scroll-x',
 } as const;
 export type Overflow = typeof Overflow[keyof typeof Overflow];
 
@@ -55,7 +76,7 @@ export function getNullSelection<M extends boolean>(
   multiselect: M,
 ): SelectValueType<M> {
   if (multiselect) {
-    return ([] as Array<string>) as SelectValueType<M>;
+    return [] as Array<string> as SelectValueType<M>;
   } else {
     return null as SelectValueType<M>;
   }
@@ -73,8 +94,8 @@ export interface ComboboxMultiselectProps<M extends boolean> {
   multiselect?: M;
   /**
    * The initial selection.
-   * Must be a string for a single-select, or an array of strings for multiselect.
-   * Changing the initialValue after initial render will not change the selection.
+   * Must be a string (or array of strings) that matches the `value` prop of a `ComboboxOption`.
+   * Changing the `initialValue` after initial render will not change the selection.
    */
   initialValue?: SelectValueType<M>;
   /**
@@ -84,10 +105,12 @@ export interface ComboboxMultiselectProps<M extends boolean> {
   onChange?: onChangeType<M>;
   /**
    * The controlled value of the Combobox.
-   * Must be a string for a single-select, or an array of strings for multiselect.
-   * Changing value after initial render will affect the selection.
+   * Must be a string (or array of strings) that matches the `value` prop of a `ComboboxOption`.
+   * Changing `value` after initial render _will_ affect the selection.
+   * `value` will always take precedence over `initialValue` if both are provided.
    */
   value?: SelectValueType<M>;
+
   /**
    * Defines the overflow behavior of a multiselect combobox.
    *
@@ -248,6 +271,7 @@ export type ComboboxProps<M extends boolean> = Either<
 /**
  * Combobox Option Props
  */
+
 interface BaseComboboxOptionProps {
   /**
    * The internal value of the option. Used as the identifier in Combobox `initialValue`, value and filteredOptions.
@@ -266,6 +290,12 @@ interface BaseComboboxOptionProps {
    */
   glyph?: ReactElement;
 
+  /**
+   * Defines whether the option is disabled.
+   * Node: disabled options are still rendered in the menu, but not selectable.
+   */
+  disabled?: boolean;
+
   /**
    * Styling Prop
    */
@@ -277,12 +307,20 @@ export type ComboboxOptionProps = Either<
   'value' | 'displayName'
 >;
 
+export interface OptionObject {
+  value: string;
+  displayName: string;
+  isDisabled: boolean;
+  hasGlyph?: boolean;
+}
+
 export interface InternalComboboxOptionProps {
   value: string;
   displayName: string;
   isSelected: boolean;
   isFocused: boolean;
   setSelected: () => void;
+  disabled?: boolean;
   glyph?: ReactElement;
   className?: string;
   index: number;

package/src/ComboboxContext.tsx

@@ -4,7 +4,7 @@ import { ComboboxSize, TrunctationLocation } from './Combobox.types';
 interface ComboboxData {
   multiselect: boolean;
   darkMode: boolean;
-  size: keyof typeof ComboboxSize;
+  size: ComboboxSize;
   withIcons: boolean;
   disabled: boolean;
   chipTruncationLocation?: TrunctationLocation;
@@ -15,7 +15,7 @@ interface ComboboxData {
 export const ComboboxContext = createContext<ComboboxData>({
   multiselect: false,
   darkMode: false,
-  size: 'default',
+  size: ComboboxSize.Default,
   withIcons: false,
   disabled: false,
 });

package/src/ComboboxOption.tsx

@@ -10,13 +10,14 @@ import {
   InternalComboboxOptionProps,
 } from './Combobox.types';
 import { ComboboxContext } from './ComboboxContext';
-import { wrapJSX } from './util';
+import { wrapJSX } from './utils';
+import { fontFamilies } from '@leafygreen-ui/tokens';
 
 /**
  * Styles
  */
 
-const comboboxOptionStyle = () => css`
+const comboboxOptionStyle = css`
   position: relative;
   display: flex;
   align-items: center;
@@ -25,10 +26,12 @@ const comboboxOptionStyle = () => css`
   color: inherit;
   cursor: pointer;
   overflow: hidden;
+  font-family: ${fontFamilies.legacy};
   font-size: var(--lg-combobox-item-font-size);
   line-height: var(--lg-combobox-item-line-height);
   padding: var(--lg-combobox-item-padding-y) var(--lg-combobox-item-padding-x);
 
+  // Left wedge
   &:before {
     content: '';
     position: absolute;
@@ -58,11 +61,21 @@ const comboboxOptionStyle = () => css`
   }
 `;
 
+const comboboxOptionDisabledStyle = css`
+  cursor: not-allowed;
+  color: ${uiColors.gray.base};
+
+  &:hover {
+    background-color: inherit;
+  }
+`;
+
 const flexSpan = css`
   display: inline-flex;
   gap: 8px;
   justify-content: start;
   align-items: inherit;
+  overflow-wrap: anywhere;
 `;
 
 const disallowPointer = css`
@@ -72,10 +85,10 @@ const disallowPointer = css`
 const displayNameStyle = (isSelected: boolean) => css`
   font-weight: ${isSelected ? 'bold' : 'normal'};
 `;
+
 /**
  * Component
  */
-
 const InternalComboboxOption = React.forwardRef<
   HTMLLIElement,
   InternalComboboxOptionProps
@@ -86,31 +99,35 @@ const InternalComboboxOption = React.forwardRef<
       glyph,
       isSelected,
       isFocused,
+      disabled,
       setSelected,
       className,
     }: InternalComboboxOptionProps,
     forwardedRef,
   ) => {
-    const { multiselect, darkMode, withIcons, inputValue } = useContext(
-      ComboboxContext,
-    );
+    const { multiselect, darkMode, withIcons, inputValue } =
+      useContext(ComboboxContext);
     const optionTextId = useIdAllocator({ prefix: 'combobox-option-text' });
     const optionRef = useForwardedRef(forwardedRef, null);
 
     const handleOptionClick = useCallback(
       (e: React.SyntheticEvent) => {
+        // stopPropagation will not stop the keyDown event (only click)
+        // since the option is never `focused`, only `aria-selected`
+        // the keyDown event does not actually fire on the option element
         e.stopPropagation();
 
         // If user clicked on the option, or the checkbox
         // Ignore extra click events on the checkbox wrapper
         if (
-          e.target === optionRef.current ||
-          (e.target as Element).tagName === 'INPUT'
+          !disabled &&
+          (e.target === optionRef.current ||
+            (e.target as Element).tagName === 'INPUT')
         ) {
           setSelected();
         }
       },
-      [optionRef, setSelected],
+      [disabled, optionRef, setSelected],
     );
 
     const renderedIcon = useMemo(() => {
@@ -136,6 +153,7 @@ const InternalComboboxOption = React.forwardRef<
             checked={isSelected}
             tabIndex={-1}
             animate={false}
+            disabled={disabled}
           />
         );
 
@@ -177,6 +195,7 @@ const InternalComboboxOption = React.forwardRef<
       inputValue,
       darkMode,
       optionTextId,
+      disabled,
       withIcons,
     ]);
 
@@ -187,9 +206,15 @@ const InternalComboboxOption = React.forwardRef<
         aria-selected={isFocused}
         aria-label={displayName}
         tabIndex={-1}
-        className={cx(comboboxOptionStyle(), className)}
+        className={cx(
+          comboboxOptionStyle,
+          {
+            [comboboxOptionDisabledStyle]: disabled,
+          },
+          className,
+        )}
         onClick={handleOptionClick}
-        onKeyPress={handleOptionClick}
+        onKeyDown={handleOptionClick}
       >
         {renderedChildren}
       </li>

package/src/ComboboxTestUtils.tsx

@@ -4,12 +4,16 @@ import {
   configure,
   queryByText,
   queryByAttribute,
+  queryAllByTestId,
   queryAllByAttribute,
 } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Combobox, ComboboxGroup, ComboboxOption } from '.';
-import { BaseComboboxProps, ComboboxMultiselectProps } from './Combobox.types';
-import { OptionObject } from './util';
+import {
+  BaseComboboxProps,
+  ComboboxMultiselectProps,
+  OptionObject,
+} from './Combobox.types';
 import { isArray, isNull } from 'lodash';
 import chalk from '@testing-library/jest-dom/node_modules/chalk';
 
@@ -28,14 +32,17 @@ export const defaultOptions: Array<OptionObject> = [
   {
     value: 'apple',
     displayName: 'Apple',
+    isDisabled: false,
   },
   {
     value: 'banana',
     displayName: 'Banana',
+    isDisabled: false,
   },
   {
     value: 'carrot',
     displayName: 'Carrot',
+    isDisabled: false,
   },
 ];
 
@@ -46,10 +53,12 @@ export const groupedOptions: Array<NestedObject> = [
       {
         value: 'apple',
         displayName: 'Apple',
+        isDisabled: false,
       },
       {
         value: 'banana',
         displayName: 'Banana',
+        isDisabled: false,
       },
     ],
   },
@@ -59,10 +68,12 @@ export const groupedOptions: Array<NestedObject> = [
       {
         value: 'carrot',
         displayName: 'Carrot',
+        isDisabled: false,
       },
       {
         value: 'eggplant',
         displayName: 'Eggplant',
+        isDisabled: false,
       },
     ],
   },
@@ -88,8 +99,15 @@ export const getComboboxJSX = (props?: renderComboboxProps) => {
       const displayName =
         typeof option === 'string' ? undefined : option.displayName;
 
+      const isDisabled = typeof option === 'string' ? false : option.isDisabled;
+
       return (
-        <ComboboxOption key={value} value={value} displayName={displayName} />
+        <ComboboxOption
+          key={value}
+          value={value}
+          displayName={displayName}
+          disabled={isDisabled}
+        />
       );
     }
   };
@@ -177,11 +195,7 @@ export function renderCombobox<T extends Select>(
    * @returns all chip elements
    */
   function queryAllChips(): Array<HTMLElement> {
-    return queryAllByAttribute(
-      'data-leafygreen-ui',
-      containerEl,
-      'combobox-chip',
-    );
+    return queryAllByTestId(containerEl, 'lg-combobox-chip');
   }
 
   /**

package/src/utils/ComboboxUtils.spec.tsx

@@ -0,0 +1,227 @@
+import { render } from '@testing-library/react';
+import React from 'react';
+import Icon from '@leafygreen-ui/icon';
+import { wrapJSX, getNameAndValue, flattenChildren } from '.';
+import ComboboxOption from '../ComboboxOption';
+import ComboboxGroup from '../ComboboxGroup';
+
+describe('packages/combobox/utils', () => {
+  describe('wrapJSX', () => {
+    test('Wraps the matched string in the provided element', () => {
+      const JSX = wrapJSX('Apple', 'pp', 'em');
+      const { container } = render(JSX);
+      const ems = container.querySelectorAll('em');
+      expect(ems).toHaveLength(1);
+      expect(ems[0]).toHaveTextContent('pp');
+      expect(container).toHaveTextContent('Apple');
+    });
+    test('Wraps the entire string when it matches', () => {
+      const JSX = wrapJSX('Apple', 'Apple', 'em');
+      const { container } = render(JSX);
+      const ems = container.querySelectorAll('em');
+      expect(ems).toHaveLength(1);
+      expect(ems[0]).toHaveTextContent('Apple');
+      expect(container).toHaveTextContent('Apple');
+    });
+    test('Keeps case consistent with source', () => {
+      const JSX = wrapJSX('Apple', 'aPPlE', 'em');
+      const { container } = render(JSX);
+      const ems = container.querySelectorAll('em');
+      expect(ems).toHaveLength(1);
+      expect(ems[0]).toHaveTextContent('Apple');
+      expect(container).toHaveTextContent('Apple');
+    });
+    // No match
+    test('Wraps nothing when there is no match', () => {
+      const JSX = wrapJSX('Apple', 'q', 'em');
+      const { container } = render(JSX);
+      const ems = container.querySelectorAll('em');
+      expect(ems).toHaveLength(0);
+      expect(container).toHaveTextContent('Apple');
+    });
+
+    // Multiple matches
+    test('wraps all instances of a match', () => {
+      const JSX = wrapJSX('Pepper', 'p', 'em');
+      const { container } = render(JSX);
+      const ems = container.querySelectorAll('em');
+      expect(ems).toHaveLength(3);
+      expect(ems[0]).toHaveTextContent('P');
+      expect(ems[1]).toHaveTextContent('p');
+      expect(ems[2]).toHaveTextContent('p');
+      expect(container).toHaveTextContent('Pepper');
+    });
+    test('wraps all instances of longer match', () => {
+      const JSX = wrapJSX('Pepper', 'pe', 'em');
+      const { container } = render(JSX);
+      const ems = container.querySelectorAll('em');
+      expect(ems).toHaveLength(2);
+      expect(ems[0]).toHaveTextContent('Pe');
+      expect(ems[1]).toHaveTextContent('pe');
+      expect(container).toHaveTextContent('Pepper');
+    });
+
+    // No `wrap`
+    test('Returns the input string when "wrap" is empty', () => {
+      const JSX = wrapJSX('Apple', '', 'em');
+      const { container } = render(JSX);
+      const ems = container.querySelectorAll('em');
+      expect(ems).toHaveLength(0);
+      expect(container).toHaveTextContent(`Apple`);
+    });
+    test('Returns the input string when "wrap" is `undefined`', () => {
+      const JSX = wrapJSX('Apple', undefined, 'em');
+      const { container } = render(JSX);
+      const ems = container.querySelectorAll('em');
+      expect(ems).toHaveLength(0);
+      expect(container).toHaveTextContent(`Apple`);
+    });
+
+    // No `element`
+    test('Returns the input string when "element" is empty', () => {
+      const JSX = wrapJSX('Apple', 'ap', '' as keyof HTMLElementTagNameMap);
+      const { container } = render(JSX);
+      const ems = container.querySelectorAll('em');
+      expect(ems).toHaveLength(0);
+      expect(container).toHaveTextContent(`Apple`);
+    });
+    test('Returns the input string when "element" is undefined', () => {
+      const JSX = wrapJSX('Apple', 'ap');
+      const { container } = render(JSX);
+      const ems = container.querySelectorAll('em');
+      expect(ems).toHaveLength(0);
+      expect(container).toHaveTextContent(`Apple`);
+    });
+
+    test('Updates after a second call', () => {
+      const JSX = wrapJSX('Apple', 'p', 'em');
+      const { container, rerender } = render(JSX);
+      let ems = container.querySelectorAll('em');
+      expect(ems).toHaveLength(2);
+      const JSX2 = wrapJSX('Apple', 'pp', 'em');
+      rerender(JSX2);
+      ems = container.querySelectorAll('em');
+      expect(ems).toHaveLength(1);
+      expect(ems[0]).toHaveTextContent('pp');
+      expect(container).toHaveTextContent(`Apple`);
+    });
+  });
+
+  describe('getNameAndValue', () => {
+    test('Returns both value and displayName as given', () => {
+      const result = getNameAndValue({
+        value: 'value',
+        displayName: 'Display Name',
+      });
+      expect(result).toEqual({ value: 'value', displayName: 'Display Name' });
+    });
+
+    test('Returns a generated displayName', () => {
+      const result = getNameAndValue({ value: 'value' });
+      expect(result).toEqual({ value: 'value', displayName: 'value' });
+    });
+
+    test('Returns a generated value', () => {
+      const result = getNameAndValue({ displayName: 'Display Name' });
+      expect(result).toEqual({
+        value: 'display-name',
+        displayName: 'Display Name',
+      });
+    });
+  });
+
+  describe('flattenChildren', () => {
+    test('returns a single option', () => {
+      const children = <ComboboxOption value="test" displayName="Test" />;
+      const flat = flattenChildren(children);
+      expect(flat).toEqual([
+        {
+          value: 'test',
+          displayName: 'Test',
+          hasGlyph: false,
+          isDisabled: false,
+        },
+      ]);
+    });
+
+    test('returns multiple options', () => {
+      const children = [
+        <ComboboxOption key="apple" value="apple" displayName="Apple" />,
+        <ComboboxOption key="banana" value="banana" displayName="Banana" />,
+      ];
+      const flat = flattenChildren(children);
+      expect(flat).toEqual([
+        {
+          value: 'apple',
+          displayName: 'Apple',
+          hasGlyph: false,
+          isDisabled: false,
+        },
+        {
+          value: 'banana',
+          displayName: 'Banana',
+          hasGlyph: false,
+          isDisabled: false,
+        },
+      ]);
+    });
+
+    test('returns hasGlyph and isDisabled', () => {
+      const children = (
+        <ComboboxOption
+          value="test"
+          displayName="Test"
+          glyph={<Icon glyph="Beaker" />}
+          disabled
+        />
+      );
+      const flat = flattenChildren(children);
+      expect(flat).toEqual([
+        {
+          value: 'test',
+          displayName: 'Test',
+          hasGlyph: true,
+          isDisabled: true,
+        },
+      ]);
+    });
+
+    test('flattens nested options', () => {
+      const children = [
+        <ComboboxOption key="apple" value="apple" displayName="Apple" />,
+        <ComboboxOption key="banana" value="banana" displayName="Banana" />,
+        <ComboboxGroup key="peppers" label="Peppers">
+          <ComboboxOption value="ghost" displayName="Ghost" />
+          <ComboboxOption value="habanero" displayName="Habanero" />
+        </ComboboxGroup>,
+      ];
+      const flat = flattenChildren(children);
+      expect(flat).toEqual([
+        {
+          value: 'apple',
+          displayName: 'Apple',
+          hasGlyph: false,
+          isDisabled: false,
+        },
+        {
+          value: 'banana',
+          displayName: 'Banana',
+          hasGlyph: false,
+          isDisabled: false,
+        },
+        {
+          value: 'ghost',
+          displayName: 'Ghost',
+          hasGlyph: false,
+          isDisabled: false,
+        },
+        {
+          value: 'habanero',
+          displayName: 'Habanero',
+          hasGlyph: false,
+          isDisabled: false,
+        },
+      ]);
+    });
+  });
+});

package/src/utils/OptionObjectUtils.ts

@@ -0,0 +1,26 @@
+import { OptionObject } from '../Combobox.types';
+
+export const getOptionObjectFromValue = (
+  value: string | null,
+  options: Array<OptionObject>,
+): OptionObject | undefined => {
+  if (value) return options.find(opt => opt.value === value);
+};
+
+export const getDisplayNameForValue = (
+  value: string | null,
+  options: Array<OptionObject>,
+): string => {
+  return value
+    ? getOptionObjectFromValue(value, options)?.displayName ?? value
+    : '';
+};
+
+export const getValueForDisplayName = (
+  displayName: string | null,
+  options: Array<OptionObject>,
+): string => {
+  return displayName
+    ? options.find(opt => opt.displayName === displayName)?.value ?? displayName
+    : '';
+};

package/src/utils/flattenChildren.tsx

@@ -0,0 +1,47 @@
+import React from 'react';
+import { isComponentType, keyMap as _keyMap } from '@leafygreen-ui/lib';
+import { OptionObject } from '../Combobox.types';
+import { getNameAndValue } from './getNameAndValue';
+
+/**
+ *
+ * Flattens multiple nested ComboboxOptions into a 1D array
+ *
+ * @param _children
+ * @returns `Array<OptionObject>`
+ */
+export const flattenChildren = (
+  _children: React.ReactNode,
+): Array<OptionObject> => {
+  // TS doesn't like .reduce
+  // @ts-expect-error
+  return React.Children.toArray(_children).reduce(
+    // @ts-expect-error
+    (
+      acc: Array<OptionObject>,
+      child: React.ReactNode,
+    ): Array<OptionObject> | undefined => {
+      if (isComponentType(child, 'ComboboxOption')) {
+        const { value, displayName } = getNameAndValue(child.props);
+        const { glyph, disabled } = child.props;
+
+        return [
+          ...acc,
+          {
+            value,
+            displayName,
+            isDisabled: !!disabled,
+            hasGlyph: !!glyph,
+          },
+        ];
+      } else if (isComponentType(child, 'ComboboxGroup')) {
+        const { children } = child.props;
+
+        if (children) {
+          return [...acc, ...flattenChildren(children)];
+        }
+      }
+    },
+    [] as Array<OptionObject>,
+  );
+};

package/src/utils/getNameAndValue.ts

@@ -0,0 +1,23 @@
+import kebabCase from 'lodash/kebabCase';
+import { ComboboxOptionProps } from '../Combobox.types';
+
+/**
+ *
+ * Returns an object with properties `value` & `displayName`
+ * based on the props provided
+ *
+ * @property value: string
+ * @property displayName: string
+ */
+export const getNameAndValue = ({
+  value: valProp,
+  displayName: nameProp,
+}: ComboboxOptionProps): {
+  value: string;
+  displayName: string;
+} => {
+  return {
+    value: valProp ?? kebabCase(nameProp),
+    displayName: nameProp ?? valProp ?? '', // TODO consider adding a prop to customize displayName => startCase(valProp),
+  };
+};