@svgrid/grid 1.0.2 → 1.1.0

package/dist/spreadsheet.js

@@ -0,0 +1,194 @@
+/**
+ * Spreadsheet-style layout helpers — cell merging + per-cell borders.
+ *
+ * These are *layout-only* augmentations on top of `<SvGrid>`. They don't
+ * change the grid's data model, sorting, or filtering — they just decorate
+ * the rendered body cells. Bind the action to the wrapper around your
+ * SvGrid and pass merge / border specs; the helper observes DOM mutations
+ * and re-applies the layout whenever the grid re-renders.
+ *
+ * Limitations (worth knowing up front):
+ *   - Merges + borders index into the CURRENTLY-DISPLAYED rows (after
+ *     sort / filter), via the `data-svgrid-row` index the grid sets on
+ *     every body cell. If your data sorts or filters, recompute the
+ *     specs against the new display order.
+ *   - Merges use real `colspan` / `rowspan` plus `display:none` on
+ *     covered TDs. Column widths come from the inline styles SvGrid
+ *     emits on each TD; we don't fight those.
+ *   - For long row-merges across a virtualised window, only rows that
+ *     are actually rendered get the rowspan applied. Disable
+ *     virtualisation on grids that need a continuous merge.
+ */
+const BORDER_KEYS = ['top', 'right', 'bottom', 'left'];
+const MARK = 'data-svgrid-sheet';
+function borderCss(spec) {
+    if (!spec)
+        return null;
+    const w = spec.width ?? 2;
+    const s = spec.style ?? 'solid';
+    const c = spec.color ?? 'currentColor';
+    return `${w}px ${s} ${c}`;
+}
+/** Look up a body cell by its display-row + column id. Falls back to
+ *  null if the cell isn't in the current render window (virtualisation,
+ *  scrolled out, or filtered away). */
+function findCell(root, rowIndex, columnId) {
+    return root.querySelector(`td[data-svgrid-row="${rowIndex}"][data-col-id="${CSS.escape(columnId)}"]`);
+}
+const OVERLAY_CLASS = 'sv-cell-border-overlay';
+/** Apply / re-apply layout decorations. Called once on mount, again on
+ *  every relevant DOM mutation inside the grid, and whenever the action
+ *  options update. */
+function apply(root, opts) {
+    // ---- 1. Clean up anything the LAST run added -----------------------
+    for (const td of root.querySelectorAll(`td[${MARK}]`)) {
+        td.removeAttribute('colspan');
+        td.removeAttribute('rowspan');
+        if (td.style.display === 'none')
+            td.style.display = '';
+        // Remove the overlay child we previously injected for borders.
+        const overlay = td.querySelector(`:scope > .${OVERLAY_CLASS}`);
+        if (overlay)
+            overlay.remove();
+        td.classList.remove('sv-merge-edge-right', 'sv-merge-edge-bottom', 'sv-merge-in-range');
+        td.removeAttribute(MARK);
+    }
+    const colOrder = opts.columnOrder;
+    const colIndexOf = new Map();
+    for (let i = 0; i < colOrder.length; i += 1)
+        colIndexOf.set(colOrder[i], i);
+    // ---- 2. Merges -----------------------------------------------------
+    for (const m of opts.merges ?? []) {
+        const startCol = colIndexOf.get(m.columnId);
+        if (startCol === undefined)
+            continue;
+        const rs = Math.max(1, m.rowspan ?? 1);
+        const cs = Math.max(1, m.colspan ?? 1);
+        const origin = findCell(root, m.rowIndex, m.columnId);
+        if (!origin)
+            continue;
+        if (cs > 1)
+            origin.setAttribute('colspan', String(cs));
+        if (rs > 1)
+            origin.setAttribute('rowspan', String(rs));
+        origin.setAttribute(MARK, '');
+        for (let dr = 0; dr < rs; dr += 1) {
+            for (let dc = 0; dc < cs; dc += 1) {
+                if (dr === 0 && dc === 0)
+                    continue;
+                const colId = colOrder[startCol + dc];
+                if (!colId)
+                    continue;
+                const td = findCell(root, m.rowIndex + dr, colId);
+                if (!td)
+                    continue;
+                td.style.display = 'none';
+                td.setAttribute(MARK, '');
+            }
+        }
+        // Selection-edge inheritance:
+        // The grid sets `data-range-*` per cell. The merge's RIGHTMOST /
+        // BOTTOMMOST covered cells are `display:none`, so the borders
+        // they would draw never render. Mirror those edge flags onto the
+        // origin via dedicated CSS classes (so we can toggle them
+        // independently of Svelte's own data-range-* updates without a
+        // ping-pong loop).
+        const lastColId = colOrder[startCol + cs - 1];
+        const rightCell = lastColId ? findCell(root, m.rowIndex, lastColId) : null;
+        const bottomCell = findCell(root, m.rowIndex + rs - 1, m.columnId);
+        const farCell = lastColId ? findCell(root, m.rowIndex + rs - 1, lastColId) : null;
+        const wantRight = rightCell?.getAttribute('data-range-right') === 'true' ||
+            farCell?.getAttribute('data-range-right') === 'true';
+        const wantBottom = bottomCell?.getAttribute('data-range-bottom') === 'true' ||
+            farCell?.getAttribute('data-range-bottom') === 'true';
+        const inRange = rightCell?.getAttribute('data-selected-range') === 'true' ||
+            bottomCell?.getAttribute('data-selected-range') === 'true' ||
+            farCell?.getAttribute('data-selected-range') === 'true' ||
+            origin.getAttribute('data-selected-range') === 'true';
+        origin.classList.toggle('sv-merge-edge-right', wantRight);
+        origin.classList.toggle('sv-merge-edge-bottom', wantBottom);
+        origin.classList.toggle('sv-merge-in-range', inRange);
+    }
+    // ---- 3. Borders ---------------------------------------------------
+    // Use an absolute-positioned overlay div so each edge renders
+    // independently of the grid's own border-collapse rules. Adjacent
+    // TDs no longer "eat" the right / bottom edges of a bordered cell.
+    for (const b of opts.borders ?? []) {
+        const td = findCell(root, b.rowIndex, b.columnId);
+        if (!td)
+            continue;
+        let any = false;
+        const overlay = document.createElement('div');
+        overlay.className = OVERLAY_CLASS;
+        overlay.style.cssText =
+            'position:absolute;inset:0;pointer-events:none;box-sizing:border-box;z-index:1;';
+        for (const e of BORDER_KEYS) {
+            const css = borderCss(b[e]);
+            if (!css)
+                continue;
+            overlay.style.setProperty(`border-${e}`, css);
+            any = true;
+        }
+        if (!any)
+            continue;
+        // Ensure the TD is a positioning context for the overlay.
+        if (getComputedStyle(td).position === 'static')
+            td.style.position = 'relative';
+        td.appendChild(overlay);
+        td.setAttribute(MARK, '');
+    }
+}
+/** Svelte action. Attach to the element that hosts your `<SvGrid>` so
+ *  the action can watch its DOM for re-renders.
+ *
+ * ```svelte
+ * <div use:spreadsheetLayout={{ merges, borders, columnOrder }}>
+ *   <SvGrid {data} {columns} ... />
+ * </div>
+ * ```
+ *
+ * The action re-applies the layout whenever the grid's body mutates
+ * (new rows, column reorder, virtualization scroll) and whenever the
+ * options change. */
+export function spreadsheetLayout(node, opts) {
+    let current = opts;
+    let frame = 0;
+    // The MutationObserver fires for EVERY DOM change inside the grid -
+    // batch them into one rAF so a big virtualization scroll doesn't run
+    // apply() dozens of times in a tick.
+    function schedule() {
+        if (frame)
+            return;
+        frame = requestAnimationFrame(() => {
+            frame = 0;
+            apply(node, current);
+        });
+    }
+    const observer = new MutationObserver(schedule);
+    observer.observe(node, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: [
+            'data-svgrid-row', 'data-col-id', 'style',
+            // Watch selection-range attrs so we can transfer them from
+            // hidden covered cells to merge origins.
+            'data-range-top', 'data-range-bottom', 'data-range-left',
+            'data-range-right', 'data-selected-range',
+        ],
+    });
+    // First-paint pass: schedule the same way so we don't run before the
+    // grid's initial render landed.
+    schedule();
+    return {
+        update(next) {
+            current = next;
+            schedule();
+        },
+        destroy() {
+            observer.disconnect();
+            if (frame)
+                cancelAnimationFrame(frame);
+        },
+    };
+}

