@svgrid/grid 3.0.4 → 3.0.6

package/src/SvGrid.controller.svelte.ts

@@ -309,6 +309,60 @@ export function createSvGridController<
   // preserves reference identity for non-overridden keys, which the columns-identity
   // column cache and the `data`/`columns` sync effects rely on.
   let optionOverrides = $state<Record<string, unknown>>({});
+
+  /**
+   * A `rowModel` answers for the props it can, so a server-backed grid is
+   * one prop rather than a dozen.
+   *
+   * Bumped by the model itself through `subscribe` (see the effect below),
+   * which is what makes `getRows()` and `isLoading()` - plain method calls,
+   * invisible to the reactive system - re-read when the model changes.
+   */
+  let rowModelVersion = $state(0);
+  const rowModelProps = $derived.by(function rowModelProps_d() {
+    const model = rawProps.rowModel;
+    if (!model) return null;
+    rowModelVersion; // read, so a notification re-derives
+    const paging = model.pagination;
+    return {
+      data: model.getRows(),
+      loading: model.isLoading(),
+      loadingOverlay: true,
+      getRowId: model.getRowId,
+      // A model that sorts or filters server-side is telling the grid not
+      // to do it locally; one that does neither leaves the grid in charge.
+      externalSort: model.setSort ? true : undefined,
+      externalFilter: model.setFilter ? true : undefined,
+      onSortingChange: model.setSort ? (s: any) => model.setSort!(s) : undefined,
+      onFiltersChange: model.setFilter ? (f: any) => model.setFilter!(f) : undefined,
+      onVisibleRangeChange: model.setViewport
+        ? (r: { startIndex: number; endIndex: number }) =>
+            model.setViewport!(r.startIndex, r.endIndex)
+        : undefined,
+      rowPlaceholder: model.rowPlaceholder,
+      onRetryRow: model.retryRow,
+      serverGroup: model.group,
+      rowSelectionModel: model.selection,
+      serverFilterValues: model.filterValues
+        ? (columnId: string) => model.filterValues!(columnId)
+        : undefined,
+      pinnedTopRows: model.pinnedTopRows,
+      pinnedBottomRows: model.pinnedBottomRows,
+      pivotResultColumns: model.pivotResultColumns ?? undefined,
+      externalPagination: paging ? true : undefined,
+      rowCount: paging?.rowCount,
+      pageIndex: paging?.pageIndex,
+      pageSize: paging?.pageSize,
+      pageSizeOptions: paging?.pageSizes,
+      onPaginationChange: paging
+        ? (p: { pageIndex: number; pageSize: number }) => {
+            if (p.pageSize !== paging.pageSize) paging.setPageSize(p.pageSize);
+            else paging.setPage(p.pageIndex);
+          }
+        : undefined,
+    } as Partial<Props<TFeatures, TData>>;
+  });
+
   const props = new Proxy(rawProps, {
     // Read the override as a PROPERTY (tracked by `$state`), not via `in` (the `has`
     // trap is not tracked) - so a reactive read of `props.X` re-runs when an override
@@ -318,7 +372,21 @@ export function createSvGridController<
     get: (t, k) => {
       const v =
         typeof k === "string" ? optionOverrides[k] : undefined;
-      return v !== undefined ? v : Reflect.get(t, k);
+      if (v !== undefined) return v;
+      // Pivot mode swaps the column list: `pivotResultColumns` (the prop, or
+      // the row model's) stands in for `columns` while it is set, and
+      // `columns` itself stays the app's own list for when pivot ends.
+      if (k === "columns") {
+        const pivot =
+          Reflect.get(t, "pivotResultColumns") ??
+          (rowModelProps as Record<string, unknown> | null)?.pivotResultColumns;
+        if (pivot) return pivot;
+      }
+      const own = Reflect.get(t, k);
+      // A prop written on the grid always beats the row model, so adopting
+      // `rowModel` is never all-or-nothing.
+      if (own !== undefined || typeof k !== "string") return own;
+      return (rowModelProps as Record<string, unknown> | null)?.[k];
     },
   }) as Props<TFeatures, TData>;
 
@@ -447,7 +515,11 @@ export function createSvGridController<
   // previously declared it twice and open-coded the push in three places.
   type HistoryStep = SharedHistoryStep
   const UNDO_LIMIT = 200
-  let history    = $state<HistoryStep[]>([])
+  // Raw: pushHistory always assigns a fresh array and nothing renders from a
+  // step, so deep proxies would cost 200 wrapped objects for nothing. It also
+  // keeps a consumer's `tag` the object it passed, which a proxy would not be:
+  // the sheet shell compares tags by identity.
+  let history    = $state.raw<HistoryStep[]>([])
   /** Index in `history` of the LAST applied step. -1 means "nothing applied".
    *  undo() decrements; redo() increments. New edits truncate everything
    *  past the pointer (the classic "you can't redo after editing" rule). */
