@svgrid/grid 3.0.4 → 4.0.0

package/src/SvGrid.types.ts

@@ -1,6 +1,7 @@
 // Type definitions extracted from SvGrid.svelte. These are compile-time
 // only - moving them out keeps the component's <script> focused on logic.
 import type { Snippet } from "svelte";
+import type { GridRowModel } from "./row-model";
 import type {
   CellEditorType,
   ColumnDef,
@@ -1113,7 +1114,13 @@ export type SchedulerConfig<
 };
 
 export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData> = {
-  data: ReadonlyArray<TData>;
+  /**
+   * The rows to render.
+   *
+   * Optional only because `rowModel` can supply them instead; a grid with
+   * neither renders empty. When both are present `data` wins.
+   */
+  data?: ReadonlyArray<TData>;
   columns: Array<ColumnDef<TFeatures, TData>>;
   /**
    * Kanban board mode. When set, the grid renders its rows as cards in
@@ -2099,6 +2106,99 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
     scrollHeight: number;
     clientHeight: number;
   }) => void;
+  /**
+   * Fires when the range of rows on screen changes, with the first and last
+   * row INDEX (not pixels). Coalesced to one call per frame, so it is cheap
+   * to wire to something that fetches.
+   *
+   * This is the hook a block-loading data source needs and
+   * `onScrollBottomReached` cannot give it: "the user is looking at rows
+   * 4,000-4,020" answers which block to fetch and which to keep, while
+   * "they hit the bottom" only ever means "append more". Both are free; use
+   * this one with `createServerDataSource({ mode: 'infinite' })`, or let
+   * `rowModel` wire it for you.
+   *
+   * Reports `0, data.length - 1` when virtualization is off, since every row
+   * really is rendered.
+   */
+  onVisibleRangeChange?: (range: {
+    startIndex: number;
+    endIndex: number;
+  }) => void;
+  /**
+   * Marks a row as one whose data has not arrived: `"loading"` draws a
+   * shimmer in every cell, `"failed"` draws a full-width "could not load"
+   * row with a Retry button, and `null` (the default for every row) renders
+   * normally.
+   *
+   * Placeholder rows are inert - not selectable, not editable, and skipped
+   * by cell navigation - because there is nothing there to act on yet.
+   *
+   * `createServerDataSource` in `infinite` mode fills the gaps with rows this
+   * recognises, so the usual wiring is `rowPlaceholder={rowPlaceholderState}`
+   * (or nothing at all, via `rowModel`).
+   */
+  rowPlaceholder?: (row: TData, rowIndex: number) => "loading" | "failed" | null;
+  /** Called by the Retry button on a `"failed"` placeholder row. */
+  onRetryRow?: (row: TData, rowIndex: number) => void;
+  /**
+   * Hand selection over to an external model.
+   *
+   * The grid normally tracks selection as a record of the row ids it has
+   * seen, which is right until the rows it has seen are a window onto a
+   * million on a server: "select all" then means 20 ticked checkboxes rather
+   * than a million, and the header checkbox cannot honestly say `all`. A
+   * model that stores the RULE ("everything except these three") can answer
+   * both, so when this is set the header checkbox, the row checkboxes and
+   * `api.selectAllRows()` all route through it instead.
+   *
+   * `@svgrid/enterprise` ships one for the server-side row model; this is the
+   * seam it plugs into.
+   */
+  /**
+   * Drive the grid from a row model instead of wiring a dozen props.
+   *
+   * `createServerDataSource` returns one, and so does the Enterprise
+   * server-side row model, so server-backed grids become:
+   *
+   * ```svelte
+   * <SvGrid rowModel={ctl} {columns} />
+   * ```
+   *
+   * The model supplies `data`, `loading`, `getRowId`, the external sort
+   * and filter wiring, the visible range, placeholder rows, group
+   * accessors, selection and paging - each one only if it implements that
+   * part. A prop written explicitly on the grid always wins, so you can
+   * adopt it and still override one piece.
+   */
+  rowModel?: GridRowModel<TData>;
+  /**
+   * Columns that REPLACE `columns` while set. The server-side row model
+   * supplies them in pivot mode - one column per pivoted value, grouped
+   * under a header per pivot key - and clears them when pivot mode ends,
+   * so `columns` stays the app's own list. Rarely set by hand.
+   */
+  pivotResultColumns?: Array<ColumnDef<TFeatures, TData>> | null;
+  rowSelectionModel?: {
+    isSelected: (rowId: string, row: TData) => boolean;
+    /** Whether the header checkbox shows empty, indeterminate, or ticked. */
+    headerState: () => "none" | "some" | "all";
+    toggle: (rowId: string, row: TData, next: boolean) => void;
+    /** The header checkbox: select or clear everything, loaded or not. */
+    toggleAll: (next: boolean) => void;
+    /**
+     * How many rows the rule selects, counting the ones the grid never
+     * loaded; `null` when it cannot say. The selection bar shows this
+     * instead of counting ticked rows on screen.
+     */
+    selectedCount?: () => number | null;
+    /**
+     * Apply one patch to every selected row, loaded or not. When present,
+     * the bulk-edit drawer sends its edits here instead of writing the
+     * loaded cells. Resolves with how many rows changed.
+     */
+    bulkUpdate?: (patch: Record<string, unknown>) => Promise<number>;
+  };
   /**
    * Marks a row as an expandable "detail row". When this returns true the
    * grid renders that row as a SINGLE full-width cell (colspan across every
@@ -2119,8 +2219,10 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * Server-side group / tree keyboard + accessibility, built into the grid. When
    * set, the grid uses the treegrid role and marks matching rows with
    * `aria-level` / `aria-expanded`, and ArrowRight / ArrowLeft expand / collapse
-   * the focused group row (no app-level key handling). Pair with `serverGroupRows`
-   * + `SvGroupCell` for the visual expander. Every accessor receives the row data.
+   * the focused group row (no app-level key handling). Pair with
+   * `serverGroupRows` + `SvGroupCell` from `@svgrid/enterprise` for the visual
+   * expander, or drive it from your own tree state. Every accessor receives the
+   * row data.
    */
   serverGroup?: {
     /** Whether a row is an expandable group / branch. */

package/src/build-api.ts

@@ -735,9 +735,10 @@ export function createGridApi<
         });
       },
       selectAllRows() {
-        const next: Record<string, boolean> = {};
-        for (const row of ctx.allRows) if (!isGroupRow(row)) next[row.id] = true;
-        ctx.grid.setRowSelection(() => next);
+        // One implementation of "select everything", shared with the header
+        // checkbox, so it knows about an external selection model and about
+        // rows whose data has not arrived.
+        ctx.setSelectAllRows(true);
       },
       toggleRowSelected(id) {
         ctx.toggleRowSelectionById(id);
@@ -745,7 +746,13 @@ export function createGridApi<
       // ---- Pagination
       getPageInfo() {
         const { pageIndex, pageSize } = ctx.paginationState;
-        const total = ctx.allRowsBeforePagination.length;
+        // Under external pagination the grid holds ONE page, so counting the
+        // rows in hand would report a 95-row table as a 20-row one. The
+        // consumer tells us the real total through rowCount, which is what
+        // the footer has always shown.
+        const total = ctx.externalPaginationEnabled
+          ? (ctx.props.rowCount ?? ctx.allRowsBeforePagination.length)
+          : ctx.allRowsBeforePagination.length;
         const pageCount = Math.max(1, Math.ceil(total / Math.max(1, pageSize)));
         return { pageIndex, pageSize, pageCount, total };
       },

package/src/core.rowmodel-cache.test.ts

@@ -119,3 +119,54 @@ describe('row-model cache: selection', () => {
     expect(target.getIsSelected()).toBe(false)
   })
 })
