Combobox hooks docs #1276
Combobox hooks docs #1276
Conversation
LFDanLu
requested review from
dannify,
devongovett and
snowystinger
as code owners
|
Build successful! 🎉 |
|
Build successful! 🎉 |
LFDanLu
force-pushed
the
docs_combobox
branch
from
ae6d669
to
fd50d2d
Compare
|
Build successful! 🎉 |
|
Build successful! 🎉 |
|
Build successful! 🎉 |
|
Build successful! 🎉 |
|
Build successful! 🎉 |
|
Build successful! 🎉 |
| shouldCloseOnBlur?: boolean | ||
| } | ||
|
|
||
| /** | ||
| * Provides state management for a ComboBox component. Handles building a collection | ||
| * of items from props and manages the option selection state of the ComboBox. Also tracks the input value, |
There was a problem hiding this comment.
For some reason this Also bugs me when I read it. Maybe In addition... or Additional functionality includes...
| <InterfaceType properties={docs.links[docs.exports.useComboBox.return.id].properties} /> | ||
| </TypeContext.Provider> | ||
|
|
||
| State is managed by the <TypeLink links={statelyDocs.links} type={statelyDocs.exports.useComboBoxState} /> hook from `@react-stately/select`. |
There was a problem hiding this comment.
Why is this a TypeLink instead directly to the stately docs page?
There was a problem hiding this comment.
Follows the pattern set up by previous stately doc pages. The stately pages are typically pretty bare, so having this TypeLink is sufficient since it shows the stately hook's api.
| ); | ||
| } | ||
|
|
||
| <ComboBox label="Favorite Animal" defaultSelectedKey="red panda"> |
There was a problem hiding this comment.
Should this example have an empty dropdown, seen as a line in the image, when nothing matches?
There was a problem hiding this comment.
Hm, I can't seem to get that to happen. What browser/repro steps?
There was a problem hiding this comment.
Chrome (that is a version behind) and attaching video.
Screen.Recording.2021-01-14.at.3.19.05.PM.mov
There was a problem hiding this comment.
Ahhh, I see, problem with the controlled story, lemme see if I can change something
There was a problem hiding this comment.
kk, I pushed up a fix, good catch. I forgot to add items to the field state since that was controlled as well and useComboBoxState doesn't close the menu if the collection is empty and items/open state is controlled, that is up to the user event handlers
There was a problem hiding this comment.
Maybe we should not have a default selected key? It's weird to click the button and only see one option...
| ///- end collapse -/// | ||
| // Using the same ComboBox component code from the first example... | ||
|
|
||
| <ComboBox label="Favorite Animal" menuTrigger="focus"> |
There was a problem hiding this comment.
Should we have all three cases of menuTrigger as examples?
There was a problem hiding this comment.
IMO I feel like the description before the example is sufficient, happy for others to weigh in
|
Build successful! 🎉 |
|
Build successful! 🎉 |
|
Build successful! 🎉 |
|
|
||
| It is important to note that you don't have to control every single aspect of a ComboBox. If you decide to only control a single property of the | ||
| ComboBox, be sure to provide the change handler for that prop as well e.g. controlling `selectedKey` would require `onSelectionChange` to be passed to `useComboBox` as well. | ||
|
|
There was a problem hiding this comment.
Should we expand on the fact that the filtering in the example is different than the previous one precisely because it's controlled?
There was a problem hiding this comment.
Sure, I'll add a little blurb
|
Build successful! 🎉 |
|
|
||
| ## Anatomy | ||
|
|
||
| A ComboBox consists of a label, an input which displays the current value, a listbox popup, and a button |
There was a problem hiding this comment.
| A ComboBox consists of a label, an input which displays the current value, a listbox popup, and a button | |
| A ComboBox consists of a label, an input which displays the current value, a listbox popup, and an optional button |
|
|
||
| ### Uncontrolled | ||
|
|
||
| This base example uses an `<input>` element for the ComboBox text input and a `<button>` element for the ComboBox menu trigger. A `<span>` |
There was a problem hiding this comment.
| This base example uses an `<input>` element for the ComboBox text input and a `<button>` element for the ComboBox menu trigger. A `<span>` | |
| This example uses an `<input>` element for the ComboBox text input, and a `<button>` element for the ComboBox menu trigger. A `<span>` |
| // to allow screen reader users to dismiss the popup easily. | ||
| return ( | ||
| <div {...overlayProps} ref={popoverRef}> | ||
| <DismissButton onDismiss={() => state.close()} /> |
There was a problem hiding this comment.
In RSP, we have only a single DismissButton. I guess because when you're at the start, you can navigate back to the input? Should we match?
There was a problem hiding this comment.
Sounds good, I'll remove the extra one
| ); | ||
| } | ||
|
|
||
| <ComboBox label="Favorite Animal" defaultSelectedKey="red panda"> |
There was a problem hiding this comment.
Maybe we should not have a default selected key? It's weird to click the button and only see one option...
|
|
||
| The following example shows how you would create a controlled ComboBox, controlling everything from the selected value (`selectedKey`) | ||
| to the combobox options (`items`). By passing in `inputValue`, `selectedKey`, `isOpen`, and `items` to the `useComboBoxState` hook you can control | ||
| what exactly your ComboBox should display. For example, note that the item filtering for the controlled ComboBox below now follows a "starts with" |
There was a problem hiding this comment.
| what exactly your ComboBox should display. For example, note that the item filtering for the controlled ComboBox below now follows a "starts with" | |
| exactly what your ComboBox should display. For example, note that the item filtering for the controlled ComboBox below now follows a "starts with" |
| * Keyboard support for opening the ComboBox menu using the arrow keys, including automatically focusing | ||
| the first or last item accordingly | ||
| * Virtual focus management for ComboBox menu option navigation | ||
| * VoiceOver announcement enhancements for option focusing, filtering, and selection |
There was a problem hiding this comment.
I'd call these workarounds rather than enhancements... maybe something like this?
| * VoiceOver announcement enhancements for option focusing, filtering, and selection | |
| * Custom localized announcements for option focusing, filtering, and selection using an ARIA live region to work around VoiceOver bugs |
| It also holds state to track if the popup is open, if the ComboBox is focused, and the current input value. | ||
| For more information about selection, see [Selection](/react-stately/selection.html). | ||
|
|
||
| ## Usage |
There was a problem hiding this comment.
I think we should split this into two sections: The "Example" section like we have on other aria pages which shows how to build the component using our hooks, and a "Usage" section that shows how to use the built component. Uncontrolled and Controlled can be under usage, but the code for the first example should be under "Example". The usage section should basically be a version of what we have on the spectrum docs, but without the spectrum-specific parts.
There was a problem hiding this comment.
Sounds good, I've moved the first example and accompanying text to a "Example" section and added a Uncontrolled section to "Usage"
| setInputValue(value: string): void, | ||
| /** Function that when called handles updating the ComboBox's input value and selected key. */ |
There was a problem hiding this comment.
| /** Function that when called handles updating the ComboBox's input value and selected key. */ | |
| /** Selects the currently focused item and updates the input value. */ |
| @@ -48,6 +57,12 @@ function isAppleDevice() { | |||
| : false; | |||
| } | |||
|
|
|||
| /** | |||
| * Provides the behavior and accessibility implementation for a ComboBox component. | |||
| * A ComboBox combines a text entry with a picker menu, allowing users to filter longer lists to only the selections matching a query. | |||
There was a problem hiding this comment.
| * A ComboBox combines a text entry with a picker menu, allowing users to filter longer lists to only the selections matching a query. | |
| * A ComboBox combines a text input with a listbox, allowing users to filter a list of options to items matching a query. |
| ## Internationalization | ||
|
|
||
| `useComboBox` handles some aspects of internationalization automatically. | ||
| For example, the item focus, count, and selection VoiceOver announcements are formatted to match the current locale. |
There was a problem hiding this comment.
| For example, the item focus, count, and selection VoiceOver announcements are formatted to match the current locale. | |
| For example, the item focus, count, and selection VoiceOver announcements are localized. |
|
|
||
| ## Features | ||
|
|
||
| There is no native element to implement a ComboBox in HTML. `useComboBox` helps achieve accessible ComboBox components that can |
There was a problem hiding this comment.
| There is no native element to implement a ComboBox in HTML. `useComboBox` helps achieve accessible ComboBox components that can | |
| A ComboBox can be built using the [<datalist>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist) HTML element, but this is very limited in functionality and difficult to style. `useComboBox` helps achieve accessible ComboBox components that can |
|
Build successful! 🎉 |
|
Build successful! 🎉 |
|
Build successful! 🎉 |
…ocs_combobox_hooks
|
Build successful! 🎉 |
|
Build successful! 🎉 |
* Reuse the same example instead of duplicating * Add anatomy and a couple more examples * Updates * Add select to the pickers category with combobox
|
Build successful! 🎉 |
|
Build successful! 🎉 |
Closes #1257
✅ Pull Request Checklist:
📝 Test Instructions:
🧢 Your Project: