@svgrid/grid 2.2.30 → 2.2.32

package/src/core.ts

@@ -45,6 +45,11 @@ export type CellSpanParams<TData extends RowData = RowData> = {
   value: unknown
 }
 
+/** The raw option list a column's `editorOptions` can supply. */
+export type EditorOptionSource = ReadonlyArray<
+  string | number | { value: string | number; label?: string; color?: string }
+>
+
 /** Params passed to a column's `valueParser(...)` on edit commit. */
 export type ValueParserParams<TData extends RowData = RowData> = {
   /** The value after built-in per-`editorType` coercion. */
@@ -172,6 +177,16 @@ export function applyGroupAggregate<TData extends RowData>(
   }
 }
 
+/**
+ * A column definition.
+ *
+ * `TFeatures` is a phantom parameter - it is threaded through nested
+ * `columns` groups but no member depends on it, so `{}`, `TableFeatures` and
+ * `typeof features` are all interchangeable here. It is deliberately left
+ * WITHOUT a default: `ColumnDef<Row>` would otherwise bind `Row` to this slot
+ * and silently type your data as `RowData`, losing every field-name check.
+ * Prefer {@link GridColumns} / {@link GridColumnDef} for the common case.
+ */
 export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> = {
   id?: string
   field?: keyof TData & string
@@ -336,16 +351,20 @@ export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> =
    *
    * Pass a function `(row) => options` for row-dependent (cascading)
    * options - e.g. City options that depend on Country in the same row.
+   *
+   * Either form may return a **Promise**, for options that come from the
+   * server. While it resolves, the editor shows a loading state and the cell
+   * renders its raw value.
+   *
+   * Results are cached so reopening an editor does not refetch: a static source
+   * per column, a per-row source per row AND per that row's data - so a cascade
+   * reloads by itself when the cell it depends on is edited. Call
+   * `api.refreshEditorOptions(columnId?)` when the list changes server-side.
    */
   editorOptions?:
-    | ReadonlyArray<
-        string | number | { value: string | number; label?: string; color?: string }
-      >
-    | ((
-        row: TData,
-      ) => ReadonlyArray<
-        string | number | { value: string | number; label?: string; color?: string }
-      >)
+    | EditorOptionSource
+    | Promise<EditorOptionSource>
+    | ((row: TData) => EditorOptionSource | Promise<EditorOptionSource>)
   /** When true, list/chips allow multiple selections. Cell value becomes an array. */
   editorMultiple?: boolean
   /** Separator used when joining array values for the readonly cell display. Defaults to ', '. */
@@ -409,6 +428,23 @@ export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> =
     | ((ctx: CellContext<TData>) => string | ReadonlyArray<string> | Record<string, boolean> | undefined | null)
 }
 
+/**
+ * A column definition keyed only by your row type - the ergonomic form of
+ * {@link ColumnDef}, whose first parameter is a phantom feature bag that is
+ * almost always `{}`.
+ *
+ * ```ts
+ * const columns: GridColumns<Person> = [{ field: 'firstName', header: 'Name' }]
+ * ```
+ *
+ * Interchangeable with `ColumnDef<{}, TData>` and `ColumnDef<typeof features,
+ * TData>` in both directions, so it mixes freely with existing code.
+ */
+export type GridColumnDef<TData extends RowData = RowData> = ColumnDef<TableFeatures, TData>
+
+/** An array of {@link GridColumnDef} - what you pass to `<SvGrid columns={...}>`. */
+export type GridColumns<TData extends RowData = RowData> = Array<GridColumnDef<TData>>
+
 export type Column<TData extends RowData> = {
   id: string
   columnDef: ColumnDef<any, TData>
@@ -647,6 +683,119 @@ export function createGroupedRowModel<TData extends RowData>(): RowModelFactory<
     return buildGroups(rows, 0, 0, 'group')
   }
 }