@@ -460,6 +532,9 @@ export function createSvGridController<
    *  $state: it is written and read synchronously inside a single call and
    *  nothing renders from it. */
   let historyGroupId: string | undefined = undefined
+  /** The consumer's mark for the steps recorded from now on (`api.setHistoryTag`);
+   *  not $state for the same reason. */
+  let historyTag: unknown = undefined
 
   // ---- Hover tooltip (custom popover, not native title=) ---------------
   // Triggered by per-column `tooltip` field OR per-cell `notes` prop.
@@ -531,7 +606,25 @@ export function createSvGridController<
   // catch-all gridStateVersion, so navigation doesn't rebuild 1M rows.
   let dataStateVersion = $state(0);
   const selectionColumnWidth = 44;
+  const detailToggleColumnWidth = 36;
   const rowNumberColumnWidth = $derived(props.rowNumberWidth ?? 56);
+  const showDetailToggleEffective = $derived(props.showDetailToggle === true);
+  /**
+   * What the chevron on a row does, or null when the row has no detail to
+   * open: a detail row itself, a group or placeholder on a server model, a
+   * row `hasDetail` rules out, or a grid with nothing to call.
+   */
+  function detailToggleOf(row: Row<TData>, rowIndex: number): { open: boolean; toggle: () => void } | null {
+    const data = row.original;
+    if (props.isDetailRow?.(data, rowIndex)) return null;
+    const sg = props.serverGroup;
+    if (sg) {
+      if (!sg.toggleDetail || sg.isGroup(data) || (sg.hasDetail && !sg.hasDetail(data))) return null;
+      return { open: sg.detailOpen?.(data) ?? false, toggle: () => sg.toggleDetail!(data) };
+    }
+    if (!props.onDetailToggle || (props.hasDetail && !props.hasDetail(data))) return null;
+    return { open: props.isDetailOpen?.(data) ?? false, toggle: () => props.onDetailToggle!(data, rowIndex) };
+  }
   // A per-row `rowHeight` function already supplies heights, so auto-measuring
   // would fight it. Fixed numbers are fine - they become the pre-measure estimate.
   const autoRowHeightOn = $derived(
@@ -703,6 +796,16 @@ export function createSvGridController<
       ((props.selectionMode ?? "both") === "row" ||
         (props.selectionMode ?? "both") === "both"),
   );
+  /** The system columns to the left of the data: row numbers, selection, the detail toggle. */
+  const systemColumnsWidth = $derived(
+    (showRowNumbersEffective ? rowNumberColumnWidth : 0) +
+      (showRowSelectionEffective ? selectionColumnWidth : 0) +
+      (showDetailToggleEffective ? detailToggleColumnWidth : 0),
+  );
+  /** Where the detail-toggle column sticks: after the row numbers and the selection column. */
+  const detailToggleColumnLeft = $derived(
+    (showRowNumbersEffective ? rowNumberColumnWidth : 0) + (showRowSelectionEffective ? selectionColumnWidth : 0),
+  );
   // `selectable` is the shortcut alias, so it wins over the fine-grained prop,
   // which in turn wins over `selectionMode` - the same precedence the other
   // shortcuts use. Unlike them it starts ON (selectionMode defaults to 'both'),
@@ -739,7 +842,10 @@ export function createSvGridController<
   // re-synced whenever the parent passes a new array; the imperative API
   // mutates these so add/remove operations don't need a callback round-trip.
   // svelte-ignore state_referenced_locally
-  let internalData = $state.raw<ReadonlyArray<TData>>(props.data);
+  // `data` is optional on the type (a `rowModel` may supply the rows
+  // instead), so every read falls back to empty rather than to undefined.
+  const EMPTY_DATA: ReadonlyArray<TData> = [];
+  let internalData = $state.raw<ReadonlyArray<TData>>(props.data ?? EMPTY_DATA);
   // Resolve `cellDataType` / `inferColumnTypes` into concrete editorType +
   // format defaults once, up front, so every downstream reader sees a normal
   // column. Explicit fields on the ColumnDef always win.
@@ -791,7 +897,7 @@ export function createSvGridController<
     // accumulated cell-edit overrides - otherwise `getCellDisplayValue`
     // would keep returning the old edited values from `editedCellValues`
     // even though the underlying data has been replaced.
