Canvas API signatures

Package guide · Version policy

Data and lifecycle

getValue

getValue: (rowIndex: number, columnKey: string) => unknown

replaceText

replaceText: (search: string, replacement: string, options?: Parameters<GridEngine["replaceText"]>[2]) => ReturnType<GridEngine["replaceText"]>

Source-only bounded literal replacement. One undo command; permission/validation failures leave the batch unchanged.

subscribe

subscribe: (subscriber: { readonly onEvent?: (event: GridEvent) => void; readonly onInvalidate?: (change: GridInvalidation) => void; }) => () => void

takeObserverErrors

takeObserverErrors: () => unknown[]

captureRowIdentity

captureRowIdentity: () => readonly RowId[]

Capture before external structural changes. Explicitly scans all row IDs.

refreshData

refreshData: (previousRowIds?: readonly RowId[] | "values") => void

External writes are outside history. All refresh modes clear undo/redo; values mode requires unchanged row IDs/order/count.

rowCount

rowCount: number

columns

columns: readonly Column[]

render

render: () => void

Schedule a browser repaint. It is not an identity reconciliation command; use refreshData after external changes.

updateCells

updateCells: (updates: readonly CellUpdate[]) => void

Typed values; no parsing. Column validation and writable permissions run before one atomic write. Uses visible indices.

destroy

destroy: () => void

Release this instance. Idempotent; host-owned sources and external subscriptions still need host cleanup.

Selection and clipboard

selectColumn

selectColumn: (index: number) => void

selectRow

selectRow: (index: number) => void

selectAll

selectAll: () => void

getSelection

getSelection: () => CellSelection | null

getSelectionRange

getSelectionRange: () => SelectionRange | null

getSelectionRanges

getSelectionRanges: () => SelectionRange[]

cutSelectionBlocks

cutSelectionBlocks: () => string

cancelCut

cancelCut: () => void

copySelectionBlocks

copySelectionBlocks: () => string

pasteSelectionBlocks

pasteSelectionBlocks: (text: string) => void

copySelection

copySelection: () => string

TSV text through copy permissions. No direct operating-system clipboard access in core.

paste

paste: (text: string) => void

Parse TSV/editor text and preflight the complete destination before writing.

History

undo

undo: () => boolean

Replay the last command only if current identities/values/permissions allow it; returns whether replay occurred.

redo

redo: () => boolean

Reapply a previously undone command under current identity/value/permission checks.

Views and persistence

exportState

exportState: () => GridState

Domain UI state only: excludes row data, callbacks, source transport and undo history.

restoreState

restoreState: (state: unknown) => void

Validate unknown state before committing; application permissions cannot be replaced by saved state.

exportConfiguration

exportConfiguration: () => GridConfiguration

JSON-safe column order/widths, frozen counts and core-owned view; excludes data, callbacks and history.

setView

setView: (view: LocalViewOptions) => void

Set local sort/filter criteria, not a server query. Structural commands require clearing the projected view.

view

view: Readonly<LocalViewOptions>

Structure and groups

getMerge

getMerge: (row: number, col: number) => Readonly<SelectionRange> | null

getMergedCells

getMergedCells: () => readonly Readonly<SelectionRange>[]

canMerge

canMerge: (range: SelectionRange) => boolean

mergeCells

mergeCells: (range: SelectionRange) => void

unmergeCells

unmergeCells: (range: SelectionRange) => void

getRowGroups

getRowGroups: () => readonly Readonly<RowGroup>[]

groupRows

groupRows: (start: number, end: number) => string

ungroupRows

ungroupRows: (id: string) => void

setGroupCollapsed

setGroupCollapsed: (id: string, collapsed: boolean) => void

insertColumns

insertColumns: (index: number, columns: readonly Column[]) => void

deleteColumns

deleteColumns: (indices: readonly number[]) => void

insertRows

insertRows: (index: number, rows: readonly DataRow[]) => void

deleteRows

deleteRows: (indices: readonly number[]) => void

moveRows

moveRows: (indices: readonly number[], beforeIndex: number) => void

moveColumns

moveColumns: (indices: readonly number[], beforeIndex: number) => void

Permissions and formatting

isLocked

isLocked: (target: CellLockTarget) => boolean

canManageLocks

canManageLocks: () => boolean

setLocked

setLocked: (target: CellLockTarget, locked: boolean) => void

getFormat

getFormat: (rowIndex: number, columnIndex: number) => Readonly<CellFormat>

canFormat

canFormat: (targets: readonly CellFormatTarget[]) => boolean

format

format: (targets: readonly CellFormatTarget[], patch: CellFormatPatch | null) => void

getCellPermission

getCellPermission: (rowIndex: number, columnIndex: number) => CellPermission

Layout and browser controls

setColumnEditor

setColumnEditor: (key: string, editor: ColumnEditor | null) => void

Replace a configured browser editor. Host callbacks remain trusted code.

