From 88a9196a5fa94a08914b4c49a3f0f27eaf0a96c3 Mon Sep 17 00:00:00 2001 From: Oleksandr Fediashov Date: Wed, 25 Oct 2023 11:34:36 +0200 Subject: [PATCH] chore: fix specs location --- ...-ee6aa3f8-2e1c-435e-a344-90d9f2233e8f.json | 7 + .../react-components/react-skeleton/SPEC.md | 105 ---- .../react-skeleton/docs/Spec.md | 108 ++-- packages/react-components/react-table/Spec.md | 505 ----------------- .../react-components/react-table/docs/Spec.md | 508 ++++++++++++++++-- 5 files changed, 557 insertions(+), 676 deletions(-) create mode 100644 change/@fluentui-react-table-ee6aa3f8-2e1c-435e-a344-90d9f2233e8f.json delete mode 100644 packages/react-components/react-skeleton/SPEC.md delete mode 100644 packages/react-components/react-table/Spec.md diff --git a/change/@fluentui-react-table-ee6aa3f8-2e1c-435e-a344-90d9f2233e8f.json b/change/@fluentui-react-table-ee6aa3f8-2e1c-435e-a344-90d9f2233e8f.json new file mode 100644 index 00000000000000..e874653d9f4dca --- /dev/null +++ b/change/@fluentui-react-table-ee6aa3f8-2e1c-435e-a344-90d9f2233e8f.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "chore: move the component spec", + "packageName": "@fluentui/react-table", + "email": "olfedias@microsoft.com", + "dependentChangeType": "none" +} diff --git a/packages/react-components/react-skeleton/SPEC.md b/packages/react-components/react-skeleton/SPEC.md deleted file mode 100644 index 6aef4f6f2778e7..00000000000000 --- a/packages/react-components/react-skeleton/SPEC.md +++ /dev/null @@ -1,105 +0,0 @@ -# @fluentui/react-skeleton Spec - -## Background - -The `Skeleton` component is a temporary placeholder for UI that is in a loading state. - -## Prior Art - -| Library | Component Name | Spec Link | Notes | -| ----------- | -------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Ant Design | Skeleton | [Skeleton](https://ant.design/components/skeleton/) | Has an `avatar`, `button`, `list`, and `togglebutton`. Has animated and non-animated versions, and shape variants for the component skeletons(rounded or rectangular). | -| Fast | Skeleton | [Skeleton](https://explore.fast.design/components/fast-skeleton) | Has three components: `Avatar`, `List`, and `Button`. No shape variants. | -| Semantic UI | Placeholder | [Placeholder](https://react.semantic-ui.com/elements/placeholder/) | Has `Header` and `Paragraph` subcomponents. The `Header` can take in an image as a prop | -| UI Fabric | Shimmer | [Shimmer](https://developer.microsoft.com/en-us/fluentui#/controls/web/shimmer) | Shimmer has a way to pass in custom elements as well as the defaults. There is also a prop to change the colors of the Skeleton components. | - -### Comparison of v8 and v0 - -The existing components are: - -- v8 - - `Shimmer` -- v0 - - Does not have an existing `Skeleton` component. - -## Sample Code - -Basic example: - -```jsx -import { Skeleton, SkeletonItem } from '@fluentui/react-skeleton'; - -function App() { - return ( - - - - - ); -} -``` - -## Variants - -- There are three basic `Skeleton` shapes - - `Rectangle` - - `Circle` - - `Square` - -### Shape - -The `Skeleton` is a combination of any of the two shapes in order to represent the content that will be loaded onto the screen. That is, it is a combination of rectangles and circles that is a visual representation of the wireframe of a page. - -## API - -### Slots - -- `root` - The root slot of the `Skeleton` is the container that will contain the items that make up a `Skeleton` in representation of the data that is loading. The default html element is a `svg`. - -### Props - -See API at: - -- [Skeleton.types.ts](./src/components/Skeleton/Skeleton.types.ts). -- [SkeletonItem.types.ts](./src/components/SkeletonItem/SkeletonItem.types.ts). - -## Structure - -```html - - -
- - -
-
-``` - -## Migration - -See [MIGRATION.md](./MIGRATION.md). - -## Behaviors - -### States - -- **Display** - The `Skeleton` will use the following priority: - - - The `appearance` prop will allow the use of a `translucent` appearance. - - Specifying `wave` or `pulse` will change the animation style of the `Skeleton` - - The component also has `rtl` support and will animate the `Skeleton` from right to left if set. - - Setting the `shape` prop in `` will render a `rectangle`, `square`, or a `circle` (default is `rectangle`). - - Setting the `size` prop in `` will allow the user to specify the size of the element (default is 16). - -### Interaction - -The Skeleton is non-interactive. - -- **Keyboard** - Not keyboard focusable. -- **Mouse** - Nothing - -- **Touch** - Nothing - -## Accessibility - -- An `aria-label` is added to the `Skeleton` container to let users know that content is loading diff --git a/packages/react-components/react-skeleton/docs/Spec.md b/packages/react-components/react-skeleton/docs/Spec.md index d6226a78af1ece..6aef4f6f2778e7 100644 --- a/packages/react-components/react-skeleton/docs/Spec.md +++ b/packages/react-components/react-skeleton/docs/Spec.md @@ -2,62 +2,104 @@ ## Background -_Description and use cases of this component_ +The `Skeleton` component is a temporary placeholder for UI that is in a loading state. ## Prior Art -_Include background research done for this component_ +| Library | Component Name | Spec Link | Notes | +| ----------- | -------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Ant Design | Skeleton | [Skeleton](https://ant.design/components/skeleton/) | Has an `avatar`, `button`, `list`, and `togglebutton`. Has animated and non-animated versions, and shape variants for the component skeletons(rounded or rectangular). | +| Fast | Skeleton | [Skeleton](https://explore.fast.design/components/fast-skeleton) | Has three components: `Avatar`, `List`, and `Button`. No shape variants. | +| Semantic UI | Placeholder | [Placeholder](https://react.semantic-ui.com/elements/placeholder/) | Has `Header` and `Paragraph` subcomponents. The `Header` can take in an image as a prop | +| UI Fabric | Shimmer | [Shimmer](https://developer.microsoft.com/en-us/fluentui#/controls/web/shimmer) | Shimmer has a way to pass in custom elements as well as the defaults. There is also a prop to change the colors of the Skeleton components. | -- _Link to Open UI research_ -- _Link to comparison of v7 and v0_ -- _Link to GitHub epic issue for the converged component_ +### Comparison of v8 and v0 + +The existing components are: + +- v8 + - `Shimmer` +- v0 + - Does not have an existing `Skeleton` component. ## Sample Code -_Provide some representative example code that uses the proposed API for the component_ +Basic example: + +```jsx +import { Skeleton, SkeletonItem } from '@fluentui/react-skeleton'; + +function App() { + return ( + + + + + ); +} +``` ## Variants -_Describe visual or functional variants of this control, if applicable. For example, a slider could have a 2D variant._ +- There are three basic `Skeleton` shapes + - `Rectangle` + - `Circle` + - `Square` + +### Shape + +The `Skeleton` is a combination of any of the two shapes in order to represent the content that will be loaded onto the screen. That is, it is a combination of rectangles and circles that is a visual representation of the wireframe of a page. ## API -_List the **Props** and **Slots** proposed for the component. Ideally this would just be a link to the component's `.types.ts` file_ +### Slots + +- `root` - The root slot of the `Skeleton` is the container that will contain the items that make up a `Skeleton` in representation of the data that is loading. The default html element is a `svg`. + +### Props + +See API at: + +- [Skeleton.types.ts](./src/components/Skeleton/Skeleton.types.ts). +- [SkeletonItem.types.ts](./src/components/SkeletonItem/SkeletonItem.types.ts). ## Structure -- _**Public**_ -- _**Internal**_ -- _**DOM** - how the component will be rendered as HTML elements_ +```html + -## Migration +
+ -_Describe what will need to be done to upgrade from the existing implementations:_ +
+
+``` -- _Migration from v8_ -- _Migration from v0_ +## Migration + +See [MIGRATION.md](./MIGRATION.md). ## Behaviors -_Explain how the component will behave in use, including:_ +### States + +- **Display** - The `Skeleton` will use the following priority: + + - The `appearance` prop will allow the use of a `translucent` appearance. + - Specifying `wave` or `pulse` will change the animation style of the `Skeleton` + - The component also has `rtl` support and will animate the `Skeleton` from right to left if set. + - Setting the `shape` prop in `` will render a `rectangle`, `square`, or a `circle` (default is `rectangle`). + - Setting the `size` prop in `` will allow the user to specify the size of the element (default is 16). + +### Interaction + +The Skeleton is non-interactive. + +- **Keyboard** - Not keyboard focusable. +- **Mouse** - Nothing -- _Component States_ -- _Interaction_ - - _Keyboard_ - - _Cursor_ - - _Touch_ - - _Screen readers_ +- **Touch** - Nothing ## Accessibility -Base accessibility information is included in the design document. After the spec is filled and review, outcomes from it need to be communicated to design and incorporated in the design document. - -- Decide whether to use **native element** or folow **ARIA** and provide reasons -- Identify the **[ARIA](https://www.w3.org/TR/wai-aria-practices-1.2/) pattern** and, if the component is listed there, follow its specification as possible. -- Identify accessibility **variants**, the `role` ([ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#role_definitions)) of the component, its `slots` and `aria-*` props. -- Describe the **keyboard navigation**: Tab Oder and Arrow Key Navigation. Describe any other keyboard **shortcuts** used -- Specify texts for **state change announcements** - [ARIA live regions - ](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) (number of available items in dropdown, error messages, confirmations, ...) -- Identify UI parts that appear on **hover or focus** and specify keyboard and screen reader interaction with them -- List cases when **focus** needs to be **trapped** in sections of the UI (for dialogs and popups or for hierarchical navigation) -- List cases when **focus** needs to be **moved programatically** (if parts of the UI are appearing/disappearing or other cases) +- An `aria-label` is added to the `Skeleton` container to let users know that content is loading diff --git a/packages/react-components/react-table/Spec.md b/packages/react-components/react-table/Spec.md deleted file mode 100644 index db55ed2e132899..00000000000000 --- a/packages/react-components/react-table/Spec.md +++ /dev/null @@ -1,505 +0,0 @@ -# @fluentui/react-table Spec - -## Background - -A table is a control that represents information in a two dimensional format in rows and columns. -A table can also be interactive where the user can navigation each individual cell in the table using -keyboard or nest controls inside table cells. Tables should can include both header and footer cells -that can be used to label the data in the associated cells or facilitate data sorting. - -## Prior Art - -- https://open-ui.org/components/table.research -- [23983](https://github.com/microsoft/fluentui/issues/23983) - -### Comparison of v8 and v0 - -- v0 [Table](https://fluentsite.z22.web.core.windows.net/components/table/props) component -- v8 [DetailsList](https://developer.microsoft.com/en-us/fluentui#/controls/web/detailslist) component - -The equivalent of the proposed Table component is DetailsList for v8 and Table in v0. There are many differences -between the two are the complexity of the built-in features of these components. The v0 Table off-loads more complex -scenarios to the end user rather than built in. The v8 DetailsList owns a lot of the complex features of a table -such as selection, sorting, virtualization and marquee selection. - -#### Focusability and interaction - -The v0 Table supports row and cell keyboard navigation through focusing. This is done through an accessibility behaviour -prop. - -```tsx - -``` - -The v8 DetailsList supports focusing rows and navigating rows using arrow keys by default. - -Row navigation behaves the same way for v0 and v8. Each table row is focusable and navigable using the up and down -arrow keys. Using up or down arrow while focused on a cell will focus the next row. - -In v0 if there are nested focusable elements inside a focusable cell, then the user must press `Enter` to move focus -into the cell. The focus inside a cell is trapped and focus can only revert to the cell when the user presses `Escape`. v8 -handles this in a completely different way. Cells are not focusable by default but the FocusZone component will allow -horizontal cell navigation by the the focusable elements. - -The pattern followed by v0 has a drawback that there is no screen reader prompt to let users know that a table cell -contains interactive elements. The pattern followed by v8 however has a drawback that custom handling is necessary -when the cell contents also need to support arrow key navigation. - -#### Selection - -The v0 table does not support any built-in selection features. However guidance on how to implement a table with -selectable rows is provided in [prototypes on the docsite](https://fluentsite.z22.web.core.windows.net/0.63.0/prototype-table). - -The v8 DetailsList supports row selection by displaying a checkbox on first column that indicates the selection status -of the row. The first column of the header is also a checkbox that can either indicate the selection status of the -rows or can be used to toggle selection of all rows in the list. Additionally, the DetailsList supports marquee selection -where a user can click and drag a selection box that will select every row that is partially contained within the selection box. - -v8 uses a non-standard Selection class that is passed as reference through props to get the current selection state of the list. -The architecture choice for selection is most likely related to having to support marquee selection as a composite behaviour. - -```tsx -_selection = new Selection({ - onSelectionChanged: () => { - this.setState({ - selectionDetails: this._getSelectionDetails(), - }); - }, -}); - -; - -// Marquee selection - - ; -; -``` - -Selection in the DetailsList is also possible with keyboard by holding down the `Shift` key while using up and down -arrow to navigate rows. The next focused row is selected if `Shift` is pressed. - -#### Sorting - -Both v0 Table and v8 DetailsList provide code samples of sorting data by column that follow the same principle. The component -APIs both allow events for column click which can be used to sort data. - -```tsx -// v0 -const sortColumnHeader = (title, order, onOrderChange) => ({ - content: `${title} ${order !== 0 ? order === 1 ? : : ''}` - onClick: () => onOrderChange(order === 0 ? 1 : -order), -}); - -const header = { - key: 'header', - items: columns.map(c => - sortColumnHeader(c.title, c.name === sortColumn ? sortDirection : 0, newSortDirection => { - setSortColumn(c.name); - setSortDirection(newSortDirection); - }), - ), -}; - -
; - -// v8 -const onColumnClick = (ev: React.MouseEvent, column: IColumn): void => { - // sort data -}; - -const columns: IColumn[] = [ - { - name: 'File Type', - fieldName: 'name', - onColumnClick: onColumnClick, - }, - { - name: 'Name', - fieldName: 'name', - onColumnClick: onColumnClick, - }, -]; - - -``` - -#### Column resizing - -Column resizing is only supported by the v8 DetailsList. Columns can be resized without any additional configuration. -In order to support this, every column always has an inline style where the width in pixels is applied. - -## Sample Code - -```tsx -
- - - - - - - - - - - - - - - -
-``` - -## Variants - -### Sorting - -The table header should support design and interactions for sorting the table by column. - -### Selectable rows - -Table rows can be selected. The table header should also support a 'select all' feature, selecting the -table header should select all rows. - -### Primary column - -A primary column is generally the first column of the table, however there is no strict requirement on this. This -column has some design differences and supports secondary content which can contain extra instructions or -description. - -### Column actions - -Each cell can support optional buttons/actions that only appear when focused or the row is hovered. - -#### Cell media - -A cell can also include a media item such as an icon or an avatar positioned at the start of the cell. - -### Sizes - -The table supports the following sizes that affect the layout and size of its child components: - -- small -- smaller -- medium -- large - -## API - -### Table - -The `Table` component is intended to present data in a tabular format. Apart from sortable headers, the component -is intended to be presentational and not interactive. This component can also be a bail out for end users if -overriding the default interaction behaviour of the `DataGrid` component is too difficult. - -- [Table](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/Table/Table.types.ts); -- [TableHeader](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/TableHeader/TableHeader.types.ts); -- [TableRow](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/TableRow/TableRow.types.ts); -- [TableCell](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/TableCell/TableCell.types.ts); -- [TableCellLayout](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/TableCellLayout/TableCellLayout.types.ts); -- [TableBody](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/TableBody/TableBody.types.ts); -- [TableSelectionCell](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/TableSelectionCell/TableSelectionCell.types.ts); - -### DataGrid - -- [DataGrid](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGrid/DataGrid.types.ts); -- [DataGridHeader](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGridHeader/DataGridHeader.types.ts); -- [DataGridRow](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGridRow/DataGridRow.types.ts); -- [DataGridCell](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGridCell/DataGridCell.types.ts); -- [DataGridCellLayout](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGridCellLayout/DataGridCellLayout.types.ts); -- [DataGridBody](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGridBody/DataGridBody.types.ts); -- [DataGridSelectionCell](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGridSelectionCell/DataGridSelectionCell.types.ts); - -## Structure - -### Table - -```tsx - - - - - - - - - - - - -
-``` - -```html - - - - - - - - - - - - -
-``` - -### Table cell with media - -```tsx - - - }>Cell - - -``` - -```html - - FileIcon Cell - -``` - -### Table without semantic elements - -```tsx - - - - Header - - -
- -// OR - - - - - Header - - -
-``` - -```html -
-
-
-
-
-
-
-``` - -### Sortable - -```tsx - - - - Header - - -
-``` - -```html - - - - - - -
-``` - -### Primary column - -```tsx - - - - - } appearance="primary"> - Children - - - - -
-``` - -```html - - - - - - -
- -
- Main content - Description -
- Children -
-``` - -### Column actions - -```tsx - - - - }> - Content -
-``` - -```html - - - - - - -
- - Content -
- -
-
-``` - -### DataGrid - -```tsx - item.file.label} - onSelectionChange={(e, data) => console.log(data)} -> - - - {({ renderHeaderCell }) => {renderHeaderCell()}} - - - > - {({ item, rowId }) => ( - key={rowId} selectionCell={{ 'aria-label': 'Select row' }}> - {({ renderCell }) => {renderCell(item)}} - - )} - - -``` - -```html -
-
-
-
-
-
- -
-
-
-
-
-
-``` - -## Migration - -> ⚒️ This section is still being developed and will be completed once APIs for this component become more stable - -## Behaviors - -### Sortable header cells - -Table header cells are only focusable when they are sortable. Focus when tabbing into the Table control should -focus on the first sortable header, if any. - - - - - -### Navigation modes - -The below are the different navigation modes that are possible on a table - -#### none - -This mode is the default, there is no keyboard navigation possible in the table content. However, this does not -include the header cells which can be sortable. They are covered above. - -#### cell - -This is the most accessible and screenreader friendly navigation mode. This is what is recommended by the -[WAI APG examples](https://www.w3.org/WAI/ARIA/apg/example-index/grid/dataGrids). Navigation happsn only -on the level of the cell in both directions. - - - - - - - -#### row - -This navigation mode can cause screen reader issues since tables are not intended to be navigated by row in any mode. -This mode only navigates the table by row and can be useful when row selection is the only interactive feature of -the component - - - - - -### Nested focusables in cells - -#### Single focusable - -When there is a single focusable element inside a cell, users are recommended to choose `cell` navigation mode. -In this scenario, cells will be focused on navigation, but the focusable -element inside the cell should be focused if it exists. - - - - -#### Nested focusable - -When there are multile focusable elemnts inside a cell, we implement a pattern similar to the [WAI grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/). -Pressing `Enter` on a cell will move focus and trap focus inside until the user presses `Escape` to revert back to grid navigation. - - - - - -## Accessibility - -The spec aims to use the accessibility section as little as possible and building an accessible component by default. -The follow a11y resources were used in the drafting of this spec: - -- https://www.w3.org/WAI/ARIA/apg/patterns/grid/ -- https://www.w3.org/WAI/ARIA/apg/example-index/grid/dataGrids -- https://www.w3.org/WAI/ARIA/apg/example-index/table/sortable-table.html -- https://www.w3.org/WAI/ARIA/apg/example-index/table/table -- https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role -- https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/table_role diff --git a/packages/react-components/react-table/docs/Spec.md b/packages/react-components/react-table/docs/Spec.md index 35fe6b2c237c95..db55ed2e132899 100644 --- a/packages/react-components/react-table/docs/Spec.md +++ b/packages/react-components/react-table/docs/Spec.md @@ -2,62 +2,504 @@ ## Background -_Description and use cases of this component_ +A table is a control that represents information in a two dimensional format in rows and columns. +A table can also be interactive where the user can navigation each individual cell in the table using +keyboard or nest controls inside table cells. Tables should can include both header and footer cells +that can be used to label the data in the associated cells or facilitate data sorting. ## Prior Art -_Include background research done for this component_ +- https://open-ui.org/components/table.research +- [23983](https://github.com/microsoft/fluentui/issues/23983) -- _Link to Open UI research_ -- _Link to comparison of v7 and v0_ -- _Link to GitHub epic issue for the converged component_ +### Comparison of v8 and v0 + +- v0 [Table](https://fluentsite.z22.web.core.windows.net/components/table/props) component +- v8 [DetailsList](https://developer.microsoft.com/en-us/fluentui#/controls/web/detailslist) component + +The equivalent of the proposed Table component is DetailsList for v8 and Table in v0. There are many differences +between the two are the complexity of the built-in features of these components. The v0 Table off-loads more complex +scenarios to the end user rather than built in. The v8 DetailsList owns a lot of the complex features of a table +such as selection, sorting, virtualization and marquee selection. + +#### Focusability and interaction + +The v0 Table supports row and cell keyboard navigation through focusing. This is done through an accessibility behaviour +prop. + +```tsx + +``` + +The v8 DetailsList supports focusing rows and navigating rows using arrow keys by default. + +Row navigation behaves the same way for v0 and v8. Each table row is focusable and navigable using the up and down +arrow keys. Using up or down arrow while focused on a cell will focus the next row. + +In v0 if there are nested focusable elements inside a focusable cell, then the user must press `Enter` to move focus +into the cell. The focus inside a cell is trapped and focus can only revert to the cell when the user presses `Escape`. v8 +handles this in a completely different way. Cells are not focusable by default but the FocusZone component will allow +horizontal cell navigation by the the focusable elements. + +The pattern followed by v0 has a drawback that there is no screen reader prompt to let users know that a table cell +contains interactive elements. The pattern followed by v8 however has a drawback that custom handling is necessary +when the cell contents also need to support arrow key navigation. + +#### Selection + +The v0 table does not support any built-in selection features. However guidance on how to implement a table with +selectable rows is provided in [prototypes on the docsite](https://fluentsite.z22.web.core.windows.net/0.63.0/prototype-table). + +The v8 DetailsList supports row selection by displaying a checkbox on first column that indicates the selection status +of the row. The first column of the header is also a checkbox that can either indicate the selection status of the +rows or can be used to toggle selection of all rows in the list. Additionally, the DetailsList supports marquee selection +where a user can click and drag a selection box that will select every row that is partially contained within the selection box. + +v8 uses a non-standard Selection class that is passed as reference through props to get the current selection state of the list. +The architecture choice for selection is most likely related to having to support marquee selection as a composite behaviour. + +```tsx +_selection = new Selection({ + onSelectionChanged: () => { + this.setState({ + selectionDetails: this._getSelectionDetails(), + }); + }, +}); + +; + +// Marquee selection + + ; +; +``` + +Selection in the DetailsList is also possible with keyboard by holding down the `Shift` key while using up and down +arrow to navigate rows. The next focused row is selected if `Shift` is pressed. + +#### Sorting + +Both v0 Table and v8 DetailsList provide code samples of sorting data by column that follow the same principle. The component +APIs both allow events for column click which can be used to sort data. + +```tsx +// v0 +const sortColumnHeader = (title, order, onOrderChange) => ({ + content: `${title} ${order !== 0 ? order === 1 ? : : ''}` + onClick: () => onOrderChange(order === 0 ? 1 : -order), +}); + +const header = { + key: 'header', + items: columns.map(c => + sortColumnHeader(c.title, c.name === sortColumn ? sortDirection : 0, newSortDirection => { + setSortColumn(c.name); + setSortDirection(newSortDirection); + }), + ), +}; + +
; + +// v8 +const onColumnClick = (ev: React.MouseEvent, column: IColumn): void => { + // sort data +}; + +const columns: IColumn[] = [ + { + name: 'File Type', + fieldName: 'name', + onColumnClick: onColumnClick, + }, + { + name: 'Name', + fieldName: 'name', + onColumnClick: onColumnClick, + }, +]; + + +``` + +#### Column resizing + +Column resizing is only supported by the v8 DetailsList. Columns can be resized without any additional configuration. +In order to support this, every column always has an inline style where the width in pixels is applied. ## Sample Code -_Provide some representative example code that uses the proposed API for the component_ +```tsx +
+ + + + + + + + + + + + + + + +
+``` ## Variants -_Describe visual or functional variants of this control, if applicable. For example, a slider could have a 2D variant._ +### Sorting + +The table header should support design and interactions for sorting the table by column. + +### Selectable rows + +Table rows can be selected. The table header should also support a 'select all' feature, selecting the +table header should select all rows. + +### Primary column + +A primary column is generally the first column of the table, however there is no strict requirement on this. This +column has some design differences and supports secondary content which can contain extra instructions or +description. + +### Column actions + +Each cell can support optional buttons/actions that only appear when focused or the row is hovered. + +#### Cell media + +A cell can also include a media item such as an icon or an avatar positioned at the start of the cell. + +### Sizes + +The table supports the following sizes that affect the layout and size of its child components: + +- small +- smaller +- medium +- large ## API -_List the **Props** and **Slots** proposed for the component. Ideally this would just be a link to the component's `.types.ts` file_ +### Table + +The `Table` component is intended to present data in a tabular format. Apart from sortable headers, the component +is intended to be presentational and not interactive. This component can also be a bail out for end users if +overriding the default interaction behaviour of the `DataGrid` component is too difficult. + +- [Table](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/Table/Table.types.ts); +- [TableHeader](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/TableHeader/TableHeader.types.ts); +- [TableRow](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/TableRow/TableRow.types.ts); +- [TableCell](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/TableCell/TableCell.types.ts); +- [TableCellLayout](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/TableCellLayout/TableCellLayout.types.ts); +- [TableBody](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/TableBody/TableBody.types.ts); +- [TableSelectionCell](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/TableSelectionCell/TableSelectionCell.types.ts); + +### DataGrid + +- [DataGrid](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGrid/DataGrid.types.ts); +- [DataGridHeader](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGridHeader/DataGridHeader.types.ts); +- [DataGridRow](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGridRow/DataGridRow.types.ts); +- [DataGridCell](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGridCell/DataGridCell.types.ts); +- [DataGridCellLayout](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGridCellLayout/DataGridCellLayout.types.ts); +- [DataGridBody](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGridBody/DataGridBody.types.ts); +- [DataGridSelectionCell](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-table/src/components/DataGridSelectionCell/DataGridSelectionCell.types.ts); ## Structure -- _**Public**_ -- _**Internal**_ -- _**DOM** - how the component will be rendered as HTML elements_ +### Table -## Migration +```tsx + + + + + + + + + + + + +
+``` + +```html + + + + + + + + + + + + +
+``` + +### Table cell with media + +```tsx + + + }>Cell + + +``` + +```html + + FileIcon Cell + +``` + +### Table without semantic elements + +```tsx + + + + Header + + +
+ +// OR + + + + + Header + + +
+``` + +```html +
+
+
+
+
+
+
+``` + +### Sortable + +```tsx + + + + Header + + +
+``` + +```html + + + + + + +
+``` + +### Primary column + +```tsx + + + + + } appearance="primary"> + Children + + + + +
+``` + +```html + + + + + + +
+ +
+ Main content + Description +
+ Children +
+``` + +### Column actions + +```tsx + + + + }> + Content +
+``` + +```html + + + + + + +
+ + Content +
+ +
+
+``` + +### DataGrid -_Describe what will need to be done to upgrade from the existing implementations:_ +```tsx + item.file.label} + onSelectionChange={(e, data) => console.log(data)} +> + + + {({ renderHeaderCell }) => {renderHeaderCell()}} + + + > + {({ item, rowId }) => ( + key={rowId} selectionCell={{ 'aria-label': 'Select row' }}> + {({ renderCell }) => {renderCell(item)}} + + )} + + +``` -- _Migration from v8_ -- _Migration from v0_ +```html +
+
+
+
+
+
+ +
+
+
+
+
+
+``` + +## Migration + +> ⚒️ This section is still being developed and will be completed once APIs for this component become more stable ## Behaviors -_Explain how the component will behave in use, including:_ +### Sortable header cells + +Table header cells are only focusable when they are sortable. Focus when tabbing into the Table control should +focus on the first sortable header, if any. + + + + + +### Navigation modes + +The below are the different navigation modes that are possible on a table + +#### none + +This mode is the default, there is no keyboard navigation possible in the table content. However, this does not +include the header cells which can be sortable. They are covered above. + +#### cell -- _Component States_ -- _Interaction_ - - _Keyboard_ - - _Cursor_ - - _Touch_ - - _Screen readers_ +This is the most accessible and screenreader friendly navigation mode. This is what is recommended by the +[WAI APG examples](https://www.w3.org/WAI/ARIA/apg/example-index/grid/dataGrids). Navigation happsn only +on the level of the cell in both directions. + + + + + + +#### row + +This navigation mode can cause screen reader issues since tables are not intended to be navigated by row in any mode. +This mode only navigates the table by row and can be useful when row selection is the only interactive feature of +the component + + + + + +### Nested focusables in cells + +#### Single focusable + +When there is a single focusable element inside a cell, users are recommended to choose `cell` navigation mode. +In this scenario, cells will be focused on navigation, but the focusable +element inside the cell should be focused if it exists. + + + + +#### Nested focusable + +When there are multile focusable elemnts inside a cell, we implement a pattern similar to the [WAI grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/). +Pressing `Enter` on a cell will move focus and trap focus inside until the user presses `Escape` to revert back to grid navigation. + + + + + ## Accessibility -Base accessibility information is included in the design document. After the spec is filled and review, outcomes from it need to be communicated to design and incorporated in the design document. - -- Decide whether to use **native element** or folow **ARIA** and provide reasons -- Identify the **[ARIA](https://www.w3.org/TR/wai-aria-practices-1.2/) pattern** and, if the component is listed there, follow its specification as possible. -- Identify accessibility **variants**, the `role` ([ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#role_definitions)) of the component, its `slots` and `aria-*` props. -- Describe the **keyboard navigation**: Tab Oder and Arrow Key Navigation. Describe any other keyboard **shortcuts** used -- Specify texts for **state change announcements** - [ARIA live regions - ](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) (number of available items in dropdown, error messages, confirmations, ...) -- Identify UI parts that appear on **hover or focus** and specify keyboard and screen reader interaction with them -- List cases when **focus** needs to be **trapped** in sections of the UI (for dialogs and popups or for hierarchical navigation) -- List cases when **focus** needs to be **moved programatically** (if parts of the UI are appearing/disappearing or other cases) +The spec aims to use the accessibility section as little as possible and building an accessible component by default. +The follow a11y resources were used in the drafting of this spec: + +- https://www.w3.org/WAI/ARIA/apg/patterns/grid/ +- https://www.w3.org/WAI/ARIA/apg/example-index/grid/dataGrids +- https://www.w3.org/WAI/ARIA/apg/example-index/table/sortable-table.html +- https://www.w3.org/WAI/ARIA/apg/example-index/table/table +- https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role +- https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/table_role