vlist 1.9.1 → 2.0.0

package/dist/rendering/scale.js

@@ -0,0 +1,267 @@
+/**
+ * vlist - Compression Module
+ * Pure functions for handling large lists that exceed browser size limits
+ *
+ * When a list's total size (sum of all item sizes) exceeds the browser's
+ * maximum element size (~16.7M pixels), we "compress" the virtual scroll space.
+ *
+ * Key concepts:
+ * - actualSize: The true size if all items were rendered
+ * - virtualSize: The capped size used for the scroll container (≤ MAX_VIRTUAL_SIZE)
+ * - compressionRatio: virtualSize / actualSize (1 = no compression, <1 = compressed)
+ *
+ * When compressed:
+ * - Scroll position maps to item index via ratio, not pixel math
+ * - Item positions are calculated relative to a "virtual index" at current scroll
+ * - Near-bottom interpolation ensures the last items are reachable
+ */
+import { MAX_VIRTUAL_SIZE } from "../constants";
+import { countVisibleItems, } from "./sizes";
+// Re-export for convenience
+export { MAX_VIRTUAL_SIZE };
+/**
+ * Calculate compression state for a list
+ * Pure function - no side effects
+ *
+ * @param _totalItems - Total number of items
+ * @param sizeCache - Size cache for item sizes/offsets
+ * @param force - When true, enables compressed mode even if total size is under the limit.
+ *   Useful for testing, consistent UX, or preemptively enabling compression
+ *   before the list grows past the browser limit.
+ */
+export const getCompressionState = (_totalItems, sizeCache, force) => {
+    const actualSize = sizeCache.getTotalSize();
+    const isCompressed = force === true || actualSize > MAX_VIRTUAL_SIZE;
+    const virtualSize = actualSize > MAX_VIRTUAL_SIZE ? MAX_VIRTUAL_SIZE : actualSize;
+    const ratio = actualSize > 0 ? virtualSize / actualSize : 1;
+    return {
+        isCompressed,
+        actualSize,
+        virtualSize,
+        ratio,
+    };
+};
+// =============================================================================
+// Range Calculations (Compressed)
+// =============================================================================
+/**
+ * Calculate visible range with compression support
+ * Pure function - no side effects
+ *
+ * @param scrollTop - Current scroll position
+ * @param containerHeight - Viewport container height
+ * @param sizeCache - Size cache for item sizes/offsets
+ * @param totalItems - Total number of items
+ * @param compression - Compression state
+ * @param out - Output range to mutate (avoids allocation on hot path)
+ */
+export const calculateCompressedVisibleRange = (scrollPosition, containerHeight, sizeCache, totalItems, compression, out) => {
+    if (totalItems === 0 || containerHeight === 0) {
+        out.start = 0;
+        out.end = -1;
+        return out;
+    }
+    if (!compression.isCompressed || compression.ratio === 1) {
+        // Normal calculation using size cache.
+        // Also used when ratio === 1 (force mode, no actual compression) —
+        // the scroll infrastructure is active but positions map 1:1,
+        // so offset-based math is exact and avoids interpolation drift.
+        const start = sizeCache.indexAtOffset(scrollPosition);
+        // Find the last item that is at least partially visible
+        // Add 1 to match the fixed-height ceil() behavior (safe overshoot)
+        let end = sizeCache.indexAtOffset(scrollPosition + containerHeight);
+        if (end < totalItems - 1)
+            end++;
+        out.start = Math.max(0, start);
+        out.end = Math.min(totalItems - 1, Math.max(0, end));
+        return out;
+    }
+    // Compressed calculation — map scrollTop to actual space, then use
+    // sizeCache prefix sums to find the correct index. This handles mixed
+    // item sizes (e.g. group headers shorter than data items) correctly,
+    // matching how calculateCompressedItemPosition maps positions.
+    const { virtualSize } = compression;
+    const scrollRatio = scrollPosition / virtualSize;
+    const actualSize = sizeCache.getTotalSize();
+    const actualScrollOffset = scrollRatio * actualSize;
+    const start = sizeCache.indexAtOffset(actualScrollOffset);
+    const visibleCount = countVisibleItems(sizeCache, Math.max(0, start), containerHeight, totalItems);
+    const end = start + visibleCount;
+    out.start = Math.max(0, start);
+    out.end = Math.min(totalItems - 1, Math.max(0, end));
+    return out;
+};
+/**
+ * Calculate render range with compression support (adds overscan)
+ * Pure function - no side effects
+ *
+ * @param out - Output range to mutate (avoids allocation on hot path)
+ */
+export const calculateCompressedRenderRange = (visibleRange, overscan, totalItems, out) => {
+    if (totalItems === 0) {
+        out.start = 0;
+        out.end = -1;
+        return out;
+    }
+    out.start = Math.max(0, visibleRange.start - overscan);
+    out.end = Math.min(totalItems - 1, visibleRange.end + overscan);
+    return out;
+};
+// =============================================================================
+// Item Positioning (Compressed)
+// =============================================================================
+/**
+ * Calculate item position (translateY) with compression support
+ * Pure function - no side effects
+ *
+ * In compressed mode (manual wheel scrolling, overflow: hidden), items are
+ * positioned RELATIVE TO THE VIEWPORT. The scroll container doesn't actually
+ * scroll - we intercept wheel events and manually position items.
+ *
+ * Key insight:
+ * - Calculate a "virtual scroll index" from the scroll ratio
+ * - Items are positioned relative to this virtual index using actual heights
+ * - Each item keeps its full height for proper rendering
+ *
+ * @param index - Item index
+ * @param scrollTop - Current (virtual) scroll position
+ * @param sizeCache - Size cache for item sizes/offsets
+ * @param totalItems - Total number of items
+ * @param containerHeight - Viewport container height
+ * @param compression - Compression state
+ */
+export const calculateCompressedItemPosition = (index, scrollPosition, sizeCache, totalItems, _containerHeight, compression, _rangeStart) => {
+    if (!compression.isCompressed || totalItems === 0) {
+        // Normal: absolute position in content space (scroll handled by container)
+        return sizeCache.getOffset(index);
+    }
+    // When ratio === 1 (force mode, no actual compression), virtualSize === actualSize
+    // so scroll position maps 1:1 to pixel offset. Use simple subtraction to avoid
+    // near-bottom interpolation drift that causes a gap at the bottom.
+    if (compression.ratio === 1) {
+        return sizeCache.getOffset(index) - scrollPosition;
+    }
+    const { virtualSize } = compression;
+    // Normal compressed positioning
+    //
+    // Map scrollTop to an actual-space offset via the compression ratio,
+    // then position the item relative to that offset.
+    // With compression slack on the content div the linear formula is valid
+    // for ALL scroll positions — no near-bottom interpolation needed.
+    const scrollRatio = scrollPosition / virtualSize;
+    const actualSize = sizeCache.getTotalSize();
+    const virtualScrollOffset = scrollRatio * actualSize;
+    return sizeCache.getOffset(index) - virtualScrollOffset;
+};
+// =============================================================================
+// Scroll Position Calculations (Compressed)
+// =============================================================================
+/**
+ * Calculate scroll position to bring an index into view (with compression)
+ * Pure function - no side effects
+ *
+ * @param index - Target item index
+ * @param sizeCache - Size cache for item sizes/offsets
+ * @param containerHeight - Viewport container height
+ * @param totalItems - Total number of items
+ * @param compression - Compression state
+ * @param align - Alignment within viewport
+ */
+export const calculateCompressedScrollToIndex = (index, sizeCache, containerHeight, totalItems, compression, align = "start") => {
+    if (totalItems === 0)
+        return 0;
+    let targetPosition;
+    if (compression.isCompressed && compression.ratio !== 1) {
+        // Map index to compressed scroll position using linear formula.
+        // With compression slack on the content div the linear mapping is valid
+        // for ALL indices — no special-case needed for the last item.
+        const indexRatio = index / totalItems;
+        targetPosition = indexRatio * compression.virtualSize;
+        // Alignment adjustment must be scaled by the compression ratio.
+        // The viewport shows containerHeight/itemSize items regardless of
+        // compression, but each scroll-pixel maps to 1/ratio actual pixels.
+        // Without scaling, the pixel offset overshoots by 1/ratio items.
+        const itemSize = sizeCache.getSize(index);
+        switch (align) {
+            case "center":
+                targetPosition -= (containerHeight - itemSize) / 2 * compression.ratio;
+                break;
+            case "end":
+                targetPosition -= (containerHeight - itemSize) * compression.ratio;
+                break;
+        }
+        // NOTE: no maxScroll clamp here — the caller (withScale) manages
+        // maxScroll with compression slack included.  Clamping to
+        // virtualSize − containerHeight would prevent reaching the last items.
+        return Math.max(0, targetPosition);
+    }
+    // Direct calculation using actual offset.
+    // Also used when ratio === 1 (force mode) — positions map 1:1.
+    targetPosition = sizeCache.getOffset(index);
+    // Adjust for alignment using the specific item's size
+    const itemSize = sizeCache.getSize(index);
+    switch (align) {
+        case "center":
+            targetPosition -= (containerHeight - itemSize) / 2;
+            break;
+        case "end":
+            targetPosition -= containerHeight - itemSize;
+            break;
+    }
+    // Clamp to valid range
+    const maxScroll = compression.virtualSize - containerHeight;
+    return Math.max(0, Math.min(targetPosition, maxScroll));
+};
+/**
+ * Calculate the approximate item index at a given scroll position
+ * Useful for debugging and scroll position restoration
+ * Pure function - no side effects
+ */
+export const calculateIndexFromScrollPosition = (scrollPosition, sizeCache, totalItems, compression) => {
+    if (totalItems === 0)
+        return 0;
+    if (compression.isCompressed && compression.ratio !== 1) {
+        const scrollRatio = scrollPosition / compression.virtualSize;
+        return Math.floor(scrollRatio * totalItems);
+    }
+    // Direct lookup — also used when ratio === 1 (force mode, no actual compression)
+    return sizeCache.indexAtOffset(scrollPosition);
+};
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Check if compression is needed for a list configuration
+ * Pure function - no side effects
+ *
+ * Note: This overload accepts a HeightCache for variable heights.
+ * For simple fixed-height checks, use needsCompressionFixed().
+ */
+export const needsCompression = (totalItems, heightOrCache) => {
+    if (typeof heightOrCache === "number") {
+        return totalItems * heightOrCache > MAX_VIRTUAL_SIZE;
+    }
+    return heightOrCache.getTotalSize() > MAX_VIRTUAL_SIZE;
+};
+/**
+ * Calculate maximum items supported without compression
+ * Only meaningful for fixed-height items
+ * Pure function - no side effects
+ */
+export const getMaxItemsWithoutCompression = (itemSize) => {
+    if (itemSize <= 0)
+        return 0;
+    return Math.floor(MAX_VIRTUAL_SIZE / itemSize);
+};
+/**
+ * Get human-readable compression info for debugging
+ * Pure function - no side effects
+ */
+export const getCompressionInfo = (totalItems, sizeCache, force) => {
+    const compression = getCompressionState(totalItems, sizeCache, force);
+    if (!compression.isCompressed) {
+        return `No compression needed (${totalItems} items, ${(compression.actualSize / 1000000).toFixed(2)}M px)`;
+    }
+    const ratioPercent = (compression.ratio * 100).toFixed(1);
+    return `Compressed to ${ratioPercent}% (${totalItems} items, ${(compression.actualSize / 1000000).toFixed(1)}M px → ${(compression.virtualSize / 1000000).toFixed(1)}M px virtual)`;
+};

