@tristan2828/ui-foundation 4.6.0 → 4.8.0

package/conventions/docs/cell-patterns.md

@@ -1088,3 +1088,70 @@ What the cell decides:
   count reads it.
 - **On the record's view**, the same `CountLink` beside its label (`Open
   tasks: 3`), with the record's name in `label` like the table's.
+
+## 21. Rows grouped under headings, and a pill filter
+
+A feed, an activity log or a timeline reads best as rows under day
+headings (Today, Yesterday, Earlier this week, then each older week, then
+months), each heading with a count and a summary ("4 · 1 h 12 m"). The
+same screens usually want one quick filter as pills above the rows (All /
+Video / Audio / Text, one pressed at a time) rather than a dropdown: there
+are few values, and switching between them is the main thing people do.
+Raised for an app's feed (issue #135); the package's Storybook renders it
+(`app/DataTable` "Grouped" and "Grouped no matches"), with axe in both
+themes.
+
+```tsx
+import { byDay, DataTable, PillFilter } from '@tristan2828/ui-foundation'
+
+const byPublished = byDay<FeedItem>('publishedAt')   // module level: once, not every render
+
+const { page, filters, setFilter, setPage } = useTableUrlState(['kind'])
+
+<DataTable
+  header={false}
+  groupBy={byPublished}
+  groupSummary={(items) => `${items.length} · ${duration(sum(items, 'minutes'))}`}
+  emptyTitle={filters.kind ? `No ${KIND_LABELS[filters.kind].toLowerCase()} items` : 'Nothing in the feed yet'}
+  emptyAction={filters.kind ? <Button variant="outline" onClick={() => setFilter('kind', '')}>Show all types</Button> : undefined}
+  toolbar={
+    <PillFilter label="Type" value={filters.kind} onValueChange={(kind) => setFilter('kind', kind)}
+      options={KINDS.map((kind) => ({ value: kind, label: KIND_LABELS[kind] }))} />
+  }
+  … />
+```
+
+- **The server sorts, the table only heads.** `groupBy` says which
+  group a row is in; a heading row starts wherever the key changes, so
+  sort the list by the grouped field (newest first) or a key will come
+  back with a second heading. Paging pages rows: a group split across
+  pages repeats its heading on the next, and `groupSummary` is given the
+  group's rows *on this page*. A summary that must count the whole group
+  comes from the API.
+- **`byDay(field, { now, timeZone })`** counts calendar days in the
+  zone (the browser's by default), so a time near midnight or a daylight
+  saving change never moves a row to the wrong day. Weeks start on
+  Monday (`weekStartsOn: 0` for Sunday). Four weeks back it switches to
+  months ("September", "December 2025"). A later date is Upcoming, no
+  date is No date. Pin `now` in a test, as for pattern 8.
+- **A heading is a row header for its group** (`<th scope="rowgroup">`
+  in the group's own `<tbody>`), so a screen reader names a cell's group
+  as it names its column. It stays in view while a wide table scrolls
+  sideways.
+- **`header={false}`** for a list-like table whose columns explain
+  themselves (a thumbnail with a title block, then actions). The header
+  row takes no room but stays in the table, so the columns keep their
+  names for a screen reader; sorting, if any, moves to the toolbar.
+  Fewer, wider columns read as a list: put the thumbnail inside the
+  title's cell rather than a column of its own.
+- **`PillFilter` is a filter like the others**: its value is in the URL
+  (`useTableUrlState`, '' for All) and `setFilter` sets it, so it returns
+  to page 1 and survives a refresh, back and forward. Pressing the
+  pressed pill leaves it pressed; All takes the filter off
+  (`allLabel={null}` drops All for a filter that always has a value). It
+  is one tab stop, the arrows along it; the pressed pill is filled with
+  `--primary`, not the toggle's faint tint.
+- **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.

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

@@ -1,6 +1,8 @@
+import { type ReactNode } from 'react';
 import type { CellData, RowData, TableFeatures } from '@tanstack/react-table';
 import { type LegacyColumnDef } from '@tanstack/react-table/legacy';
 import type { AppError } from '../../api/contracts.js';
+import { type RowGroup } from './table-groups.js';
 export type SortingState = {
     id: string;
     desc: boolean;
@@ -70,6 +72,24 @@ export type DataTableProps<TData extends Record<string, unknown>> = {
      * don't move it (only the first load can).
      */
     width?: DataTableWidth;
+    /**
+     * Rows under headings: each row's group (`byDay(field)` for a feed or a
+     * log). Rows keep the server's order, and a heading row spanning every
+     * column starts each run of one key. Paging pages rows, not groups, so a
+     * group split across pages repeats its heading on the next.
+     */
+    groupBy?: (row: TData) => RowGroup;
+    /**
+     * What a heading says after its label ("4 · 1 h 12 m"), from the group's
+     * rows on this page.
+     */
+    groupSummary?: (rows: TData[]) => ReactNode;
+    /**
+     * False hides the column header row, for a list-like table whose columns
+     * explain themselves (a thumbnail, a title block, actions). Screen readers
+     * still get the column names; sorting moves to the toolbar.
+     */
+    header?: boolean;
 };
 export type DataTableWidth = 'full' | 'content';
-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, }: 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, }: DataTableProps<TData>): import("react").JSX.Element;

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

@@ -22,6 +22,7 @@ import { Skeleton } from '../ui/skeleton.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 { Table, TableBody, TableCell, 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 +75,13 @@ const PINNED_FIRST_CONTENT_CLASS = 'max-md:max-w-[45cqw] max-md:whitespace-norma
 // background so it reads identically on striped and unstriped rows, and it
 // stays on screen when the table is scrolled right.
 const ROW_GROUP_CLASS = 'group/row hover:bg-transparent';
+// `header={false}`: the header row stays in the table, so every cell keeps
+// its column header for a screen reader, but takes no room: each header
+// is its name in an sr-only span, in a cell with no height or padding.
+const HIDDEN_HEAD_CLASS = 'h-0 p-0';
+// A group's heading row (`groupBy`): a little air above, so the groups
+// read apart, and the page's background, never the zebra stripe.
+const GROUP_HEADING_CLASS = 'h-auto bg-background pt-4 pb-1.5 align-bottom';
 // `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
