@tristan2828/ui-foundation 3.21.0 → 3.23.0

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

@@ -189,7 +189,12 @@ is a filled-in example while the Widgets demo is still here).
    - `src/routes/widgets/widgets-table.tsx` →
      `src/routes/<entity>/<entity>-table.tsx` — thin consumer of the
      foundation's `<DataTable>`. Swap the type, columns, and toolbar
-     filters.
+     filters. More than three filters (search, saved views aside): keep
+     the most used in the toolbar and put the rest inside
+     `<SecondaryFilters>`, as the template does with Extra Categories,
+     Progress and In Stock. Pass it each filter that's on as an
+     `ActiveFilter` (its chip text and how to take it off) and an
+     `onClear` that clears them all in one `setFilters` call.
    - `src/routes/widgets/widget-view.tsx` →
      `src/routes/<entity>/<entity>-view.tsx` — thin consumer of the
      foundation's `<EntityView>`. Swap the title, badges and sections for

package/conventions/docs/cell-patterns.md

@@ -10,14 +10,14 @@ alternatives ([`column-options.md`](column-options.md)), not designed in the abs
 Patterns 12 (boolean), 15 (yes/no flipped in the row), 16 (title linking
 to its view), 17 (quick action on the view) and 18 (editable value) are
 the template's own references: Widget's In Stock and Name columns and its
-view render them, and their specs pin them. Pattern 19 (stage circle)
-and the multi-value variant of 4, the dependency list in 10 and the
-pressed icon in 15 were each built for a real app's screen first; the
-package's Storybook renders them (`app/StageCircle`,
-`patterns/CellPatterns`), and its checks pin their accessibility and
-contrast in both themes. The other patterns from 11 on are
-marked **Unproven**: written ahead of a real
-column, so no app has tested them on real data yet. Prefer a proven
+view render them, and their specs pin them. Patterns 19 (stage circle)
+and 20 (count linking to the related records), the multi-value variant
+of 4, the dependency list in 10 and the pressed icon in 15 were each
+built for a real app's screen first; the package's Storybook renders
+them (`app/StageCircle`, `app/CountLink`, `patterns/CellPatterns`), and
+its checks pin their accessibility and contrast in both themes. The
+other patterns from 11 on are marked **Unproven**: written ahead of a
+real column, so no app has tested them on real data yet. Prefer a proven
 pattern when one fits. When you use an unproven one, say so in the
 entity's plan, and raise what you learned for the foundation, so the
 entry can lose its label. A pattern that proves generic is worth raising
