@tristan2828/ui-foundation 4.45.0 → 4.46.0

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–502
-- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 504–562
-- [Notices](#notices) · lines 564–592
-- [A value over time](#a-value-over-time) · lines 594–627
-- [A list as a board](#a-list-as-a-board) · lines 629–680
-- [A list as cards](#a-list-as-cards) · lines 682–728
-- [Picking at random](#picking-at-random) · lines 730–761
-- [Filling in what's missing](#filling-in-whats-missing) · lines 763–813
+- [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 -->
 
@@ -684,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
@@ -727,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;

package/dist/components/app/data-table.js

@@ -14,16 +14,18 @@ import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } fr
 import { flexRender } from '@tanstack/react-table';
 import { cn } from 'cn';
 import { getCoreRowModel, useLegacyTable } from '@tanstack/react-table/legacy';
-import { ArrowDownIcon, ArrowUpIcon, ArrowUpDownIcon, ChevronLeftIcon, ChevronRightIcon, TableIcon } from 'lucide-react';
+import { ArrowDownIcon, ArrowUpIcon, ArrowUpDownIcon, ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon, ListTreeIcon, TableIcon, XIcon, } from 'lucide-react';
 import { ErrorState } from './error-state.js';
 import { Button } from '../ui/button.js';
+import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuTrigger, } from '../ui/dropdown-menu.js';
 import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from '../ui/empty.js';
+import { Sheet, SheetContent, SheetHeader, SheetTitle } from '../ui/sheet.js';
 import { Skeleton } from '../ui/skeleton.js';
 import { ToggleGroup, ToggleGroupItem } from '../ui/toggle-group.js';
 import { EditInPlaceContext } from './edit-in-place.js';
 import { EditInPlaceStore } from './edit-in-place-store.js';
 import { LeaveGuard } from './editable-value.js';
-import { groupRuns } from './table-groups.js';
+import { groupByValues, groupRuns } from './table-groups.js';
 import { Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow, } from '../ui/table.js';
 // A column def's id as TanStack resolves it (constructColumn): `id`, then
 // `accessorKey` with dots as underscores, then a string header. Group
@@ -74,6 +76,35 @@ function LayoutSwitch({ options, value, onValueChange, }) {
                 onValueChange(chosen);
         }, children: options.map(({ id, label, icon: Icon }) => (_jsxs(ToggleGroupItem, { value: id, className: LAYOUT_ITEM_CLASS, title: label, children: [_jsx(Icon, { "aria-hidden": "true", className: "size-4" }), _jsx("span", { className: "max-sm:sr-only", children: label })] }, id))) }));
 }
+// The Group menu (`groupings`): a radio list, None first, that closes on
+// a pick. Base UI's radio group needs a value for None, so it's this
+// stand-in, never '' (the grouping's own word for None).
+const NO_GROUPING = '__none__';
+function GroupMenu({ groupings, value, onValueChange, }) {
+    const current = groupings.find((grouping) => grouping.id === value);
+    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { render: _jsx(Button, { variant: "outline", size: "sm", "data-slot": "data-table-group-menu" }), children: [_jsx(ListTreeIcon, { "aria-hidden": "true" }), current ? `Group: ${current.label}` : 'Group'] }), _jsx(DropdownMenuContent, { align: "end", className: "w-48", children: _jsxs(DropdownMenuGroup, { children: [_jsx(DropdownMenuLabel, { children: "Group by" }), _jsxs(DropdownMenuRadioGroup, { value: current?.id ?? NO_GROUPING, onValueChange: (next) => onValueChange(next === NO_GROUPING ? '' : String(next)), children: [_jsx(DropdownMenuRadioItem, { value: NO_GROUPING, closeOnClick: true, children: "None" }), groupings.map((grouping) => (_jsx(DropdownMenuRadioItem, { value: grouping.id, closeOnClick: true, children: grouping.label }, grouping.id)))] })] }) })] }));
+}
+// Whether the detail panel (`detailPanel`) fits beside the table, or opens
+// as a bottom sheet. Wide on the server and wherever matchMedia is missing
+// (a test's DOM), so markup never depends on it.
+const WIDE_QUERY = '(min-width: 64rem)';
+const canMatchMedia = () => typeof window !== 'undefined' && typeof window.matchMedia === 'function';
+function subscribeWide(listener) {
+    if (!canMatchMedia())
+        return () => { };
+    const query = window.matchMedia(WIDE_QUERY);
+    query.addEventListener('change', listener);
+    return () => query.removeEventListener('change', listener);
+}
+const useIsWide = () => useSyncExternalStore(subscribeWide, () => !canMatchMedia() || window.matchMedia(WIDE_QUERY).matches, () => true);
+// A click on one of these inside a row is the control's own, not a pick of
+// the row. A link is the exception: a plain click picks the row instead of
+// following it (a modified one still opens it, in a new tab).
+const ROW_CONTROL_SELECTOR = 'a[href],button,input,select,textarea,label,summary,[contenteditable="true"],' +
+    '[role="button"],[role="checkbox"],[role="switch"],[role="combobox"],[role="link"],[role="slider"]';
+// Keys typed into one of these are its own: ↑/↓ and Escape stay with it.
+const TYPING_SELECTOR = 'input,select,textarea,[contenteditable="true"],[role="combobox"],[role="listbox"],[role="menu"],' +
+    '[role="slider"],[role="spinbutton"]';
 function TableSkeleton({ columnCount }) {
     return (_jsx("div", { className: "flex flex-col gap-2 p-2", "data-state": "loading", children: Array.from({ length: 5 }, (_, row) => (_jsx("div", { className: "flex gap-4", children: Array.from({ length: columnCount }, (_, col) => (_jsx(Skeleton, { className: "h-8 flex-1" }, col))) }, row))) }));
 }
@@ -140,6 +171,25 @@ const HIDDEN_HEAD_CLASS = 'h-0 p-0';
 const ALIGN_CLASS = { center: 'text-center', right: 'text-right' };
 const alignClass = (align) => align && ALIGN_CLASS[align];
 const GROUP_HEADING_CLASS = 'h-auto bg-background pt-4 pb-1.5 align-bottom';
