@gntik-ai/blocks 0.5.0 → 0.7.0

package/src/tables/CursorPagerFooter/block.meta.ts

@@ -0,0 +1,23 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Cursor pager footer',
+  family: 'tables',
+  status: 'beta',
+  description:
+    'Responsive stateless cursor-pagination footer for data-table paginated={false}. Forwards CursorPaginationProps: hasPrevious, hasNext, onPrevious, onNext, loading, busy, summary, shownCount, total, unavailableBehaviour, pageSize, pageSizeOptions, onPageSizeChange, previousLabel, nextLabel, ariaLabel, loadingLabel, labels and className. Consumer-owned opaque cursors stay outside the kit. summary accepts plain text or null; the count form requires labels.shownSummary and labels.totalSummary; select options require labels.rowsPerPage and labels.rowsPerPageLabel. Flat names override labels.previous, labels.next and labels.navLabel, then catalog defaults. loadingLabel=null preserves the summary while busy. One persistent polite atomic status; buttons remain focusable when aria-disabled. Removal of a focused control moves focus to Next, Previous, select, then nav root, including while busy. No page numbers or ranges. No props renders fixtures.',
+  labels: [
+    { key: 'previous', type: 'string', state: 'Previous name, below previousLabel and above catalog defaults' },
+    { key: 'next', type: 'string', state: 'Next name, below nextLabel and above catalog defaults' },
+    { key: 'navLabel', type: 'string', state: 'Navigation name, below ariaLabel and above catalog defaults' },
+    {
+      key: 'shownSummary',
+      type: '(shownCount: number) => string',
+      state: 'Required in count form: no positive exact total',
+    },
+    { key: 'totalSummary', type: '(total: number) => string', state: 'Required in count form: positive exact total' },
+    { key: 'rowsPerPage', type: 'string', state: 'Required with pageSizeOptions: visible select label' },
+    { key: 'rowsPerPageLabel', type: 'string', state: 'Required with pageSizeOptions: select accessible name' },
+  ],
+  uses: ['CursorPagination'],
+};

package/src/tables/CursorPagerFooter/examples/Busy.tsx

@@ -0,0 +1,7 @@
+import { CursorPagerFooter } from '../CursorPagerFooter';
+
+export default function Busy() {
+  return (
+    <CursorPagerFooter hasPrevious hasNext busy summary="25 records loaded" onPrevious={() => {}} onNext={() => {}} />
+  );
+}

package/src/tables/CursorPagerFooter/examples/CursorStack.tsx

@@ -0,0 +1,40 @@
+import { useState } from 'react';
+import { DataTable } from '../../DataTable/DataTable';
+import { CursorPagerFooter } from '../CursorPagerFooter';
+
+// Mock API responses: only this consumer stores or interprets opaque continuation tokens.
+const responses: Record<string, { rows: { name: string }[]; next?: string }> = {
+  start: { rows: [{ name: 'Record A' }], next: 'opaque-k7' },
+  'opaque-k7': { rows: [{ name: 'Record B' }], next: 'opaque-m9' },
+  'opaque-m9': { rows: [{ name: 'Record C' }] },
+};
+
+export default function CursorStack() {
+  const [stack, setStack] = useState<string[]>([]);
+  const response = responses[stack.at(-1) ?? 'start'] ?? responses.start!;
+  return (
+    <div className="space-y-4">
+      <DataTable
+        rows={response.rows}
+        columns={[{ id: 'name', header: 'Name', accessor: (row) => row.name }]}
+        caption="Records"
+        paginated={false}
+        selectable={false}
+        showColumnMenu={false}
+        showDensityToggle={false}
+        showViewSwitcher={false}
+        resizable={false}
+      />
+      <CursorPagerFooter
+        hasPrevious={stack.length > 0}
+        hasNext={response.next !== undefined}
+        onPrevious={() => setStack((current) => current.slice(0, -1))}
+        onNext={() => {
+          if (response.next) setStack((current) => [...current, response.next!]);
+        }}
+        shownCount={response.rows.length}
+        labels={{ shownSummary: (n) => `${n} records shown`, totalSummary: (n) => `${n} records in total` }}
+      />
+    </div>
+  );
+}

