Improve Accessibility - captions (#957)

* Improve Accessibility - captions

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption

> A caption functions like a heading for a table. Most screen readers announce the content of captions. Captions help users to find a table and understand what it’s about and decide if they want to read it. If the user uses “Tables Mode”, captions are the primary mechanism to identify tables. The caption is provided by the <caption> element.

from: https://www.w3.org/WAI/tutorials/tables/caption-summary/

* renderCaption

---------

Co-authored-by: Kevin Van Cott <[email protected]>

packages/material-react-table/src/components/table/MRT_Table.tsx

@@ -27,6 +27,7 @@ export const MRT_Table = <TData extends MRT_RowData>({
       layoutMode,
       memoMode,
       muiTableProps,
+      renderCaption,
     },
   } = table;
   const { columnSizing, columnSizingInfo, columnVisibility, isFullScreen } =
@@ -37,6 +38,8 @@ export const MRT_Table = <TData extends MRT_RowData>({
     ...rest,
   };
 
+  const caption = parseFromValuesOrFunc(renderCaption, { table });
+
   const columnSizeVars = useMemo(() => {
     const headers = getFlatHeaders();
     const colSizes: { [key: string]: number } = {};
@@ -67,6 +70,7 @@ export const MRT_Table = <TData extends MRT_RowData>({
         ...(parseFromValuesOrFunc(tableProps?.sx, theme) as any),
       })}
     >
+      {!!caption && <caption>{caption}</caption>}
       {enableTableHead && <MRT_TableHead {...commonTableGroupProps} />}
       {memoMode === 'table-body' || columnSizingInfo.isResizingColumn ? (
         <Memo_MRT_TableBody {...commonTableGroupProps} />

packages/material-react-table/src/types.ts

@@ -1164,6 +1164,9 @@ export type MRT_TableOptions<TData extends MRT_RowData> = Omit<
   renderBottomToolbarCustomActions?: (props: {
     table: MRT_TableInstance<TData>;
   }) => ReactNode;
+  renderCaption?:
+    | ((props: { table: MRT_TableInstance<TData> }) => ReactNode)
+    | ReactNode;
   renderColumnActionsMenuItems?: (props: {
     closeMenu: () => void;
     column: MRT_Column<TData>;

packages/material-react-table/stories/styling/Caption.stories.tsx

@@ -0,0 +1,66 @@
+import { type MRT_ColumnDef, MaterialReactTable } from '../../src';
+import { faker } from '@faker-js/faker';
+import { type Meta } from '@storybook/react';
+
+const meta: Meta = {
+  title: 'Styling/Caption Examples',
+};
+
+export default meta;
+
+const columns: MRT_ColumnDef<(typeof data)[0]>[] = [
+  {
+    accessorKey: 'firstName',
+    header: 'First Name',
+  },
+  {
+    accessorKey: 'lastName',
+    header: 'Last Name',
+  },
+  {
+    accessorKey: 'age',
+    header: 'Age',
+  },
+  {
+    accessorKey: 'address',
+    header: 'Address',
+  },
+  {
+    accessorKey: 'state',
+    header: 'State',
+  },
+  {
+    accessorKey: 'phoneNumber',
+    header: 'Phone Number',
+  },
+];
+
+const data = [...Array(25)].map(() => ({
+  address: faker.location.streetAddress(),
+  age: faker.number.int({ max: 60, min: 20 }),
+  firstName: faker.person.firstName(),
+  lastName: faker.person.lastName(),
+  phoneNumber: faker.phone.number(),
+  state: faker.location.state(),
+}));
+
+export const BottomCaption = () => (
+  <MaterialReactTable
+    columns={columns}
+    data={data}
+    renderCaption={() => 'Table Caption'}
+  />
+);
+
+export const TopCaption = () => (
+  <MaterialReactTable
+    columns={columns}
+    data={data}
+    muiTableProps={{
+      sx: {
+        captionSide: 'top',
+      },
+    }}
+    renderCaption={() => 'Table Caption'}
+  />
+);