@khanacademy/wonder-blocks-dropdown 5.2.1 → 5.3.1

package/src/components/option-item.tsx

@@ -5,7 +5,12 @@ import {DetailCell} from "@khanacademy/wonder-blocks-cell";
 import {mix, color, spacing} from "@khanacademy/wonder-blocks-tokens";
 import {LabelMedium, LabelSmall} from "@khanacademy/wonder-blocks-typography";
 
-import {AriaProps, StyleType, View} from "@khanacademy/wonder-blocks-core";
+import {
+    addStyle,
+    AriaProps,
+    StyleType,
+    View,
+} from "@khanacademy/wonder-blocks-core";
 
 import {Strut} from "@khanacademy/wonder-blocks-layout";
 import Check from "./check";
@@ -50,6 +55,13 @@ type OptionProps = AriaProps & {
      * @ignore
      */
     selected: boolean;
+    /**
+     * Whether this item is focused. Auto-populated by listbox in combination of
+     * aria-activedescendant.
+     * @ignore
+     */
+    focused: boolean;
+
     /**
      * Aria role to use, defaults to "option".
      */
@@ -70,6 +82,21 @@ type OptionProps = AriaProps & {
      * @ignore
      */
     style?: StyleType;
+    /**
+     * Injected by the parent component to determine how we are going to handle
+     * the component states (hovered, focused, selected, etc.)
+     * Defaults to "dropdown".
+     * @ignore
+     */
+    parentComponent?: "dropdown" | "listbox";
+
+    /**
+     * The unique identifier of the option item.
+     *
+     * This is used to identify the option item in the listbox so that it can be
+     * focused programmatically (e.g. when the user presses the arrow keys).
+     */
+    id?: string;
 
     /**
      * Inherited from WB Cell.
@@ -104,12 +131,15 @@ type OptionProps = AriaProps & {
 
 type DefaultProps = {
     disabled: OptionProps["disabled"];
+    focused: OptionProps["focused"];
     horizontalRule: OptionProps["horizontalRule"];
     onToggle: OptionProps["onToggle"];
     role: OptionProps["role"];
     selected: OptionProps["selected"];
 };
 
+const StyledListItem = addStyle("li");
+
 /**
  * For option items that can be selected in a dropdown, selection denoted either
  * with a check ✔️ or a checkbox ☑️. Use as children in SingleSelect or
@@ -122,6 +152,7 @@ export default class OptionItem extends React.Component<OptionProps> {
     }
     static defaultProps: DefaultProps = {
         disabled: false,
+        focused: false,
         horizontalRule: "none",
         onToggle: () => void 0,
         role: "option",
@@ -145,17 +176,17 @@ export default class OptionItem extends React.Component<OptionProps> {
         }
     };
 
-    render(): React.ReactNode {
+    renderCell(): React.ReactNode {
         const {
             disabled,
             label,
-            role,
             selected,
             testId,
-            style,
             leftAccessory,
             horizontalRule,
+            parentComponent,
             rightAccessory,
+            style,
             subtitle1,
             subtitle2,
             // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -164,6 +195,7 @@ export default class OptionItem extends React.Component<OptionProps> {
             onClick,
             onToggle,
             variant,
+            role,
             /* eslint-enable @typescript-eslint/no-unused-vars */
             ...sharedProps
         } = this.props;
@@ -180,10 +212,16 @@ export default class OptionItem extends React.Component<OptionProps> {
             <DetailCell
                 disabled={disabled}
                 horizontalRule={horizontalRule}
-                rootStyle={defaultStyle}
+                rootStyle={
+                    parentComponent === "listbox"
+                        ? styles.listboxItem
+                        : defaultStyle
+                }
                 style={styles.itemContainer}
-                aria-selected={selected ? "true" : "false"}
-                role={role}
+                aria-selected={
+                    parentComponent !== "listbox" && selected ? "true" : "false"
+                }
+                role={parentComponent !== "listbox" ? role : undefined}
                 testId={testId}
                 leftAccessory={
                     <>
@@ -220,17 +258,77 @@ export default class OptionItem extends React.Component<OptionProps> {
                         </LabelSmall>
                     ) : undefined
                 }
-                onClick={this.handleClick}
+                onClick={
+                    parentComponent !== "listbox" ? this.handleClick : undefined
+                }
                 {...sharedProps}
             />
         );
     }
