@svgrid/grid 3.0.3 → 3.0.5

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/svgrid.upsell-license.test.ts

@@ -1,11 +1,11 @@
 /**
  * Every Enterprise gate carries the same licensing line.
  *
- * There are four of them - Kanban board, scheduler, pivot mode and the
- * selection bar - and they used to be four hand-written paragraphs. Four gates
- * worded four ways is how a product ends up explaining its own licensing
+ * There are five of them - Kanban board, scheduler, Gantt, pivot mode and the
+ * selection bar - and they used to be four hand-written paragraphs. Gates
+ * worded one way each is how a product ends up explaining its own licensing
  * inconsistently, so they now share one snippet. This is the test that keeps
- * them sharing it: a fifth Enterprise feature that hand-rolls its own note
+ * them sharing it: a sixth Enterprise feature that hand-rolls its own note
  * will show up here as a missing licensing line.
  *
  * None of the renderers are registered in this file, which is the point - it
@@ -17,6 +17,7 @@ import SvGrid from './SvGrid.svelte'
 import {
   createCoreRowModel,
   hasBoardView,
+  hasGanttView,
   hasSchedulerView,
   hasSelectionBarView,
   tableFeatures,
@@ -69,12 +70,14 @@ describe('Enterprise upsell notes', () => {
     // Otherwise every assertion below is checking the wrong branch.
     expect(hasBoardView()).toBe(false)
     expect(hasSchedulerView()).toBe(false)
+    expect(hasGanttView()).toBe(false)
     expect(hasSelectionBarView()).toBe(false)
   })
 
   const gates: Array<[string, Record<string, unknown>, ((api: SvGridApi<typeof features, Row>) => void)?]> = [
     ['Kanban board', { board: { groupBy: 'team' } }],
     ['scheduler', { scheduler: { startField: 'name' } }],
+    ['Gantt', { gantt: { startField: 'name' } }],
     ['selection bar', { showRowSelection: true, selectionBar: true }, (api) => api.selectRows(['1'])],
     // pivotViewOn = a pivot config AND pivot mode on; without the Pro engine
     // `pivotResult` stays null and the upsell renders in its place.

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')
@@ -151,6 +161,25 @@ describe('treeData fields', () => {
   })
 })
 
+describe('gantt versus treeData', () => {
+  it('flags both trees being configured at once', () => {
+    const msg = run({ gantt: { startField: 'name' }, treeData: { parentField: 'name' } }).find(
+      (m) => m.includes('`gantt` and `treeData`'),
+    )!
+    expect(msg).toBeDefined()
+    expect(msg).toContain('gantt.parentField')
+    expect(msg).toContain('summary bars will under-report')
+  })
+
+  it('is silent for a Gantt on its own', () => {
+    expect(run({ gantt: { startField: 'name' } })).toEqual([])
+  })
+
+  it('is silent for treeData on its own', () => {
+    expect(run({ treeData: { parentField: 'name' } })).toEqual([])
+  })
+})
+
 describe('pinning versus column virtualization', () => {
   it('flags pinning while column virtualization is on by default', () => {
     const msg = run({ initialColumnPinning: { left: ['name'] } })[0]!

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,10 @@ export type ValidateInput<TFeatures extends TableFeatures, TData extends RowData
   pageSize?: number
   groupBy?: ReadonlyArray<string>
   treeData?: { parentField?: string; idField?: string; column?: string }
+  /** Gantt mode. Only its presence matters here - see rule 6b. */
+  gantt?: unknown
+  /** 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 +74,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)
@@ -189,6 +198,22 @@ export function validateGridConfig<
     }
   }
 
+  // ---- 6b. gantt + treeData: two trees over one set of rows -----------------
+  // The Gantt builds its own work-breakdown tree from `gantt.parentField`,
+  // because it needs every descendant - a collapsed phase still contributes to
+  // its summary bar. `treeData` hides collapsed children from the view before
+  // the renderer sees them, so the two together silently drop tasks out of
+  // their phase's rollup the moment anything is collapsed.
+  if (input.gantt && input.treeData) {
+    messages.push(
+      '[svgrid] `gantt` and `treeData` are both set. The Gantt builds its own ' +
+        'work-breakdown tree from `gantt.parentField` and needs every ' +
+        'descendant row, but `treeData` hides collapsed children from the view, ' +
+        'so summary bars will under-report. Remove `treeData` and set ' +
+        '`gantt.parentField` instead.',
+    )
+  }
+
   // ---- 7. Pinning that column virtualization will hide ----------------------
   // Documented incompatibility: the virtualizer recycles column DOM nodes, so
   // sticky pinning cannot survive it. `columnVirtualization` defaults to ON,

package/src/virtualization/virtualizer.ts

@@ -33,29 +33,46 @@ function sameState(a: VirtualizerState, b: VirtualizerState) {
   for (let i = 0; i < a.items.length; i += 1) {
     const ai = a.items[i]!
     const bi = b.items[i]!
-    if (ai.index !== bi.index || ai.start !== bi.start || ai.size !== bi.size) return false
+    if (ai.index !== bi.index || ai.start !== bi.start || ai.size !== bi.size || ai.key !== bi.key) return false
   }
   return true
 }
 
-// Slot-based keying: the key is the POSITION of the item inside the
-// visible window (slot 0 = topmost rendered row, slot 1 = next, etc.)
-// - NOT the data index. As the user scrolls, the window's startIndex
-// changes but the slot keys stay the same (0..N-1), so Svelte recycles
-// the existing <tr> DOM nodes and only updates their data + position.
+// Slot-based keying: the key is a SLOT number, not the data index, so the
+// same N <tr> nodes stay alive for the lifetime of the grid and scrolling
+// never mounts or unmounts a row. With data-index keys, scrolling down one
+// row meant the old topmost key disappeared and a new bottommost key
+// appeared, so Svelte unmounted the top <tr> and mounted a fresh one at the
+// bottom on every scroll tick.
 //
-// This avoids the mount/unmount churn that previously fired on every
-// scroll tick: with data-index keys, scrolling down 1 row meant the old
-// topmost key disappeared and a new bottommost key appeared, forcing
-// Svelte to unmount the top <tr> and mount a fresh one at the bottom.
-// Slot-based keys keep the same N <tr> nodes alive for the lifetime of
-// the grid; scroll just translates them via the top spacer.
+// The slot for data index i is `i mod N`, N being the window length. That
+// matters for what a one-row scroll costs: while N holds, a row that stays
+// inside the window keeps its slot, so Svelte keeps its <tr> and touches
+// nothing in it, and only the row that entered gets new content - the keyed
+// each moves that one <tr> to the other end with a single `insertBefore`.
+// The earlier `i - startIndex` slot scheme handed EVERY rendered row a new
+// index on every one-row scroll, so an arrow key re-rendered all ~30 rows x
+// every rendered column to shift the data up by one.
+//
+// The modulus has to be EXACTLY N, not merely >= N: under a larger modulus
+// the window's residues are a proper subset, so each one-row scroll drops
+// one residue and picks up another, and Svelte unmounts a <tr> and mounts a
+// fresh one instead of moving it (measured: mount + unmount per arrow key,
+// zero moves). When N changes - the top and bottom overscan clamping on the
+// first and last rows, a resize, variable row heights - every slot remaps
+// and the whole window re-renders once, which is what the old scheme did on
+// every tick.
+function slotKey(index: number, windowLength: number): string {
+  return `virtual_slot_${index % windowLength}`
+}
+
 function buildUniformItems(
   startIndex: number,
   endIndex: number,
   estimateSize: number,
 ): Array<VirtualItem> {
   const items: Array<VirtualItem> = []
+  const windowLength = endIndex - startIndex + 1
   for (let index = startIndex; index <= endIndex; index += 1) {
     const start = index * estimateSize
     items.push({
@@ -63,7 +80,7 @@ function buildUniformItems(
       start,
       size: estimateSize,
       end: start + estimateSize,
-      key: `virtual_slot_${index - startIndex}`,
+      key: slotKey(index, windowLength),
     })
   }
   return items
@@ -91,8 +108,8 @@ export function buildPreMeasureItems(
   if (count <= 0) return []
   const size = Math.max(estimateSize, 1)
   const visible = Math.ceil(Math.max(viewportHeight, 0) / size)
-  const endIndex = Math.min(visible + Math.max(overscan, 0), count - 1)
-  return buildUniformItems(0, Math.max(endIndex, 0), size)
+  const endIndex = Math.max(Math.min(visible + Math.max(overscan, 0), count - 1), 0)
+  return buildUniformItems(0, endIndex, size)
 }
 
 function buildVariableItems(
@@ -101,6 +118,7 @@ function buildVariableItems(
   offsets: Array<number>,
 ): Array<VirtualItem> {
   const items: Array<VirtualItem> = []
+  const windowLength = endIndex - startIndex + 1
   for (let index = startIndex; index <= endIndex; index += 1) {
     const start = offsets[index] ?? 0
     const end = offsets[index + 1] ?? start
@@ -109,7 +127,7 @@ function buildVariableItems(
       start,
       size: end - start,
       end,
-      key: `virtual_slot_${index - startIndex}`,
+      key: slotKey(index, windowLength),
     })
   }
   return items
@@ -215,8 +233,12 @@ export function createVirtualizer(initial: VirtualizerOptions) {
     const sizeFn = options.estimateSize
     const offsets = new Array<number>(count + 1)
     offsets[0] = 0
+    // A size of 0 is a real size: a collapsed row or column takes no room
+    // and both searches below stay monotonic over equal offsets. Only a
+    // negative size is nonsense. The floor used to be 1, which left every
+    // hidden column a one-pixel sliver.
     for (let i = 0; i < count; i += 1) {
-      offsets[i + 1] = offsets[i]! + Math.max(sizeFn(i), 1)
+      offsets[i + 1] = offsets[i]! + Math.max(sizeFn(i), 0)
     }
     offsetCache = { fn: sizeFn, count, offsets }
     return offsets