Types

Every type exported from grist-widget-sdk. Grouped by area.

Core results

type GristRowRecord<T = GristRecordFields> = T & { id: number }
type GristRecordFields = Record<string, unknown>

type GristWidgetMode = "empty" | "row" | "new-row"
type GristWidgetStatus = "booting" | "unavailable" | "ready" | "error"
type GristActionStatus = "idle" | "running" | "error"
type GristTheme = "light" | "dark"

type GristMappings = Record<string, string | string[]>
type GristColumnMappingStatus = {
  ok: boolean
  /** True until the host reports mappings; do not gate UI or alerts while pending. */
  pending?: boolean
  missing: string[]
  emptyMultiples: string[]
}

Provider / hook options

type GristReadyOptions = {
  requiredAccess?: "none" | "read table" | "full"
  columns?: Array<GristColumnDescriptor | string>
  allowSelectBy?: boolean
  hasCustomOptions?: boolean
  onEditOptions?: () => void

  availabilityMaxAttempts?: number  // default 30
  availabilityIntervalMs?: number   // default 200
  logWhenNotEmbedded?: boolean      // default false
}

type GristColumnDescriptor =
  | string
  | {
      name: string
      title?: string
      description?: string
      type?: string
      optional?: boolean
      allowMultiple?: boolean
      strictType?: boolean
    }

type UseGristOptions = GristReadyOptions

Result types

type UseGristResult<TRow = GristRecordFields, TMapped = TRow> = {
  // Status, selection, writes, reads, options, linking, REST, theme.
  // See /api/use-grist for the full enumeration.
}

type UseGristStatusResult = { ... }       // /api/slice-hooks
type UseGristSelectionResult = { ... }    // /api/slice-hooks
type UseGristWritesResult = { ... }       // /api/slice-hooks
type UseGristThemeResult = { theme: GristTheme | null }

Linking

type GristCursorPos = {
  rowId?: number
  field?: string
  colRef?: string
  sectionId?: number
}

Writes

type GristActionTuple = [string, ...unknown[]]

type GristTableOperations = {
  getTableId(): Promise<string>
  create(records, options?): Promise<{ id: number } | { id: number }[]>
  update(records, options?): Promise<void>
  upsert(records, options?): Promise<void>
  destroy(recordIds: number | number[]): Promise<void>
}

type GristUpsertOptions = {
  add?: boolean
  update?: boolean
  onMany?: "first" | "none" | "all"
  allowEmptyRequire?: boolean
  parseStrings?: boolean
}

Reads

type GristFetchTableRowsOptions<T> = {
  columns?: Record<string, GristReplicaColumn>
  order?: "grist" | "id" | "none"
  safeParse?: boolean | GristSafeParseOptions
  onSafeParseIssues?: (issues: GristSafeParseIssue[]) => void
}

Attachments / REST

type GristFetchedAttachmentBlob = { blob: Blob; contentType: string }
type GristFetchedAttachment = { base64: string; contentType: string }

type GristFetchWithAuthOptions = RequestInit & { readOnly?: boolean }
type GristAccessToken = { token: string; baseUrl: string }

Replica document

See /design/replica-document for full discussion.

type GristReplicaDocument = {
  generatedAt: string
  source?: string
  mode?: "schema-only" | "schema+samples" | "schema+data"
  docName?: string
  selection?: GristReplicaSelection
  tables: Record<string, GristReplicaTable>
}

type GristReplicaTable = {
  label?: string
  columns: Record<string, GristReplicaColumn>
  rows?: GristReplicaRow[]
  rowCount?: number
  dataOmitted?: boolean
  error?: string
}

type GristReplicaColumn = {
  type: string
  label?: string
  description?: string
  isFormula?: boolean
  widgetOptions?: Record<string, unknown>
}

type GristReplicaRow = { id: number; [col: string]: unknown }

type GristReplicaSelection = {
  tableId?: string
  rowId?: number | null
  rowIds?: number[]
  mode?: GristWidgetMode
}

Safe parsing

type GristSafeParseIssue = {
  code: string
  message: string
  meta?: unknown
  colId?: string
  rowId?: number
}

type GristSafeParseCellResult<T> = {
  ok: boolean
  typedValue: T | null
  displayValue: unknown
  raw: unknown
  issues: GristSafeParseIssue[]
}

type GristSafeParseOptions = {
  refMode?: "detailed" | "id"
  fallbackUntypedToString?: boolean
  validateChoices?: boolean
  helperValues?: Record<string, unknown>
}

Alerts

type GristSdkAlertDescriptor = {
  id: "column-mapping" | "action-error" | "unavailable" | "error"
  kind: "info" | "warning" | "destructive"
  ariaRole: "status" | "alert"
  message: string
}

type GristSdkAlertOptions = {
  columnMappingHint?: string
  actionErrorHint?: string
}

Component props

type GristWidgetProviderProps = {
  options?: GristReadyOptions
  children: React.ReactNode
}

type GristBoundaryProps = {
  children: React.ReactNode
  bootingFallback?: React.ReactNode
  unavailableFallback?:
    | React.ReactNode
    | ((ctx: { reload: () => Promise<void>; isReloading: boolean }) => React.ReactNode)
  errorFallback?:
    | React.ReactNode
    | ((error: string, ctx: { reload: () => Promise<void>; isReloading: boolean }) => React.ReactNode)
  unavailableGraceMs?: number
  className?: string
  appearance?: GristBoundaryAppearance
}

type GristBoundaryAppearance = {
  spinner?: React.ReactNode
  layout?: (children: React.ReactNode) => React.ReactNode
  bootingMessage?: string
  unavailableTitle?: string
  unavailableMessage?: string
  errorTitle?: string
}