@pretable/core 0.4.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -13
- package/dist/index.cjs +8148 -1849
- package/dist/index.d.cts +876 -470
- package/dist/index.d.ts +876 -470
- package/dist/index.mjs +8140 -1850
- package/package.json +3 -2
package/dist/index.d.cts
CHANGED
|
@@ -1,62 +1,640 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
* describe the visible row window in {@link PretableGridSnapshot.visibleRange}.
|
|
4
|
-
*
|
|
2
|
+
* Expand mapped/intersection types into readable editor hovers.
|
|
5
3
|
* @public
|
|
6
4
|
*/
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
5
|
+
type Prettify<T> = {
|
|
6
|
+
[K in keyof T]: T[K];
|
|
7
|
+
} & {};
|
|
8
|
+
/** @public */
|
|
9
|
+
type PretableRowId = string | number;
|
|
11
10
|
/**
|
|
12
|
-
*
|
|
13
|
-
*
|
|
11
|
+
* Values with stable, collision-free local grouping identity.
|
|
14
12
|
* @public
|
|
15
13
|
*/
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
14
|
+
type PretableGroupKey = string | number | bigint | boolean | Date | null | undefined;
|
|
15
|
+
/** @public */
|
|
16
|
+
type PretableColumnType = "text" | "number" | "date" | "enum" | "boolean";
|
|
17
|
+
/** @public */
|
|
18
|
+
interface PretableAggregator<TRow extends object = object, TValue = unknown, TAccumulator = unknown, TOutput = unknown> {
|
|
19
|
+
readonly init: () => TAccumulator;
|
|
20
|
+
readonly accumulate: (accumulator: TAccumulator, value: TValue, row: TRow) => TAccumulator;
|
|
21
|
+
readonly merge: (left: TAccumulator, right: TAccumulator) => TAccumulator;
|
|
22
|
+
/**
|
|
23
|
+
* Produces a detached accumulator for `finalize`. Required when the
|
|
24
|
+
* accumulator is a class instance or otherwise cannot be structured-cloned
|
|
25
|
+
* without losing behavior.
|
|
26
|
+
*/
|
|
27
|
+
readonly snapshotAccumulator?: (accumulator: TAccumulator) => TAccumulator;
|
|
28
|
+
readonly finalize: (accumulator: TAccumulator) => TOutput;
|
|
21
29
|
}
|
|
22
|
-
|
|
30
|
+
/** @public */
|
|
31
|
+
type PretableBuiltinAggregate<TValue> = "count" | ([NonNullable<TValue>] extends [never] ? never : NonNullable<TValue> extends number ? "sum" | "avg" | "min" | "max" : never);
|
|
32
|
+
/** @public */
|
|
33
|
+
type PretableAggregateSpec<TRow extends object, TValue> = PretableBuiltinAggregate<TValue> | PretableCompatibleAggregator<TRow, TValue, unknown>;
|
|
34
|
+
declare const columnDescriptor: unique symbol;
|
|
35
|
+
/** Compile-time-only accessor-form carrier emitted by the column helper. @public */
|
|
36
|
+
interface PretableColumnAccessorKind<TKind extends "direct" | "computed"> {
|
|
37
|
+
readonly [columnDescriptor]: {
|
|
38
|
+
readonly accessorKind: TKind;
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
/** @public */
|
|
42
|
+
interface PretableFormatInput<TRow extends object, TValue = unknown, TColumn = unknown> {
|
|
43
|
+
readonly value: TValue;
|
|
44
|
+
readonly row: TRow;
|
|
45
|
+
readonly column: TColumn;
|
|
46
|
+
}
|
|
47
|
+
/** @public */
|
|
48
|
+
interface PretableAggregateFormatInput<TValue, TColumn> {
|
|
49
|
+
readonly value: TValue;
|
|
50
|
+
readonly column: TColumn;
|
|
51
|
+
}
|
|
52
|
+
/** @public */
|
|
53
|
+
type PretableAggregateOutputOf<TAggregate> = TAggregate extends {
|
|
54
|
+
readonly finalize: (accumulator: never) => infer TOutput;
|
|
55
|
+
} ? TOutput : TAggregate extends "sum" | "avg" | "min" | "max" | "count" ? number | null : never;
|
|
56
|
+
/** @public */
|
|
57
|
+
interface PretableColumnDefinition<TRow extends object, TId extends string, TValue, TType extends PretableColumnType, TAggregate = undefined> {
|
|
58
|
+
readonly id: TId;
|
|
59
|
+
readonly type: TType;
|
|
60
|
+
readonly header?: string;
|
|
61
|
+
readonly accessorKey?: Extract<keyof TRow, string>;
|
|
62
|
+
readonly accessor: (row: TRow) => TValue;
|
|
63
|
+
/** Compatibility spelling retained on the original column object. */
|
|
64
|
+
readonly value: (row: TRow) => TValue;
|
|
65
|
+
readonly compare?: (left: TValue, right: TValue) => number;
|
|
66
|
+
readonly aggregate?: TAggregate;
|
|
67
|
+
readonly format?: (input: PretableFormatInput<TRow, TValue, PretableColumnDefinition<TRow, TId, TValue, TType, TAggregate>>) => string;
|
|
68
|
+
readonly formatAggregate?: (input: PretableAggregateFormatInput<PretableAggregateOutputOf<TAggregate>, PretableColumnDefinition<TRow, TId, TValue, TType, TAggregate>>) => string;
|
|
69
|
+
readonly [columnDescriptor]: {
|
|
70
|
+
readonly row: TRow;
|
|
71
|
+
readonly id: TId;
|
|
72
|
+
readonly value: TValue;
|
|
73
|
+
readonly type: TType;
|
|
74
|
+
readonly aggregate: TAggregate;
|
|
75
|
+
};
|
|
76
|
+
}
|
|
77
|
+
/** @public */
|
|
78
|
+
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;
|
|
79
|
+
/** @public */
|
|
80
|
+
interface PretableColumnCallbackContext<TRow extends object, TId extends string, TValue, TType extends PretableColumnType, TAggregate> {
|
|
81
|
+
readonly id: TId;
|
|
82
|
+
readonly type: TType;
|
|
83
|
+
readonly accessor: (row: TRow) => TValue;
|
|
84
|
+
readonly value: (row: TRow) => TValue;
|
|
85
|
+
readonly aggregate?: TAggregate;
|
|
86
|
+
}
|
|
87
|
+
/** @public */
|
|
88
|
+
type PretableColumnOptions<TRow extends object, TId extends string, TValue, TType extends PretableColumnTypeFor<TValue>, TAggregate extends PretableAggregateSpec<TRow, TValue> | undefined> = {
|
|
89
|
+
readonly type: TType;
|
|
90
|
+
readonly header?: string;
|
|
91
|
+
readonly compare?: (left: TValue, right: TValue) => number;
|
|
92
|
+
readonly aggregate?: TAggregate;
|
|
93
|
+
readonly format?: (input: {
|
|
94
|
+
readonly value: TValue;
|
|
95
|
+
readonly row: TRow;
|
|
96
|
+
readonly column: PretableColumnCallbackContext<TRow, TId, TValue, TType, TAggregate>;
|
|
97
|
+
}) => string;
|
|
98
|
+
readonly formatAggregate?: (input: {
|
|
99
|
+
readonly value: PretableAggregateOutputOf<TAggregate>;
|
|
100
|
+
readonly column: PretableColumnCallbackContext<TRow, TId, TValue, TType, TAggregate>;
|
|
101
|
+
}) => string;
|
|
102
|
+
};
|
|
103
|
+
/** @public */
|
|
104
|
+
interface PretableColumnHelper<TRow extends object> {
|
|
105
|
+
accessor<const TId extends string, const TAccessor extends (...args: never[]) => unknown, const TType extends (unknown extends NoInfer<TValue> ? never : PretableColumnTypeFor<NoInfer<TValue>>) | ([TValue] extends [typeof columnDescriptor] ? [ReturnType<TAccessor>] extends [never] ? never : PretableColumnType : never), TValue = typeof columnDescriptor, const TAggregate extends PretableAggregateSpec<TRow, NoInfer<TValue>> | ([TValue] extends [typeof columnDescriptor] ? [ReturnType<TAccessor>] extends [never] ? never : PretableAggregateSpec<TRow, never> | "sum" | "avg" | "min" | "max" : never) | undefined = undefined>(id: TId, accessor: TAccessor & ((row: TRow) => TValue), options: {
|
|
106
|
+
readonly type: TType;
|
|
107
|
+
readonly header?: string;
|
|
108
|
+
readonly compare?: (left: TValue, right: TValue) => number;
|
|
109
|
+
readonly aggregate?: TAggregate;
|
|
110
|
+
readonly format?: (input: {
|
|
111
|
+
readonly value: TValue;
|
|
112
|
+
readonly row: TRow;
|
|
113
|
+
readonly column: PretableColumnCallbackContext<TRow, TId, TValue, TType, TAggregate>;
|
|
114
|
+
}) => string;
|
|
115
|
+
readonly formatAggregate?: (input: {
|
|
116
|
+
readonly value: PretableAggregateOutputOf<TAggregate>;
|
|
117
|
+
readonly column: PretableColumnCallbackContext<TRow, TId, TValue, TType, TAggregate>;
|
|
118
|
+
}) => string;
|
|
119
|
+
}): PretableColumnDefinition<TRow, TId, ReturnType<TAccessor>, TType, TAggregate> & PretableColumnAccessorKind<"computed">;
|
|
120
|
+
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">;
|
|
121
|
+
}
|
|
122
|
+
/** @public */
|
|
123
|
+
type ColumnIdOf<TColumns> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
|
|
124
|
+
readonly id: infer TId extends string;
|
|
125
|
+
} ? TId : never : never;
|
|
126
|
+
/** @public */
|
|
127
|
+
type ColumnValueOf<TColumns, TColumnId extends ColumnIdOf<TColumns>> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
|
|
128
|
+
readonly id: TColumnId;
|
|
129
|
+
readonly accessor: (...args: never[]) => infer TValue;
|
|
130
|
+
} ? TValue : never : never;
|
|
131
|
+
/** @public */
|
|
132
|
+
type ColumnAggregateValueOf<TColumns, TColumnId extends ColumnIdOf<TColumns>> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
|
|
133
|
+
readonly id: TColumnId;
|
|
134
|
+
readonly aggregate?: infer TAggregate;
|
|
135
|
+
} ? PretableAggregateOutputOf<TAggregate> : never : never;
|
|
136
|
+
/** @public */
|
|
137
|
+
type PretableAggregatesFor<TColumns> = Prettify<{
|
|
138
|
+
readonly [TColumn in TColumns extends readonly (infer TItem)[] ? TItem : never as TColumn extends {
|
|
139
|
+
readonly id: infer TId extends string;
|
|
140
|
+
readonly aggregate?: infer TAggregate;
|
|
141
|
+
} ? [TAggregate] extends [undefined] ? never : TId : never]: TColumn extends {
|
|
142
|
+
readonly aggregate?: infer TAggregate;
|
|
143
|
+
} ? PretableAggregateOutputOf<TAggregate> : never;
|
|
144
|
+
}>;
|
|
23
145
|
/**
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
* It is *derived*, never stored: `options.columns` remains the consumer's
|
|
28
|
-
* truth, and {@link resolveEffectiveColumns} rebuilds this column on read
|
|
29
|
-
* whenever `rowGroups` is non-empty. The alternative — pushing it into
|
|
30
|
-
* `options.columns` — cannot work, because `mergeColumnsFromProps` rebuilds
|
|
31
|
-
* that array by mapping over the consumer's own array and would delete any
|
|
32
|
-
* column props never mentioned.
|
|
33
|
-
*
|
|
146
|
+
* The runtime filter operand accepted by a declared column type.
|
|
147
|
+
* Enum columns retain known string literal values and otherwise accept strings.
|
|
34
148
|
* @public
|
|
35
149
|
*/
|
|
36
|
-
|
|
150
|
+
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>;
|
|
151
|
+
/** @public */
|
|
152
|
+
type PretableFilterFor<TColumns> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
|
|
153
|
+
readonly id: infer TId extends string;
|
|
154
|
+
readonly accessor: (...args: never[]) => infer TValue;
|
|
155
|
+
readonly type: infer TType extends PretableColumnType;
|
|
156
|
+
} ? {
|
|
157
|
+
readonly columnId: TId;
|
|
158
|
+
readonly operator: "isEmpty" | "isNotEmpty";
|
|
159
|
+
} | (TType extends "number" ? {
|
|
160
|
+
readonly columnId: TId;
|
|
161
|
+
readonly operator: "equals" | "notEquals" | "gt" | "gte" | "lt" | "lte";
|
|
162
|
+
readonly value: PretableFilterOperandFor<TValue, TType>;
|
|
163
|
+
} | {
|
|
164
|
+
readonly columnId: TId;
|
|
165
|
+
readonly operator: "between";
|
|
166
|
+
readonly value: readonly [
|
|
167
|
+
PretableFilterOperandFor<TValue, TType>,
|
|
168
|
+
PretableFilterOperandFor<TValue, TType>
|
|
169
|
+
];
|
|
170
|
+
} : TType extends "date" ? {
|
|
171
|
+
readonly columnId: TId;
|
|
172
|
+
readonly operator: "on" | "before" | "after";
|
|
173
|
+
readonly value: PretableFilterOperandFor<TValue, TType>;
|
|
174
|
+
} | {
|
|
175
|
+
readonly columnId: TId;
|
|
176
|
+
readonly operator: "dateBetween";
|
|
177
|
+
readonly value: readonly [
|
|
178
|
+
PretableFilterOperandFor<TValue, TType>,
|
|
179
|
+
PretableFilterOperandFor<TValue, TType>
|
|
180
|
+
];
|
|
181
|
+
} : TType extends "enum" | "boolean" ? {
|
|
182
|
+
readonly columnId: TId;
|
|
183
|
+
readonly operator: "isAnyOf" | "isNoneOf";
|
|
184
|
+
readonly value: readonly PretableFilterOperandFor<TValue, TType>[];
|
|
185
|
+
} : {
|
|
186
|
+
readonly columnId: TId;
|
|
187
|
+
readonly operator: "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith";
|
|
188
|
+
readonly value: PretableFilterOperandFor<TValue, TType>;
|
|
189
|
+
}) : never : never;
|
|
190
|
+
/** @public */
|
|
191
|
+
type PretableSortFor<TColumns> = Prettify<(TColumns extends readonly (infer TColumn)[] ? TColumn extends {
|
|
192
|
+
readonly id: infer TId extends string;
|
|
193
|
+
} ? {
|
|
194
|
+
readonly columnId: TId;
|
|
195
|
+
} : never : never) & {
|
|
196
|
+
readonly direction: "asc" | "desc";
|
|
197
|
+
readonly nulls?: "first" | "last";
|
|
198
|
+
}>;
|
|
199
|
+
/** @public */
|
|
200
|
+
type PretableRowGroupFor<TColumns> = Prettify<(TColumns extends readonly (infer TColumn)[] ? TColumn extends {
|
|
201
|
+
readonly id: infer TId extends string;
|
|
202
|
+
readonly accessor: (...args: never[]) => infer TValue;
|
|
203
|
+
} ? [TValue] extends [never] ? never : [TValue] extends [PretableGroupKey] ? {
|
|
204
|
+
readonly columnId: TId;
|
|
205
|
+
} : never : never : never) & {
|
|
206
|
+
readonly direction?: "asc" | "desc";
|
|
207
|
+
readonly nulls?: "first" | "last";
|
|
208
|
+
}>;
|
|
209
|
+
/** @public */
|
|
210
|
+
interface PretableQueryFor<TColumns> {
|
|
211
|
+
readonly filters: readonly PretableFilterFor<TColumns>[];
|
|
212
|
+
readonly sort: readonly PretableSortFor<TColumns>[];
|
|
213
|
+
readonly rowGroups: readonly PretableRowGroupFor<TColumns>[];
|
|
214
|
+
}
|
|
215
|
+
/** @public */
|
|
216
|
+
interface PretableCompatibleAggregator<TRow extends object, TValue, TOutput> {
|
|
217
|
+
readonly init: () => unknown;
|
|
218
|
+
readonly accumulate: {
|
|
219
|
+
bivarianceHack(accumulator: unknown, value: TValue, row: TRow): unknown;
|
|
220
|
+
}["bivarianceHack"] & ((accumulator: never, value: TValue, row: TRow) => unknown);
|
|
221
|
+
readonly merge: {
|
|
222
|
+
bivarianceHack(left: unknown, right: unknown): unknown;
|
|
223
|
+
}["bivarianceHack"];
|
|
224
|
+
readonly snapshotAccumulator?: {
|
|
225
|
+
bivarianceHack(accumulator: unknown): unknown;
|
|
226
|
+
}["bivarianceHack"];
|
|
227
|
+
readonly finalize: {
|
|
228
|
+
bivarianceHack(accumulator: unknown): TOutput;
|
|
229
|
+
}["bivarianceHack"];
|
|
230
|
+
}
|
|
231
|
+
/** @public */
|
|
232
|
+
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>>;
|
|
233
|
+
/** @public */
|
|
234
|
+
interface PretableColumnDerivation<TRow extends object, TId extends string, TValue, TType extends PretableColumnType, TAggregate> {
|
|
235
|
+
readonly id: TId;
|
|
236
|
+
readonly type: TType;
|
|
237
|
+
readonly accessor: (row: TRow) => TValue;
|
|
238
|
+
readonly value: (row: TRow) => TValue;
|
|
239
|
+
readonly compare?: (left: TValue, right: TValue) => number;
|
|
240
|
+
readonly aggregate?: PretableCompatibleAggregateSpec<TRow, TValue, TAggregate>;
|
|
241
|
+
readonly [columnDescriptor]: {
|
|
242
|
+
readonly row: TRow;
|
|
243
|
+
readonly id: TId;
|
|
244
|
+
readonly value: TValue;
|
|
245
|
+
readonly type: TType;
|
|
246
|
+
readonly aggregate: PretableCompatibleAggregateSpec<TRow, TValue, TAggregate>;
|
|
247
|
+
};
|
|
248
|
+
}
|
|
249
|
+
/** @public */
|
|
250
|
+
type PretableDerivationsFor<TColumns> = {
|
|
251
|
+
readonly [K in keyof TColumns]: TColumns[K] extends {
|
|
252
|
+
readonly id: infer TId extends string;
|
|
253
|
+
readonly type: infer TType extends PretableColumnType;
|
|
254
|
+
readonly accessor: (row: infer TRow extends object) => infer TValue;
|
|
255
|
+
readonly aggregate?: infer TAggregate;
|
|
256
|
+
} ? PretableColumnDerivation<TRow, TId, TValue, TType, TAggregate> : never;
|
|
257
|
+
};
|
|
258
|
+
|
|
259
|
+
/** @public */
|
|
260
|
+
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";
|
|
261
|
+
/** @public */
|
|
262
|
+
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";
|
|
263
|
+
/** @public */
|
|
264
|
+
interface PretableRowModelErrorContext {
|
|
265
|
+
readonly operation: PretableRowModelOperation;
|
|
266
|
+
readonly rowId?: PretableRowId;
|
|
267
|
+
readonly columnId?: string;
|
|
268
|
+
readonly cause?: unknown;
|
|
269
|
+
}
|
|
270
|
+
/** @public */
|
|
271
|
+
declare class PretableRowModelError extends Error {
|
|
272
|
+
readonly name: string;
|
|
273
|
+
readonly code: PretableRowModelErrorCode;
|
|
274
|
+
readonly operation: PretableRowModelOperation;
|
|
275
|
+
readonly rowId?: PretableRowId;
|
|
276
|
+
readonly columnId?: string;
|
|
277
|
+
constructor(code: PretableRowModelErrorCode, message: string, context: PretableRowModelErrorContext);
|
|
278
|
+
}
|
|
279
|
+
/** @public */
|
|
280
|
+
declare class PretableDisposedModelError extends PretableRowModelError {
|
|
281
|
+
readonly name: string;
|
|
282
|
+
constructor(operation: PretableRowModelOperation);
|
|
283
|
+
}
|
|
284
|
+
/** @public */
|
|
285
|
+
declare class PretableReentrantMutationError extends PretableRowModelError {
|
|
286
|
+
readonly activeOperation: PretableRowModelOperation;
|
|
287
|
+
readonly name = "PretableReentrantMutationError";
|
|
288
|
+
constructor(operation: PretableRowModelOperation, activeOperation: PretableRowModelOperation);
|
|
289
|
+
}
|
|
290
|
+
/** @public */
|
|
291
|
+
declare class PretableRowIdentityChangeError extends PretableRowModelError {
|
|
292
|
+
readonly nextRowId: unknown;
|
|
293
|
+
readonly name = "PretableRowIdentityChangeError";
|
|
294
|
+
constructor(rowId: PretableRowId, nextRowId: unknown, cause?: unknown);
|
|
295
|
+
}
|
|
296
|
+
/** @public */
|
|
297
|
+
declare class PretableUnsupportedRowUpdateError extends PretableRowModelError {
|
|
298
|
+
readonly name = "PretableUnsupportedRowUpdateError";
|
|
299
|
+
constructor(rowId: PretableRowId, cause?: unknown);
|
|
300
|
+
}
|
|
301
|
+
/** @public */
|
|
302
|
+
declare class PretableInvalidGroupKeyError extends PretableRowModelError {
|
|
303
|
+
readonly value: unknown;
|
|
304
|
+
readonly name = "PretableInvalidGroupKeyError";
|
|
305
|
+
constructor(operation: PretableRowModelOperation, rowId: PretableRowId | undefined, columnId: string, value: unknown, cause?: unknown);
|
|
306
|
+
}
|
|
307
|
+
/** @public */
|
|
308
|
+
type PretableTransitionCancellationReason = "cancelled" | "superseded" | "disposed";
|
|
309
|
+
/** @public */
|
|
310
|
+
declare class PretableTransitionCancelledError extends Error {
|
|
311
|
+
readonly transitionId: number;
|
|
312
|
+
readonly reason: PretableTransitionCancellationReason;
|
|
313
|
+
readonly name = "PretableTransitionCancelledError";
|
|
314
|
+
constructor(transitionId: number, reason: PretableTransitionCancellationReason);
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
declare const groupIdBrand: unique symbol;
|
|
318
|
+
declare const rowModelDescriptor: unique symbol;
|
|
319
|
+
/** @public */
|
|
320
|
+
type PretableGroupId = string & {
|
|
321
|
+
readonly [groupIdBrand]: "PretableGroupId";
|
|
322
|
+
};
|
|
323
|
+
/** @public */
|
|
324
|
+
type PretableVisibleRowRef<TRowId extends PretableRowId> = {
|
|
325
|
+
readonly kind: "data";
|
|
326
|
+
readonly rowId: TRowId;
|
|
327
|
+
} | {
|
|
328
|
+
readonly kind: "group";
|
|
329
|
+
readonly groupId: PretableGroupId;
|
|
330
|
+
};
|
|
331
|
+
/** @public */
|
|
332
|
+
interface PretableDataRow<TRow extends object, TRowId extends PretableRowId> {
|
|
333
|
+
readonly kind: "data";
|
|
334
|
+
readonly rowId: TRowId;
|
|
335
|
+
readonly row: TRow;
|
|
336
|
+
readonly sourceIndex: number;
|
|
337
|
+
readonly depth: number;
|
|
338
|
+
}
|
|
339
|
+
/** @public */
|
|
340
|
+
type PretableGroupRow<TColumns> = {
|
|
341
|
+
readonly [TColumnId in ColumnIdOf<TColumns>]: {
|
|
342
|
+
readonly kind: "group";
|
|
343
|
+
readonly groupId: PretableGroupId;
|
|
344
|
+
readonly depth: number;
|
|
345
|
+
readonly columnId: TColumnId;
|
|
346
|
+
readonly value: ColumnValueOf<TColumns, TColumnId>;
|
|
347
|
+
readonly childCount: number;
|
|
348
|
+
readonly aggregates: PretableAggregatesFor<TColumns>;
|
|
349
|
+
readonly expanded: boolean;
|
|
350
|
+
};
|
|
351
|
+
}[ColumnIdOf<TColumns>];
|
|
352
|
+
/** @public */
|
|
353
|
+
type PretableVisibleRow<TRow extends object, TRowId extends PretableRowId, TColumns> = PretableDataRow<TRow, TRowId> | PretableGroupRow<TColumns>;
|
|
354
|
+
/** @public */
|
|
355
|
+
type PretableExpansionDefault = {
|
|
356
|
+
readonly kind: "collapsed";
|
|
357
|
+
} | {
|
|
358
|
+
readonly kind: "expanded";
|
|
359
|
+
} | {
|
|
360
|
+
readonly kind: "through-depth";
|
|
361
|
+
readonly depth: number;
|
|
362
|
+
};
|
|
363
|
+
/** @public */
|
|
364
|
+
interface PretableExpansionState {
|
|
365
|
+
readonly default: PretableExpansionDefault;
|
|
366
|
+
readonly overrideCount: number;
|
|
367
|
+
}
|
|
368
|
+
/** @public */
|
|
369
|
+
interface PretableRowModelSnapshot<TRow extends object, TRowId extends PretableRowId, TColumns> {
|
|
370
|
+
readonly revision: number;
|
|
371
|
+
readonly sourceRowCount: number;
|
|
372
|
+
readonly visibleRowCount: number;
|
|
373
|
+
readonly visibleDataRowCount: number;
|
|
374
|
+
rowAt(index: number): PretableVisibleRow<TRow, TRowId, TColumns> | undefined;
|
|
375
|
+
/**
|
|
376
|
+
* Returns the half-open visible-row interval `[start, end)`. Both bounds are
|
|
377
|
+
* clamped to `[0, visibleRowCount]`.
|
|
378
|
+
*/
|
|
379
|
+
range(start: number, end: number): readonly PretableVisibleRow<TRow, TRowId, TColumns>[];
|
|
380
|
+
/** Returns the visible rank of `ref`, or `-1` when it is absent. */
|
|
381
|
+
indexOf(ref: PretableVisibleRowRef<TRowId>): number;
|
|
382
|
+
/** Returns the data-only rank of `ref`, or `-1` when it is absent. */
|
|
383
|
+
dataIndexOf(ref: PretableVisibleRowRef<TRowId>): number;
|
|
384
|
+
/**
|
|
385
|
+
* Returns the data row at a data-only rank. Group rows do not consume an
|
|
386
|
+
* index; an out-of-bounds rank returns `undefined`.
|
|
387
|
+
*/
|
|
388
|
+
dataRowAt(index: number): PretableDataRow<TRow, TRowId> | undefined;
|
|
389
|
+
/** Returns the first visible data row, or `undefined` when none is visible. */
|
|
390
|
+
firstDataRow(): PretableDataRow<TRow, TRowId> | undefined;
|
|
391
|
+
/** Returns the last visible data row, or `undefined` when none is visible. */
|
|
392
|
+
lastDataRow(): PretableDataRow<TRow, TRowId> | undefined;
|
|
393
|
+
/**
|
|
394
|
+
* Returns the next visible data row after `ref`, skipping group rows, or
|
|
395
|
+
* `undefined` when `ref` is absent or has no following data row.
|
|
396
|
+
*/
|
|
397
|
+
nextDataRow(ref: PretableVisibleRowRef<TRowId>): PretableDataRow<TRow, TRowId> | undefined;
|
|
398
|
+
/**
|
|
399
|
+
* Returns the previous visible data row before `ref`, skipping group rows,
|
|
400
|
+
* or `undefined` when `ref` is absent or has no preceding data row.
|
|
401
|
+
*/
|
|
402
|
+
previousDataRow(ref: PretableVisibleRowRef<TRowId>): PretableDataRow<TRow, TRowId> | undefined;
|
|
403
|
+
/** Returns the immediate parent group of `ref`, if it has one. */
|
|
404
|
+
parentGroupOf(ref: PretableVisibleRowRef<TRowId>): PretableGroupRow<TColumns> | undefined;
|
|
405
|
+
/**
|
|
406
|
+
* Returns `ref` when visible, otherwise its nearest visible ancestor group;
|
|
407
|
+
* returns `undefined` when neither the ref nor a visible ancestor is known.
|
|
408
|
+
*/
|
|
409
|
+
nearestVisibleRef(ref: PretableVisibleRowRef<TRowId>): PretableVisibleRowRef<TRowId> | undefined;
|
|
410
|
+
isGroupExpanded(groupId: PretableGroupId): boolean;
|
|
411
|
+
readonly query: Readonly<PretableQueryFor<TColumns>>;
|
|
412
|
+
readonly expansion: Readonly<PretableExpansionState>;
|
|
413
|
+
}
|
|
414
|
+
/** @public */
|
|
415
|
+
type PretableRowModelStatus = {
|
|
416
|
+
readonly kind: "ready";
|
|
417
|
+
} | {
|
|
418
|
+
readonly kind: "rebuilding";
|
|
419
|
+
readonly transitionId: number;
|
|
420
|
+
readonly completedRows: number;
|
|
421
|
+
readonly totalRows: number;
|
|
422
|
+
} | {
|
|
423
|
+
readonly kind: "error";
|
|
424
|
+
readonly transitionId: number;
|
|
425
|
+
readonly error: PretableRowModelError;
|
|
426
|
+
} | {
|
|
427
|
+
readonly kind: "disposed";
|
|
428
|
+
};
|
|
429
|
+
/** @public */
|
|
430
|
+
interface PretableRowModelState<TRow extends object, TRowId extends PretableRowId, TColumns> {
|
|
431
|
+
readonly snapshot: PretableRowModelSnapshot<TRow, TRowId, TColumns>;
|
|
432
|
+
readonly status: PretableRowModelStatus;
|
|
433
|
+
}
|
|
434
|
+
/** @public */
|
|
435
|
+
interface PretableRowUpdate<TRow extends object, TRowId extends PretableRowId> {
|
|
436
|
+
readonly id: TRowId;
|
|
437
|
+
/**
|
|
438
|
+
* An enumerable-own-data-property patch for an ordinary object or
|
|
439
|
+
* null-prototype record. Class instances, arrays, built-in exotic objects,
|
|
440
|
+
* and proxies are not valid partial-update targets because cloning them
|
|
441
|
+
* would lose private state or observable behavior. Replace those values
|
|
442
|
+
* atomically with `setRows` instead. Development builds enforce this for
|
|
443
|
+
* rows that cannot be verified and frozen; production trusts this contract
|
|
444
|
+
* without reflection or proxy detection.
|
|
445
|
+
*/
|
|
446
|
+
readonly changes: Partial<TRow>;
|
|
447
|
+
}
|
|
448
|
+
/** @public */
|
|
449
|
+
interface PretableTransaction<TRow extends object, TRowId extends PretableRowId> {
|
|
450
|
+
readonly add?: readonly TRow[];
|
|
451
|
+
readonly update?: readonly PretableRowUpdate<TRow, TRowId>[];
|
|
452
|
+
readonly remove?: readonly TRowId[];
|
|
453
|
+
}
|
|
454
|
+
/** @public */
|
|
455
|
+
type PretableMutationIssue<TRowId extends PretableRowId> = {
|
|
456
|
+
readonly code: "unknown-update-id";
|
|
457
|
+
readonly rowId: TRowId;
|
|
458
|
+
} | {
|
|
459
|
+
readonly code: "unknown-remove-id";
|
|
460
|
+
readonly rowId: TRowId;
|
|
461
|
+
} | {
|
|
462
|
+
readonly code: "unknown-group-id";
|
|
463
|
+
readonly groupId: PretableGroupId;
|
|
464
|
+
};
|
|
465
|
+
/** @public */
|
|
466
|
+
interface PretableMutationResult<TRowId extends PretableRowId> {
|
|
467
|
+
readonly previousRevision: number;
|
|
468
|
+
readonly revision: number;
|
|
469
|
+
readonly added: number;
|
|
470
|
+
readonly updated: number;
|
|
471
|
+
readonly removed: number;
|
|
472
|
+
readonly unchanged: number;
|
|
473
|
+
readonly ignored: number;
|
|
474
|
+
readonly issues: readonly PretableMutationIssue<TRowId>[];
|
|
475
|
+
}
|
|
476
|
+
/** @public */
|
|
477
|
+
interface PretableQueryTransition<TColumns> {
|
|
478
|
+
readonly id: number;
|
|
479
|
+
readonly requestedQuery: Readonly<PretableQueryFor<TColumns>>;
|
|
480
|
+
readonly finished: Promise<number>;
|
|
481
|
+
cancel(): void;
|
|
482
|
+
}
|
|
483
|
+
/** @public */
|
|
484
|
+
interface PretableDerivationTransition<TColumns> {
|
|
485
|
+
readonly id: number;
|
|
486
|
+
readonly requestedDerivations: Readonly<PretableDerivationsFor<TColumns>>;
|
|
487
|
+
readonly finished: Promise<number>;
|
|
488
|
+
cancel(): void;
|
|
489
|
+
}
|
|
490
|
+
/** @public */
|
|
491
|
+
type PretableVisibleRowField = "row" | "depth" | "expanded" | "childCount" | "aggregates";
|
|
492
|
+
/** @public */
|
|
493
|
+
type PretableChangeOperation<TRowId extends PretableRowId> = {
|
|
494
|
+
readonly kind: "insert";
|
|
495
|
+
readonly ref: PretableVisibleRowRef<TRowId>;
|
|
496
|
+
readonly index: number;
|
|
497
|
+
} | {
|
|
498
|
+
readonly kind: "remove";
|
|
499
|
+
readonly ref: PretableVisibleRowRef<TRowId>;
|
|
500
|
+
readonly previousIndex: number;
|
|
501
|
+
} | {
|
|
502
|
+
readonly kind: "move";
|
|
503
|
+
readonly ref: PretableVisibleRowRef<TRowId>;
|
|
504
|
+
readonly previousIndex: number;
|
|
505
|
+
readonly index: number;
|
|
506
|
+
} | {
|
|
507
|
+
readonly kind: "update";
|
|
508
|
+
readonly ref: PretableVisibleRowRef<TRowId>;
|
|
509
|
+
readonly index: number;
|
|
510
|
+
readonly fields: readonly PretableVisibleRowField[];
|
|
511
|
+
};
|
|
512
|
+
/** @public */
|
|
513
|
+
interface PretableChangeSet<TRowId extends PretableRowId> {
|
|
514
|
+
/** The snapshot revision to which the first operation applies. */
|
|
515
|
+
readonly previousRevision: number;
|
|
516
|
+
/** The atomically published revision produced by the complete operation list. */
|
|
517
|
+
readonly revision: number;
|
|
518
|
+
/**
|
|
519
|
+
* Applies sequentially: every index is measured after the preceding
|
|
520
|
+
* operation in this list. Row data and group fields are read from the
|
|
521
|
+
* snapshot at `revision`; operations never expose mutable row-model roots.
|
|
522
|
+
*/
|
|
523
|
+
readonly operations: readonly PretableChangeOperation<TRowId>[];
|
|
524
|
+
}
|
|
525
|
+
/** @public */
|
|
526
|
+
type PretableChangeSequence<TRowId extends PretableRowId> = {
|
|
527
|
+
readonly kind: "changes";
|
|
528
|
+
readonly fromRevision: number;
|
|
529
|
+
readonly toRevision: number;
|
|
530
|
+
readonly changes: readonly PretableChangeSet<TRowId>[];
|
|
531
|
+
} | {
|
|
532
|
+
readonly kind: "reset";
|
|
533
|
+
readonly toRevision: number;
|
|
534
|
+
readonly reason: "unknown-revision" | "journal-evicted" | "bulk-replace";
|
|
535
|
+
};
|
|
536
|
+
/** @public */
|
|
537
|
+
interface PretableDistinctValueOptions {
|
|
538
|
+
readonly search?: string;
|
|
539
|
+
readonly start?: number;
|
|
540
|
+
readonly limit?: number;
|
|
541
|
+
readonly population?: "all" | "filtered";
|
|
542
|
+
/** Includes nullish, NaN, and trim-empty string values. Defaults to false. */
|
|
543
|
+
readonly includeBlanks?: boolean;
|
|
544
|
+
/** Places included blank values before or after non-blank values. */
|
|
545
|
+
readonly blankOrder?: "first" | "last";
|
|
546
|
+
}
|
|
547
|
+
/** @public */
|
|
548
|
+
interface PretableDistinctValueResult<TValue> {
|
|
549
|
+
readonly values: readonly {
|
|
550
|
+
/** Numeric zero uses SameValueZero identity and is returned as positive zero. */
|
|
551
|
+
readonly value: TValue;
|
|
552
|
+
readonly count: number;
|
|
553
|
+
}[];
|
|
554
|
+
readonly totalDistinct: number;
|
|
555
|
+
readonly population: "all" | "filtered";
|
|
556
|
+
readonly rowModelRevision: number;
|
|
557
|
+
}
|
|
558
|
+
/** @public */
|
|
559
|
+
interface PretableDistinctValueQuery<TValue> {
|
|
560
|
+
readonly status: "pending" | "ready" | "error" | "cancelled";
|
|
561
|
+
readonly finished: Promise<PretableDistinctValueResult<TValue>>;
|
|
562
|
+
cancel(): void;
|
|
563
|
+
}
|
|
37
564
|
/**
|
|
38
|
-
*
|
|
39
|
-
*
|
|
565
|
+
* Column IDs whose complete inferred value type has stable local identity.
|
|
40
566
|
* @public
|
|
41
567
|
*/
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
568
|
+
type PretableDistinctColumnIdOf<TColumns> = TColumns extends readonly (infer TColumn)[] ? TColumn extends {
|
|
569
|
+
readonly id: infer TColumnId extends string;
|
|
570
|
+
readonly accessor: (...args: never[]) => infer TValue;
|
|
571
|
+
} ? [TValue] extends [
|
|
572
|
+
string | number | bigint | boolean | Date | null | undefined
|
|
573
|
+
] ? [TValue] extends [never] ? never : TColumnId : never : never : never;
|
|
574
|
+
/** @public */
|
|
575
|
+
interface PretableRowModel<TRow extends object, TRowId extends PretableRowId, TColumns> {
|
|
576
|
+
readonly [rowModelDescriptor]: {
|
|
577
|
+
readonly row: TRow;
|
|
578
|
+
readonly rowId: TRowId;
|
|
579
|
+
readonly columns: TColumns;
|
|
580
|
+
};
|
|
581
|
+
getState(): PretableRowModelState<TRow, TRowId, TColumns>;
|
|
47
582
|
/**
|
|
48
|
-
*
|
|
49
|
-
*
|
|
583
|
+
* Returns the immutable original schema/presentation tuple supplied when
|
|
584
|
+
* this model was created. `setDerivations` replaces engine behavior only;
|
|
585
|
+
* it never changes this presentation fallback or its identity.
|
|
50
586
|
*/
|
|
51
|
-
|
|
587
|
+
getColumns(): TColumns;
|
|
588
|
+
subscribe(listener: () => void): () => void;
|
|
589
|
+
setRows(rows: readonly TRow[]): PretableMutationResult<TRowId>;
|
|
590
|
+
/**
|
|
591
|
+
* Applies one atomic batch. Partial updates require ordinary or
|
|
592
|
+
* null-prototype row records; use `setRows` to replace proxy, class, array,
|
|
593
|
+
* or other exotic row values.
|
|
594
|
+
*/
|
|
595
|
+
applyTransaction(transaction: PretableTransaction<TRow, TRowId>): PretableMutationResult<TRowId>;
|
|
596
|
+
setQuery(query: PretableQueryFor<TColumns>): PretableQueryTransition<TColumns>;
|
|
597
|
+
setDerivations(derivations: PretableDerivationsFor<TColumns>): PretableDerivationTransition<TColumns>;
|
|
598
|
+
setGroupExpanded(groupId: PretableGroupId, expanded: boolean): PretableMutationResult<TRowId>;
|
|
599
|
+
setExpansionDefault(policy: PretableExpansionDefault, options?: {
|
|
600
|
+
readonly preserveOverrides?: boolean;
|
|
601
|
+
}): PretableMutationResult<TRowId>;
|
|
602
|
+
expandAll(): PretableMutationResult<TRowId>;
|
|
603
|
+
collapseAll(): PretableMutationResult<TRowId>;
|
|
604
|
+
/**
|
|
605
|
+
* Returns a retained contiguous sequence through the current revision, or a
|
|
606
|
+
* reset instruction when replay is no longer possible. The current revision
|
|
607
|
+
* always returns an empty `changes` sequence.
|
|
608
|
+
*/
|
|
609
|
+
changesSince(revision: number): PretableChangeSequence<TRowId>;
|
|
610
|
+
distinctValues<TColumnId extends PretableDistinctColumnIdOf<TColumns>>(columnId: TColumnId, options?: PretableDistinctValueOptions): PretableDistinctValueQuery<ColumnValueOf<TColumns, TColumnId>>;
|
|
611
|
+
dispose(): void;
|
|
52
612
|
}
|
|
613
|
+
/** @public */
|
|
614
|
+
type RowOf<TModel> = TModel extends {
|
|
615
|
+
readonly [rowModelDescriptor]: {
|
|
616
|
+
readonly row: infer TRow extends object;
|
|
617
|
+
};
|
|
618
|
+
} ? TRow : never;
|
|
619
|
+
/** @public */
|
|
620
|
+
type RowIdOf<TModel> = TModel extends {
|
|
621
|
+
readonly [rowModelDescriptor]: {
|
|
622
|
+
readonly rowId: infer TRowId extends PretableRowId;
|
|
623
|
+
};
|
|
624
|
+
} ? TRowId : never;
|
|
625
|
+
/** @public */
|
|
626
|
+
type ColumnsOf<TModel> = TModel extends {
|
|
627
|
+
readonly [rowModelDescriptor]: {
|
|
628
|
+
readonly columns: infer TColumns;
|
|
629
|
+
};
|
|
630
|
+
} ? TColumns : never;
|
|
53
631
|
|
|
54
632
|
/**
|
|
55
|
-
* Base row constraint
|
|
633
|
+
* Base row constraint. Concrete row shapes remain fully generic.
|
|
56
634
|
*
|
|
57
635
|
* @public
|
|
58
636
|
*/
|
|
59
|
-
type PretableRow =
|
|
637
|
+
type PretableRow = object;
|
|
60
638
|
/**
|
|
61
639
|
* Sort direction — `null` means unsorted.
|
|
62
640
|
*
|
|
@@ -83,7 +661,7 @@ interface PretableEditInput<TRow extends PretableRow = PretableRow> {
|
|
|
83
661
|
value: unknown;
|
|
84
662
|
}
|
|
85
663
|
/**
|
|
86
|
-
* In-progress cell edit observed
|
|
664
|
+
* In-progress cell edit observed through the UI grid state.
|
|
87
665
|
* `error` carries the validation message (status `"editing"`) or the commit
|
|
88
666
|
* failure message (status `"error"`).
|
|
89
667
|
*
|
|
@@ -129,34 +707,40 @@ interface PretableColumn<TRow extends PretableRow = PretableRow> {
|
|
|
129
707
|
/** Number-editor increment for ArrowUp/Down and steppers. Default 1. */
|
|
130
708
|
step?: number;
|
|
131
709
|
filterable?: boolean;
|
|
132
|
-
/**
|
|
133
|
-
* Restrict the filter menu to the operators the processor can honor. Omitted
|
|
134
|
-
* = the full per-type set (today's behavior). Load-bearing under external
|
|
135
|
-
* filter authority: an unpruned menu offers operators the server will ignore.
|
|
136
|
-
*
|
|
137
|
-
* @experimental
|
|
138
|
-
*/
|
|
710
|
+
/** Restrict the filter menu to operators the current processor can honor. */
|
|
139
711
|
filterOperators?: FilterOperator[];
|
|
140
712
|
type?: ColumnType;
|
|
141
|
-
/**
|
|
142
|
-
* Horizontal alignment of this column's cells and header label. Defaults to
|
|
143
|
-
* `"end"` for `type: "number"` and to the writing direction otherwise.
|
|
144
|
-
*/
|
|
713
|
+
/** Horizontal alignment. Number columns default to `"end"`. */
|
|
145
714
|
align?: ColumnAlign;
|
|
146
715
|
options?: ColumnOption[];
|
|
147
716
|
value?: (row: TRow) => unknown;
|
|
148
|
-
format?: (input: PretableFormatInput<TRow
|
|
149
|
-
/** Native
|
|
717
|
+
format?: (input: PretableFormatInput<TRow, unknown, PretableColumn<TRow>>) => string;
|
|
718
|
+
/** Native number presentation; derivation and editing continue to use raw values. */
|
|
150
719
|
numberFormat?: Intl.NumberFormatOptions;
|
|
151
720
|
/**
|
|
152
721
|
* Render this column's aggregate on a group row.
|
|
153
722
|
*
|
|
154
|
-
* Deliberately not `format`: `
|
|
723
|
+
* Deliberately not `format`: the plain-cell formatter's `row` is non-optional, so
|
|
155
724
|
* every consumer formatter is entitled to dereference it, and a group row has
|
|
156
725
|
* no row. Columns without `formatAggregate` fall back to the same default
|
|
157
726
|
* stringification a plain cell uses.
|
|
158
727
|
*/
|
|
159
|
-
formatAggregate?: (input:
|
|
728
|
+
formatAggregate?: (input: {
|
|
729
|
+
value: unknown;
|
|
730
|
+
column: PretableColumn<TRow>;
|
|
731
|
+
group: {
|
|
732
|
+
readonly id: string;
|
|
733
|
+
readonly groupId: string;
|
|
734
|
+
readonly depth: number;
|
|
735
|
+
readonly columnId: string;
|
|
736
|
+
readonly value: unknown;
|
|
737
|
+
readonly childCount: number;
|
|
738
|
+
readonly aggregates: Readonly<Record<string, unknown>>;
|
|
739
|
+
readonly expanded: boolean;
|
|
740
|
+
};
|
|
741
|
+
/** Whether the aggregate covers the full result or only loaded rows. */
|
|
742
|
+
scope: "all" | "loaded";
|
|
743
|
+
}) => string;
|
|
160
744
|
minWidthPx?: number;
|
|
161
745
|
maxWidthPx?: number;
|
|
162
746
|
/**
|
|
@@ -170,157 +754,36 @@ interface PretableColumn<TRow extends PretableRow = PretableRow> {
|
|
|
170
754
|
flex?: number;
|
|
171
755
|
resizable?: boolean;
|
|
172
756
|
reorderable?: boolean;
|
|
173
|
-
/** Group rows by this column by default; levels follow column order. */
|
|
174
|
-
rowGroup?: boolean;
|
|
175
757
|
/** Aggregate shown for this column on group rows. */
|
|
176
|
-
aggregate?:
|
|
758
|
+
aggregate?: unknown;
|
|
177
759
|
editable?: boolean | ((input: PretableEditInput<TRow>) => boolean | Promise<boolean>);
|
|
178
760
|
validate?: (value: unknown, input: PretableEditInput<TRow>) => (true | string) | Promise<true | string>;
|
|
179
761
|
parseEditValue?: (raw: string, input: PretableEditInput<TRow>) => unknown;
|
|
180
762
|
formatEditValue?: (value: unknown, input: PretableEditInput<TRow>) => string;
|
|
181
763
|
}
|
|
182
|
-
/**
|
|
183
|
-
* Input passed to a column's `format` function.
|
|
184
|
-
*
|
|
185
|
-
* @public
|
|
186
|
-
*/
|
|
187
|
-
interface PretableFormatInput<TRow extends PretableRow = PretableRow> {
|
|
188
|
-
value: unknown;
|
|
189
|
-
row: TRow;
|
|
190
|
-
column: PretableColumn<TRow>;
|
|
191
|
-
}
|
|
192
|
-
/**
|
|
193
|
-
* Input passed to a column's `formatAggregate` function. Carries the group row
|
|
194
|
-
* in place of a data row — an aggregate has no row behind it.
|
|
195
|
-
*
|
|
196
|
-
* @public
|
|
197
|
-
*/
|
|
198
|
-
interface PretableAggregateFormatInput<TRow extends PretableRow = PretableRow> {
|
|
199
|
-
value: unknown;
|
|
200
|
-
column: PretableColumn<TRow>;
|
|
201
|
-
group: PretableGroupRow;
|
|
202
|
-
/**
|
|
203
|
-
* `"loaded"` when the aggregate folded a window onto a larger population, so
|
|
204
|
-
* a sum over 200 loaded rows is never presentable as a population sum. Local
|
|
205
|
-
* mode always passes `"all"`.
|
|
206
|
-
*
|
|
207
|
-
* @experimental
|
|
208
|
-
*/
|
|
209
|
-
scope: "all" | "loaded";
|
|
210
|
-
}
|
|
211
|
-
/**
|
|
212
|
-
* Who applies an operation to the loaded records: the engine's derivation
|
|
213
|
-
* pipeline, or an external processor upstream of `setRows` (a server, a worker,
|
|
214
|
-
* a wasm index — the engine does not know or care).
|
|
215
|
-
*
|
|
216
|
-
* @experimental
|
|
217
|
-
* @public
|
|
218
|
-
*/
|
|
764
|
+
/** Who applies a query slice to the loaded rows. @experimental @public */
|
|
219
765
|
type PretableProcessingAuthority = "engine" | "external";
|
|
220
|
-
/**
|
|
221
|
-
* Per-operation processing authority. Construction-time: flipping authority is
|
|
222
|
-
* a dataset pivot, so it takes a new grid rather than a mutator.
|
|
223
|
-
*
|
|
224
|
-
* @experimental
|
|
225
|
-
* @public
|
|
226
|
-
*/
|
|
766
|
+
/** Per-slice processing authority for remotely fulfilled queries. @experimental @public */
|
|
227
767
|
interface PretableProcessingOptions {
|
|
228
|
-
/**
|
|
229
|
-
* `"external"`: filter state is displayed (funnel indicators, menu contents,
|
|
230
|
-
* `snapshot.filters`) but never applied to the loaded records. Default
|
|
231
|
-
* `"engine"`.
|
|
232
|
-
*/
|
|
233
768
|
filter?: PretableProcessingAuthority;
|
|
234
|
-
/**
|
|
235
|
-
* `"external"`: sort state is displayed (header arrows, priority badges,
|
|
236
|
-
* `snapshot.sort`) but the model order is the supplied record order. Default
|
|
237
|
-
* `"engine"`.
|
|
238
|
-
*/
|
|
239
769
|
sort?: PretableProcessingAuthority;
|
|
240
770
|
}
|
|
241
|
-
/**
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
* position instead, replacing `rows` in a different order — an external
|
|
258
|
-
* sort, a streaming batch, a removal — would silently re-point selection,
|
|
259
|
-
* focus and an open editor at whichever rows now occupy those positions. No
|
|
260
|
-
* error, no warning, wrong rows.
|
|
261
|
-
*
|
|
262
|
-
* The function receives only the row, so position is not in scope. Rows with
|
|
263
|
-
* no natural key need one synthesized when the data is loaded, not derived
|
|
264
|
-
* from where the row happens to sit.
|
|
265
|
-
*
|
|
266
|
-
* Ids must be unique and stable across renders for the same logical row.
|
|
267
|
-
*
|
|
268
|
-
* @example
|
|
269
|
-
* ```ts
|
|
270
|
-
* createGrid({ columns, rows, getRowId: (row) => row.id });
|
|
271
|
-
* ```
|
|
272
|
-
*/
|
|
273
|
-
getRowId: (row: TRow) => string;
|
|
274
|
-
autosize?: boolean | AutosizeOptions;
|
|
275
|
-
/**
|
|
276
|
-
* Who applies filtering and sorting to the loaded records. Construction-time
|
|
277
|
-
* only.
|
|
278
|
-
*
|
|
279
|
-
* @experimental
|
|
280
|
-
*/
|
|
281
|
-
processing?: PretableProcessingOptions;
|
|
282
|
-
/**
|
|
283
|
-
* Fold group aggregates over rows the active filter hides. Default `false`,
|
|
284
|
-
* so a group total always equals the sum of the rows visible beneath it.
|
|
285
|
-
* `childCount` is post-filter either way.
|
|
286
|
-
*/
|
|
287
|
-
aggregateFilteredRows?: boolean;
|
|
288
|
-
/**
|
|
289
|
-
* Expanded state for groups with no entry in `groupExpansionOverrides`.
|
|
290
|
-
* Default `true`. Groups appearing mid-stream inherit it with no bookkeeping.
|
|
291
|
-
*/
|
|
292
|
-
groupsDefaultExpanded?: boolean;
|
|
293
|
-
/**
|
|
294
|
-
* How many per-group expand/collapse decisions the grid remembers. Default
|
|
295
|
-
* `10_000`. Past the limit the least-recently-decided group is forgotten and
|
|
296
|
-
* reverts to `groupsDefaultExpanded`.
|
|
297
|
-
*
|
|
298
|
-
* **Why a limit exists.** Expansion state is keyed by a path-derived group id
|
|
299
|
-
* rather than owned by a node, which is what lets a group survive emptying and
|
|
300
|
-
* returning mid-stream. The price is that ids for groups which never return
|
|
301
|
-
* would otherwise accumulate forever under a stream whose grouping keys churn.
|
|
302
|
-
*
|
|
303
|
-
* Values below 1 clamp to 1; a non-finite value other than `Infinity` falls
|
|
304
|
-
* back to the default. Pass `Infinity` to opt out of the cap entirely and
|
|
305
|
-
* accept unbounded growth.
|
|
306
|
-
*
|
|
307
|
-
* `expandAll()` / `collapseAll()` are unaffected — they flip the default and
|
|
308
|
-
* clear the set, so "collapse everything" costs one entry-free operation no
|
|
309
|
-
* matter how many groups exist.
|
|
310
|
-
*/
|
|
311
|
-
groupExpansionOverrideLimit?: number;
|
|
312
|
-
/**
|
|
313
|
-
* Configure the derived group column — the synthetic column that carries the
|
|
314
|
-
* label, twisty and child count for every grouping level. Present in
|
|
315
|
-
* `getColumns()` exactly while `rowGroups` is non-empty.
|
|
316
|
-
*/
|
|
317
|
-
groupColumn?: PretableGroupColumnOptions;
|
|
318
|
-
/**
|
|
319
|
-
* Drop the grouped columns from the data area while grouping is active.
|
|
320
|
-
* Default `true`, uniformly — whether the grouping came from `rowGroup: true`
|
|
321
|
-
* on a column or from a later `setRowGroups` call.
|
|
322
|
-
*/
|
|
323
|
-
hideGroupedColumns?: boolean;
|
|
771
|
+
/** Population size represented by a loaded result window. @experimental @public */
|
|
772
|
+
type PretableMatchingTotal = {
|
|
773
|
+
kind: "exact";
|
|
774
|
+
count: number;
|
|
775
|
+
} | {
|
|
776
|
+
kind: "estimate";
|
|
777
|
+
count: number;
|
|
778
|
+
} | {
|
|
779
|
+
kind: "unknown";
|
|
780
|
+
atLeast?: number;
|
|
781
|
+
};
|
|
782
|
+
/** Metadata accompanying a remotely fulfilled result window. @experimental @public */
|
|
783
|
+
interface PretableResultMeta {
|
|
784
|
+
total?: PretableMatchingTotal;
|
|
785
|
+
/** Stable identity for the query/result population represented by the rows. */
|
|
786
|
+
datasetKey?: string;
|
|
324
787
|
}
|
|
325
788
|
/**
|
|
326
789
|
* One entry in the ordered sort list; index in the list = priority.
|
|
@@ -381,321 +844,264 @@ interface PretableViewportState {
|
|
|
381
844
|
width: number;
|
|
382
845
|
}
|
|
383
846
|
/**
|
|
384
|
-
*
|
|
847
|
+
* Direction passed to the UI grid's focus movement action.
|
|
385
848
|
*
|
|
386
849
|
* @public
|
|
387
850
|
*/
|
|
388
|
-
|
|
389
|
-
add?: TRow[];
|
|
390
|
-
update?: Partial<TRow>[];
|
|
391
|
-
remove?: string[];
|
|
392
|
-
}
|
|
851
|
+
type PretableFocusDirection = "up" | "down" | "left" | "right";
|
|
393
852
|
/**
|
|
394
|
-
*
|
|
853
|
+
* Optional behavior modifiers for UI-grid focus movement.
|
|
395
854
|
*
|
|
396
855
|
* @public
|
|
397
856
|
*/
|
|
398
|
-
interface
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
sourceIndex: number;
|
|
403
|
-
/** Nesting depth beneath its group ancestors; `0` when ungrouped. */
|
|
404
|
-
depth: number;
|
|
857
|
+
interface PretableMoveFocusOptions {
|
|
858
|
+
extend?: boolean;
|
|
859
|
+
jumpToEdge?: boolean;
|
|
860
|
+
byPage?: boolean;
|
|
405
861
|
}
|
|
406
|
-
/**
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
*/
|
|
411
|
-
interface PretableGroupRow {
|
|
412
|
-
kind: "group";
|
|
413
|
-
/** Stable, path-derived id (see `makeGroupId`). */
|
|
414
|
-
id: string;
|
|
415
|
-
/** Nesting depth; the outermost group level is `0`. */
|
|
416
|
-
depth: number;
|
|
417
|
-
/** The column this level groups by. */
|
|
418
|
-
columnId: string;
|
|
419
|
-
/** The group key value, as read from the grouping column. */
|
|
420
|
-
value: unknown;
|
|
421
|
-
/** Data rows beneath this group, post-filter. */
|
|
422
|
-
childCount: number;
|
|
423
|
-
/** Finalized aggregate values, keyed by column id. */
|
|
424
|
-
aggregates: Record<string, unknown>;
|
|
862
|
+
/** A typed data-cell address owned by the indexed UI layer. @public */
|
|
863
|
+
interface PretableIndexedCellAddress<TRowId extends PretableRowId, TColumnId extends string> {
|
|
864
|
+
readonly rowId: TRowId;
|
|
865
|
+
readonly columnId: TColumnId;
|
|
425
866
|
}
|
|
426
|
-
/**
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
*
|
|
431
|
-
* @public
|
|
432
|
-
*/
|
|
433
|
-
type PretableVisibleRow<TRow extends PretableRow = PretableRow> = PretableDataRow<TRow> | PretableGroupRow;
|
|
434
|
-
/**
|
|
435
|
-
* An aggregate function, defined as a monoid rather than as `(values) => result`.
|
|
436
|
-
*
|
|
437
|
-
* The engine folds over a group's descendant leaf rows (`init`, then
|
|
438
|
-
* `accumulate` per leaf, then `finalize`), so order-sensitive statistics such as
|
|
439
|
-
* median remain expressible. `merge` must nevertheless be associative with
|
|
440
|
-
* `init()` as its identity: that contract is what allows a future switch to
|
|
441
|
-
* child-aggregate rollup to be a pure internal optimization instead of a
|
|
442
|
-
* breaking change to every consumer's aggregate function.
|
|
443
|
-
*
|
|
444
|
-
* `accumulate` may mutate and return `acc` — the engine hands each fold a fresh
|
|
445
|
-
* `init()` and never retains an earlier accumulator. `merge` must NOT mutate
|
|
446
|
-
* either argument.
|
|
447
|
-
*
|
|
448
|
-
* @public
|
|
449
|
-
*/
|
|
450
|
-
interface PretableAggregator<TAcc = unknown, TOut = unknown> {
|
|
451
|
-
/** Empty accumulator. */
|
|
452
|
-
init(): TAcc;
|
|
453
|
-
/** Fold one leaf cell value into the accumulator. */
|
|
454
|
-
accumulate(acc: TAcc, value: unknown, row: PretableRow): TAcc;
|
|
455
|
-
/** Combine two accumulators (must be associative; `init()` is the identity). */
|
|
456
|
-
merge(a: TAcc, b: TAcc): TAcc;
|
|
457
|
-
/** Produce the display value — always a plain scalar, never a wrapper object. */
|
|
458
|
-
finalize(acc: TAcc): TOut;
|
|
867
|
+
/** Inclusive data-cell range; group rows can never be endpoints. @public */
|
|
868
|
+
interface PretableIndexedCellRange<TRowId extends PretableRowId, TColumnId extends string> {
|
|
869
|
+
readonly start: PretableIndexedCellAddress<TRowId, TColumnId>;
|
|
870
|
+
readonly end: PretableIndexedCellAddress<TRowId, TColumnId>;
|
|
459
871
|
}
|
|
460
|
-
/**
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
type PretableMatchingTotal = {
|
|
476
|
-
kind: "exact";
|
|
477
|
-
count: number;
|
|
478
|
-
} | {
|
|
479
|
-
kind: "estimate";
|
|
480
|
-
count: number;
|
|
872
|
+
/** Inclusive data-row span stored by its stable endpoint IDs. @public */
|
|
873
|
+
interface PretableIndexedRowRange<TRowId extends PretableRowId> {
|
|
874
|
+
readonly startRowId: TRowId;
|
|
875
|
+
readonly endRowId: TRowId;
|
|
876
|
+
}
|
|
877
|
+
/** Immutable normalized interval index for symbolic row selections. @public */
|
|
878
|
+
interface PretableIndexedRowRangeIndex<TRowId extends PretableRowId> extends Iterable<PretableIndexedRowRange<TRowId>> {
|
|
879
|
+
readonly size: number;
|
|
880
|
+
}
|
|
881
|
+
/** Sparse row-checkbox state. Select-all never materializes the data population. @public */
|
|
882
|
+
type PretableIndexedRowSelection<TRowId extends PretableRowId> = {
|
|
883
|
+
readonly kind: "explicit";
|
|
884
|
+
readonly rowIds: ReadonlySet<TRowId>;
|
|
885
|
+
readonly ranges?: PretableIndexedRowRangeIndex<TRowId>;
|
|
886
|
+
readonly excludedRanges?: PretableIndexedRowRangeIndex<TRowId>;
|
|
481
887
|
} | {
|
|
482
|
-
kind: "
|
|
483
|
-
|
|
888
|
+
readonly kind: "all";
|
|
889
|
+
readonly excludedRanges?: PretableIndexedRowRangeIndex<TRowId>;
|
|
484
890
|
};
|
|
485
|
-
/**
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
*/
|
|
498
|
-
interface
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
891
|
+
/** Data-only selection owned by the indexed UI layer. @public */
|
|
892
|
+
interface PretableIndexedSelectionState<TRowId extends PretableRowId, TColumnId extends string> {
|
|
893
|
+
readonly rows: PretableIndexedRowSelection<TRowId>;
|
|
894
|
+
readonly ranges: readonly PretableIndexedCellRange<TRowId, TColumnId>[];
|
|
895
|
+
readonly anchor: PretableIndexedCellAddress<TRowId, TColumnId> | null;
|
|
896
|
+
}
|
|
897
|
+
/** Header-checkbox state derived without visiting every visible row. @public */
|
|
898
|
+
interface PretableIndexedSelectionSummary {
|
|
899
|
+
readonly state: "none" | "some" | "all";
|
|
900
|
+
readonly selectedCount: number;
|
|
901
|
+
readonly visibleCount: number;
|
|
902
|
+
}
|
|
903
|
+
/** Group and data rows share one focus path while preserving runtime identity. @public */
|
|
904
|
+
interface PretableIndexedFocusState<TRowId extends PretableRowId, TColumnId extends string> {
|
|
905
|
+
readonly ref: PretableVisibleRowRef<TRowId> | null;
|
|
906
|
+
readonly columnId: TColumnId | null;
|
|
907
|
+
}
|
|
908
|
+
/** Keyboard movements supported by indexed focus navigation. @public */
|
|
909
|
+
type PretableIndexedFocusMovement = "up" | "down" | "left" | "right" | "page-up" | "page-down" | "home" | "end" | "tab" | "shift-tab" | "parent";
|
|
910
|
+
/** Visual-column input; derivation behavior remains in the row model. @public */
|
|
911
|
+
interface PretableGridUiColumn<TColumnId extends string> {
|
|
912
|
+
readonly id: TColumnId;
|
|
913
|
+
readonly widthPx?: number;
|
|
914
|
+
readonly pinned?: "left" | "right";
|
|
915
|
+
}
|
|
916
|
+
/** Normalized visual-only column layout published by the UI store. @public */
|
|
917
|
+
interface PretableGridUiColumnLayout<TColumnId extends string> {
|
|
918
|
+
readonly id: TColumnId;
|
|
919
|
+
readonly widthPx: number;
|
|
920
|
+
readonly pinned?: "left" | "right";
|
|
921
|
+
}
|
|
922
|
+
/** A correlated, data-row-only editing session. @public */
|
|
923
|
+
type PretableIndexedEditingState<TRowId extends PretableRowId, TColumns> = {
|
|
924
|
+
readonly [TColumnId in ColumnIdOf<TColumns>]: {
|
|
925
|
+
readonly rowId: TRowId;
|
|
926
|
+
readonly columnId: TColumnId;
|
|
927
|
+
readonly value: ColumnValueOf<TColumns, TColumnId>;
|
|
928
|
+
readonly status: "editing" | "validating" | "saving" | "error";
|
|
929
|
+
readonly error?: string;
|
|
930
|
+
};
|
|
931
|
+
}[ColumnIdOf<TColumns>];
|
|
932
|
+
/** The long-lived grid store's complete observable UI state. @public */
|
|
933
|
+
interface PretableGridUiState<TRowId extends PretableRowId, TColumns> {
|
|
934
|
+
readonly viewport: Readonly<PretableViewportState>;
|
|
935
|
+
readonly focus: Readonly<PretableIndexedFocusState<TRowId, ColumnIdOf<TColumns>>>;
|
|
936
|
+
readonly selection: Readonly<PretableIndexedSelectionState<TRowId, ColumnIdOf<TColumns>>>;
|
|
937
|
+
readonly editing: PretableIndexedEditingState<TRowId, TColumns> | null;
|
|
938
|
+
readonly columnLayout: readonly Readonly<PretableGridUiColumnLayout<ColumnIdOf<TColumns>>>[];
|
|
939
|
+
readonly observedRowModelRevision: number | null;
|
|
511
940
|
}
|
|
941
|
+
declare const gridUiCoreType: unique symbol;
|
|
942
|
+
/** Framework-independent UI-only indexed grid store. @public */
|
|
943
|
+
interface PretableGridUiCore<TRow extends object, TRowId extends PretableRowId, TColumns> {
|
|
944
|
+
readonly rowModel: PretableRowModel<TRow, TRowId, TColumns>;
|
|
945
|
+
readonly getState: () => PretableGridUiState<TRowId, TColumns>;
|
|
946
|
+
readonly subscribe: (listener: () => void) => () => void;
|
|
947
|
+
readonly setViewport: (viewport: PretableViewportState) => void;
|
|
948
|
+
readonly setFocus: (focus: PretableIndexedFocusState<TRowId, ColumnIdOf<TColumns>>) => void;
|
|
949
|
+
readonly moveFocus: (movement: PretableIndexedFocusMovement, options?: {
|
|
950
|
+
readonly pageRows?: number;
|
|
951
|
+
}) => void;
|
|
952
|
+
readonly setSelection: (selection: PretableIndexedSelectionState<TRowId, ColumnIdOf<TColumns>>) => void;
|
|
953
|
+
readonly toggleRowSelection: (rowId: TRowId) => void;
|
|
954
|
+
readonly selectRowRange: (startRowId: TRowId, endRowId: TRowId) => void;
|
|
955
|
+
readonly isRowSelected: (rowId: TRowId) => boolean;
|
|
956
|
+
readonly getSelectionSummary: () => PretableIndexedSelectionSummary;
|
|
957
|
+
readonly selectAllVisibleRows: () => void;
|
|
958
|
+
readonly clearSelection: () => void;
|
|
959
|
+
readonly beginEdit: <TColumnId extends ColumnIdOf<TColumns>>(input: {
|
|
960
|
+
readonly rowId: TRowId;
|
|
961
|
+
readonly columnId: TColumnId;
|
|
962
|
+
readonly value: ColumnValueOf<TColumns, TColumnId>;
|
|
963
|
+
}) => void;
|
|
964
|
+
readonly setEditDraft: (value: unknown) => void;
|
|
965
|
+
readonly setEditStatus: (status: "editing" | "validating" | "saving" | "error", error?: string) => void;
|
|
966
|
+
readonly cancelEdit: () => void;
|
|
967
|
+
/** Reconciles the current visual column set without changing row schema. */
|
|
968
|
+
readonly setColumns: (columns: readonly PretableGridUiColumn<ColumnIdOf<TColumns>>[]) => void;
|
|
969
|
+
readonly setColumnWidth: (columnId: ColumnIdOf<TColumns>, width: number) => void;
|
|
970
|
+
readonly setColumnPinned: (columnId: ColumnIdOf<TColumns>, pinned: "left" | "right" | null) => void;
|
|
971
|
+
readonly setColumnOrder: (columnIds: readonly ColumnIdOf<TColumns>[]) => void;
|
|
972
|
+
/** @internal Called only after renderer geometry for this exact revision exists. */
|
|
973
|
+
readonly observeRowModelRevision: (revision: number) => void;
|
|
974
|
+
readonly dispose: () => void;
|
|
975
|
+
/** @internal Compile-time-only invariant descriptor. */
|
|
976
|
+
readonly [gridUiCoreType]?: (value: readonly [TRow, TRowId, TColumns]) => readonly [TRow, TRowId, TColumns];
|
|
977
|
+
}
|
|
978
|
+
|
|
979
|
+
/** Options accepted by the UI-only grid facade. @public */
|
|
980
|
+
interface CreateGridUiCoreOptions<TRow extends object, TRowId extends PretableRowId, TColumns> {
|
|
981
|
+
readonly rowModel: PretableRowModel<TRow, TRowId, TColumns>;
|
|
982
|
+
readonly columns: readonly PretableGridUiColumn<ColumnIdOf<TColumns>>[];
|
|
983
|
+
readonly viewport?: PretableViewportState;
|
|
984
|
+
}
|
|
985
|
+
|
|
512
986
|
/**
|
|
513
|
-
*
|
|
987
|
+
* Half-open row index range — `start` inclusive, `end` exclusive — used to
|
|
988
|
+
* describe a visible row window without materializing the rows outside it.
|
|
514
989
|
*
|
|
515
990
|
* @public
|
|
516
991
|
*/
|
|
517
|
-
interface
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
filters: Record<string, ColumnFilter>;
|
|
521
|
-
selection: PretableSelectionState;
|
|
522
|
-
focus: PretableFocusState;
|
|
523
|
-
/** Count of loaded source records — not the matching population. */
|
|
524
|
-
loadedRowCount: number;
|
|
525
|
-
/**
|
|
526
|
-
* Engine filter authority: computed locally and always exact (post-filter,
|
|
527
|
-
* pre-grouping). External filter authority: the last supplied
|
|
528
|
-
* `resultMeta.total`, else `{ kind: "unknown" }`.
|
|
529
|
-
*
|
|
530
|
-
* @experimental
|
|
531
|
-
*/
|
|
532
|
-
matchingTotal: PretableMatchingTotal;
|
|
533
|
-
/**
|
|
534
|
-
* The last supplied dataset identity; `null` before any. Local mode never
|
|
535
|
-
* changes it.
|
|
536
|
-
*
|
|
537
|
-
* @experimental
|
|
538
|
-
*/
|
|
539
|
-
datasetKey: string | null;
|
|
540
|
-
visibleRows: PretableVisibleRow<TRow>[];
|
|
541
|
-
visibleRange: PretableRowRange;
|
|
542
|
-
editing: PretableEditState | null;
|
|
543
|
-
/** Grouping columns, outermost first; `[]` when ungrouped. */
|
|
544
|
-
rowGroups: string[];
|
|
545
|
-
/** Group ids whose expanded state differs from {@link groupsDefaultExpanded}. */
|
|
546
|
-
groupExpansionOverrides: ReadonlySet<string>;
|
|
547
|
-
/** Expanded state for every group with no entry in the override set. */
|
|
548
|
-
groupsDefaultExpanded: boolean;
|
|
992
|
+
interface PretableRowRange {
|
|
993
|
+
start: number;
|
|
994
|
+
end: number;
|
|
549
995
|
}
|
|
550
996
|
/**
|
|
551
|
-
*
|
|
997
|
+
* Tuning knobs for column autosize calculations.
|
|
552
998
|
*
|
|
553
999
|
* @public
|
|
554
1000
|
*/
|
|
555
|
-
|
|
1001
|
+
interface AutosizeOptions {
|
|
1002
|
+
maxWidthPx?: number;
|
|
1003
|
+
minWidthPx?: number;
|
|
1004
|
+
averageCharWidth?: number;
|
|
1005
|
+
cellPaddingPx?: number;
|
|
1006
|
+
}
|
|
1007
|
+
|
|
1008
|
+
/** Id of the synthetic visual column that carries grouped row labels. @public */
|
|
1009
|
+
declare const GROUP_COLUMN_ID = "__pretable_group__";
|
|
1010
|
+
/** Presentation options for the synthetic grouped-row column. @public */
|
|
1011
|
+
interface PretableGroupColumnOptions {
|
|
1012
|
+
/** Header text. Defaults to the first grouped column's header. */
|
|
1013
|
+
header?: string;
|
|
1014
|
+
/** Column width. Defaults to 200 pixels. */
|
|
1015
|
+
widthPx?: number;
|
|
1016
|
+
/** Pin the group column to the left. */
|
|
1017
|
+
pinned?: "left";
|
|
1018
|
+
}
|
|
1019
|
+
|
|
556
1020
|
/**
|
|
557
|
-
*
|
|
1021
|
+
* Create a framework-independent UI-state grid over an explicit indexed row
|
|
1022
|
+
* model. Data, queries, grouping, aggregation, and expansion remain owned by
|
|
1023
|
+
* `rowModel`; this handle owns only focus, selection, editing, viewport, and
|
|
1024
|
+
* visual column layout.
|
|
558
1025
|
*
|
|
559
1026
|
* @public
|
|
560
1027
|
*/
|
|
561
|
-
|
|
562
|
-
extend?: boolean;
|
|
563
|
-
jumpToEdge?: boolean;
|
|
564
|
-
byPage?: boolean;
|
|
565
|
-
}
|
|
1028
|
+
declare function createGrid<TRow extends object, TRowId extends PretableRowId, TColumns>(options: CreateGridUiCoreOptions<TRow, TRowId, TColumns>): PretableGridUiCore<TRow, TRowId, TColumns>;
|
|
566
1029
|
|
|
567
1030
|
/**
|
|
568
|
-
*
|
|
1031
|
+
* Creates a typed column-definition helper for an ordinary row object.
|
|
569
1032
|
*
|
|
570
1033
|
* @public
|
|
571
1034
|
*/
|
|
572
|
-
|
|
1035
|
+
declare function createColumnHelper<TRow extends object>(): PretableColumnHelper<TRow>;
|
|
573
1036
|
|
|
1037
|
+
/** Options for a local row model with an explicit row-ID accessor. @public */
|
|
1038
|
+
interface CreateLocalRowModelOptions<TColumns, TRowId extends PretableRowId> {
|
|
1039
|
+
readonly rows: readonly (TColumns extends readonly [
|
|
1040
|
+
infer TFirstColumn,
|
|
1041
|
+
...(readonly unknown[])
|
|
1042
|
+
] ? TFirstColumn extends {
|
|
1043
|
+
readonly accessor: (row: infer TRow extends object) => infer TValue;
|
|
1044
|
+
} ? [TValue] extends [unknown] ? TRow : never : never : never)[];
|
|
1045
|
+
readonly columns: TColumns & {
|
|
1046
|
+
readonly [K in keyof TColumns]: TColumns[K] extends {
|
|
1047
|
+
readonly accessor: (row: infer TColumnRow extends object) => infer TColumnValue;
|
|
1048
|
+
} ? [TColumnValue] extends [unknown] ? TColumns extends readonly [
|
|
1049
|
+
infer TFirstColumn,
|
|
1050
|
+
...(readonly unknown[])
|
|
1051
|
+
] ? TFirstColumn extends {
|
|
1052
|
+
readonly accessor: (row: infer TFirstRow extends object) => infer TFirstValue;
|
|
1053
|
+
} ? [TFirstValue] extends [unknown] ? [TColumnRow] extends [TFirstRow] ? [TFirstRow] extends [TColumnRow] ? TColumns[K] : never : never : never : never : never : never : never;
|
|
1054
|
+
};
|
|
1055
|
+
readonly derivations?: PretableDerivationsFor<TColumns>;
|
|
1056
|
+
readonly query?: PretableQueryFor<TColumns>;
|
|
1057
|
+
readonly initialExpansion?: PretableExpansionDefault;
|
|
1058
|
+
readonly aggregateFilteredRows?: boolean;
|
|
1059
|
+
readonly getRowId: (row: TColumns extends readonly [infer TFirstColumn, ...(readonly unknown[])] ? TFirstColumn extends {
|
|
1060
|
+
readonly accessor: (row: infer TRow extends object) => infer TValue;
|
|
1061
|
+
} ? [TValue] extends [unknown] ? TRow : never : never : never) => TRowId;
|
|
1062
|
+
}
|
|
1063
|
+
/** Options for a local row model using the conventional `row.id`. @public */
|
|
1064
|
+
type CreateLocalRowModelWithDefaultIdOptions<TColumns> = (TColumns extends readonly [infer TFirstColumn, ...(readonly unknown[])] ? TFirstColumn extends {
|
|
1065
|
+
readonly accessor: (row: infer TRow extends object) => infer TValue;
|
|
1066
|
+
} ? [TValue] extends [unknown] ? TRow : never : never : never) extends {
|
|
1067
|
+
readonly id: PretableRowId;
|
|
1068
|
+
} ? Prettify<{
|
|
1069
|
+
readonly rows: readonly (TColumns extends readonly [
|
|
1070
|
+
infer TFirstColumn,
|
|
1071
|
+
...(readonly unknown[])
|
|
1072
|
+
] ? TFirstColumn extends {
|
|
1073
|
+
readonly accessor: (row: infer TRow extends object) => infer TValue;
|
|
1074
|
+
} ? [TValue] extends [unknown] ? TRow : never : never : never)[];
|
|
1075
|
+
readonly columns: TColumns & {
|
|
1076
|
+
readonly [K in keyof TColumns]: TColumns[K] extends {
|
|
1077
|
+
readonly accessor: (row: infer TColumnRow extends object) => infer TColumnValue;
|
|
1078
|
+
} ? [TColumnValue] extends [unknown] ? TColumns extends readonly [
|
|
1079
|
+
infer TFirstColumn,
|
|
1080
|
+
...(readonly unknown[])
|
|
1081
|
+
] ? TFirstColumn extends {
|
|
1082
|
+
readonly accessor: (row: infer TFirstRow extends object) => infer TFirstValue;
|
|
1083
|
+
} ? [TFirstValue] extends [unknown] ? [TColumnRow] extends [TFirstRow] ? [TFirstRow] extends [TColumnRow] ? TColumns[K] : never : never : never : never : never : never : never;
|
|
1084
|
+
};
|
|
1085
|
+
readonly derivations?: PretableDerivationsFor<TColumns>;
|
|
1086
|
+
readonly query?: PretableQueryFor<TColumns>;
|
|
1087
|
+
readonly initialExpansion?: PretableExpansionDefault;
|
|
1088
|
+
readonly aggregateFilteredRows?: boolean;
|
|
1089
|
+
readonly getRowId?: undefined;
|
|
1090
|
+
}> : never;
|
|
574
1091
|
/**
|
|
575
|
-
*
|
|
576
|
-
* observation pretable promises to support; does not extend the internal
|
|
577
|
-
* engine type, so private methods cannot leak through the public surface.
|
|
1092
|
+
* Creates a local row model using the conventional `row.id` field.
|
|
578
1093
|
*
|
|
579
1094
|
* @public
|
|
580
1095
|
*/
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
/** The options the grid was constructed with. */
|
|
585
|
-
readonly options: PretableGridOptions<TRow>;
|
|
586
|
-
/** Subscribe to grid mutations. Returns an unsubscribe function. */
|
|
587
|
-
subscribe(listener: () => void): () => void;
|
|
588
|
-
/** Read the current snapshot. Stable reference until the next mutation. */
|
|
589
|
-
getSnapshot(): PretableGridSnapshot<TRow>;
|
|
590
|
-
/**
|
|
591
|
-
* The columns to draw: `options.columns` plus the derived group column, minus
|
|
592
|
-
* the grouped columns, while grouping is active. Identical to
|
|
593
|
-
* `options.columns` — by identity — when ungrouped. Stable reference until
|
|
594
|
-
* the columns or the grouping levels change.
|
|
595
|
-
*/
|
|
596
|
-
getColumns(): readonly PretableColumn<TRow>[];
|
|
597
|
-
setSort(columnId: string | null, direction: PretableSortDirection): void;
|
|
598
|
-
/** Atomically replace the ordered sort list. Unknown and `sortable: false` columns are dropped. */
|
|
599
|
-
replaceSort(entries: PretableSortEntry[]): void;
|
|
600
|
-
setColumnFilter(columnId: string, filter: ColumnFilter | null): void;
|
|
601
|
-
clearFilters(): void;
|
|
602
|
-
replaceFilters(nextFilters: Record<string, ColumnFilter>): void;
|
|
603
|
-
/**
|
|
604
|
-
* The distinct values a column takes across the LOADED records — never a
|
|
605
|
-
* claim about the matching population. Under external filter authority the
|
|
606
|
-
* loaded records are a window onto the result set, so this list can omit
|
|
607
|
-
* values the user would need to filter for; declare `column.options` to give
|
|
608
|
-
* an enum filter its full universe. The surface dev-warns when a funnel menu
|
|
609
|
-
* falls back to this list in that mode.
|
|
610
|
-
*/
|
|
611
|
-
distinctColumnValues(columnId: string): string[];
|
|
612
|
-
setSelection(state: PretableSelectionState): void;
|
|
613
|
-
selectAll(): void;
|
|
614
|
-
clearSelection(): void;
|
|
615
|
-
addRange(range: PretableCellRange): void;
|
|
616
|
-
extendRangeFromAnchor(addr: PretableCellAddress): void;
|
|
617
|
-
toggleRowSelection(rowId: string): void;
|
|
618
|
-
setSelectAllVisible(checked: boolean): void;
|
|
619
|
-
setFocus(addr: PretableCellAddress | null): void;
|
|
620
|
-
moveFocus(direction: PretableFocusDirection, options?: PretableMoveFocusOptions): void;
|
|
621
|
-
/**
|
|
622
|
-
* Replace the grouping levels, outermost first; `[]` ungroups. Ids that do
|
|
623
|
-
* not match a column are dropped, and expansion state for groups that no
|
|
624
|
-
* longer exist is pruned.
|
|
625
|
-
*/
|
|
626
|
-
setRowGroups(columnIds: readonly string[]): void;
|
|
627
|
-
/** Flip one group's expanded state. Unknown ids are still recorded. */
|
|
628
|
-
toggleGroup(groupId: string): void;
|
|
629
|
-
/** Set one group's expanded state explicitly. */
|
|
630
|
-
setGroupExpanded(groupId: string, expanded: boolean): void;
|
|
631
|
-
/** Expand every group, including ones that do not exist yet. */
|
|
632
|
-
expandAll(): void;
|
|
633
|
-
/** Collapse every group, including ones that do not exist yet. */
|
|
634
|
-
collapseAll(): void;
|
|
635
|
-
setViewport(viewport: PretableViewportState): void;
|
|
636
|
-
autosizeColumns(options?: AutosizeOptions): void;
|
|
637
|
-
setColumnWidth(columnId: string, width: number): void;
|
|
638
|
-
moveColumn(columnId: string, toIndex: number): void;
|
|
639
|
-
/**
|
|
640
|
-
* Set the relative order of the columns. Ids that do not match a column are
|
|
641
|
-
* ignored, and columns absent from `ids` keep their current relative order at
|
|
642
|
-
* the end. Pin state is never read from `ids` nor changed: the result is
|
|
643
|
-
* regrouped into `[pinned "left"…, unpinned…, pinned "right"…]`, so an order
|
|
644
|
-
* that interleaves pinned and unpinned columns is normalised rather than
|
|
645
|
-
* honoured literally.
|
|
646
|
-
*/
|
|
647
|
-
setColumnOrder(ids: readonly string[]): void;
|
|
648
|
-
setColumnPinned(columnId: string, pinned: "left" | "right" | null): void;
|
|
649
|
-
autosizeColumn(columnId: string, options?: AutosizeOptions): void;
|
|
650
|
-
resetColumnLayout(): void;
|
|
651
|
-
mergeColumnsFromProps(nextColumns: PretableColumn<TRow>[]): void;
|
|
652
|
-
applyTransaction(transaction: PretableTransaction<TRow>): void;
|
|
653
|
-
/**
|
|
654
|
-
* Replace the full row set in place. Unlike recreating the grid, this
|
|
655
|
-
* preserves selection and focus (both keyed by row id), dropping only the
|
|
656
|
-
* references whose rows are no longer present. Suited to high-frequency
|
|
657
|
-
* updates where row identities are stable.
|
|
658
|
-
*/
|
|
659
|
-
setRows(rows: TRow[], meta?: PretableResultMeta): void;
|
|
660
|
-
/**
|
|
661
|
-
* Update result metadata without a rows replacement — a late-arriving exact
|
|
662
|
-
* count, say. Avoids forcing a fake rows-identity change.
|
|
663
|
-
*
|
|
664
|
-
* @experimental
|
|
665
|
-
*/
|
|
666
|
-
setResultMeta(meta: PretableResultMeta): void;
|
|
667
|
-
beginEdit(addr: PretableCellAddress, opts?: {
|
|
668
|
-
draft?: unknown;
|
|
669
|
-
status?: "checking" | "editing";
|
|
670
|
-
}): void;
|
|
671
|
-
setEditDraft(value: unknown): void;
|
|
672
|
-
markEditing(): void;
|
|
673
|
-
markEditValidating(): void;
|
|
674
|
-
markEditSaving(): void;
|
|
675
|
-
markEditInvalid(message: string): void;
|
|
676
|
-
markEditError(message: string): void;
|
|
677
|
-
commitEditSucceeded(): void;
|
|
678
|
-
cancelEdit(): void;
|
|
679
|
-
}
|
|
680
|
-
|
|
1096
|
+
declare function createLocalRowModel<const TColumns extends readonly [unknown, ...(readonly unknown[])]>(options: CreateLocalRowModelWithDefaultIdOptions<TColumns>): PretableRowModel<CreateLocalRowModelWithDefaultIdOptions<TColumns>["rows"][number], CreateLocalRowModelWithDefaultIdOptions<TColumns>["rows"][number] extends {
|
|
1097
|
+
readonly id: infer TRowId extends PretableRowId;
|
|
1098
|
+
} ? TRowId : never, TColumns>;
|
|
681
1099
|
/**
|
|
682
|
-
*
|
|
683
|
-
* that exposes every action and observation pretable supports.
|
|
684
|
-
*
|
|
685
|
-
* @example
|
|
686
|
-
* ```ts
|
|
687
|
-
* const grid = createGrid({
|
|
688
|
-
* columns: [{ id: "name" }, { id: "age" }],
|
|
689
|
-
* rows: [{ id: "1", name: "Ada", age: 36 }],
|
|
690
|
-
* getRowId: (row) => row.id,
|
|
691
|
-
* });
|
|
692
|
-
* grid.setSort("age", "desc");
|
|
693
|
-
* const snapshot = grid.getSnapshot();
|
|
694
|
-
* ```
|
|
1100
|
+
* Creates a local row model using an explicit string or number row ID.
|
|
695
1101
|
*
|
|
696
1102
|
* @public
|
|
697
1103
|
*/
|
|
698
|
-
declare function
|
|
1104
|
+
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>;
|
|
699
1105
|
|
|
700
1106
|
/**
|
|
701
1107
|
* Options for Pretable's currency number-format presets.
|
|
@@ -715,4 +1121,4 @@ declare const numberFormats: {
|
|
|
715
1121
|
readonly accounting: (options: PretableCurrencyFormatOptions) => Intl.NumberFormatOptions;
|
|
716
1122
|
};
|
|
717
1123
|
|
|
718
|
-
export { type AutosizeOptions, type ColumnAlign, type ColumnFilter, type ColumnOption, type ColumnType, type FilterOperator, type FilterValue, GROUP_COLUMN_ID, type PretableAggregateFormatInput, type PretableAggregateSpec, type PretableAggregator, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableCurrencyFormatOptions, type PretableDataRow, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type
|
|
1124
|
+
export { type AutosizeOptions, type ColumnAggregateValueOf, type ColumnAlign, type ColumnFilter, type ColumnIdOf, type ColumnOption, type ColumnType, type ColumnValueOf, type ColumnsOf, type CreateGridUiCoreOptions, type CreateLocalRowModelOptions, type CreateLocalRowModelWithDefaultIdOptions, type FilterOperator, type FilterValue, GROUP_COLUMN_ID, type PretableAggregateFormatInput, type PretableAggregateOutputOf, type PretableAggregateSpec, type PretableAggregatesFor, type PretableAggregator, type PretableBuiltinAggregate, type PretableCellAddress, type PretableCellRange, type PretableChangeOperation, type PretableChangeSequence, type PretableChangeSet, type PretableColumn, type PretableColumnAccessorKind, type PretableColumnCallbackContext, type PretableColumnDefinition, type PretableColumnDerivation, type PretableColumnHelper, type PretableColumnOptions, type PretableColumnType, type PretableColumnTypeFor, type PretableCompatibleAggregateSpec, type PretableCompatibleAggregator, type PretableCurrencyFormatOptions, type PretableDataRow, type PretableDerivationTransition, type PretableDerivationsFor, PretableDisposedModelError, type PretableDistinctColumnIdOf, type PretableDistinctValueOptions, type PretableDistinctValueQuery, type PretableDistinctValueResult, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableExpansionDefault, type PretableExpansionState, type PretableFilterFor, type PretableFilterOperandFor, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGridUiColumn, type PretableGridUiColumnLayout, type PretableGridUiCore, type PretableGridUiState, type PretableGroupColumnOptions, type PretableGroupId, type PretableGroupKey, type PretableGroupRow, type PretableIndexedCellAddress, type PretableIndexedCellRange, type PretableIndexedEditingState, type PretableIndexedFocusMovement, type PretableIndexedFocusState, type PretableIndexedRowRange, type PretableIndexedRowRangeIndex, type PretableIndexedRowSelection, type PretableIndexedSelectionState, type PretableIndexedSelectionSummary, PretableInvalidGroupKeyError, type PretableMatchingTotal, type PretableMoveFocusOptions, type PretableMutationIssue, type PretableMutationResult, type PretableProcessingAuthority, type PretableProcessingOptions, type PretableQueryFor, type PretableQueryTransition, PretableReentrantMutationError, type PretableResultMeta, type PretableRow, type PretableRowGroupFor, type PretableRowId, PretableRowIdentityChangeError, type PretableRowModel, PretableRowModelError, type PretableRowModelErrorCode, type PretableRowModelErrorContext, type PretableRowModelOperation, type PretableRowModelSnapshot, type PretableRowModelState, type PretableRowModelStatus, type PretableRowRange, type PretableRowUpdate, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableSortFor, type PretableTransaction, type PretableTransitionCancellationReason, PretableTransitionCancelledError, PretableUnsupportedRowUpdateError, type PretableViewportState, type PretableVisibleRow, type PretableVisibleRowField, type PretableVisibleRowRef, type Prettify, type RowIdOf, type RowOf, createColumnHelper, createGrid, createLocalRowModel, numberFormats };
|