vlist 2.0.0 → 2.0.2

package/dist/rendering/viewport.js

@@ -1,268 +0,0 @@
-/**
- * vlist - Virtual Scrolling Core
- * Pure functions for virtual scroll calculations
- *
- * Compression support is NOT imported here — it's injected via
- * CompressionState parameters. When compression is inactive
- * (the common case), all calculations use simple size-cache math
- * with zero dependency on the compression module.
- *
- * This keeps the builder core lightweight. The withCompression feature
- * and the monolithic createVList entry point import compression
- * separately and pass the state in.
- */
-/**
- * A "no compression" state for lists that don't need it.
- * Used by the builder core when withCompression is not installed.
- */
-export const NO_COMPRESSION = {
-    isCompressed: false,
-    actualSize: 0,
-    virtualSize: 0,
-    ratio: 1,
-};
-/**
- * Create a trivial compression state from a size cache.
- * No compression logic — just reads the total height.
- * For use when the full compression module is not loaded.
- */
-export const getSimpleCompressionState = (_totalItems, sizeCache) => {
-    const h = sizeCache.getTotalSize();
-    return {
-        isCompressed: false,
-        actualSize: h,
-        virtualSize: h,
-        ratio: 1,
-    };
-};
-// =============================================================================
-// Simple (non-compressed) range calculation
-// =============================================================================
-/**
- * Calculate visible range using size cache lookups.
- * Fast path for lists that don't need compression (< ~350 000 items at 48px).
- * Mutates `out` to avoid allocation on the scroll hot path.
- */
-export const simpleVisibleRange = (scrollPosition, containerHeight, sizeCache, totalItems, _compression, out) => {
-    if (totalItems === 0 || containerHeight === 0) {
-        out.start = 0;
-        out.end = -1;
-        return out;
-    }
-    const start = sizeCache.indexAtOffset(scrollPosition);
-    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;
-};
-/**
- * Calculate render range (adds overscan around visible range).
- * This function is compression-agnostic — works for both paths.
- * Mutates `out` to avoid allocation on the scroll hot path.
- */
-export const calculateRenderRange = (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;
-};
-/**
- * Simple scroll-to-index calculation (non-compressed).
- * Uses size cache offsets directly.
- */
-export const simpleScrollToIndex = (index, sizeCache, containerHeight, totalItems, _compression, align) => {
-    if (totalItems === 0)
-        return 0;
-    const safeIndex = Math.max(0, Math.min(index, totalItems - 1));
-    const itemOffset = sizeCache.getOffset(safeIndex);
-    const itemSize = sizeCache.getSize(safeIndex);
-    const totalHeight = sizeCache.getTotalSize();
-    const maxScroll = Math.max(0, totalHeight - containerHeight);
-    let position;
-    switch (align) {
-        case "center":
-            position = itemOffset - containerHeight / 2 + itemSize / 2;
-            break;
-        case "end":
-            position = itemOffset - containerHeight + itemSize;
-            break;
-        case "start":
-        default:
-            position = itemOffset;
-            break;
-    }
-    return Math.max(0, Math.min(position, maxScroll));
-};
-// =============================================================================
-// Calculate total content height
-// =============================================================================
-/**
- * Calculate total content height.
- * Uses compression's virtualSize when compressed, raw height otherwise.
- */
-export const calculateTotalSize = (_totalItems, sizeCache, compression) => {
-    if (compression && compression.isCompressed) {
-        return compression.virtualSize;
-    }
-    return sizeCache.getTotalSize();
-};
-/**
- * Calculate actual total size (without compression cap)
- */
-export const calculateActualSize = (_totalItems, sizeCache) => {
-    return sizeCache.getTotalSize();
-};
-/**
- * Calculate the offset (translateY) for an item
- * For non-compressed lists only
- */
-export const calculateItemOffset = (index, sizeCache) => {
-    return sizeCache.getOffset(index);
-};
-// =============================================================================
-// Scroll helpers
-// =============================================================================
-/**
- * Clamp scroll position to valid range
- */
-export const clampScrollPosition = (scrollPosition, totalHeight, containerHeight) => {
-    const maxScroll = Math.max(0, totalHeight - containerHeight);
-    return Math.max(0, Math.min(scrollPosition, maxScroll));
-};
-/**
- * Determine scroll direction
- */
-export const getScrollDirection = (currentScrollTop, previousScrollTop) => {
-    return currentScrollTop >= previousScrollTop ? "down" : "up";
-};
-// =============================================================================
-// Viewport State
-// =============================================================================
-/**
- * Create initial viewport state.
- *
- * Accepts an optional `visibleRangeFn` so that compression-aware callers
- * can inject the compressed version. Defaults to `simpleVisibleRange`.
- */
-export const createViewportState = (containerHeight, sizeCache, totalItems, overscan, compression, visibleRangeFn = simpleVisibleRange) => {
-    const visibleRange = { start: 0, end: 0 };
-    const renderRange = { start: 0, end: 0 };
-    visibleRangeFn(0, containerHeight, sizeCache, totalItems, compression, visibleRange);
-    calculateRenderRange(visibleRange, overscan, totalItems, renderRange);
-    return {
-        scrollPosition: 0,
-        containerSize: containerHeight,
-        totalSize: compression.virtualSize,
-        actualSize: compression.actualSize,
-        isCompressed: compression.isCompressed,
-        compressionRatio: compression.ratio,
-        visibleRange,
-        renderRange,
-    };
-};
-/**
- * Update viewport state after scroll.
- * Mutates state in place for performance on the scroll hot path.
- */
-export const updateViewportState = (state, scrollPosition, sizeCache, totalItems, overscan, compression, visibleRangeFn = simpleVisibleRange) => {
-    visibleRangeFn(scrollPosition, state.containerSize, sizeCache, totalItems, compression, state.visibleRange);
-    calculateRenderRange(state.visibleRange, overscan, totalItems, state.renderRange);
-    state.scrollPosition = scrollPosition;
-    return state;
-};
-/**
- * Update viewport state when container resizes.
- * Mutates state in place for performance.
- */
-export const updateViewportSize = (state, containerHeight, sizeCache, totalItems, overscan, compression, visibleRangeFn = simpleVisibleRange) => {
-    visibleRangeFn(state.scrollPosition, containerHeight, sizeCache, totalItems, compression, state.visibleRange);
-    calculateRenderRange(state.visibleRange, overscan, totalItems, state.renderRange);
-    state.containerSize = containerHeight;
-    state.totalSize = compression.virtualSize;
-    state.actualSize = compression.actualSize;
-    state.isCompressed = compression.isCompressed;
-    state.compressionRatio = compression.ratio;
-    return state;
-};
-/**
- * Update viewport state when total items changes.
- * Mutates state in place for performance.
- */
-export const updateViewportItems = (state, sizeCache, totalItems, overscan, compression, visibleRangeFn = simpleVisibleRange) => {
-    visibleRangeFn(state.scrollPosition, state.containerSize, sizeCache, totalItems, compression, state.visibleRange);
-    calculateRenderRange(state.visibleRange, overscan, totalItems, state.renderRange);
-    state.totalSize = compression.virtualSize;
-    state.actualSize = compression.actualSize;
-    state.isCompressed = compression.isCompressed;
-    state.compressionRatio = compression.ratio;
-    return state;
-};
-// =============================================================================
-// calculateScrollToIndex (public API)
-// =============================================================================
-/**
- * Calculate scroll position to bring an index into view.
- *
- * Accepts an optional `scrollToIndexFn` so that compression-aware callers
- * can inject the compressed version. Defaults to `simpleScrollToIndex`.
- */
-export const calculateScrollToIndex = (index, sizeCache, containerHeight, totalItems, align = "start", compression, scrollToIndexFn = simpleScrollToIndex) => {
-    return scrollToIndexFn(index, sizeCache, containerHeight, totalItems, compression, align);
-};
-// =============================================================================
-// Range Utilities
-// =============================================================================
-/**
- * Check if two ranges are equal
- */
-export const rangesEqual = (a, b) => {
-    return a.start === b.start && a.end === b.end;
-};
-/**
- * Check if an index is within a range
- */
-export const isInRange = (index, range) => {
-    return index >= range.start && index <= range.end;
-};
-/**
- * Get the count of items in a range
- */
-export const getRangeCount = (range) => {
-    if (range.end < range.start)
-        return 0;
-    return range.end - range.start + 1;
-};
-/**
- * Create an array of indices from a range
- */
-export const rangeToIndices = (range) => {
-    const indices = [];
-    for (let i = range.start; i <= range.end; i++) {
-        indices.push(i);
-    }
-    return indices;
-};
-/**
- * Calculate which indices need to be added/removed when range changes
- */
-export const diffRanges = (oldRange, newRange) => {
-    const add = [];
-    const remove = [];
-    for (let i = oldRange.start; i <= oldRange.end; i++) {
-        if (i < newRange.start || i > newRange.end) {
-            remove.push(i);
-        }
-    }
-    for (let i = newRange.start; i <= newRange.end; i++) {
-        if (i < oldRange.start || i > oldRange.end) {
-            add.push(i);
-        }
-    }
-    return { add, remove };
-};

