@svgrid/grid 1.0.2 → 1.1.0

package/dist/virtualization/scroll-scaling.js

@@ -0,0 +1,64 @@
+// 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;
+}
+/**
+ * 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 {};

package/dist/virtualization/scroll-scaling.test.js

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest';
+import { createRowScrollScaling } from './scroll-scaling';
+const VIEWPORT = 600;
+describe('createRowScrollScaling - inert (content fits under the cap)', () => {
+    // 1M rows * 18px = 18M, under a 33.5M (Chrome) cap -> no scaling.
+    const s = createRowScrollScaling(18000000, 33554400, VIEWPORT);
+    it('is inactive and exposes the true height as the DOM height', () => {
+        expect(s.active).toBe(false);
+        expect(s.domTotal).toBe(18000000);
+    });
+    it('both maps are the identity', () => {
+        for (const v of [0, 1, 1234, 9000000, 17999400]) {
+            expect(s.domToLogical(v)).toBe(v);
+            expect(s.logicalToDom(v)).toBe(v);
+        }
+    });
+});
+describe('createRowScrollScaling - active (content exceeds the cap)', () => {
+    // 1M rows * 32px = 32M, over Firefox's ~17.9M cap -> scaling engages.
+    const trueTotal = 32000000;
+    const maxDom = 17895697;
+    const s = createRowScrollScaling(trueTotal, maxDom, VIEWPORT);
+    const domMax = s.domTotal - VIEWPORT;
+    const logicalMax = trueTotal - VIEWPORT;
+    it('caps the DOM height at the browser limit', () => {
+        expect(s.active).toBe(true);
+        expect(s.domTotal).toBe(maxDom);
+        expect(s.domTotal).toBeLessThanOrEqual(maxDom);
+    });
+    it('maps the endpoints exactly so the first and last rows are reachable', () => {
+        expect(s.domToLogical(0)).toBe(0);
+        // The bottom of the DOM scroll range reaches the bottom of the logical range.
+        expect(s.domToLogical(domMax)).toBeCloseTo(logicalMax, 3);
+        expect(s.logicalToDom(0)).toBe(0);
+        expect(s.logicalToDom(logicalMax)).toBeCloseTo(domMax, 3);
+    });
+    it('clamps out-of-range inputs instead of overshooting', () => {
+        expect(s.domToLogical(-100)).toBe(0);
+        expect(s.domToLogical(domMax + 10000)).toBeCloseTo(logicalMax, 3);
+        expect(s.logicalToDom(-100)).toBe(0);
+        expect(s.logicalToDom(logicalMax + 10000)).toBeCloseTo(domMax, 3);
+    });
+    it('logicalToDom is the inverse of domToLogical across the range', () => {
+        for (let i = 0; i <= 10; i += 1) {
+            const domTop = (domMax * i) / 10;
+            const roundTrip = s.logicalToDom(s.domToLogical(domTop));
+            expect(roundTrip).toBeCloseTo(domTop, 2);
+        }
+    });
+    it('both maps are monotonic non-decreasing', () => {
+        let prevL = -1;
+        let prevD = -1;
+        for (let i = 0; i <= 20; i += 1) {
+            const domTop = (domMax * i) / 20;
+            const logical = s.domToLogical(domTop);
+            expect(logical).toBeGreaterThanOrEqual(prevL);
+            prevL = logical;
+            const logIn = (logicalMax * i) / 20;
+            const dom = s.logicalToDom(logIn);
+            expect(dom).toBeGreaterThanOrEqual(prevD);
+            prevD = dom;
+        }
+    });
+});
+describe('createRowScrollScaling - edge cases', () => {
+    it('handles an empty grid without dividing by zero', () => {
+        const s = createRowScrollScaling(0, 17895697, VIEWPORT);
+        expect(s.active).toBe(false);
+        expect(s.domTotal).toBe(0);
+        expect(s.domToLogical(0)).toBe(0);
+        expect(s.logicalToDom(0)).toBe(0);
+    });
+    it('handles content shorter than the viewport', () => {
+        const s = createRowScrollScaling(200, 17895697, VIEWPORT);
+        expect(s.active).toBe(false);
+        expect(s.domToLogical(0)).toBe(0);
+    });
+    it('extreme scale (100M rows) keeps the last row reachable', () => {
+        const trueTotal = 100000000 * 32; // 3.2 billion px
+        const s = createRowScrollScaling(trueTotal, 33554400, VIEWPORT);
+        expect(s.active).toBe(true);
+        expect(s.domTotal).toBe(33554400);
+        const domMax = s.domTotal - VIEWPORT;
+        expect(s.domToLogical(domMax)).toBeCloseTo(trueTotal - VIEWPORT, 0);
+    });
+});

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

@@ -7,5 +7,7 @@ export declare function createSvelteVirtualizer(options: VirtualizerOptions): {
     scrollToIndex: (index: number) => void;
     getVirtualItems: () => import("./types").VirtualItem[];
     getTotalSize: () => number;
+    getOffsetForIndex: (index: number) => number;
+    getSizeForIndex: (index: number) => number;
     getState: () => import("./types").VirtualizerState;
 };

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

@@ -15,6 +15,8 @@ export function createSvelteVirtualizer(options) {
         scrollToIndex: virtualizer.scrollToIndex,
         getVirtualItems: virtualizer.getVirtualItems,
         getTotalSize: virtualizer.getTotalSize,
+        getOffsetForIndex: virtualizer.getOffsetForIndex,
+        getSizeForIndex: virtualizer.getSizeForIndex,
         getState: virtualizer.getState,
     };
 }

package/dist/virtualization/virtualizer.d.ts

@@ -7,6 +7,13 @@ export declare function createVirtualizer(initial: VirtualizerOptions): {
     scrollToIndex(index: number): void;
     getVirtualItems(): VirtualItem[];
     getTotalSize(): number;
+    /** Cumulative offset of row `index` from the top in px, regardless
+     *  of whether `estimateSize` is uniform or per-index. Uses the
+     *  cached offsets array under function-form sizing so the lookup
+     *  is O(1) instead of O(index). */
+    getOffsetForIndex(index: number): number;
+    /** Height of row `index` in px (whichever estimateSize provides). */
+    getSizeForIndex(index: number): number;
     getState(): VirtualizerState;
     subscribe(listener: VirtualizerListener): () => boolean;
 };