@@ -836,3 +836,69 @@ cell: ({ getValue }) => {
   `<EditableValue>` like a badge.
 - **Cost:** a reader learns the shapes once. Until then the word does the
   work, which is why it stays.
+
+## 20. Count linking to the related records
+
+A count of the records in another table that point at this row (open
+Tasks per Project, items per Tag), which opens that table already filtered
+to them. The count is a `computed` integer (the entity plan's type).
+The package ships it: `CountLink`, rendered in its Storybook
+(`app/CountLink`).
+
+```tsx
+import { CountLink } from '@tristan2828/ui-foundation'
+
+cell: ({ row }) => {
+  const { id, name, openTaskCount: count } = row.original
+  return (
+    <CountLink
+      count={count}
+      to={`/tasks?project=${id}`}
+      label={`open ${count === 1 ? 'task' : 'tasks'} in ${name}`}
+    />
+  )
+}
+```
+
+What the component decides, so a cell doesn't have to:
+
+- **Underlined at rest**, not only on hover as in pattern 16. A title
+  reads as a name to open; a bare number doesn't look like it goes
+  anywhere until it's underlined. Hover thickens the line. Foreground,
+  not `text-link`: `--link` is for links in written text, and a column of
+  blue numbers pulls the eye from every other column.
+- **Zero is a plain `0`**, not a link (a link to an empty list is a dead
+  end) and not an em dash: zero is a value (pattern 11). Same
+  `tabular-nums`, so it lines up with the links.
+- **The accessible name is the count, then `label`**: `3 open tasks in
+  Kitchen remodel`. Every row's link text is just a number, so `3` alone
+  isn't distinct, and starting with it keeps the link findable by what
+  it shows (speech input, `getByRole('link', { name: /^3 / })`).
+
+What the cell decides:
+
+- **`label` says what's counted and which row**, singular for one
+  (`open task in Garden`).
+- **The target is the other entity's list, filtered by the URL**:
+  `/<other>?<filterName>=<id>`, the same query string `useTableUrlState`
+  reads (a multi-value filter takes the id the same way). Back, forward,
+  a refresh and saved views keep working, and the other list needs a
+  filter by this reference (`Filter: yes` in its plan).
+- **The count and the list it opens must agree.** If the target list
+  narrows by default (hides finished records unless asked), the count
+  applies the same condition, and the word in the name says so (`open`
+  tasks). Where the list has a filter for that condition, prefer putting
+  it in the link too (`?project=7&status=open`), so the list shows what
+  was counted even if its default changes. Say the rule in the field's
+  `description` in `openapi.yaml` (`Tasks in this project that aren't
+  done; what /tasks?project=<id> lists`), so the backend, the mocks and
+  the next agent count the same thing.
+- **Sorted on the server, as a number**, like any computed field: the
+  scalar subquery is the sort expression, with a stable tiebreak (the
+  name, then the id) so rows with the same count don't change places
+  between pages.
+- **Cost:** one correlated subquery per row read. Fine at an app's scale;
+  give the other table's foreign key column an index, since every row's
+  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.

package/conventions/docs/design-language.md

@@ -194,6 +194,10 @@ shade: note `info`, tip `success`, important category slot 2, warning
 `warning`, caution `destructive`. The package draws all of it; an app
 only renders `<Markdown>` or the editor.
 
+`--link` is for written text only. A link in a table cell is
+`text-foreground` and underlined, never blue: a column of coloured text
+pulls the eye from every other column (cell patterns 16 and 20).
+
 ## Density
 
 Tables have three densities, set with `data-density` on **any ancestor**

package/conventions/docs/entity-plan-template.md

@@ -43,7 +43,8 @@ One or two sentences: what one record is, and who uses the screens.
     every read and never stores it — give its rule, and if it's a choice,
     its values in sort order with a label for each; a read-only column, a filter and a sort the
     server evaluates, never on the form). A count of related records is a
-    `computed` integer.
+    `computed` integer; say whether its column links to those records
+    (cell pattern 20) and which of them it counts (`open tasks`).
   - *Close variants* (built by a small, stated change to the nearest
     pattern): `integer` (from decimal), `url` (from email — a format
     check), `date` (from date-time — no time part).

package/dist/components/app/count-link.d.ts

@@ -0,0 +1,14 @@
+import { type To } from 'react-router';
+export interface CountLinkProps {
+    /** How many related records there are. Count what `to` lists. */
+    count: number;
+    /** The other entity's list, filtered to this row: `/tasks?project=7`. */
+    to: To;
+    /**
+     * What's counted and for which row, read after the count: `open tasks in
+     * Kitchen remodel` (`open task` for one).
+     */
+    label: string;
+    className?: string;
+}
+export declare function CountLink({ count, to, label, className }: CountLinkProps): import("react").JSX.Element;

package/dist/components/app/count-link.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// A count linking to the related records (cell pattern 20): how many
+// records of another entity point at this row, as a link to that entity's
+// list filtered to them (`/tasks?project=7`, the query string
+// useTableUrlState reads).
+//
+// - Underlined at rest: a bare number doesn't look like it goes anywhere.
+//   Foreground, not text-link: --link is for written text.
+// - Zero is a plain 0, not a link (a list of nothing is a dead end) and
+//   not an em dash (zero is a value).
+// - The accessible name is the count, then `label`, so every row's link is
+//   distinct ("3 open tasks in Kitchen remodel") and still starts with
+//   what it shows.
+import { Link } from 'react-router';
+import { cn } from 'cn';
+export function CountLink({ count, to, label, className }) {
+    if (count === 0)
+        return _jsx("span", { className: cn('tabular-nums', className), children: "0" });
+    return (_jsx(Link, { to: to, "aria-label": `${count} ${label}`, className: cn('rounded-sm tabular-nums text-foreground underline underline-offset-4 outline-none', 'hover:decoration-2 focus-visible:ring-3 focus-visible:ring-ring/50', className), children: count }));
+}

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

@@ -37,20 +37,27 @@ function leafColumnIds(columns) {
 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))) }));
 }
-// The pinned cell gets a flat `bg-background`, not `bg-inherit`: the zebra
+// The pinned cell gets an opaque background, not `bg-inherit`: the zebra
 // stripe (table.tsx) is a *translucent* color, so inheriting it would let
 // the columns scrolling behind show through at 40% opacity — exactly the
