grist-widget-sdk 0.4.0 → 0.5.0

package/dist/{use-grist-BK0eke9K.d.cts → define-widget-B1FIvI-h.d.cts}

@@ -1,100 +1,5 @@
 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';
 
-type ValidateColumnMappingsResult = {
-    ok: boolean;
-    /**
-     * `true` while the host has not yet reported column mappings (e.g. between
-     * `grist.ready()` resolving and the first `onRecord` / `onRecords` callback,
-     * or before `sectionApi.mappings()` returns). Callers should not gate UI or
-     * emit mapping alerts while pending.
-     */
-    pending?: boolean;
-    /** Logical names of required columns the user has not yet mapped. */
-    missing: string[];
-    /** Logical names of `allowMultiple` columns mapped to an empty list. */
-    emptyMultiples: string[];
-};
-
-type GristNoiseColumnsOptions = {
-    excludeId?: boolean;
-    excludeGristHelpers?: boolean;
-    excludeLoggingColumns?: boolean;
-    /**
-     * When `true`, treat Grist's `manualSort` column as noise (omit from filtered replicas).
-     * Default `false` — `manualSort` is kept unless you opt in.
-     */
-    excludeManualSort?: boolean;
-};
-
-type GristFetchedAttachmentBlob = {
-    blob: Blob;
-    contentType: string;
-};
-/**
- * All attachment ids found in a Grist attachment cell value (ordered, deduped).
- * Attachment columns are usually an **array** of file refs; a single id or one JSON object is also supported.
- */
-declare function extractGristAttachmentIdsFromCell(value: unknown): string[];
-/** First attachment id in the cell, if any (see {@link extractGristAttachmentIdsFromCell}). */
-declare function extractGristAttachmentId(value: unknown): string | undefined;
-
-type GristEncodedAttachmentList = ["L", ...(number | string)[]];
-type GristAttachmentUploadResult = {
-    /** All attachment ids returned by `POST /attachments`. */
-    ids: string[];
-    /** First id in `ids` (convenience for single-file uploads). */
-    firstId: string;
-};
-/** Wire value for an Attachments cell (Grist list encoding). */
-declare function gristAttachmentCellValues(attachmentIds: (string | number)[]): GristEncodedAttachmentList;
-/** Wire value for a single-file Attachments cell. */
-declare function gristAttachmentCellValue(attachmentId: string | number): GristEncodedAttachmentList;
-/**
- * Merge new attachment ids into an existing Attachments cell value (deduped, order preserved).
- */
-declare function mergeGristAttachmentCellValue(existingCell: unknown, newIds: (string | number)[]): GristEncodedAttachmentList;
-
-/** Column-oriented table payload (`fetchTable`, `fetchSelectedTable`): `{ id: [...], Name: [...] }`. */
-type GristColumnarTable = Record<string, unknown[]>;
-type GristTableRowsOrder = "none" | "id" | "grist";
-type FetchGristTableRowsOptions = {
-    /** Column metadata, to decode each cell (except `id`) with `decodeGristValue`. */
-    columns?: Record<string, GristReplicaColumn>;
-    /**
-     * Row order:
-     * - `grist` (default): `manualSort` ascending when present, then `id`.
-     * - `id`: numeric `id` ascending.
-     * - `none`: as `fetchTable` returned them.
-     */
-    order?: GristTableRowsOrder;
-};
-/** Turn `fetchTable` output into row objects (order follows the `id` column). */
-declare function tableDataToRows<T = Record<string, unknown>>(data: GristColumnarTable): GristRowRecord<T>[];
-
-/**
- * Grist `docApi.applyUserActions` payloads are arrays of user-action tuples.
- * @see https://support.getgrist.com/code/interfaces/grist_plugin_api.GristDocAPI/#applyuseractions
- */
-type GristUserActionTuple = unknown[];
-/** `["UpdateRecord", tableId, rowId, { col: value, ... }]` */
-declare function gristUpdateRecordAction(tableId: string, rowId: number, patch: Record<string, unknown>): GristUserActionTuple;
-/** `["AddRecord", tableId, null, { col: value, ... }]` */
-declare function gristAddRecordAction(tableId: string, values: Record<string, unknown>): GristUserActionTuple;
-/** `["RemoveRecord", tableId, rowId]` */
-declare function gristRemoveRecordAction(tableId: string, rowId: number): GristUserActionTuple;
-/** `["AddColumn", tableId, colId, colInfo]` — `colInfo` shape depends on Grist version / column type. */
-declare function gristAddColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
-/** `["AddVisibleColumn", tableId, colId, colInfo]` — like `AddColumn` but also adds the column to the current view section. */
-declare function gristAddVisibleColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
-/** `["RenameColumn", tableId, colId, newColId]` */
-declare function gristRenameColumnAction(tableId: string, colId: string, newColId: string): GristUserActionTuple;
-/** `["ModifyColumn", tableId, colId, colInfo]` */
-declare function gristModifyColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
-/** `["RemoveColumn", tableId, colId]` */
-declare function gristRemoveColumnAction(tableId: string, colId: string): GristUserActionTuple;
-/** `["AddTable", tableId, tableInfo]` */
-declare function gristAddTableAction(tableId: string, tableInfo: Record<string, unknown>): GristUserActionTuple;
-
 /**
  * Typed reads, with read-only access: each mapped cell checked against the
  * type its column declares in `GRIST_OPTIONS.columns`.
@@ -125,12 +30,20 @@ type Check = {
     ok: false;
     message: string;
 };
+declare function checkGristCell(type: string | undefined, value: unknown): Check;
 /**
- * `value` as its declared `type` promises ("Numeric", "Ref:Tasks",
- * "Text,Ref"…): a match of any listed type, or a failure that says why.
- * Without a type (or "Any"), the value as it is.
+ * A value as Grist stores it in a column of the declared `type`: the
+ * reverse of what typed reads give. Lists become `["L", ...]` (a RefList's
+ * `Reference` items become their row ids), a `Date` for a Date or DateTime
+ * column becomes seconds since the epoch, a `Reference` for a Ref column its
+ * row id. A list already encoded (`["L", ...]`, as the attachment helpers
+ * return it) and every other value pass through, so it is safe to call twice.
+ *
+ * Grist's plugin API writes values as given: a bare array written to a
+ * ChoiceList or RefList column is stored as an error cell. Checked in
+ * Grist 1.7.22.
  */