+export type TreeRowModelOptions = {
+  /** Field holding each row's parent id. Rows with no parent are roots. */
+  parentField: string
+  /** Field holding the row's own id. Defaults to `'id'`. */
+  idField?: string
+}
+
+/**
+ * Client-side tree data: nest the grid's own flat rows into a parent/child
+ * hierarchy that `createExpandedRowModel` then walks.
+ *
+ * This works on the rows the grid already built rather than on raw data, so
+ * tree rows keep their cells, editing, selection and formatting - they are real
+ * data rows that happen to have children, not synthetic banners like grouping's.
+ * That is also why the model is parent-id based: nested source arrays never
+ * become rows (the grid only builds rows for `data`), so nested input is
+ * flattened first with {@link flattenTreeData}. One code path, no duplicated
+ * row construction.
+ *
+ * Rows are tagged `__treeRow` so `isGroupRow` does not mistake an expandable
+ * data row for a full-width group banner.
+ */
+export function createTreeRowModel<TData extends RowData>(
+  options: TreeRowModelOptions,
+): RowModelFactory<TData> {
+  const { parentField, idField = 'id' } = options
+  return ({ table, rows }) => {
+    if (!rows.length) return rows
+    const keyOf = (row: Row<TData>) => (row.original as any)?.[idField]
+    const parentOf = (row: Row<TData>) => (row.original as any)?.[parentField]
+
+    const present = new Set<unknown>()
+    for (const row of rows) present.add(keyOf(row))
+
+    const childrenByParent = new Map<unknown, Array<Row<TData>>>()
+    const roots: Array<Row<TData>> = []
+    for (const row of rows) {
+      const parent = parentOf(row)
+      // A row whose parent is absent (filtered out, or never existed) becomes a
+      // root rather than disappearing - silently dropping rows is worse than a
+      // shallower tree. Self-parenting is treated the same way.
+      if (parent == null || parent === keyOf(row) || !present.has(parent)) {
+        roots.push(row)
+        continue
+      }
+      const list = childrenByParent.get(parent) ?? []
+      list.push(row)
+      childrenByParent.set(parent, list)
+    }
+
+    // Guards a cycle in the parent chain from recursing forever.
+    const seen = new Set<unknown>()
+    const build = (row: Row<TData>, depth: number): Row<TData> => {
+      const key = keyOf(row)
+      const id = row.id
+      if (seen.has(key)) {
+        return { ...row, depth, subRows: [], getCanExpand: () => false } as Row<TData>
+      }
+      seen.add(key)
+      const subRows = (childrenByParent.get(key) ?? []).map((child) => build(child, depth + 1))
+      return {
+        ...row,
+        depth,
+        subRows,
+        leafCount: subRows.reduce((n, sub) => n + 1 + (sub.leafCount ?? 0), 0),
+        __treeRow: true,
+        getCanExpand: () => subRows.length > 0,
+        getIsExpanded: () => Boolean((table.getState().expanded ?? {})[id]),
+        toggleExpanded: () => {
+          table.setExpanded((prev) => ({ ...prev, [id]: !prev[id] }))
+        },
+      } as Row<TData>
+    }
+
+    return roots.map((root) => build(root, 0))
+  }
+}
+
+export type FlattenTreeOptions = {
+  /** Field holding an array of child objects. */
+  childrenField: string
+  /** Field holding each object's id. Defaults to `'id'`. */
+  idField?: string
+  /** Field to WRITE the resolved parent id onto. Defaults to `'__parentId'`. */
+  parentField?: string
+}
+
+/**
+ * Flatten nested tree data into the flat parent-id shape `createTreeRowModel`
+ * consumes, stamping each child with its parent's id.
+ *
+ * Children are emitted directly after their parent so the natural order already
+ * matches the rendered tree. The `childrenField` array is left on the objects
+ * (harmless, and callers often still want it); only the parent link is added.
+ */
+export function flattenTreeData<T extends RowData>(
+  data: ReadonlyArray<T>,
+  options: FlattenTreeOptions,
+): T[] {
+  const { childrenField, idField = 'id', parentField = '__parentId' } = options
+  const out: T[] = []
+  const walk = (nodes: ReadonlyArray<T>, parentId: unknown) => {
+    for (const node of nodes) {
+      const flat = { ...node, [parentField]: parentId } as T
+      out.push(flat)
+      const kids = (node as any)[childrenField]
+      if (Array.isArray(kids) && kids.length) walk(kids as ReadonlyArray<T>, (node as any)[idField])
+    }
+  }
+  walk(data, null)
+  return out
+}
+
 export function createExpandedRowModel<TData extends RowData>(): RowModelFactory<TData> {
   return ({ table, rows }) => {
     const expanded: ExpandedState = table.getState().expanded ?? {}

package/src/editing.test.ts

@@ -154,7 +154,7 @@ describe('isCellEditable', () => {
       data: [{ a: 'hello' }],
     })
     ed.isCellEditable(ctx.allColumns[0], ctx.allRows[0])
-    const cc = spy.mock.calls[0][0]
+    const cc = spy.mock.calls[0]![0]
     expect(cc.getValue()).toBe('hello')
     expect(cc.cell.getValue()).toBe('hello')
     expect(cc.cell.getContext()).toBe(cc)

package/src/editor-contract.ts

@@ -68,16 +68,23 @@ export type SvEditorProps = {
  * The interaction surface an editor exposes when embedded as a grid cell editor.
  * Standalone usage ignores these; the grid supplies them so every editor shares
  * one commit / cancel / move contract (Enter commits, Escape cancels, Tab moves)
- * instead of each cell-editor re-implementing key handling. Consumed in Phase 2
- * (the editor registry).
+ * instead of each cell-editor re-implementing key handling.
+ *
+ * `CellEditorContext` (editor-registry.ts) extends this type, so what the grid
+ * hands a registered editor and what this contract promises are the same thing
+ * by construction rather than by convention.
  */
 export type EditorInteraction<V = unknown> = {
-  /** Commit the current value and stop editing (Enter, option pick, blur-commit). */
-  onCommit?: (value: V) => void
+  /**
+   * Commit the value and stop editing (Enter, option pick, blur-commit).
+   * The argument is optional: an editor that has been reporting through
+   * `onChange` can just call `onCommit()` to commit what the grid already has.
+   */
+  onCommit?: (value?: V) => void
   /** Abandon the edit and restore the previous value (Escape). */
   onCancel?: () => void
   /** Commit, then move to the adjacent cell (Tab = 1, Shift+Tab = -1). */
-  onCommitAndMove?: (value: V, direction: 1 | -1) => void
+  onCommitAndMove?: (value: V | undefined, direction: 1 | -1) => void
   /** Ask the surrounding popover/panel to close without committing. */
   onRequestClose?: () => void
   /** True while mounted inside a grid cell (lets an editor tune autofocus etc.). */

package/src/editor-registry.grid.test.ts

@@ -95,4 +95,52 @@ describe('registry wiring in SvGrid', () => {
       destroy()
     }
   })
+
+  it('hands the editor the full EditorInteraction contract, not a subset', async () => {
+    // The contract type used to be documented but never supplied: the registry
+    // passed only value/onChange/onCommit/onCancel, so an editor written against
+    // `EditorInteraction` (Tab-to-move, dismiss-without-commit, in-cell tuning)
+    // silently got undefined for half of it.
+    let seen: Record<string, unknown> = {}
+    registerCellEditor('stars', {
+      component: SvRating,
+      props: (ctx) => {
+        seen = ctx as unknown as Record<string, unknown>
+        return { value: ctx.value }
+      },
+    })
+
+    const { api, target, destroy } = await mountGrid()
+    try {
+      api.startEditing(0, 'score')
+      await tick()
+      await tick()
+      expect(typeof seen.onCommit).toBe('function')
+      expect(typeof seen.onCancel).toBe('function')
+      expect(typeof seen.onChange).toBe('function')
+      expect(typeof seen.onCommitAndMove).toBe('function')
+      expect(typeof seen.onRequestClose).toBe('function')
+      expect(seen.inCell).toBe(true)
+      expect(seen.rowId).toBeTruthy()
+      expect(seen.columnId).toBe('score')
+      void target
+    } finally {
+      destroy()
+    }
+  })
+
+  it('defaults to passing the whole contract when a registration has no props mapping', async () => {
+    // A registration with no `props` should still work for a contract-aware
+    // editor - that is the point of the default mapping.
+    registerCellEditor('stars', SvRating)
+    const { api, target, destroy } = await mountGrid()
+    try {
+      api.startEditing(0, 'score')
+      await tick()
+      await tick()
+      expect(target.querySelector('.sv-rating')).not.toBeNull()
+    } finally {
+      destroy()
+    }
+  })
 })

package/src/editor-registry.test.ts

@@ -15,6 +15,8 @@ import {
 const Fake = (() => {}) as unknown as Component<any>
 const Fake2 = (() => {}) as unknown as Component<any>
 
+// onCommitAndMove / onRequestClose / inCell are deliberately left off: the
+// tests below assert that defaultEditorProps maps them to undefined.
 function ctx(overrides: Partial<CellEditorContext> = {}): CellEditorContext {
   return {
     value: 42,
@@ -24,7 +26,7 @@ function ctx(overrides: Partial<CellEditorContext> = {}): CellEditorContext {
     onCommit: () => {},
     onCancel: () => {},
     ...overrides,
-  }
+  } as CellEditorContext
 }
 
 afterEach(() => {

package/src/editor-registry.ts

@@ -20,9 +20,20 @@
  * mounting.
  */
 import type { Component } from 'svelte'
+import type { EditorInteraction } from './editor-contract'
 
-/** Context the grid hands a cell editor when it mounts one for an edit. */
-export type CellEditorContext<T = unknown> = {
+/**
+ * Context the grid hands a cell editor when it mounts one for an edit.
+ *
+ * Extends {@link EditorInteraction} - the shared commit / cancel / move contract
+ * the `Sv*` editors are written against - and narrows the parts the grid always
+ * supplies, so a registered component and a built-in editor speak the same
+ * language. `onCommitAndMove`, `onRequestClose` and `inCell` come from the
+ * contract and are always populated by the grid.
+ */
+export type CellEditorContext<T = unknown> = Required<
+  Pick<EditorInteraction<T>, 'onCommit' | 'onCancel' | 'onCommitAndMove' | 'onRequestClose' | 'inCell'>
+> & {
   /** The value currently being edited. */
   value: T
   /** Id of the row being edited. */
@@ -31,10 +42,6 @@ export type CellEditorContext<T = unknown> = {
   columnId: string
   /** Update the in-progress value WITHOUT ending the edit. */
   onChange: (value: T) => void
-  /** Commit the value and stop editing (optionally pass a final value). */
-  onCommit: (value?: T) => void
-  /** Discard changes and stop editing (returns focus to the grid). */
-  onCancel: () => void
 }
 
 /** How a registered component is mounted and wired for a cell edit. */
@@ -87,13 +94,22 @@ export function registeredCellEditorTypes(): string[] {
   return [...registry.keys()]
 }
 
-/** The default context → props mapping used when a registration has no `props`. */
+/**
+ * The default context → props mapping used when a registration has no `props`.
+ * Passes the whole {@link EditorInteraction} surface, so an editor written
+ * against the shared contract works when registered with no mapping at all.
+ * Svelte ignores props a component doesn't declare, so the extra keys are inert
+ * for a simple editor that only wants `value` + `onCommit`.
+ */
 export function defaultEditorProps(ctx: CellEditorContext): Record<string, unknown> {
   return {
     value: ctx.value,
     onChange: ctx.onChange,
     onCommit: ctx.onCommit,
     onCancel: ctx.onCancel,
+    onCommitAndMove: ctx.onCommitAndMove,
+    onRequestClose: ctx.onRequestClose,
+    inCell: ctx.inCell,
   }
 }
 

package/src/facet-buckets.test.ts

@@ -62,11 +62,11 @@ describe('isBucketableColumn', () => {
   const cols = makeColumns()
 
   it('returns { isDate: false } for a number column', () => {
-    expect(isBucketableColumn(cols.num)).toEqual({ isDate: false })
+    expect(isBucketableColumn(cols.num!)).toEqual({ isDate: false })
   })
 
   it('returns { isDate: true } for a date column', () => {
-    expect(isBucketableColumn(cols.when)).toEqual({ isDate: true })
+    expect(isBucketableColumn(cols.when!)).toEqual({ isDate: true })
   })
 
   it('returns { isDate: true } for a datetime column', () => {
@@ -81,15 +81,15 @@ describe('isBucketableColumn', () => {
   })
 
   it('returns null for a text column', () => {
-    expect(isBucketableColumn(cols.id)).toBeNull()
+    expect(isBucketableColumn(cols.id!)).toBeNull()
   })
 
   it('returns null for a checkbox column', () => {
-    expect(isBucketableColumn(cols.flag)).toBeNull()
+    expect(isBucketableColumn(cols.flag!)).toBeNull()
   })
 
   it('returns null for a column with no editorType', () => {
-    expect(isBucketableColumn(cols.name)).toBeNull()
+    expect(isBucketableColumn(cols.name!)).toBeNull()
   })
 })
 
@@ -105,7 +105,7 @@ describe('buildBuckets - numeric', () => {
       name: '',
       flag: false,
     }))
-    expect(buildBuckets(cols.num, false, data, accessor)).toBeNull()
+    expect(buildBuckets(cols.num!, false, data, accessor)).toBeNull()
   })
 
   it('builds 10 buckets when distinct values exceed the threshold', () => {
@@ -117,7 +117,7 @@ describe('buildBuckets - numeric', () => {
       name: '',
       flag: false,
     }))
-    const buckets = buildBuckets(cols.num, false, data, accessor)
+    const buckets = buildBuckets(cols.num!, false, data, accessor)
     expect(buckets).not.toBeNull()
     expect(buckets!).toHaveLength(10)
   })
@@ -130,12 +130,12 @@ describe('buildBuckets - numeric', () => {
       name: '',
       flag: false,
     }))
-    const buckets = buildBuckets(cols.num, false, data, accessor)!
-    expect(buckets[0].numericMin).toBe(0)
-    expect(buckets[9].numericMax).toBe(30)
+    const buckets = buildBuckets(cols.num!, false, data, accessor)!
+    expect(buckets[0]!.numericMin).toBe(0)
+    expect(buckets[9]!.numericMax).toBe(30)
     // bucket i's max equals bucket i+1's min (contiguous, no gaps)
     for (let i = 0; i < buckets.length - 1; i += 1) {
-      expect(buckets[i].numericMax).toBeCloseTo(buckets[i + 1].numericMin, 10)
+      expect(buckets[i]!.numericMax).toBeCloseTo(buckets[i + 1]!.numericMin, 10)
     }
   })
 
@@ -147,10 +147,10 @@ describe('buildBuckets - numeric', () => {
       name: '',
       flag: false,
     }))