+// A grouping's heading (`groupings`) is a button that folds its rows: the
+// label, then the count, a chevron that turns when folded.
+const GROUP_TOGGLE_CLASS = '-mx-1 inline-flex items-baseline gap-2 rounded-sm px-1 outline-none hover:underline ' +
+    'focus-visible:ring-3 focus-visible:ring-ring/50';
+// `detailPanel`: a row that can be picked shows a pointer and its focus
+// ring inside it (a row has no outline of its own room); the picked one
+// takes the muted fill on every cell, over the zebra stripe and the pinned
+// cells' opaque backgrounds as highlightRow's wash does, with a bar in
+// --primary at its start, so it reads without colour too.
+const SELECTABLE_ROW_CLASS = 'cursor-pointer outline-none focus-visible:[&>td]:shadow-[inset_0_2px_0_0_var(--ring),inset_0_-2px_0_0_var(--ring)]';
+const SELECTED_ROW_CLASS = '[&>td]:bg-muted [&>td:first-child]:shadow-[inset_3px_0_0_0_var(--primary)] ' +
+    'focus-visible:[&>td:first-child]:shadow-[inset_3px_0_0_0_var(--primary),inset_0_2px_0_0_var(--ring),inset_0_-2px_0_0_var(--ring)]';
+// The table and the panel side by side once one is picked on a wide
+// screen. The grid is there from the start, so opening the panel never
+// remounts the table (and the focused row with it).
+const WITH_DETAIL_OPEN_CLASS = 'grid-cols-[minmax(0,1fr)_minmax(18rem,26rem)]';
+const DETAIL_ASIDE_CLASS = 'sticky top-4 flex max-h-[calc(100dvh-2rem)] min-w-0 flex-col gap-3 overflow-y-auto rounded-lg border ' +
+    'border-border bg-card p-4 text-card-foreground';
+const EMPTY_KEYS = new Set();
 // `width="content"`: from a table area 80rem wide, as wide as the columns
 // need (`w-fit` over the table's own `w-full`), at least 36rem, or the
 // width it last had loaded while it shows another state
@@ -208,7 +258,7 @@ function useBottomScrollbar(containerRef, isSuccessView) {
     }, [containerRef, isSuccessView, isOverflowing]);
     return { barRef, isOverflowing, scrollWidth };
 }