package/dist/types.js

@@ -1,5 +0,0 @@
-/**
- * vlist - Core Types
- * Minimal, clean interfaces for the virtual list
- */
-export {};

package/dist/utils/padding.js

@@ -1,49 +0,0 @@
-/**
- * vlist/utils — Padding Resolution
- * Shared helpers for resolving the CSS-shorthand padding config into
- * concrete pixel values. Used by core (to apply CSS) and by plugins
- * (to subtract cross-axis padding from container dimensions).
- */
-// =============================================================================
-// Resolve All Sides
-// =============================================================================
-/** Zero padding singleton — avoids allocation when padding is undefined */
-const ZERO = { top: 0, right: 0, bottom: 0, left: 0 };
-/**
- * Resolve a padding config into all four sides.
- *
- * - `undefined`        → { 0, 0, 0, 0 }
- * - `number`           → equal on all sides
- * - `[v, h]`           → top/bottom = v, left/right = h
- * - `[t, r, b, l]`     → per-side (CSS order)
- *
- * Returns a frozen singleton for the zero case (no allocation).
- */
-export const resolvePadding = (padding) => {
-    if (padding == null)
-        return ZERO;
-    if (typeof padding === "number") {
-        return padding === 0 ? ZERO : { top: padding, right: padding, bottom: padding, left: padding };
-    }
-    if (padding.length === 2) {
-        const [v, h] = padding;
-        return (v === 0 && h === 0) ? ZERO : { top: v, right: h, bottom: v, left: h };
-    }
-    const [top, right, bottom, left] = padding;
-    return (top === 0 && right === 0 && bottom === 0 && left === 0)
-        ? ZERO
-        : { top, right, bottom, left };
-};
-// =============================================================================
-// Axis Helpers
-// =============================================================================
-/**
- * Total padding along the main axis (scroll direction).
- * Vertical → top + bottom. Horizontal → left + right.
- */
-export const mainAxisPaddingFrom = (p, isHorizontal) => isHorizontal ? p.left + p.right : p.top + p.bottom;
-/**
- * Total padding along the cross axis (perpendicular to scroll).
- * Vertical → left + right. Horizontal → top + bottom.
- */
-export const crossAxisPaddingFrom = (p, isHorizontal) => isHorizontal ? p.top + p.bottom : p.left + p.right;