@@ -142,7 +150,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', }) {
+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, }) {
     // 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
@@ -200,6 +208,10 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     }, [width, isSuccessView]);
     const containerRef = useRef(null);
     const { barRef, isOverflowing, scrollWidth } = useBottomScrollbar(containerRef, Boolean(pinFirstColumn) && isSuccessView);
+    const rows = table.getRowModel().rows;
+    const visibleColumnCount = table.getVisibleLeafColumns().length;
+    // One body row, the same in a plain table and a grouped one.
+    const renderRow = (row) => (_jsx(TableRow, { className: cn(pinFirstColumn && ROW_GROUP_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, cell.column.columnDef.meta?.align === 'center' && 'text-center'), 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 content = (_jsxs("div", { ref: root, className: cn('flex flex-col gap-4', width === 'content' && CONTENT_WIDTH_CLASS), "data-width": width, style: width === 'content' && !isSuccessView && lastWidth !== null
             ? { '--data-table-last-width': `${lastWidth}px` }
             : undefined, children: [toolbar, error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (_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: [_jsxs(Table, { "data-state": "success", containerRef: containerRef, 
@@ -213,11 +225,13 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                         // `width="content"` couldn't fit the table. Its query only
                         // serves a phone-width rule, and an 80rem table area never
                         // is one.
-                        width === 'content' && '@7xl/data-table:[container-type:normal]'), children: [_jsx(TableHeader, { children: table.getHeaderGroups().map((headerGroup) => (_jsx(TableRow, { children: headerGroup.headers.map((header, index) => {
+                        width === 'content' && '@7xl/data-table:[container-type:normal]'), children: [_jsx(TableHeader, { className: cn(!showHeader && '[&_tr]:border-0'), children: table.getHeaderGroups().map((headerGroup) => (_jsx(TableRow, { children: headerGroup.headers.map((header, index) => {
                                         const canSort = header.column.getCanSort();
                                         const sortDirection = header.column.getIsSorted();
-                                        const content = header.isPlaceholder ? null : canSort ? (_jsxs("button", { type: "button", className: cn('flex items-center gap-1 text-foreground', header.column.columnDef.meta?.align === 'center' && 'w-full justify-center'), onClick: header.column.getToggleSortingHandler(), children: [flexRender(header.column.columnDef.header, header.getContext()), sortDirection === 'asc' ? (_jsx(ArrowUpIcon, { className: "size-3.5 text-muted-foreground" })) : sortDirection === 'desc' ? (_jsx(ArrowDownIcon, { className: "size-3.5 text-muted-foreground" })) : (_jsx(ArrowUpDownIcon, { className: "size-3.5 text-muted-foreground/50" }))] })) : (flexRender(header.column.columnDef.header, header.getContext()));
-                                        return (_jsx(TableHead, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn &&
+                                        // Hidden, a header is its name only: a sort button no
+                                        // one can see would still take focus.
+                                        const content = header.isPlaceholder ? null : canSort && showHeader ? (_jsxs("button", { type: "button", className: cn('flex items-center gap-1 text-foreground', header.column.columnDef.meta?.align === 'center' && 'w-full justify-center'), onClick: header.column.getToggleSortingHandler(), children: [flexRender(header.column.columnDef.header, header.getContext()), sortDirection === 'asc' ? (_jsx(ArrowUpIcon, { className: "size-3.5 text-muted-foreground" })) : sortDirection === 'desc' ? (_jsx(ArrowDownIcon, { className: "size-3.5 text-muted-foreground" })) : (_jsx(ArrowUpDownIcon, { className: "size-3.5 text-muted-foreground/50" }))] })) : (flexRender(header.column.columnDef.header, header.getContext()));
+                                        return (_jsx(TableHead, { className: cn(!showHeader && HIDDEN_HEAD_CLASS, pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn &&
                                                 index === headerGroup.headers.length - 1 &&
                                                 PINNED_LAST_COLUMN_CLASS, header.column.columnDef.meta?.align === 'center' && 'text-center'), "aria-sort": !canSort
                                                 ? undefined
@@ -225,9 +239,7 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                                                     ? 'ascending'
                                                     : sortDirection === 'desc'
                                                         ? 'descending'
-                                                        : 'none', children: pinFirstColumn && index === 0 ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: content })) : (content) }, header.id));
-                                    }) }, headerGroup.id))) }), _jsx(TableBody, { children: table.getRowModel().rows.map((row) => (_jsx(TableRow, { className: cn(pinFirstColumn && ROW_GROUP_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, cell.column.columnDef.meta?.align === 'center' && 'text-center'), 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))) })] }), pinFirstColumn && isOverflowing && (_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, {}) })] })] })] }))] }));
+                                                        : '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) }))] }), pinFirstColumn && isOverflowing && (_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] }));
 }