-export function DataTable({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width = 'full', groupBy, groupSummary, header: showHeader = true, highlightRow, totals, layouts, layout: layoutProp, onLayoutChange, tableLayout, }) {
+export function DataTable({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width = 'full', groupBy, groupSummary, header: showHeader = true, highlightRow, totals, layouts, layout: layoutProp, onLayoutChange, tableLayout, groupings, grouping: groupingProp, onGroupingChange, detailPanel, detailLabel = 'Details', }) {
     // The switch's own state, for a table that doesn't pass `layout`.
     const [ownLayout, setOwnLayout] = useState('table');
     const requestedLayout = layoutProp ?? ownLayout;
@@ -219,6 +269,22 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
             setOwnLayout(next);
         onLayoutChange?.(next);
     };
+    // The grouping on (`groupings`), the menu's own state for a table that
+    // doesn't pass `grouping`.
+    const [ownGrouping, setOwnGrouping] = useState('');
+    const activeGrouping = groupings?.find((candidate) => candidate.id === (groupingProp ?? ownGrouping));
+    const setGrouping = (next) => {
+        if (groupingProp === undefined)
+            setOwnGrouping(next);
+        onGroupingChange?.(next);
+    };
+    // The folded headings, for the grouping they were folded in: picking
+    // another starts with every group open.
+    const [folds, setFolds] = useState({ grouping: '', keys: EMPTY_KEYS });
+    const folded = activeGrouping && folds.grouping === activeGrouping.id ? folds.keys : EMPTY_KEYS;
+    // The picked row (`detailPanel`) and the place it was picked in.
+    const [selection, setSelection] = useState(null);
+    const isWide = useIsWide();
     // Editing in place in the rows (cell pattern 18, "In a table's rows"):
     // a cell that renders an <EditableValue> edits where it's shown, one at
     // a time, with the leave-page prompt while one is open, the same rules
@@ -228,9 +294,13 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     const pageCount = Math.max(1, Math.ceil(total / pageSize));
     // TanStack treats a column missing from this map as visible, so every
     // column gets an entry once a list is given.
-    const columnVisibility = visibleColumns
-        ? Object.fromEntries(leafColumnIds(columns).map((id) => [id, visibleColumns.includes(id)]))
-        : {};
+    // While grouped, the grouped column is hidden: its value is the heading.
+    const columnVisibility = {
+        ...(visibleColumns
+            ? Object.fromEntries(leafColumnIds(columns).map((id) => [id, visibleColumns.includes(id)]))
+            : {}),
+        ...(activeGrouping ? { [activeGrouping.id]: false } : {}),
+    };
     const table = useLegacyTable({
         data,
         columns,
@@ -279,14 +349,124 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     const rows = table.getRowModel().rows;
     const visibleLeafColumns = table.getVisibleLeafColumns();
     const visibleColumnCount = visibleLeafColumns.length;
+    // The groups, if any: a grouping's (folding, with counts), else groupBy's.
+    const runs = activeGrouping
+        ? groupByValues(rows, (row) => activeGrouping.value(row.original), activeGrouping.options, activeGrouping.emptyLabel ?? 'Not set').map((run) => ({ ...run, foldable: true }))
+        : groupBy
+            ? groupRuns(rows, (row) => groupBy(row.original)).map((run) => ({ ...run, foldable: false }))
+            : null;
+    const allFolded = runs !== null && runs.length > 0 && runs.every((run) => folded.has(run.key));
+    const toggleFold = (key) => {
+        if (!activeGrouping)
+            return;
+        const keys = new Set(folded);
+        if (!keys.delete(key))
+            keys.add(key);
+        setFolds({ grouping: activeGrouping.id, keys });
+    };
+    const foldAll = () => {
+        if (!activeGrouping || !runs)
+            return;
+        setFolds({ grouping: activeGrouping.id, keys: allFolded ? EMPTY_KEYS : new Set(runs.map((run) => run.key)) });
+    };
+    // Every row's place in the list as shown (folded groups left out), in
+    // order, for ↑/↓. Under a grouping a place is the group and the row,
+    // since a multi-value field shows a row in more than one.
+    const placeKey = (runKey, rowId) => activeGrouping ? `${encodeURIComponent(runKey)}:${rowId}` : rowId;
+    const places = runs
+        ? runs.flatMap((run) => folded.has(run.key) ? [] : run.rows.map((row) => ({ key: placeKey(run.key, row.id), rowId: row.id })))
+        : rows.map((row) => ({ key: row.id, rowId: row.id }));
+    const selectedRow = detailPanel && selection ? rows.find((row) => row.id === selection.rowId) : undefined;
+    // The place marked picked: where it was picked, or (regrouped since) the
+    // row's first place. None while its group is folded.
+    const selectedKey = selectedRow
+        ? places.some((place) => place.key === selection?.key)
+            ? selection?.key
+            : places.find((place) => place.rowId === selectedRow.id)?.key
+        : undefined;
+    // The list's one tab stop: the picked row, else the first.
+    const tabStopKey = selectedKey ?? places[0]?.key;
+    const focusRow = (key) => {
+        if (key === undefined)
+            return;
+        containerRef.current?.querySelector(`tr[data-row-key="${CSS.escape(key)}"]`)?.focus();
+    };
+    const closeDetail = () => {
+        setSelection(null);
+        focusRow(selectedKey);
+    };
+    const onRowClick = (event, place) => {
+        const target = event.target;
+        // A click from a portal (a picker's popup opened from a cell) reaches
+        // the row through React, not the DOM: it's that control's.
+        if (!event.currentTarget.contains(target))
+            return;
+        if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+            return;
+        const control = target.closest(ROW_CONTROL_SELECTOR);
+        if (control && event.currentTarget.contains(control)) {
+            if (!control.matches('a[href]'))
+                return;
+            // In the capture phase, so react-router's Link sees it prevented and
+            // doesn't navigate.
+            event.preventDefault();
+        }
+        setSelection(place);
+    };
+    const onListKeyDown = (event) => {
+        const target = event.target;
+        if (event.defaultPrevented || !event.currentTarget.contains(target) || target.closest(TYPING_SELECTOR))
+            return;
+        if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+            if (places.length === 0)
+                return;
+            event.preventDefault();
+            const down = event.key === 'ArrowDown';
+            const index = places.findIndex((place) => place.key === selectedKey);
+            const nextIndex = index === -1 ? (down ? 0 : places.length - 1) : Math.min(places.length - 1, Math.max(0, index + (down ? 1 : -1)));
+            const next = places[nextIndex];
+            if (!next)
+                return;
+            setSelection(next);
+            focusRow(next.key);
+        }
+        else if (event.key === 'Enter' && target.dataset.rowKey !== undefined) {
+            const place = places.find((candidate) => candidate.key === target.dataset.rowKey);
+            if (!place)
+                return;
+            event.preventDefault();
+            setSelection(place);
+        }
+        else if (event.key === 'Escape' && selectedRow) {
+            event.preventDefault();
+            closeDetail();
+        }
+    };
     // One body row, the same in a plain table and a grouped one.
-    const renderRow = (row) => (_jsx(TableRow, { "data-highlighted": highlightRow?.(row.original) || undefined, className: cn(pinFirstColumn && ROW_GROUP_CLASS, highlightRow?.(row.original) && HIGHLIGHTED_ROW_CLASS), children: row.getVisibleCells().map((cell, index) => (_jsx(TableCell, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn && index === row.getVisibleCells().length - 1 && PINNED_LAST_COLUMN_CLASS, alignClass(cell.column.columnDef.meta?.align)), children: pinFirstColumn && index === 0 ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: flexRender(cell.column.columnDef.cell, cell.getContext()) })) : (flexRender(cell.column.columnDef.cell, cell.getContext())) }, cell.id))) }, row.id));
+    const renderRow = (row, key = row.id) => {
+        const isSelected = key === selectedKey;
+        return (_jsx(TableRow, { "data-highlighted": highlightRow?.(row.original) || undefined, ...(detailPanel
+                ? {
+                    'data-row-key': key,
+                    'data-selected': isSelected || undefined,
+                    'aria-selected': isSelected,
+                    tabIndex: key === tabStopKey ? 0 : -1,
+                    onClickCapture: (event) => onRowClick(event, { key, rowId: row.id }),
+                }
+                : {}), className: cn(pinFirstColumn && ROW_GROUP_CLASS, highlightRow?.(row.original) && HIGHLIGHTED_ROW_CLASS, detailPanel && SELECTABLE_ROW_CLASS, isSelected && SELECTED_ROW_CLASS), children: row.getVisibleCells().map((cell, index) => (_jsx(TableCell, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn && index === row.getVisibleCells().length - 1 && PINNED_LAST_COLUMN_CLASS, alignClass(cell.column.columnDef.meta?.align)), children: pinFirstColumn && index === 0 ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: flexRender(cell.column.columnDef.cell, cell.getContext()) })) : (flexRender(cell.column.columnDef.cell, cell.getContext())) }, cell.id))) }, key));
+    };
     const content = (_jsxs("div", { ref: root, className: cn('flex flex-col gap-4', width === 'content' && CONTENT_WIDTH_CLASS), "data-width": width, "data-layout": layouts?.length ? currentLayout : undefined, style: width === 'content' && !isSuccessView && lastWidth !== null
             ? { '--data-table-last-width': `${lastWidth}px` }
-            : undefined, children: [layouts?.length ? (_jsxs("div", { className: "flex flex-wrap items-end gap-x-4 gap-y-2", children: [_jsx("div", { className: "min-w-0 flex-1", children: toolbar }), _jsx(LayoutSwitch, { options: [
+            : undefined, children: [layouts?.length || groupings?.length ? (_jsxs("div", { className: "flex flex-wrap items-end gap-x-4 gap-y-2", children: [_jsx("div", { className: "min-w-0 flex-1", children: toolbar }), groupings?.length ? (_jsxs("div", { className: "flex items-center gap-2", children: [activeGrouping && (_jsx(Button, { variant: "ghost", size: "sm", "data-slot": "data-table-fold-all", disabled: !runs?.length, onClick: foldAll, children: allFolded ? 'Unfold all' : 'Fold all' })), _jsx(GroupMenu, { groupings: groupings, value: activeGrouping?.id ?? '', onValueChange: setGrouping })] })) : null, layouts?.length ? (_jsx(LayoutSwitch, { options: [
                             { id: 'table', label: tableLayout?.label ?? 'Table', icon: tableLayout?.icon ?? TableIcon },
                             ...layouts,
-                        ], value: currentLayout, onValueChange: setLayout })] })) : (toolbar), error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (cardLayout ? (_jsx(CardsSkeleton, { layout: cardLayout })) : (_jsx(TableSkeleton, { columnCount: table.getVisibleLeafColumns().length }))) : isEmpty ? (_jsxs(Empty, { "data-state": "empty", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: emptyTitle }), emptyDescription && _jsx(EmptyDescription, { children: emptyDescription })] }), emptyAction] })) : (_jsxs(_Fragment, { children: [cardLayout ? (_jsx(Cards, { layout: cardLayout, rows: rows, groupBy: groupBy, groupSummary: groupSummary })) : (_jsxs(Table, { "data-state": "success", containerRef: containerRef, 
+                        ], value: currentLayout, onValueChange: setLayout })) : null] })) : (toolbar), error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (cardLayout ? (_jsx(CardsSkeleton, { layout: cardLayout })) : (_jsx(TableSkeleton, { columnCount: table.getVisibleLeafColumns().length }))) : isEmpty ? (_jsxs(Empty, { "data-state": "empty", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: emptyTitle }), emptyDescription && _jsx(EmptyDescription, { children: emptyDescription })] }), emptyAction] })) : (_jsxs(DetailFrame, { enabled: Boolean(detailPanel) && !cardLayout, aside: selectedRow && detailPanel && isWide ? (_jsxs("aside", { "aria-label": detailLabel, "data-slot": "data-table-detail", className: DETAIL_ASIDE_CLASS, onKeyDown: (event) => {
+                        const target = event.target;
+                        if (event.key !== 'Escape' || event.defaultPrevented || target.closest(TYPING_SELECTOR))
+                            return;
+                        event.preventDefault();
+                        closeDetail();
+                    }, children: [_jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsx("h2", { className: "type-label text-muted-foreground", children: detailLabel }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Close", onClick: closeDetail, children: _jsx(XIcon, { "aria-hidden": "true" }) })] }), detailPanel(selectedRow.original)] })) : null, children: [cardLayout ? (_jsx(Cards, { layout: cardLayout, runs: runs, rows: rows, folded: folded, onToggleFold: toggleFold, groupSummary: groupSummary })) : (_jsxs(Table, { "data-state": "success", containerRef: containerRef, onKeyDown: detailPanel ? onListKeyDown : undefined, 
                         // With the sticky bar below as the visible scrollbar, hide the
                         // container's own. It stays overflow-x-auto and fully
                         // scrollable (wheel, trackpad, drag, and the sync effect); it
@@ -315,18 +495,38 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                                                     : sortDirection === 'desc'
                                                         ? 'descending'
                                                         : 'none', children: !showHeader ? (_jsx("span", { className: "sr-only", children: content })) : pinFirstColumn && index === 0 ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: content })) : (content) }, header.id));
-                                    }) }, headerGroup.id))) }), groupBy ? (groupRuns(rows, (row) => groupBy(row.original)).map((run, runIndex) => (_jsxs(TableBody, { "data-slot": "table-group", children: [_jsx(TableRow, { "data-slot": "table-group-heading", className: "hover:bg-transparent", children: _jsx(TableHead, { scope: "rowgroup", colSpan: visibleColumnCount, className: GROUP_HEADING_CLASS, children: _jsxs("span", { className: "sticky left-(--table-cell-px) inline-flex items-baseline gap-2", children: [_jsx("span", { className: "type-label text-foreground", children: run.label }), groupSummary && (_jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: groupSummary(run.rows.map((row) => row.original)) }))] }) }) }), _jsx("tr", { hidden: true, "aria-hidden": "true", "data-slot": "table-group-stripe-offset" }), run.rows.map(renderRow)] }, `${runIndex}:${run.key}`)))) : (_jsx(TableBody, { children: rows.map(renderRow) })), totals && (_jsx(TableFooter, { className: TOTALS_FOOTER_CLASS, children: _jsx(TableRow, { "data-slot": "table-totals", className: "hover:bg-transparent", children: visibleLeafColumns.map((column, index) => {
+                                    }) }, headerGroup.id))) }), runs ? (runs.map((run, runIndex) => {
+                                const isFolded = folded.has(run.key);
+                                return (_jsxs(TableBody, { "data-slot": "table-group", "data-folded": isFolded || undefined, children: [_jsx(TableRow, { "data-slot": "table-group-heading", className: "hover:bg-transparent has-aria-expanded:bg-transparent", children: _jsx(TableHead, { scope: "rowgroup", colSpan: visibleColumnCount, className: GROUP_HEADING_CLASS, children: _jsxs("span", { className: "sticky left-(--table-cell-px) inline-flex items-baseline gap-2", children: [_jsx(GroupLabel, { run: run, isFolded: isFolded, onToggle: () => toggleFold(run.key) }), groupSummary && (_jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: groupSummary(run.rows.map((row) => row.original), { key: run.key, label: run.label }) }))] }) }) }), _jsx("tr", { hidden: true, "aria-hidden": "true", "data-slot": "table-group-stripe-offset" }), !isFolded && run.rows.map((row) => renderRow(row, placeKey(run.key, row.id)))] }, `${runIndex}:${run.key}`));
+                            })) : (_jsx(TableBody, { children: rows.map((row) => renderRow(row)) })), totals && (_jsx(TableFooter, { className: TOTALS_FOOTER_CLASS, children: _jsx(TableRow, { "data-slot": "table-totals", className: "hover:bg-transparent", children: visibleLeafColumns.map((column, index) => {
                                         const className = cn(pinFirstColumn && index === 0 && PINNED_TOTALS_LABEL_CLASS, pinLastColumn && index === visibleColumnCount - 1 && PINNED_LAST_COLUMN_CLASS, alignClass(column.columnDef.meta?.align));
                                         return index === 0 ? (_jsx(TableHead, { scope: "row", className: cn(TOTALS_LABEL_CLASS, className), children: pinFirstColumn ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: totals.label })) : (totals.label) }, column.id)) : (_jsx(TableCell, { className: className, children: totals.cells?.[column.id] }, column.id));
                                     }) }) }))] })), pinFirstColumn && isOverflowing && !cardLayout && (_jsx("div", { ref: barRef, "aria-hidden": "true", tabIndex: -1, "data-slot": "bottom-scrollbar", className: "sticky bottom-0 z-20 h-4 overflow-x-auto border-t border-border bg-background", children: _jsx("div", { style: { width: scrollWidth, height: 1 } }) })), _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("p", { className: "type-body text-muted-foreground", children: [total === 0 ? 0 : (page - 1) * pageSize + 1, '–', Math.min(page * pageSize, total), " of ", total] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Previous page", disabled: page <= 1, onClick: () => onPageChange(page - 1), children: _jsx(ChevronLeftIcon, {}) }), _jsxs("span", { className: "type-body text-muted-foreground", children: ["Page ", page, " of ", pageCount] }), _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Next page", disabled: page >= pageCount, onClick: () => onPageChange(page + 1), children: _jsx(ChevronRightIcon, {}) })] })] })] }))] }));
