@svgrid/grid 3.0.7 → 3.0.9

package/src/headless.reactivity.svelte.test.ts

@@ -0,0 +1,89 @@
+/**
+ * The headless docs tell you to write:
+ *
+ *   const table = createSvGrid({ ..., state: { sorting }, onSortingChange })
+ *   const rows  = $derived(table.getRowModel().rows)
+ *
+ * `createStore` (core.ts) is a plain closure + listener set, NOT runes, and
+ * `options.state` is spread into the initial store once at creation. So that
+ * `$derived` has no reactive dependency on the engine's state: clicking a
+ * header updates the store and the component's own `sorting` rune, the sort
+ * indicator moves, and the ROWS never recompute.
+ *
+ * Caught while recording the headless video: the arrow cleared and the order
+ * did not change. Lives in a `.svelte.test.ts` so `$state` is available.
+ */
+import { describe, expect, it } from 'vitest'
+import { flushSync } from 'svelte'
+import {
+  createSvGrid,
+  createCoreRowModel,
+  createSortedRowModel,
+  tableFeatures,
+  rowSortingFeature,
+} from './index'
+
+type Repo = { name: string; stars: number }
+
+// Deliberately NOT in stars order: clearing the sort has to produce a
+// visibly different list, or the assertions below prove nothing.
+const data: Repo[] = [
+  { name: 'sv-grid', stars: 172 },
+  { name: 'svelte', stars: 78000 },
+  { name: 'vite', stars: 68000 },
+]
+
+const features = tableFeatures({ rowSortingFeature })
+const columns = [
+  { field: 'name', header: 'Repo' },
+  { field: 'stars', header: 'Stars' },
+] as never
+
+function build(onSortingChange: (next: unknown) => void, seed: Array<{ id: string; desc: boolean }>) {
+  return createSvGrid({
+    _features: features,
+    _rowModels: {
+      coreRowModel: createCoreRowModel<Repo>(),
+      sortedRowModel: createSortedRowModel<Repo>(),
+    },
+    data,
+    columns,
+    state: { sorting: seed },
+    onSortingChange,
+  } as never)
+}
+
+describe('headless state reactivity', () => {
+  it('seeds the sort from options.state', () => {
+    const table = build(() => {}, [{ id: 'stars', desc: true }])
+    const names = table.getRowModel().rows.map((r) => (r.original as Repo).name)
+    expect(names).toEqual(['svelte', 'vite', 'sv-grid'])
+  })
+
+  it('re-sorts when the toggle handler runs', () => {
+    let sorting = $state([{ id: 'stars', desc: true }])
+    const table = build((next) => (sorting = next as typeof sorting), sorting)
+
+    // The pattern the headless docs now teach: touch the state rune the
+    // component owns so the derived re-runs. A plain
+    // `$derived(table.getRowModel().rows)` reads only the framework-free
+    // engine and never recomputes, which is the bug this guards.
+    const rows = $derived.by(() => {
+      void sorting
+      return table.getRowModel().rows
+    })
+    expect(rows.map((r) => (r.original as Repo).name)).toEqual(['svelte', 'vite', 'sv-grid'])
+
+    const stars = table.getAllColumns().find((c) => c.id === 'stars')!
+    stars.getToggleSortingHandler()()
+    flushSync()
+
+    // The engine's own state really did change...
+    expect(table.getState().sorting).toEqual([])
+    // ...and the component's rune did too, which is why the arrow clears.
+    expect(sorting).toEqual([])
+
+    // The rows must follow the cleared sort, i.e. fall back to data order.
+    expect(rows.map((r) => (r.original as Repo).name)).toEqual(['sv-grid', 'svelte', 'vite'])
+  })
+})

package/src/headless.ts