package/dist/summaries.d.ts

@@ -0,0 +1,12 @@
+import { type Column, type Row, type RowData, type TableFeatures } from "./index";
+import "./sv-grid-scrollbar";
+export declare function createSummaries<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData>(ctx: any): {
+    computeSummaries: (rows: ReadonlyArray<Row<TData>>, columns: ReadonlyArray<Column<TData>>) => Record<string, string>;
+    hasRenderedColumn: (entry: {
+        item: (typeof ctx.renderedColumnItems)[number];
+        column: (typeof ctx.allColumns)[number] | undefined;
+    }) => entry is {
+        item: (typeof ctx.renderedColumnItems)[number];
+        column: (typeof ctx.allColumns)[number];
+    };
+};

package/dist/summaries.js

@@ -0,0 +1,65 @@
+import "./sv-grid-scrollbar";
+import { getCellKey, } from "./SvGrid.helpers";
+import { formatSummaryNumeric, } from "./cell-values";
+export function createSummaries(ctx) {
+    /**
+     * Aggregate every row into a per-column footer summary (sum for numeric
+     * columns, `Count: N` otherwise). This loop is the hottest path on a
+     * large grid - it is rows x columns iterations - so two things keep the
+     * constant factor down:
+     *
+     *   1. The edited-cell overlay is only consulted when an edit actually
+     *      exists. `key in editedCellValues` hits a reactive-proxy `has`
+     *      trap for every cell otherwise - 5M no-op trap calls on a
+     *      100k x 50 grid. Skipping it when the map is empty is the single
+     *      biggest win here.
+     *   2. The column's accessor (`accessorFn` / `field`) is resolved once
+     *      per column, not re-read off `columnDef` for every cell.
+     */
+    function computeSummaries(rows, columns) {
+        const summary = {};
+        const rowCount = rows.length;
+        const hasEdits = Object.keys(ctx.editedCellValues).length > 0;
+        for (const column of columns) {
+            const def = column.columnDef;
+            const accessorFn = def.accessorFn;
+            const field = def.field;
+            const columnId = column.id;
+            let numericSum = 0;
+            let numericCount = 0;
+            for (let i = 0; i < rowCount; i += 1) {
+                const row = rows[i];
+                let value;
+                const base = accessorFn
+                    ? accessorFn(row.original)
+                    : field
+                        ? row.original[field]
+                        : row.getCellValueByColumnId(columnId);
+                if (hasEdits) {
+                    const key = getCellKey(row.id, columnId);
+                    value = key in ctx.editedCellValues ? ctx.editedCellValues[key] : base;
+                }
+                else {
+                    value = base;
+                }
+                const asNumber = Number(value);
+                if (Number.isFinite(asNumber)) {
+                    numericSum += asNumber;
+                    numericCount += 1;
+                }
+            }
+            summary[columnId] =
+                numericCount > 0
+                    ? formatSummaryNumeric(column, numericSum)
+                    : `Count: ${rowCount}`;
+        }
+        return summary;
+    }
+    function hasRenderedColumn(entry) {
+        return entry.column !== undefined;
+    }
+    return {
+        computeSummaries,
+        hasRenderedColumn,
+    };
+}