-    return (_jsxs(EditInPlaceContext.Provider, { value: store, children: [editing && _jsx(LeaveGuard, { store: store }), width === 'content' ? _jsx("div", { className: "@container/data-table", children: content }) : content] }));
+    return (_jsxs(EditInPlaceContext.Provider, { value: store, children: [editing && _jsx(LeaveGuard, { store: store }), width === 'content' ? _jsx("div", { className: "@container/data-table", children: content }) : content, detailPanel && (_jsx(Sheet, { open: Boolean(selectedRow) && !isWide && isSuccessView && !cardLayout, onOpenChange: (open) => {
+                    if (!open)
+                        setSelection(null);
+                }, children: _jsxs(SheetContent, { side: "bottom", className: "max-h-[85dvh] overflow-y-auto", "data-slot": "data-table-detail-sheet", children: [_jsx(SheetHeader, { className: "pb-0", children: _jsx(SheetTitle, { children: detailLabel }) }), _jsx("div", { className: "px-4 pb-4", children: selectedRow && detailPanel(selectedRow.original) })] }) }))] }));
+}
+// The list and, once a row is picked on a wide screen, the detail panel
+// beside it (`detailPanel`). Without a panel it adds nothing.
+function DetailFrame({ enabled, aside, children }) {
+    if (!enabled)
+        return _jsx(_Fragment, { children: children });
+    return (_jsxs("div", { "data-slot": "data-table-with-detail", className: cn('grid items-start gap-4', aside && WITH_DETAIL_OPEN_CLASS), children: [_jsx("div", { className: "flex min-w-0 flex-col gap-4", children: children }), aside] }));
+}
+// A group's heading text: under a grouping, a button that folds the group,
+// with its row count; under `groupBy`, the label alone.
+function GroupLabel({ run, isFolded, onToggle, }) {
+    if (!run.foldable)
+        return _jsx("span", { className: "type-label text-foreground", children: run.label });
+    return (_jsxs("button", { type: "button", "aria-expanded": !isFolded, onClick: onToggle, className: GROUP_TOGGLE_CLASS, children: [_jsx(ChevronDownIcon, { "aria-hidden": "true", className: cn('size-4 self-center text-muted-foreground transition-transform', isFolded && '-rotate-90') }), _jsx("span", { className: "type-label text-foreground", children: run.label }), _jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: run.rows.length })] }));
 }
