@svgrid/grid 2.6.20 → 2.6.22

package/dist/core.js

@@ -1,31 +1,70 @@
 import { resolveColumnId } from './column-id.js';
 /** Apply a group aggregator over a bucket's leaf rows for one column. */
 export function applyGroupAggregate(agg, columnId, rows) {
-    const raw = rows.map((r) => r.getCellValueByColumnId(columnId));
+    // One pass, no intermediate arrays.
+    //
+    // This used to build a `raw` array, then a coerced one, then a filtered one -
+    // three allocations per aggregated column PER GROUP - before reducing. On a
+    // 100k-row grid grouped two levels deep, aggregation was about two thirds of
+    // the total grouping cost (213ms with three aggregators against 81ms with
+    // none), and each additional aggregated column added roughly 80ms.
+    //
+    // `count` first: it never needs to look at a value at all.
+    if (agg === 'count')
+        return rows.length;
+    if (agg === 'first') {
+        return rows.length ? rows[0].getCellValueByColumnId(columnId) : undefined;
+    }
+    if (agg === 'countDistinct') {
+        const seen = new Set();
+        for (const row of rows)
+            seen.add(String(row.getCellValueByColumnId(columnId) ?? ''));
+        return seen.size;
+    }
     if (typeof agg === 'function') {
-        const nums = raw.map((v) => Number(v)).filter((n) => Number.isFinite(n));
+        // Custom aggregators keep their contract: the finite numbers, then the
+        // original row objects. Note `Number(null)` is 0 and therefore finite, so
+        // nulls DO reach the callback as zeros - long-standing behaviour.
+        const nums = [];
+        for (const row of rows) {
+            const n = Number(row.getCellValueByColumnId(columnId));
+            if (Number.isFinite(n))
+                nums.push(n);
+        }
         return agg(nums, rows.map((r) => r.original));
     }
-    if (agg === 'count')
-        return rows.length;
-    if (agg === 'countDistinct')
-        return new Set(raw.map((v) => String(v ?? ''))).size;
-    if (agg === 'first')
-        return raw[0];
-    const nums = raw.map((v) => Number(v)).filter((n) => Number.isFinite(n));
-    if (!nums.length)
+    // sum / avg / min / max / extent share one accumulation pass.
+    let count = 0;
+    let sum = 0;
+    let min = Infinity;
+    let max = -Infinity;
+    for (const row of rows) {
+        const n = Number(row.getCellValueByColumnId(columnId));
+        if (!Number.isFinite(n))
+            continue;
+        count++;
+        // Left-to-right, matching the previous `reduce`, so float rounding is
+        // bit-identical rather than merely close.
+        sum += n;
+        // Math.min/max on scalars rather than `<`, which differs on -0, and rather
+        // than the old `Math.min(...nums)` - spreading a whole group throws
+        // RangeError once the bucket is big enough to exhaust the argument stack.
+        min = Math.min(min, n);
+        max = Math.max(max, n);
+    }
+    if (!count)
         return undefined;
     switch (agg) {
         case 'sum':
-            return nums.reduce((a, b) => a + b, 0);
+            return sum;
         case 'avg':
-            return nums.reduce((a, b) => a + b, 0) / nums.length;
+            return sum / count;
         case 'min':
-            return Math.min(...nums);
+            return min;
         case 'max':
-            return Math.max(...nums);
+            return max;
         case 'extent':
-            return `${Math.min(...nums)} – ${Math.max(...nums)}`;
+            return `${min} – ${max}`;
         default:
             return undefined;
     }
@@ -47,15 +86,49 @@ function createStore(initial) {
         },
     };
 }
+/**
+ * Click-to-sort. Injected by the `sortable` shortcut.
+ *
+ * This and the five features below are opaque markers: pass the ones you want
+ * to {@link tableFeatures} and the grid wires up the matching row model. With
+ * `<SvGrid>` you rarely name them - the boolean shortcuts (`sortable`,
+ * `filterable`, `pageable`, `groupable`) inject them for you. Reach for them
+ * directly when driving the headless core, or when you want a feature on
+ * without its UI.
+ *
+ * The names match TanStack Table v9, so a features object written for it works
+ * here unchanged.
+ */
 export const rowSortingFeature = { key: 'rowSortingFeature' };
