grist-widget-sdk 0.3.27 → 0.4.0

package/dist/use-grist-reads-DpjVuI0H.d.cts

@@ -1,480 +0,0 @@
-import { c as GristReplicaColumn, G as GristRowRecord, s as GristDocApi, n as GristRequiredAccess, r as GristColumnsToMap, d as GristWidgetColumnMap, i as GristReadyOptions } from './types-D3JxUCfL.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;
-};
-/** Canonical 4-state status — projected from the handshake snapshot. */
-type GristWidgetStatus = "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[];
-};
-
-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;
-};
-
-export { inferDisplayHelpersByRef as $, findRowIndexById as A, getGristAccessToken as B, gristAddColumnAction as C, gristAddRecordAction as D, gristAddTableAction as E, gristAddVisibleColumnAction as H, gristBulkAddRecordAction as I, gristBulkRemoveRecordAction as J, gristBulkUpdateRecordAction as K, gristCellValueSchema as M, gristDuplicateTableAction as N, gristModifyColumnAction as O, gristRemoveColumnAction as P, gristRemoveRecordAction as Q, gristRemoveTableAction as R, gristRenameColumnAction as T, gristRenameTableAction as V, gristReplaceTableDataAction as W, gristSafeRefListValueSchema as X, gristSafeRefValueSchema as Y, gristSetDocumentInfoAction as Z, gristUpdateRecordAction as _, isGristNoiseColumn as a0, materializeGristRowsFromColumnar as a1, rowAtIndex as a2, safeParseGristTableData as a3, safeParseGristValues as a4, safeParseRowsToDisplayRows as a5, sortRowsByGristOrder as a6, tableDataToRows as a7, computeRowCount as v, decodeColumnarToReplicaRows as w, fetchGristRow as x, fetchGristTableRows as y, fetchWithGristAuth as z };
-export type { FetchGristTableRowsOptions as F, GristWidgetSnapshot as G, ListColumnsOptions as L, SafeParseGristTableDataOptions as S, UseGristCoreOptions as U, GristNoiseColumnsOptions as a, GristTerminationReason as a8, GristGeneration as a9, GristMappingSource as aa, GristAuthz as ab, GristConfig as ac, GristCurrentTableState as ad, GristLifecycle as ae, GristLifecyclePhase as af, GristLink as ag, GristLinkState as ah, GristMappingComplete as ai, GristMappingIncomplete as aj, GristMappingState as ak, GristStreamFreshness as al, GristSync as am, GristAccessToken as b, GristCapabilities as c, GristCellValue as d, GristColumnInfo as e, GristColumnLike as f, GristColumnarTable as g, GristSafeParseCellResult as h, GristSafeParseIssue as i, GristSafeParseIssueCode as j, GristSafeRefListValue as k, GristSafeRefValue as l, GristSafeTableCellIssue as m, GristSafeTableCellMeta as n, GristTableRowsOrder as o, GristUserActionTuple as p, GristWidgetStatus as q, ListTablesOptions as r, SafeParseGristTableDataResult as s, SafeParseGristValuesOptions as t, UseGristCoreResult as u };