@gemologic/sheen-table 0.2.1 → 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 (71) hide show
  1. package/dist/DataTable.d.ts +58 -10
  2. package/dist/DataTable.js +1294 -1625
  3. package/dist/DataTableToolbar.js +1 -2
  4. package/dist/FilterBar.d.ts +3 -0
  5. package/dist/FilterBar.js +131 -108
  6. package/dist/QueryBuilder.js +72 -68
  7. package/dist/cell-edit.js +1 -2
  8. package/dist/client-state.d.ts +9 -3
  9. package/dist/client-state.js +36 -31
  10. package/dist/client-view.js +12 -13
  11. package/dist/column-layout.js +1 -2
  12. package/dist/columns.d.ts +5 -1
  13. package/dist/columns.js +7 -5
  14. package/dist/constrained-columns.js +1 -2
  15. package/dist/core.d.ts +5 -5
  16. package/dist/core.js +28 -28
  17. package/dist/data-table-features.d.ts +134 -0
  18. package/dist/data-table-features.js +560 -0
  19. package/dist/export.js +1 -2
  20. package/dist/facets.js +5 -7
  21. package/dist/filter-bar-state.js +14 -18
  22. package/dist/filter-client.js +1 -2
  23. package/dist/filter.js +1 -2
  24. package/dist/grouping.js +1 -2
  25. package/dist/index.d.ts +5 -3
  26. package/dist/index.js +32 -31
  27. package/dist/messages.d.ts +4 -1
  28. package/dist/messages.js +5 -3
  29. package/dist/pagination.d.ts +43 -1
  30. package/dist/pagination.js +110 -56
  31. package/dist/query-builder-state.js +1 -2
  32. package/dist/requests.d.ts +3 -3
  33. package/dist/requests.js +39 -30
  34. package/dist/row-hierarchy.js +1 -2
  35. package/dist/row-identity.js +1 -2
  36. package/dist/saved-views.d.ts +17 -14
  37. package/dist/saved-views.js +72 -70
  38. package/dist/search-controller.js +1 -2
  39. package/dist/search.js +1 -2
  40. package/dist/selection-client.js +1 -2
  41. package/dist/selection.d.ts +3 -0
  42. package/dist/selection.js +9 -2
  43. package/dist/server-export.d.ts +16 -7
  44. package/dist/server-export.js +58 -55
  45. package/dist/sorting.js +1 -2
  46. package/dist/table-state-changes.d.ts +6 -3
  47. package/dist/table-state-changes.js +45 -42
  48. package/dist/table-state.d.ts +20 -4
  49. package/dist/table-state.js +67 -42
  50. package/dist/text-normalization.js +1 -2
  51. package/dist/url-state.d.ts +12 -9
  52. package/dist/url-state.js +34 -32
  53. package/package.json +5 -5
  54. package/src/DataTable.tsx +490 -766
  55. package/src/FilterBar.tsx +19 -3
  56. package/src/QueryBuilder.tsx +5 -5
  57. package/src/client-state.ts +31 -17
  58. package/src/columns.ts +9 -3
  59. package/src/core.ts +5 -5
  60. package/src/data-table-features.tsx +592 -0
  61. package/src/index.ts +5 -3
  62. package/src/messages.ts +2 -2
  63. package/src/pagination.ts +83 -14
  64. package/src/requests.ts +22 -8
  65. package/src/saved-views.ts +33 -11
  66. package/src/selection.ts +8 -0
  67. package/src/server-export.ts +17 -11
  68. package/src/styles.css +17 -11
  69. package/src/table-state-changes.ts +22 -12
  70. package/src/table-state.ts +53 -11
  71. package/src/url-state.ts +27 -10
package/src/pagination.ts CHANGED
@@ -5,41 +5,95 @@ export interface PageResult<Row> { readonly rows: readonly Row[]; readonly total
5
5
  export type ServerPageAssessment<Row> =
6
6
  | { readonly kind: "accepted"; readonly pagination: TablePagination; readonly result: PageResult<Row> }
7
7
  | { readonly kind: "refetch"; readonly pagination: PageState; readonly total: number };
8
+ /** Opaque server cursor plus the side of it to read. Null requests the first page. */
9
+ export interface CursorPosition { readonly direction: "after" | "before"; readonly value: string }
10
+ export interface CursorPagination { readonly kind: "cursor"; readonly pageSize: number; readonly cursor: CursorPosition | null }
11
+ /** Every server pagination choice: complete (false), numbered, or cursor. */
12
+ export type ServerPagination = TablePagination | CursorPagination;
13
+ /** Optional full-query count. Estimates and lower bounds are announced as such, never as exact counts. */
14
+ export interface CursorTotal { readonly kind: "exact" | "estimate" | "atLeast"; readonly value: number }
15
+ export interface CursorPageResult<Row> {
16
+ readonly rows: readonly Row[];
17
+ /** Null when no later page exists. */
18
+ readonly nextCursor: string | null;
19
+ /** Null when no earlier page exists. */
20
+ readonly previousCursor: string | null;
21
+ readonly total?: CursorTotal;
22
+ }
23
+ export type CursorPageAssessment<Row> =
24
+ | { readonly kind: "accepted"; readonly pagination: CursorPagination; readonly result: CursorPageResult<Row> }
25
+ | { readonly kind: "refetch"; readonly pagination: CursorPagination };
26
+
27
+ const explicitServerPagination = "Server mode requires explicit pagination, including explicit false for complete results";
8
28
 
9
29
  function nonnegativeInteger(value: unknown, name: string): asserts value is number {
10
30
  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`${name} must be a nonnegative safe integer`);
11
31
  }
12
32
 
