feat(multi-select, simple-select): add listActionButton & onListAction

src/components/select/filterable-select/filterable-select.mdx

@@ -83,9 +83,9 @@ will have the same width as the input.
 
 ### With Action Button
 
-Default Action Button will be rendered when the `listActionButton` prop is set to `true` on the Component.
+Setting the `listActionButton` prop to `true` renders a default `"Add New Item"` `Button`. However, a custom `Button` component can be passed as the `listActionButton` value via a node.
 
-A custom `Button` Component could be passed as the `listActionButton` value.
+We recommend this pattern for loading/adding new options to the `FilterableSelect`.
 
 <Canvas of={FilterableSelectStories.WithActionButton} />
 

src/components/select/filterable-select/filterable-select.stories.tsx

@@ -370,11 +370,7 @@ export const WithActionButton: Story = () => {
         label="color"
         value={value}
         onChange={(event) => setValue(event.target.value)}
-        listActionButton={
-          <Button iconType="add" iconPosition="after">
-            Add a New Element
-          </Button>
-        }
+        listActionButton
         onListAction={() => setIsOpen(true)}
       >
         {optionList}
@@ -384,7 +380,7 @@ export const WithActionButton: Story = () => {
         onCancel={() => setIsOpen(false)}
         title="Dialog component triggered on action"
       >
-        <Button onClick={addNew}>Add new</Button>
+        <Button onClick={addNew}>Add a New Element</Button>
       </Dialog>
     </Box>
   );

src/components/select/multi-select/components.test-pw.tsx

@@ -284,6 +284,65 @@ export const MultiSelectMultiColumnsComponent = (
   );
 };
 
+export const MultiSelectWithActionButtonComponent = () => {
+  const [value, setValue] = useState<string[]>([]);
+
+  function onChangeHandler(event: React.ChangeEvent<HTMLInputElement>) {
+    setValue((event.target.value as unknown) as string[]);
+  }
+
+  const [isOpen, setIsOpen] = useState(false);
+  const [optionList, setOptionList] = useState([
+    <Option text="Amber" value="amber" key="Amber" />,
+    <Option text="Black" value="black" key="Black" />,
+    <Option text="Blue" value="blue" key="Blue" />,
+    <Option text="Brown" value="brown" key="Brown" />,
+    <Option text="Green" value="green" key="Green" />,
+    <Option text="Amber" value="amber1" key="Amber1" />,
+    <Option text="Black" value="black1" key="Black1" />,
+    <Option text="Blue" value="blue1" key="Blue1" />,
+    <Option text="Brown" value="brown1" key="Brown1" />,
+    <Option text="Green" value="green1" key="Green1" />,
+  ]);
+  function addNew() {
+    const counter = optionList.length.toString();
+    setOptionList((newOptionList) => [
+      ...newOptionList,
+      <Option
+        text={`New${counter}`}
+        value={`val${counter}`}
+        key={`New${counter}`}
+      />,
+    ]);
+    setIsOpen(false);
+    setValue((prevValue) => [...prevValue, `val${counter}`]);
+  }
+  return (
+    <>
+      <MultiSelect
+        label="color"
+        value={value}
+        onChange={onChangeHandler}
+        listActionButton={
+          <Button iconType="add" iconPosition="after">
+            Add a New Element
+          </Button>
+        }
+        onListAction={() => setIsOpen(true)}
+      >
+        {optionList}
+      </MultiSelect>
+      <Dialog
+        open={isOpen}
+        onCancel={() => setIsOpen(false)}
+        title="Dialog component triggered on action"
+      >
+        <Button onClick={addNew}>Add new</Button>
+      </Dialog>
+    </>
+  );
+};
+
 export const MultiSelectMaxOptionsComponent = (
   props: Partial<MultiSelectProps>
 ) => {
@@ -365,6 +424,29 @@ export const MultiSelectCustomColorComponent = (
   );
 };
 
