vlist 2.0.0 → 2.0.1

package/dist/plugins/scale/plugin.js

@@ -1,507 +0,0 @@
-/**
- * vlist v2 — Scale Plugin
- *
- * Enables support for 1M+ item lists by compressing the scroll space
- * when total content size exceeds the browser's ~16.7M pixel limit.
- *
- * Priority 20 — runs after layout plugins (10), before selection (50).
- *
- * When compressed:
- * - Native scroll is disabled (overflow: hidden)
- * - Custom wheel handler with lerp smooth scroll
- * - Custom touch handler with momentum
- * - Items positioned relative to viewport via onCalculate hook
- * - Fallback scrollbar created if no scrollbar plugin present
- *
- * Uses v1's rendering/scale.ts pure math functions directly.
- */
-import { getCompressionState, calculateCompressedVisibleRange, calculateCompressedItemPosition, calculateCompressedScrollToIndex, } from "../../rendering/scale";
-import { createScrollbar } from "../scrollbar/scrollbar";
-import { SCROLL_EASING, SCROLL_DURATION } from "../../constants";
-// =============================================================================
-// Constants
-// =============================================================================
-const LERP_FACTOR = 0.65;
-const SNAP_THRESHOLD = 0.5;
-const SCROLL_SPEED_MULTIPLIER = 1.7;
-const TOUCH_DECELERATION = 0.95;
-const TOUCH_MIN_VELOCITY = 0.1;
-const TOUCH_VELOCITY_SAMPLES = 5;
-const TOUCH_VELOCITY_WINDOW = 100;
-// =============================================================================
-// Factory
-// =============================================================================
-export function scale(config) {
-    const force = config?.force ?? false;
-    let engineState;
-    let sizeCache;
-    let viewport;
-    let horizontal;
-    let overscan;
-    let compression = {
-        isCompressed: false,
-        actualSize: 0,
-        virtualSize: 0,
-        ratio: 1,
-    };
-    let compressedActive = false;
-    let slack = 0;
-    let fallbackScrollbar = null;
-    let ownsScrollbar = false;
-    // Virtual scroll state
-    let virtualScrollPosition = 0;
-    let targetScrollPosition = 0;
-    let smoothScrollId = null;
-    let easedScrollId = null;
-    // Touch state
-    let touchStartPos = 0;
-    let touchScrollStart = 0;
-    let momentumId = null;
-    // Pre-allocated ring buffer for velocity sampling (zero-alloc hot path)
-    const sampleTimes = new Float64Array(TOUCH_VELOCITY_SAMPLES);
-    const samplePositions = new Float64Array(TOUCH_VELOCITY_SAMPLES);
-    let sampleCount = 0;
-    let sampleHead = 0;
-    // Reusable range object for compressed visible range calc
-    const compRange = { start: 0, end: -1 };
-    // Track item count so onCalculate can detect data mutations
-    let lastCheckedTotal = -1;
-    let storedCtx = null;
-    function getMaxScroll() {
-        return Math.max(0, compression.virtualSize + slack - engineState.containerSize);
-    }
-    function computeSlack() {
-        if (compression.virtualSize <= 0)
-            return 0;
-        return Math.max(0, engineState.containerSize * (1 - compression.ratio));
-    }
-    function updateCompression(ctx) {
-        const totalItems = engineState.totalItems;
-        compression = getCompressionState(totalItems, sizeCache, force);
-        if (compression.isCompressed && !compressedActive) {
-            activateCompression(ctx);
-        }
-        else if (!compression.isCompressed && compressedActive) {
-            deactivateCompression(ctx);
-        }
-        if (compression.isCompressed) {
-            slack = computeSlack();
-            engineState.isCompressed = true;
-            engineState.compressionRatio = compression.ratio;
-            ctx.updateContentSize(compression.virtualSize + slack);
-            if (fallbackScrollbar) {
-                fallbackScrollbar.updateBounds(compression.virtualSize + slack, engineState.containerSize);
-            }
-        }
-    }
-    // Wheel/touch handlers — stored so we can remove them
-    let wheelHandler = null;
-    let touchStartHandler = null;
-    let touchMoveHandler = null;
-    let touchEndHandler = null;
-    let nativeScrollReset = null;
-    function applyVirtualScroll(pos) {
-        virtualScrollPosition = pos;
-        targetScrollPosition = pos;
-        engineState.prevScrollPosition = engineState.scrollPosition;
-        engineState.scrollPosition = pos;
-        engineState.scrollDirection = pos > engineState.prevScrollPosition ? 1 : -1;
-        storedCtx.forceRender();
-    }
-    function cancelAnimations() {
-        if (smoothScrollId !== null) {
-            cancelAnimationFrame(smoothScrollId);
-            smoothScrollId = null;
-        }
-        if (easedScrollId !== null) {
-            cancelAnimationFrame(easedScrollId);
-            easedScrollId = null;
-        }
-    }
-    function setVirtualPosition(pos) {
-        cancelAnimations();
-        applyVirtualScroll(Math.max(0, Math.min(pos, getMaxScroll())));
-    }
-    function easedScrollTo(target, duration, easing = SCROLL_EASING) {
-        cancelAnimations();
-        const clampedTarget = Math.max(0, Math.min(target, getMaxScroll()));
-        const from = virtualScrollPosition;
-        if (Math.abs(clampedTarget - from) < SNAP_THRESHOLD) {
-            applyVirtualScroll(clampedTarget);
-            return;
-        }
-        const start = performance.now();
-        const tick = (now) => {
-            const t = Math.min((now - start) / duration, 1);
-            applyVirtualScroll(from + (clampedTarget - from) * easing(t));
-            if (t < 1)
-                easedScrollId = requestAnimationFrame(tick);
-            else
-                easedScrollId = null;
-        };
-        easedScrollId = requestAnimationFrame(tick);
-    }
-    function activateCompression(ctx) {
-        compressedActive = true;
-        engineState.isCompressed = true;
-        const scrollProp = horizontal ? "scrollLeft" : "scrollTop";
-        const overflowProp = horizontal ? "overflowX" : "overflow";
-        // Capture native position before disabling
-        const nativePos = viewport[scrollProp];
-        viewport.style[overflowProp] = "hidden";
-        viewport[scrollProp] = 0;
-        if (nativePos > 0) {
-            virtualScrollPosition = nativePos;
-            targetScrollPosition = nativePos;
-            engineState.scrollPosition = nativePos;
-        }
-        slack = computeSlack();
-        // Lerp smooth scroll tick
-        const smoothScrollTick = () => {
-            const diff = targetScrollPosition - virtualScrollPosition;
-            const maxScroll = getMaxScroll();
-            if (Math.abs(diff) < SNAP_THRESHOLD) {
-                virtualScrollPosition = Math.max(0, Math.min(targetScrollPosition, maxScroll));
-                targetScrollPosition = virtualScrollPosition;
-                smoothScrollId = null;
-            }
-            else {
-                virtualScrollPosition += diff * LERP_FACTOR;
-                virtualScrollPosition = Math.max(0, Math.min(virtualScrollPosition, maxScroll));
-                smoothScrollId = requestAnimationFrame(smoothScrollTick);
-            }
-            engineState.prevScrollPosition = engineState.scrollPosition;
-            engineState.scrollPosition = virtualScrollPosition;
-            engineState.scrollDirection = virtualScrollPosition > engineState.prevScrollPosition ? 1 : -1;
-            ctx.forceRender();
-        };
-        // Wheel handler
-        wheelHandler = (e) => {
-            e.preventDefault();
-            const maxScroll = getMaxScroll();
-            targetScrollPosition = Math.max(0, Math.min(targetScrollPosition + e.deltaY * compression.ratio * SCROLL_SPEED_MULTIPLIER, maxScroll));
-            if (smoothScrollId === null) {
-                smoothScrollId = requestAnimationFrame(smoothScrollTick);
-            }
-        };
-        viewport.addEventListener("wheel", wheelHandler, { passive: false });
-        // Touch handlers
-        const cancelMomentum = () => {
-            if (momentumId !== null) {
-                cancelAnimationFrame(momentumId);
-                momentumId = null;
-            }
-        };
-        touchStartHandler = (e) => {
-            cancelMomentum();
-            if (smoothScrollId !== null) {
-                cancelAnimationFrame(smoothScrollId);
-                smoothScrollId = null;
-            }
-            const touch = e.touches[0];
-            if (!touch)
-                return;
-            const y = horizontal ? touch.clientX : touch.clientY;
-            touchStartPos = y;
-            touchScrollStart = virtualScrollPosition;
-            sampleCount = 1;
-            sampleHead = 0;
-            sampleTimes[0] = performance.now();
-            samplePositions[0] = y;
-        };
-        touchMoveHandler = (e) => {
-            e.preventDefault();
-            const touch = e.touches[0];
-            if (!touch)
-                return;
-            const y = horizontal ? touch.clientX : touch.clientY;
-            const now = performance.now();
-            const slot = sampleCount < TOUCH_VELOCITY_SAMPLES ? sampleCount : sampleHead;
-            sampleTimes[slot] = now;
-            samplePositions[slot] = y;
-            if (sampleCount < TOUCH_VELOCITY_SAMPLES) {
-                sampleCount++;
-            }
-            else {
-                sampleHead = (sampleHead + 1) % TOUCH_VELOCITY_SAMPLES;
-            }
-            const delta = touchStartPos - y;
-            const maxScroll = getMaxScroll();
-            const newPos = Math.max(0, Math.min(touchScrollStart + delta * compression.ratio * SCROLL_SPEED_MULTIPLIER, maxScroll));
-            virtualScrollPosition = newPos;
-            targetScrollPosition = newPos;
-            engineState.prevScrollPosition = engineState.scrollPosition;
-            engineState.scrollPosition = newPos;
-            engineState.scrollDirection = newPos > engineState.prevScrollPosition ? 1 : -1;
-            ctx.forceRender();
-        };
-        touchEndHandler = () => {
-            const now = performance.now();
-            // Scan ring buffer for oldest/newest within velocity window (zero alloc)
-            let oldestTime = Infinity, oldestPos = 0;
-            let newestTime = -1, newestPos = 0;
-            let recentCount = 0;
-            for (let i = 0; i < sampleCount; i++) {
-                const idx = (sampleHead + i) % TOUCH_VELOCITY_SAMPLES;
-                const t = sampleTimes[idx];
-                if (now - t >= TOUCH_VELOCITY_WINDOW)
-                    continue;
-                recentCount++;
-                const p = samplePositions[idx];
-                if (t < oldestTime) {
-                    oldestTime = t;
-                    oldestPos = p;
-                }
-                if (t > newestTime) {
-                    newestTime = t;
-                    newestPos = p;
-                }
-            }
-            let velocity = 0;
-            if (recentCount >= 2) {
-                const dt = newestTime - oldestTime;
-                if (dt > 0)
-                    velocity = (oldestPos - newestPos) / dt;
-            }
-            sampleCount = 0;
-            sampleHead = 0;
-            if (Math.abs(velocity) < TOUCH_MIN_VELOCITY)
-                return;
-            let frameVelocity = velocity * 16;
-            const momentumTick = () => {
-                frameVelocity *= TOUCH_DECELERATION;
-                if (Math.abs(frameVelocity) < 0.5) {
-                    momentumId = null;
-                    return;
-                }
-                const maxScroll = getMaxScroll();
-                let newPos = virtualScrollPosition + frameVelocity;
-                newPos = Math.max(0, Math.min(newPos, maxScroll));
-                if ((newPos <= 0 && frameVelocity < 0) || (newPos >= maxScroll && frameVelocity > 0)) {
-                    virtualScrollPosition = newPos;
-                    targetScrollPosition = newPos;
-                    engineState.scrollPosition = newPos;
-                    ctx.forceRender();
-                    momentumId = null;
-                    return;
-                }
-                virtualScrollPosition = newPos;
-                targetScrollPosition = newPos;
-                engineState.prevScrollPosition = engineState.scrollPosition;
-                engineState.scrollPosition = newPos;
-                engineState.scrollDirection = newPos > engineState.prevScrollPosition ? 1 : -1;
-                ctx.forceRender();
-                momentumId = requestAnimationFrame(momentumTick);
-            };
-            momentumId = requestAnimationFrame(momentumTick);
-        };
-        viewport.addEventListener("touchstart", touchStartHandler, { passive: true });
-        viewport.addEventListener("touchmove", touchMoveHandler, { passive: false });
-        viewport.addEventListener("touchend", touchEndHandler, { passive: true });
-        viewport.addEventListener("touchcancel", touchEndHandler, { passive: true });
-        // Native scroll drift guard
-        nativeScrollReset = () => {
-            if (viewport[scrollProp] !== 0) {
-                viewport[scrollProp] = 0;
-            }
-        };
-        viewport.addEventListener("scroll", nativeScrollReset, { passive: true });
-        // Scroll callback used by both existing scrollbar plugin and fallback
-        const scrollbarCallback = (position) => {
-            virtualScrollPosition = position;
-            targetScrollPosition = position;
-            if (smoothScrollId !== null) {
-                cancelAnimationFrame(smoothScrollId);
-                smoothScrollId = null;
-            }
-            engineState.prevScrollPosition = engineState.scrollPosition;
-            engineState.scrollPosition = position;
-            engineState.scrollDirection = position > engineState.prevScrollPosition ? 1 : -1;
-            ctx.forceRender();
-        };
-        // If scrollbar plugin exists, redirect its callback and use its instance.
-        // Otherwise create a fallback scrollbar.
-        const setCallback = ctx.getMethod("_scrollbar:setCallback");
-        const getInstance = ctx.getMethod("_scrollbar:getInstance");
-        if (setCallback && getInstance) {
-            setCallback(scrollbarCallback);
-            const existing = getInstance();
-            if (existing) {
-                fallbackScrollbar = existing;
-                ownsScrollbar = false;
-                fallbackScrollbar.updateBounds(compression.virtualSize + slack, engineState.containerSize);
-            }
-        }
-        else if (!fallbackScrollbar) {
-            const classPrefix = ctx.config.classPrefix;
-            fallbackScrollbar = createScrollbar(viewport, scrollbarCallback, {}, classPrefix, horizontal, ctx.dom.root);
-            ownsScrollbar = true;
-            if (!viewport.classList.contains(`${classPrefix}-viewport--custom-scrollbar`)) {
-                viewport.classList.add(`${classPrefix}-viewport--custom-scrollbar`);
-            }
-            fallbackScrollbar.updateBounds(compression.virtualSize + slack, engineState.containerSize);
-        }
-    }
-    function deactivateCompression(ctx) {
-        compressedActive = false;
-        engineState.isCompressed = false;
-        engineState.compressionRatio = 1;
-        virtualScrollPosition = 0;
-        targetScrollPosition = 0;
-        sampleCount = 0;
-        sampleHead = 0;
-        cleanup();
-        const overflowProp = horizontal ? "overflowX" : "overflow";
-        viewport.style[overflowProp] = "auto";
-        slack = 0;
-        ctx.updateContentSize(sizeCache.getTotalSize());
-    }
-    function cleanup() {
-        if (smoothScrollId !== null) {
-            cancelAnimationFrame(smoothScrollId);
-            smoothScrollId = null;
-        }
-        if (easedScrollId !== null) {
-            cancelAnimationFrame(easedScrollId);
-            easedScrollId = null;
-        }
-        if (momentumId !== null) {
-            cancelAnimationFrame(momentumId);
-            momentumId = null;
-        }
-        if (wheelHandler) {
-            viewport.removeEventListener("wheel", wheelHandler);
-            wheelHandler = null;
-        }
-        if (touchStartHandler) {
-            viewport.removeEventListener("touchstart", touchStartHandler);
-            touchStartHandler = null;
-        }
-        if (touchMoveHandler) {
-            viewport.removeEventListener("touchmove", touchMoveHandler);
-            touchMoveHandler = null;
-        }
-        if (touchEndHandler) {
-            viewport.removeEventListener("touchend", touchEndHandler);
-            viewport.removeEventListener("touchcancel", touchEndHandler);
-            touchEndHandler = null;
-        }
-        if (nativeScrollReset) {
-            viewport.removeEventListener("scroll", nativeScrollReset);
-            nativeScrollReset = null;
-        }
-        if (fallbackScrollbar && ownsScrollbar) {
-            fallbackScrollbar.destroy();
-        }
-        fallbackScrollbar = null;
-        ownsScrollbar = false;
-        const scrollProp = horizontal ? "scrollLeft" : "scrollTop";
-        if (viewport && viewport[scrollProp] !== 0) {
-            viewport[scrollProp] = 0;
-        }
-    }
-    return {
-        name: "scale",
-        priority: 20,
-        setup(ctx) {
-            engineState = ctx.getState();
-            sizeCache = ctx.sizeCache;
-            viewport = ctx.dom.viewport;
-            horizontal = ctx.config.horizontal;
-            overscan = ctx.config.overscan;
-            storedCtx = ctx;
-            ctx.registerMethod("_updateCompressionMode", () => updateCompression(ctx));
-            // Register scroll get/set so scrollToIndex routes through us
-            ctx.setScrollFns(() => virtualScrollPosition, (actualOffset) => {
-                if (!compression.isCompressed || !compressedActive) {
-                    const prop = horizontal ? "scrollLeft" : "scrollTop";
-                    viewport[prop] = actualOffset;
-                    return;
-                }
-                cancelAnimations();
-                if (momentumId !== null) {
-                    cancelAnimationFrame(momentumId);
-                    momentumId = null;
-                }
-                const virtualPos = actualOffset * compression.ratio;
-                applyVirtualScroll(Math.max(0, Math.min(virtualPos, getMaxScroll())));
-            });
-            ctx.setScrollToIndexFn((index, align, behavior, duration, easing) => {
-                if (!compression.isCompressed || !compressedActive)
-                    return false;
-                const virtualPos = calculateCompressedScrollToIndex(index, sizeCache, engineState.containerSize, engineState.totalItems, compression, align);
-                if (behavior === "smooth") {
-                    easedScrollTo(virtualPos, duration ?? SCROLL_DURATION, easing);
-                }
-                else {
-                    setVirtualPosition(virtualPos);
-                }
-            });
-            // Initial compression check
-            updateCompression(ctx);
-            lastCheckedTotal = engineState.totalItems;
-            ctx.registerDestroyHandler(cleanup);
-        },
-        hooks: {
-            onCalculate(state) {
-                // Re-check compression when item count changes (data mutation)
-                if (state.totalItems !== lastCheckedTotal && storedCtx) {
-                    lastCheckedTotal = state.totalItems;
-                    updateCompression(storedCtx);
-                }
-                if (!compression.isCompressed || !compressedActive)
-                    return;
-                // Override phase1's buffer contents with compressed positioning.
-                // Phase1 ran with state.scrollPosition = virtualScrollPosition and
-                // sizeCache in actual space, so its range calc may be off.
-                // We recalculate using the compression-aware formula.
-                const totalItems = state.totalItems;
-                if (totalItems === 0 || state.containerSize <= 0) {
-                    state.visibleCount = 0;
-                    return;
-                }
-                // Calculate compressed visible range
-                calculateCompressedVisibleRange(state.scrollPosition, state.containerSize, sizeCache, totalItems, compression, compRange);
-                // Apply overscan
-                const renderStart = Math.max(0, compRange.start - overscan);
-                const renderEnd = Math.min(totalItems - 1, compRange.end + overscan);
-                // Fill buffers with compressed item positions
-                const count = Math.min(renderEnd - renderStart + 1, state.capacity);
-                state.visibleCount = count;
-                state.startIndex = renderStart;
-                for (let i = 0; i < count; i++) {
-                    const idx = renderStart + i;
-                    state.visibleIndices[i] = idx;
-                    state.visibleOffsets[i] = calculateCompressedItemPosition(idx, state.scrollPosition, sizeCache, totalItems, state.containerSize, compression);
-                    state.visibleSizes[i] = sizeCache.getSize(idx);
-                }
-                state.prevRangeStart = renderStart;
-                state.prevRangeEnd = renderEnd;
-            },
-            onAfterScroll(scrollPosition) {
-                if (fallbackScrollbar && compressedActive) {
-                    fallbackScrollbar.updatePosition(scrollPosition);
-                    fallbackScrollbar.show();
-                }
-            },
-            onResize() {
-                if (compressedActive) {
-                    slack = computeSlack();
-                    if (fallbackScrollbar) {
-                        fallbackScrollbar.updateBounds(compression.virtualSize + slack, engineState.containerSize);
-                    }
-                    // Clamp virtual scroll to new bounds
-                    const maxScroll = getMaxScroll();
-                    if (virtualScrollPosition > maxScroll) {
-                        virtualScrollPosition = maxScroll;
-                        targetScrollPosition = maxScroll;
-                        engineState.scrollPosition = maxScroll;
-                    }
-                }
-            },
-        },
-        destroy() {
-            cleanup();
-        },
-    };
-}