33
+ function pageSize(value: unknown): number {
34
+ nonnegativeInteger(value, "pageSize");
35
+ if (value === 0) throw new Error("pageSize must be positive");
36
+ return value;
37
+ }
38
+
39
+ function closed(value: object, fields: readonly string[]): void {
40
+ if (Object.keys(value).some(key => !fields.includes(key))) throw new Error("pagination contains unknown fields");
41
+ }
42
+
43
+ function cursorToken(value: unknown, name: string): string {
44
+ if (typeof value !== "string" || !value) throw new Error(`${name} must be a nonempty string or null`);
45
+ return value;
46
+ }
47
+
13
48
  export function parsePagination(value: unknown): TablePagination {
14
49
  if (value === false) return false;
15
50
  if (typeof value !== "object" || value === null || Array.isArray(value) || !("pageIndex" in value) || !("pageSize" in value)) throw new Error("pagination must be false or { pageIndex, pageSize }");
16
- if (Object.keys(value).some(key => key !== "pageIndex" && key !== "pageSize")) throw new Error("pagination contains unknown fields");
51
+ closed(value, ["pageIndex", "pageSize"]);
17
52
  nonnegativeInteger(value.pageIndex, "pageIndex");
18
- nonnegativeInteger(value.pageSize, "pageSize");
19
- if (value.pageSize === 0) throw new Error("pageSize must be positive");
20
- return Object.freeze({ pageIndex: value.pageIndex, pageSize: value.pageSize });
53
+ return Object.freeze({ pageIndex: value.pageIndex, pageSize: pageSize(value.pageSize) });
21
54
  }
22
55
 
23
56
  export function resolvePagination(mode: "client" | "server", value?: TablePagination): TablePagination {
24
57
  if (mode !== "client" && mode !== "server") throw new Error("Table mode must be client or server");
25
58
  if (value === undefined) {
26
- if (mode === "server") throw new Error("Server mode requires explicit pagination, including explicit false for complete results");
59
+ if (mode === "server") throw new Error(explicitServerPagination);
27
60
  return false;
28
61
  }
29
62
  return parsePagination(value);
30
63
  }
31
64
 
