docs: Improves Table documentation

change/@fluentui-react-table-393b87fd-7546-484a-8f7f-c8bc7d2d6b08.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "docs: Update docstrings for props",
+  "packageName": "@fluentui/react-table",
+  "email": "lingfangao@hotmail.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-table/src/components/Table/Table.types.ts

@@ -7,18 +7,20 @@ export type TableSlots = {
 export type TableContextValue = {
   /**
    * Affects the sizes of all table subcomponents
-   * @default
+   * @default medium
    */
   size: 'extra-small' | 'small' | 'medium';
 
   /**
    * Render all table elements as divs intead of semantic table elements
    * Using divs no longer uses `display: table` layout but `display: flex`
+   * @default false
    */
   noNativeElements: boolean;
 
   /**
    * Whether the table is sortable
+   * @default false
    */
   sortable: boolean;
 };

packages/react-components/react-table/src/components/TableCellLayout/TableCellLayout.types.ts

@@ -36,6 +36,10 @@ export type TableCellLayoutSlots = {
  * TableCellLayout Props
  */
 export type TableCellLayoutProps = ComponentProps<Partial<TableCellLayoutSlots>> & {
+  /**
+   * Renders design variants of the table cell
+   * @default undefined
+   */
   appearance?: 'primary';
 };
 

packages/react-components/react-table/src/components/TableHeaderCell/TableHeaderCell.types.ts

@@ -17,6 +17,9 @@ export type TableHeaderCellSlots = {
  * TableHeaderCell Props
  */
 export type TableHeaderCellProps = ComponentProps<Partial<TableHeaderCellSlots>> & {
+  /**
+   * @default undefined
+   */
   sortDirection?: SortDirection;
 };
 

packages/react-components/react-table/src/components/TableRow/TableRow.types.ts

@@ -10,7 +10,8 @@ export type TableRowSlots = {
  */
 export type TableRowProps = ComponentProps<TableRowSlots> & {
   /**
-   * A table row can have different variants
+   * A table row can have different variants. These appearances are
+   * intended to be used with selection.
    * @default none
    */
   appearance?: 'brand' | 'neutral' | 'none';

packages/react-components/react-table/src/components/TableSelectionCell/TableSelectionCell.types.ts

@@ -20,17 +20,25 @@ export type TableSelectionCellSlots = {
  */
 export type TableSelectionCellProps = ComponentProps<Partial<Omit<TableSelectionCellSlots, 'media'>>> & {
   /**
-   * A table can have two kinds of selection modes
+   * A table can have two kinds of selection modes.
+   * @default checkbox
    */
   type?: 'checkbox' | 'radio';
+
+  /**
+   * @default false
+   */
   checked?: CheckboxProps['checked'];
+
   /**
-   * Only visible when checked or the parent row is hovered
+   * Only visible when checked or the parent row is hovered/focused
+   * @default false
    */
   subtle?: boolean;
 
   /**
    * Completely hides the selection cell visually but takes up the same space
+   * @default false
    */
   hidden?: boolean;
 };

packages/react-components/react-table/stories/Table/CellActions.stories.tsx

@@ -112,3 +112,16 @@ export const CellActions = () => {
     </Table>
   );
 };
+
+CellActions.parameters = {
+  docs: {
+    description: {
+      story: [
+        '`TableCellActions` is a container that is visible when the `TableRow`is hovered or focus lies within the',
+        'or when the current focused element is within the row. It is commonly used to contain interactive actions',
+        'like buttons, but can be used for any generic content. Please ensure that the contents of cell actions',
+        'are accessible.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-table/stories/Table/CellNavigation.stories.tsx

@@ -108,3 +108,15 @@ export const CellNavigation = () => {
     </Table>
   );
 };
+
+CellNavigation.parameters = {
+  docs: {
+    description: {
+      story: [
+        'The `Table` primitive components do not support keyboard navigation. This should be added by users.',
+        'Cell navigation can be achieved simply using the `useArrowNavigationGroup` utility provided by the Library.',
+        'user state.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-table/stories/Table/MultipleSelect.stories.tsx

@@ -184,3 +184,15 @@ export const MultipleSelect = () => {
     </Table>
   );
 };
+
+MultipleSelect.parameters = {
+  docs: {
+    description: {
+      story: [
+        'Selection can be achieved easily by combining the `TableSelectionCell` component along with',
+        'other primitive components. The hook can handle state management for selection, although its use is not',
+        'necessary if users already have their own state management.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-table/stories/Table/MultipleSelectControlled.stories.tsx

@@ -190,3 +190,14 @@ export const MultipleSelectControlled = () => {
     </Table>
   );
 };
+
+MultipleSelectControlled.parameters = {
+  docs: {
+    description: {
+      story: [
+        'By default our hook is uncontrolled. However, it is possible to control selection features with external',
+        'user state.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-table/stories/Table/NonNativeElements.stories.tsx

@@ -100,3 +100,17 @@ export const NonNativeElements = () => {
     </Table>
   );
 };
+
+NonNativeElements.parameters = {
+  docs: {
+    description: {
+      story: [
+        'By default `Table` components will render native semantic `<table>` HTML elements.',
+        'Native semantic elements provide the best accessibility support and it is recommended to user them.',
+        'However, for certain use cases (i.e. Virtualization) the native semantic elements are not advisable',
+        'due to strict browser layouting. Using the `noNativeElements` prop will ensure that all components are',
+        'rendered as divs while ensuring a layout experience similar to semantic table elements.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-table/stories/Table/PrimaryCell.stories.tsx

@@ -115,3 +115,15 @@ export const PrimaryCell = () => {
     </Table>
   );
 };
+
+PrimaryCell.parameters = {
+  docs: {
+    description: {
+      story: [
+        'A primary cell creates emphasis by increasing icon size and font weight for the main text.',
+        'Generally the primary cell should be used in the first column of a table, but there is no obligation',
+        'to do so and can be used in any column by the user.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-table/stories/Table/SingleSelect.stories.tsx

@@ -180,3 +180,17 @@ export const SingleSelect = () => {
     </Table>
   );
 };
+
+SingleSelect.parameters = {
+  docs: {
+    description: {
+      story: [
+        'The single selection scenario is similar to the multiple selection scenario. The `TableSelectionCell`',
+        'Can render both checkbox and radio style components which are Fluent',
+        '[Checkbox](?path=/docs/components-checkbox--default) and [Radio](?path=/docs/components-radio--default)',
+        'components. While the design recommendation is to use checkbox for multiselect and radio for single select.',
+        'There is no obligation to do so.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-table/stories/Table/SingleSelectControlled.stories.tsx

@@ -186,3 +186,14 @@ export const SingleSelectControlled = () => {
     </Table>
   );
 };
+
+SingleSelectControlled.parameters = {
+  docs: {
+    description: {
+      story: [
+        'By default our hook is uncontrolled. However, it is possible to control selection features with external',
+        'user state.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-table/stories/Table/Sort.stories.tsx

@@ -178,3 +178,15 @@ export const Sort = () => {
     </Table>
   );
 };
+
+Sort.parameters = {
+  docs: {
+    description: {
+      story: [
+        'Using the `sortable` prop will configure all header cells to be buttons and add extra styles.',
+        'The `TableHeaderCell` component accepts a `sortDirection` prop that will indicate whether the',
+        'header is sorted. Handling the sort of data and column state is handled by our hook.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-table/stories/Table/SortControlled.stories.tsx

@@ -183,3 +183,14 @@ export const SortControlled = () => {
     </Table>
   );
 };
+
+SortControlled.parameters = {
+  docs: {
+    description: {
+      story: [
+        'By default our hook is uncontrolled. However, it is possible to control sort features',
+        'with external user state.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-table/stories/Table/SubtleSelection.stories.tsx

@@ -184,3 +184,17 @@ export const SubtleSelection = () => {
     </Table>
   );
 };
+
+SubtleSelection.parameters = {
+  docs: {
+    description: {
+      story: [
+        'By setting the `subtle` prop on the `TableSelectionCell` component, the selection indicator will only',
+        'appear when:',
+        '- the `TableRow` component is hovered.',
+        '- The current focused element is within the `TableRow`',
+        '- The `TableSelectionCell` is checked',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-table/stories/Table/TableDescription.md

@@ -10,3 +10,12 @@
 >
 > - Features and APIs may change before final release
 > - Please contact us if you intend to use this in your product
+
+> 💡 This component is considered **low-level** and should be used when there is a need for more **customization** and
+> support for **non-standard features**. Please check out the [DataGrid component](?path=/docs/preview-components-datagrid--default)
+> if you don't need lots of customization and rely on common features. There is less work involved and you will benefit
+> from first class Microsoft design and accessibility support.
+
+A Table displays sets of two-dimensional data. The primitive components can be fully customized to support different
+feature sets. The library provides a default hook that handles the business logic and state management of common
+features. There is no obligation to use our hook with these components, we've created it for convenience.

packages/react-components/react-table/stories/Table/index.stories.tsx

@@ -1,24 +1,42 @@
-import { Table } from '@fluentui/react-components/unstable';
+import {
+  Table,
+  TableHeader,
+  TableHeaderCell,
+  TableBody,
+  TableRow,
+  TableCell,
+  TableSelectionCell,
+  TableCellLayout,
+} from '@fluentui/react-components/unstable';
 import descriptionMd from './TableDescription.md';
 
 export { Default } from './Default.stories';
-export { Sort } from './Sort.stories';
-export { SortControlled } from './SortControlled.stories';
-export { CellActions } from './CellActions.stories';
-export { PrimaryCell } from './PrimaryCell.stories';
 export { SizeSmall } from './SizeSmall.stories';
 export { SizeExtraSmall } from './SizeExtraSmall.stories';
 export { NonNativeElements } from './NonNativeElements.stories';
+export { CellActions } from './CellActions.stories';
+export { PrimaryCell } from './PrimaryCell.stories';
+export { CellNavigation } from './CellNavigation.stories';
+export { Sort } from './Sort.stories';
+export { SortControlled } from './SortControlled.stories';
 export { MultipleSelect } from './MultipleSelect.stories';
 export { SingleSelect } from './SingleSelect.stories';
 export { MultipleSelectControlled } from './MultipleSelectControlled.stories';
 export { SingleSelectControlled } from './SingleSelectControlled.stories';
-export { CellNavigation } from './CellNavigation.stories';
 export { SubtleSelection } from './SubtleSelection.stories';
 
 export default {
   title: 'Preview Components/Table',
   component: Table,
+  subcomponents: {
+    TableHeader,
+    TableHeaderCell,
+    TableBody,
+    TableRow,
+    TableCell,
+    TableSelectionCell,
+    TableCellLayout,
+  },
   parameters: {
     docs: {
       description: {