@svgrid/grid 2.6.20 → 2.6.22

package/dist/SvGrid.css

@@ -1573,7 +1573,7 @@ select.sv-grid-fr-editor {
   position: relative;
 }
 /* Declarative cell validation (column `validate` hook). Invalid cells get a
- * soft red wash and a red inset ring - Handsontable's `htInvalid` look. The
+ * soft red wash and a red inset ring - the conventional spreadsheet invalid-cell look. The
  * value keeps rendering as-is; the message (if any) shows as the tooltip. */
 .sv-grid-cell-invalid {
   background-color: var(--sg-invalid-bg, rgba(239, 68, 68, 0.14)) !important;

package/dist/SvGrid.svelte

@@ -15,6 +15,8 @@
   } from "./index";
   import "./sv-grid-scrollbar";
   import "./SvGrid.css";
+  import type { RowResizeOptions } from "./row-resize";
+  import type { ColumnResizeOptions } from "./column-resize";
   import {
     RenderSnippetConfig,
     RenderComponentConfig,
@@ -167,7 +169,9 @@
   const hideTooltip = $derived(ctrl.hideTooltip);
   const findHits = $derived(ctrl.findHits);
   const headerHeight = $derived(ctrl.headerHeight);
-  const resizingColumnId = $derived(ctrl.resizingColumnId);
+  // Column resizing has always been unconditional; `columnResize={false}` is
+  // the opt-out, so the default has to stay on when the prop is absent.
+  const columnResizeEnabled = $derived(opt.columnResize === true);
   const selectionColumnWidth = $derived(ctrl.selectionColumnWidth);
   const rowNumberColumnWidth = $derived(ctrl.rowNumberColumnWidth);
   const showRowNumbersEffective = $derived(ctrl.showRowNumbersEffective);
@@ -184,6 +188,7 @@
     ctrl.showInlineColumnFilterEffective,
   );
   const showRowSelectionEffective = $derived(ctrl.showRowSelectionEffective);
+  const rowSummariesEnabled = $derived(ctrl.rowSummariesEnabled);
   const grid = $derived(ctrl.grid);
   const allColumns = $derived(ctrl.allColumns);
   const headerGroups = $derived(ctrl.headerGroups);
@@ -263,6 +268,23 @@
   // Row-grouping display modes: group state lives in synthetic columns instead
   // of a full-width banner row.
   const groupColumnMode = $derived(ctrl.groupColumnMode);
+  /**
+   * True when a cell's content needs none of the wrapper snippets.
+   *
+   * A cell body normally renders through `cellBodyWithFormat` ->
+   * `cellBodyFormatted` -> `cellBody`, and with no grouping, no tree data and
+   * no conditional formats the first two are pure pass-throughs: three snippet
+   * renders and two `{#if}` blocks per cell to reach content that one render
+   * produces. Measured by ablation, that chain is 4.2 ms of a 17.4 ms mount at
+   * 28 rows x 9 columns - about a quarter of the whole mount, and the largest
+   * single per-cell cost.
+   *
+   * Computed once per render rather than per cell, so the fast path costs one
+   * boolean read at each of the ~250 cells instead of two snippet frames.
+   */
+  const plainCellBody = $derived(
+    !groupColumnMode && !treeData && !hasConditionalFormats,
+  );
   const autoGroupCell = $derived(ctrl.autoGroupCell);
   const isAutoGroupColumn = (id: string): boolean =>
     id === "__autoGroup" || id.startsWith("__group_");
@@ -279,7 +301,60 @@
   // The fixed row height, matching what the virtualized path takes from the virtualizer.
   // The non-virtualized (`virtualization={false}`) body must apply this too, else its rows
   // fall back to content height and look shorter than a virtualized grid's.
