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.
Files changed (88) hide show
  1. package/CHANGELOG.md +84 -0
  2. package/README.md +79 -208
  3. package/dist/app.cjs +1336 -4415
  4. package/dist/app.cjs.map +1 -1
  5. package/dist/app.d.cts +6 -103
  6. package/dist/app.d.ts +6 -103
  7. package/dist/app.js +5 -7
  8. package/dist/chunk-4ZGVKGDF.js +204 -0
  9. package/dist/chunk-4ZGVKGDF.js.map +1 -0
  10. package/dist/{chunk-6Y2IONGJ.js → chunk-LSALXIGM.js} +191 -20
  11. package/dist/chunk-LSALXIGM.js.map +1 -0
  12. package/dist/chunk-MAPAWVQC.js +1898 -0
  13. package/dist/chunk-MAPAWVQC.js.map +1 -0
  14. package/dist/{chunk-YQNMIL33.js → chunk-OXA2VITC.js} +532 -181
  15. package/dist/chunk-OXA2VITC.js.map +1 -0
  16. package/dist/define-widget-B1FIvI-h.d.cts +433 -0
  17. package/dist/define-widget-B9gEtJP0.d.ts +433 -0
  18. package/dist/emulator/testing.cjs +3341 -6512
  19. package/dist/emulator/testing.cjs.map +1 -1
  20. package/dist/emulator/testing.d.cts +29 -14
  21. package/dist/emulator/testing.d.ts +29 -14
  22. package/dist/emulator/testing.js +78 -72
  23. package/dist/emulator/testing.js.map +1 -1
  24. package/dist/emulator.cjs +63 -249
  25. package/dist/emulator.cjs.map +1 -1
  26. package/dist/emulator.d.cts +6 -8
  27. package/dist/emulator.d.ts +6 -8
  28. package/dist/emulator.js +5 -11
  29. package/dist/index.cjs +1442 -4862
  30. package/dist/index.cjs.map +1 -1
  31. package/dist/index.d.cts +81 -260
  32. package/dist/index.d.ts +81 -260
  33. package/dist/index.js +12 -158
  34. package/dist/mount-grist-widget-CkB-3iG_.d.ts +137 -0
  35. package/dist/mount-grist-widget-Dtelqao_.d.cts +137 -0
  36. package/dist/{inline-DpcT8tV9.d.ts → templates-CGmRIQBV.d.cts} +89 -35
  37. package/dist/{inline-C7DkvuET.d.cts → templates-Cq94qOcf.d.ts} +89 -35
  38. package/dist/{types-D3JxUCfL.d.cts → types-DBStn0Dk.d.cts} +2 -26
  39. package/dist/{types-D3JxUCfL.d.ts → types-DBStn0Dk.d.ts} +2 -26
  40. package/package.json +8 -37
  41. package/dist/advanced.cjs +0 -2799
  42. package/dist/advanced.cjs.map +0 -1
  43. package/dist/advanced.d.cts +0 -822
  44. package/dist/advanced.d.ts +0 -822
  45. package/dist/advanced.js +0 -872
  46. package/dist/advanced.js.map +0 -1
  47. package/dist/chunk-22U7WAY3.js +0 -463
  48. package/dist/chunk-22U7WAY3.js.map +0 -1
  49. package/dist/chunk-64SVRWW7.js +0 -758
  50. package/dist/chunk-64SVRWW7.js.map +0 -1
  51. package/dist/chunk-6Y2IONGJ.js.map +0 -1
  52. package/dist/chunk-B4AKVSWV.js +0 -2362
  53. package/dist/chunk-B4AKVSWV.js.map +0 -1
  54. package/dist/chunk-ELGVOHFD.js +0 -32
  55. package/dist/chunk-ELGVOHFD.js.map +0 -1
  56. package/dist/chunk-GTTD5HPO.js +0 -36
  57. package/dist/chunk-GTTD5HPO.js.map +0 -1
  58. package/dist/chunk-NO6FYX33.js +0 -2084
  59. package/dist/chunk-NO6FYX33.js.map +0 -1
  60. package/dist/chunk-OPTOYD2Y.js +0 -277
  61. package/dist/chunk-OPTOYD2Y.js.map +0 -1
  62. package/dist/chunk-PM3B4WYV.js +0 -12
  63. package/dist/chunk-PM3B4WYV.js.map +0 -1
  64. package/dist/chunk-REV5AUXD.js +0 -25
  65. package/dist/chunk-REV5AUXD.js.map +0 -1
  66. package/dist/chunk-YQNMIL33.js.map +0 -1
  67. package/dist/create-grist-emulator-BCqp1BF9.d.ts +0 -81
  68. package/dist/create-grist-emulator-DBM8OSIR.d.cts +0 -81
  69. package/dist/emulator/devtools.cjs +0 -1404
  70. package/dist/emulator/devtools.cjs.map +0 -1
  71. package/dist/emulator/devtools.d.cts +0 -48
  72. package/dist/emulator/devtools.d.ts +0 -48
  73. package/dist/emulator/devtools.js +0 -506
  74. package/dist/emulator/devtools.js.map +0 -1
  75. package/dist/emulator/transports.cjs +0 -1132
  76. package/dist/emulator/transports.cjs.map +0 -1
  77. package/dist/emulator/transports.d.cts +0 -38
  78. package/dist/emulator/transports.d.ts +0 -38
  79. package/dist/emulator/transports.js +0 -12
  80. package/dist/emulator/transports.js.map +0 -1
  81. package/dist/templates-8k2LKoO-.d.cts +0 -24
  82. package/dist/templates-DIwi_mvI.d.ts +0 -24
  83. package/dist/use-grist-reads-DUMvJgV7.d.ts +0 -480
  84. package/dist/use-grist-reads-DpjVuI0H.d.cts +0 -480
  85. package/dist/use-grist-types-DdOLEJXN.d.cts +0 -499
  86. package/dist/use-grist-types-kwxoFeub.d.ts +0 -499
  87. package/dist/use-grist-widget-options-from-context-CGOlQ5Vc.d.cts +0 -43
  88. package/dist/use-grist-widget-options-from-context-CGOlQ5Vc.d.ts +0 -43
