grist-widget-sdk 0.2.0

package/dist/types-Fb2wplkv.d.cts

@@ -0,0 +1,228 @@
+/**
+ * How row bodies were populated when the replica document was built (hint only).
+ * Loaders should still treat omitted `rows` like `[]` via {@link normalizeReplicaTableInput}.
+ */
+type GristDocumentMode = "schema-only" | "schema+samples" | "schema+data";
+/**
+ * Decoded row in replica JSON (`id` + fields). Same as wire `fetchTable` row objects,
+ * but **not** columnar `Record<colId, unknown[]>` — that shape is only on `docApi.fetchTable`.
+ */
+type GristReplicaRow = GristRowRecord;
+/**
+ * Column metadata in replica JSON: Grist-native fields only (no samples / scan stats).
+ * `formulaKind` is optional UI convenience; use {@link resolveGristFormulaKind} when missing.
+ */
+type GristReplicaColumn = {
+    /** Internal row id in `_grist_Tables_column` for this column. */
+    colRef?: number;
+    type?: string;
+    label?: string;
+    parentPos?: number;
+    isFormula?: boolean;
+    formulaKind?: GristFormulaKind;
+    /** Present only when non-empty; may be truncated. */
+    formula?: string;
+    description?: string;
+    widgetOptions?: Record<string, unknown>;
+    /** Internal `_grist_Tables_column` row id of the display helper for refs. */
+    displayColRef?: number;
+    /** Internal `_grist_Tables_column` row id of the visible column. */
+    visibleColRef?: number;
+};
+type GristReplicaTable = {
+    label?: string;
+    columns?: Record<string, GristReplicaColumn>;
+    /** Decoded rows; omit or `[]` interchangeably until normalized at boundaries. */
+    rows?: GristReplicaRow[];
+    rowCount?: number;
+    dataOmitted?: boolean;
+    dataOmittedReason?: string;
+    error?: string;
+};
+/**
+ * Canonical Grist replica document: one JSON type for `getDocumentJson`, fixtures,
+ * and `createGristEmulator({ document })`.
+ */
+type GristReplicaDocument = {
+    generatedAt: string;
+    /** Optional provenance label (e.g. widget id); hosts may log this when building or persisting replicas. */
+    source?: string;
+    docName?: string;
+    mode?: GristDocumentMode;
+    tables: Record<string, GristReplicaTable>;
+    selection?: Partial<GristReplicaSelection> & {
+        tableId?: string;
+    };
+    widgetOptions?: Record<string, unknown>;
+    widgetInteraction?: GristWidgetInteraction;
+    configuration?: GristWidgetConfiguration;
+    accessToken?: {
+        token: string;
+        baseUrl: string;
+        ttlMsecs: number;
+    } | null;
+};
+
+/** Access level passed to `grist.ready({ requiredAccess })`. */
+type GristRequiredAccess = "none" | "read table" | "full";
+/**
+ * Single-column declaration in `grist.ready({ columns })`.
+ * Mirrors Grist `ColumnToMap`. See https://support.getgrist.com/code/interfaces/grist_plugin_api.ColumnToMap/
+ */
+type GristColumnToMap = {
+    /** Logical column name your widget code uses (must be a valid JSON property name). */
+    name: string;
+    /** Short label shown in the section mapping UI. */
+    title?: string | null;
+    /** Long help text for the section mapping UI. */
+    description?: string | null;
+    /** Comma-separated list of allowed Grist column types. Defaults to `"Any"`. */
+    type?: string;
+    /** Mark column as optional (default: required). */
+    optional?: boolean;
+    /** Allow multiple column assignment (resulting `mappings[name]` becomes `string[]`). */
+    allowMultiple?: boolean;
+    /** Match column type strictly (so `"Any"` matches only `"Any"`). */
+    strictType?: boolean;
+};
+/** Argument shape for `grist.ready({ columns })`. */
+type GristColumnsToMap = Array<string | GristColumnToMap>;
+/**
+ * Mapping returned by Grist between logical widget column names and real table column ids.
+ * Single mappings are `string`; `allowMultiple` columns are `string[]`.
+ */
+type GristWidgetColumnMap = Record<string, string | string[] | undefined>;
+/** A row from `grist.onRecord` or `fetchTable`. Always carries a numeric `id`. */
+type GristRowRecord<T = Record<string, unknown>> = T & {
+    id: number;
+};
+/** Arguments accepted by `grist.ready` for custom widgets. */
+type GristReadyOptions = {
+    requiredAccess?: GristRequiredAccess;
+    columns?: GristColumnsToMap;
+    allowSelectBy?: boolean;
+    hasCustomOptions?: boolean;
+    onEditOptions?: () => void | Promise<void>;
+    /** Passed to availability detection (default 10). */
+    availabilityMaxAttempts?: number;
+    /** Ms between availability polls (default 1000). */
+    availabilityIntervalMs?: number;
+    /** Log when the page is not iframe-embedded (default false). */
+    logWhenNotEmbedded?: boolean;
+};
+/** Optional second argument to `docApi.applyUserActions`. */
+type GristApplyUserActionsOptions = {
+    /** Description shown in the document undo stack. */
+    desc?: string;
+};
+/**
+ * Last `grist.ready` options mirrored with the emulator (optional on fixtures).
+ */
+type GristWidgetConfiguration = {
+    requiredAccess?: GristRequiredAccess;
+    columns?: GristColumnsToMap;
+    allowSelectBy?: boolean;
+    hasCustomOptions?: boolean;
+};
+/**
+ * How Grist treats the column (from `_grist_Tables_column` `isFormula` + `formula`).
+ * `empty_slot` is Grist's "empty column" state: `isFormula` true with no formula text.
+ */
+type GristFormulaKind = "computed" | "trigger" | "none" | "empty_slot";
+/** Options for `fetchSelectedTable` / `fetchSelectedRecord` on `docApi` (GristView). */
+type GristFetchSelectedOptions = {
+    keepEncoded?: boolean;
+    format?: "rows" | "columns" | string;
+};
+/** Argument to `grist.setCursorPos` (subset of Grist `CursorPos`). */
+type GristCursorPos = {
+    rowId?: number;
+    field?: string;
+    colRef?: string;
+    sectionId?: number;
+};
+/** Selection slice persisted on replica fixtures (emulator / widget). */
+type GristReplicaSelection = {
+    tableId: string;
+    rowId: number | "new" | null;
+    mappings?: GristWidgetColumnMap | null;
+    cursor?: GristCursorPos;
+};
+/**
+ * Linking state reported by Grist in `onOptions` settings (`InteractionOptions.linking`).
+ * @see https://github.com/gristlabs/grist-core/blob/main/app/plugin/CustomSectionAPI.ts
+ */
+type GristWidgetLinkingInfo = {
+    /** Incoming link type, or `null` when this section is not driven by a selector. */
+    asTarget: string | null;
+    /** True when another section uses this widget as a link source. */
+    asSource: boolean;
+};
+/**
+ * Second argument to `grist.onOptions` — document ↔ widget relationship (subset of Grist `InteractionOptions`).
+ */
+type GristWidgetInteraction = {
+    access_level?: string;
+    /** Present on Grist builds that report page linking; absent on older hosts. */
+    linking?: GristWidgetLinkingInfo;
+    [key: string]: unknown;
+};
+/**
+ * `TableOperations`-style record for `update`. Must include `id`; other fields are partial.
+ * @see https://support.getgrist.com/code/interfaces/TableOperations.TableOperations/#update
+ */
+type GristTableUpdateRecord = {
+    id: number;
+    fields: Record<string, unknown>;
+};
+/** Record for `create` (no id needed). */
+type GristTableNewRecord = {
+    fields: Record<string, unknown>;
+};
+/** Record for `upsert`: `require` is the match key set, `fields` is what to write. */
+type GristTableUpsertRecord = {
+    require: Record<string, unknown>;
+    fields?: Record<string, unknown>;
+};
+/** Options accepted by `TableOperations.create / update`. */
+type GristTableOpOptions = {
+    parseStrings?: boolean;
+};
+/** Options accepted by `TableOperations.upsert`. */
+type GristTableUpsertOptions = GristTableOpOptions & {
+    add?: boolean;
+    update?: boolean;
+    onMany?: "first" | "none" | "all";
+    allowEmptyRequire?: boolean;
+};
+type GristMinimalRecord = {
+    id: number;
+};
+/** Wraps `grist.getTable(...)` / `grist.selectedTable`. */
+type GristTableOperations = {
+    getTableId: () => Promise<string>;
+    create: (records: GristTableNewRecord | GristTableNewRecord[], options?: GristTableOpOptions) => Promise<GristMinimalRecord | GristMinimalRecord[]>;
+    update: (records: GristTableUpdateRecord | GristTableUpdateRecord[], options?: GristTableOpOptions) => Promise<void>;
+    upsert: (records: GristTableUpsertRecord | GristTableUpsertRecord[], options?: GristTableUpsertOptions) => Promise<void>;
+    destroy: (recordIds: number | number[]) => Promise<void>;
+};
+/** Subset of `grist.docApi` from https://docs.getgrist.com/grist-plugin-api.js */
+type GristDocApi = {
+    getDocName: () => Promise<string> | string;
+    listTables: () => Promise<string[]> | string[];
+    fetchTable: (tableId: string) => Promise<Record<string, unknown[]>>;
+    applyUserActions: (actions: unknown[][], options?: GristApplyUserActionsOptions) => Promise<unknown>;
+    /** Present when the widget requested sufficient access (e.g. full). */
+    getAccessToken?: (options?: {
+        readOnly?: boolean;
+    }) => Promise<{
+        token: string;
+        baseUrl: string;
+    }>;
+    /** Current section's table data (often smaller than {@link fetchTable} for the whole table). */
+    fetchSelectedTable?: (options?: GristFetchSelectedOptions) => Promise<Record<string, unknown[]>>;
+    /** Single row in the current section by numeric row id. */
+    fetchSelectedRecord?: (rowId: number, options?: GristFetchSelectedOptions) => Promise<Record<string, unknown>>;
+};
+
+export type { GristApplyUserActionsOptions as G, GristColumnToMap as a, GristColumnsToMap as b, GristCursorPos as c, GristDocApi as d, GristDocumentMode as e, GristFetchSelectedOptions as f, GristFormulaKind as g, GristMinimalRecord as h, GristReadyOptions as i, GristReplicaColumn as j, GristReplicaDocument as k, GristReplicaRow as l, GristReplicaSelection as m, GristReplicaTable as n, GristRequiredAccess as o, GristRowRecord as p, GristTableNewRecord as q, GristTableOpOptions as r, GristTableOperations as s, GristTableUpdateRecord as t, GristTableUpsertOptions as u, GristTableUpsertRecord as v, GristWidgetColumnMap as w, GristWidgetConfiguration as x, GristWidgetInteraction as y, GristWidgetLinkingInfo as z };

