@svgrid/grid 3.0.3 → 4.0.0

package/src/svgrid.row-model-prop.svelte.test.ts

@@ -0,0 +1,352 @@
+/**
+ * `<SvGrid rowModel={ctl} />` - the one-prop integration.
+ *
+ * The seams below it are tested in `svgrid.row-model-seam.svelte.test.ts`;
+ * this suite is about what the prop itself is for: that handing the grid a
+ * model wires all of those seams at once, that the model drives re-renders,
+ * and that writing a prop explicitly still wins - so adopting it is never
+ * all-or-nothing.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import {
+  createCoreRowModel,
+  createServerDataSource,
+  rowSelectionFeature,
+  rowSortingFeature,
+  tableFeatures,
+  type ColumnDef,
+  type GridRowModel,
+  type ServerDataSource,
+  type SvGridApi,
+} from './index'
+
+type Row = { id: number; name: string }
+const features = tableFeatures({ rowSortingFeature, rowSelectionFeature })
+const cols: ColumnDef<typeof features, Row>[] = [{ field: 'name', header: 'Name', width: 160 }]
+
+const tick = () => new Promise<void>((r) => setTimeout(r))
+const settle = async () => {
+  for (let i = 0; i < 20; i += 1) await Promise.resolve()
+  await tick()
+}
+
+function mountGrid(props: Record<string, unknown>) {
+  return new Promise<{
+    api: SvGridApi<typeof features, Row>
+    target: HTMLElement
+    destroy: () => void
+  }>((res, rej) => {
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    const app = mount(SvGrid, {
+      target,
+      props: {
+        columns: cols,
+        features,
+        _rowModels: { coreRowModel: createCoreRowModel() },
+        containerHeight: 200,
+        virtualization: false,
+        onApiReady(api: SvGridApi<typeof features, Row>) {
+          res({ api, target, destroy: () => { unmount(app); target.remove() } })
+        },
+        ...props,
+      } as any,
+    })
+    queueMicrotask(() => {
+      if (!target.querySelector('[role="grid"]')) rej(new Error('no grid'))
+    })
+  })
+}
+
+/** A hand-written model, to prove the grid depends on the shape not the class. */
+function handWritten(rows: Row[]) {
+  const listeners = new Set<() => void>()
+  let current = rows
+  let loading = false
+  const sorts: Array<unknown> = []
+  return {
+    sorts,
+    push(next: Row[]) {
+      current = next
+      for (const l of listeners) l()
+    },
+    setLoading(next: boolean) {
+      loading = next
+      for (const l of listeners) l()
+    },
+    model: {
+      subscribe(onChange: () => void) {
+        listeners.add(onChange)
+        return () => listeners.delete(onChange)
+      },
+      getRows: () => current,
+      isLoading: () => loading,
+      getRowId: (r: Row) => String(r.id),
+      setSort: (s: unknown) => sorts.push(s),
+    } satisfies GridRowModel<Row>,
+  }
+}
+
+describe('the rowModel prop', () => {
+  it('renders the rows the model reports, with no data prop at all', async () => {
+    const source = handWritten([
+      { id: 1, name: 'Ada' },
+      { id: 2, name: 'Grace' },
+    ])
+    const { target, destroy } = await mountGrid({ rowModel: source.model })
+    await tick()
+
+    expect(target.textContent).toContain('Ada')
+    expect(target.textContent).toContain('Grace')
+    destroy()
+  })
+
+  it('re-renders when the model says it changed', async () => {
+    const source = handWritten([{ id: 1, name: 'Ada' }])
+    const { target, destroy } = await mountGrid({ rowModel: source.model })
+    await tick()
+    expect(target.textContent).not.toContain('Linus')
+
+    source.push([{ id: 1, name: 'Ada' }, { id: 9, name: 'Linus' }])
+    await vi.waitFor(() => expect(target.textContent).toContain('Linus'))
+    destroy()
+  })
+
+  it('unsubscribes on unmount', async () => {
+    const source = handWritten([{ id: 1, name: 'Ada' }])
+    const { destroy } = await mountGrid({ rowModel: source.model })
+    await tick()
+    destroy()
+    await tick()
+
+    // A model that outlives the grid must not keep it alive through a
+    // listener; pushing after unmount should reach nobody and throw nothing.
+    expect(() => source.push([{ id: 2, name: 'Grace' }])).not.toThrow()
+  })
+
+  it('takes over sorting when the model sorts, and says so to the grid', async () => {
+    const source = handWritten([
+      { id: 1, name: 'Zoe' },
+      { id: 2, name: 'Ada' },
+    ])
+    const { api, target, destroy } = await mountGrid({ rowModel: source.model, sortable: true })
+    await tick()
+
+    api.setSort('name', 'asc')
+    await tick()
+
+    // The model was told; the grid did NOT reorder locally, because a model
+    // with `setSort` implies `externalSort`. (The grid also reports the
+    // empty initial sort on mount, as it does for any onSortingChange.)
+    expect(source.sorts.at(-1)).toEqual([{ id: 'name', desc: false }])
+    const firstRow = target.querySelector('tbody .sv-grid-row')!
+    expect(firstRow.textContent).toContain('Zoe')
+    destroy()
+  })
+
+  it('lets an explicit prop win over the model', async () => {
+    const source = handWritten([{ id: 1, name: 'Ada' }])
+    const { target, destroy } = await mountGrid({
+      rowModel: source.model,
+      data: [{ id: 7, name: 'Override' }],
+    })
+    await tick()
+
+    expect(target.textContent).toContain('Override')
+    expect(target.textContent).not.toContain('Ada')
+    destroy()
+  })
+
+  it('drives a real server controller end to end', async () => {
+    const source: ServerDataSource<Row> = {
+      async getRows(req) {
+        const all: Row[] = Array.from({ length: 250 }, (_, i) => ({ id: i, name: `Row ${i}` }))
+        const sorted = req.sortModel[0]?.desc ? [...all].reverse() : all
+        return { rows: sorted.slice(req.startRow, req.endRow), rowCount: all.length }
+      },
+    }
+    const ctl = createServerDataSource<Row>(source, {
+      mode: 'infinite',
+      blockSize: 100,
+      onChange: () => {},
+    })
+
+    const { target, destroy } = await mountGrid({ rowModel: ctl })
+
+    // The grid reported its visible range, the controller fetched block 0, and
+    // the rows arrived - with no wiring in this test beyond the one prop.
+    await vi.waitFor(() => expect(target.textContent).toContain('Row 0'))
+    expect(ctl.getCacheState().length).toBeGreaterThan(0)
+    expect(ctl.getRows()).toHaveLength(250)
+    destroy()
+    ctl.dispose()
+  }, 20_000)
+
+  it('wires the pager from a page-mode controller', async () => {
+    const source: ServerDataSource<Row> = {
+      async getRows(req) {
+        const all: Row[] = Array.from({ length: 95 }, (_, i) => ({ id: i, name: `Row ${i}` }))
+        return { rows: all.slice(req.startRow, req.endRow), rowCount: all.length }
+      },
+    }
+    const ctl = createServerDataSource<Row>(source, { pageSize: 20, onChange: () => {} })
+    ctl.refresh()
+    await settle()
+
+    const { api, destroy } = await mountGrid({ rowModel: ctl, pageable: true })
+
+    // 95 rows on the server, not the 20 in hand: the count came from the model.
+    await vi.waitFor(() => expect(api.getPageInfo().pageCount).toBe(5))
+    expect(api.getPageInfo().pageSize).toBe(20)
+    destroy()
+    ctl.dispose()
+  }, 20_000)
+
+  it('takes the page-size choices from the model and sizes the page to the body on request', async () => {
+    const calls: number[] = []
+    let pageSize = 10
+    const rows: Row[] = Array.from({ length: 50 }, (_, i) => ({ id: i, name: `Row ${i}` }))
+    const model: GridRowModel<Row> = {
+      subscribe: () => () => {},
+      getRows: () => rows.slice(0, pageSize),
+      isLoading: () => false,
+      get pagination() {
+        return {
+          pageIndex: 0,
+          pageSize,
+          rowCount: 50,
+          setPage: () => {},
+          setPageSize: (n: number) => {
+            calls.push(n)
+            pageSize = n
+          },
+          pageSizes: [7, 14, 21],
+          autoPageSize: true,
+        }
+      },
+    }
+    // jsdom lays nothing out; give every element a 100px box so the grid
+    // measures its body on mount (the way the responsive test fakes width).
+    const desc = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'clientHeight')
+    Object.defineProperty(HTMLElement.prototype, 'clientHeight', { configurable: true, get: () => 100 })
+    try {
+      const { api, target, destroy } = await mountGrid({ rowModel: model, pageable: true, rowHeight: 20 })
+      // The footer offers the model's sizes, not the grid's defaults.
+      await vi.waitFor(() => expect(target.querySelector('.sv-grid-pagination')).toBeTruthy())
+      expect(api.getOption('pageSizeOptions')).toEqual([7, 14, 21])
+      // Auto size: 100px of body over 20px rows is a page of five.
+      await vi.waitFor(() => expect(calls.at(-1)).toBe(5))
+      destroy()
+    } finally {
+      if (desc) Object.defineProperty(HTMLElement.prototype, 'clientHeight', desc)
+      else delete (HTMLElement.prototype as { clientHeight?: number }).clientHeight
+    }
+  }, 20_000)
+})
+
+describe('editing under a row model', () => {
+  type Node = Row & { kind: "group" | "leaf" }
+  it('refuses to edit a server group row or a placeholder, and edits a leaf', async () => {
+    const nodes: Node[] = [
+      { id: 1, name: 'EMEA', kind: 'group' },
+      { id: 2, name: 'Ada', kind: 'leaf' },
+    ]
+    const model: GridRowModel<Node> = {
+      subscribe: () => () => {},
+      getRows: () => nodes,
+      isLoading: () => false,
+      getRowId: (r) => String(r.id),
+      group: {
+        isGroup: (r) => r.kind === 'group',
+        level: () => 0,
+        expanded: () => false,
+        onToggle: () => {},
+      },
+    }
+    const { api, target, destroy } = await mountGrid({
+      rowModel: model,
+      columns: [{ field: 'name', header: 'Name', width: 160, editorType: 'text' }],
+      editable: true,
+    })
+    try {
+      // The group row: nothing opens, whatever the column says.
+      api.startEditing(0, 'name')
+      await tick()
+      expect(target.querySelector('.sv-grid-cell input')).toBeNull()
+      // The leaf: an editor.
+      api.startEditing(1, 'name')
+      await vi.waitFor(() => expect(target.querySelector('.sv-grid-cell input')).not.toBeNull())
+    } finally {
+      destroy()
+    }
+  })
+})
+
+describe('the rowModel prop with virtualization on', () => {
+  /** 100k rows, so only a window is rendered and most rows are placeholders. */
+  function bigSource(): ServerDataSource<Row> {
+    return {
+      async getRows(req) {
+        const rows: Row[] = []
+        for (let i = req.startRow; i < Math.min(req.endRow, 100_000); i += 1) {
+          rows.push({ id: i, name: `Row ${i}` })
+        }
+        return { rows, rowCount: 100_000 }
+      },
+    }
+  }
+
+  it('renders skeletons for the rows it has not loaded', async () => {
+    const ctl = createServerDataSource<Row>(bigSource(), {
+      mode: 'infinite',
+      blockSize: 100,
+      onChange: () => {},
+    })
+    const { target, destroy } = await mountGrid({
+      rowModel: ctl,
+      virtualization: true,
+      containerHeight: 300,
+      rowHeight: 30,
+    })
+
+    // Block 0 landed, so the window at the top is real data.
+    await vi.waitFor(() => expect(target.textContent).toContain('Row 0'))
+
+    // The grid claims the whole table, and everything outside the loaded
+    // block is a placeholder - which is what keeps the scrollbar honest.
+    const rows = ctl.getRows()
+    expect(rows).toHaveLength(100_000)
+    expect(ctl.rowPlaceholder?.(rows[50_000] as Row, 50_000)).toBe('loading')
+    destroy()
+    ctl.dispose()
+  }, 20_000)
+
+  it('draws skeleton cells for a row the model calls a placeholder', async () => {
+    // Straight through the seam, with no fetching involved: the question here
+    // is only whether `rowModel.rowPlaceholder` reaches the renderer. Driving
+    // it from a real controller cannot answer that - with virtualization off
+    // the grid reports every row as visible, so every block loads and no
+    // placeholder survives to be rendered.
+    const rows: Row[] = [
+      { id: 0, name: 'Ada' },
+      { id: 1, name: 'Grace' },
+      { id: 2, name: 'Linus' },
+    ]
+    const model: GridRowModel<Row> = {
+      subscribe: () => () => {},
+      getRows: () => rows,
+      isLoading: () => false,
+      rowPlaceholder: (row) => (row.id === 2 ? 'loading' : null),
+    }
+    const { target, destroy } = await mountGrid({ rowModel: model })
+    await tick()
+
+    const placeholder = target.querySelector('.sv-grid-placeholder-row')!
+    expect(placeholder).not.toBeNull()
+    expect(placeholder.querySelectorAll('.sv-grid-placeholder-skeleton').length).toBe(cols.length)
+    expect(target.textContent).toContain('Ada')
+    destroy()
+  })
+})

