@khanacademy/wonder-blocks-dropdown 2.9.4 → 2.10.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @khanacademy/wonder-blocks-dropdown
 
+## 2.10.0
+
+### Minor Changes
+
+-   0e773ce6: Add `autoFocus` and `enableTypeAhead` props to improve keyboard navigation with the `SingleSelect` component
+
+## 2.9.5
+
+### Patch Changes
+
+-   ceb111df: ClickableBehavior no longer has tabIndex 0 by default. It must be passed in.
+-   Updated dependencies [ceb111df]
+    -   @khanacademy/wonder-blocks-clickable@2.4.0
+    -   @khanacademy/wonder-blocks-modal@3.0.1
+    -   @khanacademy/wonder-blocks-search-field@1.0.13
+
 ## 2.9.4
 
 ### Patch Changes

package/dist/es/index.js

@@ -302,7 +302,8 @@ class OptionItem extends React.Component {
     return React.createElement(ClickableBehavior, {
       disabled: disabled,
       onClick: this.handleClick,
-      role: role
+      role: role,
+      tabIndex: 0
     }, (state, childrenProps) => {
       const {
         pressed,
@@ -748,13 +749,14 @@ class DropdownCore extends React.Component {
 
     this.handleKeyDown = event => {
       const {
+        enableTypeAhead,
         onOpenChanged,
         open,
         searchText
       } = this.props;
       const keyCode = event.which || event.keyCode;
 
-      if (getStringForKey(event.key)) {
+      if (enableTypeAhead && getStringForKey(event.key)) {
         event.stopPropagation();
         this.textSuggestion += event.key;
         this.handleKeyDownDebounced(this.textSuggestion);
@@ -913,7 +915,7 @@ class DropdownCore extends React.Component {
 
   componentDidMount() {
     this.updateEventListeners();
-    this.initialFocusItem();
+    this.maybeFocusInitialItem();
   }
 
   componentDidUpdate(prevProps) {
@@ -923,7 +925,7 @@ class DropdownCore extends React.Component {
 
     if (prevProps.open !== open) {
       this.updateEventListeners();
-      this.initialFocusItem();
+      this.maybeFocusInitialItem();
     } else if (open) {
       const {
         itemRefs,
@@ -972,11 +974,16 @@ class DropdownCore extends React.Component {
     }
   }
 
-  initialFocusItem() {
+  maybeFocusInitialItem() {
     const {
+      autoFocus,
       open
     } = this.props;
 
+    if (!autoFocus) {
+      return;
+    }
+
     if (open) {
       this.resetFocusedIndex();
       this.scheduleToFocusCurrentItem();
@@ -1268,6 +1275,8 @@ class DropdownCore extends React.Component {
 
 DropdownCore.defaultProps = {
   alignment: "left",
+  autoFocus: true,
+  enableTypeAhead: true,
   labels: {
     clearSearch: defaultLabels.clearSearch,
     filter: defaultLabels.filter,
@@ -1811,7 +1820,7 @@ const _generateStyles = (light, placeholder) => {
   return stateStyles[styleKey];
 };
 
-const _excluded$1 = ["children", "disabled", "id", "light", "opener", "placeholder", "selectedValue", "testId", "alignment", "dropdownStyle", "isFilterable", "labels", "onChange", "onToggle", "opened", "style", "className"];
+const _excluded$1 = ["children", "disabled", "id", "light", "opener", "placeholder", "selectedValue", "testId", "alignment", "autoFocus", "dropdownStyle", "enableTypeAhead", "isFilterable", "labels", "onChange", "onToggle", "opened", "style", "className"];
 class SingleSelect extends React.Component {
   constructor(props) {
     super(props);
@@ -1963,9 +1972,11 @@ class SingleSelect extends React.Component {
   render() {
     const {
       alignment,
+      autoFocus,
       children,
       className,
       dropdownStyle,
+      enableTypeAhead,
       isFilterable,
       labels,
       light,
@@ -1981,6 +1992,8 @@ class SingleSelect extends React.Component {
       role: "listbox",
       selectionType: "single",
       alignment: alignment,
+      autoFocus: autoFocus,
+      enableTypeAhead: enableTypeAhead,
       dropdownStyle: [isFilterable && filterableDropdownStyle, selectDropdownStyle, dropdownStyle],
       initialFocusedIndex: this.selectedIndex,
       items: items,
@@ -2001,7 +2014,9 @@ class SingleSelect extends React.Component {
 }
 SingleSelect.defaultProps = {
   alignment: "left",
+  autoFocus: true,
   disabled: false,
+  enableTypeAhead: true,
   light: false,
   labels: {
     clearSearch: defaultLabels.clearSearch,

package/dist/index.js

@@ -536,7 +536,8 @@ class OptionItem extends react__WEBPACK_IMPORTED_MODULE_1__["Component"] {
     return /*#__PURE__*/react__WEBPACK_IMPORTED_MODULE_1__["createElement"](ClickableBehavior, {
       disabled: disabled,
       onClick: this.handleClick,
-      role: role
+      role: role,
+      tabIndex: 0
     }, (state, childrenProps) => {
       const {
         pressed,
@@ -819,13 +820,14 @@ class DropdownCore extends react__WEBPACK_IMPORTED_MODULE_0__["Component"] {
 
     this.handleKeyDown = event => {
       const {
+        enableTypeAhead,
         onOpenChanged,
         open,
         searchText
       } = this.props;
       const keyCode = event.which || event.keyCode; // Listen for the keydown events if we are using ASCII characters.
 
-      if (Object(_util_helpers_js__WEBPACK_IMPORTED_MODULE_14__[/* getStringForKey */ "b"])(event.key)) {
+      if (enableTypeAhead && Object(_util_helpers_js__WEBPACK_IMPORTED_MODULE_14__[/* getStringForKey */ "b"])(event.key)) {
         event.stopPropagation();
         this.textSuggestion += event.key; // Trigger the filter logic only after the debounce is resolved.
 
@@ -1016,7 +1018,7 @@ class DropdownCore extends react__WEBPACK_IMPORTED_MODULE_0__["Component"] {
 
   componentDidMount() {
     this.updateEventListeners();
-    this.initialFocusItem();
+    this.maybeFocusInitialItem();
   }
 
   componentDidUpdate(prevProps) {
@@ -1026,7 +1028,7 @@ class DropdownCore extends react__WEBPACK_IMPORTED_MODULE_0__["Component"] {
 
     if (prevProps.open !== open) {
       this.updateEventListeners();
-      this.initialFocusItem();
+      this.maybeFocusInitialItem();
     } // If the menu changed, but from open to open, figure out if we need
     // to recalculate the focus somehow.
     else if (open) {
@@ -1096,11 +1098,16 @@ class DropdownCore extends react__WEBPACK_IMPORTED_MODULE_0__["Component"] {
   // to closed or vice versa
 
 
-  initialFocusItem() {
+  maybeFocusInitialItem() {
     const {
+      autoFocus,
       open
     } = this.props;
 
+    if (!autoFocus) {
+      return;
+    }
+
     if (open) {
       this.resetFocusedIndex();
       this.scheduleToFocusCurrentItem();
@@ -1455,6 +1462,8 @@ class DropdownCore extends react__WEBPACK_IMPORTED_MODULE_0__["Component"] {
 
 DropdownCore.defaultProps = {
   alignment: "left",
+  autoFocus: true,
+  enableTypeAhead: true,
   labels: {
     clearSearch: _util_constants_js__WEBPACK_IMPORTED_MODULE_12__[/* defaultLabels */ "d"].clearSearch,
     filter: _util_constants_js__WEBPACK_IMPORTED_MODULE_12__[/* defaultLabels */ "d"].filter,
@@ -2286,7 +2295,9 @@ class SingleSelect extends react__WEBPACK_IMPORTED_MODULE_1__["Component"] {
 
       /* eslint-disable no-unused-vars */
       alignment,
+      autoFocus,
       dropdownStyle,
+      enableTypeAhead,
       isFilterable,
       labels,
       onChange,
@@ -2323,9 +2334,11 @@ class SingleSelect extends react__WEBPACK_IMPORTED_MODULE_1__["Component"] {
   render() {
     const {
       alignment,
+      autoFocus,
       children,
       className,
       dropdownStyle,
+      enableTypeAhead,
       isFilterable,
       labels,
       light,
@@ -2341,6 +2354,8 @@ class SingleSelect extends react__WEBPACK_IMPORTED_MODULE_1__["Component"] {
       role: "listbox",
       selectionType: "single",
       alignment: alignment,
+      autoFocus: autoFocus,
+      enableTypeAhead: enableTypeAhead,
       dropdownStyle: [isFilterable && _util_constants_js__WEBPACK_IMPORTED_MODULE_6__[/* filterableDropdownStyle */ "e"], _util_constants_js__WEBPACK_IMPORTED_MODULE_6__[/* selectDropdownStyle */ "g"], dropdownStyle],
       initialFocusedIndex: this.selectedIndex,
       items: items,
@@ -2361,7 +2376,9 @@ class SingleSelect extends react__WEBPACK_IMPORTED_MODULE_1__["Component"] {
 }
 SingleSelect.defaultProps = {
   alignment: "left",
+  autoFocus: true,
   disabled: false,
+  enableTypeAhead: true,
   light: false,
   labels: {
     clearSearch: _util_constants_js__WEBPACK_IMPORTED_MODULE_6__[/* defaultLabels */ "d"].clearSearch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-dropdown",
-  "version": "2.9.4",
+  "version": "2.10.0",
   "design": "v1",
   "description": "Dropdown variants for Wonder Blocks.",
   "main": "dist/index.js",
@@ -16,13 +16,13 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.18.6",
-    "@khanacademy/wonder-blocks-clickable": "^2.3.3",
+    "@khanacademy/wonder-blocks-clickable": "^2.4.0",
     "@khanacademy/wonder-blocks-color": "^1.2.0",
     "@khanacademy/wonder-blocks-core": "^4.5.0",
     "@khanacademy/wonder-blocks-icon": "^1.2.32",
     "@khanacademy/wonder-blocks-layout": "^1.4.12",
-    "@khanacademy/wonder-blocks-modal": "^3.0.0",
-    "@khanacademy/wonder-blocks-search-field": "^1.0.12",
+    "@khanacademy/wonder-blocks-modal": "^3.0.1",
+    "@khanacademy/wonder-blocks-search-field": "^1.0.13",
     "@khanacademy/wonder-blocks-spacing": "^3.0.5",
     "@khanacademy/wonder-blocks-timing": "^2.1.0",
     "@khanacademy/wonder-blocks-typography": "^1.1.34"
@@ -38,7 +38,7 @@
     "react-window": "^1.8.5"
   },
   "devDependencies": {
-    "@khanacademy/wonder-blocks-button": "^3.0.6",
+    "@khanacademy/wonder-blocks-button": "^3.0.7",
     "wb-dev-build-settings": "^0.4.0"
   }
 }

package/src/components/__docs__/single-select.stories.js

@@ -5,6 +5,8 @@ import {StyleSheet} from "aphrodite";
 import Button from "@khanacademy/wonder-blocks-button";
 import Color from "@khanacademy/wonder-blocks-color";
 import {View} from "@khanacademy/wonder-blocks-core";
+import {TextField} from "@khanacademy/wonder-blocks-form";
+import Icon from "@khanacademy/wonder-blocks-icon";
 import {Strut} from "@khanacademy/wonder-blocks-layout";
 import {OnePaneDialog, ModalLauncher} from "@khanacademy/wonder-blocks-modal";
 import Spacing from "@khanacademy/wonder-blocks-spacing";
@@ -19,16 +21,23 @@ import {
 } from "@khanacademy/wonder-blocks-dropdown";
 
 import type {SingleSelectLabels} from "@khanacademy/wonder-blocks-dropdown";
+import type {IconAsset} from "@khanacademy/wonder-blocks-icon";
 
 import ComponentInfo from "../../../../../.storybook/components/component-info.js";
 import {name, version} from "../../../package.json";
 import singleSelectArgtypes from "./base-select.argtypes.js";
+import {defaultLabels} from "../../util/constants.js";
 
 export default {
     title: "Dropdown / SingleSelect",
     component: SingleSelect,
     subcomponents: {OptionItem, SeparatorItem},
-    argTypes: singleSelectArgtypes,
+    argTypes: {
+        ...singleSelectArgtypes,
+        labels: {
+            defaultValue: defaultLabels,
+        },
+    },
     args: {
         isFilterable: true,
         opened: false,
@@ -38,10 +47,8 @@ export default {
         selectedValue: "",
     },
     decorators: [
-        (Story: StoryComponentType): React.Element<typeof View> => (
-            <View style={styles.example}>
-                <Story />
-            </View>
+        (Story: any): React.Element<typeof View> => (
+            <View style={styles.example}>{Story()}</View>
         ),
     ],
     parameters: {
@@ -126,18 +133,23 @@ const styles = StyleSheet.create({
         paddingRight: Spacing.medium_16,
         paddingTop: Spacing.medium_16,
     },
+    // AutoFocus
+    icon: {
+        position: "absolute",
+        right: Spacing.medium_16,
+    },
 });
 
 const items = [
-    <OptionItem label="Banana" value="banana" />,
-    <OptionItem label="Strawberry" value="strawberry" disabled />,
-    <OptionItem label="Pear" value="pear" />,
-    <OptionItem label="Orange" value="orange" />,
-    <OptionItem label="Watermelon" value="watermelon" />,
-    <OptionItem label="Apple" value="apple" />,
-    <OptionItem label="Grape" value="grape" />,
-    <OptionItem label="Lemon" value="lemon" />,
-    <OptionItem label="Mango" value="mango" />,
+    <OptionItem label="Banana" value="banana" key={0} />,
+    <OptionItem label="Strawberry" value="strawberry" disabled key={1} />,
+    <OptionItem label="Pear" value="pear" key={2} />,
+    <OptionItem label="Orange" value="orange" key={3} />,
+    <OptionItem label="Watermelon" value="watermelon" key={4} />,
+    <OptionItem label="Apple" value="apple" key={5} />,
+    <OptionItem label="Grape" value="grape" key={6} />,
+    <OptionItem label="Lemon" value="lemon" key={7} />,
+    <OptionItem label="Mango" value="mango" key={8} />,
 ];
 
 const Template = (args) => {
@@ -516,3 +528,90 @@ CustomLabels.parameters = {
         },
     },
 };
+
+/**
+ * Auto focus disabled
+ */
+const timeSlots = [
+    "12:00 AM",
+    "2:00 AM",
+    "4:00 AM",
+    "6:00 AM",
+    "8:00 AM",
+    "10:00 AM",
+    "12:00 PM",
+    "2:00 PM",
+    "4:00 PM",
+    "6:00 PM",
+    "8:00 PM",
+    "10:00 PM",
+    "11:59 PM",
+];
+
+const timeSlotOptions = timeSlots.map((timeSlot) => (
+    <OptionItem label={timeSlot} value={timeSlot} />
+));
+
+const clockIcon: IconAsset = {
+    small: `M0 8C0 3.58 3.58 0 7.99 0C12.42 0 16 3.58 16 8C16 12.42 12.42 16 7.99 16C3.58 16 0 12.42 0 8ZM1.6 8C1.6 11.54 4.46 14.4 8 14.4C11.54 14.4 14.4 11.54 14.4 8C14.4 4.46 11.54 1.6 8 1.6C4.46 1.6 1.6 4.46 1.6 8ZM7.2 4H8.4V8.2L12 10.34L11.4 11.32L7.2 8.8V4Z`,
+};
+
+export const AutoFocusDisabled: StoryComponentType = () => {
+    const textFieldRef = React.useRef(null);
+    const [value, setValue] = React.useState(null);
+    const [opened, setOpened] = React.useState(false);
+
+    return (
+        <View style={styles.wrapper}>
+            <SingleSelect
+                autoFocus={false}
+                enableTypeAhead={false}
+                onChange={setValue}
+                selectedValue={value}
+                opened={opened}
+                onToggle={setOpened}
+                placeholder="Choose a time"
+                opener={({focused, hovered, pressed, text}) => (
+                    <View style={styles.row}>
+                        <TextField
+                            placeholder="Choose a time"
+                            id="single-select-opener"
+                            onChange={setValue}
+                            value={value ?? ""}
+                            ref={textFieldRef}
+                            autoComplete="off"
+                            style={styles.fullBleed}
+                        />
+                        <Icon
+                            color={Color.blue}
+                            icon={clockIcon}
+                            size="small"
+                            style={styles.icon}
+                        />
+                    </View>
+                )}
+            >
+                {timeSlotOptions}
+            </SingleSelect>
+        </View>
+    );
+};
+
+AutoFocusDisabled.parameters = {
+    docs: {
+        description: {
+            story:
+                `This example illustrates how you can disable the auto focus
+                of the \`SingleSelect\` component. Note that for this example,
+                we are using a \`TextField\` component as a custom opener to
+                ilustrate how the focus remains on the opener.\n\n` +
+                `**Note:** We also disabled the \`enableTypeAhead\` prop to be
+                able to use the textbox properly.`,
+        },
+    },
+    chromatic: {
+        // we don't need screenshots because this story only tests focus +
+        // keyboard behavior.
+        disableSnapshot: true,
+    },
+};

package/src/components/__tests__/single-select.test.js

@@ -97,6 +97,31 @@ describe("SingleSelect", () => {
                 // Assert
                 expect(onChange).toHaveBeenCalledWith("1"); // value
             });
+
+            it("should not focus in the first item if autoFocus is disabled", async () => {
+                // Arrange
+                render(
+                    <SingleSelect
+                        autoFocus={false}
+                        onChange={onChange}
+                        placeholder="Choose"
+                        opener={() => <input type="text" />}
+                    >
+                        <OptionItem label="item 1" value="1" />
+                        <OptionItem label="item 2" value="2" />
+                        <OptionItem label="item 3" value="3" />
+                    </SingleSelect>,
+                );
+
+                // Act
+                userEvent.click(screen.getByRole("textbox"));
+
+                // wait for the dropdown to open
+                await screen.findByRole("listbox");
+
+                // Assert
+                expect(screen.getByRole("textbox")).toHaveFocus();
+            });
         });
 
         describe("keyboard", () => {
@@ -183,6 +208,32 @@ describe("SingleSelect", () => {
                 expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
             });
 
+            it("should NOT find/select an item using the keyboard if enableTypeAhead is set false", () => {
+                // Arrange
+                render(
+                    <SingleSelect
+                        onChange={onChange}
+                        placeholder="Choose"
+                        enableTypeAhead={false}
+                    >
+                        <OptionItem label="apple" value="apple" />
+                        <OptionItem label="orange" value="orange" />
+                        <OptionItem label="pear" value="pear" />
+                    </SingleSelect>,
+                );
+                userEvent.tab();
+
+                // Act
+
+                // Try to find first occurrence but it should not be found
+                // as we have disabled type ahead.
+                userEvent.keyboard("or");
+                jest.advanceTimersByTime(501);
+
+                // Assert
+                expect(onChange).not.toHaveBeenCalled();
+            });
+
             it("should dismiss the dropdown when pressing {escape}", () => {
                 // Arrange
                 render(uncontrolledSingleSelect);

package/src/components/dropdown-core.js

@@ -72,18 +72,38 @@ type Labels = {|
 // values to the parent components that are instantiating this component
 // @see https://flow.org/en/docs/react/hoc/#toc-exporting-wrapped-components
 type DefaultProps = {|
-    /**
-     * An index that represents the index of the focused element when the menu
-     * is opened.
-     */
-    initialFocusedIndex?: number,
-
     /**
      * Whether this menu should be left-aligned or right-aligned with the
      * opener component. Defaults to left-aligned.
      */
     alignment: "left" | "right",
 
+    /**
+     * Whether to auto focus an option. Defaults to true.
+     */
+    autoFocus: boolean,
+
+    /**
+     * Whether to enable the type-ahead suggestions feature. Defaults to true.
+     *
+     * This feature allows to navigate the listbox using the keyboard.
+     * - Type a character: focus moves to the next item with a name that starts
+     *   with the typed character.
+     * - Type multiple characters in rapid succession: focus moves to the next
+     *   item with a name that starts with the string of characters typed.
+     *
+     * **NOTE:** Type-ahead is recommended for all listboxes, but there might be
+     * some cases where it's not desirable (for example when using a `TextField`
+     * as the opener element).
+     */
+    enableTypeAhead: boolean,
+
+    /**
+     * An index that represents the index of the focused element when the menu
+     * is opened.
+     */
+    initialFocusedIndex?: number,
+
     /**
      * The object containing the custom labels used inside this component.
      */
@@ -106,24 +126,13 @@ type ItemAriaRole = "option" | "menuitem";
 
 type Props = {|
     ...DefaultProps,
-    /**
-     * Items for the menu.
-     */
-    items: Array<DropdownItem>,
 
-    /**
-     * An optional handler to set the searchText of the parent. When this and
-     * the searchText exist, SearchField will be displayed at the top of the
-     * dropdown body.
-     */
-    onSearchTextChanged?: ?(searchText: string) => mixed,
+    // Required props
 
     /**
-     * An optional string that the user entered to search the items. When this
-     * and the onSearchTextChanged exist, SearchField will be displayed at the
-     * top of the dropdown body.
+     * Items for the menu.
      */
-    searchText?: ?string,
+    items: Array<DropdownItem>,
 
     /**
      * Callback for when the menu is opened or closed. Parameter is whether
@@ -146,6 +155,27 @@ type Props = {|
      */
     openerElement: ?HTMLElement,
 
+    /**
+     * The aria "role" applied to the dropdown container.
+     */
+    role: DropdownAriaRole,
+
+    // Optional props
+
+    /**
+     * An optional handler to set the searchText of the parent. When this and
+     * the searchText exist, SearchField will be displayed at the top of the
+     * dropdown body.
+     */
+    onSearchTextChanged?: ?(searchText: string) => mixed,
+
+    /**
+     * An optional string that the user entered to search the items. When this
+     * and the onSearchTextChanged exist, SearchField will be displayed at the
+     * top of the dropdown body.
+     */
+    searchText?: ?string,
+
     /**
      * Styling specific to the dropdown component that isn't part of the opener,
      * passed by the specific implementation of the dropdown menu,
@@ -162,11 +192,6 @@ type Props = {|
      */
     className?: string,
 
-    /**
-     * The aria "role" applied to the dropdown container.
-     */
-    role: DropdownAriaRole,
-
     /**
      * When this is true, the dropdown body shows a search text input at the
      * top. The items will be filtered by the input.
@@ -247,6 +272,8 @@ class DropdownCore extends React.Component<Props, State> {
 
     static defaultProps: DefaultProps = {
         alignment: "left",
+        autoFocus: true,
+        enableTypeAhead: true,
         labels: {
             clearSearch: defaultLabels.clearSearch,
             filter: defaultLabels.filter,
@@ -320,7 +347,7 @@ class DropdownCore extends React.Component<Props, State> {
 
     componentDidMount() {
         this.updateEventListeners();
-        this.initialFocusItem();
+        this.maybeFocusInitialItem();
     }
 
     componentDidUpdate(prevProps: Props) {
@@ -328,7 +355,7 @@ class DropdownCore extends React.Component<Props, State> {
 
         if (prevProps.open !== open) {
             this.updateEventListeners();
-            this.initialFocusItem();
+            this.maybeFocusInitialItem();
         }
         // If the menu changed, but from open to open, figure out if we need
         // to recalculate the focus somehow.
@@ -396,8 +423,12 @@ class DropdownCore extends React.Component<Props, State> {
 
     // Figure out focus states for the dropdown after it has changed from open
     // to closed or vice versa
-    initialFocusItem() {
-        const {open} = this.props;
+    maybeFocusInitialItem() {
+        const {autoFocus, open} = this.props;
+
+        if (!autoFocus) {
+            return;
+        }
 
         if (open) {
             this.resetFocusedIndex();
@@ -544,11 +575,11 @@ class DropdownCore extends React.Component<Props, State> {
     }
 
     handleKeyDown: (event: SyntheticKeyboardEvent<>) => void = (event) => {
-        const {onOpenChanged, open, searchText} = this.props;
+        const {enableTypeAhead, onOpenChanged, open, searchText} = this.props;
         const keyCode = event.which || event.keyCode;
 
         // Listen for the keydown events if we are using ASCII characters.
-        if (getStringForKey(event.key)) {
+        if (enableTypeAhead && getStringForKey(event.key)) {
             event.stopPropagation();
             this.textSuggestion += event.key;
             // Trigger the filter logic only after the debounce is resolved.

package/src/components/option-item.js

@@ -144,6 +144,7 @@ export default class OptionItem extends React.Component<OptionProps> {
                 disabled={disabled}
                 onClick={this.handleClick}
                 role={role}
+                tabIndex={0}
             >
                 {(state, childrenProps) => {
                     const {pressed, hovered, focused} = state;

package/src/components/single-select.js

@@ -39,8 +39,54 @@ export type SingleSelectLabels = {|
     someResults: (numOptions: number) => string,
 |};
 
+type DefaultProps = {|
+    /**
+     * Whether this dropdown should be left-aligned or right-aligned with the
+     * opener component. Defaults to left-aligned.
+     */
+    alignment: "left" | "right",
+
+    /**
+     * Whether to auto focus an option. Defaults to true.
+     */
+    autoFocus: boolean,
+
+    /**
+     * Whether to enable the type-ahead suggestions feature. Defaults to true.
+     *
+     * This feature allows to navigate the listbox using the keyboard.
+     * - Type a character: focus moves to the next item with a name that starts
+     *   with the typed character.
+     * - Type multiple characters in rapid succession: focus moves to the next
+     *   item with a name that starts with the string of characters typed.
+     *
+     * **NOTE:** Type-ahead is recommended for all listboxes, but there might be
+     * some cases where it's not desirable (for example when using a `TextField`
+     * as the opener element).
+     */
+    enableTypeAhead: boolean,
+
+    /**
+     * Whether this component is disabled. A disabled dropdown may not be opened
+     * and does not support interaction. Defaults to false.
+     */
+    disabled: boolean,
+
+    /**
+     * Whether to display the "light" version of this component instead, for
+     * use when the component is used on a dark background.
+     */
+    light: boolean,
+
+    /**
+     * The object containing the custom labels used inside this component.
+     */
+    labels: SingleSelectLabels,
+|};
+
 type Props = {|
     ...AriaProps,
+    ...DefaultProps,
 
     /**
      * The items in this select.
@@ -81,24 +127,6 @@ type Props = {|
      */
     selectedValue?: ?string,
 
-    /**
-     * Whether this dropdown should be left-aligned or right-aligned with the
-     * opener component. Defaults to left-aligned.
-     */
-    alignment: "left" | "right",
-
-    /**
-     * Whether this component is disabled. A disabled dropdown may not be opened
-     * and does not support interaction. Defaults to false.
-     */
-    disabled: boolean,
-
-    /**
-     * Whether to display the "light" version of this component instead, for
-     * use when the component is used on a dark background.
-     */
-    light: boolean,
-
     /**
      * Optional styling to add to the opener component wrapper.
      */
@@ -131,11 +159,6 @@ type Props = {|
      * top. The items will be filtered by the input.
      */
     isFilterable?: boolean,
-
-    /**
-     * The object containing the custom labels used inside this component.
-     */
-    labels: SingleSelectLabels,
 |};
 
 type State = {|
@@ -157,13 +180,6 @@ type State = {|
     openerElement: ?HTMLElement,
 |};
 
-type DefaultProps = {|
-    alignment: Props["alignment"],
-    disabled: Props["disabled"],
-    light: Props["light"],
-    labels: Props["labels"],
-|};
-
 /**
  * The single select allows the selection of one item. Clients are responsible
  * for keeping track of the selected item in the select.
@@ -194,7 +210,9 @@ export default class SingleSelect extends React.Component<Props, State> {
 
     static defaultProps: DefaultProps = {
         alignment: "left",
+        autoFocus: true,
         disabled: false,
+        enableTypeAhead: true,
         light: false,
         labels: {
             clearSearch: defaultLabels.clearSearch,
@@ -351,7 +369,9 @@ export default class SingleSelect extends React.Component<Props, State> {
             // passing them down to the opener as part of sharedProps
             /* eslint-disable no-unused-vars */
             alignment,
+            autoFocus,
             dropdownStyle,
+            enableTypeAhead,
             isFilterable,
             labels,
             onChange,
@@ -400,9 +420,11 @@ export default class SingleSelect extends React.Component<Props, State> {
     render(): React.Node {
         const {
             alignment,
+            autoFocus,
             children,
             className,
             dropdownStyle,
+            enableTypeAhead,
             isFilterable,
             labels,
             light,
@@ -418,6 +440,8 @@ export default class SingleSelect extends React.Component<Props, State> {
                 role="listbox"
                 selectionType="single"
                 alignment={alignment}
+                autoFocus={autoFocus}
+                enableTypeAhead={enableTypeAhead}
                 dropdownStyle={[
                     isFilterable && filterableDropdownStyle,
                     selectDropdownStyle,

package/src/components/__docs__/single-select.argtypes.js

@@ -1,54 +0,0 @@
-// @flow
-export default {
-    alignment: {
-        table: {
-            category: "Layout",
-        },
-    },
-    disabled: {
-        table: {
-            category: "States",
-        },
-    },
-    isFilterable: {
-        table: {
-            category: "States",
-        },
-    },
-    light: {
-        table: {
-            category: "States",
-        },
-    },
-    opened: {
-        control: "boolean",
-        table: {
-            category: "States",
-        },
-    },
-    onToggle: {
-        table: {
-            category: "Events",
-        },
-    },
-    onChange: {
-        table: {
-            category: "Events",
-        },
-    },
-    dropdownStyle: {
-        table: {
-            category: "Styling",
-        },
-    },
-    style: {
-        table: {
-            category: "Styling",
-        },
-    },
-    className: {
-        table: {
-            category: "Styling",
-        },
-    },
-};