GridEvents | @sheetwrite/core

Payload map for events emitted by a Grid.

Package: @sheetwrite/core
Source: packages/core/src/types/grid.ts#L444

Members 13

change

change: ChangeEventinterface ChangeEvent {
  transaction: Transaction;
  changes: CellChange[];
  commitReason: CommitReason;
  source: OperationSource;
  epoch?: number;
}interface ChangeEvent {
  transaction: Transaction;
  changes: CellChange[];
  commitReason: CommitReason;
  source: OperationSource;
  epoch?: number;
}interface ChangeEvent {
  transaction: Transaction;
  changes: CellChange[];
  commitReason: CommitReason;
  source: OperationSource;
  epoch?: number;
}Payload of the change event; flows OUT for API submission/reconcile.API reference →;

selection

selection: { selection: Selectiontype Selection =
  | { kind: "cell"; addr: CellAddress }
  | { kind: "range"; range: Range }
  | { kind: "row"; sheet: SheetId; row: number }
  | { kind: "column"; sheet: SheetId; col: number }
  | { kind: "multi"; ranges: Range[] };type Selection =
  | { kind: "cell"; addr: CellAddress }
  | { kind: "range"; range: Range }
  | { kind: "row"; sheet: SheetId; row: number }
  | { kind: "column"; sheet: SheetId; col: number }
  | { kind: "multi"; ranges: Range[] };type Selection =
  | {
      kind: "cell";
      addr: CellAddress;
    }
  | {
      kind: "range";
      range: Range;
    }
  | {
      kind: "row";
      sheet: SheetId;
      row: number;
    }
  | {
      kind: "column";
      sheet: SheetId;
      col: number;
    }
  // … 4 more lines — see the API reference
}Current cell, range, row, column, or multi-range selection.API reference → | null };

scroll

scroll: { scrollTop: number; firstRow: number; lastRow: number; scrollLeft: number; firstVisibleColumn: number | null; lastVisibleColumn: number | null; };

edit-begin

"edit-begin": { addr: CellAddressinterface CellAddress {
  sheet: SheetId;
  row: number;
  col: number;
}interface CellAddress {
  sheet: SheetId;
  row: number;
  col: number;
}interface CellAddress {
  sheet: SheetId;
  row: number;
  col: number;
}Zero-based address of one cell on a stable sheet ID.API reference → };

edit-commit

"edit-commit": { addr: CellAddressinterface CellAddress {
  sheet: SheetId;
  row: number;
  col: number;
}interface CellAddress {
  sheet: SheetId;
  row: number;
  col: number;
}interface CellAddress {
  sheet: SheetId;
  row: number;
  col: number;
}Zero-based address of one cell on a stable sheet ID.API reference →; value: CellValuetype CellValue =
  | { kind: "literal"; value: CellScalar }
  | { kind: "ref"; target: CellAddress }
  | { kind: "formula"; src: string };type CellValue =
  | { kind: "literal"; value: CellScalar }
  | { kind: "ref"; target: CellAddress }
  | { kind: "formula"; src: string };type CellValue =
  | {
      kind: "literal";
      value: CellScalar;
    }
  | {
      kind: "ref";
      target: CellAddress;
    }
  | {
      kind: "formula";
      src: string;
    };A cell's persisted input: a literal, a cross-reference, or a formula. References resolve through the store's reference graph; formulas resolve in the WASM calculation engine.API reference → };

search

search: SearchResultinterface SearchResult {
  query: string;
  matches: CellAddress[];
  active: number;
}interface SearchResult {
  query: string;
  matches: CellAddress[];
  active: number;
}interface SearchResult {
  query: string;
  matches: CellAddress[];
  active: number;
}Ordered matches and active index produced by a grid search.API reference →;

command-state-change Command availability or formatting activity changed.

"command-state-change": GridCommandStateChangeEventinterface GridCommandStateChangeEvent {
  readonly states: Readonly<
    Record<GridCommandName, GridCommandState>
  >;
}interface GridCommandStateChangeEvent {
  readonly states: Readonly<
    Record<GridCommandName, GridCommandState>
  >;
}interface GridCommandStateChangeEvent {
  readonly states: Readonly<
    Record<
      GridCommandName,
      GridCommandState
    >
  >;
}Complete command-state snapshot emitted whenever availability or activity can change.API reference →;

