@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
@@ -1,6 +1,7 @@
1
- import { parseClientViewState } from "./client-state.ts";
2
- import type { ClientStateSchema } from "./client-state.ts";
3
- import type { ClientViewState } from "./client-view.ts";
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 ClientViewState {
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
- export interface TableStateSchema extends ClientStateSchema {
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: TableStateSchema): TableState {
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 = parseClientViewState({ search: value.search, filter: value.filter, sorting: value.sorting, pagination: value.pagination }, schema);
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
- export function serializeState(state: TableState, schema: TableStateSchema): string {
58
- const serialized = JSON.stringify({ version: 1, state: parseTableState(state, schema) });
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
- export function deserializeState(serialized: string, schema: TableStateSchema): TableState {
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 parseTableState(envelope.state, schema);
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 { 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 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
- /** Pull-based URL state using the same structural adapter as AppShell. */
32
- export function createTableUrlState(router: TableUrlRouter, parameter: string, schema: TableStateSchema) {
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: deserializeState(values[0] ?? "", schema) });
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, options: { readonly replace?: boolean } = {}): TableUrlWrite {
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, serializeState(state, schema));
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 });