+
+describe('base rows: reuse across a data swap', () => {
+  // The core reads `options.data` and `options.columns` off the object it was
+  // given (the component hands it a reactive one), so a swap is a write there.
+  const grid = () => {
+    const options = {
+      _features: tableFeatures({ rowSelectionFeature }),
+      _rowModels: { coreRowModel: createCoreRowModel<Row>() },
+      columns: COLUMNS as unknown as Array<ColumnDef<ReturnType<typeof tableFeatures>, Row>>,
+      data: makeRows(50),
+      getRowId: (r: Row) => String(r.id),
+    }
+    return { g: createSvGridCore<ReturnType<typeof tableFeatures>, Row>(options), options }
+  }
+
+  it('keeps the row object for a data object that stayed at its index, and rebuilds the rest', () => {
+    const { g, options } = grid()
+    const before = g.getRowModel().rows
+    const data = options.data.slice()
+    // A block landing: forty of fifty entries are the same objects, ten are new.
+    for (let i = 20; i < 30; i += 1) data[i] = { ...data[i]!, name: 'fresh' }
+    options.data = data
+    const after = g.getRowModel().rows
+    expect(after).toHaveLength(50)
+    for (let i = 0; i < 50; i += 1) {
+      if (i >= 20 && i < 30) expect(after[i]).not.toBe(before[i])
+      else expect(after[i]).toBe(before[i])
+    }
+    expect(after[25]!.getCellValueByColumnId('name')).toBe('fresh')
+  })
+
+  it('does not serve a memoised value after the object was changed in place', () => {
+    const { g, options } = grid()
+    const rows = g.getRowModel().rows
+    expect(rows[3]!.getCellValueByColumnId('score')).toBe((3 * 31) % 1000)
+    options.data[3]!.score = 4242
+    options.data = options.data.slice()
+    const again = g.getRowModel().rows
+    expect(again[3]).toBe(rows[3])
+    expect(again[3]!.getCellValueByColumnId('score')).toBe(4242)
+  })
+
+  it('rebuilds every row when the columns change', () => {
+    const { g, options } = grid()
+    const before = g.getRowModel().rows
+    options.columns = [...COLUMNS, { field: 'extra' }] as unknown as typeof options.columns
+    const after = g.getRowModel().rows
+    expect(after[0]).not.toBe(before[0])
+    expect(after[0]!.getAllCells()).toHaveLength(4)
+  })
+})