mutation-rejected

"mutation-rejected": { issues: MutationIssuetype MutationIssue =
  | {
      kind: "validation";
      severity: "error" | "warning";
      ruleId: string;
      addr: CellAddress;
      value: CellValue;
      message: string;
      operationIndex: number;
    }
  | {
      kind: "protection";
      severity: "error";
      protectedRangeId: string;
      range: Range;
  // … 32 more lines — see the API reference
}type MutationIssue =
  | {
      kind: "validation";
      severity: "error" | "warning";
      ruleId: string;
      addr: CellAddress;
      value: CellValue;
      message: string;
      operationIndex: number;
    }
  | {
      kind: "protection";
      severity: "error";
      protectedRangeId: string;
      range: Range;
  // … 32 more lines — see the API reference
}type MutationIssue =
  | {
      kind: "validation";
      severity:
        "error" | "warning";
      ruleId: string;
      addr: CellAddress;
      value: CellValue;
      message: string;
      operationIndex: number;
    }
  | {
      kind: "protection";
      severity: "error";
      protectedRangeId: string;
      range: Range;
      operationIndex: number;
      message: string;
    }
  // … 29 more lines — see the API reference
}Structured warning or rejection produced while applying an operation.API reference →[] };

active-sheet Emitted after the visible sheet changes (direct call or cross-sheet scroll).

"active-sheet": { sheet: SheetIdtype SheetId = string;type SheetId = string;type SheetId = string;Stable identifier used to address a workbook sheet.API reference → };

hyperlink-activate

"hyperlink-activate": HyperlinkActivationEvent;

renderer-fallback Emitted once when the worker renderer could not be constructed and the grid fell back to the main-thread canvas renderer.

"renderer-fallback": { requested: "worker"; error: SheetwriteErrorclass SheetwriteError
  extends Error
  implements SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
  // … 73 more lines — see the API reference
}class SheetwriteError
  extends Error
  implements SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
  // … 73 more lines — see the API reference
}class SheetwriteError
  extends Error
  implements
    SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
    | "datasource-request-failed"
    | "renderer-fallback"
    | "export-failed"
  // … 75 more lines — see the API reference
}Canonical envelope for thrown and callback-delivered Sheetwrite failures.API reference → };

datasource-error

"datasource-error": { request: Omit<DataSourceRequestinterface DataSourceRequest {
  protocol: 2;
  sheet: SheetId;
  start: number;
  end: number;
  columns: readonly DataSourceColumnBand[];
  signal: AbortSignal;
  revision: number;
}interface DataSourceRequest {
  protocol: 2;
  sheet: SheetId;
  start: number;
  end: number;
  columns: readonly DataSourceColumnBand[];
  signal: AbortSignal;
  revision: number;
}interface DataSourceRequest {
  protocol: 2;
  sheet: SheetId;
  start: number;
  end: number;
  columns: readonly DataSourceColumnBand[];
  signal: AbortSignal;
  revision: number;
}Cancellable sheet rectangle requested from a DataSource.API reference →, "signal">; error: SheetwriteErrorclass SheetwriteError
  extends Error
  implements SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
  // … 73 more lines — see the API reference
}class SheetwriteError
  extends Error
  implements SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
  // … 73 more lines — see the API reference
}class SheetwriteError
  extends Error
  implements
    SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
    | "datasource-request-failed"
    | "renderer-fallback"
    | "export-failed"
  // … 75 more lines — see the API reference
}Canonical envelope for thrown and callback-delivered Sheetwrite failures.API reference →; };

export-error Built-in toolbar/context-menu export failed after its action was dispatched.

"export-error": { format: "xlsx"; error: SheetwriteErrorclass SheetwriteError
  extends Error
  implements SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
  // … 73 more lines — see the API reference
}class SheetwriteError
  extends Error
  implements SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
  // … 73 more lines — see the API reference
}class SheetwriteError
  extends Error
  implements
    SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
    | "datasource-request-failed"
    | "renderer-fallback"
    | "export-failed"
  // … 75 more lines — see the API reference
}Canonical envelope for thrown and callback-delivered Sheetwrite failures.API reference → };