-// A card layout's success view: the rows as cards in a grid or a list,
-// each run of one group (`groupBy`) under its own heading, as the table's
-// heading rows are, with the same label and summary.
-function Cards({ layout, rows, groupBy, groupSummary, }) {
+function Cards({ layout, runs, rows, folded, onToggleFold, groupSummary, }) {
     const list = (items) => (_jsx("ul", { role: "list", className: cn(layout.arrange === 'list' ? CARD_LIST_CLASS : ['grid', CARD_GRID_CLASS[layout.size ?? 'md'], CARD_GRID_GAP_CLASS]), children: items.map((row) => (_jsx("li", { "data-slot": "data-table-card", className: "min-w-0", children: layout.renderCard(row.original) }, row.id))) }));
-    return (_jsx("div", { className: "@container/data-table-cards flex flex-col gap-6", "data-state": "success", "data-slot": "data-table-cards", children: groupBy
-            ? groupRuns(rows, (row) => groupBy(row.original)).map((run, runIndex) => (_jsxs("section", { "data-slot": "table-group", className: "flex flex-col gap-3", children: [_jsxs("h2", { "data-slot": "table-group-heading", className: "flex items-baseline gap-2 border-b border-border pb-1.5", children: [_jsx("span", { className: "type-label text-foreground", children: run.label }), groupSummary && (_jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: groupSummary(run.rows.map((row) => row.original)) }))] }), list(run.rows)] }, `${runIndex}:${run.key}`)))
+    return (_jsx("div", { className: "@container/data-table-cards flex flex-col gap-6", "data-state": "success", "data-slot": "data-table-cards", children: runs
+            ? runs.map((run, runIndex) => {
+                const isFolded = folded.has(run.key);
+                return (_jsxs("section", { "data-slot": "table-group", "data-folded": isFolded || undefined, className: "flex flex-col gap-3", children: [_jsxs("h2", { "data-slot": "table-group-heading", className: "flex items-baseline gap-2 border-b border-border pb-1.5", children: [_jsx(GroupLabel, { run: run, isFolded: isFolded, onToggle: () => onToggleFold(run.key) }), groupSummary && (_jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: groupSummary(run.rows.map((row) => row.original), { key: run.key, label: run.label }) }))] }), !isFolded && list(run.rows)] }, `${runIndex}:${run.key}`));
+            })
             : list(rows) }));
 }

