vlist 2.0.0 → 2.0.2

package/dist/plugins/scrollbar/controller.js

@@ -1,574 +0,0 @@
-/**
- * vlist - Scroll Controller
- * Handles both native scrolling and manual wheel-based scrolling for compressed lists
- *
- * When compression is active (large lists exceeding browser height limits),
- * we switch from native scrolling to manual wheel event handling.
- * This allows smooth scrolling through millions of items.
- */
-// =============================================================================
-// Velocity Tracker (Circular Buffer)
-// =============================================================================
-/** Number of samples in circular buffer (avoids array allocation on every update) */
-const VELOCITY_SAMPLE_COUNT = 8;
-/** Minimum samples needed before velocity readings are considered reliable */
-const MIN_RELIABLE_SAMPLES = 3;
-/**
- * Maximum time gap (ms) between samples before the buffer is considered stale.
- * After a pause longer than this, previous samples no longer represent the
- * current scroll gesture — we reset and start measuring fresh.
- * Set below the idle timeout (150ms) so stale detection triggers before idle.
- */
-const STALE_GAP_MS = 100;
-const createVelocityTracker = (initialPosition = 0) => {
-    // Pre-allocate sample array to avoid allocation during scrolling
-    const samples = new Array(VELOCITY_SAMPLE_COUNT);
-    for (let i = 0; i < VELOCITY_SAMPLE_COUNT; i++) {
-        samples[i] = { position: 0, time: 0 };
-    }
-    return {
-        velocity: 0,
-        lastPosition: initialPosition,
-        lastTime: performance.now(),
-        samples,
-        sampleIndex: 0,
-        sampleCount: 0,
-    };
-};
-const updateVelocityTracker = (tracker, newPosition) => {
-    const now = performance.now();
-    const timeDelta = now - tracker.lastTime;
-    if (timeDelta === 0)
-        return tracker;
-    // Stale gap detection: if too much time has passed since the last sample,
-    // the previous measurements belong to a different scroll gesture.
-    // Reset the buffer and record this position as the new baseline.
-    // Velocity stays at 0 (unreliable) until MIN_RELIABLE_SAMPLES accumulate.
-    if (timeDelta > STALE_GAP_MS) {
-        tracker.sampleCount = 0;
-        tracker.sampleIndex = 0;
-        tracker.velocity = 0;
-        // Record baseline — first real velocity will be computed on the next update
-        const baseline = tracker.samples[0];
-        baseline.position = newPosition;
-        baseline.time = now;
-        tracker.sampleIndex = 1;
-        tracker.sampleCount = 1;
-        tracker.lastPosition = newPosition;
-        tracker.lastTime = now;
-        return tracker;
-    }
-    // Write to current slot in circular buffer (no allocation)
-    const currentSample = tracker.samples[tracker.sampleIndex];
-    currentSample.position = newPosition;
-    currentSample.time = now;
-    // Advance index (wrap around)
-    tracker.sampleIndex = (tracker.sampleIndex + 1) % VELOCITY_SAMPLE_COUNT;
-    tracker.sampleCount = Math.min(tracker.sampleCount + 1, VELOCITY_SAMPLE_COUNT);
-    // Calculate average velocity from samples (only when we have enough data)
-    if (tracker.sampleCount >= 2) {
-        const oldestIndex = (tracker.sampleIndex - tracker.sampleCount + VELOCITY_SAMPLE_COUNT) %
-            VELOCITY_SAMPLE_COUNT;
-        const oldest = tracker.samples[oldestIndex];
-        const totalDistance = newPosition - oldest.position;
-        const totalTime = now - oldest.time;
-        tracker.velocity = totalTime > 0 ? totalDistance / totalTime : 0;
-    }
-    // sampleCount < 2: keep velocity at 0 (not enough data yet)
-    // Update position/time baseline (mutate in place to avoid allocation)
-    tracker.lastPosition = newPosition;
-    tracker.lastTime = now;
-    return tracker;
-};
-/** Check if the velocity tracker has accumulated enough samples for reliable readings */
-const isVelocityTrackerReliable = (tracker) => tracker.sampleCount >= MIN_RELIABLE_SAMPLES;
-// =============================================================================
-// Scroll Controller Factory
-// =============================================================================
-/**
- * Create a scroll controller for a viewport element
- *
- * Supports two modes:
- * 1. Native scrolling (default) - uses browser's built-in scroll
- * 2. Compressed scrolling - manual wheel handling for large lists
- */
-export const createScrollController = (viewport, config = {}) => {
-    const { wheel = true, sensitivity = 1, smoothing = false, idleTimeout: idleMs = 150, onScroll, onIdle, scrollElement, horizontal = false, } = config;
-    const windowMode = !!scrollElement;
-    // State
-    let scrollPosition = 0;
-    let maxScroll = 0;
-    let containerHeight = windowMode
-        ? horizontal
-            ? window.innerWidth
-            : window.innerHeight
-        : horizontal
-            ? viewport.clientWidth
-            : viewport.clientHeight;
-    let compressed = config.compressed ?? false;
-    let compression = config.compression;
-    let velocityTracker = createVelocityTracker();
-    let isScrolling = false;
-    let idleTimeout = null;
-    // =============================================================================
-    // Native Scroll Handling
-    // =============================================================================
-    const handleNativeScrollRaw = () => {
-        const newPosition = horizontal ? viewport.scrollLeft : viewport.scrollTop;
-        const direction = newPosition >= scrollPosition ? "down" : "up";
-        velocityTracker = updateVelocityTracker(velocityTracker, newPosition);
-        scrollPosition = newPosition;
-        if (onScroll) {
-            onScroll({
-                scrollTop: scrollPosition,
-                direction,
-                velocity: velocityTracker.velocity,
-            });
-        }
-        // Idle detection
-        scheduleIdleCheck();
-    };
-    // M1: RAF-throttle native scroll to guarantee at most one processing per frame
-    const handleNativeScroll = rafThrottle(handleNativeScrollRaw);
-    // =============================================================================
-    // Window Scroll Handling
-    // =============================================================================
-    const handleWindowScrollRaw = () => {
-        // Compute list-relative scroll position from the viewport's bounding rect.
-        // When the list's top edge is at the window's top, rect.top = 0, scrollTop = 0.
-        // When the list has scrolled 500px past, rect.top = -500, scrollTop = 500.
-        const rect = viewport.getBoundingClientRect();
-        const newPosition = horizontal
-            ? Math.max(0, -rect.left)
-            : Math.max(0, -rect.top);
-        const direction = newPosition >= scrollPosition ? "down" : "up";
-        velocityTracker = updateVelocityTracker(velocityTracker, newPosition);
-        scrollPosition = newPosition;
-        if (!isScrolling) {
-            isScrolling = true;
-        }
-        if (onScroll) {
-            onScroll({
-                scrollTop: scrollPosition,
-                direction,
-                velocity: velocityTracker.velocity,
-            });
-        }
-        // Idle detection
-        scheduleIdleCheck();
-    };
-    const handleWindowScroll = rafThrottle(handleWindowScrollRaw);
-    // =============================================================================
-    // Compressed (Manual) Scroll Handling
-    // =============================================================================
-    /** Block wheel events (used in native mode when wheel is disabled) */
-    const blockWheel = (event) => {
-        event.preventDefault();
-    };
-    /**
-     * Translate vertical wheel (deltaY) into horizontal scroll in native mode.
-     * Trackpad deltaX already causes native horizontal scroll, so only remap
-     * deltaY when there is no deltaX. This keeps trackpad gestures natural
-     * while letting a regular mouse wheel drive horizontal scrolling.
-     */
-    const handleHorizontalWheel = (event) => {
-        if (event.deltaX)
-            return; // native horizontal scroll handles it
-        event.preventDefault();
-        viewport.scrollLeft += event.deltaY;
-    };
-    const handleWheel = (event) => {
-        if (!compressed)
-            return;
-        event.preventDefault();
-        const delta = (horizontal ? event.deltaX || event.deltaY : event.deltaY) * sensitivity;
-        let newPosition = scrollPosition + delta;
-        // Apply smoothing if enabled
-        if (smoothing) {
-            newPosition = scrollPosition + delta * 0.3;
-        }
-        // Clamp to valid range
-        newPosition = Math.max(0, Math.min(newPosition, maxScroll));
-        if (newPosition !== scrollPosition) {
-            const previousPosition = scrollPosition;
-            const direction = newPosition >= previousPosition ? "down" : "up";
-            velocityTracker = updateVelocityTracker(velocityTracker, newPosition);
-            scrollPosition = newPosition;
-            if (!isScrolling) {
-                isScrolling = true;
-            }
-            if (onScroll) {
-                onScroll({
-                    scrollTop: scrollPosition,
-                    direction,
-                    velocity: velocityTracker.velocity,
-                });
-            }
-            // Idle detection
-            scheduleIdleCheck();
-        }
-    };
-    // =============================================================================
-    // Idle Detection
-    // =============================================================================
-    const scheduleIdleCheck = () => {
-        if (idleTimeout) {
-            clearTimeout(idleTimeout);
-        }
-        idleTimeout = setTimeout(() => {
-            isScrolling = false;
-            // Reset velocity tracker with current scroll position to avoid
-            // calculating huge velocity on next scroll event
-            velocityTracker = createVelocityTracker(scrollPosition);
-            if (onIdle) {
-                onIdle();
-            }
-        }, idleMs);
-    };
-    // =============================================================================
-    // Mode Switching
-    // =============================================================================
-    const enableCompression = (newCompression) => {
-        if (compressed)
-            return;
-        compressed = true;
-        compression = newCompression;
-        maxScroll = newCompression.virtualSize - containerHeight;
-        // In window mode, compression is purely mathematical — the content div
-        // height is set to the virtual height by vlist.ts, and the browser scrolls
-        // natively. No overflow changes or wheel interception needed.
-        if (windowMode)
-            return;
-        // Remove native scroll listener and cancel pending RAF
-        handleNativeScroll.cancel();
-        viewport.removeEventListener("scroll", handleNativeScroll);
-        // Remove native-mode wheel listeners
-        if (!wheel) {
-            viewport.removeEventListener("wheel", blockWheel);
-        }
-        else if (horizontal) {
-            viewport.removeEventListener("wheel", handleHorizontalWheel);
-        }
-        // Switch to overflow hidden
-        if (horizontal) {
-            viewport.style.overflowX = "hidden";
-        }
-        else {
-            viewport.style.overflow = "hidden";
-        }
-        // Add wheel listener (only if wheel is enabled)
-        if (wheel) {
-            viewport.addEventListener("wheel", handleWheel, { passive: false });
-        }
-        // Convert current scroll position to compressed equivalent
-        const nativePos = horizontal ? viewport.scrollLeft : viewport.scrollTop;
-        if (nativePos > 0) {
-            const nativeMax = horizontal
-                ? (compression?.actualSize ?? viewport.scrollWidth)
-                : (compression?.actualSize ?? viewport.scrollHeight);
-            const ratio = nativePos / nativeMax;
-            scrollPosition = ratio * maxScroll;
-        }
-        // Reset native scroll
-        if (horizontal) {
-            viewport.scrollLeft = 0;
-        }
-        else {
-            viewport.scrollTop = 0;
-        }
-    };
-    const disableCompression = () => {
-        if (!compressed)
-            return;
-        compressed = false;
-        // In window mode, nothing to revert — compression was purely mathematical
-        if (windowMode) {
-            compression = undefined;
-            return;
-        }
-        // Remove wheel listener
-        viewport.removeEventListener("wheel", handleWheel);
-        // Restore native scrolling
-        if (horizontal) {
-            viewport.style.overflowX = "auto";
-        }
-        else {
-            viewport.style.overflow = "auto";
-        }
-        // Add native scroll listener
-        viewport.addEventListener("scroll", handleNativeScroll, { passive: true });
-        // Re-add native-mode wheel listeners
-        if (!wheel) {
-            viewport.addEventListener("wheel", blockWheel, { passive: false });
-        }
-        else if (horizontal) {
-            viewport.addEventListener("wheel", handleHorizontalWheel, {
-                passive: false,
-            });
-        }
-        // Restore scroll position
-        if (compression && scrollPosition > 0) {
-            const ratio = scrollPosition / maxScroll;
-            const restoredPos = ratio * (compression.actualSize - containerHeight);
-            if (horizontal) {
-                viewport.scrollLeft = restoredPos;
-            }
-            else {
-                viewport.scrollTop = restoredPos;
-            }
-        }
-        compression = undefined;
-    };
-    // =============================================================================
-    // Public API
-    // =============================================================================
-    const getScrollTop = () => {
-        // In window mode, scrollPosition is always the source of truth
-        // (viewport.scrollTop is 0 because overflow is visible).
-        // In compressed mode, scrollPosition is manually tracked.
-        // In native container mode, read from the DOM.
-        if (windowMode || compressed)
-            return scrollPosition;
-        return horizontal ? viewport.scrollLeft : viewport.scrollTop;
-    };
-    const scrollTo = (position, smooth = false) => {
-        const clampedPosition = Math.max(0, Math.min(position, maxScroll || Infinity));
-        if (windowMode) {
-            // Scroll the window so the desired list position is at the top of the viewport.
-            // listDocumentTop = the list's absolute position in the document.
-            const rect = viewport.getBoundingClientRect();
-            if (horizontal) {
-                const listDocumentLeft = rect.left + window.scrollX;
-                window.scrollTo({
-                    left: listDocumentLeft + clampedPosition,
-                    behavior: smooth ? "smooth" : "auto",
-                });
-            }
-            else {
-                const listDocumentTop = rect.top + window.scrollY;
-                window.scrollTo({
-                    top: listDocumentTop + clampedPosition,
-                    behavior: smooth ? "smooth" : "auto",
-                });
-            }
-            // The window scroll event will fire and update scrollPosition via handleWindowScroll
-        }
-        else if (compressed) {
-            if (clampedPosition === scrollPosition)
-                return;
-            const previousPosition = scrollPosition;
-            const direction = clampedPosition >= previousPosition ? "down" : "up";
-            velocityTracker = updateVelocityTracker(velocityTracker, clampedPosition);
-            scrollPosition = clampedPosition;
-            if (!isScrolling) {
-                isScrolling = true;
-            }
-            if (onScroll) {
-                onScroll({
-                    scrollTop: scrollPosition,
-                    direction,
-                    velocity: velocityTracker.velocity,
-                });
-            }
-            scheduleIdleCheck();
-        }
-        else {
-            if (horizontal) {
-                viewport.scrollTo({
-                    left: clampedPosition,
-                    behavior: smooth ? "smooth" : "auto",
-                });
-            }
-            else {
-                viewport.scrollTo({
-                    top: clampedPosition,
-                    behavior: smooth ? "smooth" : "auto",
-                });
-            }
-        }
-    };
-    const scrollBy = (delta) => {
-        scrollTo(getScrollTop() + delta);
-    };
-    const isAtTop = () => {
-        return getScrollTop() <= 0;
-    };
-    const isAtBottom = (threshold = 0) => {
-        const scrollTop = getScrollTop();
-        // In window mode or compressed mode, use maxScroll (explicitly tracked).
-        // In native container mode, derive from the viewport's scroll geometry.
-        const max = windowMode || compressed
-            ? maxScroll
-            : horizontal
-                ? viewport.scrollWidth - viewport.clientWidth
-                : viewport.scrollHeight - viewport.clientHeight;
-        return scrollTop >= max - threshold;
-    };
-    const getScrollPercentage = () => {
-        const scrollTop = getScrollTop();
-        const max = windowMode || compressed
-            ? maxScroll
-            : horizontal
-                ? viewport.scrollWidth - viewport.clientWidth
-                : viewport.scrollHeight - viewport.clientHeight;
-        if (max <= 0)
-            return 0;
-        return Math.min(1, Math.max(0, scrollTop / max));
-    };
-    const updateConfig = (newConfig) => {
-        if (newConfig.compression) {
-            compression = newConfig.compression;
-            maxScroll = compression.virtualSize - containerHeight;
-        }
-    };
-    const isCompressedMode = () => compressed;
-    const getVelocityValue = () => Math.abs(velocityTracker.velocity);
-    const getIsTracking = () => isVelocityTrackerReliable(velocityTracker);
-    const getIsScrolling = () => isScrolling;
-    const getIsWindowMode = () => windowMode;
-    const updateContainerHeightFn = (height) => {
-        containerHeight = height;
-        // Recompute maxScroll if we have compression or are in window mode
-        if (compression) {
-            maxScroll = compression.virtualSize - containerHeight;
-        }
-        else if (windowMode) {
-            // In window mode without compression, maxScroll is derived from
-            // the content div height. vlist.ts calls updateConfig with compression
-            // when totalHeight changes, so this path handles the non-compressed case.
-            // We can't compute it here without knowing totalHeight, so leave it
-            // and let updateConfig handle it when compression state is updated.
-        }
-    };
-    const destroy = () => {
-        if (idleTimeout) {
-            clearTimeout(idleTimeout);
-        }
-        if (windowMode) {
-            handleWindowScroll.cancel();
-            window.removeEventListener("scroll", handleWindowScroll);
-        }
-        else {
-            handleNativeScroll.cancel();
-            viewport.removeEventListener("scroll", handleNativeScroll);
-            viewport.removeEventListener("wheel", handleWheel);
-            viewport.removeEventListener("wheel", blockWheel);
-            viewport.removeEventListener("wheel", handleHorizontalWheel);
-        }
-    };
-    // =============================================================================
-    // Initialization
-    // =============================================================================
-    if (windowMode) {
-        // Window scroll mode — listen to window, don't manage viewport overflow
-        if (compressed && compression) {
-            maxScroll = compression.virtualSize - containerHeight;
-        }
-        window.addEventListener("scroll", handleWindowScroll, { passive: true });
-    }
-    else if (compressed && compression) {
-        // Start in compressed mode
-        maxScroll = compression.virtualSize - containerHeight;
-        if (horizontal) {
-            viewport.style.overflowX = "hidden";
-        }
-        else {
-            viewport.style.overflow = "hidden";
-        }
-        if (wheel) {
-            viewport.addEventListener("wheel", handleWheel, { passive: false });
-        }
-    }
-    else {
-        // Start in native scroll mode
-        if (horizontal) {
-            viewport.style.overflowX = "auto";
-            viewport.style.overflowY = "hidden";
-        }
-        else {
-            viewport.style.overflow = "auto";
-        }
-        viewport.addEventListener("scroll", handleNativeScroll, { passive: true });
-        if (!wheel) {
-            viewport.addEventListener("wheel", blockWheel, { passive: false });
-        }
-        else if (horizontal) {
-            viewport.addEventListener("wheel", handleHorizontalWheel, {
-                passive: false,
-            });
-        }
-    }
-    return {
-        getScrollTop,
-        scrollTo,
-        scrollBy,
-        isAtTop,
-        isAtBottom,
-        getScrollPercentage,
-        getVelocity: getVelocityValue,
-        isTracking: getIsTracking,
-        isScrolling: getIsScrolling,
-        updateConfig,
-        enableCompression,
-        disableCompression,
-        isCompressed: isCompressedMode,
-        isWindowMode: getIsWindowMode,
-        updateContainerHeight: updateContainerHeightFn,
-        destroy,
-    };
-};
-// =============================================================================
-// Utility Functions
-// =============================================================================
-/**
- * Throttle scroll handler using requestAnimationFrame
- */
-export const rafThrottle = (fn) => {
-    let frameId = null;
-    let lastArgs = null;
-    const throttled = (...args) => {
-        lastArgs = args;
-        if (frameId === null) {
-            frameId = requestAnimationFrame(() => {
-                frameId = null;
-                if (lastArgs) {
-                    fn(...lastArgs);
-                }
-            });
-        }
-    };
-    throttled.cancel = () => {
-        if (frameId !== null) {
-            cancelAnimationFrame(frameId);
-            frameId = null;
-        }
-    };
-    return throttled;
-};
-/**
- * Check if scroll position is at bottom
- */
-export const isAtBottom = (scrollTop, scrollHeight, clientHeight, threshold = 0) => {
-    return scrollTop + clientHeight >= scrollHeight - threshold;
-};
-/**
- * Check if scroll position is at top
- */
-export const isAtTop = (scrollTop, threshold = 0) => {
-    return scrollTop <= threshold;
-};
-/**
- * Get scroll percentage (0-1)
- */
-export const getScrollPercentage = (scrollTop, scrollHeight, clientHeight) => {
-    const maxScroll = scrollHeight - clientHeight;
-    if (maxScroll <= 0)
-        return 0;
-    return Math.min(1, Math.max(0, scrollTop / maxScroll));
-};
-/**
- * Check if a range is visible in the scroll viewport
- */
-export const isRangeVisible = (rangeStart, rangeEnd, visibleStart, visibleEnd) => {
-    return rangeStart <= visibleEnd && rangeEnd >= visibleStart;
-};

