@svgrid/grid 3.0.5 → 3.0.7

package/src/keyboard.ts

@@ -50,6 +50,9 @@ export function getKeyboardIntent(event: KeyboardEvent): GridKeyboardIntent {
   //   Tab        → move right (Shift+Tab → left), wraps at row boundaries
   //   Delete     → clear contents of the selected cells
   //   F2 / Space → start editing the active cell
+  // Ctrl+Enter acts on the row rather than moving: a group opens or closes,
+  // a row with a detail panel shows or hides it (see the activate branch).
+  if (event.key === 'Enter' && (event.ctrlKey || event.metaKey)) return 'activate'
   if (event.key === 'Enter') return event.shiftKey ? 'moveUp' : 'moveDown'
   if (event.key === 'Tab') return event.shiftKey ? 'tabPrev' : 'tabNext'
   if (event.key === 'F2') return 'activate'

package/src/row-drag-touch.ts

@@ -23,7 +23,7 @@ export type TouchDragDeps = {
   ctx: any;
   managed: () => boolean;
   originalAt: (rowIndex: number) => unknown;
-  commitDropOnRow: (rowIndex: number, side: "before" | "after") => void;
+  commitDropOnRow: (rowIndex: number, side: "before" | "after" | "into") => void;
   clearIndicators: () => void;
   cancelPendingLeave: () => void;
   /** Publish the dragged row on the shared cross-grid bus. */
@@ -135,7 +135,7 @@ export function createTouchDrag(deps: TouchDragDeps): TouchDragHandle {
     if (commit && ctx.rowDropIndex != null) {
       deps.commitDropOnRow(
         ctx.rowDropIndex as number,
-        (ctx.rowDropSide ?? "before") as "before" | "after",
+        (ctx.rowDropSide ?? "before") as "before" | "after" | "into",
       );
     } else {
       deps.clearIndicators();

package/src/row-drag.test.ts

@@ -73,6 +73,57 @@ describe('createRowDrag - same-grid reorder', () => {
   })
 })
 
+describe('createRowDrag - a custom drop (onRowDrop)', () => {
+  it('reports the drop with its side and leaves the data alone', () => {
+    const rows: Task[] = [
+      { id: 1, title: 'a' },
+      { id: 2, title: 'b' },
+      { id: 3, title: 'c' },
+    ]
+    const onRowDrop = vi.fn()
+    const ctx = makeCtx(rows, { ...P, onRowDrop })
+    const h = createRowDrag(ctx)
+    h.onRowDragStart(fakeEvent(), 0) // drag 'a'
+    h.onRowDragOver(fakeEvent(35, 0, 40), 2) // low on c: after
+    expect(ctx.rowDropSide).toBe('after')
+    h.onRowDrop(fakeEvent(), 2)
+    expect(onRowDrop).toHaveBeenCalledWith({ row: rows[0], target: rows[2], targetIndex: 2, side: 'after' })
+    expect((ctx.internalData as Task[]).map((r) => r.title)).toEqual(['a', 'b', 'c'])
+    // The empty space below the rows reports no target.
+    h.onRowDragStart(fakeEvent(), 1)
+    h.onRowsContainerDrop(fakeEvent())
+    expect(onRowDrop).toHaveBeenLastCalledWith({ row: rows[1], target: null, targetIndex: null, side: 'after' })
+  })
+
+  it('offers "into" over the middle of a group row, and only then', () => {
+    const rows: Task[] = [
+      { id: 1, title: 'folder' },
+      { id: 2, title: 'file' },
+    ]
+    const ctx = makeCtx(rows, {
+      ...P,
+      onRowDrop: vi.fn(),
+      serverGroup: { isGroup: (r: Task) => r.title === 'folder', level: () => 0, onToggle: () => {} },
+    })
+    const h = createRowDrag(ctx)
+    h.onRowDragStart(fakeEvent(), 1)
+    h.onRowDragOver(fakeEvent(20, 0, 40), 0) // the middle of the folder
+    expect(ctx.rowDropSide).toBe('into')
+    h.onRowDragOver(fakeEvent(3, 0, 40), 0) // its top edge
+    expect(ctx.rowDropSide).toBe('before')
+    h.onRowDragOver(fakeEvent(19, 0, 40), 1) // the middle of a file: no nesting, just the halves
+    expect(ctx.rowDropSide).toBe('before')
+    h.onRowDragOver(fakeEvent(21, 0, 40), 1)
+    expect(ctx.rowDropSide).toBe('after')
+    // Without a custom handler the middle band does not exist.
+    const managed = makeCtx(rows, { ...P, serverGroup: ctx.props.serverGroup })
+    const hm = createRowDrag(managed)
+    hm.onRowDragStart(fakeEvent(), 1)
+    hm.onRowDragOver(fakeEvent(20, 0, 40), 0)
+    expect(managed.rowDropSide).toBe('after')
+  })
+})
+
 describe('createRowDrag - grid-to-grid', () => {
   it('moves a row from source into target when groups match', () => {
     const a = makeCtx([{ id: 1, title: 'a1' }, { id: 2, title: 'a2' }], { ...P, rowDragGroup: 'g' })

package/src/row-drag.ts

@@ -116,7 +116,25 @@ export function createRowDrag<TFeatures, TData>(ctx: any) {
     if (e.dataTransfer) e.dataTransfer.dropEffect = "move";
     const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
     ctx.rowDropIndex = rowIndex;
-    ctx.rowDropSide = e.clientY < rect.top + rect.height / 2 ? "before" : "after";
+    ctx.rowDropSide = sideAt(rowIndex, rect, e.clientY);
+  }
+
+  /**
+   * Which edge the pointer is on. A custom drop handler also gets the middle
+   * of a group or tree row as "into" (the row becomes its child); the
+   * managed reorder only knows before and after.
+   */
+  function sideAt(rowIndex: number, rect: DOMRect, y: number): "before" | "after" | "into" {
+    const rel = (y - rect.top) / Math.max(rect.height, 1);
+    if (ctx.props.onRowDrop && rel >= 0.25 && rel <= 0.75 && canNest(rowIndex)) return "into";
+    return rel < 0.5 ? "before" : "after";
+  }
+  function canNest(rowIndex: number): boolean {
+    const row = ctx.allRows[rowIndex];
+    if (!row) return false;
+    const sg = ctx.props.serverGroup;
+    if (sg) return !!sg.isGroup(row.original);
+    return typeof row.getCanExpand === "function" && row.getCanExpand();
   }
 
   function onRowDragLeave(rowIndex: number) {
@@ -147,7 +165,7 @@ export function createRowDrag<TFeatures, TData>(ctx: any) {
    * both land here, so the reorder, the cross-grid hand-off and the
    * `onRowDragEnd` payload have exactly one implementation.
    */
-  function commitDropOnRow(rowIndex: number, side: "before" | "after") {
+  function commitDropOnRow(rowIndex: number, side: "before" | "after" | "into") {
     if (!canAccept() || !bus) return;
     const dragged = bus.row;
     const target = originalAt(rowIndex);
@@ -155,6 +173,15 @@ export function createRowDrag<TFeatures, TData>(ctx: any) {
     const sameGrid = sourceGridId === gridId;
     clearIndicators();
 
+    // A custom handler owns the drop: the grid reports it and leaves its
+    // data alone (a row model's rows are not the grid's to splice).
+    if (sameGrid && ctx.props.onRowDrop) {
+      bus = null;
+      ctx.props.onRowDrop({ row: dragged, target, targetIndex: rowIndex, side });
+      return;
+    }
+    if (side === "into") side = "after";
+
     const data = (ctx.internalData as unknown[]).slice();
     if (sameGrid) {
       const from = data.indexOf(dragged);
@@ -198,6 +225,12 @@ export function createRowDrag<TFeatures, TData>(ctx: any) {
     const sameGrid = sourceGridId === gridId;
     clearIndicators();
 
+    if (sameGrid && ctx.props.onRowDrop) {
+      bus = null;
+      ctx.props.onRowDrop({ row: dragged, target: null, targetIndex: null, side: "after" });
+      return;
+    }
+
     const data = (ctx.internalData as unknown[]).slice();
     if (sameGrid) {
       const from = data.indexOf(dragged);

package/src/row-model.ts

@@ -84,6 +84,12 @@ export type GridRowModel<TData> = {
     level: (row: TData) => number
     expanded?: (row: TData) => boolean
     onToggle: (row: TData) => void
+    /** Open or close the detail panel under a leaf. Ctrl+Enter on a row calls it when `renderDetailRow` is set, and so does the `showDetailToggle` chevron. */
+    toggleDetail?: (row: TData) => void
+    /** Whether the detail under a leaf is open: the chevron's direction. */
+    detailOpen?: (row: TData) => boolean
+    /** Whether a row can open a detail; the chevron is left out where this is false. */
+    hasDetail?: (row: TData) => boolean
   }
   /** Selection the grid does not own - see the `rowSelectionModel` prop. */
   selection?: {

package/src/row-resize.ts

@@ -69,6 +69,20 @@ export function rowResize(node: HTMLElement, opts: RowResizeOptions) {
   /** The last press on a strip, for telling a double-click from two drags. */
   let lastPress: { rowIndex: number; at: number } | null = null
 
+  /**
+   * A focusable `role="separator"` is a splitter, and a splitter carries its
+   * position: axe's `aria-required-attr` fails one without `aria-valuenow`,
+   * and a screen reader reading the strip says nothing useful without it. The
+   * value is the row's height in pixels, between the action's min and max.
+   */
+  function setStripValue(strip: HTMLElement, height: number): void {
+    const min = current.min ?? 20
+    const max = current.max ?? 320
+    strip.setAttribute('aria-valuemin', String(min))
+    strip.setAttribute('aria-valuemax', String(max))
+    strip.setAttribute('aria-valuenow', String(Math.round(Math.max(min, Math.min(max, height || min)))))
+  }
+
   function rowIndexOf(tr: HTMLTableRowElement): number {
     const dataRow = tr.querySelector<HTMLElement>('[data-svgrid-row]')
     const val = dataRow?.dataset.svgridRow
@@ -81,6 +95,7 @@ export function rowResize(node: HTMLElement, opts: RowResizeOptions) {
     const max = current.max ?? 320
     const next = Math.max(min, Math.min(max, drag.startHeight + (e.clientY - drag.startY)))
     drag.trEl.style.height = `${Math.round(next)}px`
+    setStripValue(drag.strip, next)
     current.onResizeMove?.(drag.rowIndex, Math.round(next))
   }
   function onPointerUp(e: PointerEvent) {
@@ -124,6 +139,7 @@ export function rowResize(node: HTMLElement, opts: RowResizeOptions) {
       Math.max(min, Math.min(max, tr.getBoundingClientRect().height + delta)),
     )
     tr.style.height = `${next}px`
+    setStripValue(t, next)
     current.onResizeMove?.(rowIndex, next)
     current.onResize(rowIndex, next)
   }
@@ -189,7 +205,13 @@ export function rowResize(node: HTMLElement, opts: RowResizeOptions) {
           ? tr.querySelector<HTMLTableCellElement>('.sv-grid-cell')
           : null)
       if (!gutter) continue
-      if (gutter.querySelector(`:scope > .${STRIP_CLASS}`)) continue
+      const already = gutter.querySelector<HTMLElement>(`:scope > .${STRIP_CLASS}`)
+      if (already) {
+        // The row may have been resized from outside the action (a saved
+        // height, a double-click autofit); keep the separator's value honest.
+        setStripValue(already, tr.getBoundingClientRect().height)
+        continue
+      }
       // Anchor the strip to the gutter cell + allow it to overflow
       // downward into the row gap so the hit-area straddles the
       // row boundary the way Excel does.
@@ -203,6 +225,7 @@ export function rowResize(node: HTMLElement, opts: RowResizeOptions) {
       // A separator used as an interactive splitter has to be focusable so
       // keyboard-only users can reach it and drive `onKeyDown` (#79).
       strip.tabIndex = 0
+      setStripValue(strip, tr.getBoundingClientRect().height)
       // Inline the geometry + pointer-events so the strip works even
       // before SvGrid.css is parsed; the hover tint still comes from
       // the stylesheet. We keep the strip fully inside the gutter

package/src/selection.ts

@@ -548,7 +548,7 @@ export function createSelection<
     ctx.stopEdgeScroll();
     // Also commit a fill-handle drag if one was in progress - the user
     // released the mouse, time to apply the pattern.
-    if (ctx.fillDrag) ctx.onFillPointerUp();
+    if (ctx.fillDrag) ctx.onFillPointerUp(event);
     if (ctx.moveDrag) ctx.onMovePointerUp(event);
   }
 

package/src/server-block-cache.test.ts

@@ -294,6 +294,33 @@ describe('createBlockCache', () => {
     cache.dispose()
   })
 
+  it('retries one failed block by a row index, leaving the other failed blocks alone', async () => {
+    const server = scriptedFetch({ failBlocks: new Set([1, 3]) })
+    const cache = createBlockCache<Row>({
+      blockSize: 100,
+      fetch: server.fetch,
+      onChange: () => {},
+      schedule: sync,
+    })
+    cache.setViewport(100, 399)
+    await server.flush()
+    expect(cache.getCacheState().filter((b) => b.status === 'failed').map((b) => b.blockIndex)).toEqual([1, 3])
+
+    server.failBlocks.clear()
+    // The Retry on a row in block 3: block 1 stays failed, one request goes out.
+    const before = server.startsRequested().length
+    cache.retryFailedAt(350)
+    await server.flush()
+    expect(server.startsRequested().length).toBe(before + 1)
+    expect(cache.getCacheState().find((b) => b.blockIndex === 3)!.status).toBe('loaded')
+    expect(cache.getCacheState().find((b) => b.blockIndex === 1)!.status).toBe('failed')
+    // A row whose block is fine is a no-op.
+    cache.retryFailedAt(250)
+    await server.flush()
+    expect(server.startsRequested().length).toBe(before + 1)
+    cache.dispose()
+  })
+
   it('keeps the first block at its skeleton length when it fails with no count', async () => {
     // Nothing is known about the list yet, so the failed rows are the few
     // the level showed while loading, not a hundred and one of them.

package/src/server-block-cache.ts

@@ -177,6 +177,11 @@ export type BlockCache<TData> = {
   lastRowKnown(): boolean
   /** Re-fetch the blocks that failed. */
   retryFailed(): void
+  /**
+   * Re-fetch the failed block holding `rowIndex`, and only that one; the
+   * Retry on a failed row. A row whose block has not failed is a no-op.
+   */
+  retryFailedAt(rowIndex: number): void
   /**
    * Re-fetch the loaded blocks in place, keeping the row count and scroll
    * position. What you want after a mutation lands on the server.
@@ -502,6 +507,14 @@ export function createBlockCache<TData>(options: BlockCacheOptions<TData>): Bloc
       if (any) emit()
     },
 
+    retryFailedAt(rowIndex) {
+      const index = blockOf(Math.max(0, rowIndex))
+      if (blocks.get(index)?.status !== 'failed') return
+      blocks.delete(index)
+      ensureBlock(index)
+      emit()
+    },
+
     refresh() {
       // Keep the count and the scroll position: drop the DATA, re-request the
       // same blocks. The user sees skeletons where they were, not a jump home.

package/src/server-data-source.infinite.test.ts

@@ -167,6 +167,68 @@ describe('createServerDataSource in infinite mode', () => {
     ctl.dispose()
   })
 
+  it('retries only the block under the row the grid asks about', async () => {
+    let failing = true
+    const starts: number[] = []
+    const source: ServerDataSource<Row> = {
+      async getRows(req) {
+        starts.push(req.startRow)
+        if (failing && req.startRow >= 100) throw new Error('backend down')
+        const rows: Row[] = []
+        for (let i = req.startRow; i < Math.min(req.endRow, 1000); i += 1) {
+          rows.push({ id: i, name: `Row ${i}` })
+        }
+        return { rows, rowCount: 1000 }
+      },
+    }
+    let view!: ServerState<Row>
+    const ctl = createServerDataSource<Row>(source, {
+      mode: 'infinite',
+      blockSize: 100,
+      onChange: (s) => (view = s),
+    })
+    ctl.setViewport(100, 299)
+    await settle()
+    expect(view.failedBlocks).toEqual([1, 2])
+
+    failing = false
+    const before = starts.length
+    // The GridRowModel seam the failed row's Retry button goes through.
+    ctl.retryRow!(view.rows[250]!, 250)
+    await settle()
+    expect(starts.slice(before)).toEqual([200])
+    expect(view.failedBlocks).toEqual([1])
+    ctl.dispose()
+  })
+
+  it('hands each block a signal that purge, a sort change and dispose abort', async () => {
+    const signals: AbortSignal[] = []
+    const source: ServerDataSource<Row> = {
+      async getRows(req) {
+        signals.push(req.signal!)
+        // A server that never answers: only the abort can end these.
+        return new Promise(() => {})
+      },
+    }
+    const ctl = createServerDataSource<Row>(source, { mode: 'infinite', blockSize: 100, onChange: () => {} })
+    ctl.setViewport(0, 20)
+    await settle()
+    expect(signals).toHaveLength(1)
+    expect(signals[0]!.aborted).toBe(false)
+
+    ctl.purge()
+    await settle()
+    expect(signals[0]!.aborted).toBe(true)
+    expect(signals).toHaveLength(2)
+
+    ctl.setSort([{ id: 'id', desc: true }])
+    await settle()
+    expect(signals[1]!.aborted).toBe(true)
+
+    ctl.dispose()
+    expect(signals.at(-1)!.aborted).toBe(true)
+  })
+
   it('refresh keeps the count and the scroll position, purge does not', async () => {
     const { source, starts } = tableOf(1000)
     let view!: ServerState<Row>

package/src/server-data-source.test.ts

@@ -86,6 +86,25 @@ describe('createServerDataSource', () => {
     expect(ctl.getState().rows[0]).toEqual({ id: 30 })
   })
 
+  it('aborts the page fetch a newer one supersedes, and the last one on dispose', async () => {
+    const signals: AbortSignal[] = []
+    const src: ServerDataSource<Row> = {
+      getRows: async (req) => {
+        signals.push(req.signal!)
+        return new Promise(() => {})
+      },
+    }
+    const ctl = createServerDataSource(src, { pageSize: 10, onChange: () => {} })
+    ctl.refresh()
+    ctl.setPage(3)
+    await new Promise((r) => setTimeout(r, 5))
+    expect(signals).toHaveLength(2)
+    expect(signals[0]!.aborted).toBe(true)
+    expect(signals[1]!.aborted).toBe(false)
+    ctl.dispose()
+    expect(signals[1]!.aborted).toBe(true)
+  })
+
   it('dispose stops further updates', async () => {
     const src = makeSource(50, 20)
     const onChange = vi.fn()

package/src/server-data-source.ts

@@ -63,8 +63,17 @@ export type ServerFilterModel = {
   expression?: GridPredicateExpr
 }
 
-/** A value column to roll up per group. */
-export type ServerAggregation = { col: string; fn: 'sum' | 'avg' | 'min' | 'max' | 'count' }
+/** The aggregate functions every backend helper understands. */
+export type ServerAggFn = 'sum' | 'avg' | 'min' | 'max' | 'count'
+
+/**
+ * One value column to roll up per group. `fn` is one of the five built-ins
+ * or any name your backend knows (`median`, `countDistinct`, a domain
+ * aggregate): the request carries it untouched. The SvelteKit planner emits
+ * only the built-ins plus the names it was told to allow, since `fn` ends
+ * up in SQL.
+ */
+export type ServerAggregation = { col: string; fn: ServerAggFn | (string & {}) }
 
 /**
  * One range of rows as the grid asks for it. A flat request carries the
@@ -122,6 +131,16 @@ export type ServerRequest = {
    * transport posts the whole request to your endpoint.
    */
   context?: unknown
+  /**
+   * Aborted when the grid no longer wants the answer: the block was purged
+   * or evicted, the sort or filter changed, a group was collapsed, the
+   * controller was disposed. Hand it to `fetch` and a query the user has
+   * scrolled past is cancelled at the server instead of completing for
+   * nothing; a rejection carrying the abort is ignored by the grid. Not
+   * serialisable - the SvelteKit transport reads it and leaves it out of
+   * the body.
+   */
+  signal?: AbortSignal
 }
 
 /**
@@ -236,6 +255,21 @@ export type ServerPlaceholderRow = {
   readonly state: 'loading' | 'failed'
 }
 
+/**
+ * The detail panel under a leaf whose detail is open: master-detail on a
+ * server-side row model. The grid draws it through `renderDetailRow`
+ * (mark it with `isDetailRow`); `master` is the leaf it belongs to.
+ */
+export type ServerDetailRow<TData> = {
+  kind: 'detail'
+  id: string
+  level: number
+  route?: string[]
+  /** The leaf's id, as `getRowId` names it. */
+  masterId: string
+  master: TData
+}
+
 /**
  * Every row a server row model can put on screen. Each carries an `id` and
  * a `level`. The block-cached model adds {@link ServerPlaceholderRow} for
@@ -244,6 +278,7 @@ export type ServerPlaceholderRow = {
 export type ServerDisplayRow<TData> =
   | ServerGroupRow<TData>
   | ServerLeafRow<TData>
+  | ServerDetailRow<TData>
   | ServerMoreRow
   | ServerFooterRow<TData>
   | ServerSkeletonRow
@@ -523,6 +558,8 @@ export function createServerDataSource<TData>(
   // Monotonic request id: only the latest fetch is allowed to land, so a slow
   // response for an old sort/filter can't clobber a newer one.
   let requestSeq = 0
+  /** The page fetch in flight; a newer one, or dispose, aborts it. */
+  let pageAbort: AbortController | null = null
   let disposed = false
   // Once per controller: a misconfigured backend would otherwise log on every
   // page, scroll and filter change.
@@ -559,7 +596,7 @@ export function createServerDataSource<TData>(
       maxConcurrentRequests: options.maxConcurrentRequests,
       blockLoadDebounceMs: options.blockLoadDebounceMs,
       initialRowCount: options.initialRowCount,
-      fetch: async (startRow, endRow) => {
+      fetch: async (startRow, endRow, signal) => {
         const result = await source.getRows({
           startRow,
           endRow,
@@ -572,6 +609,7 @@ export function createServerDataSource<TData>(
           groupBy: [],
           groupKeys: [],
           aggregations: [],
+          signal,
         })
         noteExpressionApplied(result)
         return { rows: result.rows, rowCount: result.rowCount }
@@ -617,6 +655,9 @@ export function createServerDataSource<TData>(
   async function fetchPage() {
     if (disposed) return
     const id = ++requestSeq
+    pageAbort?.abort()
+    const controller = new AbortController()
+    pageAbort = controller
     state.loading = true
     state.error = null
     emit()
@@ -634,6 +675,7 @@ export function createServerDataSource<TData>(
         groupBy: [],
         groupKeys: [],
         aggregations: [],
+        signal: controller.signal,
       })
       if (disposed || id !== requestSeq) return // stale
       state.rows = result.rows
@@ -815,7 +857,7 @@ export function createServerDataSource<TData>(
     getRowId: options.getRowId ? (row: TData) => options.getRowId!(row) : undefined,
     // Only infinite mode has unloaded rows to stand in for.
     rowPlaceholder: infinite ? (row: TData) => rowPlaceholderState(row) : undefined,
-    retryRow: infinite ? () => cache?.retryFailed() : undefined,
+    retryRow: infinite ? (_row: TData, rowIndex: number) => cache?.retryFailedAt(rowIndex) : undefined,
     /**
      * A getter, not a snapshot: the grid re-reads this after every change
      * notification, and a frozen object would leave the pager on page 1
@@ -878,6 +920,8 @@ export function createServerDataSource<TData>(
     getState: () => ({ ...state }),
     dispose() {
       disposed = true
+      pageAbort?.abort()
+      pageAbort = null
       cache?.dispose()
       cache = null
       // An in-flight fetch's resolution short-circuits on `disposed`, so it

package/src/server.ts

@@ -19,6 +19,7 @@ export {
   type ServerState,
   type ServerSortModel,
   type ServerFilterModel,
+  type ServerAggFn,
   type ServerAggregation,
   type ServerGroupRow,
   type ServerLeafRow,
@@ -28,6 +29,7 @@ export {
   type ServerGrandTotalRow,
   type ServerPlaceholderRow,
   type ServerDisplayRow,
+  type ServerDetailRow,
 } from './server-data-source'
 export {
   createBlockCache,

package/src/sparkline.test.ts

@@ -59,6 +59,13 @@ describe('buildSparkline', () => {
     expect(g.bars[0]!.h).toBeCloseTo(g.bars[1]!.h)
   })
 
+  it('leaves a blank gap for a zero, marking only wins and losses', () => {
+    const g = buildSparkline([1, 0, -1, 0, 1], { type: 'winloss', height: 20 })!
+    // Two wins and a loss draw; the two zeros are gaps, as Excel draws them.
+    expect(g.bars).toHaveLength(3)
+    expect(g.bars.map((b) => b.negative)).toEqual([false, true, false])
+  })
+
   it('honors a fixed min/max scale', () => {
     const a = buildSparkline([5, 5, 5], { type: 'line', min: 0, max: 10 })!
     // flat series on a 0..10 scale sits at the vertical middle, not the top

package/src/sparkline.ts

@@ -102,11 +102,13 @@ export function buildSparkline(
     const barW = Math.max(1, slot - gap)
     const mid = height / 2
     const h = innerH / 2
-    const bars: SparklineBar[] = values.map((v, i) => {
+    const bars: SparklineBar[] = []
+    values.forEach((v, i) => {
       const x = pad + i * slot + (slot - barW) / 2
-      if (v > 0) return { x, y: mid - h, w: barW, h, negative: false }
-      if (v < 0) return { x, y: mid, w: barW, h, negative: true }
-      return { x, y: mid - 1, w: barW, h: 2, negative: false }
+      // A win/loss sparkline marks a win up and a loss down; a zero is a
+      // blank gap, no mark at all, the way Excel draws one.
+      if (v > 0) bars.push({ x, y: mid - h, w: barW, h, negative: false })
+      else if (v < 0) bars.push({ x, y: mid, w: barW, h, negative: true })
     })
     return { ...base, linePath: '', areaPath: '', bars, lastPoint: null }
   }

package/src/svgrid-wrapper.types.ts

@@ -146,6 +146,14 @@ export type SvGridApi<
   TFeatures extends TableFeatures,
   TData extends RowData,
 > = {
+  // ----- DOM -----
+  /**
+   * The grid's root element (`.sv-grid-root`), or null before mount and
+   * after unmount. For measuring, focusing, or reading the theme the grid
+   * is drawn with - the PDF export takes its colours from here.
+   */
+  getElement(): HTMLElement | null
+
   // ----- Cells -----
   /** Read a cell value from the underlying data at `rowIndex`. */
   getCellValue(rowIndex: number, columnId: string): unknown
@@ -430,6 +438,16 @@ export type SvGridApi<
   /** Snapshot of the current data array (pre-pipeline). */
   getData(): ReadonlyArray<TData>
 
+  /**
+   * The stable id the grid keys a row by: what the `getRowId` prop
+   * computed, or the row's position when no `getRowId` is set. Pass a
+   * display index (the space `getActiveCell`, `scrollToRow` and the cell
+   * methods use) or a row object; returns null for an unknown index or a
+   * row that is not in the data. Pair with `selectRows`, `toggleRowSelected`
+   * or an `applyTransaction` remove, all of which take these ids.
+   */
+  getRowId(row: number | TData): string | null
+
   /**
    * Snapshot of every column the grid currently knows about, in visual
    * order, with the human-readable header label. Use this when exporting
@@ -580,6 +598,20 @@ export type SvGridApi<
   canRedo(): boolean
   /** Wipe both stacks (e.g. after a server save commits the buffer). */
   clearHistory(): void
+  /**
+   * Mark every step recorded from now on with `tag`, until the next call;
+   * `undefined` stops the marking. The grid never reads the tag. It is for a
+   * consumer that shows one of several data sets through the grid (a
+   * workbook's sheets, say) and has to know which one the next Ctrl+Z would
+   * change before it lets the grid apply it: it tags the steps with the data
+   * set they were made on and asks `peekUndo` first.
+   */
+  setHistoryTag(tag: unknown): void
+  /** The step the next `undo()` would apply, or null when there is none. A
+   *  multi-cell action carries one tag, so it reports as one. */
+  peekUndo(): { tag: unknown } | null
+  /** The step the next `redo()` would apply, or null when there is none. */
+  peekRedo(): { tag: unknown } | null
 
   // ----- Keyboard commands -----
   /**

package/src/svgrid.api.test.ts

@@ -104,6 +104,27 @@ describe('SvGridApi - getData / getDisplayedRows', () => {
     }
   })
 
+  it('getRowId resolves a display index and a row object, and returns null for the unknown', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      // No getRowId prop: the id is the row's index as a string.
+      expect(api.getRowId(0)).toBe('0')
+      expect(api.getRowId(4)).toBe('4')
+      expect(api.getRowId(99)).toBeNull()
+      const third = api.getData()[2]!
+      expect(api.getRowId(third)).toBe('2')
+      expect(api.getRowId({ id: 999, name: 'x', team: 'x', salary: 0 })).toBeNull()
+      // After a sort the display index follows the new order.
+      api.setSort('salary', 'desc')
+      await Promise.resolve()
+      const topId = api.getRowId(0)
+      expect(topId).not.toBeNull()
+      expect(api.getData()[Number(topId)]!.salary).toBe(Math.max(...sampleRows.map((r) => r.salary)))
+    } finally {
+      destroy()
+    }
+  })
+
   it('getDisplayedRows returns the post-pipeline visible rows', async () => {
     const { api, destroy } = await mountGrid()
     try {