feat(Table, Datagrid): Added new tableTitle prop

.changeset/feat-table-datagrid-caption.md

@@ -0,0 +1,5 @@
+---
+'react-magma-dom': minor
+---
+
+feat(Table, Datagrid): Added new prop `tableTitle` to `Table` and `Datagrid` which supports a captioned title above each Table and Datagrid.

packages/react-magma-dom/src/components/Datagrid/Datagrid.stories.tsx

@@ -15,6 +15,7 @@ import { magma } from '../../theme/magma';
 import { Spacer, SpacerAxis } from '../Spacer';
 import { Announce } from '../Announce';
 import { VisuallyHidden } from '../VisuallyHidden';
+import { Heading } from '../Heading';
 
 const rowsForPagination = [
   {
@@ -282,6 +283,11 @@ export default {
         type: 'boolean',
       },
     },
+    tableTitle: {
+      control: {
+        type: 'text',
+      },
+    },
   },
 } as Meta;
 
@@ -337,18 +343,23 @@ const defaultArgs = {
 };
 
 export const Default = Template.bind({});
-Default.args = defaultArgs;
+Default.args = { ...defaultArgs, tableTitle: 'Default' };
+
+export const TitleWithNode = Template.bind({});
+TitleWithNode.args = { ...defaultArgs, tableTitle: <Heading level={1}>Title with node</Heading> };
 
 export const ColoredRows = Template.bind({});
 ColoredRows.args = {
   ...defaultArgs,
   rows: coloredRows,
+  tableTitle: 'Colored rows',
 };
 
 export const Selectable = Template.bind({});
 Selectable.args = {
   ...defaultArgs,
   isSelectable: true,
+  tableTitle: 'Selectable',
 };
 
 export const SelectableAndSortable: Story<DatagridProps> = ({
@@ -536,18 +547,21 @@ export const SelectableAndSortable: Story<DatagridProps> = ({
 SelectableAndSortable.args = {
   isSelectable: true,
   isSortableBySelected: true,
+  tableTitle: 'Selectable and sortable',
 };
 
 export const ControlledSelectable = ControlledTemplate.bind({});
 ControlledSelectable.args = {
   ...defaultArgs,
   isSelectable: true,
+  tableTitle: 'Controlled selectable',
 };
 
 export const DisabledSelectableRow = Template.bind({});
 DisabledSelectableRow.args = {
   ...defaultArgs,
   isSelectable: true,
+  tableTitle: 'Disabled selectable row',
   rows: [
     ...defaultArgs.rows,
     {
@@ -564,6 +578,7 @@ DisabledSelectableRow.args = {
 export const PaginationChangedDefaults = Template.bind({});
 PaginationChangedDefaults.args = {
   ...defaultArgs,
+  tableTitle: 'Pagination changed defaults',
   paginationProps: {
     defaultPage: 2,
     defaultRowsPerPage: 5,
@@ -574,6 +589,7 @@ PaginationChangedDefaults.args = {
 export const ControlledPagination = ControlledPaginatedTemplate.bind({});
 ControlledPagination.args = {
   ...defaultArgs,
+  tableTitle: 'Controlled pagination',
   paginationProps: {
     rowsPerPageValues: [5, 10, 20],
   },
@@ -582,6 +598,7 @@ ControlledPagination.args = {
 export const WithoutPagination = Template.bind({});
 WithoutPagination.args = {
   ...defaultArgs,
+  tableTitle: 'Without pagination',
   hasPagination: false,
 };
 
@@ -627,6 +644,7 @@ const CustomPaginationComponent: React.FunctionComponent<
 export const PaginationWithCustomComponent = Template.bind({});
 PaginationWithCustomComponent.args = {
   ...defaultArgs,
+  tableTitle: 'Pagination with custom component',
   components: {
     Pagination: CustomPaginationComponent,
   },

packages/react-magma-dom/src/components/Datagrid/Datagrid.test.js

@@ -4,7 +4,12 @@ import { Datagrid } from '.';
 import { TableRowColor } from '../Table';
 import { Button } from '../Button';
 import { usePagination } from '../Pagination/usePagination';
-import { render, screen, fireEvent } from '@testing-library/react';
+import {
+  render,
+  screen,
+  fireEvent,
+  getByDisplayValue,
+} from '@testing-library/react';
 import { magma } from '../../theme/magma';
 
 const columns = [
@@ -836,6 +841,18 @@ describe('Datagrid', () => {
     });
   });
 
+  it('should display the title', () => {
+    const { getByText } = render(
+      <Datagrid
+        columns={columns}
+        rows={rowsForPagination}
+        tableTitle="Datagrid title"
+      />
+    );
+
+    expect(getByText('Datagrid title')).toBeInTheDocument();
+  });
+
   it('Does not violate accessibility standards', () => {
     const { container } = render(<Datagrid columns={columns} rows={rows} />);
 

packages/react-magma-dom/src/components/Datagrid/Datagrid.tsx

@@ -3,6 +3,9 @@ import { useControlled } from '../../hooks/useControlled';
 import { useDataPagination } from '../../hooks/useDataPagination';
 import { XOR } from '../../utils';
 import { IndeterminateCheckboxStatus } from '../IndeterminateCheckbox';
+import { StyledCaption } from '../Table';
+import { ThemeContext } from '../../theme/ThemeContext';
+
 import {
   Table,
   TableBody,
@@ -51,6 +54,10 @@ export interface DatagridRow {
    * Used to allow each unique column field as a key with the row content as the value
    */
   [key: string]: any;
+  /**
+   * Title that appears above the Datagrid
+   */
+  tableTitle?: React.ReactNode | string;
 }
 
 export interface DatagridComponents {
@@ -160,6 +167,7 @@ export const Datagrid = React.forwardRef<HTMLTableElement, DatagridProps>(
       selectedRows: selectedRowsProp,
       hasPagination = true,
       onSortBySelected,
+      tableTitle,
       sortDirection,
       ...other
     } = props;
@@ -169,6 +177,8 @@ export const Datagrid = React.forwardRef<HTMLTableElement, DatagridProps>(
       default: defaultSelectedRows,
     });
 
+    const theme = React.useContext(ThemeContext);
+
     const isControlled = selectedRowsProp ? true : false;
 
     const {
@@ -278,6 +288,12 @@ export const Datagrid = React.forwardRef<HTMLTableElement, DatagridProps>(
 
     return (
       <>
+        {tableTitle && (
+          <StyledCaption isInverse={props.isInverse} isTitleNode={typeof tableTitle !== 'string'} theme={theme}>
+            {tableTitle}
+          </StyledCaption>
+        )}
+
         <Table {...other} ref={ref} aria-live="polite">
           <TableHead>
             <TableRow