grist-widget-sdk 0.3.26 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # grist-widget-sdk
 
+## 0.4.0
+
+### Minor Changes
+
+- a257767: The emulator is a test harness only. Removed: `grist-widget-sdk/emulator/transports` (the iframe transport, `createIframeTransport`) and `grist-widget-sdk/emulator/devtools` (the inspector), which only the retired playground used; `createGristEmulator`'s `transport` option takes `{ kind: "inline", target? }` only. `renderWithGrist`, `smokeTestWidget` and `createGristEmulator` are unchanged. To see a widget run, use a real Grist: `pnpm demo`, or its demo page (`pnpm demo --save`).
+- 74395a7: **0.4.0: a synchronous runtime and a small public surface (breaking).**
+  
+  The connection to Grist is one synchronous `connect()` and one store read through `useSyncExternalStore`, instead of the handshake state machine (detection polling, a 30 s heartbeat, generations). `useGrist()` keeps its shape for what widgets use and re-renders less (a cursor move: 3 renders to 1). The root entry exports 29 runtime names instead of about 195; `grist-widget-sdk/advanced` is gone.
+  
+  Fixed on the way: `fetchSelectedTable()` returned rows while typed as columns (a widget passing it to `tableDataToRows()` got nothing; it now returns columns); `mode` stuck on `"new-row"` when the selection went away; records reused and mutated by the host no longer go unnoticed. The emulator now matches Grist on `setOptions` (replaces), the add-row (`onNewRecord` only), unmapped columns (`mappedRecord` is `null`) and access (it grants what the widget asks for unless a test sets `widgetInteraction.access_level`).
+  
+  What to replace, if a widget uses it (the six reference widgets need nothing):
+  
+  | Removed | Use instead |
+  | --- | --- |
+  | `useGristSelection()`, `useGristStatus()`, `useGristWrites()`, `useGristTheme()` | `useGrist()` |
+  | `grist-widget-sdk/advanced` (`useGristReady`, `useGristHandshake`, `useGristCapabilities`, `useGristRowsFromTable`, …), `GristHandshakeProvider` | `useGrist()` (`status`, `columnMappingStatus`), or `fetchTableRows` in an effect |
+  | `w.capabilities` | `w.status`, `w.columnMappingStatus.ok`, `w.isReady` |
+  | `w.getWidgetOptions()`, `w.getWidgetOption(key)` | `w.widgetOptions` |
+  | `w.setWidgetOption(key, value)` | `w.patchWidgetOptions({ [key]: value })` |
+  | `w.clearWidgetOptions()` | `w.setWidgetOptions({})` |
+  | `w.fetchRow(table, id)` | `w.fetchTableRows(table)` |
+  | `w.fetchSelectedRecord(id)` | `w.record`, or `w.fetchSelectedTable()` |
+  | `w.buildReplicaDocumentFromDocApi(...)`, `buildReplicaDocumentFromDocApi` | `useGristSchema()` |
+  | `w.getDocName()`, `w.configure()`, `w.refreshMappings()`, `w.refreshCurrentTable()`, `w.currentTableLoading` | — (`currentTableId` and `mappings` follow Grist) |
+  | `w.isNewRecord`, `w.recordsMappings`, `w.newRecordMappings` | `w.mode === "new-row"`, `w.mappings` |
+  | `w.widgetInteraction`, `w.readError`, `w.mapBackSkipped` | the alerts `mountGristWidget()` shows |
+  | `w.getAccessToken()`, `w.fetchAttachmentBase64()`, `getGristAccessToken`, `fetchWithGristAuth` | `w.fetchWithAuth()`, `w.fetchAttachmentBlob()` |
+  | `<GristBoundary gate widget bootingFallback …>` | `<GristBoundary>`: it gates on declared columns itself |
+  | alert and boundary helpers (`getGristSdkAlertDescriptors`, `deriveBoundaryView`, `format…AlertMessage`, …), `validateColumnMappings` | `mountGristWidget()` shows them; `w.columnMappingStatus` |
+  | replica builders and normalizers, value codecs beyond `decodeGristValue` / `encodeGristValue` / `isGristCellError`, `gristBulk*` / table / document action builders | write the user-action tuple; `useGristSchema()` |
+  | `GristReadyOptions.availabilityMaxAttempts`, `availabilityIntervalMs`, `logWhenNotEmbedded` | — (no polling) |
+- 673a02d: **Typed reads, with read-only access; no zod in a widget's bundle.**
+  
+  Each mapped cell is now checked against the type its column declares in `GRIST_OPTIONS.columns`: no schema to fetch, no full access. `mappedRecord` (and the new `mappedRecords`, every row of the section) holds the value each type promises (`Text` → string, `Numeric` → number, `Date` → `Date`, `Ref` → row id, `RefList` / `Attachments` → ids, `ChoiceList` → strings); a cell that doesn't match (text Grist couldn't parse, a formula error, a column whose type changed) is `null`, and listed in the new `cellIssues` (`{ rowId, column, message, value }`), which `mountGristWidget()` shows as a `cell-issues` alert. `GristMappedRow<typeof GRIST_OPTIONS>` types the mapped records from the declaration (declare it `as const satisfies UseGristOptions`). `UseGristOptions.schema` takes any Standard Schema (zod 4, valibot, arktype) for extra rules; the SDK depends on none. `checkGristCell(type, value)` checks a value read another way.
+  
+  Removed: `safeParseGristTableData`, `safeParseRowsToDisplayRows` and `fetchTableRows`'s `safeParse` option (the zod-based safe-parse), which put zod in every widget. A widget's template build goes from 129 KB to 94 KB of JavaScript, gzipped; CI now fails above 100 KB.
+  
+  What to change, if a widget relies on it (the six reference widgets need nothing): a `Ref` column's value in `mappedRecord` is now its row id (it was a `Reference` object), and a cell that doesn't match its declared type is `null` (it was the raw value); safe-parse users read `mappedRecords` / `cellIssues`, or call `checkGristCell` per cell.
+
+### Patch Changes
+
+- f4a467a: Routine dependency updates via Dependabot (PR #241). See the PR diff for the exact version bumps.
+- f5e04b4: `fetchWithGristAuth()` (and `w.fetchWithAuth()`) now refuses an absolute URL on another origin than the document's Grist instance, instead of sending the document's access token there. The token travels as the `auth` query parameter, so a URL taken from a cell or another input could hand it to any host. Relative paths and absolute URLs on the Grist instance work as before; for other hosts, use plain `fetch()`.
+
+## 0.3.27
+
+### Patch Changes
+
+- c5ea5c8: New in `grist-widget-sdk/emulator/testing`: `smokeTestWidget({ App, options })`, a widget's whole smoke test in one call. It mounts the widget the way `mountGristWidget()` does inside Grist, against an emulated document with one table holding a column per declared column and a row of sample values. Every column is mapped and the requested access granted, and the test waits until the widget renders past `GristBoundary`. It rejects with the widget's own error if it throws, or with what the page showed instead if it never gets there, and accepts a `document` and a `timeout`. It only reads `GRIST_OPTIONS`, so the test stays valid as the widget changes.
+  
+  Also new: `installJsdomStubs()`, inert `ResizeObserver` and `matchMedia` stand-ins for whichever jsdom lacks, for a widget's other tests or a Vitest setup file. `smokeTestWidget()` installs them itself.
+
 ## 0.3.26
 
 ### Patch Changes

package/README.md

@@ -147,7 +147,7 @@ Subpath exports:
 
 ## Replica document (`GristReplicaDocument`)
 
-One JSON shape is used for **`useGristSchema()`**, **`getDocumentJson` / `buildDocumentJson`**, playground **`*.grist.json`** fixtures, and **`createGristEmulator({ document })`**. Valid fixtures are checked with **`parseDocument`** (Zod).
+One JSON shape is used for **`useGristSchema()`**, **`getDocumentJson` / `buildDocumentJson`**, **`*.grist.json`** fixtures, and **`createGristEmulator({ document })`**. Valid fixtures are checked with **`parseDocument`** (Zod).
 
 ### Top-level fields