-
Notifications
You must be signed in to change notification settings - Fork 1.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs(Combobox): update dev docs; add mdx docs #6734
Changes from all commits
aae5638
abc6c48
5c3ef5a
b8f1226
8ba4ce1
07ebbaf
02b6c55
525d2ad
11788e9
92192f0
877aeff
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -13,25 +13,120 @@ import ComboBox from '../ComboBox'; | |||||
|
||||||
## Table of Contents | ||||||
|
||||||
<!-- START doctoc generated TOC please keep comment here to allow auto update --> | ||||||
|
||||||
- [Overview](#overview) | ||||||
- [Component API](#component-api) | ||||||
- [Disabled](#disabled) | ||||||
- [Light](#light) | ||||||
- [downshiftProps](#combobox-downshiftprops) | ||||||
- [Placeholder and labeling](#placeholders-and-labeling) | ||||||
- [initialSelectedItem](#initialselecteditem) | ||||||
- [itemToElement](#itemtoelement) | ||||||
- [itemToString](#itemtostring) | ||||||
- [Feedback](#feedback) | ||||||
|
||||||
<!-- END doctoc generated TOC please keep comment here to allow auto update --> | ||||||
|
||||||
## Overview | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Might be able to use the same strategy as TJ did over in Dropdown for use-cases / component API: https://github.com/carbon-design-system/carbon/blob/master/packages/react/src/components/Dropdown/Dropdown.mdx Some other examples could be:
|
||||||
|
||||||
A combobox allows the user to make a selection from a predefined list of options | ||||||
and is typically used when there are a large amount of options to choose from. | ||||||
|
||||||
<Preview> | ||||||
<Story id="combobox--default" /> | ||||||
<Story id="combobox--combobox" /> | ||||||
</Preview> | ||||||
|
||||||
## Component API | ||||||
|
||||||
<Props /> | ||||||
<Props sort="asc" /> | ||||||
|
||||||
## Disabled | ||||||
|
||||||
A disabled comobobox is available but should not be used as the sole means of | ||||||
conveying information. For example, if the user must complete a previous form | ||||||
input before moving on to the combobox, make sure to make that clear to the user | ||||||
via an error state on the previous form element in adition to disabling the next | ||||||
element. | ||||||
|
||||||
<Preview> | ||||||
<Story id="combobox--disabled" /> | ||||||
</Preview> | ||||||
|
||||||
## Light | ||||||
|
||||||
The light prop should never be used against a light background. The form element | ||||||
must have proper contrast against the pages background. | ||||||
|
||||||
<Preview> | ||||||
<Story id="combobox--light" /> | ||||||
</Preview> | ||||||
|
||||||
## Combobox `downshiftProps` | ||||||
|
||||||
Our `Combobox` component utilizes [Downshift](https://www.downshift-js.com/) | ||||||
under the hood to help provide complex yet accessible custom dropdown | ||||||
components. We provide access to the built in Downshift features with this prop. | ||||||
For more information, checkout the Downshift prop | ||||||
[documentation](https://www.downshift-js.com/downshift#props-used-in-examples) | ||||||
|
||||||
## Placeholders and Labeling | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
The placeholder is not a replacement for a label under any circumstances | ||||||
including space restraints. Placeholders should be used to provide additive | ||||||
information regarding the format of the input. In all cases a label is required | ||||||
_in addition to_ a placeholder. | ||||||
|
||||||
## `initialSelectedItem` | ||||||
|
||||||
If you want the Combobox to render with a value already selected, but do not | ||||||
want to fully control the component, you can use `initialSelectedItem` | ||||||
|
||||||
``` | ||||||
const items = ['Option 1', 'Option 2', 'Option 3'] | ||||||
|
||||||
<Combobox initialSelectedItem={items[2]} />; | ||||||
``` | ||||||
|
||||||
## `itemToElement` | ||||||
|
||||||
The Combobox takes in an `items` array and can then be formatted by | ||||||
`itemToElement` and `itemToString`. `itemToElement` allows you to wrap each | ||||||
dropdown item in a custom element. | ||||||
|
||||||
``` | ||||||
<Combobox | ||||||
items={[ | ||||||
{ id: 'option-0', text: 'Option 0' }, | ||||||
{ id: 'option-1', text: 'Option 1' }, | ||||||
{ id: 'option-2', text: 'Option 2' }, | ||||||
]} | ||||||
itemToElement={(item) => | ||||||
item ? ( | ||||||
<span className="test" style={{ color: 'red' }}> | ||||||
{item.text} 🔥 | ||||||
</span> | ||||||
) : ( | ||||||
'' | ||||||
) | ||||||
} | ||||||
label="Select an option..." | ||||||
/> | ||||||
``` | ||||||
|
||||||
## `itemToString` | ||||||
|
||||||
If the `items` array is not an array of strings, you'll need to use | ||||||
`itemToString` to grab the text to be used as the `Combobox` item text. | ||||||
|
||||||
``` | ||||||
<Combobox | ||||||
items={[ | ||||||
{ id: 'option-0', text: 'Option 0' }, | ||||||
{ id: 'option-1', text: 'Option 1' }, | ||||||
{ id: 'option-2', text: 'Option 2' }, | ||||||
]} | ||||||
itemToString={(item) => (item ? item.text : '')} | ||||||
/> | ||||||
``` | ||||||
|
||||||
## Feedback | ||||||
|
||||||
Help us improve these docs by | ||||||
[editing this file on GitHub](https://github.com/carbon-design-system/carbon/edit/master/packages/react/src/components/ComboBox/ComboBox.mdx) | ||||||
[editing this file on GitHub](https://github.com/carbon-design-system/carbon/edit/master/packages/react/src/components/ComboBox/ComboBox.stories.mdx) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would it help to add the new sections to the TOC too or nah?