package/dist/rendering/scroll.js

@@ -0,0 +1,71 @@
+/**
+ * vlist - Smart Edge Scroll
+ * Shared scroll utility used by both core baseline and withSelection feature.
+ * Only scrolls when the target item is outside the viewport; aligns to nearest edge.
+ *
+ * Split into two functions for tree-shaking:
+ * - scrollToFocusSimple: normal mode only (used by base builder)
+ * - scrollToFocus: handles both normal and compressed modes (used by features)
+ */
+/**
+ * Simple scroll-to-focus: normal (non-compressed) mode only.
+ * Padding-aware: accounts for CSS padding on the content element.
+ */
+export const scrollToFocusSimple = (index, sizeCache, scrollPosition, containerSize, startPadding = 0, endPadding = 0) => {
+    const itemOffset = sizeCache.getOffset(index);
+    const itemSize = sizeCache.getSize(index);
+    const adjustedTop = itemOffset + startPadding;
+    const adjustedBottom = adjustedTop + itemSize;
+    const viewportBottom = scrollPosition + containerSize;
+    if (adjustedTop < scrollPosition)
+        return Math.max(0, itemOffset);
+    if (adjustedBottom > viewportBottom)
+        return adjustedBottom + endPadding - containerSize;
+    return scrollPosition;
+};
+/**
+ * Full scroll-to-focus: handles both normal and compressed (withScale) modes.
+ * Used by withSelection feature which must work with compression.
+ */
+export const scrollToFocus = (index, sizeCache, scrollPosition, containerSize, startPadding = 0, endPadding = 0, compression, totalItems, visibleRange) => {
+    const isCompressed = compression != null &&
+        compression.isCompressed &&
+        compression.ratio !== 1;
+    if (!isCompressed) {
+        return scrollToFocusSimple(index, sizeCache, scrollPosition, containerSize, startPadding, endPadding);
+    }
+    // ── Compressed: prefix-sum positioning ──
+    // Use actual offsets from the size cache instead of linear index math.
+    // Linear math assumes uniform item sizes, but group headers are shorter
+    // than data items, causing the focused item to land short of the edge.
+    const { virtualSize } = compression;
+    const itemSize = sizeCache.getSize(Math.max(0, index));
+    const effectiveSize = containerSize - startPadding - endPadding;
+    const fullyVisible = Math.max(1, Math.floor(effectiveSize / itemSize));
+    const totalActualSize = sizeCache.getTotalSize();
+    if (visibleRange) {
+        if (index >= visibleRange.start + fullyVisible) {
+            const itemBottom = sizeCache.getOffset(index) + itemSize;
+            const targetActualTop = itemBottom + endPadding - containerSize;
+            return Math.max(0, (targetActualTop / totalActualSize) * virtualSize);
+        }
+        if (index <= visibleRange.start) {
+            const targetActualTop = sizeCache.getOffset(index) - startPadding;
+            return Math.max(0, (targetActualTop / totalActualSize) * virtualSize);
+        }
+        return scrollPosition;
+    }
+    // No visible range — fallback
+    const currentIndex = (scrollPosition / virtualSize) * totalItems;
+    const currentEnd = currentIndex + fullyVisible;
+    if (index >= currentEnd) {
+        const itemBottom = sizeCache.getOffset(index) + itemSize;
+        const targetActualTop = itemBottom + endPadding - containerSize;
+        return Math.max(0, (targetActualTop / totalActualSize) * virtualSize);
+    }
+    if (index < currentIndex) {
+        const targetActualTop = sizeCache.getOffset(index) - startPadding;
+        return Math.max(0, (targetActualTop / totalActualSize) * virtualSize);
+    }
+    return scrollPosition;
+};