-declare function checkGristCell(type: string | undefined, value: unknown): Check;
+declare function encodeGristCell(type: string | undefined, value: unknown): unknown;
 /** Minimal Standard Schema (https://standardschema.dev): zod 4, valibot, arktype implement it. */
 type StandardSchema<T = unknown> = {
     readonly "~standard": {
@@ -154,9 +67,9 @@ type CellOf<T extends string> = T extends `${infer A},${infer Rest}` ? CellOf<A>
 type ColumnValue<C> = C extends {
     type: infer T extends string;
     allowMultiple: true;
-} ? CellOf<T>[] : C extends {
+} ? (CellOf<T> | null)[] : C extends {
     type: infer T extends string;
-} ? CellOf<T> : C extends {
+} ? CellOf<T> | null : C extends {
     allowMultiple: true;
 } ? unknown[] : unknown;
 type RequiredName<C> = C extends {
@@ -196,6 +109,101 @@ type GristMappedRow<O extends {
     [N in OptionalName<C>]?: ColumnValue<ByName<C, N>>;
 } : Record<string, unknown>;
 
+type ValidateColumnMappingsResult = {
+    ok: boolean;
+    /**
+     * `true` while the host has not yet reported column mappings (e.g. between
+     * `grist.ready()` resolving and the first `onRecord` / `onRecords` callback,
+     * or before `sectionApi.mappings()` returns). Callers should not gate UI or
+     * emit mapping alerts while pending.
+     */
+    pending?: boolean;
+    /** Logical names of required columns the user has not yet mapped. */
+    missing: string[];
+    /** Logical names of `allowMultiple` columns mapped to an empty list. */
+    emptyMultiples: string[];
+};
+
+type GristNoiseColumnsOptions = {
+    excludeId?: boolean;
+    excludeGristHelpers?: boolean;
+    excludeLoggingColumns?: boolean;
+    /**
+     * When `true`, treat Grist's `manualSort` column as noise (omit from filtered replicas).
+     * Default `false` — `manualSort` is kept unless you opt in.
+     */
+    excludeManualSort?: boolean;
+};
+
+type GristFetchedAttachmentBlob = {
+    blob: Blob;
+    contentType: string;
+};
+/**
+ * All attachment ids found in a Grist attachment cell value (ordered, deduped).
+ * Attachment columns are usually an **array** of file refs; a single id or one JSON object is also supported.
+ */
+declare function extractGristAttachmentIdsFromCell(value: unknown): string[];
+/** First attachment id in the cell, if any (see {@link extractGristAttachmentIdsFromCell}). */
+declare function extractGristAttachmentId(value: unknown): string | undefined;
+
+type GristEncodedAttachmentList = ["L", ...(number | string)[]];
+type GristAttachmentUploadResult = {
+    /** All attachment ids returned by `POST /attachments`. */
+    ids: string[];
+    /** First id in `ids` (convenience for single-file uploads). */
+    firstId: string;
+};
+/** Wire value for an Attachments cell (Grist list encoding). */
+declare function gristAttachmentCellValues(attachmentIds: (string | number)[]): GristEncodedAttachmentList;
+/** Wire value for a single-file Attachments cell. */
+declare function gristAttachmentCellValue(attachmentId: string | number): GristEncodedAttachmentList;
+/**
+ * Merge new attachment ids into an existing Attachments cell value (deduped, order preserved).
+ */
+declare function mergeGristAttachmentCellValue(existingCell: unknown, newIds: (string | number)[]): GristEncodedAttachmentList;
+
+/** Column-oriented table payload (`fetchTable`, `fetchSelectedTable`): `{ id: [...], Name: [...] }`. */
+type GristColumnarTable = Record<string, unknown[]>;
+type GristTableRowsOrder = "none" | "id" | "grist";
+type FetchGristTableRowsOptions = {
+    /** Column metadata, to decode each cell (except `id`) with `decodeGristValue`. */
+    columns?: Record<string, GristReplicaColumn>;
+    /**
+     * Row order:
+     * - `grist` (default): `manualSort` ascending when present, then `id`.
+     * - `id`: numeric `id` ascending.
+     * - `none`: as `fetchTable` returned them.
+     */
+    order?: GristTableRowsOrder;
+};
+/** Turn `fetchTable` output into row objects (order follows the `id` column). */
+declare function tableDataToRows<T = Record<string, unknown>>(data: GristColumnarTable): GristRowRecord<T>[];
+
+/**
+ * Grist `docApi.applyUserActions` payloads are arrays of user-action tuples.
+ * @see https://support.getgrist.com/code/interfaces/grist_plugin_api.GristDocAPI/#applyuseractions
+ */
+type GristUserActionTuple = unknown[];
+/** `["UpdateRecord", tableId, rowId, { col: value, ... }]` */
+declare function gristUpdateRecordAction(tableId: string, rowId: number, patch: Record<string, unknown>): GristUserActionTuple;
+/** `["AddRecord", tableId, null, { col: value, ... }]` */
+declare function gristAddRecordAction(tableId: string, values: Record<string, unknown>): GristUserActionTuple;
+/** `["RemoveRecord", tableId, rowId]` */
+declare function gristRemoveRecordAction(tableId: string, rowId: number): GristUserActionTuple;
+/** `["AddColumn", tableId, colId, colInfo]` — `colInfo` shape depends on Grist version / column type. */
+declare function gristAddColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
+/** `["AddVisibleColumn", tableId, colId, colInfo]` — like `AddColumn` but also adds the column to the current view section. */
+declare function gristAddVisibleColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
+/** `["RenameColumn", tableId, colId, newColId]` */
+declare function gristRenameColumnAction(tableId: string, colId: string, newColId: string): GristUserActionTuple;
+/** `["ModifyColumn", tableId, colId, colInfo]` */
+declare function gristModifyColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
+/** `["RemoveColumn", tableId, colId]` */
+declare function gristRemoveColumnAction(tableId: string, colId: string): GristUserActionTuple;
+/** `["AddTable", tableId, tableInfo]` */
+declare function gristAddTableAction(tableId: string, tableInfo: Record<string, unknown>): GristUserActionTuple;
+
 /**
  * The alerts `mountGristWidget()` shows above a running widget: what needs the
  * user's attention in Grist (column mapping, access, a failed write, an
@@ -293,6 +301,8 @@ type GristWidgetStatus = "booting" | "ready" | "unavailable" | "error";
 
 /** What the widget asks Grist for: access, columns to map, and the alerts it doesn't want. */
 type UseGristOptions = GristRuntimeOptions;
+/** A write under declared names: any of the mapped record's fields but its `id`. */
+type GristRecordPatch<TMapped> = Partial<Omit<TMapped, "id">>;
 /** Derived from the selection: no row, a row, or the add-row placeholder. */
 type GristWidgetMode = "empty" | "row" | "new-row";
 /**
@@ -331,8 +341,22 @@ type UseGristResult<TRow = Record<string, unknown>, TMapped = Record<string, unk
     mode: GristWidgetMode;
     /** The Grist column id mapped to a declared name, or the name itself. */
     resolveMappedColumnId: (name: string) => string;
-    /** A patch under declared names, as real column ids for a write (multi-column mappings are skipped). */
+    /**
+     * A patch under declared names, as real column ids for a write, each value
+     * encoded for its declared type (multi-column mappings are skipped).
+     */
     mapBack: (patch: Partial<TMapped>) => Record<string, unknown>;
+    /**
+     * Writes a patch under declared names to the selected row (or to `rowId`),
+     * encoded for each declared type: `mapBack` + `table.update` in one call.
+     * Rejects when no row is selected.
+     */
+    updateRecord: {
+        (patch: GristRecordPatch<TMapped>): Promise<void>;
+        (rowId: number, patch: GristRecordPatch<TMapped>): Promise<void>;
+    };
+    /** Adds a row to the section's table from a patch under declared names; resolves to its row id. */
+    addRecord: (patch: GristRecordPatch<TMapped>) => Promise<number>;
     /** The section's table id. */
     currentTableId: string | null;
     /** Any table as rows (full access). */
@@ -354,5 +378,56 @@ declare function useGristOptional<TRow = Record<string, unknown>, TMapped = Reco
 /** `useGrist()` inside `<GristWidgetProvider>`; throws outside one. */
 declare function useGristContext<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped>;
 
-export { gristRenameColumnAction as A, gristUpdateRecordAction as B, mergeGristAttachmentCellValue as C, tableDataToRows as D, useGrist as E, useGristContext as F, useGristOptional as H, checkGristCell as o, extractGristAttachmentId as p, extractGristAttachmentIdsFromCell as q, gristAddColumnAction as r, gristAddRecordAction as s, gristAddTableAction as t, gristAddVisibleColumnAction as u, gristAttachmentCellValue as v, gristAttachmentCellValues as w, gristModifyColumnAction as x, gristRemoveColumnAction as y, gristRemoveRecordAction as z };
-export type { GristNoiseColumnsOptions as G, ListColumnsOptions as L, StandardSchema as S, UseGristOptions as U, ValidateColumnMappingsResult as V, GristAttachmentUploadResult as a, GristCellIssue as b, GristColumnInfo as c, GristColumnarTable as d, GristFetchedAttachmentBlob as e, GristMappedRow as f, GristSdkAlertKind as g, GristTheme as h, GristUserActionTuple as i, GristWidgetActionStatus as j, GristWidgetMode as k, GristWidgetStatus as l, ListTablesOptions as m, UseGristResult as n };
+/**
+ * `defineGristWidget()`: a widget's whole declaration in one typed value.
+ * Everything else reads it: `widget.useGrist()` types the mapped records and
+ * the writes from it, `mountGristWidget()` takes the access level, the
+ * columns and the title from it, and the tests map its columns.
+ *
+ * ```ts
+ * export const widget = defineGristWidget({
+ *   title: "Tasks",
+ *   requiredAccess: "full",
+ *   columns: [{ name: "Title", type: "Text" }, { name: "Done", type: "Bool" }],
+ * })
+ *
+ * const w = widget.useGrist()   // w.mappedRecord: { id; Title: string | null; Done: boolean | null } | null
+ * await w.updateRecord({ Done: true })
+ * ```
+ */
+
+/** What a widget declares: `UseGristOptions`, plus its title and description. */
+type GristWidgetDefinition = UseGristOptions & {
+    /** The widget's name: the page's title, and its manifest's. */
+    title?: string;
+    /** One sentence: the page's description, and its manifest's. */
+    description?: string;
+};
+/** The widget's mapped record type, from its declaration. */
+type GristWidgetRow<W> = W extends GristWidget<infer D> ? GristMappedRow<D> : never;
+/** A declared widget. Pass it to `mountGristWidget()` (as `widget`, exported from `src/app/App.tsx`). */
+type GristWidget<D extends GristWidgetDefinition = GristWidgetDefinition> = {
+    /** The declaration, as written. */
+    readonly definition: D;
+    /** What the widget asks Grist for: the declaration without its title and description. */
+    readonly options: UseGristOptions;
+    readonly metadata: {
+        title?: string;
+        description?: string;
+    };
+    /**
+     * `useGrist()`, typed from the declaration: `mappedRecord`, `mappedRecords`,
+     * `mapBack`, `updateRecord` and `addRecord` use the declared names and the
+     * value each declared type gives. A hook: call it in a component.
+     */
+    useGrist: () => UseGristResult<GristRowRecord, GristMappedRow<D>>;
+};
+/**
+ * Declares a widget. The `const` type parameter keeps the column names and
+ * types literal, so the mapped record is typed with no annotation, no
+ * `as const` and no generics.
+ */
+declare function defineGristWidget<const D extends GristWidgetDefinition>(definition: D): GristWidget<D>;
+
+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 };
+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 };

package/dist/{use-grist-C5DMZ3wU.d.ts → define-widget-B9gEtJP0.d.ts}

@@ -1,100 +1,5 @@
 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.js';
 
-type ValidateColumnMappingsResult = {
-    ok: boolean;
-    /**
-     * `true` while the host has not yet reported column mappings (e.g. between
-     * `grist.ready()` resolving and the first `onRecord` / `onRecords` callback,
-     * or before `sectionApi.mappings()` returns). Callers should not gate UI or
-     * emit mapping alerts while pending.
-     */
-    pending?: boolean;
-    /** Logical names of required columns the user has not yet mapped. */
-    missing: string[];
-    /** Logical names of `allowMultiple` columns mapped to an empty list. */
-    emptyMultiples: string[];
-};
-
-type GristNoiseColumnsOptions = {
-    excludeId?: boolean;
-    excludeGristHelpers?: boolean;
-    excludeLoggingColumns?: boolean;
-    /**
-     * When `true`, treat Grist's `manualSort` column as noise (omit from filtered replicas).
-     * Default `false` — `manualSort` is kept unless you opt in.
-     */
-    excludeManualSort?: boolean;
-};
-
-type GristFetchedAttachmentBlob = {
-    blob: Blob;
-    contentType: string;
-};
-/**
- * All attachment ids found in a Grist attachment cell value (ordered, deduped).
- * Attachment columns are usually an **array** of file refs; a single id or one JSON object is also supported.
- */
-declare function extractGristAttachmentIdsFromCell(value: unknown): string[];
-/** First attachment id in the cell, if any (see {@link extractGristAttachmentIdsFromCell}). */
-declare function extractGristAttachmentId(value: unknown): string | undefined;
-
-type GristEncodedAttachmentList = ["L", ...(number | string)[]];
-type GristAttachmentUploadResult = {
-    /** All attachment ids returned by `POST /attachments`. */
-    ids: string[];
-    /** First id in `ids` (convenience for single-file uploads). */
-    firstId: string;
-};
-/** Wire value for an Attachments cell (Grist list encoding). */
-declare function gristAttachmentCellValues(attachmentIds: (string | number)[]): GristEncodedAttachmentList;
-/** Wire value for a single-file Attachments cell. */
-declare function gristAttachmentCellValue(attachmentId: string | number): GristEncodedAttachmentList;
-/**
- * Merge new attachment ids into an existing Attachments cell value (deduped, order preserved).
- */
-declare function mergeGristAttachmentCellValue(existingCell: unknown, newIds: (string | number)[]): GristEncodedAttachmentList;
-
-/** Column-oriented table payload (`fetchTable`, `fetchSelectedTable`): `{ id: [...], Name: [...] }`. */
-type GristColumnarTable = Record<string, unknown[]>;
-type GristTableRowsOrder = "none" | "id" | "grist";
-type FetchGristTableRowsOptions = {
-    /** Column metadata, to decode each cell (except `id`) with `decodeGristValue`. */
-    columns?: Record<string, GristReplicaColumn>;
-    /**
-     * Row order:
-     * - `grist` (default): `manualSort` ascending when present, then `id`.
-     * - `id`: numeric `id` ascending.
-     * - `none`: as `fetchTable` returned them.
-     */
-    order?: GristTableRowsOrder;
-};
-/** Turn `fetchTable` output into row objects (order follows the `id` column). */
-declare function tableDataToRows<T = Record<string, unknown>>(data: GristColumnarTable): GristRowRecord<T>[];
-
-/**
- * Grist `docApi.applyUserActions` payloads are arrays of user-action tuples.
- * @see https://support.getgrist.com/code/interfaces/grist_plugin_api.GristDocAPI/#applyuseractions
- */
-type GristUserActionTuple = unknown[];
-/** `["UpdateRecord", tableId, rowId, { col: value, ... }]` */
-declare function gristUpdateRecordAction(tableId: string, rowId: number, patch: Record<string, unknown>): GristUserActionTuple;
-/** `["AddRecord", tableId, null, { col: value, ... }]` */
-declare function gristAddRecordAction(tableId: string, values: Record<string, unknown>): GristUserActionTuple;
-/** `["RemoveRecord", tableId, rowId]` */
-declare function gristRemoveRecordAction(tableId: string, rowId: number): GristUserActionTuple;
-/** `["AddColumn", tableId, colId, colInfo]` — `colInfo` shape depends on Grist version / column type. */
-declare function gristAddColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
-/** `["AddVisibleColumn", tableId, colId, colInfo]` — like `AddColumn` but also adds the column to the current view section. */
-declare function gristAddVisibleColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
-/** `["RenameColumn", tableId, colId, newColId]` */
-declare function gristRenameColumnAction(tableId: string, colId: string, newColId: string): GristUserActionTuple;
-/** `["ModifyColumn", tableId, colId, colInfo]` */
-declare function gristModifyColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
-/** `["RemoveColumn", tableId, colId]` */
-declare function gristRemoveColumnAction(tableId: string, colId: string): GristUserActionTuple;
-/** `["AddTable", tableId, tableInfo]` */
-declare function gristAddTableAction(tableId: string, tableInfo: Record<string, unknown>): GristUserActionTuple;
-
 /**
  * Typed reads, with read-only access: each mapped cell checked against the
  * type its column declares in `GRIST_OPTIONS.columns`.
@@ -125,12 +30,20 @@ type Check = {
     ok: false;
     message: string;
 };
+declare function checkGristCell(type: string | undefined, value: unknown): Check;
 /**
- * `value` as its declared `type` promises ("Numeric", "Ref:Tasks",
- * "Text,Ref"…): a match of any listed type, or a failure that says why.
- * Without a type (or "Any"), the value as it is.
+ * A value as Grist stores it in a column of the declared `type`: the
+ * reverse of what typed reads give. Lists become `["L", ...]` (a RefList's
+ * `Reference` items become their row ids), a `Date` for a Date or DateTime
+ * column becomes seconds since the epoch, a `Reference` for a Ref column its
+ * row id. A list already encoded (`["L", ...]`, as the attachment helpers
+ * return it) and every other value pass through, so it is safe to call twice.
+ *
+ * Grist's plugin API writes values as given: a bare array written to a
+ * ChoiceList or RefList column is stored as an error cell. Checked in
+ * Grist 1.7.22.
  */
-declare function checkGristCell(type: string | undefined, value: unknown): Check;
+declare function encodeGristCell(type: string | undefined, value: unknown): unknown;
 /** Minimal Standard Schema (https://standardschema.dev): zod 4, valibot, arktype implement it. */
 type StandardSchema<T = unknown> = {
     readonly "~standard": {
@@ -154,9 +67,9 @@ type CellOf<T extends string> = T extends `${infer A},${infer Rest}` ? CellOf<A>
 type ColumnValue<C> = C extends {
     type: infer T extends string;
     allowMultiple: true;
-} ? CellOf<T>[] : C extends {
+} ? (CellOf<T> | null)[] : C extends {
     type: infer T extends string;
-} ? CellOf<T> : C extends {
+} ? CellOf<T> | null : C extends {
     allowMultiple: true;
 } ? unknown[] : unknown;
 type RequiredName<C> = C extends {
@@ -196,6 +109,101 @@ type GristMappedRow<O extends {
     [N in OptionalName<C>]?: ColumnValue<ByName<C, N>>;
 } : Record<string, unknown>;
 
+type ValidateColumnMappingsResult = {
+    ok: boolean;
+    /**
+     * `true` while the host has not yet reported column mappings (e.g. between
+     * `grist.ready()` resolving and the first `onRecord` / `onRecords` callback,
+     * or before `sectionApi.mappings()` returns). Callers should not gate UI or
+     * emit mapping alerts while pending.
+     */
+    pending?: boolean;
+    /** Logical names of required columns the user has not yet mapped. */
+    missing: string[];
+    /** Logical names of `allowMultiple` columns mapped to an empty list. */
+    emptyMultiples: string[];
+};
+
+type GristNoiseColumnsOptions = {
+    excludeId?: boolean;
+    excludeGristHelpers?: boolean;
+    excludeLoggingColumns?: boolean;
+    /**
+     * When `true`, treat Grist's `manualSort` column as noise (omit from filtered replicas).
+     * Default `false` — `manualSort` is kept unless you opt in.
+     */
+    excludeManualSort?: boolean;
+};
+
+type GristFetchedAttachmentBlob = {
+    blob: Blob;
+    contentType: string;
+};
+/**
+ * All attachment ids found in a Grist attachment cell value (ordered, deduped).
+ * Attachment columns are usually an **array** of file refs; a single id or one JSON object is also supported.
+ */
+declare function extractGristAttachmentIdsFromCell(value: unknown): string[];
+/** First attachment id in the cell, if any (see {@link extractGristAttachmentIdsFromCell}). */
+declare function extractGristAttachmentId(value: unknown): string | undefined;
+
+type GristEncodedAttachmentList = ["L", ...(number | string)[]];
+type GristAttachmentUploadResult = {
+    /** All attachment ids returned by `POST /attachments`. */
+    ids: string[];
+    /** First id in `ids` (convenience for single-file uploads). */
+    firstId: string;
+};
+/** Wire value for an Attachments cell (Grist list encoding). */
+declare function gristAttachmentCellValues(attachmentIds: (string | number)[]): GristEncodedAttachmentList;
+/** Wire value for a single-file Attachments cell. */
+declare function gristAttachmentCellValue(attachmentId: string | number): GristEncodedAttachmentList;
+/**
+ * Merge new attachment ids into an existing Attachments cell value (deduped, order preserved).
+ */
+declare function mergeGristAttachmentCellValue(existingCell: unknown, newIds: (string | number)[]): GristEncodedAttachmentList;
+
+/** Column-oriented table payload (`fetchTable`, `fetchSelectedTable`): `{ id: [...], Name: [...] }`. */
+type GristColumnarTable = Record<string, unknown[]>;
+type GristTableRowsOrder = "none" | "id" | "grist";
+type FetchGristTableRowsOptions = {
+    /** Column metadata, to decode each cell (except `id`) with `decodeGristValue`. */
+    columns?: Record<string, GristReplicaColumn>;
+    /**
+     * Row order:
+     * - `grist` (default): `manualSort` ascending when present, then `id`.
+     * - `id`: numeric `id` ascending.
+     * - `none`: as `fetchTable` returned them.
+     */
+    order?: GristTableRowsOrder;
+};
+/** Turn `fetchTable` output into row objects (order follows the `id` column). */
+declare function tableDataToRows<T = Record<string, unknown>>(data: GristColumnarTable): GristRowRecord<T>[];
+
+/**
+ * Grist `docApi.applyUserActions` payloads are arrays of user-action tuples.
+ * @see https://support.getgrist.com/code/interfaces/grist_plugin_api.GristDocAPI/#applyuseractions
+ */
+type GristUserActionTuple = unknown[];
+/** `["UpdateRecord", tableId, rowId, { col: value, ... }]` */
+declare function gristUpdateRecordAction(tableId: string, rowId: number, patch: Record<string, unknown>): GristUserActionTuple;
+/** `["AddRecord", tableId, null, { col: value, ... }]` */
+declare function gristAddRecordAction(tableId: string, values: Record<string, unknown>): GristUserActionTuple;
+/** `["RemoveRecord", tableId, rowId]` */
+declare function gristRemoveRecordAction(tableId: string, rowId: number): GristUserActionTuple;
+/** `["AddColumn", tableId, colId, colInfo]` — `colInfo` shape depends on Grist version / column type. */
+declare function gristAddColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
+/** `["AddVisibleColumn", tableId, colId, colInfo]` — like `AddColumn` but also adds the column to the current view section. */
+declare function gristAddVisibleColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
+/** `["RenameColumn", tableId, colId, newColId]` */
+declare function gristRenameColumnAction(tableId: string, colId: string, newColId: string): GristUserActionTuple;
+/** `["ModifyColumn", tableId, colId, colInfo]` */
+declare function gristModifyColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
+/** `["RemoveColumn", tableId, colId]` */
+declare function gristRemoveColumnAction(tableId: string, colId: string): GristUserActionTuple;
+/** `["AddTable", tableId, tableInfo]` */
+declare function gristAddTableAction(tableId: string, tableInfo: Record<string, unknown>): GristUserActionTuple;
+
 /**
  * The alerts `mountGristWidget()` shows above a running widget: what needs the
  * user's attention in Grist (column mapping, access, a failed write, an
@@ -293,6 +301,8 @@ type GristWidgetStatus = "booting" | "ready" | "unavailable" | "error";
 
 /** What the widget asks Grist for: access, columns to map, and the alerts it doesn't want. */
 type UseGristOptions = GristRuntimeOptions;
+/** A write under declared names: any of the mapped record's fields but its `id`. */
+type GristRecordPatch<TMapped> = Partial<Omit<TMapped, "id">>;
 /** Derived from the selection: no row, a row, or the add-row placeholder. */
 type GristWidgetMode = "empty" | "row" | "new-row";
 /**
@@ -331,8 +341,22 @@ type UseGristResult<TRow = Record<string, unknown>, TMapped = Record<string, unk
     mode: GristWidgetMode;
     /** The Grist column id mapped to a declared name, or the name itself. */
     resolveMappedColumnId: (name: string) => string;
-    /** A patch under declared names, as real column ids for a write (multi-column mappings are skipped). */
+    /**
+     * A patch under declared names, as real column ids for a write, each value
+     * encoded for its declared type (multi-column mappings are skipped).
+     */
     mapBack: (patch: Partial<TMapped>) => Record<string, unknown>;
+    /**
+     * Writes a patch under declared names to the selected row (or to `rowId`),
+     * encoded for each declared type: `mapBack` + `table.update` in one call.
+     * Rejects when no row is selected.
+     */
+    updateRecord: {
+        (patch: GristRecordPatch<TMapped>): Promise<void>;
+        (rowId: number, patch: GristRecordPatch<TMapped>): Promise<void>;
+    };
+    /** Adds a row to the section's table from a patch under declared names; resolves to its row id. */
+    addRecord: (patch: GristRecordPatch<TMapped>) => Promise<number>;
     /** The section's table id. */
     currentTableId: string | null;
     /** Any table as rows (full access). */
@@ -354,5 +378,56 @@ declare function useGristOptional<TRow = Record<string, unknown>, TMapped = Reco
 /** `useGrist()` inside `<GristWidgetProvider>`; throws outside one. */
 declare function useGristContext<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped>;
 
-export { gristRenameColumnAction as A, gristUpdateRecordAction as B, mergeGristAttachmentCellValue as C, tableDataToRows as D, useGrist as E, useGristContext as F, useGristOptional as H, checkGristCell as o, extractGristAttachmentId as p, extractGristAttachmentIdsFromCell as q, gristAddColumnAction as r, gristAddRecordAction as s, gristAddTableAction as t, gristAddVisibleColumnAction as u, gristAttachmentCellValue as v, gristAttachmentCellValues as w, gristModifyColumnAction as x, gristRemoveColumnAction as y, gristRemoveRecordAction as z };
-export type { GristNoiseColumnsOptions as G, ListColumnsOptions as L, StandardSchema as S, UseGristOptions as U, ValidateColumnMappingsResult as V, GristAttachmentUploadResult as a, GristCellIssue as b, GristColumnInfo as c, GristColumnarTable as d, GristFetchedAttachmentBlob as e, GristMappedRow as f, GristSdkAlertKind as g, GristTheme as h, GristUserActionTuple as i, GristWidgetActionStatus as j, GristWidgetMode as k, GristWidgetStatus as l, ListTablesOptions as m, UseGristResult as n };
+/**
+ * `defineGristWidget()`: a widget's whole declaration in one typed value.
+ * Everything else reads it: `widget.useGrist()` types the mapped records and
+ * the writes from it, `mountGristWidget()` takes the access level, the
+ * columns and the title from it, and the tests map its columns.
+ *
+ * ```ts
+ * export const widget = defineGristWidget({
+ *   title: "Tasks",
+ *   requiredAccess: "full",
+ *   columns: [{ name: "Title", type: "Text" }, { name: "Done", type: "Bool" }],
+ * })
+ *
+ * const w = widget.useGrist()   // w.mappedRecord: { id; Title: string | null; Done: boolean | null } | null
+ * await w.updateRecord({ Done: true })
+ * ```
+ */
+
+/** What a widget declares: `UseGristOptions`, plus its title and description. */
+type GristWidgetDefinition = UseGristOptions & {
+    /** The widget's name: the page's title, and its manifest's. */
+    title?: string;
+    /** One sentence: the page's description, and its manifest's. */
+    description?: string;
+};
+/** The widget's mapped record type, from its declaration. */
+type GristWidgetRow<W> = W extends GristWidget<infer D> ? GristMappedRow<D> : never;
+/** A declared widget. Pass it to `mountGristWidget()` (as `widget`, exported from `src/app/App.tsx`). */
+type GristWidget<D extends GristWidgetDefinition = GristWidgetDefinition> = {
+    /** The declaration, as written. */
+    readonly definition: D;
+    /** What the widget asks Grist for: the declaration without its title and description. */
+    readonly options: UseGristOptions;
+    readonly metadata: {
+        title?: string;
+        description?: string;
+    };
+    /**
+     * `useGrist()`, typed from the declaration: `mappedRecord`, `mappedRecords`,
+     * `mapBack`, `updateRecord` and `addRecord` use the declared names and the
+     * value each declared type gives. A hook: call it in a component.
+     */
+    useGrist: () => UseGristResult<GristRowRecord, GristMappedRow<D>>;
+};
+/**
+ * Declares a widget. The `const` type parameter keeps the column names and
+ * types literal, so the mapped record is typed with no annotation, no
+ * `as const` and no generics.
+ */
+declare function defineGristWidget<const D extends GristWidgetDefinition>(definition: D): GristWidget<D>;
+
+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 };
+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 };