package/src/tables/CursorPagerFooter/examples/Hidden.tsx

@@ -0,0 +1,16 @@
+import { CursorPagerFooter } from '../CursorPagerFooter';
+
+export default function Hidden() {
+  return (
+    <CursorPagerFooter
+      hasPrevious
+      hasNext={false}
+      unavailableBehaviour="hidden"
+      shownCount={7}
+      total={57}
+      labels={{ shownSummary: (n) => `${n} records shown`, totalSummary: (n) => `${n} records in total` }}
+      onPrevious={() => {}}
+      onNext={() => {}}
+    />
+  );
+}

package/src/tables/CursorPagerFooter/examples/RowsPerPage.tsx

@@ -0,0 +1,21 @@
+import { useState } from 'react';
+import { CursorPagerFooter } from '../CursorPagerFooter';
+
+export default function RowsPerPage() {
+  const [pageSize, setPageSize] = useState(25);
+  return (
+    <CursorPagerFooter
+      hasPrevious={false}
+      hasNext
+      busy
+      summary={null}
+      loadingLabel={null}
+      pageSize={pageSize}
+      pageSizeOptions={[10, 25, 50, 100]}
+      onPageSizeChange={setPageSize}
+      labels={{ rowsPerPage: 'Rows per page', rowsPerPageLabel: 'Rows per page' }}
+      onPrevious={() => {}}
+      onNext={() => {}}
+    />
+  );
+}

package/src/tables/CursorPagerFooter/fixtures.ts

@@ -0,0 +1,13 @@
+import type { CursorPaginationProps } from '@gntik-ai/ui';
+
+export const CURSOR_PAGER_PREVIEW = {
+  hasPrevious: false,
+  hasNext: true,
+  onPrevious: () => {},
+  onNext: () => {},
+  shownCount: 25,
+  labels: {
+    shownSummary: (shownCount: number) => `${shownCount} records shown`,
+    totalSummary: (total: number) => `${total} records in total`,
+  },
+} satisfies CursorPaginationProps;

package/src/tables/DataTable/DataTable.labels.test.tsx