package/dist/components/app/entity-view.d.ts

@@ -66,6 +66,12 @@ export type EntityViewProps = {
     titleEdit?: EditInPlace & {
         label: string;
     };
+    /**
+     * A line under the title, in muted body type: what the record is for (a
+     * goal, a one-line summary). Any markup, an `<EditableValue>` included,
+     * so it can be edited in place where it's shown.
+     */
+    subtitle?: ReactNode;
     /**
      * A few status-like values beside the title, as `<Badge>`s, or as the
      * control that changes one when the plan makes it a quick action (a
@@ -80,6 +86,13 @@ export type EntityViewProps = {
      * every width. Announced when it appears or changes after the page loads.
      */
     notice?: ReactNode;
+    /**
+     * A row of the record's key numbers (`<KeyStats>`) under the header and
+     * its notice, across the page at every width: in the rail layout above
+     * both columns, so on a phone it comes before the rail and the main
+     * column.
+     */
+    strip?: ReactNode;
     sections: EntityViewSection[];
     /**
      * Below every section (both columns in the rail layout), in small muted
@@ -101,4 +114,4 @@ export type EntityViewProps = {
         label: string;
     };
 };
-export declare function EntityView({ title, documentTitle, titleEdit, badges, actions, notice, sections, footer, layout, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;
+export declare function EntityView({ title, documentTitle, titleEdit, subtitle, badges, actions, notice, strip, sections, footer, layout, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;

package/dist/components/app/entity-view.js

@@ -29,8 +29,10 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // autosave as it's typed (`autosave`), and be the editor itself, with no
 // click to open (`alwaysEditable`).
 //
+// In the header, `subtitle` under the title (a goal, a one-line summary).
 // Around the sections: `notice` (a <Notice>) under the header, across the
-// page, for a state that decides what you do with the record; `footer`
+// page, for a state that decides what you do with the record; `strip` (a
+// <KeyStats>) under that, the record's key numbers; `footer`
 // (a <SourceCredit>) after them all, for crediting the data's source.
 //
 // Two layouts. `column` (the default): every section in one column capped
@@ -141,7 +143,7 @@ function Rail({ label, sections }) {
     const [ref, fits] = useFitsWindow();
     return (_jsx("aside", { ref: ref, "aria-label": label, "data-fits": fits ? '' : undefined, className: cn(RAIL_LAYOUT.rail, RAIL_LAYOUT.sticky, 'flex min-w-0 flex-col gap-6'), children: sections.map((section) => (_jsx(ViewSection, { section: section, inRail: true }, section.title))) }));
 }
-export function EntityView({ title, documentTitle, titleEdit, badges, actions, notice, sections, footer, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
+export function EntityView({ title, documentTitle, titleEdit, subtitle, badges, actions, notice, strip, sections, footer, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
     // Editing in place: one store per view, and the leave-page prompt only
     // while a field is open (or one is always editable).
     const [store] = useState(() => new EditInPlaceStore());
@@ -158,5 +160,5 @@ export function EntityView({ title, documentTitle, titleEdit, badges, actions, n
         return _jsx(EntityViewSkeleton, { layout: layout });
     const railSections = sections.filter((section) => section.placement === 'rail');
     const mainSections = sections.filter((section) => section.placement !== 'rail');
-    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [editing && _jsx(LeaveGuard, { store: store }), _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), _jsx("div", { role: "status", "data-slot": "entity-view-notice", className: "empty:hidden", children: notice }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), _jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) })] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title))), footer && (_jsx("footer", { "data-slot": "entity-view-footer", className: "type-caption text-muted-foreground", children: footer }))] }) }));
+    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [editing && _jsx(LeaveGuard, { store: store }), _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), subtitle && (_jsx("div", { "data-slot": "entity-view-subtitle", className: "type-body break-words text-muted-foreground", children: subtitle })), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), _jsx("div", { role: "status", "data-slot": "entity-view-notice", className: "empty:hidden", children: notice }), strip && _jsx("div", { "data-slot": "entity-view-strip", children: strip }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), _jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) })] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title))), footer && (_jsx("footer", { "data-slot": "entity-view-footer", className: "type-caption text-muted-foreground", children: footer }))] }) }));
 }

package/dist/components/app/key-stats.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+export type KeyStat = {
+    label: string;
+    value: ReactNode;
+    /** A few words under the value ("of 12", "since May"), in caption type. */
+    hint?: ReactNode;
+};
+export type KeyStatsProps = {
+    stats: readonly KeyStat[];
+    /** What an empty value reads as. Defaults to "Not set". */
+    emptyLabel?: string;
+    className?: string;
+};
+export declare function KeyStats({ stats, emptyLabel, className }: KeyStatsProps): import("react").JSX.Element;

package/dist/components/app/key-stats.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from 'cn';
+const isEmpty = (value) => value === null || value === undefined || value === false || value === '';
+export function KeyStats({ stats, emptyLabel = 'Not set', className }) {
+    return (_jsx("dl", { "data-slot": "key-stats", className: cn('flex flex-wrap gap-x-8 gap-y-3 rounded-lg border border-border bg-card px-4 py-3 text-card-foreground', className), children: stats.map((stat) => (_jsxs("div", { className: "flex min-w-0 flex-col gap-0.5", children: [_jsx("dt", { className: "type-caption text-muted-foreground", children: stat.label }), _jsx("dd", { className: "type-section-title tabular-nums break-words text-foreground", children: isEmpty(stat.value) ? _jsx("span", { className: "type-body text-muted-foreground", children: emptyLabel }) : stat.value }), stat.hint && _jsx("dd", { className: "type-caption text-muted-foreground", children: stat.hint })] }, stat.label))) }));
+}

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

@@ -7,3 +7,15 @@ export type GroupRun<T> = RowGroup & {
     rows: T[];
 };
 export declare function groupRuns<T>(rows: readonly T[], groupOf: (row: T) => RowGroup): GroupRun<T>[];