package/dist/svgrid-wrapper.types.d.ts

@@ -164,6 +164,15 @@ export type SvGridApi<TFeatures extends TableFeatures, TData extends RowData> =
      * default. Useful for "save view" + URL persistence.
      */
     getColumnWidths(): Record<string, number>;
+    /**
+     * Snap one column's width to its widest visible cell (header text +
+     * any rendered body cell). Equivalent to double-clicking the column's
+     * resize handle. The grid also exposes this through the column menu's
+     * "Autosize" item.
+     */
+    autosizeColumn(columnId: string): void;
+    /** Run `autosizeColumn` on every column. */
+    autosizeAllColumns(): void;
     /**
      * Replace the column-pinning state in one call. Each entry is a
      * column id; the order in the array becomes the visible order along
@@ -325,7 +334,9 @@ export type SvGridWrapperProps<TFeatures extends TableFeatures, TData extends Ro
     showRowSelection?: boolean;
     showPagination?: boolean;
     virtualization?: boolean;
-    rowHeight?: number;
+    /** Row height in pixels. Pass a function `(rowIndex) => px` for per-row
+     *  variable heights (e.g. when wiring up an interactive row-resize). */
+    rowHeight?: number | ((rowIndex: number) => number);
     overscan?: number;
     containerHeight?: number;
     columnVirtualization?: boolean;

