@tristan2828/ui-foundation 3.10.0 → 3.11.0

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

@@ -353,6 +353,12 @@ is a filled-in example while the Widgets demo is still here).
 
 ## What not to copy
 
+- The saved-views row in `widgets-table.tsx` (`VIEWS`, the "Saved views"
+  button group and `visibleColumns`) unless the plan's List screen lists
+  saved views. When it does, copy it: `useTableUrlState`'s third argument
+  takes the views, `activeView` says which one the filters are, and that
+  view's `columns` go to `DataTable`'s `visibleColumns` (the table's own
+  default list when no view is active, or `undefined` for every column).
 - `src/api/gateway/widgets.ts`, `src/mocks/data.ts`, `src/mocks/handlers.ts`
   are demo-domain content — write the entity's own versions rather than
   adapting these by find-and-replace.

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

@@ -92,6 +92,19 @@ per list; delete the section if there are none.
 
 - Default sort:
 - Page size: 10 unless there's a reason.
+- Saved views (optional; delete if none): one row per view, a button
+  above the filters that sets every filter and the sort in one press.
+  Columns: blank for the table's usual columns, or the exact columns the
+  view shows, for a view of one kind of record that shows a field only
+  that kind uses. The columns last while the view's filters do; any other
+  filter puts the usual columns back. If the usual columns should leave
+  out a field only a view shows, say so here.
+
+| View | Filters | Sort | Columns |
+|---|---|---|---|
+| All tasks | none | dueDate asc | |
+| Bugs | kind = bug | dueDate asc | title, severity, assignee, dueDate |
+
 - Anything else the table must show or do:
 
 ## View screen

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

@@ -52,5 +52,13 @@ export type DataTableProps<TData extends Record<string, unknown>> = {
      * unaffected. See conventions/docs/entity-plan-template.md "Default sort".
      */
     enableSortingRemoval?: boolean;
+    /**
+     * The ids of the columns to show; the rest are hidden. They keep their
+     * order in `columns`. Leave undefined to show every column. A table
+     * with saved views passes the active view's `columns`
+     * (useTableUrlState's `activeView`), or its own default list when no
+     * view is active, which can leave out a column only one view shows.
+     */
+    visibleColumns?: readonly string[];
 };
-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, }: 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, }: DataTableProps<TData>): import("react").JSX.Element;

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

@@ -20,6 +20,20 @@ import { Button } from '../ui/button.js';
 import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from '../ui/empty.js';
 import { Skeleton } from '../ui/skeleton.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
+// columns are looked through to their leaves, which visibility is keyed by.
+function leafColumnIds(columns) {
+    return columns.flatMap((column) => {
+        if ('columns' in column && column.columns)
+            return leafColumnIds(column.columns);
+        const accessorKey = 'accessorKey' in column ? column.accessorKey : undefined;
+        const id = column.id ??
+            (accessorKey === undefined ? undefined : String(accessorKey).replaceAll('.', '_')) ??
+            (typeof column.header === 'string' ? column.header : undefined);
+        return id === undefined ? [] : [id];
+    });
+}
 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))) }));
 }
@@ -109,8 +123,13 @@ 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, }) {
+export function DataTable({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, }) {
     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)]))