-// bleed-through a solid background avoids. That also means the pinned
-// column shows no stripe, which is why it is the thing that carries the
-// hover highlight. --accent is only ~3% off the page background, so a
-// solid left edge marker carries the signal; an inset shadow rather than a
-// border, so nothing reflows.
-const PINNED_COLUMN_CLASS = 'sticky left-0 z-10 border-r bg-background group-hover/row:bg-accent ' +
-    'group-hover/row:shadow-[inset_3px_0_0_0_var(--primary)]';
+// bleed-through a solid background avoids. On an even row it's the stripe
+// pre-mixed onto the page (--table-stripe), so the stripe runs the whole
+// row's width (issue #92); `:where()` keeps that rule's specificity at the
+// background's, so the hover below still wins on every row. The pinned
+// cell carries the hover highlight. --accent is only ~3% off the page
+// background, so a solid left edge marker carries the signal; an inset
+// shadow rather than a border, so nothing reflows.
+const PINNED_CELL_CLASS = 'z-10 bg-background [:where(tbody>tr:nth-child(even))>&]:bg-(--table-stripe) group-hover/row:bg-accent';
+const PINNED_COLUMN_CLASS = `sticky left-0 border-r ${PINNED_CELL_CLASS} group-hover/row:shadow-[inset_3px_0_0_0_var(--primary)]`;
 // The right-edge mirror, opaque for the same reason. Its edge marker points
 // inward from the right, so the two pinned columns bracket the row.
-const PINNED_LAST_COLUMN_CLASS = 'sticky right-0 z-10 border-l bg-background group-hover/row:bg-accent ' +
-    'group-hover/row:shadow-[inset_-3px_0_0_0_var(--primary)]';
+const PINNED_LAST_COLUMN_CLASS = `sticky right-0 border-l ${PINNED_CELL_CLASS} group-hover/row:shadow-[inset_-3px_0_0_0_var(--primary)]`;
+// A pinned first column's content, capped below md at 45% of the table's
+// scroll area (`cqw`: the container is an inline-size query container)
+// and wrapping, so a long title can't widen the column past the screen
+// and leave every other column scrolling underneath it (issue #91).
+// Wider screens are unchanged: the column sizes to its content.
+const PINNED_FIRST_CONTENT_CLASS = 'max-md:max-w-[45cqw] max-md:whitespace-normal max-md:break-words';
 // Hover highlights the pinned cell, not the whole row. A row-level hover
 // cannot be made consistent against the zebra stripe: `tr:nth-child(even)`
 // is specificity (0,2,1) and `tr:hover` is (0,2,0), so the stripe wins and
@@ -169,9 +176,10 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                         // scrollable (wheel, trackpad, drag, and the sync effect); it
                         // just no longer draws a bar directly under the last row.
                         containerClassName: cn(pinFirstColumn &&
-                            '[scrollbar-width:none] [&::-webkit-scrollbar]:hidden'), children: [_jsx(TableHeader, { children: table.getHeaderGroups().map((headerGroup) => (_jsx(TableRow, { children: headerGroup.headers.map((header, index) => {
+                            '@container [scrollbar-width:none] [&::-webkit-scrollbar]:hidden'), children: [_jsx(TableHeader, { 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 &&
                                                 index === headerGroup.headers.length - 1 &&
                                                 PINNED_LAST_COLUMN_CLASS, header.column.columnDef.meta?.align === 'center' && 'text-center'), "aria-sort": !canSort
@@ -180,8 +188,8 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                                                     ? 'ascending'
                                                     : sortDirection === 'desc'
                                                         ? 'descending'
-                                                        : 'none', children: 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())) }, header.id));
+                                                        : '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 || pinLastColumn) && 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: 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, {}) })] })] })] }))] }));
+                                            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, {}) })] })] })] }))] }));
 }

package/dist/components/app/secondary-filters.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+/** A filter that's on: its chip's text ("In stock: No") and how to take it off. */
+export type ActiveFilter = {
+    id: string;
+    label: string;
+    onRemove: () => void;
+};
+export type SecondaryFiltersProps = {
+    /** The filter controls the button opens, each with its own label. */
+    children: ReactNode;
+    /** The filters among them that are on now, in the order their chips show. */
+    active: readonly ActiveFilter[];
+    /** Takes every one of them off at once. */
+    onClear: () => void;
+    /** The button's text. */
+    label?: string;
+};
+export declare function SecondaryFilters({ children, active, onClear, label }: SecondaryFiltersProps): import("react").JSX.Element;