+export const MultiSelectListActionEventComponent = (
+  props: Partial<MultiSelectProps>
+) => {
+  return (
+    <MultiSelect
+      label="color"
+      labelInline
+      {...props}
+      listActionButton={
+        <Button iconType="add" iconPosition="after">
+          Add a New Element
+        </Button>
+      }
+    >
+      <Option text="Amber" value="1" />
+      <Option text="Black" value="2" />
+      <Option text="Blue" value="3" />
+      <Option text="Brown" value="4" />
+      <Option text="Green" value="5" />
+    </MultiSelect>
+  );
+};
+
 export const MultiSelectWithManyOptionsAndVirtualScrolling = () => (
   <MultiSelect
     name="virtualised"

src/components/select/multi-select/multi-select.component.tsx

@@ -7,6 +7,7 @@ import React, {
 } from "react";
 import invariant from "invariant";
 
+import { ButtonProps } from "../../button";
 import { filterOutStyledSystemSpacingProps } from "../../../style/utils";
 import SelectTextbox, {
   FormInputPropTypes,
@@ -55,6 +56,8 @@ export interface MultiSelectProps
   defaultValue?: string[] | Record<string, unknown>[];
   /** If true the loader animation is displayed in the option list */
   isLoading?: boolean;
+  /** True for default text button or a Button Component to be rendered */
+  listActionButton?: boolean | React.ReactElement<ButtonProps>;
   /** When true component will work in multi column mode.
    * Children should consist of OptionRow components in this mode
    */
@@ -65,6 +68,8 @@ export interface MultiSelectProps
   onFilterChange?: (filterText: string) => void;
   /** A custom callback for when the dropdown menu opens */
   onOpen?: () => void;
+  /** A callback for when the Action Button is triggered */
+  onListAction?: () => void;
   /** If true the Component opens on focus */
   openOnFocus?: boolean;
   /** SelectList table header, should consist of multiple th elements.
@@ -122,7 +127,9 @@ export const MultiSelect = React.forwardRef<HTMLInputElement, MultiSelectProps>(
       onKeyDown,
       openOnFocus = false,
       noResultsMessage,
+      listActionButton,
       placeholder,
+      onListAction,
       isLoading,
       tableHeader,
       multiColumn,
@@ -444,6 +451,17 @@ export const MultiSelect = React.forwardRef<HTMLInputElement, MultiSelectProps>(
       };
     }, [handleGlobalClick]);
 
+    useEffect(() => {
+      const hasListActionButton = listActionButton !== undefined;
+      const onListActionMissingMessage =
+        "onListAction prop required when using listActionButton prop";
+
+      invariant(
+        !hasListActionButton || (hasListActionButton && onListAction),
+        onListActionMissingMessage
+      );
+    }, [listActionButton, onListAction]);
+
     const onFilterChange = useStableCallback(
       onFilterChangeProp as (filterTextArg: unknown) => void
     );
@@ -529,6 +547,11 @@ export const MultiSelect = React.forwardRef<HTMLInputElement, MultiSelectProps>(
       isMouseDownReported.current = true;
     }
 
+    function handleOnListAction() {
+      setOpenState(false);
+      onListAction?.();
+    }
+
     function handleTextboxFocus(event: React.FocusEvent<HTMLInputElement>) {
       const triggerFocus = () => onFocus?.(event);
 
@@ -579,6 +602,12 @@ export const MultiSelect = React.forwardRef<HTMLInputElement, MultiSelectProps>(
           selectionConfirmed,
         } = optionData;
 
+        if (selectionType === "tab") {
+          setOpenState(false);
+          textboxRef?.focus();
+          return;
+        }
+
         if (selectionType === "navigationKey") {
           setHighlightedValue(newValue);
           setActiveDescendantId(selectedOptionId);
@@ -682,11 +711,13 @@ export const MultiSelect = React.forwardRef<HTMLInputElement, MultiSelectProps>(
         filterText={filterText.trim()}
         highlightedValue={highlightedValue}
         noResultsMessage={noResultsMessage}
+        listActionButton={listActionButton}
         isLoading={isLoading}
         tableHeader={tableHeader}
         multiColumn={multiColumn}
         listPlacement={listWidth !== undefined ? placement : listPlacement}
         listMaxHeight={listMaxHeight}
+        onListAction={handleOnListAction}
         flipEnabled={flipEnabled}
         multiselectValues={actualValue}
         isOpen={isOpen}

src/components/select/multi-select/multi-select.mdx

@@ -96,6 +96,14 @@ If there is no `id` prop specified on an object, then the exact objects will be
 
 <Canvas of={MultiSelectStories.WithObjectAsValue} />
 
+### With Action Button
+
+Setting the `listActionButton` prop to `true` renders a default `"Add New Item"` `Button`. However, a custom `Button` component can be passed as the `listActionButton` value via a node.
+
+We recommend this pattern for loading/adding new options to the `MultiSelect`.
+
+<Canvas of={MultiSelectStories.WithActionButton} />
+
 ### With isLoading prop
 
 When `isLoading` prop is passed, a loader will be appended at the end of the Select List. That functionality could be used to load the options asynchronously.

src/components/select/multi-select/multi-select.pw.tsx

@@ -9,9 +9,11 @@ import {
   MultiSelectLazyLoadTwiceComponent,
   MultiSelectObjectAsValueComponent,
   MultiSelectMultiColumnsComponent,
+  MultiSelectWithActionButtonComponent,
   MultiSelectCustomColorComponent,
   MultiSelectLongPillComponent,
   MultiSelectOnFilterChangeEventComponent,
+  MultiSelectListActionEventComponent,
   MultiSelectWithManyOptionsAndVirtualScrolling,
   MultiSelectNestedInDialog,
   MultiSelectErrorOnChangeNewValidation,
@@ -893,6 +895,82 @@ test.describe("MultiSelect component", () => {
     ).toBeVisible();
   });
 
+  test("should render list options with an action button and trigger Dialog on action", async ({
+    mount,
+    page,
+  }) => {
+    await mount(<MultiSelectWithActionButtonComponent />);
+
+    await dropdownButton(page).click();
+    await expect(selectListWrapper(page)).toBeVisible();
+    const addElementButtonElement = page.locator('[data-component="button"]');
+    await expect(addElementButtonElement).toBeVisible();
+    await expect(addElementButtonElement).toHaveText("Add a New Element");
+    const iconElement = page.locator('[type="add"]');
+    await expect(iconElement).toBeVisible();
+    await addElementButtonElement.click();
+    await expect(alertDialogPreview(page)).toBeVisible();
+  });
+
+  test("should render list options with an action button that is visible without scrolling and without affecting the list height", async ({
+    mount,
+    page,
+  }) => {
+    await mount(<MultiSelectWithActionButtonComponent />);
+
+    await dropdownButton(page).click();
+    await expect(selectListWrapper(page)).toBeVisible();
+    await expect(page.locator('[data-component="button"]')).toBeInViewport();
+    const selectListHeight = await selectListWrapper(
+      page
+    ).evaluate((wrapperElement) =>
+      parseInt(
+        window.getComputedStyle(wrapperElement).getPropertyValue("height")
+      )
+    );
+    await expect(selectListHeight).toBeGreaterThan(220);
+    await expect(selectListHeight).toBeLessThan(250);
+  });
+
+  test("when navigating with the keyboard, the selected option is not hidden behind an action button", async ({
+    mount,
+    page,
+  }) => {
+    await mount(<MultiSelectWithActionButtonComponent />);
+
+    await dropdownButton(page).click();
+    const inputElement = commonDataElementInputPreview(page);
+    for (let i = 0; i < 5; i++) {
+      // eslint-disable-next-line no-await-in-loop
+      await inputElement.focus();
+      // eslint-disable-next-line no-await-in-loop
+      await inputElement.press("ArrowDown");
+    }
+    await expect(selectOptionByText(page, "Green").nth(0)).toBeInViewport();
+  });
+
+  test("should add new list option from Add new Dialog", async ({
+    mount,
+    page,
+  }) => {
+    await mount(<MultiSelectWithActionButtonComponent />);
+
+    const newOption = "New10";
+    await dropdownButton(page).click();
+    await expect(selectListWrapper(page)).toBeVisible();
+    const addElementButtonElement = page.locator('[data-component="button"]');
+    await expect(addElementButtonElement).toBeVisible();
+    await addElementButtonElement.click();
+    await expect(alertDialogPreview(page)).toBeVisible();
+    await page.waitForTimeout(250);
+    const addNewButtonElement = page.getByRole("button", {
+      name: "Add New",
+    });
+    await expect(addNewButtonElement).toBeVisible();
+    await addNewButtonElement.click();
+    await expect(multiSelectPill(page)).toHaveAttribute("title", newOption);
+  });
+
   [
     ["3", "Blue"],
     ["7", "Pink"],
@@ -1273,6 +1351,23 @@ test.describe("Check events for MultiSelect component", () => {
     await expect(callbackArguments.length).toBe(1);
     await expect(callbackArguments[0]).toBe(text);
   });
+
+  test("should call onListAction event when the Action Button is clicked", async ({
+    mount,
+    page,
+  }) => {
+    let callbackCount = 0;
+    const callback = () => {
+      callbackCount += 1;
+    };
+    await mount(
+      <MultiSelectListActionEventComponent onListAction={callback} />
+    );
+
+    await dropdownButton(page).click();
+    await page.locator('[data-component="button"]').click();
+    await expect(callbackCount).toBe(1);
+  });
 });
 
 test.describe("Check virtual scrolling", () => {
@@ -1899,6 +1994,16 @@ test.describe("Accessibility tests for MultiSelect component", () => {
     });
   });
 
+  test("should pass accessibility tests with an action button and trigger Dialog on action", async ({
+    mount,
+    page,
+  }) => {
+    await mount(<MultiSelectWithActionButtonComponent />);
+
+    await dropdownButton(page).click();
+    await checkAccessibility(page, undefined, "scrollable-region-focusable");
+  });
+
   test("should pass accessibility tests with virtual scrolling", async ({
     mount,
     page,