@pretable/core 0.10.0 → 0.11.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/index.d.ts DELETED
@@ -1,1356 +0,0 @@
1
- /**
2
- * Expand mapped/intersection types into readable editor hovers.
3
- * @public
4
- */
5
- type Prettify<T> = {
6
- [K in keyof T]: T[K];
7
- } & {};
8
- /** @public */
9
- type PretableRowId = string | number;
10
- /**
11
- * Values with stable, collision-free local grouping identity.
12
- * @public
13
- */
14
- type PretableGroupKey = string | number | bigint | boolean | Date | null | undefined;
15
- /** @public */
16
- type PretableColumnType = "text" | "number" | "date" | "enum" | "boolean";
17
- /** @public */
18
- interface PretableAggregator<TRow extends object = object, TValue = unknown, TAccumulator = unknown, TOutput = unknown> {
19
- readonly init: () => TAccumulator;
20
- readonly accumulate: (accumulator: TAccumulator, value: TValue, row: TRow) => TAccumulator;
21
- readonly merge: (left: TAccumulator, right: TAccumulator) => TAccumulator;
22
- /**
23
- * Produces a detached accumulator for `finalize`. Required when the
24
- * accumulator is a class instance or otherwise cannot be structured-cloned
25
- * without losing behavior.
26
- */
27
- readonly snapshotAccumulator?: (accumulator: TAccumulator) => TAccumulator;
28
- readonly finalize: (accumulator: TAccumulator) => TOutput;
29
- }
30
- /** @public */
31
- type PretableBuiltinAggregate<TValue> = "count" | ([NonNullable<TValue>] extends [never] ? never : NonNullable<TValue> extends number ? "sum" | "avg" | "min" | "max" : never);
32
- /** @public */
33
- type PretableAggregateSpec<TRow extends object, TValue> = PretableBuiltinAggregate<TValue> | PretableCompatibleAggregator<TRow, TValue, unknown>;
34
- declare const columnDescriptor: unique symbol;
35
- /** Compile-time-only accessor-form carrier emitted by the column helper. @public */
36
- interface PretableColumnAccessorKind<TKind extends "direct" | "computed"> {
37
- readonly [columnDescriptor]: {
38
- readonly accessorKind: TKind;
39
- };
40
- }
41
- /** @public */
42
- interface PretableFormatInput<TRow extends object, TValue = unknown, TColumn = unknown> {
43
- readonly value: TValue;
44
- readonly row: TRow;
45
- readonly column: TColumn;
46
- }
47
- /** @public */
48
- interface PretableAggregateFormatInput<TValue, TColumn> {
49
- readonly value: TValue;
50
- readonly column: TColumn;
51
- }
52
- /** @public */
53
- type PretableAggregateOutputOf<TAggregate> = TAggregate extends {
54
- readonly finalize: (accumulator: never) => infer TOutput;
55
- } ? TOutput : TAggregate extends "sum" | "avg" | "min" | "max" | "count" ? number | null : never;
56
- /** @public */
57
- interface PretableColumnDefinition<TRow extends object, TId extends string, TValue, TType extends PretableColumnType, TAggregate = undefined> {
58
- readonly id: TId;
59
- readonly type: TType;
60
- readonly header?: string;
61
- readonly accessorKey?: Extract<keyof TRow, string>;
62
- readonly accessor: (row: TRow) => TValue;
63
- /** Compatibility spelling retained on the original column object. */
64
- readonly value: (row: TRow) => TValue;
65
- readonly compare?: (left: TValue, right: TValue) => number;
66
- readonly aggregate?: TAggregate;
67
- /**
68
- * Native number presentation. Outranked by `format` for data cells and by
69
- * `formatAggregate` for group aggregates; derivation, editing, and every
70
- * row-model read continue to see the raw value.
71
- */
72
- readonly numberFormat?: Intl.NumberFormatOptions;
73
- readonly format?: (input: PretableFormatInput<TRow, TValue, PretableColumnDefinition<TRow, TId, TValue, TType, TAggregate>>) => string;
74
- readonly formatAggregate?: (input: PretableAggregateFormatInput<PretableAggregateOutputOf<TAggregate>, PretableColumnDefinition<TRow, TId, TValue, TType, TAggregate>>) => string;
75
- readonly [columnDescriptor]: {
76
- readonly row: TRow;
77
- readonly id: TId;
78
- readonly value: TValue;
79
- readonly type: TType;
80
- readonly aggregate: TAggregate;
81
- };
82
- }
83
- /** @public */
84
- type PretableColumnTypeFor<TValue> = [TValue] extends [never] ? never : [NonNullable<TValue>] extends [never] ? Exclude<PretableColumnType, "number"> : NonNullable<TValue> extends number ? "number" : NonNullable<TValue> extends boolean ? "boolean" : NonNullable<TValue> extends Date ? "date" : NonNullable<TValue> extends string ? "text" | "enum" | "date" : PretableColumnType;
85
- /** @public */
86
- interface PretableColumnCallbackContext<TRow extends object, TId extends string, TValue, TType extends PretableColumnType, TAggregate> {
87
- readonly id: TId;
88
- readonly type: TType;
89
- readonly accessor: (row: TRow) => TValue;
90
- readonly value: (row: TRow) => TValue;
91
- readonly aggregate?: TAggregate;
92
- }
93
- /** @public */
94
- type PretableColumnOptions<TRow extends object, TId extends string, TValue, TType extends PretableColumnTypeFor<TValue>, TAggregate extends PretableAggregateSpec<TRow, TValue> | undefined> = {
95
- readonly type: TType;
96
- readonly header?: string;
97
- readonly compare?: (left: TValue, right: TValue) => number;
98
- readonly aggregate?: TAggregate;
99
- /** Native number presentation; `format` outranks it for data cells. */
100
- readonly numberFormat?: Intl.NumberFormatOptions;
101
- readonly format?: (input: {
102
- readonly value: TValue;
103
- readonly row: TRow;
104
- readonly column: PretableColumnCallbackContext<TRow, TId, TValue, TType, TAggregate>;
105
- }) => string;
106
- readonly formatAggregate?: (input: {
107
- readonly value: PretableAggregateOutputOf<TAggregate>;
108
- readonly column: PretableColumnCallbackContext<TRow, TId, TValue, TType, TAggregate>;
109
- }) => string;
110
- };
111
- /** @public */
112
- interface PretableColumnHelper<TRow extends object> {
113
- accessor<const TId extends string, const TAccessor extends (...args: never[]) => unknown, const TType extends (unknown extends NoInfer<TValue> ? never : PretableColumnTypeFor<NoInfer<TValue>>) | ([TValue] extends [typeof columnDescriptor] ? [ReturnType<TAccessor>] extends [never] ? never : PretableColumnType : never), TValue = typeof columnDescriptor, const TAggregate extends PretableAggregateSpec<TRow, NoInfer<TValue>> | ([TValue] extends [typeof columnDescriptor] ? [ReturnType<TAccessor>] extends [never] ? never : PretableAggregateSpec<TRow, never> | "sum" | "avg" | "min" | "max" : never) | undefined = undefined>(id: TId, accessor: TAccessor & ((row: TRow) => TValue), options: {
114
- readonly type: TType;
115
- readonly header?: string;
116
- readonly compare?: (left: TValue, right: TValue) => number;
117
- readonly aggregate?: TAggregate;
118
- /** Native number presentation; `format` outranks it for data cells. */
119
- readonly numberFormat?: Intl.NumberFormatOptions;
120
- readonly format?: (input: {
121
- readonly value: TValue;
122
- readonly row: TRow;
123
- readonly column: PretableColumnCallbackContext<TRow, TId, TValue, TType, TAggregate>;
124
- }) => string;
125
- readonly formatAggregate?: (input: {
126
- readonly value: PretableAggregateOutputOf<TAggregate>;
127
- readonly column: PretableColumnCallbackContext<TRow, TId, TValue, TType, TAggregate>;
128
- }) => string;
129
- }): PretableColumnDefinition<TRow, TId, ReturnType<TAccessor>, TType, TAggregate> & PretableColumnAccessorKind<"computed">;
130
- accessor<const TKey extends Extract<keyof TRow, string>, const TType extends PretableColumnTypeFor<TRow[TKey]>, const TAggregate extends PretableAggregateSpec<TRow, TRow[TKey]> | undefined = undefined>(key: TKey, options: PretableColumnOptions<TRow, TKey, TRow[TKey], TType, TAggregate>): PretableColumnDefinition<TRow, TKey, TRow[TKey], TType, TAggregate> & PretableColumnAccessorKind<"direct">;
131
- }
132
- /** @public */
133
- type ColumnIdOf<TColumns> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
134
- readonly id: infer TId extends string;
135
- } ? TId : never : never;
136
- /** @public */
137
- type ColumnValueOf<TColumns, TColumnId extends ColumnIdOf<TColumns>> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
138
- readonly id: TColumnId;
139
- readonly accessor: (...args: never[]) => infer TValue;
140
- } ? TValue : never : never;
141
- /** @public */
142
- type ColumnAggregateValueOf<TColumns, TColumnId extends ColumnIdOf<TColumns>> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
143
- readonly id: TColumnId;
144
- readonly aggregate?: infer TAggregate;
145
- } ? PretableAggregateOutputOf<TAggregate> : never : never;
146
- /** @public */
147
- type PretableAggregatesFor<TColumns> = Prettify<{
148
- readonly [TColumn in TColumns extends readonly (infer TItem)[] ? TItem : never as TColumn extends {
149
- readonly id: infer TId extends string;
150
- readonly aggregate?: infer TAggregate;
151
- } ? [TAggregate] extends [undefined] ? never : TId : never]: TColumn extends {
152
- readonly aggregate?: infer TAggregate;
153
- } ? PretableAggregateOutputOf<TAggregate> : never;
154
- }>;
155
- /**
156
- * The runtime filter operand accepted by a declared column type.
157
- * Enum columns retain known string literal values and otherwise accept strings.
158
- * @public
159
- */
160
- type PretableFilterOperandFor<TValue, TType extends PretableColumnType> = TType extends "text" ? string : TType extends "number" ? number : TType extends "date" ? string | number | Date : TType extends "boolean" ? boolean : [Extract<NonNullable<TValue>, string>] extends [never] ? string : Extract<NonNullable<TValue>, string>;
161
- /** @public */
162
- type PretableFilterFor<TColumns> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
163
- readonly id: infer TId extends string;
164
- readonly accessor: (...args: never[]) => infer TValue;
165
- readonly type: infer TType extends PretableColumnType;
166
- } ? {
167
- readonly columnId: TId;
168
- readonly operator: "isEmpty" | "isNotEmpty";
169
- } | (TType extends "number" ? {
170
- readonly columnId: TId;
171
- readonly operator: "equals" | "notEquals" | "gt" | "gte" | "lt" | "lte";
172
- readonly value: PretableFilterOperandFor<TValue, TType>;
173
- } | {
174
- readonly columnId: TId;
175
- readonly operator: "between";
176
- readonly value: readonly [
177
- PretableFilterOperandFor<TValue, TType>,
178
- PretableFilterOperandFor<TValue, TType>
179
- ];
180
- } : TType extends "date" ? {
181
- readonly columnId: TId;
182
- readonly operator: "on" | "before" | "after";
183
- readonly value: PretableFilterOperandFor<TValue, TType>;
184
- } | {
185
- readonly columnId: TId;
186
- readonly operator: "dateBetween";
187
- readonly value: readonly [
188
- PretableFilterOperandFor<TValue, TType>,
189
- PretableFilterOperandFor<TValue, TType>
190
- ];
191
- } : TType extends "enum" | "boolean" ? {
192
- readonly columnId: TId;
193
- readonly operator: "isAnyOf" | "isNoneOf";
194
- readonly value: readonly PretableFilterOperandFor<TValue, TType>[];
195
- } : {
196
- readonly columnId: TId;
197
- readonly operator: "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith";
198
- readonly value: PretableFilterOperandFor<TValue, TType>;
199
- }) : never : never;
200
- /** @public */
201
- type PretableSortFor<TColumns> = Prettify<(TColumns extends readonly (infer TColumn)[] ? TColumn extends {
202
- readonly id: infer TId extends string;
203
- } ? {
204
- readonly columnId: TId;
205
- } : never : never) & {
206
- readonly direction: "asc" | "desc";
207
- readonly nulls?: "first" | "last";
208
- }>;
209
- /** @public */
210
- type PretableRowGroupFor<TColumns> = Prettify<(TColumns extends readonly (infer TColumn)[] ? TColumn extends {
211
- readonly id: infer TId extends string;
212
- readonly accessor: (...args: never[]) => infer TValue;
213
- } ? [TValue] extends [never] ? never : [TValue] extends [PretableGroupKey] ? {
214
- readonly columnId: TId;
215
- } : never : never : never) & {
216
- readonly direction?: "asc" | "desc";
217
- readonly nulls?: "first" | "last";
218
- }>;
219
- /** @public */
220
- interface PretableQueryFor<TColumns> {
221
- readonly filters: readonly PretableFilterFor<TColumns>[];
222
- readonly sort: readonly PretableSortFor<TColumns>[];
223
- readonly rowGroups: readonly PretableRowGroupFor<TColumns>[];
224
- }
225
- /** @public */
226
- interface PretableCompatibleAggregator<TRow extends object, TValue, TOutput> {
227
- readonly init: () => unknown;
228
- readonly accumulate: {
229
- bivarianceHack(accumulator: unknown, value: TValue, row: TRow): unknown;
230
- }["bivarianceHack"] & ((accumulator: never, value: TValue, row: TRow) => unknown);
231
- readonly merge: {
232
- bivarianceHack(left: unknown, right: unknown): unknown;
233
- }["bivarianceHack"];
234
- readonly snapshotAccumulator?: {
235
- bivarianceHack(accumulator: unknown): unknown;
236
- }["bivarianceHack"];
237
- readonly finalize: {
238
- bivarianceHack(accumulator: unknown): TOutput;
239
- }["bivarianceHack"];
240
- }
241
- /** @public */
242
- type PretableCompatibleAggregateSpec<TRow extends object, TValue, TAggregate> = [TAggregate] extends [undefined] ? undefined : ([PretableAggregateOutputOf<TAggregate>] extends [number | null] ? [number | null] extends [PretableAggregateOutputOf<TAggregate>] ? PretableBuiltinAggregate<TValue> : never : never) | PretableCompatibleAggregator<TRow, TValue, PretableAggregateOutputOf<TAggregate>>;
243
- /** @public */
244
- interface PretableColumnDerivation<TRow extends object, TId extends string, TValue, TType extends PretableColumnType, TAggregate> {
245
- readonly id: TId;
246
- readonly type: TType;
247
- readonly accessor: (row: TRow) => TValue;
248
- readonly value: (row: TRow) => TValue;
249
- readonly compare?: (left: TValue, right: TValue) => number;
250
- readonly aggregate?: PretableCompatibleAggregateSpec<TRow, TValue, TAggregate>;
251
- readonly [columnDescriptor]: {
252
- readonly row: TRow;
253
- readonly id: TId;
254
- readonly value: TValue;
255
- readonly type: TType;
256
- readonly aggregate: PretableCompatibleAggregateSpec<TRow, TValue, TAggregate>;
257
- };
258
- }
259
- /** @public */
260
- type PretableDerivationsFor<TColumns> = {
261
- readonly [K in keyof TColumns]: TColumns[K] extends {
262
- readonly id: infer TId extends string;
263
- readonly type: infer TType extends PretableColumnType;
264
- readonly accessor: (row: infer TRow extends object) => infer TValue;
265
- readonly aggregate?: infer TAggregate;
266
- } ? PretableColumnDerivation<TRow, TId, TValue, TType, TAggregate> : never;
267
- };
268
-
269
- /** @public */
270
- type PretableRowModelOperation = "set-rows" | "apply-transaction" | "set-query" | "set-derivations" | "set-group-expanded" | "set-expansion-default" | "expand-all" | "collapse-all" | "changes-since" | "distinct-values" | "dispose";
271
- /** @public */
272
- type PretableRowModelErrorCode = "disposed-model" | "duplicate-row-id" | "existing-row-id" | "transaction-conflict" | "reentrant-mutation" | "row-identity-change" | "unsupported-row-update" | "accessor-failed" | "invalid-group-key" | "comparator-failed" | "aggregator-failed" | "derivation-failed";
273
- /** @public */
274
- interface PretableRowModelErrorContext {
275
- readonly operation: PretableRowModelOperation;
276
- readonly rowId?: PretableRowId;
277
- readonly columnId?: string;
278
- readonly cause?: unknown;
279
- }
280
- /** @public */
281
- declare class PretableRowModelError extends Error {
282
- readonly name: string;
283
- readonly code: PretableRowModelErrorCode;
284
- readonly operation: PretableRowModelOperation;
285
- readonly rowId?: PretableRowId;
286
- readonly columnId?: string;
287
- constructor(code: PretableRowModelErrorCode, message: string, context: PretableRowModelErrorContext);
288
- }
289
- /** @public */
290
- declare class PretableDisposedModelError extends PretableRowModelError {
291
- readonly name: string;
292
- constructor(operation: PretableRowModelOperation);
293
- }
294
- /** @public */
295
- declare class PretableReentrantMutationError extends PretableRowModelError {
296
- readonly activeOperation: PretableRowModelOperation;
297
- readonly name = "PretableReentrantMutationError";
298
- constructor(operation: PretableRowModelOperation, activeOperation: PretableRowModelOperation);
299
- }
300
- /** @public */
301
- declare class PretableRowIdentityChangeError extends PretableRowModelError {
302
- readonly nextRowId: unknown;
303
- readonly name = "PretableRowIdentityChangeError";
304
- constructor(rowId: PretableRowId, nextRowId: unknown, cause?: unknown);
305
- }
306
- /** @public */
307
- declare class PretableUnsupportedRowUpdateError extends PretableRowModelError {
308
- readonly name = "PretableUnsupportedRowUpdateError";
309
- constructor(rowId: PretableRowId, cause?: unknown);
310
- }
311
- /** @public */
312
- declare class PretableInvalidGroupKeyError extends PretableRowModelError {
313
- readonly value: unknown;
314
- readonly name = "PretableInvalidGroupKeyError";
315
- constructor(operation: PretableRowModelOperation, rowId: PretableRowId | undefined, columnId: string, value: unknown, cause?: unknown);
316
- }
317
- /** @public */
318
- type PretableTransitionCancellationReason = "cancelled" | "superseded" | "disposed";
319
- /** @public */
320
- declare class PretableTransitionCancelledError extends Error {
321
- readonly transitionId: number;
322
- readonly reason: PretableTransitionCancellationReason;
323
- readonly name = "PretableTransitionCancelledError";
324
- constructor(transitionId: number, reason: PretableTransitionCancellationReason);
325
- }
326
-
327
- declare const groupIdBrand: unique symbol;
328
- declare const rowModelDescriptor: unique symbol;
329
- /** @public */
330
- type PretableGroupId = string & {
331
- readonly [groupIdBrand]: "PretableGroupId";
332
- };
333
- /** @public */
334
- type PretableVisibleRowRef<TRowId extends PretableRowId> = {
335
- readonly kind: "data";
336
- readonly rowId: TRowId;
337
- } | {
338
- readonly kind: "group";
339
- readonly groupId: PretableGroupId;
340
- };
341
- /** @public */
342
- interface PretableDataRow<TRow extends object, TRowId extends PretableRowId> {
343
- readonly kind: "data";
344
- readonly rowId: TRowId;
345
- readonly row: TRow;
346
- readonly sourceIndex: number;
347
- readonly depth: number;
348
- }
349
- /** @public */
350
- type PretableGroupRow<TColumns> = {
351
- readonly [TColumnId in ColumnIdOf<TColumns>]: {
352
- readonly kind: "group";
353
- readonly groupId: PretableGroupId;
354
- readonly depth: number;
355
- readonly columnId: TColumnId;
356
- readonly value: ColumnValueOf<TColumns, TColumnId>;
357
- readonly childCount: number;
358
- readonly aggregates: PretableAggregatesFor<TColumns>;
359
- readonly expanded: boolean;
360
- };
361
- }[ColumnIdOf<TColumns>];
362
- /** @public */
363
- type PretableVisibleRow<TRow extends object, TRowId extends PretableRowId, TColumns> = PretableDataRow<TRow, TRowId> | PretableGroupRow<TColumns>;
364
- /** @public */
365
- type PretableExpansionDefault = {
366
- readonly kind: "collapsed";
367
- } | {
368
- readonly kind: "expanded";
369
- } | {
370
- readonly kind: "through-depth";
371
- readonly depth: number;
372
- };
373
- /** @public */
374
- interface PretableExpansionState {
375
- readonly default: PretableExpansionDefault;
376
- readonly overrideCount: number;
377
- }
378
- /** @public */
379
- interface PretableRowModelSnapshot<TRow extends object, TRowId extends PretableRowId, TColumns> {
380
- readonly revision: number;
381
- readonly sourceRowCount: number;
382
- readonly visibleRowCount: number;
383
- readonly visibleDataRowCount: number;
384
- rowAt(index: number): PretableVisibleRow<TRow, TRowId, TColumns> | undefined;
385
- /**
386
- * Returns the half-open visible-row interval `[start, end)`. Both bounds are
387
- * clamped to `[0, visibleRowCount]`.
388
- */
389
- range(start: number, end: number): readonly PretableVisibleRow<TRow, TRowId, TColumns>[];
390
- /** Returns the visible rank of `ref`, or `-1` when it is absent. */
391
- indexOf(ref: PretableVisibleRowRef<TRowId>): number;
392
- /** Returns the data-only rank of `ref`, or `-1` when it is absent. */
393
- dataIndexOf(ref: PretableVisibleRowRef<TRowId>): number;
394
- /**
395
- * Returns the data row at a data-only rank. Group rows do not consume an
396
- * index; an out-of-bounds rank returns `undefined`.
397
- */
398
- dataRowAt(index: number): PretableDataRow<TRow, TRowId> | undefined;
399
- /** Returns the first visible data row, or `undefined` when none is visible. */
400
- firstDataRow(): PretableDataRow<TRow, TRowId> | undefined;
401
- /** Returns the last visible data row, or `undefined` when none is visible. */
402
- lastDataRow(): PretableDataRow<TRow, TRowId> | undefined;
403
- /**
404
- * Returns the next visible data row after `ref`, skipping group rows, or
405
- * `undefined` when `ref` is absent or has no following data row.
406
- */
407
- nextDataRow(ref: PretableVisibleRowRef<TRowId>): PretableDataRow<TRow, TRowId> | undefined;
408
- /**
409
- * Returns the previous visible data row before `ref`, skipping group rows,
410
- * or `undefined` when `ref` is absent or has no preceding data row.
411
- */
412
- previousDataRow(ref: PretableVisibleRowRef<TRowId>): PretableDataRow<TRow, TRowId> | undefined;
413
- /** Returns the immediate parent group of `ref`, if it has one. */
414
- parentGroupOf(ref: PretableVisibleRowRef<TRowId>): PretableGroupRow<TColumns> | undefined;
415
- /**
416
- * Returns `ref` when visible, otherwise its nearest visible ancestor group;
417
- * returns `undefined` when neither the ref nor a visible ancestor is known.
418
- */
419
- nearestVisibleRef(ref: PretableVisibleRowRef<TRowId>): PretableVisibleRowRef<TRowId> | undefined;
420
- isGroupExpanded(groupId: PretableGroupId): boolean;
421
- readonly query: Readonly<PretableQueryFor<TColumns>>;
422
- readonly expansion: Readonly<PretableExpansionState>;
423
- }
424
- /** @public */
425
- type PretableRowModelStatus = {
426
- readonly kind: "ready";
427
- } | {
428
- readonly kind: "rebuilding";
429
- readonly transitionId: number;
430
- readonly completedRows: number;
431
- readonly totalRows: number;
432
- } | {
433
- readonly kind: "error";
434
- readonly transitionId: number;
435
- readonly error: PretableRowModelError;
436
- } | {
437
- readonly kind: "disposed";
438
- };
439
- /** @public */
440
- interface PretableRowModelState<TRow extends object, TRowId extends PretableRowId, TColumns> {
441
- readonly snapshot: PretableRowModelSnapshot<TRow, TRowId, TColumns>;
442
- readonly status: PretableRowModelStatus;
443
- }
444
- /** @public */
445
- interface PretableRowUpdate<TRow extends object, TRowId extends PretableRowId> {
446
- readonly id: TRowId;
447
- /**
448
- * An enumerable-own-data-property patch for an ordinary object or
449
- * null-prototype record. Class instances, arrays, built-in exotic objects,
450
- * and proxies are not valid partial-update targets because cloning them
451
- * would lose private state or observable behavior. Replace those values
452
- * atomically with `setRows` instead. Development builds enforce this for
453
- * rows that cannot be verified and frozen; production trusts this contract
454
- * without reflection or proxy detection.
455
- */
456
- readonly changes: Partial<TRow>;
457
- }
458
- /** @public */
459
- interface PretableTransaction<TRow extends object, TRowId extends PretableRowId> {
460
- readonly add?: readonly TRow[];
461
- readonly update?: readonly PretableRowUpdate<TRow, TRowId>[];
462
- readonly remove?: readonly TRowId[];
463
- }
464
- /** @public */
465
- type PretableMutationIssue<TRowId extends PretableRowId> = {
466
- readonly code: "unknown-update-id";
467
- readonly rowId: TRowId;
468
- } | {
469
- readonly code: "unknown-remove-id";
470
- readonly rowId: TRowId;
471
- } | {
472
- readonly code: "unknown-group-id";
473
- readonly groupId: PretableGroupId;
474
- };
475
- /** @public */
476
- interface PretableMutationResult<TRowId extends PretableRowId> {
477
- readonly previousRevision: number;
478
- readonly revision: number;
479
- readonly added: number;
480
- readonly updated: number;
481
- readonly removed: number;
482
- readonly unchanged: number;
483
- readonly ignored: number;
484
- readonly issues: readonly PretableMutationIssue<TRowId>[];
485
- }
486
- /** @public */
487
- interface PretableQueryTransition<TColumns> {
488
- readonly id: number;
489
- readonly requestedQuery: Readonly<PretableQueryFor<TColumns>>;
490
- readonly finished: Promise<number>;
491
- cancel(): void;
492
- }
493
- /** @public */
494
- interface PretableDerivationTransition<TColumns> {
495
- readonly id: number;
496
- readonly requestedDerivations: Readonly<PretableDerivationsFor<TColumns>>;
497
- readonly finished: Promise<number>;
498
- cancel(): void;
499
- }
500
- /** @public */
501
- type PretableVisibleRowField = "row" | "depth" | "expanded" | "childCount" | "aggregates";
502
- /** @public */
503
- type PretableChangeOperation<TRowId extends PretableRowId> = {
504
- readonly kind: "insert";
505
- readonly ref: PretableVisibleRowRef<TRowId>;
506
- readonly index: number;
507
- } | {
508
- readonly kind: "remove";
509
- readonly ref: PretableVisibleRowRef<TRowId>;
510
- readonly previousIndex: number;
511
- } | {
512
- readonly kind: "move";
513
- readonly ref: PretableVisibleRowRef<TRowId>;
514
- readonly previousIndex: number;
515
- readonly index: number;
516
- } | {
517
- readonly kind: "update";
518
- readonly ref: PretableVisibleRowRef<TRowId>;
519
- readonly index: number;
520
- readonly fields: readonly PretableVisibleRowField[];
521
- };
522
- /** @public */
523
- interface PretableChangeSet<TRowId extends PretableRowId> {
524
- /** The snapshot revision to which the first operation applies. */
525
- readonly previousRevision: number;
526
- /** The atomically published revision produced by the complete operation list. */
527
- readonly revision: number;
528
- /**
529
- * Applies sequentially: every index is measured after the preceding
530
- * operation in this list. Row data and group fields are read from the
531
- * snapshot at `revision`; operations never expose mutable row-model roots.
532
- */
533
- readonly operations: readonly PretableChangeOperation<TRowId>[];
534
- }
535
- /** @public */
536
- type PretableChangeSequence<TRowId extends PretableRowId> = {
537
- readonly kind: "changes";
538
- readonly fromRevision: number;
539
- readonly toRevision: number;
540
- readonly changes: readonly PretableChangeSet<TRowId>[];
541
- } | {
542
- readonly kind: "reset";
543
- readonly toRevision: number;
544
- readonly reason: "unknown-revision" | "journal-evicted" | "bulk-replace";
545
- };
546
- /** @public */
547
- interface PretableDistinctValueOptions {
548
- readonly search?: string;
549
- readonly start?: number;
550
- readonly limit?: number;
551
- readonly population?: "all" | "filtered";
552
- /** Includes nullish, NaN, and trim-empty string values. Defaults to false. */
553
- readonly includeBlanks?: boolean;
554
- /** Places included blank values before or after non-blank values. */
555
- readonly blankOrder?: "first" | "last";
556
- }
557
- /** @public */
558
- interface PretableDistinctValueResult<TValue> {
559
- readonly values: readonly {
560
- /** Numeric zero uses SameValueZero identity and is returned as positive zero. */
561
- readonly value: TValue;
562
- readonly count: number;
563
- }[];
564
- readonly totalDistinct: number;
565
- readonly population: "all" | "filtered";
566
- readonly rowModelRevision: number;
567
- }
568
- /** @public */
569
- interface PretableDistinctValueQuery<TValue> {
570
- readonly status: "pending" | "ready" | "error" | "cancelled";
571
- readonly finished: Promise<PretableDistinctValueResult<TValue>>;
572
- cancel(): void;
573
- }
574
- /**
575
- * Column IDs whose complete inferred value type has stable local identity.
576
- * @public
577
- */
578
- type PretableDistinctColumnIdOf<TColumns> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
579
- readonly id: infer TColumnId extends string;
580
- readonly accessor: (...args: never[]) => infer TValue;
581
- } ? [TValue] extends [
582
- string | number | bigint | boolean | Date | null | undefined
583
- ] ? [TValue] extends [never] ? never : TColumnId : never : never : never;
584
- /** @public */
585
- interface PretableRowModel<TRow extends object, TRowId extends PretableRowId, TColumns> {
586
- readonly [rowModelDescriptor]: {
587
- readonly row: TRow;
588
- readonly rowId: TRowId;
589
- readonly columns: TColumns;
590
- };
591
- getState(): PretableRowModelState<TRow, TRowId, TColumns>;
592
- /**
593
- * Returns the immutable original schema/presentation tuple supplied when
594
- * this model was created. `setDerivations` replaces engine behavior only;
595
- * it never changes this presentation fallback or its identity.
596
- */
597
- getColumns(): TColumns;
598
- subscribe(listener: () => void): () => void;
599
- setRows(rows: readonly TRow[]): PretableMutationResult<TRowId>;
600
- /**
601
- * Applies one atomic batch. Partial updates require ordinary or
602
- * null-prototype row records; use `setRows` to replace proxy, class, array,
603
- * or other exotic row values.
604
- */
605
- applyTransaction(transaction: PretableTransaction<TRow, TRowId>): PretableMutationResult<TRowId>;
606
- setQuery(query: PretableQueryFor<TColumns>): PretableQueryTransition<TColumns>;
607
- setDerivations(derivations: PretableDerivationsFor<TColumns>): PretableDerivationTransition<TColumns>;
608
- setGroupExpanded(groupId: PretableGroupId, expanded: boolean): PretableMutationResult<TRowId>;
609
- setExpansionDefault(policy: PretableExpansionDefault, options?: {
610
- readonly preserveOverrides?: boolean;
611
- }): PretableMutationResult<TRowId>;
612
- expandAll(): PretableMutationResult<TRowId>;
613
- collapseAll(): PretableMutationResult<TRowId>;
614
- /**
615
- * Returns a retained contiguous sequence through the current revision, or a
616
- * reset instruction when replay is no longer possible. The current revision
617
- * always returns an empty `changes` sequence.
618
- */
619
- changesSince(revision: number): PretableChangeSequence<TRowId>;
620
- distinctValues<TColumnId extends PretableDistinctColumnIdOf<TColumns>>(columnId: TColumnId, options?: PretableDistinctValueOptions): PretableDistinctValueQuery<ColumnValueOf<TColumns, TColumnId>>;
621
- dispose(): void;
622
- }
623
- /** @public */
624
- type RowOf<TModel> = TModel extends {
625
- readonly [rowModelDescriptor]: {
626
- readonly row: infer TRow extends object;
627
- };
628
- } ? TRow : never;
629
- /** @public */
630
- type RowIdOf<TModel> = TModel extends {
631
- readonly [rowModelDescriptor]: {
632
- readonly rowId: infer TRowId extends PretableRowId;
633
- };
634
- } ? TRowId : never;
635
- /** @public */
636
- type ColumnsOf<TModel> = TModel extends {
637
- readonly [rowModelDescriptor]: {
638
- readonly columns: infer TColumns;
639
- };
640
- } ? TColumns : never;
641
-
642
- /**
643
- * Base row constraint. Concrete row shapes remain fully generic.
644
- *
645
- * @public
646
- */
647
- type PretableRow = object;
648
- /**
649
- * Sort direction — `null` means unsorted.
650
- *
651
- * @public
652
- */
653
- type PretableSortDirection = "asc" | "desc" | null;
654
- /**
655
- * Phase of an in-progress cell edit.
656
- *
657
- * @public
658
- */
659
- type PretableEditStatus = "checking" | "editing" | "validating" | "saving" | "error";
660
- /**
661
- * Input passed to a column's edit hooks (`editable`, `validate`, `parseEditValue`,
662
- * `formatEditValue`).
663
- *
664
- * @public
665
- */
666
- interface PretableEditInput<TRow extends PretableRow = PretableRow> {
667
- rowId: string;
668
- columnId: string;
669
- row: TRow;
670
- column: PretableColumn<TRow>;
671
- value: unknown;
672
- }
673
- /**
674
- * In-progress cell edit observed through the UI grid state.
675
- * `error` carries the validation message (status `"editing"`) or the commit
676
- * failure message (status `"error"`).
677
- *
678
- * @public
679
- */
680
- interface PretableEditState {
681
- rowId: string;
682
- columnId: string;
683
- draft: unknown;
684
- status: PretableEditStatus;
685
- error?: string;
686
- }
687
- /** @public */
688
- type ColumnType = "text" | "number" | "date" | "enum" | "boolean";
689
- /** @public */
690
- type ColumnAlign = "start" | "center" | "end";
691
- /** @public */
692
- type FilterOperator = "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith" | "gt" | "gte" | "lt" | "lte" | "between" | "isAnyOf" | "isNoneOf" | "on" | "before" | "after" | "dateBetween" | "isEmpty" | "isNotEmpty";
693
- /** @public */
694
- type FilterValue = string | number | readonly [number, number] | readonly [string, string] | readonly string[] | null;
695
- /** @public — one column's active filter. `value` is omitted for isEmpty/isNotEmpty. */
696
- interface ColumnFilter {
697
- operator: FilterOperator;
698
- value?: FilterValue;
699
- }
700
- /** @public */
701
- interface ColumnOption {
702
- value: string;
703
- label?: string;
704
- }
705
- /**
706
- * Engine-level column definition. `@pretable/react` extends this with React-specific render fields.
707
- *
708
- * @public
709
- */
710
- interface PretableColumn<TRow extends PretableRow = PretableRow> {
711
- id: string;
712
- header?: string;
713
- wrap?: boolean;
714
- widthPx?: number;
715
- pinned?: "left" | "right";
716
- sortable?: boolean;
717
- /** Number-editor increment for ArrowUp/Down and steppers. Default 1. */
718
- step?: number;
719
- filterable?: boolean;
720
- /** Restrict the filter menu to operators the current processor can honor. */
721
- filterOperators?: FilterOperator[];
722
- type?: ColumnType;
723
- /** Horizontal alignment. Number columns default to `"end"`. */
724
- align?: ColumnAlign;
725
- options?: ColumnOption[];
726
- value?: (row: TRow) => unknown;
727
- format?: (input: PretableFormatInput<TRow, unknown, PretableColumn<TRow>>) => string;
728
- /** Native number presentation; derivation and editing continue to use raw values. */
729
- numberFormat?: Intl.NumberFormatOptions;
730
- /**
731
- * Render this column's aggregate on a group row.
732
- *
733
- * Deliberately not `format`: the plain-cell formatter's `row` is non-optional, so
734
- * every consumer formatter is entitled to dereference it, and a group row has
735
- * no row. Columns without `formatAggregate` fall back to the same default
736
- * stringification a plain cell uses.
737
- */
738
- formatAggregate?: (input: {
739
- value: unknown;
740
- column: PretableColumn<TRow>;
741
- group: {
742
- readonly id: string;
743
- readonly groupId: string;
744
- readonly depth: number;
745
- readonly columnId: string;
746
- readonly value: unknown;
747
- readonly childCount: number;
748
- readonly aggregates: Readonly<Record<string, unknown>>;
749
- readonly expanded: boolean;
750
- };
751
- /** Whether the aggregate covers the full result or only loaded rows. */
752
- scope: "all" | "loaded";
753
- }) => string;
754
- minWidthPx?: number;
755
- maxWidthPx?: number;
756
- /**
757
- * Share of the width the fixed columns leave over, so the row ends exactly at
758
- * the viewport edge instead of underfilling or overflowing it. Weights are
759
- * relative: two columns at `flex: 1` split the remainder evenly, `1` and `3`
760
- * split it a quarter to three quarters. `minWidthPx`/`maxWidthPx` still
761
- * apply, and a column that has been resized (which sets `widthPx`) stops
762
- * flexing — an explicit width outranks a computed one.
763
- */
764
- flex?: number;
765
- resizable?: boolean;
766
- reorderable?: boolean;
767
- /** Aggregate shown for this column on group rows. */
768
- aggregate?: unknown;
769
- editable?: boolean | ((input: PretableEditInput<TRow>) => boolean | Promise<boolean>);
770
- validate?: (value: unknown, input: PretableEditInput<TRow>) => (true | string) | Promise<true | string>;
771
- parseEditValue?: (raw: string, input: PretableEditInput<TRow>) => unknown;
772
- formatEditValue?: (value: unknown, input: PretableEditInput<TRow>) => string;
773
- }
774
- /** Who applies a query slice to the loaded rows. @experimental @public */
775
- type PretableProcessingAuthority = "engine" | "external";
776
- /** Per-slice processing authority for remotely fulfilled queries. @experimental @public */
777
- interface PretableProcessingOptions {
778
- filter?: PretableProcessingAuthority;
779
- sort?: PretableProcessingAuthority;
780
- }
781
- /** Population size represented by a loaded result window. @experimental @public */
782
- type PretableMatchingTotal = {
783
- kind: "exact";
784
- count: number;
785
- } | {
786
- kind: "estimate";
787
- count: number;
788
- } | {
789
- kind: "unknown";
790
- atLeast?: number;
791
- };
792
- /** Metadata accompanying a remotely fulfilled result window. @experimental @public */
793
- interface PretableResultMeta {
794
- total?: PretableMatchingTotal;
795
- /** Stable identity for the query/result population represented by the rows. */
796
- datasetKey?: string;
797
- /**
798
- * Where the loaded rows sit inside the population, when they are a window
799
- * rather than a prefix. Absent means the classic prefix case.
800
- *
801
- * `hasMore` rather than a remaining count: a keyset cursor walks forward, so
802
- * the extent must promise only what is fetchable. A count would invite a
803
- * scrollbar that reaches rows the cursor cannot serve.
804
- */
805
- window?: {
806
- /** Dataset index of `rows[0]`. */
807
- readonly start: number;
808
- /** Whether anything follows this window. NOT how much. */
809
- readonly hasMore: boolean;
810
- };
811
- }
812
- /**
813
- * One entry in the ordered sort list; index in the list = priority.
814
- *
815
- * @public
816
- */
817
- interface PretableSortEntry {
818
- columnId: string;
819
- direction: "asc" | "desc";
820
- }
821
- /**
822
- * Cell address — the (rowId, columnId) pair that uniquely identifies a cell.
823
- *
824
- * @public
825
- */
826
- interface PretableCellAddress {
827
- rowId: string;
828
- columnId: string;
829
- }
830
- /**
831
- * Inclusive cell range — both bounds (start and end) are inside the selection.
832
- *
833
- * @public
834
- */
835
- interface PretableCellRange {
836
- startRowId: string;
837
- endRowId: string;
838
- startColumnId: string;
839
- endColumnId: string;
840
- /**
841
- * Dataset positions of this range's endpoints, when the grid is serving a
842
- * window under the honesty gate — see
843
- * {@link PretableIndexedDatasetRowSpan}. Present on every range the grid
844
- * emits through `onSelectionChange`, and accepted back through the
845
- * controlled `state.selection` prop so a selection that is persisted and
846
- * restored stays countable while its rows are evicted. Omitting it on the
847
- * way back in is safe: the engine recovers the positions by row id from
848
- * the selection it is replacing.
849
- */
850
- datasetRowSpan?: PretableIndexedDatasetRowSpan;
851
- }
852
- /**
853
- * Cell-range selection state including the optional anchor for shift-extension.
854
- *
855
- * @public
856
- */
857
- interface PretableSelectionState {
858
- ranges: PretableCellRange[];
859
- anchor: PretableCellAddress | null;
860
- }
861
- /**
862
- * Currently focused cell — both fields are null when nothing is focused.
863
- *
864
- * @public
865
- */
866
- interface PretableFocusState {
867
- rowId: string | null;
868
- columnId: string | null;
869
- }
870
- /**
871
- * Viewport-level scroll + size state.
872
- *
873
- * @public
874
- */
875
- interface PretableViewportState {
876
- scrollTop: number;
877
- scrollLeft: number;
878
- height: number;
879
- width: number;
880
- }
881
- /**
882
- * Direction passed to the UI grid's focus movement action.
883
- *
884
- * @public
885
- */
886
- type PretableFocusDirection = "up" | "down" | "left" | "right";
887
- /**
888
- * Optional behavior modifiers for UI-grid focus movement.
889
- *
890
- * @public
891
- */
892
- interface PretableMoveFocusOptions {
893
- extend?: boolean;
894
- jumpToEdge?: boolean;
895
- byPage?: boolean;
896
- }
897
- /** A typed data-cell address owned by the indexed UI layer. @public */
898
- interface PretableIndexedCellAddress<TRowId extends PretableRowId, TColumnId extends string> {
899
- readonly rowId: TRowId;
900
- readonly columnId: TColumnId;
901
- }
902
- /**
903
- * Where a cell range's two endpoints sit in the DATASET — the coordinate
904
- * system `PretableIndexedSelectionWindow` is expressed in, not snapshot
905
- * indices, which shift under the loaded window every time it moves.
906
- *
907
- * Under the honesty gate this is the range's IDENTITY, not an annotation on
908
- * it: a range named by row ids stops meaning anything once those rows are
909
- * evicted, because an id cannot be resolved to a position without the row.
910
- * A dataset position survives the row. So `end - start + 1` stays answerable
911
- * with nothing loaded, and so does "is this rendered row inside it?".
912
- *
913
- * `start`/`end` mirror the range's own `start`/`end` endpoints and are NOT
914
- * normalized — `start` may exceed `end` for a range dragged upwards. Count
915
- * and containment order them; keeping the orientation is what lets a range
916
- * with one evicted endpoint resolve the survivor live and the absentee from
917
- * memory, instead of guessing which remembered bound belongs to which.
918
- *
919
- * @public
920
- */
921
- interface PretableIndexedDatasetRowSpan {
922
- /** Dataset position of the range's `start` endpoint. */
923
- readonly start: number;
924
- /** Dataset position of the range's `end` endpoint. */
925
- readonly end: number;
926
- /**
927
- * The population these positions were measured in — `resultMeta.datasetKey`
928
- * as of the measurement. A re-sort or a filter change re-fills the same
929
- * dataset positions with different rows, so a span carrying a different key
930
- * than the window currently reports is not stale-but-usable, it is about a
931
- * different table. Count and containment both refuse it rather than
932
- * answering from it: `indexedRangeContainsCell` returns a bare boolean and
933
- * has no `verified` channel to downgrade through, and a wrong `true` there
934
- * paints the wrong rows.
935
- *
936
- * **This is load-bearing, and it fails CLOSED.** An absent key is not a
937
- * match — it is the absence of any evidence about the population, which
938
- * leaves the engine unable to tell a scroll from a re-sort, so it refuses.
939
- * A grid that publishes `resultMeta.window` but no `resultMeta.datasetKey`
940
- * therefore gets no span at all: its selections degrade to the loaded
941
- * window, visibly, in `rowCount` and `verified`. `@pretable/react` warns
942
- * once when it sees that combination.
943
- *
944
- * Local mode is a different case and is genuinely unaffected: with no
945
- * window there are no dataset positions to record, so there is nothing a
946
- * key could qualify.
947
- */
948
- readonly datasetKey?: string;
949
- }
950
- /** Inclusive data-cell range; group rows can never be endpoints. @public */
951
- interface PretableIndexedCellRange<TRowId extends PretableRowId, TColumnId extends string> {
952
- readonly start: PretableIndexedCellAddress<TRowId, TColumnId>;
953
- readonly end: PretableIndexedCellAddress<TRowId, TColumnId>;
954
- /**
955
- * Where `start` and `end` sit in the dataset. Absent in local mode and
956
- * outside the honesty gate, where dataset positions are meaningless and
957
- * every endpoint is loaded anyway.
958
- *
959
- * Derived by the engine on every write — `setSelection` fills it in from
960
- * the loaded snapshot, and from the positions the selection being replaced
961
- * already remembers, so a gesture extending from an EVICTED anchor still
962
- * produces a countable range. Reconciliation refreshes it. A consumer that
963
- * echoes a selection back through the controlled `state` prop may
964
- * round-trip it verbatim, but does not have to: dropping it costs nothing,
965
- * because the engine recovers it by row id from the selection it replaces.
966
- */
967
- readonly datasetRowSpan?: PretableIndexedDatasetRowSpan;
968
- }
969
- /** Inclusive data-row span stored by its stable endpoint IDs. @public */
970
- interface PretableIndexedRowRange<TRowId extends PretableRowId> {
971
- readonly startRowId: TRowId;
972
- readonly endRowId: TRowId;
973
- }
974
- /** Immutable normalized interval index for symbolic row selections. @public */
975
- interface PretableIndexedRowRangeIndex<TRowId extends PretableRowId> extends Iterable<PretableIndexedRowRange<TRowId>> {
976
- readonly size: number;
977
- }
978
- /** Sparse row-checkbox state. Select-all never materializes the data population. @public */
979
- type PretableIndexedRowSelection<TRowId extends PretableRowId> = {
980
- readonly kind: "explicit";
981
- readonly rowIds: ReadonlySet<TRowId>;
982
- readonly ranges?: PretableIndexedRowRangeIndex<TRowId>;
983
- readonly excludedRanges?: PretableIndexedRowRangeIndex<TRowId>;
984
- } | {
985
- readonly kind: "all";
986
- readonly excludedRanges?: PretableIndexedRowRangeIndex<TRowId>;
987
- };
988
- /**
989
- * The row-checkbox slice as a consumer WRITES it — the settable counterpart of
990
- * {@link PretableIndexedRowSelection}, which is what the engine holds.
991
- *
992
- * Same two cases and the same discriminant, because they describe the same
993
- * thing; only the containers differ. The engine stores a `ReadonlySet` and an
994
- * opaque normalized interval index, neither of which a consumer can build; this
995
- * shape takes plain arrays and the engine indexes them at the boundary.
996
- *
997
- * The sparseness survives that conversion, which is the point of not flattening
998
- * this to a list of ids:
999
- *
1000
- * - `{ kind: "all" }` is symbolic. Applying it is O(1) whatever the row
1001
- * count — it never enumerates the population, so select-all over a million
1002
- * rows stays free.
1003
- * - `ranges` carries a shift-checked span as its two endpoints, so a 100k-row
1004
- * span costs two ids rather than 100k.
1005
- * - `excludedRowIds` is POINTS, not spans, matching what the engine can
1006
- * actually store: unticking one row out of a symbolic "all" records that
1007
- * one row. A span-shaped exclusion would read as though it could untick a
1008
- * range, which nothing here can do.
1009
- *
1010
- * @public
1011
- */
1012
- type PretableRowSelectionState<TRowId extends PretableRowId> = {
1013
- readonly kind: "explicit";
1014
- readonly rowIds: readonly TRowId[];
1015
- readonly ranges?: readonly PretableIndexedRowRange<TRowId>[];
1016
- readonly excludedRowIds?: readonly TRowId[];
1017
- } | {
1018
- readonly kind: "all";
1019
- readonly excludedRowIds?: readonly TRowId[];
1020
- };
1021
- /** Data-only selection owned by the indexed UI layer. @public */
1022
- interface PretableIndexedSelectionState<TRowId extends PretableRowId, TColumnId extends string> {
1023
- readonly rows: PretableIndexedRowSelection<TRowId>;
1024
- readonly ranges: readonly PretableIndexedCellRange<TRowId, TColumnId>[];
1025
- readonly anchor: PretableIndexedCellAddress<TRowId, TColumnId> | null;
1026
- }
1027
- /**
1028
- * Loaded span, in dataset-index terms, that `reconcileIndexedSelection` uses
1029
- * to tell an evicted row (outside `[start, start + length)`) from a deleted
1030
- * one (inside it) — see `resultMeta.window` on `PretableResultMeta`, which
1031
- * this mirrors with `length` standing in for `rows.length`. `@internal`
1032
- * rather than derived from `PretableResultMeta` directly: grid-core has no
1033
- * dependency on the react-level honesty gate that decides whether a window
1034
- * may be trusted, so callers pass this only once that gate has passed.
1035
- *
1036
- * @internal
1037
- */
1038
- interface PretableIndexedSelectionWindow {
1039
- readonly start: number;
1040
- readonly length: number;
1041
- /**
1042
- * `resultMeta.datasetKey` for the population this window is a slice of.
1043
- * Carried here rather than on a channel of its own because a span is only
1044
- * meaningful paired with the population it was measured in, and the two
1045
- * must never be able to disagree — see
1046
- * {@link PretableIndexedDatasetRowSpan.datasetKey}.
1047
- *
1048
- * Absent switches spans off entirely for this window: none are recorded and
1049
- * none are read back. That is fail-closed by design, not an oversight.
1050
- */
1051
- readonly datasetKey?: string;
1052
- }
1053
- /** Header-checkbox state derived without visiting every visible row. @public */
1054
- interface PretableIndexedSelectionSummary {
1055
- readonly state: "none" | "some" | "all";
1056
- readonly selectedCount: number;
1057
- readonly visibleCount: number;
1058
- }
1059
- /**
1060
- * How many data rows the CELL-RANGE slice covers — `ranges`, the slice a
1061
- * click/shift-click/marquee builds. Distinct from
1062
- * {@link PretableIndexedSelectionSummary}, which counts the separate sparse
1063
- * row-selection program behind the checkbox column; the two answer different
1064
- * questions and neither is derived from the other.
1065
- *
1066
- * @public
1067
- */
1068
- interface PretableIndexedCellSelectionSummary {
1069
- /**
1070
- * Distinct data rows covered, counted by arithmetic over spans — O(ranges),
1071
- * independent of how many rows are selected or how many are loaded.
1072
- * Overlapping ranges are unioned, never double-counted.
1073
- */
1074
- readonly rowCount: number;
1075
- /**
1076
- * Whether every contributing range had both endpoints loaded, so
1077
- * `rowCount` is a fact about rows that are provably still there.
1078
- *
1079
- * `false` means the count came wholly or partly from remembered dataset
1080
- * positions: the rows are evicted, and a row deleted server-side while
1081
- * evicted cannot be detected, so `rowCount` may overstate. It is still the
1082
- * best available number — the loaded-rows-only alternative understates a
1083
- * genuine selection by whatever fraction is evicted — but it may not be
1084
- * presented as a proven one. Same rule as `PretableMatchingTotal`'s
1085
- * `"exact" | "estimate"`: keep the number, qualify the claim, and let the
1086
- * boundary that must speak a bare integer downgrade (see
1087
- * `resolveAriaRowCount`).
1088
- */
1089
- readonly verified: boolean;
1090
- }
1091
- /** Group and data rows share one focus path while preserving runtime identity. @public */
1092
- interface PretableIndexedFocusState<TRowId extends PretableRowId, TColumnId extends string> {
1093
- readonly ref: PretableVisibleRowRef<TRowId> | null;
1094
- readonly columnId: TColumnId | null;
1095
- }
1096
- /** Keyboard movements supported by indexed focus navigation. @public */
1097
- type PretableIndexedFocusMovement = "up" | "down" | "left" | "right" | "page-up" | "page-down" | "home" | "end" | "tab" | "shift-tab" | "parent";
1098
- /** Visual-column input; derivation behavior remains in the row model. @public */
1099
- interface PretableGridUiColumn<TColumnId extends string> {
1100
- readonly id: TColumnId;
1101
- readonly widthPx?: number;
1102
- readonly pinned?: "left" | "right";
1103
- }
1104
- /** Normalized visual-only column layout published by the UI store. @public */
1105
- interface PretableGridUiColumnLayout<TColumnId extends string> {
1106
- readonly id: TColumnId;
1107
- readonly widthPx: number;
1108
- readonly pinned?: "left" | "right";
1109
- }
1110
- /** A correlated, data-row-only editing session. @public */
1111
- type PretableIndexedEditingState<TRowId extends PretableRowId, TColumns> = {
1112
- readonly [TColumnId in ColumnIdOf<TColumns>]: {
1113
- readonly rowId: TRowId;
1114
- readonly columnId: TColumnId;
1115
- readonly value: ColumnValueOf<TColumns, TColumnId>;
1116
- readonly status: "editing" | "validating" | "saving" | "error";
1117
- readonly error?: string;
1118
- };
1119
- }[ColumnIdOf<TColumns>];
1120
- /** The long-lived grid store's complete observable UI state. @public */
1121
- interface PretableGridUiState<TRowId extends PretableRowId, TColumns> {
1122
- readonly viewport: Readonly<PretableViewportState>;
1123
- readonly focus: Readonly<PretableIndexedFocusState<TRowId, ColumnIdOf<TColumns>>>;
1124
- readonly selection: Readonly<PretableIndexedSelectionState<TRowId, ColumnIdOf<TColumns>>>;
1125
- readonly editing: PretableIndexedEditingState<TRowId, TColumns> | null;
1126
- readonly columnLayout: readonly Readonly<PretableGridUiColumnLayout<ColumnIdOf<TColumns>>>[];
1127
- readonly observedRowModelRevision: number | null;
1128
- }
1129
- declare const gridUiCoreType: unique symbol;
1130
- /** Framework-independent UI-only indexed grid store. @public */
1131
- interface PretableGridUiCore<TRow extends object, TRowId extends PretableRowId, TColumns> {
1132
- readonly rowModel: PretableRowModel<TRow, TRowId, TColumns>;
1133
- readonly getState: () => PretableGridUiState<TRowId, TColumns>;
1134
- readonly subscribe: (listener: () => void) => () => void;
1135
- readonly setViewport: (viewport: PretableViewportState) => void;
1136
- readonly setFocus: (focus: PretableIndexedFocusState<TRowId, ColumnIdOf<TColumns>>) => void;
1137
- readonly moveFocus: (movement: PretableIndexedFocusMovement, options?: {
1138
- readonly pageRows?: number;
1139
- }) => void;
1140
- readonly setSelection: (selection: PretableIndexedSelectionState<TRowId, ColumnIdOf<TColumns>>) => void;
1141
- /**
1142
- * Replace the row-checkbox slice, leaving the cell ranges and anchor alone.
1143
- *
1144
- * The write-side counterpart of `getState().selection.rows`. `setSelection`
1145
- * cannot do this job: it takes the engine's own containers, which a consumer
1146
- * has no way to construct.
1147
- *
1148
- * Idempotent — applying a value the slice already holds publishes nothing, so
1149
- * a controlled caller can push on every render without looping.
1150
- */
1151
- readonly setRowSelection: (rows: PretableRowSelectionState<TRowId>) => void;
1152
- readonly toggleRowSelection: (rowId: TRowId) => void;
1153
- readonly selectRowRange: (startRowId: TRowId, endRowId: TRowId) => void;
1154
- readonly isRowSelected: (rowId: TRowId) => boolean;
1155
- readonly getSelectionSummary: () => PretableIndexedSelectionSummary;
1156
- /**
1157
- * How many data rows the CELL-RANGE slice covers, and whether that number
1158
- * is proven. Counted by arithmetic over dataset spans, so it stays correct
1159
- * — and O(ranges) — while most of the selection is evicted.
1160
- *
1161
- * A separate method from {@link getSelectionSummary} because they count
1162
- * different slices: that one counts the sparse row-selection program the
1163
- * checkbox column drives, this one counts `selection.ranges`.
1164
- */
1165
- readonly getCellSelectionSummary: () => PretableIndexedCellSelectionSummary;
1166
- readonly selectAllVisibleRows: () => void;
1167
- readonly clearSelection: () => void;
1168
- readonly beginEdit: <TColumnId extends ColumnIdOf<TColumns>>(input: {
1169
- readonly rowId: TRowId;
1170
- readonly columnId: TColumnId;
1171
- readonly value: ColumnValueOf<TColumns, TColumnId>;
1172
- }) => void;
1173
- readonly setEditDraft: (value: unknown) => void;
1174
- readonly setEditStatus: (status: "editing" | "validating" | "saving" | "error", error?: string) => void;
1175
- readonly cancelEdit: () => void;
1176
- /** Reconciles the current visual column set without changing row schema. */
1177
- readonly setColumns: (columns: readonly PretableGridUiColumn<ColumnIdOf<TColumns>>[]) => void;
1178
- readonly setColumnWidth: (columnId: ColumnIdOf<TColumns>, width: number) => void;
1179
- readonly setColumnPinned: (columnId: ColumnIdOf<TColumns>, pinned: "left" | "right" | null) => void;
1180
- readonly setColumnOrder: (columnIds: readonly ColumnIdOf<TColumns>[]) => void;
1181
- /** @internal Called only after renderer geometry for this exact revision exists. */
1182
- readonly observeRowModelRevision: (revision: number) => void;
1183
- readonly dispose: () => void;
1184
- /** @internal Compile-time-only invariant descriptor. */
1185
- readonly [gridUiCoreType]?: (value: readonly [TRow, TRowId, TColumns]) => readonly [TRow, TRowId, TColumns];
1186
- }
1187
-
1188
- /** Options accepted by the UI-only grid facade. @public */
1189
- interface CreateGridUiCoreOptions<TRow extends object, TRowId extends PretableRowId, TColumns> {
1190
- readonly rowModel: PretableRowModel<TRow, TRowId, TColumns>;
1191
- readonly columns: readonly PretableGridUiColumn<ColumnIdOf<TColumns>>[];
1192
- readonly viewport?: PretableViewportState;
1193
- /**
1194
- * @internal Late-bound getter for the loaded span (dataset-index terms)
1195
- * behind the same honesty gate as `aria-rowindex` and the scroll-extent
1196
- * spacers — see `WindowSpacers`/`getWindowSpacers` in `@pretable/react`'s
1197
- * `pretable-model.ts`, which this mirrors and is fed by. Read fresh on
1198
- * every row-model revision (never cached) so `reconcileIndexedSelection`
1199
- * can tell an evicted row from a deleted one — see
1200
- * {@link PretableIndexedSelectionWindow}. Undefined, or a getter that
1201
- * returns null, reproduces pre-eviction behavior exactly: every absent
1202
- * row is treated as deleted.
1203
- */
1204
- readonly getSelectionWindow?: () => PretableIndexedSelectionWindow | null;
1205
- }
1206
-
1207
- /**
1208
- * Render the engine's row-checkbox slice as the shape a consumer can write
1209
- * back — the inverse of {@link createIndexedRowSelection}.
1210
- *
1211
- * Sparse in, sparse out. A symbolic "all" stays two words, and a shift-checked
1212
- * 100k-row span stays its two endpoint ids; nothing here walks a population.
1213
- *
1214
- * @public
1215
- */
1216
- declare function describeRowSelection<TRowId extends PretableRowId>(rows: PretableIndexedRowSelection<TRowId>): PretableRowSelectionState<TRowId>;
1217
-
1218
- /**
1219
- * Half-open row index range — `start` inclusive, `end` exclusive — used to
1220
- * describe a visible row window without materializing the rows outside it.
1221
- *
1222
- * @public
1223
- */
1224
- interface PretableRowRange {
1225
- start: number;
1226
- end: number;
1227
- }
1228
- /**
1229
- * Tuning knobs for column autosize calculations.
1230
- *
1231
- * @public
1232
- */
1233
- interface AutosizeOptions {
1234
- maxWidthPx?: number;
1235
- minWidthPx?: number;
1236
- averageCharWidth?: number;
1237
- cellPaddingPx?: number;
1238
- }
1239
-
1240
- /** Id of the synthetic visual column that carries grouped row labels. @public */
1241
- declare const GROUP_COLUMN_ID = "__pretable_group__";
1242
- /** Presentation options for the synthetic grouped-row column. @public */
1243
- interface PretableGroupColumnOptions {
1244
- /** Header text. Defaults to the first grouped column's header. */
1245
- header?: string;
1246
- /** Column width. Defaults to 200 pixels. */
1247
- widthPx?: number;
1248
- /** Pin the group column to the left. */
1249
- pinned?: "left";
1250
- }
1251
-
1252
- /**
1253
- * Create a framework-independent UI-state grid over an explicit indexed row
1254
- * model. Data, queries, grouping, aggregation, and expansion remain owned by
1255
- * `rowModel`; this handle owns only focus, selection, editing, viewport, and
1256
- * visual column layout.
1257
- *
1258
- * @public
1259
- */
1260
- declare function createGrid<TRow extends object, TRowId extends PretableRowId, TColumns>(options: CreateGridUiCoreOptions<TRow, TRowId, TColumns>): PretableGridUiCore<TRow, TRowId, TColumns>;
1261
-
1262
- /**
1263
- * Creates a typed column-definition helper for an ordinary row object.
1264
- *
1265
- * @public
1266
- */
1267
- declare function createColumnHelper<TRow extends object>(): PretableColumnHelper<TRow>;
1268
-
1269
- /** Options for a local row model with an explicit row-ID accessor. @public */
1270
- interface CreateLocalRowModelOptions<TColumns, TRowId extends PretableRowId> {
1271
- readonly rows: readonly (TColumns extends readonly [
1272
- infer TFirstColumn,
1273
- ...(readonly unknown[])
1274
- ] ? TFirstColumn extends {
1275
- readonly accessor: (row: infer TRow extends object) => infer TValue;
1276
- } ? [TValue] extends [unknown] ? TRow : never : never : never)[];
1277
- readonly columns: TColumns & {
1278
- readonly [K in keyof TColumns]: TColumns[K] extends {
1279
- readonly accessor: (row: infer TColumnRow extends object) => infer TColumnValue;
1280
- } ? [TColumnValue] extends [unknown] ? TColumns extends readonly [
1281
- infer TFirstColumn,
1282
- ...(readonly unknown[])
1283
- ] ? TFirstColumn extends {
1284
- readonly accessor: (row: infer TFirstRow extends object) => infer TFirstValue;
1285
- } ? [TFirstValue] extends [unknown] ? [TColumnRow] extends [TFirstRow] ? [TFirstRow] extends [TColumnRow] ? TColumns[K] : never : never : never : never : never : never : never;
1286
- };
1287
- readonly derivations?: PretableDerivationsFor<TColumns>;
1288
- readonly query?: PretableQueryFor<TColumns>;
1289
- readonly initialExpansion?: PretableExpansionDefault;
1290
- readonly aggregateFilteredRows?: boolean;
1291
- readonly getRowId: (row: TColumns extends readonly [infer TFirstColumn, ...(readonly unknown[])] ? TFirstColumn extends {
1292
- readonly accessor: (row: infer TRow extends object) => infer TValue;
1293
- } ? [TValue] extends [unknown] ? TRow : never : never : never) => TRowId;
1294
- }
1295
- /** Options for a local row model using the conventional `row.id`. @public */
1296
- type CreateLocalRowModelWithDefaultIdOptions<TColumns> = (TColumns extends readonly [infer TFirstColumn, ...(readonly unknown[])] ? TFirstColumn extends {
1297
- readonly accessor: (row: infer TRow extends object) => infer TValue;
1298
- } ? [TValue] extends [unknown] ? TRow : never : never : never) extends {
1299
- readonly id: PretableRowId;
1300
- } ? Prettify<{
1301
- readonly rows: readonly (TColumns extends readonly [
1302
- infer TFirstColumn,
1303
- ...(readonly unknown[])
1304
- ] ? TFirstColumn extends {
1305
- readonly accessor: (row: infer TRow extends object) => infer TValue;
1306
- } ? [TValue] extends [unknown] ? TRow : never : never : never)[];
1307
- readonly columns: TColumns & {
1308
- readonly [K in keyof TColumns]: TColumns[K] extends {
1309
- readonly accessor: (row: infer TColumnRow extends object) => infer TColumnValue;
1310
- } ? [TColumnValue] extends [unknown] ? TColumns extends readonly [
1311
- infer TFirstColumn,
1312
- ...(readonly unknown[])
1313
- ] ? TFirstColumn extends {
1314
- readonly accessor: (row: infer TFirstRow extends object) => infer TFirstValue;
1315
- } ? [TFirstValue] extends [unknown] ? [TColumnRow] extends [TFirstRow] ? [TFirstRow] extends [TColumnRow] ? TColumns[K] : never : never : never : never : never : never : never;
1316
- };
1317
- readonly derivations?: PretableDerivationsFor<TColumns>;
1318
- readonly query?: PretableQueryFor<TColumns>;
1319
- readonly initialExpansion?: PretableExpansionDefault;
1320
- readonly aggregateFilteredRows?: boolean;
1321
- readonly getRowId?: undefined;
1322
- }> : never;
1323
- /**
1324
- * Creates a local row model using the conventional `row.id` field.
1325
- *
1326
- * @public
1327
- */
1328
- declare function createLocalRowModel<const TColumns extends readonly [unknown, ...(readonly unknown[])]>(options: CreateLocalRowModelWithDefaultIdOptions<TColumns>): PretableRowModel<CreateLocalRowModelWithDefaultIdOptions<TColumns>["rows"][number], CreateLocalRowModelWithDefaultIdOptions<TColumns>["rows"][number] extends {
1329
- readonly id: infer TRowId extends PretableRowId;
1330
- } ? TRowId : never, TColumns>;
1331
- /**
1332
- * Creates a local row model using an explicit string or number row ID.
1333
- *
1334
- * @public
1335
- */
1336
- declare function createLocalRowModel<const TColumns extends readonly [unknown, ...(readonly unknown[])], const TRowId extends PretableRowId>(options: CreateLocalRowModelOptions<TColumns, TRowId>): PretableRowModel<CreateLocalRowModelOptions<TColumns, TRowId>["rows"][number], TRowId, TColumns>;
1337
-
1338
- /**
1339
- * Options for Pretable's currency number-format presets.
1340
- *
1341
- * @public
1342
- */
1343
- type PretableCurrencyFormatOptions = Omit<Intl.NumberFormatOptions, "style" | "currency" | "currencySign"> & {
1344
- currency: string;
1345
- };
1346
- /**
1347
- * Native number-format presets for money and accounting presentation.
1348
- *
1349
- * @public
1350
- */
1351
- declare const numberFormats: {
1352
- readonly money: (options: PretableCurrencyFormatOptions) => Intl.NumberFormatOptions;
1353
- readonly accounting: (options: PretableCurrencyFormatOptions) => Intl.NumberFormatOptions;
1354
- };
1355
-
1356
- export { type AutosizeOptions, type ColumnAggregateValueOf, type ColumnAlign, type ColumnFilter, type ColumnIdOf, type ColumnOption, type ColumnType, type ColumnValueOf, type ColumnsOf, type CreateGridUiCoreOptions, type CreateLocalRowModelOptions, type CreateLocalRowModelWithDefaultIdOptions, type FilterOperator, type FilterValue, GROUP_COLUMN_ID, type PretableAggregateFormatInput, type PretableAggregateOutputOf, type PretableAggregateSpec, type PretableAggregatesFor, type PretableAggregator, type PretableBuiltinAggregate, type PretableCellAddress, type PretableCellRange, type PretableChangeOperation, type PretableChangeSequence, type PretableChangeSet, type PretableColumn, type PretableColumnAccessorKind, type PretableColumnCallbackContext, type PretableColumnDefinition, type PretableColumnDerivation, type PretableColumnHelper, type PretableColumnOptions, type PretableColumnType, type PretableColumnTypeFor, type PretableCompatibleAggregateSpec, type PretableCompatibleAggregator, type PretableCurrencyFormatOptions, type PretableDataRow, type PretableDerivationTransition, type PretableDerivationsFor, PretableDisposedModelError, type PretableDistinctColumnIdOf, type PretableDistinctValueOptions, type PretableDistinctValueQuery, type PretableDistinctValueResult, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableExpansionDefault, type PretableExpansionState, type PretableFilterFor, type PretableFilterOperandFor, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGridUiColumn, type PretableGridUiColumnLayout, type PretableGridUiCore, type PretableGridUiState, type PretableGroupColumnOptions, type PretableGroupId, type PretableGroupKey, type PretableGroupRow, type PretableIndexedCellAddress, type PretableIndexedCellRange, type PretableIndexedCellSelectionSummary, type PretableIndexedDatasetRowSpan, type PretableIndexedEditingState, type PretableIndexedFocusMovement, type PretableIndexedFocusState, type PretableIndexedRowRange, type PretableIndexedRowRangeIndex, type PretableIndexedRowSelection, type PretableIndexedSelectionState, type PretableIndexedSelectionSummary, PretableInvalidGroupKeyError, type PretableMatchingTotal, type PretableMoveFocusOptions, type PretableMutationIssue, type PretableMutationResult, type PretableProcessingAuthority, type PretableProcessingOptions, type PretableQueryFor, type PretableQueryTransition, PretableReentrantMutationError, type PretableResultMeta, type PretableRow, type PretableRowGroupFor, type PretableRowId, PretableRowIdentityChangeError, type PretableRowModel, PretableRowModelError, type PretableRowModelErrorCode, type PretableRowModelErrorContext, type PretableRowModelOperation, type PretableRowModelSnapshot, type PretableRowModelState, type PretableRowModelStatus, type PretableRowRange, type PretableRowSelectionState, type PretableRowUpdate, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableSortFor, type PretableTransaction, type PretableTransitionCancellationReason, PretableTransitionCancelledError, PretableUnsupportedRowUpdateError, type PretableViewportState, type PretableVisibleRow, type PretableVisibleRowField, type PretableVisibleRowRef, type Prettify, type RowIdOf, type RowOf, createColumnHelper, createGrid, createLocalRowModel, describeRowSelection, numberFormats, type PretableIndexedSelectionWindow as ɵPretableIndexedSelectionWindow };