package/src/core.ts

@@ -1545,6 +1545,7 @@ export function createSvGridCore<TFeatures extends TableFeatures, TData extends
   let cachedBaseRowsInput: ReadonlyArray<TData> | null = null
   let cachedBaseRowsColumns: Array<Column<TData>> | null = null
   let cachedBaseRows: Array<Row<TData>> = []
+  let cachedRowCtx: BaseRowCtx<TData> | null = null
   let cachedRowModel: RowModel<TData> | null = null
   let cachedRowModelBaseRows: Array<Row<TData>> | null = null
   let cachedPipeline = options._rowModels
@@ -1754,22 +1755,35 @@ export function createSvGridCore<TFeatures extends TableFeatures, TData extends
     getRowModel() {
       const columns = grid.getAllColumns()
       if (cachedBaseRowsInput !== options.data || cachedBaseRowsColumns !== columns) {
+        // Same columns as last time: the shared context still describes them,
+        // and a row whose data object sits at the same index can keep its
+        // row object. A row model that streams blocks hands the grid a new
+        // array of 60k entries per block where 100 changed; building 60k
+        // fresh row objects each time was most of the cost of a block
+        // landing. The reused row drops its memoised values and cells, since
+        // an app may have changed the object in place before passing a new
+        // array - that is the case the old rebuild covered by accident.
+        const previous = cachedBaseRowsColumns === columns && cachedRowCtx ? cachedBaseRows : null
         cachedBaseRowsInput = options.data
         cachedBaseRowsColumns = columns
         // O(1) column-id → index lookup so getCellValueByColumnId doesn't do
         // a linear `findIndex` on every cell read (was O(rows × cells × cols)).
-        const columnIndexById = new Map<string, number>()
-        for (let i = 0; i < columns.length; i++) columnIndexById.set(columns[i]!.id, i)
-        const columnCount = columns.length
-
-        // One shared context for every row in this table, so a row carries a
-        // pointer rather than a closure scope. See BASE_ROW_METHODS.
-        const rowCtx: BaseRowCtx<TData> = {
-          grid: grid as SvGrid<TData>,
-          store,
-          columns,
-          columnCount,
-          columnIndexById,
+        let rowCtx: BaseRowCtx<TData>
+        if (previous && cachedRowCtx) {
+          rowCtx = cachedRowCtx
+        } else {
+          const columnIndexById = new Map<string, number>()
+          for (let i = 0; i < columns.length; i++) columnIndexById.set(columns[i]!.id, i)
+          // One shared context for every row in this table, so a row carries a
+          // pointer rather than a closure scope. See BASE_ROW_METHODS.
+          rowCtx = {
+            grid: grid as SvGrid<TData>,
+            store,
+            columns,
+            columnCount: columns.length,
+            columnIndexById,
+          }
+          cachedRowCtx = rowCtx
         }
 
         cachedBaseRows = new Array(options.data.length)
@@ -1785,6 +1799,13 @@ export function createSvGridCore<TFeatures extends TableFeatures, TData extends
         }
         for (let index = 0; index < options.data.length; index++) {
           const original = options.data[index]!
+          const kept = previous?.[index] as BaseRowState<TData> | undefined
+          if (kept && kept.original === original) {
+            kept[ROW_VALUES] = null
+            kept[ROW_CELLS] = null
+            cachedBaseRows[index] = kept
+            continue
+          }
           // `_values` and `_cells` stay null until something reads them - a
           // 100k-row grid showing twenty rows must not materialise every row's
           // values or cell objects to paint.

package/src/editing.ts

@@ -47,6 +47,14 @@ export function createEditing<
   function isCellEditable(column: Column<TData>, row?: Row<TData>): boolean {
     const editable = column.columnDef.editable;
     if (editable === false) return false;
+    if (row) {
+      // A server-side group row is a key with aggregates under the leaf
+      // columns, and a placeholder row has no data yet: neither takes an
+      // edit, whatever the column says.
+      const serverGroup = ctx.props.serverGroup;
+      if (serverGroup && row.original !== undefined && serverGroup.isGroup(row.original)) return false;
+      if (ctx.placeholderStateOf?.(row)) return false;
+    }
     if (typeof editable !== "function") return true;
     if (!row) return true;
     const cellCtx: CellContext<TData> = {

package/src/grid-icons.ts

@@ -97,8 +97,8 @@ export type GridIcons = Partial<Record<GridIconName, Snippet>>
 
 /**
  * Icons whose built-in form is a character rather than an SVG path. Kept as
- * data so `<SvGrid>`, its footer and the standalone `SvRowGroupPanel` render
- * the same defaults instead of three copies drifting apart.
+ * data so `<SvGrid>`, its footer and the row-group panel in @svgrid/enterprise
+ * render the same defaults instead of three copies drifting apart.
  *
  * Each is the exact character that shipped inline before, so a grid that sets
  * no `icons` renders byte-for-byte what it always did.

package/src/grid-messages.ts

@@ -106,6 +106,9 @@ export type GridChromeMessages = {
   bulkEditCancel: string
   bulkEditNoFields: string
   chartRange: string
+  // Rows whose data has not arrived (server-side / infinite loading)
+  rowLoadFailed: string
+  rowLoadRetry: string
   // Upsell notes (enterprise views not installed)
   pivotUpsellTitle: string
   pivotUpsellBody: string
@@ -185,6 +188,8 @@ export const defaultGridMessages: GridChromeMessages = {
   opBefore: 'Before',
   opAfter: 'After',
   chartRange: 'Chart selected range',
+  rowLoadFailed: 'Could not load these rows.',
+  rowLoadRetry: 'Retry',
   pivotUpsellTitle: 'Pivot mode',
   pivotUpsellBody: 'Pivot mode is an Enterprise feature. Install @svgrid/enterprise and call enablePivot() to use it.',
   upsellLicense:

package/src/icon-seam.test.ts

@@ -20,18 +20,16 @@ const SRC = join(process.cwd(), 'src')
 const read = (f: string) => readFileSync(join(SRC, f), 'utf8')
 
 /** Files that render grid chrome and therefore must go through the seam. */
-const CHROME = ['SvGrid.svelte', 'GridMenus.svelte', 'GridFooter.svelte', 'SvRowGroupPanel.svelte']
+const CHROME = ['SvGrid.svelte', 'GridMenus.svelte', 'GridFooter.svelte']
 
 /**
  * Drop the regions allowed to contain raw icon markup: the `icon` snippet's own
- * body (which IS the built-in set), the `ic` snippet in SvRowGroupPanel, and
- * every `<script>` block.
+ * body (which IS the built-in set) and every `<script>` block.
  */
 function stripAllowedRegions(src: string): string {
   let out = src.replace(/<script[\s\S]*?<\/script>/g, '')
   // The built-in catalogue: from the snippet header to its closing tag.
   out = out.replace(/\{#snippet icon\(name: GridIconName\)\}[\s\S]*?\n\{\/snippet\}/g, '')
-  out = out.replace(/\{#snippet ic\(name: GridIconName\)\}[\s\S]*?\{\/snippet\}/g, '')
   return out
 }
 

package/src/index.ts

@@ -754,9 +754,11 @@ export {
 export {
   createServerDataSource,
   type ServerDataSource,
+  type ServerSelectionRule,
   type ServerRequest,
   type ServerResult,
   type ServerController,
+  type ServerControllerOptions,
   type ServerState,
   type ServerSortModel,
   type ServerFilterModel,
@@ -766,19 +768,26 @@ export {
   type ServerMoreRow,
   type ServerFooterRow,
   type ServerSkeletonRow,
+  type ServerGrandTotalRow,
+  type ServerPlaceholderRow,
   type ServerDisplayRow,
 } from './server-data-source'
 export {
-  createServerGroupModel,
-  serverGroupRows,
-  serverGroupNav,
-  type ServerGroupController,
-  type ServerGroupControllerOptions,
-  type ServerGroupState,
-  type ServerGroupGridRow,
-} from './server-group-model'
-export { default as SvGroupCell } from './SvGroupCell.svelte'
-export { default as SvRowGroupPanel } from './SvRowGroupPanel.svelte'
+  createBlockCache,
+  createRowPlaceholder,
+  rowPlaceholderState,
+  type BlockCache,
+  type BlockCacheOptions,
+  type BlockCacheState,
+  type BlockFetchResult,
+  type BlockState,
+} from './server-block-cache'
+export {
+  toServerFilterColumns,
+  type GridRowModel,
+  type GridFilterState,
+  type GridRowModelSort,
+} from './row-model'
 export {
   createNamedViews,
   memoryViews,

package/src/row-model.ts

@@ -0,0 +1,146 @@
+/**
+ * `GridRowModel` - one prop instead of eleven.
+ *
+ * A grid backed by a server needs the same wiring every time: hand it the
+ * rows, tell it not to sort or filter locally, forward the sort and the filter
+ * to the backend, report which rows are on screen, say which rows have not
+ * loaded, and delegate selection. Written out by hand that is a dozen props
+ * and a filter-shape conversion that every app gets slightly differently:
+ *
+ * ```svelte
+ * <SvGrid data={s.rows} externalSort externalFilter loading={s.loading}
+ *   onSortingChange={(x) => ctl.setSort(x)}
+ *   onFiltersChange={(f) => ctl.setFilter({ global: f.global,
+ *     columns: Object.fromEntries(f.columns.map((c) => [c.id, { ... }])) })}
+ *   onVisibleRangeChange={(r) => ctl.setViewport(r.startIndex, r.endIndex)}
+ *   ... />
+ * ```
+ *
+ * An object that implements this interface carries all of it, so the same grid
+ * becomes:
+ *
+ * ```svelte
+ * <SvGrid rowModel={ctl} {columns} />
+ * ```
+ *
+ * `createServerDataSource` returns one, and so does the Enterprise server row
+ * model - which is the point of the interface rather than a concrete type: the
+ * grid depends on the SHAPE, never on either implementation, and an app with
+ * its own fetching can satisfy it too.
+ *
+ * Every member except `subscribe` / `getRows` / `isLoading` is optional, and a
+ * prop written explicitly on `<SvGrid>` always wins over the model's answer -
+ * so adopting this is never all-or-nothing.
+ */
+import type { FilterOperator } from './SvGrid.types'
+
+/** The filter state as the grid reports it, straight from `onFiltersChange`. */
+export type GridFilterState = {
+  global: string
+  columns: Array<{
+    id: string
+    operator: FilterOperator
+    value: string
+    valueTo?: string
+    selectedValues?: Array<string>
+  }>
+}
+
+/** The sort the grid hands a row model: column id and direction, in priority order. */
+export type GridRowModelSort = Array<{ id: string; desc: boolean }>
+
+/**
+ * What `<SvGrid rowModel>` consumes: rows, a loading flag, a change
+ * subscription, and whichever optional parts the model implements - sort,
+ * filter, viewport, placeholders, group accessors, selection, filter
+ * values, paging, pinned rows and pivot columns. `createServerDataSource`
+ * and the Enterprise `createServerRowModel` both satisfy it.
+ */
+export type GridRowModel<TData> = {
+  /**
+   * Register a callback for "something changed, re-read me". Returns an
+   * unsubscribe function, which the grid calls on unmount.
+   */
+  subscribe(onChange: () => void): () => void
+  /** The rows to render, including any placeholders for unloaded ones. */
+  getRows(): ReadonlyArray<TData>
+  /** True while a fetch is in flight, for the loading overlay. */
+  isLoading(): boolean
+  /** Stable row id. Required once selection or editing is involved. */
+  getRowId?(row: TData, index: number): string
+  /** Sort on the server. Present means "do not sort locally". */
+  setSort?(sort: GridRowModelSort): void
+  /** Filter on the server. Present means "do not filter locally". */
+  setFilter?(filters: GridFilterState): void
+  /** Which rows are on screen, so a block-loading model knows what to fetch. */
+  setViewport?(startIndex: number, endIndex: number): void
+  /** Why a row has no data yet, or null when it does. */
+  rowPlaceholder?(row: TData, rowIndex: number): 'loading' | 'failed' | null
+  /** Retry the failed block a placeholder row belongs to. */
+  retryRow?(row: TData, rowIndex: number): void
+  /** Group / tree accessors, for the grid's treegrid keyboard and ARIA. */
+  group?: {
+    isGroup: (row: TData) => boolean
+    level: (row: TData) => number
+    expanded?: (row: TData) => boolean
+    onToggle: (row: TData) => void
+  }
+  /** Selection the grid does not own - see the `rowSelectionModel` prop. */
+  selection?: {
+    isSelected: (rowId: string, row: TData) => boolean
+    headerState: () => 'none' | 'some' | 'all'
+    toggle: (rowId: string, row: TData, next: boolean) => void
+    toggleAll: (next: boolean) => void
+    selectedCount?: () => number | null
+    bulkUpdate?: (patch: Record<string, unknown>) => Promise<number>
+  }
+  /** Distinct values for a column's set filter, fetched from the server. */
+  filterValues?(columnId: string): Promise<Array<string>>
+  /** Server-side paging. Omit it for infinite scrolling. */
+  pagination?: {
+    pageIndex: number
+    pageSize: number
+    rowCount: number
+    setPage(pageIndex: number): void
+    setPageSize(pageSize: number): void
+    /** Choices for the footer's page-size selector. */
+    pageSizes?: number[]
+    /**
+     * Ask the grid for as many rows as its body fits: it measures and calls
+     * `setPageSize` whenever the fit changes.
+     */
+    autoPageSize?: boolean
+  }
+  /** Rows to pin above / below the scrolling body - a grand total, say. */
+  readonly pinnedTopRows?: ReadonlyArray<TData>
+  readonly pinnedBottomRows?: ReadonlyArray<TData>
+  /**
+   * Columns that replace the grid's `columns` while the model is in pivot
+   * mode, or null. Read after every change notification.
+   */
+  readonly pivotResultColumns?: ReadonlyArray<unknown> | null
+}
+
+/**
+ * Turn the grid's filter payload into the column-keyed map a `ServerRequest`
+ * carries. Exported because a hand-written `GridRowModel` needs exactly this
+ * conversion, and copying it is how the two shapes drift apart.
+ */
+export function toServerFilterColumns(
+  filters: GridFilterState,
+): Record<
+  string,
+  { operator: string; value: string; valueTo?: string; selectedValues?: Array<string> }
+> {
+  return Object.fromEntries(
+    filters.columns.map((c) => [
+      c.id,
+      {
+        operator: c.operator,
+        value: c.value,
+        ...(c.valueTo !== undefined ? { valueTo: c.valueTo } : {}),
+        ...(c.selectedValues !== undefined ? { selectedValues: c.selectedValues } : {}),
+      },
+    ]),
+  )
+}

package/src/selection.test.ts

@@ -39,6 +39,9 @@ function makeCtx(overrides: any = {}) {
     allRows: [],
     allColumns: [],
     headerSelectionState: 'none',
+    // The real controller always supplies this; a fake that omits it would
+    // make every select-all path throw rather than assert.
+    placeholderStateOf: () => null,
     userHasActivatedCell: false,
     enableCellSelectionEffective: true,
     selectionRange: { anchor: null, focus: null },

package/src/selection.ts

@@ -21,16 +21,45 @@ export function createSelection<
   TData extends RowData = RowData,
 >(ctx: any) {
   function isRowSelected(rowId: string) {
+    const model = ctx.props.rowSelectionModel;
+    if (model) {
+      const row = ctx.allRows.find((r: any) => r.id === rowId);
+      return row ? model.isSelected(rowId, row.original) : false;
+    }
     return Boolean(ctx.rowSelectionState[rowId]);
   }
 
   function toggleRowSelectionById(rowId: string) {
+    const model = ctx.props.rowSelectionModel;
+    if (model) {
+      const row = ctx.allRows.find((r: any) => r.id === rowId);
+      if (!row) return;
+      model.toggle(rowId, row.original, !model.isSelected(rowId, row.original));
+      return;
+    }
     ctx.grid.setRowSelection((prev: any) => ({ ...prev, [rowId]: !prev[rowId] }));
   }
 
   function toggleSelectAllRows() {
-    const selectable = ctx.allRows.filter((row: any) => !isGroupRow(row));
-    const select = ctx.headerSelectionState !== "all";
+    setSelectAllRows(ctx.headerSelectionState !== "all");
+  }
+
+  /**
+   * Select or clear every row, for the header checkbox and for
+   * `api.selectAllRows()`.
+   */
+  function setSelectAllRows(select: boolean) {
+    // An external model decides what "all" means - possibly a million rows
+    // the grid has never seen - so it gets the intent, not a row list.
+    if (ctx.props.rowSelectionModel) {
+      ctx.props.rowSelectionModel.toggleAll(select);
+      return;
+    }
+    // Placeholder rows are excluded: there is no row there to select yet,
+    // and ticking one would leave a selected id that never resolves.
+    const selectable = ctx.allRows.filter(
+      (row: any) => !isGroupRow(row) && !ctx.placeholderStateOf(row),
+    );
     ctx.grid.setRowSelection((prev: any) => {
       const next = { ...prev };
       for (const row of selectable) {
@@ -687,6 +716,7 @@ export function createSelection<
     isRowSelected,
     toggleRowSelectionById,
     toggleSelectAllRows,
+    setSelectAllRows,
     setActiveCell,
     scrollActiveCellIntoView,
     setSelection,