package/dist/svgrid.comments-autocomplete.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/svgrid.comments-autocomplete.test.js

@@ -0,0 +1,96 @@
+/**
+ * Track C: free-text autocomplete cell type + editable cell comments.
+ */
+import { describe, expect, it } from 'vitest';
+import { mount, unmount } from 'svelte';
+import SvGrid from './SvGrid.svelte';
+import { createCoreRowModel, tableFeatures } from './index';
+const features = tableFeatures({});
+const rows = [
+    { id: 1, name: 'Ann', city: 'Paris' },
+    { id: 2, name: 'Bo', city: 'Berlin' },
+];
+const tick = () => new Promise((r) => queueMicrotask(r));
+function mountGrid(extraCols, props = {}) {
+    return new Promise((res) => {
+        const target = document.createElement('div');
+        document.body.appendChild(target);
+        const app = mount(SvGrid, {
+            target,
+            props: {
+                data: rows,
+                columns: [{ field: 'name', header: 'Name', width: 160, editorType: 'text' }, ...extraCols],
+                features,
+                _rowModels: { coreRowModel: createCoreRowModel() },
+                rowHeight: 32,
+                containerHeight: 360,
+                virtualization: false,
+                enableInlineEditing: true,
+                enableCellSelection: true,
+                onApiReady(api) {
+                    res({ api, target, destroy: () => { unmount(app); target.remove(); } });
+                },
+                ...props,
+            },
+        });
+    });
+}
+function dataCell(target, col) {
+    return target.querySelectorAll('.sv-grid-cell[data-svgrid-row]')[col];
+}
+describe('autocomplete cell type', () => {
+    it('filters suggestions as you type and commits the picked option', async () => {
+        const { api, target, destroy } = await mountGrid([
+            {
+                field: 'city',
+                header: 'City',
+                width: 200,
+                editorType: 'autocomplete',
+                editorOptions: ['Paris', 'Berlin', 'Boston', 'Brussels'],
+            },
+        ]);
+        await tick();
+        // city is the 2nd column => index 1 in the first row's cells
+        const cell = target.querySelectorAll('.sv-grid-cell[data-svgrid-row="0"]')[1];
+        cell.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
+        await tick();
+        const input = target.querySelector('.sv-grid-cell-editor-autocomplete');
+        expect(input).not.toBeNull();
+        input.value = 'B';
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+        await tick();
+        const opts = [...target.querySelectorAll('.sv-grid-autocomplete-option')].map((b) => b.textContent?.trim());
+        // 'B' matches Berlin, Boston, Brussels - not Paris
+        expect(opts).toEqual(['Berlin', 'Boston', 'Brussels']);
+        const berlin = [...target.querySelectorAll('.sv-grid-autocomplete-option')].find((b) => b.textContent?.trim() === 'Boston');
+        berlin.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
+        await tick();
+        expect(api.getCellValue(0, 'city')).toBe('Boston');
+        destroy();
+    });
+});
+describe('editable comments', () => {
+    it('adds a comment via the context menu and emits onNoteChange', async () => {
+        const changes = [];
+        const { target, destroy } = await mountGrid([{ field: 'city', header: 'City', width: 200, editorType: 'text' }], { contextMenu: true, editableComments: true, onNoteChange: (e) => changes.push(e) });
+        await tick();
+        const cell = dataCell(target, 0);
+        cell.dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, cancelable: true }));
+        await tick();
+        const editItem = [...target.querySelectorAll('.sv-grid-context-menu .sv-grid-menu-item')].find((b) => b.textContent?.trim() === 'Edit comment');
+        expect(editItem).toBeTruthy();
+        editItem.click();
+        await tick();
+        const ta = target.querySelector('.sv-grid-comment-textarea');
+        expect(ta).not.toBeNull();
+        ta.value = 'Needs review';
+        ta.dispatchEvent(new Event('input', { bubbles: true }));
+        await tick();
+        target.querySelector('.sv-grid-comment-save').click();
+        await tick();
+        expect(changes.length).toBe(1);
+        expect(changes[0].note).toBe('Needs review');
+        expect(target.querySelector('.sv-grid-comment-editor')).toBeNull();
+        destroy();
+    });
+});

