@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
|
@@ -1,11 +1,13 @@
|
|
|
1
|
-
import {
|
|
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 {
|
|
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
|
|
17
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
57
|
+
return parse({ ...state, columns });
|
|
48
58
|
}
|
|
49
59
|
default: throw new Error("Unknown table state change");
|
|
50
60
|
}
|
package/src/table-state.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import type { ClientStateSchema } from "./client-state.ts";
|
|
3
|
-
import
|
|
1
|
+
import { parseQueryState } from "./client-state.ts";
|
|
2
|
+
import type { ClientStateSchema, QueryState } from "./client-state.ts";
|
|
3
|
+
import { parseCursorPagination, parsePagination } from "./pagination.ts";
|
|
4
|
+
import type { CursorPagination, ServerPagination, TablePagination } from "./pagination.ts";
|
|
4
5
|
|
|
5
6
|
export interface ColumnState {
|
|
6
7
|
readonly id: string;
|
|
@@ -9,13 +10,22 @@ export interface ColumnState {
|
|
|
9
10
|
readonly width: number | null;
|
|
10
11
|
readonly pin: "start" | "end" | false;
|
|
11
12
|
}
|
|
12
|
-
export interface TableState extends
|
|
13
|
+
export interface TableState<Pagination extends ServerPagination = TablePagination> extends QueryState<Pagination> {
|
|
13
14
|
/** Array order is the user-defined column order. Every available column occurs once. */
|
|
14
15
|
readonly columns: readonly ColumnState[];
|
|
15
16
|
}
|
|
16
|
-
|
|
17
|
+
/** Shared column and query fields; internal pagination-generic owners accept it. */
|
|
18
|
+
export interface TableStateSchemaFields extends ClientStateSchema {
|
|
17
19
|
readonly columns: readonly string[];
|
|
18
20
|
}
|
|
21
|
+
/** Schema for complete or numbered pagination state. */
|
|
22
|
+
export interface TableStateSchema extends TableStateSchemaFields {
|
|
23
|
+
readonly pagination?: never;
|
|
24
|
+
}
|
|
25
|
+
/** Schema for cursor pagination state. Persisted envelopes always store `cursor: null` because cursor tokens are short-lived. */
|
|
26
|
+
export interface CursorTableStateSchema extends TableStateSchemaFields {
|
|
27
|
+
readonly pagination: "cursor";
|
|
28
|
+
}
|
|
19
29
|
|
|
20
30
|
function record(value: unknown): value is Record<string, unknown> {
|
|
21
31
|
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
@@ -25,8 +35,29 @@ function exact(value: Record<string, unknown>, fields: readonly string[], path:
|
|
|
25
35
|
for (const key of fields) if (!Object.hasOwn(value, key)) throw new Error(`Invalid table state at ${path}: missing ${key}`);
|
|
26
36
|
}
|
|
27
37
|
|
|
38
|
+
/** Cursor schemas read only cursor state; other schemas read complete or numbered state. Unknown schema kinds fail closed. */
|
|
39
|
+
export function schemaPagination(schema: TableStateSchema | CursorTableStateSchema): "cursor" | "page" {
|
|
40
|
+
const kind: unknown = schema.pagination;
|
|
41
|
+
if (kind === undefined) return "page";
|
|
42
|
+
if (kind === "cursor") return kind;
|
|
43
|
+
throw new Error("Table state schema pagination must be omitted or cursor");
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** Persisted cursor state is always the first page; a stored live token fails closed. */
|
|
47
|
+
function parsePersistedCursor(value: unknown): CursorPagination {
|
|
48
|
+
const pagination = parseCursorPagination(value);
|
|
49
|
+
if (pagination.cursor !== null) throw new Error("Persisted cursor pagination must use cursor: null");
|
|
50
|
+
return pagination;
|
|
51
|
+
}
|
|
52
|
+
|
|
28
53
|
/** Strictly validate before applying saved/URL state, never partially restore it. */
|
|
29
|
-
export function parseTableState(value: unknown, schema:
|
|
54
|
+
export function parseTableState(value: unknown, schema: CursorTableStateSchema): TableState<CursorPagination>;
|
|
55
|
+
export function parseTableState(value: unknown, schema: TableStateSchema): TableState;
|
|
56
|
+
export function parseTableState(value: unknown, schema: TableStateSchema | CursorTableStateSchema): TableState<ServerPagination> {
|
|
57
|
+
return schemaPagination(schema) === "cursor" ? parseTableStateWith(value, schema, parseCursorPagination) : parseTableStateWith(value, schema, parsePagination);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export function parseTableStateWith<Pagination extends ServerPagination>(value: unknown, schema: TableStateSchemaFields, readPagination: (value: unknown) => Pagination): TableState<Pagination> {
|
|
30
61
|
const available = new Set<string>();
|
|
31
62
|
for (const id of schema.columns) {
|
|
32
63
|
if (typeof id !== "string" || !id.trim() || available.has(id)) throw new Error("Invalid or duplicate table schema column");
|
|
@@ -37,7 +68,7 @@ export function parseTableState(value: unknown, schema: TableStateSchema): Table
|
|
|
37
68
|
}
|
|
38
69
|
if (!record(value)) throw new Error("Invalid table state: expected an object");
|
|
39
70
|
exact(value, ["search", "filter", "sorting", "pagination", "columns"], "$");
|
|
40
|
-
const query =
|
|
71
|
+
const query = parseQueryState({ search: value.search, filter: value.filter, sorting: value.sorting, pagination: value.pagination }, schema, readPagination);
|
|
41
72
|
if (!Array.isArray(value.columns) || value.columns.length !== available.size) throw new Error("Invalid table state: expected one state entry per available column");
|
|
42
73
|
const seen = new Set<string>();
|
|
43
74
|
const columns = Array.from(value.columns, (entry: unknown, index): ColumnState => {
|
|
@@ -54,13 +85,24 @@ export function parseTableState(value: unknown, schema: TableStateSchema): Table
|
|
|
54
85
|
return Object.freeze({ ...query, columns: Object.freeze(columns) });
|
|
55
86
|
}
|
|
56
87
|
|
|
57
|
-
|
|
58
|
-
const serialized = JSON.stringify({ version: 1, state
|
|
88
|
+
function toEnvelope(state: TableState<ServerPagination>): string {
|
|
89
|
+
const serialized = JSON.stringify({ version: 1, state });
|
|
59
90
|
if (serialized.length > 262144) throw new Error("Serialized table state exceeds 262144 characters");
|
|
60
91
|
return serialized;
|
|
61
92
|
}
|
|
62
93
|
|
|
63
|
-
|
|
94
|
+
/** Cursor state is persisted as its first page: the live cursor token is replaced with null. */
|
|
95
|
+
export function serializeState(state: TableState<CursorPagination>, schema: CursorTableStateSchema): string;
|
|
96
|
+
export function serializeState(state: TableState, schema: TableStateSchema): string;
|
|
97
|
+
export function serializeState(state: TableState<ServerPagination>, schema: TableStateSchema | CursorTableStateSchema): string {
|
|
98
|
+
if (schemaPagination(schema) === "page") return toEnvelope(parseTableStateWith(state, schema, parsePagination));
|
|
99
|
+
const parsed = parseTableStateWith(state, schema, parseCursorPagination);
|
|
100
|
+
return toEnvelope(parseTableStateWith({ ...parsed, pagination: { ...parsed.pagination, cursor: null } }, schema, parsePersistedCursor));
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
export function deserializeState(serialized: string, schema: CursorTableStateSchema): TableState<CursorPagination>;
|
|
104
|
+
export function deserializeState(serialized: string, schema: TableStateSchema): TableState;
|
|
105
|
+
export function deserializeState(serialized: string, schema: TableStateSchema | CursorTableStateSchema): TableState<ServerPagination> {
|
|
64
106
|
if (serialized.length > 262144) throw new Error("Serialized table state exceeds 262144 characters");
|
|
65
107
|
let envelope: unknown;
|
|
66
108
|
try { envelope = JSON.parse(serialized); }
|
|
@@ -68,5 +110,5 @@ export function deserializeState(serialized: string, schema: TableStateSchema):
|
|
|
68
110
|
if (!record(envelope)) throw new Error("Invalid table state envelope");
|
|
69
111
|
exact(envelope, ["version", "state"], "$");
|
|
70
112
|
if (envelope.version !== 1) throw new Error("Unsupported table state version");
|
|
71
|
-
return
|
|
113
|
+
return schemaPagination(schema) === "cursor" ? parseTableStateWith(envelope.state, schema, parsePersistedCursor) : parseTableStateWith(envelope.state, schema, parsePagination);
|
|
72
114
|
}
|
package/src/url-state.ts
CHANGED
|
@@ -1,14 +1,15 @@
|
|
|
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 TableUrlLocation { readonly pathname: string; readonly search: string; readonly hash: string }
|
|
5
6
|
export interface TableUrlRouter {
|
|
6
7
|
readonly location: () => TableUrlLocation;
|
|
7
8
|
readonly navigate: (to: string, options?: { readonly replace?: boolean; readonly scroll?: boolean }) => void;
|
|
8
9
|
}
|
|
9
|
-
export type TableUrlRead =
|
|
10
|
+
export type TableUrlRead<Pagination extends ServerPagination = TablePagination> =
|
|
10
11
|
| { readonly kind: "absent" }
|
|
11
|
-
| { readonly kind: "accepted"; readonly state: TableState }
|
|
12
|
+
| { readonly kind: "accepted"; readonly state: TableState<Pagination> }
|
|
12
13
|
| { readonly kind: "invalid"; readonly error: unknown };
|
|
13
14
|
export type TableUrlWrite =
|
|
14
15
|
| { readonly kind: "unchanged"; readonly to: string }
|
|
@@ -28,22 +29,38 @@ function target(pathname: string, parameters: URLSearchParams, hash: string): st
|
|
|
28
29
|
return `${pathname}${search ? `?${search}` : ""}${hash}`;
|
|
29
30
|
}
|
|
30
31
|
|
|
31
|
-
|
|
32
|
-
|
|
32
|
+
export interface TableUrlState<Pagination extends ServerPagination = TablePagination> {
|
|
33
|
+
readonly read: () => TableUrlRead<Pagination>;
|
|
34
|
+
readonly write: (state: TableState<Pagination>, options?: { readonly replace?: boolean }) => TableUrlWrite;
|
|
35
|
+
readonly clear: (options?: { readonly replace?: boolean }) => TableUrlWrite;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** Pull-based URL state using the same structural adapter as AppShell. Cursor schemas write and read only the first page. */
|
|
39
|
+
export function createTableUrlState(router: TableUrlRouter, parameter: string, schema: CursorTableStateSchema): TableUrlState<CursorPagination>;
|
|
40
|
+
export function createTableUrlState(router: TableUrlRouter, parameter: string, schema: TableStateSchema): TableUrlState;
|
|
41
|
+
export function createTableUrlState(router: TableUrlRouter, parameter: string, schema: TableStateSchema | CursorTableStateSchema): TableUrlState<CursorPagination> | TableUrlState {
|
|
42
|
+
schemaPagination(schema);
|
|
43
|
+
if (schema.pagination === "cursor") {
|
|
44
|
+
return tableUrlState<CursorPagination>(router, parameter, state => serializeState(state, schema), value => deserializeState(value, schema));
|
|
45
|
+
}
|
|
46
|
+
return tableUrlState<TablePagination>(router, parameter, state => serializeState(state, schema), value => deserializeState(value, schema));
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function tableUrlState<Pagination extends ServerPagination>(router: TableUrlRouter, parameter: string, serialize: (state: TableState<Pagination>) => string, deserialize: (value: string) => TableState<Pagination>): TableUrlState<Pagination> {
|
|
33
50
|
const name = parameterName(parameter);
|
|
34
|
-
function read(): TableUrlRead {
|
|
51
|
+
function read(): TableUrlRead<Pagination> {
|
|
35
52
|
try {
|
|
36
53
|
const { parameters } = locationParts(router.location());
|
|
37
54
|
const values = parameters.getAll(name);
|
|
38
55
|
if (values.length === 0) return Object.freeze({ kind: "absent" });
|
|
39
56
|
if (values.length !== 1) throw new Error(`Table URL parameter ${name} must occur exactly once`);
|
|
40
|
-
return Object.freeze({ kind: "accepted", state:
|
|
57
|
+
return Object.freeze({ kind: "accepted", state: deserialize(values[0] ?? "") });
|
|
41
58
|
} catch (error) { return Object.freeze({ kind: "invalid", error }); }
|
|
42
59
|
}
|
|
43
|
-
function write(state: TableState
|
|
60
|
+
function write(state: TableState<Pagination>, options: { readonly replace?: boolean } = {}): TableUrlWrite {
|
|
44
61
|
const current = locationParts(router.location());
|
|
45
62
|
const present = target(current.pathname, current.parameters, current.hash);
|
|
46
|
-
current.parameters.set(name,
|
|
63
|
+
current.parameters.set(name, serialize(state));
|
|
47
64
|
const to = target(current.pathname, current.parameters, current.hash);
|
|
48
65
|
if (to === present) return Object.freeze({ kind: "unchanged", to });
|
|
49
66
|
router.navigate(to, { replace: options.replace ?? true, scroll: false });
|