@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.
@@ -0,0 +1,1918 @@
1
+ //#region ../row-model/dist/column-types.d.ts
2
+ /**
3
+ * Expand mapped/intersection types into readable editor hovers.
4
+ * @public
5
+ */
6
+ type Prettify<T> = { [K in keyof T]: T[K]; } & {};
7
+ /** @public */
8
+ type PretableRowId = string | number;
9
+ /**
10
+ * Values with stable, collision-free local grouping identity.
11
+ * @public
12
+ */
13
+ type PretableGroupKey = string | number | bigint | boolean | Date | null | undefined;
14
+ /** @public */
15
+ type PretableColumnType = "text" | "number" | "date" | "enum" | "boolean";
16
+ /** @public */
17
+ interface PretableAggregator<TRow extends object = object, TValue = unknown, TAccumulator = unknown, TOutput = unknown> {
18
+ readonly init: () => TAccumulator;
19
+ readonly accumulate: (accumulator: TAccumulator, value: TValue, row: TRow) => TAccumulator;
20
+ readonly merge: (left: TAccumulator, right: TAccumulator) => TAccumulator;
21
+ /**
22
+ * Produces a detached accumulator for `finalize`. Required when the
23
+ * accumulator is a class instance or otherwise cannot be structured-cloned
24
+ * without losing behavior.
25
+ */
26
+ readonly snapshotAccumulator?: (accumulator: TAccumulator) => TAccumulator;
27
+ readonly finalize: (accumulator: TAccumulator) => TOutput;
28
+ }
29
+ /** @public */
30
+ type PretableBuiltinAggregate<TValue> = "count" | ([NonNullable<TValue>] extends [never] ? never : NonNullable<TValue> extends number ? "sum" | "avg" | "min" | "max" : never);
31
+ /** @public */
32
+ type PretableAggregateSpec<TRow extends object, TValue> = PretableBuiltinAggregate<TValue> | PretableCompatibleAggregator<TRow, TValue, unknown>;
33
+ /**
34
+ * Compile-time-only sentinel for `PretableColumnHelper.accessor`'s `TValue`:
35
+ * it means "no value type has been inferred from the accessor yet", which is
36
+ * what lets the helper offer the widened `type` and `aggregate` choices in the
37
+ * accessor-form overload and the narrowed ones everywhere else.
38
+ *
39
+ * It is an interface with an unwritable key rather than the `unique symbol` it
40
+ * replaced, for the reason spelled out over `PretableGroupId` in `./types.ts`:
41
+ * a `unique symbol` is nominal per declaration file, and these declarations are
42
+ * re-emitted into `core/dist` by the public declaration bundle.
43
+ *
44
+ * @public
45
+ */
46
+ interface PretableUninferredColumnValue {
47
+ readonly "~pretableUninferredColumnValue": true;
48
+ }
49
+ /** Compile-time-only accessor-form carrier emitted by the column helper. @public */
50
+ interface PretableColumnAccessorKind<TKind extends "direct" | "computed"> {
51
+ readonly "~pretableColumn": {
52
+ readonly accessorKind: TKind;
53
+ };
54
+ }
55
+ /** @public */
56
+ interface PretableFormatInput<TRow extends object, TValue = unknown, TColumn = unknown> {
57
+ readonly value: TValue;
58
+ readonly row: TRow;
59
+ readonly column: TColumn;
60
+ }
61
+ /** @public */
62
+ interface PretableAggregateFormatInput<TValue, TColumn> {
63
+ readonly value: TValue;
64
+ readonly column: TColumn;
65
+ }
66
+ /** @public */
67
+ type PretableAggregateOutputOf<TAggregate> = TAggregate extends {
68
+ readonly finalize: (accumulator: never) => infer TOutput;
69
+ } ? TOutput : TAggregate extends "sum" | "avg" | "min" | "max" | "count" ? number | null : never;
70
+ /** @public */
71
+ interface PretableColumnDefinition<TRow extends object, TId extends string, TValue, TType extends PretableColumnType, TAggregate = undefined> {
72
+ readonly id: TId;
73
+ readonly type: TType;
74
+ readonly header?: string;
75
+ readonly accessorKey?: Extract<keyof TRow, string>;
76
+ readonly accessor: (row: TRow) => TValue;
77
+ /** Compatibility spelling retained on the original column object. */
78
+ readonly value: (row: TRow) => TValue;
79
+ readonly compare?: (left: TValue, right: TValue) => number;
80
+ readonly aggregate?: TAggregate;
81
+ /**
82
+ * Native number presentation. Outranked by `format` for data cells and by
83
+ * `formatAggregate` for group aggregates; derivation, editing, and every
84
+ * row-model read continue to see the raw value.
85
+ */
86
+ readonly numberFormat?: Intl.NumberFormatOptions;
87
+ readonly format?: (input: PretableFormatInput<TRow, TValue, PretableColumnDefinition<TRow, TId, TValue, TType, TAggregate>>) => string;
88
+ readonly formatAggregate?: (input: PretableAggregateFormatInput<PretableAggregateOutputOf<TAggregate>, PretableColumnDefinition<TRow, TId, TValue, TType, TAggregate>>) => string;
89
+ readonly ["~pretableColumn"]: {
90
+ readonly row: TRow;
91
+ readonly id: TId;
92
+ readonly value: TValue;
93
+ readonly type: TType;
94
+ readonly aggregate: TAggregate;
95
+ };
96
+ }
97
+ /** @public */
98
+ 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;
99
+ /** @public */
100
+ interface PretableColumnCallbackContext<TRow extends object, TId extends string, TValue, TType extends PretableColumnType, TAggregate> {
101
+ readonly id: TId;
102
+ readonly type: TType;
103
+ readonly accessor: (row: TRow) => TValue;
104
+ readonly value: (row: TRow) => TValue;
105
+ readonly aggregate?: TAggregate;
106
+ }
107
+ /** @public */
108
+ type PretableColumnOptions<TRow extends object, TId extends string, TValue, TType extends PretableColumnTypeFor<TValue>, TAggregate extends PretableAggregateSpec<TRow, TValue> | undefined> = {
109
+ readonly type: TType;
110
+ readonly header?: string;
111
+ readonly compare?: (left: TValue, right: TValue) => number;
112
+ readonly aggregate?: TAggregate;
113
+ /** Native number presentation; `format` outranks it for data cells. */
114
+ readonly numberFormat?: Intl.NumberFormatOptions;
115
+ readonly format?: (input: {
116
+ readonly value: TValue;
117
+ readonly row: TRow;
118
+ readonly column: PretableColumnCallbackContext<TRow, TId, TValue, TType, TAggregate>;
119
+ }) => string;
120
+ readonly formatAggregate?: (input: {
121
+ readonly value: PretableAggregateOutputOf<TAggregate>;
122
+ readonly column: PretableColumnCallbackContext<TRow, TId, TValue, TType, TAggregate>;
123
+ }) => string;
124
+ };
125
+ /** @public */
126
+ interface PretableColumnHelper<TRow extends object> {
127
+ accessor<const TId extends string, const TAccessor extends (...args: never[]) => unknown, const TType extends (unknown extends NoInfer<TValue> ? never : PretableColumnTypeFor<NoInfer<TValue>>) | ([TValue] extends [PretableUninferredColumnValue] ? [ReturnType<TAccessor>] extends [never] ? never : PretableColumnType : never), TValue = PretableUninferredColumnValue, const TAggregate extends PretableAggregateSpec<TRow, NoInfer<TValue>> | ([TValue] extends [PretableUninferredColumnValue] ? [ReturnType<TAccessor>] extends [never] ? never : PretableAggregateSpec<TRow, never> | "sum" | "avg" | "min" | "max" : never) | undefined = undefined>(id: TId, accessor: TAccessor & ((row: TRow) => TValue), options: {
128
+ readonly type: TType;
129
+ readonly header?: string;
130
+ readonly compare?: (left: TValue, right: TValue) => number;
131
+ readonly aggregate?: TAggregate;
132
+ /** Native number presentation; `format` outranks it for data cells. */
133
+ readonly numberFormat?: Intl.NumberFormatOptions;
134
+ readonly format?: (input: {
135
+ readonly value: TValue;
136
+ readonly row: TRow;
137
+ readonly column: PretableColumnCallbackContext<TRow, TId, TValue, TType, TAggregate>;
138
+ }) => string;
139
+ readonly formatAggregate?: (input: {
140
+ readonly value: PretableAggregateOutputOf<TAggregate>;
141
+ readonly column: PretableColumnCallbackContext<TRow, TId, TValue, TType, TAggregate>;
142
+ }) => string;
143
+ }): PretableColumnDefinition<TRow, TId, ReturnType<TAccessor>, TType, TAggregate> & PretableColumnAccessorKind<"computed">;
144
+ 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">;
145
+ }
146
+ /** @public */
147
+ type ColumnIdOf<TColumns> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
148
+ readonly id: infer TId extends string;
149
+ } ? TId : never : never;
150
+ /**
151
+ * The value type of the column with the given id.
152
+ *
153
+ * An accessored column resolves to its exact declared type. A column that
154
+ * declares no accessor — the loose, id-keyed shape — resolves to `unknown`,
155
+ * not `never`: the value genuinely isn't known statically, and `never` is
156
+ * assignable to everything, so it silently accepted (and made vacuous) every
157
+ * runtime guard written against it. `unknown` forces the guard instead.
158
+ *
159
+ * Two pieces of the shape below are load-bearing:
160
+ *
161
+ * - The inner `never` stays `never`. The lookup distributes over the column
162
+ * union, so for a mixed tuple every non-matching member contributes to the
163
+ * result union; `never` is the union identity, so those members vanish and
164
+ * the matching member's type survives exactly. Falling back to `unknown`
165
+ * per member would union `unknown` into every answer and destroy that.
166
+ * - The fallback is applied through `[...] extends [infer TResolved]`, which
167
+ * binds the resolved type once (no repetition, no extra exported alias)
168
+ * while the tuple wrapper blocks distribution. A naked `extends infer` would
169
+ * distribute, and distributing over `never` short-circuits the whole
170
+ * conditional to `never` — which is precisely the case this fallback exists
171
+ * to catch.
172
+ *
173
+ * @public
174
+ */
175
+ type ColumnValueOf<TColumns, TColumnId extends ColumnIdOf<TColumns>> = [TColumns extends readonly (infer TColumn)[] ? TColumn extends {
176
+ readonly id: TColumnId;
177
+ readonly accessor: (...args: never[]) => infer TValue;
178
+ } ? TValue : never : never] extends [infer TResolved] ? [TResolved] extends [never] ? unknown : TResolved : never;
179
+ /** @public */
180
+ type ColumnAggregateValueOf<TColumns, TColumnId extends ColumnIdOf<TColumns>> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
181
+ readonly id: TColumnId;
182
+ readonly aggregate?: infer TAggregate;
183
+ } ? PretableAggregateOutputOf<TAggregate> : never : never;
184
+ /** @public */
185
+ type PretableAggregatesFor<TColumns> = Prettify<{ readonly [TColumn in TColumns extends readonly (infer TItem)[] ? TItem : never as TColumn extends {
186
+ readonly id: infer TId extends string;
187
+ readonly aggregate?: infer TAggregate;
188
+ } ? [TAggregate] extends [undefined] ? never : TId : never]: TColumn extends {
189
+ readonly aggregate?: infer TAggregate;
190
+ } ? PretableAggregateOutputOf<TAggregate> : never; }>;
191
+ /**
192
+ * The runtime filter operand accepted by a declared column type.
193
+ * Enum columns retain known string literal values and otherwise accept strings.
194
+ * @public
195
+ */
196
+ 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>;
197
+ /** @public */
198
+ type PretableFilterFor<TColumns> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
199
+ readonly id: infer TId extends string;
200
+ readonly accessor: (...args: never[]) => infer TValue;
201
+ readonly type: infer TType extends PretableColumnType;
202
+ } ? {
203
+ readonly columnId: TId;
204
+ readonly operator: "isEmpty" | "isNotEmpty";
205
+ } | (TType extends "number" ? {
206
+ readonly columnId: TId;
207
+ readonly operator: "equals" | "notEquals" | "gt" | "gte" | "lt" | "lte";
208
+ readonly value: PretableFilterOperandFor<TValue, TType>;
209
+ } | {
210
+ readonly columnId: TId;
211
+ readonly operator: "between";
212
+ readonly value: readonly [PretableFilterOperandFor<TValue, TType>, PretableFilterOperandFor<TValue, TType>];
213
+ } : TType extends "date" ? {
214
+ readonly columnId: TId;
215
+ readonly operator: "on" | "before" | "after";
216
+ readonly value: PretableFilterOperandFor<TValue, TType>;
217
+ } | {
218
+ readonly columnId: TId;
219
+ readonly operator: "dateBetween";
220
+ readonly value: readonly [PretableFilterOperandFor<TValue, TType>, PretableFilterOperandFor<TValue, TType>];
221
+ } : TType extends "enum" | "boolean" ? {
222
+ readonly columnId: TId;
223
+ readonly operator: "isAnyOf" | "isNoneOf";
224
+ readonly value: readonly PretableFilterOperandFor<TValue, TType>[];
225
+ } : {
226
+ readonly columnId: TId;
227
+ readonly operator: "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith";
228
+ readonly value: PretableFilterOperandFor<TValue, TType>;
229
+ }) : never : never;
230
+ /**
231
+ * A branch of the filter tree: a join operator and the nodes it joins. A group
232
+ * may hold leaves, further groups, or nothing at all, and may nest.
233
+ *
234
+ * An `and` group holds when every child holds; an `or` group holds when any
235
+ * child does. An EMPTY group holds under both operators — it constrains
236
+ * nothing, so a group still being assembled never removes rows.
237
+ * @public
238
+ */
239
+ interface PretableFilterGroupFor<TColumns> {
240
+ readonly op: "and" | "or";
241
+ readonly children: readonly PretableFilterNodeFor<TColumns>[];
242
+ }
243
+ /**
244
+ * One node of the filter tree: either a typed leaf or a group of nodes.
245
+ * @public
246
+ */
247
+ type PretableFilterNodeFor<TColumns> = PretableFilterFor<TColumns> | PretableFilterGroupFor<TColumns>;
248
+ /**
249
+ * Narrows one filter-tree node to a group. Checked positively on the group's
250
+ * own fields, so an unknown shape fails closed rather than being treated as a
251
+ * branch with no children.
252
+ * @public
253
+ */
254
+ declare function isPretableFilterGroup<TColumns>(node: PretableFilterNodeFor<TColumns>): node is PretableFilterGroupFor<TColumns>;
255
+ /** @public */
256
+ type PretableSortFor<TColumns> = Prettify<(TColumns extends readonly (infer TColumn)[] ? TColumn extends {
257
+ readonly id: infer TId extends string;
258
+ } ? {
259
+ readonly columnId: TId;
260
+ } : never : never) & {
261
+ readonly direction: "asc" | "desc";
262
+ readonly nulls?: "first" | "last";
263
+ }>;
264
+ /** @public */
265
+ type PretableRowGroupFor<TColumns> = Prettify<(TColumns extends readonly (infer TColumn)[] ? TColumn extends {
266
+ readonly id: infer TId extends string;
267
+ readonly accessor: (...args: never[]) => infer TValue;
268
+ } ? [TValue] extends [never] ? never : [TValue] extends [PretableGroupKey] ? {
269
+ readonly columnId: TId;
270
+ } : never : never : never) & {
271
+ readonly direction?: "asc" | "desc";
272
+ readonly nulls?: "first" | "last";
273
+ }>;
274
+ /** @public */
275
+ interface PretableQueryFor<TColumns> {
276
+ readonly filters: readonly PretableFilterNodeFor<TColumns>[];
277
+ readonly sort: readonly PretableSortFor<TColumns>[];
278
+ readonly rowGroups: readonly PretableRowGroupFor<TColumns>[];
279
+ }
280
+ /** @public */
281
+ interface PretableCompatibleAggregator<TRow extends object, TValue, TOutput> {
282
+ readonly init: () => unknown;
283
+ readonly accumulate: {
284
+ bivarianceHack(accumulator: unknown, value: TValue, row: TRow): unknown;
285
+ }["bivarianceHack"] & ((accumulator: never, value: TValue, row: TRow) => unknown);
286
+ readonly merge: {
287
+ bivarianceHack(left: unknown, right: unknown): unknown;
288
+ }["bivarianceHack"];
289
+ readonly snapshotAccumulator?: {
290
+ bivarianceHack(accumulator: unknown): unknown;
291
+ }["bivarianceHack"];
292
+ readonly finalize: {
293
+ bivarianceHack(accumulator: unknown): TOutput;
294
+ }["bivarianceHack"];
295
+ }
296
+ /** @public */
297
+ 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>>;
298
+ /** @public */
299
+ interface PretableColumnDerivation<TRow extends object, TId extends string, TValue, TType extends PretableColumnType, TAggregate> {
300
+ readonly id: TId;
301
+ readonly type: TType;
302
+ readonly accessor: (row: TRow) => TValue;
303
+ readonly value: (row: TRow) => TValue;
304
+ readonly compare?: (left: TValue, right: TValue) => number;
305
+ readonly aggregate?: PretableCompatibleAggregateSpec<TRow, TValue, TAggregate>;
306
+ readonly ["~pretableColumn"]: {
307
+ readonly row: TRow;
308
+ readonly id: TId;
309
+ readonly value: TValue;
310
+ readonly type: TType;
311
+ readonly aggregate: PretableCompatibleAggregateSpec<TRow, TValue, TAggregate>;
312
+ };
313
+ }
314
+ /** @public */
315
+ type PretableDerivationsFor<TColumns> = { readonly [K in keyof TColumns]: TColumns[K] extends {
316
+ readonly id: infer TId extends string;
317
+ readonly type: infer TType extends PretableColumnType;
318
+ readonly accessor: (row: infer TRow extends object) => infer TValue;
319
+ readonly aggregate?: infer TAggregate;
320
+ } ? PretableColumnDerivation<TRow, TId, TValue, TType, TAggregate> : never; };
321
+ //#endregion
322
+ //#region ../row-model/dist/errors.d.ts
323
+ /** @public */
324
+ 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";
325
+ /** @public */
326
+ 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";
327
+ /** @public */
328
+ interface PretableRowModelErrorContext {
329
+ readonly operation: PretableRowModelOperation;
330
+ readonly rowId?: PretableRowId;
331
+ readonly columnId?: string;
332
+ readonly cause?: unknown;
333
+ }
334
+ /** @public */
335
+ declare class PretableRowModelError extends Error {
336
+ readonly name: string;
337
+ readonly code: PretableRowModelErrorCode;
338
+ readonly operation: PretableRowModelOperation;
339
+ readonly rowId?: PretableRowId;
340
+ readonly columnId?: string;
341
+ constructor(code: PretableRowModelErrorCode, message: string, context: PretableRowModelErrorContext);
342
+ }
343
+ /** @public */
344
+ declare class PretableDisposedModelError extends PretableRowModelError {
345
+ readonly name: string;
346
+ constructor(operation: PretableRowModelOperation);
347
+ }
348
+ /** @public */
349
+ declare class PretableReentrantMutationError extends PretableRowModelError {
350
+ readonly activeOperation: PretableRowModelOperation;
351
+ readonly name = "PretableReentrantMutationError";
352
+ constructor(operation: PretableRowModelOperation, activeOperation: PretableRowModelOperation);
353
+ }
354
+ /** @public */
355
+ declare class PretableRowIdentityChangeError extends PretableRowModelError {
356
+ readonly nextRowId: unknown;
357
+ readonly name = "PretableRowIdentityChangeError";
358
+ constructor(rowId: PretableRowId, nextRowId: unknown, cause?: unknown);
359
+ }
360
+ /** @public */
361
+ declare class PretableUnsupportedRowUpdateError extends PretableRowModelError {
362
+ readonly name = "PretableUnsupportedRowUpdateError";
363
+ constructor(rowId: PretableRowId, cause?: unknown);
364
+ }
365
+ /** @public */
366
+ declare class PretableInvalidGroupKeyError extends PretableRowModelError {
367
+ readonly value: unknown;
368
+ readonly name = "PretableInvalidGroupKeyError";
369
+ constructor(operation: PretableRowModelOperation, rowId: PretableRowId | undefined, columnId: string, value: unknown, cause?: unknown);
370
+ }
371
+ /** @public */
372
+ type PretableTransitionCancellationReason = "cancelled" | "superseded" | "disposed";
373
+ /** @public */
374
+ declare class PretableTransitionCancelledError extends Error {
375
+ readonly transitionId: number;
376
+ readonly reason: PretableTransitionCancellationReason;
377
+ readonly name = "PretableTransitionCancelledError";
378
+ constructor(transitionId: number, reason: PretableTransitionCancellationReason);
379
+ }
380
+ //#endregion
381
+ //#region ../row-model/dist/types.d.ts
382
+ /**
383
+ * Brand keys are STRING literals, not `unique symbol`s, and that is load-bearing
384
+ * packaging rather than style.
385
+ *
386
+ * These types ship to consumers three ways at once: `tsc` emits them into
387
+ * `row-model/dist`, and the public declaration bundle re-emits them into
388
+ * `core/dist` — with `@pretable/react` compiling against BOTH at
389
+ * once. A `unique symbol` is nominal PER DECLARATION FILE, so each re-emission
390
+ * minted a fresh, incompatible brand: `PretableGroupId` from `row-model/dist`
391
+ * was not assignable to `PretableGroupId` from `core/dist` despite being the
392
+ * same declaration, and `RowOf<>`/`ColumnsOf<>` — which match structurally on
393
+ * `~pretableRowModel` — silently resolved to `never` across the seam. The
394
+ * repository carried two `as unknown as` casts to paper over exactly that.
395
+ *
396
+ * A string-literal key is structural, so N copies of the declaration are one
397
+ * type. Nominality is unchanged in practice: `PretableGroupId` is
398
+ * `string & {...}`, which no literal can inhabit without a cast, and the `~`
399
+ * prefix keeps the key unwritable as an identifier (the Standard Schema
400
+ * convention). `scripts/__tests__/public-api-symbol-brands.test.mjs` fails the
401
+ * build if a symbol-keyed brand reappears in a published API report.
402
+ */
403
+ /** @public */
404
+ type PretableGroupId = string & {
405
+ readonly "~pretableGroupId": "PretableGroupId";
406
+ };
407
+ /** @public */
408
+ type PretableVisibleRowRef<TRowId extends PretableRowId> = {
409
+ readonly kind: "data";
410
+ readonly rowId: TRowId;
411
+ } | {
412
+ readonly kind: "group";
413
+ readonly groupId: PretableGroupId;
414
+ };
415
+ /** @public */
416
+ interface PretableDataRow<TRow extends object, TRowId extends PretableRowId> {
417
+ readonly kind: "data";
418
+ readonly rowId: TRowId;
419
+ readonly row: TRow;
420
+ readonly sourceIndex: number;
421
+ readonly depth: number;
422
+ }
423
+ /** @public */
424
+ type PretableGroupRow<TColumns> = { readonly [TColumnId in ColumnIdOf<TColumns>]: {
425
+ readonly kind: "group";
426
+ readonly groupId: PretableGroupId;
427
+ readonly depth: number;
428
+ readonly columnId: TColumnId;
429
+ readonly value: ColumnValueOf<TColumns, TColumnId>;
430
+ readonly childCount: number;
431
+ readonly aggregates: PretableAggregatesFor<TColumns>;
432
+ readonly expanded: boolean;
433
+ }; }[ColumnIdOf<TColumns>];
434
+ /** @public */
435
+ type PretableVisibleRow<TRow extends object, TRowId extends PretableRowId, TColumns> = PretableDataRow<TRow, TRowId> | PretableGroupRow<TColumns>;
436
+ /** @public */
437
+ type PretableExpansionDefault = {
438
+ readonly kind: "collapsed";
439
+ } | {
440
+ readonly kind: "expanded";
441
+ } | {
442
+ readonly kind: "through-depth";
443
+ readonly depth: number;
444
+ };
445
+ /** @public */
446
+ interface PretableExpansionState {
447
+ readonly default: PretableExpansionDefault;
448
+ readonly overrideCount: number;
449
+ }
450
+ /** @public */
451
+ interface PretableRowModelSnapshot<TRow extends object, TRowId extends PretableRowId, TColumns> {
452
+ readonly revision: number;
453
+ readonly sourceRowCount: number;
454
+ readonly visibleRowCount: number;
455
+ readonly visibleDataRowCount: number;
456
+ rowAt(index: number): PretableVisibleRow<TRow, TRowId, TColumns> | undefined;
457
+ /**
458
+ * Returns the half-open visible-row interval `[start, end)`. Both bounds are
459
+ * clamped to `[0, visibleRowCount]`.
460
+ */
461
+ range(start: number, end: number): readonly PretableVisibleRow<TRow, TRowId, TColumns>[];
462
+ /** Returns the visible rank of `ref`, or `-1` when it is absent. */
463
+ indexOf(ref: PretableVisibleRowRef<TRowId>): number;
464
+ /** Returns the data-only rank of `ref`, or `-1` when it is absent. */
465
+ dataIndexOf(ref: PretableVisibleRowRef<TRowId>): number;
466
+ /**
467
+ * Returns the data row at a data-only rank. Group rows do not consume an
468
+ * index; an out-of-bounds rank returns `undefined`.
469
+ */
470
+ dataRowAt(index: number): PretableDataRow<TRow, TRowId> | undefined;
471
+ /** Returns the first visible data row, or `undefined` when none is visible. */
472
+ firstDataRow(): PretableDataRow<TRow, TRowId> | undefined;
473
+ /** Returns the last visible data row, or `undefined` when none is visible. */
474
+ lastDataRow(): PretableDataRow<TRow, TRowId> | undefined;
475
+ /**
476
+ * Returns the next visible data row after `ref`, skipping group rows, or
477
+ * `undefined` when `ref` is absent or has no following data row.
478
+ */
479
+ nextDataRow(ref: PretableVisibleRowRef<TRowId>): PretableDataRow<TRow, TRowId> | undefined;
480
+ /**
481
+ * Returns the previous visible data row before `ref`, skipping group rows,
482
+ * or `undefined` when `ref` is absent or has no preceding data row.
483
+ */
484
+ previousDataRow(ref: PretableVisibleRowRef<TRowId>): PretableDataRow<TRow, TRowId> | undefined;
485
+ /** Returns the immediate parent group of `ref`, if it has one. */
486
+ parentGroupOf(ref: PretableVisibleRowRef<TRowId>): PretableGroupRow<TColumns> | undefined;
487
+ /**
488
+ * Returns `ref` when visible, otherwise its nearest visible ancestor group;
489
+ * returns `undefined` when neither the ref nor a visible ancestor is known.
490
+ */
491
+ nearestVisibleRef(ref: PretableVisibleRowRef<TRowId>): PretableVisibleRowRef<TRowId> | undefined;
492
+ isGroupExpanded(groupId: PretableGroupId): boolean;
493
+ /**
494
+ * Slots of the visible rows in the half-open interval `[start, end)`, in
495
+ * visible order — the dense-identity seam for the renderer's layout
496
+ * source; aligns index-for-index with {@link range}. Flat roots only: on a
497
+ * flat root every visible entry is a data row bound to a slot. A grouped
498
+ * root returns `undefined` wholesale (group rows carry no slot) and the
499
+ * caller must fall back to string identities.
500
+ *
501
+ * A slot is the row's CURRENT model binding — it stays valid only while
502
+ * the model binds that slot to the same row (updates carry it; permanent
503
+ * removal releases it for reuse). Consumers own that currency.
504
+ *
505
+ * Optional at the type seam so structural snapshot wrappers stay valid;
506
+ * every model-produced snapshot implements it.
507
+ *
508
+ * @internal
509
+ */
510
+ ɵvisibleSlotRange?(start: number, end: number): readonly number[] | undefined;
511
+ /**
512
+ * Slot currently bound to `rowId`, or `undefined` when the id is unknown
513
+ * or the root is grouped. One row-store lookup — for k-sized paths only
514
+ * (op stamping): never call this per visible row; use
515
+ * `ɵvisibleSlotRange` for the bulk walk.
516
+ *
517
+ * @internal
518
+ */
519
+ ɵslotOfRowId?(rowId: TRowId): number | undefined;
520
+ /**
521
+ * The slot-space size this root's slot-indexed structures were built for
522
+ * (every bound slot is `< ɵslotCapacity()`), or `undefined` on a grouped
523
+ * root — same fallback contract as `ɵvisibleSlotRange`.
524
+ *
525
+ * @internal
526
+ */
527
+ ɵslotCapacity?(): number | undefined;
528
+ readonly query: Readonly<PretableQueryFor<TColumns>>;
529
+ readonly expansion: Readonly<PretableExpansionState>;
530
+ }
531
+ /** @public */
532
+ type PretableRowModelStatus = {
533
+ readonly kind: "ready";
534
+ } | {
535
+ readonly kind: "rebuilding";
536
+ readonly transitionId: number;
537
+ readonly completedRows: number;
538
+ readonly totalRows: number;
539
+ } | {
540
+ readonly kind: "error";
541
+ readonly transitionId: number;
542
+ readonly error: PretableRowModelError;
543
+ } | {
544
+ readonly kind: "disposed";
545
+ };
546
+ /** @public */
547
+ interface PretableRowModelState<TRow extends object, TRowId extends PretableRowId, TColumns> {
548
+ readonly snapshot: PretableRowModelSnapshot<TRow, TRowId, TColumns>;
549
+ readonly status: PretableRowModelStatus;
550
+ }
551
+ /** @public */
552
+ interface PretableRowUpdate<TRow extends object, TRowId extends PretableRowId> {
553
+ readonly id: TRowId;
554
+ /**
555
+ * An enumerable-own-data-property patch for an ordinary object or
556
+ * null-prototype record. Class instances, arrays, built-in exotic objects,
557
+ * and proxies are not valid partial-update targets because cloning them
558
+ * would lose private state or observable behavior. Replace those values
559
+ * atomically with `setRows` instead. Development builds enforce this for
560
+ * rows that cannot be verified and frozen; production trusts this contract
561
+ * without reflection or proxy detection.
562
+ */
563
+ readonly changes: Partial<TRow>;
564
+ }
565
+ /** @public */
566
+ interface PretableTransaction<TRow extends object, TRowId extends PretableRowId> {
567
+ readonly add?: readonly TRow[];
568
+ readonly update?: readonly PretableRowUpdate<TRow, TRowId>[];
569
+ readonly remove?: readonly TRowId[];
570
+ }
571
+ /** @public */
572
+ type PretableMutationIssue<TRowId extends PretableRowId> = {
573
+ readonly code: "unknown-update-id";
574
+ readonly rowId: TRowId;
575
+ } | {
576
+ readonly code: "unknown-remove-id";
577
+ readonly rowId: TRowId;
578
+ } | {
579
+ readonly code: "unknown-group-id";
580
+ readonly groupId: PretableGroupId;
581
+ };
582
+ /** @public */
583
+ interface PretableMutationResult<TRowId extends PretableRowId> {
584
+ readonly previousRevision: number;
585
+ readonly revision: number;
586
+ readonly added: number;
587
+ readonly updated: number;
588
+ readonly removed: number;
589
+ readonly unchanged: number;
590
+ readonly ignored: number;
591
+ readonly issues: readonly PretableMutationIssue<TRowId>[];
592
+ }
593
+ /** @public */
594
+ interface PretableQueryTransition<TColumns> {
595
+ readonly id: number;
596
+ readonly requestedQuery: Readonly<PretableQueryFor<TColumns>>;
597
+ readonly finished: Promise<number>;
598
+ cancel(): void;
599
+ }
600
+ /** @public */
601
+ interface PretableDerivationTransition<TColumns> {
602
+ readonly id: number;
603
+ readonly requestedDerivations: Readonly<PretableDerivationsFor<TColumns>>;
604
+ readonly finished: Promise<number>;
605
+ cancel(): void;
606
+ }
607
+ /** @public */
608
+ type PretableVisibleRowField = "row" | "depth" | "expanded" | "childCount" | "aggregates";
609
+ /** @public */
610
+ type PretableChangeOperation<TRowId extends PretableRowId> = {
611
+ readonly kind: "insert";
612
+ readonly ref: PretableVisibleRowRef<TRowId>;
613
+ readonly index: number;
614
+ } | {
615
+ readonly kind: "remove";
616
+ readonly ref: PretableVisibleRowRef<TRowId>;
617
+ readonly previousIndex: number;
618
+ } | {
619
+ readonly kind: "move";
620
+ readonly ref: PretableVisibleRowRef<TRowId>;
621
+ readonly previousIndex: number;
622
+ readonly index: number;
623
+ } | {
624
+ readonly kind: "update";
625
+ readonly ref: PretableVisibleRowRef<TRowId>;
626
+ readonly index: number;
627
+ readonly fields: readonly PretableVisibleRowField[];
628
+ };
629
+ /** @public */
630
+ interface PretableChangeSet<TRowId extends PretableRowId> {
631
+ /** The snapshot revision to which the first operation applies. */
632
+ readonly previousRevision: number;
633
+ /** The atomically published revision produced by the complete operation list. */
634
+ readonly revision: number;
635
+ /**
636
+ * Applies sequentially: every index is measured after the preceding
637
+ * operation in this list. Row data and group fields are read from the
638
+ * snapshot at `revision`; operations never expose mutable row-model roots.
639
+ */
640
+ readonly operations: readonly PretableChangeOperation<TRowId>[];
641
+ }
642
+ /** @public */
643
+ type PretableChangeSequence<TRowId extends PretableRowId> = {
644
+ readonly kind: "changes";
645
+ readonly fromRevision: number;
646
+ readonly toRevision: number;
647
+ readonly changes: readonly PretableChangeSet<TRowId>[];
648
+ } | {
649
+ readonly kind: "reset";
650
+ readonly toRevision: number;
651
+ /**
652
+ * `"reorder"` asserts the visible row set and every row's content are
653
+ * unchanged — only the order moved (a sort-only commit). `"refilter"`
654
+ * asserts the opposite: membership changed (rows entered or left)
655
+ * while surviving rows kept their relative order and identities (a
656
+ * filter-only commit). Every other reason makes no such promise;
657
+ * consumers that do not understand `"reorder"` or `"refilter"` may
658
+ * treat either exactly like `"bulk-replace"`.
659
+ */
660
+ readonly reason: "unknown-revision" | "journal-evicted" | "bulk-replace" | "reorder" | "refilter";
661
+ };
662
+ /** @public */
663
+ interface PretableDistinctValueOptions {
664
+ readonly search?: string;
665
+ readonly start?: number;
666
+ readonly limit?: number;
667
+ readonly population?: "all" | "filtered";
668
+ /** Includes nullish, NaN, and trim-empty string values. Defaults to false. */
669
+ readonly includeBlanks?: boolean;
670
+ /** Places included blank values before or after non-blank values. */
671
+ readonly blankOrder?: "first" | "last";
672
+ }
673
+ /** @public */
674
+ interface PretableDistinctValueResult<TValue> {
675
+ readonly values: readonly {
676
+ /** Numeric zero uses SameValueZero identity and is returned as positive zero. */
677
+ readonly value: TValue;
678
+ readonly count: number;
679
+ }[];
680
+ readonly totalDistinct: number;
681
+ readonly population: "all" | "filtered";
682
+ readonly rowModelRevision: number;
683
+ }
684
+ /** @public */
685
+ interface PretableDistinctValueQuery<TValue> {
686
+ readonly status: "pending" | "ready" | "error" | "cancelled";
687
+ readonly finished: Promise<PretableDistinctValueResult<TValue>>;
688
+ cancel(): void;
689
+ }
690
+ /**
691
+ * Column IDs whose complete inferred value type has stable local identity.
692
+ * @public
693
+ */
694
+ type PretableDistinctColumnIdOf<TColumns> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
695
+ readonly id: infer TColumnId extends string;
696
+ readonly accessor: (...args: never[]) => infer TValue;
697
+ } ? [TValue] extends [string | number | bigint | boolean | Date | null | undefined] ? [TValue] extends [never] ? never : TColumnId : never : never : never;
698
+ /** @public */
699
+ interface PretableRowModel<TRow extends object, TRowId extends PretableRowId, TColumns> {
700
+ readonly ["~pretableRowModel"]: {
701
+ readonly row: TRow;
702
+ readonly rowId: TRowId;
703
+ readonly columns: TColumns;
704
+ };
705
+ getState(): PretableRowModelState<TRow, TRowId, TColumns>;
706
+ /**
707
+ * Returns the immutable original schema/presentation tuple supplied when
708
+ * this model was created. `setDerivations` replaces engine behavior only;
709
+ * it never changes this presentation fallback or its identity.
710
+ */
711
+ getColumns(): TColumns;
712
+ subscribe(listener: () => void): () => void;
713
+ setRows(rows: readonly TRow[]): PretableMutationResult<TRowId>;
714
+ /**
715
+ * Applies one atomic batch. Partial updates require ordinary or
716
+ * null-prototype row records; use `setRows` to replace proxy, class, array,
717
+ * or other exotic row values.
718
+ */
719
+ applyTransaction(transaction: PretableTransaction<TRow, TRowId>): PretableMutationResult<TRowId>;
720
+ setQuery(query: PretableQueryFor<TColumns>): PretableQueryTransition<TColumns>;
721
+ setDerivations(derivations: PretableDerivationsFor<TColumns>): PretableDerivationTransition<TColumns>;
722
+ setGroupExpanded(groupId: PretableGroupId, expanded: boolean): PretableMutationResult<TRowId>;
723
+ setExpansionDefault(policy: PretableExpansionDefault, options?: {
724
+ readonly preserveOverrides?: boolean;
725
+ }): PretableMutationResult<TRowId>;
726
+ expandAll(): PretableMutationResult<TRowId>;
727
+ collapseAll(): PretableMutationResult<TRowId>;
728
+ /**
729
+ * Returns a retained contiguous sequence through the current revision, or a
730
+ * reset instruction when replay is no longer possible. The current revision
731
+ * always returns an empty `changes` sequence.
732
+ */
733
+ changesSince(revision: number): PretableChangeSequence<TRowId>;
734
+ distinctValues<TColumnId extends PretableDistinctColumnIdOf<TColumns>>(columnId: TColumnId, options?: PretableDistinctValueOptions): PretableDistinctValueQuery<ColumnValueOf<TColumns, TColumnId>>;
735
+ dispose(): void;
736
+ }
737
+ /** @public */
738
+ type RowOf<TModel> = TModel extends {
739
+ readonly ["~pretableRowModel"]: {
740
+ readonly row: infer TRow extends object;
741
+ };
742
+ } ? TRow : never;
743
+ /** @public */
744
+ type RowIdOf<TModel> = TModel extends {
745
+ readonly ["~pretableRowModel"]: {
746
+ readonly rowId: infer TRowId extends PretableRowId;
747
+ };
748
+ } ? TRowId : never;
749
+ /** @public */
750
+ type ColumnsOf<TModel> = TModel extends {
751
+ readonly ["~pretableRowModel"]: {
752
+ readonly columns: infer TColumns;
753
+ };
754
+ } ? TColumns : never;
755
+ //#endregion
756
+ //#region ../row-model/dist/create-local-row-model.d.ts
757
+ /**
758
+ * Re-declares who selected the loaded records, recompiling the plan when the
759
+ * answer changes. Deliberately a registry lookup rather than a method on
760
+ * `PretableRowModel`: only the rows-mode React surface needs it — a consumer
761
+ * who builds their own model already decides what goes into the query — and
762
+ * the public model interface should not grow a knob that boundary excludes.
763
+ *
764
+ * Silently ignores any model this module did not create. Callers must still
765
+ * withhold it from models they do not own — a consumer-supplied model built by
766
+ * `createLocalRowModel` is registered here too, and moving its authority would
767
+ * be exactly the explicit-model change this design excludes.
768
+ *
769
+ * @internal
770
+ */
771
+ declare function ɵsetLocalRowModelFilterAuthority(model: object, authority: "engine" | "external"): void;
772
+ /**
773
+ * Re-declares who ordered the loaded records. The sort twin of
774
+ * `ɵsetLocalRowModelFilterAuthority`, with the same registry design and
775
+ * the same ownership rule: withhold it from models the surface does not own.
776
+ *
777
+ * @internal
778
+ */
779
+ declare function ɵsetLocalRowModelSortAuthority(model: object, authority: "engine" | "external"): void;
780
+ //#endregion
781
+ //#region ../row-model/dist/aggregate-overrides.d.ts
782
+ /**
783
+ * Per-column aggregate OVERRIDES, applied to a derivation list.
784
+ *
785
+ * grid-core stores what a tool panel chose (`PretableGridUiState`'s
786
+ * `columnAggregates`); row-model resolves what an aggregate MEANS. Both layers
787
+ * CAN see both halves — `createGridUiCore` takes a `rowModel` and that
788
+ * interface exposes `setDerivations` — so this is a layering choice, not an
789
+ * impossibility: row-model must not depend on grid-core's state shape, and
790
+ * grid-core deliberately drives no derivations at all (it never calls
791
+ * `setDerivations`). The merge is therefore a pure function that a composing
792
+ * layer calls with both inputs, and the merged list travels the ordinary
793
+ * `setDerivations` / `compileQuery` path from there.
794
+ */
795
+ /**
796
+ * Aggregate overrides keyed by column id, as a plain lookup.
797
+ *
798
+ * Values are `unknown` because grid-core stores an aggregate without
799
+ * interpreting one; validation happens where every other aggregate is
800
+ * validated, when the merged derivations are compiled. An unknown builtin name
801
+ * or a malformed aggregator object throws `CompiledQueryValidationError`
802
+ * there, exactly as a bad declared `aggregate` does.
803
+ *
804
+ * @public
805
+ */
806
+ type PretableColumnAggregateOverrides = Readonly<Record<string, unknown>>;
807
+ /**
808
+ * Apply `overrides` on top of the `aggregate` each derivation declares.
809
+ *
810
+ * IDS ARE THE SCHEMA VOCABULARY — the `id` on the derivations themselves, the
811
+ * same ids `PretableQueryFor` and `RuntimeColumn` use. grid-core keys
812
+ * `columnAggregates` by the LAYOUT column vocabulary instead (see its doc on
813
+ * `PretableGridUiState.columnAggregates`), so a caller reading that state owes
814
+ * the translation before calling this. Nothing in the signature enforces that:
815
+ * both vocabularies are `string`, so the fence is this sentence.
816
+ *
817
+ * An override LAYER, not a replacement: a derivation whose id is absent from
818
+ * `overrides` keeps whatever it declared, so clearing an override — which
819
+ * strips the key rather than storing `undefined` — restores the declared
820
+ * value. A key carrying `undefined` is likewise treated as no override, so
821
+ * `undefined` never acquires a second meaning here. `null` is the value that
822
+ * says "draw NO aggregate for a column whose prop declares one": the merge
823
+ * strips the declared `aggregate` from that derivation, so `compileQuery`
824
+ * never sees the sentinel and validates nothing new.
825
+ *
826
+ * An override for an id no derivation carries is ignored, never appended: this
827
+ * function only ever rewrites the `aggregate` of derivations it was given, and
828
+ * preserves their order, so a merged list stays positionally comparable with
829
+ * the one it came from — which is what `derivationsEqualForPlan` needs to
830
+ * decide plan reuse.
831
+ *
832
+ * TYPES DESCRIBE THE DECLARED SHAPE, NOT THE MERGED ONE. An override arrives
833
+ * as `unknown`, so the returned list keeps the input's type: a column that
834
+ * declared no `aggregate` but carries an override aggregates at runtime while
835
+ * its type still says it does not, and an override of a different output type
836
+ * is invisible to `PretableAggregatesFor`. The alternative — inferring a new
837
+ * derivation type per override — cannot work off state grid-core stores as
838
+ * `unknown`.
839
+ *
840
+ * IDENTITY: returns the INPUT ARRAY ITSELF when nothing applies, so a caller
841
+ * memoising on identity (React) does not re-request derivations every render;
842
+ * that covers a restated override too, since an override `Object.is`-equal to
843
+ * the declared value changes nothing. It is NOT idempotent on the applying
844
+ * path: two calls with equal inputs return two DISTINCT arrays whenever any
845
+ * override actually applies. A React caller must therefore `useMemo` the merge
846
+ * on `[derivations, overrides]` and hold the MERGED array as its
847
+ * last-requested value, rather than calling this inline inside the effect that
848
+ * compares against it — otherwise every render looks like a change and pays a
849
+ * `compileQuery` before concluding no-op. That memo is sound because
850
+ * grid-core's `columnAggregates` object identity is stable across publishes
851
+ * that do not touch it.
852
+ *
853
+ * @public
854
+ */
855
+ declare function mergeColumnAggregateOverrides<TDerivations extends readonly {
856
+ readonly id: string;
857
+ }[]>(derivations: TDerivations, overrides: PretableColumnAggregateOverrides): TDerivations;
858
+ //#endregion
859
+ //#region ../grid-core/dist/types.d.ts
860
+ /**
861
+ * Base row constraint. Concrete row shapes remain fully generic.
862
+ *
863
+ * @public
864
+ */
865
+ type PretableRow = object;
866
+ /**
867
+ * Sort direction — `null` means unsorted.
868
+ *
869
+ * @public
870
+ */
871
+ type PretableSortDirection = "asc" | "desc" | null;
872
+ /**
873
+ * Phase of a cell edit that is already OPEN — i.e. every phase except
874
+ * `"checking"`, which is the pre-authorization phase only `beginEdit` can
875
+ * enter and which nothing can return to.
876
+ *
877
+ * This union had no name and was spelled out in four places. It is written as
878
+ * literals rather than `Exclude<PretableEditStatus, "checking">` for two
879
+ * reasons: an `Exclude` whose second argument stops naming a member silently
880
+ * widens to the whole union instead of failing, and the docs guard can only
881
+ * pin a table to a union whose members the API report states outright.
882
+ *
883
+ * The cost is that the two unions could drift, so they are held together by
884
+ * assertion instead of by construction — see the `toEqualTypeOf` pair in
885
+ * `packages/react/src/__tests__/narrowed-literal-unions.test.ts`, which fails
886
+ * if either list changes without the other.
887
+ *
888
+ * @public
889
+ */
890
+ type PretableOpenEditStatus = "editing" | "validating" | "saving" | "error";
891
+ /**
892
+ * Phase of an in-progress cell edit.
893
+ *
894
+ * `"checking"` is the pre-authorization phase an async `editable` predicate
895
+ * runs under; the rest are {@link PretableOpenEditStatus}.
896
+ *
897
+ * @public
898
+ */
899
+ type PretableEditStatus = "checking" | "editing" | "validating" | "saving" | "error";
900
+ /**
901
+ * Input passed to a column's edit hooks (`editable`, `validate`, `parseEditValue`,
902
+ * `formatEditValue`).
903
+ *
904
+ * @public
905
+ */
906
+ interface PretableEditInput<TRow extends PretableRow = PretableRow> {
907
+ rowId: string;
908
+ columnId: string;
909
+ row: TRow;
910
+ column: PretableColumn<TRow>;
911
+ value: unknown;
912
+ }
913
+ /**
914
+ * In-progress cell edit observed through the UI grid state.
915
+ * `error` carries the validation message (status `"editing"`) or the commit
916
+ * failure message (status `"error"`).
917
+ *
918
+ * @public
919
+ */
920
+ interface PretableEditState {
921
+ rowId: string;
922
+ columnId: string;
923
+ draft: unknown;
924
+ status: PretableEditStatus;
925
+ error?: string;
926
+ }
927
+ /** @public */
928
+ type ColumnType = "text" | "number" | "date" | "enum" | "boolean";
929
+ /** @public */
930
+ type ColumnAlign = "start" | "center" | "end";
931
+ /** @public */
932
+ type FilterOperator = "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith" | "gt" | "gte" | "lt" | "lte" | "between" | "isAnyOf" | "isNoneOf" | "on" | "before" | "after" | "dateBetween" | "isEmpty" | "isNotEmpty";
933
+ /** @public */
934
+ type FilterValue = string | number | readonly [number, number] | readonly [string, string] | readonly string[] | null;
935
+ /** @public — one column's active filter. `value` is omitted for isEmpty/isNotEmpty. */
936
+ interface ColumnFilter {
937
+ operator: FilterOperator;
938
+ value?: FilterValue;
939
+ }
940
+ /** @public */
941
+ interface ColumnOption {
942
+ value: string;
943
+ label?: string;
944
+ }
945
+ /**
946
+ * Engine-level column definition. `@pretable/react` extends this with React-specific render fields.
947
+ *
948
+ * @public
949
+ */
950
+ interface PretableColumn<TRow extends PretableRow = PretableRow> {
951
+ id: string;
952
+ header?: string;
953
+ wrap?: boolean;
954
+ widthPx?: number;
955
+ pinned?: "left" | "right";
956
+ sortable?: boolean;
957
+ /** Number-editor increment for ArrowUp/Down and steppers. Default 1. */
958
+ step?: number;
959
+ filterable?: boolean;
960
+ /** Restrict the filter menu to operators the current processor can honor. */
961
+ filterOperators?: FilterOperator[];
962
+ type?: ColumnType;
963
+ /** Horizontal alignment. Number columns default to `"end"`. */
964
+ align?: ColumnAlign;
965
+ options?: ColumnOption[];
966
+ value?: (row: TRow) => unknown;
967
+ format?: (input: PretableFormatInput<TRow, unknown, PretableColumn<TRow>>) => string;
968
+ /** Native number presentation; derivation and editing continue to use raw values. */
969
+ numberFormat?: Intl.NumberFormatOptions;
970
+ /**
971
+ * Render this column's aggregate on a group row.
972
+ *
973
+ * Deliberately not `format`: the plain-cell formatter's `row` is non-optional, so
974
+ * every consumer formatter is entitled to dereference it, and a group row has
975
+ * no row. Columns without `formatAggregate` fall back to the same default
976
+ * stringification a plain cell uses.
977
+ */
978
+ formatAggregate?: (input: {
979
+ value: unknown;
980
+ column: PretableColumn<TRow>;
981
+ group: {
982
+ readonly id: string;
983
+ readonly groupId: string;
984
+ readonly depth: number;
985
+ readonly columnId: string;
986
+ readonly value: unknown;
987
+ readonly childCount: number;
988
+ readonly aggregates: Readonly<Record<string, unknown>>;
989
+ readonly expanded: boolean;
990
+ };
991
+ /** Whether the aggregate covers the full result or only loaded rows. */
992
+ scope: "all" | "loaded";
993
+ }) => string;
994
+ minWidthPx?: number;
995
+ maxWidthPx?: number;
996
+ /**
997
+ * Share of the width the fixed columns leave over, so the row ends exactly at
998
+ * the viewport edge instead of underfilling or overflowing it. Weights are
999
+ * relative: two columns at `flex: 1` split the remainder evenly, `1` and `3`
1000
+ * split it a quarter to three quarters. `minWidthPx`/`maxWidthPx` still
1001
+ * apply, and a column that has been resized (which sets `widthPx`) stops
1002
+ * flexing — an explicit width outranks a computed one.
1003
+ */
1004
+ flex?: number;
1005
+ resizable?: boolean;
1006
+ reorderable?: boolean;
1007
+ /** Aggregate shown for this column on group rows. */
1008
+ aggregate?: unknown;
1009
+ editable?: boolean | ((input: PretableEditInput<TRow>) => boolean | Promise<boolean>);
1010
+ validate?: (value: unknown, input: PretableEditInput<TRow>) => (true | string) | Promise<true | string>;
1011
+ parseEditValue?: (raw: string, input: PretableEditInput<TRow>) => unknown;
1012
+ formatEditValue?: (value: unknown, input: PretableEditInput<TRow>) => string;
1013
+ }
1014
+ /** Who applies a query slice to the loaded rows. @public */
1015
+ type PretableProcessingAuthority = "engine" | "external";
1016
+ /** Per-slice processing authority for remotely fulfilled queries. @public */
1017
+ interface PretableProcessingOptions {
1018
+ filter?: PretableProcessingAuthority;
1019
+ sort?: PretableProcessingAuthority;
1020
+ }
1021
+ /** Population size represented by a loaded result window. @public */
1022
+ type PretableMatchingTotal = {
1023
+ kind: "exact";
1024
+ count: number;
1025
+ } | {
1026
+ kind: "estimate";
1027
+ count: number;
1028
+ } | {
1029
+ kind: "unknown";
1030
+ atLeast?: number;
1031
+ };
1032
+ /** Metadata accompanying a remotely fulfilled result window. @public */
1033
+ interface PretableResultMeta {
1034
+ total?: PretableMatchingTotal;
1035
+ /** Stable identity for the query/result population represented by the rows. */
1036
+ datasetKey?: string;
1037
+ /**
1038
+ * Where the loaded rows sit inside the population, when they are a window
1039
+ * rather than a prefix. Absent means the classic prefix case.
1040
+ *
1041
+ * `hasMore` rather than a remaining count: a keyset cursor walks forward, so
1042
+ * the extent must promise only what is fetchable. A count would invite a
1043
+ * scrollbar that reaches rows the cursor cannot serve.
1044
+ */
1045
+ window?: {
1046
+ /** Dataset index of `rows[0]`. */
1047
+ readonly start: number;
1048
+ /** Whether anything follows this window. NOT how much. */
1049
+ readonly hasMore: boolean;
1050
+ };
1051
+ }
1052
+ /**
1053
+ * One entry in the ordered sort list; index in the list = priority.
1054
+ *
1055
+ * @public
1056
+ */
1057
+ interface PretableSortEntry {
1058
+ columnId: string;
1059
+ direction: "asc" | "desc";
1060
+ }
1061
+ /**
1062
+ * Cell address — the (rowId, columnId) pair that uniquely identifies a cell.
1063
+ *
1064
+ * @public
1065
+ */
1066
+ interface PretableCellAddress {
1067
+ rowId: string;
1068
+ columnId: string;
1069
+ }
1070
+ /**
1071
+ * Inclusive cell range — both bounds (start and end) are inside the selection.
1072
+ *
1073
+ * @public
1074
+ */
1075
+ interface PretableCellRange {
1076
+ startRowId: string;
1077
+ endRowId: string;
1078
+ startColumnId: string;
1079
+ endColumnId: string;
1080
+ /**
1081
+ * Dataset positions of this range's endpoints, when the grid is serving a
1082
+ * window under the honesty gate — see
1083
+ * {@link PretableIndexedDatasetRowSpan}. Present on every range the grid
1084
+ * emits through `onSelectionChange`, and accepted back through the
1085
+ * controlled `state.selection` prop so a selection that is persisted and
1086
+ * restored stays countable while its rows are evicted. Omitting it on the
1087
+ * way back in is safe: the engine recovers the positions by row id from
1088
+ * the selection it is replacing.
1089
+ */
1090
+ datasetRowSpan?: PretableIndexedDatasetRowSpan;
1091
+ }
1092
+ /**
1093
+ * Cell-range selection state including the optional anchor for shift-extension.
1094
+ *
1095
+ * @public
1096
+ */
1097
+ interface PretableSelectionState {
1098
+ ranges: PretableCellRange[];
1099
+ anchor: PretableCellAddress | null;
1100
+ }
1101
+ /**
1102
+ * Currently focused cell — both fields are null when nothing is focused.
1103
+ *
1104
+ * @public
1105
+ */
1106
+ interface PretableFocusState {
1107
+ rowId: string | null;
1108
+ columnId: string | null;
1109
+ }
1110
+ /**
1111
+ * Viewport-level scroll + size state.
1112
+ *
1113
+ * @public
1114
+ */
1115
+ interface PretableViewportState {
1116
+ scrollTop: number;
1117
+ scrollLeft: number;
1118
+ height: number;
1119
+ width: number;
1120
+ }
1121
+ /**
1122
+ * Direction passed to the UI grid's focus movement action.
1123
+ *
1124
+ * @public
1125
+ */
1126
+ type PretableFocusDirection = "up" | "down" | "left" | "right";
1127
+ /**
1128
+ * Optional behavior modifiers for UI-grid focus movement.
1129
+ *
1130
+ * @public
1131
+ */
1132
+ interface PretableMoveFocusOptions {
1133
+ extend?: boolean;
1134
+ jumpToEdge?: boolean;
1135
+ byPage?: boolean;
1136
+ /**
1137
+ * How many rows `byPage` steps. Only the surface knows: the step is a
1138
+ * screen's worth of the BODY viewport, which the engine cannot measure.
1139
+ * Omitted, the engine falls back to its own constant.
1140
+ */
1141
+ pageRows?: number;
1142
+ }
1143
+ /** A typed data-cell address owned by the indexed UI layer. @public */
1144
+ interface PretableIndexedCellAddress<TRowId extends PretableRowId, TColumnId extends string> {
1145
+ readonly rowId: TRowId;
1146
+ readonly columnId: TColumnId;
1147
+ }
1148
+ /**
1149
+ * Where a cell range's two endpoints sit in the DATASET — the coordinate
1150
+ * system `PretableIndexedSelectionWindow` is expressed in, not snapshot
1151
+ * indices, which shift under the loaded window every time it moves.
1152
+ *
1153
+ * Under the honesty gate this is the range's IDENTITY, not an annotation on
1154
+ * it: a range named by row ids stops meaning anything once those rows are
1155
+ * evicted, because an id cannot be resolved to a position without the row.
1156
+ * A dataset position survives the row. So `end - start + 1` stays answerable
1157
+ * with nothing loaded, and so does "is this rendered row inside it?".
1158
+ *
1159
+ * `start`/`end` mirror the range's own `start`/`end` endpoints and are NOT
1160
+ * normalized — `start` may exceed `end` for a range dragged upwards. Count
1161
+ * and containment order them; keeping the orientation is what lets a range
1162
+ * with one evicted endpoint resolve the survivor live and the absentee from
1163
+ * memory, instead of guessing which remembered bound belongs to which.
1164
+ *
1165
+ * @public
1166
+ */
1167
+ interface PretableIndexedDatasetRowSpan {
1168
+ /** Dataset position of the range's `start` endpoint. */
1169
+ readonly start: number;
1170
+ /** Dataset position of the range's `end` endpoint. */
1171
+ readonly end: number;
1172
+ /**
1173
+ * The population these positions were measured in — `resultMeta.datasetKey`
1174
+ * as of the measurement. A re-sort or a filter change re-fills the same
1175
+ * dataset positions with different rows, so a span carrying a different key
1176
+ * than the window currently reports is not stale-but-usable, it is about a
1177
+ * different table. Count and containment both refuse it rather than
1178
+ * answering from it: `indexedRangeContainsCell` returns a bare boolean and
1179
+ * has no `verified` channel to downgrade through, and a wrong `true` there
1180
+ * paints the wrong rows.
1181
+ *
1182
+ * **This is load-bearing, and it fails CLOSED.** An absent key is not a
1183
+ * match — it is the absence of any evidence about the population, which
1184
+ * leaves the engine unable to tell a scroll from a re-sort, so it refuses.
1185
+ * A grid that publishes `resultMeta.window` but no `resultMeta.datasetKey`
1186
+ * therefore gets no span at all: its selections degrade to the loaded
1187
+ * window, visibly, in `rowCount` and `verified`. `@pretable/react` warns
1188
+ * once when it sees that combination.
1189
+ *
1190
+ * Local mode is a different case and is genuinely unaffected: with no
1191
+ * window there are no dataset positions to record, so there is nothing a
1192
+ * key could qualify.
1193
+ */
1194
+ readonly datasetKey?: string;
1195
+ /**
1196
+ * How many rows the population held when these positions were measured —
1197
+ * `resultMeta.total.count`, which the honesty gate already forces to be
1198
+ * EXACT before any of this is reachable.
1199
+ *
1200
+ * `datasetKey` identifies the QUERY, not the population, and the docs tell
1201
+ * consumers to keep it stable while they page within one result. So an
1202
+ * insert or a delete made by somebody else, upstream of an evicted
1203
+ * selection, leaves the key matching while re-filling the remembered
1204
+ * positions with different rows. Measured: a selection of `row-1..row-8`
1205
+ * evicted, five rows prepended to the same result, and the returning window
1206
+ * painted four rows that had not existed when the user selected — while the
1207
+ * rows they did select painted nothing.
1208
+ *
1209
+ * The count is the cheapest thing that changes on any NET population
1210
+ * change, and it is already required to be exact, so it costs the consumer
1211
+ * nothing. It fails CLOSED for the same reason `datasetKey` does: an absent
1212
+ * count is not agreement, it is the absence of evidence.
1213
+ *
1214
+ * **What it does not catch:** a change that leaves the size alone — an
1215
+ * insert and a delete in the same revision, or a row replaced in place.
1216
+ * Containment still answers from the remembered span there, and the summary
1217
+ * still reports `verified: false`, which is all the engine can say. Closing
1218
+ * that gap needs a population token only the consumer can mint; see
1219
+ * `docs/content/server-side-data/eviction.mdx`.
1220
+ */
1221
+ readonly datasetTotal?: number;
1222
+ }
1223
+ /** Inclusive data-cell range; group rows can never be endpoints. @public */
1224
+ interface PretableIndexedCellRange<TRowId extends PretableRowId, TColumnId extends string> {
1225
+ readonly start: PretableIndexedCellAddress<TRowId, TColumnId>;
1226
+ readonly end: PretableIndexedCellAddress<TRowId, TColumnId>;
1227
+ /**
1228
+ * Where `start` and `end` sit in the dataset. Absent in local mode and
1229
+ * outside the honesty gate, where dataset positions are meaningless and
1230
+ * every endpoint is loaded anyway.
1231
+ *
1232
+ * Derived by the engine on every write — `setSelection` fills it in from
1233
+ * the loaded snapshot, and from the positions the selection being replaced
1234
+ * already remembers, so a gesture extending from an EVICTED anchor still
1235
+ * produces a countable range. Reconciliation refreshes it. A consumer that
1236
+ * echoes a selection back through the controlled `state` prop may
1237
+ * round-trip it verbatim, but does not have to: dropping it costs nothing,
1238
+ * because the engine recovers it by row id from the selection it replaces.
1239
+ */
1240
+ readonly datasetRowSpan?: PretableIndexedDatasetRowSpan;
1241
+ }
1242
+ /** Inclusive data-row span stored by its stable endpoint IDs. @public */
1243
+ interface PretableIndexedRowRange<TRowId extends PretableRowId> {
1244
+ readonly startRowId: TRowId;
1245
+ readonly endRowId: TRowId;
1246
+ }
1247
+ /** Immutable normalized interval index for symbolic row selections. @public */
1248
+ interface PretableIndexedRowRangeIndex<TRowId extends PretableRowId> extends Iterable<PretableIndexedRowRange<TRowId>> {
1249
+ readonly size: number;
1250
+ }
1251
+ /** Sparse row-checkbox state. Select-all never materializes the data population. @public */
1252
+ type PretableIndexedRowSelection<TRowId extends PretableRowId> = {
1253
+ readonly kind: "explicit";
1254
+ readonly rowIds: ReadonlySet<TRowId>;
1255
+ readonly ranges?: PretableIndexedRowRangeIndex<TRowId>;
1256
+ readonly excludedRanges?: PretableIndexedRowRangeIndex<TRowId>;
1257
+ } | {
1258
+ readonly kind: "all";
1259
+ readonly excludedRanges?: PretableIndexedRowRangeIndex<TRowId>;
1260
+ };
1261
+ /**
1262
+ * The row-checkbox slice as a consumer WRITES it — the settable counterpart of
1263
+ * {@link PretableIndexedRowSelection}, which is what the engine holds.
1264
+ *
1265
+ * Same two cases and the same discriminant, because they describe the same
1266
+ * thing; only the containers differ. The engine stores a `ReadonlySet` and an
1267
+ * opaque normalized interval index, neither of which a consumer can build; this
1268
+ * shape takes plain arrays and the engine indexes them at the boundary.
1269
+ *
1270
+ * The sparseness survives that conversion, which is the point of not flattening
1271
+ * this to a list of ids:
1272
+ *
1273
+ * - `{ kind: "all" }` is symbolic. Applying it is O(1) whatever the row
1274
+ * count — it never enumerates the population, so select-all over a million
1275
+ * rows stays free.
1276
+ * - `ranges` carries a shift-checked span as its two endpoints, so a 100k-row
1277
+ * span costs two ids rather than 100k.
1278
+ * - `excludedRowIds` is POINTS, not spans, matching what the engine can
1279
+ * actually store: unticking one row out of a symbolic "all" records that
1280
+ * one row. A span-shaped exclusion would read as though it could untick a
1281
+ * range, which nothing here can do.
1282
+ *
1283
+ * @public
1284
+ */
1285
+ type PretableRowSelectionState<TRowId extends PretableRowId> = {
1286
+ readonly kind: "explicit";
1287
+ readonly rowIds: readonly TRowId[];
1288
+ readonly ranges?: readonly PretableIndexedRowRange<TRowId>[];
1289
+ readonly excludedRowIds?: readonly TRowId[];
1290
+ } | {
1291
+ readonly kind: "all";
1292
+ readonly excludedRowIds?: readonly TRowId[];
1293
+ };
1294
+ /** Data-only selection owned by the indexed UI layer. @public */
1295
+ interface PretableIndexedSelectionState<TRowId extends PretableRowId, TColumnId extends string> {
1296
+ readonly rows: PretableIndexedRowSelection<TRowId>;
1297
+ readonly ranges: readonly PretableIndexedCellRange<TRowId, TColumnId>[];
1298
+ readonly anchor: PretableIndexedCellAddress<TRowId, TColumnId> | null;
1299
+ }
1300
+ /**
1301
+ * Loaded span, in dataset-index terms, that `reconcileIndexedSelection` uses
1302
+ * to tell an evicted row (outside `[start, start + length)`) from a deleted
1303
+ * one (inside it) — see `resultMeta.window` on `PretableResultMeta`, which
1304
+ * this mirrors with `length` standing in for `rows.length`. `@internal`
1305
+ * rather than derived from `PretableResultMeta` directly: grid-core has no
1306
+ * dependency on the react-level honesty gate that decides whether a window
1307
+ * may be trusted, so callers pass this only once that gate has passed.
1308
+ *
1309
+ * @internal
1310
+ */
1311
+ interface PretableIndexedSelectionWindow {
1312
+ readonly start: number;
1313
+ readonly length: number;
1314
+ /**
1315
+ * `resultMeta.datasetKey` for the population this window is a slice of.
1316
+ * Carried here rather than on a channel of its own because a span is only
1317
+ * meaningful paired with the population it was measured in, and the two
1318
+ * must never be able to disagree — see
1319
+ * {@link PretableIndexedDatasetRowSpan.datasetKey}.
1320
+ *
1321
+ * Absent switches spans off entirely for this window: none are recorded and
1322
+ * none are read back. That is fail-closed by design, not an oversight.
1323
+ */
1324
+ readonly datasetKey?: string;
1325
+ /**
1326
+ * How many rows the population currently holds — `resultMeta.total.count`.
1327
+ * REQUIRED, not optional like `datasetKey`: the honesty gate that produces
1328
+ * this window already refuses to pass without an exact total, so a window
1329
+ * that cannot state its population size does not exist, and making the
1330
+ * field optional would only create a way to fail OPEN by omission. See
1331
+ * {@link PretableIndexedDatasetRowSpan.datasetTotal} for what comparing it
1332
+ * catches and what it does not.
1333
+ */
1334
+ readonly datasetTotal: number;
1335
+ }
1336
+ /**
1337
+ * What the presentation layer knows about the loaded window on one revision.
1338
+ *
1339
+ * A single object, read once, rather than a window getter beside a
1340
+ * windowed-ness getter: two reads at two instants can disagree, and the whole
1341
+ * of `create-grid-ui-core`'s `observed` pairing exists because that class of
1342
+ * skew has already cost this engine a permanently wrong span.
1343
+ *
1344
+ * `null` from the getter means the consumer is not windowed at all — local
1345
+ * mode. A non-null value with a null `window` means it IS windowed and this
1346
+ * revision's honesty gate did not pass. See
1347
+ * {@link PretableIndexedEvictionContext.windowed}.
1348
+ *
1349
+ * @internal
1350
+ */
1351
+ interface PretableIndexedWindowing {
1352
+ readonly window: PretableIndexedSelectionWindow | null;
1353
+ }
1354
+ /** Header-checkbox state derived without visiting every visible row. @public */
1355
+ interface PretableIndexedSelectionSummary {
1356
+ readonly state: "none" | "some" | "all";
1357
+ readonly selectedCount: number;
1358
+ readonly visibleCount: number;
1359
+ }
1360
+ /**
1361
+ * How many data rows the CELL-RANGE slice covers — `ranges`, the slice a
1362
+ * click/shift-click/marquee builds. Distinct from
1363
+ * {@link PretableIndexedSelectionSummary}, which counts the separate sparse
1364
+ * row-selection program behind the checkbox column; the two answer different
1365
+ * questions and neither is derived from the other.
1366
+ *
1367
+ * @public
1368
+ */
1369
+ interface PretableIndexedCellSelectionSummary {
1370
+ /**
1371
+ * Distinct data rows covered, counted by arithmetic over spans — O(ranges),
1372
+ * independent of how many rows are selected or how many are loaded.
1373
+ * Overlapping ranges are unioned, never double-counted.
1374
+ */
1375
+ readonly rowCount: number;
1376
+ /**
1377
+ * Whether every contributing range had both endpoints loaded, so
1378
+ * `rowCount` is a fact about rows that are provably still there.
1379
+ *
1380
+ * `false` means the count came wholly or partly from remembered dataset
1381
+ * positions: the rows are evicted, and a row deleted server-side while
1382
+ * evicted cannot be detected, so `rowCount` may overstate. It is still the
1383
+ * best available number — the loaded-rows-only alternative understates a
1384
+ * genuine selection by whatever fraction is evicted — but it may not be
1385
+ * presented as a proven one. Same rule as `PretableMatchingTotal`'s
1386
+ * `"exact" | "estimate"`: keep the number, qualify the claim, and let the
1387
+ * boundary that must speak a bare integer downgrade (see
1388
+ * `resolveAriaRowCount`).
1389
+ */
1390
+ readonly verified: boolean;
1391
+ }
1392
+ /**
1393
+ * The column-header strip as a focus target.
1394
+ *
1395
+ * Deliberately NOT a variant of `PretableVisibleRowRef`. That type is the row
1396
+ * model's own address space — `indexOf`, `nearestVisibleRef`, the row-height
1397
+ * index and the transaction draft all speak it — and the row model has no
1398
+ * header row to produce. Widening it there would force ~50 sites in
1399
+ * `@pretable-internal/row-model` and `@pretable-internal/renderer-dom` to
1400
+ * branch on a variant they can never see.
1401
+ *
1402
+ * The FOCUS ref is a different, wider space: a focus cursor addresses a cell,
1403
+ * and a header cell is a cell. Widening here is what makes the compiler demand
1404
+ * that every site handing `focus.ref` to a row-model API says what it does with
1405
+ * a header first — which is the whole point of the encoding.
1406
+ *
1407
+ * It carries no column: the column lives in `PretableIndexedFocusState.columnId`
1408
+ * exactly as it does for a data row. `{ref: null, columnId}` was ruled out by
1409
+ * measurement, not argument — `reconcileIndexedFocus` normalizes a null ref to
1410
+ * `emptyFocus()`, so it collapses to "no focus" on the first round trip.
1411
+ *
1412
+ * @public
1413
+ */
1414
+ interface PretableHeaderRowRef {
1415
+ readonly kind: "header";
1416
+ }
1417
+ /**
1418
+ * Everywhere the focus cursor can sit: any visible row, or the header strip.
1419
+ *
1420
+ * @public
1421
+ */
1422
+ type PretableIndexedFocusRef<TRowId extends PretableRowId> = PretableVisibleRowRef<TRowId> | PretableHeaderRowRef;
1423
+ /** Group rows, data rows and the header share one focus path while preserving runtime identity. @public */
1424
+ interface PretableIndexedFocusState<TRowId extends PretableRowId, TColumnId extends string> {
1425
+ readonly ref: PretableIndexedFocusRef<TRowId> | null;
1426
+ readonly columnId: TColumnId | null;
1427
+ }
1428
+ /**
1429
+ * Keyboard movements supported by indexed focus navigation.
1430
+ *
1431
+ * The four edge jumps come in two axes, and which axis a movement belongs to
1432
+ * is the whole reason they are named separately:
1433
+ *
1434
+ * - `"home"` / `"end"` are the VERTICAL edges — the first and last row of the
1435
+ * current column.
1436
+ * - `"first-column"` / `"last-column"` are the HORIZONTAL edges — the first
1437
+ * and last column of the current row.
1438
+ *
1439
+ * On the header, which is a single row, every edge is a column edge, so
1440
+ * `"home"` and `"end"` land on the first and last column there. That is the
1441
+ * one place the two axes coincide, and it is what made the distinction easy to
1442
+ * lose: `Cmd/Ctrl + Left` and `Cmd/Ctrl + Right` were both mapped onto
1443
+ * `"home"` / `"end"`, so on a data cell they jumped to the first and last ROW
1444
+ * while behaving correctly on the header.
1445
+ *
1446
+ * @public
1447
+ */
1448
+ type PretableIndexedFocusMovement = "up" | "down" | "left" | "right" | "page-up" | "page-down" | "home" | "end" | "first-column" | "last-column" | "tab" | "shift-tab" | "parent";
1449
+ /**
1450
+ * Optional modifiers for {@link PretableIndexedFocusMovement}.
1451
+ *
1452
+ * Named rather than spelled inline at each `moveFocus` so the react handle can
1453
+ * import it: an inline object literal is a copy, and a copy drifts. `pageRows`
1454
+ * is how many rows `"page-up"` / `"page-down"` travel.
1455
+ *
1456
+ * @public
1457
+ */
1458
+ interface PretableIndexedMoveFocusOptions {
1459
+ readonly pageRows?: number;
1460
+ }
1461
+ /** Visual-column input; derivation behavior remains in the row model. @public */
1462
+ interface PretableGridUiColumn<TColumnId extends string> {
1463
+ readonly id: TColumnId;
1464
+ readonly widthPx?: number;
1465
+ readonly pinned?: "left" | "right";
1466
+ /**
1467
+ * A hidden column STAYS in the layout — its width, pin state and position
1468
+ * persist so re-showing restores them — and is filtered out of the drawn
1469
+ * order by the presentation layer, never removed here.
1470
+ */
1471
+ readonly hidden?: boolean;
1472
+ }
1473
+ /** Normalized visual-only column layout published by the UI store. @public */
1474
+ interface PretableGridUiColumnLayout<TColumnId extends string> {
1475
+ readonly id: TColumnId;
1476
+ readonly widthPx: number;
1477
+ readonly pinned?: "left" | "right";
1478
+ /** Present only when `true` — see {@link PretableGridUiColumn.hidden}. */
1479
+ readonly hidden?: boolean;
1480
+ }
1481
+ /** A correlated, data-row-only editing session. @public */
1482
+ type PretableIndexedEditingState<TRowId extends PretableRowId, TColumns> = { readonly [TColumnId in ColumnIdOf<TColumns>]: {
1483
+ readonly rowId: TRowId;
1484
+ readonly columnId: TColumnId;
1485
+ readonly value: ColumnValueOf<TColumns, TColumnId>;
1486
+ readonly status: PretableEditStatus;
1487
+ readonly error?: string;
1488
+ }; }[ColumnIdOf<TColumns>];
1489
+ /**
1490
+ * The long-lived grid store's complete observable UI state.
1491
+ *
1492
+ * `TColumns` and `TColumnId` are two different column vocabularies and are
1493
+ * deliberately separate parameters. `TColumns` is the row model's SCHEMA: it
1494
+ * is the only thing that correlates a column to the type of the value in it,
1495
+ * so `editing` is written against it. `TColumnId` is what the grid DRAWS,
1496
+ * which is a superset — a presentation layer may add columns the schema never
1497
+ * declared (`@pretable/react` draws a grouped-row column and a row-checkbox
1498
+ * column), and those ids appear in `columnLayout`, under the focus cursor and
1499
+ * inside a selection range exactly like a schema column's do.
1500
+ *
1501
+ * Collapsing the two is not merely imprecise, it disables checking: a
1502
+ * consumer's `columnOrder` naming a drawn-but-unschema'd id has to be
1503
+ * comparable against what the engine holds, or the mismatch is discoverable
1504
+ * only at runtime. Defaulted to {@link ColumnIdOf} so the schema-exact case —
1505
+ * a grid with no presentation extras, which is most of them — needs no
1506
+ * annotation and keeps the narrow ids it has always had.
1507
+ *
1508
+ * @public
1509
+ */
1510
+ interface PretableGridUiState<TRowId extends PretableRowId, TColumns, TColumnId extends string = ColumnIdOf<TColumns>> {
1511
+ readonly viewport: Readonly<PretableViewportState>;
1512
+ readonly focus: Readonly<PretableIndexedFocusState<TRowId, TColumnId>>;
1513
+ readonly selection: Readonly<PretableIndexedSelectionState<TRowId, TColumnId>>;
1514
+ readonly editing: PretableIndexedEditingState<TRowId, TColumns> | null;
1515
+ readonly columnLayout: readonly Readonly<PretableGridUiColumnLayout<TColumnId>>[];
1516
+ /**
1517
+ * Whether a column the rows are grouped BY is dropped from the drawn set.
1518
+ *
1519
+ * Seeded from the create option of the same name and thereafter owned by the
1520
+ * engine, so a tool panel can write it — the same prop-is-the-initial-value
1521
+ * contract `columnLayout` holds for column visibility.
1522
+ *
1523
+ * Optional, and ABSENT rather than `false` when the option was not supplied:
1524
+ * the default lives above grid-core (the surface applies it), so "unset" and
1525
+ * "explicitly off" have to stay distinguishable to a consumer reading this
1526
+ * state.
1527
+ */
1528
+ readonly hideGroupedColumns?: boolean;
1529
+ /**
1530
+ * Per-column aggregate OVERRIDES, keyed by LAYOUT column id — the same
1531
+ * vocabulary `columnLayout` uses, hidden entries included, not the narrower
1532
+ * DRAWN set. A hidden column keeps its override exactly as it keeps its
1533
+ * width and pin, so re-showing it restores the whole cell.
1534
+ *
1535
+ * That id vocabulary (`TColumnId`) is also NOT the schema vocabulary
1536
+ * row-model keys a `RuntimeColumn` by; `setColumns` flags the same hazard
1537
+ * for `editing.columnId`. Whatever consumes this map has to translate rather
1538
+ * than assume the two agree.
1539
+ *
1540
+ * An override LAYER, not a replacement: a column absent from this map keeps
1541
+ * whatever `aggregate` its consumer declared on the column prop, so a
1542
+ * consumer who never opens the tool panel sees today's behaviour exactly,
1543
+ * and one who changes the prop after mount is still obeyed. Owning the value
1544
+ * outright would make the prop dead from the first render on.
1545
+ *
1546
+ * A key is therefore PRESENT only while the pane has chosen something;
1547
+ * clearing an override strips the key rather than writing `undefined`, so
1548
+ * "the pane chose nothing" and "the pane chose undefined" cannot be
1549
+ * confused. Always present as an object — an empty map is unambiguous, so
1550
+ * unlike {@link PretableGridUiState.hideGroupedColumns} there is nothing for
1551
+ * absence to encode.
1552
+ *
1553
+ * Values are `unknown`: grid-core stores an aggregate, it never interprets
1554
+ * one. Resolving `"sum"` or an object aggregator is row-model's job. Because
1555
+ * `undefined` is spoken for as "clear the override", there is no value here
1556
+ * that means "draw NO aggregate for a column whose prop declares one" —
1557
+ * expressing that needs a sentinel this layer does not yet define.
1558
+ *
1559
+ * Not seedable from `createGridUiCore`, deliberately, and so asymmetric with
1560
+ * {@link PretableGridUiState.hideGroupedColumns} above: a consumer stating
1561
+ * an aggregate up front writes it on the column itself, and an initial
1562
+ * override would only be that consumer overriding their own prop.
1563
+ */
1564
+ readonly columnAggregates: Readonly<Partial<Record<TColumnId, unknown>>>;
1565
+ readonly observedRowModelRevision: number | null;
1566
+ }
1567
+ /**
1568
+ * Framework-independent UI-only indexed grid store.
1569
+ *
1570
+ * See {@link PretableGridUiState} for why the schema column tuple
1571
+ * (`TColumns`) and the drawn column-id vocabulary (`TColumnId`) are separate
1572
+ * parameters.
1573
+ *
1574
+ * @public
1575
+ */
1576
+ interface PretableGridUiCore<TRow extends object, TRowId extends PretableRowId, TColumns, TColumnId extends string = ColumnIdOf<TColumns>> {
1577
+ readonly rowModel: PretableRowModel<TRow, TRowId, TColumns>;
1578
+ readonly getState: () => PretableGridUiState<TRowId, TColumns, TColumnId>;
1579
+ readonly subscribe: (listener: () => void) => () => void;
1580
+ readonly setViewport: (viewport: PretableViewportState) => void;
1581
+ readonly setFocus: (focus: PretableIndexedFocusState<TRowId, TColumnId>) => void;
1582
+ readonly moveFocus: (movement: PretableIndexedFocusMovement, options?: PretableIndexedMoveFocusOptions) => void;
1583
+ readonly setSelection: (selection: PretableIndexedSelectionState<TRowId, TColumnId>) => void;
1584
+ /**
1585
+ * Replace the row-checkbox slice, leaving the cell ranges and anchor alone.
1586
+ *
1587
+ * The write-side counterpart of `getState().selection.rows`. `setSelection`
1588
+ * cannot do this job: it takes the engine's own containers, which a consumer
1589
+ * has no way to construct.
1590
+ *
1591
+ * Idempotent — applying a value the slice already holds publishes nothing, so
1592
+ * a controlled caller can push on every render without looping.
1593
+ */
1594
+ readonly setRowSelection: (rows: PretableRowSelectionState<TRowId>) => void;
1595
+ readonly toggleRowSelection: (rowId: TRowId) => void;
1596
+ readonly selectRowRange: (startRowId: TRowId, endRowId: TRowId) => void;
1597
+ readonly isRowSelected: (rowId: TRowId) => boolean;
1598
+ readonly getSelectionSummary: () => PretableIndexedSelectionSummary;
1599
+ /**
1600
+ * How many data rows the CELL-RANGE slice covers, and whether that number
1601
+ * is proven. Counted by arithmetic over dataset spans, so it stays correct
1602
+ * — and O(ranges) — while most of the selection is evicted.
1603
+ *
1604
+ * A separate method from {@link getSelectionSummary} because they count
1605
+ * different slices: that one counts the sparse row-selection program the
1606
+ * checkbox column drives, this one counts `selection.ranges`.
1607
+ */
1608
+ readonly getCellSelectionSummary: () => PretableIndexedCellSelectionSummary;
1609
+ readonly selectAllVisibleRows: () => void;
1610
+ readonly clearSelection: () => void;
1611
+ /**
1612
+ * `TEditColumnId` ranges over the SCHEMA ids, not the drawn ones: an edit
1613
+ * carries a value, and only the schema says what type the value in a given
1614
+ * column has. A drawn-but-unschema'd column (a checkbox gutter, a group
1615
+ * label) has no value to edit, and this signature is what says so.
1616
+ *
1617
+ * `status` is the phase the session OPENS in and defaults to `"editing"`.
1618
+ * `"checking"` is the only other legal entry phase: it is what an async
1619
+ * `editable` predicate runs under, and it exists so the editor can render
1620
+ * read-only and `aria-busy` while the answer is in flight. Nothing can
1621
+ * return to it, which is why {@link PretableOpenEditStatus} — the type of
1622
+ * every later transition — excludes it.
1623
+ */
1624
+ readonly beginEdit: <TEditColumnId extends ColumnIdOf<TColumns>>(input: {
1625
+ readonly rowId: TRowId;
1626
+ readonly columnId: TEditColumnId;
1627
+ readonly value: ColumnValueOf<TColumns, TEditColumnId>;
1628
+ readonly status?: "checking" | "editing";
1629
+ }) => void;
1630
+ readonly setEditDraft: (value: unknown) => void;
1631
+ readonly setEditStatus: (status: PretableOpenEditStatus, error?: string) => void;
1632
+ readonly cancelEdit: () => void;
1633
+ /** Reconciles the current visual column set without changing row schema. */
1634
+ readonly setColumns: (columns: readonly PretableGridUiColumn<TColumnId>[]) => void;
1635
+ readonly setColumnWidth: (columnId: TColumnId, width: number) => void;
1636
+ readonly setColumnPinned: (columnId: TColumnId, pinned: "left" | "right" | null) => void;
1637
+ /**
1638
+ * Show or hide a column WITHOUT removing it from the layout: width, pin
1639
+ * state and position all persist, so re-showing restores the column exactly
1640
+ * as it was. Hiding the column under the focus cursor or the selection
1641
+ * anchor re-seats onto the nearest still-visible neighbor in layout order,
1642
+ * left first, then right. Idempotent: applying the visibility a column
1643
+ * already has publishes nothing.
1644
+ */
1645
+ readonly setColumnVisible: (columnId: TColumnId, visible: boolean) => void;
1646
+ readonly setColumnOrder: (columnIds: readonly TColumnId[]) => void;
1647
+ /**
1648
+ * Write {@link PretableGridUiState.hideGroupedColumns}. Idempotent: applying
1649
+ * the value the state already holds publishes nothing.
1650
+ *
1651
+ * Setting `false` is not the same as never having set anything — it makes
1652
+ * the key PRESENT and off, which is what overrides a default resolved above
1653
+ * grid-core.
1654
+ */
1655
+ readonly setHideGroupedColumns: (value: boolean) => void;
1656
+ /**
1657
+ * Override the aggregate shown for one column on group rows, or pass
1658
+ * `undefined` to CLEAR the override and return the column to the `aggregate`
1659
+ * its consumer declared. See {@link PretableGridUiState.columnAggregates}
1660
+ * for why this is a layer over the prop rather than the value itself.
1661
+ *
1662
+ * Idempotent: writing the value already held publishes nothing, and so does
1663
+ * clearing an override that was never set. Equality is reference `===`, as
1664
+ * it is for {@link setColumnWidth} — so a caller passing a fresh inline
1665
+ * object aggregator publishes on every call, however equal it looks.
1666
+ *
1667
+ * A column id absent from `columnLayout` is a silent no-op, matching
1668
+ * {@link setColumnPinned} — an override for an id the layout never holds has
1669
+ * nothing to evict it. Hidden columns ARE in the layout and do take
1670
+ * overrides.
1671
+ */
1672
+ readonly setColumnAggregate: (columnId: TColumnId, aggregate: unknown) => void;
1673
+ /** @internal Called only after renderer geometry for this exact revision exists. */
1674
+ readonly observeRowModelRevision: (revision: number) => void;
1675
+ readonly dispose: () => void;
1676
+ /**
1677
+ * @internal Compile-time-only invariant descriptor. Keyed by a string
1678
+ * literal, not a `unique symbol` — see `PretableGroupId` in
1679
+ * `@pretable-internal/row-model`'s `types.ts` for why a symbol brand does not
1680
+ * survive the public declaration bundle re-emitting this declaration into
1681
+ * `core/dist`.
1682
+ */
1683
+ readonly "~pretableGridUiCore"?: (value: readonly [TRow, TRowId, TColumns, TColumnId]) => readonly [TRow, TRowId, TColumns, TColumnId];
1684
+ }
1685
+ //#endregion
1686
+ //#region ../grid-core/dist/create-grid-ui-core.d.ts
1687
+ /**
1688
+ * Options accepted by the UI-only grid facade.
1689
+ *
1690
+ * See {@link PretableGridUiState} for why the schema column tuple
1691
+ * (`TColumns`) and the drawn column-id vocabulary (`TColumnId`) are separate
1692
+ * parameters: `columns` below is the DRAWN set, which a presentation layer is
1693
+ * entitled to extend beyond the schema.
1694
+ *
1695
+ * @public
1696
+ */
1697
+ interface CreateGridUiCoreOptions<TRow extends object, TRowId extends PretableRowId, TColumns, TColumnId extends string = ColumnIdOf<TColumns>> {
1698
+ readonly rowModel: PretableRowModel<TRow, TRowId, TColumns>;
1699
+ readonly columns: readonly PretableGridUiColumn<TColumnId>[];
1700
+ readonly viewport?: PretableViewportState;
1701
+ /**
1702
+ * INITIAL value of {@link PretableGridUiState.hideGroupedColumns}; the
1703
+ * engine owns it after that, and `setHideGroupedColumns` is the write path.
1704
+ * Omitting it leaves the state key absent rather than `false`, so a
1705
+ * consumer's own default stays distinguishable from an explicit off.
1706
+ */
1707
+ readonly hideGroupedColumns?: boolean;
1708
+ /**
1709
+ * @internal Late-bound getter for what the presentation layer knows about
1710
+ * the loaded window — see `WindowState`/`getWindowing` in
1711
+ * `@pretable/react`'s `pretable-model.ts`, which this mirrors and is fed
1712
+ * by. Read fresh on every row-model revision (never cached) so
1713
+ * `reconcileIndexedSelection` can tell an evicted row from a deleted one —
1714
+ * see {@link PretableIndexedSelectionWindow}.
1715
+ *
1716
+ * Undefined, or a getter returning null, is LOCAL MODE and reproduces
1717
+ * pre-eviction behaviour exactly: every absent row is treated as deleted. A
1718
+ * non-null result whose `window` is null says the consumer IS windowed but
1719
+ * this revision's honesty gate did not pass, which is a different thing and
1720
+ * gets the opposite answer — see
1721
+ * {@link PretableIndexedEvictionContext.windowed}.
1722
+ */
1723
+ readonly getWindowing?: () => PretableIndexedWindowing | null;
1724
+ }
1725
+ /**
1726
+ * Creates the framework-independent indexed UI store.
1727
+ *
1728
+ * @internal Re-exported by `@pretable/core` as `ɵcreateGridUiCore` for
1729
+ * `@pretable/react`, which must reach the engine through the same declaration
1730
+ * emission `@pretable/core` publishes rather than through this package
1731
+ * directly. See the note on that re-export in `packages/core/src/public_api.ts`.
1732
+ */
1733
+ declare function createGridUiCore<TRow extends object, TRowId extends PretableRowId, TColumns, TColumnId extends string = ColumnIdOf<TColumns>>(options: CreateGridUiCoreOptions<TRow, TRowId, TColumns, TColumnId>): PretableGridUiCore<TRow, TRowId, TColumns, TColumnId>;
1734
+ //#endregion
1735
+ //#region ../grid-core/dist/indexed-selection.d.ts
1736
+ /**
1737
+ * Render the engine's row-checkbox slice as the shape a consumer can write
1738
+ * back — the inverse of {@link createIndexedRowSelection}.
1739
+ *
1740
+ * Sparse in, sparse out. A symbolic "all" stays two words, and a shift-checked
1741
+ * 100k-row span stays its two endpoint ids; nothing here walks a population.
1742
+ *
1743
+ * @public
1744
+ */
1745
+ declare function describeRowSelection<TRowId extends PretableRowId>(rows: PretableIndexedRowSelection<TRowId>): PretableRowSelectionState<TRowId>;
1746
+ /**
1747
+ * Data rows covered by the CELL-RANGE slice (`selection.ranges`), by
1748
+ * arithmetic over spans rather than by visiting rows — so a 4,901-row
1749
+ * selection with 30 rows loaded still counts 4,901.
1750
+ *
1751
+ * Not to be confused with {@link getIndexedSelectionSummary}, which counts
1752
+ * the separate sparse row-selection program the checkbox column drives.
1753
+ *
1754
+ * `loadedWindow` is the same honesty-gated span `reconcileIndexedSelection`
1755
+ * takes; omitting it (local mode) restricts the count to what the snapshot
1756
+ * can resolve, exactly as before eviction existed.
1757
+ *
1758
+ * @internal Re-exported by `@pretable/core` as
1759
+ * `ɵgetIndexedCellSelectionSummary`.
1760
+ */
1761
+ declare function getIndexedCellSelectionSummary<TRow extends object, TRowId extends PretableRowId, TColumns, TColumnId extends string>(selection: PretableIndexedSelectionState<TRowId, TColumnId>, snapshot: PretableRowModelSnapshot<TRow, TRowId, TColumns>, loadedWindow?: PretableIndexedSelectionWindow | null): PretableIndexedCellSelectionSummary;
1762
+ /**
1763
+ * Whether a cell range covers `ref` / `columnId`, resolved against the drawn
1764
+ * column order.
1765
+ *
1766
+ * @internal Re-exported by `@pretable/core` as `ɵindexedRangeContainsCell`.
1767
+ */
1768
+ declare function indexedRangeContainsCell<TRow extends object, TRowId extends PretableRowId, TColumns, TColumnId extends string>(range: PretableIndexedCellRange<TRowId, TColumnId>, ref: PretableVisibleRowRef<TRowId>, columnId: TColumnId, snapshot: PretableRowModelSnapshot<TRow, TRowId, TColumns>, columns: readonly TColumnId[],
1769
+ /**
1770
+ * The loaded span, when the honesty gate is passing. Supplying it is what
1771
+ * lets a rendered row in the MIDDLE of a range paint while the range's own
1772
+ * endpoints are evicted — the case that previously painted nothing at all,
1773
+ * because resolving both endpoints was a precondition.
1774
+ */
1775
+ loadedWindow?: PretableIndexedSelectionWindow | null): boolean;
1776
+ //#endregion
1777
+ //#region ../layout-core/dist/types.d.ts
1778
+ /**
1779
+ * Half-open row index range — `start` inclusive, `end` exclusive — used to
1780
+ * describe a visible row window without materializing the rows outside it.
1781
+ *
1782
+ * @public
1783
+ */
1784
+ interface PretableRowRange {
1785
+ start: number;
1786
+ end: number;
1787
+ }
1788
+ /**
1789
+ * Tuning knobs for column autosize calculations.
1790
+ *
1791
+ * @public
1792
+ */
1793
+ interface AutosizeOptions {
1794
+ maxWidthPx?: number;
1795
+ minWidthPx?: number;
1796
+ averageCharWidth?: number;
1797
+ cellPaddingPx?: number;
1798
+ }
1799
+ //#endregion
1800
+ //#region ../grid-core/dist/indexed-focus.d.ts
1801
+ /**
1802
+ * The one header address there is.
1803
+ *
1804
+ * Frozen and shared so identity comparison short-circuits — `sameRef` in
1805
+ * `create-grid-ui-core` still compares structurally, because a consumer may
1806
+ * hand in its own `{kind: "header"}` literal through `setFocus`.
1807
+ *
1808
+ * @internal Re-exported by `@pretable/core` as `ɵHEADER_FOCUS_REF`.
1809
+ */
1810
+ declare const HEADER_FOCUS_REF: PretableHeaderRowRef;
1811
+ //#endregion
1812
+ //#region ../grid-core/dist/group-column.d.ts
1813
+ /** Id of the synthetic visual column that carries grouped row labels. @public */
1814
+ declare const GROUP_COLUMN_ID = "__pretable_group__";
1815
+ /** Presentation options for the synthetic grouped-row column. @public */
1816
+ interface PretableGroupColumnOptions {
1817
+ /** Header text. Defaults to the first grouped column's header. */
1818
+ header?: string;
1819
+ /** Column width. Defaults to 200 pixels. */
1820
+ widthPx?: number;
1821
+ /** Pin the group column to the left. */
1822
+ pinned?: "left";
1823
+ }
1824
+ //#endregion
1825
+ //#region src/create-grid.d.ts
1826
+ /**
1827
+ * Create a framework-independent UI-state grid over an explicit indexed row
1828
+ * model. Data, queries, grouping, aggregation, and expansion remain owned by
1829
+ * `rowModel`; this handle owns only focus, selection, editing, viewport, and
1830
+ * visual column layout.
1831
+ *
1832
+ * @public
1833
+ */
1834
+ declare function createGrid<TRow extends object, TRowId extends PretableRowId, TColumns>(options: CreateGridUiCoreOptions<TRow, TRowId, TColumns>): PretableGridUiCore<TRow, TRowId, TColumns>;
1835
+ //#endregion
1836
+ //#region src/create-column-helper.d.ts
1837
+ /**
1838
+ * Creates a typed column-definition helper for an ordinary row object.
1839
+ *
1840
+ * @public
1841
+ */
1842
+ declare function createColumnHelper<TRow extends object>(): PretableColumnHelper<TRow>;
1843
+ //#endregion
1844
+ //#region src/create-local-row-model.d.ts
1845
+ /** Options for a local row model with an explicit row-ID accessor. @public */
1846
+ interface CreateLocalRowModelOptions<TColumns, TRowId extends PretableRowId> {
1847
+ readonly rows: readonly (TColumns extends readonly [infer TFirstColumn, ...(readonly unknown[])] ? TFirstColumn extends {
1848
+ readonly accessor: (row: infer TRow extends object) => infer TValue;
1849
+ } ? [TValue] extends [unknown] ? TRow : never : never : never)[];
1850
+ readonly columns: TColumns & { readonly [K in keyof TColumns]: TColumns[K] extends {
1851
+ readonly accessor: (row: infer TColumnRow extends object) => infer TColumnValue;
1852
+ } ? [TColumnValue] extends [unknown] ? TColumns extends readonly [infer TFirstColumn, ...(readonly unknown[])] ? TFirstColumn extends {
1853
+ readonly accessor: (row: infer TFirstRow extends object) => infer TFirstValue;
1854
+ } ? [TFirstValue] extends [unknown] ? [TColumnRow] extends [TFirstRow] ? [TFirstRow] extends [TColumnRow] ? TColumns[K] : never : never : never : never : never : never : never; };
1855
+ readonly derivations?: PretableDerivationsFor<TColumns>;
1856
+ readonly query?: PretableQueryFor<TColumns>;
1857
+ readonly initialExpansion?: PretableExpansionDefault;
1858
+ readonly aggregateFilteredRows?: boolean;
1859
+ readonly getRowId: (row: TColumns extends readonly [infer TFirstColumn, ...(readonly unknown[])] ? TFirstColumn extends {
1860
+ readonly accessor: (row: infer TRow extends object) => infer TValue;
1861
+ } ? [TValue] extends [unknown] ? TRow : never : never : never) => TRowId;
1862
+ }
1863
+ /** Options for a local row model using the conventional `row.id`. @public */
1864
+ type CreateLocalRowModelWithDefaultIdOptions<TColumns> = (TColumns extends readonly [infer TFirstColumn, ...(readonly unknown[])] ? TFirstColumn extends {
1865
+ readonly accessor: (row: infer TRow extends object) => infer TValue;
1866
+ } ? [TValue] extends [unknown] ? TRow : never : never : never) extends {
1867
+ readonly id: PretableRowId;
1868
+ } ? Prettify<{
1869
+ readonly rows: readonly (TColumns extends readonly [infer TFirstColumn, ...(readonly unknown[])] ? TFirstColumn extends {
1870
+ readonly accessor: (row: infer TRow extends object) => infer TValue;
1871
+ } ? [TValue] extends [unknown] ? TRow : never : never : never)[];
1872
+ readonly columns: TColumns & { readonly [K in keyof TColumns]: TColumns[K] extends {
1873
+ readonly accessor: (row: infer TColumnRow extends object) => infer TColumnValue;
1874
+ } ? [TColumnValue] extends [unknown] ? TColumns extends readonly [infer TFirstColumn, ...(readonly unknown[])] ? TFirstColumn extends {
1875
+ readonly accessor: (row: infer TFirstRow extends object) => infer TFirstValue;
1876
+ } ? [TFirstValue] extends [unknown] ? [TColumnRow] extends [TFirstRow] ? [TFirstRow] extends [TColumnRow] ? TColumns[K] : never : never : never : never : never : never : never; };
1877
+ readonly derivations?: PretableDerivationsFor<TColumns>;
1878
+ readonly query?: PretableQueryFor<TColumns>;
1879
+ readonly initialExpansion?: PretableExpansionDefault;
1880
+ readonly aggregateFilteredRows?: boolean;
1881
+ readonly getRowId?: undefined;
1882
+ }> : never;
1883
+ /**
1884
+ * Creates a local row model using the conventional `row.id` field.
1885
+ *
1886
+ * @public
1887
+ */
1888
+ declare function createLocalRowModel<const TColumns extends readonly [unknown, ...(readonly unknown[])]>(options: CreateLocalRowModelWithDefaultIdOptions<TColumns>): PretableRowModel<CreateLocalRowModelWithDefaultIdOptions<TColumns>["rows"][number], CreateLocalRowModelWithDefaultIdOptions<TColumns>["rows"][number] extends {
1889
+ readonly id: infer TRowId extends PretableRowId;
1890
+ } ? TRowId : never, TColumns>;
1891
+ /**
1892
+ * Creates a local row model using an explicit string or number row ID.
1893
+ *
1894
+ * @public
1895
+ */
1896
+ 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>;
1897
+ //#endregion
1898
+ //#region src/number-formats.d.ts
1899
+ /**
1900
+ * Options for Pretable's currency number-format presets.
1901
+ *
1902
+ * @public
1903
+ */
1904
+ type PretableCurrencyFormatOptions = Omit<Intl.NumberFormatOptions, "style" | "currency" | "currencySign"> & {
1905
+ currency: string;
1906
+ };
1907
+ /**
1908
+ * Native number-format presets for money and accounting presentation.
1909
+ *
1910
+ * @public
1911
+ */
1912
+ declare const numberFormats: {
1913
+ readonly money: (options: PretableCurrencyFormatOptions) => Intl.NumberFormatOptions;
1914
+ readonly accounting: (options: PretableCurrencyFormatOptions) => Intl.NumberFormatOptions;
1915
+ };
1916
+ //#endregion
1917
+ 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 PretableColumnAggregateOverrides, 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 PretableFilterGroupFor, type PretableFilterNodeFor, 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 PretableHeaderRowRef, type PretableIndexedCellAddress, type PretableIndexedCellRange, type PretableIndexedCellSelectionSummary, type PretableIndexedDatasetRowSpan, type PretableIndexedEditingState, type PretableIndexedFocusMovement, type PretableIndexedFocusRef, type PretableIndexedFocusState, type PretableIndexedMoveFocusOptions, type PretableIndexedRowRange, type PretableIndexedRowRangeIndex, type PretableIndexedRowSelection, type PretableIndexedSelectionState, type PretableIndexedSelectionSummary, PretableInvalidGroupKeyError, type PretableMatchingTotal, type PretableMoveFocusOptions, type PretableMutationIssue, type PretableMutationResult, type PretableOpenEditStatus, 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, type PretableUninferredColumnValue, PretableUnsupportedRowUpdateError, type PretableViewportState, type PretableVisibleRow, type PretableVisibleRowField, type PretableVisibleRowRef, type Prettify, type RowIdOf, type RowOf, createColumnHelper, createGrid, createLocalRowModel, describeRowSelection, isPretableFilterGroup, mergeColumnAggregateOverrides, numberFormats, HEADER_FOCUS_REF as ɵHEADER_FOCUS_REF, type PretableIndexedSelectionWindow as ɵPretableIndexedSelectionWindow, type PretableIndexedWindowing as ɵPretableIndexedWindowing, createGridUiCore as ɵcreateGridUiCore, getIndexedCellSelectionSummary as ɵgetIndexedCellSelectionSummary, indexedRangeContainsCell as ɵindexedRangeContainsCell, ɵsetLocalRowModelFilterAuthority, ɵsetLocalRowModelSortAuthority };
1918
+ //# sourceMappingURL=index.d.mts.map