feat(multiselect): new All option for multiselect

packages/react/src/components/ListBox/ListBoxMenuItem.tsx

@@ -6,7 +6,13 @@
  */
 
 import cx from 'classnames';
-import React, { ForwardedRef, useEffect, useRef, useState } from 'react';
+import React, {
+  ForwardedRef,
+  ReactNode,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
 import PropTypes from 'prop-types';
 import { usePrefix } from '../../internal/usePrefix';
 import { ForwardRefReturn, ReactAttr } from '../../types/common';
@@ -24,6 +30,11 @@ function useIsTruncated(ref) {
 }
 
 export interface ListBoxMenuItemProps extends ReactAttr<HTMLLIElement> {
+  /**
+   * Specify any children nodes that should be rendered inside of the ListBox
+   * Menu Item
+   */
+  children?: ReactNode;
   /**
    * Specify whether the current menu item is "active".
    */
@@ -38,6 +49,11 @@ export interface ListBoxMenuItemProps extends ReactAttr<HTMLLIElement> {
    * Specify whether the item should be disabled
    */
   disabled?: boolean;
+
+  /**
+   * Provide an optional tooltip for the ListBoxMenuItem
+   */
+  title?: string;
 }
 
 export type ListBoxMenuItemForwardedRef =

packages/react/src/components/MultiSelect/MultiSelect.stories.js

@@ -163,6 +163,8 @@ Playground.args = {
   clearSelectionDescription: 'Total items selected: ',
   useTitleInItem: false,
   clearSelectionText: 'To clear selection, press Delete or Backspace,',
+  selectAll: false,
+  selectAllItemText: 'All options',
 };
 
 Playground.argTypes = {
@@ -383,6 +385,59 @@ export const _Controlled = () => {
   );
 };
 
+export const SelectAll = () => {
+  const [label, setLabel] = useState('Choose options');
+
+  const onChange = (value) => {
+    if (value.selectedItems.length == 1) {
+      setLabel('Option selected');
+    } else if (value.selectedItems.length > 1) {
+      setLabel('Options selected');
+    } else {
+      setLabel('Choose options');
+    }
+  };
+
+  return (
+    <div style={{ width: 300 }}>
+      <MultiSelect
+        label={label}
+        id="carbon-multiselect-example"
+        titleText="Multiselect title"
+        helperText="This is helper text"
+        items={[
+          {
+            id: 'downshift-1-item-0',
+            text: 'Editor',
+          },
+          {
+            id: 'downshift-1-item-1',
+            text: 'Owner',
+          },
+          {
+            id: 'downshift-1-item-2',
+            text: 'Uploader',
+          },
+          {
+            id: 'downshift-1-item-3',
+            text: 'Reader - a disabled item',
+            disabled: true,
+          },
+          {
+            id: 'select-all',
+            text: 'All roles',
+            isSelectAll: true,
+          },
+        ]}
+        itemToString={(item) => (item ? item.text : '')}
+        selectionFeedback="top-after-reopen"
+        onChange={onChange}
+        selectAllItemText="All roles"
+      />
+    </div>
+  );
+};
+
 const aiLabel = (
   <AILabel className="slug-container">
     <AILabelContent>

packages/react/src/components/MultiSelect/MultiSelect.tsx

@@ -18,7 +18,6 @@ import PropTypes from 'prop-types';
 import React, {
   ForwardedRef,
   useContext,
-  useRef,
   useState,
   useMemo,
   ReactNode,
@@ -43,6 +42,8 @@ import { keys, match } from '../../internal/keyboard';
 import { usePrefix } from '../../internal/usePrefix';
 import { FormContext } from '../FluidForm';
 import { ListBoxProps } from '../ListBox/ListBox';
+import Checkbox from '../Checkbox';
+import type { InternationalProps } from '../../types/common';
 import type { TranslateWithId } from '../../types/common';
 import { noopFn } from '../../internal/noopFn';
 import {
@@ -330,6 +331,36 @@ const MultiSelect = React.forwardRef(
     }: MultiSelectProps<ItemType>,
     ref: ForwardedRef<HTMLButtonElement>
   ) => {
+    const sortOptions = {
+      selectedItems: selected,
+      itemToString,
+      compareItems,
+      locale,
+    };
+
+    const filteredItems = useMemo(() => {
+      return sortItems!(
+        items.filter((item) => {
+          if (typeof item === 'object' && item !== null) {
+            for (const key in item) {
+              if (Object.hasOwn(item, key) && item[key] === undefined) {
+                return false; // Return false if any property has an undefined value
+              }
+            }
+          }
+          return true; // Return true if item is not an object with undefined values
+        }),
+        sortOptions as SortItemsOptions<ItemType>
+      );
+    }, [items]);
+
+    let selectAll = filteredItems.some((item) => (item as any).isSelectAll);
+    if ((selected ?? []).length > 0 && selectAll) {
+      console.warn(
+        'Warning: `selectAll` should not be used when `selectedItems` is provided. Please pass either `selectAll` or `selectedItems`, not both.'
+      );
+      selectAll = false;
+    }
     const prefix = usePrefix();
     const { isFluid } = useContext(FormContext);
     const multiSelectInstanceId = useId();
@@ -339,16 +370,6 @@ const MultiSelect = React.forwardRef(
     const [prevOpenProp, setPrevOpenProp] = useState(open);
     const [topItems, setTopItems] = useState([]);
     const [itemsCleared, setItemsCleared] = useState(false);
-    const {
-      selectedItems: controlledSelectedItems,
-      onItemChange,
-      clearSelection,
-    } = useSelection({
-      disabled,
-      initialSelectedItems,
-      onChange,
-      selectedItems: selected,
-    });
 
     const { refs, floatingStyles, middlewareData } = useFloating(
       autoAlign
@@ -387,19 +408,18 @@ const MultiSelect = React.forwardRef(
       }
     }, [autoAlign, floatingStyles, refs.floating, middlewareData, open]);
 
-    // Filter out items with an object having undefined values
-    const filteredItems = useMemo(() => {
-      return items.filter((item) => {
-        if (typeof item === 'object' && item !== null) {
-          for (const key in item) {
-            if (Object.hasOwn(item, key) && item[key] === undefined) {
-              return false; // Return false if any property has an undefined value
-            }
-          }
-        }
-        return true; // Return true if item is not an object with undefined values
-      });
-    }, [items]);
+    const {
+      selectedItems: controlledSelectedItems,
+      onItemChange,
+      clearSelection,
+    } = useSelection({
+      disabled,
+      initialSelectedItems,
+      onChange,
+      selectedItems: selected,
+      selectAll,
+      filteredItems,
+    });
 
     const selectProps: UseSelectProps<ItemType> = {
       stateReducer,
@@ -416,7 +436,7 @@ const MultiSelect = React.forwardRef(
         );
       },
       selectedItem: controlledSelectedItems,
-      items: filteredItems,
+      items: filteredItems as ItemType[],
       isItemDisabled(item, _index) {
         return (item as any).disabled;
       },
@@ -526,19 +546,13 @@ const MultiSelect = React.forwardRef(
         selectedItems && selectedItems.length > 0,
       [`${prefix}--list-box--up`]: direction === 'top',
       [`${prefix}--multi-select--readonly`]: readOnly,
+      [`${prefix}--multi-select--selectall`]: selectAll,
     });
 
     // needs to be capitalized for react to render it correctly
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     const ItemToElement = itemToElement!;
 
-    const sortOptions = {
-      selectedItems: controlledSelectedItems,
-      itemToString,
-      compareItems,
-      locale,
-    };
-
     if (selectionFeedback === 'fixed') {
       sortOptions.selectedItems = [];
     } else if (selectionFeedback === 'top-after-reopen') {
@@ -590,7 +604,7 @@ const MultiSelect = React.forwardRef(
           } else {
             return {
               ...changes,
-              highlightedIndex: props.items.indexOf(highlightedIndex),
+              highlightedIndex: filteredItems.indexOf(highlightedIndex),
             };
           }
         case ToggleButtonKeyDownArrowDown:
@@ -661,13 +675,17 @@ const MultiSelect = React.forwardRef(
       selectedItems.length > 0 &&
       selectedItems.map((item) => (item as selectedItemType)?.text);
 
+    const selectedItemsWithoutSelectAll = selectedItems.filter(
+      (item: any) => !item.isSelectAll
+    );
+
     // Memoize the value of getMenuProps to avoid an infinite loop
     const menuProps = useMemo(
       () =>
         getMenuProps({
           ref: autoAlign ? refs.setFloating : null,
         }),
-      [autoAlign]
+      [autoAlign, getMenuProps, refs.setFloating]
     );
 
     return (
@@ -712,7 +730,7 @@ const MultiSelect = React.forwardRef(
                 clearSelection={
                   !disabled && !readOnly ? clearSelection : noopFn
                 }
-                selectionCount={selectedItems.length}
+                selectionCount={selectedItemsWithoutSelectAll.length}
                 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                 translateWithId={translateWithId!}
                 disabled={disabled}
@@ -743,15 +761,16 @@ const MultiSelect = React.forwardRef(
           </div>
           <ListBox.Menu {...menuProps}>
             {isOpen &&
-              // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-              sortItems!(
-                filteredItems,
-                sortOptions as SortItemsOptions<ItemType>
-              ).map((item, index) => {
+              filteredItems.map((item, index) => {
                 const isChecked =
                   selectedItems.filter((selected) => isEqual(selected, item))
                     .length > 0;
 
+                const isIndeterminate =
+                  selectedItems.length !== 0 &&
+                  item['isSelectAll'] &&
+                  !isChecked;
+
                 const itemProps = getItemProps({
                   item,
                   // we don't want Downshift to set aria-selected for us
@@ -763,24 +782,27 @@ const MultiSelect = React.forwardRef(
                 return (
                   <ListBox.MenuItem
                     key={itemProps.id}
-                    isActive={isChecked}
+                    isActive={isChecked && !item['isSelectAll']}
                     aria-label={itemText}
                     isHighlighted={highlightedIndex === index}
                     title={itemText}
                     disabled={itemProps['aria-disabled']}
                     {...itemProps}>
                     <div className={`${prefix}--checkbox-wrapper`}>
-                      <span
+                      <Checkbox
+                        id={`${itemProps.id}__checkbox`}
+                        labelText={
+                          itemToElement ? (
+                            <ItemToElement key={itemProps.id} {...item} />
+                          ) : (
+                            itemText
+                          )
+                        }
+                        checked={isChecked}
                         title={useTitleInItem ? itemText : undefined}
-                        className={`${prefix}--checkbox-label`}
-                        data-contained-checkbox-state={isChecked}
-                        id={`${itemProps.id}__checkbox`}>
-                        {itemToElement ? (
-                          <ItemToElement key={itemProps.id} {...item} />
-                        ) : (
-                          itemText
-                        )}
-                      </span>
+                        indeterminate={isIndeterminate}
+                        disabled={disabled}
+                      />
                     </div>
                   </ListBox.MenuItem>
                 );

packages/react/src/components/MultiSelect/__tests__/FilterableMultiSelect-test.js

@@ -6,7 +6,7 @@
  */
 
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { act, render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import FilterableMultiSelect from '../FilterableMultiSelect';
 import {
@@ -15,12 +15,11 @@ import {
   findMenuIconNode,
   generateItems,
   generateGenericItem,
-  waitForPosition,
 } from '../../ListBox/test-helpers';
 import { AILabel } from '../../AILabel';
 
 const prefix = 'cds';
-
+const waitForPosition = () => act(async () => {});
 const openMenu = async () => {
   await userEvent.click(screen.getByRole('combobox'));
 };