@svgrid/grid 1.0.0

package/dist/virtualization/virtualizer.js

@@ -0,0 +1,232 @@
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+function sameOptions(a, b) {
+    return (a.count === b.count &&
+        a.estimateSize === b.estimateSize &&
+        (a.overscan ?? 6) === (b.overscan ?? 6) &&
+        a.viewportHeight === b.viewportHeight &&
+        (a.scrollOffset ?? 0) === (b.scrollOffset ?? 0));
+}
+function sameState(a, b) {
+    if (a.totalSize !== b.totalSize ||
+        a.startIndex !== b.startIndex ||
+        a.endIndex !== b.endIndex ||
+        a.viewportHeight !== b.viewportHeight ||
+        a.items.length !== b.items.length) {
+        return false;
+    }
+    // Per-item start+size check: catches column-resize cases where the total
+    // is unchanged (e.g. column A grew, column B shrunk to compensate under
+    // fit-to-width). Without this, the virtualizer skips the emit and the
+    // grid renders with stale widths.
+    for (let i = 0; i < a.items.length; i += 1) {
+        const ai = a.items[i];
+        const bi = b.items[i];
+        if (ai.index !== bi.index || ai.start !== bi.start || ai.size !== bi.size)
+            return false;
+    }
+    return true;
+}
+// Slot-based keying: the key is the POSITION of the item inside the
+// visible window (slot 0 = topmost rendered row, slot 1 = next, etc.)
+// - NOT the data index. As the user scrolls, the window's startIndex
+// changes but the slot keys stay the same (0..N-1), so Svelte recycles
+// the existing <tr> DOM nodes and only updates their data + position.
+//
+// This avoids the mount/unmount churn that previously fired on every
+// scroll tick: with data-index keys, scrolling down 1 row meant the old
+// topmost key disappeared and a new bottommost key appeared, forcing
+// Svelte to unmount the top <tr> and mount a fresh one at the bottom.
+// Slot-based keys keep the same N <tr> nodes alive for the lifetime of
+// the grid; scroll just translates them via the top spacer.
+function buildUniformItems(startIndex, endIndex, estimateSize) {
+    const items = [];
+    for (let index = startIndex; index <= endIndex; index += 1) {
+        const start = index * estimateSize;
+        items.push({
+            index,
+            start,
+            size: estimateSize,
+            end: start + estimateSize,
+            key: `virtual_slot_${index - startIndex}`,
+        });
+    }
+    return items;
+}
+function buildVariableItems(startIndex, endIndex, offsets) {
+    const items = [];
+    for (let index = startIndex; index <= endIndex; index += 1) {
+        const start = offsets[index] ?? 0;
+        const end = offsets[index + 1] ?? start;
+        items.push({
+            index,
+            start,
+            size: end - start,
+            end,
+            key: `virtual_slot_${index - startIndex}`,
+        });
+    }
+    return items;
+}
+function createState(options, 
+/** Pre-built cumulative offsets for the variable-size path. */
+offsets) {
+    const count = Math.max(options.count, 0);
+    const overscan = Math.max(options.overscan ?? 6, 0);
+    const viewportHeight = Math.max(options.viewportHeight, 0);
+    if (typeof options.estimateSize === 'function' && offsets) {
+        const totalSize = offsets[count] ?? 0;
+        const maxOffset = Math.max(totalSize - viewportHeight, 0);
+        const scrollOffset = clamp(options.scrollOffset ?? 0, 0, maxOffset);
+        // First index whose end > scrollOffset.
+        let lo = 0;
+        let hi = count;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if ((offsets[mid + 1] ?? 0) <= scrollOffset)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        const visibleStart = lo;
+        // First index whose start >= scrollOffset + viewportHeight.
+        const viewportEnd = scrollOffset + viewportHeight;
+        lo = visibleStart;
+        hi = count;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if ((offsets[mid] ?? 0) < viewportEnd)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        const visibleEnd = Math.max(lo - 1, visibleStart);
+        const startIndex = count === 0 ? 0 : clamp(visibleStart - overscan, 0, count - 1);
+        const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscan, 0, count - 1);
+        return {
+            items: endIndex >= startIndex ? buildVariableItems(startIndex, endIndex, offsets) : [],
+            totalSize,
+            startIndex,
+            endIndex,
+            scrollOffset,
+            viewportHeight,
+        };
+    }
+    // Uniform-size fast path (original behavior).
+    const estimateSize = Math.max(typeof options.estimateSize === 'number' ? options.estimateSize : 1, 1);
+    const totalSize = count * estimateSize;
+    const maxOffset = Math.max(totalSize - viewportHeight, 0);
+    const scrollOffset = clamp(options.scrollOffset ?? 0, 0, maxOffset);
+    const visibleStart = Math.floor(scrollOffset / estimateSize);
+    const visibleCount = Math.ceil(viewportHeight / estimateSize);
+    const visibleEnd = Math.min(visibleStart + visibleCount, Math.max(count - 1, 0));
+    const startIndex = count === 0 ? 0 : clamp(visibleStart - overscan, 0, count - 1);
+    const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscan, 0, count - 1);
+    return {
+        items: endIndex >= startIndex ? buildUniformItems(startIndex, endIndex, estimateSize) : [],
+        totalSize,
+        startIndex,
+        endIndex,
+        scrollOffset,
+        viewportHeight,
+    };
+}
+export function createVirtualizer(initial) {
+    let options = initial;
+    let offsetCache = null;
+    function getOffsets() {
+        if (typeof options.estimateSize !== 'function')
+            return null;
+        const count = Math.max(options.count, 0);
+        if (offsetCache &&
+            offsetCache.fn === options.estimateSize &&
+            offsetCache.count === count) {
+            return offsetCache.offsets;
+        }
+        const sizeFn = options.estimateSize;
+        const offsets = new Array(count + 1);
+        offsets[0] = 0;
+        for (let i = 0; i < count; i += 1) {
+            offsets[i + 1] = offsets[i] + Math.max(sizeFn(i), 1);
+        }
+        offsetCache = { fn: sizeFn, count, offsets };
+        return offsets;
+    }
+    let state = createState(options, getOffsets());
+    const listeners = new Set();
+    function emit() {
+        listeners.forEach((listener) => listener());
+    }
+    function recalc() {
+        const next = createState(options, getOffsets());
+        if (sameState(state, next))
+            return;
+        state = next;
+        emit();
+    }
+    return {
+        setOptions(next) {
+            const merged = { ...options, ...next };
+            if (sameOptions(options, merged))
+                return;
+            options = merged;
+            recalc();
+        },
+        setScrollOffset(scrollOffset) {
+            if ((options.scrollOffset ?? 0) === scrollOffset)
+                return;
+            options = { ...options, scrollOffset };
+            recalc();
+        },
+        setViewportHeight(viewportHeight) {
+            if (options.viewportHeight === viewportHeight)
+                return;
+            options = { ...options, viewportHeight };
+            recalc();
+        },
+        scrollToIndex(index) {
+            const boundedIndex = clamp(index, 0, Math.max(options.count - 1, 0));
+            // Read the current state's totals so the offset is correct under both
+            // uniform and per-index sizing.
+            const totalSize = state.totalSize;
+            let targetOffset;
+            if (typeof options.estimateSize === 'function') {
+                // Use the cached cumulative offsets if present.
+                const offsets = getOffsets();
+                if (offsets) {
+                    targetOffset = offsets[boundedIndex] ?? 0;
+                }
+                else {
+                    let acc = 0;
+                    const sizeFn = options.estimateSize;
+                    for (let i = 0; i < boundedIndex; i += 1)
+                        acc += Math.max(sizeFn(i), 1);
+                    targetOffset = acc;
+                }
+            }
+            else {
+                targetOffset = boundedIndex * Math.max(options.estimateSize, 1);
+            }
+            const maxOffset = Math.max(totalSize - options.viewportHeight, 0);
+            const nextOffset = clamp(targetOffset, 0, maxOffset);
+            if ((options.scrollOffset ?? 0) === nextOffset)
+                return;
+            options = { ...options, scrollOffset: nextOffset };
+            recalc();
+        },
+        getVirtualItems() {
+            return state.items;
+        },
+        getTotalSize() {
+            return state.totalSize;
+        },
+        getState() {
+            return state;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}

package/dist/virtualization/virtualizer.test.d.ts

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

package/dist/virtualization/virtualizer.test.js

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { createVirtualizer } from './virtualizer';
+describe('virtualizer', () => {
+    it('computes bounded virtual range with overscan', () => {
+        const v = createVirtualizer({
+            count: 100000,
+            estimateSize: 36,
+            overscan: 8,
+            viewportHeight: 360,
+            scrollOffset: 0,
+        });
+        const items = v.getVirtualItems();
+        expect(items.length).toBeGreaterThan(0);
+        expect(items[0]?.index).toBe(0);
+        expect(items[items.length - 1]?.index).toBe(18);
+    });
+    it('updates range when scroll offset changes', () => {
+        const v = createVirtualizer({
+            count: 100000,
+            estimateSize: 40,
+            overscan: 5,
+            viewportHeight: 400,
+            scrollOffset: 0,
+        });
+        v.setScrollOffset(4000);
+        const state = v.getState();
+        expect(state.startIndex).toBeLessThanOrEqual(100);
+        expect(state.endIndex).toBeGreaterThanOrEqual(110);
+    });
+    it('scrollToIndex clamps target offset', () => {
+        const v = createVirtualizer({
+            count: 100,
+            estimateSize: 30,
+            overscan: 2,
+            viewportHeight: 300,
+            scrollOffset: 0,
+        });
+        v.scrollToIndex(9999);
+        expect(v.getState().scrollOffset).toBe(2700);
+    });
+});

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@svgrid/grid",
+  "version": "1.0.0",
+  "description": "SvGrid - a headless-first, Svelte 5-native data grid engine and render component.",
+  "author": "jQWidgets <boikom@jqwidgets.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sv-grid/sv-grid.git",
+    "directory": "packages/grid"
+  },
+  "homepage": "https://svgrid.com",
+  "keywords": [
+    "svelte",
+    "grid",
+    "table",
+    "headless",
+    "datagrid"
+  ],
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "svelte": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "import": "./dist/index.js"
+    },
+    "./static-functions": {
+      "types": "./dist/static-functions.d.ts",
+      "svelte": "./dist/static-functions.js",
+      "import": "./dist/static-functions.js"
+    },
+    "./flex-render": {
+      "types": "./dist/flex-render.d.ts",
+      "svelte": "./dist/flex-render.js",
+      "import": "./dist/flex-render.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "clean": "rimraf ./build && rimraf ./dist",
+    "test:eslint": "eslint ./src",
+    "test:types": "svelte-check --tsconfig ./tsconfig.json",
+    "test:lib": "vitest run --coverage",
+    "test:build": "publint --strict",
+    "build": "svelte-package --input ./src --output ./dist"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^7.0.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "eslint-plugin-svelte": "^3.17.1",
+    "jsdom": "^29.1.1",
+    "svelte": "^5.55.5",
+    "svelte-check": "^4.4.6"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  }
+}