package/dist/index.d.ts CHANGED
@@ -1,276 +1,35 @@
1
- import { l as GristFormulaKind, c as GristReplicaColumn, b as GristReplicaDocument, a as GristReplicaTable, m as GristReplicaRow, n as GristRequiredAccess, o as GristDocumentMode, i as GristReadyOptions } from './types-D3JxUCfL.js';
2
- export { p as GristApplyUserActionsOptions, q as GristColumnToMap, r as GristColumnsToMap, e as GristCursorPos, s as GristDocApi, j as GristFetchSelectedOptions, t as GristMinimalRecord, g as GristReplicaSelection, G as GristRowRecord, u as GristTableNewRecord, v as GristTableOpOptions, k as GristTableOperations, w as GristTableUpdateRecord, x as GristTableUpsertOptions, y as GristTableUpsertRecord, d as GristWidgetColumnMap, h as GristWidgetConfiguration, f as GristWidgetInteraction, z as GristWidgetLinkingInfo } from './types-D3JxUCfL.js';
3
- import { G as GristSdkAlertsWidgetSlice, a as UseGristResult, b as GetGristSdkAlertDescriptorsOptions, c as GristSdkAlertDescriptor, U as UseGristOptions, d as UseGristSelectionResult, e as UseGristStatusResult, f as UseGristThemeResult, g as UseGristWritesResult } from './use-grist-types-kwxoFeub.js';
4
- export { B as BuildReplicaDocumentFromDocApiOptions, h as GristAttachmentUploadResult, i as GristEncodedAttachmentList, j as GristFetchedAttachment, k as GristFetchedAttachmentBlob, l as GristSdkAlertKind, m as GristSdkAlertSeverity, n as GristTheme, o as GristWidgetActionStatus, p as GristWidgetMode, R as ReplicaTableColumnMetaLite, V as ValidateColumnMappingsResult, q as buildReplicaColumnsFromColumnar, r as buildReplicaDocumentFromDocApi, s as extractAttachmentIdsFromUploadPayload, t as extractFirstAttachmentIdFromUploadPayload, u as extractGristAttachmentId, v as extractGristAttachmentIdsFromCell, w as fetchAttachmentBase64, x as fetchAttachmentBase64ForCell, y as fetchAttachmentBlob, z as formatAccessInsufficientMessage, A as formatColumnMappingAlertMessage, C as formatLinkStaleAlertMessage, D as formatMappingPendingAlertMessage, E as formatMappingUnreportedAlertMessage, F as formatSectionNotLinkedAlertMessage, H as formatSourceNotWiredAlertMessage, I as getAttachmentDownloadUrl, J as getAttachmentDownloadUrlForCell, K as getGristSdkAlertDescriptors, L as getGristSdkAlertSeverity, M as getGristSdkAlertTitle, N as gristAttachmentCellValue, O as gristAttachmentCellValues, P as isAccessInsufficientError, Q as isWidgetSectionNotLinked, S as loadColumnMetadataByTable, T as mergeGristAttachmentCellValue, W as orderedColumnIds, X as parseGristAttachmentUploadResponse, Y as parseGristAttachmentUploadResponseIds, Z as uploadGristAttachment, _ as validateColumnMappings } from './use-grist-types-kwxoFeub.js';
5
- import { a as GristNoiseColumnsOptions } from './use-grist-reads-DUMvJgV7.js';
6
- import { GristWidgetSnapshot } from './advanced.js';
7
- export { F as FetchGristTableRowsOptions, b as GristAccessToken, c as GristCapabilities, d as GristCellValue, e as GristColumnInfo, f as GristColumnLike, g as GristColumnarTable, h as GristSafeParseCellResult, i as GristSafeParseIssue, j as GristSafeParseIssueCode, k as GristSafeRefListValue, l as GristSafeRefValue, m as GristSafeTableCellIssue, n as GristSafeTableCellMeta, o as GristTableRowsOrder, p as GristUserActionTuple, q as GristWidgetStatus, L as ListColumnsOptions, r as ListTablesOptions, S as SafeParseGristTableDataOptions, s as SafeParseGristTableDataResult, t as SafeParseGristValuesOptions, U as UseGristCoreOptions, u as UseGristCoreResult, v as computeRowCount, w as decodeColumnarToReplicaRows, x as fetchGristRow, y as fetchGristTableRows, z as fetchWithGristAuth, A as findRowIndexById, B as getGristAccessToken, C as gristAddColumnAction, D as gristAddRecordAction, E as gristAddTableAction, H as gristAddVisibleColumnAction, I as gristBulkAddRecordAction, J as gristBulkRemoveRecordAction, K as gristBulkUpdateRecordAction, M as gristCellValueSchema, N as gristDuplicateTableAction, O as gristModifyColumnAction, P as gristRemoveColumnAction, Q as gristRemoveRecordAction, R as gristRemoveTableAction, T as gristRenameColumnAction, V as gristRenameTableAction, W as gristReplaceTableDataAction, X as gristSafeRefListValueSchema, Y as gristSafeRefValueSchema, Z as gristSetDocumentInfoAction, _ as gristUpdateRecordAction, $ as inferDisplayHelpersByRef, a0 as isGristNoiseColumn, a1 as materializeGristRowsFromColumnar, a2 as rowAtIndex, a3 as safeParseGristTableData, a4 as safeParseGristValues, a5 as safeParseRowsToDisplayRows, a6 as sortRowsByGristOrder, a7 as tableDataToRows } from './use-grist-reads-DUMvJgV7.js';
1
+ import { U as UseGristOptions, a as GristNoiseColumnsOptions } from './define-widget-B9gEtJP0.js';
2
+ export { b as GristAttachmentUploadResult, c as GristCellIssue, d as GristColumnInfo, e as GristColumnarTable, f as GristFetchedAttachmentBlob, g as GristMappedRow, h as GristRecordPatch, i as GristSdkAlertKind, j as GristTheme, k as GristUserActionTuple, G as GristWidget, l as GristWidgetActionStatus, m as GristWidgetDefinition, n as GristWidgetMode, o as GristWidgetRow, p as GristWidgetStatus, L as ListColumnsOptions, q as ListTablesOptions, S as StandardSchema, r as UseGristResult, V as ValidateColumnMappingsResult, s as checkGristCell, t as defineGristWidget, u as encodeGristCell, v as extractGristAttachmentId, w as extractGristAttachmentIdsFromCell, x as gristAddColumnAction, y as gristAddRecordAction, z as gristAddTableAction, A as gristAddVisibleColumnAction, B as gristAttachmentCellValue, C as gristAttachmentCellValues, D as gristModifyColumnAction, E as gristRemoveColumnAction, F as gristRemoveRecordAction, H as gristRenameColumnAction, I as gristUpdateRecordAction, J as mergeGristAttachmentCellValue, K as tableDataToRows, M as useGrist, N as useGristContext, O as useGristOptional } from './define-widget-B9gEtJP0.js';
8
3
  import * as react from 'react';