package/dist/utils/stats.js

@@ -1,124 +0,0 @@
-// src/utils/stats.ts
-// Pure computation module for scroll statistics.
-// Tracks velocity (current + running average), computes cumulative item count
-// and progress from scroll position using geometric mapping.
-//
-// No DOM access, no RAF, no side effects — purely functional state tracker.
-import { MAX_VIRTUAL_SIZE } from "../constants";
-// =============================================================================
-// Constants
-// =============================================================================
-const MAX_VELOCITY = 50;
-const MIN_VELOCITY = 0.1;
-// =============================================================================
-// Factory
-// =============================================================================
-/**
- * Create a stats tracker.
- *
- * All inputs are provided via callbacks so the tracker always reflects
- * the latest values without needing to be recreated when the list changes.
- *
- * ```ts
- * const stats = createStats({
- *   getScrollPosition: () => list.getScrollPosition(),
- *   getTotal: () => items.length,
- *   getItemSize: () => ITEM_HEIGHT,
- *   getContainerSize: () => containerEl.clientHeight,
- * })
- *
- * const { progress, itemCount, total } = stats.getState()
- * ```
- */
-export function createStats(config) {
-    // ───────────────────────────────────────────────────────────────────────────
-    // Velocity state
-    // ───────────────────────────────────────────────────────────────────────────
-    let currentVelocity = 0;
-    let velocitySum = 0;
-    let velocityCount = 0;
-    function getVelocityAverage() {
-        return velocityCount > 0 ? velocitySum / velocityCount : 0;
-    }
-    function onVelocity(velocity) {
-        currentVelocity = velocity;
-        if (velocity > MIN_VELOCITY && velocity < MAX_VELOCITY) {
-            velocitySum += velocity;
-            velocityCount++;
-        }
-    }
-    // ───────────────────────────────────────────────────────────────────────────
-    // Geometric item count
-    // ───────────────────────────────────────────────────────────────────────────
-    /**
-     * Compute cumulative item count from scroll position geometrically.
-     *
-     * scrollPosition is the DOM scrollTop/scrollLeft — in compressed/scaled
-     * mode this is the virtual (compressed) scroll position. We map it back
-     * to real item indices using the same linear mapping vlist uses internally:
-     *
-     *   columns         = getColumns() ?? 1
-     *   totalRows       = ceil(total / columns)
-     *   totalActualSize = totalRows × itemSize
-     *   totalVirtualSize = min(totalActualSize, MAX_VIRTUAL_SIZE)
-     *   maxVirtualScroll = totalVirtualSize − containerSize
-     *   maxActualScroll  = totalActualSize − containerSize
-     *   ratio            = maxActualScroll / maxVirtualScroll
-     *   actualOffset     = scrollPosition × ratio
-     *   visibleRows      = ceil((actualOffset + containerSize) / itemSize)
-     *   itemCount        = min(visibleRows × columns, total)
-     *
-     * containerSize is provided by the caller (clientHeight for vertical,
-     * clientWidth for horizontal).
-     *
-     * Using scroll-range ratio (not size ratio) ensures that at max scroll
-     * the end of the viewport aligns exactly with the last row/column.
-     * For grid/masonry, rows are converted to items via the column multiplier.
-     */
-    function getItemCount() {
-        const total = config.getTotal();
-        if (total === 0)
-            return 0;
-        const itemSize = config.getItemSize();
-        if (itemSize <= 0)
-            return 0;
-        const containerSize = config.getContainerSize();
-        if (containerSize <= 0)
-            return 0;
-        const scrollPosition = config.getScrollPosition();
-        // For grid/masonry layouts, vlist virtualizes rows — each row holds
-        // `columns` items. Convert total items → total rows for the geometric
-        // mapping, then convert visible rows back to items at the end.
-        const columns = typeof config.getColumns === "function" ? config.getColumns() : 1;
-        const totalRows = Math.ceil(total / columns);
-        // Map virtual scroll position back to actual content offset.
-        // Use scroll-range ratio so maxScroll maps exactly to the last row.
-        const totalActualSize = totalRows * itemSize;
-        const totalVirtualSize = Math.min(totalActualSize, MAX_VIRTUAL_SIZE);
-        const maxVirtualScroll = totalVirtualSize - containerSize;
-        const maxActualScroll = totalActualSize - containerSize;
-        const ratio = maxVirtualScroll > 0 ? maxActualScroll / maxVirtualScroll : 1;
-        const actualOffset = scrollPosition * ratio;
-        const lastVisibleRow = Math.ceil((actualOffset + containerSize) / itemSize);
-        return Math.min(lastVisibleRow * columns, total);
-    }
-    // ───────────────────────────────────────────────────────────────────────────
-    // Public API
-    // ───────────────────────────────────────────────────────────────────────────
-    function getState() {
-        const total = config.getTotal();
-        const itemCount = getItemCount();
-        const progress = total > 0 ? Math.min(100, Math.max(0, (itemCount / total) * 100)) : 0;
-        return {
-            progress,
-            velocity: currentVelocity,
-            velocityAvg: getVelocityAverage(),
-            itemCount,
-            total,
-        };
-    }
-    return {
-        getState,
-        onVelocity,
-    };
-}