package/dist/components/app/pill-filter.d.ts

@@ -0,0 +1,15 @@
+export type PillFilterOption = {
+    value: string;
+    label: string;
+};
+export type PillFilterProps = {
+    /** What the pills choose ("Type"): the group's accessible name. */
+    label: string;
+    options: readonly PillFilterOption[];
+    /** The pressed option's value; '' is All. */
+    value: string;
+    onValueChange: (value: string) => void;
+    /** The first pill, which clears the filter. null leaves it out, for a filter that always has a value. */
+    allLabel?: string | null;
+};
+export declare function PillFilter({ label, options, value, onValueChange, allLabel }: PillFilterProps): import("react").JSX.Element;

package/dist/components/app/pill-filter.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// One quick filter as pills above a table's rows (All / Video / Audio /
+// Text), for a filter with few values that switching between is the main
+// thing people do; a dropdown hides the choices behind a click. One pill
+// is pressed at a time, and pressing the pressed one again leaves it so:
+// "All" is how the filter comes off.
+//
+// Holds no state: the app passes the value it keeps in the URL like any
+// filter (useTableUrlState's `filters.<name>`, '' for All) and sets it
+// with `setFilter`. Built on shadcn's ToggleGroup (Base UI): a group named
+// by `label`, one tab stop, the arrow keys along it, each pill a toggle
+// button with aria-pressed.
+import { ToggleGroup, ToggleGroupItem } from '../ui/toggle-group.js';
+// The All pill's value inside the group: Base UI's toggles need one that
+// isn't empty, and '' is what the app's filter calls All.
+const ALL = '__all__';
+// Pressed is filled with the primary colour: the toggle's own pressed tint
+// (bg-muted) is ~3% off the page, too faint to say which one is on.
+const PILL_CLASS = 'rounded-full px-3 aria-pressed:border-primary aria-pressed:bg-primary aria-pressed:text-primary-foreground ' +
+    'aria-pressed:hover:bg-primary/90 aria-pressed:hover:text-primary-foreground';
+export function PillFilter({ label, options, value, onValueChange, allLabel = 'All' }) {
+    const pills = allLabel === null ? options : [{ value: ALL, label: allLabel }, ...options];
+    const pressed = value === '' && allLabel !== null ? ALL : value;
+    return (_jsx(ToggleGroup, { "aria-label": label, variant: "outline", size: "sm", spacing: 1, className: "flex-wrap", value: [pressed], onValueChange: (next) => {
+            // [] is the pressed pill pressed again: it stays on.
+            const chosen = next[0];
+            if (chosen === undefined || chosen === pressed)
+                return;
+            onValueChange(chosen === ALL ? '' : chosen);
+        }, children: pills.map((option) => (_jsx(ToggleGroupItem, { value: option.value, className: PILL_CLASS, children: option.label }, option.value))) }));
+}

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