+        : {};
     const table = useLegacyTable({
         data,
         columns,
@@ -118,6 +137,7 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
         state: {
             sorting,
             pagination: { pageIndex: page - 1, pageSize },
+            columnVisibility,
         },
         manualSorting: true,
         ...(enableSortingRemoval === undefined ? {} : { enableSortingRemoval }),
@@ -143,7 +163,7 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     const isSuccessView = !error && !isLoading && !isPastLastPage && !isEmpty;
     const containerRef = useRef(null);
     const { barRef, isOverflowing, scrollWidth } = useBottomScrollbar(containerRef, Boolean(pinFirstColumn) && isSuccessView);
-    return (_jsxs("div", { className: "flex flex-col gap-4", children: [toolbar, error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (_jsx(TableSkeleton, { columnCount: columns.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, 
+    return (_jsxs("div", { className: "flex flex-col gap-4", 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, 
                         // 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

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

@@ -7,8 +7,15 @@ export type TableView<F extends string, M extends string> = {
     filters?: Partial<Record<F, string>>;
     multiFilters?: Partial<Record<M, string[]>>;
     sort?: Sort;
+    /**
+     * The ids of the columns this view shows, for DataTable's
+     * `visibleColumns`. Leave it out to show the table's default columns.
+     * Applies only while the view is active (see activeViewOf).
+     */
+    columns?: readonly string[];
 };
 export declare function serializeSort(next: Sort): string | null;
 export declare function applyUrlChanges(previous: URLSearchParams, changes: UrlChanges): URLSearchParams;
 export declare function viewToUrlChanges<F extends string, M extends string>(filterNames: readonly F[], multiFilterNames: readonly M[], view: TableView<F, M>): UrlChanges;
+export declare function activeViewOf<F extends string, M extends string, V extends string>(views: Readonly<Record<V, TableView<F, M>>>, filters: Readonly<Record<F, string>>, multiFilters: Readonly<Record<M, readonly string[]>>): V | null;
 export {};

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

@@ -30,3 +30,17 @@ export function viewToUrlChanges(filterNames, multiFilterNames, view) {
         page: null,
     };
 }
+// Which of `views` the current filters are: the first whose filters and
+// multi filters equal the URL's exactly (multi filters in any order), or
+// null. A view is active only while it is still "this combination and
+// nothing else", so adding or changing any filter returns the table to its
+// default columns: a view's columns are chosen for the records its filters
+// select, and would hide a field those other records fill. Sort and page
+// don't change which records are shown, so they don't count. Decided with
+// the developer on 2026-10-05.
+export function activeViewOf(views, filters, multiFilters) {
+    const sameItems = (a, b) => a.length === b.length && [...a].sort().every((item, index) => item === [...b].sort()[index]);
+    const matches = (view) => Object.keys(filters).every((name) => filters[name] === (view.filters?.[name] ?? '')) &&
+        Object.keys(multiFilters).every((name) => sameItems(multiFilters[name], view.multiFilters?.[name] ?? []));
+    return Object.keys(views).find((id) => matches(views[id])) ?? null;
+}

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

@@ -1,10 +1,11 @@
 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>(filterNames: readonly F[], multiFilterNames?: readonly M[]): {
+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>>>>): {
     page: number;
     sorting: SortingState;
     filters: Record<F, string>;
     multiFilters: Record<M, string[]>;
+    activeView: V | null;
     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,5 @@
 import { useSearchParams } from 'react-router';
-import { applyUrlChanges, serializeSort, viewToUrlChanges } from './table-url-changes.js';
+import { activeViewOf, applyUrlChanges, serializeSort, viewToUrlChanges, } from './table-url-changes.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
@@ -10,14 +10,20 @@ import { applyUrlChanges, serializeSort, viewToUrlChanges } from './table-url-ch
 // (multi-choice fields) are string arrays, repeated in the URL the same way
 // the API takes them. Changing the sort or any filter returns to page 1.
 //
+// `views` are the table's saved views, by id. `activeView` is the id of the
+// one the current filters are, or null (activeViewOf() says when a view
+// counts as active); pass that view's `columns` to DataTable. A view is
+// pressed with applyView().
+//
 // Every setter is one update(), and must stay one: see setFilters.
-export function useTableUrlState(filterNames, multiFilterNames = []) {
+export function useTableUrlState(filterNames, multiFilterNames = [], views = {}) {
     const [params, setParams] = useSearchParams();
     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' }] : [];
     const filters = Object.fromEntries(filterNames.map((name) => [name, params.get(name) ?? '']));
     const multiFilters = Object.fromEntries(multiFilterNames.map((name) => [name, params.getAll(name)]));
+    const activeView = activeViewOf(views, filters, multiFilters);
     function update(changes) {
         setParams((previous) => applyUrlChanges(previous, changes), { replace: true });
     }
@@ -26,6 +32,7 @@ export function useTableUrlState(filterNames, multiFilterNames = []) {
         sorting,
         filters,
         multiFilters,
+        activeView,
         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 }),

package/package.json

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