+/**
+ * Rows grouped by a choice field's value (DataTable's `groupings`): one
+ * group per option, in the options' order, then any value the options
+ * don't name (in the order first met), then the rows with none under
+ * `emptyLabel`. A multi-value field (an array) puts the row under each of
+ * its values. Rows keep the server's order inside a group, and a group
+ * with no rows on this page never exists.
+ */
+export declare function groupByValues<T>(rows: readonly T[], valueOf: (row: T) => string | readonly string[] | null | undefined, options: readonly {
+    value: string;
+    label: string;
+}[], emptyLabel: string): GroupRun<T>[];

package/dist/components/app/table-groups.js

@@ -16,3 +16,40 @@ export function groupRuns(rows, groupOf) {
     }
     return runs;
 }
+/**
+ * Rows grouped by a choice field's value (DataTable's `groupings`): one
+ * group per option, in the options' order, then any value the options
+ * don't name (in the order first met), then the rows with none under
+ * `emptyLabel`. A multi-value field (an array) puts the row under each of
+ * its values. Rows keep the server's order inside a group, and a group
+ * with no rows on this page never exists.
+ */
+export function groupByValues(rows, valueOf, options, emptyLabel) {
+    const byKey = new Map();
+    const unknown = [];
+    const known = new Set(options.map((option) => option.value));
+    // The empty group's key can't collide with a value: values are non-empty.
+    const EMPTY = '';
+    for (const row of rows) {
+        const raw = valueOf(row);
+        const values = [...new Set((typeof raw === 'string' ? [raw] : (raw ?? [])).filter((value) => value !== ''))];
+        for (const value of values.length > 0 ? values : [EMPTY]) {
+            if (value !== EMPTY && !known.has(value) && !byKey.has(value))
+                unknown.push(value);
+            const group = byKey.get(value);
+            if (group)
+                group.push(row);
+            else
+                byKey.set(value, [row]);
+        }
+    }
+    const run = (key, label) => {
+        const groupRows = byKey.get(key);
+        return groupRows ? [{ key, label, rows: groupRows }] : [];
+    };
+    return [
+        ...options.flatMap((option) => run(option.value, option.label)),
+        ...unknown.flatMap((value) => run(value, value)),
+        ...run(EMPTY, emptyLabel),
+    ];
+}

package/dist/hooks/table-url-changes.d.ts

@@ -13,6 +13,13 @@ export type TableView<F extends string, M extends string> = {
      * Applies only while the view is active (see activeViewOf).
      */
     columns?: readonly string[];
+    /**
+     * The grouping this view turns on, for DataTable's `grouping`: a
+     * grouping's id, or '' for None. Pressing the view sets it; a view that
+     * leaves it out keeps whatever grouping is on, since a grouping is how
+     * the rows are read, not which rows they are.
+     */
+    group?: string;
 };
 export declare function serializeSort(next: Sort): string | null;
 export declare function applyUrlChanges(previous: URLSearchParams, changes: UrlChanges): URLSearchParams;

package/dist/hooks/table-url-changes.js

@@ -27,6 +27,7 @@ export function viewToUrlChanges(filterNames, multiFilterNames, view) {
         ...Object.fromEntries(filterNames.map((name) => [name, view.filters?.[name] ?? ''])),
         ...Object.fromEntries(multiFilterNames.map((name) => [name, view.multiFilters?.[name] ?? []])),
         sort: view.sort ? serializeSort(view.sort) : null,
+        ...(view.group === undefined ? {} : { group: view.group || null }),
         page: null,
     };
 }

package/dist/hooks/use-table-layout.d.ts