+/** Per-column filtering. Injected by the `filterable` shortcut. */
 export const columnFilteringFeature = { key: 'columnFilteringFeature' };
+/** Paging of the row model. Injected by the `pageable` shortcut. */
 export const rowPaginationFeature = { key: 'rowPaginationFeature' };
+/** Row grouping with aggregation. Injected by the `groupable` shortcut. */
 export const columnGroupingFeature = { key: 'columnGroupingFeature' };
+/** Row selection state (the checkbox column reads it). */
 export const rowSelectionFeature = { key: 'rowSelectionFeature' };
+/** Expand / collapse, for tree rows and master-detail. */
 export const rowExpandingFeature = { key: 'rowExpandingFeature' };
+/**
+ * Declare which features a grid uses. Identity at runtime - its whole job is to
+ * capture the exact set in the type, so `ColumnDef<typeof features, Row>` knows
+ * what is registered and anything you did not register is tree-shaken out.
+ *
+ * ```ts
+ * const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+ * ```
+ *
+ * Same call signature as TanStack Table v9, so a features object written for it
+ * transfers unchanged.
+ */
 export function tableFeatures(features) {
     return features;
 }
+/**
+ * Built-in comparators, chosen per column by its data type. `auto` compares as
+ * 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),
@@ -65,30 +138,174 @@ export const sortFns = {
         return aa - bb;
     },
 };
+/**
+ * Built-in match functions, named by {@link ColumnFilter}'s `fn`.
+ * `includesString` is case-insensitive substring; `equals` is strict identity.
+ */
 export const filterFns = {
     includesString: (value, query) => String(value).toLowerCase().includes(query.toLowerCase()),
     equals: (value, query) => value === query,
 };
+/**
+ * Keys for a base row's private fields.
+ *
+ * Symbols, not string keys, and that is load-bearing. A row's shared methods
+ * need a pointer back to the table, but `_ctx` as a normal property made every
+ * row serialise the entire grid: `JSON.stringify(oneRow)` grew with the dataset
+ * (981 chars at 3 rows, 67,719 at 3,000) because `options.data` is reachable
+ * through it, so stringifying a row model was quadratic. Rows used to serialise
+ * to a small constant and must again.
+ *
+ * A symbol key is invisible to `JSON.stringify`, `Object.keys` and `for...in`,
+ * yet IS copied by object spread - which matters because several row models
+ * legitimately do `{ ...row, depth }` and the clone needs these to work.
+ * Non-enumerable string keys would have hidden them from JSON but also from the
+ * spread, silently breaking every cloned row.
+ */
+const ROW_CTX = Symbol('svgrid.row.ctx');
+const ROW_VALUES = Symbol('svgrid.row.values');
+const ROW_CELLS = Symbol('svgrid.row.cells');
+/**
+ * The methods every base row carries, defined ONCE and assigned by reference.
+ *
+ * Rows used to be built as object literals whose methods were closures, which
+ * meant a 100k-row grid allocated 700k closures and a closure scope per row
+ * before painting anything. Measured at 100k x 9: 13.8 ms and 56.5 MB to build,
+ * against 2.0 ms and 14.5 MB for this shape - the single largest cost in
+ * mounting a large grid.
+ *
+ * They read their row through `this` rather than a captured variable, which is
+ * why they can be shared. Note they are assigned as OWN properties rather than
+ * put on a prototype: `Row` is public, several row models legitimately do
+ * `{ ...row, depth }`, and a spread copies own properties but not a prototype.
+ * A class here would silently strip every method off a cloned row.
+ */
+const BASE_ROW_METHODS = {
+    getCanExpand() {
+        return false;
+    },
+    getIsExpanded() {
+        return Boolean((this[ROW_CTX].store.state.expanded ?? {})[this.id]);
+    },
+    toggleExpanded() {
+        const id = this.id;
+        this[ROW_CTX].grid.setExpanded((prev) => ({ ...prev, [id]: !prev[id] }));
+    },
+    getIsSelected() {
+        return Boolean((this[ROW_CTX].store.state.rowSelection ?? {})[this.id]);
+    },
+    toggleSelected() {
+        const id = this.id;
+        this[ROW_CTX].grid.setRowSelection((prev) => ({ ...prev, [id]: !prev[id] }));
+    },
+    getAllCells() {
+        return this[ROW_CELLS] ?? buildBaseRowCells(this);
+    },
+    getCellValueByColumnId(columnId) {
+        const idx = this[ROW_CTX].columnIndexById.get(columnId);
+        if (idx === undefined)
+            return undefined;
+        if (!this[ROW_VALUES])
+            this[ROW_VALUES] = baseRowValues(this);
+        return this[ROW_VALUES][idx];
+    },
+};
+/**
+ * Materialise one row's `Cell[]`, memoised on the row.
+ *
+ * A free function taking the row rather than a method using `this`, because the
+ * cell closures need a stable reference to it and aliasing `this` inside a
+ * method is exactly the pattern that produces `self`/`that` bugs.
+ */
+function buildBaseRowCells(row) {
+    const { columns, columnCount, grid } = row[ROW_CTX];
+    const built = new Array(columnCount);
+    for (let i = 0; i < columnCount; i++) {
+        const column = columns[i];
+        const colIndex = i;
+        const cell = {
+            id: `${row.id}_${column.id}`,
+            row,
+            column,
+            getValue: () => {
+                if (!row[ROW_VALUES])
+                    row[ROW_VALUES] = baseRowValues(row);
+                return row[ROW_VALUES][colIndex];
+            },
+            getContext: () => ({
+                cell,
+                row,
+                column,
+                table: grid,
+                getValue: () => cell.getValue(),
+            }),
+        };
+        built[i] = cell;
+    }
+    row[ROW_CELLS] = built;
+    return built;
+}
+/**
+ * Resolve every column's value for one row. Kept lazy: a 100k-row grid showing
+ * twenty rows must not materialise 900k values to paint.
+ */
+function baseRowValues(row) {
+    const { columns, columnCount } = row[ROW_CTX];
+    const original = row.original;
+    const values = new Array(columnCount);
+    for (let i = 0; i < columnCount; i++) {
+        const def = columns[i].columnDef;
+        if (def.fieldFn)
+            values[i] = def.fieldFn(original);
+        else if (def.field)
+            values[i] = original[def.field];
+        else
+            values[i] = undefined;
+    }
+    return values;
+}
+/**
+ * The identity stage that starts every pipeline. Always required, even when no
+ * other stage is: it is what turns your data into rows.
+ */
 export function createCoreRowModel() {
     return ({ rows }) => rows;
 }
+/**
+ * Drops rows that fail the active {@link ColumnFiltersState}. Pairs with
+ * `columnFilteringFeature`; without it there are no filters to apply.
+ */
 export function createFilteredRowModel() {
     return ({ table, rows }) => {
         const filters = table.getState().columnFilters ?? [];
         if (!filters.length)
             return rows;
+        // Resolve each filter's match function once, outside the row loop.
+        const compiled = filters.map((filter) => ({
+            id: filter.id,
+            value: filter.value,
+            fn: filter.fn ? filterFns[filter.fn] : filterFns.includesString,
+        }));
         return rows.filter((row) => {
-            return filters.every((filter) => {
-                const cellValue = row
-                    .getAllCells()
-                    .find((cell) => cell.column.id === filter.id)
-                    ?.getValue();
-                const filterFn = filter.fn ? filterFns[filter.fn] : filterFns.includesString;
-                return filterFn(cellValue, filter.value);
-            });
+            for (let i = 0; i < compiled.length; i++) {
+                const filter = compiled[i];
+                // `getCellValueByColumnId` rather than `getAllCells().find(...)`.
+                // Both read the same lazily-built `cachedValues` array, but the latter
+                // also builds and caches the row's whole `Cell[]` - one object per
+                // column - purely to reach one field. On a 100k-row grid that is
+                // 100,000 cell arrays the filter never looks at again, and it defeats
+                // the laziness the row factory exists to provide.
+                if (!filter.fn(row.getCellValueByColumnId(filter.id), filter.value))
+                    return false;
+            }
+            return true;
         });
     };
 }