-    const buckets = buildBuckets(cols.num, false, data, accessor)!
+    const buckets = buildBuckets(cols.num!, false, data, accessor)!
     expect(buckets.filter((b) => b.isLast)).toHaveLength(1)
-    expect(buckets[9].isLast).toBe(true)
-    expect(buckets[0].isLast).toBe(false)
+    expect(buckets[9]!.isLast).toBe(true)
+    expect(buckets[0]!.isLast).toBe(false)
     expect(buckets.every((b) => b.isDate === false)).toBe(true)
   })
 
@@ -162,8 +162,8 @@ describe('buildBuckets - numeric', () => {
       name: '',
       flag: false,
     }))
-    const buckets = buildBuckets(cols.num, false, data, accessor)!
-    expect(buckets[0].label).toContain('–')
+    const buckets = buildBuckets(cols.num!, false, data, accessor)!
+    expect(buckets[0]!.label).toContain('–')
   })
 
   it('ignores non-finite / blank values when computing min/max and distinct', () => {
@@ -180,10 +180,10 @@ describe('buildBuckets - numeric', () => {
       { id: 'b', num: undefined as unknown as number, when: '', name: '', flag: false },
       { id: 'c', num: 'not-a-number' as unknown as number, when: '', name: '', flag: false },
     ]
-    const buckets = buildBuckets(cols.num, false, data, accessor)!
+    const buckets = buildBuckets(cols.num!, false, data, accessor)!
     // range is still 0..30 - the junk rows were skipped
-    expect(buckets[0].numericMin).toBe(0)
-    expect(buckets[9].numericMax).toBe(30)
+    expect(buckets[0]!.numericMin).toBe(0)
+    expect(buckets[9]!.numericMax).toBe(30)
   })
 
   it('returns null when all finite values are identical (min === max)', () => {
@@ -196,7 +196,7 @@ describe('buildBuckets - numeric', () => {
       name: '',
       flag: false,
     }))
-    expect(buildBuckets(cols.num, false, data, accessor)).toBeNull()
+    expect(buildBuckets(cols.num!, false, data, accessor)).toBeNull()
   })
 
   it('returns null when there is no finite data at all', () => {
@@ -207,11 +207,11 @@ describe('buildBuckets - numeric', () => {
       name: '',
       flag: false,
     }))
-    expect(buildBuckets(cols.num, false, data, accessor)).toBeNull()
+    expect(buildBuckets(cols.num!, false, data, accessor)).toBeNull()
   })
 
   it('returns null for an empty dataset', () => {
-    expect(buildBuckets(cols.num, false, [], accessor)).toBeNull()
+    expect(buildBuckets(cols.num!, false, [], accessor)).toBeNull()
   })
 
   it('handles negative ranges', () => {
@@ -222,9 +222,9 @@ describe('buildBuckets - numeric', () => {
       name: '',
       flag: false,
     }))
-    const buckets = buildBuckets(cols.num, false, data, accessor)!
-    expect(buckets[0].numericMin).toBe(-20)
-    expect(buckets[9].numericMax).toBe(20)
+    const buckets = buildBuckets(cols.num!, false, data, accessor)!
+    expect(buckets[0]!.numericMin).toBe(-20)
+    expect(buckets[9]!.numericMax).toBe(20)
   })
 })
 
