chore: improve DataGrid colspan props, types and docs (#2597)

* chore: improve DataGrid colspan props, types and docs * chore: respond to PR feedback * chore: add props to doc site mdx Co-authored-by: Shadi <TheSisb@users.noreply.github.com>
twilio-labs · Aug 9, 2022 · e21a9ff · e21a9ff
1 parent 3640836
commit e21a9ff
Show file tree

Hide file tree

Showing 8 changed files with 74 additions and 9 deletions.
diff --git a/.changeset/dull-singers-decide.md b/.changeset/dull-singers-decide.md
@@ -0,0 +1,6 @@
+---
+'@twilio-paste/core': patch
+'@twilio-paste/data-grid': patch
+---
+
+[Data Grid] include supporting types and documentation for existing colSpan prop
diff --git a/packages/paste-core/components/data-grid/__tests__/index.spec.tsx b/packages/paste-core/components/data-grid/__tests__/index.spec.tsx
@@ -3,11 +3,14 @@ import {Button} from '@twilio-paste/button';
 import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
-import {DataGridHeaderSort} from '../src';
-import {ComposableCellsDataGrid} from '../stories/components/ComposableCellsDataGrid';
-import {SortableColumnsDataGrid} from '../stories/components/SortableColumnsDataGrid';
-import {PaginatedDataGrid} from '../stories/components/PaginatedDataGrid';
-import {PlainDataGrid} from '../stories/components/PlainDataGrid';
+import {DataGridCell, DataGridHeaderSort, DataGridHeader} from '../src';
+import {
+  ColumnSpanDataGrid,
+  ComposableCellsDataGrid,
+  SortableColumnsDataGrid,
+  PaginatedDataGrid,
+  PlainDataGrid,
+} from '../stories/index.stories';
 
 const checkTagName = (el: Element, name: string): void => expect(el.tagName).toBe(name.toUpperCase());
 
@@ -42,6 +45,14 @@ describe('Data Grid', () => {
     });
   });
 