+
+    render(): React.ReactNode {
+        const {disabled, focused, parentComponent, role, selected} = this.props;
+
+        if (parentComponent === "listbox") {
+            return (
+                <StyledListItem
+                    onMouseDown={(e) => {
+                        // Prevents the combobox from losing focus when clicking
+                        // on the option item.
+                        e.preventDefault();
+                    }}
+                    onClick={this.handleClick}
+                    style={[
+                        styles.reset,
+                        styles.item,
+                        focused && styles.itemFocused,
+                        disabled && styles.itemDisabled,
+                    ]}
+                    role={role}
+                    aria-selected={selected ? "true" : "false"}
+                    aria-disabled={disabled ? "true" : "false"}
+                    id={this.props.id}
+                    tabIndex={-1}
+                >
+                    {this.renderCell()}
+                </StyledListItem>
+            );
+        }
+
+        return this.renderCell();
+    }
 }
 
 const {blue, white, offBlack} = color;
 
+const focusedStyle = {
+    // Override the default focus state for the cell element, so that it
+    // can be added programmatically to the button element.
+    borderRadius: spacing.xxxSmall_4,
+    outline: `${spacing.xxxxSmall_2}px solid ${color.blue}`,
+    outlineOffset: -spacing.xxxxSmall_2,
+};
+
 const styles = StyleSheet.create({
+    reset: {
+        margin: 0,
+        padding: 0,
+        border: 0,
+        background: "none",
+        outline: "none",
+        fontSize: "100%",
+        verticalAlign: "baseline",
+        textAlign: "left",
+        textDecoration: "none",
+        listStyle: "none",
+        cursor: "pointer",
+    },
+    listboxItem: {
+        backgroundColor: "transparent",
+        color: "inherit",
+    },
     item: {
+        backgroundColor: color.white,
         // Reset the default styles for the cell element so it can grow
         // vertically.
         minHeight: "unset",
@@ -238,13 +336,7 @@ const styles = StyleSheet.create({
         /**
          * States
          */
-        ":focus": {
-            // Override the default focus state for the cell element, so that it
-            // can be added programmatically to the button element.
-            borderRadius: spacing.xxxSmall_4,
-            outline: `${spacing.xxxxSmall_2}px solid ${color.blue}`,
-            outlineOffset: -spacing.xxxxSmall_2,
-        },
+        ":focus": focusedStyle,
 
         ":focus-visible": {
             // Override the default focus-visible state for the cell element, so
@@ -259,6 +351,22 @@ const styles = StyleSheet.create({
             background: blue,
         },
 
+        [":active[aria-selected=false]" as any]: {},
+
+        // disabled
+        [":hover[aria-disabled=true]" as any]: {
+            cursor: "not-allowed",
+        },
+
+        [":is([aria-disabled=true])" as any]: {
+            color: color.offBlack32,
+            ":focus-visible": {
+                // Prevent the focus ring from being displayed when the cell is
+                // disabled.
+                outline: "none",
+            },
+        },
+
         // Allow hover styles on non-touch devices only. This prevents an
         // issue with hover being sticky on touch devices (e.g. mobile).
         ["@media not (hover: hover)" as any]: {
@@ -309,6 +417,10 @@ const styles = StyleSheet.create({
             color: mix(color.fadedBlue16, white),
         },
     },
+    itemFocused: focusedStyle,
+    itemDisabled: {
+        outlineColor: color.offBlack32,
+    },
     itemContainer: {
         minHeight: "unset",
         // Make sure that the item is always at least as tall as 40px.

package/src/hooks/use-listbox.tsx

@@ -0,0 +1,224 @@
+import * as React from "react";
+import {updateMultipleSelection} from "../util/selection";
+import {MaybeValueOrValues, OptionItemComponent} from "../util/types";
+
+type Props = {
+    /**
+     * The list of items to display in the listbox.
+     */
+    children: Array<OptionItemComponent>;
+    /**
+     * Whether the listbox is disabled.
+     */
+    disabled: boolean | undefined;
+    /**
+     * The unique identifier of the listbox element.
+     */
+    id: string;
+    /**
+     * The value of the currently selected items.
+     */
+    value?: MaybeValueOrValues;
+    /**
+     * The type of selection that the listbox supports.
+     */
+    selectionType: "single" | "multiple";
+};
+
+/**
+ * Hook for managing the state of a listbox.
+ *
+ * It manages how the options are rendered and how the listbox behaves.
+ *
+ * This includes:
+ * - Keyboard navigation.
+ * - Selection management.
+ */
+export function useListbox({
+    children: options,
+    disabled,
+    id,
+    selectionType = "single",
+    value,
+}: Props) {
+    // find the index of the first selected Item
+    const selectedValueIndex = React.useMemo(() => {
+        const firstValue = Array.isArray(value) ? value[0] : value;
+        if (!firstValue || firstValue === "") {
+            // Focus on the first item if no value is selected
+            return 0;
+        }
+        return options.findIndex((item) => item.props.value === firstValue);
+    }, [options, value]);
+    // The index of the currently focused item in the listbox.
+    const [focusedIndex, setFocusedIndex] = React.useState(selectedValueIndex);
+    // Whether the listbox is currently focused.
+    const [isListboxFocused, setIsListboxFocused] = React.useState(false);
+
+    const [selected, setSelected] = React.useState(value);
+
+    const focusItem = (index: number) => {
+        setFocusedIndex(index);
+    };
+
+    const focusPreviousItem = React.useCallback(() => {
+        if (focusedIndex === 0) {
+            focusItem(options.length - 1);
+        } else {
+            focusItem(focusedIndex - 1);
+        }
+    }, [options, focusedIndex]);
+
+    const focusNextItem = React.useCallback(() => {
+        if (focusedIndex === options.length - 1) {
+            focusItem(0);
+        } else {
+            focusItem(focusedIndex + 1);
+        }
+    }, [options, focusedIndex]);
+
+    const selectOption = React.useCallback(
+        (index: number) => {
+            const optionItem = options[index] as OptionItemComponent;
+
+            if (optionItem.props.disabled) {
+                return;
+            }
+
+            if (selectionType === "single") {
+                setSelected(optionItem.props.value);
+            } else {
+                setSelected((prevSelected) => {
+                    const newSelectedValue = updateMultipleSelection(
+                        prevSelected as Array<string>,
+                        optionItem.props.value,
+                    );
+
+                    return newSelectedValue;
+                });
+            }
+        },
+        [options, selectionType],
+    );
+
+    const handleKeyDown = React.useCallback(
+        (event: React.KeyboardEvent) => {
+            const {key} = event;
+
+            switch (key) {
+                case "ArrowUp":
+                    event.preventDefault();
+                    focusPreviousItem();
+                    return;
+                case "ArrowDown":
+                    event.preventDefault();
+                    focusNextItem();
+                    return;
+                case "Home":
+                    event.preventDefault();
+                    focusItem(0);
+                    return;
+                case "End":
+                    event.preventDefault();
+                    focusItem(options.length - 1);
+                    return;
+                case "Enter":
+                case " ":
+                    // Prevent form submission
+                    event.preventDefault();
+
+                    selectOption(focusedIndex);
+                    return;
+            }
+        },
+        [focusNextItem, focusPreviousItem, focusedIndex, options, selectOption],
+    );
+
+    // Some keys should be handled during the keyup event instead.
+    const handleKeyUp = React.useCallback((event: React.KeyboardEvent) => {
+        switch (event.key) {
+            case " ":
+                // Prevent space from scrolling down the page
+                event.preventDefault();
+                return;
+        }
+    }, []);
+
+    const handleFocus = React.useCallback(() => {
+        if (!disabled) {
+            setIsListboxFocused(true);
+        }
+    }, [disabled]);
+
+    const handleBlur = React.useCallback(() => {
+        if (!disabled) {
+            setIsListboxFocused(false);
+        }
+    }, [disabled]);
+
+    const handleClick = React.useCallback(
+        (value: string) => {
+            const index = options.findIndex(
+                (item) => item.props.value === value,
+            );
+
+            const isOptionDisabled = options[index].props.disabled;
+
+            if (disabled || isOptionDisabled) {
+                return;
+            }
+
+            focusItem(index);
+            selectOption(index);
+        },
+        [disabled, options, selectOption],
+    );
+
+    const renderList = React.useMemo(() => {
+        return options.map((component, index) => {
+            const isSelected =
+                selected?.includes(component.props.value) || false;
+            const optionId = id ? `${id}-option-${index}` : `option-${index}`;
+
+            // Renders option items and pass the extra props needed to manage
+            // the listbox state.
+            return React.cloneElement(component, {
+                key: index,
+                focused: isListboxFocused && index === focusedIndex,
+                disabled: component.props.disabled || disabled || false,
+                selected: isSelected,
+                variant: selectionType === "single" ? "check" : "checkbox",
+                parentComponent: "listbox",
+                id: optionId,
+                onToggle: () => {
+                    handleClick(component.props.value);
+                },
+                role: "option",
+            });
+        });
+    }, [
+        options,
+        selected,
+        id,
+        isListboxFocused,
+        focusedIndex,
+        disabled,
+        selectionType,
+        handleClick,
+    ]);
+
+    return {
+        isListboxFocused,
+        // current option focused
+        focusedIndex,
+        // list of options
+        renderList,
+        // selected value(s)
+        selected,
+        // handlers
+        handleKeyDown,
+        handleKeyUp,
+        handleFocus,
+        handleBlur,
+    };
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import SeparatorItem from "./components/separator-item";
 import ActionMenu from "./components/action-menu";
 import SingleSelect from "./components/single-select";
 import MultiSelect from "./components/multi-select";
+import Listbox from "./components/listbox";
 
 import type {Labels} from "./components/multi-select";
 import type {SingleSelectLabels} from "./components/single-select";
@@ -15,6 +16,7 @@ export {
     ActionMenu,
     SingleSelect,
     MultiSelect,
+    Listbox,
 };
 
 export type {Labels, SingleSelectLabels};

package/src/util/__tests__/selection.test.ts

@@ -0,0 +1,50 @@
+import {updateMultipleSelection} from "../selection";
+
+describe("updateMultipleSelection", () => {
+    it("should create a new selection if there is no previous selection", () => {
+        // Arrange
+        const previousSelection = null;
+        const value = "apple";
+
+        // Act
+        const result = updateMultipleSelection(previousSelection, value);
+
+        // Assert
+        expect(result).toEqual(["apple"]);
+    });
+
+    it("should create a new selection if the previous selection is empty", () => {
+        // Arrange
+        const value = "apple";
+
+        // Act
+        const result = updateMultipleSelection([], value);
+
+        // Assert
+        expect(result).toEqual(["apple"]);
+    });
+
+    it("should add the value to the selection", () => {
+        // Arrange
+        const previousSelection = ["pear", "grape"];
+        const value = "apple";
+
+        // Act
+        const result = updateMultipleSelection(previousSelection, value);
+
+        // Assert
+        expect(result).toEqual(["pear", "grape", "apple"]);
+    });
+
+    it("should remove the value from the selection", () => {
+        // Arrange
+        const previousSelection = ["pear", "grape", "apple"];
+        const value = "grape";
+
+        // Act
+        const result = updateMultipleSelection(previousSelection, value);
+
+        // Assert
+        expect(result).toEqual(["pear", "apple"]);
+    });
+});

package/src/util/selection.ts

@@ -0,0 +1,16 @@
+import {MaybeString} from "./types";
+
+export function updateMultipleSelection(
+    previousSelection: Array<MaybeString> | null | undefined,
+    value = "",
+) {
+    if (!previousSelection) {
+        return [value];
+    }
+
+    return previousSelection.includes(value)
+        ? // Item is already selected, remove it from the list
+          previousSelection.filter((item) => item !== value)
+        : // Item is not selected yet, add it to the list
+          [...previousSelection, value];
+}

package/src/util/types.ts

@@ -46,6 +46,15 @@ export type OpenerProps = ClickableState & {
     opened: boolean;
 };
 
-export type OptionItemComponentArray = React.ReactElement<
-    React.ComponentProps<typeof OptionItem>
->[];
+export type OptionItemComponent = React.ReactElement<
+    PropsFor<typeof OptionItem>
+>;
+
+export type OptionItemComponentArray = OptionItemComponent[];
+
+/**
+ * Allows optional values to be passed to the listbox.
+ */
+export type MaybeString = string | null | undefined;
+
+export type MaybeValueOrValues = MaybeString | Array<MaybeString>;