package/dist/types-Fb2wplkv.d.ts

@@ -0,0 +1,228 @@
+/**
+ * How row bodies were populated when the replica document was built (hint only).
+ * Loaders should still treat omitted `rows` like `[]` via {@link normalizeReplicaTableInput}.
+ */
+type GristDocumentMode = "schema-only" | "schema+samples" | "schema+data";
+/**
+ * Decoded row in replica JSON (`id` + fields). Same as wire `fetchTable` row objects,
+ * but **not** columnar `Record<colId, unknown[]>` — that shape is only on `docApi.fetchTable`.
+ */
+type GristReplicaRow = GristRowRecord;
+/**
+ * Column metadata in replica JSON: Grist-native fields only (no samples / scan stats).
+ * `formulaKind` is optional UI convenience; use {@link resolveGristFormulaKind} when missing.
+ */
+type GristReplicaColumn = {
+    /** Internal row id in `_grist_Tables_column` for this column. */
+    colRef?: number;
+    type?: string;
+    label?: string;
+    parentPos?: number;
+    isFormula?: boolean;
+    formulaKind?: GristFormulaKind;
+    /** Present only when non-empty; may be truncated. */
+    formula?: string;
+    description?: string;
+    widgetOptions?: Record<string, unknown>;
+    /** Internal `_grist_Tables_column` row id of the display helper for refs. */
+    displayColRef?: number;
+    /** Internal `_grist_Tables_column` row id of the visible column. */
+    visibleColRef?: number;
+};
+type GristReplicaTable = {
+    label?: string;
+    columns?: Record<string, GristReplicaColumn>;
+    /** Decoded rows; omit or `[]` interchangeably until normalized at boundaries. */
+    rows?: GristReplicaRow[];
+    rowCount?: number;
+    dataOmitted?: boolean;
+    dataOmittedReason?: string;
+    error?: string;
+};
+/**
+ * Canonical Grist replica document: one JSON type for `getDocumentJson`, fixtures,
+ * and `createGristEmulator({ document })`.
+ */
+type GristReplicaDocument = {
+    generatedAt: string;
+    /** Optional provenance label (e.g. widget id); hosts may log this when building or persisting replicas. */
+    source?: string;
+    docName?: string;
+    mode?: GristDocumentMode;
+    tables: Record<string, GristReplicaTable>;
+    selection?: Partial<GristReplicaSelection> & {
+        tableId?: string;
+    };
+    widgetOptions?: Record<string, unknown>;
+    widgetInteraction?: GristWidgetInteraction;
+    configuration?: GristWidgetConfiguration;
+    accessToken?: {
+        token: string;
+        baseUrl: string;
+        ttlMsecs: number;
+    } | null;
+};
+
+/** Access level passed to `grist.ready({ requiredAccess })`. */
+type GristRequiredAccess = "none" | "read table" | "full";
+/**
+ * Single-column declaration in `grist.ready({ columns })`.
+ * Mirrors Grist `ColumnToMap`. See https://support.getgrist.com/code/interfaces/grist_plugin_api.ColumnToMap/
+ */
+type GristColumnToMap = {
+    /** Logical column name your widget code uses (must be a valid JSON property name). */
+    name: string;
+    /** Short label shown in the section mapping UI. */
+    title?: string | null;
+    /** Long help text for the section mapping UI. */
+    description?: string | null;
+    /** Comma-separated list of allowed Grist column types. Defaults to `"Any"`. */
+    type?: string;
+    /** Mark column as optional (default: required). */
+    optional?: boolean;
+    /** Allow multiple column assignment (resulting `mappings[name]` becomes `string[]`). */
+    allowMultiple?: boolean;
+    /** Match column type strictly (so `"Any"` matches only `"Any"`). */
+    strictType?: boolean;
+};
+/** Argument shape for `grist.ready({ columns })`. */
+type GristColumnsToMap = Array<string | GristColumnToMap>;
+/**
+ * Mapping returned by Grist between logical widget column names and real table column ids.
+ * Single mappings are `string`; `allowMultiple` columns are `string[]`.
+ */
+type GristWidgetColumnMap = Record<string, string | string[] | undefined>;
+/** A row from `grist.onRecord` or `fetchTable`. Always carries a numeric `id`. */
+type GristRowRecord<T = Record<string, unknown>> = T & {
+    id: number;
+};
+/** Arguments accepted by `grist.ready` for custom widgets. */
+type GristReadyOptions = {
+    requiredAccess?: GristRequiredAccess;
+    columns?: GristColumnsToMap;
+    allowSelectBy?: boolean;
+    hasCustomOptions?: boolean;
+    onEditOptions?: () => void | Promise<void>;
+    /** Passed to availability detection (default 10). */
+    availabilityMaxAttempts?: number;
+    /** Ms between availability polls (default 1000). */
+    availabilityIntervalMs?: number;
+    /** Log when the page is not iframe-embedded (default false). */
+    logWhenNotEmbedded?: boolean;
+};
+/** Optional second argument to `docApi.applyUserActions`. */
+type GristApplyUserActionsOptions = {
+    /** Description shown in the document undo stack. */
+    desc?: string;
+};
+/**
+ * Last `grist.ready` options mirrored with the emulator (optional on fixtures).
+ */
+type GristWidgetConfiguration = {
+    requiredAccess?: GristRequiredAccess;
+    columns?: GristColumnsToMap;
+    allowSelectBy?: boolean;
+    hasCustomOptions?: boolean;
+};
+/**
+ * How Grist treats the column (from `_grist_Tables_column` `isFormula` + `formula`).
+ * `empty_slot` is Grist's "empty column" state: `isFormula` true with no formula text.
+ */
+type GristFormulaKind = "computed" | "trigger" | "none" | "empty_slot";
+/** Options for `fetchSelectedTable` / `fetchSelectedRecord` on `docApi` (GristView). */
+type GristFetchSelectedOptions = {
+    keepEncoded?: boolean;
+    format?: "rows" | "columns" | string;
+};
+/** Argument to `grist.setCursorPos` (subset of Grist `CursorPos`). */
+type GristCursorPos = {
+    rowId?: number;
+    field?: string;
+    colRef?: string;
+    sectionId?: number;
+};
+/** Selection slice persisted on replica fixtures (emulator / widget). */
+type GristReplicaSelection = {
+    tableId: string;
+    rowId: number | "new" | null;
+    mappings?: GristWidgetColumnMap | null;
+    cursor?: GristCursorPos;
+};
+/**
+ * Linking state reported by Grist in `onOptions` settings (`InteractionOptions.linking`).
+ * @see https://github.com/gristlabs/grist-core/blob/main/app/plugin/CustomSectionAPI.ts
+ */
+type GristWidgetLinkingInfo = {
+    /** Incoming link type, or `null` when this section is not driven by a selector. */
+    asTarget: string | null;
+    /** True when another section uses this widget as a link source. */
+    asSource: boolean;
+};
+/**
+ * Second argument to `grist.onOptions` — document ↔ widget relationship (subset of Grist `InteractionOptions`).
+ */
+type GristWidgetInteraction = {
+    access_level?: string;
+    /** Present on Grist builds that report page linking; absent on older hosts. */
+    linking?: GristWidgetLinkingInfo;
+    [key: string]: unknown;
+};
+/**
+ * `TableOperations`-style record for `update`. Must include `id`; other fields are partial.
+ * @see https://support.getgrist.com/code/interfaces/TableOperations.TableOperations/#update
+ */
+type GristTableUpdateRecord = {
+    id: number;
+    fields: Record<string, unknown>;
+};
+/** Record for `create` (no id needed). */
+type GristTableNewRecord = {
+    fields: Record<string, unknown>;
+};
+/** Record for `upsert`: `require` is the match key set, `fields` is what to write. */
+type GristTableUpsertRecord = {
+    require: Record<string, unknown>;
+    fields?: Record<string, unknown>;
+};
+/** Options accepted by `TableOperations.create / update`. */
+type GristTableOpOptions = {
+    parseStrings?: boolean;
+};
+/** Options accepted by `TableOperations.upsert`. */
+type GristTableUpsertOptions = GristTableOpOptions & {
+    add?: boolean;
+    update?: boolean;
+    onMany?: "first" | "none" | "all";
+    allowEmptyRequire?: boolean;
+};
+type GristMinimalRecord = {
+    id: number;
+};
+/** Wraps `grist.getTable(...)` / `grist.selectedTable`. */
+type GristTableOperations = {
+    getTableId: () => Promise<string>;
+    create: (records: GristTableNewRecord | GristTableNewRecord[], options?: GristTableOpOptions) => Promise<GristMinimalRecord | GristMinimalRecord[]>;
+    update: (records: GristTableUpdateRecord | GristTableUpdateRecord[], options?: GristTableOpOptions) => Promise<void>;
+    upsert: (records: GristTableUpsertRecord | GristTableUpsertRecord[], options?: GristTableUpsertOptions) => Promise<void>;
+    destroy: (recordIds: number | number[]) => Promise<void>;
+};
+/** Subset of `grist.docApi` from https://docs.getgrist.com/grist-plugin-api.js */
+type GristDocApi = {
+    getDocName: () => Promise<string> | string;
+    listTables: () => Promise<string[]> | string[];
+    fetchTable: (tableId: string) => Promise<Record<string, unknown[]>>;
+    applyUserActions: (actions: unknown[][], options?: GristApplyUserActionsOptions) => Promise<unknown>;
+    /** Present when the widget requested sufficient access (e.g. full). */
+    getAccessToken?: (options?: {
+        readOnly?: boolean;
+    }) => Promise<{
+        token: string;
+        baseUrl: string;
+    }>;
+    /** Current section's table data (often smaller than {@link fetchTable} for the whole table). */
+    fetchSelectedTable?: (options?: GristFetchSelectedOptions) => Promise<Record<string, unknown[]>>;
+    /** Single row in the current section by numeric row id. */
+    fetchSelectedRecord?: (rowId: number, options?: GristFetchSelectedOptions) => Promise<Record<string, unknown>>;
+};
+
+export type { GristApplyUserActionsOptions as G, GristColumnToMap as a, GristColumnsToMap as b, GristCursorPos as c, GristDocApi as d, GristDocumentMode as e, GristFetchSelectedOptions as f, GristFormulaKind as g, GristMinimalRecord as h, GristReadyOptions as i, GristReplicaColumn as j, GristReplicaDocument as k, GristReplicaRow as l, GristReplicaSelection as m, GristReplicaTable as n, GristRequiredAccess as o, GristRowRecord as p, GristTableNewRecord as q, GristTableOpOptions as r, GristTableOperations as s, GristTableUpdateRecord as t, GristTableUpsertOptions as u, GristTableUpsertRecord as v, GristWidgetColumnMap as w, GristWidgetConfiguration as x, GristWidgetInteraction as y, GristWidgetLinkingInfo as z };