@@ -241,11 +241,11 @@ describe('buildBuckets - date', () => {
       name: '',
       flag: false,
     }))
-    const buckets = buildBuckets(cols.when, true, data, accessor)!
+    const buckets = buildBuckets(cols.when!, true, data, accessor)!
     expect(buckets).toHaveLength(10)
     expect(buckets.every((b) => b.isDate === true)).toBe(true)
     // labels should look like dates (contain a 4-digit year)
-    expect(buckets[0].label).toMatch(/\d{4}/)
+    expect(buckets[0]!.label).toMatch(/\d{4}/)
   })
 
   it('accepts Date instances directly', () => {
@@ -257,9 +257,9 @@ describe('buildBuckets - date', () => {
     )
     // accessor reads row[column.id]; column id is 'when'
     const rows = data.map((d) => ({ when: d.when })) as unknown as Row[]
-    const buckets = buildBuckets(cols.when, true, rows, accessor)!
+    const buckets = buildBuckets(cols.when!, true, rows, accessor)!
     expect(buckets).toHaveLength(10)
-    expect(buckets[0].numericMin).toBe(start)
+    expect(buckets[0]!.numericMin).toBe(start)
   })
 
   it('returns null when date values are too few', () => {
@@ -270,7 +270,7 @@ describe('buildBuckets - date', () => {
       name: '',
       flag: false,
     }))
-    expect(buildBuckets(cols.when, true, data, accessor)).toBeNull()
+    expect(buildBuckets(cols.when!, true, data, accessor)).toBeNull()
   })
 
   it('skips invalid date strings', () => {
@@ -286,9 +286,9 @@ describe('buildBuckets - date', () => {
       })),
       { id: 'bad', num: 0, when: 'not-a-date', name: '', flag: false },
     ]