package/dist/svgrid.context-menu.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/svgrid.context-menu.test.js

@@ -0,0 +1,102 @@
+/**
+ * Right-click context menu (Track A). Mounts a grid with `contextMenu`,
+ * fires a synthetic `contextmenu` event on a cell, and asserts the menu
+ * opens with the expected items and that actions/close work.
+ */
+import { describe, expect, it } from 'vitest';
+import { mount, unmount } from 'svelte';
+import SvGrid from './SvGrid.svelte';
+import { createCoreRowModel, createFilteredRowModel, createSortedRowModel, rowSelectionFeature, rowSortingFeature, sortFns, tableFeatures, } from './index';
+const features = tableFeatures({ rowSortingFeature, rowSelectionFeature });
+const rows = Array.from({ length: 6 }, (_, i) => ({
+    id: i + 1,
+    name: `Person ${i + 1}`,
+    team: ['A', 'B'][i % 2],
+}));
+const cols = [
+    { field: 'name', header: 'Name', width: 200, editorType: 'text' },
+    { field: 'team', header: 'Team', width: 160, editorType: 'text' },
+];
+const tick = () => new Promise((r) => queueMicrotask(r));
+function mountGrid(contextMenu) {
+    return new Promise((res, rej) => {
+        const target = document.createElement('div');
+        document.body.appendChild(target);
+        const app = mount(SvGrid, {
+            target,
+            props: {
+                data: rows,
+                columns: cols,
+                features,
+                _rowModels: {
+                    coreRowModel: createCoreRowModel(),
+                    filteredRowModel: createFilteredRowModel(),
+                    sortedRowModel: createSortedRowModel(sortFns),
+                },
+                rowHeight: 32,
+                containerHeight: 400,
+                virtualization: false,
+                enableCellSelection: true,
+                contextMenu,
+                onApiReady(api) {
+                    res({ api, target, destroy: () => { unmount(app); target.remove(); } });
+                },
+            },
+        });
+        queueMicrotask(() => { if (!target.querySelector('[role="grid"]'))
+            rej(new Error('no grid')); });
+    });
+}
+function rightClickFirstCell(target) {
+    const cell = target.querySelector('.sv-grid-cell[data-svgrid-row]');
+    const r = cell.getBoundingClientRect();
+    cell.dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, cancelable: true, clientX: r.x + 4, clientY: r.y + 4 }));
+    return cell;
+}
+describe('SvGrid context menu', () => {
+    it('opens the default menu on right-click with the built-in items', async () => {
+        const { target, destroy } = await mountGrid(true);
+        await tick();
+        rightClickFirstCell(target);
+        await tick();
+        const menu = target.querySelector('.sv-grid-context-menu');
+        expect(menu).not.toBeNull();
+        const labels = [...menu.querySelectorAll('.sv-grid-menu-item')].map((b) => b.textContent?.trim());
+        expect(labels).toContain('Copy');
+        expect(labels).toContain('Paste');
+        expect(labels).toContain('Remove row');
+        expect(labels).toContain('Remove column');
+        destroy();
+    });
+    it('does not open when contextMenu is omitted (native menu shows)', async () => {
+        const { target, destroy } = await mountGrid(undefined);
+        await tick();
+        const cell = target.querySelector('.sv-grid-cell[data-svgrid-row]');
+        const ev = new MouseEvent('contextmenu', { bubbles: true, cancelable: true });
+        cell.dispatchEvent(ev);
+        await tick();
+        expect(target.querySelector('.sv-grid-context-menu')).toBeNull();
+        expect(ev.defaultPrevented).toBe(false);
+        destroy();
+    });
+    it('renders only the configured custom items and runs the action', async () => {
+        let ran = 0;
+        const items = [
+            'copy',
+            'separator',
+            { key: 'flag', label: 'Flag row', action: () => { ran += 1; } },
+        ];
+        const { target, destroy } = await mountGrid(items);
+        await tick();
+        rightClickFirstCell(target);
+        await tick();
+        const labels = [...target.querySelectorAll('.sv-grid-context-menu .sv-grid-menu-item')].map((b) => b.textContent?.trim());
+        expect(labels).toEqual(['Copy', 'Flag row']);
+        const flag = [...target.querySelectorAll('.sv-grid-context-menu .sv-grid-menu-item')].find((b) => b.textContent?.trim() === 'Flag row');
+        flag.click();
+        expect(ran).toBe(1);
+        await tick();
+        expect(target.querySelector('.sv-grid-context-menu')).toBeNull();
+        destroy();
+    });
+});

