@gntik-ai/blocks 0.6.0 → 0.8.0

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

@@ -0,0 +1,33 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import CursorStack from './examples/CursorStack';
+import Busy from './examples/Busy';
+import Hidden from './examples/Hidden';
+import RowsPerPage from './examples/RowsPerPage';
+import { CursorPagerFooter } from './CursorPagerFooter';
+
+it('lets a consumer navigate its own opaque cursor stack without numbered table pagination', async () => {
+  const user = userEvent.setup();
+  render(<CursorStack />);
+  expect(screen.getByRole('cell', { name: 'Record A' })).toBeVisible();
+  await user.click(screen.getByRole('button', { name: 'Next page' }));
+  expect(screen.getByRole('cell', { name: 'Record B' })).toBeVisible();
+  await user.click(screen.getByRole('button', { name: 'Next page' }));
+  expect(screen.getByRole('cell', { name: 'Record C' })).toBeVisible();
+  expect(screen.getByRole('button', { name: 'Next page' })).toHaveAttribute('aria-disabled', 'true');
+  await user.click(screen.getByRole('button', { name: 'Previous page' }));
+  expect(screen.getByRole('cell', { name: 'Record B' })).toBeVisible();
+  expect(screen.getAllByRole('navigation')).toHaveLength(1);
+});
+
+for (const theme of ['dark', 'light', 'high_contrast']) {
+  it.each([CursorPagerFooter, CursorStack, Busy, Hidden, RowsPerPage])(
+    `footer examples have no axe violations in ${theme}: %s`,
+    async (Example) => {
+      document.documentElement.className = theme;
+      const { container } = render(<Example />);
+      await expectNoAxeViolations(container);
+    },
+  );
+}

package/src/tables/CursorPagerFooter/CursorPagerFooter.test.tsx

@@ -0,0 +1,51 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { CursorPagerFooter } from './CursorPagerFooter';
+
+describe('CursorPagerFooter', () => {
+  it('renders meaningful no-props fixtures for the catalogue', () => {
+    render(<CursorPagerFooter />);
+    expect(screen.getByRole('navigation', { name: 'Pagination' })).toBeVisible();
+    expect(screen.getByRole('status')).toHaveTextContent('25 records shown');
+    expect(screen.getByRole('button', { name: 'Previous page' })).toHaveAttribute('aria-disabled', 'true');
+  });
+
+  it('forwards navigation, count, labels, select, busy, summary and className props', async () => {
+    const user = userEvent.setup();
+    const onNext = vi.fn();
+    const props = {
+      hasPrevious: false,
+      hasNext: true,
+      onPrevious: vi.fn(),
+      onNext,
+      shownCount: 25,
+      total: 97,
+      pageSize: 25,
+      pageSizeOptions: [25, 50],
+      onPageSizeChange: vi.fn(),
+      unavailableBehaviour: 'hidden' as const,
+      previousLabel: 'Back',
+      nextLabel: 'Forward',
+      ariaLabel: 'Records',
+      labels: {
+        shownSummary: (n: number) => `${n} shown`,
+        totalSummary: (n: number) => `${n} exact`,
+        rowsPerPage: 'Response size',
+        rowsPerPageLabel: 'Choose size',
+      },
+      className: 'gap-4',
+    };
+    const { rerender } = render(<CursorPagerFooter {...props} />);
+    expect(screen.getByRole('navigation', { name: 'Records' })).toHaveClass('gap-4');
+    expect(screen.queryByRole('button', { name: 'Back' })).not.toBeInTheDocument();
+    expect(screen.getByRole('status')).toHaveTextContent('97 exact');
+    expect(screen.getByRole('combobox', { name: 'Choose size' })).toHaveTextContent('25');
+    await user.click(screen.getByRole('button', { name: 'Forward' }));
+    expect(onNext).toHaveBeenCalledExactlyOnceWith();
+    rerender(<CursorPagerFooter {...props} loading loadingLabel="Fetching" />);
+    expect(screen.getByRole('status')).toHaveTextContent('Fetching');
+    expect(screen.getByRole('button', { name: 'Forward' })).toHaveAttribute('aria-busy', 'true');
+    rerender(<CursorPagerFooter {...props} busy summary={null} loadingLabel={null} />);
+    expect(screen.getByRole('status')).toBeEmptyDOMElement();
+  });
+});

