@svgrid/grid 3.0.6 → 3.0.7

package/dist/core.js

@@ -130,14 +130,54 @@ export function tableFeatures(features) {
  * text; set a column's type or supply your own comparator to override.
  */
 export const sortFns = {
-    auto: (a, b) => String(a).localeCompare(String(b)),
-    number: (a, b) => Number(a ?? 0) - Number(b ?? 0),
-    date: (a, b) => {
-        const aa = new Date(a).getTime();
-        const bb = new Date(b).getTime();
-        return aa - bb;
-    },
+    auto: (a, b) => compareAutoValues(a, b),
+    number: (a, b) => compareNumericKeys(numberSortKey(a), numberSortKey(b)),
+    date: (a, b) => compareNumericKeys(dateSortKey(a), dateSortKey(b)),
 };
+/** Null, undefined and the empty string: the values every built-in sort puts first. */
+function isBlankSortValue(value) {
+    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) {
+    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) {
+    if (isBlankSortValue(value))
+        return -Infinity;
+    const t = new Date(value).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, b) {
+    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));
+}
 /**
  * Built-in match functions, named by {@link ColumnFilter}'s `fn`.
  * `includesString` is case-insensitive substring; `equals` is strict identity.
@@ -736,18 +776,42 @@ export function createSortedRowModel(localSortFns = sortFns) {
             let keys = new Array(n);
             let compare;
             let keyOf;
+            let autoMode;
             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)).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 = new Array(n);
                 // Decide whether ranking is worth attempting BEFORE paying for it.
@@ -770,7 +834,7 @@ export function createSortedRowModel(localSortFns = sortFns) {
                     const sample = new Set();
                     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.
@@ -778,7 +842,7 @@ export function createSortedRowModel(localSortFns = sortFns) {
                         distinct = new Set();
                 }
                 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);
@@ -809,12 +873,21 @@ export function createSortedRowModel(localSortFns = sortFns) {
                     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 {
@@ -1037,14 +1110,39 @@ export function createSortedRowModel(localSortFns = sortFns) {
     };
 }
 /**
- * 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, b) {
-    return a - b;
+    return a === b ? 0 : a - b;
+}
+/** Text key for the `auto` comparator: blanks become '' so they collate first. */
+function autoTextKey(value) {
+    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, columnId) {
+    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';
 }
 /**
  * Text key comparison for the built-in `auto` comparator.

package/dist/export-format.d.ts

@@ -21,6 +21,14 @@ export { computeColumnStat, contrastText, formatsNeedingStats, resolveCellFormat
 /** 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 declare function coerceExportDate(value: unknown): Date | null;
+/**
+ * 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 declare function toLocalIsoString(d: Date): string;
 /**
  * Format a raw cell value to its on-screen display string using the column's
  * `format` config. Mirrors the grid's own numeric / currency / percent / date

package/dist/export-format.js

@@ -1,4 +1,4 @@
-import { formatNumericWithConfig, getDateFormatter, resolveDatePattern, } from './cell-formatting.js';
+import { formatNumericWithConfig, getDateFormatter, parseDateValue, resolveDatePattern, } from './cell-formatting.js';
 // Re-export the pure conditional-formatting engine here too, so the
 // Svelte-free `@svgrid/grid/format` subpath carries it for @svgrid/enterprise's
 // export code (which must not pull in SvGrid.svelte).
@@ -6,17 +6,24 @@ export { computeColumnStat, contrastText, formatsNeedingStats, resolveCellFormat
 /** 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) {
-    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) {
+    const pad = (n, 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)}`);
 }
 /**
  * Format a raw cell value to its on-screen display string using the column's
@@ -190,7 +197,7 @@ function csvCell(value, delimiter) {
     const s = value == null
         ? ''
         : value instanceof Date
-            ? value.toISOString()
+            ? toLocalIsoString(value)
             : String(value);
     if (s === '')
         return s;
@@ -231,7 +238,7 @@ const HTML_ESCAPE = {
     "'": '&#39;',
 };
 function htmlCell(value) {
-    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, (c) => HTML_ESCAPE[c]);
 }
 /**
@@ -311,7 +318,7 @@ export async function serializeJson(rows, fields, opts = {}) {
 }
 /** Escape a Markdown table cell: pipes and newlines would break the row. */
 function mdCell(value) {
-    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>');
 }
 /**
@@ -351,7 +358,7 @@ const XML_ESCAPE = {
     "'": '&apos;',
 };
 function xmlText(value) {
-    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/dist/virtualization/column-virtualizer.d.ts

@@ -10,6 +10,7 @@ export declare function createColumnVirtualizer(input: {
     setViewportWidth(viewportWidth: number): void;
     setHorizontalOffset(scrollOffset: number): void;
     setOptions(next: Partial<import("./types.js").VirtualizerOptions>): void;
+    measure(): void;
     setScrollOffset(scrollOffset: number): void;
     setViewportHeight(viewportHeight: number): void;
     scrollToIndex(index: number): void;

package/dist/virtualization/svelte-virtualizer.svelte.d.ts

@@ -2,6 +2,7 @@ import type { VirtualizerOptions } from './types.js';
 export declare function createSvelteVirtualizer(options: VirtualizerOptions): {
     readonly version: number;
     setOptions: (next: Partial<VirtualizerOptions>) => void;
+    measure: () => void;
     setScrollOffset: (scrollOffset: number) => void;
     setViewportHeight: (viewportHeight: number) => void;
     scrollToIndex: (index: number) => void;

package/dist/virtualization/svelte-virtualizer.svelte.js

@@ -10,6 +10,7 @@ export function createSvelteVirtualizer(options) {
             return version;
         },
         setOptions: virtualizer.setOptions,
+        measure: virtualizer.measure,
         setScrollOffset: virtualizer.setScrollOffset,
         setViewportHeight: virtualizer.setViewportHeight,
         scrollToIndex: virtualizer.scrollToIndex,

package/dist/virtualization/virtualizer.d.ts

@@ -16,6 +16,9 @@ type VirtualizerListener = () => void;
 export declare function buildPreMeasureItems(count: number, estimateSize: number, viewportHeight: number, overscan: number): Array<VirtualItem>;
 export declare function createVirtualizer(initial: VirtualizerOptions): {
     setOptions(next: Partial<VirtualizerOptions>): void;
+    /** Drop the cached offsets and re-read every size from `estimateSize`.
+     *  Call after the sizes a stable size function reports have changed. */
+    measure(): void;
     setScrollOffset(scrollOffset: number): void;
     setViewportHeight(viewportHeight: number): void;
     scrollToIndex(index: number): void;