9
4
  import { ReactNode } from 'react';
10
- export { U as UseGristWidgetOptionsFromContextConfig, a as UseGristWidgetOptionsFromContextResult, u as useGristWidgetOptionsFromContext } from './use-grist-widget-options-from-context-CGOlQ5Vc.js';
11
- import 'zod';
12
-
13
- declare function inferGristFormulaKind(isFormula: boolean, formulaTrimmed: string): GristFormulaKind;
14
- /** Use when `formulaKind` may be missing (e.g. older document builds). */
15
- declare function resolveGristFormulaKind(col: GristReplicaColumn): GristFormulaKind;
16
- /** Serialize cell values for JSON output. */
17
- declare function serializeJsonFriendly(value: unknown): unknown;
18
-
19
- /**
20
- * Ensure `rows` is a concrete array for emulator / merge logic.
21
- * Call at host boundaries (`createDocument`, tests); JSON may still omit `rows` for schema-only.
22
- */
23
- declare function normalizeReplicaTableInput<T extends GristReplicaTable>(table: T): T & {
24
- rows: GristReplicaRow[];
25
- };
26
- /** Apply {@link normalizeReplicaTableInput} to every table; shallow-copies the document shell. */
27
- declare function normalizeReplicaDocumentInput<T extends GristReplicaDocument>(doc: T): T;
28
- /** How row arrays appear in serialized replica JSON from {@link buildReplicaJsonPayload}. */
29
- type ReplicaJsonIncludeRows = "none" | "samples" | "full";
30
- /**
31
- * Clone a replica document for JSON output: strip rows, cap to first N, or pass through.
32
- * Does not mutate the source document.
33
- */
34
- declare function buildReplicaJsonPayload(doc: GristReplicaDocument, options: {
35
- includeRows: ReplicaJsonIncludeRows;
36
- sampleRowLimit?: number;
37
- }): GristReplicaDocument;
38
-
39
- /**
40
- * Grist stores column widget configuration in `_grist_Tables_column.widgetOptions`
41
- * as a JSON string. Choice fields use `choices: string[]` plus optional
42
- * `choiceOptions: Record<string, Style>` (e.g. `fillColor`, `textColor`).
43
- *
44
- * @see https://github.com/gristlabs/grist-core/blob/main/app/client/widgets/ChoiceEditor.js
45
- */
46
- /** One selectable choice for UI (value stored in the cell is `value`). */
47
- type GristChoiceListEntry = {
48
- value: string;
49
- label: string;
50
- fillColor?: string;
51
- textColor?: string;
52
- };
53
- /**
54
- * Parse a cell value from `_grist_Tables_column.widgetOptions` into a plain object.
55
- */
56
- declare function parseGristWidgetOptionsCell(raw: unknown): Record<string, unknown> | undefined;
57
- /**
58
- * Normalizes Grist Choice / ChoiceList widgetOptions into a flat list for dropdowns.
59
- * `choices` entries are string labels (the stored cell value). Per-choice styling
60
- * lives in `choiceOptions[label]`.
61
- */
62
- declare function normalizeGristChoiceListEntries(widgetOptions: Record<string, unknown> | undefined): GristChoiceListEntry[];
63
-
64
- /**
65
- * Encoding helpers for Grist cell values.
66
- *
67
- * Grist sends some types as marshalled tuples or numeric epochs. This file
68
- * exposes pure decode/encode functions so widget code never has to spelunk
69
- * Grist's wire format.
70
- *
71
- * References: Grist `grist/RowRecord` and `grist/DocActions` typings.
72
- */
73
-
74
- /** `["E", "ErrorClass", "message", traceback?]` — Grist error sentinel. */
75
- type GristEncodedError = ["E", string, string?, string?];
76
- /** `["L", ...items]` — list (used for ChoiceList, RefList, Attachments). */
77
- type GristEncodedList = ["L", ...unknown[]];
78
- /** `["D", epochSeconds, "tz/Name"]` — DateTime with timezone. */
79
- type GristEncodedDateTime = ["D", number, string];
80
- /** `["d", epochSeconds]` — Date (no time). */
81
- type GristEncodedDate = ["d", number];
82
- /** `["R", tableId, rowId]` — explicit reference. */
83
- type GristEncodedRef = ["R", string, number];
84
- /** `["r", rowId]` — bare reference (when table is contextual). */
85
- type GristEncodedBareRef = ["r", number];
86
- /** `["P", encoded]` — pending marker. */
87
- type GristEncodedPending = ["P"];
88
- type GristDecodedValue = null | string | number | boolean | Date | GristDecodedValue[] | {
89
- __error: true;
90
- type: string;
91
- message?: string;
92
- traceback?: string;
93
- } | {
94
- __ref: true;
95
- tableId?: string;
96
- rowId: number;
97
- };
98
- /**
99
- * Normalises a Grist `fetchTable` cell that points at a row in another table.
100
- * Most payloads use a bare numeric row id, but `Ref:*` values may appear as
101
- * `["R", tableId, rowId]` or `["r", rowId]` (same shape as {@link decodeGristValue}).
102
- */
103
- declare function coerceGristDocApiRefRowId(value: unknown): number | undefined;
104
- /**
105
- * Decodes a Grist cell value into an idiomatic JS value.
106
- *
107
- * Pass the column's metadata (from `useGristSchema` or `_grist_Tables_column`)
108
- * for type-aware decoding (e.g. `Date` columns return `Date` even when stored as a number).
109
- */
110
- declare function decodeGristValue(value: unknown, column?: GristReplicaColumn): GristDecodedValue;
111
- /** Convenience: true when the cell is a Grist error sentinel. */
112
- declare function isGristCellError(value: unknown): value is GristEncodedError;
113
- /**
114
- * Encodes a JS value into Grist's expected wire form for a given column type.
115
- *
116
- * Use before passing values to `applyUserActions` or `TableOperations.update`
117
- * for `Date`, `DateTime`, `Ref`, `RefList`, and `ChoiceList` columns.
118
- */
119
- declare function encodeGristValue(value: unknown, column?: GristReplicaColumn): unknown;
120
-
121
- /**
122
- * Pure projections from the handshake snapshot for boundary / shell UI.
123
- *
124
- * Blocking states (`booting`, `unavailable`, `error`) map to full-screen chrome
125
- * via `<GristBoundary>`. Non-blocking degradations stay on the alert path
126
- * ({@link getGristSdkAlertDescriptors}).
127
- */
128
-
129
- type GristBoundaryBlockingKind = "booting" | "unavailable" | "error";
130
- type GristBoundaryBootPhase = "idle" | "detecting" | "negotiating" | "generic";
131
- type GristBoundaryView = {
132
- mode: "blocking";
133
- kind: GristBoundaryBlockingKind;
134
- bootPhase?: GristBoundaryBootPhase;
135
- title: string;
136
- message: string;
137
- showRetry: boolean;
138
- } | {
139
- mode: "ready";
140
- };
141
- /**
142
- * Human-readable boot label from lifecycle phase (for spinners / progress UI).
143
- */
144
- declare function deriveBoundaryBootLabel(snapshot: GristWidgetSnapshot): string;
145
- declare function deriveBoundaryBootPhase(snapshot: GristWidgetSnapshot): GristBoundaryBootPhase;
146
- /**
147
- * Turn internal handshake errors into short, actionable copy for `<GristBoundary>`.
148
- */
149
- declare function formatBoundaryUserMessage(raw: string | null, snapshot: GristWidgetSnapshot): string;
150
- /**
151
- * Classify how `<GristBoundary>` should render: full-screen blocking vs children.
152
- */
153
- declare function deriveBoundaryView(snapshot: GristWidgetSnapshot): GristBoundaryView;
154
- /** Copy for `gate="canRender"` while column mappings are not yet usable. */
155
- declare const GRIST_BOUNDARY_PREPARING_COPY: {
156
- readonly title: "Map your columns";
157
- readonly message: "Open the widget settings in Grist (Creator Panel → Custom widget) and connect each required column to your table.";
158
- };
159
-
160
- /**
161
- * React hook: widget slice + optional handshake snapshot for
162
- * {@link getGristSdkAlertDescriptors}.
163
- */
164
- declare function useGristSdkAlertDescriptors(widget?: GristSdkAlertsWidgetSlice | UseGristResult, options?: GetGristSdkAlertDescriptorsOptions): GristSdkAlertDescriptor[];
5
+ import { a as GristReplicaTable, l as GristRequiredAccess, m as GristDocumentMode, e as GristReplicaColumn, i as GristReadyOptions, G as GristReplicaDocument, n as GristFormulaKind } from './types-DBStn0Dk.js';
6
+ export { o as GristApplyUserActionsOptions, p as GristColumnToMap, q as GristColumnsToMap, c as GristCursorPos, j as GristFetchSelectedOptions, r as GristReplicaRow, f as GristRowRecord, k as GristTableOperations, b as GristWidgetColumnMap, d as GristWidgetInteraction } from './types-DBStn0Dk.js';
165
7
 