setTheme

setTheme: (theme: Partial<GridTheme>) => void

Validated theme patch; does not recreate the grid or resize rows.

openSearch

openSearch: () => void

autoFitColumn

autoFitColumn: (index: number) => void

autoFitRow

autoFitRow: (index: number) => void

frozenRows

frozenRows: number

frozenColumns

frozenColumns: number

setFrozen

setFrozen: (rows: number, columns: number) => void

setColumnWidth

setColumnWidth: (index: number, width: number) => void

setRowHeight

setRowHeight: (index: number, height: number) => void

Construction options

Call createGrid with GridOptions. Required fields are marked; options are read at construction unless the package guide specifies a runtime setter.

Field	Required	Type
allowMerging	No	boolean | undefined
allowRowGrouping	No	boolean | undefined
canChangeLayout	No	((request: Readonly<LayoutRequest>) => boolean) | undefined
view	No	LocalViewOptions | undefined
viewMode	No	"core" | "host" | undefined
onViewChange	No	((view: LocalViewOptions) => void) | undefined
theme	No	Partial<GridTheme> | undefined
imageColumns	No	readonly string[] | undefined
avatarColumns	No	readonly string[] | undefined
mediaOptions	No	{ readonly size?: number; readonly maxVisible?: number; readonly maxConcurrentUploads?: number; readonly upload?: (file: File, context: Readonly<{ columnKey: string; signal: AbortSignal; onProgress: (loaded: number, total?: number) => void; }>) => Promise<MediaItem>; } | undefined
columnEditors	No	Readonly<Record<string, ColumnEditor>> | undefined
richTextColumns	No	Readonly<Record<string, RichTextFormat>> | undefined
markdownToHtml	No	((source: string) => string) | undefined
multilineEditor	No	boolean | undefined
editorOptions	No	{ readonly pinned?: boolean; readonly showLabel?: boolean | "scroll" | "always"; readonly guardNavigation?: boolean; } | undefined
wrapText	No	boolean | undefined
detectLinks	No	boolean | undefined
allowOpenLinks	No	boolean | undefined
contextMenuSuggestions	No	boolean | undefined
linkPreview	No	boolean | { readonly enabled?: boolean; readonly allowMetadata?: boolean; readonly load: (href: string, signal: AbortSignal) => Promise<{ readonly title?: string; readonly description?: string; readonly image?: string; }>; } | undefined
accessibility	No	"active" | "viewport" | undefined
getCellLabel	No	((rowIndex: number, columnKey: string, value: unknown) => string | undefined) | undefined
renderCell	No	CellRenderer | undefined
createEditor	No	CellEditorFactory | undefined
onEditorMount	No	((cell: Readonly<CellEditorInfo>, editor: CellEditor) => void | (() => void)) | undefined
onObserverError	No	((error: unknown) => void) | undefined
choiceEditor	No	false | ChoiceEditorOptions | undefined
motion	No	boolean | { readonly duration?: number; } | undefined
tableLockNotice	No	false | { readonly title?: string; readonly description?: string; } | undefined
selectionStyle	No	{ readonly activeCellBorderInRange?: boolean; readonly activeBorderWidth?: number; readonly headerTintOpacity?: number; readonly rangeBorderWidth?: number; readonly rangeTintOpacity?: number; } | undefined
allowColumnChanges	No	boolean | undefined
columnTypes	No	readonly ColumnType[] | undefined
onRowChange	No	((request: Readonly<RowChangeRequest>) => void) | undefined
canRowChange	No	((request: Readonly<RowChangeRequest>) => boolean) | undefined
onReorder	No	((request: Readonly<ReorderRequest>) => void) | undefined
canReorder	No	((request: Readonly<ReorderRequest>) => boolean) | undefined
onSelectionChange	No	((selection: CellSelection | null) => void) | undefined
onSelectionRangesChange	No	((ranges: readonly SelectionRange[]) => void) | undefined
onSelectionRangeChange	No	((range: SelectionRange | null) => void) | undefined
container	Yes	HTMLElement
columns	Yes	readonly Column[]
dataSource	Yes	DataSource
rowHeight	No	number | undefined
columnWidth	No	number | undefined
headerHeight	No	number | undefined
headerGroups	No	readonly HeaderGroup[] | undefined
autoRowHeight	No	boolean | undefined
measureCellHeight	No	((value: unknown, columnKey: string, width: number) => number | undefined) | undefined
indexColumn	No	boolean | undefined
permissions	No	Partial<CellPermission> | undefined
canChangeStructure	No	((request: Readonly<StructureRequest>) => boolean) | undefined
frozenRows	No	number | undefined
frozenColumns	No	number | undefined
resolveCellPermission	No	CellPermissionResolver | undefined
onEvent	No	((event: GridEvent) => void) | undefined
allowLockChanges	No	boolean | undefined
columnWidths	No	Readonly<Record<string, number>> | undefined