@svgrid/grid 3.0.3 → 4.0.0

package/src/row-model.ts

@@ -0,0 +1,146 @@
+/**
+ * `GridRowModel` - one prop instead of eleven.
+ *
+ * A grid backed by a server needs the same wiring every time: hand it the
+ * rows, tell it not to sort or filter locally, forward the sort and the filter
+ * to the backend, report which rows are on screen, say which rows have not
+ * loaded, and delegate selection. Written out by hand that is a dozen props
+ * and a filter-shape conversion that every app gets slightly differently:
+ *
+ * ```svelte
+ * <SvGrid data={s.rows} externalSort externalFilter loading={s.loading}
+ *   onSortingChange={(x) => ctl.setSort(x)}
+ *   onFiltersChange={(f) => ctl.setFilter({ global: f.global,
+ *     columns: Object.fromEntries(f.columns.map((c) => [c.id, { ... }])) })}
+ *   onVisibleRangeChange={(r) => ctl.setViewport(r.startIndex, r.endIndex)}
+ *   ... />
+ * ```
+ *
+ * An object that implements this interface carries all of it, so the same grid
+ * becomes:
+ *
+ * ```svelte
+ * <SvGrid rowModel={ctl} {columns} />
+ * ```
+ *
+ * `createServerDataSource` returns one, and so does the Enterprise server row
+ * model - which is the point of the interface rather than a concrete type: the
+ * grid depends on the SHAPE, never on either implementation, and an app with
+ * its own fetching can satisfy it too.
+ *
+ * Every member except `subscribe` / `getRows` / `isLoading` is optional, and a
+ * prop written explicitly on `<SvGrid>` always wins over the model's answer -
+ * so adopting this is never all-or-nothing.
+ */
+import type { FilterOperator } from './SvGrid.types'
+
+/** The filter state as the grid reports it, straight from `onFiltersChange`. */
+export type GridFilterState = {
+  global: string
+  columns: Array<{
+    id: string
+    operator: FilterOperator
+    value: string
+    valueTo?: string
+    selectedValues?: Array<string>
+  }>
+}
+
+/** The sort the grid hands a row model: column id and direction, in priority order. */
+export type GridRowModelSort = Array<{ id: string; desc: boolean }>
+
+/**
+ * What `<SvGrid rowModel>` consumes: rows, a loading flag, a change
+ * subscription, and whichever optional parts the model implements - sort,
+ * filter, viewport, placeholders, group accessors, selection, filter
+ * values, paging, pinned rows and pivot columns. `createServerDataSource`
+ * and the Enterprise `createServerRowModel` both satisfy it.
+ */
+export type GridRowModel<TData> = {
+  /**
+   * Register a callback for "something changed, re-read me". Returns an
+   * unsubscribe function, which the grid calls on unmount.
+   */
+  subscribe(onChange: () => void): () => void
+  /** The rows to render, including any placeholders for unloaded ones. */
+  getRows(): ReadonlyArray<TData>
+  /** True while a fetch is in flight, for the loading overlay. */
+  isLoading(): boolean
+  /** Stable row id. Required once selection or editing is involved. */
+  getRowId?(row: TData, index: number): string
+  /** Sort on the server. Present means "do not sort locally". */
+  setSort?(sort: GridRowModelSort): void
+  /** Filter on the server. Present means "do not filter locally". */
+  setFilter?(filters: GridFilterState): void
+  /** Which rows are on screen, so a block-loading model knows what to fetch. */
+  setViewport?(startIndex: number, endIndex: number): void
+  /** Why a row has no data yet, or null when it does. */
+  rowPlaceholder?(row: TData, rowIndex: number): 'loading' | 'failed' | null
+  /** Retry the failed block a placeholder row belongs to. */
+  retryRow?(row: TData, rowIndex: number): void
+  /** Group / tree accessors, for the grid's treegrid keyboard and ARIA. */
+  group?: {
+    isGroup: (row: TData) => boolean
+    level: (row: TData) => number
+    expanded?: (row: TData) => boolean
+    onToggle: (row: TData) => void
+  }
+  /** Selection the grid does not own - see the `rowSelectionModel` prop. */
+  selection?: {
+    isSelected: (rowId: string, row: TData) => boolean
+    headerState: () => 'none' | 'some' | 'all'
+    toggle: (rowId: string, row: TData, next: boolean) => void
+    toggleAll: (next: boolean) => void
+    selectedCount?: () => number | null
+    bulkUpdate?: (patch: Record<string, unknown>) => Promise<number>
+  }
+  /** Distinct values for a column's set filter, fetched from the server. */
+  filterValues?(columnId: string): Promise<Array<string>>
+  /** Server-side paging. Omit it for infinite scrolling. */
+  pagination?: {
+    pageIndex: number
+    pageSize: number
+    rowCount: number
+    setPage(pageIndex: number): void
+    setPageSize(pageSize: number): void
+    /** Choices for the footer's page-size selector. */
+    pageSizes?: number[]
+    /**
+     * Ask the grid for as many rows as its body fits: it measures and calls
+     * `setPageSize` whenever the fit changes.
+     */
+    autoPageSize?: boolean
+  }
+  /** Rows to pin above / below the scrolling body - a grand total, say. */
+  readonly pinnedTopRows?: ReadonlyArray<TData>
+  readonly pinnedBottomRows?: ReadonlyArray<TData>
+  /**
+   * Columns that replace the grid's `columns` while the model is in pivot
+   * mode, or null. Read after every change notification.
+   */
+  readonly pivotResultColumns?: ReadonlyArray<unknown> | null
+}
+
+/**
+ * Turn the grid's filter payload into the column-keyed map a `ServerRequest`
+ * carries. Exported because a hand-written `GridRowModel` needs exactly this
+ * conversion, and copying it is how the two shapes drift apart.
+ */
+export function toServerFilterColumns(
+  filters: GridFilterState,
+): Record<
+  string,
+  { operator: string; value: string; valueTo?: string; selectedValues?: Array<string> }
+> {
+  return Object.fromEntries(
+    filters.columns.map((c) => [
+      c.id,
+      {
+        operator: c.operator,
+        value: c.value,
+        ...(c.valueTo !== undefined ? { valueTo: c.valueTo } : {}),
+        ...(c.selectedValues !== undefined ? { selectedValues: c.selectedValues } : {}),
+      },
+    ]),
+  )
+}

