Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
List - initial implementation (#29760)
- Loading branch information
Showing
72 changed files
with
3,938 additions
and
385 deletions.
There are no files selected for viewing
7 changes: 7 additions & 0 deletions
7
change/@fluentui-react-shared-contexts-c8fe7f5c-9503-41d6-a0d6-dec1071446ac.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| { | ||
| "type": "minor", | ||
| "comment": "deprecate unused ListItemButton exports", | ||
| "packageName": "@fluentui/react-shared-contexts", | ||
| "email": "jirivyhnalek@microsoft.com", | ||
| "dependentChangeType": "patch" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,3 @@ | ||
| /** Jest test setup file. */ | ||
|
|
||
| require('@testing-library/jest-dom'); |
3 changes: 3 additions & 0 deletions
3
packages/react-components/react-list-preview/cypress.config.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| import { baseConfig } from '@fluentui/scripts-cypress'; | ||
|
|
||
| export default baseConfig; |
243 changes: 243 additions & 0 deletions
243
packages/react-components/react-list-preview/docs/ListA11y.md
Large diffs are not rendered by default.
Oops, something went wrong.
203 changes: 203 additions & 0 deletions
203
packages/react-components/react-list-preview/docs/MIGRATION.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,203 @@ | ||
| # List migration | ||
|
|
||
| ## Migration from v8 | ||
|
|
||
| ### Composition over configuration | ||
|
|
||
| Compared to its v8 counterpart, the v9 `List` uses composition over configuration when it comes to rendering items, same as other components in Fluent UI React v9. This means that instead of passing an array of items to the `List` component, it's up to you to render `ListItem` components with appropriate content. | ||
|
|
||
| Take this example in v8: | ||
|
|
||
| ```js | ||
| const items = [{ name: 'John' }, { name: 'Alice' }]; | ||
|
|
||
| const MyList = () => { | ||
| return <List items={items} />; | ||
| }; | ||
| ``` | ||
|
|
||
| becomes this in v9: | ||
|
|
||
| ```js | ||
| const items = [{ name: 'John' }, { name: 'Alice' }]; | ||
|
|
||
| const MyList = () => { | ||
| return ( | ||
| <List> | ||
| {items.map(item => { | ||
| <ListItem key={item}>{item}</ListItem>; | ||
| })} | ||
| </List> | ||
| ); | ||
| }; | ||
| ``` | ||
|
|
||
| ### Virtualization approach | ||
|
|
||
| Virtualization is **not part** of `List` in Fluent UI React v9. We don't want to force any particular solution for virtualization, but we provide [examples](https://react.fluentui.dev/?path=/story/preview-components-list--virtualized-list-with-actionable-items) how to use `List` with a popular library `react-window` to get the desired effect. | ||
|
|
||
| This makes the API of `List` much simpler. | ||
|
|
||
| ### v8 Property mapping | ||
|
|
||
| Most of the v8 props are for it's virtualization functionality. Since the v9 `List` takes a different approach, most of the props cannot be directly migrated. | ||
|
|
||
| | v8 List | v9 List | | ||
| | ------------------------- | -------------------------------- | | ||
| | `className` | `className` | | ||
| | `componentRef` | `componentRef` | | ||
| | `getItemCountForPage` | N/A | | ||
| | `getKey` | N/A as you control the ListItems | | ||
| | `getPageHeight` | N/A | | ||
| | `getPageSpecification` | N/A | | ||
| | `getPageStyle` | N/A | | ||
| | `ignoreScrollingState` | N/A | | ||
| | `items` | render `<ListItem>` instead | | ||
| | `onPageAdded` | N/A | | ||
| | `onPagesUpdated` | N/A | | ||
| | `onRenderCell` | N/A | | ||
| | `onRenderCellConditional` | N/A | | ||
| | `onRenderPage` | N/A | | ||
| | `onRenderRoot` | N/A | | ||
| | `onRenderSurface` | N/A | | ||
| | `onShouldVirtualize` | N/A | | ||
| | `renderCount` | N/A | | ||
| | `renderEarly` | N/A | | ||
| | `renderedWindowsAhead` | N/A | | ||
| | `renderedWindowsBehind` | N/A | | ||
| | `role` | `role` | | ||
| | `startIndex` | N/A | | ||
| | `usePageCache` | N/A | | ||
| | `version` | N/A | | ||
| | - | `defaultSelectedItems` | | ||
| | - | `onSelectionChange` | | ||
| | - | `selectionMode` | | ||
|
|
||
| ## Migration from v0 | ||
|
|
||
| ### Composition, also known as "Children API" | ||
|
|
||
| In Fluent UI React v9 we prefer to use composition over configuration where possible. List is no exception. the v0 list also supports composition API under a name of "Children API". | ||
|
|
||
| #### Children API component mapping | ||
|
|
||
| Migrating from a v9 Children API to v9 composition API is quite straighforward. You can replace the components like this: | ||
|
|
||
| - Use v9 `List` instead of v0 `List` | ||
| - Use v9 `ListItem` instead of v0 `List.Item` | ||
|
|
||
| For props please refer to [Property mapping](#v0-property-mapping) section. | ||
|
|
||
| #### Shorthand API | ||
|
|
||
| For Shorthand API things are a bit more complicated, as your code needs to me updated to use composition. | ||
|
|
||
| Take this example in v0: | ||
|
|
||
| ```js | ||
| const items = [ | ||
| { | ||
| key: 'robert', | ||
| header: 'Robert Tolbert', | ||
| content: 'Program the sensor to the SAS alarm through the haptic SQL card!', | ||
| }, | ||
| { | ||
| key: 'celeste', | ||
| header: 'Celeste Burton', | ||
| content: 'Use the online FTP application to input the multi-byte application!', | ||
| }, | ||
| ]; | ||
|
|
||
| const MyList = () => { | ||
| return <List items={items} />; | ||
| }; | ||
| ``` | ||
|
|
||
| becomes this in v9: | ||
|
|
||
| ```js | ||
| const items = [ | ||
| { | ||
| key: 'robert', | ||
| header: 'Robert Tolbert', | ||
| content: 'Program the sensor to the SAS alarm through the haptic SQL card!', | ||
| }, | ||
| { | ||
| key: 'celeste', | ||
| header: 'Celeste Burton', | ||
| content: 'Use the online FTP application to input the multi-byte application!', | ||
| }, | ||
| ]; | ||
|
|
||
| const MyList = () => { | ||
| return ( | ||
| <List> | ||
| {items.map(item => { | ||
| <ListItem key={item.key}> | ||
| <h2>{item.header}</h2> | ||
| <p>{item.content}></p> | ||
| </ListItem>; | ||
| })} | ||
| </List> | ||
| ); | ||
| }; | ||
| ``` | ||
|
|
||
| ### v0 Property mapping | ||
|
|
||
| Compared to its v0 counterpart, the v9 List implementation is much more generic and it **doesn't have any opinion** on how it's content should look like. This means that you will **not** find layout specific props like `header`, `headerMedia`, `content` or layout specific components. This allows for much more flexible use of the component. | ||
|
|
||
| We recommend using a component like `Persona` where possible, or creating a custom layout component where necessary. | ||
|
|
||
| #### List | ||
|
|
||
| | v0 List | v9 List | | ||
| | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `accessibility` | built in, customize with `useArrowNavigationGroup` from `tabster` | | ||
| | `as` | `as` | | ||
| | `className` | `className` | | ||
| | `debug` | N/A | | ||
| | `defaultSelectedIndex` | `defaultSelectedItems` | | ||
| | `design` | N/A | | ||
| | `horizontal` | N/A - will be added in the future | | ||
| | `items` | N/A - use `ListItem` components as Children | | ||
| | `navigable` | `navigable` | | ||
| | `onSelectedIndexChange` | `onSelectionChange` | | ||
| | `ref` | `ref` | | ||
| | `selectable` | use `selectionMode` of value `single` or `multiselect` | | ||
| | `selectedIndex` | only in controlled mode, use `selection` state; see [example](https://react.fluentui.dev/?path=/story/preview-components-list--list-selection-controlled). | | ||
| | `styles` | use slots in combination with `className` | | ||
| | `truncateContent` | N/A - the `List` is not concerned about it's content | | ||
| | `truncateHeader` | N/A - the `List` is not concerned about it's content | | ||
| | `variables` | N/A - use slots in combination with `className` | | ||
| | `wrap` | N/A - the `List` is not concerned about it's content | | ||
|
|
||
| #### ListItem | ||
|
|
||
| | v0 ListItem | v9 ListItem | | ||
| | ----------------- | ------------------------------------------------------------------------------------- | | ||
| | `accessibility` | N/A | | ||
| | `as` | `as` | | ||
| | `className` | `className` | | ||
| | `content` | N/A - use children | | ||
| | `contentMedia` | N/A - use children | | ||
| | `debug` | N/A | | ||
| | `design` | N/A | | ||
| | `endMedia` | N/A - use children | | ||
| | `header` | N/A - use children | | ||
| | `headerMedia` | N/A - use children | | ||
| | `important` | N/A | | ||
| | `index` | N/A | | ||
| | `media` | N/A - use children | | ||
| | `navigable` | N/A - use `tabIndex={0}` or `navigable` on the `List` | | ||
| | `onClick` | `onAction` | | ||
| | `ref` | ref | | ||
| | `selectable` | N/A - use `List` props like `selectionMode`, `selectedItems` and `onSelectionChange` | | ||
| | `selected` | N/A - use `selectedItems` (or tracked internally when `defaultSelectedItems` is used) | | ||
| | `styles` | N/A - use `className` for any slot | | ||
| | `truncateContent` | N/A - the `List` is not concerned about it's content | | ||
| | `truncateHeader` | N/A - the `List` is not concerned about it's content | | ||
|
|
||
| #### Other | ||
|
|
||
| Other components like `ListItemContent`, `ListItemContentMedia`, `ListItemEndMedia`, `ListItemHeader`,`ListItemHeaderMedia` and `ListItemMedia` are _not_ currently present in v9 `List` implementation for the reasons mentioned above. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
1 change: 0 additions & 1 deletion
1
packages/react-components/react-list-preview/src/ListItemButton.ts
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.