@svgrid/grid 1.2.21 → 1.2.23

package/src/index.ts

@@ -1,4 +1,27 @@
 export { formatNumericWithConfig, resolveDatePattern } from './cell-formatting'
+export {
+  coerceExportDate,
+  formatValueForExport,
+  projectGridRows,
+  toExcelNumFmt,
+  valueForExcel,
+  serializeDelimited,
+  serializeJson,
+  serializeMarkdown,
+  serializeHtml,
+  serializeXml,
+  downloadTextFile,
+  downloadBlobFile,
+  copyTextToClipboard,
+  type GridExportOptions,
+  type GridExportScope,
+  type GridExportColumn,
+  type GridClipboardOptions,
+  type GridClipboardFormat,
+  type SerializeProgress,
+  type SerializeOptions,
+  type CsvOptions,
+} from './export-format'
 
 export {
   columnFilteringFeature,
@@ -46,6 +69,54 @@ export { createGrid, createSvGrid, type SvelteGrid } from './createGrid.svelte'
 export { createGridState, createSvGridState } from './createGridState.svelte'
 export { subscribeGrid, subscribeSvGrid } from './subscribe'
 export { default as SvGrid } from './SvGrid.svelte'
+export { default as SvGridDropdown } from './SvGridDropdown.svelte'
+export { default as SvCalendar, type CalendarValue, type CalendarPreset, type CalendarAnimation } from './SvCalendar.svelte'
+export { default as SvTimePicker, type TimeValue } from './SvTimePicker.svelte'
+export { default as SvDateTimePicker, type DateTimeValue } from './SvDateTimePicker.svelte'
+// UI kit - Group B (buttons & toggles)
+export { default as SvButton } from './SvButton.svelte'
+export { default as SvRepeatButton } from './SvRepeatButton.svelte'
+export { default as SvToggleButton } from './SvToggleButton.svelte'
+export { default as SvSwitchButton } from './SvSwitchButton.svelte'
+export { default as SvCheckBox } from './SvCheckBox.svelte'
+export { default as SvRadioGroup, type RadioOption } from './SvRadioGroup.svelte'
+export { default as SvRating } from './SvRating.svelte'
+// UI kit - Group C (text inputs)
+export { default as SvNumberInput } from './SvNumberInput.svelte'
+export { default as SvPasswordInput } from './SvPasswordInput.svelte'
+export { default as SvMaskedInput } from './SvMaskedInput.svelte'
+export { default as SvPhoneInput } from './SvPhoneInput.svelte'
+export { default as SvColorInput } from './SvColorInput.svelte'
+export { applyMask, unmask, isMaskComplete } from './datetime/mask'
+export { COUNTRIES, COUNTRY_BY_CODE, flagEmoji, type Country } from './countries'
+// UI kit - Group D (selection overlays)
+export { default as SvListBox } from './SvListBox.svelte'
+export { default as SvDropDownList } from './SvDropDownList.svelte'
+export { default as SvComboBox } from './SvComboBox.svelte'
+export { default as SvAutoComplete } from './SvAutoComplete.svelte'
+export { default as SvTagsInput } from './SvTagsInput.svelte'
+export { default as SvCountryInput } from './SvCountryInput.svelte'
+export { filterOptions, type ListOption } from './list-option'
+// UI kit - Group E (range & feedback)
+export { default as SvSlider } from './SvSlider.svelte'
+export { default as SvGauge } from './SvGauge.svelte'
+// UI kit - Group F (composite / layout)
+export { default as SvTabs, type TabItem } from './SvTabs.svelte'
+export { default as SvTree, type TreeNode as SvTreeNode } from './SvTree.svelte'
+export { default as SvForm, type FormField, type FormFieldType } from './SvForm.svelte'
+export { anchoredRect, portalToBody, PANEL_THEME_VARS, type AnchoredRect } from './popover'
+export {
+  toDate, startOfDay, addDays, addMonths, addYears, clampDate, isSameDay,
+  monthMatrix, isoWeek, decadeRange, withTime, snapMinute, type DateLike,
+} from './datetime/date-core'
+export { formatDate, parseDate, tokenizeMask } from './datetime/date-format'
+export {
+  selectDate, rangeDays, isSelected, isMultiSelectMode, emptySelection,
+  type SelectionMode, type SelectionState,
+} from './datetime/date-selection'
+export {
+  isDisabledDay, isOutOfRange, isRestricted, isImportant, type RestrictOptions,
+} from './datetime/date-restrict'
 export { default as FlexRender } from './FlexRender.svelte'
 export { renderComponent, renderSnippet } from './render-component'
 export { default as SvGridChart } from './SvGridChart.svelte'

package/src/list-option.ts

@@ -0,0 +1,15 @@
+/** Shared option shape for the SvGrid UI-kit selection controls. */
+export type ListOption = {
+  value: string | number
+  label: string
+  disabled?: boolean
+  /** Optional group heading this option belongs under. */
+  group?: string
+}
+
+/** Case-insensitive substring filter over option labels. */
+export function filterOptions(options: ReadonlyArray<ListOption>, query: string): ListOption[] {
+  const q = query.trim().toLowerCase()
+  if (!q) return [...options]
+  return options.filter((o) => o.label.toLowerCase().includes(q))
+}

package/src/menus.ts

@@ -368,23 +368,42 @@ export function createMenus<
     }
   }
 