package/dist/virtualization/virtualizer.js

@@ -210,9 +210,22 @@ export function createVirtualizer(initial) {
     return {
         setOptions(next) {
             const merged = { ...options, ...next };
-            if (sameOptions(options, merged))
+            // Passing a size function means "sizes may have changed", even when it is
+            // the same reference: the documented variable-height pattern is a stable
+            // function reading a mutable map, and keying the cache on identity alone
+            // left the offsets and total stale after a row grew (#102).
+            const remeasure = typeof next.estimateSize === 'function';
+            if (!remeasure && sameOptions(options, merged))
                 return;
             options = merged;
+            if (remeasure)
+                offsetCache = null;
+            recalc();
+        },
+        /** Drop the cached offsets and re-read every size from `estimateSize`.
+         *  Call after the sizes a stable size function reports have changed. */
+        measure() {
+            offsetCache = null;
             recalc();
         },
         setScrollOffset(scrollOffset) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svgrid/grid",
-  "version": "3.0.6",
+  "version": "3.0.7",
   "description": "Svelte 5-native data grid and data table. Headless-first engine with virtual scrolling for 100k+ rows, Excel-style filtering, inline editing, grouping, tree data, pivot, and server-side data. Drop-in <SvGrid> component. TypeScript, SSR-ready.",
   "author": "jQWidgets <boikom@jqwidgets.com>",
   "license": "MIT",

package/src/SvGrid.controller.svelte.ts

@@ -845,7 +845,18 @@ export function createSvGridController<
   // `data` is optional on the type (a `rowModel` may supply the rows
   // instead), so every read falls back to empty rather than to undefined.
   const EMPTY_DATA: ReadonlyArray<TData> = [];
-  let internalData = $state.raw<ReadonlyArray<TData>>(props.data ?? EMPTY_DATA);
+  // Seeded as a copy, for the same reason the sync effect below makes one: the
+  // row model tells data apart by array identity, so the grid has to own an
+  // array the consumer cannot grow behind its back.
+  let internalData = $state.raw<ReadonlyArray<TData>>(
+    props.data?.length ? props.data.slice() : EMPTY_DATA,
+  );
+  // What the last sync saw, so the effect can tell a replacement (drop the
+  // cell edits) from a push or splice (keep them) and skip a no-op run.
+  // svelte-ignore state_referenced_locally
+  let lastData: ReadonlyArray<TData> = props.data ?? EMPTY_DATA;
+  // svelte-ignore state_referenced_locally
+  let lastDataLength = props.data?.length ?? 0;
   // Resolve `cellDataType` / `inferColumnTypes` into concrete editorType +
   // format defaults once, up front, so every downstream reader sees a normal
   // column. Explicit fields on the ColumnDef always win.
@@ -893,12 +904,27 @@ export function createSvGridController<
   }
 
   $effect(() => {
+    const next = props.data ?? EMPTY_DATA;
+    // Reading `length` is what subscribes this effect to a `$state` array's own
+    // length signal, so `rows.push(...)` and `rows.splice(...)` re-run it.
+    // Without this read nothing in the grid tracks the row count at all:
+    // `getRowModel` reads `.length` only inside its cache miss, and the miss is
+    // keyed on the array reference, which a mutation does not change.
+    const length = next.length;
+    const replaced = next !== lastData;
+    if (!replaced && length === lastDataLength) return;
+    lastData = next;
+    lastDataLength = length;
+    // A fresh array object, because `getRowModel` memoises on identity. The
+    // elements are the same objects, so a row that did not move keeps its row
+    // object and a field write still reaches its cell through the proxy.
+    internalData = length === 0 ? EMPTY_DATA : next.slice();
     // When the consumer replaces `data` (e.g. a "Reset" button), drop any
     // accumulated cell-edit overrides - otherwise `getCellDisplayValue`
     // would keep returning the old edited values from `editedCellValues`
-    // even though the underlying data has been replaced.
-    internalData = props.data ?? EMPTY_DATA;
-    editedCellValues = {};
+    // even though the underlying data has been replaced. Growing or shrinking
+    // the array is not a reset, so it keeps them.
+    if (replaced) editedCellValues = {};
   });
   $effect(() => {
     internalColumns = resolveCols(props.columns);

package/src/SvGrid.css

@@ -1387,9 +1387,6 @@ select.sv-grid-fr-editor {
 .sv-grid-cell-active,
 .sv-grid-cell-editing {
   position: relative;
-  /* High enough to sit above pinned-column stacking contexts (z=4) so the
-     list/chips popover overlays adjacent cells instead of being clipped. */
-  z-index: 20;
   /* `box-shadow: inset` is bound to the cell's own box, so the ring
      clips cleanly with the cell when it's partially scrolled out of
      view (and shows up consistently at the right edge of a virtualized
@@ -1399,10 +1396,24 @@ select.sv-grid-fr-editor {
      inconsistent at scroll boundaries. */
   box-shadow: inset 0 0 0 2px var(--sg-accent, #0b63f3);
   outline: none;
-  /* Let list/chips popouts extend past the cell box (default cells have
-     overflow: hidden so the chips picker would otherwise be clipped). */
+}
+/* Only the EDITING cell escapes its own box and outranks the pinned-column
+   stacking contexts (z=4), so its list/chips popout overlays the neighbours
+   instead of being clipped. The merely-ACTIVE cell used to get the same
+   treatment, and on a grid scrolled sideways that made it paint straight over
+   the sticky selection / row-number column: the checkbox disappeared and the
+   cell's text - unclipped, because overflow was visible - spilled across it.
+   A grid seeds its active cell at (0,0), so this hit the FIRST row of any
+   horizontally scrolled grid with `showRowSelection`, untouched by the user. */
+.sv-grid-cell-editing {
+  z-index: 20;
   overflow: visible;
 }
+/* Above ordinary cells so the ring is not overdrawn by a neighbour, below the
+   sticky columns (z=4) so those keep covering it as they should. */
+.sv-grid-cell-active:not(.sv-grid-cell-editing) {
+  z-index: 3;
+}
 /* The active cell a grid mounts with is seeded at (0,0), not chosen: no
    ring until a click, an arrow key or the api activates a cell (the same
    gate the fill handle has always had). Once activated it stays through a

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/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 {