package/dist/rendering/sizes.js

@@ -0,0 +1,193 @@
+/**
+ * vlist - Size Cache
+ * Efficient size management for fixed and variable item sizes
+ *
+ * Provides two implementations:
+ * - Fixed: O(1) operations using multiplication (zero overhead, matches existing behavior)
+ * - Variable: O(1) offset lookup via prefix sums, O(log n) binary search for index-at-offset
+ *
+ * The SizeCache abstraction allows all virtual scrolling and compression code
+ * to work identically with both fixed and variable sizes, for both vertical and horizontal scrolling.
+ */
+// =============================================================================
+// Fixed Size Cache
+// =============================================================================
+/**
+ * Create a fixed-size cache
+ * All operations are O(1) using simple multiplication — zero overhead
+ */
+const createFixedSizeCache = (size, initialTotal) => {
+    let total = initialTotal;
+    return {
+        getOffset: (index) => index * size,
+        getSize: (_index) => size,
+        indexAtOffset: (offset) => {
+            if (total === 0 || size === 0)
+                return 0;
+            return Math.max(0, Math.min(Math.floor(offset / size), total - 1));
+        },
+        getTotalSize: () => total * size,
+        getTotal: () => total,
+        rebuild: (newTotal) => {
+            total = newTotal;
+        },
+        isVariable: () => false,
+    };
+};
+// =============================================================================
+// Variable Size Cache
+// =============================================================================
+/**
+ * Create a variable-size cache using prefix sums
+ *
+ * Prefix sums array: prefixSums[i] = sum of sizes for items 0..i-1
+ *   prefixSums[0] = 0
+ *   prefixSums[1] = size(0)
+ *   prefixSums[n] = total size of all n items
+ *
+ * This enables:
+ *   getOffset(i) = prefixSums[i]           — O(1)
+ *   getTotalSize() = prefixSums[n]         — O(1)
+ *   indexAtOffset(y) = binary search        — O(log n)
+ */
+const createVariableSizeCache = (sizeFn, initialTotal) => {
+    let total = initialTotal;
+    let prefixSums = new Float64Array(0);
+    /**
+     * Build prefix sums from the size function
+     * O(n) — only called on data changes, never on scroll
+     */
+    const build = (n) => {
+        total = n;
+        prefixSums = new Float64Array(n + 1);
+        prefixSums[0] = 0;
+        for (let i = 0; i < n; i++) {
+            prefixSums[i + 1] = prefixSums[i] + sizeFn(i);
+        }
+    };
+    // Initial build
+    build(initialTotal);
+    /**
+     * Binary search: find the largest index i where prefixSums[i] <= offset
+     * This gives the item that contains the given scroll offset
+     */
+    const binarySearch = (offset) => {
+        if (total === 0)
+            return 0;
+        // Clamp to valid range
+        if (offset <= 0)
+            return 0;
+        if (offset >= prefixSums[total])
+            return total - 1;
+        let lo = 0;
+        let hi = total - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >>> 1;
+            if (prefixSums[mid] <= offset) {
+                lo = mid;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        return lo;
+    };
+    return {
+        getOffset: (index) => {
+            if (index <= 0)
+                return 0;
+            if (index >= total)
+                return prefixSums[total];
+            return prefixSums[index];
+        },
+        getSize: (index) => sizeFn(index),
+        indexAtOffset: (offset) => binarySearch(offset),
+        getTotalSize: () => prefixSums[total] ?? 0,
+        getTotal: () => total,
+        rebuild: (newTotal) => build(newTotal),
+        isVariable: () => true,
+    };
+};
+// =============================================================================
+// Factory
+// =============================================================================
+/**
+ * Create a size cache — returns fixed or variable implementation
+ *
+ * When size is a number, returns a zero-overhead fixed implementation.
+ * When size is a function, builds a prefix-sum array for efficient lookups.
+ */
+export const createSizeCache = (size, initialTotal) => {
+    if (typeof size === "number") {
+        return createFixedSizeCache(size, initialTotal);
+    }
+    return createVariableSizeCache(size, initialTotal);
+};
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Count how many items fit in a given container size starting from startIndex
+ * Used for compressed mode visible range calculations
+ *
+ * For fixed sizes: O(1) via division
+ * For variable sizes: O(k) where k = visible item count (typically 10-50)
+ */
+export const countVisibleItems = (sizeCache, startIndex, containerSize, totalItems) => {
+    if (totalItems === 0)
+        return 0;
+    if (!sizeCache.isVariable()) {
+        return Math.ceil(containerSize / sizeCache.getSize(0));
+    }
+    let count = 0;
+    let accumulated = 0;
+    let idx = startIndex;
+    while (idx < totalItems && accumulated < containerSize) {
+        accumulated += sizeCache.getSize(idx);
+        count++;
+        idx++;
+    }
+    return Math.max(1, count);
+};
+/**
+ * Count how many items fit starting from the bottom of the list
+ * Used for near-bottom interpolation in compressed mode
+ *
+ * For fixed sizes: O(1) via division
+ * For variable sizes: O(k) where k = items fitting (typically 10-50)
+ */
+export const countItemsFittingFromBottom = (sizeCache, containerSize, totalItems) => {
+    if (totalItems === 0)
+        return 0;
+    if (!sizeCache.isVariable()) {
+        return Math.floor(containerSize / sizeCache.getSize(0));
+    }
+    let count = 0;
+    let accumulated = 0;
+    for (let i = totalItems - 1; i >= 0; i--) {
+        const s = sizeCache.getSize(i);
+        if (accumulated + s > containerSize)
+            break;
+        accumulated += s;
+        count++;
+    }
+    return Math.max(count, 1);
+};
+/**
+ * Calculate the pixel offset for a fractional virtual scroll index
+ *
+ * In compressed mode, the scroll position maps to a fractional item index
+ * (e.g., 5.3 means 30% into item 5). This function calculates the actual
+ * pixel offset for such a fractional position using variable sizes.
+ *
+ * For fixed sizes this reduces to: virtualIndex * itemSize
+ * For variable sizes: offset(floor) + frac * size(floor)
+ */
+export const getOffsetForVirtualIndex = (sizeCache, virtualIndex, totalItems) => {
+    if (totalItems === 0)
+        return 0;
+    const intPart = Math.floor(virtualIndex);
+    const fracPart = virtualIndex - intPart;
+    const safeInt = Math.max(0, Math.min(intPart, totalItems - 1));
+    return sizeCache.getOffset(safeInt) + fracPart * sizeCache.getSize(safeInt);
+};

package/dist/rendering/sort.js

@@ -0,0 +1,65 @@
+// src/rendering/sort.ts
+/**
+ * Shared DOM sort utility for accessibility.
+ *
+ * Virtual list renderers append new elements at the end of the container
+ * for performance (batched DocumentFragment insertion). After scrolling,
+ * DOM order diverges from logical item order. Screen readers traverse
+ * DOM order, so items are encountered in a nonsensical sequence.
+ *
+ * This utility reorders DOM children to match logical index order.
+ * Called on scroll idle — zero cost during scroll, single lightweight
+ * reflow when idle (items are position:absolute, no geometry change).
+ *
+ * **Minimal-move approach**: walks sorted elements and current DOM children
+ * in parallel.  Elements already at the correct position are never touched
+ * — preserving browser :hover state and avoiding CSS transition replays
+ * on elements under the cursor.
+ *
+ * Used by: core renderer, grid renderer, masonry renderer, and core.ts
+ * inlined render path.
+ */
+/**
+ * Reorder DOM children so they follow logical data-index order.
+ *
+ * Only elements that are out of position are moved via `insertBefore`.
+ * Elements already in the correct spot are skipped entirely (no DOM
+ * mutation), which preserves :hover state and CSS transitions.
+ *
+ * @param container  - The DOM element that holds rendered items
+ * @param keys       - The rendered Map's keys (item indices)
+ * @param getElement - Lookup function: index → HTMLElement | undefined
+ */
+export const sortRenderedDOM = (container, keys, getElement) => {
+    // Collect and sort logical indices
+    const sorted = Array.from(keys).sort((a, b) => a - b);
+    if (sorted.length <= 1)
+        return;
+    // Resolve to elements in target (sorted) order, skip undefined
+    const elements = [];
+    for (let i = 0; i < sorted.length; i++) {
+        const el = getElement(sorted[i]);
+        if (el)
+            elements.push(el);
+    }
+    if (elements.length <= 1)
+        return;
+    // Walk sorted elements against current DOM children in parallel.
+    // `cursor` tracks our position in the DOM child list.
+    // For each target element:
+    //   - if it matches the cursor → already in place, advance cursor
+    //   - if not → insertBefore(cursor) to put it in the right spot
+    let cursor = container.firstChild;
+    for (let i = 0; i < elements.length; i++) {
+        const el = elements[i];
+        if (el === cursor) {
+            // Already in the correct position — skip, no DOM mutation
+            cursor = cursor.nextSibling;
+        }
+        else {
+            // Out of place — move it before the current cursor position.
+            // insertBefore(el, null) is equivalent to appendChild.
+            container.insertBefore(el, cursor);
+        }
+    }
+};