Core API signatures

Package guide · Version policy

Data and lifecycle

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.

sourceRowCount

sourceRowCount: number

getRowId

getRowId: (row: number) => RowId

columns

columns: readonly Readonly<{ permissions?: CellPermissionPolicy; defaultValue?: unknown; key: string; title: string; editable?: boolean; parse?: (text: string) => unknown; validate?: (value: unknown) => string | undefined; invalidInput?: "reject" | "allow"; }>[]

rowCount

rowCount: number

getValue

getValue: (row: number, key: string) => unknown

editCell

editCell: (row: number, col: number, text: string) => void

Editor-style text command: applies parsers, editable/writable permissions and validation.

updateCells

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

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

replaceText

replaceText: (search: string, replacement: string, options?: { readonly scope?: "view" | "selection"; readonly caseSensitive?: boolean; }) => Readonly<{ changedCells: number; matches: number; }>

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

destroy

destroy: () => void

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

Selection and clipboard

getSelection

getSelection: () => CellSelection | null

getSelectionRange

getSelectionRange: () => SelectionRange | null

getSelectionRanges

getSelectionRanges: () => SelectionRange[]

select

select: (row: number, col: number, extend?: boolean) => boolean

selectRange

selectRange: (range: SelectionRange, mode?: "replace" | "add" | "extend") => boolean

clearSelection

clearSelection: () => void

cutSelectionBlocks

cutSelectionBlocks: () => string

cancelCut

cancelCut: () => void

pasteCutSelectionBlocks

pasteCutSelectionBlocks: (text: string) => 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.

canUndo

canUndo: () => boolean

canRedo

canRedo: () => boolean

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.

setView

setView: (next: LocalViewOptions) => void

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

view

view: Readonly<LocalViewOptions>

exportConfiguration

exportConfiguration: () => GridConfiguration

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

Structure and groups

getMergedCells

getMergedCells: () => readonly Readonly<{ startRow: number; endRow: number; startColumn: number; endColumn: number; }>[]

getMerge

getMerge: (row: number, col: number) => Readonly<{ startRow: number; endRow: number; startColumn: number; endColumn: number; }> | null

canMerge

canMerge: (range: SelectionRange) => boolean

mergeCells

mergeCells: (range: SelectionRange) => void

unmergeCells

unmergeCells: (range: SelectionRange) => void

getRowGroups

getRowGroups: () => readonly Readonly<{ id: string; startRow: number; endRow: number; collapsed: boolean; }>[]

groupRows

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

ungroupRows

ungroupRows: (id: string) => void

setGroupCollapsed

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

insertColumns

insertColumns: (index: number, added: 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

getCellPermission

getCellPermission: (row: number, col: number) => CellPermission

getFormat

getFormat: (row: number, col: number) => Readonly<CellFormat>

canFormat

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

format

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

isLocked

isLocked: (target: CellLockTarget) => boolean

canManageLocks

canManageLocks: () => boolean

setLocked

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

Layout and browser controls

frozenRows

frozenRows: number

frozenColumns

frozenColumns: number

getViewport

getViewport: (viewport: ViewportOptions) => Readonly<{ hitTest(x: number, y: number): { row: number; col: number; } | null; cellRect(row: number, col: number): Readonly<{ x: number; y: number; width: number; height: number; clip: Readonly<{ x: number; y: number; width: number; height: number; }>; }>; width: number; height: number; scrollLeft: number; scrollTop: number; frozenWidth: number; frozenHeight: number; regions: readonly ViewportRegion[]; }>

canChangeLayout

canChangeLayout: (request: LayoutRequest) => boolean

getRowSourceIndex

getRowSourceIndex: (row: number) => number

rows

rows: Readonly<{ size: (i: number) => number; position: (i: number) => number; indexAt: (offset: number) => number; range: (offset: number, extent: number) => { start: number; end: number; }; }>

columnsLayout

columnsLayout: Readonly<{ size: (index: number) => number; position: (index: number) => number; indexAt: (offset: number) => number; range: (offset: number, extent: number) => { start: number; end: number; }; }>

canChangeStructure

canChangeStructure: (request: Readonly<StructureRequest>) => boolean

isRowHeightManual

isRowHeightManual: (index: number) => boolean

measureRowHeight

measureRowHeight: (index: number, size: number) => void

canEdit

canEdit: (row: number, col: number) => boolean

canPaste

canPaste: () => boolean

addSelection

addSelection: (row: number, col: number) => boolean

setFrozen

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

setColumnWidth

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

setRowHeight

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

Construction options

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

Field	Required	Type
onObserverError	No	((error: unknown) => void) | undefined
allowMerging	No	boolean | undefined
allowRowGrouping	No	boolean | undefined
canChangeLayout	No	((request: Readonly<LayoutRequest>) => boolean) | undefined
columns	Yes	readonly Column[]
view	No	LocalViewOptions | undefined
canChangeStructure	No	((request: Readonly<StructureRequest>) => boolean) | undefined
dataSource	Yes	DataSource
permissions	No	Partial<CellPermission> | undefined
resolveCellPermission	No	CellPermissionResolver | undefined
onEvent	No	((event: GridEvent) => void) | undefined
rowHeight	No	number | undefined
columnWidth	No	number | undefined
columnWidths	No	Readonly<Record<string, number>> | undefined
allowLockChanges	No	boolean | undefined
frozenRows	No	number | undefined
frozenColumns	No	number | undefined
onInvalidate	No	((change: GridInvalidation) => void) | undefined