basalt-ui 1.24.0 → 1.25.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.25.0](https://github.com/jkrumm/basalt-ui/compare/v1.24.0...v1.25.0) (2026-08-22)
+
+
+### Features
+
+* make manualPagination refuse every prop that would misreport ([d18e5f1](https://github.com/jkrumm/basalt-ui/commit/d18e5f1d8091af82a589a140ece7484cca654084))
+
 # [1.24.0](https://github.com/jkrumm/basalt-ui/compare/v1.23.1...v1.24.0) (2026-08-22)
 
 

package/MIGRATING.md

@@ -85,7 +85,7 @@ New: `maxHeight`, `minWidth`, `stickyHeader`, `stickyHeaderOffset`, `verticalSpa
 defaults to `true` in basalt, overriding Mantine's `false`; every other one is a conditional
 pass-through, so omitting it keeps Mantine's default.
 
-**Porting argo's three tables onto them made them 341 → 370 lines. 29 LONGER.** argo named these
+**Porting argo's three tables onto them made them 341 → 370–379 lines. 29–38 LONGER.** argo named these
 props as the reason the tables stayed hand-rolled, and adding them shortened nothing: column defs
 cost more than JSX rows when every cell is bespoke — eight accessor blocks at 4–6 lines each against
 an eight-`<Table.Td>` row at ~3. **The ask was mis-specified.** Adopt them for what they buy —

package/README.md

@@ -625,7 +625,7 @@ const columns = [
 - `emptyState` renders inside a `<td colSpan>`, so the header row survives an empty table. There is
   no mode that replaces the whole table.
 
-**Honest result:** porting argo's three tables onto these props made them 341 → **370** lines, 29
+**Honest result:** porting argo's three tables onto these props made them 341 → **370–379** lines, 29–38
 longer. Column defs cost more than JSX rows when every cell is bespoke. Adopt the props for what
 they actually buy — the `type="native"` footgun, alignment stated once instead of on both `th` and
 `td`, and sorting/filtering/pagination owned by basalt — not for a line count.

package/agent/rules/basalt-data.md

@@ -76,6 +76,17 @@ basalt defaults to `true`:
 outside the union **throws** naming the column — a money column never silently left-aligns. Set it
 once on the column def instead of repeating `textAlign: 'right'` on the header and the cell.
 
+**`meta.numeral: false` is needed less often than it looks.** The auto style sets `fontFamily`,
+`fontSize`, `fontWeight`, `fontVariantNumeric` and `color` on the `<td>` whenever the raw value is a
+number — but a child `Text` sets its own `color` and `fontWeight` and wins those, and never sets a
+`fontFamily`. **Only `fontFamily` leaks.** So `c="dimmed"` is not a reason to opt out (and on a
+percentage column the mono figures are what you want); `fw={600}` on an accent figure is, because
+the `<td>`'s monospace still overrides the family the `Text` inherited. One consumer measured this
+across three tables: **3 columns** genuinely needed the opt-out, not the 4 that were assumed. Reach
+for it when the cell renders its own chrome — a coloured `Text`, a `Badge`, a sparkline — and check
+what actually leaked before adding it. `null` is worth a thought too: `typeof null === 'object'`, so
+a `number | null` column goes mono only on its non-null rows, which is worse than uniformly wrong.
+
 ### Controlled sorting and URL sync
 
 `initialSorting` seeds the internal `useState` and `onSortingChange` is called on every sort
@@ -148,8 +159,47 @@ Global search (`enableGlobalFilter`, `globalFilterPlaceholder`, `searchIcon`,
 pinning (`enablePinning`, `initialColumnPinning`). **Don't hand-roll any of these** — read the props
 on the type, they are all there.
 
-Still deferred: row selection, row expansion / sub-rows, and fully controlled (external) sorting —
-`onSortingChange` is the sync seam. Add them when a concrete consumer need arises; keep the API
+### `manualPagination` imposes a contract on the rest of the props
+
+Adopting it makes `data` **one server page** while the bar still reads `Showing 1–25 of 412`. Every
+other client-side control then becomes a claim about 412 rows it can only make about 25 — a sort
+that reorders one page under a header chevron that says it sorted all of them is a plausible, wrong
+answer with nothing on screen to give it away. So each control has to be resolved explicitly; there
+is no safe default, because only the call site knows whether the server does the work.
+
+| With `manualPagination`   | Resolve it with                                                                     |
+| ------------------------- | ----------------------------------------------------------------------------------- |
+| the pagination bar itself | `enablePagination` (without it `manualPagination` is inert) + `rowCount`            |
+| sorting                   | `manualSorting` + sort in the `onSortingChange` request, or `enableSorting={false}` |
+| `enableGlobalFilter`      | `manualFiltering` + filter in the `onGlobalFilterChange` request                    |
+| `facets`                  | `manualFiltering` + `onColumnFiltersChange`                                         |
+
+```tsx
+<BasaltDataTable
+  data={page.rows}
+  columns={columns}
+  enablePagination
+  manualPagination
+  rowCount={page.total}
+  manualSorting
+  onSortingChange={(s) => refetch({ sort: s[0] })}
+  onPaginationChange={(p) => refetch({ page: p })}
+/>
+```
+
+`manualSorting` / `manualFiltering` don't switch the controls off — the headers and inputs stay
+live and keep reporting through their `on*Change` callbacks. They stop the table from _recomputing_
+the answer locally, so what renders is the order and the selection the server sent.
+
+**Unresolved, it is not silent.** A contradiction throws in dev naming every breach at once, and a
+production bundle (where the throw is constant-folded away) degrades to the honest table instead:
+no sort headers, no filter controls, no `of N` it cannot stand behind, plus one `console.error`.
+You will never get the plausible wrong answer, but you also won't get sorting you thought you had —
+so read the throw, don't work around it.
+
+Still deferred: row selection, row expansion / sub-rows, and fully controlled (external) sorting
+STATE — `manualSorting` hands the _work_ to the server, but the table still owns the `SortingState`
+and reports it through `onSortingChange`. Add them when a concrete consumer need arises; keep the API
 additive.
 
 ### The blessed lane vs the raw escape hatch
@@ -196,11 +246,21 @@ takes no view here — it steers raw `overflow: auto`, and `Table.ScrollContaine
 component, not a raw scroll box.)
 
 **Adopt the blessed lane for ownership, not for a line count.** Porting one consumer's three tables
-onto these props made them 341 → **370** lines, 29 longer: eight accessor blocks at 4–6 lines each
-cost more than an eight-`<Table.Td>` row at ~3 when every cell is bespoke. What the port bought was
-the `type="native"` footgun, alignment stated once instead of on both `th` and `td` six times over,
-and sorting/filtering/pagination no longer being yours to maintain. Expect that trade, not a
-shrink.
+onto these props made them 341 → **370–379** lines, **29–38 longer**: a scratch port measured the
+low end, the consumer's own shipped port the high end, because it kept the comment blocks
+justifying each table's `numeral` opt-outs and its `enableSorting` decision. Accessor blocks at
+4–6 lines each cost more than an eight-`<Table.Td>` row at ~3 when every cell is bespoke, and the
+opt-outs are lines the hand-rolled version never had to write. Budget the high end. What the port
+bought was the `type="native"` footgun, alignment stated once instead of on both `th` and `td` —
+**4 literals in one table alone, 6 across the two that had alignment to state** — and
+sorting/filtering/pagination no longer being yours to maintain. Expect that trade, not a shrink.
+
+That consumer deliberately left the third table hand-rolled, and the reason generalises: four of
+its six columns would have needed `enableSorting: false` (three sparkline cells over `number[]`
+accessors, one status enum), and a numeric column rendering its own coloured `Text` would have
+needed a `numeral: false` it did not need before. A table with no sorting, no pagination, no filter
+and no alignment to declare is a layout grid that happens to use `<table>` — adopting the component
+there buys nothing and taxes you to switch off things you never asked for.
 
 ## BasaltVirtualList
 

package/agent/rules/basalt-query.md

@@ -99,8 +99,8 @@ function Library() {
 
 **Rendering only the empty branch is the bug this retires.** A consumer's library showed
 `No images` on a **500**, and a share detail showed `Share not found` on a dropped connection —
-"nothing here" is what an app renders when nobody wrote the other three branches. One import
-replaced 204 hand-rolled lines across 10 call sites there.
+"nothing here" is what an app renders when nobody wrote the other three branches. Swapping the
+import replaced 204 hand-rolled lines across 10 call sites there, with no prop or JSX change.
 
 Precedence, in evaluation order:
 

package/dist/dashboard/query-state.d.ts

@@ -5,7 +5,7 @@ export type QueryStateVariant = 'page' | 'section';
  * The structural subset of a TanStack `UseQueryResult` these components read.
  *
  * Typed as a SUBSET rather than as `UseQueryResult<T>` on purpose: a composed, derived or
- * hand-rolled result must be passable without a cast (3 of image-share's 10 call sites are), and
+ * hand-rolled result must be passable without a cast, and
  * these components stay independent of which `@tanstack/react-query` major a consumer pins. This
  * is NOT a claim that the root barrel is free of that package — `./connectivity` imports
  * `onlineManager` as a value and is re-exported from `src/index.ts`. The cost of the subset is

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

@@ -1,5 +1,5 @@
 import type { MantineSpacing } from '@mantine/core';
-import type { ColumnDef, ColumnPinningState, PaginationState, RowData, SortingState } from '@tanstack/react-table';
+import type { ColumnDef, ColumnFiltersState, ColumnPinningState, PaginationState, RowData, SortingState } from '@tanstack/react-table';
 import type { ReactNode } from 'react';
 /** Horizontal alignment of a column's header AND its cells. */
 export type DataTableAlign = 'left' | 'center' | 'right';
@@ -74,15 +74,43 @@ export type BasaltDataTableProps<T> = {
      */
     columns: ColumnDef<T, any>[];
     /**
-     * Enable column sorting via clickable headers.
+     * Enable column sorting via clickable headers. Client-side — the rows in `data` are what get
+     * reordered.
+     *
+     * Under `manualPagination` that is one page, so leaving this on without also passing
+     * `manualSorting` is a contract violation and throws in dev — see `manualPagination`.
      * @default true
      */
     enableSorting?: boolean;
+    /**
+     * Hand sorting to the server: the table stops reordering `data` locally and renders it in the
+     * order given, while the headers keep toggling `SortingState` and reporting it through
+     * `onSortingChange` — which is where you re-request the sorted page.
+     *
+     * This is the required companion to `manualPagination` whenever sort headers are live; without
+     * it a server-paginated table sorts one page and the "of N" bar presents that as a sort of all N.
+     * @default false
+     * @example
+     * <BasaltDataTable
+     *   data={page.rows}
+     *   columns={columns}
+     *   enablePagination
+     *   manualPagination
+     *   manualSorting
+     *   rowCount={page.total}
+     *   onSortingChange={(s) => refetch({ sort: s[0] })}
+     * />
+     */
+    manualSorting?: boolean;
     /** Stripe alternate rows. Forwarded to Mantine `Table` — `'odd'`/`'even'` pick the phase. */
     striped?: boolean | 'odd' | 'even';
     /** Highlight hovered rows. Forwarded to Mantine `Table`. */
     highlightOnHover?: boolean;
-    /** Rendered when `data` is empty. Falls back to a simple message when omitted. */
+    /**
+     * Rendered when no rows are VISIBLE — `data` is empty, or a filter/page matches none of it.
+     * Falls back to a simple message when omitted. (Before 1.25.0 this tracked `data.length` alone,
+     * so a search matching nothing rendered a blank `<tbody>` with no message at all.)
+     */
     emptyState?: ReactNode;
     /**
      * When true, renders skeleton placeholder rows instead of the empty-state branch.
@@ -141,6 +169,18 @@ export type BasaltDataTableProps<T> = {
      * facets={[{ columnId: 'department', label: 'Department', options: departmentOptions }]}
      */
     facets?: DataTableFacet[];
+    /** Called whenever the faceted column filters change — the seam for server-side faceting. */
+    onColumnFiltersChange?: (filters: ColumnFiltersState) => void;
+    /**
+     * Hand filtering to the server: the table stops narrowing `data` locally and renders every row
+     * given, while the search input and facets keep reporting through `onGlobalFilterChange` /
+     * `onColumnFiltersChange` — which is where you re-request the filtered page.
+     *
+     * Required alongside `manualPagination` whenever `enableGlobalFilter` or `facets` is set;
+     * without it the controls narrow one page while "of N" keeps counting the whole set.
+     * @default false
+     */
+    manualFiltering?: boolean;
     /**
      * Right-aligned toolbar slot (e.g. an "Export" button). Renders the toolbar row even when no
      * search input or facets are configured.
@@ -169,6 +209,21 @@ export type BasaltDataTableProps<T> = {
      * Disables local pagination slicing — pass the already-paginated page of `data` plus `rowCount`
      * (and optionally `pageCount`) for server-driven pagination. `onPaginationChange` is where you
      * fetch the next page.
+     *
+     * **It imposes a contract, enforced at render.** `data` is now one page, but the pagination bar
+     * says "Showing 1–25 of 412" — so every OTHER client-side control becomes a claim about 412 rows
+     * that it can only make about 25. Each has to be resolved explicitly, because only the call site
+     * knows whether the server does the work:
+     *
+     * - `rowCount` (or `pageCount`) must be given, or "of N" counts the page and the pager collapses
+     *   to a single page nobody can leave;
+     * - sorting must be handed over with `manualSorting`, or switched off with `enableSorting={false}`;
+     * - `enableGlobalFilter` / `facets`, if used, must be handed over with `manualFiltering`;
+     * - `enablePagination` must be on, or `manualPagination` is inert and the page renders as if it
+     *   were the whole table.
+     *
+     * Unresolved, each throws in dev and degrades to the honest render in production (no sort
+     * headers, no filter controls, no "of N") — never to the plausible wrong answer.
      * @default false
      * @example
      * <BasaltDataTable
@@ -235,8 +290,13 @@ export type BasaltDataTableProps<T> = {
  * A sortable data table backed by TanStack Table and rendered with Mantine primitives.
  * Generic over `T` — column types are inferred from `ColumnDef<T>`.
  *
- * Sorting is local/client-side (no `any`). When `enableSorting` is `false` the table
- * is read-only. An `emptyState` node is rendered when `data` is empty.
+ * Sorting is local/client-side by default (no `any`); `manualSorting` hands it to the server.
+ * When `enableSorting` is `false` the table is read-only. An `emptyState` node is rendered
+ * whenever no rows are visible — empty `data`, or a filter that matches none of it.
+ *
+ * `manualPagination` imposes a contract on the rest of the props (see its docblock): every
+ * client-side control it would turn into a false claim about the unseen rows must be handed to the
+ * server or switched off, and an unresolved one throws in dev rather than misreporting.
  *
  * Toolbar (search + facets), pagination, and column pinning are opt-in chrome layered on top —
  * see the corresponding props below. None of them change rendering unless explicitly enabled.
@@ -251,5 +311,5 @@ export type BasaltDataTableProps<T> = {
  *   emptyState={<Text c="dimmed">No users found.</Text>}
  * />
  */
-export declare function BasaltDataTable<T>({ data, columns, enableSorting, striped, highlightOnHover, emptyState, isLoading, skeletonRows, initialSorting, onSortingChange, enableGlobalFilter, globalFilterPlaceholder, searchIcon, initialGlobalFilter, onGlobalFilterChange, facets, toolbarActions, enablePagination, pageSizeOptions, initialPagination, onPaginationChange, manualPagination, rowCount, pageCount, enablePinning, initialColumnPinning, maxHeight, minWidth, stickyHeader, stickyHeaderOffset, verticalSpacing, horizontalSpacing, withRowBorders, withTableBorder, }: BasaltDataTableProps<T>): import("react").JSX.Element;
+export declare function BasaltDataTable<T>({ data, columns, enableSorting, manualSorting, striped, highlightOnHover, emptyState, isLoading, skeletonRows, initialSorting, onSortingChange, enableGlobalFilter, globalFilterPlaceholder, searchIcon, initialGlobalFilter, onGlobalFilterChange, facets, onColumnFiltersChange, manualFiltering, toolbarActions, enablePagination, pageSizeOptions, initialPagination, onPaginationChange, manualPagination, rowCount, pageCount, enablePinning, initialColumnPinning, maxHeight, minWidth, stickyHeader, stickyHeaderOffset, verticalSpacing, horizontalSpacing, withRowBorders, withTableBorder, }: BasaltDataTableProps<T>): import("react").JSX.Element;
 //# sourceMappingURL=data-table.d.ts.map

package/dist/data/data-table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-table.d.ts","sourceRoot":"","sources":["../../src/data/data-table.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"data-table.d.ts","sourceRoot":"","sources":["../../src/data/data-table.tsx"],"names":[],"mappings":"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"}

package/dist/data/data-table.js

@@ -85,10 +85,43 @@ function getPinnedCellStyle(table, column) {
     boxShadow: isEdge ? `-4px 0 6px -4px ${alpha(VX.ink, 0.18)}` : void 0
   };
 }
+function isDev() {
+  return process.env["NODE_ENV"] !== "production";
+}
+const BREACH_REMEDY = {
+  inert: "`enablePagination` is not set, so `manualPagination` never reaches the table and the server page renders as if it were the whole set, with no bar to say otherwise. Pass `enablePagination`, or drop `manualPagination`.",
+  total: 'neither `rowCount` nor `pageCount` was given, so "of N" counts only the rows on this page and the pager collapses to one page nobody can leave. Pass `rowCount={total}`.',
+  sorting: 'client-side sorting is still armed. It reorders only the rows in `data` \u2014 one page \u2014 while the header chevron and "of N" together present it as a sort of all of them. Pass `manualSorting` and sort in the request you make from `onSortingChange`, or `enableSorting={false}`.',
+  filtering: 'the search input / facets still filter client-side. They narrow only the rows in `data` \u2014 one page \u2014 while "of N" keeps counting the whole set. Pass `manualFiltering` and filter in the request you make from `onGlobalFilterChange` / `onColumnFiltersChange`, or drop `enableGlobalFilter` / `facets`.'
+};
+function manualPaginationBreaches(config) {
+  if (!config.manualPagination) return [];
+  if (!config.enablePagination) return ["inert"];
+  const breaches = [];
+  if (config.rowCount === void 0 && config.pageCount === void 0) breaches.push("total");
+  const anyColumnMaySort = config.columns.some((column) => column.enableSorting !== false);
+  if (config.enableSorting && anyColumnMaySort && !config.manualSorting) breaches.push("sorting");
+  if ((config.enableGlobalFilter || config.hasFacets) && !config.manualFiltering)
+    breaches.push("filtering");
+  return breaches;
+}
+function manualPaginationMessage(breaches) {
+  return "BasaltDataTable: `manualPagination` is set, so `data` is one server page \u2014 but:\n  \xB7 " + breaches.map((breach) => BREACH_REMEDY[breach]).join("\n  \xB7 ") + "\nEach has to be resolved explicitly: only the call site knows whether the server does the work, so there is no default that is not a guess about the data.";
+}
+const reportedBreaches = /* @__PURE__ */ new Set();
+function enforceManualPaginationContract(breaches) {
+  if (breaches.length === 0) return;
+  const message = manualPaginationMessage(breaches);
+  if (isDev()) throw new Error(message);
+  if (reportedBreaches.has(message)) return;
+  reportedBreaches.add(message);
+  console.error(message);
+}
 function BasaltDataTable({
   data,
   columns,
   enableSorting = true,
+  manualSorting = false,
   striped,
   highlightOnHover,
   emptyState,
@@ -102,6 +135,8 @@ function BasaltDataTable({
   initialGlobalFilter,
   onGlobalFilterChange,
   facets,
+  onColumnFiltersChange,
+  manualFiltering = false,
   toolbarActions,
   enablePagination = false,
   pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
@@ -148,6 +183,16 @@ function BasaltDataTable({
     },
     [onGlobalFilterChange]
   );
+  const handleColumnFiltersChange = useCallback(
+    (updater) => {
+      setColumnFilters((prev) => {
+        const next = typeof updater === "function" ? updater(prev) : updater;
+        onColumnFiltersChange?.(next);
+        return next;
+      });
+    },
+    [onColumnFiltersChange]
+  );
   const handlePaginationChange = useCallback(
     (updater) => {
       setPagination((prev) => {
@@ -170,6 +215,23 @@ function BasaltDataTable({
       return { ...column, filterFn };
     });
   }, [columns, facets]);
+  const hasFacets = Boolean(facets && facets.length > 0);
+  const breaches = manualPaginationBreaches({
+    columns,
+    enablePagination,
+    manualPagination,
+    rowCount,
+    pageCount,
+    enableSorting,
+    manualSorting,
+    enableGlobalFilter,
+    hasFacets,
+    manualFiltering
+  });
+  enforceManualPaginationContract(breaches);
+  const sortingEnabled = enableSorting && !breaches.includes("sorting");
+  const filteringEnabled = !breaches.includes("filtering");
+  const totalIsAuthoritative = !breaches.includes("total");
   const table = useReactTable({
     data,
     columns: tableColumns,
@@ -182,23 +244,33 @@ function BasaltDataTable({
     },
     onSortingChange: handleSortingChange,
     onGlobalFilterChange: handleGlobalFilterChange,
-    onColumnFiltersChange: setColumnFilters,
+    onColumnFiltersChange: handleColumnFiltersChange,
     onColumnPinningChange: setColumnPinning,
     ...enablePagination && { onPaginationChange: handlePaginationChange },
     getCoreRowModel: getCoreRowModel(),
     getSortedRowModel: getSortedRowModel(),
     getFilteredRowModel: getFilteredRowModel(),
+    // Both row models stay installed and are BYPASSED by these flags, which is TanStack's own
+    // seam — so a degraded table renders `data` in the order and completeness the server sent it.
+    // Forced only by a BREACH, never by `enableSorting={false}` on its own: that pair still applies
+    // an `initialSorting` today (it disables the header control, not the row model) and a table
+    // that is not misreporting has no business losing it.
+    manualSorting: manualSorting || breaches.includes("sorting"),
+    manualFiltering: manualFiltering || breaches.includes("filtering"),
     ...enablePagination && {
       getPaginationRowModel: getPaginationRowModel(),
       manualPagination,
       ...manualPagination && rowCount !== void 0 && { rowCount },
       ...manualPagination && pageCount !== void 0 && { pageCount }
     },
-    enableSorting,
+    enableSorting: sortingEnabled,
     enableColumnPinning: enablePinning
   });
-  const showToolbar = enableGlobalFilter || Boolean(facets && facets.length > 0) || Boolean(toolbarActions);
+  const showSearch = enableGlobalFilter && filteringEnabled;
+  const showFacets = hasFacets && filteringEnabled;
+  const showToolbar = showSearch || showFacets || Boolean(toolbarActions);
   const headerGroups = enablePinning ? getOrderedHeaderGroups(table) : table.getHeaderGroups();
+  const rows = table.getRowModel().rows;
   const tableNode = /* @__PURE__ */ jsxs(
     Table,
     {
@@ -212,7 +284,7 @@ function BasaltDataTable({
       withTableBorder,
       children: [
         /* @__PURE__ */ jsx(Table.Thead, { children: headerGroups.map((headerGroup) => /* @__PURE__ */ jsx(Table.Tr, { children: headerGroup.headers.map((header) => {
-          const canSort = enableSorting && header.column.getCanSort();
+          const canSort = sortingEnabled && header.column.getCanSort();
           const sorted = header.column.getIsSorted();
           const toggleSorting = header.column.getToggleSortingHandler();
           const pinnedStyle = enablePinning ? getPinnedCellStyle(table, header.column) : void 0;
@@ -241,7 +313,7 @@ function BasaltDataTable({
             header.id
           );
         }) }, headerGroup.id)) }),
-        /* @__PURE__ */ jsx(Table.Tbody, { children: isLoading ? Array.from({ length: skeletonRows }, (_, rowIndex) => /* @__PURE__ */ jsx(Table.Tr, { children: columns.map((_2, colIndex) => /* @__PURE__ */ jsx(Table.Td, { children: /* @__PURE__ */ jsx(Skeleton, { height: 16, radius: "sm" }) }, `skeleton-${rowIndex}-${colIndex}`)) }, `skeleton-${rowIndex}`)) : data.length === 0 ? /* @__PURE__ */ jsx(Table.Tr, { children: /* @__PURE__ */ jsx(Table.Td, { colSpan: columns.length, children: emptyState ?? /* @__PURE__ */ jsx(Text, { c: "dimmed", ta: "center", size: "sm", py: "sm", children: "No data to display." }) }) }) : table.getRowModel().rows.map((row) => {
+        /* @__PURE__ */ jsx(Table.Tbody, { children: isLoading ? Array.from({ length: skeletonRows }, (_, rowIndex) => /* @__PURE__ */ jsx(Table.Tr, { children: columns.map((_2, colIndex) => /* @__PURE__ */ jsx(Table.Td, { children: /* @__PURE__ */ jsx(Skeleton, { height: 16, radius: "sm" }) }, `skeleton-${rowIndex}-${colIndex}`)) }, `skeleton-${rowIndex}`)) : rows.length === 0 ? /* @__PURE__ */ jsx(Table.Tr, { children: /* @__PURE__ */ jsx(Table.Td, { colSpan: columns.length, children: emptyState ?? /* @__PURE__ */ jsx(Text, { c: "dimmed", ta: "center", size: "sm", py: "sm", children: "No data to display." }) }) }) : rows.map((row) => {
           const cells = enablePinning ? [
             ...row.getLeftVisibleCells(),
             ...row.getCenterVisibleCells(),
@@ -275,7 +347,7 @@ function BasaltDataTable({
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     showToolbar && /* @__PURE__ */ jsxs(Group, { justify: "space-between", align: "flex-end", wrap: "wrap", gap: "xs", mb: "xs", children: [
       /* @__PURE__ */ jsxs(Group, { gap: "xs", wrap: "wrap", align: "flex-end", children: [
-        enableGlobalFilter && /* @__PURE__ */ jsx(
+        showSearch && /* @__PURE__ */ jsx(
           TextInput,
           {
             size: "xs",
@@ -287,7 +359,7 @@ function BasaltDataTable({
             w: 220
           }
         ),
-        facets?.map((facet) => {
+        showFacets && facets?.map((facet) => {
           const column = table.getColumn(facet.columnId);
           if (!column) return null;
           if (facet.multiple) {
@@ -341,8 +413,7 @@ function BasaltDataTable({
         rangeStart,
         "\u2013",
         rangeEnd,
-        " of ",
-        total
+        totalIsAuthoritative ? ` of ${total}` : ""
       ] }),
       /* @__PURE__ */ jsxs(Group, { gap: "xs", align: "center", children: [
         /* @__PURE__ */ jsx(

package/dist/data/table.d.ts

@@ -20,5 +20,5 @@
  */
 export { BasaltDataTable } from './data-table.js';
 export type { BasaltDataTableProps, DataTableAlign, DataTableFacet, DataTableFacetOption, } from './data-table.js';
-export { createColumnHelper, useReactTable, flexRender, getCoreRowModel, getSortedRowModel, getFilteredRowModel, getPaginationRowModel, type ColumnDef, type SortingState, type ColumnHelper, type PaginationState, type ColumnPinningState, } from '@tanstack/react-table';
+export { createColumnHelper, useReactTable, flexRender, getCoreRowModel, getSortedRowModel, getFilteredRowModel, getPaginationRowModel, type ColumnDef, type SortingState, type ColumnHelper, type PaginationState, type ColumnPinningState, type ColumnFiltersState, } from '@tanstack/react-table';
 //# sourceMappingURL=table.d.ts.map

package/dist/data/table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/data/table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,cAAc,CAAA;AASrB,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/data/table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,cAAc,CAAA;AASrB,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EAEvB,KAAK,kBAAkB,GACxB,MAAM,uBAAuB,CAAA"}

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.24.0
+# basalt-ui v1.25.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.24.0
+Version: 1.25.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/dashboard/query-state.tsx

@@ -26,7 +26,7 @@ export type QueryStateVariant = 'page' | 'section'
  * The structural subset of a TanStack `UseQueryResult` these components read.
  *
  * Typed as a SUBSET rather than as `UseQueryResult<T>` on purpose: a composed, derived or
- * hand-rolled result must be passable without a cast (3 of image-share's 10 call sites are), and
+ * hand-rolled result must be passable without a cast, and
  * these components stay independent of which `@tanstack/react-query` major a consumer pins. This
  * is NOT a claim that the root barrel is free of that package — `./connectivity` imports
  * `onlineManager` as a value and is re-exported from `src/index.ts`. The cost of the subset is

package/src/data/data-table.test.tsx

@@ -13,12 +13,13 @@
  *     (`apps/playground/src/data-table-align.type-guard.ts`); the value can only be caught here,
  *     and a silent fallback to left-aligned would look correct in review.
  */
-import { MantineProvider } from '@mantine/core'
-import { render, screen } from '@testing-library/react'
+import { MantineProvider, Text } from '@mantine/core'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { describe, expect, test } from 'bun:test'
 import { BasaltDataTable } from './data-table'
 import { createColumnHelper } from './table'
 import type { BasaltDataTableProps } from './data-table'
+import type { ColumnFiltersState } from './table'
 
 type Row = { project: string; cost: number }
 const col = createColumnHelper<Row>()
@@ -156,3 +157,193 @@ describe('regression — the bare table is unchanged', () => {
     expect(screen.getByText('linewatch')).toBeTruthy()
   })
 })
+
+/**
+ * The manual-pagination contract (argo round 10, P1).
+ *
+ * `manualPagination` makes `data` one server page while the bar reads "Showing 1–25 of 412", so
+ * every remaining client-side control becomes a claim about 412 rows it can only make about 25.
+ * These pin the replacement for the old silence: loud where the props contradict each other, and
+ * honest — never plausible-but-wrong — where a production bundle has dropped the throw.
+ */
+
+/** Run `fn` with the production dev-gate, restoring whatever the runner had set. */
+function inProd(fn: () => void): void {
+  const previous = process.env['NODE_ENV']
+  process.env['NODE_ENV'] = 'production'
+  try {
+    fn()
+  } finally {
+    if (previous === undefined) delete process.env['NODE_ENV']
+    else process.env['NODE_ENV'] = previous
+  }
+}
+
+const SERVER_PAGE: Partial<BasaltDataTableProps<Row>> = {
+  enablePagination: true,
+  manualPagination: true,
+  rowCount: 412,
+}
+
+describe('manualPagination — the props that would misreport must be resolved', () => {
+  test('the bare adoption throws, naming the page-local sort and both ways out', () => {
+    expect(() => renderTable(SERVER_PAGE)).toThrow(
+      /client-side sorting is still armed[\s\S]*`manualSorting`[\s\S]*`enableSorting=\{false\}`/,
+    )
+  })
+
+  test('no rowCount and no pageCount throws — "of N" would count the page', () => {
+    expect(() =>
+      renderTable({ enablePagination: true, manualPagination: true, manualSorting: true }),
+    ).toThrow(/neither `rowCount` nor `pageCount`/)
+  })
+
+  test('manualPagination without enablePagination throws — the prop is inert, not harmless', () => {
+    expect(() => renderTable({ manualPagination: true })).toThrow(
+      /`enablePagination` is not set, so `manualPagination` never reaches the table/,
+    )
+  })
+
+  test('client-side search over one server page throws too — the same defect, one control over', () => {
+    expect(() =>
+      renderTable({ ...SERVER_PAGE, manualSorting: true, enableGlobalFilter: true }),
+    ).toThrow(/the search input \/ facets still filter client-side/)
+  })
+
+  test('facets trip the filtering breach even with no search input', () => {
+    expect(() =>
+      renderTable({
+        ...SERVER_PAGE,
+        manualSorting: true,
+        facets: [{ columnId: 'project', label: 'Project', options: [] }],
+      }),
+    ).toThrow(/still filter client-side/)
+  })
+
+  test('every unresolved breach is reported at once, not one per fix-and-rerun', () => {
+    expect(() => renderTable({ manualPagination: true, enablePagination: true })).toThrow(
+      /neither `rowCount`[\s\S]*client-side sorting is still armed/,
+    )
+  })
+})
+
+describe('manualPagination — the two sanctioned resolutions', () => {
+  test("enableSorting={false} renders, and no header claims to sort — argo's workaround", () => {
+    const { container } = renderTable({ ...SERVER_PAGE, enableSorting: false })
+    for (const th of container.querySelectorAll('th')) {
+      expect(th.getAttribute('aria-sort')).toBeNull()
+      expect(th.getAttribute('tabindex')).toBeNull()
+    }
+    expect(container.textContent).toContain('of 412')
+  })
+
+  test('manualSorting keeps the headers live but stops reordering the page locally', () => {
+    // asc by cost would put linewatch (3) above argo (12) — under manualSorting the server's
+    // order is what renders, because the server is the one that sorted.
+    const sorted = renderTable({
+      ...SERVER_PAGE,
+      manualSorting: true,
+      initialSorting: [{ id: 'cost', desc: false }],
+    })
+    expect(sorted.container.querySelector('tbody tr')?.textContent).toContain('argo')
+    expect(sorted.container.querySelector('th')?.getAttribute('aria-sort')).toBe('none')
+
+    // The control: the same initialSorting on a client-side table DOES reorder.
+    const local = renderTable({ initialSorting: [{ id: 'cost', desc: false }] })
+    expect(local.container.querySelector('tbody tr')?.textContent).toContain('linewatch')
+  })
+
+  test('manualFiltering hands the search to the server — the input filters nothing locally', () => {
+    const { container } = renderTable({
+      ...SERVER_PAGE,
+      manualSorting: true,
+      manualFiltering: true,
+      enableGlobalFilter: true,
+      initialGlobalFilter: 'zzzz',
+    })
+    // Client-side that term matches no row; the server page renders whole.
+    expect(container.querySelectorAll('tbody tr')).toHaveLength(2)
+    expect(container.querySelector('input')).toBeTruthy()
+  })
+})
+
+describe('manualPagination — production degrades to the honest table, never the plausible one', () => {
+  test('no sort headers, no search input, and no "of N" it cannot stand behind', () => {
+    const errors: unknown[][] = []
+    const previous = console.error
+    console.error = (...args: unknown[]) => errors.push(args)
+    try {
+      inProd(() => {
+        const { container } = renderTable({
+          manualPagination: true,
+          enablePagination: true,
+          enableGlobalFilter: true,
+        })
+        // Sorting: the control is gone, so the table asserts nothing about the unseen rows.
+        for (const th of container.querySelectorAll('th')) {
+          expect(th.getAttribute('aria-sort')).toBeNull()
+        }
+        // Filtering: same — a control that can only narrow one page is not rendered.
+        expect(container.querySelector('input[placeholder="Search…"]')).toBeNull()
+        // The count: no rowCount was given, so the bar states the range and claims no total.
+        expect(container.textContent).toContain('Showing 1–2')
+        expect(container.textContent).not.toContain('of 2')
+      })
+    } finally {
+      console.error = previous
+    }
+    // The degradation is not its own silence.
+    expect(errors).toHaveLength(1)
+    expect(String(errors[0]?.[0])).toContain('BasaltDataTable: `manualPagination` is set')
+  })
+})
+
+/**
+ * Sibling defect found by reading, not by a consumer: the empty branch keyed off `data.length`,
+ * so any narrowing that left `data` non-empty but the row model empty rendered a `<tbody>` with
+ * nothing in it — no rows, no message. A blank body reads as a broken table, not as no matches.
+ */
+describe('the empty state tracks the rendered rows, not the raw array', () => {
+  test('a search matching nothing shows the empty state instead of a blank tbody', () => {
+    const { container } = renderTable({
+      enableGlobalFilter: true,
+      initialGlobalFilter: 'no-such-project',
+    })
+    expect(container.querySelectorAll('tbody tr')).toHaveLength(1)
+    expect(container.textContent).toContain('No data to display.')
+  })
+
+  test('a custom emptyState is honoured on a filtered-to-nothing table too', () => {
+    const { container } = renderTable({
+      enableGlobalFilter: true,
+      initialGlobalFilter: 'no-such-project',
+      emptyState: <Text>Nothing matches that search.</Text>,
+    })
+    expect(container.textContent).toContain('Nothing matches that search.')
+  })
+
+  test('a page index past the end shows the empty state rather than an empty body', () => {
+    const { container } = renderTable({
+      enablePagination: true,
+      initialPagination: { pageIndex: 9, pageSize: 10 },
+    })
+    expect(container.textContent).toContain('No data to display.')
+  })
+})
+
+describe('onColumnFiltersChange — the seam server-side faceting needs', () => {
+  test('a facet selection reports the new columnFilters', async () => {
+    const seen: ColumnFiltersState[] = []
+    const { container } = renderTable({
+      facets: [
+        { columnId: 'project', label: 'Project', options: [{ value: 'argo', label: 'argo' }] },
+      ],
+      onColumnFiltersChange: (filters) => seen.push(filters),
+    })
+    const select = container.querySelector('input[placeholder="Project"]')
+    if (!select) throw new Error('expected the facet Select')
+    fireEvent.click(select)
+    fireEvent.click(await screen.findByRole('option', { name: 'argo' }))
+    await waitFor(() => expect(seen).toEqual([[{ id: 'project', value: 'argo' }]]))
+  })
+})

package/src/data/data-table.tsx

@@ -171,15 +171,43 @@ export type BasaltDataTableProps<T> = {
   // oxlint-disable-next-line typescript/no-explicit-any -- TanStack-idiomatic heterogeneous column array
   columns: ColumnDef<T, any>[]
   /**
-   * Enable column sorting via clickable headers.
+   * Enable column sorting via clickable headers. Client-side — the rows in `data` are what get
+   * reordered.
+   *
+   * Under `manualPagination` that is one page, so leaving this on without also passing
+   * `manualSorting` is a contract violation and throws in dev — see `manualPagination`.
    * @default true
    */
   enableSorting?: boolean
+  /**
+   * Hand sorting to the server: the table stops reordering `data` locally and renders it in the
+   * order given, while the headers keep toggling `SortingState` and reporting it through
+   * `onSortingChange` — which is where you re-request the sorted page.
+   *
+   * This is the required companion to `manualPagination` whenever sort headers are live; without
+   * it a server-paginated table sorts one page and the "of N" bar presents that as a sort of all N.
+   * @default false
+   * @example
+   * <BasaltDataTable
+   *   data={page.rows}
+   *   columns={columns}
+   *   enablePagination
+   *   manualPagination
+   *   manualSorting
+   *   rowCount={page.total}
+   *   onSortingChange={(s) => refetch({ sort: s[0] })}
+   * />
+   */
+  manualSorting?: boolean
   /** Stripe alternate rows. Forwarded to Mantine `Table` — `'odd'`/`'even'` pick the phase. */
   striped?: boolean | 'odd' | 'even'
   /** Highlight hovered rows. Forwarded to Mantine `Table`. */
   highlightOnHover?: boolean
-  /** Rendered when `data` is empty. Falls back to a simple message when omitted. */
+  /**
+   * Rendered when no rows are VISIBLE — `data` is empty, or a filter/page matches none of it.
+   * Falls back to a simple message when omitted. (Before 1.25.0 this tracked `data.length` alone,
+   * so a search matching nothing rendered a blank `<tbody>` with no message at all.)
+   */
   emptyState?: ReactNode
   /**
    * When true, renders skeleton placeholder rows instead of the empty-state branch.
@@ -241,6 +269,18 @@ export type BasaltDataTableProps<T> = {
    * facets={[{ columnId: 'department', label: 'Department', options: departmentOptions }]}
    */
   facets?: DataTableFacet[]
+  /** Called whenever the faceted column filters change — the seam for server-side faceting. */
+  onColumnFiltersChange?: (filters: ColumnFiltersState) => void
+  /**
+   * Hand filtering to the server: the table stops narrowing `data` locally and renders every row
+   * given, while the search input and facets keep reporting through `onGlobalFilterChange` /
+   * `onColumnFiltersChange` — which is where you re-request the filtered page.
+   *
+   * Required alongside `manualPagination` whenever `enableGlobalFilter` or `facets` is set;
+   * without it the controls narrow one page while "of N" keeps counting the whole set.
+   * @default false
+   */
+  manualFiltering?: boolean
   /**
    * Right-aligned toolbar slot (e.g. an "Export" button). Renders the toolbar row even when no
    * search input or facets are configured.
@@ -272,6 +312,21 @@ export type BasaltDataTableProps<T> = {
    * Disables local pagination slicing — pass the already-paginated page of `data` plus `rowCount`
    * (and optionally `pageCount`) for server-driven pagination. `onPaginationChange` is where you
    * fetch the next page.
+   *
+   * **It imposes a contract, enforced at render.** `data` is now one page, but the pagination bar
+   * says "Showing 1–25 of 412" — so every OTHER client-side control becomes a claim about 412 rows
+   * that it can only make about 25. Each has to be resolved explicitly, because only the call site
+   * knows whether the server does the work:
+   *
+   * - `rowCount` (or `pageCount`) must be given, or "of N" counts the page and the pager collapses
+   *   to a single page nobody can leave;
+   * - sorting must be handed over with `manualSorting`, or switched off with `enableSorting={false}`;
+   * - `enableGlobalFilter` / `facets`, if used, must be handed over with `manualFiltering`;
+   * - `enablePagination` must be on, or `manualPagination` is inert and the page renders as if it
+   *   were the whole table.
+   *
+   * Unresolved, each throws in dev and degrades to the honest render in production (no sort
+   * headers, no filter controls, no "of N") — never to the plausible wrong answer.
    * @default false
    * @example
    * <BasaltDataTable
@@ -423,14 +478,110 @@ function getPinnedCellStyle<T>(
   }
 }
 
+// ── The manual-pagination contract ────────────────────────────────────────────
+
+/** The house dev gate (`src/provider`, `src/charts/kinds/BandStrip` use the same expression):
+ * `basaltViteConfig` defines `process.env.NODE_ENV`, so a production bundle constant-folds this to
+ * `false` and drops the throw. Read per call, never hoisted, so a test can flip it. */
+function isDev(): boolean {
+  return process.env['NODE_ENV'] !== 'production'
+}
+
+/** One client-side control that `manualPagination` turns into a claim the table cannot support. */
+type ManualPaginationBreach = 'inert' | 'total' | 'sorting' | 'filtering'
+
+const BREACH_REMEDY: Record<ManualPaginationBreach, string> = {
+  inert:
+    '`enablePagination` is not set, so `manualPagination` never reaches the table and the server ' +
+    'page renders as if it were the whole set, with no bar to say otherwise. Pass ' +
+    '`enablePagination`, or drop `manualPagination`.',
+  total:
+    'neither `rowCount` nor `pageCount` was given, so "of N" counts only the rows on this page and ' +
+    'the pager collapses to one page nobody can leave. Pass `rowCount={total}`.',
+  sorting:
+    'client-side sorting is still armed. It reorders only the rows in `data` — one page — while the ' +
+    'header chevron and "of N" together present it as a sort of all of them. Pass `manualSorting` ' +
+    'and sort in the request you make from `onSortingChange`, or `enableSorting={false}`.',
+  filtering:
+    'the search input / facets still filter client-side. They narrow only the rows in `data` — one ' +
+    'page — while "of N" keeps counting the whole set. Pass `manualFiltering` and filter in the ' +
+    'request you make from `onGlobalFilterChange` / `onColumnFiltersChange`, or drop ' +
+    '`enableGlobalFilter` / `facets`.',
+}
+
+/**
+ * Every way the props on hand contradict `manualPagination`. Computed from PROPS only — never from
+ * the table instance, whose `getCanSort()` would read back the very `enableSorting` this decides.
+ */
+function manualPaginationBreaches(config: {
+  columns: readonly { enableSorting?: boolean }[]
+  enablePagination: boolean
+  manualPagination: boolean
+  rowCount: number | undefined
+  pageCount: number | undefined
+  enableSorting: boolean
+  manualSorting: boolean
+  enableGlobalFilter: boolean
+  hasFacets: boolean
+  manualFiltering: boolean
+}): ManualPaginationBreach[] {
+  if (!config.manualPagination) return []
+  if (!config.enablePagination) return ['inert']
+  const breaches: ManualPaginationBreach[] = []
+  if (config.rowCount === undefined && config.pageCount === undefined) breaches.push('total')
+  const anyColumnMaySort = config.columns.some((column) => column.enableSorting !== false)
+  if (config.enableSorting && anyColumnMaySort && !config.manualSorting) breaches.push('sorting')
+  if ((config.enableGlobalFilter || config.hasFacets) && !config.manualFiltering)
+    breaches.push('filtering')
+  return breaches
+}
+
+function manualPaginationMessage(breaches: ManualPaginationBreach[]): string {
+  return (
+    'BasaltDataTable: `manualPagination` is set, so `data` is one server page — but:\n  · ' +
+    breaches.map((breach) => BREACH_REMEDY[breach]).join('\n  · ') +
+    '\nEach has to be resolved explicitly: only the call site knows whether the server does the ' +
+    'work, so there is no default that is not a guess about the data.'
+  )
+}
+
+/** Bounded by the sixteen possible breach sets, so it cannot grow with render count. */
+const reportedBreaches = new Set<string>()
+
+/**
+ * Dev throws; production reports once and lets the caller degrade.
+ *
+ * Split deliberately from BandStrip's datum/prop rule rather than copied. That rule throws on a bad
+ * PROP because a prop is authored, deterministic, and caught the first time the component renders —
+ * all true here. What differs is that a bad `meta.align` has no honest render (every alignment we
+ * could pick might be the wrong one, and would look right in review), whereas this one does: a
+ * table with no sort headers, no filter controls and no "of N" asserts nothing false. Throwing in
+ * production would add no correctness the degradation does not already give, and would convert a
+ * misreport on a rarely-visited page into a blank one. The report is what keeps the degradation
+ * from being its own silence.
+ */
+function enforceManualPaginationContract(breaches: ManualPaginationBreach[]): void {
+  if (breaches.length === 0) return
+  const message = manualPaginationMessage(breaches)
+  if (isDev()) throw new Error(message)
+  if (reportedBreaches.has(message)) return
+  reportedBreaches.add(message)
+  console.error(message)
+}
+
 // ── Component ─────────────────────────────────────────────────────────────────
 
 /**
  * A sortable data table backed by TanStack Table and rendered with Mantine primitives.
  * Generic over `T` — column types are inferred from `ColumnDef<T>`.
  *
- * Sorting is local/client-side (no `any`). When `enableSorting` is `false` the table
- * is read-only. An `emptyState` node is rendered when `data` is empty.
+ * Sorting is local/client-side by default (no `any`); `manualSorting` hands it to the server.
+ * When `enableSorting` is `false` the table is read-only. An `emptyState` node is rendered
+ * whenever no rows are visible — empty `data`, or a filter that matches none of it.
+ *
+ * `manualPagination` imposes a contract on the rest of the props (see its docblock): every
+ * client-side control it would turn into a false claim about the unseen rows must be handed to the
+ * server or switched off, and an unresolved one throws in dev rather than misreporting.
  *
  * Toolbar (search + facets), pagination, and column pinning are opt-in chrome layered on top —
  * see the corresponding props below. None of them change rendering unless explicitly enabled.
@@ -449,6 +600,7 @@ export function BasaltDataTable<T>({
   data,
   columns,
   enableSorting = true,
+  manualSorting = false,
   striped,
   highlightOnHover,
   emptyState,
@@ -462,6 +614,8 @@ export function BasaltDataTable<T>({
   initialGlobalFilter,
   onGlobalFilterChange,
   facets,
+  onColumnFiltersChange,
+  manualFiltering = false,
   toolbarActions,
   enablePagination = false,
   pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
@@ -511,6 +665,17 @@ export function BasaltDataTable<T>({
     [onGlobalFilterChange],
   )
 
+  const handleColumnFiltersChange = useCallback(
+    (updater: Updater<ColumnFiltersState>) => {
+      setColumnFilters((prev) => {
+        const next = typeof updater === 'function' ? updater(prev) : updater
+        onColumnFiltersChange?.(next)
+        return next
+      })
+    },
+    [onColumnFiltersChange],
+  )
+
   const handlePaginationChange = useCallback(
     (updater: Updater<PaginationState>) => {
       setPagination((prev) => {
@@ -550,6 +715,27 @@ export function BasaltDataTable<T>({
     })
   }, [columns, facets])
 
+  // Enforced before the table is built, so the degraded options below are the ones TanStack gets —
+  // a degraded table must not merely hide a control, it must not compute the answer either.
+  const hasFacets = Boolean(facets && facets.length > 0)
+  const breaches = manualPaginationBreaches({
+    columns,
+    enablePagination,
+    manualPagination,
+    rowCount,
+    pageCount,
+    enableSorting,
+    manualSorting,
+    enableGlobalFilter,
+    hasFacets,
+    manualFiltering,
+  })
+  enforceManualPaginationContract(breaches)
+  // Unreachable in dev (the line above threw); in production these are the honest fallbacks.
+  const sortingEnabled = enableSorting && !breaches.includes('sorting')
+  const filteringEnabled = !breaches.includes('filtering')
+  const totalIsAuthoritative = !breaches.includes('total')
+
   const table = useReactTable<T>({
     data,
     columns: tableColumns,
@@ -562,25 +748,36 @@ export function BasaltDataTable<T>({
     },
     onSortingChange: handleSortingChange,
     onGlobalFilterChange: handleGlobalFilterChange,
-    onColumnFiltersChange: setColumnFilters,
+    onColumnFiltersChange: handleColumnFiltersChange,
     onColumnPinningChange: setColumnPinning,
     ...(enablePagination && { onPaginationChange: handlePaginationChange }),
     getCoreRowModel: getCoreRowModel(),
     getSortedRowModel: getSortedRowModel(),
     getFilteredRowModel: getFilteredRowModel(),
+    // Both row models stay installed and are BYPASSED by these flags, which is TanStack's own
+    // seam — so a degraded table renders `data` in the order and completeness the server sent it.
+    // Forced only by a BREACH, never by `enableSorting={false}` on its own: that pair still applies
+    // an `initialSorting` today (it disables the header control, not the row model) and a table
+    // that is not misreporting has no business losing it.
+    manualSorting: manualSorting || breaches.includes('sorting'),
+    manualFiltering: manualFiltering || breaches.includes('filtering'),
     ...(enablePagination && {
       getPaginationRowModel: getPaginationRowModel(),
       manualPagination,
       ...(manualPagination && rowCount !== undefined && { rowCount }),
       ...(manualPagination && pageCount !== undefined && { pageCount }),
     }),
-    enableSorting,
+    enableSorting: sortingEnabled,
     enableColumnPinning: enablePinning,
   })
 
-  const showToolbar =
-    enableGlobalFilter || Boolean(facets && facets.length > 0) || Boolean(toolbarActions)
+  const showSearch = enableGlobalFilter && filteringEnabled
+  const showFacets = hasFacets && filteringEnabled
+  const showToolbar = showSearch || showFacets || Boolean(toolbarActions)
   const headerGroups = enablePinning ? getOrderedHeaderGroups(table) : table.getHeaderGroups()
+  // The rows actually rendered, not `data` — a filter or a page index that matches nothing leaves
+  // `data` non-empty while the body has nothing in it, and a blank body reads as a broken table.
+  const rows = table.getRowModel().rows
 
   const tableNode = (
     <Table
@@ -597,7 +794,7 @@ export function BasaltDataTable<T>({
         {headerGroups.map((headerGroup) => (
           <Table.Tr key={headerGroup.id}>
             {headerGroup.headers.map((header) => {
-              const canSort = enableSorting && header.column.getCanSort()
+              const canSort = sortingEnabled && header.column.getCanSort()
               const sorted = header.column.getIsSorted()
               const toggleSorting = header.column.getToggleSortingHandler()
               const pinnedStyle = enablePinning
@@ -654,7 +851,7 @@ export function BasaltDataTable<T>({
               ))}
             </Table.Tr>
           ))
-        ) : data.length === 0 ? (
+        ) : rows.length === 0 ? (
           <Table.Tr>
             <Table.Td colSpan={columns.length}>
               {emptyState ?? (
@@ -665,7 +862,7 @@ export function BasaltDataTable<T>({
             </Table.Td>
           </Table.Tr>
         ) : (
-          table.getRowModel().rows.map((row) => {
+          rows.map((row) => {
             const cells = enablePinning
               ? [
                   ...row.getLeftVisibleCells(),
@@ -718,7 +915,7 @@ export function BasaltDataTable<T>({
       {showToolbar && (
         <Group justify="space-between" align="flex-end" wrap="wrap" gap="xs" mb="xs">
           <Group gap="xs" wrap="wrap" align="flex-end">
-            {enableGlobalFilter && (
+            {showSearch && (
               <TextInput
                 size="xs"
                 radius="md"
@@ -729,40 +926,41 @@ export function BasaltDataTable<T>({
                 w={220}
               />
             )}
-            {facets?.map((facet) => {
-              const column = table.getColumn(facet.columnId)
-              if (!column) return null
-              if (facet.multiple) {
-                const value = (column.getFilterValue() as string[] | undefined) ?? []
+            {showFacets &&
+              facets?.map((facet) => {
+                const column = table.getColumn(facet.columnId)
+                if (!column) return null
+                if (facet.multiple) {
+                  const value = (column.getFilterValue() as string[] | undefined) ?? []
+                  return (
+                    <MultiSelect
+                      key={facet.columnId}
+                      size="xs"
+                      radius="md"
+                      placeholder={facet.label}
+                      data={facet.options}
+                      value={value}
+                      onChange={(next) => column.setFilterValue(next.length > 0 ? next : undefined)}
+                      clearable
+                      w={200}
+                    />
+                  )
+                }
+                const value = (column.getFilterValue() as string | undefined) ?? null
                 return (
-                  <MultiSelect
+                  <Select
                     key={facet.columnId}
                     size="xs"
                     radius="md"
                     placeholder={facet.label}
                     data={facet.options}
                     value={value}
-                    onChange={(next) => column.setFilterValue(next.length > 0 ? next : undefined)}
+                    onChange={(next) => column.setFilterValue(next ?? undefined)}
                     clearable
-                    w={200}
+                    w={180}
                   />
                 )
-              }
-              const value = (column.getFilterValue() as string | undefined) ?? null
-              return (
-                <Select
-                  key={facet.columnId}
-                  size="xs"
-                  radius="md"
-                  placeholder={facet.label}
-                  data={facet.options}
-                  value={value}
-                  onChange={(next) => column.setFilterValue(next ?? undefined)}
-                  clearable
-                  w={180}
-                />
-              )
-            })}
+              })}
           </Group>
           {toolbarActions}
         </Group>
@@ -783,7 +981,8 @@ export function BasaltDataTable<T>({
       {enablePagination && (
         <Group justify="space-between" mt="xs" wrap="wrap" gap="xs" align="center">
           <Text style={RANGE_LABEL_STYLE}>
-            Showing {rangeStart}–{rangeEnd} of {total}
+            Showing {rangeStart}–{rangeEnd}
+            {totalIsAuthoritative ? ` of ${total}` : ''}
           </Text>
           <Group gap="xs" align="center">
             <Select

package/src/data/table.ts

@@ -48,4 +48,6 @@ export {
   type ColumnHelper,
   type PaginationState,
   type ColumnPinningState,
+  // The type `onColumnFiltersChange` hands back — needed at the call site for server-side faceting.
+  type ColumnFiltersState,
 } from '@tanstack/react-table'