@constructive-io/sheets 0.13.1 → 0.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +231 -148
- package/dist/advanced.cjs +7220 -4030
- package/dist/advanced.cjs.map +1 -1
- package/dist/advanced.d.cts +2 -2
- package/dist/advanced.d.ts +2 -2
- package/dist/advanced.js +5 -5
- package/dist/auth.cjs.map +1 -1
- package/dist/auth.js +3 -3
- package/dist/chunk-CJ4PRA64.js +312 -0
- package/dist/chunk-CJ4PRA64.js.map +1 -0
- package/dist/chunk-II3MSNRO.js +18 -0
- package/dist/chunk-II3MSNRO.js.map +1 -0
- package/dist/{chunk-MXVNIKES.js → chunk-J7KK4UWI.js} +6 -6
- package/dist/chunk-MBSHDF55.js +839 -0
- package/dist/chunk-MBSHDF55.js.map +1 -0
- package/dist/{chunk-ZKANUG3F.js → chunk-MOFFS5WQ.js} +20 -15
- package/dist/chunk-MOFFS5WQ.js.map +1 -0
- package/dist/chunk-VCBY2AMT.js +8920 -0
- package/dist/chunk-VCBY2AMT.js.map +1 -0
- package/dist/{chunk-H5HR5HUJ.js → chunk-ZOQDSOMO.js} +50 -312
- package/dist/chunk-ZOQDSOMO.js.map +1 -0
- package/dist/date-editor-ORCB43ZM.js +346 -0
- package/dist/date-editor-ORCB43ZM.js.map +1 -0
- package/dist/grid-cell-types-YNIVK4hN.d.cts +346 -0
- package/dist/grid-cell-types-YNIVK4hN.d.ts +346 -0
- package/dist/index.cjs +22910 -12084
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1497 -337
- package/dist/index.d.ts +1497 -337
- package/dist/index.js +12833 -6142
- package/dist/index.js.map +1 -1
- package/dist/sheets-context-Bb7ZoNBg.d.cts +436 -0
- package/dist/sheets-context-CPuf31LS.d.ts +436 -0
- package/dist/testing.cjs +1253 -638
- package/dist/testing.cjs.map +1 -1
- package/dist/testing.d.cts +80 -11
- package/dist/testing.d.ts +80 -11
- package/dist/testing.js +791 -148
- package/dist/testing.js.map +1 -1
- package/package.json +5 -5
- package/dist/chunk-4EZ6A23C.js +0 -44
- package/dist/chunk-4EZ6A23C.js.map +0 -1
- package/dist/chunk-5QPNOKMA.js +0 -4397
- package/dist/chunk-5QPNOKMA.js.map +0 -1
- package/dist/chunk-AYMXT3ME.js +0 -540
- package/dist/chunk-AYMXT3ME.js.map +0 -1
- package/dist/chunk-H5HR5HUJ.js.map +0 -1
- package/dist/chunk-PZL2BCWF.js +0 -168
- package/dist/chunk-PZL2BCWF.js.map +0 -1
- package/dist/chunk-X7DHTSOX.js +0 -21
- package/dist/chunk-X7DHTSOX.js.map +0 -1
- package/dist/chunk-ZKANUG3F.js.map +0 -1
- package/dist/date-editor-ZFNDKYBD.js +0 -358
- package/dist/date-editor-ZFNDKYBD.js.map +0 -1
- package/dist/grid-cell-types-Pbe2m2tE.d.cts +0 -253
- package/dist/grid-cell-types-Pbe2m2tE.d.ts +0 -253
- package/dist/map-picker-ZUGGOIZS.js +0 -290
- package/dist/map-picker-ZUGGOIZS.js.map +0 -1
- package/dist/sheets-context-CY1RmDKL.d.cts +0 -244
- package/dist/sheets-context-Cu3Ec_ca.d.ts +0 -244
- /package/dist/{chunk-MXVNIKES.js.map → chunk-J7KK4UWI.js.map} +0 -0
package/dist/index.d.cts
CHANGED
|
@@ -1,60 +1,99 @@
|
|
|
1
1
|
import * as react from 'react';
|
|
2
|
-
import react__default, {
|
|
3
|
-
import {
|
|
4
|
-
export { A as AdapterListQuery,
|
|
2
|
+
import react__default, { ReactNode, Component, ErrorInfo } from 'react';
|
|
3
|
+
import { S as SheetsExecuteFn, b as SheetsConfig, C as CellProps, c as CellTypeDefinition, d as SheetsCellRenderContext, e as CellTypeMatchInput, f as SheetsScopeKey, R as ResolvedUploadChoices, g as SheetsBackendAdapter, P as ProcessingPolicy, h as SheetsStorageTransport } from './sheets-context-Bb7ZoNBg.cjs';
|
|
4
|
+
export { A as AdapterListQuery, i as AdapterListResult, j as AdapterPageInfo, k as AdapterTableContext, l as AdapterTableModelOptions, m as CellColumnDescriptor, n as CellTypePlugin, K as KeyValueStore, o as SheetsAuthEmbedded, p as SheetsAuthStandalone, q as SheetsContext, r as SheetsContextValue, s as SheetsExecuteOptions, t as SheetsFileValue, u as SheetsLogger, v as SheetsMapConfig, w as SheetsMapPlaceSearch, x as SheetsMapTiles, y as SheetsPartialResult, z as SheetsResponseError, B as SheetsStoredView, D as SheetsUploadColumnConfig, E as SheetsUploadConfig, a as SheetsUploadFn, F as SheetsUploadProcessingConfig, G as SheetsUploadResult, H as SheetsViewStorage, I as SheetsViewStorageScope, J as createKeyValueViewStorage, L as createMemoryViewStorage, M as createSheetsExecute, N as createSheetsUpload, O as defineCellType, Q as partialResultOf, T as responseErrorsOf, U as useSheetsContext } from './sheets-context-Bb7ZoNBg.cjs';
|
|
5
5
|
import { StoreApi } from 'zustand';
|
|
6
|
-
import { R as RelationInfo, d as
|
|
7
|
-
export { B as BaseCellProps, c as CellCategory, i as CellValue, j as FieldMetadata, k as RelationKind, l as RowData, a as SheetsCellKind, T as TableSchema,
|
|
8
|
-
import {
|
|
9
|
-
export { ConstructiveError } from '@constructive-io/data';
|
|
6
|
+
import { R as RelationInfo, d as SheetsRowIdentifier, E as EditorProps, S as SheetsCell, F as FieldMetadata, D as DraftSubmitResult, e as CellRegistryEntry, b as CellType, f as CellRenderer, g as CellPlugin, h as ColumnSchema } from './grid-cell-types-YNIVK4hN.cjs';
|
|
7
|
+
export { B as BaseCellProps, c as CellCategory, i as CellValue, j as FieldMetadata, k as RelationKind, l as RowData, a as SheetsCellKind, m as SheetsRowIdentityResolution, T as TableSchema, n as canRunSheetsMutation, o as getSheetsWriteCapability, p as isImageField, r as relationInfoFromModel, q as resolveCellType, s as resolveSheetsIdentifier, t as resolveSheetsRowIdentity, u as sheetsIdentifierCacheKey, v as sheetsIdentifierToRowKey, w as sheetsIdentifierToWhere, x as sheetsRowKey } from './grid-cell-types-YNIVK4hN.cjs';
|
|
8
|
+
import { TableModel, RelationModel, SortSpec, TableKey, ColumnModel, FieldSelection, MutationOptions, PageInfo, ColumnOption, MetaschemaTable, MetaQuery, QueryOptions } from '@constructive-io/data';
|
|
9
|
+
export { ArgumentModel, CELL_ERRORS_KEY, ColumnFileModel, ColumnFilterModel, ColumnModel, ColumnOption, ColumnSemantic, ColumnSortModel, ColumnValueKind, ColumnValueModel, ColumnWriteModel, ConstructiveError, CreateOperationModel, DeleteOperationModel, DisplayFieldOverrides, DisplayFieldsModel, FilterOperatorModel, InputFieldModel, InputValueModel, ListOperationModel, ModelIssue, ModelIssueCode, RELATION_TOTAL_COUNTS_KEY, RelationJunctionModel, RelationKeyPair, RelationModel, RelationModelKind, RelationTargetModel, SortDirection, SortSpec, TableKey, TableModel, TableModelError, TableModelErrorCode, TableOperations, TableSearchModel, TableStorageModel, TableStorageUploadModel, UpdateOperationModel, readCellError, readRelationTotalCount, resolveDisplayFields } from '@constructive-io/data';
|
|
10
10
|
import * as _tanstack_react_query from '@tanstack/react-query';
|
|
11
11
|
import { UseQueryResult } from '@tanstack/react-query';
|
|
12
12
|
import { z } from 'zod';
|
|
13
13
|
export { SheetsAuthGate, SheetsAuthGateProps, useSheetsForgotPassword, useSheetsLogin, useSheetsRegister, useSheetsResetPassword } from './auth.cjs';
|
|
14
14
|
import 'graphql';
|
|
15
15
|
|
|
16
|
-
interface SheetsProviderProps {
|
|
17
|
-
config: SheetsConfig;
|
|
18
|
-
children: React.ReactNode;
|
|
19
|
-
}
|
|
20
|
-
declare function SheetsProvider({ config, children }: SheetsProviderProps): react.JSX.Element;
|
|
21
|
-
|
|
22
16
|
/**
|
|
23
|
-
*
|
|
17
|
+
* The FALLBACK upload path: shape discovery over the full introspection.
|
|
24
18
|
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
19
|
+
* Used only for a storage service whose `_meta` names no upload mutation (an
|
|
20
|
+
* older server), and by hosts that call `createSheetsUpload` directly. It reads
|
|
21
|
+
* the full introspection once per endpoint and finds root mutations with the
|
|
22
|
+
* upload input and payload shape, and the fields that resolve a download URL by
|
|
23
|
+
* file id. The model-driven path in `uploads/` replaces all of this when the
|
|
24
|
+
* storage `_meta` names the upload mutation.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Resolve a file's signed `downloadUrl` by id, for callers outside the grid
|
|
29
|
+
* (a storage browser's copy link). Returns null on any failure.
|
|
30
|
+
*/
|
|
31
|
+
declare function resolveDownloadUrl(execute: SheetsExecuteFn, endpoint: string, fileId: string): Promise<string | null>;
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* The presigned upload protocol, shared by every upload path.
|
|
31
35
|
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
36
|
+
* 1. Hash the file (SHA-256, Web Crypto). The server needs the hash before it
|
|
37
|
+
* issues the URL: it names the object and is signed into the PUT.
|
|
38
|
+
* 2. Ask the upload mutation for a presigned PUT URL. A `deduplicated` answer
|
|
39
|
+
* means the bytes are already stored: no PUT.
|
|
40
|
+
* 3. PUT the bytes with the payload's `uploadHeaders`, unchanged (the URL is
|
|
41
|
+
* signed over them: Content-Type, the checksum, the file row id). No
|
|
42
|
+
* Authorization header; the signature is in the URL.
|
|
43
|
+
* 4. An expired URL is requested again once.
|
|
34
44
|
*
|
|
35
|
-
* The
|
|
36
|
-
*
|
|
37
|
-
* whose input + payload carry the upload shape.
|
|
45
|
+
* The server confirms the PUT later (a background job) and expires rows that
|
|
46
|
+
* never received one, so a cancelled or failed PUT leaves nothing behind.
|
|
38
47
|
*
|
|
39
|
-
* The
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
* (Relay-disabled backends); and the Relay `node(nodeId:)` fallback.
|
|
48
|
+
* The model-driven path (`uploads/`) names the upload mutation from the storage
|
|
49
|
+
* service's `_meta`. The shape discovery in `sheets-upload-discovery.ts` is the
|
|
50
|
+
* FALLBACK for a storage service whose `_meta` names no upload mutation.
|
|
43
51
|
*/
|
|
44
|
-
|
|
45
52
|
/**
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
* an already-uploaded file).
|
|
49
|
-
*
|
|
50
|
-
* `downloadUrl` is a Grafast computed field, so it cannot be selected through the
|
|
51
|
-
* runtime query builder (`buildSelect` intersects the select against pg columns and
|
|
52
|
-
* drops computed fields). This discovers the by-id field once per endpoint (cached)
|
|
53
|
-
* and reads it through the SAME resolver the upload path uses. Returns null on any
|
|
54
|
-
* failure — a missing url is not exceptional for the caller (it just disables
|
|
55
|
-
* copy/download), so the throwing internals are swallowed here.
|
|
53
|
+
* The file projection the upload mutation returns: what an image or upload
|
|
54
|
+
* column stores. The server may add keys (image `versions`); they are kept as returned.
|
|
56
55
|
*/
|
|
57
|
-
|
|
56
|
+
interface FileProjection {
|
|
57
|
+
id: string;
|
|
58
|
+
key: string;
|
|
59
|
+
bucket_id?: string;
|
|
60
|
+
mime?: string;
|
|
61
|
+
size?: number;
|
|
62
|
+
filename?: string;
|
|
63
|
+
/** Durable public URL; set only for a public bucket. */
|
|
64
|
+
url?: string;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* The file row the storage service created for an upload that did not finish
|
|
68
|
+
* (a refused or blocked PUT, a cancel, an answer without an upload URL). Sheets
|
|
69
|
+
* never deletes it: the storage service expires a row that never received its
|
|
70
|
+
* bytes. A host with its own cleanup rule reads it from the error.
|
|
71
|
+
*/
|
|
72
|
+
interface UnfinishedUpload {
|
|
73
|
+
/** Id of the files table row. */
|
|
74
|
+
fileId: string;
|
|
75
|
+
/** GraphQL type name of the files table, or null when the upload path does not know it. */
|
|
76
|
+
filesType: string | null;
|
|
77
|
+
/** `TableModel.key` of the files table, or null when the upload path does not know it. */
|
|
78
|
+
filesTableKey: string | null;
|
|
79
|
+
}
|
|
80
|
+
/** The file row an upload error left on the storage service, or null when the server issued none. */
|
|
81
|
+
declare function unfinishedUploadOf(error: unknown): UnfinishedUpload | null;
|
|
82
|
+
interface UploadProgressEvent {
|
|
83
|
+
loaded: number;
|
|
84
|
+
total: number;
|
|
85
|
+
percentage: number;
|
|
86
|
+
}
|
|
87
|
+
interface TransferOptions {
|
|
88
|
+
onProgress?: (progress: UploadProgressEvent) => void;
|
|
89
|
+
signal?: AbortSignal;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
interface SheetsProviderProps {
|
|
93
|
+
config: SheetsConfig;
|
|
94
|
+
children: React.ReactNode;
|
|
95
|
+
}
|
|
96
|
+
declare function SheetsProvider({ config, children }: SheetsProviderProps): react.JSX.Element;
|
|
58
97
|
|
|
59
98
|
type DraftRowStatus = 'idle' | 'saving' | 'error';
|
|
60
99
|
interface DraftRow {
|
|
@@ -125,10 +164,195 @@ interface SheetsAuthState {
|
|
|
125
164
|
setAuthenticated: (token: string, expiresAt: string, identityKey?: string | null) => void;
|
|
126
165
|
setUnauthenticated: () => void;
|
|
127
166
|
}
|
|
128
|
-
type SheetsStoreState = DraftRowsSlice &
|
|
167
|
+
type SheetsStoreState = DraftRowsSlice & SheetsAuthState;
|
|
129
168
|
declare function useSheetsStore<T>(selector: (state: SheetsStoreState) => T): T;
|
|
130
169
|
declare function useSheetsStoreApi(): StoreApi<SheetsStoreState>;
|
|
131
170
|
|
|
171
|
+
/**
|
|
172
|
+
* The filter, sort, search and column layout of one grid, as one serializable
|
|
173
|
+
* value.
|
|
174
|
+
*
|
|
175
|
+
* Columns and relations are named by their field name in the table model, so a
|
|
176
|
+
* host can store the value (a saved view) and load it later. Load a stored value
|
|
177
|
+
* through `validateSheetsViewState`: it drops every part the current model no
|
|
178
|
+
* longer supports and says what it dropped, and it upgrades a version 1 value
|
|
179
|
+
* (no column layout) to the current version.
|
|
180
|
+
*/
|
|
181
|
+
/** Version of the state shape. Version 2 added `columns`. */
|
|
182
|
+
declare const SHEETS_VIEW_STATE_VERSION = 2;
|
|
183
|
+
/** How the children of a filter group combine. */
|
|
184
|
+
type SheetsFilterLogic = 'and' | 'or';
|
|
185
|
+
/**
|
|
186
|
+
* A filter value as the user entered it: text (exact decimal text for big
|
|
187
|
+
* numbers, ISO text for dates, times and timestamps), a boolean, a list of
|
|
188
|
+
* values for list operators, field values for an operator that takes an object,
|
|
189
|
+
* or null for an operator without a value.
|
|
190
|
+
*/
|
|
191
|
+
type SheetsFilterValue = string | boolean | readonly string[] | Readonly<Record<string, string>> | null;
|
|
192
|
+
/** A condition on one column. */
|
|
193
|
+
interface SheetsColumnCondition {
|
|
194
|
+
kind: 'column';
|
|
195
|
+
/** Stable id within the state. */
|
|
196
|
+
id: string;
|
|
197
|
+
/** Column field name. */
|
|
198
|
+
column: string;
|
|
199
|
+
/** Operator name the column's filter really has, for example `includesInsensitive`. */
|
|
200
|
+
operator: string;
|
|
201
|
+
value: SheetsFilterValue;
|
|
202
|
+
}
|
|
203
|
+
/** What a relation condition tests. */
|
|
204
|
+
type SheetsRelationTest = 'any' | 'none' | 'labelContains';
|
|
205
|
+
/** A condition on one relation. */
|
|
206
|
+
interface SheetsRelationCondition {
|
|
207
|
+
kind: 'relation';
|
|
208
|
+
/** Stable id within the state. */
|
|
209
|
+
id: string;
|
|
210
|
+
/** Relation field name. */
|
|
211
|
+
relation: string;
|
|
212
|
+
/** `any`: has a linked record; `none`: has no linked record; `labelContains`: a linked record's label contains `value`. */
|
|
213
|
+
test: SheetsRelationTest;
|
|
214
|
+
/** Text for `labelContains`, otherwise null. */
|
|
215
|
+
value: string | null;
|
|
216
|
+
}
|
|
217
|
+
type SheetsFilterCondition = SheetsColumnCondition | SheetsRelationCondition;
|
|
218
|
+
/** A group of conditions and groups. */
|
|
219
|
+
interface SheetsFilterGroup {
|
|
220
|
+
kind: 'group';
|
|
221
|
+
/** Stable id within the state. */
|
|
222
|
+
id: string;
|
|
223
|
+
logic: SheetsFilterLogic;
|
|
224
|
+
children: readonly SheetsFilterNode[];
|
|
225
|
+
}
|
|
226
|
+
type SheetsFilterNode = SheetsFilterGroup | SheetsFilterCondition;
|
|
227
|
+
type SheetsSortDirection = 'asc' | 'desc';
|
|
228
|
+
/** One sort key. The first key in a list sorts first. */
|
|
229
|
+
interface SheetsSortKey {
|
|
230
|
+
/** Column field name. */
|
|
231
|
+
column: string;
|
|
232
|
+
direction: SheetsSortDirection;
|
|
233
|
+
}
|
|
234
|
+
/** Row heights the grid offers. */
|
|
235
|
+
type SheetsRowHeight = 'short' | 'medium' | 'tall' | 'extraTall';
|
|
236
|
+
/** Which columns show, in what order, how wide, how many stay in place, and how tall rows are. */
|
|
237
|
+
interface SheetsColumnLayout {
|
|
238
|
+
/**
|
|
239
|
+
* Grid column keys (column and relation field names) in display order. Keys
|
|
240
|
+
* the table has but this list does not name follow, in the table's order, so a
|
|
241
|
+
* new column shows up at the end.
|
|
242
|
+
*/
|
|
243
|
+
order: readonly string[];
|
|
244
|
+
/** Grid column keys that are hidden. */
|
|
245
|
+
hidden: readonly string[];
|
|
246
|
+
/** How many leading visible columns stay in place while the grid scrolls sideways. */
|
|
247
|
+
frozenCount: number;
|
|
248
|
+
/** Column widths in pixels, by grid column key. A column without an entry keeps its default width. */
|
|
249
|
+
widths: Readonly<Record<string, number>>;
|
|
250
|
+
rowHeight: SheetsRowHeight;
|
|
251
|
+
}
|
|
252
|
+
/** Filter, sort, search and column layout of one grid. */
|
|
253
|
+
interface SheetsViewState {
|
|
254
|
+
version: typeof SHEETS_VIEW_STATE_VERSION;
|
|
255
|
+
filters: SheetsFilterGroup;
|
|
256
|
+
sort: readonly SheetsSortKey[];
|
|
257
|
+
/** Search text; empty for no search. */
|
|
258
|
+
search: string;
|
|
259
|
+
columns: SheetsColumnLayout;
|
|
260
|
+
}
|
|
261
|
+
/** Why the validator dropped part of a state. */
|
|
262
|
+
type SheetsViewStateDropReason = 'invalid-shape' | 'unknown-column' | 'column-not-filterable' | 'unknown-operator' | 'unknown-option' | 'unknown-relation' | 'relation-test-unavailable' | 'column-not-sortable' | 'duplicate-sort' | 'search-unavailable';
|
|
263
|
+
/** One part of a state that the current model does not support. */
|
|
264
|
+
interface SheetsViewStateDrop {
|
|
265
|
+
/** Which part of the state. */
|
|
266
|
+
part: 'filters' | 'sort' | 'search' | 'columns';
|
|
267
|
+
/** Column or relation the dropped part named, or null. */
|
|
268
|
+
target: string | null;
|
|
269
|
+
reason: SheetsViewStateDropReason;
|
|
270
|
+
/** Human-readable explanation, safe to show to the user. */
|
|
271
|
+
message: string;
|
|
272
|
+
}
|
|
273
|
+
/** A state the model supports, and what was dropped to get it. */
|
|
274
|
+
interface SheetsViewStateValidation {
|
|
275
|
+
state: SheetsViewState;
|
|
276
|
+
dropped: readonly SheetsViewStateDrop[];
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
interface SheetsOpenTableRequest {
|
|
280
|
+
/** `TableModel.key` of the table to open. */
|
|
281
|
+
tableKey: string;
|
|
282
|
+
/** GraphQL type name of that table. */
|
|
283
|
+
tableName: string;
|
|
284
|
+
/**
|
|
285
|
+
* The rows the user was looking at (the junction rows of this record), as a filter
|
|
286
|
+
* group a host passes straight to `<Sheets filters>`; null when no exact filter can be
|
|
287
|
+
* built, in which case the host opens the table unfiltered.
|
|
288
|
+
*/
|
|
289
|
+
filters: SheetsFilterGroup | null;
|
|
290
|
+
/** Why the editor asks: the links live in a table with more fields than the editor can fill. */
|
|
291
|
+
reason: 'linked-records';
|
|
292
|
+
}
|
|
293
|
+
type SheetsOpenTableHandler = (request: SheetsOpenTableRequest) => void;
|
|
294
|
+
declare const SheetsOpenTableContext: react.Context<SheetsOpenTableHandler | null>;
|
|
295
|
+
/** A request to show one linked record, for example in the record panel's navigation stack. */
|
|
296
|
+
interface SheetsOpenRecordRequest {
|
|
297
|
+
/** `TableModel.key` of the record's table. */
|
|
298
|
+
tableKey: string;
|
|
299
|
+
/** GraphQL type name of that table. */
|
|
300
|
+
tableName: string;
|
|
301
|
+
/** Primary-key values of the record, by field name. */
|
|
302
|
+
key: Readonly<Record<string, unknown>>;
|
|
303
|
+
/** The record's label, for a title while it loads. */
|
|
304
|
+
label: string;
|
|
305
|
+
}
|
|
306
|
+
type SheetsOpenRecordHandler = (request: SheetsOpenRecordRequest) => void;
|
|
307
|
+
declare const SheetsOpenRecordContext: react.Context<SheetsOpenRecordHandler | null>;
|
|
308
|
+
/** The host's handler for opening a linked record, or null when the host has none. */
|
|
309
|
+
declare function useOpenRecordHandler(): SheetsOpenRecordHandler | null;
|
|
310
|
+
|
|
311
|
+
interface RelationSectionProps {
|
|
312
|
+
/** The record's table model. */
|
|
313
|
+
table: TableModel;
|
|
314
|
+
/** One relation of that table (the grid's rule for which to show: `gridRelations(table)`). */
|
|
315
|
+
relation: RelationModel;
|
|
316
|
+
/** The saved record (scalar fields and relation fields as read) or the new record's values; null while it loads. */
|
|
317
|
+
row: Readonly<Record<string, unknown>> | null;
|
|
318
|
+
/** The saved record's primary key; null for a record that is not created yet. */
|
|
319
|
+
rowIdentifier: SheetsRowIdentifier | null;
|
|
320
|
+
/** True for a record that is not created yet. */
|
|
321
|
+
isDraft: boolean;
|
|
322
|
+
/** A new record needs this link: the heading is marked like a required field. */
|
|
323
|
+
required?: boolean;
|
|
324
|
+
/** A reason the host already holds for keeping the relation read-only; it wins over the model's rules. */
|
|
325
|
+
readOnlyReason?: string | null;
|
|
326
|
+
/**
|
|
327
|
+
* belongsTo: the local key fields plus the chosen record under `relation.fieldName`
|
|
328
|
+
* (the grid editor's shape). On a new record this is the change itself; on a saved
|
|
329
|
+
* record it follows the write, for an immediate update of the shown record.
|
|
330
|
+
*/
|
|
331
|
+
onCommitPatch?: (patch: Record<string, unknown>) => void;
|
|
332
|
+
/** Called after any write (the affected tables are already refetching). */
|
|
333
|
+
onInvalidateData?: () => void;
|
|
334
|
+
/** Open a linked record; defaults to the nearest `SheetsOpenRecordContext` handler. Without either, no open control is shown. */
|
|
335
|
+
onOpenRecord?: SheetsOpenRecordHandler;
|
|
336
|
+
/** Heading level of the section title. Default 3. */
|
|
337
|
+
headingLevel?: 2 | 3 | 4;
|
|
338
|
+
}
|
|
339
|
+
declare function RelationSection({ table, relation, row, rowIdentifier, isDraft, required, readOnlyReason, onCommitPatch, onInvalidateData, onOpenRecord, headingLevel, }: RelationSectionProps): react.JSX.Element;
|
|
340
|
+
|
|
341
|
+
/**
|
|
342
|
+
* Which relation and foreign-key columns the grid shows, and in what order,
|
|
343
|
+
* from the table model alone (never from the keys of a loaded row).
|
|
344
|
+
*
|
|
345
|
+
* - Every readable relation is a column, except a hasMany to a junction
|
|
346
|
+
* table that a pure manyToMany relation already shows.
|
|
347
|
+
* - A foreign-key column is hidden only when its belongsTo relation is shown;
|
|
348
|
+
* the relation column takes the place of its first key column.
|
|
349
|
+
* - Primary-key columns come first, then the other columns in model order,
|
|
350
|
+
* then hasOne, hasMany and manyToMany relations in model order.
|
|
351
|
+
*/
|
|
352
|
+
|
|
353
|
+
/** The relations the grid shows as columns, in model order. */
|
|
354
|
+
declare function gridRelations(model: TableModel): RelationModel[];
|
|
355
|
+
|
|
132
356
|
/** A grid row: arbitrary column values keyed by field name, plus an optional id. */
|
|
133
357
|
type SheetsRow = Record<string, unknown> & {
|
|
134
358
|
id?: string | number;
|
|
@@ -321,44 +545,24 @@ declare function extendRangeToCell(sel: SheetsSelection, col: number, row: numbe
|
|
|
321
545
|
*/
|
|
322
546
|
declare function moveActive(sel: SheetsSelection, dCol: number, dRow: number, colCount: number, rowCount: number): SheetsSelection;
|
|
323
547
|
|
|
324
|
-
/**
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
identifier: SheetsRowIdentifier;
|
|
331
|
-
/** GraphQL primary-key input, including renamed and composite keys. */
|
|
332
|
-
primaryKey: Readonly<Record<string, RowIdentityValue>>;
|
|
333
|
-
/** Stable, schema-qualified key used by caches, selection, and editors. */
|
|
334
|
-
key: string;
|
|
335
|
-
}> | Readonly<{
|
|
336
|
-
status: 'unavailable';
|
|
337
|
-
reason: 'no-primary-key' | 'invalid-row';
|
|
338
|
-
}>;
|
|
339
|
-
/**
|
|
340
|
-
* Resolve one server row from `_meta`. The familiar scalar `id` contract is kept
|
|
341
|
-
* for existing adapters, while renamed and composite keys use the full PK input.
|
|
342
|
-
*/
|
|
343
|
-
declare function resolveSheetsRowIdentity(table: MetaTable$1, row: Readonly<Record<string, unknown>>): SheetsRowIdentityResolution;
|
|
344
|
-
/** Resolve a public CRUD identifier through the same `_meta` identity contract. */
|
|
345
|
-
declare function resolveSheetsIdentifier(table: MetaTable$1, identifier: SheetsRowIdentifier): SheetsRowIdentityResolution;
|
|
346
|
-
/** Build the PostGraphile connection filter used by `findOne`. */
|
|
347
|
-
declare function sheetsIdentifierToWhere(table: MetaTable$1, identifier: SheetsRowIdentifier): Record<string, {
|
|
348
|
-
equalTo: RowIdentityValue;
|
|
349
|
-
}> | null;
|
|
350
|
-
/** Use scalar IDs as cache keys for compatibility; use serialized identities otherwise. */
|
|
351
|
-
declare function sheetsIdentifierCacheKey(table: MetaTable$1, identifier: SheetsRowIdentifier): string | number | null;
|
|
352
|
-
/** Stable TanStack/selection/editor key with an index fallback only for non-writable rows. */
|
|
353
|
-
declare function sheetsRowKey(table: MetaTable$1, row: Readonly<Record<string, unknown>>, index: number): string;
|
|
354
|
-
declare function getSheetsWriteCapability(table: MetaTable$1 | null): TableWriteCapability | null;
|
|
355
|
-
declare function canRunSheetsMutation(capability: TableWriteCapability | null, operation: SheetsMutationOperation): boolean;
|
|
548
|
+
/** One cell write the grid refused before sending it. */
|
|
549
|
+
interface RejectedWrite {
|
|
550
|
+
rowIndex: number;
|
|
551
|
+
colKey: string;
|
|
552
|
+
reason: string;
|
|
553
|
+
}
|
|
356
554
|
|
|
357
555
|
/** A single cell write request. */
|
|
358
556
|
interface CellWrite {
|
|
359
557
|
rowIndex: number;
|
|
360
558
|
colKey: string;
|
|
361
559
|
value: unknown;
|
|
560
|
+
/**
|
|
561
|
+
* The value is text the user typed or pasted (JSON and lists are read from it).
|
|
562
|
+
* Defaults to true for a string value, false otherwise; an editor or a fill that
|
|
563
|
+
* hands over a stored value sets it to false.
|
|
564
|
+
*/
|
|
565
|
+
fromText?: boolean;
|
|
362
566
|
}
|
|
363
567
|
interface CommitCellsOptions {
|
|
364
568
|
/** When false, the commit is NOT pushed to history (used by undo/redo replays). Default true. */
|
|
@@ -367,6 +571,8 @@ interface CommitCellsOptions {
|
|
|
367
571
|
interface CommitCellsResult {
|
|
368
572
|
/** Number of server cells actually written (post readonly/null/no-op filtering). */
|
|
369
573
|
applied: number;
|
|
574
|
+
/** Writes refused before sending (the value did not fit, or the cell is read-only), when there are any. */
|
|
575
|
+
rejected?: readonly RejectedWrite[];
|
|
370
576
|
}
|
|
371
577
|
|
|
372
578
|
/**
|
|
@@ -380,7 +586,7 @@ interface CommitCellsResult {
|
|
|
380
586
|
* will not bust the per-cell memo.
|
|
381
587
|
*
|
|
382
588
|
* Getters (live reads off the existing refs):
|
|
383
|
-
* rowCount / colCount / activeCell / selection / combinedRows / columnKeys
|
|
589
|
+
* rowCount / colCount / activeCell / resumeCell / selection / combinedRows / columnKeys
|
|
384
590
|
*
|
|
385
591
|
* Anchor access wraps the existing `anchorRef` (the FIXED corner a range extends FROM):
|
|
386
592
|
* getAnchor / setAnchor
|
|
@@ -389,8 +595,92 @@ interface CommitCellsResult {
|
|
|
389
595
|
* setActiveCell, moveActiveCell, extendToCell, setSelection, commitCells,
|
|
390
596
|
* openEditorAtActive, openEditorAt, undo, redo, scrollToCell, sortToggle,
|
|
391
597
|
* getCellsInRange, toTSV, emit
|
|
392
|
-
|
|
393
|
-
|
|
598
|
+
*
|
|
599
|
+
* View (filter, sort and search): `view`, see {@link GridViewCommandTarget}.
|
|
600
|
+
*/
|
|
601
|
+
|
|
602
|
+
/**
|
|
603
|
+
* The filter, sort, search, column layout and saved-view actions the view
|
|
604
|
+
* commands run. Each `can*` / `has*` reads the table model and the view, so a
|
|
605
|
+
* command is only runnable when it would do something.
|
|
606
|
+
*/
|
|
607
|
+
interface GridViewCommandTarget {
|
|
608
|
+
/** The table can be searched and the search box is on screen. */
|
|
609
|
+
readonly canSearch: boolean;
|
|
610
|
+
/** A search is active. */
|
|
611
|
+
readonly hasSearch: boolean;
|
|
612
|
+
/** The filter builder can open: the built-in toolbar is shown and the table has a filterable field. */
|
|
613
|
+
readonly canFilter: boolean;
|
|
614
|
+
/** At least one filter condition exists. */
|
|
615
|
+
readonly hasFilters: boolean;
|
|
616
|
+
/** The sort control can open: the built-in toolbar is shown and the table has a sortable column. */
|
|
617
|
+
readonly canSortAny: boolean;
|
|
618
|
+
/** At least one sort key exists. */
|
|
619
|
+
readonly hasSort: boolean;
|
|
620
|
+
/** The grid column can be sorted. */
|
|
621
|
+
canSort(colKey: string): boolean;
|
|
622
|
+
/** Focus the toolbar search box; false when it is not there. */
|
|
623
|
+
focusSearch(): boolean;
|
|
624
|
+
clearSearch(): void;
|
|
625
|
+
openFilters(): void;
|
|
626
|
+
clearFilters(): void;
|
|
627
|
+
openSort(): void;
|
|
628
|
+
clearSort(): void;
|
|
629
|
+
/** Sort by this column alone. */
|
|
630
|
+
sortBy(colKey: string, direction: 'asc' | 'desc'): void;
|
|
631
|
+
/** The column can be filtered (the built-in toolbar is shown). */
|
|
632
|
+
canFilterBy(colKey: string): boolean;
|
|
633
|
+
/** Add a condition on the column and open the filters. */
|
|
634
|
+
filterBy(colKey: string): void;
|
|
635
|
+
/** The column can be hidden (it is not the last one shown). */
|
|
636
|
+
canHide(colKey: string): boolean;
|
|
637
|
+
hide(colKey: string): void;
|
|
638
|
+
/** The column can move one place left (-1) or right (1) among the shown columns. */
|
|
639
|
+
canMove(colKey: string, step: -1 | 1): boolean;
|
|
640
|
+
move(colKey: string, step: -1 | 1): void;
|
|
641
|
+
/** How many leading columns stay in place. */
|
|
642
|
+
readonly frozenCount: number;
|
|
643
|
+
/** Freeze the shown columns up to and including this one. */
|
|
644
|
+
freezeUpTo(colKey: string): void;
|
|
645
|
+
unfreeze(): void;
|
|
646
|
+
/** Open the header menu of a column. */
|
|
647
|
+
openColumnMenu(colKey: string): void;
|
|
648
|
+
/** The Fields control can open (the built-in toolbar is shown). */
|
|
649
|
+
readonly canOpenFields: boolean;
|
|
650
|
+
openFields(): void;
|
|
651
|
+
/** The view switcher can open (the built-in toolbar is shown). */
|
|
652
|
+
readonly canOpenViews: boolean;
|
|
653
|
+
openViews(): void;
|
|
654
|
+
/** The active saved view has unsaved changes. */
|
|
655
|
+
readonly canSaveView: boolean;
|
|
656
|
+
saveView(): void;
|
|
657
|
+
}
|
|
658
|
+
/** The record panel, when the grid has one: open one row as a record. */
|
|
659
|
+
interface GridRecordCommandTarget {
|
|
660
|
+
/** The row can be opened (it is loaded and is a record). */
|
|
661
|
+
canOpen(rowIndex: number): boolean;
|
|
662
|
+
open(rowIndex: number): void;
|
|
663
|
+
/** The panel is open. Escape in the grid closes it only then. */
|
|
664
|
+
isOpen?(): boolean;
|
|
665
|
+
close?(): void;
|
|
666
|
+
}
|
|
667
|
+
/** The record panel's new-record form, when the grid has one. */
|
|
668
|
+
interface GridNewRecordCommandTarget {
|
|
669
|
+
/** The table allows new records. */
|
|
670
|
+
canCreate(): boolean;
|
|
671
|
+
open(): void;
|
|
672
|
+
}
|
|
673
|
+
/** Links in cells (an email or web address): find the one a cell holds, and open it. */
|
|
674
|
+
interface GridLinkCommandTarget {
|
|
675
|
+
/** The address the cell's link opens, or null when the cell holds no link. */
|
|
676
|
+
hrefAt(col: number, row: number): string | null;
|
|
677
|
+
/** Open an address: a web address in a new tab, an email in the mail app. */
|
|
678
|
+
open(href: string): void;
|
|
679
|
+
}
|
|
680
|
+
/** The grid's context menu, opened from the keyboard at a cell. */
|
|
681
|
+
interface GridContextMenuCommandTarget {
|
|
682
|
+
open(col: number, row: number): void;
|
|
683
|
+
}
|
|
394
684
|
/** Extracted cell matrix — mirrors `getCellsInRange`'s return shape. */
|
|
395
685
|
interface CellMatrix {
|
|
396
686
|
cols: string[];
|
|
@@ -404,6 +694,11 @@ interface GridCommandContext {
|
|
|
404
694
|
readonly colCount: number;
|
|
405
695
|
/** The active (keyboard cursor) cell `[col, row]`, or undefined. */
|
|
406
696
|
readonly activeCell: [number, number] | undefined;
|
|
697
|
+
/**
|
|
698
|
+
* Where the cursor comes back after the active cell was cleared: the last active cell while
|
|
699
|
+
* it is still inside the grid. Absent means the first cell.
|
|
700
|
+
*/
|
|
701
|
+
readonly resumeCell?: [number, number];
|
|
407
702
|
/** The LATEST canonical selection (post-sort/filter-clear safe). */
|
|
408
703
|
readonly selection: SheetsSelection | undefined;
|
|
409
704
|
/** The current combined (server + draft) row window. */
|
|
@@ -434,8 +729,11 @@ interface GridCommandContext {
|
|
|
434
729
|
redo(): void | Promise<void>;
|
|
435
730
|
/** Scroll a cell into view. */
|
|
436
731
|
scrollToCell(col: number, row: number): void;
|
|
437
|
-
/**
|
|
438
|
-
|
|
732
|
+
/**
|
|
733
|
+
* Header sort click for a column key: cycle that column alone, or with `additive`
|
|
734
|
+
* (Shift+click) add it to the sort, flip it, or remove it.
|
|
735
|
+
*/
|
|
736
|
+
sortToggle(colKey: string, additive?: boolean): void;
|
|
439
737
|
/** Toggle a single row in the checkbox selection (the existing rowMarker.onToggleRow). */
|
|
440
738
|
toggleRow(rowIndex: number, shift: boolean): void;
|
|
441
739
|
/** Toggle select-all in the checkbox selection (the existing rowMarker.onToggleAll). */
|
|
@@ -446,6 +744,11 @@ interface GridCommandContext {
|
|
|
446
744
|
toTSV(values: (readonly unknown[])[]): string;
|
|
447
745
|
/** Emit an observational event (analytics/telemetry; never changes behavior). */
|
|
448
746
|
emit(type: SheetsEvent['type'], meta?: Record<string, unknown>): void;
|
|
747
|
+
readonly view: GridViewCommandTarget;
|
|
748
|
+
readonly record?: GridRecordCommandTarget;
|
|
749
|
+
readonly newRecord?: GridNewRecordCommandTarget;
|
|
750
|
+
readonly link?: GridLinkCommandTarget;
|
|
751
|
+
readonly contextMenu?: GridContextMenuCommandTarget;
|
|
449
752
|
}
|
|
450
753
|
|
|
451
754
|
/**
|
|
@@ -495,8 +798,10 @@ declare function kbd(key: string, ...modifiers: KeyModifier[]): KeyBinding;
|
|
|
495
798
|
* DEFAULT_KEYMAP + resolveKeyCommand (P4 Phase 1).
|
|
496
799
|
*
|
|
497
800
|
* A keymap is an ordered Binding[]; `resolveKeyCommand` returns the FIRST matching
|
|
498
|
-
* binding's command id (first-match-wins) or `null` when nothing matches
|
|
499
|
-
*
|
|
801
|
+
* binding's command id (first-match-wins) or `null` when nothing matches. The grid tries
|
|
802
|
+
* every binding of a chord in order (`resolveKeyBindings`) and runs the first whose command
|
|
803
|
+
* can run, so one key can mean "close the panel, else clear the selection". Nothing matches
|
|
804
|
+
* an unbound PRINTABLE key either, so the dispatch funnel can fall to the `editor.typeToEdit`
|
|
500
805
|
* sentinel (the printable-key path is NOT in the keymap; the funnel routes it explicitly).
|
|
501
806
|
*
|
|
502
807
|
* Triggers come in three kinds — `key` (matched here via the copied matchKeyBinding),
|
|
@@ -509,7 +814,7 @@ declare function kbd(key: string, ...modifiers: KeyModifier[]): KeyBinding;
|
|
|
509
814
|
*/
|
|
510
815
|
|
|
511
816
|
/** A pointer gesture name (resolved by the pointer handlers, not the key funnel). */
|
|
512
|
-
type PointerGesture = 'click' | 'shiftClick' | 'dblclick' | 'headerClick' | 'rowToggle' | 'rowToggleAll';
|
|
817
|
+
type PointerGesture = 'click' | 'shiftClick' | 'dblclick' | 'headerClick' | 'headerShiftClick' | 'rowToggle' | 'rowToggleAll';
|
|
513
818
|
/** What fires a command. */
|
|
514
819
|
type Trigger = {
|
|
515
820
|
kind: 'key';
|
|
@@ -525,6 +830,11 @@ type Trigger = {
|
|
|
525
830
|
interface Binding {
|
|
526
831
|
trigger: Trigger;
|
|
527
832
|
command: string;
|
|
833
|
+
/**
|
|
834
|
+
* Keep the key from the browser while the grid has focus even when the command
|
|
835
|
+
* does not run. For chords whose browser action loses work (Mod+R reloads the page).
|
|
836
|
+
*/
|
|
837
|
+
claim?: boolean;
|
|
528
838
|
}
|
|
529
839
|
|
|
530
840
|
/**
|
|
@@ -572,13 +882,160 @@ interface CommandResult {
|
|
|
572
882
|
*/
|
|
573
883
|
type Interceptor = (ev: DispatchEvent, next: () => CommandResult) => CommandResult;
|
|
574
884
|
|
|
885
|
+
interface ColumnLayoutBindings {
|
|
886
|
+
layout: SheetsColumnLayout;
|
|
887
|
+
/** Every grid column key of the table, in display order (shown and hidden). */
|
|
888
|
+
orderedKeys: readonly string[];
|
|
889
|
+
/** The keys that show, in display order. */
|
|
890
|
+
visibleKeys: readonly string[];
|
|
891
|
+
/** How many leading visible columns stay in place. */
|
|
892
|
+
frozenCount: number;
|
|
893
|
+
/** Row height in pixels. */
|
|
894
|
+
rowHeightPx: number;
|
|
895
|
+
isHidden: (key: string) => boolean;
|
|
896
|
+
/** Why a column cannot be hidden (it is the last one shown), or null. */
|
|
897
|
+
hideReason: (key: string) => string | null;
|
|
898
|
+
setHidden: (key: string, hidden: boolean) => void;
|
|
899
|
+
showAll: () => void;
|
|
900
|
+
hideAll: () => void;
|
|
901
|
+
/** Move to a position of the full display order (Fields list). */
|
|
902
|
+
moveTo: (key: string, index: number) => void;
|
|
903
|
+
/** Move beside another column (drag and drop). */
|
|
904
|
+
moveBeside: (key: string, target: string, side: 'before' | 'after') => void;
|
|
905
|
+
/** Move one place among the visible columns; false when it is already at that end. */
|
|
906
|
+
moveStep: (key: string, step: -1 | 1) => boolean;
|
|
907
|
+
freezeUpTo: (key: string) => void;
|
|
908
|
+
unfreeze: () => void;
|
|
909
|
+
setWidth: (key: string, width: number) => void;
|
|
910
|
+
setRowHeight: (rowHeight: SheetsRowHeight) => void;
|
|
911
|
+
fieldsOpen: boolean;
|
|
912
|
+
setFieldsOpen: (open: boolean) => void;
|
|
913
|
+
/** The column whose header menu is open, or null. */
|
|
914
|
+
menuColumn: string | null;
|
|
915
|
+
setMenuColumn: (key: string | null) => void;
|
|
916
|
+
}
|
|
917
|
+
|
|
918
|
+
/**
|
|
919
|
+
* The list variables for a view state: the filter (conditions and search,
|
|
920
|
+
* combined with `and`) and the sort, built only from the table model.
|
|
921
|
+
*/
|
|
922
|
+
|
|
923
|
+
type Where = Record<string, unknown>;
|
|
924
|
+
/** Whether a condition is part of the filter, and why not. */
|
|
925
|
+
type ConditionStatus = {
|
|
926
|
+
status: 'applied';
|
|
927
|
+
} | {
|
|
928
|
+
status: 'incomplete';
|
|
929
|
+
} | {
|
|
930
|
+
status: 'invalid';
|
|
931
|
+
message: string;
|
|
932
|
+
};
|
|
933
|
+
interface ViewQuery {
|
|
934
|
+
/** The filter input value, or undefined for no filter. */
|
|
935
|
+
where: Where | undefined;
|
|
936
|
+
/** The sort, first key first, or undefined for none. */
|
|
937
|
+
orderBy: SortSpec[] | undefined;
|
|
938
|
+
/** Status of every condition, by condition id. */
|
|
939
|
+
conditions: ReadonlyMap<string, ConditionStatus>;
|
|
940
|
+
/** Number of conditions in the filter. */
|
|
941
|
+
appliedCount: number;
|
|
942
|
+
/** Related tables whose models some condition still needs. */
|
|
943
|
+
waitingFor: readonly TableKey[];
|
|
944
|
+
}
|
|
945
|
+
type RelatedModelLookup = (key: TableKey) => TableModel | null;
|
|
946
|
+
/**
|
|
947
|
+
* The list variables for a state the model supports (see
|
|
948
|
+
* `validateSheetsViewState`). Conditions that are incomplete or invalid, or
|
|
949
|
+
* that the filter input cannot combine, are left out of the filter and
|
|
950
|
+
* reported in `conditions`, so `appliedCount` counts only what filters.
|
|
951
|
+
*/
|
|
952
|
+
declare function buildViewQuery(state: SheetsViewState, model: TableModel, related?: RelatedModelLookup): ViewQuery;
|
|
953
|
+
|
|
954
|
+
/**
|
|
955
|
+
* What the toolbar search box searches, from the table model.
|
|
956
|
+
*
|
|
957
|
+
* A table with a combined search field searches through it. Otherwise the
|
|
958
|
+
* search matches every text column that really has a case-insensitive contains
|
|
959
|
+
* operator, combined with `or`; without `or` it matches the first such column.
|
|
960
|
+
*/
|
|
961
|
+
|
|
962
|
+
type SearchPlan = {
|
|
963
|
+
mode: 'unified';
|
|
964
|
+
/** Filter input field that takes the search text. */
|
|
965
|
+
field: string;
|
|
966
|
+
/** Columns the table's search covers, when the server names them. */
|
|
967
|
+
columns: readonly string[];
|
|
968
|
+
} | {
|
|
969
|
+
mode: 'columns';
|
|
970
|
+
/** Columns matched with a case-insensitive contains, in table order. */
|
|
971
|
+
columns: readonly {
|
|
972
|
+
name: string;
|
|
973
|
+
field: string;
|
|
974
|
+
}[];
|
|
975
|
+
};
|
|
976
|
+
|
|
977
|
+
interface SheetsViewProps {
|
|
978
|
+
/** Controlled filters. Omit to let the grid own them. */
|
|
979
|
+
filters?: SheetsFilterGroup;
|
|
980
|
+
onFiltersChange?: (filters: SheetsFilterGroup) => void;
|
|
981
|
+
/** Controlled sort, first key first. Omit to let the grid own it. */
|
|
982
|
+
sort?: readonly SheetsSortKey[];
|
|
983
|
+
onSortChange?: (sort: readonly SheetsSortKey[]) => void;
|
|
984
|
+
/** Controlled search text. Omit to let the grid own it. */
|
|
985
|
+
search?: string;
|
|
986
|
+
onSearchChange?: (search: string) => void;
|
|
987
|
+
/** Controlled column layout (order, hidden, frozen count, widths, row height). Omit to let the grid own it. */
|
|
988
|
+
columns?: SheetsColumnLayout;
|
|
989
|
+
onColumnsChange?: (columns: SheetsColumnLayout) => void;
|
|
990
|
+
}
|
|
991
|
+
/** The view bindings the toolbar, the header and the commands use. */
|
|
992
|
+
interface SheetsViewBindings {
|
|
993
|
+
/** The state in use, valid for the current model. */
|
|
994
|
+
state: SheetsViewState;
|
|
995
|
+
model: TableModel | null;
|
|
996
|
+
/** Parts of the given state the model does not support. */
|
|
997
|
+
dropped: readonly SheetsViewStateDrop[];
|
|
998
|
+
/** Status of every condition, by condition id. */
|
|
999
|
+
conditions: ReadonlyMap<string, ConditionStatus>;
|
|
1000
|
+
/** Conditions that are part of the filter. */
|
|
1001
|
+
appliedCount: number;
|
|
1002
|
+
/** What the search box searches, or null when the table cannot be searched. */
|
|
1003
|
+
searchPlan: SearchPlan | null;
|
|
1004
|
+
columnLabel: (name: string) => string;
|
|
1005
|
+
/** A related table's model, once loaded. */
|
|
1006
|
+
relatedModel: (key: TableKey) => TableModel | null;
|
|
1007
|
+
setFilters: (filters: SheetsFilterGroup) => void;
|
|
1008
|
+
clearFilters: () => void;
|
|
1009
|
+
setSort: (sort: readonly SheetsSortKey[]) => void;
|
|
1010
|
+
/** Header click: cycle one column, or with `additive` add it to the sort. */
|
|
1011
|
+
toggleSort: (column: string, additive: boolean) => void;
|
|
1012
|
+
setSearch: (search: string) => void;
|
|
1013
|
+
setColumns: (columns: SheetsColumnLayout) => void;
|
|
1014
|
+
/** Replace filters, sort, search and layout at once (a saved view). */
|
|
1015
|
+
applyState: (state: SheetsViewState) => void;
|
|
1016
|
+
/** Open the filters with a new condition on a column or relation; false when no condition could be added. */
|
|
1017
|
+
filterBy: (column: string) => boolean;
|
|
1018
|
+
/** Column layout and its actions. */
|
|
1019
|
+
layout: ColumnLayoutBindings;
|
|
1020
|
+
/** Why a grid column cannot be sorted, or null when it can. Empty text for a column the grid adds itself. */
|
|
1021
|
+
unsortableReason: (column: string) => string | null;
|
|
1022
|
+
filtersOpen: boolean;
|
|
1023
|
+
setFiltersOpen: (open: boolean) => void;
|
|
1024
|
+
sortOpen: boolean;
|
|
1025
|
+
setSortOpen: (open: boolean) => void;
|
|
1026
|
+
/** Attach to the search input so `focusSearch` can reach it. */
|
|
1027
|
+
searchInputRef: React.MutableRefObject<HTMLInputElement | null>;
|
|
1028
|
+
/** Focus the search box; false when there is none. */
|
|
1029
|
+
focusSearch: () => boolean;
|
|
1030
|
+
}
|
|
1031
|
+
|
|
575
1032
|
/**
|
|
576
1033
|
* Lifecycle/interaction event emitted by {@link Sheets} via the optional
|
|
577
1034
|
* `onEvent` prop. Purely observational: firing an event never changes grid
|
|
578
1035
|
* behavior, so consumers can wire analytics/telemetry without side effects.
|
|
579
1036
|
*/
|
|
580
1037
|
interface SheetsEvent {
|
|
581
|
-
type: 'load:success' | 'load:error' | 'cell:edit' | 'row:create' | 'row:delete' | 'filter:apply' | 'sort:change' | 'page:change';
|
|
1038
|
+
type: 'load:success' | 'load:error' | 'cell:edit' | 'row:create' | 'row:delete' | 'filter:apply' | 'sort:change' | 'search:change' | 'page:change';
|
|
582
1039
|
/** The table the event originated from. */
|
|
583
1040
|
tableName: string;
|
|
584
1041
|
/** Epoch ms (`Date.now()`) when the event fired. */
|
|
@@ -602,7 +1059,10 @@ interface SheetsSlots {
|
|
|
602
1059
|
empty?: React.ReactNode | ((ctx: {
|
|
603
1060
|
tableName: string;
|
|
604
1061
|
}) => React.ReactNode);
|
|
605
|
-
/**
|
|
1062
|
+
/**
|
|
1063
|
+
* Replaces the default error panel: full-screen while the table's model is missing, and over
|
|
1064
|
+
* the grid body (toolbar kept) when only the rows failed to load.
|
|
1065
|
+
*/
|
|
606
1066
|
error?: (ctx: {
|
|
607
1067
|
error: unknown;
|
|
608
1068
|
retry: () => void;
|
|
@@ -630,14 +1090,37 @@ interface SheetsHandle {
|
|
|
630
1090
|
refetch(): void;
|
|
631
1091
|
/** Return the currently selected rows (empty array when nothing selected). */
|
|
632
1092
|
getSelectedRows(): Record<string, unknown>[];
|
|
633
|
-
/**
|
|
1093
|
+
/**
|
|
1094
|
+
* Download the selected rows (or all rows when none selected) as CSV.
|
|
1095
|
+
* `protectFormulas` overrides the grid's `csvExport.protectFormulas` for this download.
|
|
1096
|
+
*/
|
|
634
1097
|
exportCsv(opts?: {
|
|
635
1098
|
columns?: string[];
|
|
636
1099
|
filename?: string;
|
|
1100
|
+
protectFormulas?: boolean;
|
|
637
1101
|
}): void;
|
|
1102
|
+
/** Open a record of this table in the record panel. False when the identifier does not name a record. */
|
|
1103
|
+
openRecord(recordId: SheetsRowIdentifier): boolean;
|
|
1104
|
+
/** Open the record panel on a new record. False when the table does not allow new records. */
|
|
1105
|
+
openNewRecord(): boolean;
|
|
1106
|
+
/** Close the record panel. */
|
|
1107
|
+
closeRecord(): void;
|
|
638
1108
|
}
|
|
639
|
-
|
|
1109
|
+
/**
|
|
1110
|
+
* `filters` / `sort` / `search` (each with its change callback) let a host own
|
|
1111
|
+
* the view state, for example to persist it as a saved view. Each one omitted is
|
|
1112
|
+
* owned by the grid. The grid checks every given state against the table model
|
|
1113
|
+
* and leaves out what the model no longer supports (see `validateSheetsViewState`).
|
|
1114
|
+
*/
|
|
1115
|
+
interface DataGridProps<TRow extends SheetsRow = SheetsRow> extends SheetsViewProps {
|
|
640
1116
|
tableName: string;
|
|
1117
|
+
/**
|
|
1118
|
+
* Make the grid read-only for this host: `true`, or the reason to show. Every cell,
|
|
1119
|
+
* paste and fill, Add row, New record, Import, Delete, every link and the record panel's
|
|
1120
|
+
* fields refuse writes and show the reason; viewing, sorting, filtering, search and
|
|
1121
|
+
* export stay. `true` shows "This table is read-only here."
|
|
1122
|
+
*/
|
|
1123
|
+
readOnly?: boolean | string;
|
|
641
1124
|
className?: string;
|
|
642
1125
|
pageSize?: number;
|
|
643
1126
|
showSelection?: boolean;
|
|
@@ -665,6 +1148,29 @@ interface DataGridProps<TRow extends SheetsRow = SheetsRow> {
|
|
|
665
1148
|
* Omitting it leaves behavior unchanged.
|
|
666
1149
|
*/
|
|
667
1150
|
onEvent?: (e: SheetsEvent) => void;
|
|
1151
|
+
/**
|
|
1152
|
+
* Called when the user asks to see another table, for example the table that
|
|
1153
|
+
* stores links needing more fields than the link editor can fill. The grid
|
|
1154
|
+
* does not navigate; omit it and the editor offers no such action.
|
|
1155
|
+
*/
|
|
1156
|
+
onOpenTable?: SheetsOpenTableHandler;
|
|
1157
|
+
/**
|
|
1158
|
+
* CSV export settings. `protectFormulas`: text that starts with =, +, -, @, a tab or
|
|
1159
|
+
* a carriage return is written with a leading apostrophe, so a spreadsheet app does not
|
|
1160
|
+
* run it as a formula (numbers are not changed). Off by default. It applies to
|
|
1161
|
+
* "Export selected" and `SheetsHandle.exportCsv`, and is the starting choice of the
|
|
1162
|
+
* checkbox in the "Export view" dialog.
|
|
1163
|
+
*/
|
|
1164
|
+
csvExport?: {
|
|
1165
|
+
protectFormulas?: boolean;
|
|
1166
|
+
};
|
|
1167
|
+
/**
|
|
1168
|
+
* The record open in the record panel, for deep links: an identifier of a record of
|
|
1169
|
+
* this table, or null for closed. Omit it to let the grid own the panel state.
|
|
1170
|
+
*/
|
|
1171
|
+
recordId?: SheetsRowIdentifier | null;
|
|
1172
|
+
/** Called whenever the user opens, moves to or closes a record of this table in the record panel. */
|
|
1173
|
+
onRecordOpenChange?: (recordId: SheetsRowIdentifier | null) => void;
|
|
668
1174
|
/**
|
|
669
1175
|
* Optional render-slot overrides for the toolbar / empty / error / loading
|
|
670
1176
|
* regions. Any omitted slot falls back to the built-in default.
|
|
@@ -676,8 +1182,9 @@ interface DataGridProps<TRow extends SheetsRow = SheetsRow> {
|
|
|
676
1182
|
*/
|
|
677
1183
|
commands?: GridCommand[];
|
|
678
1184
|
/**
|
|
679
|
-
* Extra / override key bindings, scanned BEFORE the defaults
|
|
680
|
-
*
|
|
1185
|
+
* Extra / override key bindings, scanned BEFORE the defaults, so a rebind of a
|
|
1186
|
+
* built-in chord wins. When several bindings match a key, they are tried in order
|
|
1187
|
+
* and the first whose command can run wins. Omitting it = the default keymap.
|
|
681
1188
|
*/
|
|
682
1189
|
keymap?: Binding[];
|
|
683
1190
|
/**
|
|
@@ -707,6 +1214,56 @@ declare const Sheets: <TRow extends SheetsRow = SheetsRow>(props: DataGridProps<
|
|
|
707
1214
|
}) => react__default.ReactElement;
|
|
708
1215
|
type SheetsProps<TRow extends SheetsRow = SheetsRow> = DataGridProps<TRow>;
|
|
709
1216
|
|
|
1217
|
+
/** The built-in engine the registry falls back to (injected to avoid a cycle). */
|
|
1218
|
+
interface CellTypeBuiltins {
|
|
1219
|
+
toSheetsCell: (value: unknown, ctx: SheetsCellRenderContext) => SheetsCell;
|
|
1220
|
+
}
|
|
1221
|
+
interface CellTypeRegistry {
|
|
1222
|
+
/** Detection: consumer `match()` chain first (later defs win), else the built-in resolver. */
|
|
1223
|
+
resolveTypeKey(meta: CellTypeMatchInput, builtinFallback: () => string): string;
|
|
1224
|
+
/** Native display: consumer `def.toSheetsCell` for this typeKey, else the built-in renderer. */
|
|
1225
|
+
toSheetsCell(typeKey: string, value: unknown, ctx: SheetsCellRenderContext): SheetsCell;
|
|
1226
|
+
/** The registered definition for a typeKey, if any (consumer defs only). */
|
|
1227
|
+
get(typeKey: string): CellTypeDefinition<any> | undefined;
|
|
1228
|
+
/** The native cell COMPONENT override for a typeKey, if any (consumer `def.cell`). */
|
|
1229
|
+
getCellComponent(typeKey: string): React.ComponentType<CellProps> | undefined;
|
|
1230
|
+
/** The native EDITOR override for a typeKey, if any (consumer `def.editorComponent`). */
|
|
1231
|
+
getEditorComponent(typeKey: string): React.ComponentType<EditorProps> | undefined;
|
|
1232
|
+
}
|
|
1233
|
+
/**
|
|
1234
|
+
* Build a registry. `cellTypes` are consumer definitions in precedence order
|
|
1235
|
+
* (provider `plugins` first, then per-instance `cellTypes`); later entries win,
|
|
1236
|
+
* so an instance-level def overrides a provider-level one with the same typeKey.
|
|
1237
|
+
*/
|
|
1238
|
+
declare function createCellTypeRegistry(cellTypes: CellTypeDefinition<any>[], builtins: CellTypeBuiltins): CellTypeRegistry;
|
|
1239
|
+
|
|
1240
|
+
/** Resolved DOM cell payload: the neutral cell plus its (optional) view component. */
|
|
1241
|
+
interface SheetsCellResolution {
|
|
1242
|
+
cell: SheetsCell;
|
|
1243
|
+
component?: React.ComponentType<CellProps>;
|
|
1244
|
+
colKey: string;
|
|
1245
|
+
/**
|
|
1246
|
+
* The resolved cell-type key (post detection-override) — the SINGLE source of
|
|
1247
|
+
* truth the host feeds to `resolveEditIntent` to route activation. Always set;
|
|
1248
|
+
* `'text'` for the loading/empty fallthrough cells that carry no type. (Mirror
|
|
1249
|
+
* of the `meta.cellType` the cell itself now self-describes.)
|
|
1250
|
+
*/
|
|
1251
|
+
typeKey: string;
|
|
1252
|
+
/** Typed server row locator, separate from the grid's string key. */
|
|
1253
|
+
rowIdentifier?: SheetsRowIdentifier | null;
|
|
1254
|
+
readOnlyReason?: string;
|
|
1255
|
+
/** Field metadata for the column — fed to a native overlay editor's EditorProps.fieldMeta. */
|
|
1256
|
+
fieldMeta?: FieldMetadata;
|
|
1257
|
+
/** Relation info for the column (when relational) — fed to a native overlay editor's EditorProps.relationInfo. */
|
|
1258
|
+
relationInfo?: RelationInfo;
|
|
1259
|
+
/** The table-model column behind this cell, or null when the cell is not a column. */
|
|
1260
|
+
column?: ColumnModel | null;
|
|
1261
|
+
/** The table-model relation behind this cell, or null when the cell is not a relation. */
|
|
1262
|
+
relation?: RelationModel | null;
|
|
1263
|
+
/** A problem with this draft cell's value (for example a missing required value), shown on the cell. */
|
|
1264
|
+
errorMessage?: string;
|
|
1265
|
+
}
|
|
1266
|
+
|
|
710
1267
|
type RelationMetadataSource = 'relation' | 'foreignKey';
|
|
711
1268
|
interface RelationMetadata {
|
|
712
1269
|
tableName: string;
|
|
@@ -750,9 +1307,12 @@ interface RelationColumnInfo {
|
|
|
750
1307
|
relationTypeByField: Map<string, RelationKind>;
|
|
751
1308
|
}
|
|
752
1309
|
/**
|
|
753
|
-
* Create data grid columns with relation metadata baked in
|
|
1310
|
+
* Create data grid columns with relation metadata baked in.
|
|
1311
|
+
*
|
|
1312
|
+
* @param tableName - table name or `TableModel.key`.
|
|
1313
|
+
* @param _rows - ignored; columns come from the table model, not from loaded rows.
|
|
754
1314
|
*/
|
|
755
|
-
declare function useRelationColumns(tableName?: string,
|
|
1315
|
+
declare function useRelationColumns(tableName?: string, _rows?: unknown[]): RelationColumnInfo;
|
|
756
1316
|
/**
|
|
757
1317
|
* Drop-in replacement for the original useDataGridColumns hook
|
|
758
1318
|
* Maintains complete backward compatibility while providing improvements
|
|
@@ -772,117 +1332,15 @@ declare function useDataGridColumns(tableName?: string, rows?: unknown[]): {
|
|
|
772
1332
|
invalidateRelationCache: () => Promise<void>;
|
|
773
1333
|
};
|
|
774
1334
|
|
|
775
|
-
/** The built-in engine the registry falls back to (injected to avoid a cycle). */
|
|
776
|
-
interface CellTypeBuiltins {
|
|
777
|
-
toSheetsCell: (value: unknown, ctx: SheetsCellRenderContext) => SheetsCell;
|
|
778
|
-
}
|
|
779
|
-
interface CellTypeRegistry {
|
|
780
|
-
/** Detection: consumer `match()` chain first (later defs win), else the built-in resolver. */
|
|
781
|
-
resolveTypeKey(meta: CellTypeMatchInput, builtinFallback: () => string): string;
|
|
782
|
-
/** Native display: consumer `def.toSheetsCell` for this typeKey, else the built-in renderer. */
|
|
783
|
-
toSheetsCell(typeKey: string, value: unknown, ctx: SheetsCellRenderContext): SheetsCell;
|
|
784
|
-
/** The registered definition for a typeKey, if any (consumer defs only). */
|
|
785
|
-
get(typeKey: string): CellTypeDefinition<any> | undefined;
|
|
786
|
-
/** The native cell COMPONENT override for a typeKey, if any (consumer `def.cell`). */
|
|
787
|
-
getCellComponent(typeKey: string): React.ComponentType<CellProps> | undefined;
|
|
788
|
-
/** The native EDITOR override for a typeKey, if any (consumer `def.editorComponent`). */
|
|
789
|
-
getEditorComponent(typeKey: string): React.ComponentType<EditorProps> | undefined;
|
|
790
|
-
}
|
|
791
|
-
/**
|
|
792
|
-
* Build a registry. `cellTypes` are consumer definitions in precedence order
|
|
793
|
-
* (provider `plugins` first, then per-instance `cellTypes`); later entries win,
|
|
794
|
-
* so an instance-level def overrides a provider-level one with the same typeKey.
|
|
795
|
-
*/
|
|
796
|
-
declare function createCellTypeRegistry(cellTypes: CellTypeDefinition<any>[], builtins: CellTypeBuiltins): CellTypeRegistry;
|
|
797
|
-
|
|
798
|
-
/** Result of submitting a draft row */
|
|
799
|
-
interface DraftSubmitResult {
|
|
800
|
-
/** The created row with its metadata-defined primary-key fields. */
|
|
801
|
-
createdRow: Record<string, unknown> | null;
|
|
802
|
-
}
|
|
803
|
-
|
|
804
|
-
/** Resolved DOM cell payload: the neutral cell plus its (optional) view component. */
|
|
805
|
-
interface SheetsCellResolution {
|
|
806
|
-
cell: SheetsCell;
|
|
807
|
-
component?: React.ComponentType<CellProps>;
|
|
808
|
-
colKey: string;
|
|
809
|
-
/**
|
|
810
|
-
* The resolved cell-type key (post detection-override) — the SINGLE source of
|
|
811
|
-
* truth the host feeds to `resolveEditIntent` to route activation. Always set;
|
|
812
|
-
* `'text'` for the loading/empty fallthrough cells that carry no type. (Mirror
|
|
813
|
-
* of the `meta.cellType` the cell itself now self-describes.)
|
|
814
|
-
*/
|
|
815
|
-
typeKey: string;
|
|
816
|
-
/** Field metadata for the column — fed to a native overlay editor's EditorProps.fieldMeta. */
|
|
817
|
-
fieldMeta?: FieldMetadata;
|
|
818
|
-
/** Relation info for the column (when relational) — fed to a native overlay editor's EditorProps.relationInfo. */
|
|
819
|
-
relationInfo?: RelationInfo;
|
|
820
|
-
}
|
|
821
|
-
|
|
822
|
-
type FilterValue = string | number | boolean | null | undefined;
|
|
823
|
-
type FilterNode = FilterCondition | FilterGroup;
|
|
824
|
-
interface FilterCondition {
|
|
825
|
-
type: "condition";
|
|
826
|
-
id: string;
|
|
827
|
-
field: string;
|
|
828
|
-
operator: string;
|
|
829
|
-
value: FilterValue;
|
|
830
|
-
}
|
|
831
|
-
interface FilterGroup {
|
|
832
|
-
type: "group";
|
|
833
|
-
id: string;
|
|
834
|
-
conjunction: "and" | "or";
|
|
835
|
-
children: FilterNode[];
|
|
836
|
-
}
|
|
837
|
-
declare const MAX_FILTER_DEPTH = 3;
|
|
838
|
-
type FieldTypeMap = Record<string, {
|
|
839
|
-
gqlType: string;
|
|
840
|
-
isArray: boolean;
|
|
841
|
-
}>;
|
|
842
|
-
declare function createEmptyGroup(conjunction?: "and" | "or"): FilterGroup;
|
|
843
|
-
declare function countConditions(node: FilterNode): number;
|
|
844
|
-
interface SheetsControlsProps {
|
|
845
|
-
openSearch?: () => void;
|
|
846
|
-
filterTree: FilterGroup;
|
|
847
|
-
setFilterTree: (tree: FilterGroup) => void;
|
|
848
|
-
filtersOpen: boolean;
|
|
849
|
-
setFiltersOpen: (open: boolean) => void;
|
|
850
|
-
clearAllFilters: () => void;
|
|
851
|
-
applyFilters: () => void;
|
|
852
|
-
columnKeys: string[];
|
|
853
|
-
fieldTypeMap: FieldTypeMap;
|
|
854
|
-
showSelection: boolean;
|
|
855
|
-
gridSelection: SheetsSelection | null;
|
|
856
|
-
setGridSelection: (selection: SheetsSelection | null) => void;
|
|
857
|
-
deleteSelected: () => void;
|
|
858
|
-
onAddRow?: () => void;
|
|
859
|
-
onExport?: () => void;
|
|
860
|
-
canDelete?: boolean;
|
|
861
|
-
readOnlyReason?: string | null;
|
|
862
|
-
}
|
|
863
|
-
declare function SheetsControls(props: SheetsControlsProps): react.JSX.Element;
|
|
864
|
-
|
|
865
1335
|
interface GridState {
|
|
866
|
-
sorting: {
|
|
867
|
-
id: string | null;
|
|
868
|
-
desc: boolean;
|
|
869
|
-
};
|
|
870
1336
|
pageIndex: number;
|
|
871
|
-
filterTree: FilterGroup;
|
|
872
|
-
filtersOpen: boolean;
|
|
873
1337
|
columnWidths: Map<string, number>;
|
|
874
1338
|
gridSelection: SheetsSelection | undefined;
|
|
875
1339
|
}
|
|
876
1340
|
declare function useGridState(): {
|
|
877
1341
|
state: GridState;
|
|
878
1342
|
actions: {
|
|
879
|
-
setSorting: (sorting: GridState["sorting"]) => void;
|
|
880
|
-
toggleSorting: (colId: string) => void;
|
|
881
1343
|
setPageIndex: (pageIndex: number) => void;
|
|
882
|
-
setFilterTree: (tree: FilterGroup) => void;
|
|
883
|
-
clearAllFilters: () => void;
|
|
884
|
-
toggleFiltersPanel: () => void;
|
|
885
|
-
setFiltersOpen: (open: boolean) => void;
|
|
886
1344
|
resizeColumn: (id: string, width: number) => void;
|
|
887
1345
|
setGridSelection: (selection: SheetsSelection | undefined) => void;
|
|
888
1346
|
setActiveCell: (col: number, row: number) => void;
|
|
@@ -891,6 +1349,13 @@ declare function useGridState(): {
|
|
|
891
1349
|
};
|
|
892
1350
|
};
|
|
893
1351
|
|
|
1352
|
+
/** One reversible step: a label plus its undo / redo thunks (throw when nothing changed). */
|
|
1353
|
+
interface HistoryEntry {
|
|
1354
|
+
label: string;
|
|
1355
|
+
undo: () => Promise<void> | void;
|
|
1356
|
+
redo: () => Promise<void> | void;
|
|
1357
|
+
}
|
|
1358
|
+
|
|
894
1359
|
type RowRecord$2 = Record<string, unknown>;
|
|
895
1360
|
/** Data for a single loaded page */
|
|
896
1361
|
interface PageData<T = RowRecord$2> {
|
|
@@ -908,8 +1373,10 @@ interface UseInfiniteTableOptions {
|
|
|
908
1373
|
field: string;
|
|
909
1374
|
direction: 'asc' | 'desc';
|
|
910
1375
|
}>;
|
|
911
|
-
/**
|
|
912
|
-
where?: Record<string, unknown
|
|
1376
|
+
/** A filter in the server's filter input shape (any operator the model reports, relation and search fields included). */
|
|
1377
|
+
where?: Readonly<Record<string, unknown>>;
|
|
1378
|
+
/** Columns to fetch (the primary key and relation keys are always added). Omitted: every readable column. */
|
|
1379
|
+
columns?: readonly string[];
|
|
913
1380
|
/** Field selection preset or custom selection */
|
|
914
1381
|
select?: FieldSelection;
|
|
915
1382
|
/** Enable/disable the hook */
|
|
@@ -935,10 +1402,14 @@ interface UseInfiniteTableResult<T = RowRecord$2> {
|
|
|
935
1402
|
pageSize: number;
|
|
936
1403
|
/** Overall loading state (true if any page is loading) */
|
|
937
1404
|
isLoading: boolean;
|
|
1405
|
+
/** True while a page request for the current options is in flight, also while placeholder rows from the previous options show */
|
|
1406
|
+
isFetching: boolean;
|
|
938
1407
|
/** Whether initial data has been loaded */
|
|
939
1408
|
hasInitialData: boolean;
|
|
940
|
-
/** Error from the most recent failed fetch */
|
|
1409
|
+
/** Error from the most recent failed fetch, or why the table model is unavailable */
|
|
941
1410
|
error: Error | null;
|
|
1411
|
+
/** The table model, or null while it loads or when it failed */
|
|
1412
|
+
model: TableModel | null;
|
|
942
1413
|
/** Invalidate all pages and refetch */
|
|
943
1414
|
invalidate: () => void;
|
|
944
1415
|
/** Reset to initial state (clears all pages, refetches page 0) */
|
|
@@ -963,6 +1434,50 @@ interface VisibleRowRange {
|
|
|
963
1434
|
endIndex: number;
|
|
964
1435
|
}
|
|
965
1436
|
|
|
1437
|
+
/** A saved view, checked against the current model. */
|
|
1438
|
+
interface SavedView {
|
|
1439
|
+
id: string;
|
|
1440
|
+
name: string;
|
|
1441
|
+
/** The stored state as the current model supports it. */
|
|
1442
|
+
state: SheetsViewState;
|
|
1443
|
+
/** What the model no longer supports, as messages for the user. */
|
|
1444
|
+
dropped: readonly SheetsViewStateDrop[];
|
|
1445
|
+
updatedAt: string;
|
|
1446
|
+
}
|
|
1447
|
+
interface SavedViewsBindings {
|
|
1448
|
+
/** 'loading' until the stored views and the table model are both there. */
|
|
1449
|
+
status: 'loading' | 'ready' | 'error';
|
|
1450
|
+
/** Why the views could not be loaded or the last change failed, or null. */
|
|
1451
|
+
error: string | null;
|
|
1452
|
+
views: readonly SavedView[];
|
|
1453
|
+
/** The view in use, or null for the default view (nothing saved). */
|
|
1454
|
+
activeView: SavedView | null;
|
|
1455
|
+
/** The grid differs from the active view as saved. Always false for the default view. */
|
|
1456
|
+
dirty: boolean;
|
|
1457
|
+
/** True while a change is being written. */
|
|
1458
|
+
busy: boolean;
|
|
1459
|
+
/** Messages about parts of the active view the model dropped when it loaded. */
|
|
1460
|
+
activeDropped: readonly SheetsViewStateDrop[];
|
|
1461
|
+
/** Switch to a view, or with null to the default view (no filter, sort or search, every field shown). Unsaved changes are discarded. */
|
|
1462
|
+
select: (viewId: string | null) => Promise<boolean>;
|
|
1463
|
+
/** Save the grid as a new view and switch to it. */
|
|
1464
|
+
create: (name: string) => Promise<boolean>;
|
|
1465
|
+
/** Save the grid into the active view. */
|
|
1466
|
+
save: () => Promise<boolean>;
|
|
1467
|
+
/** Go back to the active view as saved. */
|
|
1468
|
+
discard: () => void;
|
|
1469
|
+
rename: (viewId: string, name: string) => Promise<boolean>;
|
|
1470
|
+
/** Copy a view under a new name and switch to the copy. */
|
|
1471
|
+
duplicate: (viewId: string) => Promise<boolean>;
|
|
1472
|
+
remove: (viewId: string) => Promise<boolean>;
|
|
1473
|
+
/** Load the views again after an error. */
|
|
1474
|
+
retry: () => void;
|
|
1475
|
+
/** Why a name cannot be used, or null. */
|
|
1476
|
+
nameProblem: (name: string, exceptViewId?: string) => string | null;
|
|
1477
|
+
open: boolean;
|
|
1478
|
+
setOpen: (open: boolean) => void;
|
|
1479
|
+
}
|
|
1480
|
+
|
|
966
1481
|
/** Draft-row bindings for a headless shell. */
|
|
967
1482
|
interface SheetsDraftBindings {
|
|
968
1483
|
/** Whether any client-side draft rows exist. */
|
|
@@ -973,6 +1488,8 @@ interface SheetsDraftBindings {
|
|
|
973
1488
|
submitDrafts: () => Promise<void>;
|
|
974
1489
|
/** Delete the currently selected rows (draft + server). */
|
|
975
1490
|
deleteSelected: () => Promise<void>;
|
|
1491
|
+
/** Delete these rows by index: a saved row is deleted, a new row is discarded. */
|
|
1492
|
+
deleteRows: (rows: readonly number[]) => Promise<void>;
|
|
976
1493
|
}
|
|
977
1494
|
/**
|
|
978
1495
|
* Selection bindings for a headless shell.
|
|
@@ -1024,6 +1541,8 @@ interface UseSheetsResult {
|
|
|
1024
1541
|
isEmpty: boolean;
|
|
1025
1542
|
/** Refetch the underlying data (mode-aware: infinite vs paginated). */
|
|
1026
1543
|
refetch: () => void;
|
|
1544
|
+
/** Read the table's shape (`_meta`) and its rows again. */
|
|
1545
|
+
refreshFromServer: () => void;
|
|
1027
1546
|
}
|
|
1028
1547
|
/**
|
|
1029
1548
|
* Internal bindings consumed only by the built-in {@link Sheets} chrome
|
|
@@ -1036,34 +1555,40 @@ interface SheetsShellBindings {
|
|
|
1036
1555
|
serverRowCount: number;
|
|
1037
1556
|
draftRowCount: number;
|
|
1038
1557
|
infiniteScroll: boolean;
|
|
1039
|
-
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
|
|
1048
|
-
|
|
1558
|
+
/** @internal Filter, sort and search state and actions (toolbar, header, view commands). NOT a stable API. */
|
|
1559
|
+
view: SheetsViewBindings;
|
|
1560
|
+
/** @internal Saved views of the table (switcher, save, discard). NOT a stable API. */
|
|
1561
|
+
savedViews: SavedViewsBindings;
|
|
1562
|
+
/** Number of filter conditions in the state, applied or not. */
|
|
1563
|
+
filterConditionCount: number;
|
|
1564
|
+
/** The list filter and sort of the view, as the data hooks get them (full-result export). */
|
|
1565
|
+
viewQuery: {
|
|
1566
|
+
where: Readonly<Record<string, unknown>> | undefined;
|
|
1567
|
+
orderBy: readonly SortSpec[] | undefined;
|
|
1568
|
+
};
|
|
1569
|
+
/** True while rows for the current filter, sort or search are being fetched (the previous rows may still show). */
|
|
1570
|
+
isFetchingRows: boolean;
|
|
1049
1571
|
setGridSelectionForControls: (selection: SheetsSelection | null) => void;
|
|
1050
|
-
/** Header sort toggle (colIndex → toggleSorting on the sortable column). */
|
|
1051
|
-
onHeaderClicked: (colIndex: number) => void;
|
|
1052
1572
|
/** Prefetch the rows in an inclusive visible window (native range, infinite mode). */
|
|
1053
1573
|
onVisibleRegionChanged: (range: VisibleRowRange) => void;
|
|
1054
|
-
/**
|
|
1055
|
-
|
|
1574
|
+
/** Changes exactly when sort, filters or search change the rows (selection resets on it). */
|
|
1575
|
+
viewSignature: string;
|
|
1056
1576
|
/** @internal Committed column widths (id → px) — the DOM grid maps these to v9 columnSizing. NOT a stable API. */
|
|
1057
1577
|
columnWidths: ReturnType<typeof useGridState>['state']['columnWidths'];
|
|
1058
1578
|
/** @internal Commit a column width (id, px) — the DOM resize handle drives this directly. NOT a stable API. */
|
|
1059
1579
|
resizeColumn: ReturnType<typeof useGridState>['actions']['resizeColumn'];
|
|
1580
|
+
/** Leading columns that stay in place under horizontal scroll (the view's layout). */
|
|
1060
1581
|
frozenCount: number;
|
|
1582
|
+
/** Row height in pixels (the view's layout). */
|
|
1583
|
+
rowHeightPx: number;
|
|
1061
1584
|
selectedRowCount: number;
|
|
1062
1585
|
canCreate: boolean;
|
|
1063
1586
|
canUpdate: boolean;
|
|
1064
1587
|
canDelete: boolean;
|
|
1065
|
-
/** Human-readable reason shown when
|
|
1588
|
+
/** Human-readable reason shown when the table model proves rows cannot be changed. */
|
|
1066
1589
|
readOnlyReason: string | null;
|
|
1590
|
+
/** @internal The table model (kinds, options, write flags, relations, sort and filter names), or null while it loads. NOT a stable API. */
|
|
1591
|
+
tableModel: TableModel | null;
|
|
1067
1592
|
/** Stable identity for selection, TanStack rows, and editor instances. */
|
|
1068
1593
|
getRowId: (row: SheetsRow | null | undefined, index: number) => string;
|
|
1069
1594
|
isSubmittingDrafts: boolean;
|
|
@@ -1091,6 +1616,8 @@ interface SheetsShellBindings {
|
|
|
1091
1616
|
canUndo: boolean;
|
|
1092
1617
|
/** @internal Whether a redo is available. NOT a stable API. */
|
|
1093
1618
|
canRedo: boolean;
|
|
1619
|
+
/** @internal Add a step to the undo history (a link editor's saved change). NOT a stable API. */
|
|
1620
|
+
recordHistory: (entry: HistoryEntry) => void;
|
|
1094
1621
|
/** @internal Observational event emitter (analytics/telemetry) — threaded into the command context. NOT a stable API. */
|
|
1095
1622
|
emit: (type: SheetsEvent['type'], meta?: Record<string, unknown>) => void;
|
|
1096
1623
|
}
|
|
@@ -1098,6 +1625,7 @@ type UseSheetsInternalResult<TRow extends SheetsRow = SheetsRow> = UseSheetsResu
|
|
|
1098
1625
|
/** @internal Bindings for the built-in <Sheets> chrome — not a stable API. */
|
|
1099
1626
|
_shell: SheetsShellBindings;
|
|
1100
1627
|
};
|
|
1628
|
+
|
|
1101
1629
|
/**
|
|
1102
1630
|
* Headless grid hook — returns the data/state bindings the built-in {@link Sheets}
|
|
1103
1631
|
* component renders with the native DOM grid.
|
|
@@ -1112,6 +1640,229 @@ type UseSheetsInternalResult<TRow extends SheetsRow = SheetsRow> = UseSheetsResu
|
|
|
1112
1640
|
*/
|
|
1113
1641
|
declare function useSheets<TRow extends SheetsRow = SheetsRow>(props: DataGridProps<TRow>): UseSheetsInternalResult<TRow>;
|
|
1114
1642
|
|
|
1643
|
+
/** The reason a grid shows for `readOnly={true}`. */
|
|
1644
|
+
declare const DEFAULT_READ_ONLY_REASON = "This table is read-only here.";
|
|
1645
|
+
interface SheetsReadOnlyProviderProps {
|
|
1646
|
+
/** `true`, or the reason to show; false or omitted leaves writes to the table model. */
|
|
1647
|
+
readOnly?: boolean | string | null;
|
|
1648
|
+
children: ReactNode;
|
|
1649
|
+
}
|
|
1650
|
+
/**
|
|
1651
|
+
* Make everything inside read-only with a reason. `<Sheets readOnly>` renders it;
|
|
1652
|
+
* a host driving `useSheets` itself wraps its grid in it.
|
|
1653
|
+
*/
|
|
1654
|
+
declare function SheetsReadOnlyProvider({ readOnly, children }: SheetsReadOnlyProviderProps): react.JSX.Element;
|
|
1655
|
+
|
|
1656
|
+
interface RowRemoval {
|
|
1657
|
+
/** The row indexes to remove. */
|
|
1658
|
+
rows: readonly number[];
|
|
1659
|
+
/** Saved rows among them: deleted on the server. */
|
|
1660
|
+
saved: number;
|
|
1661
|
+
/** New rows among them: discarded. */
|
|
1662
|
+
unsaved: number;
|
|
1663
|
+
/** Why these rows cannot be removed, or null. */
|
|
1664
|
+
blockedReason: string | null;
|
|
1665
|
+
}
|
|
1666
|
+
|
|
1667
|
+
interface SheetsControlsProps {
|
|
1668
|
+
/** Filter, sort and search bindings. */
|
|
1669
|
+
view: SheetsViewBindings;
|
|
1670
|
+
/** Grid columns, in display order. */
|
|
1671
|
+
columnKeys: readonly string[];
|
|
1672
|
+
showSelection: boolean;
|
|
1673
|
+
gridSelection: SheetsSelection | null;
|
|
1674
|
+
setGridSelection: (selection: SheetsSelection | null) => void;
|
|
1675
|
+
deleteSelected: () => void;
|
|
1676
|
+
onAddRow?: () => void;
|
|
1677
|
+
/** Download the selected rows as CSV; offered only while rows are selected. */
|
|
1678
|
+
onExport?: () => void;
|
|
1679
|
+
canDelete?: boolean;
|
|
1680
|
+
/** What deleting the selected rows does (saved rows deleted, new rows discarded); refines `canDelete`. */
|
|
1681
|
+
selectionRemoval?: RowRemoval;
|
|
1682
|
+
readOnlyReason?: string | null;
|
|
1683
|
+
/** Saved views of the table. Omit to hide the view switcher. */
|
|
1684
|
+
savedViews?: SavedViewsBindings;
|
|
1685
|
+
/** More toolbar actions (import, export of the whole view), placed before New record. */
|
|
1686
|
+
tools?: React.ReactNode;
|
|
1687
|
+
/** Open the record panel's new-record form; `disabledReason` says why it cannot open. Omit to hide. */
|
|
1688
|
+
newRecord?: {
|
|
1689
|
+
open: () => void;
|
|
1690
|
+
disabledReason: string | null;
|
|
1691
|
+
};
|
|
1692
|
+
}
|
|
1693
|
+
declare function SheetsControls(props: SheetsControlsProps): react.JSX.Element;
|
|
1694
|
+
|
|
1695
|
+
interface ImportRecordsControlProps {
|
|
1696
|
+
/** The table to add records to, or null while it loads. */
|
|
1697
|
+
model: TableModel | null;
|
|
1698
|
+
/** Name used in the dialog title and the error report's file name. Default: the table name. */
|
|
1699
|
+
tableLabel?: string;
|
|
1700
|
+
}
|
|
1701
|
+
declare function ImportRecordsControl({ model, tableLabel }: ImportRecordsControlProps): react.JSX.Element;
|
|
1702
|
+
|
|
1703
|
+
interface ExportViewControlProps {
|
|
1704
|
+
/** The table, or null while it loads. */
|
|
1705
|
+
model: TableModel | null;
|
|
1706
|
+
/** The view's filter, search included. */
|
|
1707
|
+
where?: Readonly<Record<string, unknown>>;
|
|
1708
|
+
orderBy?: readonly SortSpec[];
|
|
1709
|
+
/** The view's column keys in order (column names and relation field names). Default: every grid column. */
|
|
1710
|
+
columns?: readonly string[];
|
|
1711
|
+
/** Download file name. Default: the table name with `.csv`. */
|
|
1712
|
+
filename?: string;
|
|
1713
|
+
/** Prefix text that starts like a spreadsheet formula with an apostrophe (see `formula-protection.ts`). Default false. */
|
|
1714
|
+
protectFormulas?: boolean;
|
|
1715
|
+
}
|
|
1716
|
+
declare function ExportViewControl({ model, where, orderBy, columns, filename, protectFormulas }: ExportViewControlProps): react.JSX.Element;
|
|
1717
|
+
|
|
1718
|
+
/**
|
|
1719
|
+
* Check a stored view state against the current table model.
|
|
1720
|
+
*
|
|
1721
|
+
* Pure: returns a state that only names columns, operators, options and
|
|
1722
|
+
* relations the model has, and a list of what it dropped and why. Use it to load
|
|
1723
|
+
* a saved view; the grid also runs it on every state it receives, so a stale
|
|
1724
|
+
* state never reaches the server. A version 1 state (before the column layout)
|
|
1725
|
+
* loads with the default layout.
|
|
1726
|
+
*/
|
|
1727
|
+
|
|
1728
|
+
interface ValidateSheetsViewStateOptions {
|
|
1729
|
+
/** Column or relation title for messages; defaults to the field name. */
|
|
1730
|
+
label?: (name: string) => string;
|
|
1731
|
+
}
|
|
1732
|
+
/**
|
|
1733
|
+
* A state the model supports, from any stored value. Unknown columns,
|
|
1734
|
+
* operators, options and relations are dropped and reported; an unreadable
|
|
1735
|
+
* value becomes the empty state.
|
|
1736
|
+
*/
|
|
1737
|
+
declare function validateSheetsViewState(input: unknown, model: TableModel, options?: ValidateSheetsViewStateOptions): SheetsViewStateValidation;
|
|
1738
|
+
|
|
1739
|
+
/** Deepest nesting the filter builder offers (the root group is depth 0). */
|
|
1740
|
+
declare const MAX_FILTER_DEPTH = 3;
|
|
1741
|
+
declare function createFilterGroup(logic?: SheetsFilterLogic, children?: readonly SheetsFilterNode[]): SheetsFilterGroup;
|
|
1742
|
+
/** The state with no filter, no sort, no search, and every column shown in the table's order. */
|
|
1743
|
+
declare function createSheetsViewState(): SheetsViewState;
|
|
1744
|
+
/** Every condition in a group, depth first. */
|
|
1745
|
+
declare function filterConditionsOf(node: SheetsFilterNode): SheetsFilterCondition[];
|
|
1746
|
+
/**
|
|
1747
|
+
* The sort after a header click. A plain click cycles that column alone
|
|
1748
|
+
* (ascending, descending, none) and replaces any other key. An additive click
|
|
1749
|
+
* (Shift) adds the column as the last key, flips it, or removes it, and keeps
|
|
1750
|
+
* the other keys.
|
|
1751
|
+
*/
|
|
1752
|
+
declare function cycleSort(sort: readonly SheetsSortKey[], column: string, additive: boolean): SheetsSortKey[];
|
|
1753
|
+
|
|
1754
|
+
/**
|
|
1755
|
+
* Column layout: pure helpers over `SheetsColumnLayout`.
|
|
1756
|
+
*
|
|
1757
|
+
* `available` is always the table's grid column keys in the table's order
|
|
1758
|
+
* (`gridColumnKeys(model)`). A layout names keys by field name, so it survives
|
|
1759
|
+
* a schema change: keys it names that the table lost are ignored here (and
|
|
1760
|
+
* reported by the validator), keys the table gained follow at the end.
|
|
1761
|
+
*/
|
|
1762
|
+
|
|
1763
|
+
/** Row height of each setting, in pixels. */
|
|
1764
|
+
declare const ROW_HEIGHT_PX: Readonly<Record<SheetsRowHeight, number>>;
|
|
1765
|
+
/** The layout with every column shown in the table's order and the first column frozen. */
|
|
1766
|
+
declare function createColumnLayout(): SheetsColumnLayout;
|
|
1767
|
+
/** Every available key in display order: the layout's order first, then the rest in the table's order. */
|
|
1768
|
+
declare function orderedColumnKeys(available: readonly string[], layout: SheetsColumnLayout): string[];
|
|
1769
|
+
/** The keys that show, in display order. */
|
|
1770
|
+
declare function visibleColumnKeys(available: readonly string[], layout: SheetsColumnLayout): string[];
|
|
1771
|
+
|
|
1772
|
+
/**
|
|
1773
|
+
* Filter operators from the table model.
|
|
1774
|
+
*
|
|
1775
|
+
* A column offers exactly the operators its filter input really has
|
|
1776
|
+
* (`ColumnModel.filter.operators`). Each operator gets a plain label, a group,
|
|
1777
|
+
* and the value control its input shape and the column's kind call for. An
|
|
1778
|
+
* operator this file does not know still appears, named from its field name.
|
|
1779
|
+
*/
|
|
1780
|
+
|
|
1781
|
+
type FilterOperatorGroup = 'match' | 'text' | 'compare' | 'items' | 'empty' | 'other';
|
|
1782
|
+
/** A control for one value. */
|
|
1783
|
+
type ScalarValueControl = {
|
|
1784
|
+
kind: 'text';
|
|
1785
|
+
}
|
|
1786
|
+
/** A whole number that fits a JavaScript number; sent as a number. */
|
|
1787
|
+
| {
|
|
1788
|
+
kind: 'integer';
|
|
1789
|
+
}
|
|
1790
|
+
/** A floating-point number; sent as a number. */
|
|
1791
|
+
| {
|
|
1792
|
+
kind: 'number';
|
|
1793
|
+
}
|
|
1794
|
+
/** A whole number of any size; sent as exact text. */
|
|
1795
|
+
| {
|
|
1796
|
+
kind: 'exact-integer';
|
|
1797
|
+
}
|
|
1798
|
+
/** A decimal number of any size; sent as exact text. */
|
|
1799
|
+
| {
|
|
1800
|
+
kind: 'exact-decimal';
|
|
1801
|
+
} | {
|
|
1802
|
+
kind: 'date';
|
|
1803
|
+
} | {
|
|
1804
|
+
kind: 'datetime';
|
|
1805
|
+
} | {
|
|
1806
|
+
kind: 'time';
|
|
1807
|
+
} | {
|
|
1808
|
+
kind: 'boolean';
|
|
1809
|
+
}
|
|
1810
|
+
/** One of a fixed list. `value` is the wire value. */
|
|
1811
|
+
| {
|
|
1812
|
+
kind: 'choice';
|
|
1813
|
+
options: readonly ColumnOption[];
|
|
1814
|
+
} | {
|
|
1815
|
+
kind: 'json';
|
|
1816
|
+
};
|
|
1817
|
+
interface FilterValueField {
|
|
1818
|
+
name: string;
|
|
1819
|
+
label: string;
|
|
1820
|
+
required: boolean;
|
|
1821
|
+
control: ScalarValueControl;
|
|
1822
|
+
}
|
|
1823
|
+
/** The control a condition shows for its operator. */
|
|
1824
|
+
type FilterValueControl = ScalarValueControl
|
|
1825
|
+
/** The operator takes no value from the user. */
|
|
1826
|
+
| {
|
|
1827
|
+
kind: 'none';
|
|
1828
|
+
}
|
|
1829
|
+
/** The operator takes a list of values. */
|
|
1830
|
+
| {
|
|
1831
|
+
kind: 'multi';
|
|
1832
|
+
item: ScalarValueControl;
|
|
1833
|
+
}
|
|
1834
|
+
/** The operator takes an object: one control per field. */
|
|
1835
|
+
| {
|
|
1836
|
+
kind: 'fields';
|
|
1837
|
+
fields: readonly FilterValueField[];
|
|
1838
|
+
}
|
|
1839
|
+
/** The editor cannot enter this operator's value. */
|
|
1840
|
+
| {
|
|
1841
|
+
kind: 'unsupported';
|
|
1842
|
+
reason: string;
|
|
1843
|
+
};
|
|
1844
|
+
interface FilterOperatorOption {
|
|
1845
|
+
/** Unique within a column: the operator name, or `isNull:true` / `isNull:false`. */
|
|
1846
|
+
id: string;
|
|
1847
|
+
/** Operator field name. */
|
|
1848
|
+
operator: string;
|
|
1849
|
+
label: string;
|
|
1850
|
+
group: FilterOperatorGroup;
|
|
1851
|
+
control: FilterValueControl;
|
|
1852
|
+
/** The operand of an operator that takes no value from the user (`isNull`). */
|
|
1853
|
+
fixedValue?: boolean;
|
|
1854
|
+
}
|
|
1855
|
+
/** The label of one operator on one column. */
|
|
1856
|
+
declare function filterOperatorLabel(column: ColumnModel, operator: string): string;
|
|
1857
|
+
/**
|
|
1858
|
+
* Every operator a column's filter has, as the builder offers them: grouped,
|
|
1859
|
+
* labelled, each with its value control. `isNull` becomes two choices, "is
|
|
1860
|
+
* empty" and "is not empty". Empty when the column cannot be filtered.
|
|
1861
|
+
*/
|
|
1862
|
+
declare function filterOperatorOptions(column: ColumnModel): FilterOperatorOption[];
|
|
1863
|
+
/** The operator a new condition on this column starts with. */
|
|
1864
|
+
declare function defaultOperatorOption(column: ColumnModel): FilterOperatorOption | null;
|
|
1865
|
+
|
|
1115
1866
|
interface SheetsPaginationProps {
|
|
1116
1867
|
pageIndex: number;
|
|
1117
1868
|
pageSize: number;
|
|
@@ -1121,9 +1872,29 @@ interface SheetsPaginationProps {
|
|
|
1121
1872
|
}
|
|
1122
1873
|
declare function SheetsPagination(props: SheetsPaginationProps): react.JSX.Element;
|
|
1123
1874
|
|
|
1875
|
+
interface SheetsStatusBarProps {
|
|
1876
|
+
/** Rows the server reports for the current filter and search; null until the first count for this view arrives. */
|
|
1877
|
+
total: number | null;
|
|
1878
|
+
/** A filter or a search narrows the rows ("12 matching rows"). */
|
|
1879
|
+
filtered: boolean;
|
|
1880
|
+
/** The rows are being fetched again; the count may change. */
|
|
1881
|
+
updating?: boolean;
|
|
1882
|
+
/** More status after the count (the grid passes its save status). */
|
|
1883
|
+
children?: ReactNode;
|
|
1884
|
+
}
|
|
1885
|
+
declare function SheetsStatusBar({ total, filtered, updating, children }: SheetsStatusBarProps): react.JSX.Element;
|
|
1886
|
+
|
|
1124
1887
|
type TableWithCategory = {
|
|
1888
|
+
/** The value `onTableChange` receives and `activeTable` matches, for example a `TableModel.key`. */
|
|
1125
1889
|
name: string;
|
|
1890
|
+
/** What the list shows. Default: `name`. The search matches both. */
|
|
1891
|
+
label?: string;
|
|
1126
1892
|
category?: string;
|
|
1893
|
+
/**
|
|
1894
|
+
* A table a platform module made (see `isSystemTable` in `@constructive-io/data`). System tables
|
|
1895
|
+
* show in their own section, and only while "Show system tables" is on (off by default).
|
|
1896
|
+
*/
|
|
1897
|
+
system?: boolean;
|
|
1127
1898
|
};
|
|
1128
1899
|
interface TableSelectorProps {
|
|
1129
1900
|
tables: string[] | TableWithCategory[];
|
|
@@ -1137,6 +1908,48 @@ interface TableSelectorProps {
|
|
|
1137
1908
|
}
|
|
1138
1909
|
declare const SheetsTableSelector: react__default.NamedExoticComponent<TableSelectorProps>;
|
|
1139
1910
|
|
|
1911
|
+
/** Whether system tables show in table lists, and the setter every list on the page follows. */
|
|
1912
|
+
declare function useShowSystemTables(): [boolean, (show: boolean) => void];
|
|
1913
|
+
/**
|
|
1914
|
+
* The tables a list shows: the owner's, and the system tables only while they are shown. The open
|
|
1915
|
+
* table always stays, so a system table opened by a link or an address is never missing from the list.
|
|
1916
|
+
*/
|
|
1917
|
+
declare function visibleTables<T extends {
|
|
1918
|
+
system?: boolean;
|
|
1919
|
+
}>(tables: readonly T[], showSystem: boolean, isOpen: (table: T) => boolean): T[];
|
|
1920
|
+
|
|
1921
|
+
interface UseTableModelOptions {
|
|
1922
|
+
/** Resolve the model. Default true. */
|
|
1923
|
+
enabled?: boolean;
|
|
1924
|
+
}
|
|
1925
|
+
interface UseTableModelResult {
|
|
1926
|
+
/** The model, or null while it loads or when it failed. */
|
|
1927
|
+
model: TableModel | null;
|
|
1928
|
+
/** `TableModel.key` of the requested table, or null until `_meta` has loaded or when the name is unknown. */
|
|
1929
|
+
tableKey: TableKey | null;
|
|
1930
|
+
/** The `_meta` entry of the table, or null. */
|
|
1931
|
+
metaTable: MetaschemaTable | null;
|
|
1932
|
+
/** True until the model is ready (or failed). */
|
|
1933
|
+
isLoading: boolean;
|
|
1934
|
+
/** Why the model is unavailable: `_meta` failed, the name is unknown or ambiguous, or this table failed. */
|
|
1935
|
+
error: Error | null;
|
|
1936
|
+
/** Load again what failed: `_meta` when it failed (the model follows), otherwise this table's model. */
|
|
1937
|
+
refetch: () => Promise<void>;
|
|
1938
|
+
}
|
|
1939
|
+
declare function useTableModel(tableRef: string | null | undefined, options?: UseTableModelOptions): UseTableModelResult;
|
|
1940
|
+
interface UseTableModelsResult {
|
|
1941
|
+
/** The models that have loaded, by `TableModel.key`. A table that failed or is unknown is absent. */
|
|
1942
|
+
models: ReadonlyMap<TableKey, TableModel>;
|
|
1943
|
+
/** True while `_meta` or any of the models still loads. */
|
|
1944
|
+
isLoading: boolean;
|
|
1945
|
+
}
|
|
1946
|
+
/**
|
|
1947
|
+
* The models of a variable set of tables (names or keys), with the same cache
|
|
1948
|
+
* entries as `useTableModel`. Unknown or ambiguous names are skipped; use
|
|
1949
|
+
* `useTableModel` for one table's error.
|
|
1950
|
+
*/
|
|
1951
|
+
declare function useTableModels(refs: readonly string[], options?: UseTableModelOptions): UseTableModelsResult;
|
|
1952
|
+
|
|
1140
1953
|
interface UseMetaOptions {
|
|
1141
1954
|
enabled?: boolean;
|
|
1142
1955
|
}
|
|
@@ -1147,10 +1960,14 @@ type DeleteIdentifier = SheetsRowIdentifier;
|
|
|
1147
1960
|
/**
|
|
1148
1961
|
* Unified table hook options
|
|
1149
1962
|
*/
|
|
1150
|
-
interface UseTableOptions extends QueryOptions {
|
|
1963
|
+
interface UseTableOptions extends Omit<QueryOptions, 'where'> {
|
|
1964
|
+
/** A filter in the server's filter input shape (any operator the model reports, relation and search fields included). */
|
|
1965
|
+
where?: Readonly<Record<string, unknown>>;
|
|
1966
|
+
/** Columns to fetch (the primary key and relation keys are always added). Omitted: every readable column. */
|
|
1967
|
+
columns?: readonly string[];
|
|
1151
1968
|
/** Enable/disable automatic data fetching */
|
|
1152
1969
|
enabled?: boolean;
|
|
1153
|
-
/** Field selection for queries */
|
|
1970
|
+
/** Field selection for queries: `includeRelations` (or the `full` preset) chooses the relations to select. */
|
|
1154
1971
|
select?: FieldSelection;
|
|
1155
1972
|
/** Mutation options */
|
|
1156
1973
|
mutationOptions?: MutationOptions;
|
|
@@ -1162,7 +1979,11 @@ interface UseTableResult<TData extends RowRecord$1 = RowRecord$1> {
|
|
|
1162
1979
|
data: TData[];
|
|
1163
1980
|
totalCount: number;
|
|
1164
1981
|
isLoading: boolean;
|
|
1982
|
+
/** True while a request for the current options is in flight, also while the previous rows are still shown. */
|
|
1983
|
+
isFetching: boolean;
|
|
1165
1984
|
error: Error | null;
|
|
1985
|
+
/** The table model, or null while it loads or when it failed. */
|
|
1986
|
+
model: TableModel | null;
|
|
1166
1987
|
findOne: (id: SheetsRowIdentifier) => Promise<TData | null>;
|
|
1167
1988
|
create: (data: RowRecord$1) => Promise<{
|
|
1168
1989
|
createdRow: TData | null;
|
|
@@ -1183,14 +2004,15 @@ interface UseTableResult<TData extends RowRecord$1 = RowRecord$1> {
|
|
|
1183
2004
|
invalidate: () => void;
|
|
1184
2005
|
}
|
|
1185
2006
|
/**
|
|
1186
|
-
* Generate query keys for consistent cache management
|
|
2007
|
+
* Generate query keys for consistent cache management. `tableRef` is a
|
|
2008
|
+
* `TableModel.key` or a table name.
|
|
1187
2009
|
*/
|
|
1188
2010
|
declare const sheetsTableQueryKeys: {
|
|
1189
2011
|
scope: (scope: SheetsScopeKey) => readonly ["sheets", SheetsScopeKey];
|
|
1190
|
-
table: (scope: SheetsScopeKey,
|
|
1191
|
-
tableRows: (scope: SheetsScopeKey,
|
|
1192
|
-
tableRow: (scope: SheetsScopeKey,
|
|
1193
|
-
tableCount: (scope: SheetsScopeKey,
|
|
2012
|
+
table: (scope: SheetsScopeKey, tableRef: string) => readonly ["sheets", SheetsScopeKey, "table", ...string[]];
|
|
2013
|
+
tableRows: (scope: SheetsScopeKey, tableRef: string, options?: unknown) => readonly ["sheets", SheetsScopeKey, "table", ...string[], "rows", unknown];
|
|
2014
|
+
tableRow: (scope: SheetsScopeKey, tableRef: string, id: unknown) => readonly ["sheets", SheetsScopeKey, "table", ...string[], "row", unknown];
|
|
2015
|
+
tableCount: (scope: SheetsScopeKey, tableRef: string, where?: Readonly<Record<string, unknown>>) => readonly ["sheets", SheetsScopeKey, "table", ...string[], "count", Readonly<Record<string, unknown>> | null | undefined];
|
|
1194
2016
|
};
|
|
1195
2017
|
/**
|
|
1196
2018
|
* Main unified table hook
|
|
@@ -1203,7 +2025,10 @@ interface UseSheetsTableCursorOptions {
|
|
|
1203
2025
|
enabled?: boolean;
|
|
1204
2026
|
select?: FieldSelection;
|
|
1205
2027
|
pageSize?: number;
|
|
1206
|
-
|
|
2028
|
+
/** A filter in the server's filter input shape. */
|
|
2029
|
+
where?: Readonly<Record<string, unknown>>;
|
|
2030
|
+
/** Columns to fetch (the primary key and relation keys are always added). Omitted: every readable column. */
|
|
2031
|
+
columns?: readonly string[];
|
|
1207
2032
|
orderBy?: Array<{
|
|
1208
2033
|
field: string;
|
|
1209
2034
|
direction: 'asc' | 'desc';
|
|
@@ -1220,105 +2045,253 @@ interface UseSheetsTableCursorResult<TData extends RowRecord = RowRecord> {
|
|
|
1220
2045
|
}
|
|
1221
2046
|
declare function useSheetsTableCursor<TData extends RowRecord = RowRecord>(tableName: string, options?: UseSheetsTableCursorOptions): UseSheetsTableCursorResult<TData>;
|
|
1222
2047
|
|
|
1223
|
-
|
|
1224
|
-
|
|
1225
|
-
|
|
1226
|
-
interface UploadProgress {
|
|
1227
|
-
loaded: number;
|
|
1228
|
-
total: number;
|
|
1229
|
-
percentage: number;
|
|
2048
|
+
interface SendFileOptions extends TransferOptions {
|
|
2049
|
+
/** The row the file is for, passed to a host-injected uploader. */
|
|
2050
|
+
recordId?: string | number;
|
|
1230
2051
|
}
|
|
1231
|
-
/**
|
|
1232
|
-
|
|
1233
|
-
|
|
1234
|
-
|
|
1235
|
-
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
2052
|
+
/** Sends one file to storage and resolves to its projection. */
|
|
2053
|
+
type SendFile = (file: File, options?: SendFileOptions) => Promise<FileProjection>;
|
|
2054
|
+
type ColumnUploadState = {
|
|
2055
|
+
status: 'ready';
|
|
2056
|
+
send: SendFile;
|
|
2057
|
+
} | {
|
|
2058
|
+
status: 'unavailable';
|
|
2059
|
+
reason: string;
|
|
2060
|
+
};
|
|
2061
|
+
interface ColumnStorage {
|
|
2062
|
+
choices: ResolvedUploadChoices;
|
|
2063
|
+
upload: ColumnUploadState;
|
|
2064
|
+
/** Resolves download URLs by file id, or null when this column's previews cannot be signed. */
|
|
2065
|
+
resolveUrls: ((ids: readonly string[]) => Promise<Map<string, string>>) | null;
|
|
2066
|
+
/** Identity of the URL resolver, for batching and caching. */
|
|
2067
|
+
previewKey: string | null;
|
|
2068
|
+
}
|
|
2069
|
+
|
|
2070
|
+
type UploadProgress = UploadProgressEvent;
|
|
2071
|
+
/** The value a file cell stores after a write: a projection, a link, a list, or null. */
|
|
2072
|
+
type UploadResponse = unknown;
|
|
2073
|
+
interface UseColumnStorageResult {
|
|
2074
|
+
storage: ColumnStorage | null;
|
|
2075
|
+
isLoading: boolean;
|
|
2076
|
+
error: Error | null;
|
|
2077
|
+
}
|
|
2078
|
+
/** Where a file column uploads to and how its previews are signed. Resolved once per column. */
|
|
2079
|
+
declare function useColumnStorage(table: TableModel | null | undefined, column: ColumnModel | null | undefined): UseColumnStorageResult;
|
|
2080
|
+
type FileUploadState = {
|
|
2081
|
+
status: 'loading';
|
|
2082
|
+
} | {
|
|
2083
|
+
status: 'ready';
|
|
2084
|
+
send: SendFile;
|
|
2085
|
+
} | {
|
|
2086
|
+
status: 'unavailable';
|
|
2087
|
+
reason: string;
|
|
2088
|
+
};
|
|
2089
|
+
/** Whether the column can take a new file now, and the uploader when it can. */
|
|
2090
|
+
declare function useFileUploadState(table: TableModel | null | undefined, column: ColumnModel | null | undefined, readOnlyReason?: string | null): FileUploadState;
|
|
2091
|
+
interface FileCellWriteJob {
|
|
2092
|
+
table: TableModel;
|
|
2093
|
+
column: ColumnModel;
|
|
2094
|
+
/** Primary-key identity of the row. */
|
|
2095
|
+
rowKey: SheetsRowIdentifier;
|
|
2096
|
+
/** Grid row id, which keys the cell's pending state. */
|
|
2097
|
+
rowId: string;
|
|
2098
|
+
value: unknown;
|
|
2099
|
+
/** Called when the server first answers that the file is still processing. */
|
|
2100
|
+
onProcessing?: () => void;
|
|
2101
|
+
signal?: AbortSignal;
|
|
2102
|
+
}
|
|
2103
|
+
/**
|
|
2104
|
+
* Write a file cell. While the server confirms the file the cell shows
|
|
2105
|
+
* "Processing file…"; a failure stays on the cell with a retry, even when the
|
|
2106
|
+
* editor has closed, so an uploaded file is never dropped silently.
|
|
2107
|
+
*/
|
|
2108
|
+
declare function useFileCellWriter(): (job: FileCellWriteJob) => Promise<unknown>;
|
|
2109
|
+
interface FieldUploadTarget {
|
|
2110
|
+
table: TableModel;
|
|
2111
|
+
/** Column name. */
|
|
2112
|
+
column: string;
|
|
2113
|
+
rowKey: SheetsRowIdentifier;
|
|
2114
|
+
}
|
|
2115
|
+
interface FieldUploadTransport {
|
|
2116
|
+
/** Data executor for the cell write. */
|
|
2117
|
+
execute: SheetsExecuteFn;
|
|
2118
|
+
adapter: Pick<SheetsBackendAdapter, 'updateRow'>;
|
|
2119
|
+
/** Sends the file to storage (from `useColumnStorage(...).storage.upload`). */
|
|
2120
|
+
send: SendFile;
|
|
2121
|
+
policy?: ProcessingPolicy;
|
|
2122
|
+
onProgress?: (progress: UploadProgress) => void;
|
|
2123
|
+
onProcessing?: () => void;
|
|
2124
|
+
signal?: AbortSignal;
|
|
1239
2125
|
}
|
|
1240
2126
|
/**
|
|
1241
|
-
*
|
|
2127
|
+
* Upload one file into a single-file column, or clear it with null, and write
|
|
2128
|
+
* the cell. A list column takes its whole list: write it with
|
|
2129
|
+
* {@link useFileCellWriter}.
|
|
1242
2130
|
*/
|
|
2131
|
+
declare function executeFieldUpload(target: FieldUploadTarget, file: File | null, transport: FieldUploadTransport): Promise<UploadResponse>;
|
|
2132
|
+
/** @deprecated Options of {@link useSheetsFieldUpload}. */
|
|
1243
2133
|
interface UseFieldUploadOptions {
|
|
1244
2134
|
onProgress?: (progress: UploadProgress) => void;
|
|
1245
2135
|
onSuccess?: (data: UploadResponse) => void;
|
|
1246
2136
|
onError?: (error: Error) => void;
|
|
2137
|
+
/** Ignored, as before. */
|
|
1247
2138
|
showToast?: boolean;
|
|
2139
|
+
/** Ignored, as before. */
|
|
1248
2140
|
successMessage?: string;
|
|
2141
|
+
/** Ignored, as before. */
|
|
1249
2142
|
successToastDelayMs?: number;
|
|
1250
2143
|
}
|
|
1251
|
-
|
|
1252
|
-
|
|
1253
|
-
|
|
1254
|
-
|
|
1255
|
-
|
|
1256
|
-
|
|
1257
|
-
|
|
1258
|
-
|
|
2144
|
+
/**
|
|
2145
|
+
* @deprecated Use {@link useFileUploadState} with {@link useFileCellWriter}, or
|
|
2146
|
+
* {@link executeFieldUpload}. Uploads one file into a single-file column (or
|
|
2147
|
+
* clears it with null) through the model-driven path.
|
|
2148
|
+
*/
|
|
2149
|
+
declare function useSheetsFieldUpload(tableName: string, fieldName: string, recordId: SheetsRowIdentifier | null, options?: UseFieldUploadOptions): {
|
|
2150
|
+
write: (id: SheetsRowIdentifier, file: File | null) => Promise<UploadResponse>;
|
|
2151
|
+
resolveRowIdentifier: (row: Readonly<Record<string, unknown>>) => SheetsRowIdentifier | null;
|
|
2152
|
+
data: undefined;
|
|
2153
|
+
variables: undefined;
|
|
2154
|
+
error: null;
|
|
2155
|
+
isError: false;
|
|
2156
|
+
isIdle: true;
|
|
2157
|
+
isPending: false;
|
|
2158
|
+
isSuccess: false;
|
|
2159
|
+
status: "idle";
|
|
2160
|
+
mutate: _tanstack_react_query.UseMutateFunction<unknown, Error, File | null, unknown>;
|
|
2161
|
+
reset: () => void;
|
|
2162
|
+
context: unknown;
|
|
2163
|
+
failureCount: number;
|
|
2164
|
+
failureReason: Error | null;
|
|
2165
|
+
isPaused: boolean;
|
|
2166
|
+
submittedAt: number;
|
|
2167
|
+
mutateAsync: _tanstack_react_query.UseMutateAsyncFunction<unknown, Error, File | null, unknown>;
|
|
2168
|
+
} | {
|
|
2169
|
+
write: (id: SheetsRowIdentifier, file: File | null) => Promise<UploadResponse>;
|
|
2170
|
+
resolveRowIdentifier: (row: Readonly<Record<string, unknown>>) => SheetsRowIdentifier | null;
|
|
2171
|
+
data: undefined;
|
|
2172
|
+
variables: File | null;
|
|
2173
|
+
error: null;
|
|
2174
|
+
isError: false;
|
|
2175
|
+
isIdle: false;
|
|
2176
|
+
isPending: true;
|
|
2177
|
+
isSuccess: false;
|
|
2178
|
+
status: "pending";
|
|
2179
|
+
mutate: _tanstack_react_query.UseMutateFunction<unknown, Error, File | null, unknown>;
|
|
2180
|
+
reset: () => void;
|
|
2181
|
+
context: unknown;
|
|
2182
|
+
failureCount: number;
|
|
2183
|
+
failureReason: Error | null;
|
|
2184
|
+
isPaused: boolean;
|
|
2185
|
+
submittedAt: number;
|
|
2186
|
+
mutateAsync: _tanstack_react_query.UseMutateAsyncFunction<unknown, Error, File | null, unknown>;
|
|
2187
|
+
} | {
|
|
2188
|
+
write: (id: SheetsRowIdentifier, file: File | null) => Promise<UploadResponse>;
|
|
2189
|
+
resolveRowIdentifier: (row: Readonly<Record<string, unknown>>) => SheetsRowIdentifier | null;
|
|
2190
|
+
data: undefined;
|
|
2191
|
+
error: Error;
|
|
2192
|
+
variables: File | null;
|
|
2193
|
+
isError: true;
|
|
2194
|
+
isIdle: false;
|
|
2195
|
+
isPending: false;
|
|
2196
|
+
isSuccess: false;
|
|
2197
|
+
status: "error";
|
|
2198
|
+
mutate: _tanstack_react_query.UseMutateFunction<unknown, Error, File | null, unknown>;
|
|
2199
|
+
reset: () => void;
|
|
2200
|
+
context: unknown;
|
|
2201
|
+
failureCount: number;
|
|
2202
|
+
failureReason: Error | null;
|
|
2203
|
+
isPaused: boolean;
|
|
2204
|
+
submittedAt: number;
|
|
2205
|
+
mutateAsync: _tanstack_react_query.UseMutateAsyncFunction<unknown, Error, File | null, unknown>;
|
|
2206
|
+
} | {
|
|
2207
|
+
write: (id: SheetsRowIdentifier, file: File | null) => Promise<UploadResponse>;
|
|
2208
|
+
resolveRowIdentifier: (row: Readonly<Record<string, unknown>>) => SheetsRowIdentifier | null;
|
|
2209
|
+
data: unknown;
|
|
2210
|
+
error: null;
|
|
2211
|
+
variables: File | null;
|
|
2212
|
+
isError: false;
|
|
2213
|
+
isIdle: false;
|
|
2214
|
+
isPending: false;
|
|
2215
|
+
isSuccess: true;
|
|
2216
|
+
status: "success";
|
|
2217
|
+
mutate: _tanstack_react_query.UseMutateFunction<unknown, Error, File | null, unknown>;
|
|
2218
|
+
reset: () => void;
|
|
2219
|
+
context: unknown;
|
|
2220
|
+
failureCount: number;
|
|
2221
|
+
failureReason: Error | null;
|
|
2222
|
+
isPaused: boolean;
|
|
2223
|
+
submittedAt: number;
|
|
2224
|
+
mutateAsync: _tanstack_react_query.UseMutateAsyncFunction<unknown, Error, File | null, unknown>;
|
|
2225
|
+
};
|
|
2226
|
+
|
|
2227
|
+
interface UploadToFilesTableOptions {
|
|
1259
2228
|
/**
|
|
1260
|
-
*
|
|
1261
|
-
*
|
|
1262
|
-
* both steps. When omitted (e.g. image-editor's direct retry path), the
|
|
1263
|
-
* functions are built from `endpoint`/`getToken`/`onAuthError` via the same
|
|
1264
|
-
* factories — never a raw fetch.
|
|
2229
|
+
* The storage service: its GraphQL endpoint and an executor bound to it. Pass the
|
|
2230
|
+
* same object on every call; the storage catalog and schema lookups are cached on it.
|
|
1265
2231
|
*/
|
|
1266
|
-
|
|
1267
|
-
|
|
1268
|
-
|
|
1269
|
-
|
|
1270
|
-
/**
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
|
|
1280
|
-
|
|
1281
|
-
|
|
1282
|
-
|
|
1283
|
-
|
|
1284
|
-
|
|
1285
|
-
|
|
1286
|
-
|
|
1287
|
-
|
|
1288
|
-
|
|
1289
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
1292
|
-
|
|
1293
|
-
|
|
1294
|
-
*
|
|
1295
|
-
*
|
|
1296
|
-
|
|
1297
|
-
|
|
2232
|
+
storage: SheetsStorageTransport;
|
|
2233
|
+
/** The files table: its `TableModel.key`, its GraphQL type name, or its model. */
|
|
2234
|
+
filesTable: string | Pick<TableModel, 'key' | 'name'>;
|
|
2235
|
+
file: File;
|
|
2236
|
+
/** Owner of the file, for a files table whose uploads need one. Sent only when the mutation takes `ownerId`. */
|
|
2237
|
+
ownerId?: string;
|
|
2238
|
+
/** Bucket to upload into. Sent only when the mutation takes `bucketKey`. */
|
|
2239
|
+
bucketKey?: string;
|
|
2240
|
+
/** Without a bucket key, the public (true, the default) or private default bucket. Sent only when the mutation takes `isPublic`. */
|
|
2241
|
+
isPublic?: boolean;
|
|
2242
|
+
/** Sent only when the mutation takes `databaseId`. */
|
|
2243
|
+
databaseId?: string;
|
|
2244
|
+
/** Cancels the request and the PUT. The promise then rejects with an `AbortError`. */
|
|
2245
|
+
signal?: AbortSignal;
|
|
2246
|
+
onProgress?: (progress: UploadProgressEvent) => void;
|
|
2247
|
+
/** Reads `_meta`, table models and bucket rows. Default: the built-in adapter. */
|
|
2248
|
+
adapter?: Pick<SheetsBackendAdapter, 'fetchMeta' | 'fetchTableModel' | 'listRows'>;
|
|
2249
|
+
}
|
|
2250
|
+
interface UploadedFile {
|
|
2251
|
+
/** Id of the files table row. */
|
|
2252
|
+
fileId: string;
|
|
2253
|
+
/** The stored file as the storage service returned it: the value a file column stores. */
|
|
2254
|
+
file: FileProjection;
|
|
2255
|
+
/** True when the service already held these bytes; no PUT was sent and `file` is the existing file. */
|
|
2256
|
+
deduplicated: boolean;
|
|
2257
|
+
}
|
|
2258
|
+
/**
|
|
2259
|
+
* Upload `file` into `filesTable` and return the stored file and its id. Rejects
|
|
2260
|
+
* with the reason when the storage service does not offer uploads for that
|
|
2261
|
+
* table, when a required input (an owner id) is missing, when the bucket would
|
|
2262
|
+
* refuse the file, or when the request or the PUT fails.
|
|
2263
|
+
*/
|
|
2264
|
+
declare function uploadToFilesTable(options: UploadToFilesTableOptions): Promise<UploadedFile>;
|
|
1298
2265
|
|
|
1299
2266
|
declare function isSheetsScopeKey(value: unknown): value is SheetsScopeKey;
|
|
1300
2267
|
declare const sheetsQueryKeys: {
|
|
1301
2268
|
readonly root: readonly ["sheets"];
|
|
1302
2269
|
readonly scope: (scope: SheetsScopeKey) => readonly ["sheets", SheetsScopeKey];
|
|
1303
2270
|
readonly meta: (scope: SheetsScopeKey) => readonly ["sheets", SheetsScopeKey, "meta"];
|
|
1304
|
-
|
|
1305
|
-
readonly
|
|
1306
|
-
readonly
|
|
1307
|
-
readonly
|
|
1308
|
-
readonly
|
|
1309
|
-
readonly
|
|
1310
|
-
readonly
|
|
1311
|
-
readonly
|
|
1312
|
-
readonly
|
|
1313
|
-
readonly
|
|
1314
|
-
readonly
|
|
2271
|
+
/** One table model, per `_meta` version and display override. */
|
|
2272
|
+
readonly tableModel: (scope: SheetsScopeKey, tableKey: string, metaVersion: number, displayKey: string | null) => readonly ["sheets", SheetsScopeKey, "table-model", ...string[], number, string | null];
|
|
2273
|
+
readonly mediaUrl: (scope: SheetsScopeKey, endpoint: string | undefined, id: string | null) => readonly ["sheets", SheetsScopeKey, "media-url", string | undefined, string | null];
|
|
2274
|
+
readonly relations: (scope: SheetsScopeKey, tableName: string) => readonly ["sheets", SheetsScopeKey, "relations", ...string[]];
|
|
2275
|
+
readonly table: (scope: SheetsScopeKey, tableRef: string) => readonly ["sheets", SheetsScopeKey, "table", ...string[]];
|
|
2276
|
+
readonly tableRows: (scope: SheetsScopeKey, tableRef: string, options?: unknown) => readonly ["sheets", SheetsScopeKey, "table", ...string[], "rows", unknown];
|
|
2277
|
+
readonly tableRow: (scope: SheetsScopeKey, tableRef: string, id: unknown) => readonly ["sheets", SheetsScopeKey, "table", ...string[], "row", unknown];
|
|
2278
|
+
readonly tableCount: (scope: SheetsScopeKey, tableRef: string, where?: Readonly<Record<string, unknown>> | null) => readonly ["sheets", SheetsScopeKey, "table", ...string[], "count", Readonly<Record<string, unknown>> | null | undefined];
|
|
2279
|
+
readonly infiniteTable: (scope: SheetsScopeKey, tableRef: string) => readonly ["sheets", SheetsScopeKey, "infinite-table", ...string[]];
|
|
2280
|
+
readonly infiniteTablePage: (scope: SheetsScopeKey, tableRef: string, pageIndex: number, options: unknown) => readonly ["sheets", SheetsScopeKey, "infinite-table", ...string[], "page", number, unknown];
|
|
2281
|
+
readonly infiniteTableTotalCount: (scope: SheetsScopeKey, tableRef: string, where?: Readonly<Record<string, unknown>>) => readonly ["sheets", SheetsScopeKey, "infinite-table", ...string[], "totalCount", Readonly<Record<string, unknown>> | undefined];
|
|
2282
|
+
readonly cursorTable: (scope: SheetsScopeKey, tableRef: string, options?: unknown) => readonly ["sheets", SheetsScopeKey, "cursor-table", ...string[], unknown];
|
|
1315
2283
|
};
|
|
1316
|
-
|
|
1317
2284
|
/**
|
|
1318
|
-
*
|
|
1319
|
-
*
|
|
1320
|
-
*
|
|
2285
|
+
* Mutation keys. Every mutation a Sheets hook creates sits under its table's
|
|
2286
|
+
* query key, `[...table(scope, tableRef), 'mutation', operation, ...detail]`, so
|
|
2287
|
+
* `useIsMutating({ mutationKey: sheetsMutationKeys.table(scope, ref) })` counts
|
|
2288
|
+
* every write in flight on that table.
|
|
1321
2289
|
*/
|
|
2290
|
+
declare const sheetsMutationKeys: {
|
|
2291
|
+
/** Every mutation of a table, or one operation of it when `operation` is given. */
|
|
2292
|
+
readonly table: (scope: SheetsScopeKey, tableRef: string, operation?: string, ...detail: readonly unknown[]) => readonly ["sheets", SheetsScopeKey, "table", ...unknown[]];
|
|
2293
|
+
};
|
|
2294
|
+
|
|
1322
2295
|
declare function createPostGraphileAdapter(): SheetsBackendAdapter;
|
|
1323
2296
|
|
|
1324
2297
|
/**
|
|
@@ -1387,13 +2360,16 @@ declare const ENHANCED_TYPES: Set<string>;
|
|
|
1387
2360
|
declare const BUILTIN_EDITOR_TYPES: Set<string>;
|
|
1388
2361
|
/** Cell types that are never editable (always read-only). */
|
|
1389
2362
|
declare const NON_EDITABLE_TYPES: Set<string>;
|
|
1390
|
-
/** Cell types that
|
|
2363
|
+
/** Cell types that open a read-only viewer (show and copy the value) instead of an editor. */
|
|
1391
2364
|
declare const VIEWER_ONLY_TYPES: Set<string>;
|
|
1392
2365
|
|
|
1393
2366
|
/**
|
|
1394
|
-
* Maps
|
|
1395
|
-
*
|
|
1396
|
-
*
|
|
2367
|
+
* Maps raw `_meta` field metadata to a frontend cell type (priority: encoding >
|
|
2368
|
+
* pgType > gqlType).
|
|
2369
|
+
*
|
|
2370
|
+
* @deprecated The grid routes every column from its table model
|
|
2371
|
+
* (`cellTypeForColumn` over a `ColumnModel`). This mapping reads raw `_meta` only and
|
|
2372
|
+
* is kept for hosts that call it directly.
|
|
1397
2373
|
*/
|
|
1398
2374
|
declare function mapToFrontendCellType(metadata: {
|
|
1399
2375
|
gqlType: string;
|
|
@@ -1462,7 +2438,9 @@ interface ExtractedRange {
|
|
|
1462
2438
|
declare function getCellsInRange(range: SelectionRect, rows: readonly unknown[], columnKeys: readonly string[], getDisplay?: (value: unknown, rowIndex: number, colKey: string) => unknown): ExtractedRange;
|
|
1463
2439
|
/**
|
|
1464
2440
|
* Serialize a value matrix to TSV (tab-joined cols, newline-joined rows). Each value
|
|
1465
|
-
* is stringified; `null`/`undefined` become an empty cell.
|
|
2441
|
+
* is stringified (an object as JSON); `null`/`undefined` become an empty cell. A cell
|
|
2442
|
+
* with a tab, a line break or a leading quote is quoted (`"two\nlines"`, inner quotes
|
|
2443
|
+
* doubled), so multi-line text survives a copy and paste. Spreadsheet-paste shape —
|
|
1466
2444
|
* reused by P4 copy.
|
|
1467
2445
|
*/
|
|
1468
2446
|
declare function toTSV(values: readonly (readonly unknown[])[]): string;
|
|
@@ -1539,6 +2517,13 @@ interface BuildFormSpecOptions {
|
|
|
1539
2517
|
multilineFields?: Set<string>;
|
|
1540
2518
|
}
|
|
1541
2519
|
|
|
2520
|
+
/**
|
|
2521
|
+
* Build a form spec from a raw `_meta` table.
|
|
2522
|
+
*
|
|
2523
|
+
* @deprecated Use `buildModelFormSpec(tableModel, mode)` and `buildModelFormSchema(spec)`:
|
|
2524
|
+
* they follow the table model's write flags, limits and choices, and check values with
|
|
2525
|
+
* the same rules as the grid.
|
|
2526
|
+
*/
|
|
1542
2527
|
declare function buildScalarFormSpec(metaTable: MetaTable, options?: BuildFormSpecOptions): DynamicFormSpec | null;
|
|
1543
2528
|
declare function findTableFormSpec(meta: MetaTable[] | null | undefined, tableName: string, options?: BuildFormSpecOptions): DynamicFormSpec | null;
|
|
1544
2529
|
|
|
@@ -1554,47 +2539,201 @@ declare function useDynamicUpdate(tableName: string, rowId: SheetsRowIdentifier)
|
|
|
1554
2539
|
|
|
1555
2540
|
declare function createMetadataHash(value: unknown): string;
|
|
1556
2541
|
|
|
2542
|
+
/** Whether the form creates a record or edits an existing one. */
|
|
2543
|
+
type ModelFormMode = 'create' | 'update';
|
|
2544
|
+
interface ModelFormField {
|
|
2545
|
+
/** Field name on the row (also the key in the form values). */
|
|
2546
|
+
name: string;
|
|
2547
|
+
/** Readable label. */
|
|
2548
|
+
label: string;
|
|
2549
|
+
/** Column comment, or null. */
|
|
2550
|
+
description: string | null;
|
|
2551
|
+
/** The table-model column. */
|
|
2552
|
+
column: ColumnModel;
|
|
2553
|
+
/** The cell type key the grid uses for this column (a built-in cell type or a host override); it picks the editor. */
|
|
2554
|
+
cellType: string;
|
|
2555
|
+
/** The form may set this field in this mode. */
|
|
2556
|
+
writable: boolean;
|
|
2557
|
+
/** Why the field cannot be set in this mode, or null when it can. */
|
|
2558
|
+
readOnlyReason: string | null;
|
|
2559
|
+
/** A value must be given: create requires it (no default), or an edit cannot empty it. */
|
|
2560
|
+
required: boolean;
|
|
2561
|
+
/** The column accepts no value. */
|
|
2562
|
+
nullable: boolean;
|
|
2563
|
+
/** Fixed choices, or null. `value` is what is stored. */
|
|
2564
|
+
options: readonly ColumnOption[] | null;
|
|
2565
|
+
maxLength: number | null;
|
|
2566
|
+
precision: number | null;
|
|
2567
|
+
scale: number | null;
|
|
2568
|
+
}
|
|
2569
|
+
interface ModelFormSpec {
|
|
2570
|
+
/** `TableModel.key` of the table. */
|
|
2571
|
+
tableKey: string;
|
|
2572
|
+
/** GraphQL type name of the table. */
|
|
2573
|
+
tableName: string;
|
|
2574
|
+
mode: ModelFormMode;
|
|
2575
|
+
/** Changes whenever a field's rules change; use it as a cache key. */
|
|
2576
|
+
versionHash: string;
|
|
2577
|
+
/** Readable fields, in column order. */
|
|
2578
|
+
fields: ModelFormField[];
|
|
2579
|
+
}
|
|
2580
|
+
interface BuildModelFormSpecOptions {
|
|
2581
|
+
/** Host cell-type overrides keyed by `tableName.fieldName` (`SheetsConfig.fieldTypeOverrides`). */
|
|
2582
|
+
typeOverrides?: Readonly<Record<string, string>>;
|
|
2583
|
+
}
|
|
2584
|
+
/**
|
|
2585
|
+
* Build the fields of a create or edit form from the table model. Each field's cell
|
|
2586
|
+
* type and read-only reason come from the grid's own routing (`resolveModelCellRoute`:
|
|
2587
|
+
* a create is routed like a draft row, an edit like a saved row with its key fixed),
|
|
2588
|
+
* so a form and a grid cell never disagree.
|
|
2589
|
+
*/
|
|
2590
|
+
declare function buildModelFormSpec(model: TableModel, mode: ModelFormMode, options?: BuildModelFormSpecOptions): ModelFormSpec;
|
|
2591
|
+
/**
|
|
2592
|
+
* Build the validation schema of a model form. Only writable fields are in it; each
|
|
2593
|
+
* one is checked and parsed by the column's rules. Unknown keys are dropped, so a
|
|
2594
|
+
* read-only field can never reach a write.
|
|
2595
|
+
*/
|
|
2596
|
+
declare function buildModelFormSchema(spec: ModelFormSpec): z.ZodObject<Record<string, z.ZodType<unknown>>>;
|
|
2597
|
+
|
|
2598
|
+
/**
|
|
2599
|
+
* Map a table-model column to its cell type. A list column routes to a list cell
|
|
2600
|
+
* type (the editor validates each element by the column's value kind); a column with
|
|
2601
|
+
* a fixed option list routes to a choice cell type.
|
|
2602
|
+
*/
|
|
2603
|
+
declare function cellTypeForColumn(column: ColumnModel): CellType;
|
|
2604
|
+
|
|
2605
|
+
type ColumnInputResult = {
|
|
2606
|
+
ok: true;
|
|
2607
|
+
value: unknown;
|
|
2608
|
+
} | {
|
|
2609
|
+
ok: false;
|
|
2610
|
+
reason: string;
|
|
2611
|
+
};
|
|
2612
|
+
interface ColumnInputOptions {
|
|
2613
|
+
/**
|
|
2614
|
+
* The input is text the user typed or pasted, so JSON and lists are read from
|
|
2615
|
+
* the text. False (the default) for a value an editor, a fill or an undo produced.
|
|
2616
|
+
*/
|
|
2617
|
+
fromText?: boolean;
|
|
2618
|
+
/**
|
|
2619
|
+
* The value is for a record not created yet (a new row, the new-record form): clearing a
|
|
2620
|
+
* required text field keeps '' there, since the create checks the required fields as a whole.
|
|
2621
|
+
*/
|
|
2622
|
+
creating?: boolean;
|
|
2623
|
+
}
|
|
2624
|
+
/**
|
|
2625
|
+
* Turn a user's input into the value the column stores, or say why it does not fit.
|
|
2626
|
+
* Empty input clears the column (see `clearedValue`). The result is still encoded by
|
|
2627
|
+
* the write codec (`encodeWriteValues`) before it is sent.
|
|
2628
|
+
*/
|
|
2629
|
+
declare function parseColumnInput(column: ColumnModel, input: unknown, options?: ColumnInputOptions): ColumnInputResult;
|
|
2630
|
+
/**
|
|
2631
|
+
* Text for one value when it leaves the grid (copy, export). Structured values and
|
|
2632
|
+
* JSON are written as JSON so a paste reads them back exactly; choices use their label.
|
|
2633
|
+
*/
|
|
2634
|
+
declare function formatColumnValue(column: ColumnModel | null | undefined, value: unknown): string;
|
|
2635
|
+
|
|
2636
|
+
type WriteAction = 'update' | 'create' | 'delete';
|
|
2637
|
+
/** Every distinct message of a failed write, in plain words. */
|
|
2638
|
+
declare function writeErrorMessages(error: unknown, action: WriteAction): string[];
|
|
2639
|
+
/** One failed write, as the grid shows it. */
|
|
2640
|
+
interface WriteErrorReport {
|
|
2641
|
+
id: string;
|
|
2642
|
+
title: string;
|
|
2643
|
+
messages: readonly string[];
|
|
2644
|
+
}
|
|
2645
|
+
|
|
1557
2646
|
/**
|
|
1558
2647
|
* Grid Feedback Reducer
|
|
1559
2648
|
*
|
|
1560
|
-
*
|
|
1561
|
-
*
|
|
1562
|
-
*
|
|
1563
|
-
*
|
|
1564
|
-
*
|
|
2649
|
+
* One save status for every write the grid makes: cell saves (an edit, a paste, a
|
|
2650
|
+
* fill, undo and redo), new rows, deletes, and the editors and record panel that
|
|
2651
|
+
* save on their own. Writes that overlap share the status: it reads "saving" while
|
|
2652
|
+
* any write is in flight and settles once, when the last one ends, to one outcome
|
|
2653
|
+
* for all of them. So two saves can never show two checks, and a fast save cannot
|
|
2654
|
+
* replace the outcome of a slow one that is still running.
|
|
2655
|
+
*
|
|
2656
|
+
* Failed writes are also kept as reports (`writeErrors`) until the user dismisses
|
|
2657
|
+
* them, so a message is never lost when the status clears.
|
|
2658
|
+
*
|
|
2659
|
+
* Uses vanilla React (useReducer): the state is local to the grid, ephemeral, and
|
|
2660
|
+
* cleaned up on unmount.
|
|
1565
2661
|
*/
|
|
2662
|
+
|
|
1566
2663
|
type OperationStatus = 'idle' | 'pending' | 'success' | 'partial' | 'error';
|
|
2664
|
+
/** What a write does. `update` saves values, `submit` creates rows, `delete` removes rows. */
|
|
2665
|
+
type OperationType = 'delete' | 'submit' | 'update';
|
|
2666
|
+
/** The save status the grid shows. */
|
|
1567
2667
|
interface OperationFeedback {
|
|
2668
|
+
/** Stable while the status is on screen, so a new write changes it in place. */
|
|
1568
2669
|
id: string;
|
|
1569
|
-
type:
|
|
2670
|
+
type: OperationType;
|
|
1570
2671
|
status: OperationStatus;
|
|
1571
2672
|
message: string;
|
|
1572
2673
|
total: number;
|
|
1573
2674
|
completed: number;
|
|
1574
2675
|
failed: number;
|
|
2676
|
+
/** When the status last changed. A settled status is cleared `dismissAfter` ms after it. */
|
|
1575
2677
|
timestamp: number;
|
|
1576
|
-
/** Auto-dismiss duration in ms. 0 =
|
|
2678
|
+
/** Auto-dismiss duration in ms. 0 = shown until it changes. */
|
|
1577
2679
|
dismissAfter: number;
|
|
1578
2680
|
}
|
|
2681
|
+
/** One write in flight. */
|
|
2682
|
+
interface PendingWrite {
|
|
2683
|
+
id: string;
|
|
2684
|
+
type: OperationType;
|
|
2685
|
+
total: number;
|
|
2686
|
+
completed: number;
|
|
2687
|
+
failed: number;
|
|
2688
|
+
}
|
|
2689
|
+
/** One write that ended while others in the same status were running or had ended. */
|
|
2690
|
+
interface EndedWrite {
|
|
2691
|
+
type: OperationType;
|
|
2692
|
+
status: 'success' | 'partial' | 'error';
|
|
2693
|
+
message: string;
|
|
2694
|
+
}
|
|
1579
2695
|
interface FeedbackState {
|
|
1580
|
-
/**
|
|
2696
|
+
/** The save status (shown in the status bar), or null when there is nothing to show. */
|
|
1581
2697
|
operation: OperationFeedback | null;
|
|
2698
|
+
/** Writes in flight. */
|
|
2699
|
+
pending: readonly PendingWrite[];
|
|
2700
|
+
/** Writes that ended since the status was last idle or settled. */
|
|
2701
|
+
ended: readonly EndedWrite[];
|
|
2702
|
+
/** Failed writes, newest last, until the user dismisses them. */
|
|
2703
|
+
writeErrors: readonly WriteErrorReport[];
|
|
1582
2704
|
}
|
|
1583
2705
|
|
|
2706
|
+
/** The words for one write's outcome: what the status says when it saved and when it did not. */
|
|
2707
|
+
interface WriteMessages {
|
|
2708
|
+
saved: string;
|
|
2709
|
+
failed: string;
|
|
2710
|
+
}
|
|
1584
2711
|
interface FeedbackContextValue {
|
|
1585
2712
|
state: FeedbackState;
|
|
1586
|
-
startOperation: (type:
|
|
2713
|
+
startOperation: (type: OperationType, total: number) => string;
|
|
1587
2714
|
updateOperationProgress: (id: string, completed: number, failed: number) => void;
|
|
1588
|
-
completeOperation: (id: string, status: 'success' | 'partial' | 'error', message: string,
|
|
2715
|
+
completeOperation: (id: string, status: 'success' | 'partial' | 'error', message: string,
|
|
2716
|
+
/** Keep the settled status at least this long (ms); the default depends on the status. */
|
|
2717
|
+
dismissAfter?: number) => void;
|
|
1589
2718
|
clearOperationFeedback: () => void;
|
|
2719
|
+
/** Run one write under the save status; its error is re-thrown after it is reported. */
|
|
2720
|
+
trackWrite: <T>(type: OperationType, total: number, run: () => Promise<T>, messages: WriteMessages) => Promise<T>;
|
|
2721
|
+
/** Report a write that already ended (an editor that saves on its own). */
|
|
2722
|
+
noteWrite: (type: OperationType, status: 'success' | 'error', message: string) => void;
|
|
2723
|
+
/** Show a failed write until the user dismisses it. */
|
|
2724
|
+
reportWriteError: (title: string, messages: readonly string[]) => WriteErrorReport;
|
|
2725
|
+
dismissWriteError: (id: string) => void;
|
|
2726
|
+
clearWriteErrors: () => void;
|
|
1590
2727
|
}
|
|
1591
2728
|
interface FeedbackProviderProps {
|
|
1592
2729
|
children: React.ReactNode;
|
|
1593
2730
|
}
|
|
1594
2731
|
declare function FeedbackProvider({ children }: FeedbackProviderProps): react.JSX.Element;
|
|
1595
2732
|
declare function useFeedback(): FeedbackContextValue;
|
|
2733
|
+
/** The feedback of the grid around this component, or null outside a grid (a standalone record panel). */
|
|
2734
|
+
declare function useOptionalFeedback(): FeedbackContextValue | null;
|
|
1596
2735
|
/**
|
|
1597
|
-
*
|
|
2736
|
+
* The save status alone - useful for a status indicator.
|
|
1598
2737
|
*/
|
|
1599
2738
|
declare function useOperationFeedback(): OperationFeedback | null;
|
|
1600
2739
|
|
|
@@ -1630,6 +2769,25 @@ interface FloatingStatusProps {
|
|
|
1630
2769
|
*/
|
|
1631
2770
|
declare function FloatingStatus({ className }: FloatingStatusProps): react.JSX.Element;
|
|
1632
2771
|
|
|
2772
|
+
declare function SaveStatus({ className }: {
|
|
2773
|
+
className?: string;
|
|
2774
|
+
}): react.JSX.Element;
|
|
2775
|
+
|
|
2776
|
+
/**
|
|
2777
|
+
* Failed writes, each with every message the server returned. They stay until
|
|
2778
|
+
* the user dismisses them, so a message is never lost to a timeout.
|
|
2779
|
+
*/
|
|
2780
|
+
declare function WriteErrorStack({ className }: {
|
|
2781
|
+
className?: string;
|
|
2782
|
+
}): react.JSX.Element | null;
|
|
2783
|
+
|
|
2784
|
+
interface ModelIssuesNoticeProps {
|
|
2785
|
+
model: TableModel | null;
|
|
2786
|
+
dropped: readonly SheetsViewStateDrop[];
|
|
2787
|
+
columnLabel: (name: string) => string;
|
|
2788
|
+
}
|
|
2789
|
+
declare function ModelIssuesNotice({ model, dropped, columnLabel }: ModelIssuesNoticeProps): react.JSX.Element | null;
|
|
2790
|
+
|
|
1633
2791
|
interface SheetsErrorBoundaryProps {
|
|
1634
2792
|
children: ReactNode;
|
|
1635
2793
|
/** Called when a render error is caught. Mirrors SheetsConfig.onError. */
|
|
@@ -1659,9 +2817,11 @@ declare class SheetsErrorBoundary extends Component<SheetsErrorBoundaryProps, Sh
|
|
|
1659
2817
|
interface SheetsErrorStateProps {
|
|
1660
2818
|
error: unknown;
|
|
1661
2819
|
onRetry?: () => void;
|
|
2820
|
+
/** The table that failed. Only this table's grid shows the error; other tables keep working. */
|
|
2821
|
+
tableName?: string;
|
|
1662
2822
|
}
|
|
1663
|
-
/** Shown when
|
|
1664
|
-
declare function SheetsErrorState({ error, onRetry }: SheetsErrorStateProps): react.JSX.Element;
|
|
2823
|
+
/** Shown when one table's rows (or its model) fail to load. */
|
|
2824
|
+
declare function SheetsErrorState({ error, onRetry, tableName }: SheetsErrorStateProps): react.JSX.Element;
|
|
1665
2825
|
interface SheetsEmptyStateProps {
|
|
1666
2826
|
tableName?: string;
|
|
1667
2827
|
onAddRow?: () => void;
|
|
@@ -1676,34 +2836,34 @@ declare function SheetsEmptyState({ tableName, onAddRow, readOnlyReason }: Sheet
|
|
|
1676
2836
|
*/
|
|
1677
2837
|
declare function SheetsLoadingState(): react.JSX.Element;
|
|
1678
2838
|
|
|
2839
|
+
/** Filter bindings for a headless shell. */
|
|
1679
2840
|
interface DataFilteringContextValue {
|
|
1680
|
-
|
|
1681
|
-
|
|
1682
|
-
|
|
1683
|
-
|
|
1684
|
-
|
|
1685
|
-
|
|
1686
|
-
|
|
1687
|
-
|
|
2841
|
+
/** The filters in use, valid for the model. */
|
|
2842
|
+
filters: SheetsFilterGroup;
|
|
2843
|
+
setFilters: (filters: SheetsFilterGroup) => void;
|
|
2844
|
+
clearFilters: () => void;
|
|
2845
|
+
/** The list filter for the conditions that are complete and valid, or undefined. */
|
|
2846
|
+
where: Record<string, unknown> | undefined;
|
|
2847
|
+
/** Conditions in `where`. */
|
|
2848
|
+
appliedCount: number;
|
|
2849
|
+
/** Status of every condition, by condition id. */
|
|
2850
|
+
conditions: ReadonlyMap<string, ConditionStatus>;
|
|
2851
|
+
/** Conditions of `initialFilters` the model does not support. */
|
|
2852
|
+
dropped: readonly SheetsViewStateDrop[];
|
|
1688
2853
|
}
|
|
1689
2854
|
interface UseDataFilteringConfig {
|
|
1690
|
-
|
|
1691
|
-
|
|
1692
|
-
|
|
1693
|
-
|
|
1694
|
-
|
|
1695
|
-
|
|
1696
|
-
} | null;
|
|
1697
|
-
} | null> | null;
|
|
1698
|
-
} | null;
|
|
1699
|
-
initialFilterTree?: FilterGroup;
|
|
2855
|
+
/** The table model, or null while it loads. */
|
|
2856
|
+
model: TableModel | null;
|
|
2857
|
+
/** Filters to start with, for example from a saved view. */
|
|
2858
|
+
initialFilters?: SheetsFilterGroup;
|
|
2859
|
+
/** Models of related tables, for "linked record contains" conditions. */
|
|
2860
|
+
relatedModel?: (key: TableKey) => TableModel | null;
|
|
1700
2861
|
}
|
|
1701
|
-
|
|
1702
|
-
|
|
1703
|
-
|
|
1704
|
-
|
|
1705
|
-
|
|
1706
|
-
};
|
|
2862
|
+
/**
|
|
2863
|
+
* Headless filter state over the table model, for a custom shell. The built-in
|
|
2864
|
+
* grid uses the same pieces through `useSheetsView`.
|
|
2865
|
+
*/
|
|
2866
|
+
declare function useDataFiltering({ model, initialFilters, relatedModel }: UseDataFilteringConfig): DataFilteringContextValue;
|
|
1707
2867
|
|
|
1708
2868
|
interface DataPaginationContextValue {
|
|
1709
2869
|
pageIndex: number;
|
|
@@ -1734,4 +2894,4 @@ declare function useDataPagination({ initialPageSize, initialPageIndex, totalCou
|
|
|
1734
2894
|
}) => any;
|
|
1735
2895
|
};
|
|
1736
2896
|
|
|
1737
|
-
export { BOOLEAN_TYPES, BUILTIN_EDITOR_TYPES, type Binding, CellPlugin, CellProps, CellRegistry, CellRegistryEntry, CellRenderer, type CellSlot, type CellSlots, CellType, type CellTypeBuiltins, CellTypeDefinition, CellTypeMatchInput, type CellTypeRegistry, ColumnSchema, type CommandResult, DATE_TIME_TYPES, type DataFilteringContextValue, type DataPaginationContextValue, type DispatchEvent, DockStatusBar, DockStatusBarCompact, type DraftMeta, type DraftRow, type DynamicFormSpec, ENHANCED_TYPES, EditorProps, type ExtractedRange, FeedbackProvider, type
|
|
2897
|
+
export { BOOLEAN_TYPES, BUILTIN_EDITOR_TYPES, type Binding, CellPlugin, CellProps, CellRegistry, CellRegistryEntry, CellRenderer, type CellSlot, type CellSlots, CellType, type CellTypeBuiltins, CellTypeDefinition, CellTypeMatchInput, type CellTypeRegistry, type ColumnInputOptions, type ColumnInputResult, ColumnSchema, type ColumnStorage, type CommandResult, type ConditionStatus, DATE_TIME_TYPES, DEFAULT_READ_ONLY_REASON, type DataFilteringContextValue, type DataPaginationContextValue, type DispatchEvent, DockStatusBar, DockStatusBarCompact, type DraftMeta, type DraftRow, type DynamicFormSpec, ENHANCED_TYPES, EditorProps, ExportViewControl, type ExportViewControlProps, type ExtractedRange, FeedbackProvider, type FieldUploadTarget, type FieldUploadTransport, type FileCellWriteJob, type FileProjection, type FileUploadState, type FilterOperatorGroup, type FilterOperatorOption, type FilterValueControl, FloatingStatus, GEOMETRY_TYPES, type GridCommand, type GridCommandContext, ImportRecordsControl, type ImportRecordsControlProps, type Interceptor, MAX_FILTER_DEPTH, MEDIA_TYPES, type MetaField, type MetaTable, type ModelFormField, type ModelFormMode, type ModelFormSpec, ModelIssuesNotice, NON_EDITABLE_TYPES, NUMBER_TYPES, type OperationFeedback, type OperationType, ROW_HEIGHT_PX, RangeSet, type RelationColumnInfo, RelationInfo, RelationSection, type RelationSectionProps, type RowWithDraft, SHEETS_VIEW_STATE_VERSION, STRUCTURED_DATA_TYPES, SaveStatus, type ScalarFieldSpec, type ScalarValueControl, type SelectionCurrent, type SelectionRect, type SendFile, type SendFileOptions, Sheets, type SheetsAuthState, SheetsBackendAdapter, SheetsCell, SheetsCellRenderContext, type SheetsColumnCondition, type SheetsColumnLayout, SheetsConfig, SheetsControls, type SheetsControlsProps, type SheetsDraftBindings, SheetsEmptyState, SheetsErrorBoundary, SheetsErrorState, type SheetsEvent, SheetsExecuteFn, type SheetsFilterCondition, type SheetsFilterGroup, type SheetsFilterLogic, type SheetsFilterNode, type SheetsFilterValue, type SheetsHandle, SheetsLoadingState, SheetsOpenRecordContext, type SheetsOpenRecordHandler, type SheetsOpenRecordRequest, SheetsOpenTableContext, type SheetsOpenTableHandler, type SheetsOpenTableRequest, SheetsPagination, type SheetsPaginationBindings, type SheetsPaginationProps, type SheetsProps, SheetsProvider, SheetsReadOnlyProvider, type SheetsReadOnlyProviderProps, type SheetsRelationCondition, type SheetsRelationTest, type SheetsRow, type SheetsRowHeight, SheetsRowIdentifier, SheetsScopeKey, type SheetsSelection, type SheetsSelectionBindings, type SheetsSlots, type SheetsSortDirection, type SheetsSortKey, SheetsStatusBar, type SheetsStatusBarProps, type SheetsStoreState, SheetsTableSelector, type SheetsThemeInput, type SheetsThemeTokens, type SheetsViewProps, type SheetsViewState, type SheetsViewStateDrop, type SheetsViewStateDropReason, type SheetsViewStateValidation, TYPED_ARRAY_TYPES, type TableSelectorProps, type TableWithCategory, type Trigger, type UnfinishedUpload, type UploadProgress, type UploadProgressEvent, type UploadResponse, type UploadToFilesTableOptions, type UploadedFile, type UseColumnStorageResult, type UseDataFilteringConfig, type UseDataPaginationConfig, type UseFieldUploadOptions, type UseInfiniteTableOptions, type UseInfiniteTableResult, type UseMetaOptions, type UseSheetsResult, type UseSheetsTableCursorOptions, type UseSheetsTableCursorResult, type UseTableModelOptions, type UseTableModelResult, type UseTableModelsResult, type UseTableOptions, type UseTableResult, VIEWER_ONLY_TYPES, type ValidateSheetsViewStateOptions, type ViewQuery, type WriteAction, type WriteErrorReport, WriteErrorStack, type WriteMessages, buildModelFormSchema, buildModelFormSpec, buildScalarFormSpec, buildViewQuery, buildZodSchema, cellTypeForColumn, clear as clearSheetsSelection, computeDraftMetaSignature, createCellTypeRegistry, createColumnLayout, createColumnSchemaFromMeta, createFilterGroup, createMetadataHash, createPostGraphileAdapter, createSheetsViewState, cycleSort, defaultOperatorOption, emptySheetsSelection, executeFieldUpload, extendRangeToCell, fillDownWrites, fillRightWrites, filterConditionsOf, filterOperatorLabel, filterOperatorOptions, findTableFormSpec, formatColumnValue, getCellsInRange, getDraftMeta, gridRelations, isArrayCellType, isDraftRow, isSheetsScopeKey, isStructuredDataType, kbd, mapToFrontendCellType, moveActive, orderedColumnKeys, parseColumnInput, sheetsTableQueryKeys as queryKeys, resolveDownloadUrl, selectCell, selectRange, selectRow, sheetsMutationKeys, sheetsQueryKeys, toTSV, toggleRow, tokensFromCssVars, unfinishedUploadOf, uploadToFilesTable, useColumnStorage, useDataFiltering, useDataGridColumns, useDataPagination, useDynamicCreate, useDynamicUpdate, useFeedback, useFileCellWriter, useFileUploadState, useOpenRecordHandler, useOperationFeedback, useOptionalFeedback, useRelationColumns, useSheets, useSheetsAdapter, useSheetsFieldUpload, useSheetsInfiniteTable, useSheetsMeta, useSheetsStore, useSheetsStoreApi, useSheetsTable, useSheetsTableCursor, useShowSystemTables, useTableModel, useTableModels, validateSheetsViewState, visibleColumnKeys, visibleTables, writeErrorMessages };
|