package/dist/svgrid.new-features.wrapper.test.js

@@ -15,8 +15,34 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { describe, expect, it } from 'vitest';
-const sourcePath = resolve(__dirname, './SvGrid.svelte');
-const source = readFileSync(sourcePath, 'utf-8');
+// The wrapper implementation spans SvGrid.svelte plus its extracted
+// sibling modules (types + pure helpers). Concatenate them so these
+// "the wrapper declares/exposes X" assertions hold wherever the code
+// physically lives.
+const source = [
+    './SvGrid.svelte',
+    './SvGrid.controller.svelte.ts',
+    './GridMenus.svelte',
+    './GridFooter.svelte',
+    './SvGrid.types.ts',
+    './SvGrid.helpers.ts',
+    './filter-operators.ts',
+    './facet-buckets.ts',
+    './cell-values.ts',
+    './clipboard.ts',
+    './build-api.ts',
+    './columns.ts',
+    './selection.ts',
+    './editing.ts',
+    './cell-render.ts',
+    './menus.ts',
+    './summaries.ts',
+    './keyboard-handlers.ts',
+    './scroll-sync.ts',
+    './features.ts',
+]
+    .map((p) => readFileSync(resolve(__dirname, p), 'utf-8'))
+    .join('\n');
 const typesPath = resolve(__dirname, './svgrid-wrapper.types.ts');
 const types = readFileSync(typesPath, 'utf-8');
 describe('SvGrid wrapper - getRowId prop', () => {
@@ -120,7 +146,7 @@ describe('SvGrid wrapper - multi-cell paste + cut + delete', () => {
     });
     it('wires Ctrl/Cmd+X to cutSelectionToClipboard', () => {
         expect(source).toMatch(/lower === "x"/);
-        expect(source).toMatch(/void cutSelectionToClipboard\(\)/);
+        expect(source).toMatch(/void (?:ctx\.)?cutSelectionToClipboard\(\)/);
         expect(source).toMatch(/async function cutSelectionToClipboard/);
         // Confirm both calls live inside the cutSelectionToClipboard body
         // (copy first, then clear). A comment between them is fine.
@@ -131,6 +157,6 @@ describe('SvGrid wrapper - multi-cell paste + cut + delete', () => {
     });
     it('wires Delete + Backspace to clearSelectedCells (without clipboard interaction)', () => {
         expect(source).toMatch(/event\.key === "Delete" \|\| event\.key === "Backspace"/);
-        expect(source).toMatch(/if \(clearSelectedCells\(\)\)\s*\{/);
+        expect(source).toMatch(/if \((?:ctx\.)?clearSelectedCells\(\)\)\s*\{/);
     });
 });

package/dist/svgrid.wrapper.test.js

@@ -7,7 +7,33 @@ describe('SvGrid wrapper', () => {
         expect(SvGrid).toBeDefined();
     });
     it('contains full-wrapper controls and aria-activedescendant wiring', () => {
-        const source = readFileSync(resolve(__dirname, './SvGrid.svelte'), 'utf-8');
+        // The wrapper spans SvGrid.svelte plus its extracted sibling modules
+        // (types + pure helpers); read them together so these "contains X"
+        // assertions hold wherever the code physically lives.
+        const source = [
+            './SvGrid.svelte',
+            './SvGrid.controller.svelte.ts',
+            './GridMenus.svelte',
+            './GridFooter.svelte',
+            './SvGrid.types.ts',
+            './SvGrid.helpers.ts',
+            './filter-operators.ts',
+            './facet-buckets.ts',
+            './cell-values.ts',
+            './clipboard.ts',
+            './build-api.ts',
+            './columns.ts',
+            './selection.ts',
+            './editing.ts',
+            './cell-render.ts',
+            './menus.ts',
+            './summaries.ts',
+            './keyboard-handlers.ts',
+            './scroll-sync.ts',
+            './features.ts',
+        ]
+            .map((p) => readFileSync(resolve(__dirname, p), 'utf-8'))
+            .join('\n');
         expect(source).toContain('Filter all rows');
         expect(source).toContain('Previous');
         expect(source).toContain('role="status"');

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

@@ -15,6 +15,8 @@ export declare function createColumnVirtualizer(input: {
     scrollToIndex(index: number): void;
     getVirtualItems(): import("./types").VirtualItem[];
     getTotalSize(): number;
+    getOffsetForIndex(index: number): number;
+    getSizeForIndex(index: number): number;
     getState(): import("./types").VirtualizerState;
     subscribe(listener: () => void): () => boolean;
 };

package/dist/virtualization/scroll-scaling.d.ts

@@ -0,0 +1,28 @@
+export type RowScrollScaling = {
+    /** True when the true content height exceeds the cap and mapping applies. */
+    readonly active: boolean;
+    /** Height (px) the DOM scroll spacer should occupy - capped at maxDomHeight. */
+    readonly domTotal: number;
+    /** Map a DOM scrollTop into the virtualizer's logical scroll offset. */
+    domToLogical(domTop: number): number;
+    /** Map a virtualizer logical offset back into a DOM scrollTop. */
+    logicalToDom(logical: number): number;
+};
+/**
+ * Build the scaling mapping for one axis.
+ *
+ * @param trueTotal     The real content height in logical px (count * rowH, or
+ *                      the cumulative offset total for variable rows).
+ * @param maxDomHeight  The browser's max element height (detected at runtime).
+ * @param viewport      The scroll viewport height in px.
+ *
+ * Invariants (verified in scroll-scaling.test.ts):
+ *  - Inert when `trueTotal <= maxDomHeight`: both maps are the identity.
+ *  - `domTotal <= maxDomHeight` always, so the spacer never exceeds the cap.
+ *  - Endpoints line up: domTop 0 -> logical 0, and the DOM max
+ *    (`domTotal - viewport`) -> the logical max (`trueTotal - viewport`), so
+ *    the very last row is always reachable.
+ *  - `logicalToDom` is the inverse of `domToLogical` across the range.
+ *  - Both maps are monotonic non-decreasing and clamp out-of-range inputs.
+ */
+export declare function createRowScrollScaling(trueTotal: number, maxDomHeight: number, viewport: number): RowScrollScaling;