@@ -0,0 +1,9 @@
+/** The group a row belongs to: `key` tells groups apart, `label` is the heading. */
+export type RowGroup = {
+    key: string;
+    label: string;
+};
+export type GroupRun<T> = RowGroup & {
+    rows: T[];
+};
+export declare function groupRuns<T>(rows: readonly T[], groupOf: (row: T) => RowGroup): GroupRun<T>[];

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

@@ -0,0 +1,18 @@
+// DataTable's grouped rows (`groupBy`), kept free of React so tests/ can
+// unit-test it. Rows stay in the order the server sent them; a new group
+// starts wherever the key changes, so a key that comes back later (the
+// server sorted by something else) gets a second heading rather than rows
+// moved out of order. Groups come from the rows alone, so a group with no
+// rows on this page never exists.
+export function groupRuns(rows, groupOf) {
+    const runs = [];
+    for (const row of rows) {
+        const { key, label } = groupOf(row);
+        const last = runs.at(-1);
+        if (last && last.key === key)
+            last.rows.push(row);
+        else
+            runs.push({ key, label, rows: [row] });
+    }
+    return runs;
+}

package/dist/components/ui/toggle-group.d.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import { ToggleGroup as ToggleGroupPrimitive } from "@base-ui/react/toggle-group";
+import { type VariantProps } from "class-variance-authority";
+import { toggleVariants } from "./toggle.js";
+declare function ToggleGroup({ className, variant, size, spacing, orientation, children, ...props }: ToggleGroupPrimitive.Props & VariantProps<typeof toggleVariants> & {
+    spacing?: number;
+    orientation?: "horizontal" | "vertical";
+}): React.JSX.Element;
+declare function ToggleGroupItem({ className, children, variant, size, ...props }: TogglePrimitive.Props & VariantProps<typeof toggleVariants>): React.JSX.Element;
+export { ToggleGroup, ToggleGroupItem };

