@svgrid/grid 1.0.2 → 1.1.1

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.interaction.test.js

@@ -272,6 +272,37 @@ describe('SvGrid interactions - cell pointer events', () => {
             destroy();
         }
     });
+    // issue #23: a mouse drag extends the cell range, but a touch drag must NOT -
+    // it should leave the single tapped cell selected so the finger-drag scrolls.
+    async function dragSelectCount(pointerType) {
+        const { target, destroy } = await mountInteractive();
+        try {
+            const a = target.querySelector('[data-svgrid-row="0"][data-svgrid-col="0"]');
+            const c = target.querySelector('[data-svgrid-row="0"][data-svgrid-col="2"]');
+            if (!a || !c)
+                return -1; // jsdom didn't lay the cells out; caller skips
+            a.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, pointerId: 1, button: 0, pointerType }));
+            await tick();
+            c.dispatchEvent(new PointerEvent('pointerenter', { bubbles: true, pointerId: 1, pointerType }));
+            await tick();
+            return target.querySelectorAll('[data-selected-range="true"]').length;
+        }
+        finally {
+            destroy();
+        }
+    }
+    it('mouse drag extends the selection across cells', async () => {
+        const n = await dragSelectCount('mouse');
+        if (n < 0)
+            return;
+        expect(n).toBeGreaterThan(1); // (0,0) -> (0,2) selects the row's 3 cells
+    });
+    it('touch drag does not start a range selection (issue #23)', async () => {
+        const n = await dragSelectCount('touch');
+        if (n < 0)
+            return;
+        expect(n).toBeLessThanOrEqual(1); // only the tapped cell; finger-drag scrolls
+    });
 });
 describe('SvGrid interactions - copy', () => {
     it('Ctrl+C with a cell range does not throw', async () => {

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', () => {
@@ -38,7 +64,7 @@ describe('SvGrid wrapper - cellClass + rowClass', () => {
     it('computes the row-level class once per render row and threads it onto the <tr>', () => {
         expect(source).toMatch(/function computeRowClass/);
         expect(source).toMatch(/userRowClass = computeRowClass\(row, rowIndex\)/);
-        expect(source).toMatch(/class=\{`sv-grid-row \$\{userRowClass\}`\}/);
+        expect(source).toMatch(/class=\{`sv-grid-row \$\{userRowClass\}/);
     });
     it('computes the cell-level class per column and threads it onto the <td>', () => {
         expect(source).toMatch(/function computeCellClass/);
@@ -94,7 +120,7 @@ describe('SvGrid wrapper - between filter operator', () => {
         expect(source).toMatch(/if \(f\.operator === "between"\) \{[^}]*f\.value\.trim\(\)\.length > 0[^}]*f\.valueTo[^}]*\.trim\(\)\.length > 0/);
     });
     it('forwards valueTo through applyExcelFilter', () => {
-        expect(source).toMatch(/valueTo: filter\.operator === "between" \? filter\.valueTo : undefined/);
+        expect(source).toMatch(/valueTo:\s*(filter\.operator|op) === "between" \? (filter\.valueTo|valueTo) : undefined/);
     });
     it('publishes valueTo in the onFiltersChange payload only for between clauses', () => {
         expect(source).toMatch(/f\.operator === "between" && f\.valueTo\s*\?\s*\{ valueTo: f\.valueTo \}/);
@@ -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,38 @@ 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*\{/);
+    });
+    // Regression: the controller's ctx is an object literal of getters, and the
+    // copy/cut/paste handlers in keyboard-handlers + menus reach the functions
+    // via `ctx.<name>()`. A refactor once shipped the `ctx.cutSelectionToClipboard`
+    // / `ctx.pasteFromClipboard` CALLS but dropped their getters, so those threw
+    // "is not a function" at runtime - copy worked, cut + paste were dead. Assert
+    // every clipboard function called through ctx has a matching getter.
+    it('exposes a ctx getter for every clipboard command it calls through ctx', () => {
+        for (const fn of [
+            'copySelectionToClipboard',
+            'cutSelectionToClipboard',
+            'pasteFromClipboard',
+            'onGridPaste',
+            'clearSelectedCells',
+        ]) {
+            expect(source).toMatch(new RegExp(`get ${fn}\\(\\)\\s*\\{\\s*return ${fn};?\\s*\\}`));
+        }
+    });
+    it('copy/cut fall back to execCommand when navigator.clipboard is absent (insecure context)', () => {
+        expect(source).toMatch(/function writeClipboardText\(/);
+        expect(source).toMatch(/document\.execCommand\("copy"\)/);
+    });
+    it('paste falls back to a native paste event when the async API is unavailable', () => {
+        // keydown only preventDefaults (and uses the async API) in a secure context;
+        // otherwise it lets the browser deliver a native paste event to onGridPaste.
+        // Accept either the positive branch or the inverted early-return guard
+        // (`if (!navigator.clipboard?.readText) return`) - both gate on the async API.
+        expect(source).toMatch(/if \(!?navigator\.clipboard\?\.readText\)/);
+        expect(source).toMatch(/function onGridPaste\(event: ClipboardEvent\)/);
+        expect(source).toMatch(/clipboardData\?\.getData\("text\/plain"\)/);
+        // The grid root wires the handler.
+        expect(source).toMatch(/onpaste=\{onGridPaste\}/);
     });
 });

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/test-setup.js

@@ -1,8 +1,14 @@
 // Vitest setup. jsdom doesn't ship ResizeObserver, IntersectionObserver,
 // or the layout APIs SvGrid touches inside its mount effects. Provide
 // minimal no-op stubs so component mounting completes without crashing.
+//
+// These assign to globals/prototypes the jsdom env doesn't fully type, so
+// the targets are cast to `any`. We deliberately avoid expect-error
+// suppression directives: when a stub happens to line up with the lib types,
+// such a directive becomes "unused" and svelte-check fails the build (an
+// unused expect-error directive is itself an error).
 if (typeof globalThis.ResizeObserver === 'undefined') {
-    // @ts-expect-error - assigning to a globalThis property the env doesn't ship
+    ;
     globalThis.ResizeObserver = class {
         observe() { }
         unobserve() { }
@@ -10,7 +16,7 @@ if (typeof globalThis.ResizeObserver === 'undefined') {
     };
 }
 if (typeof globalThis.IntersectionObserver === 'undefined') {
-    // @ts-expect-error - same
+    ;
     globalThis.IntersectionObserver = class {
         observe() { }
         unobserve() { }
@@ -23,7 +29,7 @@ if (typeof globalThis.IntersectionObserver === 'undefined') {
 // jsdom's HTMLElement.scrollIntoView is a no-op; some grid code calls it
 // during the first effect. Make sure the method exists on every element.
 if (typeof Element !== 'undefined' && !Element.prototype.scrollIntoView) {
-    // @ts-expect-error - patching a missing DOM method
+    ;
     Element.prototype.scrollIntoView = function () { };
 }
 export {};

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,45 @@
+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;
+};
+/**
+ * Resolve the usable max element height from the two raw DOM signals.
+ *
+ * `layoutCap` is a tall probe's clamped `offsetHeight` - the height layout
+ * assigns the element. `scrollCap` is the `scrollHeight` a real `overflow:auto`
+ * container exposes for that same probe - the height the user can actually
+ * scroll through. They differ on mobile / high-DPR engines, which report a
+ * generous `offsetHeight` but then expose a SMALLER scrollable range (the
+ * physical limit is in device px, so a 3x-DPR phone has ~1/3 the CSS-px scroll
+ * cap). Trusting `offsetHeight` alone is exactly what strands the last rows of
+ * a huge grid on a phone, so we take the smaller of the two.
+ *
+ * A junk reading (<= the sanity floor, or so large the browser clearly didn't
+ * clamp) is dropped; if neither signal survives, the caller's conservative
+ * `fallback` is returned unchanged.
+ */
+export declare function resolveMaxDomHeight(layoutCap: number, scrollCap: number, fallback: 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;

package/dist/virtualization/scroll-scaling.js

@@ -0,0 +1,99 @@
+// Pure math for "huge list" vertical scroll scaling.
+//
+// Browsers cap how tall a single element may be (Chrome/Safari ~33.5M px,
+// Firefox ~17.9M, mobile/high-DPR lower). Once a virtualized grid's true
+// content height (count * rowHeight) exceeds that cap the scroll container
+// silently clamps its scrollHeight and the tail rows become unreachable - a
+// 1,000,000-row grid that only scrolls to ~994,000 on a phone.
+//
+// The fix (the technique react-virtualized calls "scaling"): size the DOM
+// scroll spacer to a capped height the browser CAN render, and map between the
+// limited DOM scroll range and the full logical range the virtualizer works
+// in. This module is the pure, side-effect-free core of that mapping so the
+// invariants can be unit-tested independently of the Svelte controller.
+//
+// When the true height fits under the cap, scaling is INERT: every mapping is
+// the identity and callers behave exactly as before.
+function clamp01(value) {
+    if (value <= 0)
+        return 0;
+    if (value >= 1)
+        return 1;
+    return value;
+}
+/** Below this a reading is junk (0 from jsdom, a sub-cap layout quirk, etc). */
+const MAX_DOM_HEIGHT_SANITY_FLOOR = 100000;
+/** At/above this the browser didn't clamp (returned ~the 1e9 we asked for). */
+const MAX_DOM_HEIGHT_SANITY_CEIL = 900000000;
+/**
+ * Shave a hair off the detected cap so the spacer never sits at the exact
+ * physical edge, where sub-pixel rounding could leave the final row a touch
+ * out of reach. 0.5% is invisible at desktop caps (~33.5M -> ~33.3M) yet
+ * keeps a safety gap proportional to the cap.
+ */
+const MAX_DOM_HEIGHT_SAFETY = 0.995;
+/**
+ * Resolve the usable max element height from the two raw DOM signals.
+ *
+ * `layoutCap` is a tall probe's clamped `offsetHeight` - the height layout
+ * assigns the element. `scrollCap` is the `scrollHeight` a real `overflow:auto`
+ * container exposes for that same probe - the height the user can actually
+ * scroll through. They differ on mobile / high-DPR engines, which report a
+ * generous `offsetHeight` but then expose a SMALLER scrollable range (the
+ * physical limit is in device px, so a 3x-DPR phone has ~1/3 the CSS-px scroll
+ * cap). Trusting `offsetHeight` alone is exactly what strands the last rows of
+ * a huge grid on a phone, so we take the smaller of the two.
+ *
+ * A junk reading (<= the sanity floor, or so large the browser clearly didn't
+ * clamp) is dropped; if neither signal survives, the caller's conservative
+ * `fallback` is returned unchanged.
+ */
+export function resolveMaxDomHeight(layoutCap, scrollCap, fallback) {
+    const usable = [layoutCap, scrollCap].filter((v) => Number.isFinite(v) &&
+        v > MAX_DOM_HEIGHT_SANITY_FLOOR &&
+        v < MAX_DOM_HEIGHT_SANITY_CEIL);
+    if (usable.length === 0)
+        return fallback;
+    return Math.floor(Math.min(...usable) * MAX_DOM_HEIGHT_SAFETY);
+}
+/**
+ * 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 function createRowScrollScaling(trueTotal, maxDomHeight, viewport) {
+    const safeMax = Math.max(maxDomHeight, 1);
+    const domTotal = Math.min(Math.max(trueTotal, 0), safeMax);
+    const active = trueTotal > safeMax;
+    // Scrollable ranges (content minus one viewport). Guard against zero so the
+    // ratios below never divide by zero on tiny / empty grids.
+    const domRange = Math.max(domTotal - viewport, 1);
+    const logicalRange = Math.max(trueTotal - viewport, 0);
+    return {
+        active,
+        domTotal,
+        domToLogical(domTop) {
+            if (!active)
+                return domTop;
+            return clamp01(domTop / domRange) * logicalRange;
+        },
+        logicalToDom(logical) {
+            if (!active)
+                return logical;
+            const lr = Math.max(logicalRange, 1);
+            return clamp01(logical / lr) * Math.max(domTotal - viewport, 0);
+        },
+    };
+}

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

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