package/dist/components/app/secondary-filters.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A table toolbar's less-used filters behind one "Filters" button, so a
+// table with many filters still starts near the top of the page (issue
+// #93). The primary filters (search, status, whatever most visits use)
+// stay in the toolbar; this goes beside them, holding the rest:
+//
+// - The button says how many of its filters are on ("Filters 2", named
+//   "Filters, 2 active"), and opens them in a popover, or a sheet from the
+//   bottom on a phone. Base UI gives focus back to the button on close.
+// - Each filter that's on shows beside the button as a chip with a remove
+//   button, so a filtered list never looks unfiltered while they're
+//   hidden; "Clear filters" takes them all off. Both are here too, in the
+//   panel's footer.
+// - It holds no state of its own: the app passes what's on (`active`, from
+//   the URL like every filter, useTableUrlState), so the count and chips
+//   follow back/forward and saved views. Collapsing is display only.
+// - Esc in a filter's open list closes the list only (Base UI's lists keep
+//   their Esc); the next one closes the panel.
+import { useState } from 'react';
+import { SlidersHorizontalIcon, XIcon } from 'lucide-react';
+import { Button } from '../ui/button.js';
+import { Popover, PopoverContent, PopoverTitle, PopoverTrigger } from '../ui/popover.js';
+import { Sheet, SheetContent, SheetFooter, SheetHeader, SheetTitle, SheetTrigger } from '../ui/sheet.js';
+import { useIsMobile } from '../../hooks/use-mobile.js';
+export function SecondaryFilters({ children, active, onClear, label = 'Filters' }) {
+    const isMobile = useIsMobile();
+    const [open, setOpen] = useState(false);
+    const count = active.length;
+    const trigger = (_jsxs(Button, { variant: "outline", "aria-label": count > 0 ? `${label}, ${count} active` : label, children: [_jsx(SlidersHorizontalIcon, { "aria-hidden": "true" }), label, count > 0 && (_jsx("span", { "aria-hidden": "true", className: "rounded-full bg-primary px-1.5 type-caption text-primary-foreground tabular-nums", children: count }))] }));
+    const footer = (_jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "ghost", size: "sm", disabled: count === 0, onClick: onClear, children: "Clear filters" }), _jsx(Button, { size: "sm", onClick: () => setOpen(false), children: "Done" })] }));
+    return (_jsxs("div", { "data-slot": "secondary-filters", className: "flex flex-wrap items-center gap-2", children: [isMobile ? (_jsxs(Sheet, { open: open, onOpenChange: setOpen, children: [_jsx(SheetTrigger, { render: trigger }), _jsxs(SheetContent, { side: "bottom", className: "max-h-[85svh] overflow-y-auto", children: [_jsx(SheetHeader, { children: _jsx(SheetTitle, { children: label }) }), _jsx("div", { className: "flex flex-col gap-3 px-4 [&>*]:w-full", children: children }), _jsx(SheetFooter, { children: footer })] })] })) : (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { render: trigger }), _jsxs(PopoverContent, { align: "start", className: "w-auto min-w-64 gap-3 p-3", children: [_jsx(PopoverTitle, { children: label }), _jsx("div", { className: "flex flex-col gap-3", children: children }), footer] })] })), active.map((filter) => (_jsxs("span", { "data-slot": "secondary-filter-chip", className: "inline-flex h-7 items-center gap-0.5 rounded-md bg-muted pr-0.5 pl-2 type-caption text-foreground", children: [filter.label, _jsx(Button, { variant: "ghost", size: "icon-xs", "aria-label": `Remove filter: ${filter.label}`, onClick: filter.onRemove, children: _jsx(XIcon, { "aria-hidden": "true" }) })] }, filter.id))), count > 1 && (_jsx(Button, { variant: "ghost", size: "sm", onClick: onClear, children: "Clear filters" }))] }));
+}

package/dist/components/ui/combobox.js

@@ -53,8 +53,14 @@ function ComboboxChip({ className, children, showRemove = true, ...props }) {
             // it after the chip ("Remove fragile") when the chip is plain text.
             , { "aria-label": typeof children === "string" ? `Remove ${children}` : "Remove", render: _jsx(Button, { variant: "ghost", size: "icon-xs" }), className: "-ml-1 opacity-50 hover:opacity-100", "data-slot": "combobox-chip-remove", children: _jsx(XIcon, { className: "pointer-events-none" }) }))] }));
 }