package/dist/components/ui/toggle-group.js

@@ -0,0 +1,25 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import { ToggleGroup as ToggleGroupPrimitive } from "@base-ui/react/toggle-group";
+import {} from "class-variance-authority";
+import { cn } from "cn";
+import { toggleVariants } from "./toggle.js";
+const ToggleGroupContext = React.createContext({
+    size: "default",
+    variant: "default",
+    spacing: 2,
+    orientation: "horizontal",
+});
+function ToggleGroup({ className, variant, size, spacing = 2, orientation = "horizontal", children, ...props }) {
+    return (_jsx(ToggleGroupPrimitive, { "data-slot": "toggle-group", "data-variant": variant, "data-size": size, "data-spacing": spacing, "data-orientation": orientation, style: { "--gap": spacing }, className: cn("group/toggle-group flex w-fit flex-row items-center gap-[--spacing(var(--gap))] rounded-lg data-[size=sm]:rounded-[min(var(--radius-md),10px)] data-vertical:flex-col data-vertical:items-stretch", className), ...props, children: _jsx(ToggleGroupContext.Provider, { value: { variant, size, spacing, orientation }, children: children }) }));
+}
+function ToggleGroupItem({ className, children, variant = "default", size = "default", ...props }) {
+    const context = React.useContext(ToggleGroupContext);
+    return (_jsx(TogglePrimitive, { "data-slot": "toggle-group-item", "data-variant": context.variant || variant, "data-size": context.size || size, "data-spacing": context.spacing, className: cn("shrink-0 group-data-[spacing=0]/toggle-group:rounded-none group-data-[spacing=0]/toggle-group:px-2 focus:z-10 focus-visible:z-10 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-end]:pr-1.5 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-start]:pl-1.5 group-data-horizontal/toggle-group:data-[spacing=0]:first:rounded-l-lg group-data-vertical/toggle-group:data-[spacing=0]:first:rounded-t-lg group-data-horizontal/toggle-group:data-[spacing=0]:last:rounded-r-lg group-data-vertical/toggle-group:data-[spacing=0]:last:rounded-b-lg group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:border-l-0 group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:border-t-0 group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-l group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-t", toggleVariants({
+            variant: context.variant || variant,
+            size: context.size || size,
+        }), className), ...props, children: children }));
+}
+export { ToggleGroup, ToggleGroupItem };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { AppShell, type AppShellProps, type AppShellVersion, type NavEntry, type NavItem, type NavSection } from './components/app/app-shell.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableProps, 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 { 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 EditListItemProps, } from './components/app/edit-in-place.js';
@@ -17,6 +19,7 @@ export { ListEditor } from './components/app/list-editor.js';
 export { PasswordInput } from './components/app/password-input.js';
 export { RichTextEditor, type RichTextEditorProps } from './components/app/rich-text-editor.js';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
+export { PillFilter, type PillFilterOption, type PillFilterProps } from './components/app/pill-filter.js';
 export { SecondaryFilters, type ActiveFilter, type SecondaryFiltersProps } from './components/app/secondary-filters.js';
 export { StageCircle, type StageCircleProps, type StageCircleStage, type StageCircleTone, } from './components/app/stage-circle.js';
 export { WidgetCard, WidgetList, WidgetListItem, type WidgetCardProps, type WidgetListItemProps, } from './components/app/widget-card.js';

package/dist/index.js

@@ -6,6 +6,8 @@
 export { AppShell } from './components/app/app-shell.js';
 export { CountLink } from './components/app/count-link.js';
 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 { EntityView, } from './components/app/entity-view.js';
 export { editInPlace, } from './components/app/edit-in-place.js';
@@ -22,6 +24,7 @@ export { ListEditor } from './components/app/list-editor.js';
 export { PasswordInput } from './components/app/password-input.js';
 export { RichTextEditor } from './components/app/rich-text-editor.js';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
