feat: Sticky header for atomic table components

Author: gethinwebster

pages/table-root/sticky-header.page.tsx

@@ -0,0 +1,114 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React, { useMemo, useState } from 'react';
+
+import Box from '~components/box';
+import Header from '~components/header';
+import SegmentedControl from '~components/segmented-control';
+import SpaceBetween from '~components/space-between';
+import TableBody from '~components/table-body';
+import TableBodyCell from '~components/table-body-cell';
+import TableHead from '~components/table-head';
+import TableHeaderCell from '~components/table-header-cell';
+import TableRoot, { TableRootProps } from '~components/table-root';
+import TableRow from '~components/table-row';
+
+// Sticky header in both layout modes. The Name header carries a sort button so the pinned copy's
+// pointer interaction can be exercised.
+
+const GRID_COLUMNS: ReadonlyArray<TableRootProps.ColumnDefinition> = [
+  { size: 260 },
+  { size: 260 },
+  { size: 260 },
+  { size: 260 },
+  { size: 260 },
+];
+const ROW_COUNT = 60;
+
+interface Row {
+  id: string;
+  name: string;
+  type: string;
+  size: string;
+  status: string;
+  region: string;
+}
+
+const makeRows = (n: number): Row[] =>
+  Array.from({ length: n }, (_, index) => ({
+    id: `row-${index}`,
+    name: `Resource ${String(index).padStart(3, '0')}`,
+    type: index % 3 === 0 ? 'Compute' : index % 3 === 1 ? 'Storage' : 'Network',
+    size: `${(index % 8) + 1} GiB`,
+    status: index % 2 === 0 ? 'Available' : 'Pending',
+    region: index % 2 === 0 ? 'us-east-1' : 'eu-west-1',
+  }));
+
+export default function TableStickyHeaderPage() {
+  const [layout, setLayout] = useState<'grid' | 'auto'>('grid');
+  const [ascending, setAscending] = useState(true);
+  const rows = useMemo(() => {
+    const direction = ascending ? 1 : -1;
+    return makeRows(ROW_COUNT).sort((a, b) => direction * a.name.localeCompare(b.name));
+  }, [ascending]);
+
+  const columnLayout: TableRootProps.ColumnLayout =
+    layout === 'grid' ? { type: 'grid', columns: GRID_COLUMNS } : { type: 'auto' };
+
+  return (
+    <Box padding="l">
+      <SpaceBetween size="l">
+        <Box variant="h1">Table atomics — sticky header</Box>
+        <Box color="text-body-secondary">
+          Scroll the page down — the header pins to the top. Scroll the table sideways — the pinned header tracks the
+          columns. Switch between grid and auto layout to exercise both alignment paths.
+        </Box>
+        <SegmentedControl
+          selectedId={layout}
+          onChange={({ detail }) => setLayout(detail.selectedId as 'grid' | 'auto')}
+          label="Column layout"
+          options={[
+            { id: 'grid', text: 'Grid layout' },
+            { id: 'auto', text: 'Auto layout' },
+          ]}
+        />
+        <Header counter={`(${rows.length})`}>Resources</Header>
+        <TableRoot
+          columnLayout={columnLayout}
+          ariaLabel="Resources"
+          stickyHeader={
+            <TableHead>
+              <TableRow>
+                <TableHeaderCell ariaSort={ascending ? 'ascending' : 'descending'}>
+                  <button
+                    type="button"
+                    onClick={() => setAscending(value => !value)}
+                    style={{ font: 'inherit', background: 'none', border: 0, padding: 0, cursor: 'pointer' }}
+                  >
+                    Name {ascending ? '▲' : '▼'}
+                  </button>
+                </TableHeaderCell>
+                <TableHeaderCell>Type</TableHeaderCell>
+                <TableHeaderCell>Size</TableHeaderCell>
+                <TableHeaderCell>Status</TableHeaderCell>
+                <TableHeaderCell>Region</TableHeaderCell>
+              </TableRow>
+            </TableHead>
+          }
+        >
+          <TableBody>
+            {rows.map(row => (
+              <TableRow key={row.id}>
+                <TableBodyCell>{row.name}</TableBodyCell>
+                <TableBodyCell>{row.type}</TableBodyCell>
+                <TableBodyCell>{row.size}</TableBodyCell>
+                <TableBodyCell>{row.status}</TableBodyCell>
+                <TableBodyCell>{row.region}</TableBodyCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </TableRoot>
+      </SpaceBetween>
+    </Box>
+  );
+}

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap

@@ -30931,13 +30931,27 @@ use the \`id\` attribute, consider setting it on a parent element instead.",
       "optional": true,
       "type": "string",
     },
+    {
+      "description": "Specifies a vertical offset (in pixels) for the sticky header. For example, use this if you
+need to position the sticky header below other fixed position elements on the page.",
+      "name": "stickyHeaderVerticalOffset",
+      "optional": true,
+      "type": "number",
+    },
   ],
   "regions": [
     {
-      "description": "The table's content. Provide a \`TableHead\` followed by a \`TableBody\` that contains the rows.",
+      "description": "The table's content. Provide a \`TableHead\` followed by a \`TableBody\` that contains the rows. When you
+use \`stickyHeader\`, provide only the \`TableBody\` here.",
       "isDefault": true,
       "name": "children",
     },
+    {
+      "description": "A \`TableHead\` that stays pinned to the top of its scroll container as the body scrolls. When you
+provide it, render only the \`TableBody\` as \`children\`.",
+      "isDefault": false,
+      "name": "stickyHeader",
+    },
   ],
   "releaseStatus": "stable",
 }

src/internal/components/sticky-header/__tests__/use-cells-resize-observer.test.tsx

@@ -5,9 +5,12 @@ import { useCellsResizeObserver } from '../use-cells-resize-observer';
 
 const observers: Array<{ callback: () => void; elements: Set<Element> }> = [];
 const OriginalResizeObserver = window.ResizeObserver;
+// A real observer reports a newly observed element before React runs passive effects.
+let notifyOnObserve = false;
 
 beforeEach(() => {
   observers.length = 0;
+  notifyOnObserve = false;
   window.ResizeObserver = class {
     private entry: { callback: () => void; elements: Set<Element> };
     constructor(callback: () => void) {
@@ -16,6 +19,9 @@ beforeEach(() => {
     }
     observe(element: Element) {
       this.entry.elements.add(element);
+      if (notifyOnObserve) {
+        this.entry.callback();
+      }
     }
     unobserve(element: Element) {
       this.entry.elements.delete(element);
@@ -79,6 +85,23 @@ test('calls the latest callback', () => {
   expect(latest).toHaveBeenCalledTimes(1);
 });
 
+test('reports newly observed cells to the callback from the same render', () => {
+  notifyOnObserve = true;
+  const cell = document.createElement('th');
+  const first = jest.fn();
+  const latest = jest.fn();
+  const { rerender } = renderHook(
+    ({ cells, onResize }: { cells: HTMLElement[]; onResize: () => void }) =>
+      useCellsResizeObserver(() => cells, onResize),
+    { initialProps: { cells: [] as HTMLElement[], onResize: first } }
+  );
+
+  rerender({ cells: [cell], onResize: latest });
+
+  expect(first).not.toHaveBeenCalled();
+  expect(latest).toHaveBeenCalledTimes(1);
+});
+
 test('stops reporting after unmount', () => {
   const cell = document.createElement('th');
   const { onResize, unmount } = renderCells([cell]);

src/internal/components/sticky-header/use-cells-resize-observer.ts

@@ -2,10 +2,13 @@
 // SPDX-License-Identifier: Apache-2.0
 import { useEffect, useLayoutEffect, useRef } from 'react';
 
-import { useStableCallback } from '@cloudscape-design/component-toolkit/internal';
-
 export function useCellsResizeObserver(getCells: () => ReadonlyArray<HTMLElement>, onResize: () => void) {
-  const stableOnResize = useStableCallback(onResize);
+  // Not useStableCallback: the observer can report new cells before passive effects update it.
+  const onResizeRef = useRef(onResize);
+  useLayoutEffect(() => {
+    onResizeRef.current = onResize;
+  });
+
   const observerRef = useRef<ResizeObserver | null>(null);
   const observedCellsRef = useRef<ReadonlyArray<HTMLElement>>([]);
 
@@ -20,7 +23,7 @@ export function useCellsResizeObserver(getCells: () => ReadonlyArray<HTMLElement
       return;
     }
     if (!observerRef.current) {
-      observerRef.current = new ResizeObserver(() => stableOnResize());
+      observerRef.current = new ResizeObserver(() => onResizeRef.current());
     }
     const observer = observerRef.current;
     observedCells.filter(cell => !cells.includes(cell)).forEach(cell => observer.unobserve(cell));

src/internal/components/sticky-header/use-untabbable-descendants.ts

@@ -0,0 +1,17 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { RefObject, useLayoutEffect } from 'react';
+
+import { getAllFocusables } from '../focus-lock/utils';
+
+// Takes a sticky header copy's controls out of the tab order but leaves them clickable.
+// `inert` would also stop clicks, letting them fall through to whatever is underneath.
+export function useUntabbableDescendants(containerRef: RefObject<HTMLElement>) {
+  useLayoutEffect(() => {
+    if (containerRef.current) {
+      for (const element of getAllFocusables(containerRef.current)) {
+        element.tabIndex = -1;
+      }
+    }
+  });
+}

src/table-root/__tests__/basic-table-roles.test.tsx

@@ -4,17 +4,15 @@ import React from 'react';
 
 import { findTable, makeItems, renderResourcesTable, ResourcesTable } from './table-fixtures';
 
-// Role semantics for the atomic table. In `auto` layout the parts are native
-// <table>/<thead>/<tr>/<th>/<tbody>/<td>, so the browser supplies the table semantics and no explicit
-// ARIA roles are emitted. In `grid` layout the parts are laid out with display:grid, which strips the
-// native table semantics, so the hook restores role=table -> rowgroup -> row -> columnheader/cell.
+// In `auto` layout only the table carries an explicit role; its parts keep their native roles. In `grid`
+// layout display:grid strips the native semantics, so every part gets an explicit role.
 
 describe('Table role semantics', () => {
-  describe('auto layout uses native table semantics (no explicit roles)', () => {
-    test('the table, rows, and cells carry no ARIA role attributes', () => {
+  describe('auto layout', () => {
+    test('sets role=table on the table and no roles on its parts', () => {
       const { wrapper } = renderResourcesTable({ items: makeItems(20) });
       const table = findTable(wrapper);
-      expect(table.hasAttribute('role')).toBe(false);
+      expect(table.getAttribute('role')).toBe('table');
       expect(table.querySelectorAll('[role]')).toHaveLength(0);
     });
   });