@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.
- package/dist/DataTable.d.ts +57 -13
- package/dist/DataTable.js +963 -820
- package/dist/FilterBar.d.ts +3 -3
- package/dist/FilterBar.js +5 -1
- package/dist/client-state.d.ts +9 -3
- package/dist/client-state.js +38 -32
- package/dist/core.d.ts +5 -5
- package/dist/core.js +28 -28
- package/dist/data-table-features.d.ts +18 -13
- package/dist/data-table-features.js +11 -1
- package/dist/index.d.ts +5 -3
- package/dist/index.js +32 -31
- package/dist/messages.d.ts +3 -0
- package/dist/messages.js +3 -0
- package/dist/pagination.d.ts +43 -1
- package/dist/pagination.js +109 -54
- package/dist/requests.d.ts +3 -3
- package/dist/requests.js +38 -28
- package/dist/saved-views.d.ts +17 -14
- package/dist/saved-views.js +71 -68
- package/dist/server-export.d.ts +16 -7
- package/dist/server-export.js +57 -53
- package/dist/table-state-changes.d.ts +6 -3
- package/dist/table-state-changes.js +44 -40
- package/dist/table-state.d.ts +20 -4
- package/dist/table-state.js +66 -40
- package/dist/url-state.d.ts +12 -9
- package/dist/url-state.js +33 -30
- package/package.json +3 -3
- package/src/DataTable.tsx +221 -61
- package/src/FilterBar.tsx +5 -3
- package/src/client-state.ts +31 -17
- package/src/core.ts +5 -5
- package/src/data-table-features.tsx +23 -10
- package/src/index.ts +5 -3
- package/src/messages.ts +1 -1
- package/src/pagination.ts +83 -14
- package/src/requests.ts +22 -8
- package/src/saved-views.ts +33 -11
- package/src/server-export.ts +17 -11
- package/src/table-state-changes.ts +22 -12
- package/src/table-state.ts +53 -11
- package/src/url-state.ts +27 -10
package/src/client-state.ts
CHANGED
|
@@ -2,7 +2,7 @@ import type { ClientViewState } from "./client-view.ts";
|
|
|
2
2
|
import { parseFilter } from "./filter.ts";
|
|
3
3
|
import type { FilterColumn, FilterNode } from "./filter.ts";
|
|
4
4
|
import { parsePagination, resetPagination, resizePagination } from "./pagination.ts";
|
|
5
|
-
import type { TablePagination } from "./pagination.ts";
|
|
5
|
+
import type { ServerPagination, TablePagination } from "./pagination.ts";
|
|
6
6
|
import { parseSorting } from "./sorting.ts";
|
|
7
7
|
import type { SortColumn, SortState } from "./sorting.ts";
|
|
8
8
|
|
|
@@ -10,15 +10,18 @@ export interface ClientStateSchema {
|
|
|
10
10
|
readonly filterColumns: readonly FilterColumn[];
|
|
11
11
|
readonly sortColumns: readonly SortColumn[];
|
|
12
12
|
}
|
|
13
|
-
export type ClientStateChange =
|
|
13
|
+
export type ClientStateChange<Pagination extends ServerPagination = TablePagination> =
|
|
14
14
|
| { readonly kind: "search"; readonly value: string }
|
|
15
15
|
| { readonly kind: "filter"; readonly value: FilterNode }
|
|
16
16
|
| { readonly kind: "sorting"; readonly value: SortState }
|
|
17
|
-
| { readonly kind: "pagination"; readonly value:
|
|
17
|
+
| { readonly kind: "pagination"; readonly value: Pagination }
|
|
18
18
|
| { readonly kind: "pageSize"; readonly value: number };
|
|
19
|
+
/** Query state whose pagination kind is fixed by the parser that validated it. */
|
|
20
|
+
export interface QueryState<Pagination extends ServerPagination = TablePagination> extends Omit<ClientViewState, "pagination"> {
|
|
21
|
+
readonly pagination: Pagination;
|
|
22
|
+
}
|
|
19
23
|
|
|
20
|
-
|
|
21
|
-
export function parseClientViewState(value: unknown, schema: ClientStateSchema): ClientViewState {
|
|
24
|
+
export function parseQueryState<Pagination extends ServerPagination>(value: unknown, schema: ClientStateSchema, readPagination: (value: unknown) => Pagination): QueryState<Pagination> {
|
|
22
25
|
if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Invalid client state: expected an object");
|
|
23
26
|
if (Object.keys(value).some(key => !["search", "filter", "sorting", "pagination"].includes(key))) throw new Error("Invalid client state: unknown field");
|
|
24
27
|
if (!("search" in value) || typeof value.search !== "string") throw new Error("Invalid client state: search must be a string");
|
|
@@ -27,26 +30,37 @@ export function parseClientViewState(value: unknown, schema: ClientStateSchema):
|
|
|
27
30
|
search: value.search,
|
|
28
31
|
filter: parseFilter(value.filter, schema.filterColumns),
|
|
29
32
|
sorting: parseSorting(value.sorting, schema.sortColumns),
|
|
30
|
-
pagination:
|
|
33
|
+
pagination: readPagination(value.pagination),
|
|
31
34
|
});
|
|
32
35
|
}
|
|
33
36
|
|
|
34
|
-
/**
|
|
35
|
-
export function
|
|
36
|
-
|
|
37
|
+
/** Query-state fragment only; column layout, selection, and saved-view envelopes are separate. */
|
|
38
|
+
export function parseClientViewState(value: unknown, schema: ClientStateSchema): ClientViewState {
|
|
39
|
+
return parseQueryState(value, schema, parsePagination);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export function changeQueryState<Pagination extends ServerPagination>(state: QueryState<Pagination>, change: ClientStateChange<Pagination>, schema: ClientStateSchema, readPagination: (value: unknown) => Pagination): QueryState<Pagination> {
|
|
43
|
+
const current = parseQueryState(state, schema, readPagination);
|
|
44
|
+
const existing: ServerPagination = current.pagination;
|
|
45
|
+
const parse = (next: QueryState<ServerPagination>) => parseQueryState(next, schema, readPagination);
|
|
37
46
|
switch (change.kind) {
|
|
38
|
-
case "search": return
|
|
39
|
-
case "filter": return
|
|
40
|
-
case "sorting": return
|
|
47
|
+
case "search": return parse({ ...current, search: change.value, pagination: resetPagination(existing) });
|
|
48
|
+
case "filter": return parse({ ...current, filter: change.value, pagination: resetPagination(existing) });
|
|
49
|
+
case "sorting": return parse({ ...current, sorting: change.value, pagination: resetPagination(existing) });
|
|
41
50
|
case "pagination": {
|
|
42
|
-
const pagination =
|
|
43
|
-
const resized = pagination !== false &&
|
|
44
|
-
return
|
|
51
|
+
const pagination: ServerPagination = readPagination(change.value);
|
|
52
|
+
const resized = pagination !== false && existing !== false && pagination.pageSize !== existing.pageSize;
|
|
53
|
+
return parse({ ...current, pagination: resized ? resetPagination(pagination) : pagination });
|
|
45
54
|
}
|
|
46
55
|
case "pageSize": {
|
|
47
|
-
if (
|
|
48
|
-
return
|
|
56
|
+
if (existing === false) throw new Error("Page-size changes require pagination to be enabled");
|
|
57
|
+
return parse({ ...current, pagination: resizePagination(existing, change.value) });
|
|
49
58
|
}
|
|
50
59
|
default: throw new Error("Unknown client state change");
|
|
51
60
|
}
|
|
52
61
|
}
|
|
62
|
+
|
|
63
|
+
/** Changes requested state only. Accepted rows/state remain owned by the result controller. */
|
|
64
|
+
export function changeClientViewState(state: ClientViewState, change: ClientStateChange, schema: ClientStateSchema): ClientViewState {
|
|
65
|
+
return changeQueryState(state, change, schema, parsePagination);
|
|
66
|
+
}
|
package/src/core.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
export { parsePagination, resolvePagination, resetPagination, resizePagination, getPageRange, paginateClientRows, assessServerPage } from "./pagination.ts";
|
|
2
|
-
export type { PageState, TablePagination, PageRange, PageResult, ServerPageAssessment } from "./pagination.ts";
|
|
1
|
+
export { parsePagination, parseCursorPagination, parseServerPagination, resolvePagination, resetPagination, resizePagination, getPageRange, paginateClientRows, assessServerPage, assessCursorPage } from "./pagination.ts";
|
|
2
|
+
export type { PageState, TablePagination, CursorPosition, CursorPagination, ServerPagination, CursorTotal, CursorPageResult, CursorPageAssessment, PageRange, PageResult, ServerPageAssessment } from "./pagination.ts";
|
|
3
3
|
export { createTableRequests } from "./requests.ts";
|
|
4
4
|
export type { TableRequestState, TableRequestSnapshot, TableRequestOutcome, InitialTableResult } from "./requests.ts";
|
|
5
5
|
export { parseFilter, serializeFilter, deserializeFilter } from "./filter.ts";
|
|
@@ -23,7 +23,7 @@ export type { ClientView, ClientViewState, ClientViewOptions } from "./client-vi
|
|
|
23
23
|
export { parseClientViewState, changeClientViewState } from "./client-state.ts";
|
|
24
24
|
export type { ClientStateSchema, ClientStateChange } from "./client-state.ts";
|
|
25
25
|
export { parseTableState, serializeState, deserializeState } from "./table-state.ts";
|
|
26
|
-
export type { ColumnState, TableState, TableStateSchema } from "./table-state.ts";
|
|
26
|
+
export type { ColumnState, TableState, TableStateSchema, CursorTableStateSchema } from "./table-state.ts";
|
|
27
27
|
export { changeTableState } from "./table-state-changes.ts";
|
|
28
28
|
export type { TableStateChange } from "./table-state-changes.ts";
|
|
29
29
|
export { orderColumnStates, placeColumn, moveColumn, canMoveColumn } from "./column-layout.ts";
|
|
@@ -47,8 +47,8 @@ export type { GroupAggregateColumn, GroupAggregateValue, ClientRowGroup, ServerR
|
|
|
47
47
|
export { createRowHierarchy } from "./row-hierarchy.ts";
|
|
48
48
|
export type { HierarchyLoadOutcome, RowHierarchyOptions, HierarchyRow } from "./row-hierarchy.ts";
|
|
49
49
|
export { createTableUrlState } from "./url-state.ts";
|
|
50
|
-
export type { TableUrlLocation, TableUrlRouter, TableUrlRead, TableUrlWrite } from "./url-state.ts";
|
|
50
|
+
export type { TableUrlLocation, TableUrlRouter, TableUrlRead, TableUrlWrite, TableUrlState } from "./url-state.ts";
|
|
51
51
|
export { createSavedViews } from "./saved-views.ts";
|
|
52
|
-
export type { SavedViewRecord, SavedViewSave, SavedViewsAdapter, SavedViewOperation, SavedViewsSnapshot, SavedViewOutcome, SavedViewRestore } from "./saved-views.ts";
|
|
52
|
+
export type { SavedViews, SavedViewRecord, SavedViewSave, SavedViewsAdapter, SavedViewOperation, SavedViewsSnapshot, SavedViewOutcome, SavedViewRestore } from "./saved-views.ts";
|
|
53
53
|
export { englishTableMessages, resolveTableMessages } from "./messages.ts";
|
|
54
54
|
export type { TableMessages } from "./messages.ts";
|
|
@@ -4,7 +4,7 @@ import type { Accessor, JSX } from "solid-js";
|
|
|
4
4
|
import type { ColumnEditor, ColumnValue, ResolvedColumn } from "./columns.ts";
|
|
5
5
|
import { createCellEdit } from "./cell-edit.ts";
|
|
6
6
|
import type { CellCommitOutcome, CellEditSnapshot } from "./cell-edit.ts";
|
|
7
|
-
import type { DataTableCellCommitRequest,
|
|
7
|
+
import type { DataTableCellCommitRequest, DataTableInternalProps, DataTableResult } from "./DataTable.tsx";
|
|
8
8
|
import type { FilterColumn, FilterNode } from "./filter.ts";
|
|
9
9
|
import { groupClientRows, normalizeServerGroups } from "./grouping.ts";
|
|
10
10
|
import type { ClientRowGroup } from "./grouping.ts";
|
|
@@ -52,15 +52,15 @@ export type DisplayRow<Row extends object> = DisplayDataRow<Row> | DisplayGroupR
|
|
|
52
52
|
|
|
53
53
|
/** What a feature may read from, and ask of, the table that composes it. */
|
|
54
54
|
export interface DataTableFeatureContext<Row extends object> {
|
|
55
|
-
readonly props:
|
|
55
|
+
readonly props: DataTableInternalProps<Row>;
|
|
56
56
|
readonly definitions: readonly ResolvedColumn<Row>[];
|
|
57
57
|
readonly filterColumns: readonly FilterColumn[];
|
|
58
58
|
readonly messages: Accessor<TableMessages>;
|
|
59
59
|
readonly locale: Accessor<string>;
|
|
60
60
|
/** A query is unsettled. Structural changes wait for accepted state. */
|
|
61
61
|
readonly pending: Accessor<boolean>;
|
|
62
|
-
/** Accepted rows,
|
|
63
|
-
readonly result: Accessor<DataTableResult<Row>>;
|
|
62
|
+
/** Accepted rows, facets, and server groups. Totals stay with the table because cursor pages may not know them. */
|
|
63
|
+
readonly result: Accessor<Pick<DataTableResult<Row>, "rows" | "facets" | "groups">>;
|
|
64
64
|
readonly accepted: Accessor<boolean>;
|
|
65
65
|
readonly acceptedFilter: Accessor<FilterNode>;
|
|
66
66
|
readonly requestFilter: (filter: FilterNode) => void;
|
|
@@ -110,11 +110,17 @@ export interface DataTableFeatureInstance<Row extends object> {
|
|
|
110
110
|
readonly overlay?: () => JSX.Element;
|
|
111
111
|
}
|
|
112
112
|
|
|
113
|
+
export type DataTableFeatureId = "filterBar" | "grouping" | "hierarchy" | "cellEditing";
|
|
114
|
+
|
|
113
115
|
/**
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
+
* An opt-in DataTable capability for `createDataTable`. Only Sheen's exported features are supported; the
|
|
117
|
+
* context contract is internal. A feature validates the props it owns and returns undefined when inactive.
|
|
118
|
+
* Features are row-agnostic so one list type-checks against any DataTable.
|
|
116
119
|
*/
|
|
117
|
-
export
|
|
120
|
+
export interface DataTableFeature<Id extends DataTableFeatureId = DataTableFeatureId> {
|
|
121
|
+
readonly id: Id;
|
|
122
|
+
readonly create: <Row extends object>(context: DataTableFeatureContext<Row>) => DataTableFeatureInstance<Row> | undefined;
|
|
123
|
+
}
|
|
118
124
|
|
|
119
125
|
export function defaultCell(value: ColumnValue): JSX.Element {
|
|
120
126
|
if (value === null) return "";
|
|
@@ -200,7 +206,7 @@ function plainKey(event: KeyboardEvent): boolean {
|
|
|
200
206
|
}
|
|
201
207
|
|
|
202
208
|
/** First-seen groups over complete client data or delegated server groups for the accepted page. */
|
|
203
|
-
|
|
209
|
+
function grouping<Row extends object>(context: DataTableFeatureContext<Row>): DataTableFeatureInstance<Row> | undefined {
|
|
204
210
|
const props = context.props;
|
|
205
211
|
const options = props.grouping;
|
|
206
212
|
if (!options) return undefined;
|
|
@@ -287,7 +293,7 @@ export function groupingFeature<Row extends object>(context: DataTableFeatureCon
|
|
|
287
293
|
}
|
|
288
294
|
|
|
289
295
|
/** Expandable parent rows with synchronous children or independently loaded subtrees. */
|
|
290
|
-
|
|
296
|
+
function hierarchy<Row extends object>(context: DataTableFeatureContext<Row>): DataTableFeatureInstance<Row> | undefined {
|
|
291
297
|
const props = context.props;
|
|
292
298
|
const options = props.hierarchy;
|
|
293
299
|
if (!options) return undefined;
|
|
@@ -388,7 +394,7 @@ interface CellEditRecord {
|
|
|
388
394
|
}
|
|
389
395
|
|
|
390
396
|
/** Inline editing for columns that declare an editor. Drafts survive virtualization until the reset boundary changes. */
|
|
391
|
-
|
|
397
|
+
function cellEditing<Row extends object>(context: DataTableFeatureContext<Row>): DataTableFeatureInstance<Row> | undefined {
|
|
392
398
|
const props = context.props;
|
|
393
399
|
const editable = context.definitions.filter(column => column.editor !== null);
|
|
394
400
|
if (editable.length > 0 && !props.onCellCommit) throw new Error("DataTable editable columns require onCellCommit");
|
|
@@ -577,3 +583,10 @@ export function cellEditingFeature<Row extends object>(context: DataTableFeature
|
|
|
577
583
|
overlay: () => <Toaster controller={toaster} />,
|
|
578
584
|
};
|
|
579
585
|
}
|
|
586
|
+
|
|
587
|
+
/** Client or delegated server grouping through the `grouping` prop. */
|
|
588
|
+
export const groupingFeature: DataTableFeature<"grouping"> = { id: "grouping", create: grouping };
|
|
589
|
+
/** Expandable row trees through the `hierarchy` prop. */
|
|
590
|
+
export const hierarchyFeature: DataTableFeature<"hierarchy"> = { id: "hierarchy", create: hierarchy };
|
|
591
|
+
/** Inline editing for columns that declare an editor, through `onCellCommit` and `editResetKey`. */
|
|
592
|
+
export const cellEditingFeature: DataTableFeature<"cellEditing"> = { id: "cellEditing", create: cellEditing };
|
package/src/index.ts
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
export * from "./core.ts";
|
|
2
|
-
export { DataTable } from "./DataTable.tsx";
|
|
3
|
-
export
|
|
4
|
-
export {
|
|
2
|
+
export { DataTable, createDataTable } from "./DataTable.tsx";
|
|
3
|
+
export { groupingFeature, hierarchyFeature, cellEditingFeature } from "./data-table-features.tsx";
|
|
4
|
+
export type { DataTableFeature, DataTableFeatureId } from "./data-table-features.tsx";
|
|
5
|
+
export type { ComposedDataTable, ComposedDataTableProps, DataTableProps, DataTableResult, DataTableCursorResult, DataTableInitialState, DataTableSelectionOptions, DataTableGroupingOptions, DataTableHierarchyOptions, DataTableExportFormat, DataTableExportOptions, DataTableCellCommitRequest, DataTableAction, DataTableActionContext, DataTableMobileLayoutOptions, DataTableVariant, DataTableDensity, DataTableSearchOptions, DataTableFilterBarOptions, ClientDataTableProps, ServerDataTableProps } from "./DataTable.tsx";
|
|
6
|
+
export { FilterBar, filterBarFeature } from "./FilterBar.tsx";
|
|
5
7
|
export type { FilterBarProps, FilterDateEditor, FilterDateEditorProps } from "./FilterBar.tsx";
|
|
6
8
|
export { QueryBuilder } from "./QueryBuilder.tsx";
|
|
7
9
|
export type { QueryBuilderProps } from "./QueryBuilder.tsx";
|
package/src/messages.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
export const englishTableMessages = Object.freeze({
|
|
2
2
|
loading: "Loading", refreshing: "Refreshing, showing existing results", noResults: "No results", retry: "Retry", retryFailed: "Retry failed. Try again.", serverError: "Something went wrong",
|
|
3
|
-
searchTable: "Search {caption}", searchMatchMode: "Search match mode", searchRanked: "Smart", searchExact: "Exact", tableShortcuts: "Tables", tableControls: "{caption} table controls", resultCountOne: "{count} result", resultCount: "{count} results",
|
|
3
|
+
searchTable: "Search {caption}", searchMatchMode: "Search match mode", searchRanked: "Smart", searchExact: "Exact", tableShortcuts: "Tables", tableControls: "{caption} table controls", resultCountOne: "{count} result", resultCount: "{count} results", resultCountEstimate: "About {count} results", resultCountAtLeast: "{count}+ results", cursorPageRows: "Rows on this page: {count}",
|
|
4
4
|
previousResults: "Previous results", clearFilters: "Clear filters", clearSearchAndFilters: "Clear search and filters", selectAll: "Select all matching", selectPage: "Select this page", selectRow: "Select row {id}", clearSelection: "Clear selection", selectionActions: "Selection actions", selectedCount: "{count} selected",
|
|
5
5
|
cardView: "{caption}, card view", rowActions: "Actions for row {id}",
|
|
6
6
|
sort: "Sort", sortColumn: "Sort by {column}", sortedAscending: "ascending", sortedDescending: "descending", notSorted: "not sorted", sortPriority: "priority {position} of {count}",
|
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
|
-
|
|
51
|
+
closed(value, ["pageIndex", "pageSize"]);
|
|
17
52
|
nonnegativeInteger(value.pageIndex, "pageIndex");
|
|
18
|
-
|
|
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(
|
|
59
|
+
if (mode === "server") throw new Error(explicitServerPagination);
|
|
27
60
|
return false;
|
|
28
61
|
}
|
|
29
62
|
return parsePagination(value);
|
|
30
63
|
}
|
|
31
64
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
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,
|
|
2
|
-
import type { PageResult,
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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 =
|
|
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 };
|
package/src/saved-views.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import
|
|
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
|
-
|
|
60
|
-
|
|
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
|
-
|
|
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
|
|
112
|
-
const view = Object.freeze({ id: id === null ? null : text(id, "Saved view ID"), name: text(name, "Saved view name"), state:
|
|
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:
|
|
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/server-export.ts
CHANGED
|
@@ -1,25 +1,27 @@
|
|
|
1
1
|
import { parseFilter } from "./filter.ts";
|
|
2
2
|
import type { BulkSelection } from "./selection.ts";
|
|
3
|
-
import {
|
|
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
|
|
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
|
|
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 =
|
|
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
|
-
|
|
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";
|