createGridController | @sheetwrite/core/adapter

@sheetwrite/core/adapterfunction

Create a grid and wire its lifecycle once, so the React/Vue/Svelte adapters (and any plain host) share a single, drift-free implementation instead of each re-deriving the same create → subscribe → teardown behavior.

initSheetwrite() MUST already have been awaited; createGrid throws otherwise.

Live handlers

handlers is held by reference, not copied. Every event reads the object's current fields (handlers.onGridChange?.(…)), so a host swaps callbacks across renders by mutating the fields of the same object it passed in — never by replacing the object, which the controller would not see. This is what lets a framework feed fresh closures each render without tearing the grid down and rebuilding it.

Package: @sheetwrite/core/adapter
Source: packages/core/src/grid-controller.ts#L92

Declaration

function createGridController(
  host: HTMLElement,
  options: GridOptionsinterface GridOptions {
  workbook: Workbook;
  data?: ColumnarData;
  datasource?: DataSource;
  datasourceStorage?: DataSourceStorageOptions;
  renderer?: "canvas" | "worker";
  workerUrl?: string | URL;
  theme?: Partial<Theme>;
  readOnly?: boolean;
  protectionResolver?: ProtectionResolver;
  mutationPolicy?: MutationPolicyMode;
  transactionResourceLimits?: Partial<TransactionResourceLimits>;
  renderers?: Record<string, CellRenderer>;
  overscan?: number;
  minColumns?: number;
  // … 2 more lines — see the API reference
}interface GridOptions {
  workbook: Workbook;
  data?: ColumnarData;
  datasource?: DataSource;
  datasourceStorage?: DataSourceStorageOptions;
  renderer?: "canvas" | "worker";
  workerUrl?: string | URL;
  theme?: Partial<Theme>;
  readOnly?: boolean;
  protectionResolver?: ProtectionResolver;
  mutationPolicy?: MutationPolicyMode;
  transactionResourceLimits?: Partial<TransactionResourceLimits>;
  renderers?: Record<string, CellRenderer>;
  overscan?: number;
  minColumns?: number;
  // … 2 more lines — see the API reference
}interface GridOptions {
  workbook: Workbook;
  data?: ColumnarData;
  datasource?: DataSource;
  datasourceStorage?: DataSourceStorageOptions;
  renderer?: "canvas" | "worker";
  workerUrl?: string | URL;
  theme?: Partial<Theme>;
  readOnly?: boolean;
  protectionResolver?: ProtectionResolver;
  mutationPolicy?: MutationPolicyMode;
  transactionResourceLimits?: Partial<TransactionResourceLimits>;
  renderers?: Record<
    string,
    CellRenderer
  >;
  overscan?: number;
  minColumns?: number;
  config?: GridConfig;
}Workbook, data, rendering, policy, and built-in UI options used to create a Grid.API reference →,
  handlers: GridControllerHandlersinterface GridControllerHandlers {
  onGridChange?(event: ChangeEvent): void;
  onSelectionChange?(selection: Selection | null): void;
  onViewportChange?(event: GridEvents["scroll"]): void;
  onEditBegin?(event: GridEvents["edit-begin"]): void;
  onEditCommit?(event: GridEvents["edit-commit"]): void;
  onSearch?(result: GridEvents["search"]): void;
  onActiveSheetChange?(event: GridEvents["active-sheet"]): void;
}interface GridControllerHandlers {
  onGridChange?(event: ChangeEvent): void;
  onSelectionChange?(selection: Selection | null): void;
  onViewportChange?(event: GridEvents["scroll"]): void;
  onEditBegin?(event: GridEvents["edit-begin"]): void;
  onEditCommit?(event: GridEvents["edit-commit"]): void;
  onSearch?(result: GridEvents["search"]): void;
  onActiveSheetChange?(event: GridEvents["active-sheet"]): void;
}interface GridControllerHandlers {
  onGridChange?(
    event: ChangeEvent,
  ): void;
  onSelectionChange?(
    selection: Selection | null,
  ): void;
  onViewportChange?(
    event: GridEvents["scroll"],
  ): void;
  onEditBegin?(
    event: GridEvents["edit-begin"],
  ): void;
  onEditCommit?(
    event: GridEvents["edit-commit"],
  ): void;
  onSearch?(
    result: GridEvents["search"],
  ): void;
  // … 4 more lines — see the API reference
}Event callbacks a host (a framework adapter, or any plain app) hangs off a grid's lifecycle. The controller reads these fields live on every event — see createGridController — so a host may swap any callback at any time by mutating the fields of the object it passed in, without recreating the grid. Every field is optional; a missing callback simply drops that event.API reference →,
): GridControllerinterface GridController {
  readonly grid: Grid;
  setTheme(theme: Partial<Theme> | undefined): void;
  setReadOnly(readOnly: boolean): void;
  setConfig(config: GridConfig | undefined): void;
  setOverscan(overscan: number | undefined): void;
  setMinColumns(minColumns: number | undefined): void;
  destroy(): void;
}interface GridController {
  readonly grid: Grid;
  setTheme(theme: Partial<Theme> | undefined): void;
  setReadOnly(readOnly: boolean): void;
  setConfig(config: GridConfig | undefined): void;
  setOverscan(overscan: number | undefined): void;
  setMinColumns(minColumns: number | undefined): void;
  destroy(): void;
}interface GridController {
  readonly grid: Grid;
  setTheme(
    theme:
      Partial<Theme> | undefined,
  ): void;
  setReadOnly(
    readOnly: boolean,
  ): void;
  setConfig(
    config:
      GridConfig | undefined,
  ): void;
  setOverscan(
    overscan: number | undefined,
  ): void;
  setMinColumns(
    minColumns:
      number | undefined,
  // … 3 more lines — see the API reference
}The lifecycle handle returned by createGridController: the live grid, a theme passthrough, and a single teardown that detaches every subscription and destroys the grid.API reference →