package/dist/plugins/scrollbar/index.js

@@ -1,6 +0,0 @@
-/**
- * vlist v2 — Scrollbar Plugin
- */
-export { scrollbar } from "./plugin";
-export { createScrollbar, } from "./scrollbar";
-export { createScrollController, rafThrottle, isAtBottom, isAtTop, getScrollPercentage, isRangeVisible, } from "./controller";

package/dist/plugins/scrollbar/plugin.js

@@ -1,93 +0,0 @@
-/**
- * vlist v2 — Scrollbar Plugin
- *
- * Replaces the native scrollbar with a custom, cross-browser consistent scrollbar.
- * Priority 15 — runs after layout plugins (10) but before selection (50).
- *
- * Uses the v1 scrollbar UI component directly — it's standalone DOM/events code
- * with no framework dependencies. This plugin wires it into the v2 lifecycle:
- * - onAfterScroll hook → update thumb position
- * - onResize hook → update thumb/track bounds
- * - destroy → cleanup
- */
-import { createScrollbar } from "./scrollbar";
-// =============================================================================
-// Factory
-// =============================================================================
-export function scrollbar(config) {
-    let sb = null;
-    let engineState;
-    let sizeCache;
-    let lastBoundsTotal = 0;
-    let lastBoundsContainer = 0;
-    return {
-        name: "scrollbar",
-        priority: 15,
-        setup(ctx) {
-            const { dom, config: resolvedConfig } = ctx;
-            const { classPrefix, horizontal } = resolvedConfig;
-            engineState = ctx.getState();
-            sizeCache = ctx.sizeCache;
-            // Indirect callback — scale plugin can redirect via registerMethod
-            let scrollCb = (position) => {
-                if (horizontal)
-                    dom.viewport.scrollLeft = position;
-                else
-                    dom.viewport.scrollTop = position;
-            };
-            ctx.registerMethod("_scrollbar:setCallback", (cb) => { scrollCb = cb; });
-            sb = createScrollbar(dom.viewport, (position) => { scrollCb(position); }, config, classPrefix, horizontal, dom.root);
-            dom.viewport.classList.add(`${classPrefix}-viewport--custom-scrollbar`);
-            if (config?.gutter) {
-                dom.viewport.classList.add(`${classPrefix}-viewport--gutter`);
-            }
-            // Defer initial bounds update — containerSize may be 0 during setup
-            // since the viewport hasn't been laid out yet. The resize observer
-            // will fire with the correct size after first paint.
-            // Skip if compressed — the scale plugin owns bounds in that case.
-            queueMicrotask(() => {
-                if (!engineState.isCompressed) {
-                    sb?.updateBounds(sizeCache.getTotalSize(), engineState.containerSize);
-                }
-            });
-            // Expose scrollbar instance for cross-plugin coordination (scale plugin)
-            ctx.registerMethod("_scrollbar:getInstance", () => sb);
-            ctx.registerDestroyHandler(() => {
-                sb?.destroy();
-                sb = null;
-                dom.viewport.classList.remove(`${classPrefix}-viewport--custom-scrollbar`);
-                if (config?.gutter) {
-                    dom.viewport.classList.remove(`${classPrefix}-viewport--gutter`);
-                }
-            });
-        },
-        hooks: {
-            onAfterScroll(scrollPosition) {
-                if (!engineState.isCompressed) {
-                    const total = sizeCache.getTotalSize();
-                    const container = engineState.containerSize;
-                    if (total !== lastBoundsTotal || container !== lastBoundsContainer) {
-                        lastBoundsTotal = total;
-                        lastBoundsContainer = container;
-                        sb?.updateBounds(total, container);
-                    }
-                }
-                sb?.updatePosition(scrollPosition);
-                sb?.show();
-            },
-            onResize() {
-                if (!engineState.isCompressed) {
-                    const total = sizeCache.getTotalSize();
-                    const container = engineState.containerSize;
-                    lastBoundsTotal = total;
-                    lastBoundsContainer = container;
-                    sb?.updateBounds(total, container);
-                }
-            },
-        },
-        destroy() {
-            sb?.destroy();
-            sb = null;
-        },
-    };
-}