@@ -7,6 +7,7 @@ export type LayoutStore = {
 export declare function createLayoutStore(getStorage: () => StorageLike | undefined): LayoutStore;
 /** The layout to show: the URL's if the table has it, then the remembered one, then the default. */
 export declare function resolveLayout(layouts: readonly string[], fromUrl: string | null, remembered: string | null, defaultLayout: string): string;
+export declare const browserStore: LayoutStore;
 export type TableLayoutOptions = {
     /** Every layout id the table has, the table's own `'table'` among them. */
     layouts: readonly string[];

package/dist/hooks/use-table-layout.js

@@ -43,7 +43,8 @@ export function resolveLayout(layouts, fromUrl, remembered, defaultLayout) {
         return remembered;
     return defaultLayout;
 }
-const browserStore = createLayoutStore(() => (typeof window === 'undefined' ? undefined : window.localStorage));
+// This device's remembered picks, shared with useTableUrlState's grouping.
+export const browserStore = createLayoutStore(() => (typeof window === 'undefined' ? undefined : window.localStorage));
 /**
  * `{ layout, setLayout }` for DataTable's `layout` and `onLayoutChange`.
  * Setting one writes `?layout=` (replacing the history entry, as a filter

package/dist/hooks/use-table-url-state.d.ts

@@ -1,11 +1,21 @@
 import type { SortingState } from '../components/app/data-table.js';
 import { type TableView } from './table-url-changes.js';
-export declare function useTableUrlState<F extends string, M extends string = never, V extends string = never>(filterNames: readonly F[], multiFilterNames?: readonly M[], views?: Readonly<Record<V, TableView<NoInfer<F>, NoInfer<M>>>>): {
+export type TableUrlStateOptions = {
+    /**
+     * Where the table's grouping (DataTable's `grouping`) is remembered on
+     * this device, one key per table (`"my-app:tasks:group"`), the way
+     * useTableLayout remembers a layout. Without one it lives only in the URL.
+     */
+    groupStorageKey?: string;
+};
+export declare function useTableUrlState<F extends string, M extends string = never, V extends string = never>(filterNames: readonly F[], multiFilterNames?: readonly M[], views?: Readonly<Record<V, TableView<NoInfer<F>, NoInfer<M>>>>, { groupStorageKey }?: TableUrlStateOptions): {
     page: number;
     sorting: SortingState;
     filters: Record<F, string>;
     multiFilters: Record<M, string[]>;
     activeView: V | null;
+    grouping: string;
+    setGrouping: (next: string) => void;
     setPage: (next: number) => void;
     setSorting: (next: SortingState) => void;
     setFilter: (name: F, value: string) => void;

package/dist/hooks/use-table-url-state.js

@@ -1,5 +1,7 @@
+import { useCallback, useSyncExternalStore } from 'react';
 import { useSearchParams } from 'react-router';
 import { activeViewOf, applyUrlChanges, serializeSort, viewToUrlChanges, } from './table-url-changes.js';
+import { browserStore } from './use-table-layout.js';
 // A table's page, sort and filters, kept in the URL query string
 // (`?page=2&sort=name:asc&search=mouse&tags=fragile&tags=bulky`) instead of
 // component state, so they survive going to the edit form and back, a
@@ -15,9 +17,22 @@ import { activeViewOf, applyUrlChanges, serializeSort, viewToUrlChanges, } from
 // counts as active); pass that view's `columns` to DataTable. A view is
 // pressed with applyView().
 //
+// `grouping` is DataTable's: a grouping's id, or '' for None. It's
+// `?group=` in the URL, then the one remembered under `groupStorageKey`,
+// then None. Like the sort it doesn't change which rows are shown, so it
+// keeps the page and doesn't count toward the active view; a view that
+// names a `group` sets it when pressed.
+//
 // Every setter is one update(), and must stay one: see setFilters.
-export function useTableUrlState(filterNames, multiFilterNames = [], views = {}) {
+export function useTableUrlState(filterNames, multiFilterNames = [], views = {}, { groupStorageKey } = {}) {
     const [params, setParams] = useSearchParams();
+    const subscribe = useCallback((listener) => (groupStorageKey === undefined ? () => { } : browserStore.subscribe(groupStorageKey, listener)), [groupStorageKey]);
+    const rememberedGrouping = useSyncExternalStore(subscribe, () => (groupStorageKey === undefined ? null : browserStore.get(groupStorageKey)), () => null);
+    const grouping = params.get('group') ?? rememberedGrouping ?? '';
+    const rememberGrouping = (next) => {
+        if (groupStorageKey !== undefined)
+            browserStore.set(groupStorageKey, next);
+    };
     const page = Math.max(1, Math.floor(Number(params.get('page'))) || 1);
     const [sortField, sortDir] = (params.get('sort') ?? '').split(':');
     const sorting = sortField ? [{ id: sortField, desc: sortDir === 'desc' }] : [];
@@ -33,6 +48,11 @@ export function useTableUrlState(filterNames, multiFilterNames = [], views = {})
         filters,
         multiFilters,
         activeView,
+        grouping,
+        setGrouping: (next) => {
+            rememberGrouping(next);
+            update({ group: next || null });
+        },
         setPage: (next) => update({ page: next > 1 ? String(next) : null }),
         setSorting: (next) => update({ sort: serializeSort(next), page: null }),
         setFilter: (name, value) => update({ [name]: value, page: null }),
@@ -46,6 +66,10 @@ export function useTableUrlState(filterNames, multiFilterNames = [], views = {})
         setMultiFilter: (name, values) => update({ [name]: values, page: null }),
         // Replaces the whole filter + sort state at once — a saved view. See
         // viewToUrlChanges() for why anything the view doesn't set is cleared.
-        applyView: (view) => update(viewToUrlChanges(filterNames, multiFilterNames, view)),
+        applyView: (view) => {
+            if (view.group !== undefined)
+                rememberGrouping(view.group);
+            update(viewToUrlChanges(filterNames, multiFilterNames, view));
+        },
     };
 }

package/dist/index.d.ts

@@ -6,10 +6,11 @@ export { pickSpinWheelIndex, type SpinWheelItem } from './components/app/spin-wh
 export { FillInChoice, FillInQueue, type FillInChoiceProps, type FillInQueueProgress, type FillInQueueProps, } from './components/app/fill-in-queue.js';
 export { Artwork, ArtworkTag, ArtworkToggle, type ArtworkAspect, type ArtworkProps, type ArtworkToggleProps, } from './components/app/artwork.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
-export { DataTable, type DataTableCardLayout, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';
+export { DataTable, type DataTableCardLayout, type DataTableGrouping, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';
 export { type RowGroup } from './components/app/table-groups.js';
 export { byDay, type ByDayOptions } from './lib/group-by-day.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
+export { KeyStats, type KeyStat, type KeyStatsProps } from './components/app/key-stats.js';
 export { EntityView, type EntityViewField, type EntityViewLayout, type EntityViewPlacement, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
 export { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceList, type EditInPlaceListOptions, type EditInPlaceOptions, type EditKind, type EditListAddProps, type EditListItemProps, } from './components/app/edit-in-place.js';
 export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
@@ -55,7 +56,7 @@ export type { AuthContextValue, AuthStatus, AuthUser, SignInResult } from './aut
 export type { AppError, Page, QuerySpec } from './api/contracts.js';
 export type { ErrorReportingOptions } from './error-reporting/reporter.js';
 export { createQueryClient } from './api/query-client.js';
-export { useTableUrlState } from './hooks/use-table-url-state.js';
+export { useTableUrlState, type TableUrlStateOptions } from './hooks/use-table-url-state.js';
 export { useTableLayout, type TableLayoutOptions } from './hooks/use-table-layout.js';
 export { useWidgetLayout, createWidgetLayoutStore, mergeWidgetLayout, type SavedWidgetLayout, type WidgetLayout, type WidgetLayoutOptions, type WidgetLayoutStore, } from './hooks/use-widget-layout.js';
 export type { TableView, UrlChanges } from './hooks/table-url-changes.js';

package/dist/index.js

@@ -14,6 +14,7 @@ export { DataTable, } from './components/app/data-table.js';
 export {} from './components/app/table-groups.js';
 export { byDay } from './lib/group-by-day.js';
 export { EntityForm } from './components/app/entity-form.js';
+export { KeyStats } from './components/app/key-stats.js';
 export { EntityView, } from './components/app/entity-view.js';
 export { editInPlace, } from './components/app/edit-in-place.js';
 export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.45.0",
+  "version": "4.46.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {