feat(filterable-multiselect): New SelectAll Feature (#19884)

* feat(filterable-multi-select): new selectall feature and story

* fix(testing): bug fix to pass ci

* fix(select-all): hide select-all option when filtered items are disabled

* feat(select-all): add test cases

* fix(select-all): cursor padding

* chore: cleanup

* chore: cleanup fix

Author: maradwan26

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

@@ -21,6 +21,7 @@ import PropTypes from 'prop-types';
 import React, {
   cloneElement,
   forwardRef,
+  useCallback,
   useContext,
   useEffect,
   useLayoutEffect,
@@ -46,6 +47,7 @@ import ListBox, {
   type ListBoxSize,
   type ListBoxType,
 } from '../ListBox';
+import Checkbox from '../Checkbox';
 import { ListBoxTrigger, ListBoxSelection } from '../ListBox/next';
 import { match, keys } from '../../internal/keyboard';
 import { defaultItemToString } from './tools/itemToString';
@@ -389,17 +391,73 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
   );
   const [inputFocused, setInputFocused] = useState<boolean>(false);
 
+  const filteredItems = useMemo(
+    () => filterItems(items, { itemToString, inputValue }),
+    [items, inputValue, itemToString, filterItems]
+  );
+
+  const nonSelectAllItems = useMemo(
+    () => filteredItems.filter((item) => !(item as any).isSelectAll),
+    [filteredItems]
+  );
+  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 {
     selectedItems: controlledSelectedItems,
     onItemChange,
     clearSelection,
+    toggleAll,
   } = useSelection({
     disabled,
     initialSelectedItems,
     onChange,
     selectedItems: selected,
+    selectAll,
+    filteredItems,
   });
 
+  const selectAllStatus = useMemo(() => {
+    const selectable = nonSelectAllItems.filter(
+      (item) => !(item as any).disabled
+    );
+
+    const nonSelectedCount = selectable.filter(
+      (item) => !controlledSelectedItems.some((sel) => isEqual(sel, item))
+    ).length;
+
+    const totalCount = selectable.length;
+    return {
+      checked: totalCount > 0 && nonSelectedCount === 0,
+      indeterminate: nonSelectedCount > 0 && nonSelectedCount < totalCount,
+    };
+  }, [controlledSelectedItems, nonSelectAllItems]);
+
+  const handleSelectAllClick = useCallback(() => {
+    const selectable = nonSelectAllItems.filter((i) => !(i as any).disabled);
+    const { checked, indeterminate } = selectAllStatus;
+
+    // clear all options if select-all state is checked or indeterminate
+    if (checked || indeterminate) {
+      const remainingSelectedItems = controlledSelectedItems.filter(
+        (sel) => !filteredItems.some((e) => isEqual(e, sel))
+      );
+      toggleAll(remainingSelectedItems);
+
+      // select all options if select-all state is empty
+    } else {
+      const toSelect = selectable.filter(
+        (e) => !controlledSelectedItems.some((sel) => isEqual(sel, e))
+      );
+      toggleAll([...controlledSelectedItems, ...toSelect]);
+    }
+  }, [nonSelectAllItems, selectAllStatus, controlledSelectedItems, toggleAll]);
+
   const { refs, floatingStyles, middlewareData } = useFloating(
     autoAlign
       ? {
@@ -455,7 +513,14 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
   // memoize sorted items to reduce unnecessary expensive sort on rerender
   const sortedItems = useMemo(() => {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    return sortItems!(filterItems(items, { itemToString, inputValue }), {
+    const selectAllItem = items.find((item) => (item as any).isSelectAll);
+
+    const selectableRealItems = nonSelectAllItems.filter(
+      (item) => !(item as any).disabled
+    );
+
+    // Sort only non-select-all items, select-all item must stay at the top
+    const sortedReal = sortItems!(nonSelectAllItems, {
       selectedItems: {
         top: controlledSelectedItems,
         fixed: [],
@@ -465,6 +530,12 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
       compareItems,
       locale,
     });
+
+    // Only show select-all-item if there exist non-disabled filtered items to select
+    if (selectAllItem && selectableRealItems.length > 0) {
+      return [selectAllItem, ...sortedReal];
+    }
+    return sortedReal;
   }, [
     items,
     inputValue,
@@ -474,6 +545,8 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
     itemToString,
     compareItems,
     locale,
+    sortItems,
+    nonSelectAllItems,
   ]);
 
   const inline = type === 'inline';
@@ -614,14 +687,23 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
     }
     switch (type) {
       case InputKeyDownEnter:
+        if (sortedItems.length === 0) {
+          return changes;
+        }
         if (changes.selectedItem && changes.selectedItem.disabled !== true) {
-          onItemChange(changes.selectedItem);
+          if (changes.selectedItem.isSelectAll) {
+            handleSelectAllClick();
+          } else {
+            onItemChange(changes.selectedItem);
+          }
         }
         setHighlightedIndex(changes.selectedItem);
 
         return { ...changes, highlightedIndex: state.highlightedIndex };
       case ItemClick:
-        if (changes.selectedItem) {
+        if (changes.selectedItem.isSelectAll) {
+          handleSelectAllClick();
+        } else {
           onItemChange(changes.selectedItem);
         }
         setHighlightedIndex(changes.selectedItem);
@@ -752,6 +834,11 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
     ? cloneElement(candidate, { size: 'mini' })
     : null;
 
+  // exclude the select-all item from the count
+  const selectedItemsLength = controlledSelectedItems.filter(
+    (item: any) => !(item as any).isSelectAll
+  ).length;
+
   const className = cx(
     `${prefix}--multi-select`,
     `${prefix}--combo-box`,
@@ -765,6 +852,7 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
         controlledSelectedItems?.length > 0,
       [`${prefix}--multi-select--filterable--input-focused`]: inputFocused,
       [`${prefix}--multi-select--readonly`]: readOnly,
+      [`${prefix}--multi-select--selectall`]: selectAll,
     }
   );
 
@@ -938,7 +1026,7 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
                   textInput.current.focus();
                 }
               }}
-              selectionCount={controlledSelectedItems.length}
+              selectionCount={selectedItemsLength}
               translateWithId={translateWithId}
               disabled={disabled}
             />
@@ -993,10 +1081,17 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
         <ListBox.Menu {...menuProps}>
           {isOpen
             ? sortedItems.map((item, index) => {
-                const isChecked =
-                  controlledSelectedItems.filter((selected) =>
-                    isEqual(selected, item)
-                  ).length > 0;
+                let isChecked: boolean;
+                let isIndeterminate = false;
+                if ((item as any).isSelectAll) {
+                  isChecked = selectAllStatus.checked;
+                  isIndeterminate = selectAllStatus.indeterminate;
+                } else {
+                  isChecked =
+                    controlledSelectedItems.filter((selected) =>
+                      isEqual(selected, item)
+                    ).length > 0;
+                }
                 const itemProps = getItemProps({
                   item,
                   ['aria-selected']: isChecked,
@@ -1017,23 +1112,27 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
                   <ListBox.MenuItem
                     key={itemProps.id}
                     aria-label={itemText}
-                    isActive={isChecked}
+                    isActive={isChecked && !item['isSelectAll']}
                     isHighlighted={highlightedIndex === index}
                     title={itemText}
                     disabled={disabled}
                     {...modifiedItemProps}>
                     <div className={`${prefix}--checkbox-wrapper`}>
-                      <span
+                      <Checkbox
+                        id={`${itemProps.id}-item`}
+                        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}-item`}>
-                        {ItemToElement ? (
-                          <ItemToElement key={itemProps.id} {...item} />
-                        ) : (
-                          itemText
-                        )}
-                      </span>
+                        indeterminate={isIndeterminate}
+                        disabled={disabled}
+                        tabIndex={-1}
+                      />
                     </div>
                   </ListBox.MenuItem>
                 );

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

@@ -368,6 +368,25 @@ export const Filterable = (args) => {
   );
 };
 
+export const FilterableWithSelectAll = (args) => {
+  return (
+    <div
+      style={{
+        width: 300,
+      }}>
+      <FilterableMultiSelect
+        id="carbon-multiselect-example-3"
+        titleText="FilterableMultiSelect title"
+        helperText="This is helper text"
+        items={itemsWithSelectAll}
+        itemToString={(item) => (item ? item.text : '')}
+        selectionFeedback="top-after-reopen"
+        {...args}
+      />
+    </div>
+  );
+};
+
 Filterable.argTypes = {
   onChange: {
     action: 'onChange',