+/**
+ * Narrows the rows to the current page. Put it LAST: anything after it would
+ * only ever see one page of data.
+ */
 export function createPaginatedRowModel() {
     return ({ table, rows }) => {
         const pagination = table.getState().pagination ?? { pageIndex: 0, pageSize: rows.length || 10 };
@@ -96,6 +313,10 @@ export function createPaginatedRowModel() {
         return rows.slice(start, start + pagination.pageSize);
     };
 }
+/**
+ * Buckets rows by the active {@link GroupingState} and inserts a group row
+ * ahead of each bucket, carrying that bucket's aggregates.
+ */
 export function createGroupedRowModel() {
     return ({ table, rows }) => {
         const grouping = table.getState().grouping ?? [];
@@ -106,7 +327,10 @@ export function createGroupedRowModel() {
         // group row is built that stands in for its children - a non-group column
         // resolves to the value shared by every leaf row, or to undefined when the
         // leaves disagree.
-        function buildGroups(input, levelIndex, depth, idPrefix) {
+        function buildGroups(input, levelIndex, depth, idPrefix, 
+        /** Grouping columns already fixed by an ancestor bucket, and their raw
+         *  values - `undefined` where that bucket mixed several. */
+        fixedValues) {
             if (levelIndex >= grouping.length) {
                 // Leaves: actual data rows, with their nesting depth recorded.
                 return input.map((row) => ({ ...row, depth }));
@@ -118,22 +342,51 @@ export function createGroupedRowModel() {
             for (const row of input) {
                 const value = row.getCellValueByColumnId(groupKey);
                 const key = String(value ?? '');
-                const list = buckets.get(key) ?? [];
-                list.push(row);
-                buckets.set(key, list);
+                const bucket = buckets.get(key);
+                if (bucket) {
+                    bucket.rows.push(row);
+                    if (!bucket.mixed && bucket.raw !== value)
+                        bucket.mixed = true;
+                }
+                else {
+                    buckets.set(key, { rows: [row], raw: value, mixed: false });
+                }
             }
             const groupRows = [];
             let index = 0;
-            buckets.forEach((children, key) => {
+            buckets.forEach((bucket, key) => {
+                const children = bucket.rows;
                 const id = `${idPrefix}_${groupKey}_${key}`;
-                const subRows = buildGroups(children, levelIndex + 1, depth + 1, id);
+                // Record this column as fixed for deeper levels ONLY when the bucket is
+                // homogeneous. If all rows here share a raw value, so does every subset
+                // of them, which is what makes the shortcut sound.
+                //
+                // A MIXED bucket must not be recorded at all - not even as "undefined".
+                // `null`, `undefined` and `''` share a bucket key, so a mixed bucket can
+                // still split into homogeneous children one level down, and those
+                // children have a real shared value that a scan would find. Marking the
+                // column resolved here would hand them the parent's disagreement.
+                const nextFixed = bucket.mixed ? fixedValues : new Map(fixedValues).set(groupKey, bucket.raw);
+                const subRows = buildGroups(children, levelIndex + 1, depth + 1, id, nextFixed);
                 const isDeepest = levelIndex + 1 >= grouping.length;
                 const leafCount = isDeepest
                     ? subRows.length
                     : subRows.reduce((sum, sub) => sum + (sub.leafCount ?? 0), 0);
+                // Every grouping column ABOVE this level is already resolved: bucketing
+                // by it is what made it constant, so scanning the children to rediscover
+                // it is pure waste. Only the current level's key short-circuited before,
+                // so a second-level group walked all of its children to re-derive the
+                // first level's value - about 100,000 reads on the 100k x 9 two-level
+                // case, for an answer already in hand.
+                //
+                // The current level still returns the stringified bucket key rather than
+                // the raw value, because that is what it has always returned and the
+                // group row's display depends on it.
                 const resolveColumnValue = (columnId) => {
                     if (columnId === groupKey)
                         return key;
+                    if (fixedValues.has(columnId))
+                        return fixedValues.get(columnId);
                     let resolved;
                     let hasResolved = false;
                     for (const child of children) {
@@ -190,7 +443,7 @@ export function createGroupedRowModel() {
             });
             return groupRows;
         }
-        return buildGroups(rows, 0, 0, 'group');
+        return buildGroups(rows, 0, 0, 'group', new Map());
     };
 }
 /**
@@ -282,6 +535,10 @@ export function flattenTreeData(data, options) {
     walk(data, null);
     return out;
 }
+/**
+ * Hides the descendants of collapsed rows. Needed for grouping, tree data and
+ * master-detail alike - all three are the same expand/collapse mechanism.
+ */
 export function createExpandedRowModel() {
     return ({ table, rows }) => {
         const expanded = table.getState().expanded ?? {};
@@ -298,31 +555,220 @@ export function createExpandedRowModel() {
         return flattened;
     };
 }
+/**
+ * Orders rows by the active {@link SortingState}. Pass your own comparators to
+ * override the built-in {@link sortFns} - useful for locale-aware or
+ * domain-specific ordering.
+ */
 export function createSortedRowModel(localSortFns = sortFns) {
-    return ({ table, rows }) => {
+    return function sortedRowModelStage({ table, rows }) {
         const sorting = table.getState().sorting ?? [];
         if (!sorting.length)
             return rows;
-        const sorted = [...rows].sort((a, b) => {
-            for (const clause of sorting) {
-                const column = table.getAllColumns().find((col) => col.id === clause.id);
-                if (!column)
-                    continue;
-                const editorType = column.columnDef.editorType;
-                const comparator = editorType === 'number'
-                    ? localSortFns.number
-                    : editorType === 'date' || editorType === 'datetime'
-                        ? localSortFns.date
-                        : localSortFns.auto;
-                const result = comparator(a.getCellValueByColumnId(column.id), b.getCellValueByColumnId(column.id));
-                if (result !== 0)
-                    return clause.desc ? -result : result;
+        // Resolve every clause ONCE, before sorting.
+        //
+        // This used to live inside the comparator, so `getAllColumns().find(...)`
+        // ran per comparison per clause: a single-clause sort of 100k rows made
+        // 1,528,947 array scans, and a three-clause sort made 3,933,751 (measured;
+        // `pnpm bench --case=sort-1col`). The comparator is called O(n log n)
+        // times, so anything inside it that is not O(1) sets the cost of the sort.
+        const allColumns = table.getAllColumns();
+        const clauses = [];
+        for (const clause of sorting) {
+            const column = allColumns.find((col) => col.id === clause.id);
+            if (!column)
+                continue;
+            const editorType = column.columnDef.editorType;
+            const comparator = editorType === 'number'
+                ? localSortFns.number
+                : editorType === 'date' || editorType === 'datetime'
+                    ? localSortFns.date
+                    : localSortFns.auto;
+            // Precompute one sort key per row, so the comparator reads an array slot
+            // instead of walking the row's column index on every comparison. For the
+            // three built-in comparators the key is also cheaper to compare than the
+            // raw value: a timestamp rather than two `new Date()` allocations, a
+            // number rather than two `Number()` coercions, a collator rather than a
+            // fresh one per `localeCompare` call.
+            //
+            // The identity checks against `sortFns` matter: `localSortFns` is a
+            // public parameter, so a caller can substitute their own comparators.
+            // When they have, we fall through to calling their function with the raw
+            // values - still hoisted, just not specialised.
+            const columnId = column.id;
+            const n = rows.length;
+            let keys = new Array(n);
+            let compare;
+            if (comparator === sortFns.number) {
+                for (let i = 0; i < n; i++)
+                    keys[i] = Number(rows[i].getCellValueByColumnId(columnId) ?? 0);
+                compare = compareNumericKeys;
             }
-            return 0;
-        });
+            else if (comparator === sortFns.date) {
+                for (let i = 0; i < n; i++) {
+                    keys[i] = new Date(rows[i].getCellValueByColumnId(columnId)).getTime();
+                }
+                compare = compareNumericKeys;
+            }
+            else if (comparator === sortFns.auto) {
+                const strings = new Array(n);
+                // Decide whether ranking is worth attempting BEFORE paying for it.
+                //
+                // Building the distinct set and then discarding it costs about 9 ms on
+                // a 100k-row column where nearly every value is unique, and ranking
+                // saves about 19 ms where they repeat - so guessing wrong in either
+                // direction is measurable. A small stride sample answers it for well
+                // under a millisecond.
+                //
+                // Strided rather than the first N rows: data arrives sorted or
+                // clustered often enough that a prefix is a bad estimator of the whole
+                // column. Reading every k-th row is no more expensive and does not care
+                // how the rows are arranged.
+                const rankLimit = n >> 1;
+                let distinct = null;
+                if (n > 0) {
+                    const sampleTarget = Math.min(n, 256);
+                    const stride = Math.max(1, Math.floor(n / sampleTarget));
+                    const sample = new Set();
+                    let sampled = 0;
+                    for (let i = 0; i < n; i += stride) {
+                        sample.add(String(rows[i].getCellValueByColumnId(columnId)));
+                        sampled++;
+                    }
+                    // Only attempt ranking when the sample suggests real repetition.
+                    if (sample.size * 2 <= sampled)
+                        distinct = new Set();
+                }
+                for (let i = 0; i < n; i++) {
+                    const s = String(rows[i].getCellValueByColumnId(columnId));
+                    strings[i] = s;
+                    if (distinct) {
+                        distinct.add(s);
+                        if (distinct.size > rankLimit)
+                            distinct = null;
+                    }
+                }
+                // Collation is by far the most expensive comparison we do - a CPU
+                // profile of a 100k text sort put 65% of the whole operation inside the
+                // collator. But a column's DISTINCT values are usually far fewer than
+                // its rows (statuses, regions, categories, owners), so rank the
+                // distinct values once and sort by rank afterwards. That turns
+                // O(n log n) collator calls into O(u log u), where u is the number of
+                // distinct values, and the resulting order is identical because rank is
+                // a monotone relabelling of the collated order - equal strings share a
+                // rank, so ties still fall through to the stable sort exactly as before.
+                //
+                // Guarded on the uniqueness ratio: when nearly every value is distinct
+                // the ranking pass cannot save any collator calls and would just add an
+                // O(n) Map build, so that case keeps comparing directly.
+                if (distinct) {
+                    const ordered = Array.from(distinct).sort(compareCollatedKeys);
+                    const rankOf = new Map();
+                    for (let i = 0; i < ordered.length; i++)
+                        rankOf.set(ordered[i], i);
+                    for (let i = 0; i < n; i++)
+                        keys[i] = rankOf.get(strings[i]);
+                    compare = compareNumericKeys;
+                }
+                else {
+                    keys = strings;
+                    compare = compareCollatedKeys;
+                }
+            }
+            else {
+                for (let i = 0; i < n; i++)
+                    keys[i] = rows[i].getCellValueByColumnId(columnId);
+                compare = comparator;
+            }
+            clauses.push({ keys, desc: clause.desc, compare });
+        }
+        if (!clauses.length)
+            return rows;
+        // Sort an index array, then materialise. `Array.prototype.sort` is stable,
+        // so equal keys keep their original relative order exactly as the previous
+        // `[...rows].sort(...)` did.
+        const order = new Array(rows.length);
+        for (let i = 0; i < order.length; i++)
+            order[i] = i;
+        // Single-clause sorts get a specialised comparator.
+        //
+        // Most sorts are one column, and that path runs O(n log n) times - 1.66
+        // million comparisons for 100k rows. The general loop pays a clause-array
+        // index, three property loads and an indirect call on every one of them,
+        // none of which vary once the clause list is fixed. Hoisting them into a
+        // closure and, for the numeric comparator, inlining the subtraction removes
+        // the call entirely.
+        //
+        // `keys[ib] - keys[ia]` for descending is exactly `-(keys[ia] - keys[ib])`
+        // as far as sorting is concerned: both are NaN for unorderable values,
+        // which the spec coerces to 0, and they differ only in producing 0 versus
+        // -0 for equal keys, which sorts identically.
+        if (clauses.length === 1) {
+            const { keys, compare, desc } = clauses[0];
+            if (compare === compareNumericKeys) {
+                order.sort(desc
+                    ? function compareOneNumericDesc(ia, ib) { return keys[ib] - keys[ia]; }
+                    : function compareOneNumericAsc(ia, ib) { return keys[ia] - keys[ib]; });
+            }
+            else {
+                order.sort(desc
+                    ? function compareOneDesc(ia, ib) { return -compare(keys[ia], keys[ib]); }
+                    : function compareOneAsc(ia, ib) { return compare(keys[ia], keys[ib]); });
+            }
+        }
+        else {
+            order.sort(function compareRowsByClauses(ia, ib) {
+                for (let k = 0; k < clauses.length; k++) {
+                    const clause = clauses[k];
+                    const result = clause.compare(clause.keys[ia], clause.keys[ib]);
+                    if (result !== 0)
+                        return clause.desc ? -result : result;
+                }
+                return 0;
+            });
+        }
+        const sorted = new Array(rows.length);
+        for (let i = 0; i < order.length; i++)
+            sorted[i] = rows[order[i]];
         return sorted;
     };
 }
+/**
+ * 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.
+ */
+function compareNumericKeys(a, b) {
+    return a - b;
+}
+/**
+ * Text key comparison for the built-in `auto` comparator.
+ *
+ * `localeCompare`, NOT a hoisted `Intl.Collator`. The specification defines
+ * `localeCompare` with no locale or options as constructing a default collator
+ * per call, so hoisting one looks like the obvious optimisation - and it is
+ * measurably slower. V8 fast-paths `String.prototype.localeCompare` for the
+ * default locale; going through a collator object misses that path. Measured
+ * sorting 100k strings: 33 ms via `localeCompare` against 83 ms via a cached
+ * collator on ASCII, 58 ms against 99 ms with accents mixed in, and the two
+ * produce byte-identical orderings across all 100k positions.
+ *
+ * Left as its own function so the sort path has one place to change if that
+ * ever stops being true. Re-measure before "optimising" this again.
+ */
+function compareCollatedKeys(a, b) {
+    return a.localeCompare(b);
+}
+/**
+ * Build a headless grid: state, the row pipeline, and the read methods, with no
+ * DOM and no Svelte. This is the engine `<SvGrid>` renders.
+ *
+ * Most callers want `createSvGrid` (the runes-aware wrapper) or the component
+ * itself; reach for this when you are writing your own renderer or running the
+ * pipeline outside a browser.
+ */
 export function createSvGridCore(options) {
     const internalState = {
         sorting: [],
@@ -530,94 +976,61 @@ export function createSvGridCore(options) {
                 for (let i = 0; i < columns.length; i++)
                     columnIndexById.set(columns[i].id, i);
                 const columnCount = columns.length;
+                // One shared context for every row in this table, so a row carries a
+                // pointer rather than a closure scope. See BASE_ROW_METHODS.
+                const rowCtx = {
+                    grid: grid,
+                    store,
+                    columns,
+                    columnCount,
+                    columnIndexById,
+                };
                 cachedBaseRows = new Array(options.data.length);
                 const getRowId = options.getRowId;
+                const m = BASE_ROW_METHODS;
                 for (let index = 0; index < options.data.length; index++) {
                     const original = options.data[index];
-                    const id = getRowId ? getRowId(original, index) : String(index);
-                    // `values` and `cells` are computed lazily - for a 100k-row grid
-                    // with only ~20 visible rows we don't want to materialise every
-                    // row's full value array or cell objects up front.
-                    let cachedValues = null;
-                    let cachedCells = null;
-                    function computeValues() {
-                        const values = new Array(columnCount);
-                        for (let i = 0; i < columnCount; i++) {
-                            const column = columns[i];
-                            if (column.columnDef.fieldFn) {
-                                values[i] = column.columnDef.fieldFn(original);
-                            }
-                            else if (column.columnDef.field) {
-                                values[i] = original[column.columnDef.field];
-                            }
-                            else {
-                                values[i] = undefined;
-                            }
-                        }
-                        return values;
-                    }
+                    // `_values` and `_cells` stay null until something reads them - a
+                    // 100k-row grid showing twenty rows must not materialise every row's
+                    // values or cell objects to paint.
                     const row = {
-                        id,
+                        id: getRowId ? getRowId(original, index) : String(index),
                         index,
                         original,
                         depth: 0,
-                        getCanExpand: () => false,
-                        getIsExpanded: () => Boolean((store.state.expanded ?? {})[id]),
-                        toggleExpanded: () => {
-                            grid.setExpanded((prev) => ({ ...prev, [id]: !prev[id] }));
-                        },
-                        getIsSelected: () => Boolean((store.state.rowSelection ?? {})[id]),
-                        toggleSelected: () => {
-                            grid.setRowSelection((prev) => ({ ...prev, [id]: !prev[id] }));
-                        },
-                        getAllCells: () => {
-                            if (cachedCells)
-                                return cachedCells;
-                            const built = new Array(columnCount);
-                            for (let i = 0; i < columnCount; i++) {
-                                const column = columns[i];
-                                const colIndex = i;
-                                const cell = {
-                                    id: `${id}_${column.id}`,
-                                    row,
-                                    column,
-                                    getValue: () => {
-                                        if (!cachedValues)
-                                            cachedValues = computeValues();
-                                        return cachedValues[colIndex];
-                                    },
-                                    getContext: () => ({
-                                        cell,
-                                        row,
-                                        column,
-                                        table: grid,
-                                        getValue: () => cell.getValue(),
-                                    }),
-                                };
-                                built[i] = cell;
-                            }
-                            cachedCells = built;
-                            return built;
-                        },
-                        getCellValueByColumnId: (columnId) => {
-                            const idx = columnIndexById.get(columnId);
-                            if (idx === undefined)
-                                return undefined;
-                            if (!cachedValues)
-                                cachedValues = computeValues();
-                            return cachedValues[idx];
-                        },
+                        [ROW_CTX]: rowCtx,
+                        [ROW_VALUES]: null,
+                        [ROW_CELLS]: null,
+                        getCanExpand: m.getCanExpand,
+                        getIsExpanded: m.getIsExpanded,
+                        toggleExpanded: m.toggleExpanded,
+                        getIsSelected: m.getIsSelected,
+                        toggleSelected: m.toggleSelected,
+                        getAllCells: m.getAllCells,
+                        getCellValueByColumnId: m.getCellValueByColumnId,
                     };
                     cachedBaseRows[index] = row;
                 }
             }
+            // Only the slices a pipeline stage actually READS belong in this key.
+            //
+            // `rowSelection` used to be here, which meant ticking one checkbox on a
+            // 100k-row grid re-filtered and re-sorted the entire dataset to rebuild a
+            // row array that was identical by construction. Nothing reads it: the two
+            // consumers are `getIsSelected` closures (on data rows and on group rows)
+            // that read `store.state` when called, so they observe a selection change
+            // without the model being rebuilt.
+            //
+            // `_rowModels` is a closed set of six named slots, so no consumer stage
+            // can be inserted that might read selection. A caller CAN supply a custom
+            // function for one of those slots; if one ever needs a slice that is not
+            // listed here, add it here rather than reinstating all of them.
             const currentSlices = {
                 sorting: store.state.sorting,
                 columnFilters: store.state.columnFilters,
                 pagination: store.state.pagination,
                 grouping: store.state.grouping,
                 expanded: store.state.expanded,
-                rowSelection: store.state.rowSelection,
             };
             if (cachedRowModel &&
                 cachedRowModelBaseRows === cachedBaseRows &&
@@ -626,8 +1039,7 @@ export function createSvGridCore(options) {
                 cachedSlices?.columnFilters === currentSlices.columnFilters &&
                 cachedSlices?.pagination === currentSlices.pagination &&
                 cachedSlices?.grouping === currentSlices.grouping &&
-                cachedSlices?.expanded === currentSlices.expanded &&
-                cachedSlices?.rowSelection === currentSlices.rowSelection) {
+                cachedSlices?.expanded === currentSlices.expanded) {
                 return cachedRowModel;
             }
             let rows = cachedBaseRows;
@@ -653,6 +1065,7 @@ export function createSvGridCore(options) {
     };
     return grid;
 }
+/** Narrowing helper for the many options that accept a value or a function. */
 export function isFunction(value) {
     return typeof value === 'function';
 }