@khanacademy/wonder-blocks-dropdown 5.2.1 → 5.3.1

package/src/components/__tests__/listbox.test.tsx

@@ -0,0 +1,425 @@
+import * as React from "react";
+import {render, screen} from "@testing-library/react";
+
+import {userEvent} from "@testing-library/user-event";
+import {RenderStateRoot} from "@khanacademy/wonder-blocks-core";
+import Listbox from "../listbox";
+import OptionItem from "../option-item";
+
+describe("Listbox", () => {
+    it("should render the listbox", () => {
+        // Arrange
+
+        // Act
+        render(
+            <Listbox value={null} selectionType="single">
+                <OptionItem label="option 1" value="option1" />
+                <OptionItem label="option 2" value="option2" />
+                <OptionItem label="option 3" value="option3" />
+            </Listbox>,
+            {wrapper: RenderStateRoot},
+        );
+
+        // Assert
+        expect(screen.getByRole("listbox")).toBeInTheDocument();
+    });
+
+    describe("focus", () => {
+        it("should focus on the listbox when tabbing", async () => {
+            // Arrange
+            render(
+                <Listbox selectionType="single" value="option2">
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Act
+            await userEvent.tab();
+
+            // Assert
+            expect(screen.getByRole("listbox")).toHaveFocus();
+        });
+
+        it("should blur the listbox when tabbing out", async () => {
+            // Arrange
+            render(
+                <Listbox selectionType="single" value="option2">
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Act
+            await userEvent.tab();
+            await userEvent.tab();
+
+            // Assert
+            expect(screen.getByRole("listbox")).not.toHaveFocus();
+        });
+
+        it("should give visual focus on the selected option item", async () => {
+            // Arrange
+            render(
+                <Listbox selectionType="single" value="option2" id="listbox">
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Act
+            await userEvent.tab();
+
+            // Assert
+            expect(screen.getByRole("listbox")).toHaveAttribute(
+                "aria-activedescendant",
+                "listbox-option-1",
+            );
+        });
+    });
+
+    describe("keyboard navigation", () => {
+        it("should focus on the first option item", async () => {
+            // Arrange
+            render(
+                <Listbox selectionType="single" value="option2" id="listbox">
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Focus on the listbox
+            await userEvent.tab();
+
+            // Act
+            await userEvent.keyboard("{home}");
+
+            // Assert
+            expect(screen.getByRole("listbox")).toHaveAttribute(
+                "aria-activedescendant",
+                "listbox-option-0",
+            );
+        });
+
+        it("should focus on the last option item", async () => {
+            // Arrange
+            render(
+                <Listbox selectionType="single" value="option1" id="listbox">
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Focus on the listbox
+            await userEvent.tab();
+
+            // Act
+            await userEvent.keyboard("{end}");
+
+            // Assert
+            expect(screen.getByRole("listbox")).toHaveAttribute(
+                "aria-activedescendant",
+                "listbox-option-2",
+            );
+        });
+        it("should focus on the next option item", async () => {
+            // Arrange
+            render(
+                <Listbox selectionType="single" value="option2" id="listbox">
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Focus on the listbox
+            await userEvent.tab();
+
+            // Act
+            await userEvent.keyboard("{arrowdown}");
+
+            // Assert
+            expect(screen.getByRole("listbox")).toHaveAttribute(
+                "aria-activedescendant",
+                "listbox-option-2",
+            );
+        });
+
+        it("should focus on the previous option item", async () => {
+            // Arrange
+            render(
+                <Listbox selectionType="single" value="option2" id="listbox">
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Focus on the listbox
+            await userEvent.tab();
+
+            // Act
+            await userEvent.keyboard("{arrowup}");
+
+            // Assert
+            expect(screen.getByRole("listbox")).toHaveAttribute(
+                "aria-activedescendant",
+                "listbox-option-0",
+            );
+        });
+
+        it("should navigate to the first option item when pressing arrow down on the last item", async () => {
+            // Arrange
+            render(
+                <Listbox selectionType="single" value="option3" id="listbox">
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Focus on the listbox
+            await userEvent.tab();
+
+            // Act
+            await userEvent.keyboard("{arrowdown}");
+
+            // Assert
+            expect(screen.getByRole("listbox")).toHaveAttribute(
+                "aria-activedescendant",
+                "listbox-option-0",
+            );
+        });
+
+        it("should navigate to the first option item when pressing arrow up on the first item", async () => {
+            // Arrange
+            render(
+                <Listbox selectionType="single" value="option1" id="listbox">
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Focus on the listbox
+            await userEvent.tab();
+
+            // Act
+            await userEvent.keyboard("{arrowup}");
+
+            // Assert
+            expect(screen.getByRole("listbox")).toHaveAttribute(
+                "aria-activedescendant",
+                "listbox-option-2",
+            );
+        });
+    });
+
+    describe("single selection", () => {
+        it("should select an option item when pressing Enter", async () => {
+            // Arrange
+            const onChange = jest.fn();
+            render(
+                <Listbox selectionType="single" value="" onChange={onChange}>
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Focus on the listbox
+            await userEvent.tab();
+
+            // Act
+            await userEvent.keyboard("{enter}");
+
+            // Assert
+            expect(onChange).toHaveBeenCalledWith("option1");
+        });
+
+        it("should select an item when pressing space", async () => {
+            // Arrange
+            const onChange = jest.fn();
+            render(
+                <Listbox selectionType="single" value="" onChange={onChange}>
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Focus on the listbox
+            await userEvent.tab();
+
+            // Act
+            await userEvent.keyboard(" ");
+
+            // Assert
+            expect(onChange).toHaveBeenCalledWith("option1");
+        });
+
+        it("should set the selected option item with aria-selected", async () => {
+            // Arrange
+            const onChange = jest.fn();
+            render(
+                <Listbox selectionType="single" value="" onChange={onChange}>
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Focus on the listbox
+            await userEvent.tab();
+
+            // Act
+            await userEvent.keyboard("{enter}");
+
+            // Assert
+            expect(
+                screen.getByRole("option", {name: "option 1"}),
+            ).toHaveAttribute("aria-selected", "true");
+        });
+
+        it("should select an option item when clicking on it", async () => {
+            // Arrange
+            const onChange = jest.fn();
+            render(
+                <Listbox selectionType="single" value="" onChange={onChange}>
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Act
+            await userEvent.click(
+                screen.getByRole("option", {name: "option 3"}),
+            );
+
+            // Assert
+            expect(onChange).toHaveBeenCalledWith("option3");
+        });
+
+        it("should not allow selecting an option item when disabled", async () => {
+            // Arrange
+            const onChange = jest.fn();
+            render(
+                <Listbox
+                    selectionType="single"
+                    value={null}
+                    onChange={onChange}
+                    disabled
+                >
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" disabled />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Act
+            await userEvent.click(
+                screen.getByRole("option", {name: "option 3"}),
+            );
+
+            // Assert
+            expect(onChange).not.toHaveBeenCalled();
+        });
+    });
+
+    describe("multiple selection", () => {
+        it("should select multiple option items when pressing Enter", async () => {
+            // Arrange
+            const onChange = jest.fn();
+            render(
+                <Listbox selectionType="multiple" onChange={onChange}>
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Focus on the listbox
+            await userEvent.tab();
+
+            // Act
+            await userEvent.keyboard("{enter}");
+            await userEvent.keyboard("{arrowdown}");
+            await userEvent.keyboard("{enter}");
+
+            // Assert
+            expect(onChange).toHaveBeenCalledWith(["option1", "option2"]);
+        });
+    });
+
+    describe("aria", () => {
+        it("should announce aria-labelledby correctly", () => {
+            // Arrange
+            render(
+                <>
+                    <Listbox
+                        value={null}
+                        selectionType="single"
+                        aria-labelledby="label"
+                    >
+                        <OptionItem label="option 1" value="option1" />
+                        <OptionItem label="option 2" value="option2" />
+                        <OptionItem label="option 3" value="option3" />
+                    </Listbox>
+                    <div id="label">Accessible label</div>
+                </>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Assert
+            expect(
+                screen.getByRole("listbox", {
+                    name: "Accessible label",
+                }),
+            ).toBeInTheDocument();
+        });
+
+        it("should announce aria-label correctly", () => {
+            // Arrange
+            render(
+                <Listbox
+                    value={null}
+                    selectionType="single"
+                    aria-label="Accessible label"
+                >
+                    <OptionItem label="option 1" value="option1" />
+                    <OptionItem label="option 2" value="option2" />
+                    <OptionItem label="option 3" value="option3" />
+                </Listbox>,
+                {wrapper: RenderStateRoot},
+            );
+
+            // Assert
+            expect(
+                screen.getByRole("listbox", {
+                    name: "Accessible label",
+                }),
+            ).toBeInTheDocument();
+        });
+    });
+});

package/src/components/listbox.tsx

@@ -0,0 +1,176 @@
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+import {
+    StyleType,
+    useUniqueIdWithMock,
+    View,
+} from "@khanacademy/wonder-blocks-core";
+import {color} from "@khanacademy/wonder-blocks-tokens";
+
+import {useListbox} from "../hooks/use-listbox";
+import {MaybeValueOrValues, OptionItemComponent} from "../util/types";
+
+type Props = {
+    /**
+     * The list of items to display in the listbox.
+     */
+    children: Array<OptionItemComponent>;
+
+    /**
+     * Whether the use can select more than one option item. Defaults to
+     * `single`.
+     *
+     * If `multiple` is selected, `aria-multiselectable={true}` is set
+     * internally in the listbox element.
+     */
+    selectionType: "single" | "multiple";
+
+    /**
+     * The value of the currently selected items.
+     */
+    value?: MaybeValueOrValues;
+
+    /**
+     * Callback for when the selection changes. The value passed as an argument
+     * is an updated array of the selected value(s).
+     */
+    onChange?: (value: MaybeValueOrValues) => void;
+
+    /**
+     * Provides a label for the listbox.
+     */
+    "aria-label"?: string;
+
+    /**
+     * A reference to the element that describes the listbox.
+     */
+    "aria-labelledby"?: string;
+
+    /**
+     * Whether the listbox is disabled.
+     *
+     * A disabled combobox does not support interaction, but it supports focus
+     * for a11y reasons. It internally maps to`aria-disabled`. Defaults to
+     * false.
+     */
+    disabled?: boolean;
+
+    /**
+     * The unique identifier of the listbox element.
+     */
+    id?: string;
+
+    /**
+     * TODO(WB-1678): Add async support to the listbox.
+     *
+     * Whether to display the loading state to let the user know that the
+     * results are being loaded asynchronously. Defaults to false.
+     */
+    loading?: boolean;
+
+    /**
+     * Optional custom styles applied to the listbox container.
+     */
+    style?: StyleType;
+
+    /**
+     * Includes the listbox in the page tab sequence.
+     */
+    tabIndex?: number;
+
+    /**
+     * Test ID used for e2e testing.
+     */
+    testId?: string;
+};
+
+/**
+ * A `Listbox` component presents a list of options and allows a user to select
+ * one or more of them. A listbox that allows a single option to be chosen is a
+ * single-select listbox; one that allows multiple options to be selected is a
+ * multi-select listbox.
+ *
+ * ### Usage
+ *
+ * ```tsx
+ * import {Listbox} from "@khanacademy/wonder-blocks-dropdown";
+ *
+ * <Listbox>
+ *  <OptionItem label="Apple" value="apple" />
+ *  <OptionItem disabled label="Strawberry" value="strawberry" />
+ *  <OptionItem label="Pear" value="pear" />
+ * </Listbox>
+ * ```
+ */
+export default function Listbox(props: Props) {
+    const {
+        children,
+        disabled,
+        id,
+        onChange,
+        selectionType = "single",
+        style,
+        tabIndex = 0,
+        testId,
+        value,
+        "aria-label": ariaLabel,
+        "aria-labelledby": ariaLabelledby,
+    } = props;
+
+    const ids = useUniqueIdWithMock("listbox");
+    const uniqueId = id ?? ids.get("id");
+
+    const {
+        focusedIndex,
+        isListboxFocused,
+        renderList,
+        selected,
+        // event handlers
+        handleKeyDown,
+        handleKeyUp,
+        handleFocus,
+        handleBlur,
+    } = useListbox({children, disabled, id: uniqueId, selectionType, value});
+    React.useEffect(() => {
+        // If the value changes, update the parent component.
+        if (selected && selected !== value) {
+            onChange?.(selected);
+        }
+    }, [onChange, selected, value]);
+
+    return (
+        <View
+            role="listbox"
+            aria-disabled={disabled}
+            id={uniqueId}
+            style={[styles.listbox, style, disabled && styles.disabled]}
+            tabIndex={tabIndex}
+            onKeyDown={handleKeyDown}
+            onKeyUp={handleKeyUp}
+            onFocus={handleFocus}
+            onBlur={handleBlur}
+            testId={testId}
+            // This is used to inform assistive technology users of the
+            // currently active element when focused.
+            // NOTE: This uses visual focus, not actual DOM focus.
+            // @see https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_focus_vs_selection
+            aria-activedescendant={
+                isListboxFocused ? renderList[focusedIndex].props.id : undefined
+            }
+            aria-label={ariaLabel}
+            aria-labelledby={ariaLabelledby}
+            aria-multiselectable={selectionType === "multiple"}
+        >
+            {renderList}
+        </View>
+    );
+}
+
+const styles = StyleSheet.create({
+    listbox: {
+        outline: "none",
+    },
+    disabled: {
+        color: color.offBlack64,
+    },
+});

package/src/components/multi-select.tsx

@@ -18,6 +18,7 @@ import OptionItem from "./option-item";
 import type {
     DropdownItem,
     OpenerProps,
+    OptionItemComponent,
     OptionItemComponentArray,
 } from "../util/types";
 import {getLabel} from "../util/helpers";
@@ -406,12 +407,8 @@ export default class MultiSelect extends React.Component<Props, State> {
                     -1,
         );
 
-        const lastSelectedChildren: React.ReactElement<
-            React.ComponentProps<typeof OptionItem>
-        >[] = [];
-        const restOfTheChildren: React.ReactElement<
-            React.ComponentProps<typeof OptionItem>
-        >[] = [];
+        const lastSelectedChildren: OptionItemComponentArray = [];
+        const restOfTheChildren: OptionItemComponentArray = [];
         for (const child of filteredChildren) {
             if (lastSelectedValues.includes(child.props.value)) {
                 lastSelectedChildren.push(child);
@@ -440,23 +437,20 @@ export default class MultiSelect extends React.Component<Props, State> {
         ];
     }
 
-    mapOptionItemToDropdownItem: (
-        option: React.ReactElement<React.ComponentProps<typeof OptionItem>>,
-    ) => DropdownItem = (
-        option: React.ReactElement<React.ComponentProps<typeof OptionItem>>,
-    ): DropdownItem => {
-        const {selectedValues} = this.props;
-        const {disabled, value} = option.props;
-        return {
-            component: option,
-            focusable: !disabled,
-            populatedProps: {
-                onToggle: this.handleToggle,
-                selected: selectedValues.includes(value),
-                variant: "checkbox",
-            },
+    mapOptionItemToDropdownItem: (option: OptionItemComponent) => DropdownItem =
+        (option: OptionItemComponent): DropdownItem => {
+            const {selectedValues} = this.props;
+            const {disabled, value} = option.props;
+            return {
+                component: option,
+                focusable: !disabled,
+                populatedProps: {
+                    onToggle: this.handleToggle,
+                    selected: selectedValues.includes(value),
+                    variant: "checkbox",
+                },
+            };
         };
-    };
 
     handleOpenerRef: (node?: any) => void = (node: any) => {
         const openerElement = ReactDOM.findDOMNode(node) as HTMLElement;