+  describe('Column Span', () => {
+    it('applies colSpan attribute as expected', () => {
+      const {getByTestId} = render(<ColumnSpanDataGrid />);
+      const th = getByTestId('data-grid-header');
+      expect(th).toHaveAttribute('colspan', '5');
+    });
+  });
+
   describe('Composable Cells functionality', () => {
     it('has proper keyboard navigation behavior', () => {
       const {getByTestId} = render(<ComposableCellsDataGrid />);

diff --git a/packages/paste-core/components/data-grid/src/DataGridCell.tsx b/packages/paste-core/components/data-grid/src/DataGridCell.tsx
@@ -14,16 +14,17 @@ import isElement from 'lodash/isElement';
 
 type CellType = 'th' | 'td';
 export interface DataGridCellProps extends Pick<TdProps, 'textAlign'> {
-  colSpan?: number;
   as?: CellType;
   element?: BoxElementProps['element'];
+  colSpan?: number;
 }
 
 /**
  * DataGrid cell component. Every visible box in a data grid is powered by the cell.
  *
- * @param {"th" | "td"} as - is it a header or a regular cell
- * @param {string} element - customization element
+ * @param {"th" | "td"} [as=td] - is it a header or a regular cell
+ * @param {string} [element=DATA_GRID_CELL] - customization element
+ * @param {number} [colSpan] - how many columns the cell spans across
  */
 export const DataGridCell: React.FC<DataGridCellProps> = ({element = 'DATA_GRID_CELL', as = 'td', ...props}) => {
   const dataGridState = React.useContext(DataGridContext);
@@ -95,4 +96,5 @@ DataGridCell.displayName = 'DataGridCell';
 DataGridCell.propTypes = {
   as: PropTypes.oneOf<CellType>(['th', 'td']),
   element: PropTypes.string,
+  colSpan: PropTypes.number,
 };
diff --git a/packages/paste-core/components/data-grid/src/DataGridHeader.tsx b/packages/paste-core/components/data-grid/src/DataGridHeader.tsx
@@ -2,11 +2,13 @@ import * as React from 'react';
 import * as PropTypes from 'prop-types';
 import {DataGridCell} from './DataGridCell';
 import type {ThProps} from './table/Th';
+
 /**
  * DataGrid header (th) component.
  * Just a wrapper around the DataGridCell.
  *
- * @param {string} element - customization element
+ * @param {string} [element=DATA_GRID_HEADER] - customization element
+ * @param {number} [colSpan] - how many columns the cell spans across
  */
 export const DataGridHeader: React.FC<ThProps> = ({element = 'DATA_GRID_HEADER', ...props}) => {
   return <DataGridCell element={element} {...props} as="th" />;
@@ -15,4 +17,5 @@ export const DataGridHeader: React.FC<ThProps> = ({element = 'DATA_GRID_HEADER',
 DataGridHeader.displayName = 'DataGridHeader';
 DataGridHeader.propTypes = {
   element: PropTypes.string,
+  colSpan: PropTypes.number,
 };
diff --git a/packages/paste-core/components/data-grid/src/table/Th.tsx b/packages/paste-core/components/data-grid/src/table/Th.tsx
@@ -9,6 +9,7 @@ export interface ThProps {
   width?: string;
   onClick?: React.MouseEventHandler;
   element?: BoxElementProps['element'];
+  colSpan?: number;
 }
 
 export const Th = React.forwardRef<HTMLTableCellElement, ThProps>(
@@ -48,4 +49,5 @@ Th.propTypes = {
   onClick: PropTypes.func,
   width: PropTypes.string,
   element: PropTypes.string,
+  colSpan: PropTypes.number,
 };
diff --git a/packages/paste-core/components/data-grid/stories/components/ColumnSpanDataGrid.tsx b/packages/paste-core/components/data-grid/stories/components/ColumnSpanDataGrid.tsx
@@ -0,0 +1,38 @@
+import * as React from 'react';
+import type {BoxProps} from '@twilio-paste/box';
+import {DataGrid, DataGridHead, DataGridRow, DataGridHeader, DataGridBody, DataGridCell} from '../../src';
+import {TableBodyData} from './constants';
+
+export const ColumnSpanDataGrid: React.FC<{element?: BoxProps['element']}> = ({element = 'DATA_GRID'}) => {
+  return (
+    <DataGrid aria-label="User information table" data-testid="data-grid" element={element} striped>
+      <DataGridHead data-testid="data-grid-head" element={`${element}_HEAD`}>
+        <DataGridRow element={`${element}_ROW`}>
+          <DataGridHeader colSpan={5} data-testid="data-grid-header" element={`${element}_HEADER`}>
+            User Information
+          </DataGridHeader>
+        </DataGridRow>
+      </DataGridHead>
+      <DataGridBody data-testid="data-grid-body" element={`${element}_BODY`}>
+        {TableBodyData.map((row, rowIndex) => (
+          <DataGridRow
+            key={`row-${rowIndex}`}
+            data-testid={rowIndex === 0 ? 'data-grid-row' : null}
+            element={`${element}_ROW`}
+          >
+            {row.map((col, colIndex) => (
+              <DataGridCell
+                element={`${element}_CELL`}
+                key={`col-${colIndex}`}
+                data-testid={rowIndex === 0 && colIndex === 0 ? 'data-grid-cell' : null}
+                textAlign={colIndex === 4 ? 'right' : 'left'}
+              >
+                {col}
+              </DataGridCell>
+            ))}
+          </DataGridRow>
+        ))}
+      </DataGridBody>
+    </DataGrid>
+  );
+};
diff --git a/packages/paste-core/components/data-grid/stories/index.stories.tsx b/packages/paste-core/components/data-grid/stories/index.stories.tsx
@@ -7,6 +7,7 @@ export {SortableColumnsDataGrid} from './components/SortableColumnsDataGrid';
 export {KitchenSinkDataGrid} from './components/KitchenSinkDataGrid';
 export {I18nDataGrid} from './components/I18nDataGrid';
 export {DataGridLayouts} from './components/DataGridLayouts';
+export {ColumnSpanDataGrid} from './components/ColumnSpanDataGrid';
 
 // eslint-disable-next-line import/no-default-export
 export default {

diff --git a/packages/paste-website/src/pages/components/data-grid/index.mdx b/packages/paste-website/src/pages/components/data-grid/index.mdx
@@ -390,6 +390,7 @@ const Component = () => (
 | textAlign? | `string`    | CSS text align for this cell                                                              | `left`             |
 | width?     | `string`    | Allows setting column width programmatically                                              | null               |
 | element?   | `string`    | Overrides the default element name to apply unique styles with the Customization Provider | `DATA_GRID_HEADER` |
+| colSpan?   | `number`    | How many columns the cell spans across                                                    | null               |
 | children?  | `ReactNode` |                                                                                           | null               |
 
 #### DataGridHeaderSort Props
@@ -418,6 +419,7 @@ const Component = () => (
 | as?        | "th", "td"  | Cells can either be th or td, so rows can have headers.                                   | `td`             |
 | textAlign? | `string`    | CSS text align for this cell                                                              | `left`           |
 | element?   | `string`    | Overrides the default element name to apply unique styles with the Customization Provider | `DATA_GRID_CELL` |
+| colSpan?   | `number`    | How many columns the cell spans across                                                    | null             |
 | children?  | `ReactNode` |                                                                                           | null             |
 
 <ChangelogRevealer>