@pretable/core 0.0.1 → 0.0.3
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/LICENSE +21 -0
- package/README.md +48 -0
- package/dist/index.cjs +954 -83
- package/dist/index.d.cts +291 -51
- package/dist/index.d.ts +291 -51
- package/dist/index.mjs +954 -83
- package/package.json +14 -1
package/dist/index.d.cts
CHANGED
|
@@ -1,7 +1,18 @@
|
|
|
1
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Half-open row index range — `start` inclusive, `end` exclusive — used to
|
|
3
|
+
* describe the visible row window in {@link PretableGridSnapshot.visibleRange}.
|
|
4
|
+
*
|
|
5
|
+
* @public
|
|
6
|
+
*/
|
|
7
|
+
interface PretableRowRange {
|
|
2
8
|
start: number;
|
|
3
9
|
end: number;
|
|
4
10
|
}
|
|
11
|
+
/**
|
|
12
|
+
* Tuning knobs for column autosize calculations.
|
|
13
|
+
*
|
|
14
|
+
* @public
|
|
15
|
+
*/
|
|
5
16
|
interface AutosizeOptions {
|
|
6
17
|
maxWidthPx?: number;
|
|
7
18
|
minWidthPx?: number;
|
|
@@ -9,92 +20,321 @@ interface AutosizeOptions {
|
|
|
9
20
|
cellPaddingPx?: number;
|
|
10
21
|
}
|
|
11
22
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
23
|
+
/**
|
|
24
|
+
* Base row constraint — every row is at minimum a string-keyed record.
|
|
25
|
+
*
|
|
26
|
+
* @public
|
|
27
|
+
*/
|
|
28
|
+
type PretableRow = Record<string, unknown>;
|
|
29
|
+
/**
|
|
30
|
+
* Sort direction — `null` means unsorted.
|
|
31
|
+
*
|
|
32
|
+
* @public
|
|
33
|
+
*/
|
|
34
|
+
type PretableSortDirection = "asc" | "desc" | null;
|
|
35
|
+
/**
|
|
36
|
+
* Phase of an in-progress cell edit.
|
|
37
|
+
*
|
|
38
|
+
* @public
|
|
39
|
+
*/
|
|
40
|
+
type PretableEditStatus = "checking" | "editing" | "validating" | "saving" | "error";
|
|
41
|
+
/**
|
|
42
|
+
* Input passed to a column's edit hooks (`editable`, `validate`, `parseEditValue`,
|
|
43
|
+
* `formatEditValue`).
|
|
44
|
+
*
|
|
45
|
+
* @public
|
|
46
|
+
*/
|
|
47
|
+
interface PretableEditInput<TRow extends PretableRow = PretableRow> {
|
|
48
|
+
rowId: string;
|
|
49
|
+
columnId: string;
|
|
50
|
+
row: TRow;
|
|
51
|
+
column: PretableColumn<TRow>;
|
|
52
|
+
value: unknown;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* In-progress cell edit observed via `PretableGrid.getSnapshot().editing`.
|
|
56
|
+
* `error` carries the validation message (status `"editing"`) or the commit
|
|
57
|
+
* failure message (status `"error"`).
|
|
58
|
+
*
|
|
59
|
+
* @public
|
|
60
|
+
*/
|
|
61
|
+
interface PretableEditState {
|
|
62
|
+
rowId: string;
|
|
63
|
+
columnId: string;
|
|
64
|
+
draft: unknown;
|
|
65
|
+
status: PretableEditStatus;
|
|
66
|
+
error?: string;
|
|
67
|
+
}
|
|
68
|
+
/** @public */
|
|
69
|
+
type ColumnType = "text" | "number" | "date" | "enum" | "boolean";
|
|
70
|
+
/** @public */
|
|
71
|
+
type FilterOperator = "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith" | "gt" | "gte" | "lt" | "lte" | "between" | "isAnyOf" | "isNoneOf" | "on" | "before" | "after" | "dateBetween" | "isEmpty" | "isNotEmpty";
|
|
72
|
+
/** @public */
|
|
73
|
+
type FilterValue = string | number | readonly [number, number] | readonly [string, string] | readonly string[] | null;
|
|
74
|
+
/** @public — one column's active filter. `value` is omitted for isEmpty/isNotEmpty. */
|
|
75
|
+
interface ColumnFilter {
|
|
76
|
+
operator: FilterOperator;
|
|
77
|
+
value?: FilterValue;
|
|
78
|
+
}
|
|
79
|
+
/** @public */
|
|
80
|
+
interface ColumnOption {
|
|
81
|
+
value: string;
|
|
82
|
+
label?: string;
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Engine-level column definition. `@pretable/react` extends this with React-specific render fields.
|
|
86
|
+
*
|
|
87
|
+
* @public
|
|
88
|
+
*/
|
|
89
|
+
interface PretableColumn<TRow extends PretableRow = PretableRow> {
|
|
15
90
|
id: string;
|
|
16
91
|
header?: string;
|
|
17
92
|
wrap?: boolean;
|
|
18
93
|
widthPx?: number;
|
|
19
|
-
pinned?: "left";
|
|
94
|
+
pinned?: "left" | "right";
|
|
20
95
|
sortable?: boolean;
|
|
96
|
+
/** Number-editor increment for ArrowUp/Down and steppers. Default 1. */
|
|
97
|
+
step?: number;
|
|
21
98
|
filterable?: boolean;
|
|
22
|
-
|
|
99
|
+
type?: ColumnType;
|
|
100
|
+
options?: ColumnOption[];
|
|
101
|
+
value?: (row: TRow) => unknown;
|
|
102
|
+
format?: (input: PretableFormatInput<TRow>) => string;
|
|
103
|
+
minWidthPx?: number;
|
|
104
|
+
maxWidthPx?: number;
|
|
105
|
+
resizable?: boolean;
|
|
106
|
+
reorderable?: boolean;
|
|
107
|
+
editable?: boolean | ((input: PretableEditInput<TRow>) => boolean | Promise<boolean>);
|
|
108
|
+
validate?: (value: unknown, input: PretableEditInput<TRow>) => (true | string) | Promise<true | string>;
|
|
109
|
+
parseEditValue?: (raw: string, input: PretableEditInput<TRow>) => unknown;
|
|
110
|
+
formatEditValue?: (value: unknown, input: PretableEditInput<TRow>) => string;
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Input passed to a column's `format` function.
|
|
114
|
+
*
|
|
115
|
+
* @public
|
|
116
|
+
*/
|
|
117
|
+
interface PretableFormatInput<TRow extends PretableRow = PretableRow> {
|
|
118
|
+
value: unknown;
|
|
119
|
+
row: TRow;
|
|
120
|
+
column: PretableColumn<TRow>;
|
|
23
121
|
}
|
|
24
|
-
|
|
25
|
-
|
|
122
|
+
/**
|
|
123
|
+
* Options accepted by `createGrid`.
|
|
124
|
+
*
|
|
125
|
+
* @public
|
|
126
|
+
*/
|
|
127
|
+
interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
|
|
128
|
+
columns: PretableColumn<TRow>[];
|
|
26
129
|
rows: TRow[];
|
|
27
130
|
getRowId?: (row: TRow, index: number) => string;
|
|
28
131
|
autosize?: boolean | AutosizeOptions;
|
|
29
132
|
}
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
133
|
+
/**
|
|
134
|
+
* One entry in the ordered sort list; index in the list = priority.
|
|
135
|
+
*
|
|
136
|
+
* @public
|
|
137
|
+
*/
|
|
138
|
+
interface PretableSortEntry {
|
|
139
|
+
columnId: string;
|
|
140
|
+
direction: "asc" | "desc";
|
|
141
|
+
}
|
|
142
|
+
/**
|
|
143
|
+
* Cell address — the (rowId, columnId) pair that uniquely identifies a cell.
|
|
144
|
+
*
|
|
145
|
+
* @public
|
|
146
|
+
*/
|
|
147
|
+
interface PretableCellAddress {
|
|
148
|
+
rowId: string;
|
|
149
|
+
columnId: string;
|
|
33
150
|
}
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
151
|
+
/**
|
|
152
|
+
* Inclusive cell range — both bounds (start and end) are inside the selection.
|
|
153
|
+
*
|
|
154
|
+
* @public
|
|
155
|
+
*/
|
|
156
|
+
interface PretableCellRange {
|
|
157
|
+
startRowId: string;
|
|
158
|
+
endRowId: string;
|
|
159
|
+
startColumnId: string;
|
|
160
|
+
endColumnId: string;
|
|
37
161
|
}
|
|
38
|
-
|
|
162
|
+
/**
|
|
163
|
+
* Cell-range selection state including the optional anchor for shift-extension.
|
|
164
|
+
*
|
|
165
|
+
* @public
|
|
166
|
+
*/
|
|
167
|
+
interface PretableSelectionState {
|
|
168
|
+
ranges: PretableCellRange[];
|
|
169
|
+
anchor: PretableCellAddress | null;
|
|
170
|
+
}
|
|
171
|
+
/**
|
|
172
|
+
* Currently focused cell — both fields are null when nothing is focused.
|
|
173
|
+
*
|
|
174
|
+
* @public
|
|
175
|
+
*/
|
|
176
|
+
interface PretableFocusState {
|
|
39
177
|
rowId: string | null;
|
|
40
178
|
columnId: string | null;
|
|
41
179
|
}
|
|
42
|
-
|
|
180
|
+
/**
|
|
181
|
+
* Viewport-level scroll + size state.
|
|
182
|
+
*
|
|
183
|
+
* @public
|
|
184
|
+
*/
|
|
185
|
+
interface PretableViewportState {
|
|
43
186
|
scrollTop: number;
|
|
44
187
|
scrollLeft: number;
|
|
45
188
|
height: number;
|
|
46
189
|
width: number;
|
|
47
190
|
}
|
|
48
|
-
|
|
191
|
+
/**
|
|
192
|
+
* Streaming transaction — incremental row mutations applied via `PretableGrid.applyTransaction`.
|
|
193
|
+
*
|
|
194
|
+
* @public
|
|
195
|
+
*/
|
|
196
|
+
interface PretableTransaction<TRow extends PretableRow = PretableRow> {
|
|
49
197
|
add?: TRow[];
|
|
50
198
|
update?: Partial<TRow>[];
|
|
51
199
|
remove?: string[];
|
|
52
200
|
}
|
|
53
|
-
|
|
201
|
+
/**
|
|
202
|
+
* A row currently in the visible window — includes its source-array index for stable identity.
|
|
203
|
+
*
|
|
204
|
+
* @public
|
|
205
|
+
*/
|
|
206
|
+
interface PretableVisibleRow<TRow extends PretableRow = PretableRow> {
|
|
54
207
|
id: string;
|
|
55
208
|
row: TRow;
|
|
56
209
|
sourceIndex: number;
|
|
57
210
|
}
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
211
|
+
/**
|
|
212
|
+
* Read-only state observed via `PretableGrid.getSnapshot`.
|
|
213
|
+
*
|
|
214
|
+
* @public
|
|
215
|
+
*/
|
|
216
|
+
interface PretableGridSnapshot<TRow extends PretableRow = PretableRow> {
|
|
217
|
+
viewport: PretableViewportState;
|
|
218
|
+
sort: PretableSortEntry[];
|
|
219
|
+
filters: Record<string, ColumnFilter>;
|
|
220
|
+
selection: PretableSelectionState;
|
|
221
|
+
focus: PretableFocusState;
|
|
64
222
|
totalRowCount: number;
|
|
65
|
-
visibleRows:
|
|
66
|
-
visibleRange:
|
|
223
|
+
visibleRows: PretableVisibleRow<TRow>[];
|
|
224
|
+
visibleRange: PretableRowRange;
|
|
225
|
+
editing: PretableEditState | null;
|
|
67
226
|
}
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
227
|
+
/**
|
|
228
|
+
* Direction passed to `PretableGrid.moveFocus`.
|
|
229
|
+
*
|
|
230
|
+
* @public
|
|
231
|
+
*/
|
|
232
|
+
type PretableFocusDirection = "up" | "down" | "left" | "right";
|
|
233
|
+
/**
|
|
234
|
+
* Optional behavior modifiers for `PretableGrid.moveFocus`.
|
|
235
|
+
*
|
|
236
|
+
* @public
|
|
237
|
+
*/
|
|
238
|
+
interface PretableMoveFocusOptions {
|
|
239
|
+
extend?: boolean;
|
|
240
|
+
jumpToEdge?: boolean;
|
|
241
|
+
byPage?: boolean;
|
|
82
242
|
}
|
|
83
243
|
|
|
84
|
-
|
|
244
|
+
/**
|
|
245
|
+
* Per-row selection state — "selected" means fully, "indeterminate" means partial.
|
|
246
|
+
*
|
|
247
|
+
* @public
|
|
248
|
+
*/
|
|
249
|
+
type PretableRowSelectionTriState = "selected" | "indeterminate";
|
|
85
250
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
251
|
+
/**
|
|
252
|
+
* Public handle returned by {@link createGrid}. Exposes every action and
|
|
253
|
+
* observation pretable promises to support; does not extend the internal
|
|
254
|
+
* engine type, so private methods cannot leak through the public surface.
|
|
255
|
+
*
|
|
256
|
+
* @public
|
|
257
|
+
*/
|
|
258
|
+
interface PretableGrid<TRow extends PretableRow = PretableRow> {
|
|
259
|
+
/** Discriminator — distinguishes `PretableGrid` from arbitrary objects. */
|
|
260
|
+
readonly kind: "pretable-grid";
|
|
261
|
+
/** The options the grid was constructed with. */
|
|
262
|
+
readonly options: PretableGridOptions<TRow>;
|
|
263
|
+
/** Subscribe to grid mutations. Returns an unsubscribe function. */
|
|
264
|
+
subscribe(listener: () => void): () => void;
|
|
265
|
+
/** Read the current snapshot. Stable reference until the next mutation. */
|
|
266
|
+
getSnapshot(): PretableGridSnapshot<TRow>;
|
|
267
|
+
setSort(columnId: string | null, direction: PretableSortDirection): void;
|
|
268
|
+
/** Atomically replace the ordered sort list. Unknown and `sortable: false` columns are dropped. */
|
|
269
|
+
replaceSort(entries: PretableSortEntry[]): void;
|
|
270
|
+
setColumnFilter(columnId: string, filter: ColumnFilter | null): void;
|
|
271
|
+
clearFilters(): void;
|
|
272
|
+
replaceFilters(nextFilters: Record<string, ColumnFilter>): void;
|
|
273
|
+
distinctColumnValues(columnId: string): string[];
|
|
274
|
+
setSelection(state: PretableSelectionState): void;
|
|
275
|
+
selectAll(): void;
|
|
276
|
+
clearSelection(): void;
|
|
277
|
+
addRange(range: PretableCellRange): void;
|
|
278
|
+
extendRangeFromAnchor(addr: PretableCellAddress): void;
|
|
279
|
+
toggleRowSelection(rowId: string): void;
|
|
280
|
+
setSelectAllVisible(checked: boolean): void;
|
|
281
|
+
setFocus(addr: PretableCellAddress | null): void;
|
|
282
|
+
moveFocus(direction: PretableFocusDirection, options?: PretableMoveFocusOptions): void;
|
|
283
|
+
setViewport(viewport: PretableViewportState): void;
|
|
94
284
|
autosizeColumns(options?: AutosizeOptions): void;
|
|
285
|
+
setColumnWidth(columnId: string, width: number): void;
|
|
286
|
+
moveColumn(columnId: string, toIndex: number): void;
|
|
287
|
+
/**
|
|
288
|
+
* Set the relative order of the columns. Ids that do not match a column are
|
|
289
|
+
* ignored, and columns absent from `ids` keep their current relative order at
|
|
290
|
+
* the end. Pin state is never read from `ids` nor changed: the result is
|
|
291
|
+
* regrouped into `[pinned "left"…, unpinned…, pinned "right"…]`, so an order
|
|
292
|
+
* that interleaves pinned and unpinned columns is normalised rather than
|
|
293
|
+
* honoured literally.
|
|
294
|
+
*/
|
|
295
|
+
setColumnOrder(ids: readonly string[]): void;
|
|
296
|
+
setColumnPinned(columnId: string, pinned: "left" | "right" | null): void;
|
|
297
|
+
autosizeColumn(columnId: string, options?: AutosizeOptions): void;
|
|
298
|
+
resetColumnLayout(): void;
|
|
299
|
+
mergeColumnsFromProps(nextColumns: PretableColumn<TRow>[]): void;
|
|
95
300
|
applyTransaction(transaction: PretableTransaction<TRow>): void;
|
|
301
|
+
/**
|
|
302
|
+
* Replace the full row set in place. Unlike recreating the grid, this
|
|
303
|
+
* preserves selection and focus (both keyed by row id), dropping only the
|
|
304
|
+
* references whose rows are no longer present. Suited to high-frequency
|
|
305
|
+
* updates where row identities are stable.
|
|
306
|
+
*/
|
|
307
|
+
setRows(rows: TRow[]): void;
|
|
308
|
+
beginEdit(addr: PretableCellAddress, opts?: {
|
|
309
|
+
draft?: unknown;
|
|
310
|
+
status?: "checking" | "editing";
|
|
311
|
+
}): void;
|
|
312
|
+
setEditDraft(value: unknown): void;
|
|
313
|
+
markEditing(): void;
|
|
314
|
+
markEditValidating(): void;
|
|
315
|
+
markEditSaving(): void;
|
|
316
|
+
markEditInvalid(message: string): void;
|
|
317
|
+
markEditError(message: string): void;
|
|
318
|
+
commitEditSucceeded(): void;
|
|
319
|
+
cancelEdit(): void;
|
|
96
320
|
}
|
|
97
321
|
|
|
98
|
-
|
|
322
|
+
/**
|
|
323
|
+
* Create a pretable grid instance. Returns a {@link PretableGrid} handle
|
|
324
|
+
* that exposes every action and observation pretable supports.
|
|
325
|
+
*
|
|
326
|
+
* @example
|
|
327
|
+
* ```ts
|
|
328
|
+
* const grid = createGrid({
|
|
329
|
+
* columns: [{ id: "name" }, { id: "age" }],
|
|
330
|
+
* rows: [{ id: "1", name: "Ada", age: 36 }],
|
|
331
|
+
* });
|
|
332
|
+
* grid.setSort("age", "desc");
|
|
333
|
+
* const snapshot = grid.getSnapshot();
|
|
334
|
+
* ```
|
|
335
|
+
*
|
|
336
|
+
* @public
|
|
337
|
+
*/
|
|
338
|
+
declare function createGrid<TRow extends PretableRow = PretableRow>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
|
|
99
339
|
|
|
100
|
-
export { type AutosizeOptions, type PretableColumn, type
|
|
340
|
+
export { type AutosizeOptions, type ColumnFilter, type ColumnOption, type ColumnType, type FilterOperator, type FilterValue, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableMoveFocusOptions, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };
|