-    const buckets = buildBuckets(cols.when, true, data, accessor)!
+    const buckets = buildBuckets(cols.when!, true, data, accessor)!
     expect(buckets).toHaveLength(10)
-    expect(buckets[0].numericMin).toBe(start)
+    expect(buckets[0]!.numericMin).toBe(start)
   })
 })
 
@@ -344,7 +344,7 @@ describe('isInBucket', () => {
       name: '',
       flag: false,
     }))
-    const buckets = buildBuckets(cols.num, false, data, accessor)!
+    const buckets = buildBuckets(cols.num!, false, data, accessor)!
     for (const v of [0, 1, 15, 50, 99, 100]) {
       const hits = buckets.filter((b) => isInBucket(v, b))
       expect(hits).toHaveLength(1)

package/src/group-display.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { buildAutoGroupColumns, insertGroupFooters } from './group-display'
+import { buildAutoGroupColumns, insertGroupFooters, paginateGroupedRows } from './group-display'
 
 type R = { id: string; depth: number; group?: boolean; total?: number; footer?: boolean }
 
@@ -75,3 +75,93 @@ describe('buildAutoGroupColumns', () => {
     expect(r.autoColumns.map((c) => c.field)).toEqual(['region', 'category'])
   })
 })
+
+describe('paginateGroupedRows (#73)', () => {
+  // Ten groups of two rows each - the shape from the issue report, where
+  // slicing the flat list by pageSize leaves almost no data on a page.
+  const many: R[] = []
+  for (let g = 0; g < 10; g += 1) {
+    many.push({ id: `g${g}`, depth: 0, group: true })
+    many.push({ id: `g${g}r0`, depth: 1 })
+    many.push({ id: `g${g}r1`, depth: 1 })
+  }
+  const base = { getDepth: (r: R) => r.depth, isGroup: (r: R) => !!r.group }
+
+  it('counts only data rows against pageSize', () => {
+    const { rows, dataRowCount } = paginateGroupedRows(many, { ...base, pageIndex: 0, pageSize: 10 })
+    expect(dataRowCount).toBe(20)
+    // A naive slice would have yielded 10 rows TOTAL, only ~3 of them data.
+    expect(rows.filter((r) => !r.group)).toHaveLength(10)
+  })
+
+  it('reprints the banner each page a group appears on', () => {
+    const page0 = paginateGroupedRows(many, { ...base, pageIndex: 0, pageSize: 3 }).rows
+    expect(page0.map((r) => r.id)).toEqual(['g0', 'g0r0', 'g0r1', 'g1', 'g1r0'])
+    // g1 is reprinted because its second row leads the next page.
+    const page1 = paginateGroupedRows(many, { ...base, pageIndex: 1, pageSize: 3 }).rows
+    expect(page1.map((r) => r.id)).toEqual(['g1', 'g1r1', 'g2', 'g2r0', 'g2r1'])
+  })
+
+  it('emits a banner once for a group spanning many rows on one page', () => {
+    const wide: R[] = [{ id: 'g', depth: 0, group: true }]
+    for (let i = 0; i < 5; i += 1) wide.push({ id: `r${i}`, depth: 1 })
+    const { rows } = paginateGroupedRows(wide, { ...base, pageIndex: 0, pageSize: 5 })
+    expect(rows.filter((r) => r.group)).toHaveLength(1)
+    expect(rows).toHaveLength(6)
+  })
+
+  it('reprints the whole ancestor chain for nested groups', () => {
+    const nested: R[] = [
+      { id: 'A', depth: 0, group: true },
+      { id: 'A1', depth: 1, group: true },
+      { id: 'x', depth: 2 },
+      { id: 'y', depth: 2 },
+    ]
+    const page1 = paginateGroupedRows(nested, { ...base, pageIndex: 1, pageSize: 1 }).rows
+    expect(page1.map((r) => r.id)).toEqual(['A', 'A1', 'y'])
+  })
+
+  it('gives a COLLAPSED group its own page slot', () => {
+    // All groups collapsed: the flat model is banners only. Treating those as
+    // zero-cost headers left every page empty - a real bug caught by the DOM test.
+    const collapsed: R[] = []
+    for (let g = 0; g < 10; g += 1) collapsed.push({ id: `c${g}`, depth: 0, group: true })
+    const { rows, dataRowCount } = paginateGroupedRows(collapsed, {
+      ...base,
+      isExpanded: () => false,
+      pageIndex: 0,
+      pageSize: 4,
+    })
+    expect(dataRowCount).toBe(10)
+    expect(rows.map((r) => r.id)).toEqual(['c0', 'c1', 'c2', 'c3'])
+  })
+
+  it('mixes an expanded group with a collapsed sibling', () => {
+    const mixed: R[] = [
+      { id: 'open', depth: 0, group: true },
+      { id: 'o1', depth: 1 },
+      { id: 'o2', depth: 1 },
+      { id: 'shut', depth: 0, group: true },
+    ]
+    const { rows, dataRowCount } = paginateGroupedRows(mixed, {
+      ...base,
+      isExpanded: (r: R) => r.id === 'open',
+      pageIndex: 0,
+      pageSize: 5,
+    })
+    // 2 data rows + 1 collapsed group = 3 units; the open banner is free.
+    expect(dataRowCount).toBe(3)
+    expect(rows.map((r) => r.id)).toEqual(['open', 'o1', 'o2', 'shut'])
+  })
+
+  it('handles an out-of-range page', () => {
+    expect(paginateGroupedRows(many, { ...base, pageIndex: 99, pageSize: 10 }).rows).toEqual([])
+  })
+
+  it('leaves ungrouped data untouched', () => {
+    const flat: R[] = [{ id: 'a', depth: 0 }, { id: 'b', depth: 0 }, { id: 'c', depth: 0 }]
+    const { rows, dataRowCount } = paginateGroupedRows(flat, { ...base, pageIndex: 1, pageSize: 2 })
+    expect(dataRowCount).toBe(3)
+    expect(rows.map((r) => r.id)).toEqual(['c'])
+  })
+})