package/src/row-resize.test.ts

@@ -209,6 +209,50 @@ describe('rowResize - strip injection', () => {
 // Drag lifecycle
 // ---------------------------------------------------------------------------
 
+describe('rowResize - double-click', () => {
+  it('asks for an autosize of the row and keeps the click from the row itself', () => {
+    const { host, rows } = buildGrid([{ rowIndex: 0 }, { rowIndex: 1 }])
+    track(host)
+    const onAutosize = vi.fn()
+    const rowSaw = vi.fn()
+    rows[1]!.addEventListener('dblclick', rowSaw)
+    const onResize = vi.fn()
+    const action = rowResize(host, { onResize, onAutosize })
+    const strip = stripOf(rows[1]!)!
+    // Two presses on one strip inside 400ms are a double-click.
+    strip.dispatchEvent(pointer('pointerdown', { clientY: 100 }))
+    window.dispatchEvent(pointer('pointerup', { clientY: 100 }))
+    strip.dispatchEvent(pointer('pointerdown', { clientY: 100 }))
+    expect(onAutosize).toHaveBeenCalledWith(1)
+    // No drag started, so nothing to release.
+    expect(strip.classList.contains('is-resizing')).toBe(false)
+    window.dispatchEvent(pointer('pointerup', { clientY: 100 }))
+    // The first press's release reported the unchanged height; the second
+    // press started no drag.
+    expect(onResize).toHaveBeenCalledTimes(1)
+    expect(rowSaw).not.toHaveBeenCalled()
+    action.destroy()
+  })
+
+  it('does nothing without an onAutosize handler', () => {
+    const { host, rows } = buildGrid([{ rowIndex: 0 }])
+    track(host)
+    const rowSaw = vi.fn()
+    rows[0]!.addEventListener('dblclick', rowSaw)
+    const onResize = vi.fn()
+    const action = rowResize(host, { onResize })
+    const strip = stripOf(rows[0]!)!
+    strip.dispatchEvent(pointer('pointerdown', { clientY: 100 }))
+    window.dispatchEvent(pointer('pointerup', { clientY: 100 }))
+    strip.dispatchEvent(pointer('pointerdown', { clientY: 100 }))
+    // Without a handler the second press is an ordinary drag start.
+    expect(strip.classList.contains('is-resizing')).toBe(true)
+    window.dispatchEvent(pointer('pointerup', { clientY: 100 }))
+    expect(rowSaw).not.toHaveBeenCalled()
+    action.destroy()
+  })
+})
+
 describe('rowResize - drag', () => {
   it('reports the new height on pointerup and fires move callbacks', () => {
     const { host, rows } = buildGrid([{ rowIndex: 0 }])

package/src/row-resize.ts

@@ -33,6 +33,9 @@ export type RowResizeOptions = {
   onResize: (rowIndex: number, height: number) => void
   /** Optional callback fired during the drag (every pointermove). */
   onResizeMove?: (rowIndex: number, height: number) => void
+  /** Double-click on the strip: size the row to its content, the
+   *  spreadsheet gesture. Without it a double-click does nothing. */
+  onAutosize?: (rowIndex: number) => void
   /** Min row height in px. Default 20. */
   min?: number
   /** Max row height in px. Default 320. */
@@ -63,6 +66,8 @@ type ActiveDrag = {
 export function rowResize(node: HTMLElement, opts: RowResizeOptions) {
   let current = opts
   let drag: ActiveDrag | null = null
+  /** The last press on a strip, for telling a double-click from two drags. */
+  let lastPress: { rowIndex: number; at: number } | null = null
 
   function rowIndexOf(tr: HTMLTableRowElement): number {
     const dataRow = tr.querySelector<HTMLElement>('[data-svgrid-row]')
@@ -133,6 +138,18 @@ export function rowResize(node: HTMLElement, opts: RowResizeOptions) {
     if (!Number.isFinite(rowIndex)) return
     e.preventDefault()
     e.stopPropagation()
+    // The second press of a double-click: size the row to its content
+    // instead of starting another drag. Timed here rather than read from
+    // a dblclick event, whose target is the row once the first press's
+    // resize has re-rendered the strip; pointerdown carries no count.
+    const now = e.timeStamp
+    const again = lastPress !== null && lastPress.rowIndex === rowIndex && now - lastPress.at < 400
+    lastPress = { rowIndex, at: now }
+    if (again && current.onAutosize) {
+      lastPress = null
+      current.onAutosize(rowIndex)
+      return
+    }
     t.classList.add('is-resizing')
     drag = {
       rowIndex,

package/src/scroll-sync.test.ts

@@ -203,6 +203,47 @@ describe('scheduleScrollSync / flushScheduledScrollSync', () => {
   })
 })
 
+describe('syncScrollNow', () => {
+  let cancelled: number[] = []
+  beforeEach(() => {
+    cancelled = []
+    vi.stubGlobal('requestAnimationFrame', () => 42)
+    vi.stubGlobal('cancelAnimationFrame', (h: number) => {
+      cancelled.push(h)
+    })
+  })
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('flushes the virtualizers synchronously, without waiting for a frame', () => {
+    const { ctx, ss } = syncFor({
+      rowVirtualizationEnabled: true,
+      columnVirtualizationEnabled: true,
+      domToLogicalRowOffset: (n: number) => n * 2,
+    })
+    ss.syncScrollNow(30, 88)
+    expect(ctx.pendingScrollTop).toBe(30)
+    expect(ctx.pendingScrollLeft).toBe(88)
+    expect(ctx.scrollVersion).toBe(1)
+    expect(ctx.virtualizer.setScrollOffset).toHaveBeenCalledWith(60)
+    expect(ctx.columnVirtualizer.setHorizontalOffset).toHaveBeenCalledWith(88)
+    expect(ctx.scrollSyncRaf).toBeNull()
+    expect(cancelled).toEqual([])
+  })
+
+  it('cancels a frame that a scroll event already scheduled, so the position is not applied twice', () => {
+    const { ctx, ss } = syncFor({ rowVirtualizationEnabled: true })
+    ss.scheduleScrollSync(10, 0)
+    expect(ctx.scrollSyncRaf).toBe(42)
+    ss.syncScrollNow(64, 0)
+    expect(cancelled).toEqual([42])
+    expect(ctx.scrollSyncRaf).toBeNull()
+    expect(ctx.virtualizer.setScrollOffset).toHaveBeenCalledTimes(1)
+    expect(ctx.virtualizer.setScrollOffset).toHaveBeenCalledWith(64)
+  })
+})
+
 describe('onBodyScroll', () => {
   beforeEach(() => {
     // These tests assert what happens BEFORE the frame runs, so the stub just
@@ -321,7 +362,7 @@ describe('createScrollSync wiring', () => {
   it('exposes the documented handler surface', () => {
     const { ss } = syncFor()
     expect(Object.keys(ss).sort()).toEqual(
-      ['flushScheduledScrollSync', 'hideTooltip', 'onBodyScroll', 'scheduleScrollSync', 'showTooltipFor'],
+      ['flushScheduledScrollSync', 'hideTooltip', 'onBodyScroll', 'scheduleScrollSync', 'showTooltipFor', 'syncScrollNow'],
     )
   })
 })

package/src/scroll-sync.ts

@@ -66,6 +66,30 @@ export function createScrollSync<
     ctx.scrollSyncRaf = requestAnimationFrame(flushScheduledScrollSync);
   }
 
+  /**
+   * Sync the virtualizers to a scroll position NOW instead of on the next
+   * animation frame.
+   *
+   * For a scroll the grid made itself - keyboard navigation bringing the
+   * active cell into view - the position is already known, and going through
+   * the browser's `scroll` event and then the rAF above put the row-window
+   * update one frame behind the key press: the keydown's own flush painted
+   * the active cell on the OLD rows, and the rows only caught up on the next
+   * frame. Two painted frames per arrow key. Syncing inline folds the window
+   * update into the same flush as the active-cell change, so the key press
+   * paints once. The `scroll` event still fires afterwards and re-syncs to
+   * the same offset, which the virtualizers treat as a no-op.
+   */
+  function syncScrollNow(scrollTop: number, scrollLeft: number) {
+    if (ctx.scrollSyncRaf !== null) {
+      cancelAnimationFrame(ctx.scrollSyncRaf);
+      ctx.scrollSyncRaf = null;
+    }
+    ctx.pendingScrollTop = scrollTop;
+    ctx.pendingScrollLeft = scrollLeft;
+    flushScheduledScrollSync();
+  }
+
   function onBodyScroll(event: Event) {
     const container = event.currentTarget as HTMLDivElement | null;
     if (!container) return;
@@ -91,6 +115,7 @@ export function createScrollSync<
     hideTooltip,
     flushScheduledScrollSync,
     scheduleScrollSync,
+    syncScrollNow,
     onBodyScroll,
   };
 }

package/src/selection.multi-range.test.ts

@@ -58,4 +58,38 @@ describe('multiple range selection', () => {
     // outside every range
     expect(s.getCellRangeEdges(2, 2)).toBeNull()
   })
+
+  it('cellSelectionState folds active cell, range edges and fill handle into one value', () => {
+    const ctx = makeCtx()
+    ctx.activeCell = { rowIndex: 1, colIndex: 1, cellId: null }
+    ctx.fillHandleCell = { rowIndex: 1, colIndex: 1 }
+    const s = createSelection(ctx)
+    s.setSelection(0, 0)
+    s.extendSelection(1, 1)
+
+    // The focus corner: active, on the bottom-right edges, carries the handle.
+    expect(s.cellSelectionState(1, 1)).toEqual({
+      active: true,
+      edges: { top: false, bottom: true, left: false, right: true },
+      fillHandle: true,
+    })
+    // Another cell of the range: in the range, not active, no handle.
+    expect(s.cellSelectionState(0, 1)).toEqual({
+      active: false,
+      edges: { top: true, bottom: false, left: false, right: true },
+      fillHandle: false,
+    })
+    // A plain cell is `null`, not an all-false object, so the view can tell
+    // "nothing changed here" by identity.
+    expect(s.cellSelectionState(5, 5)).toBeNull()
+  })
+
+  it('cellSelectionState reports the active cell even with no range anchored', () => {
+    const ctx = makeCtx()
+    ctx.activeCell = { rowIndex: 2, colIndex: 3, cellId: null }
+    ctx.fillHandleCell = null
+    const s = createSelection(ctx)
+    expect(s.cellSelectionState(2, 3)).toEqual({ active: true, edges: null, fillHandle: false })
+    expect(s.cellSelectionState(2, 4)).toBeNull()
+  })
 })

package/src/selection.test.ts

@@ -39,6 +39,9 @@ function makeCtx(overrides: any = {}) {
     allRows: [],
     allColumns: [],
     headerSelectionState: 'none',
+    // The real controller always supplies this; a fake that omits it would
+    // make every select-all path throw rather than assert.
+    placeholderStateOf: () => null,
     userHasActivatedCell: false,
     enableCellSelectionEffective: true,
     selectionRange: { anchor: null, focus: null },
@@ -75,6 +78,8 @@ function makeCtx(overrides: any = {}) {
     // for plain drag-select. Its own behaviour is covered in move-cells.test.ts.
     trackEdgeScroll: vi.fn(),
     stopEdgeScroll: vi.fn(),
+    // Inline virtualizer sync after a programmatic scroll (scroll-sync.ts).
+    syncScrollNow: vi.fn(),
     grid: {
       setRowSelection,
       setActiveCell,
@@ -367,6 +372,19 @@ describe('createSelection - onCellPointerDown', () => {
     expect(ctx.selectionRange.anchor).toEqual({ rowIndex: 0, colIndex: 0 })
     expect(ctx.selectionRange.focus).toEqual({ rowIndex: 1, colIndex: 1 })
     expect(ctx.activeAtPointerDown).toEqual({ rowIndex: 0, colIndex: 0 })
+    // The active cell stays at the anchor, as in Excel.
+    expect(ctx.grid.setActiveCell).not.toHaveBeenCalled()
+  })
+
+  it('Shift+click on a grid never clicked makes the cell active', () => {
+    const ctx = makeCtx({
+      allRows: [makeDataRow('r0'), makeDataRow('r1')],
+      allColumns: [makeColumn('c0'), makeColumn('c1')],
+      activeCell: null,
+    })
+    const sel = createSelection(ctx)
+    sel.onCellPointerDown(1, 1, { button: 0, shiftKey: true } as any)
+    expect(ctx.grid.setActiveCell).toHaveBeenCalled()
   })
 })
 
@@ -378,7 +396,7 @@ describe('createSelection - onCellPointerEnter / drag', () => {
     expect(ctx.grid.setActiveCell).not.toHaveBeenCalled()
   })
 
-  it('extends selection and moves active cell while dragging', () => {
+  it('extends the selection while dragging and leaves the active cell where the drag began', () => {
     const ctx = makeCtx({
       isDraggingSelection: true,
       selectionRange: { anchor: { rowIndex: 0, colIndex: 0 }, focus: { rowIndex: 0, colIndex: 0 } },
@@ -388,7 +406,7 @@ describe('createSelection - onCellPointerEnter / drag', () => {
     const sel = createSelection(ctx)
     sel.onCellPointerEnter(1, 1)
     expect(ctx.selectionRange.focus).toEqual({ rowIndex: 1, colIndex: 1 })
-    expect(ctx.grid.setActiveCell).toHaveBeenCalled()
+    expect(ctx.grid.setActiveCell).not.toHaveBeenCalled()
   })
 
   it('ignores group rows while dragging', () => {
@@ -649,6 +667,19 @@ describe('createSelection - onCellClick', () => {
     expect(ctx.onCellDoubleClick).toHaveBeenCalledWith(0, 0)
   })
 
+  it('leaves the cell alone on a second click when editOnSecondClick is off', () => {
+    // A sheet: clicking the active cell again is a click, not an edit.
+    const ctx = clickCtx({
+      editingEnabled: true,
+      activeAtPointerDown: { rowIndex: 0, colIndex: 0 },
+      props: { editOnSecondClick: false },
+    })
+    const sel = createSelection(ctx)
+    sel.onCellClick(0, 0)
+    expect(ctx.onCellDoubleClick).not.toHaveBeenCalled()
+    expect(ctx.editingCell).toBeNull()
+  })
+
   it('clears editing when not re-clicking the active cell', () => {
     const ctx = clickCtx({
       editingEnabled: true,