166
8
  type GristWidgetProviderProps = {
9
+ /** Read once, at mount: what the widget asks Grist for. */
167
10
  options?: UseGristOptions;
168
11
  children: ReactNode;
169
12
  };
170
13
  /**
171
- * Sets up Grist once at the app root. Prefer slice hooks (`useGristSelection`,
172
- * `useGristWrites`, …) in large widgets; use `useGristContext()` when you need everything.
173
- *
174
- * Owns a {@link GristHandshakeManager} and mounts the slice / full-result context
175
- * tree underneath it so `useRpcHeartbeatCoalesce()` in slice hooks sees the manager
176
- * (ordering required — see `tests/sdk/handshake-rpc-coalesce.test.tsx`).
14
+ * Connects to Grist for the widgets below it: `useGrist()` under it reads this
15
+ * connection. `mountGristWidget()` renders it; render it yourself only for a
16
+ * page that manages its own React root.
177
17
  */
178
18
  declare function GristWidgetProvider({ options, children }: GristWidgetProviderProps): react.JSX.Element;
179
- /**
180
- * Access the full `UseGristResult` from inside a `<GristWidgetProvider>`.
181
- *
182
- * The returned object updates whenever any Grist state changes (record selection,
183
- * widget options, etc.). Individual methods on the result (e.g. `w.fetchTable`,
184
- * `w.listTables`) are referentially stable and safe to use in `useEffect` deps.
185
- * See `UseGristResult` JSDoc for details.
186
- */
187
- declare function useGristContext<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped>;
188
- declare function useGristOptional<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped> | null;
189
-
190
- /**
191
- * Primary Grist hook — use inside `<GristWidgetProvider>` via `useGristContext()`,
192
- * or standalone in a single-leaf widget.
193
- */
194
- declare function useGrist<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(options?: UseGristOptions): UseGristResult<TRow, TMapped>;
195
-
196
- /**
197
- * Slice subscriber: status + current-table info. Re-renders on status, error,
198
- * `currentTableId`, or `currentTableLoading` changes only.
199
- *
200
- * Must be called inside `<GristWidgetProvider>` — for standalone usage use
201
- * `useGrist()` directly.
202
- */
203
- declare function useGristStatus(): UseGristStatusResult;
204
- /**
205
- * Slice subscriber for the selection / mappings / widget-options stream.
206
- * Must be called inside `<GristWidgetProvider>`.
207
- */
208
- declare function useGristSelection<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristSelectionResult<TRow, TMapped>;
209
- /**
210
- * Slice subscriber for writes (`table`, `getTable`, `applyActions`, `actionStatus`).
211
- * Must be called inside `<GristWidgetProvider>`.
212
- */
213
- declare function useGristWrites(): UseGristWritesResult;
214
- /**
215
- * Slice subscriber for the host theme. Must be called inside `<GristWidgetProvider>`.
216
- */
217
- declare function useGristTheme(): UseGristThemeResult;
218
19
 