package/dist/virtualization/virtualizer.js

@@ -221,6 +221,36 @@ export function createVirtualizer(initial) {
         getTotalSize() {
             return state.totalSize;
         },
+        /** Cumulative offset of row `index` from the top in px, regardless
+         *  of whether `estimateSize` is uniform or per-index. Uses the
+         *  cached offsets array under function-form sizing so the lookup
+         *  is O(1) instead of O(index). */
+        getOffsetForIndex(index) {
+            if (index <= 0)
+                return 0;
+            const count = Math.max(options.count, 0);
+            const bounded = Math.min(index, count);
+            if (typeof options.estimateSize === 'function') {
+                const offsets = getOffsets();
+                if (offsets)
+                    return offsets[bounded] ?? 0;
+                let acc = 0;
+                const fn = options.estimateSize;
+                for (let i = 0; i < bounded; i += 1)
+                    acc += Math.max(fn(i), 1);
+                return acc;
+            }
+            return bounded * Math.max(options.estimateSize, 1);
+        },
+        /** Height of row `index` in px (whichever estimateSize provides). */
+        getSizeForIndex(index) {
+            if (index < 0 || index >= options.count)
+                return 0;
+            if (typeof options.estimateSize === 'function') {
+                return Math.max(options.estimateSize(index), 1);
+            }
+            return Math.max(options.estimateSize, 1);
+        },
         getState() {
             return state;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svgrid/grid",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "SvGrid - a headless-first, Svelte 5-native data grid engine and render component.",
   "author": "jQWidgets <boikom@jqwidgets.com>",
   "license": "MIT",

package/src/GridFooter.svelte

@@ -0,0 +1,164 @@
+<script lang="ts" generics="TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData">
+  import {
+      getGridCellA11yProps,
+      getGridCellDomId,
+      getGridHeaderA11yProps,
+      getGridRootA11yProps,
+      getGridRowA11yProps,
+      type EditorContext,
+      type CellEditorOption,
+      type Column,
+      type Row,
+      type RowData,
+      type TableFeatures,
+    } from "./index";
+  import "./sv-grid-scrollbar";
+  import type { Snippet } from "svelte";
+  import {
+      RenderSnippetConfig,
+      RenderComponentConfig,
+    } from "./render-component";
+  import {
+      buildSparkline,
+      toSparklineValues,
+    } from "./sparkline";
+  import SvGridDropdown from "./SvGridDropdown.svelte";
+  import type {
+      Props,
+      SelectionPoint,
+      SelectionRange,
+      CellEditState,
+      FilterOperator,
+      FilterOption,
+      MenuPosition,
+    } from "./SvGrid.types";
+  import {
+      cfTextStyle,
+      fmtStat,
+      getEditableInputValue,
+      getEditorInputType,
+      toValueArray,
+      getOptionLabel,
+      getOptionColor,
+      colorfulChipStyle,
+      getEditorClass,
+    } from "./SvGrid.helpers";
+  import {
+    } from "./SvGrid.controller.svelte";
+  import type { SvGridController } from "./SvGrid.controller.svelte";
+
+  let { ctrl }: { ctrl: SvGridController<TFeatures, TData> } = $props();
+
+  // View facade: re-bind the controller's reactive members so the markup
+  // (moved verbatim from SvGrid.svelte) stays identical.
+  const paginationEnabled = $derived(ctrl.paginationEnabled);
+  const grid = $derived(ctrl.grid);
+  const paginationState = $derived(ctrl.paginationState);
+  const allRowsBeforePagination = $derived(ctrl.allRowsBeforePagination);
+  const statusBarEnabled = $derived(ctrl.statusBarEnabled);
+  const statusBarAggregates = $derived(ctrl.statusBarAggregates);
+  const statusBarStats = $derived(ctrl.statusBarStats);
+  const changePage = $derived(ctrl.changePage);
+  const goToPage = $derived(ctrl.goToPage);
+  const setPageSize = $derived(ctrl.setPageSize);
+</script>
+
+    {#if statusBarEnabled && statusBarStats}
+      {@const s = statusBarStats}
+      <div class="sv-grid-status-bar" role="status" aria-live="polite">
+        {#each statusBarAggregates as agg (agg)}
+          {#if agg === "count"}
+            <span class="sv-grid-status-item"
+              ><span class="sv-grid-status-label">Count</span>{fmtStat(s.count)}</span
+            >
+          {:else if agg === "numericCount"}
+            <span class="sv-grid-status-item"
+              ><span class="sv-grid-status-label">Numeric</span>{fmtStat(s.numericCount)}</span
+            >
+          {:else if s.numericCount > 0 && agg === "sum"}
+            <span class="sv-grid-status-item"
+              ><span class="sv-grid-status-label">Sum</span>{fmtStat(s.sum)}</span
+            >
+          {:else if s.numericCount > 0 && agg === "avg"}
+            <span class="sv-grid-status-item"
+              ><span class="sv-grid-status-label">Avg</span>{fmtStat(s.avg)}</span
+            >
+          {:else if s.numericCount > 0 && agg === "min"}
+            <span class="sv-grid-status-item"
+              ><span class="sv-grid-status-label">Min</span>{fmtStat(s.min)}</span
+            >
+          {:else if s.numericCount > 0 && agg === "max"}
+            <span class="sv-grid-status-item"
+              ><span class="sv-grid-status-label">Max</span>{fmtStat(s.max)}</span
+            >
+          {/if}
+        {/each}
+      </div>
+    {/if}
+
+    {#if paginationEnabled}
+      {@const totalRows = allRowsBeforePagination.length}
+      {@const pageSize = paginationState.pageSize}
+      {@const pageCount = Math.max(1, Math.ceil(totalRows / pageSize))}
+      {@const currentPage = Math.min(paginationState.pageIndex + 1, pageCount)}
+      {@const rangeStart =
+        totalRows === 0 ? 0 : (currentPage - 1) * pageSize + 1}
+      {@const rangeEnd = Math.min(totalRows, currentPage * pageSize)}
+      {@const onFirst = currentPage <= 1}
+      {@const onLast = currentPage >= pageCount}
+      <div class="sv-grid-pagination" role="navigation" aria-label="Pagination">
+        <label class="sv-grid-pagination-pagesize">
+          <span>Page Size:</span>
+          <select
+            onchange={(event) =>
+              setPageSize(
+                parseInt((event.currentTarget as HTMLSelectElement).value, 10),
+              )}
+          >
+            <option value="10" selected={pageSize === 10}>10</option>
+            <option value="25" selected={pageSize === 25}>25</option>
+            <option value="50" selected={pageSize === 50}>50</option>
+            <option value="100" selected={pageSize === 100}>100</option>
+          </select>
+        </label>
+        <span class="sv-grid-pagination-range">
+          <strong>{rangeStart.toLocaleString()}</strong> to
+          <strong>{rangeEnd.toLocaleString()}</strong> of
+          <strong>{totalRows.toLocaleString()}</strong>
+        </span>
+        <div class="sv-grid-pagination-nav">
+          <button
+            type="button"
+            class="sv-grid-pagination-btn"
+            disabled={onFirst}
+            onclick={() => goToPage(0)}
+            aria-label="First page">⇤</button
+          >
+          <button
+            type="button"
+            class="sv-grid-pagination-btn"
+            disabled={onFirst}
+            onclick={() => changePage(-1)}
+            aria-label="Previous page">‹</button
+          >
+          <span class="sv-grid-pagination-label">
+            Page <strong>{currentPage.toLocaleString()}</strong> of
+            <strong>{pageCount.toLocaleString()}</strong>
+          </span>
+          <button
+            type="button"
+            class="sv-grid-pagination-btn"
+            disabled={onLast}
+            onclick={() => changePage(1)}
+            aria-label="Next page">›</button
+          >
+          <button
+            type="button"
+            class="sv-grid-pagination-btn"
+            disabled={onLast}
+            onclick={() => goToPage(pageCount - 1)}
+            aria-label="Last page">⇥</button
+          >
+        </div>
+      </div>
+    {/if}