package/src/tables/CursorPagerFooter/CursorPagerFooter.tsx

@@ -0,0 +1,10 @@
+import { CursorPagination, type CursorPaginationProps } from '@gntik-ai/ui';
+import { CURSOR_PAGER_PREVIEW } from './fixtures';
+
+/** The complete CursorPaginationProps contract, or no props for the fixture preview. */
+export type CursorPagerFooterProps = CursorPaginationProps | { [K in keyof CursorPaginationProps]?: never };
+
+/** Responsive table footer. Forwards every cursor-pagination prop without storing cursor state. */
+export function CursorPagerFooter(props: CursorPagerFooterProps = {}) {
+  return <CursorPagination {...(props.hasPrevious === undefined ? CURSOR_PAGER_PREVIEW : props)} />;
+}

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.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();
+  });
+});

package/src/tables/DataTable/DataTable.tsx

@@ -93,6 +93,12 @@ export function DataTable<T = (typeof DEPLOYMENT_ROWS)[number]>({
   onSortChange,
   manualSorting = false,
   paginated: paginatedProp,
+  paginationMode = 'client',
+  rowCount,
+  page: controlledPage,
+  pageSize: controlledPageSize,
+  onPageChange,
+  onPageSizeChange,
   defaultPageSize = 10,
   pageSizeOptions = [10, 25, 50],
   density: densityProp,
@@ -140,6 +146,7 @@ export function DataTable<T = (typeof DEPLOYMENT_ROWS)[number]>({
 }: DataTableProps<T>) {
   const { t } = useI18n();
   const singleMode = selectionMode === 'single';
+  const serverMode = paginationMode === 'server';
   const selectable = selectionMode === undefined ? selectableProp : selectionMode === 'multiple';
   const selectionColumn = selectable || singleMode;
   const paginated = !singleMode && (paginatedProp ?? true);
@@ -198,10 +205,10 @@ export function DataTable<T = (typeof DEPLOYMENT_ROWS)[number]>({
   const [innerCollapsed, setInnerCollapsed] = useState<ReadonlySet<string>>(() => new Set(defaultCollapsedGroups));
   const collapsed: ReadonlySet<string> = collapsedProp ? new Set(collapsedProp) : innerCollapsed;
 
-  const sortedRows = manualSorting ? [...rows] : sortRows(rows, columns, sort);
+  const sortedRows = serverMode ? rows : manualSorting ? [...rows] : sortRows(rows, columns, sort);
   const allGroups = effectiveGroupBy ? groupRows(sortedRows, effectiveGroupBy, rows) : null;
   const sorted = allGroups ? allGroups.flatMap((g) => g.rows) : sortedRows;
-  const pageRows = paginated ? paginate(sorted, page, pageSize) : sorted;
+  const pageRows = serverMode ? rows : paginated ? paginate(sorted, page, pageSize) : sorted;
   // Rows in collapsed groups are hidden, so select-all leaves them alone.
   const pageIds = (
     effectiveGroupBy ? pageRows.filter((row) => !collapsed.has(groupKeyOf(row, effectiveGroupBy))) : pageRows
@@ -214,6 +221,7 @@ export function DataTable<T = (typeof DEPLOYMENT_ROWS)[number]>({
     onSelectionChange?.(rows.map(getRowId).filter((id) => next.has(id)));
   };
   const changeSort = (columnId: string, direction: SortState['direction']) => {
+    if (serverMode) return;
     const next: SortState = { columnId, direction: sort?.columnId === columnId ? direction : 'ascending' };
     setInnerSort(next);
     onSortChange?.(next);
@@ -293,7 +301,7 @@ export function DataTable<T = (typeof DEPLOYMENT_ROWS)[number]>({
   const applyState = (state: DataTableViewState) => {
     const nextSort = state.sort ?? null;
     setInnerSort(nextSort);
-    if (nextSort) onSortChange?.(nextSort);
+    if (nextSort && !serverMode) onSortChange?.(nextSort);
     setHiddenList(state.hiddenColumns ?? defaultHidden);
     setWidths(state.columnWidths ?? defaultColumnWidths);
     setPinned(state.pinnedColumns ?? defaultPinnedColumns);
@@ -301,7 +309,7 @@ export function DataTable<T = (typeof DEPLOYMENT_ROWS)[number]>({
     setGroupOverride(nextGroup === groupName(groupBy) && typeof groupBy !== 'function' ? undefined : nextGroup);
     if (nextGroup !== currentState.groupBy) onGroupByChange?.(nextGroup);
     if (state.filters !== filters) onFiltersChange?.(state.filters);
-    setPage(1);
+    if (!serverMode) setPage(1);
   };
   const viewsApi = useTableViews({
     views: viewsProp,
@@ -449,9 +457,9 @@ export function DataTable<T = (typeof DEPLOYMENT_ROWS)[number]>({
                     <DataTableHeadCell
                       labels={labels}
                       key={c.id}
-                      column={c}
+                      column={serverMode ? { ...c, sortable: false } : c}
                       layout={layout.columns.get(c.id)}
-                      sortDirection={sort?.columnId === c.id ? sort.direction : 'none'}
+                      sortDirection={!serverMode && sort?.columnId === c.id ? sort.direction : 'none'}
                       onSortChange={(dir) => changeSort(c.id, dir)}
                       resize={
                         resizable && c.resizable !== false
@@ -513,15 +521,15 @@ export function DataTable<T = (typeof DEPLOYMENT_ROWS)[number]>({
           {labels?.loading ? labels.loading(caption) : <>Loading {caption.toLowerCase()}…</>}
         </p>
       )}
-      {paginated && !loading && rows.length > 0 && (
+      {paginated && !loading && (serverMode || rows.length > 0) && (
         <PaginationFooter
           labels={labels}
           className="border-t border-border px-4 py-3"
-          total={rows.length}
-          page={page}
-          onPageChange={setPage}
-          pageSize={pageSize}
-          onPageSizeChange={setPageSize}
+          total={serverMode ? rowCount : rows.length}
+          page={serverMode ? controlledPage : page}
+          onPageChange={serverMode ? onPageChange : setPage}
+          pageSize={serverMode ? controlledPageSize : pageSize}
+          onPageSizeChange={serverMode ? onPageSizeChange : setPageSize}
           pageSizeOptions={pageSizeOptions}
           noun={caption}
         />

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

@@ -8,7 +8,8 @@ export const meta: BlockMeta = {
   description:
     'Generic typed table: sortable headers with aria-sort, row selection with select-all and indeterminate by default (selectionMode="multiple"), selectionMode="none" to hide selection, column visibility menu, density toggle, row actions, loading and empty states, client-side sort and pagination, optional row groups (groupBy) with rowgroup header rows, counts, keyboard-accessible collapse buttons and group selection; column resize (pointer drag or a focusable role="separator" handle with arrow keys, min/max widths, controlled columnWidths), column pinning to either edge with sticky cells (column menu or pinnedColumns), row virtualization for large datasets (aria-rowcount/aria-rowindex, works with selection and grouping), inline cell editing (text, number and select editors; Enter/F2 to edit, Enter/Tab to commit, Escape to cancel, onCellEdit can reject with an inline error) and saved views (filters, sort, visible columns, widths, pinning and grouping) with a view switcher to save as, rename, delete and reset. ' +
     'Opt-in selectionMode="single" uses native radios in a labelled fieldset (never paginated or virtualized; paginated defaults to false and paginated=true is a type error). Single mode uses selectedId/onSelectedIdChange or defaultSelectedId; isRowDisabled skips unavailable rows and preserves a checked disabled choice without callbacks. Supply legend, aria-label or aria-labelledby for the group and getRowLabel for each radio (otherwise the first column labels it). selectionName is used verbatim and must be unique per page; omitted names use an instance-unique useId name, and duplicate supplied names or missing group labels warn in development. Tab enters once on the checked enabled row or first enabled row; arrows wrap and skip disabled rows, Space selects, Shift+Tab exits, and all-disabled groups have no tab stop. No select-all, group checkboxes, bulk actions or selection summary appear in single mode. ' +
-    'Examples in examples/single-selection.tsx: an uncontrolled non-paginated list with legend="Available items" and a controlled versions table with legend="Available versions", selectedId="v2" and a checked disabled version.',
+    'Examples in examples/single-selection.tsx: an uncontrolled non-paginated list with legend="Available items" and a controlled versions table with legend="Available versions", selectedId="v2" and a checked disabled version. ' +
+    'Opt-in paginationMode="server" accepts a controlled 1-based page, pageSize and required rowCount (known total), with onPageChange/onPageSizeChange requests. Supplied rows render in order without client sorting or slicing, and headers have no sort affordance. Single selection cannot use server mode. The footer stays visible for empty results, clamps stale pages for display without callbacks, and hides during loading. Page-size changes may also request a page to keep the first visible row on screen. The consumer owns fetching and reconciles stale pages. See examples/server-pagination.tsx for an items/total/page/pageSize envelope consumer that handles both callbacks.',
 
   labels: [
     {

package/src/tables/DataTable/data-table-props.ts

@@ -139,21 +139,44 @@ interface DataTableCommonProps<T> {
   className?: string;
 }
 
+interface ClientPaginationProps {
+  paginationMode?: 'client';
+  rowCount?: never;
+  page?: never;
+  pageSize?: never;
+  onPageChange?: never;
+  onPageSizeChange?: never;
+}
+
+interface ServerPaginationProps {
+  /** Rows arrive as one server page: no client sorting or slicing, and no sortable headers. */
+  paginationMode: 'server';
+  /** Total number of rows across all pages; required even for an empty result. */
+  rowCount: number;
+  /** Current page, 1-based. Out-of-range pages are clamped for display without callbacks. */
+  page: number;
+  pageSize: number;
+  onPageChange?: (page: number) => void;
+  /** The footer may also request a page change to keep the first visible row on screen. */
+  onPageSizeChange?: (size: number) => void;
+}
+
 export type DataTableProps<T> = DataTableCommonProps<T> &
   (
-    | {
+    | ({
         selectionMode: 'single';
         paginated?: false;
         /** Consumer-supplied accessible group label; the kit adds no default. */
         legend?: ReactNode;
         'aria-label'?: string;
         'aria-labelledby'?: string;
-      }
-    | {
+        paginationMode?: never;
+      } & ClientPaginationProps)
+    | ({
         selectionMode?: 'none' | 'multiple';
         paginated?: boolean;
         legend?: never;
         'aria-label'?: never;
         'aria-labelledby'?: never;
-      }
+      } & (ClientPaginationProps | ServerPaginationProps))
   );

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

@@ -0,0 +1,68 @@
+import { useEffect, useState } from 'react';
+import { DataTable } from '../DataTable';
+
+interface Item {
+  id: number;
+  name: string;
+}
+interface Envelope {
+  items: Item[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+const columns = [
+  { id: 'id', header: 'Id', accessor: (row: Item) => row.id },
+  { id: 'name', header: 'Name', accessor: (row: Item) => row.name },
+];
+
+// Demo endpoint adapter. Replace with the consumer's API returning this envelope.
+function readPage(page: number, pageSize: number): Envelope {
+  const total = 95;
+  const from = (page - 1) * pageSize;
+  return {
+    items: Array.from({ length: Math.max(0, Math.min(pageSize, total - from)) }, (_, i) => ({
+      id: from + i + 1,
+      name: `Item ${from + i + 1}`,
+    })),
+    total,
+    page,
+    pageSize,
+  };
+}
+async function requestPage(page: number, pageSize: number): Promise<Envelope> {
+  return readPage(page, pageSize);
+}
+
+/** Known-total, 1-based pages. The consumer owns requests and keeps the old envelope until they resolve. */
+export default function ServerPaginationExample() {
+  const [envelope, setEnvelope] = useState(() => readPage(2, 20));
+  const [request, setRequest] = useState({ page: 2, pageSize: 20 });
+  useEffect(() => {
+    let active = true;
+    void requestPage(request.page, request.pageSize).then((next) => {
+      if (active) setEnvelope(next);
+    });
+    return () => {
+      active = false;
+    };
+  }, [request]);
+
+  return (
+    <DataTable
+      caption="Items"
+      selectionMode="none"
+      columns={columns}
+      rows={envelope.items}
+      paginationMode="server"
+      rowCount={envelope.total}
+      page={envelope.page}
+      pageSize={envelope.pageSize}
+      pageSizeOptions={[10, 20, 50]}
+      onPageChange={(page) => setRequest((previous) => ({ ...previous, page }))}
+      // The footer can also call onPageChange to keep the first row visible (20 to 50 at page 2 requests page 1).
+      // Functional updates batch both callbacks into one request with the new size and page.
+      onPageSizeChange={(pageSize) => setRequest((previous) => ({ ...previous, pageSize }))}
+    />
+  );
+}