@@ -84,7 +84,7 @@ export {
 
 export { createGrid, createSvGrid, type SvelteGrid } from './createGrid.svelte'
 export { createGridState, createSvGridState } from './createGridState.svelte'
-export { subscribeGrid, subscribeSvGrid } from './subscribe'
+export { subscribeGrid, subscribeSvGrid } from './subscribe.svelte'
 
 // The virtualizers are pure window arithmetic (scroll offset in, visible
 // range out) with no DOM of their own, and a custom renderer over 50k rows

package/src/index.ts

@@ -73,7 +73,7 @@ export {
 
 export { createGrid, createSvGrid, type SvelteGrid } from './createGrid.svelte'
 export { createGridState, createSvGridState } from './createGridState.svelte'
-export { subscribeGrid, subscribeSvGrid } from './subscribe'
+export { subscribeGrid, subscribeSvGrid } from './subscribe.svelte'
 export { default as SvGrid } from './SvGrid.svelte'
 // Kanban board view. The `board` prop + its config types live in the free grid,
 // but the RENDERER (SvGridBoard) ships in @svgrid/enterprise and registers itself
@@ -801,6 +801,12 @@ export {
   type BlockFetchResult,
   type BlockState,
 } from './server-block-cache'
+export {
+  createWindowedData,
+  windowedSourceOf,
+  isWindowedData,
+  type WindowedSource,
+} from './windowed-data'
 export {
   toServerFilterColumns,
   type GridRowModel,

package/src/keyboard-handlers.ts

@@ -216,7 +216,11 @@ export function createKeyboard<
         }
       }
       if (column?.columnDef.editorType === "checkbox") {
-        ctx.toggleBooleanCell(current.rowIndex, current.colIndex);
+        // Same rule as a click: `editable: false` (or an editable callback
+        // saying no) keeps the checkbox read-only.
+        if (ctx.isCellEditableAt?.(current.rowIndex, current.colIndex) ?? true) {
+          ctx.toggleBooleanCell(current.rowIndex, current.colIndex);
+        }
         return;
       }
       ctx.onCellDoubleClick(current.rowIndex, current.colIndex);

package/src/new-features.test.ts

@@ -70,6 +70,8 @@ describe('createSvGrid - getRowId', () => {
       },
     }).getRowModel().rows
     expect(rows).toHaveLength(data.length)
+    // Rows are made when read (a first build is lazy), so read each one.
+    expect(rows.map((r) => r.id)).toEqual(['ada', 'linus', 'grace'])
     expect(seen).toEqual([
       { id: 'ada',   index: 0 },
       { id: 'linus', index: 1 },
@@ -77,6 +79,28 @@ describe('createSvGrid - getRowId', () => {
     ])
   })
 