Declaration

View full TypeScript declaration

export interface GridEvents {
  change: ChangeEventinterface ChangeEvent {
  transaction: Transaction;
  changes: CellChange[];
  commitReason: CommitReason;
  source: OperationSource;
  epoch?: number;
}interface ChangeEvent {
  transaction: Transaction;
  changes: CellChange[];
  commitReason: CommitReason;
  source: OperationSource;
  epoch?: number;
}interface ChangeEvent {
  transaction: Transaction;
  changes: CellChange[];
  commitReason: CommitReason;
  source: OperationSource;
  epoch?: number;
}Payload of the change event; flows OUT for API submission/reconcile.API reference →;
  selection: {
    selection: Selectiontype Selection =
  | { kind: "cell"; addr: CellAddress }
  | { kind: "range"; range: Range }
  | { kind: "row"; sheet: SheetId; row: number }
  | { kind: "column"; sheet: SheetId; col: number }
  | { kind: "multi"; ranges: Range[] };type Selection =
  | { kind: "cell"; addr: CellAddress }
  | { kind: "range"; range: Range }
  | { kind: "row"; sheet: SheetId; row: number }
  | { kind: "column"; sheet: SheetId; col: number }
  | { kind: "multi"; ranges: Range[] };type Selection =
  | {
      kind: "cell";
      addr: CellAddress;
    }
  | {
      kind: "range";
      range: Range;
    }
  | {
      kind: "row";
      sheet: SheetId;
      row: number;
    }
  | {
      kind: "column";
      sheet: SheetId;
      col: number;
    }
  // … 4 more lines — see the API reference
}Current cell, range, row, column, or multi-range selection.API reference → | null;
  };
  scroll: {
    scrollTop: number;
    firstRow: number;
    lastRow: number;
    scrollLeft: number;
    firstVisibleColumn: number | null;
    lastVisibleColumn: number | null;
  };
  "edit-begin": {
    addr: CellAddressinterface CellAddress {
  sheet: SheetId;
  row: number;
  col: number;
}interface CellAddress {
  sheet: SheetId;
  row: number;
  col: number;
}interface CellAddress {
  sheet: SheetId;
  row: number;
  col: number;
}Zero-based address of one cell on a stable sheet ID.API reference →;
  };
  "edit-commit": {
    addr: CellAddressinterface CellAddress {
  sheet: SheetId;
  row: number;
  col: number;
}interface CellAddress {
  sheet: SheetId;
  row: number;
  col: number;
}interface CellAddress {
  sheet: SheetId;
  row: number;
  col: number;
}Zero-based address of one cell on a stable sheet ID.API reference →;
    value: CellValuetype CellValue =
  | { kind: "literal"; value: CellScalar }
  | { kind: "ref"; target: CellAddress }
  | { kind: "formula"; src: string };type CellValue =
  | { kind: "literal"; value: CellScalar }
  | { kind: "ref"; target: CellAddress }
  | { kind: "formula"; src: string };type CellValue =
  | {
      kind: "literal";
      value: CellScalar;
    }
  | {
      kind: "ref";
      target: CellAddress;
    }
  | {
      kind: "formula";
      src: string;
    };A cell's persisted input: a literal, a cross-reference, or a formula. References resolve through the store's reference graph; formulas resolve in the WASM calculation engine.API reference →;
  };
  search: SearchResultinterface SearchResult {
  query: string;
  matches: CellAddress[];
  active: number;
}interface SearchResult {
  query: string;
  matches: CellAddress[];
  active: number;
}interface SearchResult {
  query: string;
  matches: CellAddress[];
  active: number;
}Ordered matches and active index produced by a grid search.API reference →;
  "command-state-change": GridCommandStateChangeEventinterface GridCommandStateChangeEvent {
  readonly states: Readonly<
    Record<GridCommandName, GridCommandState>
  >;
}interface GridCommandStateChangeEvent {
  readonly states: Readonly<
    Record<GridCommandName, GridCommandState>
  >;
}interface GridCommandStateChangeEvent {
  readonly states: Readonly<
    Record<
      GridCommandName,
      GridCommandState
    >
  >;
}Complete command-state snapshot emitted whenever availability or activity can change.API reference →;
  "mutation-rejected": {
    issues: MutationIssuetype MutationIssue =
  | {
      kind: "validation";
      severity: "error" | "warning";
      ruleId: string;
      addr: CellAddress;
      value: CellValue;
      message: string;
      operationIndex: number;
    }
  | {
      kind: "protection";
      severity: "error";
      protectedRangeId: string;
      range: Range;
  // … 32 more lines — see the API reference
}type MutationIssue =
  | {
      kind: "validation";
      severity: "error" | "warning";
      ruleId: string;
      addr: CellAddress;
      value: CellValue;
      message: string;
      operationIndex: number;
    }
  | {
      kind: "protection";
      severity: "error";
      protectedRangeId: string;
      range: Range;
  // … 32 more lines — see the API reference
}type MutationIssue =
  | {
      kind: "validation";
      severity:
        "error" | "warning";
      ruleId: string;
      addr: CellAddress;
      value: CellValue;
      message: string;
      operationIndex: number;
    }
  | {
      kind: "protection";
      severity: "error";
      protectedRangeId: string;
      range: Range;
      operationIndex: number;
      message: string;
    }
  // … 29 more lines — see the API reference
}Structured warning or rejection produced while applying an operation.API reference →[];
  };
  "active-sheet": {
    sheet: SheetIdtype SheetId = string;type SheetId = string;type SheetId = string;Stable identifier used to address a workbook sheet.API reference →;
  };
  "hyperlink-activate": HyperlinkActivationEvent;
  "renderer-fallback": {
    requested: "worker";
    error: SheetwriteErrorclass SheetwriteError
  extends Error
  implements SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
  // … 73 more lines — see the API reference
}class SheetwriteError
  extends Error
  implements SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
  // … 73 more lines — see the API reference
}class SheetwriteError
  extends Error
  implements
    SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
    | "datasource-request-failed"
    | "renderer-fallback"
    | "export-failed"
  // … 75 more lines — see the API reference
}Canonical envelope for thrown and callback-delivered Sheetwrite failures.API reference →;
  };
  "datasource-error": {
    request: Omit<DataSourceRequestinterface DataSourceRequest {
  protocol: 2;
  sheet: SheetId;
  start: number;
  end: number;
  columns: readonly DataSourceColumnBand[];
  signal: AbortSignal;
  revision: number;
}interface DataSourceRequest {
  protocol: 2;
  sheet: SheetId;
  start: number;
  end: number;
  columns: readonly DataSourceColumnBand[];
  signal: AbortSignal;
  revision: number;
}interface DataSourceRequest {
  protocol: 2;
  sheet: SheetId;
  start: number;
  end: number;
  columns: readonly DataSourceColumnBand[];
  signal: AbortSignal;
  revision: number;
}Cancellable sheet rectangle requested from a DataSource.API reference →, "signal">;
    error: SheetwriteErrorclass SheetwriteError
  extends Error
  implements SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
  // … 73 more lines — see the API reference
}class SheetwriteError
  extends Error
  implements SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
  // … 73 more lines — see the API reference
}class SheetwriteError
  extends Error
  implements
    SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
    | "datasource-request-failed"
    | "renderer-fallback"
    | "export-failed"
  // … 75 more lines — see the API reference
}Canonical envelope for thrown and callback-delivered Sheetwrite failures.API reference →;
  };
  "export-error": {
    format: "xlsx";
    error: SheetwriteErrorclass SheetwriteError
  extends Error
  implements SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
  // … 73 more lines — see the API reference
}class SheetwriteError
  extends Error
  implements SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
  // … 73 more lines — see the API reference
}class SheetwriteError
  extends Error
  implements
    SheetwriteErrorEnvelope
{
  constructor(
    code: SheetwriteErrorCode,
    operation: SheetwriteErrorOperation,
    message: string,
    options?: SheetwriteErrorOptions,
  );
  code:
    | "aborted"
    | "blocked"
    | "initialization-failed"
    | "initialization-required"
    | "datasource-request-failed"
    | "renderer-fallback"
    | "export-failed"
  // … 75 more lines — see the API reference
}Canonical envelope for thrown and callback-delivered Sheetwrite failures.API reference →;
  };
}