@gemologic/sheen-table 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/dist/DataTable.d.ts +57 -13
  2. package/dist/DataTable.js +963 -820
  3. package/dist/FilterBar.d.ts +3 -3
  4. package/dist/FilterBar.js +5 -1
  5. package/dist/client-state.d.ts +9 -3
  6. package/dist/client-state.js +38 -32
  7. package/dist/core.d.ts +5 -5
  8. package/dist/core.js +28 -28
  9. package/dist/data-table-features.d.ts +18 -13
  10. package/dist/data-table-features.js +11 -1
  11. package/dist/index.d.ts +5 -3
  12. package/dist/index.js +32 -31
  13. package/dist/messages.d.ts +3 -0
  14. package/dist/messages.js +3 -0
  15. package/dist/pagination.d.ts +43 -1
  16. package/dist/pagination.js +109 -54
  17. package/dist/requests.d.ts +3 -3
  18. package/dist/requests.js +38 -28
  19. package/dist/saved-views.d.ts +17 -14
  20. package/dist/saved-views.js +71 -68
  21. package/dist/server-export.d.ts +16 -7
  22. package/dist/server-export.js +57 -53
  23. package/dist/table-state-changes.d.ts +6 -3
  24. package/dist/table-state-changes.js +44 -40
  25. package/dist/table-state.d.ts +20 -4
  26. package/dist/table-state.js +66 -40
  27. package/dist/url-state.d.ts +12 -9
  28. package/dist/url-state.js +33 -30
  29. package/package.json +3 -3
  30. package/src/DataTable.tsx +221 -61
  31. package/src/FilterBar.tsx +5 -3
  32. package/src/client-state.ts +31 -17
  33. package/src/core.ts +5 -5
  34. package/src/data-table-features.tsx +23 -10
  35. package/src/index.ts +5 -3
  36. package/src/messages.ts +1 -1
  37. package/src/pagination.ts +83 -14
  38. package/src/requests.ts +22 -8
  39. package/src/saved-views.ts +33 -11
  40. package/src/server-export.ts +17 -11
  41. package/src/table-state-changes.ts +22 -12
  42. package/src/table-state.ts +53 -11
  43. package/src/url-state.ts +27 -10
package/src/DataTable.tsx CHANGED
@@ -1,10 +1,11 @@
1
1
  import { Button, Checkbox, ContextMenu, DropdownMenu, EmptyState, Glyph, Pagination, SearchInput, Skeleton, flashChange, useTheme } from "@gemologic/sheen";
2
- import type { MenuItem, ShortcutAction } from "@gemologic/sheen";
2
+ import type { GlyphName, MenuItem, ShortcutAction } from "@gemologic/sheen";
3
3
  import { createVirtualizer } from "@tanstack/solid-virtual";
4
4
  import type { VirtualItem } from "@tanstack/solid-virtual";
5
5
  import { For, Index, Show, createComputed, createEffect, createMemo, createSignal, createUniqueId, on, onCleanup, onMount, untrack } from "solid-js";
6
6
  import type { Accessor, JSX, Signal } from "solid-js";
7
- import { changeTableState } from "./table-state-changes.ts";
7
+ import { changeTableStateWith } from "./table-state-changes.ts";
8
+ import type { TableStateChange } from "./table-state-changes.ts";
8
9
  import { canMoveColumn, moveColumn, orderColumnStates, placeColumn } from "./column-layout.ts";
9
10
  import { constrainedColumnValues, summarizedColumns } from "./constrained-columns.ts";
10
11
  import type { ColumnDropPlacement, ColumnMoveDirection } from "./column-layout.ts";
@@ -14,14 +15,14 @@ import { createClientView } from "./client-view.ts";
14
15
  import type { ClientView } from "./client-view.ts";
15
16
  import { formatSearchQuery, parseSearchQuery } from "./search.ts";
16
17
  import type { SearchMode } from "./search.ts";
17
- import { getPageRange, resolvePagination } from "./pagination.ts";
18
- import type { PageResult, TablePagination } from "./pagination.ts";
18
+ import { getPageRange, parseServerPagination, resetPagination, resolvePagination } from "./pagination.ts";
19
+ import type { CursorPageResult, CursorPagination, CursorPosition, CursorTotal, PageResult, ServerPagination, TablePagination } from "./pagination.ts";
19
20
  import type { ServerRowGroup } from "./grouping.ts";
20
21
  import { createTableRequests } from "./requests.ts";
21
22
  import type { TableRequestOutcome } from "./requests.ts";
22
23
  import { createTableSelection } from "./selection.ts";
23
24
  import type { BulkSelection } from "./selection.ts";
24
- import { parseTableState, serializeState } from "./table-state.ts";
25
+ import { parseTableStateWith } from "./table-state.ts";
25
26
  import type { ColumnState, TableState } from "./table-state.ts";
26
27
  import { filterBarFeature } from "./FilterBar.tsx";
27
28
  import { DataTableToolbar } from "./DataTableToolbar.tsx";
@@ -30,12 +31,12 @@ import { parseFilter, serializeFilter } from "./filter.ts";
30
31
  import type { FilterNode } from "./filter.ts";
31
32
  import type { FilterDateEditor } from "./FilterBar.tsx";
32
33
  import { selectClientRows } from "./selection-client.ts";
33
- import { createServerExport } from "./server-export.ts";
34
+ import { createServerExportWith } from "./server-export.ts";
34
35
  import type { ServerExportOutcome, TableExportRequest } from "./server-export.ts";
35
36
  import type { CellCommitRequest, CellCommitResult } from "./cell-edit.ts";
36
37
  import { resolveTableMessages } from "./messages.ts";
37
38
  import { cellEditingFeature, createSnapshotSignal, createStableRows, defaultCell, groupingFeature, hierarchyFeature } from "./data-table-features.tsx";
