grist-widget-sdk 0.3.27 → 0.5.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/CHANGELOG.md +84 -0
- package/README.md +79 -208
- package/dist/app.cjs +1336 -4415
- package/dist/app.cjs.map +1 -1
- package/dist/app.d.cts +6 -103
- package/dist/app.d.ts +6 -103
- package/dist/app.js +5 -7
- package/dist/chunk-4ZGVKGDF.js +204 -0
- package/dist/chunk-4ZGVKGDF.js.map +1 -0
- package/dist/{chunk-6Y2IONGJ.js → chunk-LSALXIGM.js} +191 -20
- package/dist/chunk-LSALXIGM.js.map +1 -0
- package/dist/chunk-MAPAWVQC.js +1898 -0
- package/dist/chunk-MAPAWVQC.js.map +1 -0
- package/dist/{chunk-YQNMIL33.js → chunk-OXA2VITC.js} +532 -181
- package/dist/chunk-OXA2VITC.js.map +1 -0
- package/dist/define-widget-B1FIvI-h.d.cts +433 -0
- package/dist/define-widget-B9gEtJP0.d.ts +433 -0
- package/dist/emulator/testing.cjs +3341 -6512
- package/dist/emulator/testing.cjs.map +1 -1
- package/dist/emulator/testing.d.cts +29 -14
- package/dist/emulator/testing.d.ts +29 -14
- package/dist/emulator/testing.js +78 -72
- package/dist/emulator/testing.js.map +1 -1
- package/dist/emulator.cjs +63 -249
- package/dist/emulator.cjs.map +1 -1
- package/dist/emulator.d.cts +6 -8
- package/dist/emulator.d.ts +6 -8
- package/dist/emulator.js +5 -11
- package/dist/index.cjs +1442 -4862
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +81 -260
- package/dist/index.d.ts +81 -260
- package/dist/index.js +12 -158
- package/dist/mount-grist-widget-CkB-3iG_.d.ts +137 -0
- package/dist/mount-grist-widget-Dtelqao_.d.cts +137 -0
- package/dist/{inline-DpcT8tV9.d.ts → templates-CGmRIQBV.d.cts} +89 -35
- package/dist/{inline-C7DkvuET.d.cts → templates-Cq94qOcf.d.ts} +89 -35
- package/dist/{types-D3JxUCfL.d.cts → types-DBStn0Dk.d.cts} +2 -26
- package/dist/{types-D3JxUCfL.d.ts → types-DBStn0Dk.d.ts} +2 -26
- package/package.json +8 -37
- package/dist/advanced.cjs +0 -2799
- package/dist/advanced.cjs.map +0 -1
- package/dist/advanced.d.cts +0 -822
- package/dist/advanced.d.ts +0 -822
- package/dist/advanced.js +0 -872
- package/dist/advanced.js.map +0 -1
- package/dist/chunk-22U7WAY3.js +0 -463
- package/dist/chunk-22U7WAY3.js.map +0 -1
- package/dist/chunk-64SVRWW7.js +0 -758
- package/dist/chunk-64SVRWW7.js.map +0 -1
- package/dist/chunk-6Y2IONGJ.js.map +0 -1
- package/dist/chunk-B4AKVSWV.js +0 -2362
- package/dist/chunk-B4AKVSWV.js.map +0 -1
- package/dist/chunk-ELGVOHFD.js +0 -32
- package/dist/chunk-ELGVOHFD.js.map +0 -1
- package/dist/chunk-GTTD5HPO.js +0 -36
- package/dist/chunk-GTTD5HPO.js.map +0 -1
- package/dist/chunk-NO6FYX33.js +0 -2084
- package/dist/chunk-NO6FYX33.js.map +0 -1
- package/dist/chunk-OPTOYD2Y.js +0 -277
- package/dist/chunk-OPTOYD2Y.js.map +0 -1
- package/dist/chunk-PM3B4WYV.js +0 -12
- package/dist/chunk-PM3B4WYV.js.map +0 -1
- package/dist/chunk-REV5AUXD.js +0 -25
- package/dist/chunk-REV5AUXD.js.map +0 -1
- package/dist/chunk-YQNMIL33.js.map +0 -1
- package/dist/create-grist-emulator-BCqp1BF9.d.ts +0 -81
- package/dist/create-grist-emulator-DBM8OSIR.d.cts +0 -81
- package/dist/emulator/devtools.cjs +0 -1404
- package/dist/emulator/devtools.cjs.map +0 -1
- package/dist/emulator/devtools.d.cts +0 -48
- package/dist/emulator/devtools.d.ts +0 -48
- package/dist/emulator/devtools.js +0 -506
- package/dist/emulator/devtools.js.map +0 -1
- package/dist/emulator/transports.cjs +0 -1132
- package/dist/emulator/transports.cjs.map +0 -1
- package/dist/emulator/transports.d.cts +0 -38
- package/dist/emulator/transports.d.ts +0 -38
- package/dist/emulator/transports.js +0 -12
- package/dist/emulator/transports.js.map +0 -1
- package/dist/templates-8k2LKoO-.d.cts +0 -24
- package/dist/templates-DIwi_mvI.d.ts +0 -24
- package/dist/use-grist-reads-DUMvJgV7.d.ts +0 -480
- package/dist/use-grist-reads-DpjVuI0H.d.cts +0 -480
- package/dist/use-grist-types-DdOLEJXN.d.cts +0 -499
- package/dist/use-grist-types-kwxoFeub.d.ts +0 -499
- package/dist/use-grist-widget-options-from-context-CGOlQ5Vc.d.cts +0 -43
- package/dist/use-grist-widget-options-from-context-CGOlQ5Vc.d.ts +0 -43
|
@@ -0,0 +1,433 @@
|
|
|
1
|
+
import { e as GristReplicaColumn, f as GristRowRecord, i as GristReadyOptions, j as GristFetchSelectedOptions, k as GristTableOperations, o as GristApplyUserActionsOptions, c as GristCursorPos, b as GristWidgetColumnMap } from './types-DBStn0Dk.cjs';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Typed reads, with read-only access: each mapped cell checked against the
|
|
5
|
+
* type its column declares in `GRIST_OPTIONS.columns`.
|
|
6
|
+
*
|
|
7
|
+
* Grist's mapping panel only offers the columns of the declared type, so for
|
|
8
|
+
* a mapped column the declaration is the contract; and the plugin API's
|
|
9
|
+
* decoded values already say what they are (a `Date`, a `Reference` with a
|
|
10
|
+
* `rowId`, a list of ids, a `RaisedException` for a formula error, the raw
|
|
11
|
+
* text of an invalid cell). Checked in Grist 1.7.22, every type, both
|
|
12
|
+
* `cellFormat`s. So a cell is turned into the JS value its type promises, or
|
|
13
|
+
* into `null` with an issue: no schema to fetch, no full access, no
|
|
14
|
+
* dependency.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
/** A mapped cell that didn't match its declared type, or a rule of the widget's schema. */
|
|
18
|
+
type GristCellIssue = {
|
|
19
|
+
rowId: number;
|
|
20
|
+
/** The declared column name, or "" for a schema rule on the whole record. */
|
|
21
|
+
column: string;
|
|
22
|
+
message: string;
|
|
23
|
+
/** The value Grist sent. */
|
|
24
|
+
value: unknown;
|
|
25
|
+
};
|
|
26
|
+
type Check = {
|
|
27
|
+
ok: true;
|
|
28
|
+
value: unknown;
|
|
29
|
+
} | {
|
|
30
|
+
ok: false;
|
|
31
|
+
message: string;
|
|
32
|
+
};
|
|
33
|
+
declare function checkGristCell(type: string | undefined, value: unknown): Check;
|
|
34
|
+
/**
|
|
35
|
+
* A value as Grist stores it in a column of the declared `type`: the
|
|
36
|
+
* reverse of what typed reads give. Lists become `["L", ...]` (a RefList's
|
|
37
|
+
* `Reference` items become their row ids), a `Date` for a Date or DateTime
|
|
38
|
+
* column becomes seconds since the epoch, a `Reference` for a Ref column its
|
|
39
|
+
* row id. A list already encoded (`["L", ...]`, as the attachment helpers
|
|
40
|
+
* return it) and every other value pass through, so it is safe to call twice.
|
|
41
|
+
*
|
|
42
|
+
* Grist's plugin API writes values as given: a bare array written to a
|
|
43
|
+
* ChoiceList or RefList column is stored as an error cell. Checked in
|
|
44
|
+
* Grist 1.7.22.
|
|
45
|
+
*/
|
|
46
|
+
declare function encodeGristCell(type: string | undefined, value: unknown): unknown;
|
|
47
|
+
/** Minimal Standard Schema (https://standardschema.dev): zod 4, valibot, arktype implement it. */
|
|
48
|
+
type StandardSchema<T = unknown> = {
|
|
49
|
+
readonly "~standard": {
|
|
50
|
+
readonly version: 1;
|
|
51
|
+
readonly vendor: string;
|
|
52
|
+
readonly validate: (value: unknown) => {
|
|
53
|
+
readonly value: T;
|
|
54
|
+
readonly issues?: undefined;
|
|
55
|
+
} | {
|
|
56
|
+
readonly issues: ReadonlyArray<{
|
|
57
|
+
readonly message: string;
|
|
58
|
+
readonly path?: ReadonlyArray<PropertyKey | {
|
|
59
|
+
key: PropertyKey;
|
|
60
|
+
}>;
|
|
61
|
+
}>;
|
|
62
|
+
} | Promise<unknown>;
|
|
63
|
+
};
|
|
64
|
+
};
|
|
65
|
+
type BaseOf<T extends string> = T extends `${infer B}:${string}` ? B : T;
|
|
66
|
+
type CellOf<T extends string> = T extends `${infer A},${infer Rest}` ? CellOf<A> | CellOf<Rest> : BaseOf<T> extends "Text" ? string : BaseOf<T> extends "Numeric" | "Int" ? number | null : BaseOf<T> extends "Bool" ? boolean : BaseOf<T> extends "Date" | "DateTime" ? Date | null : BaseOf<T> extends "Choice" ? string | null : BaseOf<T> extends "ChoiceList" ? string[] : BaseOf<T> extends "Ref" ? number | null : BaseOf<T> extends "RefList" | "Attachments" ? number[] : unknown;
|
|
67
|
+
type ColumnValue<C> = C extends {
|
|
68
|
+
type: infer T extends string;
|
|
69
|
+
allowMultiple: true;
|
|
70
|
+
} ? (CellOf<T> | null)[] : C extends {
|
|
71
|
+
type: infer T extends string;
|
|
72
|
+
} ? CellOf<T> | null : C extends {
|
|
73
|
+
allowMultiple: true;
|
|
74
|
+
} ? unknown[] : unknown;
|
|
75
|
+
type RequiredName<C> = C extends {
|
|
76
|
+
optional: true;
|
|
77
|
+
} ? never : C extends string ? C : C extends {
|
|
78
|
+
name: infer N extends string;
|
|
79
|
+
} ? N : never;
|
|
80
|
+
type OptionalName<C> = C extends {
|
|
81
|
+
optional: true;
|
|
82
|
+
name: infer N extends string;
|
|
83
|
+
} ? N : never;
|
|
84
|
+
type ByName<Cs, N> = Extract<Cs, N | {
|
|
85
|
+
name: N;
|
|
86
|
+
}>;
|
|
87
|
+
/**
|
|
88
|
+
* The mapped record a `GRIST_OPTIONS` declaration gives, for `useGrist`'s
|
|
89
|
+
* second type argument. Declare the options with `as const satisfies
|
|
90
|
+
* UseGristOptions` so the column names and types stay literal:
|
|
91
|
+
*
|
|
92
|
+
* ```ts
|
|
93
|
+
* export const GRIST_OPTIONS = {
|
|
94
|
+
* requiredAccess: "read table",
|
|
95
|
+
* columns: [{ name: "Title", type: "Text" }, { name: "Due", type: "Date", optional: true }],
|
|
96
|
+
* } as const satisfies UseGristOptions
|
|
97
|
+
*
|
|
98
|
+
* const w = useGrist<GristRowRecord, GristMappedRow<typeof GRIST_OPTIONS>>()
|
|
99
|
+
* w.mappedRecord?.Due // Date | null | undefined
|
|
100
|
+
* ```
|
|
101
|
+
*/
|
|
102
|
+
type GristMappedRow<O extends {
|
|
103
|
+
columns?: readonly unknown[];
|
|
104
|
+
}> = O["columns"] extends readonly (infer C)[] ? {
|
|
105
|
+
id: number;
|
|
106
|
+
} & {
|
|
107
|
+
[N in RequiredName<C>]: ColumnValue<ByName<C, N>>;
|
|
108
|
+
} & {
|
|
109
|
+
[N in OptionalName<C>]?: ColumnValue<ByName<C, N>>;
|
|
110
|
+
} : Record<string, unknown>;
|
|
111
|
+
|
|
112
|
+
type ValidateColumnMappingsResult = {
|
|
113
|
+
ok: boolean;
|
|
114
|
+
/**
|
|
115
|
+
* `true` while the host has not yet reported column mappings (e.g. between
|
|
116
|
+
* `grist.ready()` resolving and the first `onRecord` / `onRecords` callback,
|
|
117
|
+
* or before `sectionApi.mappings()` returns). Callers should not gate UI or
|
|
118
|
+
* emit mapping alerts while pending.
|
|
119
|
+
*/
|
|
120
|
+
pending?: boolean;
|
|
121
|
+
/** Logical names of required columns the user has not yet mapped. */
|
|
122
|
+
missing: string[];
|
|
123
|
+
/** Logical names of `allowMultiple` columns mapped to an empty list. */
|
|
124
|
+
emptyMultiples: string[];
|
|
125
|
+
};
|
|
126
|
+
|
|
127
|
+
type GristNoiseColumnsOptions = {
|
|
128
|
+
excludeId?: boolean;
|
|
129
|
+
excludeGristHelpers?: boolean;
|
|
130
|
+
excludeLoggingColumns?: boolean;
|
|
131
|
+
/**
|
|
132
|
+
* When `true`, treat Grist's `manualSort` column as noise (omit from filtered replicas).
|
|
133
|
+
* Default `false` — `manualSort` is kept unless you opt in.
|
|
134
|
+
*/
|
|
135
|
+
excludeManualSort?: boolean;
|
|
136
|
+
};
|
|
137
|
+
|
|
138
|
+
type GristFetchedAttachmentBlob = {
|
|
139
|
+
blob: Blob;
|
|
140
|
+
contentType: string;
|
|
141
|
+
};
|
|
142
|
+
/**
|
|
143
|
+
* All attachment ids found in a Grist attachment cell value (ordered, deduped).
|
|
144
|
+
* Attachment columns are usually an **array** of file refs; a single id or one JSON object is also supported.
|
|
145
|
+
*/
|
|
146
|
+
declare function extractGristAttachmentIdsFromCell(value: unknown): string[];
|
|
147
|
+
/** First attachment id in the cell, if any (see {@link extractGristAttachmentIdsFromCell}). */
|
|
148
|
+
declare function extractGristAttachmentId(value: unknown): string | undefined;
|
|
149
|
+
|
|
150
|
+
type GristEncodedAttachmentList = ["L", ...(number | string)[]];
|
|
151
|
+
type GristAttachmentUploadResult = {
|
|
152
|
+
/** All attachment ids returned by `POST /attachments`. */
|
|
153
|
+
ids: string[];
|
|
154
|
+
/** First id in `ids` (convenience for single-file uploads). */
|
|
155
|
+
firstId: string;
|
|
156
|
+
};
|
|
157
|
+
/** Wire value for an Attachments cell (Grist list encoding). */
|
|
158
|
+
declare function gristAttachmentCellValues(attachmentIds: (string | number)[]): GristEncodedAttachmentList;
|
|
159
|
+
/** Wire value for a single-file Attachments cell. */
|
|
160
|
+
declare function gristAttachmentCellValue(attachmentId: string | number): GristEncodedAttachmentList;
|
|
161
|
+
/**
|
|
162
|
+
* Merge new attachment ids into an existing Attachments cell value (deduped, order preserved).
|
|
163
|
+
*/
|
|
164
|
+
declare function mergeGristAttachmentCellValue(existingCell: unknown, newIds: (string | number)[]): GristEncodedAttachmentList;
|
|
165
|
+
|
|
166
|
+
/** Column-oriented table payload (`fetchTable`, `fetchSelectedTable`): `{ id: [...], Name: [...] }`. */
|
|
167
|
+
type GristColumnarTable = Record<string, unknown[]>;
|
|
168
|
+
type GristTableRowsOrder = "none" | "id" | "grist";
|
|
169
|
+
type FetchGristTableRowsOptions = {
|
|
170
|
+
/** Column metadata, to decode each cell (except `id`) with `decodeGristValue`. */
|
|
171
|
+
columns?: Record<string, GristReplicaColumn>;
|
|
172
|
+
/**
|
|
173
|
+
* Row order:
|
|
174
|
+
* - `grist` (default): `manualSort` ascending when present, then `id`.
|
|
175
|
+
* - `id`: numeric `id` ascending.
|
|
176
|
+
* - `none`: as `fetchTable` returned them.
|
|
177
|
+
*/
|
|
178
|
+
order?: GristTableRowsOrder;
|
|
179
|
+
};
|
|
180
|
+
/** Turn `fetchTable` output into row objects (order follows the `id` column). */
|
|
181
|
+
declare function tableDataToRows<T = Record<string, unknown>>(data: GristColumnarTable): GristRowRecord<T>[];
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Grist `docApi.applyUserActions` payloads are arrays of user-action tuples.
|
|
185
|
+
* @see https://support.getgrist.com/code/interfaces/grist_plugin_api.GristDocAPI/#applyuseractions
|
|
186
|
+
*/
|
|
187
|
+
type GristUserActionTuple = unknown[];
|
|
188
|
+
/** `["UpdateRecord", tableId, rowId, { col: value, ... }]` */
|
|
189
|
+
declare function gristUpdateRecordAction(tableId: string, rowId: number, patch: Record<string, unknown>): GristUserActionTuple;
|
|
190
|
+
/** `["AddRecord", tableId, null, { col: value, ... }]` */
|
|
191
|
+
declare function gristAddRecordAction(tableId: string, values: Record<string, unknown>): GristUserActionTuple;
|
|
192
|
+
/** `["RemoveRecord", tableId, rowId]` */
|
|
193
|
+
declare function gristRemoveRecordAction(tableId: string, rowId: number): GristUserActionTuple;
|
|
194
|
+
/** `["AddColumn", tableId, colId, colInfo]` — `colInfo` shape depends on Grist version / column type. */
|
|
195
|
+
declare function gristAddColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
|
|
196
|
+
/** `["AddVisibleColumn", tableId, colId, colInfo]` — like `AddColumn` but also adds the column to the current view section. */
|
|
197
|
+
declare function gristAddVisibleColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
|
|
198
|
+
/** `["RenameColumn", tableId, colId, newColId]` */
|
|
199
|
+
declare function gristRenameColumnAction(tableId: string, colId: string, newColId: string): GristUserActionTuple;
|
|
200
|
+
/** `["ModifyColumn", tableId, colId, colInfo]` */
|
|
201
|
+
declare function gristModifyColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
|
|
202
|
+
/** `["RemoveColumn", tableId, colId]` */
|
|
203
|
+
declare function gristRemoveColumnAction(tableId: string, colId: string): GristUserActionTuple;
|
|
204
|
+
/** `["AddTable", tableId, tableInfo]` */
|
|
205
|
+
declare function gristAddTableAction(tableId: string, tableInfo: Record<string, unknown>): GristUserActionTuple;
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* The alerts `mountGristWidget()` shows above a running widget: what needs the
|
|
209
|
+
* user's attention in Grist (column mapping, access, a failed write, an
|
|
210
|
+
* unlinked section). The blocking states (not connected, access refused,
|
|
211
|
+
* required columns unmapped) are `<GristBoundary>`'s, not alerts.
|
|
212
|
+
*/
|
|
213
|
+
|
|
214
|
+
type GristSdkAlertKind = "column-mapping" | "mapping-pending" | "section-not-linked" | "source-not-wired" | "action-error" | "access-insufficient" | "map-back-skip" | "cell-issues";
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* The widget's connection to Grist: one store, one `connect()`.
|
|
218
|
+
*
|
|
219
|
+
* The template loads `grist-plugin-api.js` with a classic blocking script, so
|
|
220
|
+
* `window.grist` is there when the widget starts, or it never will be: the
|
|
221
|
+
* check is synchronous (with one more look at `load`, for a page that loads
|
|
222
|
+
* the script asynchronously). Then `grist.ready()` once, and every Grist
|
|
223
|
+
* stream (records, options, mappings, theme) feeds one immutable state that
|
|
224
|
+
* React reads through `useSyncExternalStore`. No polling, no heartbeat: the
|
|
225
|
+
* iframe lives and dies with the Grist page, and a failed call fails where it
|
|
226
|
+
* was made.
|
|
227
|
+
*/
|
|
228
|
+
|
|
229
|
+
type GristTheme = "light" | "dark";
|
|
230
|
+
type GristWidgetActionStatus = "idle" | "running" | "error";
|
|
231
|
+
/** What a widget asks Grist for (`UseGristOptions`). */
|
|
232
|
+
type GristRuntimeOptions = GristReadyOptions & {
|
|
233
|
+
/** Alert kinds mountGristWidget() never shows for this widget, e.g. ["section-not-linked"]. */
|
|
234
|
+
suppressAlerts?: GristSdkAlertKind[];
|
|
235
|
+
/**
|
|
236
|
+
* Extra rules for the mapped records, as a Standard Schema (zod 4,
|
|
237
|
+
* valibot, arktype…), checked after each cell's declared type. A record
|
|
238
|
+
* that fails keeps its typed values; its issues go to `cellIssues`.
|
|
239
|
+
*/
|
|
240
|
+
schema?: StandardSchema;
|
|
241
|
+
};
|
|
242
|
+
|
|
243
|
+
/**
|
|
244
|
+
* `useGrist()`'s methods, created once per runtime: every one is
|
|
245
|
+
* referentially stable for the widget's lifetime, and reads `grist` when
|
|
246
|
+
* called (the emulator installs and removes it in tests).
|
|
247
|
+
*/
|
|
248
|
+
|
|
249
|
+
type ListTablesOptions = {
|
|
250
|
+
/** Include Grist's own tables (`_grist_*`, `GristHidden_*`). */
|
|
251
|
+
includeSystem?: boolean;
|
|
252
|
+
};
|
|
253
|
+
type ListColumnsOptions = GristNoiseColumnsOptions & {
|
|
254
|
+
/** Include every column, Grist's helper and bookkeeping ones too. */
|
|
255
|
+
includeSystem?: boolean;
|
|
256
|
+
};
|
|
257
|
+
type GristColumnInfo = {
|
|
258
|
+
colId: string;
|
|
259
|
+
type?: string;
|
|
260
|
+
label?: string;
|
|
261
|
+
isFormula?: boolean;
|
|
262
|
+
formula?: string;
|
|
263
|
+
description?: string;
|
|
264
|
+
};
|
|
265
|
+
type GristApi = {
|
|
266
|
+
reload: () => Promise<void>;
|
|
267
|
+
fetchSelectedTable: (options?: GristFetchSelectedOptions) => Promise<GristColumnarTable>;
|
|
268
|
+
fetchTable: (tableId: string) => Promise<GristColumnarTable>;
|
|
269
|
+
fetchTableRows: <T extends Record<string, unknown> = Record<string, unknown>>(tableId: string, options?: FetchGristTableRowsOptions) => Promise<GristRowRecord<T>[]>;
|
|
270
|
+
listTables: (options?: ListTablesOptions) => Promise<string[]>;
|
|
271
|
+
listColumns: (tableId: string, options?: ListColumnsOptions) => Promise<GristColumnInfo[]>;
|
|
272
|
+
table: GristTableOperations;
|
|
273
|
+
getTable: (tableId: string) => GristTableOperations;
|
|
274
|
+
applyActions: (actions: GristUserActionTuple[], options?: GristApplyUserActionsOptions) => Promise<unknown>;
|
|
275
|
+
setWidgetOptions: (options: Record<string, unknown>) => Promise<void>;
|
|
276
|
+
patchWidgetOptions: (patch: Record<string, unknown>) => Promise<void>;
|
|
277
|
+
setCursorPosition: (pos: GristCursorPos) => Promise<void>;
|
|
278
|
+
setLinkedRowSelection: (rowIds: number[] | null) => Promise<void>;
|
|
279
|
+
getAttachmentUrl: (attachmentId: string, options?: {
|
|
280
|
+
readOnly?: boolean;
|
|
281
|
+
}) => Promise<string>;
|
|
282
|
+
fetchAttachmentBlob: (attachmentId: string, options?: {
|
|
283
|
+
readOnly?: boolean;
|
|
284
|
+
}) => Promise<GristFetchedAttachmentBlob>;
|
|
285
|
+
uploadAttachment: (file: Blob | File, options?: {
|
|
286
|
+
fileName?: string;
|
|
287
|
+
}) => Promise<GristAttachmentUploadResult>;
|
|
288
|
+
fetchWithAuth: (path: string, init?: RequestInit & {
|
|
289
|
+
readOnly?: boolean;
|
|
290
|
+
}) => Promise<Response>;
|
|
291
|
+
};
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* What `useGrist()` shows, derived from the runtime state: status, error,
|
|
295
|
+
* column-mapping status, the mapped record, and the access check. Pure
|
|
296
|
+
* functions, so they are tested without React or Grist.
|
|
297
|
+
*/
|
|
298
|
+
|
|
299
|
+
/** The widget's connection to Grist, as `useGrist().status` reports it. */
|
|
300
|
+
type GristWidgetStatus = "booting" | "ready" | "unavailable" | "error";
|
|
301
|
+
|
|
302
|
+
/** What the widget asks Grist for: access, columns to map, and the alerts it doesn't want. */
|
|
303
|
+
type UseGristOptions = GristRuntimeOptions;
|
|
304
|
+
/** A write under declared names: any of the mapped record's fields but its `id`. */
|
|
305
|
+
type GristRecordPatch<TMapped> = Partial<Omit<TMapped, "id">>;
|
|
306
|
+
/** Derived from the selection: no row, a row, or the add-row placeholder. */
|
|
307
|
+
type GristWidgetMode = "empty" | "row" | "new-row";
|
|
308
|
+
/**
|
|
309
|
+
* The widget's Grist state and API. Every method is referentially stable for
|
|
310
|
+
* the widget's lifetime: safe in effect dependencies. The object itself is
|
|
311
|
+
* new whenever a value changes; depend on the members you use, not on it.
|
|
312
|
+
*/
|
|
313
|
+
type UseGristResult<TRow = Record<string, unknown>, TMapped = Record<string, unknown>> = Omit<GristApi, "fetchTableRows"> & {
|
|
314
|
+
/** `"booting"` until Grist answers, then `"ready"`; `"unavailable"` outside Grist; `"error"` otherwise. */
|
|
315
|
+
status: GristWidgetStatus;
|
|
316
|
+
/** Inside Grist with its plugin API (null while connecting). */
|
|
317
|
+
isAvailable: boolean | null;
|
|
318
|
+
isReady: boolean;
|
|
319
|
+
/** Why the widget can't run (status `"error"` or `"unavailable"`), else null. */
|
|
320
|
+
error: string | null;
|
|
321
|
+
/** Grist's light or dark theme, null until Grist sends it. */
|
|
322
|
+
theme: GristTheme | null;
|
|
323
|
+
/** The selected row, raw column ids. */
|
|
324
|
+
record: GristRowRecord<TRow> | null;
|
|
325
|
+
/** The section's rows (what its filters show), raw column ids. */
|
|
326
|
+
records: GristRowRecord<TRow>[] | null;
|
|
327
|
+
/**
|
|
328
|
+
* The selected row under the declared column names, each cell the JS value
|
|
329
|
+
* its declared type promises (a cell that doesn't match is null, and in
|
|
330
|
+
* `cellIssues`); null until every required column is mapped.
|
|
331
|
+
*/
|
|
332
|
+
mappedRecord: TMapped | null;
|
|
333
|
+
/** Every row of the section, like `mappedRecord`. */
|
|
334
|
+
mappedRecords: TMapped[] | null;
|
|
335
|
+
/** The mapped cells that didn't match their declared type (or the widget's `schema`), by row. */
|
|
336
|
+
cellIssues: readonly GristCellIssue[];
|
|
337
|
+
/** Declared column name → the Grist column id(s) mapped to it. */
|
|
338
|
+
mappings: GristWidgetColumnMap;
|
|
339
|
+
/** Whether every required declared column is mapped (`pending` until Grist reports mappings). */
|
|
340
|
+
columnMappingStatus: ValidateColumnMappingsResult;
|
|
341
|
+
mode: GristWidgetMode;
|
|
342
|
+
/** The Grist column id mapped to a declared name, or the name itself. */
|
|
343
|
+
resolveMappedColumnId: (name: string) => string;
|
|
344
|
+
/**
|
|
345
|
+
* A patch under declared names, as real column ids for a write, each value
|
|
346
|
+
* encoded for its declared type (multi-column mappings are skipped).
|
|
347
|
+
*/
|
|
348
|
+
mapBack: (patch: Partial<TMapped>) => Record<string, unknown>;
|
|
349
|
+
/**
|
|
350
|
+
* Writes a patch under declared names to the selected row (or to `rowId`),
|
|
351
|
+
* encoded for each declared type: `mapBack` + `table.update` in one call.
|
|
352
|
+
* Rejects when no row is selected.
|
|
353
|
+
*/
|
|
354
|
+
updateRecord: {
|
|
355
|
+
(patch: GristRecordPatch<TMapped>): Promise<void>;
|
|
356
|
+
(rowId: number, patch: GristRecordPatch<TMapped>): Promise<void>;
|
|
357
|
+
};
|
|
358
|
+
/** Adds a row to the section's table from a patch under declared names; resolves to its row id. */
|
|
359
|
+
addRecord: (patch: GristRecordPatch<TMapped>) => Promise<number>;
|
|
360
|
+
/** The section's table id. */
|
|
361
|
+
currentTableId: string | null;
|
|
362
|
+
/** Any table as rows (full access). */
|
|
363
|
+
fetchTableRows: <T extends Record<string, unknown> = Record<string, unknown>>(tableId: string, options?: Parameters<GristApi["fetchTableRows"]>[1]) => Promise<GristRowRecord<T>[]>;
|
|
364
|
+
/** The last write's state. */
|
|
365
|
+
actionStatus: GristWidgetActionStatus;
|
|
366
|
+
actionError: string | null;
|
|
367
|
+
/** The options Grist stores for this widget, null until it sends them. */
|
|
368
|
+
widgetOptions: Record<string, unknown> | null;
|
|
369
|
+
};
|
|
370
|
+
/**
|
|
371
|
+
* The widget's Grist state and API. Inside `<GristWidgetProvider>` it uses the
|
|
372
|
+
* provider's connection and ignores `options`; outside one, the page's, made
|
|
373
|
+
* with the first caller's `options`.
|
|
374
|
+
*/
|
|
375
|
+
declare function useGrist<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(options?: UseGristOptions): UseGristResult<TRow, TMapped>;
|
|
376
|
+
/** `useGrist()` inside a provider, or null outside one: for components that also work without Grist. */
|
|
377
|
+
declare function useGristOptional<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped> | null;
|
|
378
|
+
/** `useGrist()` inside `<GristWidgetProvider>`; throws outside one. */
|
|
379
|
+
declare function useGristContext<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped>;
|
|
380
|
+
|
|
381
|
+
/**
|
|
382
|
+
* `defineGristWidget()`: a widget's whole declaration in one typed value.
|
|
383
|
+
* Everything else reads it: `widget.useGrist()` types the mapped records and
|
|
384
|
+
* the writes from it, `mountGristWidget()` takes the access level, the
|
|
385
|
+
* columns and the title from it, and the tests map its columns.
|
|
386
|
+
*
|
|
387
|
+
* ```ts
|
|
388
|
+
* export const widget = defineGristWidget({
|
|
389
|
+
* title: "Tasks",
|
|
390
|
+
* requiredAccess: "full",
|
|
391
|
+
* columns: [{ name: "Title", type: "Text" }, { name: "Done", type: "Bool" }],
|
|
392
|
+
* })
|
|
393
|
+
*
|
|
394
|
+
* const w = widget.useGrist() // w.mappedRecord: { id; Title: string | null; Done: boolean | null } | null
|
|
395
|
+
* await w.updateRecord({ Done: true })
|
|
396
|
+
* ```
|
|
397
|
+
*/
|
|
398
|
+
|
|
399
|
+
/** What a widget declares: `UseGristOptions`, plus its title and description. */
|
|
400
|
+
type GristWidgetDefinition = UseGristOptions & {
|
|
401
|
+
/** The widget's name: the page's title, and its manifest's. */
|
|
402
|
+
title?: string;
|
|
403
|
+
/** One sentence: the page's description, and its manifest's. */
|
|
404
|
+
description?: string;
|
|
405
|
+
};
|
|
406
|
+
/** The widget's mapped record type, from its declaration. */
|
|
407
|
+
type GristWidgetRow<W> = W extends GristWidget<infer D> ? GristMappedRow<D> : never;
|
|
408
|
+
/** A declared widget. Pass it to `mountGristWidget()` (as `widget`, exported from `src/app/App.tsx`). */
|
|
409
|
+
type GristWidget<D extends GristWidgetDefinition = GristWidgetDefinition> = {
|
|
410
|
+
/** The declaration, as written. */
|
|
411
|
+
readonly definition: D;
|
|
412
|
+
/** What the widget asks Grist for: the declaration without its title and description. */
|
|
413
|
+
readonly options: UseGristOptions;
|
|
414
|
+
readonly metadata: {
|
|
415
|
+
title?: string;
|
|
416
|
+
description?: string;
|
|
417
|
+
};
|
|
418
|
+
/**
|
|
419
|
+
* `useGrist()`, typed from the declaration: `mappedRecord`, `mappedRecords`,
|
|
420
|
+
* `mapBack`, `updateRecord` and `addRecord` use the declared names and the
|
|
421
|
+
* value each declared type gives. A hook: call it in a component.
|
|
422
|
+
*/
|
|
423
|
+
useGrist: () => UseGristResult<GristRowRecord, GristMappedRow<D>>;
|
|
424
|
+
};
|
|
425
|
+
/**
|
|
426
|
+
* Declares a widget. The `const` type parameter keeps the column names and
|
|
427
|
+
* types literal, so the mapped record is typed with no annotation, no
|
|
428
|
+
* `as const` and no generics.
|
|
429
|
+
*/
|
|
430
|
+
declare function defineGristWidget<const D extends GristWidgetDefinition>(definition: D): GristWidget<D>;
|
|
431
|
+
|
|
432
|
+
export { gristAddVisibleColumnAction as A, gristAttachmentCellValue as B, gristAttachmentCellValues as C, gristModifyColumnAction as D, gristRemoveColumnAction as E, gristRemoveRecordAction as F, gristRenameColumnAction as H, gristUpdateRecordAction as I, mergeGristAttachmentCellValue as J, tableDataToRows as K, useGrist as M, useGristContext as N, useGristOptional as O, checkGristCell as s, defineGristWidget as t, encodeGristCell as u, extractGristAttachmentId as v, extractGristAttachmentIdsFromCell as w, gristAddColumnAction as x, gristAddRecordAction as y, gristAddTableAction as z };
|
|
433
|
+
export type { GristWidget as G, ListColumnsOptions as L, StandardSchema as S, UseGristOptions as U, ValidateColumnMappingsResult as V, GristNoiseColumnsOptions as a, GristAttachmentUploadResult as b, GristCellIssue as c, GristColumnInfo as d, GristColumnarTable as e, GristFetchedAttachmentBlob as f, GristMappedRow as g, GristRecordPatch as h, GristSdkAlertKind as i, GristTheme as j, GristUserActionTuple as k, GristWidgetActionStatus as l, GristWidgetDefinition as m, GristWidgetMode as n, GristWidgetRow as o, GristWidgetStatus as p, ListTablesOptions as q, UseGristResult as r };
|