`, ``, and ` `. It
+handles the visual layer, e.g. column widths, spacing, dividers, row, and sort affordances, while leaving the data-source,
+sort, and selection states to the consumer.
+
+## Anatomy
+
+The component is fully composable and consumers only need to include what they need. For example, if column headers are not
+required, then `` can be omitted.
+
+{`
+| Component | Renders | Responsibility |
+| --- | --- | --- |
+| \`\` | \`\` | The full width table, and tabular figures styling |
+| \`\` | \`\` | The column definitions, as the first child of \`\` |
+| \`\` | \`\` | \`\` and its single \`\` | The header row |
+| \`\` | \`\` | The column label and its optional sort control |
+| \`\` | \`\` | The data rows |
+| \`\` | \`\` | Row selection through \`aria-selected\` |
+| \`\` | \`\` | The data cells |
+`}
+
+## Basic usage
+
+Render ``s and `` within `` and `` to render data. If consistent column sizing is needed,
+define the columns in ``.
+
+`, ``, and
+``/``, respectively. All components accept `exceptionallySetClassName` instead of `className`.
+
+The three components below also include additional props:
+
+### ``
+
+`
+
+`
+
+` would mark it as selected.
+
+` components do not dictate what external model layer they are used with. TanStack Table,
+for example, would be a good option for driving the data, including
+[sorting](https://tanstack.com/table/latest/docs/framework/react/guide/sorting) and
+[pagination](https://tanstack.com/table/latest/docs/framework/react/guide/pagination).
+
+
+
+export default meta
+
+type Story = StoryObj
+
+function PersonCell({ person }: { person: Person }) {
+ return (
+
+
+
+ {person.name}
+
+
+ {person.email}
+
+
+
+ )
+}
+
+function ActivityCell({ person }: { person: Person }) {
+ return (
+ ,
+ personId: string,
+ onActivate: (personId: string) => void,
+) {
+ if (event.key === 'Enter' || event.key === ' ') {
+ event.preventDefault()
+ onActivate(personId)
+ }
+}
+
+export const Default = {
+ render: () => (
+
+
+
+
+
+ Person
+
+
+ Role
+
+
+ Projects
+
+
+ Last active
+
+
+
+ {people.map((person) => (
+
+
+
+
+
+ {person.role}
+
+
+
+
+ {person.projects}
+
+
+
+
+
+ ))}
+
+
+ ),
+} satisfies Story
+
+export const SelectedAndClickableRows = {
+ name: 'Selected and clickable rows',
+ render: function SelectedAndClickableRows() {
+ const [selectedId, setSelectedId] = React.useState(people[1]!.id)
+
+ return (
+
+
+
+
+
+ Person
+
+
+ Role
+
+
+ Projects
+
+
+ Last active
+
+
+
+ {people.map((person) => (
+ setSelectedId(person.id)}
+ onKeyDown={(event) => handleRowKeyDown(event, person.id, setSelectedId)}
+ >
+
+
+
+
+ {person.role}
+
+
+
+
+ {person.projects}
+
+
+
+
+
+ ))}
+
+
+ )
+ },
+} satisfies Story
+
+export const NoHeaderRow = {
+ name: 'No header row',
+ render: () => (
+
+
+
+
+ {people.map((person) => (
+
+
+
+
+
+ {person.role}
+
+
+
+
+ {person.activity}
+
+
+
+ ))}
+
+
+ ),
+} satisfies Story
+
+export const MultiLineCells = {
+ name: 'Single and multi-line cells',
+ render: () => (
+
+
+
+
+
+ Single line
+
+
+ Two line
+
+
+
+
+
+
+ Cell content long enough that it has to truncate with an ellipsis
+
+
+
+ Cell content
+
+ Secondary line
+
+
+
+
+
+ ),
+} satisfies Story
+
+const features = tableFeatures({
+ columnVisibilityFeature,
+ rowPaginationFeature,
+ rowSortingFeature,
+ paginatedRowModel: createPaginatedRowModel(),
+ sortedRowModel: createSortedRowModel(),
+ sortFns: { text: sortFn_text },
+})
+
+const tanStackColumns: ColumnDef[] = [
+ { accessorKey: 'name', header: 'Person', sortFn: 'text' },
+ { accessorKey: 'role', header: 'Role', sortFn: 'text' },
+ { accessorKey: 'access', header: 'Access', enableSorting: false },
+]
+
+export const TanStackIntegration = {
+ name: 'TanStack Table integration',
+ render: function TanStackIntegration() {
+ const table = useTable({
+ features,
+ data: people,
+ columns: tanStackColumns,
+ getRowId: (person) => person.id,
+ initialState: { pagination: { pageIndex: 0, pageSize: 2 } },
+ })
+ const { pageIndex } = table.state.pagination ?? { pageIndex: 0 }
+
+ return (
+
+
+
+
+
+ {table.getHeaderGroups()[0]?.headers.map((header) => {
+ const direction = header.column.getIsSorted() || null
+ const label = String(header.column.columnDef.header)
+
+ return header.column.getCanSort() ? (
+ header.column.toggleSorting()}
+ sortAriaLabel={getSortAriaLabel(label, direction)}
+ >
+
+ {flexRender(
+ header.column.columnDef.header,
+ header.getContext(),
+ )}
+
+
+ ) : (
+
+
+ {flexRender(
+ header.column.columnDef.header,
+ header.getContext(),
+ )}
+
+
+ )
+ })}
+
+
+ {table.getRowModel().rows.map((row) => (
+
+ {row.getVisibleCells().map((cell) => (
+
+
+ {flexRender(
+ cell.column.columnDef.cell,
+ cell.getContext(),
+ )}
+
+
+ ))}
+
+ ))}
+
+
+
+ table.previousPage()}
+ >
+ Previous
+
+ table.nextPage()}
+ >
+ Next
+
+
+ Page {pageIndex + 1} of {table.getPageCount()}
+
+
+
+ )
+ },
+} satisfies Story
diff --git a/src/table/table.test.tsx b/src/table/table.test.tsx
new file mode 100644
index 000000000..4a4894d93
--- /dev/null
+++ b/src/table/table.test.tsx
@@ -0,0 +1,200 @@
+import * as React from 'react'
+
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { axe } from 'jest-axe'
+
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableColumn,
+ TableColumnGroup,
+ TableColumnHeader,
+ TableHeader,
+ TableRow,
+} from './index'
+
+function BasicTable({ withHeader = true }: { withHeader?: boolean }) {
+ return (
+
+ {withHeader ? (
+
+ Person
+ Role
+
+ ) : null}
+
+
+ Avery Morgan
+ Product designer
+
+
+
+ )
+}
+
+describe('Table primitives', () => {
+ it('renders native table semantics from composed children', () => {
+ render((),
+ body: React.createRef(),
+ row: React.createRef(),
+ cell: React.createRef(),
+ }
+ render(
+ ,
+ )
+ expect(refs.table.current?.tagName).toBe('TABLE')
+ expect(refs.body.current?.tagName).toBe('TBODY')
+ expect(refs.row.current?.tagName).toBe('TR')
+ expect(refs.cell.current?.tagName).toBe('TD')
+ })
+
+ it('marks only rows with aria-selected as selectable', () => {
+ render(
+
+
+
+ Selectable
+
+
+ Selected
+
+
+ Plain
+
+
+
,
+ )
+ const rows = screen.getAllByRole('row')
+ expect(rows[0]).toHaveAttribute('aria-selected', 'false')
+ expect(rows[1]).toHaveAttribute('aria-selected', 'true')
+ expect(rows[2]).not.toHaveAttribute('aria-selected')
+ })
+
+ it('maps the column width prop onto the column definition', () => {
+ const { container } = render(
+
+
+
+
+
+ Avery Morgan
+ Product designer
+
+
+
,
+ )
+ const [sized, defaulted] = Array.from(container.querySelectorAll('col'))
+ expect(sized?.className).toContain('columnWidth-2-5')
+ expect(defaulted?.className).toContain('columnWidth-auto')
+ })
+
+ it('has no automated accessibility violations', async () => {
+ const { container } = render(, 'className' | 'border'> &
+ ObfuscatedClassName
+
+type TableHeaderProps = Omit, 'className'> &
+ ObfuscatedClassName
+
+type TableBodyProps = Omit, 'className'> &
+ ObfuscatedClassName
+
+type TableRowProps = Omit, 'className'> &
+ ObfuscatedClassName
+
+type TableCellProps = Omit, 'align' | 'className'> &
+ ObfuscatedClassName & {
+ /** Horizontal alignment of the cell content. */
+ align?: 'start' | 'end'
+ }
+
+type TableColumnWidth =
+ | 'auto'
+ | 'content'
+ | '1/2'
+ | '1/3'
+ | '2/3'
+ | '1/4'
+ | '3/4'
+ | '1/5'
+ | '2/5'
+ | '3/5'
+ | '4/5'
+
+type TableColumnGroupProps = Omit, 'className'> &
+ ObfuscatedClassName
+
+type TableColumnProps = Omit, 'className' | 'width'> &
+ ObfuscatedClassName & {
+ /** Width of this column, as a fraction of the table. */
+ width?: TableColumnWidth
+ }
+
+type SortableProps =
+ | {
+ /** Renders the sort control and makes the header activatable. */
+ sortable: true
+
+ /** Direction for this column, or null when it is sortable but not sorted. */
+ sortDirection: 'asc' | 'desc' | null
+
+ /** Called when the sort control is activated. */
+ onSort: () => void
+
+ /** Complete localized label for the sort button. */
+ sortAriaLabel: string
+ }
+ | {
+ sortable?: false
+ sortDirection?: never
+ onSort?: never
+ sortAriaLabel?: never
+ }
+
+type TableColumnHeaderProps = Omit<
+ React.ThHTMLAttributes,
+ 'align' | 'className' | 'onSort'
+> &
+ ObfuscatedClassName &
+ SortableProps & {
+ /** Horizontal alignment of the header content. */
+ align?: 'start' | 'end'
+ }
+
+function ariaSortFor(sortDirection: 'asc' | 'desc') {
+ return sortDirection === 'asc' ? 'ascending' : 'descending'
+}
+
+/**
+ * Tabular data in native table markup, composed from:
+ * * {@link TableColumnGroup}
+ * * {@link TableColumn}
+ * * {@link TableHeader}
+ * * {@link TableColumnHeader}
+ * * {@link TableBody}
+ * * {@link TableRow}
+ * * {@link TableCell}
+ */
+const Table = React.forwardRef(function Table(
+ { exceptionallySetClassName, ...tableProps },
+ ref,
+) {
+ return (
+ (
+ function TableColumnGroup({ exceptionallySetClassName, ...groupProps }, ref) {
+ return (
+ (function TableColumn(
+ { width = 'auto', exceptionallySetClassName, ...columnProps },
+ ref,
+) {
+ return (
+ (
+ function TableHeader({ children, exceptionallySetClassName, ...headerProps }, ref) {
+ return (
+
+ {children}
+
+ )
+ },
+)
+
+/** A table body that wraps its rows. */
+const TableBody = React.forwardRef(function TableBody(
+ { exceptionallySetClassName, ...bodyProps },
+ ref,
+) {
+ return (function TableRow(
+ { exceptionallySetClassName, ...rowProps },
+ ref,
+) {
+ return (
+ (function TableCell(
+ { align = 'start', children, exceptionallySetClassName, ...cellProps },
+ ref,
+) {
+ return (
+
+ {children}
+
+ )
+})
+
+/** A table column header, optionally sortable. */
+const TableColumnHeader = React.forwardRef(
+ function TableColumnHeader(
+ {
+ sortable,
+ sortDirection = null,
+ onSort,
+ sortAriaLabel,
+ align = 'start',
+ children,
+ exceptionallySetClassName,
+ ...headerProps
+ },
+ ref,
+ ) {
+ const label = {children}
+ const indicatorDirection = sortDirection ?? 'desc'
+ const descendingClass = styles.sortIndicatorDescending ?? ''
+ const unsortedClass = styles.sortIndicatorUnsorted ?? ''
+
+ return (
+
+ {sortable ? (
+
+ {label}
+
+
+
+ ) : (
+ label
+ )}
+
+ )
+ },
+)
+
+export {
+ Table,
+ TableBody,
+ TableCell,
+ TableColumn,
+ TableColumnGroup,
+ TableColumnHeader,
+ TableHeader,
+ TableRow,
+}
+export type {
+ TableBodyProps,
+ TableCellProps,
+ TableColumnGroupProps,
+ TableColumnHeaderProps,
+ TableColumnProps,
+ TableColumnWidth,
+ TableHeaderProps,
+ TableProps,
+ TableRowProps,
+}
diff --git a/stories/components/styles/story.css b/stories/components/styles/story.css
index 6e08f70a8..fdfef8779 100644
--- a/stories/components/styles/story.css
+++ b/stories/components/styles/story.css
@@ -1,4 +1,5 @@
body {
+ color: var(--product-library-display-primary-idle-tint);
font-family: var(--reactist-font-family);
}