grist-widget-sdk 0.2.0

package/dist/use-grist-widget-options-from-context-qpFMdoBJ.d.cts

@@ -0,0 +1,522 @@
+import { j as GristReplicaColumn, p as GristRowRecord, d as GristDocApi, o as GristRequiredAccess, b as GristColumnsToMap, w as GristWidgetColumnMap, i as GristReadyOptions } from './types-Fb2wplkv.cjs';
+import { z, ZodType } from 'zod';
+
+type GristSafeParseIssueCode = "grist_error" | "invalid_format" | "type_mismatch" | "helper_mismatch" | "zod_error";
+type GristSafeParseIssue = {
+    code: GristSafeParseIssueCode;
+    message: string;
+};
+type GristSafeRefValue = {
+    rowId: number;
+    display?: string | null;
+};
+type GristSafeRefListValue = {
+    rowIds: number[];
+    displays?: string[];
+};
+declare const gristSafeRefValueSchema: z.ZodObject<{
+    rowId: z.ZodNumber;
+    display: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+declare const gristSafeRefListValueSchema: z.ZodObject<{
+    rowIds: z.ZodArray<z.ZodNumber>;
+    displays: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+declare const gristCellValueSchema: z.ZodUnion<readonly [z.ZodNull, z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodDate, z.ZodArray<z.ZodUnknown>, z.ZodObject<{
+    rowId: z.ZodNumber;
+    display: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    rowIds: z.ZodArray<z.ZodNumber>;
+    displays: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>]>;
+type GristCellValue = z.infer<typeof gristCellValueSchema>;
+type GristSafeParseCellResult<TValue = unknown> = {
+    ok: boolean;
+    typedValue: TValue | null;
+    displayValue: unknown;
+    raw: unknown;
+    issues: GristSafeParseIssue[];
+};
+type RefMode = "id" | "detailed";
+type SafeParseGristValuesOptions<TValue = unknown> = {
+    values: readonly unknown[];
+    column?: GristReplicaColumn;
+    helperValues?: readonly unknown[];
+    schema?: ZodType<TValue>;
+    fallbackUntypedToString?: boolean;
+    refMode?: RefMode;
+};
+type SafeParseGristTableDataOptions = {
+    columns?: Record<string, GristReplicaColumn>;
+    displayHelpersByRef?: Record<string, string>;
+    order?: "none" | "id" | "grist";
+    fallbackUntypedToString?: boolean;
+    refMode?: RefMode;
+};
+type GristSafeTableCellIssue = GristSafeParseIssue & {
+    rowIndex: number;
+    colId: string;
+};
+type GristSafeChoiceTokenMeta = {
+    value: string;
+    label: string;
+    fillColor?: string;
+    textColor?: string;
+    valid: boolean;
+};
+type GristSafeTableCellMeta = {
+    rowIndex: number;
+    colId: string;
+    ok: boolean;
+    issues: GristSafeParseIssue[];
+    choiceTokens?: GristSafeChoiceTokenMeta[];
+};
+type SafeParseGristTableDataResult<TRow extends Record<string, unknown> = Record<string, unknown>> = {
+    rows: GristRowRecord<TRow>[];
+    cellIssues: GristSafeTableCellIssue[];
+    cellMeta: GristSafeTableCellMeta[];
+    cellMetaByKey: Record<string, GristSafeTableCellMeta>;
+    cellResultsByColumn: Record<string, GristSafeParseCellResult[]>;
+};
+/** Maps `Ref:*` / `RefList:*` column ids to their paired `gristHelper_*` column id (same rules as safe-parse). */
+declare function inferDisplayHelpersByRef(columns: Record<string, GristReplicaColumn>): Record<string, string>;
+declare function safeParseGristValues<TValue = unknown>(options: SafeParseGristValuesOptions<TValue>): GristSafeParseCellResult<TValue>[];
+declare function safeParseGristTableData<TRow extends Record<string, unknown> = Record<string, unknown>>(data: GristColumnarTable, options?: SafeParseGristTableDataOptions): SafeParseGristTableDataResult<TRow>;
+
+/**
+ * Column-oriented table payload from `grist.docApi.fetchTable`.
+ */
+type GristColumnarTable = Record<string, unknown[]>;
+type GristTableRowsOrder = "none" | "id" | "grist";
+type FetchGristTableRowsOptions = {
+    /** Optional schema metadata map to decode cells (except `id`) with `decodeGristValue`. */
+    columns?: Record<string, GristReplicaColumn>;
+    /**
+     * Row ordering strategy.
+     * - `grist` (default): `manualSort` ascending when present, fallback `id`.
+     * - `id`: numeric `id` ascending.
+     * - `none`: preserve raw `fetchTable` row order.
+     */
+    order?: GristTableRowsOrder;
+    /**
+     * Enable safe parsing with issue reporting.
+     * - `true`: use safe parsing with defaults.
+     * - object: pass safe-parse options (`displayHelpersByRef`, `refMode`, ...).
+     */
+    safeParse?: boolean | Omit<SafeParseGristTableDataOptions, "columns" | "order">;
+    /** Optional callback fired with per-cell parse issues when `safeParse` is enabled. */
+    onSafeParseIssues?: (issues: GristSafeTableCellIssue[]) => void;
+    /** Optional callback fired with enriched per-cell safe-parse metadata. */
+    onSafeParseCellMeta?: (meta: GristSafeTableCellMeta[]) => void;
+    /** Optional callback fired with keyed per-cell metadata (`${rowId}:${colId}`). */
+    onSafeParseCellMetaByKey?: (metaByKey: Record<string, GristSafeTableCellMeta>) => void;
+};
+/**
+ * Project safe-parse rows to UI display rows by taking each cell's `displayValue`.
+ * Useful for grids that render human-friendly values while keeping safe-cell
+ * objects available for logic and metadata.
+ */
+declare function safeParseRowsToDisplayRows(rows: ReadonlyArray<Record<string, unknown>>): GristRowRecord<Record<string, unknown>>[];
+/** Row count from columnar `fetchTable` data (prefers `id` column length). */
+declare function computeRowCount(data: Record<string, unknown[]>): number;
+/**
+ * Decode columnar `fetchTable` into replica row objects (same convention as the playground grid).
+ */
+declare function decodeColumnarToReplicaRows(data: GristColumnarTable, columnIds: string[], columns: Record<string, GristReplicaColumn>, maxRows?: number): GristRowRecord[];
+/** Turn `fetchTable` output into row objects (order follows the `id` column). */
+declare function tableDataToRows<T = Record<string, unknown>>(data: GristColumnarTable): GristRowRecord<T>[];
+/**
+ * Sort rows by Grist's display order: `manualSort` ascending when present on
+ * any row, otherwise numeric `id` ascending.
+ */
+declare function sortRowsByGristOrder<T = Record<string, unknown>>(rows: readonly GristRowRecord<T>[]): GristRowRecord<T>[];
+/** Row index where `id` matches `rowId`, or `null`. */
+declare function findRowIndexById(data: GristColumnarTable, rowId: number | string): number | null;
+/** Single row at `index`, or `null` if out of range. */
+declare function rowAtIndex<T = Record<string, unknown>>(data: GristColumnarTable, index: number): GristRowRecord<T> | null;
+/**
+ * Fetch a single row from any table by id. Convenience around
+ * `docApi.fetchTable` + {@link findRowIndexById} + {@link rowAtIndex}.
+ */
+declare function fetchGristRow<T = Record<string, unknown>>(docApi: GristDocApi, tableId: string, rowId: number): Promise<GristRowRecord<T> | null>;
+/**
+ * Same row materialization as {@link fetchGristTableRows} after `fetchTable`
+ * returns columnar data. Hosts that already have columnar data (e.g. the
+ * emulator building from in-memory rows) can use this and skip `docApi.fetchTable`.
+ */
+declare function materializeGristRowsFromColumnar<T extends Record<string, unknown> = Record<string, unknown>>(data: GristColumnarTable, options?: FetchGristTableRowsOptions): GristRowRecord<T>[];
+/**
+ * Fetch a table and return rows as objects, optionally decoded from schema and sorted.
+ */
+declare function fetchGristTableRows<T extends Record<string, unknown> = Record<string, unknown>>(docApi: GristDocApi, tableId: string, options: FetchGristTableRowsOptions & {
+    safeParse: true | Omit<SafeParseGristTableDataOptions, "columns" | "order">;
+}): Promise<GristRowRecord<{
+    [K in keyof T]: GristSafeParseCellResult<T[K]> | null;
+}>[]>;
+declare function fetchGristTableRows<T extends Record<string, unknown> = Record<string, unknown>>(docApi: GristDocApi, tableId: string, options?: FetchGristTableRowsOptions): Promise<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;
+/** `["BulkUpdateRecord", tableId, rowIds, { col: value[], ... }]` — column arrays must align with `rowIds`. */
+declare function gristBulkUpdateRecordAction(tableId: string, rowIds: number[], columnarPatch: Record<string, unknown[]>): GristUserActionTuple;
+/**
+ * `["BulkAddRecord", tableId, rowIds | nullArray, { col: value[], ... }]`.
+ * Pass `null` (or omit) for `rowIds` to let Grist allocate ids; in user-action
+ * format Grist expects an array of nulls of the same length as the value arrays.
+ */
+declare function gristBulkAddRecordAction(tableId: string, values: Record<string, unknown[]>, rowIds?: Array<number | null>): GristUserActionTuple;
+/** `["BulkRemoveRecord", tableId, rowIds]` */
+declare function gristBulkRemoveRecordAction(tableId: string, rowIds: 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;
+/** `["RenameTable", tableId, newTableId]` */
+declare function gristRenameTableAction(tableId: string, newTableId: string): GristUserActionTuple;
+/** `["RemoveTable", tableId]` */
+declare function gristRemoveTableAction(tableId: string): GristUserActionTuple;
+/** `["DuplicateTable", tableId, newTableId, options?]` */
+declare function gristDuplicateTableAction(tableId: string, newTableId: string, options?: Record<string, unknown>): GristUserActionTuple;
+/** `["ReplaceTableData", tableId, rowIds, columnarData]` */
+declare function gristReplaceTableDataAction(tableId: string, rowIds: Array<number | null>, columnarData: Record<string, unknown[]>): GristUserActionTuple;
+/** `["SetDocumentInfo", info]` */
+declare function gristSetDocumentInfoAction(info: Record<string, unknown>): GristUserActionTuple;
+
+type GristColumnLike = {
+    formula?: 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;
+};
+/**
+ * Grist-centric "technical column" detection used by document hooks and widgets.
+ *
+ * - `id` (when {@link GristNoiseColumnsOptions.excludeId} is true — default)
+ * - `manualSort` (only when {@link GristNoiseColumnsOptions.excludeManualSort} is true)
+ * - `gristHelper_*` (when `excludeGristHelpers` is true — default)
+ * - trigger/logging formulas (`NOW()`, `user.*`) (when `excludeLoggingColumns` is true — default)
+ */
+declare function isGristNoiseColumn(colId: string, col?: GristColumnLike, options?: GristNoiseColumnsOptions): boolean;
+
+type GristAccessToken = {
+    token: string;
+    baseUrl: string;
+};
+/**
+ * Returns an access token suitable for calling Grist's REST API directly.
+ * Tokens are short-lived; results are cached briefly and coalesced per readOnly flag.
+ */
+declare function getGristAccessToken(docApi: GristDocApi, options?: {
+    readOnly?: boolean;
+}): Promise<GristAccessToken>;
+/**
+ * `fetch()` against Grist's REST API with the doc access token attached.
+ */
+declare function fetchWithGristAuth(docApi: GristDocApi, path: string, init?: RequestInit & {
+    readOnly?: boolean;
+}): Promise<Response>;
+
+/**
+ * Pure type contracts for the handshake / synchronization state machine.
+ *
+ * The machine models five orthogonal axes that together describe the widget's
+ * relationship with the Grist host:
+ *
+ *   1. `LIFECYCLE` — protocol handshake (one-shot via `grist.ready`).
+ *   2. `LINK`      — RPC channel health (continuous, post-online).
+ *   3. `AUTHZ`     — effective access level granted by the host.
+ *   4. `CONFIG`    — column mapping contract with the end-user.
+ *   5. `SYNC`      — freshness of each event stream and ancillary RPCs.
+ *
+ * The legacy public `status` ("booting" / "ready" / "unavailable" / "error")
+ * is a **pure projection** of the snapshot, computed in `./derive.ts`.
+ *
+ * No runtime side effects in this file — types only.
+ */
+
+/** Monotone counter bumped on reload / restart / link recovery / access widening. */
+type GristGeneration = number & {
+    readonly __brand: "GristGeneration";
+};
+type GristLifecyclePhase = "idle" | "detecting" | "negotiating" | "online" | "terminated";
+type GristTerminationReason = {
+    kind: "script_timeout";
+    attempts: number;
+} | {
+    kind: "not_embedded";
+} | {
+    kind: "ready_failed";
+    message: string;
+} | {
+    kind: "ready_timeout";
+    afterMs: number;
+} | {
+    kind: "host_rejected";
+    message: string;
+} | {
+    kind: "manual_terminate";
+};
+type GristLifecycle = {
+    phase: "idle";
+} | {
+    phase: "detecting";
+    attempts: number;
+    startedAtMs: number;
+} | {
+    phase: "negotiating";
+    access: GristRequiredAccess;
+    startedAtMs: number;
+} | {
+    phase: "online";
+    sinceMs: number;
+    declaredAccess: GristRequiredAccess;
+} | {
+    phase: "terminated";
+    reason: GristTerminationReason;
+    atMs: number;
+};
+type GristLinkState = "connected" | "stale" | "lost";
+type GristLink = {
+    state: GristLinkState;
+    /** ms timestamp of last successful RPC (or heartbeat). `null` before any. */
+    lastSuccessMs: number | null;
+    /** Consecutive RPC failures since the last success. */
+    missedPings: number;
+};
+type GristAuthz = {
+    state: "pending";
+    declared: GristRequiredAccess;
+} | {
+    state: "granted";
+    /** Effective level granted by the host. May differ from `declared`. */
+    level: GristRequiredAccess;
+    declared: GristRequiredAccess;
+    /** True if granted level >= a previously granted level for the same widget. */
+    widened: boolean;
+} | {
+    state: "denied";
+    declared: GristRequiredAccess;
+    message?: string;
+};
+/**
+ * Source that produced a mapping payload, used for deterministic merge by
+ * {@link MappingResolver} (see `./mapping-resolver.ts`).
+ */
+type GristMappingSource = "section_api" | "stream_record" | "stream_records" | "stream_new_record";
+type GristMappingComplete = {
+    state: "complete";
+    declared: GristColumnsToMap;
+    mappings: GristWidgetColumnMap;
+    /** `"merged"` is used internally when multiple sources contributed. */
+    source: GristMappingSource | "merged";
+    reportedAtMs: number;
+};
+type GristMappingIncomplete = {
+    state: "incomplete";
+    declared: GristColumnsToMap;
+    mappings: GristWidgetColumnMap;
+    missing: readonly string[];
+    emptyMultiples: readonly string[];
+    source: GristMappingSource | "merged";
+    reportedAtMs: number;
+};
+type GristMappingState = 
+/** Widget did not declare any `columns` in `grist.ready`. */
+{
+    state: "not_declared";
+}
+/** Columns declared but no host report yet received. */
+ | {
+    state: "pending";
+    declared: GristColumnsToMap;
+    declaredAtMs: number;
+} | GristMappingIncomplete | GristMappingComplete
+/** User just modified the mapping; previous payload preserved to avoid UI flicker. */
+ | {
+    state: "invalidating";
+    previous: GristMappingIncomplete | GristMappingComplete;
+    sinceMs: number;
+}
+/** Declared but no host report after a timeout. Soft state — payload may still arrive. */
+ | {
+    state: "unreported";
+    declared: GristColumnsToMap;
+    afterMs: number;
+};
+type GristConfig = {
+    mappings: GristMappingState;
+};
+type GristStreamFreshness = {
+    state: "cold";
+} | {
+    state: "warming";
+    sinceMs: number;
+} | {
+    state: "hot";
+    lastEventMs: number;
+    generation: GristGeneration;
+    payloadHash: string;
+} | {
+    state: "stale";
+    lastEventMs: number;
+    reason: "link_lost" | "tab_hidden" | "host_quiet";
+};
+type GristCurrentTableState = {
+    state: "unknown";
+} | {
+    state: "known";
+    tableId: string;
+    refreshing: boolean;
+}
+/** Local error (e.g. `selectedTable.getTableId()` rejected) — does NOT propagate to global status. */
+ | {
+    state: "errored";
+    message: string;
+    sinceMs: number;
+};
+type GristSync = {
+    record: GristStreamFreshness;
+    records: GristStreamFreshness;
+    options: GristStreamFreshness;
+    newRecord: GristStreamFreshness;
+    currentTable: GristCurrentTableState;
+};
+type GristWidgetSnapshot = {
+    generation: GristGeneration;
+    lifecycle: GristLifecycle;
+    link: GristLink;
+    authz: GristAuthz;
+    config: GristConfig;
+    sync: GristSync;
+};
+/** Mirrors the long-standing public type, kept for compat. */
+type GristWidgetStatus$1 = "booting" | "ready" | "unavailable" | "error";
+/**
+ * Pre-computed booleans that widget code should consume directly instead of
+ * re-deriving from `status` + mapping flags + writes flags.
+ *
+ * Every field is a **pure function of the snapshot** and is referentially
+ * stable across renders that don't change the snapshot's relevant slices.
+ */
+type GristCapabilities = {
+    /** `lifecycle.online` + `link != lost` + `authz.state === "granted"` with read or higher. */
+    canRead: boolean;
+    /** `canRead` + (`mappings.state` is `complete` or `not_declared`). */
+    canRender: boolean;
+    /** `canRender` + `authz.level === "full"`. Required before any write. */
+    canWriteRecords: boolean;
+    /** `canWriteRecords` + `sync.currentTable.state === "known"`. */
+    canWriteSchema: boolean;
+    /** `canRead` + `link === "connected"`. */
+    canFetchTable: boolean;
+    /** `canRead` + `sync.record.state === "hot"` + mappings not invalidating. */
+    hasFreshSelection: boolean;
+    /** `mappings.state === "complete" || "not_declared"`. */
+    hasUsableMappings: boolean;
+    /** Logical column names still missing from user mapping (incomplete only). */
+    missingMappings: readonly string[];
+    /** `allowMultiple` columns mapped to `[]` (incomplete only). */
+    emptyMultipleMappings: readonly string[];
+};
+
+/** Canonical 4-state status — projected from the handshake snapshot. */
+type GristWidgetStatus = GristWidgetStatus$1;
+type UseGristCoreOptions = GristReadyOptions & {
+    availabilityMaxAttempts?: number;
+    availabilityIntervalMs?: number;
+    logWhenNotEmbedded?: boolean;
+};
+type UseGristCoreResult = {
+    status: GristWidgetStatus;
+    isAvailable: boolean | null;
+    isReady: boolean;
+    error: string | null;
+    docApi: GristDocApi | null;
+    /** Derived from the handshake snapshot — same values as `useGristCapabilities()` on `/advanced`. */
+    capabilities: GristCapabilities;
+    reload: () => Promise<void>;
+};
+
+type ListTablesOptions = {
+    /** When true, include system tables (prefixed with `_grist` or `GristHidden_`). Default: false. */
+    includeSystem?: boolean;
+};
+type GristColumnInfo = {
+    colId: string;
+    type?: string;
+    label?: string;
+    isFormula?: boolean;
+    formula?: string;
+    description?: string;
+};
+type ListColumnsOptions = GristNoiseColumnsOptions & {
+    /** When true, include system tables' columns. Default: false. */
+    includeSystem?: boolean;
+};
+
+type UseGristWidgetOptionsFromContextConfig<T> = {
+    /** Default values returned before Grist responds and merged with stored options. */
+    defaults: T;
+    /** Debounce window for `setOptions` writes (ms). Default: 250. */
+    debounceMs?: number;
+    /**
+     * Optional namespace key. When set, this hook reads/writes
+     * `options[namespace]` instead of the whole options blob.
+     */
+    namespace?: string;
+};
+type UseGristWidgetOptionsFromContextResult<T> = {
+    options: T;
+    /** True until Grist has responded with the initial `onOptions` payload. */
+    loading: boolean;
+    /** Replace the options object (debounced write to Grist). */
+    setOptions: (next: T) => void;
+    /** Patch a subset of keys (debounced write to Grist). */
+    patchOptions: (patch: Partial<T>) => void;
+    /** Reset to `defaults` (immediate write to Grist). */
+    reset: () => Promise<void>;
+};
+/**
+ * Typed widget options hook designed for use **inside a `<GristWidgetProvider>`**.
+ *
+ * Unlike `useGristWidgetOptions()` (which calls `useGristReady()` and conflicts
+ * with the provider), this hook reads from the provider's existing context —
+ * `widgetOptions` for reactive reads, and `patchWidgetOptions` / `setWidgetOptions`
+ * for writes.
+ *
+ * ```tsx
+ * function MyConfigPanel() {
+ *   const { options, patchOptions } = useGristWidgetOptionsFromContext({
+ *     defaults: { color: '#FF0000', showLabels: true },
+ *   })
+ *   return <input value={options.color} onChange={e => patchOptions({ color: e.target.value })} />
+ * }
+ * ```
+ */
+declare function useGristWidgetOptionsFromContext<T extends Record<string, unknown>>(config: UseGristWidgetOptionsFromContextConfig<T>): UseGristWidgetOptionsFromContextResult<T>;
+
+export { gristAddTableAction as $, type GristSync as A, type GristTableRowsOrder as B, type GristTerminationReason as C, type GristUserActionTuple as D, type GristWidgetSnapshot as E, type FetchGristTableRowsOptions as F, type GristAccessToken as G, type GristWidgetStatus as H, type GristWidgetStatus$1 as I, type ListTablesOptions as J, type SafeParseGristTableDataResult as K, type ListColumnsOptions as L, type SafeParseGristValuesOptions as M, type UseGristCoreResult as N, type UseGristWidgetOptionsFromContextConfig as O, type UseGristWidgetOptionsFromContextResult as P, computeRowCount as Q, decodeColumnarToReplicaRows as R, type SafeParseGristTableDataOptions as S, fetchGristRow as T, type UseGristCoreOptions as U, fetchGristTableRows as V, fetchWithGristAuth as W, findRowIndexById as X, getGristAccessToken as Y, gristAddColumnAction as Z, gristAddRecordAction as _, type GristAuthz as a, gristAddVisibleColumnAction as a0, gristBulkAddRecordAction as a1, gristBulkRemoveRecordAction as a2, gristBulkUpdateRecordAction as a3, gristCellValueSchema as a4, gristDuplicateTableAction as a5, gristModifyColumnAction as a6, gristRemoveColumnAction as a7, gristRemoveRecordAction as a8, gristRemoveTableAction as a9, gristRenameColumnAction as aa, gristRenameTableAction as ab, gristReplaceTableDataAction as ac, gristSafeRefListValueSchema as ad, gristSafeRefValueSchema as ae, gristSetDocumentInfoAction as af, gristUpdateRecordAction as ag, inferDisplayHelpersByRef as ah, isGristNoiseColumn as ai, materializeGristRowsFromColumnar as aj, rowAtIndex as ak, safeParseGristTableData as al, safeParseGristValues as am, safeParseRowsToDisplayRows as an, sortRowsByGristOrder as ao, tableDataToRows as ap, useGristWidgetOptionsFromContext as aq, type GristCapabilities as b, type GristCellValue as c, type GristColumnInfo as d, type GristColumnLike as e, type GristColumnarTable as f, type GristConfig as g, type GristCurrentTableState as h, type GristGeneration as i, type GristLifecycle as j, type GristLifecyclePhase as k, type GristLink as l, type GristLinkState as m, type GristMappingComplete as n, type GristMappingIncomplete as o, type GristMappingSource as p, type GristMappingState as q, type GristNoiseColumnsOptions as r, type GristSafeParseCellResult as s, type GristSafeParseIssue as t, type GristSafeParseIssueCode as u, type GristSafeRefListValue as v, type GristSafeRefValue as w, type GristSafeTableCellIssue as x, type GristSafeTableCellMeta as y, type GristStreamFreshness as z };

package/package.json

@@ -0,0 +1,131 @@
+{
+  "name": "grist-widget-sdk",
+  "version": "0.2.0",
+  "description": "React hooks and helpers for Grist custom widgets",
+  "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArthurBlanchon/grist-widget-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ArthurBlanchon/grist-widget-sdk/issues"
+  },
+  "homepage": "https://grist-widgets.com",
+  "keywords": [
+    "grist",
+    "widget",
+    "custom-widget",
+    "react",
+    "typescript"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./advanced": {
+      "import": {
+        "types": "./dist/advanced.d.ts",
+        "default": "./dist/advanced.js"
+      },
+      "require": {
+        "types": "./dist/advanced.d.cts",
+        "default": "./dist/advanced.cjs"
+      }
+    },
+    "./emulator": {
+      "import": {
+        "types": "./dist/emulator.d.ts",
+        "default": "./dist/emulator.js"
+      },
+      "require": {
+        "types": "./dist/emulator.d.cts",
+        "default": "./dist/emulator.cjs"
+      }
+    },
+    "./emulator/transports": {
+      "import": {
+        "types": "./dist/emulator/transports.d.ts",
+        "default": "./dist/emulator/transports.js"
+      },
+      "require": {
+        "types": "./dist/emulator/transports.d.cts",
+        "default": "./dist/emulator/transports.cjs"
+      }
+    },
+    "./emulator/testing": {
+      "import": {
+        "types": "./dist/emulator/testing.d.ts",
+        "default": "./dist/emulator/testing.js"
+      },
+      "require": {
+        "types": "./dist/emulator/testing.d.cts",
+        "default": "./dist/emulator/testing.cjs"
+      }
+    },
+    "./emulator/devtools": {
+      "import": {
+        "types": "./dist/emulator/devtools.d.ts",
+        "default": "./dist/emulator/devtools.js"
+      },
+      "require": {
+        "types": "./dist/emulator/devtools.d.cts",
+        "default": "./dist/emulator/devtools.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10",
+    "@testing-library/jest-dom": "^6",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "fast-check": "^4.8.0",
+    "grist-plugin-api": "^0.0.1",
+    "jsdom": "^29.0.2",
+    "tsup": "^8",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.9",
+    "vitest": "^4.1.4"
+  },
+  "dependencies": {
+    "grain-rpc": "^0.1.7",
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest --run --project unit --project emulator --project docs",
+    "test:unit": "vitest --run --project unit",
+    "test:emulator": "vitest --run --project emulator --passWithNoTests",
+    "bench": "vitest run --project bench",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.vitest.json --noEmit"
+  }
+}