@svgrid/grid 2.6.6 → 2.6.8

package/src/svgrid-wrapper.types.ts

@@ -1,558 +1,558 @@
-import type { CellFormatConfig, ColumnDef, RowData, SvGridOptions, TableFeatures } from './core'
-// Type-only import (the reverse of SvGrid.types importing SvGridApi); TS resolves the
-// type-level cycle. Backs the generic key/value typing of `setOption` / `getOption`.
-import type { FilterOperator, Props } from './SvGrid.types'
-import type { GridExportOptions, GridClipboardOptions } from './export-format'
-import type { ChartSpec, ChartType } from './chart'
-import type { GridPredicateExpr } from './filtering/predicate-expr'
-
-// Aliased to the core union rather than restated: the API surfaces below hand
-// back whatever the grid actually filtered with, so a hand-maintained subset
-// here silently mistypes operators like 'endsWith' that reach callers at runtime.
-export type SvGridFilterOperator = FilterOperator
-
-/**
- * A serializable snapshot of everything that makes up the current "view":
- * sort, grouping, pagination, column layout (width / pinning / order /
- * visibility), and all filter surfaces. Round-trippable through
- * `api.getState()` / `api.setState()` - persist it to a URL, localStorage, or
- * a server to implement "save view" / "named views".
- */
-export type SvGridViewState = {
-  sorting: Array<{ id: string; desc: boolean }>
-  grouping: string[]
-  pagination: { pageIndex: number; pageSize: number }
-  columnWidths: Record<string, number>
-  columnPinning: { left: string[]; right: string[] }
-  columnOrder: string[]
-  /** Ids of columns currently hidden via setColumnVisible. */
-  hiddenColumns: string[]
-  globalFilter: string
-  columnFilters: Record<
-    string,
-    { operator: SvGridFilterOperator; value: string; valueTo?: string }
-  >
-  /** Facet (Excel-style value checklist) selections, keyed by column id. */
-  facetFilters: Record<string, string[]>
-  /**
-   * Advanced-filter expression (Pro). OPTIONAL, and omitted entirely when no
-   * advanced filter is set - so views saved before this feature existed, and
-   * views from grids that never use it, round-trip byte-identical. An explicit
-   * `null` clears the filter on `setState`.
-   */
-  advancedFilter?: GridPredicateExpr | null
-  /** Built-in chart panel state (present only when `charting` is on): the
-   *  ACTIVE chart, for back-compat + spread-and-tweak. */
-  chart?: {
-    open: boolean
-    type: ChartType
-    dimension: string | null
-    series: string | null
-    measure: string | null
-    reduce: 'sum' | 'avg' | 'count'
-    stacked: boolean
-  }
-  /** All charts in the tab strip (multi-chart), plus the active index. */
-  charts?: Array<{
-    title: string
-    type: ChartType
-    dimension: string | null
-    series: string | null
-    measure: string | null
-    reduce: 'sum' | 'avg' | 'count'
-    stacked: boolean | null
-    dataLabels: boolean | null
-    logScale: boolean | null
-    timeAxis: boolean | null
-    valueFormat: 'number' | 'currency' | 'percent' | 'compact' | null
-  }>
-  chartActive?: number
-}
-
-/**
- * A batch of row mutations for `api.applyTransaction`. `update` / `remove`
- * (by id) match on `getRowId`; `remove` also accepts row object references.
- */
-export type SvGridTransaction<TData> = {
-  add?: ReadonlyArray<TData>
-  update?: ReadonlyArray<TData>
-  remove?: ReadonlyArray<TData | string>
-}
-
-export type SvGridTransactionResult = {
-  added: number
-  updated: number
-  removed: number
-}
-
-/**
- * Imperative API exposed via the `<SvGrid onApiReady>` callback. Use it for
- * data, column, filter, sort, group, and visibility operations from outside
- * the component.
- */
-export type SvGridApi<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-> = {
-  // ----- Cells -----
-  /** Read a cell value from the underlying data at `rowIndex`. */
-  getCellValue(rowIndex: number, columnId: string): unknown
-  /** Write a cell value through the column's field. */
-  setCellValue(rowIndex: number, columnId: string, value: unknown): void
-  /**
-   * Programmatically begin editing a cell (as a double-click would). Returns
-   * `true` if editing started (cell exists, editable, editing enabled).
-   */
-  startEditing(rowIndex: number, columnId: string): boolean
-  /**
-   * Commit (default) or, with `cancel: true`, discard the active edit.
-   * Returns `true` if there was an edit in progress.
-   */
-  stopEditing(cancel?: boolean): boolean
-
-  // ----- Cell selection -----
-  /**
-   * Programmatically select one or more rectangular cell ranges. Each
-   * range is `[rowStart, colStart, rowEnd, colEnd]` in 0-indexed grid
-   * coordinates. Pass an empty array to clear the selection.
-   *
-   * The grid currently honours the FIRST range only (single-range
-   * engine); subsequent ranges are accepted for API forward compat
-   * but ignored. The grid's active cell jumps to the range's start
-   * corner.
-   */
-  selectCells(ranges: ReadonlyArray<readonly [number, number, number, number]>): void
-  /**
-   * Returns the current cell-selection rectangles in the same shape
-   * `selectCells` accepts. Empty array when no range is active.
-   */
-  getSelected(): Array<[number, number, number, number]>
-
-  // ----- Integrated charting (requires the `charting` prop) -----
-  /** Open the built-in chart panel. */
-  openChart(): void
-  /** Close the built-in chart panel. */
-  closeChart(): void
-  /** The live chart spec the panel is rendering, or `null`. */
-  getChartSpec(): ChartSpec | null
-  /** Select cell rectangles + open the chart panel (scopes to the range). */
-  chartRange(ranges?: ReadonlyArray<readonly [number, number, number, number]>): void
-  /**
-   * Configure the built-in chart panel's ACTIVE chart. Column references
-   * accept a column id OR field name. Opens the panel unless `open === false`.
-   */
-  configureChart(config: {
-    open?: boolean
-    type?: ChartType
-    dimension?: string | null
-    series?: string | null
-    measure?: string | null
-    reduce?: 'sum' | 'avg' | 'count'
-    stacked?: boolean
-    dataLabels?: boolean
-    logScale?: boolean
-    timeAxis?: boolean
-    valueFormat?: 'number' | 'currency' | 'percent' | 'compact'
-  }): void
-  /**
-   * Register a natural-language "chart this" handler. When set, the chart
-   * panel shows an AI button. `@svgrid/enterprise`'s `enableAiCharting(api)`
-   * fills this. Pass `null` to remove it.
-   */
-  setChartAiHandler(
-    handler: ((prompt: string) => Promise<Record<string, unknown> | null>) | null,
-  ): void
-
-  // ----- Rows -----
-  /** Add one row. `position` defaults to `'bottom'`. */
-  addRow(row: TData, position?: 'top' | 'bottom' | number): void
-  addRows(rows: ReadonlyArray<TData>, position?: 'top' | 'bottom' | number): void
-  /** Remove a row at the given data-array index. */
-  removeRow(rowIndex: number): void
-  removeRows(rowIndices: ReadonlyArray<number>): void
-  /**
-   * Apply a batch of add / update / remove mutations in a SINGLE data update
-   * (one re-render, not one per row) - the high-frequency / streaming path.
-   * `update` and `remove`-by-id match rows via `getRowId`, so set that prop
-   * for those to work; `remove` also accepts row object references. Returns
-   * the counts actually applied.
-   */
-  applyTransaction(tx: SvGridTransaction<TData>): SvGridTransactionResult
-
-  // ----- Columns -----
-  /** Add one column. `position` defaults to `'right'`. */
-  addColumn(
-    column: ColumnDef<TFeatures, TData>,
-    position?: 'left' | 'right' | number,
-  ): void
-  addColumns(
-    columns: ReadonlyArray<ColumnDef<TFeatures, TData>>,
-    position?: 'left' | 'right' | number,
-  ): void
-  /** Remove a column by id (or field when no id was provided). */
-  removeColumn(columnId: string): void
-
-  // ----- Visibility -----
-  setColumnVisible(columnId: string, visible: boolean): void
-  isColumnVisible(columnId: string): boolean
-
-  // ----- Sort / group / filter -----
-  /** Sort by one column (replaces any existing sort). Pass `null` to clear. */
-  setSort(columnId: string, direction: 'asc' | 'desc' | null): void
-  clearSort(): void
-  setGroupBy(columnIds: ReadonlyArray<string>): void
-
-  // ----- Options (runtime prop overrides) -----
-  /**
-   * Change a grid prop at runtime, e.g. `api.setOption('sortable', true)`. The
-   * override is merged over the incoming prop and the grid re-renders reactively -
-   * identical to the parent passing a new prop value. Pass `undefined` to clear the
-   * override and fall back to the prop.
-   *
-   * Note: seed-once props are NOT retroactive - `initialSorting`,
-   * `initialColumnPinning`, `initialHiddenColumns`, `columnOrder`, the initial
-   * `pageSize`, and the one-shot `externalSort` / `externalFilter` are read at mount,
-   * so overriding them later has no effect. Prefer the dedicated data path for
-   * `data` / `columns` (this works, but the sync effects are the idiomatic route).
-   */
-  setOption<K extends keyof Props<TFeatures, TData>>(key: K, value: Props<TFeatures, TData>[K] | undefined): void
-  /** Read a prop's effective value: the runtime override if set, else the incoming prop. */
-  getOption<K extends keyof Props<TFeatures, TData>>(key: K): Props<TFeatures, TData>[K]
-  /** Clear every runtime override set via `setOption`, reverting to the incoming props. */
-  resetOptions(): void
-
-  /** Set the operator filter for a column. Pass `null` to clear. */
-  setFilter(
-    columnId: string,
-    filter:
-      | {
-          operator: SvGridFilterOperator
-          value?: string
-          /** Upper bound for the `between` operator. Required when `operator === 'between'`. */
-          valueTo?: string
-          /**
-           * Optional SECOND condition on the same column, joined by `join`
-           * (multi-condition filtering, e.g. "> 100 AND < 500").
-           */
-          operator2?: SvGridFilterOperator
-          value2?: string
-          valueTo2?: string
-          /** How to combine the two conditions. Defaults to `'AND'`. */
-          join?: 'AND' | 'OR'
-        }
-      | null,
-  ): void
-  /**
-   * Set the facet (set-list, Excel-style multi-select) filter for a column.
-   * Pass an empty array or `null` to clear it. The values restore the
-   * checked state of the column-menu's value list - the engine then filters
-   * the data to rows whose cell value is in the set. Used to restore
-   * snapshots captured via `onFiltersChange`'s `selectedValues`.
-   */
-  setFacetFilter(columnId: string, values: ReadonlyArray<string> | null): void
-  clearFilter(columnId: string): void
-  /**
-   * Drop cached async `editorOptions` so the next render refetches them.
-   * Omit `columnId` to clear every column. Only affects columns whose
-   * `editorOptions` returns a Promise - static lists are never refetched.
-   */
-  refreshEditorOptions(columnId?: string): void
-  /**
-   * Clear every active column filter (menu, filter-row, set-list, global, and
-   * the advanced filter). Resets the grid to "no filtering" in a single call.
-   */
-  clearAllFilters(): void
-  /**
-   * Set the advanced-filter expression (Pro). `null` clears it. Composed with
-   * AND after the global, column and facet filters.
-   *
-   * Rows are only removed once `@svgrid/enterprise`'s `enableAdvancedFilter()`
-   * has registered a compiler. Without it the expression is stored but nothing
-   * is filtered - use `isAdvancedFilterActive()` to tell the two apart.
-   */
-  setAdvancedFilter(expr: GridPredicateExpr | null): void
-  /** The current advanced-filter expression, or `null`. */
-  getAdvancedFilter(): GridPredicateExpr | null
-  /** Clear the advanced filter, leaving other filter surfaces untouched. */
-  clearAdvancedFilter(): void
-  /** Whether an expression is set AND an engine is registered to run it. */
-  isAdvancedFilterActive(): boolean
-  /**
-   * Read the active column-menu filters as a snapshot. Keyed by column id.
-   * Returns an empty object when nothing is filtered. `valueTo` is only
-   * present when `operator === 'between'`.
-   */
-  getFilters(): Record<
-    string,
-    { operator: SvGridFilterOperator; value: string; valueTo?: string }
-  >
-
-  /**
-   * Snapshot of the DATA rows the grid is displaying right now - after
-   * filtering, sorting, grouping and pagination. Use this when you need the
-   * visible result set (e.g. to export it as CSV).
-   *
-   * Group banner rows are not included: the return type is `TData`, and a
-   * banner is not one of your rows. That matters while grouping is on, because
-   * with every group collapsed this returns an EMPTY array even though the
-   * grid visibly shows a banner per group. Count banners from `getState()`
-   * rather than from the length of this.
-   */
-  getDisplayedRows(): ReadonlyArray<TData>
-
-  /** Snapshot of the current data array (pre-pipeline). */
-  getData(): ReadonlyArray<TData>
-
-  /**
-   * Snapshot of every column the grid currently knows about, in visual
-   * order, with the human-readable header label. Use this when exporting
-   * or building a column-picker UI - the data is read once, no
-   * subscription. Hidden columns are included; check `visible` to filter.
-   */
-  getColumns(): ReadonlyArray<{
-    id: string
-    field?: string
-    header: string
-    visible: boolean
-    /** The column's `format` config, when set. Lets an exporter reproduce
-     *  the on-screen display value (currency, date pattern, etc.). */
-    format?: CellFormatConfig
-    /** Effective horizontal alignment ('left' | 'center' | 'right'). */
-    align?: 'left' | 'center' | 'right'
-    /** The column's declared `editorType`, when set. Lets a filter or
-     *  expression UI offer type-appropriate operators. */
-    editorType?: string
-  }>
-
-  // ----- Free data export (CSV / TSV / JSON + clipboard) -----
-  /**
-   * Export the grid to a **CSV** file. Free in the community grid; the
-   * richer Excel / PDF / styled formats live in @svgrid/enterprise. Values
-   * are formatted as shown on screen (pass `rawValues: true` for raw). Rows
-   * default to the current view (`rows: 'selected' | 'all'` to change).
-   * Resolves with the serialized text; pass `download: false` to skip the
-   * browser download and just get the string.
-   */
-  exportCsv(options?: GridExportOptions): Promise<string>
-  /** Export the grid to a **TSV** file (tab-separated). See `exportCsv`. */
-  exportTsv(options?: GridExportOptions): Promise<string>
-  /** Export the grid to a **JSON** file (array of `{ field: value }`). */
-  exportJson(options?: GridExportOptions): Promise<string>
-  /**
-   * Copy the grid to the system clipboard. `format: 'tsv'` (default) pastes
-   * straight into Excel / Sheets; `'csv'` / `'markdown'` also supported.
-   * Resolves with the copied text.
-   */
-  copyToClipboard(options?: GridClipboardOptions): Promise<string>
-
-  /** Clear every checked row. Emits `onRowSelectionChange({}, [])`. */
-  clearRowSelection(): void
-
-  // ----- Column layout (width + pinning) -----
-  /**
-   * Set the width of one column in pixels. Identical to dragging the
-   * column's resize handle. Width is clamped to `MIN_COLUMN_WIDTH`.
-   */
-  setColumnWidth(columnId: string, width: number): void
-  /**
-   * Snapshot of every column's current width (in pixels), keyed by
-   * column id. Columns the user has never resized AND that have no
-   * explicit `width` on their ColumnDef are reported at the grid-wide
-   * default. Useful for "save view" + URL persistence.
-   */
-  getColumnWidths(): Record<string, number>
-  /**
-   * Snap one column's width to its widest visible cell (header text +
-   * any rendered body cell). Equivalent to double-clicking the column's
-   * resize handle. The grid also exposes this through the column menu's
-   * "Autosize" item.
-   */
-  autosizeColumn(columnId: string): void
-  /** Run `autosizeColumn` on every column. */
-  autosizeAllColumns(): void
-  /**
-   * Replace the column-pinning state in one call. Each entry is a
-   * column id; the order in the array becomes the visible order along
-   * the pinned edge.
-   */
-  setColumnPinning(pinning: {
-    left?: ReadonlyArray<string>
-    right?: ReadonlyArray<string>
-  }): void
-  /** Snapshot of the current column-pinning state. */
-  getColumnPinning(): { left: string[]; right: string[] }
-
-  // ----- Column reorder -----
-  /**
-   * Replace the column order. Pass an array of column ids in the
-   * desired visual order. Unknown ids are skipped; columns not in the
-   * array keep their existing relative position after the listed ones.
-   * Fires `onColumnOrderChange` once the new order is applied. Pin
-   * groups (`columnPinning.left` / `right`) are still applied on top.
-   */
-  setColumnOrder(order: ReadonlyArray<string>): void
-  /**
-   * Snapshot of the current visual column order - the same shape the
-   * `onColumnOrderChange` callback receives. Useful for saving and
-   * restoring a view layout.
-   */
-  getColumnOrder(): string[]
-
-  // ----- Row expansion -----
-  /**
-   * Set whether a row (group node or expandable leaf) is expanded.
-   * The `id` is the engine's row id - for grouped rows that's the
-   * synthetic group key (e.g. `"department:Engineering"`).
-   */
-  setRowExpanded(id: string, expanded: boolean): void
-  /** Expand every group node in the current grouped row model. */
-  expandAllGroups(): void
-  /** Collapse every expansion - resets expanded state to {}. */
-  collapseAllGroups(): void
-
-  // ----- Undo / redo -----
-  /** Undo the most recent inline-edit. Returns false when the history is empty. */
-  undo(): boolean
-  /** Redo the most recently undone edit. Returns false when the redo stack is empty. */
-  redo(): boolean
-  /** True when there's at least one step on the undo stack. */
-  canUndo(): boolean
-  /** True when there's at least one step on the redo stack. */
-  canRedo(): boolean
-  /** Wipe both stacks (e.g. after a server save commits the buffer). */
-  clearHistory(): void
-
-  // ----- Find in grid -----
-  /** Open the built-in find overlay (Ctrl+F also opens it). */
-  openFind(): void
-  /** Close the find overlay and clear the query. */
-  closeFind(): void
-  /** Update the find query programmatically (useful for app-wide command palettes). */
-  setFindQuery(q: string): void
-  /** Snapshot of the current find hits (rowIndex / colIndex / columnId). */
-  getFindHits(): Array<{ rowIndex: number; colIndex: number; columnId: string }>
-
-  // ----- Row selection (read + write) -----
-  /**
-   * The currently selected data rows (group-header rows excluded), in row-model
-   * order. Read once - no subscription. The push-based equivalent is
-   * `onRowSelectionChange`.
-   */
-  getSelectedRows(): TData[]
-  /** The engine row ids of the selected rows. Keys into the selection record. */
-  getSelectedRowIds(): string[]
-  /**
-   * Select rows by engine row id. By default this REPLACES the selection;
-   * pass `additive: true` to add to the existing selection instead.
-   */
-  selectRows(ids: ReadonlyArray<string>, additive?: boolean): void
-  /** Select every selectable (non-group) row in the current row model. */
-  selectAllRows(): void
-  /** Flip one row's selected state by id. */
-  toggleRowSelected(id: string): void
-
-  // ----- Pagination -----
-  /**
-   * Current pagination snapshot. `total` is the post-filter row count;
-   * `pageCount` is derived from it and `pageSize` (always >= 1).
-   */
-  getPageInfo(): {
-    pageIndex: number
-    pageSize: number
-    pageCount: number
-    total: number
-  }
-  /** Jump to a 0-based page. Clamped to [0, pageCount - 1]. */
-  setPage(pageIndex: number): void
-  /** Advance one page (no-op past the last page). */
-  nextPage(): void
-  /** Go back one page (no-op before the first page). */
-  prevPage(): void
-  /** Jump to the first page. */
-  firstPage(): void
-  /** Jump to the last page. */
-  lastPage(): void
-  /** Change the page size, keeping the first visible row in view. */
-  setPageSize(pageSize: number): void
-
-  // ----- Navigation / scrolling -----
-  /**
-   * Scroll the body so the given row index is at the top of the viewport.
-   * Works with virtualization on. Index is clamped to the row count.
-   */
-  scrollToRow(rowIndex: number): void
-  /** The active (focused) cell, or null when nothing is focused. */
-  getActiveCell(): { rowIndex: number; colIndex: number; columnId: string } | null
-  /** Move the active cell. Both coordinates are clamped to the grid bounds. */
-  setActiveCell(rowIndex: number, colIndex: number): void
-
-  // ----- View state (save / restore) -----
-  /**
-   * Serializable snapshot of the whole view - sort, grouping, pagination,
-   * column layout, and every filter surface. Pair with `setState` for
-   * "save view" / URL persistence / named views.
-   */
-  getState(): SvGridViewState
-  /**
-   * Restore a view from a (partial) snapshot produced by `getState`. Only the
-   * keys present are applied, so you can restore just the columns, just the
-   * filters, etc.
-   */
-  setState(state: Partial<SvGridViewState>): void
-  /** Force a recompute of the row pipeline + a re-render. */
-  refresh(): void
-}
-
-export type SvGridWrapperProps<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-> = {
-  data: ReadonlyArray<TData>
-  columns: Array<ColumnDef<TFeatures, TData>>
-  /**
-   * Feature set from `tableFeatures({ ... })`. Optional - the `sortable` /
-   * `filterable` / `groupable` shortcuts inject the matching feature, so a
-   * grid can be configured from the boolean shortcuts alone.
-   */
-  features?: TFeatures
-  /**
-   * Capability shortcuts. Every capability is OFF by default (a bare grid is
-   * a plain read-only table); set a shortcut `true` to opt in.
-   *
-   *   `sortable`   - column sorting    (injects `rowSortingFeature`)
-   *   `filterable` - column filtering  (injects `columnFilteringFeature`)
-   *   `editable`   - inline editing    (alias of `enableInlineEditing`)
-   *   `groupable`  - grouping controls (alias of `showGroupingControls`)
-   *   `pageable`   - pagination footer (alias of `showPagination`)
-   */
-  sortable?: boolean
-  filterable?: boolean
-  editable?: boolean
-  groupable?: boolean
-  pageable?: boolean
-  options?: Partial<SvGridOptions<TFeatures, TData>>
-  loading?: boolean
-  error?: string | null
-  emptyMessage?: string
-  showGlobalFilter?: boolean
-  showColumnFilters?: boolean
-  showGroupingControls?: boolean
-  showRowSelection?: boolean
-  showPagination?: boolean
-  virtualization?: boolean
-  /** Row height in pixels. Pass a function `(rowIndex) => px` for per-row
-   *  variable heights (e.g. when wiring up an interactive row-resize). */
-  rowHeight?: number | ((rowIndex: number) => number)
-  overscan?: number
-  containerHeight?: number
-  columnVirtualization?: boolean
-  columnOverscan?: number
-  columnWidth?: number
-  showFilterMenu?: boolean
-  showFilterRow?: boolean
-  enableCellSelection?: boolean
-  enableInlineEditing?: boolean
-  enableRowSummaries?: boolean
-  /** Receives the imperative grid API when the component is ready. */
-  onApiReady?: (api: SvGridApi<TFeatures, TData>) => void
-}
+import type { CellFormatConfig, ColumnDef, RowData, SvGridOptions, TableFeatures } from './core'
+// Type-only import (the reverse of SvGrid.types importing SvGridApi); TS resolves the
+// type-level cycle. Backs the generic key/value typing of `setOption` / `getOption`.
+import type { FilterOperator, Props } from './SvGrid.types'
+import type { GridExportOptions, GridClipboardOptions } from './export-format'
+import type { ChartSpec, ChartType } from './chart'
+import type { GridPredicateExpr } from './filtering/predicate-expr'
+
+// Aliased to the core union rather than restated: the API surfaces below hand
+// back whatever the grid actually filtered with, so a hand-maintained subset
+// here silently mistypes operators like 'endsWith' that reach callers at runtime.
+export type SvGridFilterOperator = FilterOperator
+
+/**
+ * A serializable snapshot of everything that makes up the current "view":
+ * sort, grouping, pagination, column layout (width / pinning / order /
+ * visibility), and all filter surfaces. Round-trippable through
+ * `api.getState()` / `api.setState()` - persist it to a URL, localStorage, or
+ * a server to implement "save view" / "named views".
+ */
+export type SvGridViewState = {
+  sorting: Array<{ id: string; desc: boolean }>
+  grouping: string[]
+  pagination: { pageIndex: number; pageSize: number }
+  columnWidths: Record<string, number>
+  columnPinning: { left: string[]; right: string[] }
+  columnOrder: string[]
+  /** Ids of columns currently hidden via setColumnVisible. */
+  hiddenColumns: string[]
+  globalFilter: string
+  columnFilters: Record<
+    string,
+    { operator: SvGridFilterOperator; value: string; valueTo?: string }
+  >
+  /** Facet (Excel-style value checklist) selections, keyed by column id. */
+  facetFilters: Record<string, string[]>
+  /**
+   * Advanced-filter expression (Pro). OPTIONAL, and omitted entirely when no
+   * advanced filter is set - so views saved before this feature existed, and
+   * views from grids that never use it, round-trip byte-identical. An explicit
+   * `null` clears the filter on `setState`.
+   */
+  advancedFilter?: GridPredicateExpr | null
+  /** Built-in chart panel state (present only when `charting` is on): the
+   *  ACTIVE chart, for back-compat + spread-and-tweak. */
+  chart?: {
+    open: boolean
+    type: ChartType
+    dimension: string | null
+    series: string | null
+    measure: string | null
+    reduce: 'sum' | 'avg' | 'count'
+    stacked: boolean
+  }
+  /** All charts in the tab strip (multi-chart), plus the active index. */
+  charts?: Array<{
+    title: string
+    type: ChartType
+    dimension: string | null
+    series: string | null
+    measure: string | null
+    reduce: 'sum' | 'avg' | 'count'
+    stacked: boolean | null
+    dataLabels: boolean | null
+    logScale: boolean | null
+    timeAxis: boolean | null
+    valueFormat: 'number' | 'currency' | 'percent' | 'compact' | null
+  }>
+  chartActive?: number
+}
+
+/**
+ * A batch of row mutations for `api.applyTransaction`. `update` / `remove`
+ * (by id) match on `getRowId`; `remove` also accepts row object references.
+ */
+export type SvGridTransaction<TData> = {
+  add?: ReadonlyArray<TData>
+  update?: ReadonlyArray<TData>
+  remove?: ReadonlyArray<TData | string>
+}
+
+export type SvGridTransactionResult = {
+  added: number
+  updated: number
+  removed: number
+}
+
+/**
+ * Imperative API exposed via the `<SvGrid onApiReady>` callback. Use it for
+ * data, column, filter, sort, group, and visibility operations from outside
+ * the component.
+ */
+export type SvGridApi<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = {
+  // ----- Cells -----
+  /** Read a cell value from the underlying data at `rowIndex`. */
+  getCellValue(rowIndex: number, columnId: string): unknown
+  /** Write a cell value through the column's field. */
+  setCellValue(rowIndex: number, columnId: string, value: unknown): void
+  /**
+   * Programmatically begin editing a cell (as a double-click would). Returns
+   * `true` if editing started (cell exists, editable, editing enabled).
+   */
+  startEditing(rowIndex: number, columnId: string): boolean
+  /**
+   * Commit (default) or, with `cancel: true`, discard the active edit.
+   * Returns `true` if there was an edit in progress.
+   */
+  stopEditing(cancel?: boolean): boolean
+
+  // ----- Cell selection -----
+  /**
+   * Programmatically select one or more rectangular cell ranges. Each
+   * range is `[rowStart, colStart, rowEnd, colEnd]` in 0-indexed grid
+   * coordinates. Pass an empty array to clear the selection.
+   *
+   * The grid currently honours the FIRST range only (single-range
+   * engine); subsequent ranges are accepted for API forward compat
+   * but ignored. The grid's active cell jumps to the range's start
+   * corner.
+   */
+  selectCells(ranges: ReadonlyArray<readonly [number, number, number, number]>): void
+  /**
+   * Returns the current cell-selection rectangles in the same shape
+   * `selectCells` accepts. Empty array when no range is active.
+   */
+  getSelected(): Array<[number, number, number, number]>
+
+  // ----- Integrated charting (requires the `charting` prop) -----
+  /** Open the built-in chart panel. */
+  openChart(): void
+  /** Close the built-in chart panel. */
+  closeChart(): void
+  /** The live chart spec the panel is rendering, or `null`. */
+  getChartSpec(): ChartSpec | null
+  /** Select cell rectangles + open the chart panel (scopes to the range). */
+  chartRange(ranges?: ReadonlyArray<readonly [number, number, number, number]>): void
+  /**
+   * Configure the built-in chart panel's ACTIVE chart. Column references
+   * accept a column id OR field name. Opens the panel unless `open === false`.
+   */
+  configureChart(config: {
+    open?: boolean
+    type?: ChartType
+    dimension?: string | null
+    series?: string | null
+    measure?: string | null
+    reduce?: 'sum' | 'avg' | 'count'
+    stacked?: boolean
+    dataLabels?: boolean
+    logScale?: boolean
+    timeAxis?: boolean
+    valueFormat?: 'number' | 'currency' | 'percent' | 'compact'
+  }): void
+  /**
+   * Register a natural-language "chart this" handler. When set, the chart
+   * panel shows an AI button. `@svgrid/enterprise`'s `enableAiCharting(api)`
+   * fills this. Pass `null` to remove it.
+   */
+  setChartAiHandler(
+    handler: ((prompt: string) => Promise<Record<string, unknown> | null>) | null,
+  ): void
+
+  // ----- Rows -----
+  /** Add one row. `position` defaults to `'bottom'`. */
+  addRow(row: TData, position?: 'top' | 'bottom' | number): void
+  addRows(rows: ReadonlyArray<TData>, position?: 'top' | 'bottom' | number): void
+  /** Remove a row at the given data-array index. */
+  removeRow(rowIndex: number): void
+  removeRows(rowIndices: ReadonlyArray<number>): void
+  /**
+   * Apply a batch of add / update / remove mutations in a SINGLE data update
+   * (one re-render, not one per row) - the high-frequency / streaming path.
+   * `update` and `remove`-by-id match rows via `getRowId`, so set that prop
+   * for those to work; `remove` also accepts row object references. Returns
+   * the counts actually applied.
+   */
+  applyTransaction(tx: SvGridTransaction<TData>): SvGridTransactionResult
+
+  // ----- Columns -----
+  /** Add one column. `position` defaults to `'right'`. */
+  addColumn(
+    column: ColumnDef<TFeatures, TData>,
+    position?: 'left' | 'right' | number,
+  ): void
+  addColumns(
+    columns: ReadonlyArray<ColumnDef<TFeatures, TData>>,
+    position?: 'left' | 'right' | number,
+  ): void
+  /** Remove a column by id (or field when no id was provided). */
+  removeColumn(columnId: string): void
+
+  // ----- Visibility -----
+  setColumnVisible(columnId: string, visible: boolean): void
+  isColumnVisible(columnId: string): boolean
+
+  // ----- Sort / group / filter -----
+  /** Sort by one column (replaces any existing sort). Pass `null` to clear. */
+  setSort(columnId: string, direction: 'asc' | 'desc' | null): void
+  clearSort(): void
+  setGroupBy(columnIds: ReadonlyArray<string>): void
+
+  // ----- Options (runtime prop overrides) -----
+  /**
+   * Change a grid prop at runtime, e.g. `api.setOption('sortable', true)`. The
+   * override is merged over the incoming prop and the grid re-renders reactively -
+   * identical to the parent passing a new prop value. Pass `undefined` to clear the
+   * override and fall back to the prop.
+   *
+   * Note: seed-once props are NOT retroactive - `initialSorting`,
+   * `initialColumnPinning`, `initialHiddenColumns`, `columnOrder`, the initial
+   * `pageSize`, and the one-shot `externalSort` / `externalFilter` are read at mount,
+   * so overriding them later has no effect. Prefer the dedicated data path for
+   * `data` / `columns` (this works, but the sync effects are the idiomatic route).
+   */
+  setOption<K extends keyof Props<TFeatures, TData>>(key: K, value: Props<TFeatures, TData>[K] | undefined): void
+  /** Read a prop's effective value: the runtime override if set, else the incoming prop. */
+  getOption<K extends keyof Props<TFeatures, TData>>(key: K): Props<TFeatures, TData>[K]
+  /** Clear every runtime override set via `setOption`, reverting to the incoming props. */
+  resetOptions(): void
+
+  /** Set the operator filter for a column. Pass `null` to clear. */
+  setFilter(
+    columnId: string,
+    filter:
+      | {
+          operator: SvGridFilterOperator
+          value?: string
+          /** Upper bound for the `between` operator. Required when `operator === 'between'`. */
+          valueTo?: string
+          /**
+           * Optional SECOND condition on the same column, joined by `join`
+           * (multi-condition filtering, e.g. "> 100 AND < 500").
+           */
+          operator2?: SvGridFilterOperator
+          value2?: string
+          valueTo2?: string
+          /** How to combine the two conditions. Defaults to `'AND'`. */
+          join?: 'AND' | 'OR'
+        }
+      | null,
+  ): void
+  /**
+   * Set the facet (set-list, Excel-style multi-select) filter for a column.
+   * Pass an empty array or `null` to clear it. The values restore the
+   * checked state of the column-menu's value list - the engine then filters
+   * the data to rows whose cell value is in the set. Used to restore
+   * snapshots captured via `onFiltersChange`'s `selectedValues`.
+   */
+  setFacetFilter(columnId: string, values: ReadonlyArray<string> | null): void
+  clearFilter(columnId: string): void
+  /**
+   * Drop cached async `editorOptions` so the next render refetches them.
+   * Omit `columnId` to clear every column. Only affects columns whose
+   * `editorOptions` returns a Promise - static lists are never refetched.
+   */
+  refreshEditorOptions(columnId?: string): void
+  /**
+   * Clear every active column filter (menu, filter-row, set-list, global, and
+   * the advanced filter). Resets the grid to "no filtering" in a single call.
+   */
+  clearAllFilters(): void
+  /**
+   * Set the advanced-filter expression (Pro). `null` clears it. Composed with
+   * AND after the global, column and facet filters.
+   *
+   * Rows are only removed once `@svgrid/enterprise`'s `enableAdvancedFilter()`
+   * has registered a compiler. Without it the expression is stored but nothing
+   * is filtered - use `isAdvancedFilterActive()` to tell the two apart.
+   */
+  setAdvancedFilter(expr: GridPredicateExpr | null): void
+  /** The current advanced-filter expression, or `null`. */
+  getAdvancedFilter(): GridPredicateExpr | null
+  /** Clear the advanced filter, leaving other filter surfaces untouched. */
+  clearAdvancedFilter(): void
+  /** Whether an expression is set AND an engine is registered to run it. */
+  isAdvancedFilterActive(): boolean
+  /**
+   * Read the active column-menu filters as a snapshot. Keyed by column id.
+   * Returns an empty object when nothing is filtered. `valueTo` is only
+   * present when `operator === 'between'`.
+   */
+  getFilters(): Record<
+    string,
+    { operator: SvGridFilterOperator; value: string; valueTo?: string }
+  >
+
+  /**
+   * Snapshot of the DATA rows the grid is displaying right now - after
+   * filtering, sorting, grouping and pagination. Use this when you need the
+   * visible result set (e.g. to export it as CSV).
+   *
+   * Group banner rows are not included: the return type is `TData`, and a
+   * banner is not one of your rows. That matters while grouping is on, because
+   * with every group collapsed this returns an EMPTY array even though the
+   * grid visibly shows a banner per group. Count banners from `getState()`
+   * rather than from the length of this.
+   */
+  getDisplayedRows(): ReadonlyArray<TData>
+
+  /** Snapshot of the current data array (pre-pipeline). */
+  getData(): ReadonlyArray<TData>
+
+  /**
+   * Snapshot of every column the grid currently knows about, in visual
+   * order, with the human-readable header label. Use this when exporting
+   * or building a column-picker UI - the data is read once, no
+   * subscription. Hidden columns are included; check `visible` to filter.
+   */
+  getColumns(): ReadonlyArray<{
+    id: string
+    field?: string
+    header: string
+    visible: boolean
+    /** The column's `format` config, when set. Lets an exporter reproduce
+     *  the on-screen display value (currency, date pattern, etc.). */
+    format?: CellFormatConfig
+    /** Effective horizontal alignment ('left' | 'center' | 'right'). */
+    align?: 'left' | 'center' | 'right'
+    /** The column's declared `editorType`, when set. Lets a filter or
+     *  expression UI offer type-appropriate operators. */
+    editorType?: string
+  }>
+
+  // ----- Free data export (CSV / TSV / JSON + clipboard) -----
+  /**
+   * Export the grid to a **CSV** file. Free in the community grid; the
+   * richer Excel / PDF / styled formats live in @svgrid/enterprise. Values
+   * are formatted as shown on screen (pass `rawValues: true` for raw). Rows
+   * default to the current view (`rows: 'selected' | 'all'` to change).
+   * Resolves with the serialized text; pass `download: false` to skip the
+   * browser download and just get the string.
+   */
+  exportCsv(options?: GridExportOptions): Promise<string>
+  /** Export the grid to a **TSV** file (tab-separated). See `exportCsv`. */
+  exportTsv(options?: GridExportOptions): Promise<string>
+  /** Export the grid to a **JSON** file (array of `{ field: value }`). */
+  exportJson(options?: GridExportOptions): Promise<string>
+  /**
+   * Copy the grid to the system clipboard. `format: 'tsv'` (default) pastes
+   * straight into Excel / Sheets; `'csv'` / `'markdown'` also supported.
+   * Resolves with the copied text.
+   */
+  copyToClipboard(options?: GridClipboardOptions): Promise<string>
+
+  /** Clear every checked row. Emits `onRowSelectionChange({}, [])`. */
+  clearRowSelection(): void
+
+  // ----- Column layout (width + pinning) -----
+  /**
+   * Set the width of one column in pixels. Identical to dragging the
+   * column's resize handle. Width is clamped to `MIN_COLUMN_WIDTH`.
+   */
+  setColumnWidth(columnId: string, width: number): void
+  /**
+   * Snapshot of every column's current width (in pixels), keyed by
+   * column id. Columns the user has never resized AND that have no
+   * explicit `width` on their ColumnDef are reported at the grid-wide
+   * default. Useful for "save view" + URL persistence.
+   */
+  getColumnWidths(): Record<string, number>
+  /**
+   * Snap one column's width to its widest visible cell (header text +
+   * any rendered body cell). Equivalent to double-clicking the column's
+   * resize handle. The grid also exposes this through the column menu's
+   * "Autosize" item.
+   */
+  autosizeColumn(columnId: string): void
+  /** Run `autosizeColumn` on every column. */
+  autosizeAllColumns(): void
+  /**
+   * Replace the column-pinning state in one call. Each entry is a
+   * column id; the order in the array becomes the visible order along
+   * the pinned edge.
+   */
+  setColumnPinning(pinning: {
+    left?: ReadonlyArray<string>
+    right?: ReadonlyArray<string>
+  }): void
+  /** Snapshot of the current column-pinning state. */
+  getColumnPinning(): { left: string[]; right: string[] }
+
+  // ----- Column reorder -----
+  /**
+   * Replace the column order. Pass an array of column ids in the
+   * desired visual order. Unknown ids are skipped; columns not in the
+   * array keep their existing relative position after the listed ones.
+   * Fires `onColumnOrderChange` once the new order is applied. Pin
+   * groups (`columnPinning.left` / `right`) are still applied on top.
+   */
+  setColumnOrder(order: ReadonlyArray<string>): void
+  /**
+   * Snapshot of the current visual column order - the same shape the
+   * `onColumnOrderChange` callback receives. Useful for saving and
+   * restoring a view layout.
+   */
+  getColumnOrder(): string[]
+
+  // ----- Row expansion -----
+  /**
+   * Set whether a row (group node or expandable leaf) is expanded.
+   * The `id` is the engine's row id - for grouped rows that's the
+   * synthetic group key (e.g. `"department:Engineering"`).
+   */
+  setRowExpanded(id: string, expanded: boolean): void
+  /** Expand every group node in the current grouped row model. */
+  expandAllGroups(): void
+  /** Collapse every expansion - resets expanded state to {}. */
+  collapseAllGroups(): void
+
+  // ----- Undo / redo -----
+  /** Undo the most recent inline-edit. Returns false when the history is empty. */
+  undo(): boolean
+  /** Redo the most recently undone edit. Returns false when the redo stack is empty. */
+  redo(): boolean
+  /** True when there's at least one step on the undo stack. */
+  canUndo(): boolean
+  /** True when there's at least one step on the redo stack. */
+  canRedo(): boolean
+  /** Wipe both stacks (e.g. after a server save commits the buffer). */
+  clearHistory(): void
+
+  // ----- Find in grid -----
+  /** Open the built-in find overlay (Ctrl+F also opens it). */
+  openFind(): void
+  /** Close the find overlay and clear the query. */
+  closeFind(): void
+  /** Update the find query programmatically (useful for app-wide command palettes). */
+  setFindQuery(q: string): void
+  /** Snapshot of the current find hits (rowIndex / colIndex / columnId). */
+  getFindHits(): Array<{ rowIndex: number; colIndex: number; columnId: string }>
+
+  // ----- Row selection (read + write) -----
+  /**
+   * The currently selected data rows (group-header rows excluded), in row-model
+   * order. Read once - no subscription. The push-based equivalent is
+   * `onRowSelectionChange`.
+   */
+  getSelectedRows(): TData[]
+  /** The engine row ids of the selected rows. Keys into the selection record. */
+  getSelectedRowIds(): string[]
+  /**
+   * Select rows by engine row id. By default this REPLACES the selection;
+   * pass `additive: true` to add to the existing selection instead.
+   */
+  selectRows(ids: ReadonlyArray<string>, additive?: boolean): void
+  /** Select every selectable (non-group) row in the current row model. */
+  selectAllRows(): void
+  /** Flip one row's selected state by id. */
+  toggleRowSelected(id: string): void
+
+  // ----- Pagination -----
+  /**
+   * Current pagination snapshot. `total` is the post-filter row count;
+   * `pageCount` is derived from it and `pageSize` (always >= 1).
+   */
+  getPageInfo(): {
+    pageIndex: number
+    pageSize: number
+    pageCount: number
+    total: number
+  }
+  /** Jump to a 0-based page. Clamped to [0, pageCount - 1]. */
+  setPage(pageIndex: number): void
+  /** Advance one page (no-op past the last page). */
+  nextPage(): void
+  /** Go back one page (no-op before the first page). */
+  prevPage(): void
+  /** Jump to the first page. */
+  firstPage(): void
+  /** Jump to the last page. */
+  lastPage(): void
+  /** Change the page size, keeping the first visible row in view. */
+  setPageSize(pageSize: number): void
+
+  // ----- Navigation / scrolling -----
+  /**
+   * Scroll the body so the given row index is at the top of the viewport.
+   * Works with virtualization on. Index is clamped to the row count.
+   */
+  scrollToRow(rowIndex: number): void
+  /** The active (focused) cell, or null when nothing is focused. */
+  getActiveCell(): { rowIndex: number; colIndex: number; columnId: string } | null
+  /** Move the active cell. Both coordinates are clamped to the grid bounds. */
+  setActiveCell(rowIndex: number, colIndex: number): void
+
+  // ----- View state (save / restore) -----
+  /**
+   * Serializable snapshot of the whole view - sort, grouping, pagination,
+   * column layout, and every filter surface. Pair with `setState` for
+   * "save view" / URL persistence / named views.
+   */
+  getState(): SvGridViewState
+  /**
+   * Restore a view from a (partial) snapshot produced by `getState`. Only the
+   * keys present are applied, so you can restore just the columns, just the
+   * filters, etc.
+   */
+  setState(state: Partial<SvGridViewState>): void
+  /** Force a recompute of the row pipeline + a re-render. */
+  refresh(): void
+}
+
+export type SvGridWrapperProps<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = {
+  data: ReadonlyArray<TData>
+  columns: Array<ColumnDef<TFeatures, TData>>
+  /**
+   * Feature set from `tableFeatures({ ... })`. Optional - the `sortable` /
+   * `filterable` / `groupable` shortcuts inject the matching feature, so a
+   * grid can be configured from the boolean shortcuts alone.
+   */
+  features?: TFeatures
+  /**
+   * Capability shortcuts. Every capability is OFF by default (a bare grid is
+   * a plain read-only table); set a shortcut `true` to opt in.
+   *
+   *   `sortable`   - column sorting    (injects `rowSortingFeature`)
+   *   `filterable` - column filtering  (injects `columnFilteringFeature`)
+   *   `editable`   - inline editing    (alias of `enableInlineEditing`)
+   *   `groupable`  - grouping controls (alias of `showGroupingControls`)
+   *   `pageable`   - pagination footer (alias of `showPagination`)
+   */
+  sortable?: boolean
+  filterable?: boolean
+  editable?: boolean
+  groupable?: boolean
+  pageable?: boolean
+  options?: Partial<SvGridOptions<TFeatures, TData>>
+  loading?: boolean
+  error?: string | null
+  emptyMessage?: string
+  showGlobalFilter?: boolean
+  showColumnFilters?: boolean
+  showGroupingControls?: boolean
+  showRowSelection?: boolean
+  showPagination?: boolean
+  virtualization?: boolean
+  /** Row height in pixels. Pass a function `(rowIndex) => px` for per-row
+   *  variable heights (e.g. when wiring up an interactive row-resize). */
+  rowHeight?: number | ((rowIndex: number) => number)
+  overscan?: number
+  containerHeight?: number
+  columnVirtualization?: boolean
+  columnOverscan?: number
+  columnWidth?: number
+  showFilterMenu?: boolean
+  showFilterRow?: boolean
+  enableCellSelection?: boolean
+  enableInlineEditing?: boolean
+  enableRowSummaries?: boolean
+  /** Receives the imperative grid API when the component is ready. */
+  onApiReady?: (api: SvGridApi<TFeatures, TData>) => void
+}