@svgrid/grid 3.0.6 → 3.0.8

package/src/SvGrid.helpers.ts

@@ -3,6 +3,7 @@
 // (plus DOM/Intl globals), so they live here to keep the component leaner.
 import type { CellEditorType, CellEditorOption } from "./index";
 import type { ResolvedCellFormat } from "./conditional-formatting";
+import { parseDateValue } from "./cell-formatting";
 
 export function cfTextStyle(cf: ResolvedCellFormat): string {
   let s = "";
@@ -258,10 +259,7 @@ export function getEditorClass(editorType: CellEditorType) {
 }
 
 export function asDate(value: unknown) {
-  if (value == null || value === "") return null;
-  const parsed =
-    value instanceof Date ? value : new Date(value as string | number);
-  return Number.isNaN(parsed.getTime()) ? null : parsed;
+  return parseDateValue(value);
 }
 
 export function clampMenuX(x: number, width: number) {

package/src/SvGrid.svelte

@@ -1212,7 +1212,10 @@
     column: Column<TData>,
     cellValue: unknown,
   )}
-    {#if column.columnDef.editorType === "checkbox" || typeof cellValue === "boolean"}
+    <!-- A column's own `cell` renderer wins over every built-in display, the
+         checkbox included: a boolean field drawn as a flag button or a status
+         pill used to come out as a read-only checkbox, with `cell` never called. -->
+    {#if (column.columnDef.editorType === "checkbox" || typeof cellValue === "boolean") && column.columnDef.cell == null}
       <div
         class="sv-grid-checkbox sv-grid-checkbox-readonly"
         role="checkbox"

package/src/cell-formatting.ts

@@ -127,6 +127,37 @@ export function getNumberFormatter(
   return fmt
 }
 
+/**
+ * A cell value as a Date, or null when it is not one. Accepts a Date, epoch ms,
+ * or a parseable string.
+ *
+ * A bare calendar date ('2026-06-27') is read as LOCAL midnight of that day.
+ * `new Date('2026-06-27')` reads it as UTC midnight, which every zone west of
+ * UTC formats as the 26th. The day in the string is the day the user meant.
+ */
+export function parseDateValue(value: unknown): Date | null {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) return null
+    const d = new Date(value)
+    return Number.isNaN(d.getTime()) ? null : d
+  }
+  if (typeof value !== 'string') return null
+  const s = value.trim()
+  if (s === '') return null
+  const ymd = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s)
+  if (ymd) {
+    const [y, m, day] = [Number(ymd[1]), Number(ymd[2]) - 1, Number(ymd[3])]
+    const d = new Date(0)
+    d.setFullYear(y, m, day)
+    d.setHours(0, 0, 0, 0)
+    // Reject a rollover ('2026-02-30' is not March 2nd), as `new Date` does.
+    return d.getMonth() === m && d.getDate() === day ? d : null
+  }
+  const d = new Date(s)
+  return Number.isNaN(d.getTime()) ? null : d
+}
+
 /** Cache of `Intl.DateTimeFormat` by `(locale, options)` signature. */
 const dateFormatterCache = new Map<string, Intl.DateTimeFormat>()
 /** A cached `Intl.DateTimeFormat` for the locale and options given. Cached because

package/src/core.sort.test.ts

@@ -12,6 +12,10 @@
  * snapshot the new output, `referenceSort` below is a literal transcription of
  * the ORIGINAL comparator, and every case asserts the two agree. If the rewrite
  * ever diverges on any input, including the randomised ones, this fails.
+ *
+ * The oracle calls the pairwise `sortFns`, so it tracks their semantics: since
+ * #104 those put blanks and unparseable values first instead of returning NaN,
+ * and `auto` compares numbers numerically.
  */
 import { describe, expect, it } from 'vitest'
 // From './core' rather than './index': `createSvGridCore` is the runes-free
@@ -233,6 +237,88 @@ describe('createSortedRowModel - equivalence with the original comparator', () =
   })
 })
 