+  /**
+   * `rowResize` and `columnResize` are both opt-in and both default to OFF, so
+   * neither module is imported statically - a grid that leaves them alone must
+   * not carry their bytes. This wraps an action so its module is fetched on
+   * first enable and never otherwise. The handles appear a microtask after the
+   * first paint, which is invisible for a drag affordance.
+   *
+   * One helper for both: two hand-rolled copies of this bookkeeping would cost
+   * more base bundle than the deferral saves.
+   */
+  type LazyHandle<O> = { update(o: O): void; destroy(): void };
+  function lazyAction<O extends { disabled?: boolean }>(
+    load: () => Promise<(node: HTMLElement, opts: O) => LazyHandle<O>>,
+  ) {
+    return (node: HTMLElement, opts: O): LazyHandle<O> => {
+      let handle: LazyHandle<O> | null = null;
+      let current = opts;
+      let destroyed = false;
+      const ensure = () => {
+        if (handle || destroyed || current.disabled) return;
+        void load().then((make) => {
+          // The prop can be switched back off, or the grid unmounted, while
+          // the chunk is still in flight.
+          if (destroyed || current.disabled || handle) return;
+          handle = make(node, current);
+        });
+      };
+      ensure();
+      return {
+        update(next: O) {
+          current = next;
+          if (handle) handle.update(next);
+          else ensure();
+        },
+        destroy() {
+          destroyed = true;
+          handle?.destroy();
+        },
+      };
+    };
+  }
+
+  const lazyRowResize = lazyAction<RowResizeOptions>(() =>
+    import("./row-resize").then((m) => m.rowResize),
+  );
+  const lazyColumnResize = lazyAction<ColumnResizeOptions>(() =>
+    import("./column-resize").then((m) => m.columnResize),
+  );
+
   const rowSizePx = (i: number): number => {
+    // A height the user dragged wins over the declared one, so the row stays
+    // where they put it across re-renders and virtualization recycling.
+    const dragged = ctrl.rowResizeHeightPx(i);
+    if (dragged != null) return dragged;
     const rh = opt.rowHeight;
     return typeof rh === "function" ? rh(i) : (rh ?? 30);
   };
@@ -357,26 +432,10 @@
     return "sv-grid-cell-flash";
   }
 
-  // Keyboard-accessible column resize (#79): focus a resize handle and use the
-  // arrow keys (Shift = fine 1px step). Complements the pointer-drag resize.
-  function resizeColumnByKeyboard(e: KeyboardEvent, columnId: string) {
-    let delta = 0;
-    const step = e.shiftKey ? 1 : 10;
-    if (e.key === "ArrowLeft") delta = -step;
-    else if (e.key === "ArrowRight") delta = step;
-    else return;
-    e.preventDefault();
-    const current = ctrl.getColumnWidth(columnId);
-    ctrl.columnWidths = {
-      ...ctrl.columnWidths,
-      [columnId]: Math.max(40, current + delta),
-    };
-  }
-
   // ---- Full-row editing -------------------------------------------------
   const fullRowEdit = $derived(ctrl.fullRowEdit);
   // Commit the whole row when the user clicks away from its editors (Excel /
-  // AG-Grid feel). Clicking within any full-row editor keeps editing.
+  // spreadsheet feel). Clicking within any full-row editor keeps editing.
   // Stays here rather than in SvGridCellEditor: that component is instantiated
   // once PER editable cell during a full-row edit, so a document listener there
   // would be attached N times and commit N times.
@@ -428,7 +487,6 @@
   const setActiveCell = $derived(ctrl.setActiveCell);
   const scrollActiveCellIntoView = $derived(ctrl.scrollActiveCellIntoView);
   const getColumnWidth = $derived(ctrl.getColumnWidth);
-  const startColumnResize = $derived(ctrl.startColumnResize);
   const getCellRangeEdges = $derived(ctrl.getCellRangeEdges);
   const fillHandleCell = $derived(ctrl.fillHandleCell);
   const isInFillPreview = $derived(ctrl.isInFillPreview);
@@ -1293,6 +1351,26 @@
     class="sv-grid-root"
     class:sv-grid-root-fill={opt.containerHeight === "100%"}
     style={chartDockReserveStyle}
