DataTable: Add config-driven row groups

[rickyzhangca]

Refs github/primer#6720

Follows #8372, which introduced the presentational Table.Group API, and includes the sortable-header accessibility behavior from #8371.

	Before	After
Data shape	Flat rows only: Array<Data>	Flat rows or groups: Array<Data> | Array<DataTableRowGroup<Data>>
Config API	<DataTable data={rows} columns={columns} />	<DataTable data={groups} columns={columns} />
Group definition	Not available in the config API	{type: 'row-group', groupId, label, rows, 'aria-label'?}
Lower-level composition	Consumers manually compose rows	Table.Group remains available as the presentational escape hatch
Sorting	Sorts the flat row collection	Preserves group order and sorts rows within each group
Accessibility	Native column and row header associations	Grouped cells are automatically associated with group, row, and column headers; flat table markup is unchanged
Existing consumers	Flat data	No migration required; flat data continues to work

Grouped data example

const data: DataTableData<Repository> = [
  {
    type: 'row-group',
    groupId: 'internal',
    label: 'Internal',
    rows: [{id: 1, name: 'github/github'}],
  },
  {
    type: 'row-group',
    groupId: 'public',
    label: 'Public',
    rows: [{id: 2, name: 'primer/react'}],
  },
]

<DataTable data={data} columns={columns} />

Changelog

New

• Add config-driven row groups to DataTable through grouped data entries.
• Export DataTableRowGroup and DataTableData types from the experimental entrypoint.

Changed

• Keep client-side sorting within each group while preserving group order.
• Automatically associate grouped cells with their group, row, and column headers.

Removed

• None.

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

• npm run build
• npm test (157 files, 2,666 passed, 2 skipped, 10 todo)
• npm run type-check
• npm run lint
• npm run lint:css
• npm run lint:react-compiler --workspace=@primer/react -- --no-cache
• npm run build:components.json --workspace=@primer/react
• npm run test:classname-coverage
• npm run format:diff
• Grouped and sortable-grouped DataTable axe AAT passed across all 9 themes (18 tests).
• Verified in a real browser that sortable header names/descriptions and all group/row/column headers references remain valid after sorting.

Review the With Groups DataTable feature story for the config-driven API and With Sortable Groups for the sortable accessibility contract. With Composed Groups remains available as the lower-level Table.Group example introduced in #8372.

[changeset-bot]

🦋 Changeset detected

Latest commit: 8f84e39

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

[Copilot]

Copilot review overview

🟡 Changes recommended

There’s a correctness issue in the row-group runtime type guard (groups can be misclassified if they include an id field), plus a small e2e gate that should check aat truthiness rather than key presence.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review tier: Lite
Findings: 1 · 1

New issues introduced by this change (2)

Severity	Finding
	packages/​react/​src/​DataTable/​useTable.ts — isDataTableRowGroup requires the group object to not have an id property (`!Reflect.has(item,…
	e2e/​components/​DataTable.test.ts — The AAT gate currently uses if ('aat' in story), which will run the axe test for any story object…

What changed in this PR

Adds a config-driven row-grouping model to the experimental DataTable API by allowing data to be either a flat row array or a grouped row-array shape, rendering groups via the presentational Table.Group primitive and improving header associations for accessibility.

Changes:

• Introduces DataTableRowGroup / DataTableData types and exports them from the experimental entrypoint.
• Updates useTable + DataTable rendering to support grouped data while sorting within each group and preserving group order.
• Adds unit, type-level, and e2e coverage for grouped tables and header associations (including AAT for the grouped story).

File	Description
packages/​react/​src/​experimental/​index.ts	Exports new DataTableData and DataTableRowGroup types from the experimental entrypoint.
packages/​react/​src/​DataTable/​useTable.ts	Accepts grouped data, validates shape, and applies per-group sorting while preserving group order.
packages/​react/​src/​DataTable/​row.ts	Defines DataTableRowGroup and DataTableData types.
packages/​react/​src/​DataTable/​index.ts	Re-exports new grouping-related types.
packages/​react/​src/​DataTable/​DataTable.types.test.tsx	Adds type-level tests to ensure grouped props and inference work.
packages/​react/​src/​DataTable/​DataTable.tsx	Renders TableGroup when grouped; adds deterministic header IDs and headers associations.
packages/​react/​src/​DataTable/​DataTable.stories.tsx	Wraps DataTable for Storybook component typing.
packages/​react/​src/​DataTable/​DataTable.features.stories.tsx	Updates With Groups to use config-driven groups; keeps composed example as WithComposedGroups.
packages/​react/​src/​DataTable/​DataTable.docs.json	Documents the new data union shape and adds the composed-groups story to docs.
packages/​react/​src/​DataTable/​__tests__/​DataTableGrouping.test.tsx	Adds focused grouping behavior and accessibility association tests (incl. SSR ID uniqueness).
packages/​react/​src/​DataTable/​__tests__/​DataTable.test.tsx	Adds regression coverage for headers associations in ungrouped tables.
packages/​react/​src/​__tests__/​__snapshots__/​exports.test.ts.snap	Updates snapshot for new experimental type exports.
e2e/​components/​DataTable.test.ts	Enables axe AAT for the grouped DataTable story across themes.
.changeset/​grouped-data-table.md	Minor changeset for the new config-driven grouping capability + new exports.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[primer]

🤖 Lint issues have been automatically fixed and committed to this PR.