package/src/svgrid.row-model-seam.svelte.test.ts

@@ -0,0 +1,289 @@
+/**
+ * The four seams a server-backed row model plugs into, all free:
+ *
+ *   - `onVisibleRangeChange` - which rows are on screen, by index
+ *   - `rowPlaceholder` / `onRetryRow` - rows whose data has not arrived
+ *   - `rowSelectionModel` - selection the grid does not own
+ *
+ * They are deliberately generic: none of them mentions groups, blocks or a
+ * datasource, so the free infinite controller and the Enterprise row model
+ * plug into the same four holes, and an app with its own fetching can too.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import {
+  createCoreRowModel,
+  rowSelectionFeature,
+  rowSortingFeature,
+  tableFeatures,
+} from './index'
+import type { ColumnDef, SvGridApi } from './index'
+
+type Row = { id: number; name: string }
+const features = tableFeatures({ rowSortingFeature, rowSelectionFeature })
+const cols: ColumnDef<typeof features, Row>[] = [
+  { field: 'name', header: 'Name', width: 160 },
+  { field: 'id', header: 'Id', width: 80 },
+]
+
+const tick = () => new Promise<void>((r) => setTimeout(r))
+const rowsOf = (n: number): Row[] =>
+  Array.from({ length: n }, (_, i) => ({ id: i, name: `Row ${i}` }))
+
+function mountGrid(extra: Record<string, unknown>, data: Row[] = rowsOf(5)) {
+  return new Promise<{
+    api: SvGridApi<typeof features, Row>
+    target: HTMLElement
+    destroy: () => void
+  }>((res, rej) => {
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    const app = mount(SvGrid, {
+      target,
+      props: {
+        data,
+        columns: cols,
+        features,
+        _rowModels: { coreRowModel: createCoreRowModel() },
+        getRowId: (r: Row) => String(r.id),
+        containerHeight: 200,
+        virtualization: false,
+        onApiReady(api: SvGridApi<typeof features, Row>) {
+          res({ api, target, destroy: () => { unmount(app); target.remove() } })
+        },
+        ...extra,
+      } as any,
+    })
+    queueMicrotask(() => {
+      if (!target.querySelector('[role="grid"]')) rej(new Error('no grid'))
+    })
+  })
+}
+
+describe('onVisibleRangeChange', () => {
+  it('reports the whole list when virtualization is off', async () => {
+    const seen: Array<{ startIndex: number; endIndex: number }> = []
+    const { destroy } = await mountGrid({ onVisibleRangeChange: (r: any) => seen.push(r) }, rowsOf(5))
+    await tick()
+
+    expect(seen.at(-1)).toEqual({ startIndex: 0, endIndex: 4 })
+    destroy()
+  })
+
+  it('reports row indices, not pixels, when virtualization is on', async () => {
+    const seen: Array<{ startIndex: number; endIndex: number }> = []
+    const { destroy } = await mountGrid(
+      {
+        onVisibleRangeChange: (r: any) => seen.push(r),
+        virtualization: true,
+        containerHeight: 200,
+      },
+      rowsOf(10_000),
+    )
+    await tick()
+
+    const last = seen.at(-1)!
+    expect(last.startIndex).toBe(0)
+    // A 200px viewport cannot be showing ten thousand rows, and the numbers
+    // are row indices - if these were the pixel offsets the old deriveds
+    // carry, endIndex would be in the hundreds.
+    expect(last.endIndex).toBeGreaterThan(0)
+    expect(last.endIndex).toBeLessThan(200)
+    destroy()
+  })
+
+  it('does not fire again while the range is unchanged', async () => {
+    const seen: Array<unknown> = []
+    const { api, destroy } = await mountGrid({ onVisibleRangeChange: (r: any) => seen.push(r) })
+    await tick()
+    const count = seen.length
+
+    // Something unrelated changes; the visible rows do not.
+    api.selectRows(['1'])
+    await tick()
+    expect(seen).toHaveLength(count)
+    destroy()
+  })
+})
+
+describe('rowPlaceholder', () => {
+  it('draws a skeleton cell per column for a loading row', async () => {
+    const { target, destroy } = await mountGrid({
+      rowPlaceholder: (row: Row) => (row.id === 2 ? 'loading' : null),
+    })
+    await tick()
+
+    const placeholder = target.querySelector('.sv-grid-placeholder-row')!
+    expect(placeholder).not.toBeNull()
+    expect(placeholder.getAttribute('aria-busy')).toBe('true')
+    // One shimmer per real column, so the table keeps its shape.
+    expect(placeholder.querySelectorAll('.sv-grid-placeholder-skeleton')).toHaveLength(cols.length)
+    // And the rows around it are untouched.
+    expect(target.querySelectorAll('.sv-grid-placeholder-row')).toHaveLength(1)
+    destroy()
+  })
+
+  it('draws one full-width message with a Retry button for a failed row', async () => {
+    const retried: Array<{ row: Row; index: number }> = []
+    const { target, destroy } = await mountGrid({
+      rowPlaceholder: (row: Row) => (row.id === 3 ? 'failed' : null),
+      onRetryRow: (row: Row, index: number) => retried.push({ row, index }),
+    })
+    await tick()
+
+    const failed = target.querySelector('.sv-grid-placeholder-failed')!
+    expect(failed).not.toBeNull()
+    expect(failed.textContent).toContain('Could not load')
+    expect(failed.querySelectorAll('.sv-grid-placeholder-skeleton')).toHaveLength(0)
+
+    const retry = failed.querySelector<HTMLButtonElement>('.sv-grid-placeholder-retry')!
+    retry.click()
+    expect(retried).toHaveLength(1)
+    expect(retried[0]!.row.id).toBe(3)
+    expect(retried[0]!.index).toBe(3)
+    destroy()
+  })
+
+  it('gives a run of failed rows one message, and a band under it', async () => {
+    // A failed block is claimed row by row; the message and Retry sit on
+    // the first row of the run, the rest are the same tint with nothing
+    // to read, so a hundred-row block is not a hundred red lines.
+    const { target, destroy } = await mountGrid(
+      {
+        rowPlaceholder: (row: Row) => (row.id >= 2 && row.id <= 4 ? 'failed' : null),
+        onRetryRow: () => {},
+      },
+      rowsOf(7),
+    )
+    await tick()
+    const failed = [...target.querySelectorAll('.sv-grid-placeholder-failed')]
+    expect(failed).toHaveLength(3)
+    expect(failed.map((r) => r.classList.contains('sv-grid-placeholder-failed-cont'))).toEqual([false, true, true])
+    expect(target.querySelectorAll('.sv-grid-placeholder-retry')).toHaveLength(1)
+    expect(failed[0]!.textContent).toContain('Could not load')
+    expect(failed[1]!.textContent!.trim()).toBe('')
+    // Every row of the run keeps its own slot: the scrollbar does not move.
+    expect(target.querySelectorAll('tbody .sv-grid-row').length).toBe(7)
+    destroy()
+  })
+
+  it('omits the Retry button when there is no handler to run', async () => {
+    const { target, destroy } = await mountGrid({
+      rowPlaceholder: (row: Row) => (row.id === 3 ? 'failed' : null),
+    })
+    await tick()
+    expect(target.querySelector('.sv-grid-placeholder-retry')).toBeNull()
+    destroy()
+  })
+
+  it('keeps placeholder rows out of select-all', async () => {
+    const { api, destroy } = await mountGrid({
+      showRowSelection: true,
+      rowPlaceholder: (row: Row) => (row.id >= 3 ? 'loading' : null),
+    })
+    await tick()
+
+    api.selectAllRows()
+    await tick()
+    // Selecting a row that has not loaded would leave an id that never
+    // resolves to anything.
+    expect(api.getSelectedRowIds().sort()).toEqual(['0', '1', '2'])
+    destroy()
+  })
+
+  it('changes nothing for a grid that does not use it', async () => {
+    const { target, destroy } = await mountGrid({})
+    await tick()
+    expect(target.querySelector('.sv-grid-placeholder-row')).toBeNull()
+    expect(target.querySelectorAll('.sv-grid-row').length).toBeGreaterThan(0)
+    destroy()
+  })
+})
+
+describe('rowSelectionModel', () => {
+  /**
+   * "Everything except these", the shape a server-side selection needs.
+   *
+   * Its state is a rune, so the header checkbox re-derives when the model
+   * changes. That is a requirement of the seam, not an accident of the test:
+   * the grid re-reads `headerState()` only when something reactive that it
+   * touched has changed.
+   */
+  function exceptModel(totalRows: number) {
+    const state = $state({ selectAll: false, toggled: new Set<string>() })
+    return {
+      state,
+      isSelected: (rowId: string) => state.selectAll !== state.toggled.has(rowId),
+      headerState: () => {
+        if (state.selectAll) return state.toggled.size === 0 ? 'all' : 'some'
+        return state.toggled.size === 0 ? 'none' : 'some'
+      },
+      toggle: (rowId: string) => {
+        const next = new Set(state.toggled)
+        if (next.has(rowId)) next.delete(rowId)
+        else next.add(rowId)
+        state.toggled = next
+      },
+      toggleAll: (next: boolean) => {
+        state.selectAll = next
+        state.toggled = new Set()
+      },
+      selectedCount: () => (state.selectAll ? totalRows - state.toggled.size : state.toggled.size),
+    }
+  }
+
+  it('answers the header checkbox instead of counting loaded rows', async () => {
+    const model = exceptModel(1_000_000)
+    const { target, destroy } = await mountGrid({ showRowSelection: true, rowSelectionModel: model })
+    await tick()
+
+    const header = target.querySelector('thead [role="checkbox"], thead input[type="checkbox"]')!
+    expect(header.getAttribute('aria-checked')).toBe('false')
+
+    model.toggleAll(true)
+    await vi.waitFor(() =>
+      expect(
+        target.querySelector('thead [role="checkbox"], thead input[type="checkbox"]')!
+          .getAttribute('aria-checked'),
+      ).toBe('true'),
+    )
+    // Five rows are loaded; a million are selected. The grid says "all"
+    // because the model said so, which is the whole point of the seam.
+    expect(model.selectedCount()).toBe(1_000_000)
+    destroy()
+  })
+
+  it('routes the header checkbox click to toggleAll, not to the loaded rows', async () => {
+    const model = exceptModel(1_000_000)
+    const { target, destroy } = await mountGrid({ showRowSelection: true, rowSelectionModel: model })
+    await tick()
+
+    const header = target.querySelector<HTMLElement>('thead [role="checkbox"], thead input[type="checkbox"]')!
+    header.click()
+    await tick()
+
+    expect(model.state.selectAll).toBe(true)
+    expect(model.selectedCount()).toBe(1_000_000)
+    destroy()
+  })
+
+  it('routes a row checkbox through the model', async () => {
+    const model = exceptModel(1_000_000)
+    const { api, destroy } = await mountGrid({ showRowSelection: true, rowSelectionModel: model })
+    await tick()
+
+    api.toggleRowSelected('2')
+    await tick()
+    expect(model.state.toggled.has('2')).toBe(true)
+    expect(model.isSelected('2')).toBe(true)
+
+    model.toggleAll(true)
+    await tick()
+    api.toggleRowSelected('2')
+    // Under select-all, toggling a row means "except this one".
+    expect(model.isSelected('2')).toBe(false)
+    expect(model.selectedCount()).toBe(999_999)
+    destroy()
+  })
+})