+    use:lazyRowResize={{
+      disabled: !ctrl.rowResizeOn,
+      // No gutter column on most grids, so fall back to the first body cell -
+      // otherwise `rowResize` would be a prop that silently does nothing.
+      anchor: "row",
+      onResize: (index, height) => ctrl.setRowResizeHeight(index, height),
+    }}
+    use:lazyColumnResize={{
+      disabled: !columnResizeEnabled,
+      getWidth: (columnId) => ctrl.getColumnWidth(columnId),
+      onResize: (columnId, width) => {
+        ctrl.columnWidths = { ...ctrl.columnWidths, [columnId]: width };
+      },
+      label: (columnId) => {
+        const col = ctrl.findColumnById(columnId);
+        return col ? toolPanelHeaderLabel(col) : columnId;
+      },
+      canResize: (columnId) => ctrl.columnResizable(columnId),
+      onAutosize: (columnId) => ctrl.autosizeColumn(columnId),
+    }}
   >
     {#if showGlobalFilterEffective}
       <label class="sv-grid-global-filter">
@@ -1746,32 +1824,6 @@
                             }}
                           />
                         {/if}
-                        <div
-                          class="sv-grid-resize-handle"
-                          class:is-resizing={resizingColumnId ===
-                            header.column.id}
-                          role="separator"
-                          aria-orientation="vertical"
-                          aria-label={`Resize ${toolPanelHeaderLabel(header.column)}`}
-                          tabindex="0"
-                          {...(() => {
-                            // A focusable separator is a widget, so ARIA requires
-                            // aria-valuenow. The value it exposes is the column
-                            // width the arrow keys change; 40 is the floor
-                            // enforced in resizeColumnByKeyboard.
-                            const w = Math.round(ctrl.getColumnWidth(header.column.id));
-                            return {
-                              "aria-valuenow": w,
-                              "aria-valuemin": 40,
-                              "aria-valuetext": `${w} pixels`,
-                            };
-                          })()}
-                          onpointerdown={(event) =>
-                            startColumnResize(event, header.column.id)}
-                          onkeydown={(event) =>
-                            resizeColumnByKeyboard(event, header.column.id)}
-                          ondblclick={(event) => event.stopPropagation()}
-                        ></div>
                       {/if}
                     </th>
                   {/if}
@@ -2176,12 +2228,11 @@
                               rendered.column.columnDef.cellFlash,
                             ),
                           }}
