grist-widget-sdk 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # grist-widget-sdk
 
+## 0.5.1
+
+### Patch Changes
+
+- 10015f7: **`mountGristWidget(entry)` and `smokeTestWidget(entry)` read an entry module that also exports its component as `App`.** A widget whose `src/app/App.tsx` has `export function App()` next to `export default App` was taken for the older `{ App, options }` form: `mountGristWidget(entry)` (the 0.5 template's `src/main.tsx`) mounted it without its `GRIST_OPTIONS` (no declared columns, no access level), and `smokeTestWidget(entry)` threw. An entry module is now recognised by its default export.
+  
+  Existing widgets: nothing to do. A widget on `create-grist-widget` 0.5.0's template with a named `App` export gets its declaration back once this version is installed.
+
+## 0.5.0
+
+### Minor Changes
+
+- d3d9232: **`defineGristWidget()`: one declaration types, mounts and tests a widget.**
+  
+  ```ts
+  export const widget = defineGristWidget({
+    title: "Tasks",
+    requiredAccess: "full",
+    columns: [{ name: "Title", type: "Text" }, { name: "Done", type: "Bool" }],
+  })
+  const w = widget.useGrist()          // mappedRecord typed from the declaration: no generics, no `as const`
+  await w.updateRecord({ Done: true }) // the selected row, encoded for each declared type
+  ```
+  
+  - `defineGristWidget(definition)` keeps the column names and types literal (a `const` type parameter), so `widget.useGrist()` types `mappedRecord`, `mappedRecords`, `mapBack` and the writes from the declaration. `GristWidgetRow<typeof widget>` names the record type.
+  - `useGrist()` gains `updateRecord(patch)` / `updateRecord(rowId, patch)` and `addRecord(patch)`: `mapBack` + encoding + `table.update` / `table.create` in one call, under the declared names.
+  - `mountGristWidget(entry, { dev })` takes the widget's entry module (`import * as entry from "./app/App"`) and reads its exports: `default`, `widget` (or `GRIST_OPTIONS` and `WIDGET_METADATA`), and optionally `Alerts`, `LocalDevPage`, `ReleasePage`. A widget's customisations then live in its own file instead of `src/main.tsx`. The declaration's title and description set the page's title and meta tags. `mountGristWidget({ App, options, dev })` still works.
+  - `renderWithGrist(<App />, { widget, rows })` runs the widget as `mountGristWidget()` does inside Grist, against a table with a column per declared column, every one mapped, seeded with typed rows: no document or mapping setup in a test. `smokeTestWidget(entry)` takes the entry module as `mountGristWidget()` does (or `{ App, widget }`), so one smoke test fits a widget declared either way.
+  
+  Nothing changes for an existing widget: `GRIST_OPTIONS`, `useGrist<TRow, TMapped>()`, `mapBack` and `table.update` work as before.
+
+### Patch Changes
+
+- 734d307: **`pnpm dev` opens the widget in real Grist, in the browser, with no Docker.** The template ships its demo page (`public/demo/`, a document for its widget and the page that opens it in grist-static), and on the dev server `http://localhost:5173/demo/index.html` runs that Grist on the dev server's own widget: edits reload in place, writes land in the document. The SDK's local-dev page links to it (or says how to get it, `pnpm demo --save`, when the widget has no demo page yet). The scaffold puts the widget's title in the page.
+  
+  Existing widgets can do nothing: those with a demo page (`pnpm demo --save`) already get it on `pnpm dev` at `/demo/index.html`; the others get it once they run `pnpm demo --save` (Docker, once).
+- dfb2e66: **Writes are the mirror of typed reads.** `mapBack` now encodes each value for the type its column declares: a ChoiceList's `string[]`, a RefList's row ids or an Attachments list become `["L", ...]`, a `Date` becomes seconds, a `Reference` its row id. Before, writing back what `mappedRecord` gave stored a ChoiceList or RefList cell as an error (`["E", "KeyError"]`, checked in Grist 1.7.22), because Grist's plugin API writes values as given. `encodeGristCell(type, value)` is exported for writes that don't go through `mapBack`; a value already encoded passes through.
+  
+  The emulator now stores a bare list written to a list column as Grist does, an error cell reported in `cellIssues`, so `pnpm test` shows the mistake instead of hiding it.
+  
+  Overlapping writes count as one run: `actionStatus` stays `"running"` until the last one ends, then is `"error"` if any failed (the first write to end used to set it back to `"idle"`). A failed write nobody awaits no longer logs an unhandled rejection; the alert reports it, and the promise still rejects for whoever awaits it.
+  
+  What to change, if a widget relies on it: a widget that already encoded lists itself (`["L", ...]`, `encodeGristValue`, the attachment helpers) needs nothing. A test that wrote a bare array to a RefList through the emulator now gets an error cell: encode it, or go through `mapBack`.
+- ca3f010: `GristMappedRow` now types every declared column as its value or `null`, `Text` and `Bool` included (`Title: string | null`, not `string`). It promised a non-null value for those types while `mappedRecord` holds `null` for a cell that doesn't match its declared type, so a widget trusting the type could crash on a formula error. A widget that reads a `Text` or `Bool` column from a `GristMappedRow` may need a fallback (`row.Title ?? ""`) to compile.
+  
+  The package README, shown on npm, describes the 0.4.0 surface; it still listed `grist-widget-sdk/advanced`, the slice hooks and the emulator's iframe transport and devtools, all removed in 0.4.0.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -1,249 +1,120 @@
 # grist-widget-sdk
 
-React hooks and TypeScript utilities for building Grist widgets.
+React hooks for [Grist](https://www.getgrist.com) custom widgets: one
+`useGrist()` for the connection, the selected record and the section's
+records, column mapping, typed reads, writes, widget options and the
+document's REST API, plus an emulator to test a widget without Grist.
 
-## Why not use `grist` directly?
+Documentation: <https://gristwidgets.com/docs>. To start a widget, use the
+scaffold, which wires all of this up:
 
-Grist’s [`grist-plugin-api.js`](https://docs.getgrist.com/grist-plugin-api.js) exposes a global `grist` object. For React widgets, **`grist-widget-sdk`** replaces hand-rolled glue:
+```bash
+npm create grist-widget my-widget
+```
+
+## Why not `grist` directly?
 
 | Raw `grist` | SDK |
 | --- | --- |
-| `grist.ready` + `onRecord` callbacks | `<GristWidgetProvider>` + `useGrist()` with `mode` |
-| Wire-format dates/refs | Decoded values by default |
-| `mapColumnNames` / tuples for writes | `mappedRecord`, `mapBack`, `table.update` |
-| No test harness | `renderWithGrist` + emulator presets |
+| `grist.ready` and `onRecord` callbacks | `useGrist()`: `status`, `record`, `records`, `mode` |
+| Wire-format dates, refs and errors | Each mapped cell as its declared type (`mappedRecord`), mismatches in `cellIssues` |
+| `mapColumnNames`, tuples for writes | `mappedRecord`, `mapBack`, `table.update` |
+| No test harness | `renderWithGrist` with emulator presets |
 
 Full comparison: [Raw plugin API vs SDK](https://gristwidgets.com/docs/sdk/guide/raw-plugin-api-vs-sdk).
 
-## What This Package Provides
-
-- Main API via `grist-widget-sdk` (hooks, types, helpers)
-- `grist-widget-sdk/advanced` — lower-level hooks (`useGristReady`, `useGristHandshake`, …)
-- `grist-widget-sdk/emulator` subpath for emulator utilities
-- ESM + CJS + type declaration builds (`.d.ts`)
-
-## Installation
+## Install
 
 ```bash
 pnpm add grist-widget-sdk
 ```
 
-Required peer dependencies:
-
-- `react >= 18`
-- `react-dom >= 18`
-
-## Grist Runtime Script (Required)
-
-This package expects a global `grist` object at runtime.
-
-Load the official Grist plugin API script in your app shell/layout:
+Peer dependencies: `react` and `react-dom` 18 or later. The page must load
+Grist's plugin API, which defines the `grist` global:
 
 ```html
 <script src="https://docs.getgrist.com/grist-plugin-api.js"></script>
 ```
 
-## Quick Start Next.js (`app/layout.tsx`)
+## A widget
 
 ```tsx
-import Script from "next/script"
-import { GristBoundary, GristWidgetProvider } from "grist-widget-sdk"
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <body>
-        <Script src="https://docs.getgrist.com/grist-plugin-api.js" />
-        <GristWidgetProvider options={{ requiredAccess: "read table" }}>
-          <GristBoundary>
-            {children}
-          </GristBoundary>
-        </GristWidgetProvider>
-      </body>
-    </html>
-  )
+// src/app/App.tsx
+import { defineGristWidget } from "grist-widget-sdk"
+
+export const widget = defineGristWidget({
+  title: "Tasks",
+  requiredAccess: "full",
+  columns: [{ name: "Title", type: "Text" }, { name: "Done", type: "Bool" }],
+})
+
+export default function App() {
+  const w = widget.useGrist() // w.mappedRecord: { id; Title: string | null; Done: boolean | null } | null
+  if (w.mode !== "row" || !w.mappedRecord) return <p>Select a task.</p>
+  return <button onClick={() => w.updateRecord({ Done: true })}>{w.mappedRecord.Title}</button>
 }
 ```
 
-Then render widget content from your page, for example `app/page.tsx`:
-
 ```tsx
-import { useGrist } from "grist-widget-sdk"
-
-export default function Page() {
-  const w = useGrist()
-
-  if (w.status === "booting") return <p>Loading...</p>
-  if (w.mode === "empty") return <p>Select a row.</p>
-  if (w.mode === "new-row") return <p>New row flow</p>
+// src/main.tsx
+import { mountGristWidget } from "grist-widget-sdk/app"
+import * as entry from "./app/App"
 
-  return <p>Record id: {String(w.record?.id ?? "")}</p>
-}
+mountGristWidget(entry, { dev: import.meta.env.DEV })
 ```
 
-## Quick Start Vite (`src/main.tsx`)
-
-In `index.html`, load the script:
-
-```html
-<script src="https://docs.getgrist.com/grist-plugin-api.js"></script>
-```
-
-Then mount your widget root:
+The declaration types everything with no generics: the mapped records, and
+the writes (`updateRecord`, `addRecord`), which encode each value for its
+declared type. `mountGristWidget()` reads `App.tsx`'s exports: the widget,
+its declaration (for the access, the columns and the page title), and any
+page it replaces. Inside Grist it renders the widget in `GristWidgetProvider`
+and `GristBoundary` (the connecting, access and column-mapping screens), with
+the SDK's alerts, in Grist's light or dark theme.
+
+## Entry points
+
+- **`grist-widget-sdk`**: `defineGristWidget`, `useGrist`, `useGristContext`, `useGristOptional`,
+  `GristWidgetProvider`, `GristBoundary`, `useGristSchema`,
+  `useWidgetMetadata`, `checkGristCell`, `encodeGristCell`, the value codec, the attachment
+  helpers, the user-action builders for `applyActions`, and Grist's types.
+  [API reference](https://gristwidgets.com/docs/sdk/api).
+- **`grist-widget-sdk/app`**: `mountGristWidget`, `GristWidgetApp`,
+  `useTheme`, and the deploy-channel helpers the scaffold's pages use.
+  [Reference](https://gristwidgets.com/docs/sdk/api/app).
+- **`grist-widget-sdk/emulator`**: `createGristEmulator`, document
+  `presets`, `parseDocument`. [Reference](https://gristwidgets.com/docs/emulator/api).
+- **`grist-widget-sdk/emulator/testing`**: `renderWithGrist`,
+  `smokeTestWidget`, `installJsdomStubs`, the matchers (`actionsOf`,
+  `eventsOf`, `waitForEvent`), `presets`, and the usual
+  `@testing-library/react` helpers. [Testing](https://gristwidgets.com/docs/emulator/testing).
+- **`grist-widget-sdk/tsconfig/app.json`**, **`/tsconfig/node.json`**: the
+  compiler settings a scaffolded widget extends.
+
+ESM and CJS builds, with type declarations.
+
+## Testing a widget
 
 ```tsx
-import { StrictMode } from "react"
-import { createRoot } from "react-dom/client"
-import { GristBoundary, GristWidgetProvider, useGrist } from "grist-widget-sdk"
-
-function WidgetContent() {
-  const w = useGrist()
-
-  if (w.status === "booting") return <p>Loading...</p>
-  if (w.mode === "empty") return <p>Select a row.</p>
-  if (w.mode === "new-row") return <p>New row flow</p>
-
-  return <p>Record id: {String(w.record?.id ?? "")}</p>
-}
-
-function App() {
-  return (
-    <GristWidgetProvider options={{ requiredAccess: "read table" }}>
-      <GristBoundary>
-        <WidgetContent />
-      </GristBoundary>
-    </GristWidgetProvider>
-  )
-}
-
-createRoot(document.getElementById("root")!).render(
-  <StrictMode>
-    <App />
-  </StrictMode>
-)
+import { fireEvent, renderWithGrist, screen, waitFor } from "grist-widget-sdk/emulator/testing"
+import App, { widget } from "./App"
+
+it("marks the task done", async () => {
+  const { emulator } = renderWithGrist(<App />, { widget, rows: [{ Title: "Ship", Done: false }] })
+  fireEvent.click(await screen.findByRole("button", { name: "Ship" }))
+  await waitFor(() => expect(emulator.state.tables.get("Table1")!.rows[0]).toMatchObject({ Done: true }))
+})
 ```
 
-## Exports
-
-Main entrypoint:
-
-- `grist-widget-sdk` — production surface:
-  - Components: `GristWidgetProvider`, `GristBoundary`, `useGristContext`, `useGristOptional`
-  - Primary hook: `useGrist` (includes `capabilities` — `canRender`, `canWriteRecords`, …)
-  - Slice hooks: `useGristStatus`, `useGristSelection`, `useGristWrites`, `useGristTheme`
-  - Schema hook: `useGristSchema`
-  - Helpers: action builders, value codec, safe parsing, replica builders,
-    REST auth, attachments, column-mapping validation, alerts.
-
-Subpath exports:
-
-- `grist-widget-sdk/advanced` — low-level / mid-level hooks for power users
-  (`useGristReady`, `useGristAvailability`, `useGristRecord`, `useGristRecords`,
-  `useGristActions`, `useGristTableOps`, `useGristMappedRecord`,
-  `useGristRowsFromTable`, `useGristAccessToken`, `useGristSection`,
-  `useGristWidgetOptions`, `useGristTable`).
-- `grist-widget-sdk/emulator` — `createGristEmulator`, `parseDocument`,
-  `safeParseDocument`, `presets`, emulator types.
-
-## Replica document (`GristReplicaDocument`)
+The emulator runs in the test process and stands in for `window.grist`. It
+is a test harness, not a preview: to see a widget run, use a real Grist
+(`pnpm demo` in a scaffolded widget, or its demo page).
 
-One JSON shape is used for **`useGristSchema()`**, **`getDocumentJson` / `buildDocumentJson`**, **`*.grist.json`** fixtures, and **`createGristEmulator({ document })`**. Valid fixtures are checked with **`parseDocument`** (Zod).
+## Developing this package
 
-### Top-level fields
-
-| Field | Required | Notes |
-| --- | --- | --- |
-| `generatedAt` | yes | ISO 8601 string |
-| `tables` | yes | `Record<tableId, GristReplicaTable>` — keys align with `docApi.listTables()` / `fetchTable(tableId)` |
-| `source` | no | Provenance (e.g. pass `useGristSchema({ source })` or `buildReplicaDocumentFromDocApi(docApi, { source })`); hosts may log it |
-| `docName`, `mode`, `selection`, `widgetOptions`, `widgetInteraction`, `configuration`, `accessToken` | no | Same semantics as in types |
-
-Optional **`mode`**: `"schema-only"` \| `"schema+samples"` \| `"schema+data"` (hint only). At boundaries, use **`normalizeReplicaTableInput`** / **`normalizeReplicaDocumentInput`** so missing **`rows`** behaves like **`[]`**.
-
-### Tables and rows
-
-- **`GristReplicaTable`**: optional `label`, `columns`, `rows`, `rowCount`, `dataOmitted`, etc.
-- Row bodies are **`GristReplicaRow`** (`{ id: number, … }`), **not** columnar `fetchTable` wire format. Use **`buildReplicaDocumentFromDocApi`** or **`decodeColumnarToReplicaRows`** to build rows from `docApi.fetchTable`.
-
-### Building and serializing
-
-- Prefer **`buildReplicaDocumentFromDocApi(docApi, { includeRows: false \| "samples" \| "full", sampleRowLimit, source, includeSystemTableData })`**, or **`w.buildReplicaDocumentFromDocApi(...)`** from **`useGrist()`**.
-- **`getDocumentJson` / `buildDocumentJson`** accept **`includeRows`**: `"none"` \| `"samples"` \| `"full"` (plus optional **`sampleRowLimit`**, **`space`**).
-
-### Emulator
-
-Only a full **`GristReplicaDocument`** is accepted: **`createGristEmulator({ document })`** and **`parseDocument`**. There is no legacy coercion or alternate “emulator input” type; assemble the object (or load JSON), then **`parseDocument`** if you need validation.
-
-The canonical design document for this shape is [Replica document](https://gristwidgets.com/docs/sdk/design/replica-document).
-- `grist-widget-sdk/emulator/transports` — low-level `iframe` and `inline` transports if you need to wire your own host.
-- `grist-widget-sdk/emulator/devtools` — `<EmulatorInspector />` React component (table editor + event timeline + options).
-- `grist-widget-sdk/emulator/testing` — `renderWithGrist(...)`, vitest
-  matchers (`actionsOf`, `eventsOf`, `waitForEvent`), document `presets`,
-  and the most-used `@testing-library/react` primitives (`screen`,
-  `fireEvent`, `waitFor`, `act`, `cleanup`, `within`, `render`) so a typical
-  test file only needs one import line.
-
-## Emulator (SOTA)
-
-The emulator is the single source of truth for three use-cases:
-
-1. **Demoing widgets** — production-fidelity by loading the *real*
-   `grist-plugin-api.js` inside an iframe and speaking `grain-rpc` over
-   `postMessage`:
-
-   ```tsx
-   import { createGristEmulator, presets } from "grist-widget-sdk/emulator"
-   import { EmulatorInspector } from "grist-widget-sdk/emulator/devtools"
-
-   const iframe = document.querySelector("iframe")!
-   const emulator = createGristEmulator({
-     document: presets.todoList(),
-     transport: { kind: "iframe", iframe },
-   })
-   ```
-
-2. **Robust SDK testing** — `renderWithGrist` synthesises `window.grist`
-   in-process, so every `useGrist` test goes through the *exact* same code
-   path without ceremony:
-
-   ```ts
-   import { renderWithGrist } from "grist-widget-sdk/emulator/testing"
-
-   const { emulator, getByText } = renderWithGrist(<MyWidget />, {
-     emulator: { document: presets.contacts() },
-   })
-   emulator.mutate.addRow("Contacts", { firstName: "Grace", lastName: "Hopper" })
-   ```
-
-3. **Live IDE preview** — same `inline` transport, mounted next to the
-   widget to give a Storybook-grade dev loop.
-
-## Local Development
-
-From the workspace root:
+From the monorepo root:
 
 ```bash
 pnpm --filter grist-widget-sdk build
-pnpm --filter grist-widget-sdk dev
 pnpm --filter grist-widget-sdk test
-```
-
-## Pre-Commit / Pre-Publish Checks
-
-```bash
-pnpm --filter grist-widget-sdk build
 pnpm --filter grist-widget-sdk exec tsc --noEmit
-pnpm --filter grist-widget-sdk exec vitest run
-pnpm dlx @arethetypeswrong/cli -P packages/core
 ```
-
-If no tests exist yet:
-
-```bash
-pnpm --filter grist-widget-sdk exec vitest run --passWithNoTests
-```
-
-## Notes
-
-- This package targets pure TypeScript/React usage (no Next.js dependency required).
-- ATTW may report a `node10` warning for the `grist-widget-sdk/emulator` subpath. This is expected for modern `exports`-based packages and is non-blocking for Node 16+ and modern bundlers.