@svgrid/grid 3.0.4 → 4.0.0

package/dist/server.js

@@ -0,0 +1,13 @@
+/**
+ * `@svgrid/grid/server` - the server-side data primitives, with no Svelte in
+ * the import graph.
+ *
+ * Everything here is also on the package root. This entry point exists for
+ * code that must not pull `SvGrid.svelte` into its bundle or its test
+ * runner: a SvelteKit `+server.ts` shaping a `ServerRequest` into a query,
+ * a worker feeding a block cache, or `@svgrid/enterprise`'s own row model,
+ * whose unit tests run without the Svelte compiler.
+ */
+export { createServerDataSource, } from './server-data-source.js';
+export { createBlockCache, createRowPlaceholder, rowPlaceholderState, } from './server-block-cache.js';
+export { toServerFilterColumns, } from './row-model.js';

package/dist/validate.d.ts

@@ -35,6 +35,8 @@ export type ValidateInput<TFeatures extends TableFeatures, TData extends RowData
         idField?: string;
         column?: string;
     };
+    /** Server-side grouping: group rows carry their key and aggregates, not the leaf fields. */
+    serverGroup?: unknown;
     initialColumnPinning?: {
         left?: ReadonlyArray<string>;
         right?: ReadonlyArray<string>;

package/dist/validate.js

@@ -1,3 +1,4 @@
+import { rowPlaceholderState } from './server-block-cache.js';
 /** How many rows to sample when deciding whether a `field` exists. */
 const FIELD_SAMPLE_ROWS = 10;
 const DOCS = 'https://svgrid.com/docs/getting-started/3-data-and-columns/';
@@ -17,9 +18,13 @@ export function validateGridConfig(input) {
     // ---- 1. A `field` that does not exist on the data -------------------------
     // The single most expensive silent failure: the column renders, and every
     // cell in it is blank. Sampled across several rows so genuinely sparse data
-    // (a key absent from row 0 but present later) does not trip it.
-    const sample = (input.data ?? []).slice(0, FIELD_SAMPLE_ROWS);
-    if (sample.length) {
+    // (a key absent from row 0 but present later) does not trip it. A row
+    // model shows placeholder rows before its first block lands; those carry
+    // no data keys at all and say nothing about the columns.
+    const sample = (input.data ?? []).filter((row) => !rowPlaceholderState(row)).slice(0, FIELD_SAMPLE_ROWS);
+    // Under server-side grouping the first rows are group rows, which carry
+    // a key and aggregates and none of the leaf fields; nothing to judge by.
+    if (sample.length && !input.serverGroup) {
         const known = new Set();
         for (const row of sample) {
             if (row && typeof row === 'object')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svgrid/grid",
-  "version": "3.0.4",
+  "version": "4.0.0",
   "description": "Svelte 5-native data grid and data table. Headless-first engine with virtual scrolling for 100k+ rows, Excel-style filtering, inline editing, grouping, tree data, pivot, and server-side data. Drop-in <SvGrid> component. TypeScript, SSR-ready.",
   "author": "jQWidgets <boikom@jqwidgets.com>",
   "license": "MIT",
@@ -99,6 +99,11 @@
       "svelte": "./dist/shortcut-registry.js",
       "import": "./dist/shortcut-registry.js"
     },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "svelte": "./dist/server.js",
+      "import": "./dist/server.js"
+    },
     "./flex-render": {
       "types": "./dist/flex-render.d.ts",
       "svelte": "./dist/flex-render.js",

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>;
 
@@ -739,7 +807,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 +862,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(() => {
@@ -1037,6 +1108,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,
@@ -1805,15 +1890,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.
@@ -2833,6 +2945,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
@@ -3596,7 +3757,13 @@ 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();
+    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;
@@ -3820,7 +3987,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;
@@ -4329,6 +4501,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; },
@@ -4664,7 +4838,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 +4995,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 +5035,7 @@ export function createSvGridController<
         pageSize: props.pageSize,
         groupBy: props.groupBy,
         treeData: props.treeData,
+        serverGroup: props.serverGroup,
         initialColumnPinning: props.initialColumnPinning,
         columnVirtualization: props.columnVirtualization,
         externalPagination: props.externalPagination,

package/src/SvGrid.css

@@ -463,6 +463,79 @@
   user-select: text;
 }
 
+/* Rows whose data has not arrived yet (server-side / infinite loading).
+
+   The shimmer is per CELL, not per row, so the columns keep their widths
+   and the table does not reflow as blocks land. Widths vary a little by
+   column position so a screenful of them reads as text rather than as a
+   barcode - the same trick every skeleton screen uses. */
+.sv-grid-placeholder-cell {
+  user-select: none;
+  cursor: default;
+}
+/* The per-cell shimmer of a placeholder row. Its own name: `.sv-grid-skeleton`
+   above is the full-body loading overlay, absolutely positioned under the
+   header, and sharing it pulled every placeholder cell's bar up there. */
+.sv-grid-placeholder-skeleton {
+  display: inline-block;
+  width: 72%;
+  height: 9px;
+  border-radius: 5px;
+  vertical-align: middle;
+  background: linear-gradient(
+    90deg,
+    color-mix(in srgb, var(--sg-fg, #0f172a) 8%, transparent) 25%,
+    color-mix(in srgb, var(--sg-fg, #0f172a) 3%, transparent) 50%,
+    color-mix(in srgb, var(--sg-fg, #0f172a) 8%, transparent) 75%
+  );
+  background-size: 200% 100%;
+  animation: sv-grid-skeleton-shimmer 1.2s linear infinite;
+}
+.sv-grid-placeholder-cell:nth-child(2n) .sv-grid-placeholder-skeleton { width: 54%; }
+.sv-grid-placeholder-cell:nth-child(3n) .sv-grid-placeholder-skeleton { width: 84%; }
+@keyframes sv-grid-skeleton-shimmer {
+  from { background-position: 200% 0; }
+  to { background-position: -200% 0; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .sv-grid-placeholder-skeleton { animation: none; }
+}
+
+/* A block that failed to load: one message across the row, and a way out.
+   The cell stays a table cell so its colspan holds; the flex box is inside
+   it (a flex `td` stops spanning and the tint shrank to the text). Rows
+   that continue a failed run are the same band without the message. */
+.sv-grid-placeholder-failed .sv-grid-placeholder-cell {
+  background: color-mix(in srgb, var(--sg-danger, #dc2626) 6%, transparent);
+}
+.sv-grid-placeholder-failed-body {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-height: 100%;
+  padding-left: var(--sg-cell-px, 7px);
+}
+.sv-grid-placeholder-failed-cont .sv-grid-placeholder-cell {
+  border-top-color: transparent;
+}
+.sv-grid-placeholder-error {
+  color: var(--sg-danger, #dc2626);
+  font-size: 13px;
+}
+.sv-grid-placeholder-retry {
+  background: none;
+  border: 1px solid var(--sg-border, #e2e8f0);
+  border-radius: var(--sg-radius, 6px);
+  padding: 2px 10px;
+  font: inherit;
+  font-size: 12px;
+  color: var(--sg-fg, #0f172a);
+  cursor: pointer;
+}
+.sv-grid-placeholder-retry:hover {
+  background: color-mix(in srgb, var(--sg-fg, #0f172a) 6%, transparent);
+}
+
 /* Pinned columns read as "frozen" via three layered cues:
      1. A distinct fill (slightly stronger than the header) so the
         pinned strip is visible even before you scroll. Themes with a

package/src/SvGrid.svelte

@@ -408,6 +408,11 @@
     ctrl.columnVirtualizationEnabled,
   );
   const virtualRows = $derived(ctrl.virtualRows);
+  // The first body row on screen: where a failed run that started above
+  // the window repeats its message.
+  const firstRenderedRowIndex = $derived(
+    rowVirtualizationEnabled ? (virtualRows[0]?.index ?? 0) : 0,
+  );
   const frozenRowCount = $derived(ctrl.frozenRowCount);
   const frozenRowList = $derived(ctrl.frozenRowList);
   // Merged cells. A merge is drawn once per band (the frozen rows, the
@@ -1461,6 +1466,73 @@
     </tr>
   {/snippet}
 
+  <!-- A row whose data has not arrived.
+
+       "loading" keeps the real columns and draws a shimmer bar in each,
+       so the table keeps its shape while blocks stream in - a full-width
+       bar would make the whole grid jump every time one landed. "failed"
+       is the opposite case: there is nothing per-column to say, just one
+       message and a way to try again, so it spans the row like a detail
+       cell does. Neither is selectable or editable; there is nothing
+       there to act on.
+
+       A failed block is a run of failed rows, one per row it claimed,
+       and one message serves the run: the first failed row on screen
+       carries it (the run's first row, or the top of the window when
+       the run started above it) and the rows under it are a plain
+       tinted band. A hundred "Could not load" lines for one block
+       was a wall of red. -->
+  {#snippet placeholderRowMarkup(
+    phRow: Row<TData>,
+    phRowIndex: number,
+    phState: "loading" | "failed",
+    phStyle: string,
+    phContinues: boolean,
+  )}
+    <tr
+      class="sv-grid-row sv-grid-placeholder-row"
+      class:sv-grid-placeholder-failed={phState === "failed"}
+      class:sv-grid-placeholder-failed-cont={phContinues}
+      aria-busy={phState === "loading" ? "true" : undefined}
+      {...getGridRowA11yProps(phRowIndex + 1)}
+      style={phStyle}
+    >
+      {#if phState === "failed"}
+        <td
+          class="sv-grid-cell sv-grid-placeholder-cell"
+          colspan={allColumns.length +
+            (showRowNumbersEffective ? 1 : 0) +
+            (showRowSelectionEffective ? 1 : 0)}
+        >
+          {#if !phContinues}
+            <div class="sv-grid-placeholder-failed-body">
+              <span class="sv-grid-placeholder-error">{messages.rowLoadFailed}</span>
+              {#if opt.onRetryRow}
+                <button
+                  type="button"
+                  class="sv-grid-placeholder-retry"
+                  onclick={() => ctrl.retryRow(phRow)}>{messages.rowLoadRetry}</button
+                >
+              {/if}
+            </div>
+          {/if}
+        </td>
+      {:else}
+        {#if showRowNumbersEffective}
+          <td class="sv-grid-cell sv-grid-rownum-cell"></td>
+        {/if}
+        {#if showRowSelectionEffective}
+          <td class="sv-grid-cell sv-grid-select-cell"></td>
+        {/if}
+        {#each allColumns as col (col.id)}
+          <td class="sv-grid-cell sv-grid-placeholder-cell">
+            <span class="sv-grid-placeholder-skeleton" aria-hidden="true"></span>
+          </td>
+        {/each}
+      {/if}
+    </tr>
+  {/snippet}
+
   <!-- A single pinned row (top or bottom). Read-only by design: no
        inline editing, no row-selection checkbox, no fill handle.
        Position-sticky CSS keeps it anchored to the top of the body or
@@ -1474,7 +1546,14 @@
     the virtualizer's measured size, or the declared one.
   -->
   {#snippet bodyRow(row: Row<TData>, rowIndex: number, rowStyle: string)}
-                  {#if opt.isDetailRow?.(row.original as TData, rowIndex)}
+                  {@const phState = ctrl.placeholderStateOf(row)}
+                  {#if phState}
+                    {@const phContinues =
+                      phState === "failed" &&
+                      rowIndex > firstRenderedRowIndex &&
+                      ctrl.placeholderStateOf(allRows[rowIndex - 1]!) === "failed"}
+                    {@render placeholderRowMarkup(row, rowIndex, phState, rowStyle, phContinues)}
+                  {:else if opt.isDetailRow?.(row.original as TData, rowIndex)}
                     {@render detailRowMarkup(row, rowIndex)}
                   {:else if isGroupRow(row) && !groupColumnMode}
                     <tr
@@ -1827,7 +1906,7 @@
     style={chartDockReserveStyle}
     data-move-grab={ctrl.moveGrabHover || ctrl.moveDrag ? "true" : undefined}
     data-selbar={
-      ctrl.selectionBarOn && ctrl.selectionBarTarget.ids.length > 0
+      ctrl.selectionBarVisible
         ? (getSelectionBarView() ? ctrl.selectionBarPosition : `upsell-${ctrl.selectionBarPosition}`)
         : undefined
     }
@@ -3004,7 +3083,7 @@
          `absolute` against it, so moving it outside would anchor it to the
          page. The renderer is Enterprise and arrives through the
          selection-bar-view seam; without it, a short note in its place. -->
-    {#if ctrl.selectionBarOn && ctrl.selectionBarTarget.ids.length > 0}
+    {#if ctrl.selectionBarVisible}
       {#if getSelectionBarView()}
         {@const SelectionBarView = getSelectionBarView()}
         <SelectionBarView {ctrl} />