cursedbelt 5.28.0 → 5.30.0

package/src/react/components/DataTable/DataTable.tsx

@@ -1,7 +1,6 @@
 import {
   type ColumnDef,
   type ColumnFiltersState,
-  flexRender,
   getCoreRowModel,
   getFilteredRowModel,
   getPaginationRowModel,
@@ -26,6 +25,7 @@ import type {
 import { useVirtualizer } from '@tanstack/react-virtual';
 import { type ComponentType, Fragment, type Ref, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import { useScrollEdgeFade } from '../../hooks/useScrollEdgeFade.js';
+import { useRememberedPreference } from '../../media-gallery/rememberedPreference.js';
 import { cn } from '../../lib/cn.js';
 import { TAP_TARGET_HEIGHT } from '../../lib/tapTarget.js';
 import { CardTapTarget } from '../CardTapTarget.js';
@@ -54,7 +54,7 @@ import type {
   DataTableServerWindow,
   TableViewMode,
 } from './types.js';
-import { resolveColumnAlign } from './types.js';
+import { resolveColumnAlign, SELECT_COLUMN_ID } from './types.js';
 import { lazyPart } from './lazyPart.js';
 import type { TablePaginationProps } from './Pagination.js';
 import type { TableToolbarProps } from './Toolbar.js';
@@ -109,12 +109,31 @@ function PaginationPlaceholder() {
   );
 }
 
+/**
+ * Render a header or cell template by CALLING it — never `flexRender`.
+ *
+ * 🔴 `flexRender` mounts a function template as a component (`<Template {...ctx} />`), so its
+ * identity IS the element type. Our templates are closures rebuilt whenever `columns` changes
+ * identity, and a consumer's `columns` memo commonly depends on something that changes often
+ * (music's depended on its player: play, pause, every track). Each rebuild was a new component
+ * type for every visible cell — React unmounted and remounted the whole body, every `<img>` was
+ * recreated, and on an iPhone the list's thumbnails flickered for as long as a song played
+ * (2026-09-29). Called as a function, a template returns `<CellRenderer>` / `<SortHeader>`,
+ * whose types never change, so a column rebuild is an ordinary re-render. Every template this
+ * file builds is hook-free — the hooks live in the components it returns — which is what
+ * makes the call sound; keep it so. `DataTable.spec.tsx` → "a columns rebuild keeps the cells".
+ */
+function renderTemplate<TContext>(template: ReactNode | ((context: TContext) => ReactNode) | undefined, context: TContext): ReactNode {
+  return typeof template === 'function' ? template(context) : (template ?? null);
+}
+
 // TanStack's header is a render fn (we build a sortable button), so its column has no
 // string header for the ViewOptionsMenu to label a toggle with. Carry the label on
 // `meta` instead — augmenting the base interface so it's typed everywhere.
 declare module '@tanstack/react-table' {
   interface ColumnMeta<TData extends RowData, TValue> {
     label?: string;
+    menuLabel?: string;
     align?: 'left' | 'right';
     /** ColDef.width verbatim (px number or CSS string, e.g. `'15%'`) — TanStack's
      *  own `size` is number-only, so proportional tracks ride meta instead. */
@@ -187,6 +206,8 @@ export interface DataTableControls {
   labelOf: (id: string) => string;
   viewMode?: TableViewMode;
   setViewMode?: (mode: TableViewMode) => void;
+  /** The checkbox column, when the table has one — so the Columns menu can hide it too. */
+  selectionColumn?: { visible: boolean; setVisible: (visible: boolean) => void };
 }
 
 export interface DataTableProps<TRow extends Record<string, unknown>> {
@@ -482,6 +503,20 @@ export interface DataTableProps<TRow extends Record<string, unknown>> {
    */
   searchable?: boolean;
   searchPlaceholder?: string;
+  /**
+   * Tune the DEFAULT toolbar without composing one — which of its controls to draw, and any
+   * extra actions. It stays lazy (a composed `toolbar={(t) => <TableToolbar …/>}` pulls the
+   * toolbar into the caller's first chunk). `searchable={false}` still removes the search box
+   * but, with this set, not the rest of the line.
+   *
+   * 🔴 Why (owner, 2026-09-30, music): *"Use the cb table that comes with filtering, checkboxes,
+   * and sorting out of the box."* The track list opted out of the whole toolbar because it has
+   * its own server-side search box, and so lost the filter builder and the Columns menu with it.
+   */
+  toolbarOptions?: Pick<
+    TableToolbarProps<TRow>,
+    'enableColumnVisibility' | 'enableFilterBuilder' | 'enableSortStack' | 'extraActions'
+  >;
   /**
    * Multi-column sort: each header click puts that column at the FRONT of the
    * stack and keeps the previous keys behind it as tie-breakers, so the owner's
@@ -552,6 +587,25 @@ export interface DataTableProps<TRow extends Record<string, unknown>> {
    * owns the box. The row boxes are unchanged (`selectedIds` / `onSelectionChange`).
    */
   selectAll?: DataTableSelectAll;
+  /**
+   * Which columns are shown, CONTROLLED — `{ [ColDef.key]: false }` hides one, and
+   * `'__select'` is the checkbox column's key. Omit and the table keeps it
+   * internally, seeded from `ColDef.hidden`, exactly as before.
+   *
+   * 🔴 Why a caller would own it (owner, 2026-09-30, music: *"Allow hiding any column, like
+   * the checkbox column"*): a column hidden through the Columns menu that comes back on the
+   * next reload was never hidden, it was dismissed. Only the app knows where its per-account
+   * preferences live, so the app persists this and hands it back.
+   */
+  columnVisibility?: VisibilityState;
+  onColumnVisibilityChange?: (next: VisibilityState) => void;
+  /**
+   * Remember the Columns menu's choices under this key — `localStorage`, announced on the
+   * preference bus (`onPreferenceWrite`) and re-read on `seedPreferences`, exactly like a
+   * `RailSection`'s `persistKey`, so an app that already carries its rail to the server carries
+   * its columns with no code of its own. A controlled {@link columnVisibility} wins over it.
+   */
+  columnsPersistKey?: string;
   /**
    * Attributes and handlers for one body ROW, merged onto it after the table's own —
    * `className` joins, `style` spreads, and a handler the table also sets runs AFTER the
@@ -586,6 +640,19 @@ export interface DataTableProps<TRow extends Record<string, unknown>> {
   selectionSummary?: (selectedRows: TRow[]) => ReactNode;
 }
 
+/** A remembered column-visibility value, or `null` for anything that is not one — a stored
+ *  value from an older shape must fall back to the defaults, never throw a table off the page. */
+function parseVisibility(stored: string | null): VisibilityState | null {
+  if (!stored) return null;
+  try {
+    const value: unknown = JSON.parse(stored);
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) return null;
+    return Object.fromEntries(Object.entries(value).filter(([, shown]) => typeof shown === 'boolean')) as VisibilityState;
+  } catch {
+    return null;
+  }
+}
+
 /** Build an OnChangeFn that updates local state AND notifies an optional listener. */
 function chainUpdater<T>(
   set: Dispatch<SetStateAction<T>>,
@@ -850,6 +917,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
   cardMinWidth,
   searchable = true,
   searchPlaceholder,
+  toolbarOptions,
   multiSort = true,
   filterQuery: filterQueryProp,
   onFilterQueryChange,
@@ -863,6 +931,9 @@ export function DataTable<TRow extends Record<string, unknown>>({
   selectionSummary,
   selectAll,
   getRowProps,
+  columnVisibility: columnVisibilityProp,
+  onColumnVisibilityChange,
+  columnsPersistKey,
 }: DataTableProps<TRow>) {
   // Vertical cell padding for the wide grid tier — the one lever the density knob
   // pulls (headers + body cells stay aligned by sharing it).
@@ -875,9 +946,30 @@ export function DataTable<TRow extends Record<string, unknown>>({
   const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
   const [globalFilter, setGlobalFilter] = useState('');
 
-  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>(() =>
+  const [ownColumnVisibility, setOwnColumnVisibility] = useState<VisibilityState>(() =>
     Object.fromEntries(columns.filter((c) => c.hidden).map((c) => [c.key, false])),
   );
+  const [rememberedColumns, setRememberedColumns] = useRememberedPreference(columnsPersistKey);
+  const remembered = useMemo(() => parseVisibility(rememberedColumns), [rememberedColumns]);
+  const columnVisibility =
+    columnVisibilityProp ?? (remembered ? { ...ownColumnVisibility, ...remembered } : ownColumnVisibility);
+  const columnVisibilityRef = useRef(columnVisibility);
+  columnVisibilityRef.current = columnVisibility;
+  /** Every visibility write — TanStack's own, the Columns menu's, the checkbox column's. Computed
+   *  outside a state updater for the same reason as `applySorting`: under a controlled value
+   *  there is no state to update, and a notify inside an updater fires twice in StrictMode. */
+  const updateColumnVisibility = useCallback<OnChangeFn<VisibilityState>>(
+    (updater) => {
+      const next = typeof updater === 'function' ? updater(columnVisibilityRef.current) : updater;
+      columnVisibilityRef.current = next;
+      if (columnVisibilityProp === undefined) {
+        setOwnColumnVisibility(next);
+        if (columnsPersistKey) setRememberedColumns(JSON.stringify(next));
+      }
+      onColumnVisibilityChange?.(next);
+    },
+    [columnVisibilityProp, columnsPersistKey, onColumnVisibilityChange, setRememberedColumns],
+  );
   const [pagination, setPagination] = useState<PaginationState>({ pageIndex: 0, pageSize });
   // `null` = every column, and it STAYS null as columns come and go — see SearchBox.
   const [searchScope, setSearchScope] = useState<string[] | null>(null);
@@ -936,10 +1028,12 @@ export function DataTable<TRow extends Record<string, unknown>>({
    */
   const filteredData = useMemo(
     () =>
-      serverSide
+      // A `serverWindow` holds a hundred rows of thousands: narrowing THEM would answer a
+      // question about the loaded page, not the list. The server applies it — the table reports.
+      serverSide || serverWindow
         ? data
         : data.filter((row) => evaluateFilterQuery(row, filterQuery, (r, key) => readPath(r, key))),
-    [data, filterQuery, serverSide],
+    [data, filterQuery, serverSide, serverWindow],
   );
 
   /**
@@ -981,6 +1075,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
         // preference — `resolveColumnAlign` derives it; an explicit `align` overrides.
         meta: {
           label: col.label,
+          menuLabel: col.menuLabel,
           align: resolveColumnAlign(col),
           width: col.width,
           minWidth: col.minWidth,
@@ -1042,7 +1137,9 @@ export function DataTable<TRow extends Record<string, unknown>>({
       setFilterQuery,
       // `alwaysVisible` columns are exempt from HIDING, not from filtering — the
       // builder's universe is every column that carries data.
-      filterColumns: liveColumns.map((col) => ({ key: col.key, label: col.label })),
+      filterColumns: liveColumns
+        .filter((col) => col.filterable ?? true)
+        .map((col) => ({ key: col.key, label: col.label })),
       searchScope,
       setSearchScope,
       searchColumns: liveColumns
@@ -1056,6 +1153,14 @@ export function DataTable<TRow extends Record<string, unknown>>({
       labelOf,
       viewMode,
       setViewMode: onViewModeChange,
+      selectionColumn:
+        selectedIds !== undefined
+          ? {
+              visible: columnVisibility[SELECT_COLUMN_ID] !== false,
+              setVisible: (visible) =>
+                updateColumnVisibility((prev) => ({ ...prev, [SELECT_COLUMN_ID]: visible })),
+            }
+          : undefined,
     }),
     [
       applySorting,
@@ -1069,6 +1174,9 @@ export function DataTable<TRow extends Record<string, unknown>>({
       setFilterQuery,
       sorting,
       viewMode,
+      selectedIds,
+      columnVisibility,
+      updateColumnVisibility,
     ],
   );
 
@@ -1095,6 +1203,10 @@ export function DataTable<TRow extends Record<string, unknown>>({
   const paginationHidden = hidePagination || virtualEnabled;
 
   const selectionEnabled = selectedIds !== undefined;
+  /** The checkbox column is ON and not hidden through the Columns menu. Hiding it hides the
+   *  boxes, never the selection: a row click that selects still does, and the caller's
+   *  selection bar still counts it. */
+  const selectionShown = selectionEnabled && columnVisibility[SELECT_COLUMN_ID] !== false;
   /**
    * Without `getRowId`, TanStack ids a row by its index in the array it was
    * handed — which is `filteredData`, so the builder narrowing the rows would
@@ -1128,7 +1240,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
       const text = typeof next === 'string' ? next : ((next as TableSearchState | undefined)?.text ?? '');
       setSearchText(text);
     },
-    onColumnVisibilityChange: chainUpdater(setColumnVisibility),
+    onColumnVisibilityChange: updateColumnVisibility,
     onPaginationChange: chainUpdater(setPagination, onPaginationChange),
     // 🔴 Not `'includesString'` any more. That built-in is `String(value)`, and
     // `String(new Date())` / `String(['rock','80s'])` are not the text the
@@ -1462,15 +1574,17 @@ export function DataTable<TRow extends Record<string, unknown>>({
         // passes its own gets exactly that, and `TableToolbar` reads the same
         // controls off `table.options.meta`, so composing a toolbar is never
         // the thing that costs you the search box.
-        (searchable ? (
+        (searchable || toolbarOptions ? (
           <ToolbarPart
             table={table}
             searchPlaceholder={searchPlaceholder}
+            enableSearch={searchable}
+            {...toolbarOptions}
             fallback={<ToolbarPlaceholder />}
           />
         ) : null));
   const visibleColumnCount =
-    table.getVisibleLeafColumns().length + (hasActions ? 1 : 0) + (selectionEnabled ? 1 : 0);
+    table.getVisibleLeafColumns().length + (hasActions ? 1 : 0) + (selectionShown ? 1 : 0);
   // Cards track the SAME live visibility state as the grid (ViewOptionsMenu toggles
   // apply to both) — not just the ColDefs' initial `hidden` flags.
   const cardColumns = liveColumns.filter((c) => table.getColumn(c.key)?.getIsVisible() ?? true);
@@ -1485,7 +1599,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
   const tableMinWidth = fixedLayout
     ? Math.max(
         minTableWidth ?? 0,
-        declaredTrackFloor(cardColumns, hasActions) + (selectionEnabled ? SELECT_TRACK_PX : 0),
+        declaredTrackFloor(cardColumns, hasActions) + (selectionShown ? SELECT_TRACK_PX : 0),
       )
     : minTableWidth;
 
@@ -1536,7 +1650,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
               ladder inside it would only fight the container query. ── */}
           {/* Select-all for the tiers with no header row to carry it: the phone
               cards, and the card view at every width. */}
-          {selectionEnabled && (viewMode === 'card' || mobileCards) ? (
+          {selectionShown && (viewMode === 'card' || mobileCards) ? (
             <div
               data-cb-table-select-all=''
               className={cn('flex items-center px-2 py-1', viewMode !== 'card' && '@xl:hidden')}
@@ -1552,7 +1666,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
               onRowClick={onRowClick}
               dragPropsFor={getRowDrag ? dragPropsFor : undefined}
               selectFor={
-                selectionEnabled
+                selectionShown
                   ? (_row, index) => {
                       const tsRow = rows[index];
                       return tsRow ? rowCheckbox(tsRow) : null;
@@ -1575,7 +1689,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                   className={rowClassName?.(row.original)}
                   onRowClick={onRowClick}
                   dragProps={mergeRowProps(dragPropsFor(row.original), getRowProps?.(row.original, windowStart + row.index))}
-                  select={selectionEnabled ? rowCheckbox(row) : undefined}
+                  select={selectionShown ? rowCheckbox(row) : undefined}
                   actions={
                     hasActions ? (
                       <RowActions
@@ -1621,7 +1735,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                 // absent (the header) and every preceding lane drifts ~32px off
                 // its label — the v4 judge's tablet misalignment finding.
                 const template = [
-                  ...(selectionEnabled ? ['44px'] : []),
+                  ...(selectionShown ? ['44px'] : []),
                   'minmax(0,1fr)',
                   ...rest.map(trackOf),
                   ...(hasActions ? ['32px'] : []),
@@ -1636,7 +1750,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                     className='grid items-center gap-3 border-b border-border px-4 py-2 text-caption font-bold uppercase tracking-wider text-muted-foreground'
                     style={{ gridTemplateColumns: template }}
                   >
-                    {selectionEnabled ? <span className='flex justify-center'>{headerCheckbox()}</span> : null}
+                    {selectionShown ? <span className='flex justify-center'>{headerCheckbox()}</span> : null}
                     <span>{title?.label ?? ''}</span>
                     {rest.map((col) => (
                       <span key={col.key} className={cn(resolveColumnAlign(col) === 'right' && 'text-right')}>
@@ -1665,7 +1779,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                           getRowProps?.(row.original, windowStart + row.index),
                         )}
                       >
-                        {selectionEnabled ? (
+                        {selectionShown ? (
                           <div {...selectCellProps(row)} className='-my-3 flex self-stretch items-center justify-center'>
                             {rowCheckbox(row)}
                           </div>
@@ -1781,7 +1895,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                             // next header slides over the frozen one. It is opaque
                             // for the same reason the body cells are.
                             frozen &&
-                              (selectionEnabled
+                              (selectionShown
                                 ? 'sticky left-11 bg-card shadow-[1px_0_0_0_var(--color-border)]'
                                 : 'sticky left-0 bg-card shadow-[1px_0_0_0_var(--color-border)]'),
                             frozen && (stickyHeader ? 'z-30' : 'z-20'),
@@ -1790,7 +1904,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                         >
                           {h.isPlaceholder
                             ? null
-                            : flexRender(h.column.columnDef.header, h.getContext())}
+                            : renderTemplate(h.column.columnDef.header, h.getContext())}
                         </th>
                       );
                     };
@@ -1798,7 +1912,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                       return (
                         <>
                           {hg.headers.filter(isLeading).map((h) => renderHeader(h, -1))}
-                    {selectionEnabled ? (
+                    {selectionShown ? (
                       <th
                         scope='col'
                         className={cn(
@@ -1929,7 +2043,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                               'px-4 align-middle',
                               cellPadY,
                               frozen &&
-                                (selectionEnabled
+                                (selectionShown
                                   ? 'sticky left-11 z-10 bg-[var(--cb-frozen-bg)] shadow-[1px_0_0_0_var(--color-border)]'
                                   : 'sticky left-0 z-10 bg-[var(--cb-frozen-bg)] shadow-[1px_0_0_0_var(--color-border)]'),
                               // A rigid track cannot widen for its content, so an
@@ -1945,14 +2059,14 @@ export function DataTable<TRow extends Record<string, unknown>>({
                                 HIDE_BELOW_CLASS[cell.column.columnDef.meta.hideBelow],
                             )}
                           >
-                            {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                            {renderTemplate(cell.column.columnDef.cell, cell.getContext())}
                           </td>
                           );
                         };
                           return (
                             <>
                               {cells.filter(isLeading).map((cell) => renderCell(cell, -1))}
-                        {selectionEnabled ? (
+                        {selectionShown ? (
                           <td
                             {...selectCellProps(row)}
                             style={

package/src/react/components/DataTable/ViewOptionsMenu.tsx

@@ -4,6 +4,7 @@ import { useState } from 'react';
 import { Button } from '../Button.js';
 import { Popover } from '../Popover.js';
 import { ColumnChecklist } from './ColumnChecklist.js';
+import { SELECT_COLUMN_ID } from './types.js';
 
 export interface ViewOptionsMenuProps<TRow> {
   table: Table<TRow>;
@@ -29,8 +30,12 @@ export interface ViewOptionsMenuProps<TRow> {
 export function ViewOptionsMenu<TRow>({ table, label = 'Columns' }: ViewOptionsMenuProps<TRow>) {
   const [open, setOpen] = useState(false);
   const columns = table.getAllColumns().filter((c) => c.getCanHide());
-  if (!columns.length) return null;
-  const hiddenCount = columns.filter((c) => !c.getIsVisible()).length;
+  // The checkbox column is not a TanStack column, so it comes off the table's controls — and it
+  // is listed FIRST, where it sits (owner, 2026-09-30: *"Allow hiding any column, like the
+  // checkbox column"*).
+  const selection = table.options.meta?.cbControls?.selectionColumn;
+  if (!columns.length && !selection) return null;
+  const hiddenCount = columns.filter((c) => !c.getIsVisible()).length + (selection && !selection.visible ? 1 : 0);
 
   return (
     <Popover
@@ -60,14 +65,24 @@ export function ViewOptionsMenu<TRow>({ table, label = 'Columns' }: ViewOptionsM
           aria-label='Visible columns'
           selectAllLabel='Show all'
           selectNoneLabel='Hide all'
-          items={columns.map((col) => ({
-            key: col.id,
-            label: col.columnDef.meta?.label ?? col.id,
-            checked: col.getIsVisible(),
-          }))}
-          onToggle={(key) => table.getColumn(key)?.toggleVisibility()}
-          onSelectAll={() => table.toggleAllColumnsVisible(true)}
+          items={[
+            ...(selection ? [{ key: SELECT_COLUMN_ID, label: 'Checkboxes', checked: selection.visible }] : []),
+            ...columns.map((col) => ({
+              key: col.id,
+              // A label-less column (a cover, a handle) still needs a name in this list.
+              label: col.columnDef.meta?.menuLabel || col.columnDef.meta?.label || col.id,
+              checked: col.getIsVisible(),
+            })),
+          ]}
+          onToggle={(key) =>
+            key === SELECT_COLUMN_ID ? selection?.setVisible(!selection.visible) : table.getColumn(key)?.toggleVisibility()
+          }
+          onSelectAll={() => {
+            table.toggleAllColumnsVisible(true);
+            selection?.setVisible(true);
+          }}
           onSelectNone={() => {
+            selection?.setVisible(false);
             // Not `toggleAllColumnsVisible(false)`: that hides the pinned
             // (`alwaysVisible`) columns too in TanStack's implementation, and a
             // table with literally no columns is a blank rectangle the reader

package/src/react/components/DataTable/selection.spec.tsx

@@ -1,5 +1,5 @@
 import { afterEach, beforeAll, describe, expect, test } from 'bun:test';
-import { cleanup, fireEvent, render } from '@testing-library/react';
+import { cleanup, fireEvent, render, within } from '@testing-library/react';
 import { useState } from 'react';
 import { hoverHint } from '../../../testing/tooltip.js';
 import { DataTable, type DataTableProps, preloadDataTableParts } from './DataTable.js';
@@ -191,3 +191,59 @@ describe('DataTable row selection', () => {
     expect(list.querySelectorAll('[role="checkbox"]').length).toBe(GAMES.length + 1);
   });
 });
+
+describe('the checkbox column can be hidden (owner, 2026-09-30)', () => {
+  test('🔴 the Columns menu lists "Checkboxes", and unticking it removes the boxes but keeps the selection', () => {
+    const reported: Record<string, boolean>[] = [];
+    const changes: string[][] = [];
+    const { container, getByRole, getByLabelText } = render(
+      <Harness
+        initial={['g2']}
+        onChange={(next) => changes.push([...next])}
+        onColumnVisibilityChange={(next) => reported.push(next)}
+      />,
+    );
+    expect(headerBox(container)).not.toBeNull();
+    fireEvent.click(getByRole('button', { name: /^columns$/i }));
+    fireEvent.click(within(getByLabelText('Visible columns')).getByRole('menuitemcheckbox', { name: 'Checkboxes' }));
+    expect(reported.at(-1)).toEqual({ __select: false });
+    expect(grid(container).querySelector('[role="checkbox"]')).toBeNull();
+    expect(container.querySelectorAll('thead th').length).toBe(COLUMNS.length);
+    // Hidden, not cleared: nothing reported a new selection.
+    expect(changes).toEqual([]);
+  });
+
+  test('a CONTROLLED visibility is what the table draws — the app owns where it is kept', () => {
+    const { container } = render(<Harness columnVisibility={{ __select: false, sizeMb: false }} />);
+    expect(grid(container).querySelector('[role="checkbox"]')).toBeNull();
+    expect(container.querySelectorAll('thead th').length).toBe(1);
+  });
+});
+
+describe('columnsPersistKey', () => {
+  test('a hidden column is still hidden after a remount, and the write is announced for the server', async () => {
+    const { onPreferenceWrite } = await import('../../media-gallery/preferenceBus.js');
+    const heard: [string, string | null][] = [];
+    const off = onPreferenceWrite((key, value) => heard.push([key, value]));
+    localStorage.removeItem('spec:columns');
+    const first = render(<Harness columnsPersistKey='spec:columns' />);
+    fireEvent.click(first.getByRole('button', { name: /^columns$/i }));
+    fireEvent.click(within(first.getByLabelText('Visible columns')).getByRole('menuitemcheckbox', { name: 'Size' }));
+    expect(heard.at(-1)).toEqual(['spec:columns', JSON.stringify({ sizeMb: false })]);
+    first.unmount();
+    const second = render(<Harness columnsPersistKey='spec:columns' />);
+    expect(second.container.querySelectorAll('thead th').length).toBe(COLUMNS.length); // checkbox + Title
+    off();
+  });
+});
+
+describe('toolbarOptions', () => {
+  test('searchable={false} with toolbarOptions keeps the Columns menu and the filter builder, without a search box', () => {
+    const { queryByRole, getByRole } = render(
+      <Harness searchable={false} toolbarOptions={{ enableSortStack: false }} />,
+    );
+    expect(getByRole('button', { name: /^columns$/i })).not.toBeNull();
+    expect(getByRole('button', { name: /filter/i })).not.toBeNull();
+    expect(queryByRole('searchbox')).toBeNull();
+  });
+});

package/src/react/components/DataTable/types.ts

@@ -20,8 +20,12 @@ export interface ColDef<TRow = Record<string, unknown>> {
   /** Registry type — dispatched to `CELL_REGISTRY` (display) + `FIELD_REGISTRY` (edit). */
   type: string;
   sortable?: boolean;
-  /** Include this column when the global search filters rows (default: true). */
+  /** Include this column when the search box or the filter builder narrows rows (default:
+   *  true). `false` for a column that draws no data — a cover, a drag handle, a row control. */
   filterable?: boolean;
+  /** The column's name in the Columns menu when its header has no text (a cover, a handle) —
+   *  a checklist row with no name is a switch nobody can find. Default: `label`, then `key`. */
+  menuLabel?: string;
   /** Start hidden (toggle back on via {@link ViewOptionsMenu}). */
   hidden?: boolean;
   /** Column track width. A number is px; a string is any CSS width — use
@@ -206,3 +210,10 @@ export interface DataTableHandle {
     options?: { align?: 'start' | 'center' | 'end' | 'auto'; behavior?: 'auto' | 'smooth' },
   ): number | null;
 }
+
+/**
+ * The checkbox column's key in `columnVisibility`. It is not a TanStack column — it has no
+ * data and no header menu of its own — so it cannot be hidden through `getAllColumns()`; the
+ * Columns menu lists it by this key instead, beside the real ones.
+ */
+export const SELECT_COLUMN_ID = '__select';

package/src/react/components/DataTable/virtualize.spec.tsx

@@ -144,3 +144,23 @@ describe('serverWindow (forge task 2300)', () => {
     expect(screen.queryByRole('button', { name: /next page|previous page/i })).toBeNull();
   });
 });
+
+describe('serverWindow + the filter builder', () => {
+  test('🔴 the builder is REPORTED, never applied to the loaded window', () => {
+    const rows = Array.from({ length: 3 }, (_, i) => ({ id: `r${i}`, name: `Row ${i}` }));
+    render(
+      <DataTable<Row>
+        columns={COLUMNS}
+        data={rows}
+        getRowId={(r) => r.id}
+        serverWindow={{ start: 0, total: 3, rowHeight: 50 }}
+        filterQuery={{ groups: [{ id: 'g', conditions: [{ id: 'c', column: 'name', op: 'contains', value: 'Row 1' }] }] }}
+      />,
+    );
+    // A window is a page of what the SERVER matched; narrowing it again would hide rows the
+    // server already decided belong, and say nothing about the thousands not loaded.
+    // (Each row is drawn once per tier — grid, list, cards — hence `getAllByText`.)
+    expect(screen.getAllByText('Row 0').length).toBeGreaterThan(0);
+    expect(screen.getAllByText('Row 2').length).toBeGreaterThan(0);
+  });
+});

package/src/react/components/DatePicker.tsx

@@ -11,7 +11,7 @@ import {
   localDateToIso,
   ThemedDayButton,
 } from '../lib/daypicker.js';
-import { type ControlSize, fieldControlClass } from '../lib/field.js';
+import { type ControlSize, declareFieldWidth, fieldControlClass } from '../lib/field.js';
 import { Drawer } from './Drawer.js';
 import { Popover } from './Popover.js';
 
@@ -147,3 +147,5 @@ export function DatePicker({
     </Popover>
   );
 }
+
+declareFieldWidth(DatePicker, 'sm');

package/src/react/components/DateTimeField.tsx

@@ -1,5 +1,5 @@
 import { cn } from '../lib/cn.js';
-import { type ControlSize, fieldControlClass } from '../lib/field.js';
+import { type ControlSize, declareFieldWidth, fieldControlClass } from '../lib/field.js';
 import { DatePicker } from './DatePicker.js';
 
 export interface DateTimeFieldProps {
@@ -88,3 +88,5 @@ export function DateTimeField({
     </div>
   );
 }
+
+declareFieldWidth(DateTimeField, 'sm');