219
- type GristBoundaryGate = "ready" | "canRender";
220
20
  type GristBoundaryProps = {
221
- /**
222
- * Pass an explicit widget instance (e.g. when not using `<GristWidgetProvider>`).
223
- * Otherwise the boundary reads from the nearest provider.
224
- */
225
- widget?: UseGristResult;
226
- /**
227
- * When `"canRender"`, children render only after mappings are usable
228
- * (`capabilities.canRender`). Use for widgets that require mapped columns.
229
- */
230
- gate?: GristBoundaryGate;
231
- /** Rendered while `grist.ready` is in flight. */
232
- bootingFallback?: ReactNode;
233
- /** Shown when `gate="canRender"` and mappings are not yet usable. */
234
- preparingFallback?: ReactNode;
235
- /** Rendered when the widget is not embedded in Grist (e.g. opened directly). */
236
- unavailableFallback?: ReactNode | ((actions: GristBoundaryActions) => ReactNode);
237
- /** Rendered on any error from `useGristReady`, subscriptions, or actions. */
238
- errorFallback?: (error: string, actions: GristBoundaryActions) => ReactNode;
239
- /**
240
- * Delay before showing "unavailable" UI. Helps avoid false negatives on slow
241
- * networks where the plugin API handshake arrives late.
242
- */
243
- unavailableGraceMs?: number;
244
21
  children: ReactNode;
245
22
  };
246
- type GristBoundaryActions = {
247
- reload: () => Promise<void>;
248
- isReloading: boolean;
249
- };
250
- type GristBoundaryScreenProps = {
251
- title: string;
252
- message: string;
253
- /** Affects WAI-ARIA role only (`alert` vs `status`); copy uses the same neutral styles. */
254
- tone?: "default" | "error";
255
- showRetry?: boolean;
256
- actions?: GristBoundaryActions;
257
- retryLabel?: string;
258
- retryBusyLabel?: string;
259
- };
260
- /** Centered full-viewport chrome for booting / unavailable / error states. */
261
- declare function GristBoundaryScreen({ title, message, tone, showRetry, actions, retryLabel, retryBusyLabel, }: GristBoundaryScreenProps): react.JSX.Element;
262
23
  /**
263
- * Standardised loading / unavailable / error chrome for a Grist widget.
264
- *
265
- * ```tsx
266
- * <GristWidgetProvider options={{ requiredAccess: "full" }}>
267
- * <GristBoundary>
268
- * <MyWidget />
269
- * </GristBoundary>
270
- * </GristWidgetProvider>
271
- * ```
24
+ * Renders the widget once Grist is connected, has granted the access it
25
+ * declares, and every required declared column is mapped; until then, a
26
+ * screen that says what is missing (with a retry where one can help).
27
+ * Requires `<GristWidgetProvider>`; `mountGristWidget()` renders both.
272
28
  */