38
- import type { DataTableCellAttributes, DataTableCellBinding, DataTableFeature, DataTableFeatureContext, DataTablePresentation, DisplayDataRow, DisplayGroupRow, DisplayRow, StableRow } from "./data-table-features.tsx";
39
+ import type { DataTableCellAttributes, DataTableCellBinding, DataTableFeature, DataTableFeatureContext, DataTableFeatureId, DataTablePresentation, DisplayDataRow, DisplayGroupRow, DisplayRow, StableRow } from "./data-table-features.tsx";
39
40
 
40
41
  export interface DataTableResult<Row extends object> extends PageResult<Row> {
41
42
  readonly facets?: Readonly<Record<string, Readonly<Record<string, number>>>>;
@@ -43,6 +44,15 @@ export interface DataTableResult<Row extends object> extends PageResult<Row> {
43
44
  readonly groups?: readonly ServerRowGroup[];
44
45
  }
45
46
 
47
+ /** One cursor page. Either cursor may be null; total is optional and may be an estimate or lower bound. */
48
+ export interface DataTableCursorResult<Row extends object> extends CursorPageResult<Row> {
49
+ readonly facets?: Readonly<Record<string, Readonly<Record<string, number>>>>;
50
+ }
51
+
52
+ /** The request state for a pagination prop: cursor props produce cursor state, everything else numbered or complete state. */
53
+ type DataTableServerPagination<Pagination extends ServerPagination> = Pagination extends CursorPagination ? CursorPagination : TablePagination;
54
+ type DataTableServerResult<Row extends object, Pagination extends ServerPagination> = Pagination extends CursorPagination ? DataTableCursorResult<Row> : DataTableResult<Row>;
55
+
46
56
  export interface DataTableInitialState {
47
57
  readonly search?: string;
48
58
  readonly filter?: TableState["filter"];
@@ -150,7 +160,6 @@ interface DataTableBaseProps<Row extends object> {
150
160
  readonly variant?: DataTableVariant;
151
161
  /** Optional local density for table chrome and rows. Omission inherits the surrounding application density. */
152
162
  readonly density?: DataTableDensity;
153
- readonly pagination?: TablePagination;
154
163
  readonly initialState?: DataTableInitialState;
155
164
  /** Reactively applies an app-owned accepted filter. Use onAcceptedStateChange to keep table-authored changes synchronized. */
156
165
  readonly filter?: FilterNode;
@@ -160,7 +169,6 @@ interface DataTableBaseProps<Row extends object> {
160
169
  readonly estimatedRowHeight?: number;
161
170
  readonly initialViewportHeight?: number;
162
171
  readonly class?: string;
163
- readonly onAcceptedStateChange?: (state: TableState) => void;
164
172
  readonly onRowActivate?: (row: Row) => void;
165
173
  readonly selection?: DataTableSelectionOptions<Row>;
166
174
  /** One action model rendered in both the selection bar and each row context menu. */
@@ -188,25 +196,48 @@ interface DataTableBaseProps<Row extends object> {
188
196
  export interface ClientDataTableProps<Row extends object> extends DataTableBaseProps<Row> {
189
197
  readonly mode?: "client";
190
198
  readonly data: readonly Row[];
199
+ readonly pagination?: TablePagination;
200
+ readonly onAcceptedStateChange?: (state: TableState) => void;
191
201
  readonly initialResult?: never;
192
202
  readonly onStateChange?: never;
193
203
  readonly onExport?: never;
194
204
  readonly refreshKey?: never;
195
205
  }
196
206
 
197
- export interface ServerDataTableProps<Row extends object> extends DataTableBaseProps<Row> {
207
+ /** Pagination is false, numbered `{ pageIndex, pageSize }`, or `{ kind: "cursor", pageSize, cursor }`; its kind selects the result contract. */
208
+ export interface ServerDataTableProps<Row extends object, Pagination extends ServerPagination = TablePagination> extends DataTableBaseProps<Row> {
198
209
  readonly mode: "server";
199
- readonly pagination: TablePagination;
210
+ readonly pagination: Pagination;
211
+ readonly onAcceptedStateChange?: (state: TableState<DataTableServerPagination<Pagination>>) => void;
200
212
  readonly data?: never;
201
- readonly initialResult?: DataTableResult<Row>;
202
- readonly onStateChange: (state: TableState, signal: AbortSignal) => Promise<DataTableResult<Row>>;
213
+ readonly initialResult?: DataTableServerResult<Row, Pagination>;
214
+ readonly onStateChange: (state: TableState<DataTableServerPagination<Pagination>>, signal: AbortSignal) => Promise<DataTableServerResult<Row, Pagination>>;
203
215
  /** Change to revalidate the latest requested/accepted query without resetting layout or scroll. Initial value does not fetch. */
204
216
  readonly refreshKey?: string | number;
205
217
  /** Creates a complete server-side export for the captured accepted query and selection. Without this adapter, export UI is hidden. */
206
- readonly onExport?: (request: TableExportRequest, signal: AbortSignal) => Promise<Blob>;
218
+ readonly onExport?: (request: TableExportRequest<DataTableServerPagination<Pagination>>, signal: AbortSignal) => Promise<Blob>;
207
219
  }
208
220
 
209
- export type DataTableProps<Row extends object> = ClientDataTableProps<Row> | ServerDataTableProps<Row>;
221
+ export type DataTableProps<Row extends object, Pagination extends ServerPagination = TablePagination> = ClientDataTableProps<Row> | ServerDataTableProps<Row, Pagination>;
222
+
223
+ /**
224
+ * The composition root erases the server pagination kind. Method signatures accept every public pairing;
225
+ * parseServerPagination and per-response assessment enforce that state and results keep the configured kind.
226
+ */
227
+ interface ErasedClientProps<Row extends object> extends Omit<ClientDataTableProps<Row>, "onAcceptedStateChange"> {
228
+ onAcceptedStateChange?(state: TableState<ServerPagination>): void;
229
+ }
230
+ interface ErasedServerProps<Row extends object> extends DataTableBaseProps<Row> {
231
+ readonly mode: "server";
232
+ readonly pagination: ServerPagination;
233
+ readonly data?: never;
234
+ readonly initialResult?: DataTableResult<Row> | DataTableCursorResult<Row>;
235
+ readonly refreshKey?: string | number;
236
+ onAcceptedStateChange?(state: TableState<ServerPagination>): void;
237
+ onStateChange(state: TableState<ServerPagination>, signal: AbortSignal): Promise<DataTableResult<Row> | DataTableCursorResult<Row>>;
238
+ onExport?(request: TableExportRequest<ServerPagination>, signal: AbortSignal): Promise<Blob>;
239
+ }
240
+ export type DataTableInternalProps<Row extends object> = ErasedClientProps<Row> | ErasedServerProps<Row>;
210
241
 
211
242
  interface ScrollAnchor {
212
243
  readonly id: string;
@@ -346,17 +377,32 @@ function clientFacetRecord<Row>(view: ClientView<Row>): Readonly<Record<string,
346
377
  return Object.freeze(result);
347
378
  }
348
379
 
349
- function initialTableState<Row extends object>(props: DataTableProps<Row>): TableState {
380
+ function cursorPagination(value: ServerPagination): value is CursorPagination {
381
+ return value !== false && "kind" in value;
382
+ }
383
+
384
+ function cursorResult<Row extends object>(value: DataTableResult<Row> | DataTableCursorResult<Row>): value is DataTableCursorResult<Row> {
385
+ return "nextCursor" in value;
386
+ }
387
+
388
+ /** Client processing runs only on numbered or complete state. */
389
+ function numberedState(state: TableState<ServerPagination>): TableState {
390
+ const pagination = state.pagination;
391
+ if (cursorPagination(pagination)) throw new Error("Cursor pagination requires server mode");
392
+ return { ...state, pagination };
393
+ }
394
+
395
+ function initialTableState<Row extends object>(props: DataTableInternalProps<Row>): TableState<ServerPagination> {
350
396
  const schema = columnStateSchema(props.columns);
351
397
  const definitions = readColumnDefinitions(props.columns);
352
- const pagination = resolvePagination(props.mode ?? "client", props.pagination);
353
- const state = parseTableState({
398
+ const pagination = props.mode === "server" ? parseServerPagination(props.pagination) : resolvePagination("client", props.pagination);
399
+ const state = parseTableStateWith({
354
400
  search: props.initialState?.search ?? "",
355
401
  filter: props.filter ?? props.initialState?.filter ?? { kind: "and", children: [] },
356
402
  sorting: props.initialState?.sorting ?? [],
357
403
  pagination,
358
404
  columns: props.initialState?.columns ?? definitions.map(column => ({ id: column.id, visible: column.visible, width: typeof column.width === "number" ? column.width : null, pin: column.pin })),
359
- }, schema);
405
+ }, schema, parseServerPagination);
360
406
  for (const columnState of state.columns) {
361
407
  const definition = definitions.find(column => column.id === columnState.id);
362
408
  if (!definition) throw new Error(`Unknown table column: ${columnState.id}`);
@@ -374,6 +420,16 @@ function samePagination(left: TablePagination, right: TablePagination): boolean
374
420
  return left === false ? right === false : right !== false && left.pageIndex === right.pageIndex && left.pageSize === right.pageSize;
375
421
  }
376
422
 
423
+ function cursorKey(cursor: CursorPosition): string {
424
+ return `${cursor.direction}:${cursor.value}`;
425
+ }
426
+
427
+ interface CursorStep {
428
+ readonly label: "firstPage" | "previousPage" | "nextPage";
429
+ readonly glyph: GlyphName;
430
+ readonly target: CursorPosition | null | undefined;
431
+ }
432
+
377
433
  function columnTrack(width: number | "fill" | "content", minimum: number | null, maximum: number | null): string {
378
434
  const min = minimum ?? 80;
379
435
  if (typeof width === "number") return `${width}px`;
@@ -385,12 +441,48 @@ function clampColumnWidth(value: number, minimum: number | null, maximum: number
385
441
  return Math.min(maximum ?? 4096, Math.max(minimum ?? 80, Math.round(value)));
386
442
  }
387
443
 
388
- export function DataTable<Row extends object>(props: DataTableProps<Row>): JSX.Element {
444
+ export function DataTable<Row extends object, Pagination extends ServerPagination = TablePagination>(props: DataTableProps<Row, Pagination>): JSX.Element {
389
445
  return renderDataTable(props, [filterBarFeature, groupingFeature, hierarchyFeature, cellEditingFeature]);
390
446
  }
391
447
 
392
- /** Internal composition root. Features own their props, state, and rendering hooks; omitted features are not bundled. */
393
- export function renderDataTable<Row extends object>(props: DataTableProps<Row>, features: readonly DataTableFeature[]): JSX.Element {
448
+ /** Props owned by each opt-in feature. A composition without the feature rejects them at compile time and at render. */
449
+ interface DataTableFeatureProps {
450
+ readonly filterBar: "filterBar";
451
+ readonly grouping: "grouping";
452
+ readonly hierarchy: "hierarchy";
453
+ readonly cellEditing: "onCellCommit" | "editResetKey";
454
+ }
455
+ /** DataTable props for a composition that includes only the features named by `Id`. */
456
+ export type ComposedDataTableProps<Row extends object, Id extends DataTableFeatureId, Pagination extends ServerPagination = TablePagination> =
457
+ DataTableProps<Row, Pagination> & { readonly [Key in DataTableFeatureProps[Exclude<DataTableFeatureId, Id>]]?: never };
458
+ export type ComposedDataTable<Id extends DataTableFeatureId> = <Row extends object, Pagination extends ServerPagination = TablePagination>(props: ComposedDataTableProps<Row, Id, Pagination>) => JSX.Element;
459
+
460
+ /**
461
+ * A DataTable that bundles only the listed features. `createDataTable([])` is the lightest table; `DataTable`
462
+ * is the same composition with every feature.
463
+ */
464
+ export function createDataTable<const Features extends readonly DataTableFeature[]>(features: Features): ComposedDataTable<Features[number]["id"]> {
465
+ const composed: DataTableFeature[] = [];
466
+ for (const feature of features) {
467
+ if (typeof feature !== "object" || feature === null || typeof feature.create !== "function") throw new Error("createDataTable accepts only Sheen DataTable features");
468
+ if (composed.some(existing => existing.id === feature.id)) throw new Error(`DataTable feature ${feature.id} is listed more than once`);
469
+ composed.push(feature);
470
+ }
471
+ return props => renderDataTable(props, composed);
472
+ }
473
+
474
+ function requireFeatures<Row extends object>(props: DataTableInternalProps<Row>, definitions: readonly { readonly editor: unknown }[], features: readonly DataTableFeature[]): void {
475
+ const missing = (id: DataTableFeatureId, used: boolean, prop: string): void => {
476
+ if (used && !features.some(feature => feature.id === id)) throw new Error(`DataTable ${prop} requires the ${id}Feature; add it to createDataTable or use DataTable`);
477
+ };
478
+ missing("filterBar", props.filterBar !== undefined && props.filterBar !== false, "filterBar");
479
+ missing("grouping", props.grouping !== undefined, "grouping");
480
+ missing("hierarchy", props.hierarchy !== undefined, "hierarchy");
481
+ missing("cellEditing", props.onCellCommit !== undefined || props.editResetKey !== undefined || definitions.some(column => column.editor !== null), "cell editing");
482
+ }
483
+
484
+ /** Internal composition root behind DataTable and createDataTable. Features own their props, state, and rendering hooks; omitted features are not bundled. */
485
+ export function renderDataTable<Row extends object>(props: DataTableInternalProps<Row>, features: readonly DataTableFeature[]): JSX.Element {
394
486
  if (props.mode === "server" && typeof props.onStateChange !== "function") throw new Error("Server mode requires onStateChange");
395
487
  if (props.mode !== "server" && !Array.isArray(props.data)) throw new Error("Client mode requires a complete data array");
396
488
  if (props.mode !== "server" && props.initialResult !== undefined) throw new Error("initialResult is available only in server mode");
@@ -418,6 +510,7 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
418
510
  const locale = createMemo(() => theme.state().locale);
419
511
  const messages = createMemo(() => resolveTableMessages(theme.messages()));
420
512
  const definitions = readColumnDefinitions(props.columns);
513
+ requireFeatures(props, definitions, features);
421
514
  const definitionById = new Map(definitions.map(column => [column.id, column]));
422
515
  const searchableDefinitions = definitions.filter(column => column.search !== null);
423
516
  const searchableDefinitionById = new Map(searchableDefinitions.map(column => [column.id, column]));
@@ -425,6 +518,11 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
425
518
  const mobileLayout = resolveMobileLayout(props.mobileLayout);
426
519
  if (mobileLayout?.titleColumn && !definitions.some(column => column.id === mobileLayout.titleColumn)) throw new Error(`Unknown mobileLayout title column: ${mobileLayout.titleColumn}`);
427
520
  const initialState = initialTableState(props);
521
+ const cursorMode = cursorPagination(initialState.pagination);
522
+ if (cursorMode && props.grouping) throw new Error("DataTable grouping requires numbered or complete pagination; cursor pages carry no full-query group metadata");
523
+ if (cursorMode && props.summarizeColumns?.length) throw new Error("DataTable summarizeColumns requires numbered or complete pagination with full-query counts");
524
+ const parseState = (value: unknown): TableState<ServerPagination> => parseTableStateWith(value, schema, parseServerPagination);
525
+ const changeState = (value: TableState<ServerPagination>, change: TableStateChange<ServerPagination>): TableState<ServerPagination> => changeTableStateWith(value, change, schema, parseServerPagination);
428
526
  const selection = props.selection ? createTableSelection(initialState.filter, schema.filterColumns) : undefined;
429
527
  let selectionAnchorId: string | undefined;
430
528
  let selectionSearch = initialState.search;
@@ -445,11 +543,11 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
445
543
  let searchTimer: number | undefined;
446
544
  let searchComposing = false;
447
545
 
448
- const requests = props.mode === "server" && props.onStateChange
449
- ? createTableRequests<TableState, DataTableResult<Row>>(props.onStateChange, props.initialResult ? { state: initialState, result: props.initialResult } : undefined)
546
+ const requests = props.mode === "server"
547
+ ? createTableRequests<TableState<ServerPagination>, DataTableResult<Row> | DataTableCursorResult<Row>>((state, signal) => props.onStateChange(state, signal), props.initialResult ? { state: initialState, result: props.initialResult } : undefined)
450
548
  : undefined;
451
549
  const serverExports = props.mode === "server" && props.onExport
452
- ? createServerExport<Blob>(schema, async (request, signal) => {
550
+ ? createServerExportWith<Blob, ServerPagination>(schema, parseServerPagination, async (request, signal) => {
453
551
  const artifact = await props.onExport?.(request, signal);
454
552
  if (!(artifact instanceof Blob)) throw new Error("DataTable onExport must resolve to a Blob");
455
553
  return artifact;
@@ -470,7 +568,7 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
470
568
  const column = searchableDefinitionById.get(columnId);
471
569
  return column?.search?.(row) ?? null;
472
570
  };
473
- const clientView = createMemo<ClientView<Row> | undefined>(() => props.mode === "server" ? undefined : createClientView(props.data ?? [], clientState(), {
571
+ const clientView = createMemo<ClientView<Row> | undefined>(() => props.mode === "server" ? undefined : createClientView(props.data ?? [], numberedState(clientState()), {
474
572
  locale: locale(),
475
573
  searchColumns: searchableDefinitions.map(column => column.id),
476
574
  exactMatch: searchOptions?.exactMatch ?? false,
@@ -482,8 +580,8 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
482
580
 
483
581
  createEffect(() => {
484
582
  const view = clientView();
485
- if (!view || samePagination(clientState().pagination, view.pagination)) return;
486
- setClientState(state => parseTableState({ ...state, pagination: view.pagination }, schema));
583
+ if (!view || samePagination(numberedState(clientState()).pagination, view.pagination)) return;
584
+ setClientState(state => parseState({ ...state, pagination: view.pagination }));
487
585
  });
488
586
 
489
587
  onMount(() => {
@@ -512,16 +610,26 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
512
610
  if (download) URL.revokeObjectURL(download.href);
513
611
  });
514
612
 
515
- const acceptedState = createMemo<TableState>(() => {
613
+ const acceptedState = createMemo<TableState<ServerPagination>>(() => {
516
614
  const state = serverSnapshot()?.accepted?.state ?? clientState();
517
615
  return Object.freeze({ ...state, columns: layoutColumns() });
518
616
  });
519
- const result = (): DataTableResult<Row> => {
617
+ const result = (): DataTableResult<Row> | DataTableCursorResult<Row> => {
520
618
  const accepted = serverSnapshot()?.accepted?.result;
521
619
  if (accepted) return accepted;
522
620
  const view = clientView();
523
621
  return view ? { rows: view.rows, total: view.total, facets: clientFacetRecord(view) } : { rows: [], total: 0 };
524
622
  };
623
+ const acceptedCursorPage = (): DataTableCursorResult<Row> | undefined => {
624
+ const current = result();
625
+ return cursorResult(current) ? current : undefined;
626
+ };
627
+ /** Full-query count when known exactly. Cursor pages may omit, cap, or estimate it. */
628
+ const exactTotal = (): number | undefined => {
629
+ const current = result();
630
+ if (!cursorResult(current)) return current.total;
631
+ return current.total?.kind === "exact" ? current.total.value : undefined;
632
+ };
525
633
  const acceptedAvailable = (): boolean => props.mode !== "server" || serverSnapshot()?.accepted !== null;
526
634
  const busy = (): boolean => searchScheduled() || (serverSnapshot()?.pending ?? false);
527
635
  const pending = (): boolean => busy() || searchDraft() !== acceptedState().search || Boolean(acceptedAvailable() && serverSnapshot()?.requested);
@@ -543,7 +651,7 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
543
651
  });
544
652
  });
545
653
 
546
- async function transition(next: TableState): Promise<TableRequestOutcome | "client"> {
654
+ async function transition(next: TableState<ServerPagination>): Promise<TableRequestOutcome | "client"> {
547
655
  if (!requests || !server) {
548
656
  setClientState(next);
549
657
  props.onAcceptedStateChange?.(Object.freeze({ ...next, columns: layoutColumns() }));
@@ -560,8 +668,7 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
560
668
  const parsed = parseFilter(filter, schema.filterColumns);
561
669
  const current = serverSnapshot()?.requested ?? acceptedState();
562
670
  if (serializeFilter(parsed, schema.filterColumns) === serializeFilter(current.filter, schema.filterColumns)) return;
563
- const pagination = current.pagination === false ? false : { ...current.pagination, pageIndex: 0 };
564
- const next = parseTableState({ ...current, filter: parsed, pagination }, schema);
671
+ const next = parseState({ ...current, filter: parsed, pagination: resetPagination(current.pagination) });
565
672
  setMobilePageIndex(0);
566
673
  void transition(next).then(outcome => {
567
674
  if (outcome === "accepted" || outcome === "client") viewport?.scrollTo({ top: 0 });
@@ -622,7 +729,7 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
622
729
  setSearchScheduled(false);
623
730
  const requested = serverSnapshot()?.requested;
624
731
  const basis = requested ? Object.freeze({ ...requested, columns: layoutColumns() }) : acceptedState();
625
- const next = changeTableState(basis, { kind: "query", change: { kind: "search", value: query } }, schema);
732
+ const next = changeState(basis, { kind: "query", change: { kind: "search", value: query } });
626
733
  setMobilePageIndex(0);
627
734
  void transition(next).then(outcome => {
628
735
  if (outcome === "accepted" || outcome === "client") viewport?.scrollTo({ top: 0 });
@@ -652,10 +759,9 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
652
759
  scheduleSearch(query);
653
760
  }
654
761
 
655
- function requestPage(pageIndex: number): void {
656
- const current = acceptedState();
657
- if (current.pagination === false || pending()) return;
658
- const next = changeTableState(current, { kind: "query", change: { kind: "pagination", value: { ...current.pagination, pageIndex } } }, schema);
762
+ function requestPagination(pagination: ServerPagination): void {
763
+ if (pending()) return;
764
+ const next = changeState(acceptedState(), { kind: "query", change: { kind: "pagination", value: pagination } });
659
765
  void transition(next).then(outcome => {
660
766
  if (outcome !== "accepted" && outcome !== "client") return;
661
767
  viewport?.scrollTo({ top: 0 });
@@ -663,17 +769,27 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
663
769
  });
664
770
  }
665
771
 
772
+ function requestPage(pageIndex: number): void {
773
+ const current = acceptedState().pagination;
774
+ if (current !== false && !cursorPagination(current)) requestPagination({ ...current, pageIndex });
775
+ }
776
+
777
+ function requestCursor(cursor: CursorPosition | null): void {
778
+ const current = acceptedState().pagination;
779
+ if (cursorPagination(current)) requestPagination({ ...current, cursor });
780
+ }
781
+
666
782
  function requestSort(column: string, multiple: boolean): void {
667
783
  const requested = serverSnapshot()?.requested;
668
784
  const basis = requested ? Object.freeze({ ...requested, columns: layoutColumns() }) : acceptedState();
669
- const next = changeTableState(basis, { kind: "sortCycle", column, multiple }, schema);
785
+ const next = changeState(basis, { kind: "sortCycle", column, multiple });
670
786
  setMobilePageIndex(0);
671
787
  void transition(next);
672
788
  }
673
789
 
674
790
  function requestFilter(filter: FilterNode): void {
675
791
  if (pending()) return;
676
- const next = changeTableState(acceptedState(), { kind: "query", change: { kind: "filter", value: filter } }, schema);
792
+ const next = changeState(acceptedState(), { kind: "query", change: { kind: "filter", value: filter } });
677
793
  setMobilePageIndex(0);
678
794
  void transition(next).then(outcome => { if (outcome === "accepted" || outcome === "client") viewport?.scrollTo({ top: 0 }); });
679
795
  }
@@ -684,8 +800,7 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
684
800
  setSearchScheduled(false);
685
801
  setSearchDraft("");
686
802
  const current = acceptedState();
687
- const pagination = current.pagination === false ? false : { ...current.pagination, pageIndex: 0 };
688
- const next = parseTableState({ ...current, search: "", filter: { kind: "and", children: [] }, pagination }, schema);
803
+ const next = parseState({ ...current, search: "", filter: { kind: "and", children: [] }, pagination: resetPagination(current.pagination) });
689
804
  setMobilePageIndex(0);
690
805
  void transition(next).then(outcome => {
691
806
  if (outcome === "accepted" || outcome === "client") queueMicrotask(() => {
@@ -729,7 +844,7 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
729
844
  rowIndex,
730
845
  focusRow,
731
846
  });
732
- const extensions = features.flatMap(feature => feature(featureContext) ?? []);
847
+ const extensions = features.flatMap(feature => feature.create(featureContext) ?? []);
733
848
  const presentations = extensions.flatMap(extension => extension.presentation ? [extension.presentation] : []);
734
849
  if (presentations.length > 1) throw new Error("DataTable grouping and hierarchy are separate presentation modes");
735
850
  const presentation: DataTablePresentation<Row> | undefined = presentations[0];
@@ -893,7 +1008,7 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
893
1008
  const selectionCount = createMemo(() => {
894
1009
  const payload = selectionPayload();
895
1010
  if (!payload) return 0;
896
- return payload.kind === "query" ? Math.max(0, result().total - payload.excluded.length) : payload.ids.length;
1011
+ return payload.kind === "query" ? Math.max(0, (exactTotal() ?? 0) - payload.excluded.length) : payload.ids.length;
897
1012
  });
898
1013
  const [selectionBarPresent, setSelectionBarPresent] = createSignal(false);
899
1014
  const [selectionBarOpen, setSelectionBarOpen] = createSignal(false);
@@ -960,7 +1075,7 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
960
1075
  const value = typeof summary.value === "number"
961
1076
  ? summary.kind === "date" ? new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeZone: "UTC" }).format(summary.value) : new Intl.NumberFormat(locale).format(summary.value)
962
1077
  : summary.value;
963
- return messages().constrainedColumn.replace(/\{(column|value|count)\}/gu, (_match: string, key: string) => key === "column" ? definition.header : key === "value" ? value : new Intl.NumberFormat(locale).format(result().total));
1078
+ return messages().constrainedColumn.replace(/\{(column|value|count)\}/gu, (_match: string, key: string) => key === "column" ? definition.header : key === "value" ? value : new Intl.NumberFormat(locale).format(exactTotal() ?? 0));
964
1079
  };
965
1080
  const restoreSummary = (id: string): void => {
966
1081
  setRestoredSummaries(previous => new Set([...previous, id]));
@@ -1060,9 +1175,13 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
1060
1175
  const resultNumber = createMemo(() => new Intl.NumberFormat(locale()));
1061
1176
  const resultCount = () => {
1062
1177
  if (!acceptedAvailable()) return undefined;
1063
- const total = result().total;
1064
- const template = total === 1 ? messages().resultCountOne : messages().resultCount;
1065
- return template.replace("{count}", resultNumber().format(total));
1178
+ const current = result();
1179
+ const total: CursorTotal | undefined = cursorResult(current) ? current.total : { kind: "exact", value: current.total };
1180
+ if (!total) return undefined;
1181
+ const template = total.kind === "estimate" ? messages().resultCountEstimate
1182
+ : total.kind === "atLeast" ? messages().resultCountAtLeast
1183
+ : total.value === 1 ? messages().resultCountOne : messages().resultCount;
1184
+ return template.replace("{count}", resultNumber().format(total.value));
1066
1185
  };
1067
1186
  function downloadLastExport(): void {
1068
1187
  const download = lastDownload();
@@ -1076,14 +1195,14 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
1076
1195
  const selectionTrack = "var(--sheen-table-selection-column, 2.75rem)";
1077
1196
  const template = createMemo(() => [...(selection ? [selectionTrack] : []), ...visibleDefinitions().map(track)].join(" "));
1078
1197
 
1079
- function commitLayout(next: TableState): void {
1198
+ function commitLayout(next: TableState<ServerPagination>): void {
1080
1199
  setLayoutColumns(next.columns);
1081
1200
  const base = serverSnapshot()?.accepted?.state ?? clientState();
1082
1201
  props.onAcceptedStateChange?.(Object.freeze({ ...base, columns: next.columns }));
1083
1202
  }
1084
1203
 
1085
- function changeLayout(change: Parameters<typeof changeTableState>[1]): void {
1086
- commitLayout(changeTableState(acceptedState(), change, schema));
1204
+ function changeLayout(change: TableStateChange<ServerPagination>): void {
1205
+ commitLayout(changeState(acceptedState(), change));
1087
1206
  }
1088
1207
 
1089
1208
  function currentColumnWidth(column: (typeof columnRecords)[number]): number {
@@ -1117,9 +1236,9 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
1117
1236
  function setColumnPin(column: (typeof columnRecords)[number], pin: ColumnState["pin"]): void {
1118
1237
  let next = acceptedState();
1119
1238
  if (pin !== false && column.state().width === null && typeof column.definition.width !== "number") {
1120
- next = changeTableState(next, { kind: "columnWidth", column: column.definition.id, width: currentColumnWidth(column) }, schema);
1239
+ next = changeState(next, { kind: "columnWidth", column: column.definition.id, width: currentColumnWidth(column) });
1121
1240
  }
1122
- next = changeTableState(next, { kind: "columnPin", column: column.definition.id, pin }, schema);
1241
+ next = changeState(next, { kind: "columnPin", column: column.definition.id, pin });
1123
1242
  commitLayout(next);
1124
1243
  }
1125
1244
 
@@ -1168,7 +1287,8 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
1168
1287
  });
1169
1288
  const toolbarActions = createMemo<readonly DataTableToolbarAction[]>(() => {
1170
1289
  const next: DataTableToolbarAction[] = [];
1171
- if (selection && (presentation?.allowSelectAll ?? true) && acceptedState().search.length === 0) next.push({ kind: "action", id: "select-all", label: messages().selectAll, disabled: pending(), onSelect: selectAllMatchingRows });
1290
+ // An all-matching payload is displayed with a full-query count, so cursor pages without an exact total cannot offer it.
1291
+ if (selection && (presentation?.allowSelectAll ?? true) && acceptedState().search.length === 0 && exactTotal() !== undefined) next.push({ kind: "action", id: "select-all", label: messages().selectAll, disabled: pending(), onSelect: selectAllMatchingRows });
1172
1292
  if (availableExportFormats().length > 0) next.push({ kind: "menu", id: "export", label: messages().export, disabled: pending() || exportPending(), items: exportMenuItems() });
1173
1293
  if (lastDownload()) next.push({ kind: "action", id: "download", label: messages().downloadLastExport, onSelect: downloadLastExport });
1174
1294
  if (props.columnControls !== false) next.push({ kind: "menu", id: "columns", label: messages().columns, items: columnMenuItems() });
@@ -1549,10 +1669,10 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
1549
1669
  onCleanup(() => { if (anchorFrame !== undefined) cancelAnimationFrame(anchorFrame); });
1550
1670
  const currentRowCollection = (): readonly DisplayRow<Row>[] | readonly Row[] => presentation ? presentation.rows() : flatResultRows();
1551
1671
  let previousRows = currentRowCollection();
1552
- let previousState = serializeState(acceptedState(), schema);
1672
+ let previousState = JSON.stringify(acceptedState());
1553
1673
  createEffect(() => {
1554
1674
  const nextRows = currentRowCollection();
1555
- const nextState = serializeState(acceptedState(), schema);
1675
+ const nextState = JSON.stringify(acceptedState());
1556
1676
  const anchor = scrollAnchor;
1557
1677
  if (viewport && anchor && nextRows !== previousRows && nextState === previousState) {
1558
1678
  const index = rowIndex(anchor.id, anchor.index);
@@ -1565,8 +1685,38 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
1565
1685
 
1566
1686
  const range = createMemo(() => {
1567
1687
  const pagination = acceptedState().pagination;
1568
- return pagination === false ? undefined : getPageRange(pagination, result().total);
1688
+ return pagination === false || cursorPagination(pagination) ? undefined : getPageRange(pagination, exactTotal() ?? 0);
1689
+ });
1690
+ /** Each step's target is undefined when the accepted page has nothing in that direction. */
1691
+ const cursorSteps = createMemo<readonly CursorStep[] | undefined>(() => {
1692
+ const pagination = acceptedState().pagination;
1693
+ if (!cursorPagination(pagination)) return undefined;
1694
+ const previous = acceptedCursorPage()?.previousCursor ?? null;
1695
+ const next = acceptedCursorPage()?.nextCursor ?? null;
1696
+ return [
1697
+ { label: "firstPage", glyph: "chevrons-left", target: pagination.cursor === null || previous === null ? undefined : null },
1698
+ { label: "previousPage", glyph: "chevron-left", target: previous === null ? undefined : { direction: "before", value: previous } },
1699
+ { label: "nextPage", glyph: "chevron-right", target: next === null ? undefined : { direction: "after", value: next } },
1700
+ ];
1569
1701
  });
1702
+ /** Cursor APIs expose no page index, so the ordinal is derived from accepted navigation and resets to 1 at the first page. */
1703
+ const cursorPageNumber = createMemo<{ readonly key: string | null; readonly page: number | undefined }>(previous => {
1704
+ const pagination = acceptedState().pagination;
1705
+ const page = acceptedCursorPage();
1706
+ if (!cursorPagination(pagination) || !page) return { key: null, page: undefined };
1707
+ if (pagination.cursor === null || page.previousCursor === null) return { key: null, page: 1 };
1708
+ const key = cursorKey(pagination.cursor);
1709
+ if (key === previous.key) return previous;
1710
+ const prior = previous.page;
1711
+ return { key, page: prior === undefined ? undefined : pagination.cursor.direction === "after" ? prior + 1 : Math.max(2, prior - 1) };
1712
+ }, { key: null, page: undefined });
1713
+ const cursorStatus = (): string => {
1714
+ if (!acceptedCursorPage()) return "";
1715
+ const page = cursorPageNumber().page;
1716
+ return page === undefined
1717
+ ? messages().cursorPageRows.replaceAll("{count}", resultNumber().format(result().rows.length))
1718
+ : theme.messages().pageLabel.replaceAll("{page}", resultNumber().format(page));
1719
+ };
1570
1720
  const mobileRange = createMemo(() => {
1571
1721
  if (!mobileLayout || acceptedState().pagination !== false) return undefined;
1572
1722
  return getPageRange({ pageIndex: mobilePageIndex(), pageSize: mobileLayout.pageSize }, rowCount());
@@ -1678,13 +1828,14 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
1678
1828
  }
1679
1829
  function logicalRowIndex(index: number): number {
1680
1830
  const pagination = acceptedState().pagination;
1681
- if (treePresentation || pagination === false) return index + 2;
1682
- return getPageRange(pagination, result().total).start + index + 2;
1831
+ if (treePresentation || pagination === false || cursorPagination(pagination)) return index + 2;
1832
+ return getPageRange(pagination, exactTotal() ?? 0).start + index + 2;
1683
1833
  }
1834
+ // Cursor pages have no known absolute offset, so they report an unknown row count like tree presentations.
1684
1835
  const logicalRowCount = (): number | undefined => rowCount() === 0
1685
1836
  ? undefined
1686
- : treePresentation ? -1 : result().total + 1 + (hasFooter() ? 1 : 0);
1687
- const footerRowIndex = (): number => treePresentation ? rowCount() + 2 : result().total + 2;
1837
+ : treePresentation || cursorMode ? -1 : (exactTotal() ?? 0) + 1 + (hasFooter() ? 1 : 0);
1838
+ const footerRowIndex = (): number => treePresentation || cursorMode ? rowCount() + 2 : (exactTotal() ?? 0) + 2;
1688
1839
  function bindCell(row: () => DisplayDataRow<Row> | undefined, column: (typeof columnRecords)[number]): DataTableCellBinding<Row> | undefined {
1689
1840
  for (const extension of cellExtensions) {
1690
1841
  const binding = extension(row, column.definition);
@@ -1958,6 +2109,15 @@ export function renderDataTable<Row extends object>(props: DataTableProps<Row>,
1958
2109
  </div></Show>
1959
2110
  </div>
1960
2111
  <Show when={range()}>{page => <Pagination class="sheen-data-table-pagination" pageIndex={page().pageIndex} pageCount={page().pageCount} pending={busy()} disabled={previous()} onPageChange={requestPage} />}</Show>
2112
+ <Show when={cursorSteps()}>{steps => <nav class="sheen-pagination sheen-data-table-pagination" aria-label={theme.messages().pagination} aria-busy={busy() || undefined} aria-disabled={previous() || undefined} data-pending={busy() ? "" : undefined}>
2113
+ <Index each={steps()}>{step => {
2114
+ // Index keeps each button node, so focus survives the accepted page change. aria-disabled keeps it in Tab order.
2115
+ const unavailable = () => step().target === undefined || busy() || previous() || undefined;
2116
+ return <Button variant="ghost" class="sheen-pagination-step" aria-label={theme.messages()[step().label]} aria-disabled={unavailable()}
2117
+ onClick={() => { const target = step().target; if (target !== undefined && !unavailable()) requestCursor(target); }}><Glyph name={step().glyph} /></Button>;
2118
+ }}</Index>
2119
+ <output aria-live="polite" aria-atomic="true">{cursorStatus()}</output>
2120
+ </nav>}</Show>
1961
2121
  <For each={overlays}>{overlay => overlay()}</For>
1962
2122
  </section>;
1963
2123
  }
package/src/FilterBar.tsx CHANGED
@@ -10,7 +10,7 @@ import { appendFilterCondition, listFilterConditions, removeFilterCondition, rep
10
10
  import type { FilterCondition, FilterConditionEntry } from "./filter-bar-state.ts";
11
11
  import { resolveTableMessages } from "./messages.ts";
12
12
  import type { TableMessages } from "./messages.ts";
13
- import type { DataTableFeatureContext, DataTableFeatureInstance } from "./data-table-features.tsx";
13
+ import type { DataTableFeature, DataTableFeatureContext, DataTableFeatureInstance } from "./data-table-features.tsx";
14
14
 
15
15
  export interface FilterBarProps<Row extends object> {
16
16
  readonly columns: SheenColumns<Row>;
@@ -396,8 +396,7 @@ export function FilterBar<Row extends object>(props: FilterBarProps<Row>): JSX.E
396
396
  </div>;
397
397
  }
398
398
 
399
- /** DataTable toolbar integration for the filters declared by its column definitions. */
400
- export function filterBarFeature<Row extends object>(context: DataTableFeatureContext<Row>): DataTableFeatureInstance<Row> | undefined {
399
+ function filterBar<Row extends object>(context: DataTableFeatureContext<Row>): DataTableFeatureInstance<Row> | undefined {
401
400
  if (context.filterColumns.length === 0) return undefined;
402
401
  const props = context.props;
403
402
  return {
@@ -408,3 +407,6 @@ export function filterBarFeature<Row extends object>(context: DataTableFeatureCo
408
407
  },
409
408
  };
410
409
  }
410
+
411
+ /** DataTable toolbar integration for the filters declared by its column definitions, through the `filterBar` prop. */
412
+ export const filterBarFeature: DataTableFeature<"filterBar"> = { id: "filterBar", create: filterBar };