@@ -0,0 +1,291 @@
+import { act, render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { I18nProvider } from '@gntik-ai/ui';
+import { DataTable } from './DataTable';
+import type { DataTableLabels } from './labels';
+
+const rows = [
+  { id: 'a', name: 'Alpha', region: 'West' },
+  { id: 'b', name: 'Beta', region: 'West' },
+];
+const columns = [
+  { id: 'name', header: 'Name', accessor: (r: (typeof rows)[number]) => r.name, width: 200 },
+  { id: 'region', header: 'Region', accessor: (r: (typeof rows)[number]) => r.region, width: 160 },
+];
+const labels = {
+  scrollRegion: 'Tabla con desplazamiento',
+  columns: 'Columnas',
+  visibleColumns: 'Columnas visibles',
+  pinColumns: 'Fijar columnas',
+  pinnedLeft: 'Izquierda',
+  pinnedRight: 'Derecha',
+  pinLeft: 'Fijar izquierda',
+  pinRight: 'Fijar derecha',
+  unpinned: 'Sin fijar',
+  density: 'Densidad',
+  comfortable: 'Cómoda',
+  compact: 'Compacta',
+  defaultView: 'Vista predeterminada',
+  defaultViewOption: 'Sin vista',
+  modified: '(modificada)',
+  views: 'Vistas',
+  saveChanges: 'Guardar cambios',
+  saveAs: 'Guardar como…',
+  renameView: 'Renombrar vista…',
+  deleteView: 'Eliminar vista',
+  resetChanges: 'Restablecer cambios',
+  saveViewTitle: 'Nueva vista',
+  renameViewTitle: 'Cambiar nombre',
+  viewName: 'Nombre de vista',
+  cancel: 'Cancelar',
+  saveView: 'Guardar vista',
+  rename: 'Renombrar',
+  closeDialog: 'Cerrar diálogo',
+  selectionCount: vi.fn((n: number) => `${n} seleccionadas`),
+  selectAll: 'Seleccionar página',
+  selection: 'Selección',
+  actions: 'Acciones',
+  selectRow: vi.fn((name: string) => `Seleccionar ${name}`),
+  rowActions: vi.fn((name: string) => `Acciones de ${name}`),
+  resizeColumn: vi.fn((name: string) => `Cambiar ancho de ${name}`),
+  columnWidth: vi.fn((width: number) => `${width} píxeles`),
+} satisfies Partial<DataTableLabels>;
+
+it('replaces table menus, selection announcements, resize names and saved-view dialogs', async () => {
+  const user = userEvent.setup();
+  const { container } = render(
+    <DataTable
+      rows={rows}
+      columns={columns}
+      caption="Items"
+      paginated={false}
+      resizable
+      showPinMenu
+      defaultViews={[]}
+      labels={labels}
+      rowActions={() => [{ label: 'Inspect', onClick: () => {} }]}
+    />,
+  );
+  expect(screen.getByRole('group', { name: 'Densidad' })).toBeVisible();
+  await user.click(screen.getByRole('button', { name: 'Compacta' }));
+  await user.click(screen.getByRole('button', { name: 'Cómoda' }));
+  expect(screen.getByRole('checkbox', { name: 'Seleccionar página' })).toBeVisible();
+  await user.click(screen.getByRole('checkbox', { name: 'Seleccionar Alpha' }));
+  expect(container.querySelector('[aria-live]')?.textContent).toBe('1 seleccionadas');
+  expect(labels.selectionCount).toHaveBeenLastCalledWith(1);
+  expect(labels.selectRow).toHaveBeenCalledWith('Alpha');
+  expect(screen.getByRole('button', { name: 'Acciones de Alpha' })).toBeVisible();
+  const handle = screen.getByRole('separator', { name: 'Cambiar ancho de Name' });
+  expect(handle).toHaveAttribute('aria-valuetext', '200 píxeles');
+  expect(labels.resizeColumn).toHaveBeenCalledWith('Name');
+  expect(labels.columnWidth).toHaveBeenCalledWith(200);
+  await user.click(screen.getByRole('button', { name: 'Columnas' }));
+  expect(await screen.findByText('Columnas visibles')).toBeVisible();
+  expect(screen.getByText('Fijar columnas')).toBeVisible();
+  await user.click(screen.getByRole('menuitemcheckbox', { name: 'Region' }));
+  await user.keyboard('{Escape}');
+  await user.click(screen.getByRole('button', { name: 'Vista predeterminada (modificada)' }));
+  expect(await screen.findByText('Vistas', { exact: true })).toBeVisible();
+  expect(screen.getByRole('menuitemradio', { name: 'Sin vista' })).toBeVisible();
+  for (const name of ['Guardar cambios', 'Renombrar vista…', 'Eliminar vista', 'Restablecer cambios'])
+    expect(screen.getByRole('menuitem', { name })).toBeVisible();
+  await user.click(screen.getByRole('menuitem', { name: 'Guardar como…' }));
+  expect(await screen.findByRole('dialog', { name: 'Nueva vista' })).toBeVisible();
+  expect(screen.getByRole('button', { name: 'Cerrar diálogo' })).toBeVisible();
+  await user.type(screen.getByRole('textbox', { name: 'Nombre de vista' }), 'My view');
+  await user.click(screen.getByRole('button', { name: 'Guardar vista' }));
+  await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
+  await user.click(screen.getByRole('button', { name: 'My view' }));
+  await user.click(await screen.findByRole('menuitem', { name: 'Renombrar vista…' }));
+  expect(await screen.findByRole('dialog', { name: 'Cambiar nombre' })).toBeVisible();
+  expect(screen.getByRole('button', { name: 'Renombrar' })).toBeVisible();
+  await user.click(screen.getByRole('button', { name: 'Cancelar' }));
+  await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
+});
+
+it('replaces group counts, ungrouped names, empty and loading states, and the nested footer', async () => {
+  const selectGroup = vi.fn((name: string) => `Todo en ${name}`);
+  const groupRows = vi.fn((count: number) => `filas: ${count}`);
+  const loading = vi.fn((caption: string) => `Cargando ${caption}`);
+  const extra: Partial<DataTableLabels> = {
+    selectGroup,
+    groupRows,
+    noGroup: 'Sin grupo',
+    emptyTitle: 'Sin resultados',
+    emptyDescription: 'Cambie los filtros',
+    loading,
+    rowsPerPage: 'Filas',
+    rowsPerPageLabel: 'Por página',
+    rangeSummary: (a, b, n) => `${a}/${b}/${n}`,
+    paginationNav: (noun) => `Páginas de ${noun}`,
+    previous: 'Atrás',
+    next: 'Adelante',
+    page: (n) => `Ir a ${n}`,
+  };
+  const { rerender } = render(
+    <DataTable rows={rows} columns={columns} groupBy={() => ''} labels={extra} caption="Items" />,
+  );
+  expect(screen.getByRole('checkbox', { name: 'Todo en Sin grupo' })).toBeVisible();
+  expect(screen.getByRole('button', { name: 'Sin grupo 2 filas: 2' })).toBeVisible();
+  expect(selectGroup).toHaveBeenCalledWith('Sin grupo');
+  expect(groupRows).toHaveBeenCalledWith(2);
+  expect(screen.getByRole('navigation', { name: 'Páginas de Items' })).toBeVisible();
+  expect(screen.getByRole('combobox', { name: 'Por página' })).toBeVisible();
+  expect(screen.getByText('1/2/2')).toBeVisible();
+  rerender(<DataTable rows={[]} columns={columns} labels={extra} caption="Items" />);
+  expect(screen.getByText('Sin resultados')).toBeVisible();
+  expect(screen.getByText('Cambie los filtros')).toBeVisible();
+  rerender(<DataTable rows={rows} columns={columns} labels={extra} caption="Items" loading />);
+  expect(screen.getByRole('status').textContent).toBe('Cargando Items');
+  expect(loading).toHaveBeenCalledWith('Items');
+});
+
+it('replaces built-in inline editor names, hints and validation errors', async () => {
+  const user = userEvent.setup();
+  const editLabel = vi.fn((column: string, row: string) => `${column} de ${row}`);
+  const minimumValue = vi.fn((n: number) => `Mínimo ${n}`);
+  const maximumValue = vi.fn((n: number) => `Máximo ${n}`);
+  const editable = [
+    {
+      id: 'name',
+      header: 'Name',
+      accessor: (r: (typeof rows)[number]) => r.name,
+      editable: true,
+      editor: { type: 'number' as const, min: 1, max: 10 },
+    },
+  ];
+  render(
+    <DataTable
+      rows={rows}
+      columns={editable}
+      paginated={false}
+      onCellEdit={() => false}
+      labels={{
+        editHint: 'Pulse Intro para editar',
+        editLabel,
+        editError: 'No se guardó',
+        enterNumber: 'Escriba un número',
+        minimumValue,
+        maximumValue,
+      }}
+    />,
+  );
+  expect(screen.getByRole('button', { name: 'Alpha' })).toHaveAccessibleDescription('Pulse Intro para editar');
+  await user.click(screen.getByRole('button', { name: 'Alpha' }));
+  const input = screen.getByRole('spinbutton', { name: 'Name de Alpha' });
+  expect(editLabel).toHaveBeenCalledWith('Name', 'Alpha');
+  await user.clear(input);
+  await user.type(input, '0{Enter}');
+  expect(await screen.findByRole('alert')).toHaveTextContent('Mínimo 1');
+  expect(minimumValue).toHaveBeenCalledWith(1);
+  await user.clear(input);
+  await user.type(input, '11{Enter}');
+  expect(screen.getByRole('alert')).toHaveTextContent('Máximo 10');
+  expect(maximumValue).toHaveBeenCalledWith(10);
+  await user.clear(input);
+  await user.type(input, '5{Enter}');
+  expect(await screen.findByText('No se guardó')).toBeVisible();
+});
+
+it('keeps provider translations and legacy literals under a partial override', () => {
+  const { container, rerender } = render(
+    <I18nProvider locale="es">
+      <DataTable rows={rows} columns={columns} paginated={false} defaultViews={[]} defaultSelectedIds={['a']} />
+    </I18nProvider>,
+  );
+  const table = container.querySelector('table')?.outerHTML;
+  const groupName = screen.getByRole('group').getAttribute('aria-label');
+  rerender(
+    <I18nProvider locale="es">
+      <DataTable
+        rows={rows}
+        columns={columns}
+        paginated={false}
+        defaultViews={[]}
+        defaultSelectedIds={['a']}
+        labels={{ defaultView: 'Custom view' }}
+      />
+    </I18nProvider>,
+  );
+  expect(container.querySelector('table')?.outerHTML).toBe(table);
+  expect(screen.getByRole('group')).toHaveAttribute('aria-label', groupName);
+  expect(screen.getByRole('button', { name: 'Custom view' })).toBeVisible();
+  expect(screen.getByText('1 selected')).toBeVisible();
+});
+
+it('retains the published text-node boundaries for default selection and loading summaries', () => {
+  const { container, rerender } = render(
+    <DataTable rows={rows} columns={columns} defaultSelectedIds={['a']} paginated={false} caption="Items" />,
+  );
+  expect([...container.querySelector('[aria-live]')!.childNodes].map((node) => node.textContent)).toEqual([
+    '1',
+    ' selected',
+  ]);
+  rerender(<DataTable rows={rows} columns={columns} loading caption="Items" />);
+  expect([...screen.getByRole('status').childNodes].map((node) => node.textContent)).toEqual([
+    'Loading ',
+    'items',
+    '…',
+  ]);
+});
+
+it('replaces every pin option and the single-selection heading without translating caller radio names', async () => {
+  const user = userEvent.setup({ pointerEventsCheck: 0 });
+  const full: DataTableLabels = {
+    ...labels,
+    selectGroup: (group) => `Grupo ${group}`,
+    groupRows: (count) => `${count} filas`,
+    noGroup: 'Sin grupo',
+    emptyTitle: 'Vacío',
+    emptyDescription: 'Sin coincidencias',
+    loading: (caption) => `Cargando ${caption}`,
+    editHint: 'Editar',
+    editLabel: (column, row) => `${column} de ${row}`,
+    editError: 'Error al guardar',
+    enterNumber: 'Número requerido',
+    minimumValue: (min) => `Mínimo ${min}`,
+    maximumValue: (max) => `Máximo ${max}`,
+    rowsPerPage: 'Filas por página',
+    rowsPerPageLabel: 'Elegir tamaño',
+    rangeSummary: (from, to, total) => `${from}|${to}|${total}`,
+    paginationNav: (noun) => `Páginas de ${noun}`,
+    previous: 'Anterior',
+    next: 'Siguiente',
+    page: (n) => `Página ${n}`,
+  };
+  const { rerender } = render(
+    <I18nProvider locale="es">
+      <DataTable rows={rows} columns={columns} paginated={false} showPinMenu labels={full} />
+    </I18nProvider>,
+  );
+  await user.click(screen.getByRole('button', { name: 'Columnas' }));
+  const submenu = await screen.findByRole('menuitem', { name: 'Name' });
+  act(() => submenu.focus());
+  await user.keyboard('{ArrowRight}');
+  for (const name of ['Fijar izquierda', 'Fijar derecha', 'Sin fijar'])
+    expect(await screen.findByRole('menuitemradio', { name })).toBeVisible();
+  await user.click(screen.getByRole('menuitemradio', { name: 'Fijar izquierda' }));
+  await waitFor(() => expect(screen.queryByRole('menu')).toBeNull());
+  await waitFor(() => expect(document.querySelector('[data-base-ui-focus-guard]')).toBeNull());
+  await user.click(screen.getByRole('button', { name: 'Columnas' }));
+  await screen.findByRole('menu');
+  expect(await screen.findByRole('menuitem', { name: /Name.*Izquierda/ })).toHaveAccessibleName('NameIzquierda');
+  act(() => screen.getByRole('menuitem', { name: /Name.*Izquierda/ }).focus());
+  await user.keyboard('{ArrowRight}');
+  await user.click(await screen.findByRole('menuitemradio', { name: 'Fijar derecha' }));
+  await waitFor(() => expect(screen.queryByRole('menu')).toBeNull());
+  await waitFor(() => expect(document.querySelector('[data-base-ui-focus-guard]')).toBeNull());
+  await user.click(screen.getByRole('button', { name: 'Columnas' }));
+  expect(await screen.findByRole('menuitem', { name: /Name.*Derecha/ })).toBeVisible();
+  await user.keyboard('{Escape}');
+  await waitFor(() => expect(screen.queryByRole('menu')).toBeNull());
+  await waitFor(() => expect(document.querySelector('[data-base-ui-focus-guard]')).toBeNull());
+  rerender(
+    <I18nProvider locale="es">
+      <DataTable rows={rows} columns={columns} labels={full} selectionMode="single" legend="Items" />
+    </I18nProvider>,
+  );
+  expect(screen.getByRole('columnheader', { name: 'Selección' })).toBeInTheDocument();
+  expect(screen.getByRole('radio', { name: 'Alpha' })).toBeVisible();
+  expect(screen.queryByRole('radio', { name: 'Seleccionar Alpha' })).toBeNull();
+});

package/src/tables/DataTable/DataTable.overflow-labels.test.tsx

@@ -0,0 +1,59 @@
+import { render, screen } from '@testing-library/react';
+import { I18nProvider } from '@gntik-ai/ui';
+import { DataTable } from './DataTable';
+
+beforeEach(() => {
+  // jsdom has no layout. Supply the browser geometry/notification boundary so the
+  // real Table overflow detection exposes its keyboard-focusable scroll region.
+  vi.spyOn(HTMLElement.prototype, 'scrollWidth', 'get').mockReturnValue(800);
+  vi.spyOn(HTMLElement.prototype, 'clientWidth', 'get').mockReturnValue(300);
+  vi.stubGlobal(
+    'ResizeObserver',
+    class {
+      constructor(private readonly notify: () => void) {}
+      observe() {
+        this.notify();
+      }
+      unobserve() {}
+      disconnect() {}
+    },
+  );
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+it.each([
+  ['en', 'Scrollable table'],
+  ['es', 'Tabla desplazable'],
+] as const)('labels the overflowing region per instance over the %s provider default', (locale, defaultName) => {
+  const { rerender } = render(
+    <I18nProvider locale={locale}>
+      <DataTable paginated={false} />
+    </I18nProvider>,
+  );
+  expect(screen.getByRole('region', { name: defaultName })).toHaveAttribute('tabindex', '0');
+  rerender(
+    <I18nProvider locale={locale}>
+      <DataTable paginated={false} labels={{ scrollRegion: 'Tabla con desplazamiento' }} />
+    </I18nProvider>,
+  );
+  expect(screen.getByRole('region', { name: 'Tabla con desplazamiento' })).toHaveAttribute('tabindex', '0');
+  expect(screen.queryByRole('region', { name: defaultName })).toBeNull();
+  rerender(
+    <I18nProvider locale={locale}>
+      <DataTable paginated={false} labels={{ columns: 'Elegir columnas' }} />
+    </I18nProvider>,
+  );
+  expect(screen.getByRole('region', { name: defaultName })).toHaveAttribute('tabindex', '0');
+});
+
+it('keeps the caller caption as the virtualized region name', () => {
+  render(
+    <DataTable paginated={false} virtualize caption="Items" labels={{ scrollRegion: 'Tabla con desplazamiento' }} />,
+  );
+  expect(screen.getByRole('region', { name: 'Items' })).toHaveAttribute('tabindex', '0');
+  expect(screen.queryByRole('region', { name: 'Tabla con desplazamiento' })).toBeNull();
+});

package/src/tables/DataTable/DataTable.server-pagination.test.tsx

@@ -0,0 +1,173 @@
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+import { DataTable, type DataTableProps } from './DataTable';
+import type { DataTableColumn } from './data-table-utils';
+
+type Row = { id: number; name: string; region: string };
+const rows: Row[] = Array.from({ length: 20 }, (_, i) => ({
+  id: 40 - i,
+  name: `Item ${40 - i}`,
+  region: i % 2 ? 'East' : 'West',
+}));
+const columns: DataTableColumn<Row>[] = [
+  { id: 'id', header: 'Id', accessor: (row) => row.id, sortable: true },
+  { id: 'name', header: 'Name', accessor: (row) => row.name, sortable: true },
+  { id: 'region', header: 'Region', accessor: (row) => row.region, sortable: true },
+];
+const server = {
+  paginationMode: 'server' as const,
+  selectionMode: 'none' as const,
+  rows,
+  columns,
+  caption: 'Items',
+  page: 2,
+  pageSize: 20,
+  rowCount: 95,
+  pageSizeOptions: [10, 20, 50],
+};
+const renderedIds = () =>
+  screen
+    .getAllByRole('row')
+    .slice(1)
+    .map((row) => within(row).getAllByRole('cell')[0]!.textContent);
+const summary = () => document.querySelector('[aria-live="polite"]');
+
+// @ts-expect-error Server pagination needs a known total.
+const missingTotal: DataTableProps<Row> = { paginationMode: 'server', page: 1, pageSize: 20 };
+// @ts-expect-error Server pagination cannot be combined with single selection.
+const singleServer: DataTableProps<Row> = { ...server, selectionMode: 'single', paginated: false };
+void missingTotal;
+void singleServer;
+
+describe('DataTable controlled server pagination', () => {
+  it('renders the supplied page in order and counts the full result set', () => {
+    render(<DataTable {...server} />);
+    expect(renderedIds()).toEqual([
+      '40',
+      '39',
+      '38',
+      '37',
+      '36',
+      '35',
+      '34',
+      '33',
+      '32',
+      '31',
+      '30',
+      '29',
+      '28',
+      '27',
+      '26',
+      '25',
+      '24',
+      '23',
+      '22',
+      '21',
+    ]);
+    expect(summary()).toHaveTextContent('21–40 of 95');
+    expect(screen.getByRole('button', { name: 'Page 2', current: 'page' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Page 5' })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Page 6' })).not.toBeInTheDocument();
+  });
+
+  it('requests 1-based pages once and waits for consumer updates', async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    const { rerender } = render(<DataTable {...server} onPageChange={onPageChange} />);
+    await user.click(screen.getByRole('button', { name: 'Next page' }));
+    expect(onPageChange.mock.calls).toEqual([[3]]);
+    await user.click(screen.getByRole('button', { name: 'Previous page' }));
+    expect(onPageChange.mock.calls).toEqual([[3], [1]]);
+    expect(screen.getByRole('button', { name: 'Page 2', current: 'page' })).toBeInTheDocument();
+    expect(summary()).toHaveTextContent('21–40 of 95');
+    expect(renderedIds()).toHaveLength(20);
+    rerender(<DataTable {...server} page={1} onPageChange={onPageChange} />);
+    expect(screen.getByRole('button', { name: 'Previous page' })).toBeDisabled();
+    rerender(<DataTable {...server} page={5} rows={rows.slice(0, 15)} onPageChange={onPageChange} />);
+    expect(screen.getByRole('button', { name: 'Next page' })).toBeDisabled();
+    expect(summary()).toHaveTextContent('81–95 of 95');
+    expect(renderedIds()).toHaveLength(15);
+    expect(onPageChange.mock.calls).toEqual([[3], [1]]);
+  });
+
+  it('requests a new size and only the footer keep-first-row page, without slicing', async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    const onPageSizeChange = vi.fn();
+    render(<DataTable {...server} onPageChange={onPageChange} onPageSizeChange={onPageSizeChange} />);
+    await user.click(screen.getByRole('combobox', { name: 'Rows per page' }));
+    await user.click(screen.getByRole('option', { name: '50' }));
+    expect(onPageSizeChange.mock.calls).toEqual([[50]]);
+    expect(onPageChange.mock.calls).toEqual([[1]]);
+    expect(renderedIds()).toHaveLength(20);
+    expect(summary()).toHaveTextContent('21–40 of 95');
+  });
+
+  it.each([false, true])('has inert headers even with controlled sort and resizable=%s', async (resizable) => {
+    const user = userEvent.setup();
+    const onSortChange = vi.fn();
+    render(
+      <DataTable
+        {...server}
+        resizable={resizable}
+        sort={{ columnId: 'id', direction: 'ascending' }}
+        onSortChange={onSortChange}
+      />,
+    );
+    const before = renderedIds();
+    for (const header of screen.getAllByRole('columnheader')) {
+      expect(header).not.toHaveAttribute('aria-sort');
+      expect(within(header).queryByRole('button')).not.toBeInTheDocument();
+      expect(header.querySelector('svg')).toBeNull();
+      await user.click(header);
+      fireEvent.keyDown(header, { key: 'Enter' });
+    }
+    expect(renderedIds()).toEqual(before);
+    expect(onSortChange).not.toHaveBeenCalled();
+  });
+
+  it('applying a sorted saved view does not request a sort or page', async () => {
+    const user = userEvent.setup();
+    const onSortChange = vi.fn();
+    const onPageChange = vi.fn();
+    render(
+      <DataTable
+        {...server}
+        defaultViews={[{ id: 'saved', name: 'Saved', state: { sort: { columnId: 'id', direction: 'ascending' } } }]}
+        onSortChange={onSortChange}
+        onPageChange={onPageChange}
+      />,
+    );
+    const before = renderedIds();
+    await user.click(screen.getByRole('button', { name: 'Default view' }));
+    await user.click(await screen.findByRole('menuitemradio', { name: 'Saved' }));
+    expect(renderedIds()).toEqual(before);
+    expect(onPageChange).not.toHaveBeenCalled();
+    expect(onSortChange).not.toHaveBeenCalled();
+    expect(summary()).toHaveTextContent('21–40 of 95');
+  });
+
+  it.each([1, 3])('keeps an empty server footer at page 1 without callbacks for supplied page %s', (page) => {
+    const onPageChange = vi.fn();
+    const onPageSizeChange = vi.fn();
+    render(
+      <DataTable
+        {...server}
+        rows={[]}
+        rowCount={0}
+        page={page}
+        onPageChange={onPageChange}
+        onPageSizeChange={onPageSizeChange}
+      />,
+    );
+    expect(screen.getByText('No results')).toBeInTheDocument();
+    expect(summary()).toHaveTextContent('0–0 of 0');
+    expect(screen.getByRole('button', { name: 'Page 1', current: 'page' })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Page 2' })).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Previous page' })).toBeDisabled();
+    expect(screen.getByRole('button', { name: 'Next page' })).toBeDisabled();
+    expect(onPageChange).not.toHaveBeenCalled();
+    expect(onPageSizeChange).not.toHaveBeenCalled();
+  });
+});