feat(multiselect): new All option for multiselect

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -5375,6 +5375,9 @@ Map {
       "downshiftProps": Object {
         "type": "object",
       },
+      "hasSelectAll": Object {
+        "type": "bool",
+      },
       "helperText": Object {
         "type": "node",
       },
@@ -5408,6 +5411,9 @@ Map {
         "isRequired": true,
         "type": "node",
       },
+      "labelforSelectAll": Object {
+        "type": "string",
+      },
       "light": [Function],
       "locale": Object {
         "type": "string",

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,16 @@ export interface ListBoxMenuItemProps extends ReactAttr<HTMLLIElement> {
    * Specify whether the item should be disabled
    */
   disabled?: boolean;
+
+  /**
+   * Specify whether the item is Select All option
+   */
+  isSelectAll?: boolean;
+
+  /**
+   * Provide an optional tooltip for the ListBoxMenuItem
+   */
+  title?: string;
 }
 
 export type ListBoxMenuItemForwardedRef =
@@ -62,6 +83,7 @@ const ListBoxMenuItem = React.forwardRef<HTMLLIElement, ListBoxMenuItemProps>(
       children,
       isActive = false,
       isHighlighted = false,
+      isSelectAll = false,
       title,
       ...rest
     }: ListBoxMenuItemProps,
@@ -73,6 +95,7 @@ const ListBoxMenuItem = React.forwardRef<HTMLLIElement, ListBoxMenuItemProps>(
     const className = cx(`${prefix}--list-box__menu-item`, {
       [`${prefix}--list-box__menu-item--active`]: isActive,
       [`${prefix}--list-box__menu-item--highlighted`]: isHighlighted,
+      [`${prefix}--list-box__menu-item--selectall`]: isSelectAll,
     });
 
     return (
@@ -113,6 +136,11 @@ ListBoxMenuItem.propTypes = {
    */
   isHighlighted: PropTypes.bool,
 
+  /**
+   * Specify whether the item is Select All option
+   */
+  isSelectAll: PropTypes.bool,
+
   /**
    * Provide an optional tooltip for the ListBoxMenuItem
    */

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

@@ -380,7 +380,55 @@ export const _Controlled = () => {
   );
 };
 
-export const ExperimentalAutoAlign = () => {
+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,
+          },
+        ]}
+        itemToString={(item) => (item ? item.text : '')}
+        selectionFeedback="top-after-reopen"
+        hasSelectAll={true}
+        onChange={onChange}
+        labelforSelectAll="All roles"
+      />
+    </div>
+  );
+};
+export const _ExperimentalAutoAlign = () => {
   const ref = useRef();
   useEffect(() => {
     ref?.current?.scrollIntoView({ block: 'center', inline: 'center' });

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

@@ -43,6 +43,7 @@ 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 { noopFn } from '../../internal/noopFn';
 import {
@@ -140,6 +141,16 @@ export interface MultiSelectProps<ItemType>
    */
   downshiftProps?: Partial<UseSelectProps<ItemType>>;
 
+  /**
+   * experimental prop to Show/Hide All option
+   */
+  hasSelectAll?: boolean;
+
+  /**
+   * Provide Label for Select All option
+   */
+  labelforSelectAll?: string;
+
   /**
    * Provide helper text that is used alongside the control label for
    * additional help
@@ -322,9 +333,17 @@ const MultiSelect = React.forwardRef(
       readOnly,
       locale = 'en',
       slug,
+      hasSelectAll = false,
+      labelforSelectAll = 'All',
     }: MultiSelectProps<ItemType>,
     ref: ForwardedRef<HTMLButtonElement>
   ) => {
+    if ((selected ?? []).length > 0 && hasSelectAll) {
+      console.warn(
+        'Warning: `hasSelectAll` should not be used when `selectedItems` is provided. Please pass either `hasSelectAll` or `selectedItems`, not both.'
+      );
+      hasSelectAll = false;
+    }
     const prefix = usePrefix();
     const { isFluid } = useContext(FormContext);
     const multiSelectInstanceId = useId();
@@ -334,16 +353,12 @@ 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 selectAllOption = {
+      id: 'select-all-option',
+      text: labelforSelectAll,
+      selectAllFlag: true,
+    };
 
     const { refs, floatingStyles, middlewareData } = useFloating(
       autoAlign
@@ -396,6 +411,23 @@ const MultiSelect = React.forwardRef(
       });
     }, [items]);
 
+    const itemsWithSelectAll = hasSelectAll
+      ? [selectAllOption, ...filteredItems]
+      : filteredItems;
+
+    const {
+      selectedItems: controlledSelectedItems,
+      onItemChange,
+      clearSelection,
+    } = useSelection({
+      disabled,
+      initialSelectedItems,
+      onChange,
+      selectedItems: selected,
+      hasSelectAll,
+      itemsWithSelectAll,
+    });
+
     const selectProps: UseSelectProps<ItemType> = {
       ...downshiftProps,
       stateReducer,
@@ -412,7 +444,7 @@ const MultiSelect = React.forwardRef(
         );
       },
       selectedItem: controlledSelectedItems,
-      items: filteredItems,
+      items: itemsWithSelectAll as ItemType[],
       isItemDisabled(item, _index) {
         return (item as any).disabled;
       },
@@ -581,7 +613,7 @@ const MultiSelect = React.forwardRef(
           } else {
             return {
               ...changes,
-              highlightedIndex: props.items.indexOf(highlightedIndex),
+              highlightedIndex: itemsWithSelectAll.indexOf(highlightedIndex),
             };
           }
         case ToggleButtonKeyDownArrowDown:
@@ -652,6 +684,9 @@ const MultiSelect = React.forwardRef(
       selectedItems.length > 0 &&
       selectedItems.map((item) => (item as selectedItemType)?.text);
 
+    const selectedItemsWithoutSelectAll = selectedItems.filter(
+      (item: any) => !item.selectAllFlag
+    );
     return (
       <div className={wrapperClasses}>
         <label className={titleClasses} {...getLabelProps()}>
@@ -694,7 +729,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}
@@ -730,13 +765,18 @@ const MultiSelect = React.forwardRef(
             {isOpen &&
               // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
               sortItems!(
-                filteredItems,
+                itemsWithSelectAll as readonly ItemType[],
                 sortOptions as SortItemsOptions<ItemType>
               ).map((item, index) => {
                 const isChecked =
                   selectedItems.filter((selected) => isEqual(selected, item))
                     .length > 0;
 
+                const isIndeterminate =
+                  selectedItems.length !== 0 &&
+                  item['selectAllFlag'] &&
+                  !isChecked;
+
                 const itemProps = getItemProps({
                   item,
                   // we don't want Downshift to set aria-selected for us
@@ -748,24 +788,28 @@ const MultiSelect = React.forwardRef(
                 return (
                   <ListBox.MenuItem
                     key={itemProps.id}
-                    isActive={isChecked}
+                    isActive={isChecked && !item['selectAllFlag']}
                     aria-label={itemText}
                     isHighlighted={highlightedIndex === index}
                     title={itemText}
                     disabled={itemProps['aria-disabled']}
+                    isSelectAll={item['selectAllFlag']}
                     {...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>
                 );
@@ -844,6 +888,11 @@ MultiSelect.propTypes = {
    */
   downshiftProps: PropTypes.object as React.Validator<UseSelectProps<unknown>>,
 
+  /**
+   * experimental prop to Show/Hide All option
+   */
+  hasSelectAll: PropTypes.bool,
+
   /**
    * Provide helper text that is used alongside the control label for
    * additional help
@@ -901,6 +950,11 @@ MultiSelect.propTypes = {
    */
   label: PropTypes.node.isRequired,
 
+  /**
+   * Provide Label for Select All option.
+   */
+  labelforSelectAll: PropTypes.string,
+
   /**
    * `true` to use the light version.
    */