feat: Add colspan to Table (#7638)

* Add colSpan support to table cells

* Add aria-col-index to cells

* Don't set colspan in useGridCell

* Add colspan and colindex in collections

* Add colspan unit tests

* Add check to validate that cells total length match col length to react-aria-components

* Don't throw when isSSR

* Remove interfering test

* Re-add throwing tests

* Add check to validate number of cells match col length in GridCollection

* Rename colspan to colSpan

* Move colSpan prop down to useGridCell

* remove unneeded prop assignments

---------

Co-authored-by: Robert Snow <[email protected]>
Co-authored-by: GitHub <[email protected]>

Author: oyvinmar

packages/@react-aria/grid/src/GridKeyboardDelegate.ts

@@ -13,7 +13,7 @@
 import {Direction, DisabledBehavior, Key, KeyboardDelegate, LayoutDelegate, Node, Rect, RefObject, Size} from '@react-types/shared';
 import {DOMLayoutDelegate} from '@react-aria/selection';
 import {getChildNodes, getFirstItem, getLastItem, getNthItem} from '@react-stately/collections';
-import {GridCollection} from '@react-types/grid';
+import {GridCollection, GridNode} from '@react-types/grid';
 
 export interface GridKeyboardDelegateOptions<C> {
   collection: C,
@@ -103,6 +103,35 @@ export class GridKeyboardDelegate<T, C extends GridCollection<T>> implements Key
     return null;
   }
 
+  protected getKeyForItemInRowByIndex(key: Key, index: number = 0): Key | null {
+    if (index < 0) {
+      return null;
+    }
+
+    let item = this.collection.getItem(key);
+    if (!item) {
+      return null;
+    }
+
+    let i = 0;
+    for (let child of getChildNodes(item, this.collection) as Iterable<GridNode<T>>) {
+      if (child.colSpan && child.colSpan + i > index) {
+        return child.key ?? null;
+      }
+
+      if (child.colSpan) {
+        i = i + child.colSpan - 1;
+      }
+
+      if (i === index) {
+        return child.key ?? null;
+      }
+
+      i++;
+    }
+    return null;
+  }
+
   getKeyBelow(fromKey: Key) {
     let key: Key | null = fromKey;
     let startItem = this.collection.getItem(key);
@@ -123,11 +152,8 @@ export class GridKeyboardDelegate<T, C extends GridCollection<T>> implements Key
     if (key != null) {
       // If focus was on a cell, focus the cell with the same index in the next row.
       if (this.isCell(startItem)) {
-        let item = this.collection.getItem(key);
-        if (!item) {
-          return null;
-        }
-        return getNthItem(getChildNodes(item, this.collection), startItem.index ?? 0)?.key ?? null;
+        let startIndex = startItem.colIndex ? startItem.colIndex : startItem.index;
+        return this.getKeyForItemInRowByIndex(key, startIndex);
       }
 
       // Otherwise, focus the next row
@@ -158,11 +184,8 @@ export class GridKeyboardDelegate<T, C extends GridCollection<T>> implements Key
     if (key != null) {
       // If focus was on a cell, focus the cell with the same index in the previous row.
       if (this.isCell(startItem)) {
-        let item = this.collection.getItem(key);
-        if (!item) {
-          return null;
-        }
-        return getNthItem(getChildNodes(item, this.collection), startItem.index ?? 0)?.key || null;
+        let startIndex = startItem.colIndex ? startItem.colIndex : startItem.index;
+        return this.getKeyForItemInRowByIndex(key, startIndex);
       }
 
       // Otherwise, focus the previous row

packages/@react-aria/grid/src/useGridCell.ts

@@ -30,6 +30,8 @@ export interface GridCellProps {
   focusMode?: 'child' | 'cell',
   /** Whether selection should occur on press up instead of press down. */
   shouldSelectOnPressUp?: boolean,
+  /** Indicates how many columns the data cell spans. */
+  colSpan?: number,
   /**
    * Handler that is called when a user performs an action on the cell.
    * Please use onCellAction at the collection level instead.
@@ -251,6 +253,9 @@ export function useGridCell<T, C extends GridCollection<T>>(props: GridCellProps
   let gridCellProps: DOMAttributes = mergeProps(itemProps, {
     role: 'gridcell',
     onKeyDownCapture,
+    'aria-colspan': node.colSpan,
+    'aria-colindex': node.colIndex != null ? node.colIndex + 1 : undefined, // aria-colindex is 1-based
+    colSpan: isVirtualized ? undefined : node.colSpan,
     onFocus
   });
 

packages/@react-aria/table/docs/useTable.mdx

@@ -245,9 +245,8 @@ function TableColumnHeader({column, state}) {
   return (
     <th
       {...mergeProps(columnHeaderProps, focusProps)}
-      colSpan={column.colspan}
       style={{
-        textAlign: column.colspan > 1 ? 'center' : 'left',
+        textAlign: column.colSpan > 1 ? 'center' : 'left',
         padding: '5px 10px',
         outline: 'none',
         boxShadow: isFocusVisible ? 'inset 0 0 0 2px orange' : 'none',
@@ -767,7 +766,7 @@ function AsyncSortTable() {
 
 ### Nested columns
 
-Columns can be nested to create column groups. This will result in more than one header row to be created, with the `colspan`
+Columns can be nested to create column groups. This will result in more than one header row to be created, with the `colSpan`
 attribute of each column header cell set to the appropriate value so that the columns line up. Data for the leaf columns
 appears in each row of the table body.
 

packages/@react-aria/table/src/TableKeyboardDelegate.ts

@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import {getChildNodes, getFirstItem, getNthItem} from '@react-stately/collections';
+import {getChildNodes, getFirstItem} from '@react-stately/collections';
 import {GridKeyboardDelegate} from '@react-aria/grid';
 import {Key, Node} from '@react-types/shared';
 import {TableCollection} from '@react-types/table';
@@ -44,7 +44,8 @@ export class TableKeyboardDelegate<T> extends GridKeyboardDelegate<T, TableColle
       if (!firstItem) {
         return null;
       }
-      return getNthItem(getChildNodes(firstItem, this.collection), startItem.index)?.key ?? null;
+
+      return super.getKeyForItemInRowByIndex(firstKey, startItem.index);
     }
 
     return super.getKeyBelow(key);

packages/@react-aria/table/src/useTableColumnHeader.ts

@@ -99,7 +99,7 @@ export function useTableColumnHeader<T>(props: AriaTableColumnHeaderProps<T>, st
       ),
       role: 'columnheader',
       id: getColumnHeaderId(state, node.key),
-      'aria-colspan': node.colspan && node.colspan > 1 ? node.colspan : undefined,
+      'aria-colspan': node.colSpan && node.colSpan > 1 ? node.colSpan : undefined,
       'aria-sort': ariaSort
     }
   };

packages/@react-aria/table/stories/example-backwards-compat.tsx

@@ -103,9 +103,8 @@ export function TableColumnHeader({column, state}) {
   return (
     <th
       {...mergeProps(columnHeaderProps, focusProps)}
-      colSpan={column.colspan}
       style={{
-        textAlign: column.colspan > 1 ? 'center' : 'left',
+        textAlign: column.colSpan > 1 ? 'center' : 'left',
         padding: '5px 10px',
         outline: isFocusVisible ? '2px solid orange' : 'none',
         cursor: 'default'

packages/@react-aria/table/stories/example-resizing.tsx

@@ -171,10 +171,9 @@ export function TableColumnHeader({column, state, layout, onResizeStart, onResiz
   return (
     <th
       {...mergeProps(columnHeaderProps, focusProps)}
-      colSpan={column.colspan}
       style={{
         width: layout.getColumnWidth(column.key),
-        textAlign: column.colspan > 1 ? 'center' : 'left',
+        textAlign: column.colSpan > 1 ? 'center' : 'left',
         padding: '5px 10px',
         outline: isFocusVisible ? '2px solid orange' : 'none',
         cursor: 'default',

packages/@react-aria/table/stories/example.tsx

@@ -102,9 +102,8 @@ export function TableColumnHeader({column, state}) {
   return (
     <th
       {...mergeProps(columnHeaderProps, focusProps)}
-      colSpan={column.colspan}
       style={{
-        textAlign: column.colspan > 1 ? 'center' : 'left',
+        textAlign: column.colSpan > 1 ? 'center' : 'left',
         padding: '5px 10px',
         outline: isFocusVisible ? '2px solid orange' : 'none',
         cursor: 'default'

packages/@react-spectrum/table/src/TableViewBase.tsx

@@ -337,7 +337,7 @@ function TableViewBase<T extends object>(props: TableBaseProps<T>, ref: DOMRef<H
           <div
             role="gridcell"
             aria-colindex={item.index + 1}
-            aria-colspan={item.colspan != null && item.colspan > 1 ? item.colspan : undefined} />
+            aria-colspan={item.colSpan != null && item.colSpan > 1 ? item.colSpan : undefined} />
         );
       case 'column':
         if (item.props.isSelectionCell) {
@@ -783,7 +783,7 @@ function TableColumnHeader(props) {
               stylesOverrides,
               'react-spectrum-Table-cell',
               {
-                'react-spectrum-Table-cell--alignCenter': columnProps.align === 'center' || column.colspan > 1,
+                'react-spectrum-Table-cell--alignCenter': columnProps.align === 'center' || column.colSpan > 1,
                 'react-spectrum-Table-cell--alignEnd': columnProps.align === 'end'
               }
             )
@@ -914,7 +914,7 @@ function ResizableTableColumnHeader(props) {
   let showResizer = !isEmpty && ((headerRowHovered && getInteractionModality() !== 'keyboard') || resizingColumn != null);
   let alignment = 'start';
   let menuAlign = 'start' as 'start' | 'end';
-  if (columnProps.align === 'center' || column.colspan > 1) {
+  if (columnProps.align === 'center' || column.colSpan > 1) {
     alignment = 'center';
   } else if (columnProps.align === 'end') {
     alignment = 'end';

packages/@react-spectrum/table/stories/Table.stories.tsx

@@ -423,6 +423,105 @@ export const DynamicNestedColumnsWithResizing: TableStory = {
   name: 'dynamic with nested columns with resizing'
 };
 
+
+let timeTableColumns = [
+  {name: 'Time', key: 'time', isRowHeader: true},
+  {name: 'Monday', key: 'monday'},
+  {name: 'Tuesday', key: 'tuesday'},
+  {name: 'Wednesday', key: 'wednesday'},
+  {name: 'Thursday', key: 'thursday'},
+  {name: 'Friday', key: 'friday'}
+];
+
+
+let timeTableRows = [
+  {id: 9, time: '09:00 - 10:00', name: 'Break', type: 'break'},
+  {id: 1, time: '08:00 - 09:00', monday: 'Math', tuesday: 'History', wednesday: 'Science', thursday: 'English', friday: 'Art'},
+  {id: 2, time: '09:00 - 10:00', name: 'Break', type: 'break'},
+  {id: 3, time: '10:00 - 11:00', monday: 'Math', tuesday: 'History', wednesday: 'Science', thursday: 'English', friday: 'Art'},
+  {id: 4, time: '11:00 - 12:00', monday: 'Math', tuesday: 'History', wednesday: 'Science', thursday: 'English', friday: 'Art'},
+  {id: 5, time: '12:00 - 13:00', name: 'Break', type: 'break'},
+  {id: 6, time: '13:00 - 14:00', monday: 'History', tuesday: 'Math', wednesday: 'English', thursday: 'Science', friday: 'Art'}
+];
+
+export const TableColSpanExample = () => {
+  return (
+    <TableView aria-label="Timetable">
+      <TableHeader columns={timeTableColumns}>
+        {(column) => (
+          <Column isRowHeader={column.isRowHeader}>{column.name}</Column>
+        )}
+      </TableHeader>
+      <TableBody items={timeTableRows}>
+        {(item) => (
+          <Row key={item.id}>
+            {item.type === 'break' ? (
+            [
+              <Cell>{item.time}</Cell>,
+              <Cell colSpan={5}>{item.name}</Cell>
+            ]) : ([
+              <Cell>{item.time}</Cell>,
+              <Cell>{item.monday}</Cell>,
+              <Cell>{item.tuesday}</Cell>,
+              <Cell>{item.wednesday}</Cell>,
+              <Cell>{item.thursday}</Cell>,
+              <Cell>{item.friday}</Cell>]
+            )}
+          </Row>
+        )}
+      </TableBody>
+    </TableView>
+  );
+};
+
+export const TableCellColSpanWithVariousSpansExample = () => {
+  return (
+    <TableView aria-label="Table with various colspans">
+      <TableHeader>
+        <Column isRowHeader>Col 1</Column>
+        <Column >Col 2</Column>
+        <Column >Col 3</Column>
+        <Column >Col 4</Column>
+      </TableHeader>
+      <TableBody>
+        <Row>
+          <Cell>Cell</Cell>
+          <Cell colSpan={2}>Span 2</Cell>
+          <Cell>Cell</Cell>
+        </Row>
+        <Row>
+          <Cell>Cell</Cell>
+          <Cell>Cell</Cell>
+          <Cell>Cell</Cell>
+          <Cell>Cell</Cell>
+        </Row>
+        <Row>
+          <Cell colSpan={4}>Span 4</Cell>
+        </Row>
+        <Row>
+          <Cell>Cell</Cell>
+          <Cell>Cell</Cell>
+          <Cell>Cell</Cell>
+          <Cell>Cell</Cell>
+        </Row>
+        <Row>
+          <Cell colSpan={3}>Span 3</Cell>
+          <Cell>Cell</Cell>
+        </Row>
+        <Row>
+          <Cell>Cell</Cell>
+          <Cell>Cell</Cell>
+          <Cell>Cell</Cell>
+          <Cell>Cell</Cell>
+        </Row>
+        <Row>
+          <Cell>Cell</Cell>
+          <Cell colSpan={3}>Span 3</Cell>
+        </Row>
+      </TableBody>
+    </TableView>
+  );
+};
 export const FocusableCells: TableStory = {
   args: {
     'aria-label': 'TableView with focusable cells',