+export { PillFilter } from './components/app/pill-filter.js';
 export { SecondaryFilters } from './components/app/secondary-filters.js';
 export { StageCircle, } from './components/app/stage-circle.js';
 export { WidgetCard, WidgetList, WidgetListItem, } from './components/app/widget-card.js';

package/dist/lib/group-by-day.d.ts

@@ -0,0 +1,14 @@
+import type { RowGroup } from '../components/app/table-groups.js';
+export type ByDayOptions = {
+    /** What "today" is. Defaults to when byDay is called: pass it to pin a test. */
+    now?: Date;
+    /** The IANA zone whose calendar days count, e.g. "Europe/London". Defaults to the browser's. */
+    timeZone?: string;
+    /** 1 (Monday, the default) or 0 (Sunday). */
+    weekStartsOn?: 0 | 1;
+    /** The locale week and month names are written in. Defaults to "en-GB": "Week of 6 Oct". */
+    locale?: string;
+};
+type DateValue = string | number | Date | null | undefined;
+export declare function byDay<TData>(field: keyof TData | ((row: TData) => DateValue), { now, timeZone, weekStartsOn, locale }?: ByDayOptions): (row: TData) => RowGroup;
+export {};

package/dist/lib/group-by-day.js

@@ -0,0 +1,47 @@
+const DAY_MS = 86_400_000;
+const WEEKS_BY_WEEK = 4;
+export function byDay(field, { now = new Date(), timeZone, weekStartsOn = 1, locale = 'en-GB' } = {}) {
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        year: 'numeric',
+        month: 'numeric',
+        day: 'numeric',
+    });
+    // The calendar day `date` falls on in the zone, as days since 1970-01-01.
+    const dayOf = (date) => {
+        const part = (type) => Number(parts.formatToParts(date).find((p) => p.type === type)?.value);
+        return Date.UTC(part('year'), part('month') - 1, part('day')) / DAY_MS;
+    };
+    // Day numbers are UTC midnights, so they're formatted in UTC.
+    const dayMonth = new Intl.DateTimeFormat(locale, { day: 'numeric', month: 'short', timeZone: 'UTC' });
+    const month = new Intl.DateTimeFormat(locale, { month: 'long', timeZone: 'UTC' });
+    const monthYear = new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric', timeZone: 'UTC' });
+    const weekStart = (day) => day - ((new Date(day * DAY_MS).getUTCDay() - weekStartsOn + 7) % 7);
+    const isoDay = (day) => new Date(day * DAY_MS).toISOString().slice(0, 10);
+    const today = dayOf(now);
+    const thisWeek = weekStart(today);
+    const thisYear = new Date(today * DAY_MS).getUTCFullYear();
+    const read = typeof field === 'function' ? field : (row) => row[field];
+    return (row) => {
+        const value = read(row);
+        const date = value === null || value === undefined || value === '' ? null : new Date(value);
+        if (date === null || Number.isNaN(date.getTime()))
+            return { key: 'none', label: 'No date' };
+        const day = dayOf(date);
+        if (day > today)
+            return { key: 'upcoming', label: 'Upcoming' };
+        if (day === today)
+            return { key: 'today', label: 'Today' };
+        if (day === today - 1)
+            return { key: 'yesterday', label: 'Yesterday' };
+        if (day >= thisWeek)
+            return { key: 'this-week', label: 'Earlier this week' };
+        const week = weekStart(day);
+        if (week >= thisWeek - WEEKS_BY_WEEK * 7) {
+            return { key: `week:${isoDay(week)}`, label: `Week of ${dayMonth.format(new Date(week * DAY_MS))}` };
+        }
+        const first = new Date(day * DAY_MS);
+        const label = (first.getUTCFullYear() === thisYear ? month : monthYear).format(first);
+        return { key: `month:${isoDay(day).slice(0, 7)}`, label };
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.6.0",
+  "version": "4.8.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": {