32
- /** Filter and sort changes reset the requested page, not accepted rows. */
33
- export function resetPagination(value: TablePagination): TablePagination {
34
- const parsed = parsePagination(value);
35
- return parsed === false ? false : Object.freeze({ ...parsed, pageIndex: 0 });
65
+ export function parseCursorPagination(value: unknown): CursorPagination {
66
+ if (typeof value !== "object" || value === null || Array.isArray(value) || !("kind" in value) || value.kind !== "cursor" || !("pageSize" in value) || !("cursor" in value)) throw new Error('cursor pagination must be { kind: "cursor", pageSize, cursor }');
67
+ closed(value, ["kind", "pageSize", "cursor"]);
68
+ const cursor: unknown = value.cursor;
69
+ if (cursor === null) return Object.freeze({ kind: "cursor", pageSize: pageSize(value.pageSize), cursor: null });
70
+ if (typeof cursor !== "object" || !("direction" in cursor) || !("value" in cursor) || (cursor.direction !== "after" && cursor.direction !== "before")) throw new Error("cursor must be null or { direction: after | before, value }");
71
+ closed(cursor, ["direction", "value"]);
72
+ return Object.freeze({ kind: "cursor", pageSize: pageSize(value.pageSize), cursor: Object.freeze({ direction: cursor.direction, value: cursorToken(cursor.value, "cursor value") }) });
36
73
  }
37
74
 
38
- export function resizePagination(value: PageState, pageSize: number): PageState {
39
- if (parsePagination(value) === false) throw new Error("Page-size changes require paginated state");
40
- nonnegativeInteger(pageSize, "pageSize");
41
- if (pageSize === 0) throw new Error("pageSize must be positive");
42
- return Object.freeze({ pageIndex: 0, pageSize });
75
+ /** Validates any server choice. Cursor state is distinguished by its kind field. */
76
+ export function parseServerPagination(value: unknown): ServerPagination {
77
+ if (value === undefined) throw new Error(explicitServerPagination);
78
+ return typeof value === "object" && value !== null && "kind" in value ? parseCursorPagination(value) : parsePagination(value);
79
+ }
80
+
81
+ /** Filter and sort changes reset the requested page, not accepted rows. Cursor state returns to the first page. */
82
+ export function resetPagination(value: TablePagination): TablePagination;
83
+ export function resetPagination(value: CursorPagination): CursorPagination;
84
+ export function resetPagination(value: ServerPagination): ServerPagination;
85
+ export function resetPagination(value: ServerPagination): ServerPagination {
86
+ const parsed = parseServerPagination(value);
87
+ return parsed === false ? false : resizePagination(parsed, parsed.pageSize);
88
+ }
89
+
90
+ export function resizePagination(value: PageState, pageSize: number): PageState;
91
+ export function resizePagination(value: CursorPagination, pageSize: number): CursorPagination;
92
+ export function resizePagination(value: PageState | CursorPagination, pageSize: number): PageState | CursorPagination;
93
+ export function resizePagination(value: PageState | CursorPagination, size: number): PageState | CursorPagination {
94
+ const parsed = parseServerPagination(value);
95
+ if (parsed === false) throw new Error("Page-size changes require paginated state");
96
+ return "kind" in parsed ? Object.freeze({ kind: "cursor", pageSize: pageSize(size), cursor: null }) : Object.freeze({ pageIndex: 0, pageSize: pageSize(size) });
43
97
  }
44
98
 
45
99
  /** Clamp before multiplying so even extreme valid requested indices cannot overflow the offset. */
@@ -79,3 +133,18 @@ export function assessServerPage<Row>(value: TablePagination, result: PageResult
79
133
  if (result.rows.length !== range.end - range.start) throw new Error("Server page row count does not match the requested page and total");
80
134
  return { kind: "accepted", pagination: Object.freeze({ pageIndex: range.pageIndex, pageSize: range.pageSize }), result };
81
135
  }
136
+
137
+ /** Validate a single cursor response. An empty later page (for example after deletions) refetches the first page. */
138
+ export function assessCursorPage<Row>(value: CursorPagination, result: CursorPageResult<Row>): CursorPageAssessment<Row> {
139
+ const parsed = parseCursorPagination(value);
140
+ if (!Array.isArray(result.rows)) throw new Error("Server rows must be an array");
141
+ if (result.rows.length > parsed.pageSize) throw new Error("Cursor page contains more rows than pageSize");
142
+ if (result.nextCursor !== null) cursorToken(result.nextCursor, "nextCursor");
143
+ if (result.previousCursor !== null) cursorToken(result.previousCursor, "previousCursor");
144
+ if (result.total !== undefined) {
145
+ if (typeof result.total !== "object" || result.total === null || (result.total.kind !== "exact" && result.total.kind !== "estimate" && result.total.kind !== "atLeast")) throw new Error("Cursor total must be { kind: exact | estimate | atLeast, value }");
146
+ nonnegativeInteger(result.total.value, "total value");
147
+ }
148
+ if (result.rows.length === 0 && parsed.cursor !== null) return { kind: "refetch", pagination: resetPagination(parsed) };
149
+ return { kind: "accepted", pagination: parsed, result };
150
+ }
package/src/requests.ts CHANGED
@@ -1,7 +1,7 @@
1
- import { assessServerPage, resolvePagination } from "./pagination.ts";
2
- import type { PageResult, TablePagination } from "./pagination.ts";
1
+ import { assessCursorPage, assessServerPage, parseServerPagination } from "./pagination.ts";
2
+ import type { CursorPageAssessment, CursorPageResult, PageResult, ServerPageAssessment, ServerPagination } from "./pagination.ts";
3
3
 
4
- export interface TableRequestState { readonly pagination: TablePagination }
4
+ export interface TableRequestState { readonly pagination: ServerPagination }
5
5
  export interface TableRequestSnapshot<State, Result> {
6
6
  readonly accepted: { readonly state: State; readonly result: Result } | null;
7
7
  readonly requested: State | null;
@@ -11,16 +11,30 @@ export interface TableRequestSnapshot<State, Result> {
11
11
  export type TableRequestOutcome = "accepted" | "failed" | "superseded" | "disposed";
12
12
  export interface InitialTableResult<State, Result> { readonly state: State; readonly result: Result }
13
13
 
14
+ function cursorResult(result: PageResult<unknown> | CursorPageResult<unknown>): result is CursorPageResult<unknown> {
15
+ return "nextCursor" in result && "previousCursor" in result;
16
+ }
17
+
18
+ /** The pagination kind selects the response contract; a mismatched shape fails instead of being coerced. */
19
+ function assess(pagination: ServerPagination, result: PageResult<unknown> | CursorPageResult<unknown>): ServerPageAssessment<unknown> | CursorPageAssessment<unknown> {
20
+ const parsed = parseServerPagination(pagination);
21
+ if (parsed !== false && "kind" in parsed) {
22
+ if (!cursorResult(result)) throw new Error("Cursor pagination results require nextCursor and previousCursor");
23
+ return assessCursorPage(parsed, result);
24
+ }
25
+ if (cursorResult(result)) throw new Error("Numbered and complete server results must report total instead of cursors");
26
+ return assessServerPage(parsed, result);
27
+ }
28
+
14
29
  /** Framework-neutral request ownership. Read snapshots before/after awaiting request in the UI adapter. */
15
- export function createTableRequests<State extends TableRequestState, Result extends PageResult<unknown>>(
30
+ export function createTableRequests<State extends TableRequestState, Result extends PageResult<unknown> | CursorPageResult<unknown>>(
16
31
  onStateChange: (state: State, signal: AbortSignal) => Promise<Result>,
17
32
  initial?: InitialTableResult<State, Result>,
18
33
  ) {
19
34
  let snapshot: TableRequestSnapshot<State, Result> = { accepted: null, requested: null, pending: false, error: null };
20
35
  if (initial) {
21
36
  const state = structuredClone(initial.state);
22
- resolvePagination("server", state.pagination);
23
- const assessment = assessServerPage(state.pagination, initial.result);
37
+ const assessment = assess(state.pagination, initial.result);
24
38
  if (assessment.kind !== "accepted") throw new Error("Initial table results must describe a valid accepted page, not a page requiring refetch");
25
39
  snapshot = { accepted: { state: { ...state, pagination: assessment.pagination }, result: initial.result }, requested: null, pending: false, error: null };
26
40
  }
@@ -42,13 +56,13 @@ export function createTableRequests<State extends TableRequestState, Result exte
42
56
  try {
43
57
  // Separate transport state from both the caller and the publicly readable snapshot.
44
58
  let state: State = structuredClone(value);
45
- resolvePagination("server", state.pagination);
59
+ parseServerPagination(state.pagination);
46
60
  snapshot = { ...snapshot, requested: structuredClone(state), pending: true, error: null };
47
61
  for (let attempt = 0; attempt < 4; attempt++) {
48
62
  const result = await onStateChange(structuredClone(state), current.signal);
49
63
  if (disposed) return "disposed";
50
64
  if (token !== sequence) return "superseded";
51
- const assessment = assessServerPage(state.pagination, result);
65
+ const assessment = assess(state.pagination, result);
52
66
  state = { ...state, pagination: assessment.pagination };
53
67
  if (assessment.kind === "accepted") {
54
68
  snapshot = { accepted: { state, result }, requested: null, pending: false, error: null };
@@ -1,5 +1,6 @@
1
- import { deserializeState, serializeState } from "./table-state.ts";
2
- import type { TableState, TableStateSchema } from "./table-state.ts";
1
+ import type { CursorPagination, ServerPagination, TablePagination } from "./pagination.ts";
2
+ import { deserializeState, schemaPagination, serializeState } from "./table-state.ts";
3
+ import type { CursorTableStateSchema, TableState, TableStateSchema } from "./table-state.ts";
3
4
 
4
5
  export interface SavedViewRecord { readonly id: string; readonly name: string; readonly state: string }
5
6
  export interface SavedViewSave { readonly id: string | null; readonly name: string; readonly state: string }
@@ -19,8 +20,8 @@ export interface SavedViewsSnapshot {
19
20
  readonly error: unknown;
20
21
  }
21
22
  export type SavedViewOutcome = "accepted" | "failed" | "superseded" | "disposed";
22
- export type SavedViewRestore =
23
- | { readonly kind: "accepted"; readonly state: TableState }
23
+ export type SavedViewRestore<Pagination extends ServerPagination = TablePagination> =
24
+ | { readonly kind: "accepted"; readonly state: TableState<Pagination> }
24
25
  | { readonly kind: "missing" }
25
26
  | { readonly kind: "invalid"; readonly error: unknown };
26
27
 
@@ -56,8 +57,29 @@ function operation(value: SavedViewOperation): SavedViewOperation {
56
57
  return Object.freeze({ ...value });
57
58
  }
58
59
 
59
- /** Async saved-view ownership. Persistence and authorization stay in the app adapter. */
60
- export function createSavedViews(adapter: SavedViewsAdapter, schema: TableStateSchema) {
60
+ export interface SavedViews<Pagination extends ServerPagination = TablePagination> {
61
+ readonly getSnapshot: () => SavedViewsSnapshot;
62
+ readonly list: () => Promise<SavedViewOutcome>;
63
+ readonly save: (name: string, state: TableState<Pagination>, id?: string | null) => Promise<SavedViewOutcome>;
64
+ readonly delete: (id: string) => Promise<SavedViewOutcome>;
65
+ readonly restore: (id: string) => SavedViewRestore<Pagination>;
66
+ readonly retry: () => Promise<SavedViewOutcome>;
67
+ readonly clear: () => void;
68
+ readonly dispose: () => void;
69
+ }
70
+
71
+ /** Async saved-view ownership. Persistence and authorization stay in the app adapter. Cursor schemas save and restore only the first page. */
72
+ export function createSavedViews(adapter: SavedViewsAdapter, schema: CursorTableStateSchema): SavedViews<CursorPagination>;
73
+ export function createSavedViews(adapter: SavedViewsAdapter, schema: TableStateSchema): SavedViews;
74
+ export function createSavedViews(adapter: SavedViewsAdapter, schema: TableStateSchema | CursorTableStateSchema): SavedViews<CursorPagination> | SavedViews {
75
+ schemaPagination(schema);
76
+ if (schema.pagination === "cursor") {
77
+ return savedViews<CursorPagination>(adapter, state => serializeState(state, schema), value => deserializeState(value, schema));
78
+ }
79
+ return savedViews<TablePagination>(adapter, state => serializeState(state, schema), value => deserializeState(value, schema));
80
+ }
81
+
82
+ function savedViews<Pagination extends ServerPagination>(adapter: SavedViewsAdapter, serialize: (state: TableState<Pagination>) => string, deserialize: (value: string) => TableState<Pagination>): SavedViews<Pagination> {
61
83
  let snapshot: SavedViewsSnapshot = Object.freeze({ accepted: null, pending: null, failed: null, error: null });
62
84
  let sequence = 0n;
63
85
  let controller: AbortController | undefined;
@@ -89,7 +111,7 @@ export function createSavedViews(adapter: SavedViewsAdapter, schema: TableStateS
89
111
  if (disposed) return "disposed";
90
112
  if (token !== sequence) return "superseded";
91
113
  if (requested.view.id !== null && requested.view.id !== saved.id) throw new Error("Saved view adapter changed the requested ID");
92
- deserializeState(saved.state, schema);
114
+ deserialize(saved.state);
93
115
  const existing = snapshot.accepted ?? [];
94
116
  const index = existing.findIndex(view => view.id === saved.id);
95
117
  const accepted = index < 0 ? [...existing, saved] : existing.map(view => view.id === saved.id ? saved : view);
@@ -108,16 +130,16 @@ export function createSavedViews(adapter: SavedViewsAdapter, schema: TableStateS
108
130
  return "failed";
109
131
  } finally { if (token === sequence) controller = undefined; }
110
132
  }
111
- function save(name: string, state: TableState, id: string | null = null): Promise<SavedViewOutcome> {
112
- const view = Object.freeze({ id: id === null ? null : text(id, "Saved view ID"), name: text(name, "Saved view name"), state: serializeState(state, schema) });
133
+ function save(name: string, state: TableState<Pagination>, id: string | null = null): Promise<SavedViewOutcome> {
134
+ const view = Object.freeze({ id: id === null ? null : text(id, "Saved view ID"), name: text(name, "Saved view name"), state: serialize(state) });
113
135
  return run({ kind: "save", view });
114
136
  }
115
- function restore(id: string): SavedViewRestore {
137
+ function restore(id: string): SavedViewRestore<Pagination> {
116
138
  try {
117
139
  const checked = text(id, "Saved view ID");
118
140
  const view = snapshot.accepted?.find(candidate => candidate.id === checked);
119
141
  if (!view) return Object.freeze({ kind: "missing" });
120
- return Object.freeze({ kind: "accepted", state: deserializeState(view.state, schema) });
142
+ return Object.freeze({ kind: "accepted", state: deserialize(view.state) });
121
143
  } catch (error) { return Object.freeze({ kind: "invalid", error }); }
122
144
  }
123
145
  function clear(): void {
package/src/selection.ts CHANGED
@@ -42,6 +42,14 @@ export function createTableSelection(initialFilter: FilterNode, columns: readonl
42
42
  },
43
43
  selectAllMatching() { explicit = new Set(); excluded = new Set(); inverted = true; },
44
44
  isSelected(id: string) { return inverted ? loaded.has(id) && !excluded.has(id) : explicit.has(id); },
45
+ isLoaded(id: string) { return loaded.has(id); },
46
+ /** Counts selected loaded rows from the smaller explicit/excluded set instead of walking every loaded row. */
47
+ loadedSelectedCount() {
48
+ const marked = inverted ? excluded : explicit;
49
+ let count = 0;
50
+ for (const id of marked) if (loaded.has(id)) count++;
51
+ return inverted ? loaded.size - count : count;
52
+ },
45
53
  getPayload(): BulkSelection {
46
54
  return inverted
47
55
  ? Object.freeze({ kind: "query", filter, excluded: Object.freeze([...excluded]) })
@@ -1,25 +1,27 @@
1
1
  import { parseFilter } from "./filter.ts";
2
2
  import type { BulkSelection } from "./selection.ts";
3
- import { parseTableState } from "./table-state.ts";
3
+ import { parsePagination } from "./pagination.ts";
4
+ import type { ServerPagination, TablePagination } from "./pagination.ts";
5
+ import { parseTableStateWith } from "./table-state.ts";
4
6
  import type { TableState, TableStateSchema } from "./table-state.ts";
5
7
 
6
- export interface TableExportRequest {
8
+ export interface TableExportRequest<Pagination extends ServerPagination = TablePagination> {
7
9
  readonly format: "csv" | "json";
8
- readonly state: TableState;
10
+ readonly state: TableState<Pagination>;
9
11
  /** null exports the whole matching view; explicit empty IDs export zero rows. */
10
12
  readonly selection: BulkSelection | null;
11
13
  }
12
- export interface ServerExportSnapshot<Artifact> {
13
- readonly accepted: { readonly request: TableExportRequest; readonly artifact: Artifact } | null;
14
- readonly requested: TableExportRequest | null;
14
+ export interface ServerExportSnapshot<Artifact, Pagination extends ServerPagination = TablePagination> {
15
+ readonly accepted: { readonly request: TableExportRequest<Pagination>; readonly artifact: Artifact } | null;
16
+ readonly requested: TableExportRequest<Pagination> | null;
15
17
  readonly pending: boolean;
16
18
  readonly error: unknown;
17
19
  }
18
20
  export type ServerExportOutcome = "accepted" | "failed" | "busy" | "unavailable" | "canceled" | "disposed";
19
21
 
20
- function capture(request: TableExportRequest, schema: TableStateSchema): TableExportRequest {
22
+ function capture<Pagination extends ServerPagination>(request: TableExportRequest<Pagination>, schema: TableStateSchema, readPagination: (value: unknown) => Pagination): TableExportRequest<Pagination> {
21
23
  if (request.format !== "csv" && request.format !== "json") throw new Error("Unsupported table export format");
22
- const state = parseTableState(request.state, schema);
24
+ const state = parseTableStateWith(request.state, schema, readPagination);
23
25
  let selection: BulkSelection | null = null;
24
26
  if (request.selection !== null) {
25
27
  const source = request.selection;
@@ -40,12 +42,16 @@ function capture(request: TableExportRequest, schema: TableStateSchema): TableEx
40
42
 
41
43
  /** App callback creates the artifact; only the accepted result should be offered for download. */
42
44
  export function createServerExport<Artifact>(schema: TableStateSchema, onExport?: (request: TableExportRequest, signal: AbortSignal) => Promise<Artifact>) {
43
- let snapshot: ServerExportSnapshot<Artifact> = { accepted: null, requested: null, pending: false, error: null };
45
+ return createServerExportWith(schema, parsePagination, onExport);
46
+ }
47
+
48
+ export function createServerExportWith<Artifact, Pagination extends ServerPagination>(schema: TableStateSchema, readPagination: (value: unknown) => Pagination, onExport?: (request: TableExportRequest<Pagination>, signal: AbortSignal) => Promise<Artifact>) {
49
+ let snapshot: ServerExportSnapshot<Artifact, Pagination> = { accepted: null, requested: null, pending: false, error: null };
44
50
  let sequence = 0n;
45
51
  let controller: AbortController | undefined;
46
52
  let disposed = false;
47
53
  let clearing = false;
48
- async function request(value: TableExportRequest): Promise<ServerExportOutcome> {
54
+ async function request(value: TableExportRequest<Pagination>): Promise<ServerExportOutcome> {
49
55
  if (disposed) return "disposed";
50
56
  if (!onExport) return "unavailable";
51
57
  if (clearing) return "canceled";
@@ -55,7 +61,7 @@ export function createServerExport<Artifact>(schema: TableStateSchema, onExport?
55
61
  controller = current;
56
62
  snapshot = { ...snapshot, requested: null, pending: true, error: null };
57
63
  try {
58
- const captured = capture(value, schema);
64
+ const captured = capture(value, schema, readPagination);
59
65
  snapshot = { ...snapshot, requested: captured };
60
66
  const artifact = await onExport(captured, current.signal);
61
67
  if (disposed) return "disposed";
package/src/styles.css CHANGED
@@ -28,7 +28,7 @@
28
28
  .sheen-filter-remove { flex: 0 0 2rem; min-inline-size: 24px; min-block-size: 24px; padding: 0; color: var(--sheen-color-fg-muted); background: transparent; border: 0; border-inline-start: 1px solid var(--sheen-color-border-control); border-start-end-radius: var(--sheen-control-radius); border-end-end-radius: var(--sheen-control-radius); cursor: pointer; }
29
29
  .sheen-filter-remove:hover { color: var(--sheen-color-fg); background: var(--sheen-color-bg-hover); }
30
30
  .sheen-filter-remove:disabled { cursor: wait; opacity: 0.65; }
31
- .sheen-filter-remove:focus-visible { outline: var(--sheen-focus-ring-width) solid var(--sheen-color-focus-ring); outline-offset: var(--sheen-focus-ring-offset); }
31
+ .sheen-filter-remove:focus-visible { outline: 2px solid var(--sheen-color-focus-ring); outline-offset: 2px; box-shadow: 0 0 0 2px var(--sheen-color-focus-ring-offset); }
32
32
  .sheen-filter-add { display: inline-flex; }
33
33
  .sheen-filter-picker, .sheen-filter-editor { inline-size: min(24rem, calc(100vw - 2rem)); }
34
34
  .sheen-filter-column-list { display: grid; gap: var(--sheen-space-block-xs); max-block-size: 16rem; margin: var(--sheen-space-block-sm) 0 0; padding: 0; overflow: auto; list-style: none; }
@@ -49,10 +49,11 @@
49
49
  .sheen-data-table th { position: relative; overflow: visible; font-size: var(--sheen-text-ui-sm-size); line-height: var(--sheen-text-ui-sm-leading); font-weight: var(--sheen-text-h4-weight); color: var(--sheen-color-fg-muted); }
50
50
  .sheen-data-table-header-content { display: flex; align-items: center; gap: var(--sheen-space-inline-xs); min-inline-size: 0; }
51
51
  .sheen-data-table-header-label, .sheen-data-table-sort { min-inline-size: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
52
- .sheen-data-table-sort { display: flex; flex: 1 1 auto; align-items: center; min-block-size: 24px; gap: var(--sheen-space-inline-xs); color: inherit; background: transparent; border: 0; text-align: inherit; cursor: pointer; }
52
+ .sheen-data-table-sort { display: flex; flex: 1 1 auto; align-items: center; min-block-size: 24px; gap: var(--sheen-space-inline-xs); padding: 0; margin: 0; font: inherit; letter-spacing: inherit; color: inherit; background: transparent; border: 0; border-radius: 0; text-align: inherit; cursor: pointer; }
53
53
  .sheen-data-table-sort-label { min-inline-size: 0; overflow: hidden; text-overflow: ellipsis; }
54
54
  .sheen-data-table-sort-indicator { display: inline-flex; flex: 0 0 auto; align-items: center; gap: 0.15rem; color: var(--sheen-color-accent); }
55
- .sheen-data-table-sort-direction { font-size: 0.9em; line-height: 1; }
55
+ .sheen-data-table-sort-direction { display: inline-flex; line-height: 1; }
56
+ .sheen-data-table-sort-direction > .sheen-glyph { inline-size: 0.875rem; block-size: 0.875rem; }
56
57
  .sheen-data-table-sort-priority { display: grid; place-items: center; min-inline-size: 1rem; block-size: 1rem; padding-inline: 0.2rem; color: var(--sheen-color-accent-fg); background: var(--sheen-color-accent-subtle); border: 1px solid var(--sheen-color-accent-border); border-radius: var(--sheen-control-radius); font-size: var(--sheen-text-caption-size); line-height: 1; }
57
58
  .sheen-data-table th[data-sort-direction] { color: var(--sheen-color-fg); }
58
59
  .sheen-data-table-sort:disabled { cursor: wait; }
@@ -63,7 +64,7 @@
63
64
  .sheen-data-table-resizer { position: absolute; z-index: 2; inset-block: 0; inset-inline-end: 0; inline-size: 24px; padding: 0; background: transparent; border: 0; cursor: col-resize; touch-action: none; }
64
65
  .sheen-data-table-resizer::after { content: ""; position: absolute; inset-block: 20%; inset-inline-start: calc(50% - 1px); inline-size: 2px; border-radius: 1px; background: transparent; }
65
66
  .sheen-data-table-resizer:hover::after, .sheen-data-table-resizer[data-resizing]::after, .sheen-data-table-resizer:focus-visible::after { background: var(--sheen-color-accent); }
66
- .sheen-data-table-sort:focus-visible, .sheen-data-table-reorder:focus-visible, .sheen-data-table-resizer:focus-visible { outline: var(--sheen-focus-ring-width) solid var(--sheen-color-focus-ring); outline-offset: var(--sheen-focus-ring-offset); }
67
+ .sheen-data-table-sort:focus-visible, .sheen-data-table-reorder:focus-visible, .sheen-data-table-resizer:focus-visible { outline: 2px solid var(--sheen-color-focus-ring); outline-offset: -2px; }
67
68
  .sheen-data-table[data-resizing] { cursor: col-resize; user-select: none; }
68
69
  .sheen-data-table[data-reordering] th[data-drop-placement]::before { content: ""; position: absolute; z-index: 3; inset-block: 0; inline-size: 3px; background: var(--sheen-color-accent); }
69
70
  .sheen-data-table[data-reordering] th[data-drop-placement="before"]::before { inset-inline-start: 0; }
@@ -74,7 +75,11 @@
74
75
  .sheen-data-table tbody tr:not(.sheen-data-table-empty) { --sheen-table-row-bg: var(--sheen-color-bg); position: absolute; inset-block-start: 0; inset-inline-start: 0; box-sizing: border-box; align-items: center; border-block-end: 1px solid var(--sheen-color-border); background: var(--sheen-table-row-bg); }
75
76
  .sheen-data-table tbody tr[data-group-id] { --sheen-table-row-bg: var(--sheen-color-bg-raised); font-weight: var(--sheen-text-h4-weight); }
76
77
  .sheen-data-table tbody tr[data-selected] { --sheen-table-row-bg: var(--sheen-color-bg-selected); }
77
- @media (hover: hover) { .sheen-data-table tbody tr[data-row-id]:hover { --sheen-table-row-bg: var(--sheen-color-bg-hover); } }
78
+ /* Only pointer hover fades in. Selection, focus, and refresh states paint immediately: they answer an action, and a background transition repaints the row on the main thread every frame. */
79
+ @media (hover: hover) {
80
+ .sheen-data-table tbody tr[data-row-id]:hover { --sheen-table-row-bg: var(--sheen-color-bg-hover); }
81
+ .sheen-data-table tbody tr[data-row-id]:not([data-selected]):hover, .sheen-data-table tbody tr[data-row-id]:not([data-selected]):hover > [data-pin] { transition: background-color var(--sheen-duration-fast) var(--sheen-ease-standard); }
82
+ }
78
83
  .sheen-data-table tbody tr[data-row-id]:focus-visible { --sheen-table-row-bg: var(--sheen-color-bg-hover); }
79
84
  @media (hover: hover) { .sheen-data-table tbody tr[data-row-id][data-selected]:hover { --sheen-table-row-bg: color-mix(in oklch, var(--sheen-color-bg-selected) 82%, var(--sheen-color-bg-hover)); } }
80
85
  .sheen-data-table tbody tr[data-row-id][data-selected]:focus-visible { --sheen-table-row-bg: color-mix(in oklch, var(--sheen-color-bg-selected) 82%, var(--sheen-color-bg-hover)); }
@@ -95,12 +100,12 @@
95
100
  .sheen-data-table [data-pin-edge]::before { content: ""; position: absolute; z-index: 1; inset-block: 0; inline-size: 1px; background: var(--sheen-color-border-control); box-shadow: 0 0 0.55rem color-mix(in oklch, var(--sheen-color-fg) 22%, transparent); pointer-events: none; }
96
101
  .sheen-data-table [data-pin-edge="start"]::before { inset-inline-end: 0; }
97
102
  .sheen-data-table [data-pin-edge="end"]::before { inset-inline-start: 0; }
98
- .sheen-data-table tbody tr:focus-visible { outline: var(--sheen-focus-ring-width) solid var(--sheen-color-focus-ring); outline-offset: calc(-1 * var(--sheen-focus-ring-width)); }
103
+ .sheen-data-table tbody tr:focus-visible { outline: 2px solid var(--sheen-color-focus-ring); outline-offset: -2px; }
99
104
  .sheen-data-table-tree-cell { display: flex; align-items: center; gap: var(--sheen-space-inline-xs); min-inline-size: 0; padding-inline-start: calc(var(--sheen-table-depth, 0) * var(--sheen-space-inline-lg)); }
100
105
  .sheen-data-table-expander, .sheen-data-table-expander-space { flex: 0 0 1.5rem; inline-size: 1.5rem; block-size: 1.5rem; padding: 0; }
101
106
  .sheen-data-table-expander { color: var(--sheen-color-fg-muted); background: transparent; border: 0; border-radius: var(--sheen-control-radius); cursor: pointer; }
102
107
  .sheen-data-table-expander:disabled { cursor: wait; }
103
- .sheen-data-table-expander:focus-visible, .sheen-data-table-row-status button:focus-visible { outline: var(--sheen-focus-ring-width) solid var(--sheen-color-focus-ring); outline-offset: var(--sheen-focus-ring-offset); }
108
+ .sheen-data-table-expander:focus-visible, .sheen-data-table-row-status button:focus-visible { outline: 2px solid var(--sheen-color-focus-ring); outline-offset: -2px; }
104
109
  .sheen-data-table-tree-value, .sheen-data-table-group-label { min-inline-size: 0; overflow: hidden; text-overflow: ellipsis; }
105
110
  .sheen-data-table-group-count, .sheen-data-table-row-status { color: var(--sheen-color-fg-muted); font-size: var(--sheen-text-ui-sm-size); font-weight: var(--sheen-text-ui-sm-weight); }
106
111
  .sheen-data-table-row-status { display: inline-flex; align-items: center; gap: var(--sheen-space-inline-xs); }
@@ -114,10 +119,10 @@
114
119
  .sheen-data-table td[data-editable][data-invalid], .sheen-data-table td[data-editable][data-conflict] { z-index: calc(var(--sheen-z-chrome) + 3); overflow: visible; }
115
120
  .sheen-data-table-edit-value { display: flex; align-items: center; gap: var(--sheen-space-inline-xs); min-inline-size: 0; }
116
121
  .sheen-data-table-edit-rest { display: block; min-inline-size: 0; inline-size: 100%; overflow: hidden; border-radius: var(--sheen-control-radius); text-overflow: ellipsis; white-space: nowrap; cursor: text; }
117
- .sheen-data-table-edit-rest:focus-visible { outline: var(--sheen-focus-ring-width) solid var(--sheen-color-focus-ring); outline-offset: var(--sheen-focus-ring-offset); }
122
+ .sheen-data-table-edit-rest:focus-visible { outline: 2px solid var(--sheen-color-focus-ring); outline-offset: -2px; }
118
123
  .sheen-data-table-editor { box-sizing: border-box; min-inline-size: 0; inline-size: 100%; block-size: calc(var(--sheen-table-row-h) - 0.35rem); padding-inline: var(--sheen-space-inline-xs); color: var(--sheen-color-fg); background: var(--sheen-color-bg-inset); border: 1px solid var(--sheen-color-border-control); border-radius: var(--sheen-control-radius); font: inherit; }
119
124
  .sheen-data-table-editor-boolean { inline-size: 1rem; block-size: 1rem; padding: 0; accent-color: var(--sheen-color-accent); }
120
- .sheen-data-table-editor:focus-visible { outline: var(--sheen-focus-ring-width) solid var(--sheen-color-focus-ring); outline-offset: var(--sheen-focus-ring-offset); }
125
+ .sheen-data-table-editor:focus-visible { outline: 2px solid var(--sheen-color-focus-ring); outline-offset: -2px; }
121
126
  .sheen-data-table-edit-message { position: absolute; inset-block-start: calc(100% - 1px); inset-inline-start: var(--sheen-space-inline-sm); min-inline-size: min(16rem, calc(100vw - 2rem)); max-inline-size: 24rem; padding: var(--sheen-space-inline-xs) var(--sheen-space-inline-sm); color: var(--sheen-color-danger-fg); background: var(--sheen-color-bg-raised); border: 1px solid var(--sheen-color-danger-border); border-radius: var(--sheen-surface-radius); box-shadow: var(--sheen-elevation-overlay); font-size: var(--sheen-text-ui-sm-size); line-height: var(--sheen-text-ui-sm-leading); white-space: normal; }
122
127
  .sheen-data-table-empty { min-block-size: var(--sheen-table-row-h); }
123
128
  .sheen-data-table-empty td { grid-column: 1 / -1; block-size: auto; min-block-size: var(--sheen-table-row-h); padding: 0; overflow: visible; white-space: normal; color: var(--sheen-color-fg-muted); }
@@ -155,7 +160,7 @@
155
160
  .sheen-query-rule-fields :is(.sheen-field-label, .sheen-checkbox-group-label) { font-size: var(--sheen-text-caption-size); line-height: var(--sheen-text-caption-leading); }
156
161
  .sheen-query-empty { margin: var(--sheen-space-block-sm) 0 0; color: var(--sheen-color-fg-muted); font-size: var(--sheen-text-ui-sm-size); }
157
162
  .sheen-query-announcement { position: absolute; inline-size: 1px; block-size: 1px; padding: 0; margin: -1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; }
158
- @media (max-width: 767px) {
163
+ @media (width < 48rem) {
159
164
  .sheen-query-rule { display: grid; }
160
165
  .sheen-query-rule-fields { grid-template-columns: minmax(0, 1fr); }
161
166
  .sheen-query-node-actions { justify-content: flex-end; margin-inline-start: 0; }
@@ -171,7 +176,7 @@
171
176
  .sheen-data-table-mobile-card { --sheen-color-focus-ring-offset: var(--sheen-color-bg); display: grid; gap: var(--sheen-space-block-sm); min-inline-size: 0; padding: var(--sheen-space-block-md) var(--sheen-space-inline-md); overflow: visible; background: var(--sheen-color-bg); border: 1px solid var(--sheen-color-border); border-radius: var(--sheen-surface-radius); box-shadow: var(--sheen-shadow-1); }
172
177
  .sheen-data-table-mobile-card[data-selected] { background: var(--sheen-color-bg-selected); border-color: var(--sheen-color-border-control); }
173
178
  .sheen-data-table-mobile-card[data-load-error] { border-inline-start: 3px solid var(--sheen-color-danger-border); }
174
- .sheen-data-table-mobile-card:focus-visible { outline: var(--sheen-focus-ring-width) solid var(--sheen-color-focus-ring); outline-offset: var(--sheen-focus-ring-offset); }
179
+ .sheen-data-table-mobile-card:focus-visible { outline: 2px solid var(--sheen-color-focus-ring); outline-offset: -2px; }
175
180
  .sheen-data-table-mobile-card-header { display: flex; align-items: center; gap: var(--sheen-space-inline-sm); min-inline-size: 0; }
176
181
  .sheen-data-table-mobile-title { flex: 1 1 auto; min-inline-size: 0; font-size: var(--sheen-text-h4-size); line-height: var(--sheen-text-h4-leading); font-weight: var(--sheen-text-h4-weight); overflow-wrap: anywhere; }
177
182
  .sheen-data-table-mobile-fields, .sheen-data-table-mobile-footer { display: grid; gap: var(--sheen-space-block-xs); min-inline-size: 0; margin: 0; }
@@ -196,4 +201,5 @@
196
201
  @keyframes sheen-table-refresh { from { translate: -100% 0; } to { translate: 285% 0; } }
197
202
  @keyframes sheen-table-selection-enter { from { opacity: 0; transform: translateY(0.35rem); } to { opacity: 1; transform: translateY(0); } }
198
203
  @keyframes sheen-table-selection-exit { from { opacity: 1; transform: translateY(0); } to { opacity: 0; transform: translateY(0.35rem); } }
204
+ .sheen-data-table-mobile-card-header [data-sheen-menu-trigger] { inline-size: var(--sheen-control-h-md); min-inline-size: var(--sheen-control-h-md); padding: 0; flex: none; }
199
205
  }
@@ -1,11 +1,13 @@
1
- import { changeClientViewState } from "./client-state.ts";
2
- import type { ClientStateChange } from "./client-state.ts";
1
+ import { changeQueryState } from "./client-state.ts";
2
+ import type { ClientStateChange, QueryState } from "./client-state.ts";
3
+ import { parseCursorPagination, parsePagination } from "./pagination.ts";
4
+ import type { CursorPagination, ServerPagination, TablePagination } from "./pagination.ts";
3
5
  import type { SortEntry, SortState } from "./sorting.ts";
4
- import { parseTableState } from "./table-state.ts";
5
- import type { ColumnState, TableState, TableStateSchema } from "./table-state.ts";
6
+ import { parseTableStateWith, schemaPagination } from "./table-state.ts";
7
+ import type { ColumnState, CursorTableStateSchema, TableState, TableStateSchema, TableStateSchemaFields } from "./table-state.ts";
6
8
 
7
- export type TableStateChange =
8
- | { readonly kind: "query"; readonly change: ClientStateChange }
9
+ export type TableStateChange<Pagination extends ServerPagination = TablePagination> =
10
+ | { readonly kind: "query"; readonly change: ClientStateChange<Pagination> }
9
11
  | { readonly kind: "sortCycle"; readonly column: string; readonly multiple: boolean }
10
12
  | { readonly kind: "columnOrder"; readonly ids: readonly string[] }
11
13
  | { readonly kind: "columnVisibility"; readonly column: string; readonly visible: boolean }
@@ -13,11 +15,19 @@ export type TableStateChange =
13
15
  | { readonly kind: "columnPin"; readonly column: string; readonly pin: ColumnState["pin"] };
14
16
 
15
17
  /** Pure requested-state update. Apply accepted layout/query/results atomically in the table owner. */
16
- export function changeTableState(value: TableState, change: TableStateChange, schema: TableStateSchema): TableState {
17
- const state = parseTableState(value, schema);
18
+ export function changeTableState(value: TableState<CursorPagination>, change: TableStateChange<CursorPagination>, schema: CursorTableStateSchema): TableState<CursorPagination>;
19
+ export function changeTableState(value: TableState, change: TableStateChange, schema: TableStateSchema): TableState;
20
+ export function changeTableState(value: TableState<ServerPagination>, change: TableStateChange<ServerPagination>, schema: TableStateSchema | CursorTableStateSchema): TableState<ServerPagination> {
21
+ return schemaPagination(schema) === "cursor" ? changeTableStateWith(value, change, schema, parseCursorPagination) : changeTableStateWith(value, change, schema, parsePagination);
22
+ }
23
+
24
+ export function changeTableStateWith<Pagination extends ServerPagination>(value: TableState<Pagination>, change: TableStateChange<Pagination>, schema: TableStateSchemaFields, readPagination: (value: unknown) => Pagination): TableState<Pagination> {
25
+ const parse = (next: unknown) => parseTableStateWith(next, schema, readPagination);
26
+ const changeQuery = (query: QueryState<Pagination>, queryChange: ClientStateChange<Pagination>) => changeQueryState(query, queryChange, schema, readPagination);
27
+ const state = parse(value);
18
28
  const query = { search: state.search, filter: state.filter, sorting: state.sorting, pagination: state.pagination };
19
29
  switch (change.kind) {
20
- case "query": return parseTableState({ ...changeClientViewState(query, change.change, schema), columns: state.columns }, schema);
30
+ case "query": return parse({ ...changeQuery(query, change.change), columns: state.columns });
21
31
  case "sortCycle": {
22
32
  if (!schema.sortColumns.some(column => column.id === change.column)) throw new Error(`Column does not support sorting: ${change.column}`);
23
33
  const current = state.sorting.find(entry => entry.column === change.column);
@@ -26,11 +36,11 @@ export function changeTableState(value: TableState, change: TableStateChange, sc
26
36
  if (!change.multiple) sorting = next ? [next] : [];
27
37
  else if (!current && next) sorting = [...state.sorting, next];
28
38
  else sorting = state.sorting.flatMap(entry => entry.column === change.column ? next ? [next] : [] : [entry]);
29
- return parseTableState({ ...changeClientViewState(query, { kind: "sorting", value: sorting }, schema), columns: state.columns }, schema);
39
+ return parse({ ...changeQuery(query, { kind: "sorting", value: sorting }), columns: state.columns });
30
40
  }
31
41
  case "columnOrder": {
32
42
  const columns = new Map(state.columns.map(column => [column.id, column]));
33
- return parseTableState({ ...state, columns: Array.from(change.ids, id => columns.get(id)) }, schema);
43
+ return parse({ ...state, columns: Array.from(change.ids, id => columns.get(id)) });
34
44
  }
35
45
  case "columnVisibility":
36
46
  case "columnWidth":
@@ -44,7 +54,7 @@ export function changeTableState(value: TableState, change: TableStateChange, sc
44
54
  case "columnPin": return { ...column, pin: change.pin };
45
55
  }
46
56
  });
47
- return parseTableState({ ...state, columns }, schema);
57
+ return parse({ ...state, columns });
48
58
  }
49
59
  default: throw new Error("Unknown table state change");
50
60
  }