-                          {...getGridCellA11yProps({
-                            id: getGridCellDomId(ctrl.gridDomId, rowIndex, colIndex),
-                            rowIndex: rowIndex + 1,
-                            colIndex: colIndex + 1,
-                            selected: isRowSelected(row.id),
-                          })}
+                          role="gridcell"
+                          id={getGridCellDomId(ctrl.gridDomId, rowIndex, colIndex)}
+                          aria-colindex={colIndex + 1}
+                          aria-rowindex={rowIndex + 1}
+                          aria-selected={isRowSelected(row.id)}
                         >
                           {#if inRowEdit || isEditing}
                             <!-- The editing cell stays empty until the lazy
@@ -2193,11 +2244,15 @@
                               <CellEditor {ctrl} column={rendered.column} {row} fullRow={inRowEdit} />
                             {/if}
                           {:else}
-                            {@render cellBodyWithFormat(
-                              row,
-                              rendered.column,
-                              cellValue,
-                            )}
+                            {#if plainCellBody}
+                              {@render cellBody(row, rendered.column, cellValue)}
+                            {:else}
+                              {@render cellBodyWithFormat(
+                                row,
+                                rendered.column,
+                                cellValue,
+                              )}
+                            {/if}
                           {/if}
                           {#if !isEditing && fillHandleCell && fillHandleCell.rowIndex === rowIndex && fillHandleCell.colIndex === colIndex}
                             <!-- Excel-style fill handle: drag down/right to
@@ -2519,7 +2574,7 @@
               {/each}
             </tbody>
           {/if}
-          {#if opt.enableRowSummaries ?? true}
+          {#if rowSummariesEnabled}
             <!-- svelte-ignore a11y_no_redundant_roles -->
             <tfoot class="sv-grid-foot" role="rowgroup">
               <tr

package/dist/SvGrid.types.d.ts

@@ -993,7 +993,21 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * work; the shortcut wins only when it is explicitly set.
      */
     sortable?: boolean;
+    /**
+     * Click a header to filter that column. Injects `columnFilteringFeature`,
+     * so you do not import it yourself. Which filter surface appears is a
+     * separate question - see `filterMode` (default `'menu'`).
+     *
+     *   <SvGrid {data} {columns} filterable />
+     */
     filterable?: boolean;
+    /**
+     * Inline cell editing. Alias of `enableInlineEditing`, and wins over it when
+     * both are set. A column also needs an `editorType` to be editable; without
+     * one it falls back to a text editor.
+     *
+     *   <SvGrid {data} {columns} editable />
+     */
     editable?: boolean;
     /**
      * Cell selection - click a cell to select it, drag or shift-click to extend
@@ -1045,6 +1059,16 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
         /** Indent per depth level, in px. Default `12`. */
         indentPx?: number;
     };
+    /**
+     * Show the grouping controls: "Group by this column" in the column menu, and
+     * the group panel when `showGroupPanel` is on. Alias of
+     * `showGroupingControls`, and also injects `columnGroupingFeature`.
+     *
+     * This turns on the UI for grouping. To group without asking the user, set
+     * `groupBy` instead.
+     *
+     *   <SvGrid {data} {columns} groupable />
+     */
     groupable?: boolean;
     /**
      * Group the rows by these column ids, outermost first - `['region',
@@ -1122,7 +1146,19 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
     autoGroupColumnHeader?: string;
     /** Width (px) of each auto-group column. Default `220`. */
     autoGroupColumnWidth?: number;
+    /**
+     * Show the pagination footer. Alias of `showPagination`, and wins over it
+     * when both are set. Page size starts at `pageSize` (default 10).
+     *
+     *   <SvGrid {data} {columns} pageable pageSize={25} />
+     */
     pageable?: boolean;
+    /**
+     * Show the loading state instead of the rows. By default this replaces the
+     * grid body with "Loading..."; set `loadingOverlay` to keep the current rows
+     * visible under a dimmed overlay instead, which is what you usually want for
+     * a server-paged grid.
+     */
     loading?: boolean;
     /**
      * Render `loading` as a non-blocking overlay instead of replacing the
@@ -1134,7 +1170,16 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
     loadingOverlay?: boolean;
     /** Skeleton placeholder rows to show on first load. Defaults to 8. */
     loadingSkeletonRows?: number;
+    /**
+     * Render an error message in place of the rows. `null` or omitted means no
+     * error. Takes precedence over `loading` and over the empty state.
+     */
     error?: string | null;
+    /**
+     * Text shown when there are no rows to display - either the data is empty or
+     * a filter matched nothing. Defaults to the localized `noRows` string, so
+     * prefer `localization.text.noRows` when you are translating the whole grid.
+     */
     emptyMessage?: string;
     /**
      * The single place to localize the grid. One object with two fields:
@@ -1154,7 +1199,21 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * Omitting it (or any field) is a no-op. See {@link GridMessages}.
      */
     localization?: GridLocalization;
+    /**
+     * Show the single search box that filters across every column. Explicitly
+     * setting this wins over `filterMode`; leaving it unset means it appears only
+     * when `filterMode` is `'global'`.
+     */
     showGlobalFilter?: boolean;
+    /**
+     * Show the filter section inside each column's menu. Explicitly setting this
+     * wins over `filterMode`; unset, it follows `filterMode` (default `'menu'`,
+     * so this is normally on).
+     *
+     * Setting it `true` also adds the inline "floating filter" input under each
+     * header - that surface requires the explicit opt-in, since it otherwise
+     * duplicates the menu's own filter popover.
+     */
     showColumnFilters?: boolean;
     /**
      * Quick way to pick a single filtering UI. When set it controls which of
@@ -1163,8 +1222,23 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * Defaults to `'menu'` (only the column menu's filter section is shown).
      */
     filterMode?: "row" | "menu" | "global" | "none";
+    /**
+     * Show the grouping affordances (the column menu's "Group by this column",
+     * and the group panel). The `groupable` shortcut sets this and registers the
+     * grouping feature in one go; prefer that unless you have already registered
+     * `columnGroupingFeature` yourself.
+     */
     showGroupingControls?: boolean;
+    /**
+     * Show the row-selection checkbox column, including the select-all checkbox
+     * in the header. Unset, it follows `selectionMode` (default `'both'`, so
+     * row selection is on).
+     */
     showRowSelection?: boolean;
+    /**
+     * Show the pagination footer. Off by default. `pageable` is the shortcut
+     * alias and wins when both are set.
+     */
     showPagination?: boolean;
     /** Initial page size when pagination is enabled. Defaults to 10. */
     pageSize?: number;
@@ -1197,6 +1271,14 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
         pageIndex: number;
         pageSize: number;
     }) => void;
+    /**
+     * Render only the rows in view instead of all of them. **On by default** -
+     * this is what keeps a 100,000-row grid responsive.
+     *
+     * Turn it off when a row's height cannot be known up front and must not be
+     * clipped, such as a variable-height master-detail panel. Expect the DOM to
+     * hold every row when you do.
+     */
     virtualization?: boolean;
     /** Row height in pixels. Pass a function `(rowIndex) => px` for
      *  per-row variable heights (e.g. an interactive row-resize feature).
@@ -1214,6 +1296,28 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * supplying per-row heights).
      */
     autoRowHeight?: boolean;
+    /**
+     * Let the user drag a row's bottom edge to change its height. **Off by
+     * default**, because a resizable row needs somewhere to grab and most grids
+     * do not want a drag target on every row.
+     *
+     * The grid remembers the heights itself, so this works as a bare boolean -
+     * no `rowHeight` function required. Drag, or focus the grip and use Up/Down
+     * (Shift for 1px steps).
+     *
+     * Turning this on also turns on the **row header column** ({@link
+     * showRowNumbers}), because that is where the grip lives and where a
+     * spreadsheet puts it - a drag target on the edge of a data cell works but
+     * reads as an accident. An explicit `showRowNumbers={false}` still wins; the
+     * grip then falls back to the row's first cell, and a column of your own
+     * carrying `cellClass: 'sv-row-gutter'` is used ahead of either.
+     *
+     * Ignored under `autoRowHeight`, where the content decides the height and a
+     * manual one would immediately be overwritten. For full control of the
+     * heights - persisting them, sharing them between grids - pass a
+     * function-valued {@link rowHeight} and use the `rowResize` action directly.
+     */
+    rowResize?: boolean;
     /**
      * Height (px) of a single column-header level row. With multi-level
      * (grouped) headers the total header height is `levels * headerHeight`,
@@ -1221,6 +1325,11 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * to their content (the default). Does not affect the filter row.
      */
     headerHeight?: number;
+    /**
+     * Extra rows rendered above and below the viewport, so fast scrolling does
+     * not reach empty space before the next batch renders. Defaults to 8.
+     * Raise it for very tall rows, lower it to trim DOM work.
+     */
     overscan?: number;
     /**
      * Height of the grid's scrollable shell. A number is treated as pixels;
@@ -1228,8 +1337,24 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * make the grid fill its parent. Defaults to 520 px.
      */
     containerHeight?: number | string;
+    /**
+     * Render only the columns in view, the horizontal counterpart of
+     * `virtualization`. **On by default**, which is what makes a 100-column grid
+     * scroll smoothly.
+     *
+     * It recycles column DOM nodes, so it cannot coexist with sticky pinned
+     * columns - turn it off if you need pinning to survive horizontal scrolling.
+     */
     columnVirtualization?: boolean;
+    /**
+     * Extra columns rendered either side of the viewport when
+     * `columnVirtualization` is on. Defaults to 3.
+     */
     columnOverscan?: number;
+    /**
+     * Fallback width in pixels for columns whose `ColumnDef` sets no `width`.
+     * Defaults to 140.
+     */
     columnWidth?: number;
     /**
      * Columns pinned to the left/right edge on mount. Each entry is a
@@ -1251,6 +1376,24 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * win once they happen.
      */
     fitColumns?: boolean;
+    /**
+     * Let the user drag a column's edge to change its width. **Off by default**,
+     * so `width` means the width you asked for until you say otherwise.
+     *
+     * Turn it on for grids the reader is meant to arrange - a spreadsheet, a
+     * dense report, anything with columns whose content varies in length. Leave
+     * it off for layouts you control, and for columns that must keep their size:
+     * a row-number gutter, a checkbox column, an icon column.
+     *
+     * It is grid-wide rather than per-column: there is no `resizable: false` on a
+     * single column definition. `api.autosizeColumn()`, `fitColumns` and
+     * programmatic width changes work either way - this only governs the drag
+     * handle.
+     *
+     * The handles come from the `columnResize` action, loaded on demand: a grid
+     * that leaves this off never fetches that code.
+     */
+    columnResize?: boolean;
     /**
      * Make the grid usable on narrow screens. When the grid's own width drops
      * below the breakpoint (default `640`px), pinned columns are un-pinned so the
@@ -1262,8 +1405,24 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
     responsive?: boolean | {
         breakpoint?: number;
     };
+    /**
+     * @deprecated Has no effect - nothing in the grid reads this prop. It is kept
+     * only so existing code keeps compiling. The column menu's filter section is
+     * controlled by `showColumnFilters`, or by `filterMode="menu"` (the default).
+     */
     showFilterMenu?: boolean;
+    /**
+     * Show the always-visible filter row under the header. Explicitly setting
+     * this wins over `filterMode`; unset, it appears only when `filterMode` is
+     * `'row'`.
+     */
     showFilterRow?: boolean;
+    /**
+     * Cell selection - click to select, drag or shift-click to extend to a range,
+     * which is what clipboard copy and the range fill handle operate on. Unset,
+     * it follows `selectionMode` (default `'both'`, so this is on). `selectable`
+     * is the shortcut alias and wins over it.
+     */
     enableCellSelection?: boolean;
     /**
      * Highlight the row under the pointer. Default **false** - the hover tint can
@@ -1289,6 +1448,14 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
         rowIndex: number;
         columnId: string;
     }) => unknown;
+    /**
+     * Inline cell editing: F2 or double-click opens an editor in the active cell,
+     * Enter commits, Esc cancels. Off by default.
+     *
+     * A column still needs an `editorType` to pick its editor (text, number,
+     * date, checkbox, list, ...); without one it gets a plain text editor.
+     * `editable` is the shortcut alias and wins over this.
+     */
     enableInlineEditing?: boolean;
     /**
      * Full-row editing. When `true`, starting an edit puts the WHOLE row into
@@ -1298,7 +1465,22 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      * text / number / date / datetime / checkbox / list-select editor types.
      */
     fullRowEditing?: boolean;
+    /**
+     * Append a sticky footer row aggregating every filtered row: the sum of a
+     * numeric column, `Count: N` otherwise. Choose a different aggregate per
+     * column with that column's own `summary` option, or set it to `false` there
+     * to leave the cell blank.
+     *
+     * Off by default. `summary` is the shortcut alias and wins when both are set.
+     *
+     *   <SvGrid {data} {columns} summary />
+     */
     enableRowSummaries?: boolean;
+    /**
+     * Shortcut alias for {@link enableRowSummaries}. Wins over it when both are
+     * set, the same precedence `selectable` has over `enableCellSelection`.
+     */
+    summary?: boolean;
     /**
      * Excel-style status bar under the grid showing live aggregates of the
      * selected cell range (count, numeric count, sum, average, min, max).
@@ -1321,7 +1503,7 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
     charting?: boolean | ChartingConfig<TData>;
     /**
      * Render the header column menu (⋮) as a tabbed popover - **General**,
-     * **Filter**, and **Columns** tabs (the AG-Grid layout). Defaults to `false`,
+     * **Filter**, and **Columns** tabs (the tabbed layout). Defaults to `false`,
      * which keeps the flat menu (actions list + "Choose columns" submenu).
      */
     columnMenuTabs?: boolean;
@@ -1514,6 +1696,14 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
      *   filter.
      */
     conditionalStatScope?: "filtered" | "visible" | "all";
+    /**
+     * Fires after an inline edit commits, with the cell's old and new value and
+     * the row it belongs to. This is where you persist the change.
+     *
+     * The grid has already applied the edit to its own state by the time this
+     * runs, so it is a notification, not a veto - reject a value with the
+     * column's `valueParser` or a validation rule instead.
+     */
     onCellValueChange?: (event: {
         rowIndex: number;
         columnId: string;