+// Patched (ui-foundation, issue #94): upstream's input always keeps 4rem,
+// so chips that fit on one line still pushed it onto an empty second one
+// and the control stood twice as tall as a Select beside it. With chips
+// in and no focus it takes only what's left of the chips' line (none, if
+// they fill it); focused, it gets its 4rem back to type in, wrapping then
+// if the line is full.
 function ComboboxChipsInput({ className, ...props }) {
-    return (_jsx(ComboboxPrimitive.Input, { "data-slot": "combobox-chip-input", className: cn("min-w-16 flex-1 outline-none", className), ...props }));
+    return (_jsx(ComboboxPrimitive.Input, { "data-slot": "combobox-chip-input", className: cn("min-w-16 flex-1 outline-none [[data-slot=combobox-chips]:has([data-slot=combobox-chip])_&:not(:focus)]:min-w-0", className), ...props }));
 }
 function useComboboxAnchor() {
     return React.useRef(null);

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

@@ -9,7 +9,7 @@ export declare function useTableUrlState<F extends string, M extends string = ne
     setPage: (next: number) => void;
     setSorting: (next: SortingState) => void;
     setFilter: (name: F, value: string) => void;
-    setFilters: (changes: Partial<Record<F, string>>) => void;
+    setFilters: (changes: Partial<Record<F, string>> & Partial<Record<M, string[]>>) => void;
     setMultiFilter: (name: M, values: string[]) => void;
     applyView: (view: TableView<F, M>) => void;
 };

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

@@ -36,11 +36,12 @@ export function useTableUrlState(filterNames, multiFilterNames = [], views = {})
         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 }),
-        // Several single-value filters in one call — for any user action that
-        // changes more than one (both ends of a date range, "clear all"). Two
-        // setFilter()s in the same tick lose all but the last: react-router
-        // hands each setSearchParams updater the params from the last render,
-        // not the ones the previous updater produced.
+        // Several filters in one call — for any user action that changes more
+        // than one (both ends of a date range, "clear filters"). Two setters in
+        // the same tick lose all but the last: react-router hands each
+        // setSearchParams updater the params from the last render, not the
+        // ones the previous updater produced. Single-value filters take a
+        // string ('' clears), multi-value ones a list ([] clears).
         setFilters: (changes) => update({ ...changes, page: null }),
         setMultiFilter: (name, values) => update({ [name]: values, page: null }),
         // Replaces the whole filter + sort state at once — a saved view. See

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { AppShell, type AppShellProps, type NavItem } from './components/app/app-shell.js';
+export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableProps, type SortingState } from './components/app/data-table.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
 export { EntityView, type EntityViewField, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
@@ -15,6 +16,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 { 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 { ThemeProvider } from './components/theme-provider.js';
 export { LoginRoute, type LoginRouteProps } from './routes/login.js';

package/dist/index.js

@@ -4,6 +4,7 @@
 // points (`/gateway`, `/mocks`, `/testing`) so each stays behind its boundary.
 // Composites
 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 { EntityForm } from './components/app/entity-form.js';
 export { EntityView, } from './components/app/entity-view.js';
@@ -20,6 +21,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 { SecondaryFilters } from './components/app/secondary-filters.js';
 export { StageCircle, } from './components/app/stage-circle.js';
 export { ThemeProvider } from './components/theme-provider.js';
 // Screens outside the app shell

package/package.json

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

package/styles/theme.css

@@ -198,6 +198,11 @@
   --category-6: var(--category-6-700);
   --category-7: var(--category-7-700);
   --category-8: var(--category-8-700);
+  /* The zebra stripe (table.tsx: bg-muted/40 on even rows) mixed onto the
+     page, opaque: what a pinned table cell paints on an even row, so it
+     matches the row without letting scrolled columns show through. Mixed
+     in sRGB, as the browser composites the translucent stripe. */
+  --table-stripe: color-mix(in srgb, var(--muted) 40%, var(--background));
   --border: var(--gray-200);
   --input: var(--gray-200);
   --ring: var(--gray-400);
@@ -269,6 +274,7 @@
   --category-6: var(--category-6-400);
   --category-7: var(--category-7-400);
   --category-8: var(--category-8-400);
+  --table-stripe: color-mix(in srgb, var(--muted) 40%, var(--background));
   --border: var(--white-a10);
   --input: var(--white-a15);
   --ring: var(--gray-500);