+describe('built-in comparators keep the Array.sort contract (#104)', () => {
+  it('number: non-numeric values sort together ahead of the numbers', () => {
+    expect([5, 'n/a', 3, 1, 'n/a', 4, 2].sort(sortFns.number)).toEqual(['n/a', 'n/a', 1, 2, 3, 4, 5])
+    expect(sortFns.number('n/a', 'x')).toBe(0)
+    expect(Number.isNaN(sortFns.number('n/a', 3))).toBe(false)
+  })
+
+  it('date: blanks and invalid dates sort first and never return NaN', () => {
+    // null, not undefined: Array.prototype.sort moves undefined to the end
+    // without calling the comparator.
+    const sorted = ['2021-01-01', null, 'junk', '2020-01-01'].sort(sortFns.date)
+    expect(sorted).toEqual([null, 'junk', '2020-01-01', '2021-01-01'])
+    expect(sortFns.date(undefined, 'junk')).toBe(0)
+  })
+
+  it('auto: numbers compare numerically, blanks come first', () => {
+    expect([2, 10, 1, 20, 100, 3].sort(sortFns.auto)).toEqual([1, 2, 3, 10, 20, 100])
+    expect(['oak', null, 'nuclear', '', 'apple'].sort(sortFns.auto)).toEqual([
+      null, '', 'apple', 'nuclear', 'oak',
+    ])
+  })
+
+  it('every built-in comparator is antisymmetric and transitive on mixed values', () => {
+    const pool: unknown[] = [
+      null, undefined, '', 0, -1, 2, 10, NaN, 1e21, '1a', '2', '10', 'n/a', 'apple', 'Apple',
+      true, '2020-01-01', 'junk', 1600000000000,
+    ]
+    for (const [name, cmp] of Object.entries(sortFns)) {
+      const sign = (a: unknown, b: unknown) => Math.sign(cmp(a, b))
+      for (const a of pool) {
+        for (const b of pool) {
+          const ab = sign(a, b)
+          expect(Number.isNaN(ab), `${name}(${String(a)}, ${String(b)}) is NaN`).toBe(false)
+          expect(ab, `${name} antisymmetry on ${String(a)}, ${String(b)}`).toBe(-sign(b, a) || 0)
+          for (const c of pool) {
+            if (ab <= 0 && sign(b, c) <= 0) {
+              expect(sign(a, c), `${name}: ${String(a)} <= ${String(b)} <= ${String(c)}`).toBeLessThanOrEqual(0)
+            }
+          }
+        }
+      }
+    }
+  })
+
+  it('sorts an untyped numeric column numerically in the row model', () => {
+    const rows: Row[] = [2, 10, null, 1, 20, 100, 3].map((qty) => ({ qty }))
+    const cols = [{ field: 'qty' }]
+    expect(actualSort(rows, cols, [{ id: 'qty', desc: false }]).map((r) => r.qty)).toEqual([
+      null, 1, 2, 3, 10, 20, 100,
+    ])
+    expect(actualSort(rows, cols, [{ id: 'qty', desc: true }]).map((r) => r.qty)).toEqual([
+      100, 20, 10, 3, 2, 1, null,
+    ])
+  })
+
+  it('sorts a number column with placeholder text in order', () => {
+    const rows: Row[] = [5, 'n/a', 3, 1, 'n/a', 4, 2].map((v) => ({ v }))
+    const sorted = actualSort(rows, [{ field: 'v', editorType: 'number' }], [{ id: 'v', desc: false }])
+    expect(sorted.map((r) => r.v)).toEqual(['n/a', 'n/a', 1, 2, 3, 4, 5])
+  })
+
+  it('orders a mixed number and text column by kind, then value', () => {
+    const rows: Row[] = [10, 'b', 2, null, 'a', 1].map((v) => ({ v }))
+    const sorted = actualSort(rows, [{ field: 'v' }], [{ id: 'v', desc: false }])
+    expect(sorted.map((r) => r.v)).toEqual([null, 1, 2, 10, 'a', 'b'])
+  })
+
+  it('lets the next clause decide when two blanks tie on a numeric clause', () => {
+    // Two -Infinity keys subtract to NaN; the multi-clause loop must see 0.
+    const rows: Row[] = [
+      { num: null, text: 'b' },
+      { num: 'n/a', text: 'a' },
+      { num: 1, text: 'c' },
+    ]
+    const sorted = actualSort(rows, COLUMNS, [
+      { id: 'num', desc: false },
+      { id: 'text', desc: false },
+    ])
+    expect(sorted.map((r) => r.text)).toEqual(['a', 'b', 'c'])
+  })
+})
+
 describe('createSortedRowModel - work budget', () => {
   /** Count `getAllColumns` calls the way tools/bench does, but in-process. */
   function countColumnLookups(rowCount: number, sorting: SortingState): number {

package/src/core.ts

@@ -745,13 +745,52 @@ export function tableFeatures<T extends TableFeatures>(features: T): T {
  * text; set a column's type or supply your own comparator to override.
  */
 export const sortFns = {
-  auto: (a: unknown, b: unknown) => String(a).localeCompare(String(b)),
-  number: (a: unknown, b: unknown) => Number(a ?? 0) - Number(b ?? 0),
-  date: (a: unknown, b: unknown) => {
-    const aa = new Date(a as any).getTime()
-    const bb = new Date(b as any).getTime()
-    return aa - bb
-  },
+  auto: (a: unknown, b: unknown) => compareAutoValues(a, b),
+  number: (a: unknown, b: unknown) => compareNumericKeys(numberSortKey(a), numberSortKey(b)),
+  date: (a: unknown, b: unknown) => compareNumericKeys(dateSortKey(a), dateSortKey(b)),
+}
+
+/** Null, undefined and the empty string: the values every built-in sort puts first. */
+function isBlankSortValue(value: unknown): boolean {
+  return value == null || value === ''
+}
+
+/**
+ * Sort key for the `number` comparator. Blanks and anything that does not
+ * coerce to a number ('n/a', a placeholder) become -Infinity, so they sort
+ * together ahead of every number instead of producing NaN. A NaN key made the
+ * comparator inconsistent - NaN compared equal to everything while the numbers
+ * around it did not - and `Array.prototype.sort` then returned a visibly
+ * unsorted column (#104).
+ */
+function numberSortKey(value: unknown): number {
+  if (isBlankSortValue(value)) return -Infinity
+  const n = Number(value)
+  return Number.isNaN(n) ? -Infinity : n
+}
+
+/** Sort key for the `date` comparator; blanks and invalid dates sort first. */
+function dateSortKey(value: unknown): number {
+  if (isBlankSortValue(value)) return -Infinity
+  const t = new Date(value as any).getTime()
+  return Number.isNaN(t) ? -Infinity : t
+}
+
+/**
+ * The `auto` comparator: blanks first, then numbers in numeric order, then
+ * everything else as collated text. Ordering by kind before value keeps it
+ * transitive on mixed columns - comparing a number to a string as text
+ * instead would give 2 < 10, 10 < '1a' and '1a' < 2, a cycle.
+ */
+function compareAutoValues(a: unknown, b: unknown): number {
+  const aBlank = isBlankSortValue(a)
+  const bBlank = isBlankSortValue(b)
+  if (aBlank || bBlank) return aBlank === bBlank ? 0 : aBlank ? -1 : 1
+  const aNum = typeof a === 'number'
+  const bNum = typeof b === 'number'
+  if (aNum && bNum) return compareNumericKeys(numberSortKey(a), numberSortKey(b))
+  if (aNum !== bNum) return aNum ? -1 : 1
+  return compareCollatedKeys(String(a), String(b))
 }
 
 /**
@@ -1446,15 +1485,35 @@ export function createSortedRowModel<TData extends RowData>(
       let keys: Array<any> = new Array(n)
       let compare: (a: any, b: any) => number
       let keyOf: (row: Row<TData>) => any
+      let autoMode: 'number' | 'mixed' | 'text' | undefined
 
       if (comparator === sortFns.number) {
-        keyOf = (row) => Number(row.getCellValueByColumnId(columnId) ?? 0)
+        keyOf = (row) => numberSortKey(row.getCellValueByColumnId(columnId))
         for (let i = 0; i < n; i++) keys[i] = keyOf(rows[i]!)
         compare = compareNumericKeys
       } else if (comparator === sortFns.date) {
-        keyOf = (row) => new Date(row.getCellValueByColumnId(columnId) as any).getTime()
+        keyOf = (row) => dateSortKey(row.getCellValueByColumnId(columnId))
         for (let i = 0; i < n; i++) keys[i] = keyOf(rows[i]!)
         compare = compareNumericKeys
+      } else if (comparator === sortFns.auto && (autoMode = autoSortMode(rows, columnId)) === 'number') {
+        // A column with no declared type whose values are all numbers. Sorting
+        // it as text put 10 before 2 (#104).
+        keyOf = (row) => {
+          const value = row.getCellValueByColumnId(columnId)
+          // A text value arriving in a tick changes the mode; only a full sort
+          // can place it.
+          return typeof value === 'number' || isBlankSortValue(value)
+            ? numberSortKey(value)
+            : MISSING_KEY
+        }
+        for (let i = 0; i < n; i++) keys[i] = keyOf(rows[i]!)
+        compare = compareNumericKeys
+      } else if (autoMode === 'mixed') {
+        // Numbers and text in one column. Rare, so no key tricks: the raw
+        // values through the pairwise comparator, which orders by kind first.
+        keyOf = (row) => row.getCellValueByColumnId(columnId)
+        for (let i = 0; i < n; i++) keys[i] = keyOf(rows[i]!)
+        compare = compareAutoValues
       } else if (comparator === sortFns.auto) {
         const strings: string[] = new Array(n)
         // Decide whether ranking is worth attempting BEFORE paying for it.
@@ -1477,7 +1536,7 @@ export function createSortedRowModel<TData extends RowData>(
           const sample = new Set<string>()
           let sampled = 0
           for (let i = 0; i < n; i += stride) {
-            sample.add(String(rows[i]!.getCellValueByColumnId(columnId)))
+            sample.add(autoTextKey(rows[i]!.getCellValueByColumnId(columnId)))
             sampled++
           }
           // Only attempt ranking when the sample suggests real repetition.
@@ -1485,7 +1544,7 @@ export function createSortedRowModel<TData extends RowData>(
         }
 
         for (let i = 0; i < n; i++) {
-          const s = String(rows[i]!.getCellValueByColumnId(columnId))
+          const s = autoTextKey(rows[i]!.getCellValueByColumnId(columnId))
           strings[i] = s
           if (distinct) {
             distinct.add(s)
@@ -1514,11 +1573,19 @@ export function createSortedRowModel<TData extends RowData>(
           compare = compareNumericKeys
           // A replacement whose text is not among the ranked values has no
           // rank; the repair path treats that as "sort everything again".
-          keyOf = (row) => rankOf.get(String(row.getCellValueByColumnId(columnId))) ?? MISSING_KEY
+          keyOf = (row) => {
+            const value = row.getCellValueByColumnId(columnId)
+            // A number arriving in a tick makes the column mixed; resort fully.
+            if (typeof value === 'number') return MISSING_KEY
+            return rankOf.get(autoTextKey(value)) ?? MISSING_KEY
+          }
         } else {
           keys = strings
           compare = compareCollatedKeys
-          keyOf = (row) => String(row.getCellValueByColumnId(columnId))
+          keyOf = (row) => {
+            const value = row.getCellValueByColumnId(columnId)
+            return typeof value === 'number' ? MISSING_KEY : autoTextKey(value)
+          }
         }
       } else {
         keyOf = (row) => row.getCellValueByColumnId(columnId)
@@ -1735,14 +1802,37 @@ export function createSortedRowModel<TData extends RowData>(
 }
 
 /**
- * Numeric key comparison for the built-in `number` and `date` comparators.
- * Subtraction rather than `<`/`>` on purpose: it reproduces the originals
- * exactly, NaN included. An unparseable date or a non-numeric value yields NaN,
- * and the sort spec turns a NaN comparison result into 0 (SortCompare coerces
- * it), which is the behaviour callers already depend on.
+ * Numeric key comparison for the built-in `number`, `date` and numeric
+ * `auto` comparators. Keys are never NaN (blanks and unparseable values map to
+ * -Infinity), but two -Infinity keys subtract to NaN, so equal keys return 0
+ * explicitly: the multi-clause sort reads any non-zero result, NaN included,
+ * as decided and would skip the next clause.
  */
 function compareNumericKeys(a: number, b: number): number {
-  return a - b
+  return a === b ? 0 : a - b
+}
+
+/** Text key for the `auto` comparator: blanks become '' so they collate first. */
+function autoTextKey(value: unknown): string {
+  return isBlankSortValue(value) ? '' : String(value)
+}
+
+/**
+ * How the `auto` comparator should treat a column: 'number' when every
+ * non-blank value is a number, 'mixed' when numbers share it with anything
+ * else, 'text' otherwise. One pass, stopping as soon as the answer is known.
+ */
+function autoSortMode(rows: ReadonlyArray<Row<any>>, columnId: string): 'number' | 'mixed' | 'text' {
+  let numbers = false
+  let other = false
+  for (let i = 0; i < rows.length; i++) {
+    const value = rows[i]!.getCellValueByColumnId(columnId)
+    if (isBlankSortValue(value)) continue
+    if (typeof value === 'number') numbers = true
+    else other = true
+    if (numbers && other) return 'mixed'
+  }
+  return numbers ? 'number' : 'text'
 }
 
 /**
@@ -2126,8 +2216,11 @@ export function createSvGridCore<TFeatures extends TableFeatures, TData extends
           const original = data[index]!
           const kept = previous?.[index] as BaseRowState<TData> | undefined
           if (kept && kept.original === original) {
-            kept[ROW_VALUES] = null
-            kept[ROW_CELLS] = null
+            // Read before writing: a row nobody rendered (a million off-screen
+            // placeholders under a row model) has nothing memoised, and a
+            // store per row was a measurable share of each block landing.
+            if (kept[ROW_VALUES] !== null) kept[ROW_VALUES] = null
+            if (kept[ROW_CELLS] !== null) kept[ROW_CELLS] = null
             cachedBaseRows[index] = kept
             continue
           }

package/src/export-dates.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Dates must come out of an export as the day the grid showed, in every
+ * timezone (#103). Text exports used `toISOString()`, which is UTC, so local
+ * midnight on the 15th came out as the 14th east of UTC. A bare 'YYYY-MM-DD'
+ * was parsed as UTC midnight, so west of UTC it formatted as the day before.
+ *
+ * These pin `process.env.TZ` per case: a suite run on a UTC machine (CI) would
+ * pass the old code without it.
+ */
+import { describe, expect, it } from 'vitest'
+import { parseDateValue } from './cell-formatting'
+import { asDate } from './SvGrid.helpers'
+import {
+  coerceExportDate,
+  formatValueForExport,
+  serializeDelimited,
+  serializeHtml,
+  serializeMarkdown,
+  toLocalIsoString,
+} from './export-format'
+
+async function inZone<T>(tz: string, fn: () => T | Promise<T>): Promise<T> {
+  const prev = process.env.TZ
+  process.env.TZ = tz
+  try {
+    return await fn()
+  } finally {
+    // Assigning undefined would set the string "undefined".
+    if (prev === undefined) delete process.env.TZ
+    else process.env.TZ = prev
+  }
+}
+
+const EAST = 'Europe/Sofia' // UTC+2 in January
+const FAR_EAST = 'Pacific/Auckland' // UTC+13 in January
+const WEST = 'America/New_York' // UTC-5 in January
+
+describe('parseDateValue', () => {
+  it('reads a bare calendar date as local midnight of that day', async () => {
+    for (const tz of [EAST, FAR_EAST, WEST, 'UTC']) {
+      await inZone(tz, () => {
+        const d = parseDateValue('2026-06-27')!
+        expect([d.getFullYear(), d.getMonth(), d.getDate(), d.getHours()], tz).toEqual([2026, 5, 27, 0])
+        // The grid's display path uses the same parser.
+        expect(asDate('2026-06-27')!.getTime(), tz).toBe(d.getTime())
+      })
+    }
+  })
+
+  it('rejects an impossible calendar date instead of rolling it over', () => {
+    expect(parseDateValue('2026-02-30')).toBeNull()
+    expect(parseDateValue('2026-13-01')).toBeNull()
+  })
+
+  it('leaves full timestamps, Dates and epoch numbers alone', () => {
+    expect(parseDateValue('2024-01-15T10:00:00Z')!.toISOString()).toBe('2024-01-15T10:00:00.000Z')
+    const d = new Date(2024, 0, 15)
+    expect(parseDateValue(d)).toBe(d)
+    expect(parseDateValue(0)!.getTime()).toBe(0)
+    expect(parseDateValue(null)).toBeNull()
+    expect(parseDateValue('')).toBeNull()
+    expect(parseDateValue('nope')).toBeNull()
+    expect(parseDateValue(true)).toBeNull()
+  })
+
+  it('coerceExportDate follows it', async () => {
+    await inZone(WEST, () => {
+      expect(coerceExportDate('2024-01-15')!.getDate()).toBe(15)
+    })
+  })
+})
+
+describe('formatted date export west of UTC', () => {
+  it('shows the calendar day of a date-only string', async () => {
+    await inZone(WEST, () => {
+      expect(formatValueForExport('2024-01-15', { type: 'date', locales: 'en-US' })).toBe('01/15/2024')
+    })
+  })
+})
+
+describe('toLocalIsoString', () => {
+  it('writes the local wall clock with its offset', async () => {
+    await inZone(EAST, () => {
+      expect(toLocalIsoString(new Date(2024, 0, 15))).toBe('2024-01-15T00:00:00.000+02:00')
+    })
+    await inZone(WEST, () => {
+      expect(toLocalIsoString(new Date(2024, 0, 15, 9, 5, 7, 42))).toBe('2024-01-15T09:05:07.042-05:00')
+    })
+    await inZone('Asia/Kolkata', () => {
+      expect(toLocalIsoString(new Date(2024, 0, 15))).toBe('2024-01-15T00:00:00.000+05:30')
+    })
+  })
+
+  it('is the same instant as the Date', async () => {
+    await inZone(FAR_EAST, () => {
+      const d = new Date(2024, 0, 15, 3, 4, 5)
+      expect(new Date(toLocalIsoString(d)).getTime()).toBe(d.getTime())
+    })
+  })
+})
+
+describe('text exports keep the local day (#103)', () => {
+  it('CSV, HTML and Markdown write 2024-01-15 east of UTC', async () => {
+    for (const tz of [EAST, FAR_EAST]) {
+      await inZone(tz, async () => {
+        // Build the Date inside the zone: local midnight there.
+        const local = [{ when: 'When' }, { when: new Date(2024, 0, 15) }]
+        expect(await serializeDelimited(local, ['when']), tz).toContain('2024-01-15T00:00:00.000+')
+        expect(await serializeHtml(local, ['when']), tz).toContain('2024-01-15T00:00:00.000+')
+        expect(await serializeMarkdown(local, ['when']), tz).toContain('2024-01-15T00:00:00.000+')
+      })
+    }
+  })
+})

package/src/export-format.ts

@@ -20,6 +20,7 @@ import type { CellFormatConfig } from './core'
 import {
   formatNumericWithConfig,
   getDateFormatter,
+  parseDateValue,
   resolveDatePattern,
 } from './cell-formatting'
 
@@ -39,16 +40,27 @@ export {
 /** Best-effort coercion of a cell value to a Date. Accepts Date, epoch ms
  *  numbers, and parseable date strings. Returns null when it isn't a date. */
 export function coerceExportDate(value: unknown): Date | null {
-  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value
-  if (typeof value === 'number' && Number.isFinite(value)) {
-    const d = new Date(value)
-    return Number.isNaN(d.getTime()) ? null : d
-  }
-  if (typeof value === 'string' && value.trim() !== '') {
-    const d = new Date(value)
-    return Number.isNaN(d.getTime()) ? null : d
-  }
-  return null
+  return parseDateValue(value)
+}
+
+/**
+ * A Date as ISO 8601 in LOCAL time with its offset, e.g.
+ * `2024-01-15T00:00:00.000+02:00`. Text exports used `toISOString()`, which
+ * is UTC: local midnight on the 15th came out as `2024-01-14T22:00:00.000Z`
+ * east of UTC, and anything reading the date part got the wrong day (#103).
+ * Same instant, but the date part is the one the grid showed.
+ */
+export function toLocalIsoString(d: Date): string {
+  const pad = (n: number, w = 2) => String(Math.abs(n)).padStart(w, '0')
+  const offset = -d.getTimezoneOffset()
+  const sign = offset < 0 ? '-' : '+'
+  const year = d.getFullYear()
+  return (
+    (year < 0 ? '-' + pad(year, 6) : pad(year, 4)) +
+    `-${pad(d.getMonth() + 1)}-${pad(d.getDate())}` +
+    `T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}` +
+    `${sign}${pad(Math.floor(Math.abs(offset) / 60))}:${pad(Math.abs(offset) % 60)}`
+  )
 }
 
 /**
@@ -325,7 +337,7 @@ function csvCell(value: unknown, delimiter: string): string {
     value == null
       ? ''
       : value instanceof Date
-        ? value.toISOString()
+        ? toLocalIsoString(value)
         : String(value)
   if (s === '') return s
   if (s.includes(delimiter) || s.includes('"') || s.includes('\n') || s.includes('\r')) {
@@ -373,7 +385,7 @@ const HTML_ESCAPE: Record<string, string> = {
 }
 function htmlCell(value: unknown): string {
   const s =
-    value == null ? '' : value instanceof Date ? value.toISOString() : String(value)
+    value == null ? '' : value instanceof Date ? toLocalIsoString(value) : String(value)
   return s.replace(/[&<>"']/g, (c) => HTML_ESCAPE[c]!)
 }
 
@@ -472,7 +484,7 @@ export async function serializeJson(
 
 /** Escape a Markdown table cell: pipes and newlines would break the row. */
 function mdCell(value: unknown): string {
-  const s = value == null ? '' : value instanceof Date ? value.toISOString() : String(value)
+  const s = value == null ? '' : value instanceof Date ? toLocalIsoString(value) : String(value)
   return s.replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>')
 }
 
@@ -520,7 +532,7 @@ const XML_ESCAPE: Record<string, string> = {
   "'": '&apos;',
 }
 function xmlText(value: unknown): string {
-  const s = value == null ? '' : value instanceof Date ? value.toISOString() : String(value)
+  const s = value == null ? '' : value instanceof Date ? toLocalIsoString(value) : String(value)
   // Stripping control characters is the point: XML 1.0 forbids them outright,
   // so a stray \x00 from a data source would produce an unopenable file.
   // eslint-disable-next-line no-control-regex

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

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

package/src/headless.ts

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