package/src/FlexRender.svelte

@@ -0,0 +1,96 @@
+<script
+  lang="ts"
+  generics="TData extends RowData"
+>
+  import { isFunction } from './core'
+  import {
+    RenderComponentConfig,
+    RenderSnippetConfig,
+  } from './render-component'
+  import type {
+    Cell,
+    CellContext,
+    ColumnDefTemplate,
+    Header,
+    HeaderContext,
+    RowData,
+  } from './core'
+
+  type Props =
+    | {
+        content?: ColumnDefTemplate<
+          | HeaderContext<TData>
+          | CellContext<TData>
+        >
+        context:
+          | HeaderContext<TData>
+          | CellContext<TData>
+        cell?: never
+        header?: never
+        footer?: never
+      }
+    | {
+        cell: Cell<TData>
+        content?: never
+        context?: never
+        header?: never
+        footer?: never
+      }
+    | {
+        header: Header<TData>
+        content?: never
+        context?: never
+        cell?: never
+        footer?: never
+      }
+    | {
+        footer: Header<TData>
+        content?: never
+        context?: never
+        cell?: never
+        header?: never
+      }
+
+  let props: Props = $props()
+
+  const resolved = $derived.by(() => {
+    if ('cell' in props && props.cell) {
+      return {
+        content: props.cell.column.columnDef.cell,
+        context: props.cell.getContext(),
+      }
+    }
+    if ('header' in props && props.header) {
+      return {
+        content: props.header.column.columnDef.header,
+        context: props.header.getContext(),
+      }
+    }
+    if ('footer' in props && props.footer) {
+      return {
+        content: props.footer.column.columnDef.footer,
+        context: props.footer.getContext(),
+      }
+    }
+    return {
+      content: props.content,
+      context: props.context,
+    }
+  })
+
+  const result = $derived(
+    isFunction(resolved.content)
+      ? resolved.content(resolved.context as any)
+      : undefined,
+  )
+</script>
+
+{#if typeof resolved.content === 'string'}
+  {resolved.content}
+{:else if result instanceof RenderComponentConfig}
+  <result.component {...result.props} />
+{:else if result instanceof RenderSnippetConfig}
+  {@render result.snippet(result.params)}
+{:else if result !== undefined}
+  {result}
+{/if}