+  // External pagination is controlled: emit the requested page/size and let
+  // the consumer fetch + update props. Never mutate local pagination state.
+  function emitExternalPagination(pageIndex: number, pageSize: number): boolean {
+    if (ctx.props.externalPagination !== true) return false;
+    ctx.props.onPaginationChange?.({ pageIndex: Math.max(0, pageIndex), pageSize });
+    ctx.scrollContainer?.scrollTo?.({ top: 0 });
+    return true;
+  }
+
   function changePage(delta: number) {
+    if (
+      emitExternalPagination(
+        (ctx.props.pageIndex ?? 0) + delta,
+        ctx.props.pageSize ?? 10,
+      )
+    )
+      return;
     ctx.grid.setPagination((prev: any) => ({
       ...prev,
       pageIndex: Math.max((prev?.pageIndex ?? 0) + delta, 0),
     }));
-    ctx.scrollContainer?.scrollTo({ top: 0 });
+    ctx.scrollContainer?.scrollTo?.({ top: 0 });
   }
 
   function goToPage(pageIndex: number) {
+    if (emitExternalPagination(pageIndex, ctx.props.pageSize ?? 10)) return;
     ctx.grid.setPagination((prev: any) => ({
       ...prev,
       pageIndex: Math.max(0, pageIndex),
     }));
-    ctx.scrollContainer?.scrollTo({ top: 0 });
+    ctx.scrollContainer?.scrollTo?.({ top: 0 });
   }
 
   function setPageSize(pageSize: number) {
+    // External mode: changing page size resets to the first page.
+    if (emitExternalPagination(0, pageSize)) return;
     ctx.grid.setPagination((prev: any) => {
       const oldSize = prev?.pageSize ?? 10;
       const oldIndex = prev?.pageIndex ?? 0;

package/src/popover.ts

@@ -0,0 +1,79 @@
+/**
+ * popover - shared helpers for panels that must escape the grid's
+ * `overflow:hidden` scroll container by portalling to <body>: the theme-var
+ * snapshot + portal action, and the fixed-position anchor/flip math. Rune-free
+ * and DOM-only so it is reused verbatim by SvGridDropdown, SvDateTimePicker and
+ * any future popover. The per-component `$effect` wiring (scroll/resize
+ * reposition, outside-click close) stays in the component since it needs the
+ * component's own open state.
+ */
+
+/**
+ * Theme tokens a portalled panel must carry with it. `--sg-*` custom properties
+ * are scoped to whatever wrapper the grid sits inside (e.g. a per-preset theme
+ * class); moving the panel to <body> leaves that scope, so we snapshot the
+ * resolved values and pin them inline. Keep this list in sync with the tokens
+ * any popover panel actually consumes.
+ */
+export const PANEL_THEME_VARS = [
+  '--sg-accent', '--sg-bg', '--sg-fg', '--sg-border', '--sg-muted',
+  '--sg-header-bg', '--sg-row-hover-bg', '--sg-selection-bg',
+  '--sg-input-bg', '--sg-input-border', '--sg-selection-fg',
+] as const
+
+/**
+ * Svelte action: snapshot the resolved theme tokens from the node's current
+ * (in-scope) position, then detach it and append to <body> so it can never be
+ * clipped by an ancestor's overflow. Removes itself on destroy.
+ */
+export function portalToBody(node: HTMLElement, vars: ReadonlyArray<string> = PANEL_THEME_VARS) {
+  const cs = getComputedStyle(node)
+  for (const v of vars) {
+    const val = cs.getPropertyValue(v).trim()
+    if (val) node.style.setProperty(v, val)
+  }
+  document.body.appendChild(node)
+  return {
+    destroy() {
+      if (node.parentNode === document.body) document.body.removeChild(node)
+    },
+  }
+}
+
+export type AnchoredRect = { top: number; left: number; width: number; openUpward: boolean }
+
+export type AnchorOptions = {
+  /** Estimated panel height, used to decide whether to flip upward. */
+  estimatedHeight: number
+  /** Gap between trigger and panel. Default 2px. */
+  gap?: number
+  /** Force the panel at least this wide (else it matches the trigger). */
+  minWidth?: number
+  /** Keep the panel within the viewport horizontally. Default true. */
+  clampHorizontal?: boolean
+}
+
+/**
+ * Compute a `position: fixed` rect anchored to `triggerRect`, flipping above the
+ * trigger when there isn't room below and there's more room above. Mirrors the
+ * behavior SvGridDropdown shipped with, generalized with min-width + horizontal
+ * clamping for wider panels (date/time popovers).
+ */
+export function anchoredRect(triggerRect: DOMRect, opts: AnchorOptions): AnchoredRect {
+  const gap = opts.gap ?? 2
+  const spaceBelow = window.innerHeight - triggerRect.bottom
+  const spaceAbove = triggerRect.top
+  const openUpward = spaceBelow < opts.estimatedHeight && spaceAbove > spaceBelow
+  const width = Math.max(triggerRect.width, opts.minWidth ?? 0)
+  let left = triggerRect.left
+  if (opts.clampHorizontal !== false) {
+    const maxLeft = window.innerWidth - width - 4
+    left = Math.max(4, Math.min(left, maxLeft))
+  }
+  return {
+    top: openUpward ? triggerRect.top - opts.estimatedHeight - gap : triggerRect.bottom + gap,
+    left,
+    width,
+    openUpward,
+  }
+}

package/src/row-resize.test.ts

@@ -131,6 +131,31 @@ describe('rowResize - strip injection', () => {
     action.destroy()
   })
 
+  it('also injects a strip into the built-in row-number gutter (showRowNumbers)', () => {
+    // The native gutter cell is `.sv-grid-cell.sv-grid-row-number-cell`, NOT
+    // `.sv-row-gutter`; the action must recognise it so `showRowNumbers` grids
+    // are row-resizable without a custom gutter column.
+    const host = document.createElement('div')
+    const table = document.createElement('table')
+    const tbody = document.createElement('tbody')
+    const tr = document.createElement('tr')
+    tr.className = 'sv-grid-row'
+    const gutter = document.createElement('td')
+    gutter.className = 'sv-grid-cell sv-grid-row-number-cell'
+    const marker = document.createElement('span')
+    marker.setAttribute('data-svgrid-row', '0')
+    gutter.appendChild(marker)
+    tr.appendChild(gutter)
+    tbody.appendChild(tr)
+    table.appendChild(tbody)
+    host.appendChild(table)
+    document.body.appendChild(host)
+    track(host)
+    const action = rowResize(host, { onResize: vi.fn() })
+    expect(tr.querySelector(`.${STRIP_CLASS}`)).not.toBeNull()
+    action.destroy()
+  })
+
   it('does not override an already-positioned gutter cell', () => {
     const { host, rows } = buildGrid([{}])
     track(host)

package/src/row-resize.ts

@@ -4,10 +4,10 @@
  * reads per-row heights from a reactive store.
  *
  * The action is OFF until a consumer attaches it AND a row-header
- * gutter cell exists in each row. A row-header cell is any TD with
- * the `sv-row-gutter` class (typically the one rendering the row
- * number 1, 2, 3, ...). Demos opt in by setting
- * `cellClass: 'sv-row-gutter'` on the gutter column.
+ * gutter cell exists in each row. A row-header cell is either the
+ * grid's built-in row-number gutter (enable `showRowNumbers`) or any
+ * TD tagged with the `sv-row-gutter` class (set
+ * `cellClass: 'sv-row-gutter'` on a custom gutter column).
  *
  *   <script>
  *     let heights = $state<Record<number, number>>({})
@@ -116,8 +116,11 @@ export function rowResize(node: HTMLElement, opts: RowResizeOptions) {
     for (const tr of rows) {
       if (tr.classList.contains('sv-grid-header-row')) continue
       if (tr.classList.contains('sv-grid-row-spacer')) continue
+      // A row-header gutter cell: either a user column tagged
+      // `sv-row-gutter`, or the grid's built-in row-number gutter
+      // (`showRowNumbers`), whose cell is `.sv-grid-row-number-cell`.
       const gutter = tr.querySelector<HTMLTableCellElement>(
-        '.sv-grid-cell.sv-row-gutter',
+        '.sv-grid-cell.sv-row-gutter, .sv-grid-cell.sv-grid-row-number-cell',
       )
       if (!gutter) continue
       if (gutter.querySelector(`:scope > .${STRIP_CLASS}`)) continue

package/src/selection.test.ts

@@ -310,22 +310,26 @@ describe('createSelection - onCellPointerDown', () => {
     expect(ctx.grid.setActiveCell).not.toHaveBeenCalled()
   })
 
-  it('ignores checkbox columns (by editorType)', () => {
+  it('starts a drag on checkbox columns too (by editorType)', () => {
+    // A range drag must be able to START on a checkbox cell; the plain-click
+    // toggle still runs via onCellClick (same-cell click).
     const ctx = baseCtx({
       allColumns: [makeColumn('c0', { editorType: 'checkbox' })],
     })
     const sel = createSelection(ctx)
     sel.onCellPointerDown(0, 0, { button: 0, shiftKey: false } as any)
-    expect(ctx.grid.setActiveCell).not.toHaveBeenCalled()
+    expect(ctx.grid.setActiveCell).toHaveBeenCalled()
+    expect(ctx.isDraggingSelection).toBe(true)
   })
 
-  it('ignores boolean-valued cells', () => {
+  it('starts a drag on boolean-valued cells too', () => {
     const ctx = baseCtx({
       getCellDisplayValue: vi.fn(() => true),
     })
     const sel = createSelection(ctx)
     sel.onCellPointerDown(0, 0, { button: 0, shiftKey: false } as any)
-    expect(ctx.grid.setActiveCell).not.toHaveBeenCalled()
+    expect(ctx.grid.setActiveCell).toHaveBeenCalled()
+    expect(ctx.isDraggingSelection).toBe(true)
   })
 
   it('plain click sets active + selection and starts a drag', () => {
@@ -720,3 +724,31 @@ describe('createSelection - scrollActiveCellIntoView', () => {
     expect(container.scrollLeft).toBe(320)
   })
 })
+
+describe('createSelection - fillMarqueeEdges (Excel fill marquee)', () => {
+  // Union rectangle spans rows 1..4, cols 0..2 (source cols 0..1 extended to col 2,
+  // source rows 1..2 extended to row 4).
+  const fillDrag = {
+    sourceMinRow: 1, sourceMaxRow: 2, sourceMinCol: 0, sourceMaxCol: 1,
+    targetRow: 4, targetCol: 2,
+  }
+
+  it('returns null when there is no fill drag', () => {
+    const sel = createSelection(makeCtx())
+    expect(sel.fillMarqueeEdges(1, 0)).toBeNull()
+  })
+
+  it('flags the outer edges of the whole target rectangle', () => {
+    const sel = createSelection(makeCtx({ fillDrag }))
+    expect(sel.fillMarqueeEdges(1, 0)).toEqual({ top: true, bottom: false, left: true, right: false })
+    expect(sel.fillMarqueeEdges(4, 2)).toEqual({ top: false, bottom: true, left: false, right: true })
+    expect(sel.fillMarqueeEdges(1, 1)).toEqual({ top: true, bottom: false, left: false, right: false })
+  })
+
+  it('returns null for interior cells and cells outside the rectangle', () => {
+    const sel = createSelection(makeCtx({ fillDrag }))
+    expect(sel.fillMarqueeEdges(2, 1)).toBeNull() // interior
+    expect(sel.fillMarqueeEdges(0, 0)).toBeNull() // above
+    expect(sel.fillMarqueeEdges(5, 2)).toBeNull() // below
+  })
+})

package/src/selection.ts

@@ -396,6 +396,30 @@ export function createSelection<
     return !inSource;
   }
 
+  /**
+   * Which edges of the fill-drag rectangle a cell sits on, so the render can
+   * paint a single dashed marquee around the WHOLE target range (source +
+   * extension) - the Excel fill-handle look - instead of a thick per-cell
+   * border. Returns null when the cell isn't on the rectangle's boundary.
+   */
+  function fillMarqueeEdges(rowIndex: number, colIndex: number) {
+    const d = ctx.fillDrag;
+    if (!d) return null;
+    const minR = Math.min(d.sourceMinRow, d.targetRow);
+    const maxR = Math.max(d.sourceMaxRow, d.targetRow);
+    const minC = Math.min(d.sourceMinCol, d.targetCol);
+    const maxC = Math.max(d.sourceMaxCol, d.targetCol);
+    if (rowIndex < minR || rowIndex > maxR || colIndex < minC || colIndex > maxC) {
+      return null;
+    }
+    const top = rowIndex === minR;
+    const bottom = rowIndex === maxR;
+    const left = colIndex === minC;
+    const right = colIndex === maxC;
+    if (!top && !bottom && !left && !right) return null;
+    return { top, bottom, left, right };
+  }
+
   /** Look up a column by id without depending on `buildApi`'s private
    *  closure (those helpers don't exist at this scope). */
   function findColumnById(columnId: string) {
@@ -411,15 +435,11 @@ export function createSelection<
     const row = ctx.allRows[rowIndex];
     const column = ctx.allColumns[colIndex];
     if (!row || !column || isGroupRow(row)) return;
-    const cellValue = ctx.getCellDisplayValue(
-      row.id,
-      column.id,
-      getColumnBaseValue(row, column),
-    );
-    const isCheckboxColumn =
-      column.columnDef.editorType === "checkbox" ||
-      typeof cellValue === "boolean";
-    if (isCheckboxColumn) return; // let onCellClick toggle the checkbox
+    // NOTE: we no longer bail for checkbox columns. Bailing here meant a
+    // range drag could never START on a checkbox cell. A plain click still
+    // toggles the checkbox via onCellClick (a same-cell click), while a
+    // cross-cell drag fires its `click` on a common ancestor - not the cell -
+    // so it selects a range without toggling.
 
     const active = ctx.grid.getState().activeCell;
     ctx.activeAtPointerDown = active
@@ -566,6 +586,7 @@ export function createSelection<
     extendSelection,
     isCellInSelectedRange,
     getCellRangeEdges,
+    fillMarqueeEdges,
     getSelectionRects,
     isInFillPreview,
     findColumnById,

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

@@ -36,6 +36,17 @@ describe('createServerDataSource', () => {
     expect(states.some((s) => s.loading)).toBe(true)
   })
 
+  it('dispose() during an in-flight fetch clears the loading state (#83)', async () => {
+    const src = makeSource(250, 20) // 20ms delay keeps the fetch in-flight
+    const ctl = createServerDataSource(src, { pageSize: 50, onChange: () => {} })
+    ctl.refresh()
+    expect(ctl.getState().loading).toBe(true)
+    ctl.dispose()
+    expect(ctl.getState().loading).toBe(false)
+    await new Promise((r) => setTimeout(r, 30)) // let the fetch settle
+    expect(ctl.getState().loading).toBe(false) // stays cleared, not stuck
+  })
+
   it('setPage fetches the right slice', async () => {
     const src = makeSource(250)
     const ctl = createServerDataSource(src, { pageSize: 50, onChange: () => {} })
@@ -86,3 +97,193 @@ describe('createServerDataSource', () => {
     expect(ctl.getState().rows).toHaveLength(0)
   })
 })
+
+describe('createServerDataSource mutations', () => {
+  type URow = { id: number; name: string }
+
+  function writable() {
+    let store: URow[] = [
+      { id: 0, name: 'a' },
+      { id: 1, name: 'b' },
+      { id: 2, name: 'c' },
+    ]
+    return {
+      getRows: vi.fn(async (req: { startRow: number; endRow: number }) => ({
+        rows: store.slice(req.startRow, req.endRow),
+        rowCount: store.length,
+      })),
+      createRow: vi.fn(async (input: Partial<URow>) => {
+        const row: URow = { id: store.length, name: input.name ?? '' }
+        store = [...store, row]
+        return row
+      }),
+      updateRow: vi.fn(async (id: string, patch: Partial<URow>) => {
+        store = store.map((r) => (String(r.id) === id ? { ...r, ...patch } : r))
+        return store.find((r) => String(r.id) === id)!
+      }),
+      deleteRow: vi.fn(async (id: string) => {
+        store = store.filter((r) => String(r.id) !== id)
+      }),
+    } as unknown as ServerDataSource<URow> & {
+      getRows: ReturnType<typeof vi.fn>
+      createRow: ReturnType<typeof vi.fn>
+      updateRow: ReturnType<typeof vi.fn>
+      deleteRow: ReturnType<typeof vi.fn>
+    }
+  }
+
+  it('createRow writes through and refreshes the current page', async () => {
+    const src = writable()
+    const ctl = createServerDataSource(src, { pageSize: 50, onChange: () => {} })
+    ctl.refresh()
+    await flush()
+    const created = await ctl.createRow({ name: 'z' })
+    expect(created).toEqual({ id: 3, name: 'z' })
+    expect(src.createRow).toHaveBeenCalledWith({ name: 'z' })
+    // the follow-up refresh re-fetched, so total + rows reflect the write
+    expect(ctl.getState().total).toBe(4)
+    expect(ctl.getState().rows.some((r) => r.name === 'z')).toBe(true)
+  })
+
+  it('toggles `saving` around a mutation', async () => {
+    const src = writable()
+    const states: Array<{ saving: boolean }> = []
+    const ctl = createServerDataSource(src, { pageSize: 50, onChange: (s) => states.push(s) })
+    const p = ctl.createRow({ name: 'x' })
+    expect(ctl.getState().saving).toBe(true) // synchronous emit before the await
+    await p
+    expect(ctl.getState().saving).toBe(false)
+    expect(states.some((s) => s.saving)).toBe(true)
+  })
+
+  it('updateRow and deleteRow call through and refresh', async () => {
+    const src = writable()
+    const ctl = createServerDataSource(src, { pageSize: 50, onChange: () => {} })
+    ctl.refresh()
+    await flush()
+    const updated = await ctl.updateRow('1', { name: 'B!' })
+    expect(updated).toEqual({ id: 1, name: 'B!' })
+    expect(src.updateRow).toHaveBeenCalledWith('1', { name: 'B!' })
+    expect(ctl.getState().rows.find((r) => r.id === 1)?.name).toBe('B!')
+
+    await ctl.deleteRow('0')
+    expect(src.deleteRow).toHaveBeenCalledWith('0')
+    expect(ctl.getState().total).toBe(2)
+    expect(ctl.getState().rows.some((r) => r.id === 0)).toBe(false)
+  })
+
+  it('rejects when the source has no matching writer', async () => {
+    const readonly: ServerDataSource<URow> = {
+      getRows: async () => ({ rows: [], rowCount: 0 }),
+    }
+    const ctl = createServerDataSource(readonly, { onChange: () => {} })
+    await expect(ctl.createRow({ name: 'x' })).rejects.toThrow(/does not implement createRow/)
+    await expect(ctl.updateRow('1', {})).rejects.toThrow(/does not implement updateRow/)
+    await expect(ctl.deleteRow('1')).rejects.toThrow(/does not implement deleteRow/)
+  })
+
+  it('rejects mutations after dispose, without calling the source', async () => {
+    const src = writable()
+    const ctl = createServerDataSource(src, { onChange: () => {} })
+    ctl.dispose()
+    await expect(ctl.deleteRow('0')).rejects.toThrow(/disposed/)
+    expect(src.deleteRow).not.toHaveBeenCalled()
+  })
+
+  it('leaves read state untouched when a mutation fails', async () => {
+    const src = writable()
+    src.createRow.mockRejectedValueOnce(new Error('boom'))
+    const ctl = createServerDataSource(src, { pageSize: 50, onChange: () => {} })
+    ctl.refresh()
+    await flush()
+    await expect(ctl.createRow({ name: 'x' })).rejects.toThrow('boom')
+    expect(ctl.getState().saving).toBe(false)
+    expect(ctl.getState().total).toBe(3) // unchanged; no refresh on failure
+  })
+})
+
+describe('createServerDataSource optimistic mutations', () => {
+  type URow = { id: number; name: string }
+  const opts = (onChange: (s: any) => void = () => {}) => ({
+    pageSize: 50,
+    optimistic: true,
+    getRowId: (r: URow) => String(r.id),
+    onChange,
+  })
+
+  function writable() {
+    let store: URow[] = [
+      { id: 0, name: 'a' },
+      { id: 1, name: 'b' },
+      { id: 2, name: 'c' },
+    ]
+    return {
+      getRows: vi.fn(async (req: { startRow: number; endRow: number }) => ({
+        rows: store.slice(req.startRow, req.endRow),
+        rowCount: store.length,
+      })),
+      updateRow: vi.fn(async (id: string, patch: Partial<URow>) => {
+        store = store.map((r) => (String(r.id) === id ? { ...r, ...patch } : r))
+        return store.find((r) => String(r.id) === id)!
+      }),
+      deleteRow: vi.fn(async (id: string) => {
+        store = store.filter((r) => String(r.id) !== id)
+      }),
+    } as any
+  }
+
+  it('applies an update to local rows immediately, before the server resolves', async () => {
+    const src = writable()
+    src.updateRow.mockImplementationOnce(
+      (id: string, patch: any) => new Promise((r) => setTimeout(() => r({ id: Number(id), ...patch }), 30)),
+    )
+    const ctl = createServerDataSource(src, opts())
+    ctl.refresh()
+    await flush()
+    const p = ctl.updateRow('1', { name: 'B!' })
+    // synchronously reflected, no refetch
+    expect(ctl.getState().rows.find((r) => r.id === 1)?.name).toBe('B!')
+    expect(ctl.getState().saving).toBe(true)
+    await p
+    expect(ctl.getState().saving).toBe(false)
+    // getRows only called once (the initial refresh) - no refetch for the update
+    expect(src.getRows).toHaveBeenCalledTimes(1)
+  })
+
+  it('rolls an update back on error', async () => {
+    const src = writable()
+    src.updateRow.mockRejectedValueOnce(new Error('nope'))
+    const ctl = createServerDataSource(src, opts())
+    ctl.refresh()
+    await flush()
+    await expect(ctl.updateRow('1', { name: 'B!' })).rejects.toThrow('nope')
+    expect(ctl.getState().rows.find((r) => r.id === 1)?.name).toBe('b') // restored
+  })
+
+  it('removes a row immediately on delete and decrements total, restoring on error', async () => {
+    const src = writable()
+    const ctl = createServerDataSource(src, opts())
+    ctl.refresh()
+    await flush()
+
+    const p = ctl.deleteRow('0')
+    expect(ctl.getState().rows.some((r) => r.id === 0)).toBe(false)
+    expect(ctl.getState().total).toBe(2)
+    await p
+
+    src.deleteRow.mockRejectedValueOnce(new Error('locked'))
+    await expect(ctl.deleteRow('1')).rejects.toThrow('locked')
+    expect(ctl.getState().rows.some((r) => r.id === 1)).toBe(true) // restored
+    expect(ctl.getState().total).toBe(2)
+  })
+
+  it('falls back to a refetch when the row is not on the current page', async () => {
+    const src = writable()
+    const ctl = createServerDataSource(src, opts())
+    ctl.refresh()
+    await flush()
+    await ctl.updateRow('999', { name: 'ghost' }) // not present locally
+    // fell back to mutate() which refreshes: getRows called again
+    expect(src.getRows).toHaveBeenCalledTimes(2)
+  })
+})