273
- declare function GristBoundary({ widget, gate, bootingFallback, preparingFallback, unavailableFallback, errorFallback, unavailableGraceMs, children, }: GristBoundaryProps): react.JSX.Element;
29
+ declare function GristBoundary({ children }: GristBoundaryProps): react.JSX.Element;
30
+
31
+ /** How row arrays appear in serialized replica JSON from {@link buildReplicaJsonPayload}. */
32
+ type ReplicaJsonIncludeRows = "none" | "samples" | "full";
274
33
 
275
34
  type ColumnExcludeContext = {
276
35
  tableId: string;
@@ -332,9 +91,71 @@ declare function useGristSchema(options?: UseGristSchemaOptions): UseGristSchema
332
91
  type UseWidgetMetadataInput = {
333
92
  title: string;
334
93
  description: string;
335
- syncToParent?: boolean;
336
94
  };
337
95
  declare function useWidgetMetadata(input?: UseWidgetMetadataInput | null): void;
338
96
 
339
- export { GRIST_BOUNDARY_PREPARING_COPY, GetGristSdkAlertDescriptorsOptions, GristBoundary, GristBoundaryScreen, GristDocumentMode, GristFormulaKind, GristNoiseColumnsOptions, GristReadyOptions, GristReplicaColumn, GristReplicaDocument, GristReplicaRow, GristReplicaTable, GristRequiredAccess, GristSdkAlertDescriptor, GristSdkAlertsWidgetSlice, GristWidgetProvider, UseGristOptions, UseGristResult, UseGristSelectionResult, UseGristStatusResult, UseGristThemeResult, UseGristWritesResult, buildReplicaJsonPayload, coerceGristDocApiRefRowId, decodeGristValue, deriveBoundaryBootLabel, deriveBoundaryBootPhase, deriveBoundaryView, encodeGristValue, formatBoundaryUserMessage, inferGristFormulaKind, isGristCellError, normalizeGristChoiceListEntries, normalizeReplicaDocumentInput, normalizeReplicaTableInput, parseGristWidgetOptionsCell, resolveGristFormulaKind, serializeJsonFriendly, useGrist, useGristContext, useGristOptional, useGristSchema, useGristSdkAlertDescriptors, useGristSelection, useGristStatus, useGristTheme, useGristWrites, useWidgetMetadata };
340
- export type { GristBoundaryActions, GristBoundaryBlockingKind, GristBoundaryBootPhase, GristBoundaryGate, GristBoundaryProps, GristBoundaryView, GristChoiceListEntry, GristDecodedValue, GristEncodedBareRef, GristEncodedDate, GristEncodedDateTime, GristEncodedError, GristEncodedList, GristEncodedPending, GristEncodedRef, GristSchemaTableView, GristWidgetProviderProps, ReplicaDocumentJsonOptions, ReplicaJsonIncludeRows, UseGristSchemaOptions, UseGristSchemaResult, UseWidgetMetadataInput };
97
+ /**
98
+ * Encoding helpers for Grist cell values.
99
+ *
100
+ * Grist sends some types as marshalled tuples or numeric epochs. This file
101
+ * exposes pure decode/encode functions so widget code never has to spelunk
102
+ * Grist's wire format.
103
+ *
104
+ * References: Grist `grist/RowRecord` and `grist/DocActions` typings.
105
+ */
106
+
107
+ /** `["E", "ErrorClass", "message", traceback?]` — Grist error sentinel. */
108
+ type GristEncodedError = ["E", string, string?, string?];
109
+ type GristDecodedValue = null | string | number | boolean | Date | GristDecodedValue[] | {
110
+ __error: true;
111
+ type: string;
112
+ message?: string;
113
+ traceback?: string;
114
+ } | {
115
+ __ref: true;
116
+ tableId?: string;
117
+ rowId: number;
118
+ };
119
+ /**
120
+ * Decodes a Grist cell value into an idiomatic JS value.
121
+ *
122
+ * Pass the column's metadata (from `useGristSchema` or `_grist_Tables_column`)
123
+ * for type-aware decoding (e.g. `Date` columns return `Date` even when stored as a number).
124
+ */
125
+ declare function decodeGristValue(value: unknown, column?: GristReplicaColumn): GristDecodedValue;
126
+ /** Convenience: true when the cell is a Grist error sentinel. */
127
+ declare function isGristCellError(value: unknown): value is GristEncodedError;
128
+ /**
129
+ * Encodes a JS value into Grist's expected wire form for a given column type.
130
+ *
131
+ * Use before passing values to `applyUserActions` or `TableOperations.update`
132
+ * for `Date`, `DateTime`, `Ref`, `RefList`, and `ChoiceList` columns.
133
+ */
134
+ declare function encodeGristValue(value: unknown, column?: GristReplicaColumn): unknown;
135
+
136
+ /**
137
+ * Grist stores column widget configuration in `_grist_Tables_column.widgetOptions`
138
+ * as a JSON string. Choice fields use `choices: string[]` plus optional
139
+ * `choiceOptions: Record<string, Style>` (e.g. `fillColor`, `textColor`).
140
+ *
141
+ * @see https://github.com/gristlabs/grist-core/blob/main/app/client/widgets/ChoiceEditor.js
142
+ */
143
+ /** One selectable choice for UI (value stored in the cell is `value`). */
144
+ type GristChoiceListEntry = {
145
+ value: string;
146
+ label: string;
147
+ fillColor?: string;
148
+ textColor?: string;
149
+ };
150
+ /**
151
+ * Normalizes Grist Choice / ChoiceList widgetOptions into a flat list for dropdowns.
152
+ * `choices` entries are string labels (the stored cell value). Per-choice styling
153
+ * lives in `choiceOptions[label]`.
154
+ */
155
+ declare function normalizeGristChoiceListEntries(widgetOptions: Record<string, unknown> | undefined): GristChoiceListEntry[];
156
+
157
+ /** Use when `formulaKind` may be missing (e.g. older document builds). */
158
+ declare function resolveGristFormulaKind(col: GristReplicaColumn): GristFormulaKind;
159
+
160
+ export { GristBoundary, GristDocumentMode, GristFormulaKind, GristNoiseColumnsOptions, GristReadyOptions, GristReplicaColumn, GristReplicaDocument, GristReplicaTable, GristRequiredAccess, GristWidgetProvider, UseGristOptions, decodeGristValue, encodeGristValue, isGristCellError, normalizeGristChoiceListEntries, resolveGristFormulaKind, useGristSchema, useWidgetMetadata };
161
+ export type { GristBoundaryProps, GristChoiceListEntry, GristSchemaTableView, GristWidgetProviderProps, ReplicaDocumentJsonOptions, UseGristSchemaOptions, UseGristSchemaResult, UseWidgetMetadataInput };
package/dist/index.js CHANGED
@@ -1,213 +1,67 @@
1
1
  import {
2
- GRIST_BOUNDARY_PREPARING_COPY,
3
2
  GristBoundary,
4
- GristBoundaryScreen,
5
3
  GristWidgetProvider,
6
- buildReplicaColumnsFromColumnar,
7
- buildReplicaDocumentFromDocApi,
8
- deriveBoundaryBootLabel,
9
- deriveBoundaryBootPhase,
10
- deriveBoundaryView,
11
- extractAttachmentIdsFromUploadPayload,
12
- extractFirstAttachmentIdFromUploadPayload,
4
+ checkGristCell,
5
+ defineGristWidget,
6
+ encodeGristCell,
13
7
  extractGristAttachmentId,
14
8
  extractGristAttachmentIdsFromCell,
15
- fetchAttachmentBase64,
16
- fetchAttachmentBase64ForCell,
17
- fetchAttachmentBlob,
18
- formatAccessInsufficientMessage,
19
- formatBoundaryUserMessage,
20
- formatColumnMappingAlertMessage,
21
- formatLinkStaleAlertMessage,
22
- formatMappingPendingAlertMessage,
23
- formatMappingUnreportedAlertMessage,
24
- formatSectionNotLinkedAlertMessage,
25
- formatSourceNotWiredAlertMessage,
26
- getAttachmentDownloadUrl,
27
- getAttachmentDownloadUrlForCell,
28
- getGristSdkAlertDescriptors,
29
- getGristSdkAlertSeverity,
30
- getGristSdkAlertTitle,
31
9
  gristAttachmentCellValue,
32
10
  gristAttachmentCellValues,
33
- inferGristFormulaKind,
34
- isAccessInsufficientError,
35
- isWidgetSectionNotLinked,
36
- loadColumnMetadataByTable,
37
11
  mergeGristAttachmentCellValue,
38
- orderedColumnIds,
39
- parseGristAttachmentUploadResponse,
40
- parseGristAttachmentUploadResponseIds,
12
+ normalizeGristChoiceListEntries,
41
13
  resolveGristFormulaKind,
42
- serializeJsonFriendly,
43
- uploadGristAttachment,
14
+ tableDataToRows,
44
15
  useGrist,
45
16
  useGristContext,
46
17
  useGristOptional,
47
18
  useGristSchema,
48
- useGristSdkAlertDescriptors,
49
- useGristSelection,
50
- useGristStatus,
51
- useGristTheme,
52
- useGristWrites,
53
19
  useWidgetMetadata
54
- } from "./chunk-B4AKVSWV.js";
55
- import {
56
- fetchWithGristAuth,
57
- getGristAccessToken,
58
- useGristWidgetOptionsFromContext,
59
- validateColumnMappings
60
- } from "./chunk-NO6FYX33.js";
61
- import {
62
- buildReplicaJsonPayload,
63
- normalizeReplicaDocumentInput,
64
- normalizeReplicaTableInput
65
- } from "./chunk-GTTD5HPO.js";
66
- import {
67
- isGristNoiseColumn
68
- } from "./chunk-REV5AUXD.js";
20
+ } from "./chunk-MAPAWVQC.js";
69
21
  import {
70
- computeRowCount,
71
- decodeColumnarToReplicaRows,
72
- fetchGristRow,
73
- fetchGristTableRows,
74
- findRowIndexById,
75
- materializeGristRowsFromColumnar,
76
- rowAtIndex,
77
- safeParseRowsToDisplayRows,
78
- sortRowsByGristOrder,
79
- tableDataToRows
80
- } from "./chunk-OPTOYD2Y.js";
81
- import {
82
- coerceGristDocApiRefRowId,
83
22
  decodeGristValue,
84
23
  encodeGristValue,
85
24
  gristAddColumnAction,
86
25
  gristAddRecordAction,
87
26
  gristAddTableAction,
88
27
  gristAddVisibleColumnAction,
89
- gristBulkAddRecordAction,
90
- gristBulkRemoveRecordAction,
91
- gristBulkUpdateRecordAction,
92
- gristCellValueSchema,
93
- gristDuplicateTableAction,
94
28
  gristModifyColumnAction,
95
29
  gristRemoveColumnAction,
96
30
  gristRemoveRecordAction,
97
- gristRemoveTableAction,
98
31
  gristRenameColumnAction,
99
- gristRenameTableAction,
100
- gristReplaceTableDataAction,
101
- gristSafeRefListValueSchema,
102
- gristSafeRefValueSchema,
103
- gristSetDocumentInfoAction,
104
32
  gristUpdateRecordAction,
105
- inferDisplayHelpersByRef,
106
- isGristCellError,
107
- normalizeGristChoiceListEntries,
108
- parseGristWidgetOptionsCell,
109
- safeParseGristTableData,
110
- safeParseGristValues
111
- } from "./chunk-64SVRWW7.js";
33
+ isGristCellError
34
+ } from "./chunk-4ZGVKGDF.js";
112
35
  export {
113
- GRIST_BOUNDARY_PREPARING_COPY,
114
36
  GristBoundary,
115
- GristBoundaryScreen,
116
37
  GristWidgetProvider,
117
- buildReplicaColumnsFromColumnar,
118
- buildReplicaDocumentFromDocApi,
119
- buildReplicaJsonPayload,
120
- coerceGristDocApiRefRowId,
121
- computeRowCount,
122
- decodeColumnarToReplicaRows,
38
+ checkGristCell,
123
39
  decodeGristValue,
124
- deriveBoundaryBootLabel,
125
- deriveBoundaryBootPhase,
126
- deriveBoundaryView,
40
+ defineGristWidget,
41
+ encodeGristCell,
127
42
  encodeGristValue,
128
- extractAttachmentIdsFromUploadPayload,
129
- extractFirstAttachmentIdFromUploadPayload,
130
43
  extractGristAttachmentId,
131
44
  extractGristAttachmentIdsFromCell,
132
- fetchAttachmentBase64,
133
- fetchAttachmentBase64ForCell,
134
- fetchAttachmentBlob,
135
- fetchGristRow,
136
- fetchGristTableRows,
137
- fetchWithGristAuth,
138
- findRowIndexById,
139
- formatAccessInsufficientMessage,
140
- formatBoundaryUserMessage,
141
- formatColumnMappingAlertMessage,
142
- formatLinkStaleAlertMessage,
143
- formatMappingPendingAlertMessage,
144
- formatMappingUnreportedAlertMessage,
145
- formatSectionNotLinkedAlertMessage,
146
- formatSourceNotWiredAlertMessage,
147
- getAttachmentDownloadUrl,
148
- getAttachmentDownloadUrlForCell,
149
- getGristAccessToken,
150
- getGristSdkAlertDescriptors,
151
- getGristSdkAlertSeverity,
152
- getGristSdkAlertTitle,
153
45
  gristAddColumnAction,
154
46
  gristAddRecordAction,
155
47
  gristAddTableAction,
156
48
  gristAddVisibleColumnAction,
157
49
  gristAttachmentCellValue,
158
50
  gristAttachmentCellValues,
159
- gristBulkAddRecordAction,
160
- gristBulkRemoveRecordAction,
161
- gristBulkUpdateRecordAction,
162
- gristCellValueSchema,
163
- gristDuplicateTableAction,
164
51
  gristModifyColumnAction,
165
52
  gristRemoveColumnAction,
166
53
  gristRemoveRecordAction,
167
- gristRemoveTableAction,
168
54
  gristRenameColumnAction,
169
- gristRenameTableAction,
170
- gristReplaceTableDataAction,
171
- gristSafeRefListValueSchema,
172
- gristSafeRefValueSchema,
173
- gristSetDocumentInfoAction,
174
55
  gristUpdateRecordAction,
175
- inferDisplayHelpersByRef,
176
- inferGristFormulaKind,
177
- isAccessInsufficientError,
178
56
  isGristCellError,
179
- isGristNoiseColumn,
180
- isWidgetSectionNotLinked,
181
- loadColumnMetadataByTable,
182
- materializeGristRowsFromColumnar,
183
57
  mergeGristAttachmentCellValue,
184
58
  normalizeGristChoiceListEntries,
185
- normalizeReplicaDocumentInput,
186
- normalizeReplicaTableInput,
187
- orderedColumnIds,
188
- parseGristAttachmentUploadResponse,
189
- parseGristAttachmentUploadResponseIds,
190
- parseGristWidgetOptionsCell,
191
59
  resolveGristFormulaKind,
192
- rowAtIndex,
193
- safeParseGristTableData,
194
- safeParseGristValues,
195
- safeParseRowsToDisplayRows,
196
- serializeJsonFriendly,
197
- sortRowsByGristOrder,
198
60
  tableDataToRows,
199
- uploadGristAttachment,
200
61
  useGrist,
201
62
  useGristContext,
202
63
  useGristOptional,
203
64
  useGristSchema,
204
- useGristSdkAlertDescriptors,
205
- useGristSelection,
206
- useGristStatus,
207
- useGristTheme,
208
- useGristWidgetOptionsFromContext,
209
- useGristWrites,
210
- useWidgetMetadata,
211
- validateColumnMappings
65
+ useWidgetMetadata
212
66
  };
213
67
  //# sourceMappingURL=index.js.map