Skip to content

Commit 3079711

Browse files
smhigleysmhigley
authored
chore: react-combobox spec and migration docs update (#26396)
1 parent 2331c93 commit 3079711

File tree

4 files changed

+400
-199
lines changed

4 files changed

+400
-199
lines changed

‎change/@fluentui-react-combobox-9a051bc5-0518-476d-bde7-7d3f4705e4f4.json

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"type": "prerelease",
3+
"comment": "chore: update spec and migration docs",
4+
"packageName": "@fluentui/react-combobox",
5+
"email": "sarah.higley@microsoft.com",
6+
"dependentChangeType": "patch"
7+
}

‎packages/react-components/react-combobox/docs/Migration.md

+176
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# @fluentui/react-combobox Migration Guide
2+
3+
## Migration from v8 Dropdown
4+
5+
The v8 Dropdown component should be replaced with the [v9 Select](https://github.com/microsoft/fluentui/blob/master/packages/react-select/Spec.md) or v9 Dropdown component. The biggest change is that the v8 `options: IDropdownOption[]` prop is mapped to children in v9.
6+
7+
### Property mapping
8+
9+
| v8 Dropdown | v9 Dropdown |
10+
| ---------------------- | --------------------------------- |
11+
| `options` | `<Option>` children |
12+
| `ariaLabel` | Native `aria-*` props |
13+
| `calloutProps` | `positioning` + `listbox` |
14+
| `className` | `className` |
15+
| `componentRef` | `ref` |
16+
| `defaultSelectedKeys` | defaultSelectedOptions |
17+
| `disabled` | `disabled` |
18+
| `dropdownWidth` | `listbox` slot styles |
19+
| `errorMessage` | Handled by Field |
20+
| `id` | `id` |
21+
| `label` | Handled by Field or Label |
22+
| `multiSelect` | `multiselect` |
23+
| `multiSelectDelimiter` | controlled `value` |
24+
| `notifyOnReselect` | `onClick` on Option |
25+
| `onChange` | `onOptionSelect` |
26+
| `onDismiss` | `onOpenChange` |
27+
| `onRenderCaretDown` | `expandIcon` slot |
28+
| `onRenderContainer` | `listbox` slot |
29+
| `onRenderLabel` | Handled by Field |
30+
| `onRenderItem` | children |
31+
| `onRenderList` | `listbox` slot |
32+
| `onRenderOption` | `<Option>` children |
33+
| `onRenderPlaceholder` | `button` slot |
34+
| `onRenderTitle` | `button` slot |
35+
| `openOnKeyboardFocus` | controlled `open` |
36+
| `panelProps` | N/A |
37+
| `placeholder` | `placeholder` |
38+
| `required` | `required` |
39+
| `selectedKey(s)` | `selectedOptions` |
40+
| `styles` | `makeStyles` or HTML `style` prop |
41+
42+
## From v8 ComboBox
43+
44+
The v8 ComboBox component should be replaced with the v9 Combobox component. The biggest differences are as follows:
45+
46+
- The v8 `options: IComboBoxOption[]` prop is mapped to children in v9
47+
- Filtering is handled by authors by updating children
48+
- The v9 Combobox allows users to type any text while the input is focused. The value is updated to a matching option (or none) when blurred, unless `freeform` is true. If you don't need typing support, use Dropdown.
49+
50+
### Property mapping
51+
52+
| v8 ComboBox | v9 Combobox |
53+
| ------------------------ | ---------------------------------------------- |
54+
| `options` | `<Option>` children |
55+
| `ariaLabel` | Native `aria-*` props |
56+
| `allowFreeInput` | always true |
57+
| `allowFreeform` | `freeform` |
58+
| `ariaDescribedBy` | Native `aria-*` props |
59+
| `autocomplete` | not supported (yet) |
60+
| `autofill` | N/A |
61+
| `buttonIconProps` | `expandIcon` slot |
62+
| `calloutProps` | `positioning` + `listbox` |
63+
| `caretDownButtonStyles` | `expandIcon` slot |
64+
| `className` | `className` |
65+
| `comboBoxOptionStyles` | `<Option>` children |
66+
| `componentRef` | `ref` |
67+
| `defaultSelectedKeys` | defaultSelectedOptions |
68+
| `disabled` | `disabled` |
69+
| `dropdownMaxWidth` | `listbox` slot styles |
70+
| `dropdownWidth` | `listbox` slot styles |
71+
| `errorMessage` | Handled by Field |
72+
| `getClassNames` | `useComboboxStyles` hook |
73+
| `iconButtonProps` | `expandIcon` slot |
74+
| `id` | `id` |
75+
| `isButtonAriaHidden` | `expandIcon` slot, not recommended |
76+
| `label` | Handled by Field or Label |
77+
| `multiSelect` | `multiselect` |
78+
| `multiSelectDelimiter` | controlled `value` |
79+
| `onChange` | `onOptionSelect`\* |
80+
| `onDismiss` | `onOpenChange` |
81+
| `onInputValueChange` | `onChange`\* |
82+
| `onItemClick` | `onClick` on child `<Option>`s |
83+
| `onMenuDismiss` | `onOpenChange` |
84+
| `onMenuDismissed` | |
85+
| `onMenuOpen` | `onOpenChange` |
86+
| `onPendingValueChanged` | |
87+
| `onRenderContainer` | `listbox` slot |
88+
| `onRenderLabel` | Handled by Field |
89+
| `onRenderItem` | children |
90+
| `onRenderList` | `listbox` slot |
91+
| `onRenderLowerContent` | children |
92+
| `onRenderOption` | `<Option>` children |
93+
| `onRenderPlaceholder` | `button` slot |
94+
| `onRenderTitle` | `button` slot |
95+
| `onRenderUpperContent` | children |
96+
| `onResolveOptions` | N/A |
97+
| `onScrollToItem` | |
98+
| `openOnKeyboardFocus` | controlled `open` |
99+
| `panelProps` | N/A |
100+
| `persistMenu` | |
101+
| `placeholder` | `placeholder` |
102+
| `required` | `required` |
103+
| `scrollSelectedToTop` | |
104+
| `selectedKey(s)` | `selectedOptions` |
105+
| `shouldRestoreFocus` | |
106+
| `styles` | `makeStyles` or HTML `style` prop |
107+
| `text` | `value` |
108+
| `useComboBoxAsMenuWidth` | default behavior, `listbox` styles to override |
109+
110+
\*In v9, any native HTML properties supported on an `<input>` element may be set on `<Combobox>`, including the `onChange` handler. Because of this, the v8 `onChange` selection callback has been updated to `onOptionSelect`. The v9 Combobox's `onChange` event behavior is the same as for an `<input>` element, or the v9 Input control.
111+
112+
## From v0 Dropdown
113+
114+
The v0 Dropdown should be replaced with the v9 Combobox if it allows typing with `search: true`, and by the v9 Dropdown if it does not. The most significant difference in moving to v9 is that the v0 Dropdown `items` are defined as child `<Option>`s of the v9 Combobox or Dropdown.
115+
116+
### Property mapping
117+
118+
| v0 Dropdown | v9 Dropdown & Combobox |
119+
| ----------------------------- | ----------------------------------- |
120+
| `items` | `<Option>` children |
121+
| `activeSelectedIndex` | N/A |
122+
| `align` | `positioning` |
123+
| `checkable` | `expandIcon` |
124+
| `checkableIndicator` | `expandIcon` children |
125+
| `className` | `className` |
126+
| `clearIndicator` | N/A |
127+
| `clearable` | |
128+
| `defaultActiveSelectedIndex` | N/A |
129+
| `defaultActiveSelectedIndex` | |
130+
| `defaultOpen` | `defaultOpen` |
131+
| `defaultSearchQuery` | `defaultValue` |
132+
| `defaultValue` | `defaultSelectedOptions` |
133+
| `disabled` | `disabled` |
134+
| `error` | Handled by Field |
135+
| `flipBoundary` | `positioning` |
136+
| `fluid` | custom styles |
137+
| `getA11ySelectionMessage` | |
138+
| `getA11yStatusMessage` | |
139+
| `headerMessage` | children |
140+
| `highlightFirstItemOnOpen` | |
141+
| `highlightedIndex` | |
142+
| `inline` | custom styles |
143+
| `inverted` | theme or styles |
144+
| `itemToString` | `<Option>` children or `text` prop |
145+
| `itemToValue` | `<Option>` children or `value` prop |
146+
| `list` | `listbox` |
147+
| `loading` | children |
148+
| `loadingMessage` | |
149+
| `moveFocusOnTab` | |
150+
| `multiple` | `multiselect` |
151+
| `noResultsMessage` | children |
152+
| `offset` | `positioning` |
153+
| `onActiveSelectedIndexChange` | |
154+
| `onBlur` | `onBlur` |
155+
| `onChange` | `onOptionSelect`\* |
156+
| `onHighlightedIndexChange` | |
157+
| `onOpenChange` | `onOpenChange` |
158+
| `onSearchQueryChange` | `onChange`\* |
159+
| `open` | `open` |
160+
| `overflowBoundary` | `listbox` styles |
161+
| `placeholder` | `placeholder` |
162+
| `popperRef` | `listbox` slot's `ref` |
163+
| `position` | `positioning` |
164+
| `positionFixed` | `listbox` styles |
165+
| `renderItem` | children |
166+
| `renderSelectedItem` | children or `<Option>` styles |
167+
| `search` | use Combobox instead of Dropdown |
168+
| `searchInput` | Combobox primary slot |
169+
| `searchQuery` | `value` |
170+
| `styles` | `makeStyles` or HTML `style` prop |
171+
| `toggleIndicator` | `expandIcon` |
172+
| `triggerButton` | Dropdown primary slot |
173+
| `value` | `selectedOptions` |
174+
| `open` | `open` |
175+
176+
\*In v9, any native HTML properties supported on an `<input>` element may be set on `<Combobox>`, including the `onChange` handler. Because of this, the v0 `onChange` selection callback has been updated to `onOptionSelect`. The v9 Combobox's `onChange` event behavior is the same as for an `<input>` element, or the v9 Input control.

‎packages/react-components/react-combobox/docs/Spec-migration.md

-13
This file was deleted.

0 commit comments

Comments
 (0)