@tristan2828/ui-foundation 4.44.0 → 4.46.0

package/conventions/AGENTS.md

@@ -87,7 +87,8 @@ Every data view handles: loading, empty, error, and success. Use
 `<Skeleton>`, `<Empty>`, and the error boundary — `DataTable` already does,
 and `EntityView` (one record) adds not found: a plain 404, never a retry.
 A small widget on a hub page is a `WidgetCard`, which holds all four for
-its own data, its error inside the card; a hub's place (a module, with
+its own data, its error inside the card (folded, its `summary` follows
+the same states); a hub's place (a module, with
 one live number) is a `ModuleCard` in a `ModuleStrip`, the same way.
 Every screen has one Playwright test per state, forced via MSW overrides
 (`@tristan2828/ui-foundation/testing`).

package/conventions/docs/add-an-entity.md

@@ -4,21 +4,21 @@
 ## Index
 
 - [The reference files](#the-reference-files) · lines 37–59
-- [Before anything: the entity plan](#before-anything-the-entity-plan) · lines 61–706
+- [Before anything: the entity plan](#before-anything-the-entity-plan) · lines 61–715
   - Step 1: Add `<Entity>` to `openapi.yaml` · lines 99–106
   - Step 2: `npm run gen:api` · lines 107–108
   - Step 3: Add gateway tests in `tests/gateway/<entity>.test.ts`, derived from the spec · lines 109–120
   - Step 4: Add MSW handlers in `src/mocks/<entity>.ts` · lines 121–130
   - Step 5: Add a gateway module in `src/api/gateway/<entity>.ts` · lines 131–135
-  - Step 6: Copy the reference files, one for one, not just the two screens · lines 136–598
-  - Step 7: Register routes · lines 599–609
-  - Step 8: Add Playwright specs for all three screens · lines 610–688
-  - Step 9: Register the nav entry and route names · lines 689–703
-  - Step 10: `npm run verify`. · lines 704–706
-- [What not to copy](#what-not-to-copy) · lines 708–734
-- [After a commit, in the backend](#after-a-commit-in-the-backend) · lines 736–753
-- [Deleting](#deleting) · lines 755–784
-- [Fields only a script writes](#fields-only-a-script-writes) · lines 786–807
+  - Step 6: Copy the reference files, one for one, not just the two screens · lines 136–607
+  - Step 7: Register routes · lines 608–618
+  - Step 8: Add Playwright specs for all three screens · lines 619–697
+  - Step 9: Register the nav entry and route names · lines 698–712
+  - Step 10: `npm run verify`. · lines 713–715
+- [What not to copy](#what-not-to-copy) · lines 717–743
+- [After a commit, in the backend](#after-a-commit-in-the-backend) · lines 745–762
+- [Deleting](#deleting) · lines 764–793
+- [Fields only a script writes](#fields-only-a-script-writes) · lines 795–816
 
 <!-- /index -->
 
@@ -410,6 +410,15 @@ is a filled-in example while the Widgets demo is still here).
      view is `rail`, with Details in the rail. The rail's sections come
      first in the page (header, rail, main) at every width, so the
      view's specs find them first too.
+   - **A subtitle** (`subtitle`), only when the plan names a line that
+     says what the record is for (a goal, a one-line summary): under the
+     title in muted body type. When the plan marks it editable, wrap it
+     in `<EditableValue label=… edit={editInPlace(…)} layout="inline">`.
+   - **Key numbers** (`strip`), only when the plan names a few figures
+     read before anything else (done of total, time left, the next
+     date): `<KeyStats stats={[{ label, value, hint? }]} />`, under the
+     header across the page, so on a phone it comes before the rail and
+     the main column. Three to five; more belong in a section.
    - **A notice** (`notice`), only when the plan names a state that
      decides what you do with the record (held, overdue, archived and
      read-only): a `<Notice tone=…>` saying what it means and what to do,

package/conventions/docs/cell-patterns.md

@@ -3,37 +3,38 @@
 <!-- index: written by `npm run docs:index` in the package from the headings below; never edit it by hand -->
 ## Index
 
-- [The rules that apply to every cell](#the-rules-that-apply-to-every-cell) · lines 65–84
-- [1. Plain text](#1-plain-text) · lines 86–93
-- [2. Icon + label](#2-icon--label) · lines 95–118
-- [3. Icon in a badge](#3-icon-in-a-badge) · lines 120–133
-- [4. Icon only, label in a tooltip](#4-icon-only-label-in-a-tooltip) · lines 135–212
-  - [Several values: the icons side by side, every name in one tooltip](#several-values-the-icons-side-by-side-every-name-in-one-tooltip) · lines 160–212
-- [5. Enum → tone-mapped badge](#5-enum--tone-mapped-badge) · lines 214–227
-- [6. Multi-value enum, clustered](#6-multi-value-enum-clustered) · lines 229–241
-- [7. Link as an outline button](#7-link-as-an-outline-button) · lines 243–264
-- [8. Date, relative](#8-date-relative) · lines 266–303
-- [9. Ordinal scale (bounded integer)](#9-ordinal-scale-bounded-integer) · lines 305–353
-  - [Two variants the package draws: a step bar and a star](#two-variants-the-package-draws-a-step-bar-and-a-star) · lines 323–353
-- [10. Summary in the cell, detail in a popover](#10-summary-in-the-cell-detail-in-a-popover) · lines 355–405
-  - [A second example: what a row depends on](#a-second-example-what-a-row-depends-on) · lines 373–405
-- [11. Number or currency — Unproven](#11-number-or-currency--unproven) · lines 407–447
-- [12. Boolean](#12-boolean) · lines 449–479
-- [13. Progress bar — Unproven](#13-progress-bar--unproven) · lines 481–517
-  - [The compact form: `ProgressRing`](#the-compact-form-progressring) · lines 501–517
-- [14. Avatar and name — Unproven](#14-avatar-and-name--unproven) · lines 519–536
-- [15. Yes/no you flip in the row](#15-yesno-you-flip-in-the-row) · lines 538–647
-  - [A variant: a pressed icon inside another value's cell](#a-variant-a-pressed-icon-inside-another-values-cell) · lines 564–647
-- [16. Title linking to the record's view](#16-title-linking-to-the-records-view) · lines 649–684
-- [17. Quick action on the view](#17-quick-action-on-the-view) · lines 686–759
-- [18. Editable value](#18-editable-value) · lines 761–1207
-  - [A list of sub-items](#a-list-of-sub-items) · lines 1023–1108
-  - [In a table's rows](#in-a-tables-rows) · lines 1110–1195
-  - [A table of a few short columns: `width="content"`](#a-table-of-a-few-short-columns-widthcontent) · lines 1197–1207
-- [19. Stage circle for an ordered status](#19-stage-circle-for-an-ordered-status) · lines 1209–1275
-- [20. Count linking to the related records](#20-count-linking-to-the-related-records) · lines 1277–1341
-- [21. Rows grouped under headings, and a pill filter](#21-rows-grouped-under-headings-and-a-pill-filter) · lines 1343–1408
-- [22. A highlighted row, and rows that are done](#22-a-highlighted-row-and-rows-that-are-done) · lines 1410–1438
+- [The rules that apply to every cell](#the-rules-that-apply-to-every-cell) · lines 66–85
+- [1. Plain text](#1-plain-text) · lines 87–94
+- [2. Icon + label](#2-icon--label) · lines 96–119
+- [3. Icon in a badge](#3-icon-in-a-badge) · lines 121–134
+- [4. Icon only, label in a tooltip](#4-icon-only-label-in-a-tooltip) · lines 136–213
+  - [Several values: the icons side by side, every name in one tooltip](#several-values-the-icons-side-by-side-every-name-in-one-tooltip) · lines 161–213
+- [5. Enum → tone-mapped badge](#5-enum--tone-mapped-badge) · lines 215–228
+- [6. Multi-value enum, clustered](#6-multi-value-enum-clustered) · lines 230–242
+- [7. Link as an outline button](#7-link-as-an-outline-button) · lines 244–265
+- [8. Date, relative](#8-date-relative) · lines 267–304
+- [9. Ordinal scale (bounded integer)](#9-ordinal-scale-bounded-integer) · lines 306–354
+  - [Two variants the package draws: a step bar and a star](#two-variants-the-package-draws-a-step-bar-and-a-star) · lines 324–354
+- [10. Summary in the cell, detail in a popover](#10-summary-in-the-cell-detail-in-a-popover) · lines 356–406
+  - [A second example: what a row depends on](#a-second-example-what-a-row-depends-on) · lines 374–406
+- [11. Number or currency — Unproven](#11-number-or-currency--unproven) · lines 408–448
+- [12. Boolean](#12-boolean) · lines 450–480
+- [13. Progress bar — Unproven](#13-progress-bar--unproven) · lines 482–518
+  - [The compact form: `ProgressRing`](#the-compact-form-progressring) · lines 502–518
+- [14. Avatar and name — Unproven](#14-avatar-and-name--unproven) · lines 520–537
+- [15. Yes/no you flip in the row](#15-yesno-you-flip-in-the-row) · lines 539–648
+  - [A variant: a pressed icon inside another value's cell](#a-variant-a-pressed-icon-inside-another-values-cell) · lines 565–648
+- [16. Title linking to the record's view](#16-title-linking-to-the-records-view) · lines 650–685
+- [17. Quick action on the view](#17-quick-action-on-the-view) · lines 687–760
+- [18. Editable value](#18-editable-value) · lines 762–1208
+  - [A list of sub-items](#a-list-of-sub-items) · lines 1024–1109
+  - [In a table's rows](#in-a-tables-rows) · lines 1111–1196
+  - [A table of a few short columns: `width="content"`](#a-table-of-a-few-short-columns-widthcontent) · lines 1198–1208
+- [19. Stage circle for an ordered status](#19-stage-circle-for-an-ordered-status) · lines 1210–1276
+- [20. Count linking to the related records](#20-count-linking-to-the-related-records) · lines 1278–1342
+- [21. Rows grouped under headings, and a pill filter](#21-rows-grouped-under-headings-and-a-pill-filter) · lines 1344–1412
+- [22. A highlighted row, and rows that are done](#22-a-highlighted-row-and-rows-that-are-done) · lines 1414–1442
+- [23. A Group menu, and a record read beside the list](#23-a-group-menu-and-a-record-read-beside-the-list) · lines 1444–1518
 
 <!-- /index -->
 
@@ -1405,7 +1406,10 @@ const { page, filters, setFilter, setPage } = useTableUrlState(['kind'])
 - **No rows for a filter** is the table's own empty state, saying which
   filter, with a button to take it off. An empty group never renders:
   groups come from the rows.
-- **Not built:** collapsing groups, grouping by more than one key.
+- **Headings that fold, picked by the reader** are pattern 23's
+  `groupings`: a Group menu over choice fields. `groupBy` stays the
+  app's one fixed grouping (a feed's days). **Not built:** grouping by
+  more than one key.
 
 ## 22. A highlighted row, and rows that are done
 
@@ -1437,3 +1441,78 @@ current one. `DataTable`'s `highlightRow` returns true for it.
   the token check in both themes; `e2e/data-table.spec.ts` checks every
   cell wears the wash.
 
+## 23. A Group menu, and a record read beside the list
+
+A working list (tasks, chores, a backlog) is read two ways besides its
+columns: **grouped by one of its choice fields**, picked by the reader
+(by status to see what's moving, by area to plan a trip round the
+house), and **one record at a time without leaving the list**, its notes
+and key facts in a panel beside the rows. `DataTable`'s `groupings` and
+`detailPanel` (4.46) do both. Raised for an app's task list; the
+package's Storybook renders it (`app/DataTable grouping`), with axe in
+both themes and its specs in a real browser.
+
+```tsx
+const GROUPINGS: DataTableGrouping<Task>[] = [   // module level
+  { id: 'status', label: 'Status', options: STATUS_OPTIONS, value: (task) => task.status },
+  { id: 'categories', label: 'Category', options: CATEGORY_OPTIONS, value: (task) => task.categories, emptyLabel: 'No category' },
+  { id: 'canDoNow', label: 'Can do now', options: [{ value: 'yes', label: 'Can do now' }, { value: 'no', label: 'Not yet' }],
+    value: (task) => (task.canDoNow ? 'yes' : 'no') },
+]
+
+const { grouping, setGrouping, ...table } = useTableUrlState(FILTERS, MULTI, VIEWS, { groupStorageKey: 'my-app:tasks:group' })
+
+<DataTable
+  groupings={GROUPINGS}
+  grouping={grouping}
+  onGroupingChange={setGrouping}
+  groupSummary={(tasks) => `${tasks.filter(isReady).length} ready · top ${Math.max(...tasks.map((task) => task.score))}`}
+  detailLabel="Task"
+  detailPanel={(task) => <TaskPreview task={task} />}   // its own "Open page" link
+  … />
+```
+
+- **None is the default**, and the table is exactly as it was until a
+  grouping is picked. The Group menu sits at the end of the toolbar
+  (before a layout switch): None, then each grouping. While grouped a
+  Fold all button joins it, and the menu says which ("Group: Status").
+- **Only choice fields**: each group is one of the field's options, in
+  the options' order (the order the form lists them), so give the same
+  options list the column and the form use. A multi-value field (an
+  array) shows the row under each of its values; a row with none goes
+  last, under `emptyLabel` ("Not set" unless set). A yes/no field is two
+  options, worded as headings ("Can do now", "Not yet").
+- **The grouped column is hidden** while grouped (its value is the
+  heading), so a grouping's `id` is its column's id.
+- **A heading is a button** (`aria-expanded`) that folds its rows away:
+  a chevron, the label, the count, then `groupSummary`'s line, given the
+  group's rows *on this page* and the group itself. Folds reset when the
+  grouping changes.
+- **Remembered like the layout**: `useTableUrlState`'s `grouping` is
+  `?group=` in the URL, then the one remembered under `groupStorageKey`
+  on this device, then None. A saved view can name a `group` (''
+  for None) to turn one on when pressed; a view that names none keeps
+  the grouping that's on. Grouping doesn't change which rows are shown,
+  so it keeps the page and doesn't count toward the active view.
+- **It groups the page's rows**: paging pages rows, not groups, so a
+  list that groups wants a page size that holds it (a working list of a
+  few dozen), and a summary that must count a whole group across pages
+  comes from the API. A grouping, while on, takes the place of
+  `groupBy`'s headings.
+- **The detail panel** opens on a click on a row, or Enter on it (its
+  title link included: a plain click picks the row, a modified one still
+  opens the link in a new tab, and the panel's own "Open page" link
+  leaves). A control in a cell (a button, a switch, an editable value)
+  stays the control's. The picked row is marked (`aria-selected`, the
+  muted fill and a bar in `--primary` at its start); ↑ and ↓ move the pick
+  while the list has focus, and Escape or Close closes it, focus back on
+  the row. On a wide screen (64rem and up) the panel sits beside the
+  table and stays in view as the page scrolls; below that it is a
+  bottom sheet.
+- **The panel is the app's**: a heading-sized title, a few badges, a
+  short notes preview (a few lines of the record's notes, not the whole
+  editor), and an "Open page" link (a `<Link>` in `text-link`, so it's
+  announced as the link it is). Without `detailPanel` rows behave as they
+  always have: the title link opens the record's page.
+- **The table layout's alone:** a card layout's cards don't open the
+  panel.

package/conventions/docs/design-language.md

@@ -3,23 +3,24 @@
 <!-- index: written by `npm run docs:index` in the package from the headings below; never edit it by hand -->
 ## Index
 
-- [Semantic tones](#semantic-tones) · lines 32–60
-- [The three badge styles](#the-three-badge-styles) · lines 62–79
-- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 81–110
-- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 112–125
-- [Logos and brand marks](#logos-and-brand-marks) · lines 127–171
-- [Categorical colour](#categorical-colour) · lines 173–243
-- [Typography](#typography) · lines 245–327
-  - [Written text (notes)](#written-text-notes) · lines 276–327
-- [Density](#density) · lines 329–386
-- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 388–466
-- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 468–526
-- [Notices](#notices) · lines 528–556
-- [A value over time](#a-value-over-time) · lines 558–591
-- [A list as a board](#a-list-as-a-board) · lines 593–644
-- [A list as cards](#a-list-as-cards) · lines 646–692
-- [Picking at random](#picking-at-random) · lines 694–725
-- [Filling in what's missing](#filling-in-whats-missing) · lines 727–777
+- [Semantic tones](#semantic-tones) · lines 33–61
+- [The three badge styles](#the-three-badge-styles) · lines 63–80
+- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 82–111
+- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 113–126
+- [Logos and brand marks](#logos-and-brand-marks) · lines 128–172
+- [Categorical colour](#categorical-colour) · lines 174–244
+- [Typography](#typography) · lines 246–328
+  - [Written text (notes)](#written-text-notes) · lines 277–328
+- [Density](#density) · lines 330–387
+- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 389–503
+- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 505–563
+- [Notices](#notices) · lines 565–593
+- [A value over time](#a-value-over-time) · lines 595–628
+- [A list as a board](#a-list-as-a-board) · lines 630–681
+- [A list as cards](#a-list-as-cards) · lines 683–729
+- [Key numbers on a record](#key-numbers-on-a-record) · lines 731–753
+- [Picking at random](#picking-at-random) · lines 755–786
+- [Filling in what's missing](#filling-in-whats-missing) · lines 788–838
 
 <!-- /index -->
 
@@ -446,7 +447,42 @@ const { data, isLoading, error, refetch } = useReadyTasksQuery() // one page of
   (`"<app>:hub.<widget>"`) so a card folded stays folded on that device,
   and `defaultCollapsed` for one that should start folded. The chevron
   at the header's end is named by the title; the header's link stays
-  while folded.
+  while folded. Give a card that folds a `summary`: one short value its
+  header shows while folded (`summary={data?.total}`, `"Due today"`),
+  so a hub of folded cards still reads at a glance. It follows the
+  card's state: a small skeleton while loading, a muted dash on an error
+  (the error itself is in the body, opened), and `emptySummary`
+  (`"None"`) or nothing when empty.
+- **One open at a time on a phone:** put the cards in a
+  `WidgetCardGroup accordion="mobile"` (its `className` is the grid),
+  give each an `id`, and name the one to start open in `defaultOpen`.
+  Below the sidebar's breakpoint every card folds, opening one folds the
+  others, and a tap anywhere on a header (not its link) toggles it; on a
+  desktop the cards keep their own `collapsible`. `accordion` alone does
+  it at every width.
+- **Letting someone order the cards:** keep the order in
+  `useWidgetLayout('<app>:hub', ids)` (every card's id, in the default
+  order), render `layout.visible`, and put a `WidgetLayoutSheet` (its
+  Customize button) beside the page's title, with each card's title by id.
+  Its rows have Up, Down and a Show switch, with Reset: the same on a
+  phone, a desktop and a keyboard (the focus stays on the button
+  pressed). The order is kept on the device; a removed id drops out and
+  a new one falls in at its default place. To follow the person between
+  devices, pass `{ store }`, a `WidgetLayoutStore` over the app's
+  backend.
+
+```tsx
+const HUB_CARDS = { ready: 'Ready to start', waiting: 'Waiting on', links: 'Saved links' }
+const layout = useWidgetLayout('my-app:hub', Object.keys(HUB_CARDS))
+
+<div className="flex items-center justify-between gap-3">
+  <h1 className="type-page-title text-foreground">Home</h1>
+  <WidgetLayoutSheet layout={layout} titles={HUB_CARDS} />
+</div>
+<WidgetCardGroup accordion="mobile" defaultOpen="ready" className="grid … gap-4">
+  {layout.visible.map((id) => <HubCard key={id} id={id} />)}
+</WidgetCardGroup>
+```
 - **A row is one line:** its text is a link (`to` for a route in the
   app, `href` for an external address, which opens in a new tab with the
   external-link mark) or plain text, cut with an ellipsis, the whole of
@@ -462,7 +498,8 @@ const { data, isLoading, error, refetch } = useReadyTasksQuery() // one page of
   many 288px-or-wider columns as fit). Each card is as tall as its rows;
   it doesn't stretch to its tallest neighbour.
 - Storybook's `app/WidgetCard` shows three widgets on a page and every
-  one in each state; its checks run axe and the token and glyph checks in
+  one in each state, a folded summary in each state and an accordion,
+  and `app/WidgetLayoutSheet` a hub with its Customize sheet; its checks run axe and the token and glyph checks in
   both themes and at `large`.
 
 ## Module cards (a hub's places)
@@ -648,8 +685,8 @@ the table's.
 `DataTable`'s `layouts` (4.39) draw the same rows as cards beside the
 table: a thumbnail grid for a feed, covers for a collection, a dense line
 each for clearing a backlog. They are layouts of one list, not other
-pages: the toolbar, filters, saved views, paging and `groupBy` headings
-are the table's in every one, and so are its loading, empty and error
+pages: the toolbar, filters, saved views, paging, `groupBy` headings
+and a picked grouping's folding ones (cell pattern 23) are the table's in every one, and so are its loading, empty and error
 states.
 
 ```tsx
@@ -691,6 +728,30 @@ const { layout, setLayout } = useTableLayout({
 - `totals` and `highlightRow` are the table's alone. Sorting is the
   toolbar's in a card layout (there is no header to click).
 
+## Key numbers on a record
+
+`KeyStats` (4.46), in `EntityView`'s `strip`: the few figures a record's
+page is read for first (done of total, time left, the next date), in a
+row under the header, across the page at every width.
+
+```tsx
+<EntityView
+  subtitle={<EditableValue label="Goal" edit={goals} layout="inline">{goal}</EditableValue>}
+  strip={<KeyStats stats={[{ label: 'Done', value: '7', hint: 'of 12' }, { label: 'Next step', value: formatPlainDate(next) }]} />}
+  … />
+```
+
+- **A label over its value**: the label in caption type and muted, the
+  value in the section title's size and tabular figures, a `hint`
+  under it in caption type. One bordered card, the figures side by side,
+  wrapping on a phone. A `<dl>`, so each label is read with its value.
+- **An empty value reads as `emptyLabel`** ("Not set"), in body type and
+  muted, never a blank or a dash.
+- **Three to five.** It's what the page is for at a glance; anything
+  more is a section's label/value rows.
+- **`subtitle`** is the line under the title: what the record is for,
+  in muted body type, editable in place like any value.
+
 ## Picking at random
 
 `SpinWheel` (4.42) picks one of a few candidates by chance, for "what do

package/dist/components/app/data-table.d.ts

@@ -82,10 +82,43 @@ export type DataTableProps<TData extends Record<string, unknown>> = {
      */
     groupBy?: (row: TData) => RowGroup;
     /**
-     * What a heading says after its label ("4 · 1 h 12 m"), from the group's
-     * rows on this page.
+     * What a heading says after its label ("4 · 1 h 12 m", "3 ready · top
+     * 42"), from the group's rows on this page, for `groupBy`'s headings and
+     * a grouping's alike. `group` says which group it is.
      */
-    groupSummary?: (rows: TData[]) => ReactNode;
+    groupSummary?: (rows: TData[], group: RowGroup) => ReactNode;
+    /**
+     * The fields the rows can be grouped by, picked in a Group menu at the
+     * end of the toolbar: None (the default, the table as it is without
+     * this), then each of these. Choice fields: each group is one of the
+     * field's options, in the options' order. While grouped, the field's
+     * column is hidden (its value is the heading), each heading folds its
+     * rows away and says how many there are, with `groupSummary` after it,
+     * and a Fold all button joins the menu. A grouping, while on, takes the
+     * place of `groupBy`. It groups this page's rows: paging still pages
+     * rows.
+     */
+    groupings?: readonly DataTableGrouping<TData>[];
+    /**
+     * The grouping on: a grouping's id, or '' for None, from
+     * useTableUrlState's `grouping` (the URL's `?group=`, then the one
+     * remembered for this table). An id the table doesn't have is None.
+     * Left out, the menu keeps its own state, starting on None.
+     */
+    grouping?: string;
+    onGroupingChange?: (grouping: string) => void;
+    /**
+     * A record read beside the list without leaving it. Clicking a row (its
+     * title link too; a modified click still opens the link) or Enter on it
+     * selects it and opens this panel: beside the table on a wide screen
+     * (64rem and up), a bottom sheet below that. ↑ and ↓ move the selection
+     * while the list has focus; Escape or Close closes it. Everything in
+     * the panel is the app's, an "Open page" link included. The table
+     * layout's alone: a card layout's cards are as they are.
+     */
+    detailPanel?: (row: TData) => ReactNode;
+    /** The panel's heading and landmark name: "Details" unless set. */
+    detailLabel?: string;
     /**
      * False hides the column header row, for a list-like table whose columns
      * explain themselves (a thumbnail, a title block, actions). Screen readers
@@ -132,6 +165,30 @@ export type DataTableProps<TData extends Record<string, unknown>> = {
         icon?: IconComponent;
     };
 };
+/** A field DataTable's rows can be grouped by (`groupings`). */
+export type DataTableGrouping<TData> = {
+    /**
+     * The field's column id, hidden while grouped, and the grouping's id in
+     * the URL (`?group=status`) and in a saved view's `group`.
+     */
+    id: string;
+    /** The menu's word for it ("Status"), and the menu button's while it's on ("Group: Status"). */
+    label: string;
+    /** The field's options, in order: the groups, their order and their headings. */
+    options: readonly {
+        value: string;
+        label: string;
+    }[];
+    /**
+     * The row's value: one option's value, or a list of them for a
+     * multi-value field, whose row then shows under each. A value the
+     * options don't name gets a group of its own after theirs, headed by
+     * the value itself.
+     */
+    value: (row: TData) => string | readonly string[] | null | undefined;
+    /** The heading over rows with no value, last: "Not set" unless set ("No category"). */
+    emptyLabel?: string;
+};
 /** One of DataTable's card layouts (`layouts`). */
 export type DataTableCardLayout<TData> = {
     /** In the URL (`?layout=covers`) and remembered, so keep it short and stable. */
@@ -167,4 +224,4 @@ export type DataTableTotals = {
      */
     cells?: Partial<Record<string, ReactNode>>;
 };
-export declare function DataTable<TData extends Record<string, unknown>>({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width, groupBy, groupSummary, header: showHeader, highlightRow, totals, layouts, layout: layoutProp, onLayoutChange, tableLayout, }: DataTableProps<TData>): import("react").JSX.Element;
+export declare function DataTable<TData extends Record<string, unknown>>({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width, groupBy, groupSummary, header: showHeader, highlightRow, totals, layouts, layout: layoutProp, onLayoutChange, tableLayout, groupings, grouping: groupingProp, onGroupingChange, detailPanel, detailLabel, }: DataTableProps<TData>): import("react").JSX.Element;