+  it('makes a row, and asks getRowId for it, only when the row is read', () => {
+    // A first build is lazy: a grid that only shows its first screen must not
+    // build a row object (or call getRowId) for every row of a large dataset.
+    const seen: number[] = []
+    const rows = createSvGrid<typeof features, Row>({
+      _features: features,
+      _rowModels: { coreRowModel: createCoreRowModel<Row>() },
+      columns,
+      data,
+      getRowId: (row, index) => {
+        seen.push(index)
+        return row.id
+      },
+    }).getRowModel().rows
+    expect(seen).toEqual([])
+    expect(rows[2]!.id).toBe('grace')
+    expect(seen).toEqual([2])
+    // The same object every time it is read.
+    expect(rows[2]).toBe(rows[2])
+    expect(seen).toEqual([2])
+  })
+
   it('preserves the same id across `getRowModel()` invocations (stable identity)', () => {
     const grid = createSvGrid<typeof features, Row>({
       _features: features,

package/src/selection.test.ts

@@ -100,6 +100,20 @@ describe('createSelection - row selection', () => {
     expect(sel.isRowSelected('missing')).toBe(false)
   })
 
+  it('with a selection model, a drawn row is answered from its own data, not a scan of every row', () => {
+    const find = vi.fn(() => makeDataRow('r1', { id: 'r1' }))
+    const model = { isSelected: vi.fn((id: string, data: any) => data?.id === id), toggle: vi.fn() }
+    const ctx = makeCtx({ allRows: { find }, props: { rowSelectionModel: model } })
+    const sel = createSelection(ctx)
+    expect(sel.isRowSelected('r1', { id: 'r1' })).toBe(true)
+    sel.toggleRowSelectionById('r1', { id: 'r1' })
+    expect(model.toggle).toHaveBeenCalledWith('r1', { id: 'r1' }, false)
+    expect(find).not.toHaveBeenCalled()
+    // Without the data (an API caller) it still finds the row by id.
+    expect(sel.isRowSelected('r1')).toBe(true)
+    expect(find).toHaveBeenCalledTimes(1)
+  })
+
   it('toggleRowSelectionById flips the single row', () => {
     const ctx = makeCtx({ rowSelectionState: { r1: false } })
     const sel = createSelection(ctx)
@@ -657,6 +671,43 @@ describe('createSelection - onCellClick', () => {
     expect(ctx.selectionRange.anchor).toEqual({ rowIndex: 0, colIndex: 0 })
   })
 
+  describe('boolean cells that are not declared checkboxes', () => {
+    const boolCtx = (over: any = {}, columnDef: any = {}) =>
+      clickCtx({
+        allRows: [makeDataRow('r0', { done: true })],
+        allColumns: [makeColumn('done', { field: 'done', ...columnDef })],
+        ...over,
+      })
+
+    it('do not toggle (or write the row) while inline editing is off', () => {
+      const ctx = boolCtx({ editingEnabled: false })
+      createSelection(ctx).onCellClick(0, 0)
+      expect(ctx.toggleBooleanCell).not.toHaveBeenCalled()
+      expect(ctx.selectionRange.anchor).toEqual({ rowIndex: 0, colIndex: 0 })
+    })
+
+    it('toggle when inline editing is on and the cell is editable', () => {
+      const ctx = boolCtx({ editingEnabled: true, isCellEditableAt: () => true })
+      createSelection(ctx).onCellClick(0, 0)
+      expect(ctx.toggleBooleanCell).toHaveBeenCalledWith(0, 0)
+    })
+
+    it('do not toggle when the column has its own cell renderer', () => {
+      const ctx = boolCtx({ editingEnabled: true, isCellEditableAt: () => true }, { cell: () => 'flag' })
+      createSelection(ctx).onCellClick(0, 0)
+      expect(ctx.toggleBooleanCell).not.toHaveBeenCalled()
+    })
+  })
+
+  it('a declared checkbox that is not editable stays put', () => {
+    const ctx = clickCtx({
+      allColumns: [makeColumn('c0', { editorType: 'checkbox', editable: false })],
+      isCellEditableAt: () => false,
+    })
+    createSelection(ctx).onCellClick(0, 0)
+    expect(ctx.toggleBooleanCell).not.toHaveBeenCalled()
+  })
+
   it('enters edit mode when clicking the previously-active editable cell', () => {
     const ctx = clickCtx({
       editingEnabled: true,

package/src/selection.ts

@@ -20,21 +20,33 @@ export function createSelection<
   TFeatures extends TableFeatures = TableFeatures,
   TData extends RowData = RowData,
 >(ctx: any) {
-  function isRowSelected(rowId: string) {
+  /**
+   * A selection model needs the row's data. The body passes the row it is
+   * drawing as `original`; without it the row is looked up by id, a scan of
+   * every row - on a server model's windowed million rows, once per drawn
+   * row, that scan held the page for seconds after a sort.
+   */
+  function rowOriginal(rowId: string): { found: boolean; original?: unknown } {
+    const row = ctx.allRows.find((r: any) => r.id === rowId);
+    return row ? { found: true, original: row.original } : { found: false };
+  }
+
+  function isRowSelected(rowId: string, original?: unknown) {
     const model = ctx.props.rowSelectionModel;
     if (model) {
-      const row = ctx.allRows.find((r: any) => r.id === rowId);
-      return row ? model.isSelected(rowId, row.original) : false;
+      if (original !== undefined) return model.isSelected(rowId, original);
+      const hit = rowOriginal(rowId);
+      return hit.found ? model.isSelected(rowId, hit.original) : false;
     }
     return Boolean(ctx.rowSelectionState[rowId]);
   }
 
-  function toggleRowSelectionById(rowId: string) {
+  function toggleRowSelectionById(rowId: string, original?: unknown) {
     const model = ctx.props.rowSelectionModel;
     if (model) {
-      const row = ctx.allRows.find((r: any) => r.id === rowId);
-      if (!row) return;
-      model.toggle(rowId, row.original, !model.isSelected(rowId, row.original));
+      const hit = original !== undefined ? { found: true, original } : rowOriginal(rowId);
+      if (!hit.found) return;
+      model.toggle(rowId, hit.original, !model.isSelected(rowId, hit.original));
       return;
     }
     ctx.grid.setRowSelection((prev: any) => ({ ...prev, [rowId]: !prev[rowId] }));
@@ -472,8 +484,19 @@ export function createSelection<
 
   /** Look up a column by id without depending on `buildApi`'s private
    *  closure (those helpers don't exist at this scope). */
+  // id -> column, rebuilt when the column list changes. Called per header
+  // cell as columns scroll into view, so a linear `find` made every scroll
+  // frame cost more the more columns the grid has.
+  let columnsById: Map<string, any> = new Map();
+  let columnsByIdFor: unknown = null;
   function findColumnById(columnId: string) {
-    return ctx.allColumns.find((c: any) => c.id === columnId);
+    const all = ctx.allColumns;
+    if (all !== columnsByIdFor) {
+      columnsById = new Map();
+      for (const c of all as any[]) columnsById.set(c.id, c);
+      columnsByIdFor = all;
+    }
+    return columnsById.get(columnId);
   }
 
   function onCellPointerDown(
@@ -655,12 +678,22 @@ export function createSelection<
       row: row.original as TData,
     });
 
-    const isCheckboxColumn =
-      column.columnDef.editorType === "checkbox" ||
-      typeof cellValue === "boolean";
-
-    if (isCheckboxColumn) {
-      ctx.toggleBooleanCell(rowIndex, colIndex);
+    // A declared checkbox editor toggles on click unless the cell is not
+    // editable. A value that only HAPPENS to be boolean is drawn as a read-only
+    // checkbox, so it toggles only when inline editing is on - it used to flip
+    // and write the row on any click, in grids with editing switched off. A
+    // column with its own `cell` renderer draws (and handles) the value itself.
+    const declaredCheckbox = column.columnDef.editorType === "checkbox";
+    const inferredCheckbox =
+      !declaredCheckbox &&
+      typeof cellValue === "boolean" &&
+      column.columnDef.cell == null;
+
+    if (declaredCheckbox || inferredCheckbox) {
+      const editable = ctx.isCellEditableAt?.(rowIndex, colIndex) ?? true;
+      if (editable && (declaredCheckbox || ctx.editingEnabled)) {
+        ctx.toggleBooleanCell(rowIndex, colIndex);
+      }
       setActiveCell(rowIndex, colIndex);
       setSelection(rowIndex, colIndex);
       ctx.editingCell = null;

package/src/server-block-cache.ts

@@ -30,6 +30,7 @@
  * Enterprise's server row model runs one of these per group level; the free
  * flat controller runs exactly one.
  */
+import { createWindowedData } from './windowed-data'
 
 /**
  * The mark that says "this row is not data yet".
@@ -171,6 +172,13 @@ export type BlockCache<TData> = {
   setViewport(startIndex: number, endIndex: number): void
   /** The dense row array to hand the grid. Placeholders fill unloaded slots. */
   rows(): ReadonlyArray<TData>
+  /**
+   * The same rows as windowed data (see windowed-data.ts): `length` is the
+   * row count and each entry is read through `getRow` when the grid asks for
+   * it, so handing it over costs O(1) whatever the count. A new array per
+   * change, like `rows()`.
+   */
+  windowedRows(): ReadonlyArray<TData>
   /** One row, without building the array. Returns a placeholder when unloaded. */
   getRow(index: number): TData | typeof LOADING_ROW | typeof FAILED_ROW
   rowCount(): number | null
@@ -267,6 +275,7 @@ export function createBlockCache<TData>(options: BlockCacheOptions<TData>): Bloc
 
   let emitScheduled = false
   let rowsCache: TData[] | null = null
+  let windowedCache: TData[] | null = null
 
   const blockOf = (rowIndex: number): number => Math.floor(rowIndex / blockSize)
   const startOf = (blockIndex: number): number => blockIndex * blockSize
@@ -321,7 +330,7 @@ export function createBlockCache<TData>(options: BlockCacheOptions<TData>): Bloc
    * mutations notifies once. Every mutating path ends here.
    */
   function emit(): void {
-    rowsCache = null // rebuilt lazily, on the next read
+    rowsCache = windowedCache = null // rebuilt lazily, on the next read
     if (disposed || emitScheduled) return
     emitScheduled = true
     schedule(() => {
@@ -439,6 +448,14 @@ export function createBlockCache<TData>(options: BlockCacheOptions<TData>): Bloc
     }
   }
 
+  function rowAt(index: number): TData | typeof LOADING_ROW | typeof FAILED_ROW {
+    const block = blocks.get(blockOf(index))
+    if (!block) return LOADING_ROW
+    if (block.status === 'failed') return FAILED_ROW
+    const row = block.rows[index - startOf(blockOf(index))]
+    return row ?? LOADING_ROW
+  }
+
   function abortAll(): void {
     for (const block of blocks.values()) block.controller?.abort()
     inFlight = 0
@@ -485,14 +502,14 @@ export function createBlockCache<TData>(options: BlockCacheOptions<TData>): Bloc
       return out
     },
 
-    getRow(index) {
-      const block = blocks.get(blockOf(index))
-      if (!block) return LOADING_ROW
-      if (block.status === 'failed') return FAILED_ROW
-      const row = block.rows[index - startOf(blockOf(index))]
-      return row ?? LOADING_ROW
+    windowedRows() {
+      if (windowedCache) return windowedCache
+      windowedCache = createWindowedData<TData>(currentLength(), (i) => rowAt(i) as TData)
+      return windowedCache
     },
 
+    getRow: rowAt,
+
     rowCount: () => (countKnown ? count : null),
     lastRowKnown: () => countKnown,
 
@@ -531,7 +548,7 @@ export function createBlockCache<TData>(options: BlockCacheOptions<TData>): Bloc
       blocks.clear()
       count = null
       countKnown = false
-      rowsCache = null
+      rowsCache = windowedCache = null
       fetchViewport()
       emit()
     },
@@ -675,7 +692,7 @@ export function createBlockCache<TData>(options: BlockCacheOptions<TData>): Bloc
         controller: null,
       })
     }
-    rowsCache = null
+    rowsCache = windowedCache = null
   }
 
   /** Forget every block from `fromBlock` on, aborting any in flight. */
@@ -685,6 +702,6 @@ export function createBlockCache<TData>(options: BlockCacheOptions<TData>): Bloc
       block.controller?.abort()
       blocks.delete(index)
     }
-    rowsCache = null
+    rowsCache = windowedCache = null
   }
 }

package/src/server-data-source.ts

@@ -581,7 +581,9 @@ export function createServerDataSource<TData>(
    */
   function emitFromCache(): void {
     if (!cache || disposed) return
-    const rows = cache.rows()
+    // Windowed: the grid reads only the rows it shows, so a block landing
+    // costs the same at 100M rows as at 10K.
+    const rows = cache.windowedRows()
     state.rows = rows
     state.rowCount = cache.rowCount()
     state.lastRowKnown = cache.lastRowKnown()

package/src/server.ts

@@ -41,6 +41,12 @@ export {
   type BlockFetchResult,
   type BlockState,
 } from './server-block-cache'
+export {
+  createWindowedData,
+  windowedSourceOf,
+  isWindowedData,
+  type WindowedSource,
+} from './windowed-data'
 export {
   toServerFilterColumns,
   type GridRowModel,

package/src/spreadsheet.ts

@@ -156,6 +156,12 @@ const OVERLAY_CLASS = 'sv-cell-border-overlay'
  *  every relevant DOM mutation inside the grid, and whenever the action
  *  options update. */
 function apply(root: HTMLElement, opts: SpreadsheetActionOptions): void {
+  // Merges here are colspan / rowspan on the rendered cells, which only the
+  // table algorithm honours: keep this grid's rows in table layout (the
+  // flex-row rules in SvGrid.css skip a table marked this way).
+  for (const table of root.querySelectorAll<HTMLTableElement>('table.sv-grid-table')) {
+    if (table.getAttribute('data-row-layout') !== 'table') table.setAttribute('data-row-layout', 'table')
+  }
   // ---- 1. Clean up anything the LAST run added -----------------------
   for (const td of root.querySelectorAll<HTMLTableCellElement>(`td[${MARK}]`)) {
     td.removeAttribute('colspan')

package/src/{subscribe.test.ts → subscribe.svelte.test.ts}

@@ -6,7 +6,7 @@
  * selection actually changed.
  */
 import { describe, expect, it } from 'vitest'
-import { subscribeGrid, subscribeSvGrid } from './subscribe'
+import { subscribeGrid, subscribeSvGrid } from './subscribe.svelte'
 
 type Listener = () => void
 

package/src/{subscribe.ts → subscribe.svelte.ts}

@@ -23,7 +23,11 @@ export function subscribeGrid<
   grid: SvGrid<TData>,
   selector: (state: Record<string, any>) => TSelected,
 ) {
-  let current = selector(grid.store.state)
+  // $state, not a plain variable: core.ts keeps a deliberately framework-free
+  // store, so this Svelte adapter is where reactivity belongs. Without it a
+  // `$derived` reading .current never re-runs and the docs' headless examples
+  // render their seeded state forever.
+  let current = $state(selector(grid.store.state))
   grid.store.subscribe(() => {
     const next = selector(grid.store.state)
     if (!shallowCompare(current, next)) current = next

package/src/svgrid.behavior.test.ts

@@ -580,6 +580,35 @@ describe('SvGrid - external sort / filter', () => {
     }
   })
 
+  it('mounting is not a change: no sort, filter or selection callback fires on mount', async () => {
+    // These used to fire once on mount with the starting state. A consumer
+    // that keeps the sort in the URL and resets the page on a new sort then
+    // navigated from ?page=2 back to page 1 on every load.
+    const calls: string[] = []
+    const { api, destroy } = await mountGrid({
+      externalSort: true,
+      externalFilter: true,
+      initialSorting: [{ id: 'age', desc: true }],
+      onSortingChange: () => calls.push('sort'),
+      onFiltersChange: () => calls.push('filters'),
+      onRowSelectionChange: () => calls.push('rows'),
+      onCellSelectionChange: () => calls.push('cells'),
+    })
+    try {
+      await tick()
+      await tick()
+      expect(calls).toEqual([])
+      // ...and a real change still reports, once each.
+      api.setSort('age', 'asc')
+      api.setFilter('team', { operator: 'contains', value: 'Research' })
+      await tick()
+      expect(calls.filter((c) => c === 'sort')).toHaveLength(1)
+      expect(calls.filter((c) => c === 'filters')).toHaveLength(1)
+    } finally {
+      destroy()
+    }
+  })
+
   it('externalFilter + onFiltersChange fires when a filter is set', async () => {
     let calls = 0
     const { api, destroy } = await mountGrid({
@@ -620,6 +649,35 @@ describe('SvGrid - custom snippet cell', () => {
       destroy()
     }
   })
+
+  it('a boolean column with its own cell renderer draws the renderer, not the built-in checkbox', async () => {
+    // The checkbox branch used to run before the `cell` branch, so any boolean
+    // value came out as a read-only checkbox and the renderer was never called.
+    const flagCols: ColumnDef<typeof fullFeatures, Person>[] = personColumns.map((c) =>
+      c.field === 'active'
+        ? { ...c, cell: (ctx: any) => ((ctx.row.original as Person).active ? 'ON' : 'OFF') }
+        : c,
+    )
+    const { target, destroy } = await mountGrid({ columns: flagCols, showRowSelection: false })
+    try {
+      await tick()
+      expect(target.querySelectorAll('.sv-grid-checkbox-readonly').length).toBe(0)
+      expect(target.textContent).toContain('ON')
+      expect(target.textContent).toContain('OFF')
+    } finally {
+      destroy()
+    }
+  })
+
+  it('a boolean column without a renderer still draws the read-only checkbox', async () => {
+    const { target, destroy } = await mountGrid({ showRowSelection: false })
+    try {
+      await tick()
+      expect(target.querySelectorAll('.sv-grid-checkbox-readonly').length).toBeGreaterThan(0)
+    } finally {
+      destroy()
+    }
+  })
 })
 
 describe('SvGrid - filterMode shortcuts', () => {