grist-widget-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Arthur Blanchon
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# grist-widget-sdk
+
+React hooks and TypeScript utilities for building Grist widgets.
+
+## Why not use `grist` directly?
+
+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:
+
+| 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 |
+
+Full comparison: [Raw plugin API vs SDK](https://github.com/ArthurBlanchon/grist-widget-sdk/blob/main/apps/docs/guide/raw-plugin-api-vs-sdk.md) (also in the published docs site under **Guide → Raw 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
+
+```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:
+
+```html
+<script src="https://docs.getgrist.com/grist-plugin-api.js"></script>
+```
+
+## Quick Start Next.js (`app/layout.tsx`)
+
+```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>
+  )
+}
+```
+
+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>
+
+  return <p>Record id: {String(w.record?.id ?? "")}</p>
+}
+```
+
+## 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:
+
+```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>
+)
+```
+
+## 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`)
+
+One JSON shape is used for **`useGristSchema()`**, **`getDocumentJson` / `buildDocumentJson`**, playground **`*.grist.json`** fixtures, and **`createGristEmulator({ document })`**. Valid fixtures are checked with **`parseDocument`** (Zod).
+
+### 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 lives at **`apps/docs/design/replica-document.md`**.
+- `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:
+
+```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.