-    internalData = props.data;
+    internalData = props.data ?? EMPTY_DATA;
     editedCellValues = {};
   });
   $effect(() => {
@@ -819,36 +925,42 @@ export function createSvGridController<
   // svelte-ignore state_referenced_locally
   const treeDataConfig = props.treeData;
 
+  // Pagination is intentionally NOT in the grid's row-model pipeline. The
+  // wrapper applies its own filters (filterMenuValues, globalFilter,
+  // valueFilters) on top of `grid.getRowModel().rows`. If pagination ran
+  // first, those filters would only see the visible page. Instead the wrapper
+  // paginates last - see `allRows` below.
+  //
+  // Built ONCE. Both inputs are captured at mount, and the stages keep state
+  // between runs: the sorted and filtered stages hold their last output so a
+  // data tick can repair it instead of recomputing (core.ts, `replacedRowsOf`).
+  // This used to be a getter that built fresh stages on every read, which
+  // threw that cache away on each run - a live feed re-sorted 100k rows on
+  // every tick and the row-model memo's `cachedPipeline` never matched.
+  const rowModels = {
+    coreRowModel: createCoreRowModel<TData>(),
+    filteredRowModel: createFilteredRowModel<TData>(),
+    // External-sort mode: pass the rows through untouched so the consumer
+    // controls ordering (e.g. tree data that must preserve hierarchy).
+    sortedRowModel: externalSortEnabled
+      ? passthroughSortedRowModel
+      : createSortedRowModel<TData>(sortFns),
+    // Tree nesting replaces grouping when `treeData` is set - a row cannot
+    // be both a hierarchy node and bucketed under a group banner.
+    groupedRowModel: treeDataConfig
+      ? createTreeRowModel<TData>({
+          parentField: treeDataConfig.parentField,
+          idField: treeDataConfig.idField,
+        })
+      : createGroupedRowModel<TData>(),
+    expandedRowModel: createExpandedRowModel<TData>(),
+  };
 
   const grid = createSvGrid({
     get _features() {
       return resolveEffectiveFeatures();
     },
-    get _rowModels() {
-      // Pagination is intentionally NOT in the grid's row-model pipeline.
-      // The wrapper applies its own filters (filterMenuValues, globalFilter,
-      // valueFilters) on top of `grid.getRowModel().rows`. If pagination
-      // ran first, those filters would only see the visible page. Instead
-      // the wrapper paginates last - see `allRows` below.
-      return {
-        coreRowModel: createCoreRowModel<TData>(),
-        filteredRowModel: createFilteredRowModel<TData>(),
-        // External-sort mode: pass the rows through untouched so the consumer
-        // controls ordering (e.g. tree data that must preserve hierarchy).
-        sortedRowModel: externalSortEnabled
-          ? passthroughSortedRowModel
-          : createSortedRowModel<TData>(sortFns),
-        // Tree nesting replaces grouping when `treeData` is set - a row cannot
-        // be both a hierarchy node and bucketed under a group banner.
-        groupedRowModel: treeDataConfig
-          ? createTreeRowModel<TData>({
-              parentField: treeDataConfig.parentField,
-              idField: treeDataConfig.idField,
-            })
-          : createGroupedRowModel<TData>(),
-        expandedRowModel: createExpandedRowModel<TData>(),
-      };
-    },
+    _rowModels: rowModels,
     get columns() {
       return internalColumns;
     },
@@ -1037,6 +1149,20 @@ export function createSvGridController<
    *
    * Returns null when the cell should render nothing.
    */
+  /**
+   * Why a row has no data yet, or null when it does.
+   *
+   * Group rows are never placeholders, so the check is skipped for them:
+   * their `original` is a synthetic bucket, not a row the consumer handed
+   * us, and passing it to `rowPlaceholder` would ask a question about a row
+   * that does not exist.
+   */
+  function placeholderStateOf(row: Row<TData>): "loading" | "failed" | null {
+    const ask = props.rowPlaceholder;
+    if (!ask || isGroupRow(row)) return null;
+    return ask(row.original, row.index);
+  }
+
   function autoGroupCell(
     row: Row<TData>,
     columnId: string,
@@ -1299,10 +1425,8 @@ export function createSvGridController<
 
   /** Cumulative pixel offsets for left- and right-pinned columns. */
   const pinnedOffsets = $derived.by(function pinnedOffsets_d() {
-    const rowNumberWidth = showRowNumbersEffective ? rowNumberColumnWidth : 0;
-    const selectionWidth = showRowSelectionEffective ? selectionColumnWidth : 0;
     const left: Record<string, number> = {};
-    let leftAcc = rowNumberWidth + selectionWidth;
+    let leftAcc = systemColumnsWidth;
     for (const id of effectivePinning.left) {
       // Hidden pinned columns don't render, so they must contribute neither an
       // offset entry nor width - otherwise the next visible pinned column is
@@ -1337,7 +1461,7 @@ export function createSvGridController<
   // index currently hovered; `rowDropSide` says which edge the drop line paints.
   let rowDragActive = $state<boolean>(false);
   let rowDropIndex  = $state<number | null>(null);
-  let rowDropSide   = $state<"before" | "after" | null>(null);
+  let rowDropSide   = $state<"before" | "after" | "into" | null>(null);
 
 
 
@@ -1805,15 +1929,42 @@ export function createSvGridController<
     const rows: TData[] = [];
     const ids: string[] = [];
     if (!selectionBarOn) return { rows, ids };
+    // Under an external selection model the loaded rows are the ones the
+    // model says are selected; rows that never loaded are not in `allRows`
+    // and are counted by `selectionBarCount` below instead. This walks
+    // every loaded row, so it runs on every block a row model delivers:
+    // a model that can say "nothing is selected" spares the walk, and the
+    // props it needs are read once, not through the proxy per row.
+    const model = props.rowSelectionModel;
+    if (model && model.selectedCount?.() === 0) return { rows, ids };
+    const ask = props.rowPlaceholder;
+    const isPlaceholder = ask
+      ? (row: Row<TData>) => !isGroupRow(row) && !!ask(row.original as TData, row.index)
+      : () => false;
     for (const row of allRows) {
-      if (isGroupRow(row)) continue;
-      if (rowSelectionState[row.id]) {
+      if (isGroupRow(row) || isPlaceholder(row)) continue;
+      const selected = model
+        ? model.isSelected(row.id, row.original as TData)
+        : !!rowSelectionState[row.id];
+      if (selected) {
         rows.push(row.original as TData);
         ids.push(row.id);
       }
     }
     return { rows, ids };
   });
+  /**
+   * What the selection bar's count chip says. A model that stores the rule
+   * ("everything except these") knows about rows the grid never loaded, so
+   * its number wins over counting ticks on screen; `null` from it means it
+   * cannot say, and the bar falls back to the loaded count.
+   */
+  const selectionBarCount = $derived.by(function selectionBarCount_d() {
+    const fromModel = props.rowSelectionModel?.selectedCount?.();
+    return fromModel ?? selectionBarTarget.ids.length;
+  });
+  /** Whether the bar has anything to show: the model's count when it has one, else the loaded ticks. */
+  const selectionBarVisible = $derived(selectionBarOn && selectionBarCount > 0);
 
   // Forward selection changes to the consumer. Skips the very first invocation
   // (the initial empty state) so consumers don't get a spurious callback on mount.
@@ -1840,17 +1991,16 @@ export function createSvGridController<
   // so consumers don't see spurious callbacks during re-renders.
   let lastCellRangeSerialized = "";
   $effect(() => {
-    const a = selectionRange.anchor;
-    const f = selectionRange.focus;
-    const ranges: Array<[number, number, number, number]> =
-      a && f
-        ? [[
-            Math.min(a.rowIndex, f.rowIndex),
-            Math.min(a.colIndex, f.colIndex),
-            Math.max(a.rowIndex, f.rowIndex),
-            Math.max(a.colIndex, f.colIndex),
-          ]]
-        : [];
+    // Every rectangle, the committed ones a Ctrl+click added and the
+    // active one last, the order getSelectionRects gives: a consumer's
+    // status bar and shading cover the whole selection, not only its last
+    // range. Depend on selectionRanges so a change to the committed set
+    // re-runs this too.
+    void selectionRanges;
+    const ranges: Array<[number, number, number, number]> = getSelectionRects().map(
+      (r: { minRow: number; minCol: number; maxRow: number; maxCol: number }) =>
+        [r.minRow, r.minCol, r.maxRow, r.maxCol] as [number, number, number, number],
+    );
     const serialized = JSON.stringify(ranges);
     if (serialized === lastCellRangeSerialized) return;
     lastCellRangeSerialized = serialized;
@@ -2833,6 +2983,55 @@ export function createSvGridController<
     Math.max(virtualRowTotalSize - virtualRowEnd, 0),
   );
 
+  // A row model tells us when to re-read it. Subscribing here (rather than
+  // polling, or asking the consumer to wrap the model in a rune) is what lets
+  // `getRows()` be a plain method call on a plain object.
+  $effect(() => {
+    const model = rawProps.rowModel;
+    if (!model) return;
+    return model.subscribe(() => {
+      rowModelVersion += 1;
+    });
+  });
+
+  // The index range on screen, for data sources that fetch by block.
+  // `virtualRowStart` / `virtualRowEnd` above are PIXEL offsets; a fetcher
+  // needs row numbers, and needs them whether or not virtualization is on.
+  const visibleRowRange = $derived.by(function visibleRowRange_d() {
+    if (!rowVirtualizationEnabled) {
+      return { startIndex: 0, endIndex: Math.max(0, allRows.length - 1) };
+    }
+    const first = virtualRows[0];
+    const last = virtualRows[virtualRows.length - 1];
+    if (!first || !last) return { startIndex: 0, endIndex: 0 };
+    return { startIndex: first.index, endIndex: last.index };
+  });
+  // Emitted from an effect rather than the derived so a consumer that
+  // fetches (and therefore changes `data`) cannot re-enter the derivation.
+  let lastReportedRange = "";
+  $effect(() => {
+    const report = props.onVisibleRangeChange;
+    if (!report) return;
+    const range = visibleRowRange;
+    const key = range.startIndex + ":" + range.endIndex;
+    if (key === lastReportedRange) return;
+    lastReportedRange = key;
+    report(range);
+  });
+
+  // A paging row model that asks for `autoPageSize` gets as many rows as
+  // the body shows without scrolling, re-measured as the viewport changes.
+  $effect(() => {
+    rowModelVersion;
+    const paging = rawProps.rowModel?.pagination;
+    if (!paging?.autoPageSize) return;
+    const height = viewportHeight;
+    if (height <= 0) return;
+    const rowPx = rowSizePxOf(0) || 30;
+    const fit = Math.max(1, Math.floor(height / rowPx));
+    if (fit !== paging.pageSize) paging.setPageSize(fit);
+  });
+
   // --- Huge-list scroll scaling -----------------------------------------
   // Browsers cap how tall a single element may be, and mobile caps sit well
   // below desktop. Past a few hundred thousand rows the true content height
@@ -2902,11 +3101,21 @@ export function createSvGridController<
     return total;
   });
   /** The declared or dragged height of one row; measured under auto height. */
+  /** A detail row's declared height, or null when the row is not one (or none is declared). */
+  function detailRowHeightPx(i: number): number | null {
+    const dh = props.detailRowHeight;
+    if (dh == null || !props.isDetailRow) return null;
+    const row = allRows[i];
+    if (!row || !props.isDetailRow(row.original as TData, i)) return null;
+    return typeof dh === "function" ? dh(row.original as TData) : dh;
+  }
   function rowSizePxOf(i: number): number {
     if (isRowCollapsed(i)) return 0;
     if (autoRowHeightOn) return measuredRowHeights.get(i) ?? autoRowHeightFallback;
     const own = rowResizeHeightPx(i);
     if (own != null) return own;
+    const detail = detailRowHeightPx(i);
+    if (detail != null) return detail;
     const rh = props.rowHeight;
     return typeof rh === "function" ? rh(i) : (rh ?? 30);
   }
@@ -2916,10 +3125,94 @@ export function createSvGridController<
     for (let k = 0; k < i; k += 1) top += rowSizePxOf(k);
     return top;
   }
+  // --- Sticky group rows --------------------------------------------------
+  // The group a row belongs to, kept under the header while its rows scroll
+  // past. The ancestors of the first row under the header are the nearest
+  // group rows above it at each shallower level; under virtualization they
+  // are usually outside the rendered window, so the band renders a copy of
+  // each (its height taken off the top spacer, like the frozen band), and
+  // without virtualization the rows themselves are made sticky.
+  type StickyGroupRow = { row: Row<TData>; rowIndex: number; top: number; size: number };
+  const NO_STICKY: StickyGroupRow[] = [];
+  /** Whether a row is a group and how deep it sits, for any of the three tree sources. */
+  function rowGroupLevel(row: Row<TData>): { group: boolean; level: number } {
+    const sg = props.serverGroup;
+    if (sg) {
+      const data = row.original as TData;
+      return { group: sg.isGroup(data), level: sg.level(data) };
+    }
+    // Client grouping and tree data: an expandable row is the group (a tree
+    // row is a data row too, which is why isGroupRow() excludes it, but for
+    // the band it is the parent its children scroll under).
+    if (typeof row.getCanExpand === "function" && row.getCanExpand()) return { group: true, level: row.depth ?? 0 };
+    return { group: false, level: row.depth ?? 0 };
+  }
+  /** The first row whose bottom edge is under the header, in row-index space. */
+  const firstRowUnderHeader = $derived.by(function firstRowUnderHeader_d() {
+    if (allRows.length === 0) return -1;
+    if (rowVirtualizationEnabled) {
+      virtualizer.version;
+      const offset = virtualizer.getState().scrollOffset;
+      const hit = virtualRows.find((it) => it.end > offset);
+      return hit ? hit.index : -1;
+    }
+    rowResizeVersion;
+    autoRowHeightVersion;
+    const top = scrollMetrics.scrollTop;
+    let acc = 0;
+    let i = 0;
+    while (i < allRows.length - 1 && acc + rowSizePxOf(i) <= top) {
+      acc += rowSizePxOf(i);
+      i += 1;
+    }
+    return i;
+  });
+  const stickyGroupRows = $derived.by(function stickyGroupRows_d(): StickyGroupRow[] {
+    if (!props.stickyGroupRows) return NO_STICKY;
+    const first = firstRowUnderHeader;
+    if (first < 0) return NO_STICKY;
+    const head = allRows[first];
+    if (!head) return NO_STICKY;
+    // A group row at level L, or a leaf at level L, has its ancestors at
+    // levels L-1 .. 0, each the nearest group row above at that level.
+    let want = rowGroupLevel(head).level - 1;
+    if (want < 0) return NO_STICKY;
+    const found: Array<{ row: Row<TData>; rowIndex: number }> = [];
+    for (let i = first - 1; i >= frozenRowCount && want >= 0; i -= 1) {
+      const row = allRows[i]!;
+      const info = rowGroupLevel(row);
+      if (info.group && info.level === want) {
+        found.push({ row, rowIndex: i });
+        want -= 1;
+      }
+    }
+    if (found.length === 0) return NO_STICKY;
+    found.reverse();
+    rowResizeVersion;
+    autoRowHeightVersion;
+    let top = headerHeight + frozenBandHeight;
+    return found.map((f) => {
+      const at = top;
+      const size = rowSizePxOf(f.rowIndex);
+      top += size;
+      return { ...f, top: at, size };
+    });
+  });
+  /** The band's height under virtualization, taken off the top spacer. */
+  const stickyBandHeight = $derived(
+    rowVirtualizationEnabled ? stickyGroupRows.reduce((sum, s) => sum + s.size, 0) : 0,
+  );
+  /** Without virtualization the real row sticks: its top, or undefined. */
+  function stickyTopOfRow(rowIndex: number): number | undefined {
+    if (rowVirtualizationEnabled || stickyGroupRows.length === 0) return undefined;
+    return stickyGroupRows.find((s) => s.rowIndex === rowIndex)?.top;
+  }
+
   // Spacer heights in DOM space. With scaling inert these equal the original
-  // virtualRowStart / virtualRowBottomSpacer. The frozen band is in the flow
-  // before the spacer whatever the window shows, so it comes off the spacer.
-  const rowTopSpacer = $derived(Math.max(virtualRowStart - rowOffsetAdjustment - frozenBandHeight, 0));
+  // virtualRowStart / virtualRowBottomSpacer. The frozen band and the sticky
+  // group band are in the flow before the spacer whatever the window shows,
+  // so they come off the spacer.
+  const rowTopSpacer = $derived(Math.max(virtualRowStart - rowOffsetAdjustment - frozenBandHeight - stickyBandHeight, 0));
   const rowBottomSpacer = $derived(
     Math.max(rowDomTotalSize - (virtualRowEnd - rowOffsetAdjustment), 0),
   );
@@ -3004,10 +3297,7 @@ export function createSvGridController<
    *  `fittedColumnWidths`, so the overflow decision settles in the same
    *  render where fit-scaling lands - no race, no scrollbar flash. */
   const hasHorizontalOverflow = $derived.by(function hasHorizontalOverflow_d() {
-    const fixedCols =
-      (showRowNumbersEffective ? rowNumberColumnWidth : 0) +
-      (showRowSelectionEffective ? selectionColumnWidth : 0);
-    let total = fixedCols;
+    let total = systemColumnsWidth;
     for (const column of allColumns) total += getColumnWidth(column.id);
     // +1 to tolerate sub-pixel rounding residue from `fitColumns`.
     return total > viewportWidth + 1;
@@ -3459,9 +3749,13 @@ export function createSvGridController<
       : typeof rh === "function"
         ? rh
         : (rh ?? 30);
-    const estimateSize = rowResizeHeights.size > 0 || collapsedRows.size > 0
+    // Detail rows have their own height; only when the props say so does
+    // the per-index lookup replace the uniform fast path.
+    const detailOn = props.detailRowHeight != null && !!props.isDetailRow;
+    const estimateSize = rowResizeHeights.size > 0 || collapsedRows.size > 0 || detailOn
       ? (index: number) =>
           rowResizeHeightPx(index) ??
+          detailRowHeightPx(index) ??
           (typeof base === "function" ? base(index) : base)
       : base;
     virtualizer.setOptions({
@@ -3596,7 +3890,21 @@ export function createSvGridController<
   // rows (10k iterations on the large-dataset demo, 100k on its top tier) to
   // recount a selection that had not changed.
   const headerSelectionState = $derived.by(function headerSelectionState_d() {
-    const selectable = allRows.filter((row) => !isGroupRow(row));
+    // An external model knows about rows the grid has never seen, so it is
+    // the only thing that can answer honestly once the data is a window
+    // onto a server.
+    if (props.rowSelectionModel) return props.rowSelectionModel.headerState();
+    // Nothing checked is the common case and needs no walk: this derived
+    // re-runs on every data change, and on a 100k-row live feed the filter
+    // below was 30 ms per tick spent to conclude "none".
+    let anyChecked = false;
+    for (const id in rowSelectionState) {
+      if (rowSelectionState[id]) { anyChecked = true; break; }
+    }
+    if (!anyChecked) return "none";
+    const selectable = allRows.filter(
+      (row) => !isGroupRow(row) && !placeholderStateOf(row),
+    );
     if (!selectable.length) return "none";
     let selected = 0;
     for (const row of selectable) if (rowSelectionState[row.id]) selected += 1;
@@ -3643,8 +3951,6 @@ export function createSvGridController<
     // widths stay in the fit distribution and leave a blank gap at the edge.
     const cols = grid.getAllColumns().filter((c) => !hiddenColumns[c.id] && !hiddenByGroupCollapse[c.id] && !collapsedColumns[c.id]);
     if (!cols.length) return null;
-    const rowNumberWidth = showRowNumbersEffective ? rowNumberColumnWidth : 0;
-    const selectionWidth = showRowSelectionEffective ? selectionColumnWidth : 0;
     // Reserve the custom vertical scrollbar's width when it's visible. It
     // overlays the right 16px of the viewport (absolute, z-index 40) and
     // does NOT shrink clientWidth, so without this the last fitted column
@@ -3653,8 +3959,7 @@ export function createSvGridController<
     const scrollbarWidth = hasVerticalOverflow ? 16 : 0;
     const target =
       (scrollContainer?.clientWidth ?? 0) -
-      rowNumberWidth -
-      selectionWidth -
+      systemColumnsWidth -
       scrollbarWidth;
     if (target <= 0) return null;
 
@@ -3820,7 +4125,12 @@ export function createSvGridController<
     for (const column of allColumns) {
       const meta = isBucketableColumn(column);
       if (!meta) continue;
-      const buckets = buildBuckets(column, meta.isDate, props.data, getColumnAccessorValue);
+      const buckets = buildBuckets(
+        column,
+        meta.isDate,
+        props.data ?? EMPTY_DATA,
+        getColumnAccessorValue,
+      );
       if (buckets) map.set(column.id, buckets);
     }
     return map;
@@ -4147,6 +4457,8 @@ export function createSvGridController<
     set historyPtr(v) { historyPtr = v as never; },
     get historyGroupId() { return historyGroupId; },
     set historyGroupId(v) { historyGroupId = v as never; },
+    get historyTag() { return historyTag; },
+    set historyTag(v) { historyTag = v; },
     get historyVersion() { return historyVersion; },
     set historyVersion(v) { historyVersion = v as never; },
     get tooltip() { return tooltip; },
@@ -4183,6 +4495,11 @@ export function createSvGridController<
     get gridStateVersion() { return gridStateVersion; },
     set gridStateVersion(v) { gridStateVersion = v as never; },
     get selectionColumnWidth() { return selectionColumnWidth; },
+    get detailToggleColumnWidth() { return detailToggleColumnWidth; },
+    get detailToggleColumnLeft() { return detailToggleColumnLeft; },
+    get showDetailToggleEffective() { return showDetailToggleEffective; },
+    get systemColumnsWidth() { return systemColumnsWidth; },
+    get detailToggleOf() { return detailToggleOf; },
     get rowNumberColumnWidth() { return rowNumberColumnWidth; },
     get showRowNumbersEffective() { return showRowNumbersEffective; },
     get filterOperatorOptions() { return filterOperatorOptions; },
@@ -4329,6 +4646,8 @@ export function createSvGridController<
     get selectionBarMaxVisible() { return selectionBarMaxVisible; },
     get selectionBarHideClear() { return selectionBarHideClear; },
     get selectionBarTarget() { return selectionBarTarget; },
+    get selectionBarCount() { return selectionBarCount; },
+    get selectionBarVisible() { return selectionBarVisible; },
     get lastSelectionSerialized() { return lastSelectionSerialized; },
     set lastSelectionSerialized(v) { lastSelectionSerialized = v as never; },
     get lastCellRangeSerialized() { return lastCellRangeSerialized; },
@@ -4598,6 +4917,8 @@ export function createSvGridController<
     get frozenRowList() { return frozenRowList; },
     get frozenBandHeight() { return frozenBandHeight; },
     get frozenRowTop() { return frozenRowTop; },
+    get stickyGroupRows() { return stickyGroupRows; },
+    get stickyTopOfRow() { return stickyTopOfRow; },
     /** Record the height the user dragged a row to. */
     get setRowResizeHeight() { return setRowResizeHeight; },
     get isRowCollapsed() { return isRowCollapsed; },
@@ -4610,6 +4931,12 @@ export function createSvGridController<
       rowResizeVersion;
       return rowResizeHeightPx;
     },
+    /** The height row i is drawn at: dragged, measured, detail, declared or default. */
+    get rowSizePxOf() {
+      rowResizeVersion;
+      autoRowHeightVersion;
+      return rowSizePxOf;
+    },
     get virtualRowTotalSize() { return virtualRowTotalSize; },
     get virtualRowStart() { return virtualRowStart; },
     get virtualRowEnd() { return virtualRowEnd; },
@@ -4664,7 +4991,14 @@ export function createSvGridController<
     get isRowSelected() { return isRowSelected; },
     get toggleRowSelectionById() { return toggleRowSelectionById; },
     get headerSelectionState() { return headerSelectionState; },
+    get visibleRowRange() { return visibleRowRange; },
+    placeholderStateOf,
+    /** Retry a failed placeholder row. No-op without `onRetryRow`. */
+    retryRow(row: Row<TData>) {
+      props.onRetryRow?.(row.original, row.index);
+    },
     get toggleSelectAllRows() { return toggleSelectAllRows; },
+    get setSelectAllRows() { return setSelectAllRows; },
     get userHasActivatedCell() { return userHasActivatedCell; },
     set userHasActivatedCell(v) { userHasActivatedCell = v as never; },
     get tabRunOrigin() { return tabRunOrigin; },
@@ -4814,7 +5148,7 @@ export function createSvGridController<
   const { updateFilterRow, updateFilterOperator, updateFilterMenuValue, updateFilterMenuValueTo, addFilterToken, removeFilterToken, toggleFilterToken, toggleCheckboxWithKeyboard, isColumnFiltered, closeMenus, openInSuggest, closeInSuggest, openChooseColumns, openColumnMenu, openFilterMenu, openOperatorMenu, sortColumnFromMenu, clearColumnSort, groupByColumnFromMenu, clearGroupingFromMenu, isFacetChecked, toggleFacetValue, setFacetSelection, setFilterTokens, isAllFacetsChecked, toggleAllFacets, clearColumnFilter, changePage, goToPage, setPageSize, openContextMenu, closeContextMenu, contextMenuItems, saveComment, removeComment, closeCommentEditor } = createMenus<TFeatures, TData>(ctx);
   const { cellConditionalFormat, computeRowClass, computeCellClass, computeCellTooltip, computeCellValidity, computeCellNote, getColumnEditorOptions, areEditorOptionsLoading, formatListCellValue, formatCellValue, formatPinnedValue, computePinnedCellClass } = createCellRender<TFeatures, TData>(ctx);
   const { isCellEditable, isCellEditableAt, getRowColumnValue, getCellDisplayValue, startEditingWithChar, startEditing, stopEditing, startFullRowEdit, setFullRowDraft, commitFullRowEdit, cancelFullRowEdit, saveEditingCell, applyHistoryStep, updateEditingCellValue, onEditorKeyDown, commitAndMoveByTab, focusOnMount, onCellDoubleClick, pasteFromClipboard, onGridPaste, armPasteFallback } = createEditing<TFeatures, TData>(ctx);
-  const { isRowSelected, toggleRowSelectionById, toggleSelectAllRows, setActiveCell, scrollActiveCellIntoView, setSelection, extendSelection, isCellInSelectedRange, getCellRangeEdges, activeRangeRect, cellSelectionState, getSelectionRects, isInFillPreview, dragPreviewRect, fillMarqueeEdges, findColumnById, onCellPointerDown, onCellPointerEnter, endDragSelection, onWindowPointerMove, onCellClick, emitCellDoubleClick } = createSelection<TFeatures, TData>(ctx);
+  const { isRowSelected, toggleRowSelectionById, toggleSelectAllRows, setSelectAllRows, setActiveCell, scrollActiveCellIntoView, setSelection, extendSelection, isCellInSelectedRange, getCellRangeEdges, activeRangeRect, cellSelectionState, getSelectionRects, isInFillPreview, dragPreviewRect, fillMarqueeEdges, findColumnById, onCellPointerDown, onCellPointerEnter, endDragSelection, onWindowPointerMove, onCellClick, emitCellDoubleClick } = createSelection<TFeatures, TData>(ctx);
   const { cellPinStyle, isColumnPinned, getCurrentColumnOrder, emitColumnOrder, setColumnOrderInternal, applyColumnDrop, onColumnHeaderDragStart, onColumnHeaderDragOver, onColumnHeaderDragLeave, onColumnHeaderDrop, onColumnHeaderDragEnd, pinColumnLeft, pinColumnRight, unpinColumn, toggleColumnVisibleInPanel, moveColumnInPanel, toggleGroupInPanel, getColumnBaseWidth, getColumnWidth, measureText, autosizeColumn, autosizeAllColumns, resetColumns } = createColumns<TFeatures, TData>(ctx);
   const { onRowDragStart, onRowDragOver, onRowDragLeave, onRowDrop, onRowsContainerDragOver, onRowsContainerDrop, onRowDragEnd, onRowPointerDown, destroyRowDrag } = createRowDrag<TFeatures, TData>(ctx);
   const { register: registerAlignedGrid, broadcastScroll: broadcastAlignedScroll, broadcastWidths: broadcastAlignedWidths } = createAlignedGrids<TFeatures, TData>(ctx);
@@ -4854,6 +5188,8 @@ export function createSvGridController<
         pageSize: props.pageSize,
         groupBy: props.groupBy,
         treeData: props.treeData,
+        gantt: props.gantt,
+        serverGroup: props.serverGroup,
         initialColumnPinning: props.initialColumnPinning,
         columnVirtualization: props.columnVirtualization,
         externalPagination: props.externalPagination,