package/src/validate.test.ts

@@ -5,6 +5,7 @@
  */
 import { describe, expect, it } from 'vitest'
 import { validateGridConfig } from './validate'
+import { createRowPlaceholder } from './server-block-cache'
 
 type Row = { name: string; amount: number }
 const data: Row[] = [
@@ -48,6 +49,15 @@ describe('unknown field', () => {
     expect(run({ columns: [{ id: 'actions', header: '' }] })).toEqual([])
   })
 
+  it('looks past placeholder rows, which a row model shows before its data lands', () => {
+    const loading = [createRowPlaceholder('loading', { index: 0 }), createRowPlaceholder('loading', { index: 1 })]
+    // Only placeholders: nothing to judge the columns by, so no warning.
+    expect(run({ data: loading })).toEqual([])
+    // Placeholders ahead of real rows: the real rows are the sample.
+    expect(run({ data: [...loading, ...data] })).toEqual([])
+    expect(run({ data: [...loading, ...data], columns: [{ field: 'naem' }] })).toHaveLength(1)
+  })
+
   it('looks through group columns', () => {
     const msgs = run({ columns: [{ header: 'Group', columns: [{ field: 'nope' }] }] })
     expect(msgs[0]).toContain('"nope" does not exist')

package/src/validate.ts

@@ -20,6 +20,7 @@
  *     changes, and must not scale with row count.
  */
 import type { ColumnDef, RowData, TableFeatures } from './core'
+import { rowPlaceholderState } from './server-block-cache'
 
 /** How many rows to sample when deciding whether a `field` exists. */
 const FIELD_SAMPLE_ROWS = 10
@@ -37,6 +38,8 @@ export type ValidateInput<TFeatures extends TableFeatures, TData extends RowData
   pageSize?: number
   groupBy?: ReadonlyArray<string>
   treeData?: { parentField?: string; 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> }
   columnVirtualization?: boolean
   externalPagination?: boolean
@@ -69,9 +72,13 @@ export function validateGridConfig<
   // ---- 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<string>()
     for (const row of sample) {
       if (row && typeof row === 'object') for (const k of Object.keys(row)) known.add(k)