docs: add min-width styles to Table and DataGrid stories, add best pr…

…actices (microsoft#31721)
miroslavstastny · Jun 17, 2024 · 41835e7 · 41835e7
1 parent 1fb910e
commit 41835e7
Show file tree

Hide file tree

Showing 36 changed files with 113 additions and 27 deletions.
diff --git a/packages/react-components/react-table/stories/src/DataGrid/CompositeNavigation.stories.tsx b/packages/react-components/react-table/stories/src/DataGrid/CompositeNavigation.stories.tsx
@@ -138,7 +138,13 @@ const columns: TableColumnDefinition<Item>[] = [
 
 export const CompositeNavigation = () => {
   return (
-    <DataGrid selectionMode="multiselect" items={items} columns={columns} focusMode="composite">
+    <DataGrid
+      selectionMode="multiselect"
+      items={items}
+      columns={columns}
+      focusMode="composite"
+      style={{ minWidth: '550px' }}
+    >
       <DataGridHeader>
         <DataGridRow selectionCell={{ checkboxIndicator: { 'aria-label': 'Select all rows' } }}>
           {({ renderHeaderCell }) => <DataGridHeaderCell>{renderHeaderCell()}</DataGridHeaderCell>}

diff --git a/packages/react-components/react-table/stories/src/DataGrid/CustomRowId.stories.tsx b/packages/react-components/react-table/stories/src/DataGrid/CustomRowId.stories.tsx
@@ -175,6 +175,7 @@ export const CustomRowId = () => {
         selectedItems={selectedRows}
         onSelectionChange={onSelectionChange}
         getRowId={item => item.file.label}
+        style={{ minWidth: '550px' }}
       >
         <DataGridHeader>
           <DataGridRow selectionCell={{ checkboxIndicator: { 'aria-label': 'Select all rows' } }}>

diff --git a/...ages/react-components/react-table/stories/src/DataGrid/DataGridBestPractices.md b/...ages/react-components/react-table/stories/src/DataGrid/DataGridBestPractices.md
@@ -0,0 +1,13 @@
+## Best Practices
+
+### Do
+
+- Always enclude a `DataGridHeader` row.
+- When the DataGrid is preceded by a heading or other visible labelling text, use `aria-labelledby` to point to the heading's `id`.
+- When the DataGrid does not have any visible text label, use `aria-label` to give it an accessible name.
+- Set a `min-width` style to ensure the DataGrid displays properly at high zoom levels or small screens.
+
+### Don't
+
+- Use DataGrid to display single-column content.
+- Override the `role` attribute of DataGrid controls.
diff --git a/packages/react-components/react-table/stories/src/DataGrid/Default.stories.tsx b/packages/react-components/react-table/stories/src/DataGrid/Default.stories.tsx
@@ -157,6 +157,7 @@ export const Default = () => {
       selectionMode="multiselect"
       getRowId={item => item.file.label}
       focusMode="composite"
+      style={{ minWidth: '550px' }}
     >
       <DataGridHeader>
         <DataGridRow selectionCell={{ checkboxIndicator: { 'aria-label': 'Select all rows' } }}>

diff --git a/...es/react-components/react-table/stories/src/DataGrid/FocusableElementsInCells.stories.tsx b/...es/react-components/react-table/stories/src/DataGrid/FocusableElementsInCells.stories.tsx
@@ -147,6 +147,7 @@ export const FocusableElementsInCells = () => {
       selectionMode="multiselect"
       getRowId={item => item.file.label}
       onSelectionChange={(e, data) => console.log(data)}
+      style={{ minWidth: '550px' }}
     >
       <DataGridHeader>
         <DataGridRow selectionCell={{ checkboxIndicator: { 'aria-label': 'Select all rows' } }}>

diff --git a/packages/react-components/react-table/stories/src/DataGrid/MultipleSelect.stories.tsx b/packages/react-components/react-table/stories/src/DataGrid/MultipleSelect.stories.tsx
@@ -152,7 +152,13 @@ export const MultipleSelect = () => {
   const defaultSelectedItems = React.useMemo(() => new Set([1]), []);
 
   return (
-    <DataGrid items={items} columns={columns} selectionMode="multiselect" defaultSelectedItems={defaultSelectedItems}>
+    <DataGrid
+      items={items}
+      columns={columns}
+      selectionMode="multiselect"
+      defaultSelectedItems={defaultSelectedItems}
+      style={{ minWidth: '550px' }}
+    >
       <DataGridHeader>
         <DataGridRow selectionCell={{ checkboxIndicator: { 'aria-label': 'Select all rows' } }}>
           {({ renderHeaderCell }) => <DataGridHeaderCell>{renderHeaderCell()}</DataGridHeaderCell>}

diff --git a/...es/react-components/react-table/stories/src/DataGrid/MultipleSelectControlled.stories.tsx b/...es/react-components/react-table/stories/src/DataGrid/MultipleSelectControlled.stories.tsx
@@ -163,6 +163,7 @@ export const MultipleSelectControlled = () => {
       selectionMode="multiselect"
       selectedItems={selectedRows}
       onSelectionChange={onSelectionChange}
+      style={{ minWidth: '550px' }}
     >
       <DataGridHeader>
         <DataGridRow selectionCell={{ checkboxIndicator: { 'aria-label': 'Select all rows' } }}>

diff --git a/packages/react-components/react-table/stories/src/DataGrid/SelectionAppearance.stories.tsx b/packages/react-components/react-table/stories/src/DataGrid/SelectionAppearance.stories.tsx
@@ -158,6 +158,7 @@ export const SelectionAppearance = () => {
       selectionMode="multiselect"
       selectionAppearance="neutral"
       defaultSelectedItems={defaultSelectedItems}
+      style={{ minWidth: '550px' }}
     >
       <DataGridHeader>
         <DataGridRow selectionCell={{ checkboxIndicator: { 'aria-label': 'Select all rows' } }}>

diff --git a/packages/react-components/react-table/stories/src/DataGrid/SingleSelect.stories.tsx b/packages/react-components/react-table/stories/src/DataGrid/SingleSelect.stories.tsx
@@ -152,7 +152,13 @@ export const SingleSelect = () => {
   const defaultSelectedItems = React.useMemo(() => new Set([1]), []);
 
   return (
-    <DataGrid items={items} columns={columns} selectionMode="single" defaultSelectedItems={defaultSelectedItems}>
+    <DataGrid
+      items={items}
+      columns={columns}
+      selectionMode="single"
+      defaultSelectedItems={defaultSelectedItems}
+      style={{ minWidth: '550px' }}
+    >
       <DataGridHeader>
         <DataGridRow>
           {({ renderHeaderCell }) => <DataGridHeaderCell>{renderHeaderCell()}</DataGridHeaderCell>}

diff --git a/...ages/react-components/react-table/stories/src/DataGrid/SingleSelectControlled.stories.tsx b/...ages/react-components/react-table/stories/src/DataGrid/SingleSelectControlled.stories.tsx
@@ -163,6 +163,7 @@ export const SingleSelectControlled = () => {
       selectionMode="single"
       selectedItems={selectedRows}
       onSelectionChange={onSelectionChange}
+      style={{ minWidth: '550px' }}
     >
       <DataGridHeader>
         <DataGridRow>

diff --git a/packages/react-components/react-table/stories/src/DataGrid/Sort.stories.tsx b/packages/react-components/react-table/stories/src/DataGrid/Sort.stories.tsx
@@ -153,7 +153,7 @@ export const Sort = () => {
   );
 
   return (
-    <DataGrid items={items} columns={columns} defaultSortState={defaultSortState}>
+    <DataGrid items={items} columns={columns} defaultSortState={defaultSortState} style={{ minWidth: '500px' }}>
       <DataGridHeader>
         <DataGridRow>
           {({ renderHeaderCell }) => <DataGridHeaderCell>{renderHeaderCell()}</DataGridHeaderCell>}

diff --git a/packages/react-components/react-table/stories/src/DataGrid/SortControlled.stories.tsx b/packages/react-components/react-table/stories/src/DataGrid/SortControlled.stories.tsx
@@ -159,7 +159,14 @@ export const SortControlled = () => {
   };
 
   return (
-    <DataGrid items={items} columns={columns} sortable sortState={sortState} onSortChange={onSortChange}>
+    <DataGrid
+      items={items}
+      columns={columns}
+      sortable
+      sortState={sortState}
+      onSortChange={onSortChange}
+      style={{ minWidth: '500px' }}
+    >
       <DataGridHeader>
         <DataGridRow>
           {({ renderHeaderCell }) => <DataGridHeaderCell>{renderHeaderCell()}</DataGridHeaderCell>}

diff --git a/packages/react-components/react-table/stories/src/DataGrid/SubtleSelection.stories.tsx b/packages/react-components/react-table/stories/src/DataGrid/SubtleSelection.stories.tsx
@@ -158,6 +158,7 @@ export const SubtleSelection = () => {
       selectionMode="multiselect"
       subtleSelection
       defaultSelectedItems={defaultSelectedItems}
+      style={{ minWidth: '550px' }}
     >
       <DataGridHeader>
         <DataGridRow selectionCell={{ checkboxIndicator: { 'aria-label': 'Select all rows' } }}>

diff --git a/packages/react-components/react-table/stories/src/DataGrid/index.stories.tsx b/packages/react-components/react-table/stories/src/DataGrid/index.stories.tsx
@@ -8,6 +8,7 @@ import {
   DataGridSelectionCell,
 } from '@fluentui/react-components';
 import descriptionMd from './DataGridDescription.md';
+import bestPracticesMd from './DataGridBestPractices.md';
 
 export { Default } from './Default.stories';
 export { CompositeNavigation } from './CompositeNavigation.stories';
@@ -39,7 +40,7 @@ export default {
   parameters: {
     docs: {
       description: {
-        component: [descriptionMd].join('\n'),
+        component: [descriptionMd, bestPracticesMd].join('\n'),
       },
     },
   },

diff --git a/packages/react-components/react-table/stories/src/Table/CellActions.stories.tsx b/packages/react-components/react-table/stories/src/Table/CellActions.stories.tsx
@@ -77,7 +77,7 @@ const columns = [
 
 export const CellActions = () => {
   return (
-    <Table aria-label="Table with cell actions">
+    <Table aria-label="Table with cell actions" style={{ minWidth: '500px' }}>
       <TableHeader>
         <TableRow>
           {columns.map(column => (

diff --git a/packages/react-components/react-table/stories/src/Table/CellNavigation.stories.tsx b/packages/react-components/react-table/stories/src/Table/CellNavigation.stories.tsx
@@ -72,7 +72,12 @@ export const CellNavigation = () => {
   const keyboardNavAttr = useArrowNavigationGroup({ axis: 'grid' });
 
   return (
-    <Table {...keyboardNavAttr} role="grid" aria-label="Table with grid keyboard navigation">
+    <Table
+      {...keyboardNavAttr}
+      role="grid"
+      aria-label="Table with grid keyboard navigation"
+      style={{ minWidth: '600px' }}
+    >
       <TableHeader>
         <TableRow>
           {columns.map(column => (

diff --git a/packages/react-components/react-table/stories/src/Table/CompositeNavigation.stories.tsx b/packages/react-components/react-table/stories/src/Table/CompositeNavigation.stories.tsx
@@ -76,6 +76,7 @@ export const CompositeNavigation = () => {
       aria-label="Table with grid keyboard navigation"
       noNativeElements
       onKeyDown={onTableKeyDown}
+      style={{ minWidth: '500px' }}
       {...tableTabsterAttribute}
     >
       <TableHeader>

diff --git a/packages/react-components/react-table/stories/src/Table/DataGrid.stories.tsx b/packages/react-components/react-table/stories/src/Table/DataGrid.stories.tsx
@@ -168,7 +168,13 @@ export const DataGrid = () => {
   const keyboardNavAttr = useArrowNavigationGroup({ axis: 'grid' });
 
   return (
-    <Table {...keyboardNavAttr} role="grid" sortable aria-label="DataGrid implementation with Table primitives">
+    <Table
+      {...keyboardNavAttr}
+      role="grid"
+      sortable
+      aria-label="DataGrid implementation with Table primitives"
+      style={{ minWidth: '550px' }}
+    >
       <TableHeader>
         <TableRow>
           <TableSelectionCell

diff --git a/packages/react-components/react-table/stories/src/Table/Default.stories.tsx b/packages/react-components/react-table/stories/src/Table/Default.stories.tsx
@@ -68,7 +68,7 @@ const columns = [
 
 export const Default = () => {
   return (
-    <Table arial-label="Default table">
+    <Table arial-label="Default table" style={{ minWidth: '510px' }}>
       <TableHeader>
         <TableRow>
           {columns.map(column => (

diff --git a/packages/react-components/react-table/stories/src/Table/FocusableElements.Cells.stories.tsx b/packages/react-components/react-table/stories/src/Table/FocusableElements.Cells.stories.tsx
@@ -67,6 +67,7 @@ const columns = [
   { columnKey: 'file', label: 'File' },
   { columnKey: 'author', label: 'Author' },
   { columnKey: 'lastUpdated', label: 'Last updated' },
+  { columnKey: 'lastUpdate', label: 'Last update' },
   { columnKey: 'actions', label: 'Actions' },
 ];
 
@@ -75,13 +76,17 @@ export const FocusableElementsInCells = () => {
   const focusableGroupAttr = useFocusableGroup({ tabBehavior: 'limited-trap-focus' });
 
   return (
-    <Table {...keyboardNavAttr} role="grid" aria-label="Table with grid keyboard navigation">
+    <Table
+      {...keyboardNavAttr}
+      role="grid"
+      aria-label="Table with grid keyboard navigation"
+      style={{ minWidth: '620px' }}
+    >
       <TableHeader>
         <TableRow>
           {columns.map(column => (
             <TableHeaderCell key={column.columnKey}>{column.label}</TableHeaderCell>
           ))}
-          <TableHeaderCell />
         </TableRow>
       </TableHeader>
       <TableBody>
@@ -106,6 +111,9 @@ export const FocusableElementsInCells = () => {
             <TableCell tabIndex={0} role="gridcell">
               {item.lastUpdated.label}
             </TableCell>
+            <TableCell tabIndex={0} role="gridcell">
+              <TableCellLayout media={item.lastUpdate.icon}>{item.lastUpdate.label}</TableCellLayout>
+            </TableCell>
             <TableCell role="gridcell" tabIndex={0} {...focusableGroupAttr}>
               <TableCellLayout>
                 <Button icon={<EditRegular />} aria-label="Edit" />

diff --git a/packages/react-components/react-table/stories/src/Table/Memoization.stories.tsx b/packages/react-components/react-table/stories/src/Table/Memoization.stories.tsx
@@ -164,7 +164,13 @@ export const Memoization = () => {
   const keyboardNavAttr = useArrowNavigationGroup({ axis: 'grid' });
 
   return (
-    <Table {...keyboardNavAttr} role="grid" sortable aria-label="DataGrid implementation with Table primitives">
+    <Table
+      {...keyboardNavAttr}
+      role="grid"
+      sortable
+      aria-label="DataGrid implementation with Table primitives"
+      style={{ minWidth: '550px' }}
+    >
       <TableHeader>
         <TableRow>
           <TableSelectionCell

diff --git a/packages/react-components/react-table/stories/src/Table/MultipleSelect.stories.tsx b/packages/react-components/react-table/stories/src/Table/MultipleSelect.stories.tsx
@@ -150,7 +150,7 @@ export const MultipleSelect = () => {
   );
 
   return (
-    <Table aria-label="Table with multiselect">
+    <Table aria-label="Table with multiselect" style={{ minWidth: '550px' }}>
       <TableHeader>
         <TableRow>
           <TableSelectionCell

diff --git a/packages/react-components/react-table/stories/src/Table/MultipleSelectControlled.stories.tsx b/packages/react-components/react-table/stories/src/Table/MultipleSelectControlled.stories.tsx
@@ -154,7 +154,7 @@ export const MultipleSelectControlled = () => {
   );
 
   return (
-    <Table aria-label="Table with controlled multiselect">
+    <Table aria-label="Table with controlled multiselect" style={{ minWidth: '550px' }}>
       <TableHeader>
         <TableRow>
           <TableSelectionCell

diff --git a/packages/react-components/react-table/stories/src/Table/NonNativeElements.stories.tsx b/packages/react-components/react-table/stories/src/Table/NonNativeElements.stories.tsx
@@ -68,7 +68,7 @@ const columns = [
 
 export const NonNativeElements = () => {
   return (
-    <Table noNativeElements aria-label="Table without semantic HTML elements">
+    <Table noNativeElements aria-label="Table without semantic HTML elements" style={{ minWidth: '500px' }}>
       <TableHeader>
         <TableRow>
           {columns.map(column => (

diff --git a/packages/react-components/react-table/stories/src/Table/PrimaryCell.stories.tsx b/packages/react-components/react-table/stories/src/Table/PrimaryCell.stories.tsx
@@ -77,7 +77,7 @@ const columns = [
 
 export const PrimaryCell = () => {
   return (
-    <Table aria-label="Table with primary cell layout">
+    <Table aria-label="Table with primary cell layout" style={{ minWidth: '500px' }}>
       <TableHeader>
         <TableRow>
           {columns.map(column => (

diff --git a/packages/react-components/react-table/stories/src/Table/SelectionWithCellActions.stories.tsx b/packages/react-components/react-table/stories/src/Table/SelectionWithCellActions.stories.tsx
@@ -162,7 +162,7 @@ export const SelectionWithCellActions = () => {
   const onKeyDownCellActions = (e: React.KeyboardEvent<HTMLDivElement>) => e.key === ' ' && e.preventDefault();
 
   return (
-    <Table aria-label="Table with multiselect">
+    <Table aria-label="Table with multiselect" style={{ minWidth: '550px' }}>
       <TableHeader>
         <TableRow>
           <TableSelectionCell

diff --git a/packages/react-components/react-table/stories/src/Table/SingleSelect.stories.tsx b/packages/react-components/react-table/stories/src/Table/SingleSelect.stories.tsx
@@ -140,7 +140,7 @@ export const SingleSelect = () => {
   });
 
   return (
-    <Table aria-label="Table with single selection">
+    <Table aria-label="Table with single selection" style={{ minWidth: '550px' }}>
       <TableHeader>
         <TableRow>
           <TableSelectionCell type="radio" invisible />

diff --git a/packages/react-components/react-table/stories/src/Table/SingleSelectControlled.stories.tsx b/packages/react-components/react-table/stories/src/Table/SingleSelectControlled.stories.tsx
@@ -143,7 +143,7 @@ export const SingleSelectControlled = () => {
   });
 
   return (
-    <Table aria-label="Table with controlled single selection">
+    <Table aria-label="Table with controlled single selection" style={{ minWidth: '550px' }}>
       <TableHeader>
         <TableRow>
           <TableSelectionCell type="radio" invisible />

diff --git a/packages/react-components/react-table/stories/src/Table/SizeExtraSmall.stories.tsx b/packages/react-components/react-table/stories/src/Table/SizeExtraSmall.stories.tsx
@@ -67,7 +67,7 @@ const columns = [
 
 export const SizeExtraSmall = () => {
   return (
-    <Table size="extra-small" aria-label="Table with extra-small size">
+    <Table size="extra-small" aria-label="Table with extra-small size" style={{ minWidth: '400px' }}>
       <TableHeader>
         <TableRow>
           {columns.map(column => (

diff --git a/packages/react-components/react-table/stories/src/Table/SizeSmall.stories.tsx b/packages/react-components/react-table/stories/src/Table/SizeSmall.stories.tsx
@@ -67,7 +67,7 @@ const columns = [
 
 export const SizeSmall = () => {
   return (
-    <Table size="small" aria-label="Table with small size">
+    <Table size="small" aria-label="Table with small size" style={{ minWidth: '475px' }}>
       <TableHeader>
         <TableRow>
           {columns.map(column => (

diff --git a/packages/react-components/react-table/stories/src/Table/Sort.stories.tsx b/packages/react-components/react-table/stories/src/Table/Sort.stories.tsx
@@ -140,7 +140,7 @@ export const Sort = () => {
   const rows = sort(getRows());
 
   return (
-    <Table sortable aria-label="Table with sort">
+    <Table sortable aria-label="Table with sort" style={{ minWidth: '500px' }}>
       <TableHeader>
         <TableRow>
           <TableHeaderCell {...headerSortProps('file')}>File</TableHeaderCell>

diff --git a/packages/react-components/react-table/stories/src/Table/SortControlled.stories.tsx b/packages/react-components/react-table/stories/src/Table/SortControlled.stories.tsx
@@ -146,7 +146,7 @@ export const SortControlled = () => {
   const rows = sort(getRows());
 
   return (
-    <Table sortable aria-label="Table with controlled sort">
+    <Table sortable aria-label="Table with controlled sort" style={{ minWidth: '500px' }}>
       <TableHeader>
         <TableRow>
           <TableHeaderCell {...headerSortProps('file')}>File</TableHeaderCell>

diff --git a/packages/react-components/react-table/stories/src/Table/SubtleSelection.stories.tsx b/packages/react-components/react-table/stories/src/Table/SubtleSelection.stories.tsx
@@ -150,7 +150,7 @@ export const SubtleSelection = () => {
   );
 
   return (
-    <Table aria-label="Table with subtle selection">
+    <Table aria-label="Table with subtle selection" style={{ minWidth: '550px' }}>
       <TableHeader>
         <TableRow>
           <TableSelectionCell

diff --git a/packages/react-components/react-table/stories/src/Table/TableBestPractices.md b/packages/react-components/react-table/stories/src/Table/TableBestPractices.md
@@ -0,0 +1,13 @@
+## Best Practices
+
+### Do
+
+- Always enclude a `TableHeader` row.
+- When the Table is preceded by a heading or other visible labelling text, use `aria-labelledby` to point to the heading's `id`.
+- When the Table does not have any visible text label, use `aria-label` to give it an accessible name.
+- Set a `min-width` style to ensure the Table displays properly at high zoom levels or small screens.
+
+### Don't
+
+- Use Table to display single-column content.
+- Override the `role` attribute of Table controls.
diff --git a/packages/react-components/react-table/stories/src/Table/Virtualization.stories.tsx b/packages/react-components/react-table/stories/src/Table/Virtualization.stories.tsx
@@ -200,7 +200,7 @@ export const Virtualization = () => {
   );
 
   return (
-    <Table noNativeElements aria-label="Table with selection" aria-rowcount={rows.length}>
+    <Table noNativeElements aria-label="Table with selection" aria-rowcount={rows.length} style={{ minWidth: '650px' }}>
       <TableHeader>
         <TableRow aria-rowindex={1}>
           <TableSelectionCell