vlist 2.0.0 → 2.0.1

package/dist/plugins/autosize/plugin.js

@@ -1,185 +0,0 @@
-/**
- * vlist v2 — Autosize Plugin
- *
- * Enables dynamic item measurement via ResizeObserver for items with
- * unknown sizes. Items are rendered without an explicit main-axis size,
- * measured once by ResizeObserver, then pinned to their measured size.
- *
- * Priority 5 — runs before grid/masonry (10) so the measured cache
- * is in place before layout plugins consume it.
- *
- * Requires: `item.estimatedHeight` or `item.estimatedWidth` in config
- */
-// =============================================================================
-// Factory
-// =============================================================================
-export function autosize(config) {
-    let gap = config?.gap ?? 0;
-    let observer = null;
-    let storedCtx = null;
-    let engineState;
-    let hz;
-    let sizeProp;
-    let estimatedSize;
-    const measuredSizes = new Map();
-    const elementToIndex = new WeakMap();
-    let pendingScrollDelta = 0;
-    let pendingContentSizeUpdate = false;
-    const BOTTOM_THRESHOLD = 2;
-    function sizeFn(index) {
-        return measuredSizes.get(index) ?? estimatedSize;
-    }
-    function isAtBottom() {
-        const viewport = storedCtx.dom.viewport;
-        const maxScroll = viewport.scrollHeight - viewport.clientHeight;
-        return maxScroll > 0 && engineState.scrollPosition >= maxScroll - BOTTOM_THRESHOLD;
-    }
-    function snapToBottom() {
-        const viewport = storedCtx.dom.viewport;
-        void viewport.scrollHeight;
-        const maxScroll = viewport.scrollHeight - viewport.clientHeight;
-        if (maxScroll > engineState.scrollPosition) {
-            storedCtx.scrollTo(maxScroll);
-        }
-    }
-    function updateContentSize() {
-        storedCtx.updateContentSize(storedCtx.sizeCache.getTotalSize());
-    }
-    return {
-        name: "autosize",
-        priority: 5,
-        setup(ctx) {
-            storedCtx = ctx;
-            engineState = ctx.getState();
-            hz = ctx.config.horizontal;
-            sizeProp = hz ? "width" : "height";
-            if (gap === 0)
-                gap = ctx.config.gap;
-            // Read estimated size from the current sizeCache before replacing it.
-            // The initial cache already has gap baked in — read the raw spec size.
-            estimatedSize = typeof ctx.rawSizeSpec === "function"
-                ? ctx.rawSizeSpec(0) + gap
-                : ctx.rawSizeSpec + gap;
-            // Replace the fixed sizeCache with a variable one backed by measurements
-            ctx.setSizeConfig(sizeFn);
-            if (gap > 0) {
-                const orig = ctx.sizeCache.getTotalSize;
-                ctx.sizeCache.getTotalSize = () => {
-                    const t = orig();
-                    return t > 0 ? t - gap : 0;
-                };
-            }
-            // ResizeObserver for measuring items
-            observer = new ResizeObserver((entries) => {
-                if (engineState.destroyed || !storedCtx)
-                    return;
-                let hasNewMeasurements = false;
-                const firstVisible = engineState.startIndex;
-                for (const entry of entries) {
-                    const el = entry.target;
-                    const index = elementToIndex.get(el);
-                    if (index === undefined)
-                        continue;
-                    // Verify element wasn't recycled to a different item
-                    if (el.getAttribute("data-index") !== String(index)) {
-                        observer.unobserve(el);
-                        continue;
-                    }
-                    if (measuredSizes.has(index))
-                        continue;
-                    const boxSize = entry.borderBoxSize[0];
-                    if (!boxSize)
-                        continue;
-                    const newSize = hz ? boxSize.inlineSize : boxSize.blockSize;
-                    if (newSize <= 0)
-                        continue;
-                    const sizeWithGap = newSize + gap;
-                    const oldSize = estimatedSize;
-                    measuredSizes.set(index, sizeWithGap);
-                    hasNewMeasurements = true;
-                    if (index < firstVisible && sizeWithGap !== oldSize) {
-                        pendingScrollDelta += sizeWithGap - oldSize;
-                    }
-                    observer.unobserve(el);
-                    // Pin the element to its measured size
-                    el.style[sizeProp] = `${newSize}px`;
-                }
-                if (!hasNewMeasurements)
-                    return;
-                const atBottom = isAtBottom();
-                // Rebuild prefix sums with new measurements
-                ctx.rebuildSizeCache();
-                // Apply scroll correction for items above viewport
-                if (pendingScrollDelta) {
-                    ctx.scrollTo(engineState.scrollPosition + pendingScrollDelta);
-                    pendingScrollDelta = 0;
-                }
-                const isScrolling = engineState.scrollDirection !== 0;
-                const nearEnd = engineState.totalItems > 0
-                    && engineState.prevRangeEnd >= engineState.totalItems - 1;
-                if (atBottom || nearEnd || !isScrolling) {
-                    updateContentSize();
-                    pendingContentSizeUpdate = false;
-                    if (atBottom) {
-                        snapToBottom();
-                    }
-                }
-                else {
-                    pendingContentSizeUpdate = true;
-                }
-                ctx.forceRender();
-            });
-            // Public methods
-            ctx.registerMethod("isMeasured", (index) => measuredSizes.has(index));
-            ctx.registerMethod("setMeasuredSize", (index, size) => {
-                measuredSizes.set(index, size);
-            });
-            ctx.registerMethod("getMeasuredCount", () => measuredSizes.size);
-            // Cleanup
-            ctx.registerDestroyHandler(() => {
-                if (observer) {
-                    observer.disconnect();
-                    observer = null;
-                }
-            });
-        },
-        hooks: {
-            onCommit(state) {
-                if (!observer || !storedCtx)
-                    return;
-                for (let i = 0; i < state.visibleCount; i++) {
-                    const idx = state.visibleIndices[i];
-                    if (measuredSizes.has(idx))
-                        continue;
-                    const el = storedCtx.getRenderedElement(idx);
-                    if (!el)
-                        continue;
-                    // Clear the explicit size set by phase2Commit so
-                    // ResizeObserver can measure the natural content size.
-                    el.style[sizeProp] = "";
-                    elementToIndex.set(el, idx);
-                    observer.observe(el);
-                }
-            },
-            onIdle() {
-                if (!pendingContentSizeUpdate || !storedCtx)
-                    return;
-                const atBottom = isAtBottom();
-                updateContentSize();
-                pendingContentSizeUpdate = false;
-                if (atBottom) {
-                    snapToBottom();
-                    storedCtx.forceRender();
-                }
-            },
-        },
-        destroy() {
-            if (observer) {
-                observer.disconnect();
-                observer = null;
-            }
-            measuredSizes.clear();
-            storedCtx = null;
-        },
-    };
-}

package/dist/plugins/grid/index.js

@@ -1,5 +0,0 @@
-/**
- * vlist v2 — Grid Plugin
- */
-export { grid } from "./plugin";
-export { createGridLayout, } from "./layout";

package/dist/plugins/grid/layout.js

@@ -1,275 +0,0 @@
-/**
- * vlist - Grid Layout
- * Pure O(1) calculations for mapping between flat item indices and grid positions.
- *
- * The grid transforms a flat list into rows:
- *   Items:  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
- *   Grid (columns=4):
- *     Row 0: [0, 1, 2, 3]
- *     Row 1: [4, 5, 6, 7]
- *     Row 2: [8, 9]          ← partially filled last row
- *
- * All operations are O(1) — integer division and modulo only.
- */
-// =============================================================================
-// Factory
-// =============================================================================
-/**
- * Create a GridLayout instance.
- *
- * @param config - Grid configuration (columns, gap, optional isHeaderFn)
- * @returns GridLayout with O(1) mapping functions (or groups-aware if isHeaderFn provided)
- */
-export const createGridLayout = (config) => {
-    let columns = Math.max(1, Math.floor(config.columns));
-    let gap = config.gap ?? 0;
-    let isHeaderFn = config.isHeaderFn;
-    // Reusable position object to avoid allocation on hot paths
-    const reusablePosition = { row: 0, col: 0 };
-    /**
-     * Total rows for a given item count.
-     * When isHeaderFn is provided, headers force new rows.
-     */
-    const getTotalRows = (totalItems) => {
-        if (totalItems <= 0)
-            return 0;
-        if (!isHeaderFn) {
-            return Math.ceil(totalItems / columns);
-        }
-        // Groups-aware calculation
-        let row = 0;
-        let colInRow = 0;
-        let headerCount = 0;
-        for (let i = 0; i < totalItems; i++) {
-            if (isHeaderFn(i)) {
-                headerCount++;
-                // Header: start new row if not at beginning
-                if (colInRow) {
-                    row++;
-                    colInRow = 0;
-                }
-                // Header occupies its own row
-                row++;
-                colInRow = 0;
-            }
-            else {
-                // Regular item
-                colInRow++;
-                if (colInRow >= columns) {
-                    row++;
-                    colInRow = 0;
-                }
-            }
-        }
-        // Add final row if there are items in it
-        if (colInRow) {
-            row++;
-        }
-        return row;
-    };
-    /**
-     * Get row/col position for a flat item index.
-     * Reuses a single object to reduce GC pressure on scroll hot path.
-     */
-    const getPosition = (itemIndex) => {
-        reusablePosition.row = getRow(itemIndex);
-        reusablePosition.col = getCol(itemIndex);
-        return reusablePosition;
-    };
-    /**
-     * Get row index for a flat item index — O(1)
-     * When isHeaderFn is provided, headers force new rows and span all columns.
-     */
-    const getRow = (itemIndex) => {
-        if (!isHeaderFn) {
-            return Math.floor(itemIndex / columns);
-        }
-        // Groups-aware calculation
-        let row = 0;
-        let colInRow = 0;
-        for (let i = 0; i <= itemIndex; i++) {
-            const isHeader = isHeaderFn(i);
-            if (isHeader) {
-                // Header: start new row if not at beginning
-                if (colInRow) {
-                    row++;
-                    colInRow = 0;
-                }
-                // Header occupies its own row
-                if (i === itemIndex) {
-                    return row;
-                }
-                row++;
-                colInRow = 0;
-            }
-            else {
-                // Regular item
-                if (i === itemIndex) {
-                    return row;
-                }
-                colInRow++;
-                if (colInRow >= columns) {
-                    row++;
-                    colInRow = 0;
-                }
-            }
-        }
-        console.warn(`⚠️ getRow(${itemIndex}) fell through - returning ${row}`);
-        return row;
-    };
-    /**
-     * Get column index for a flat item index — O(1)
-     * Headers always return col 0 when isHeaderFn is provided.
-     */
-    const getCol = (itemIndex) => {
-        if (!isHeaderFn) {
-            return itemIndex % columns;
-        }
-        // Headers always at column 0
-        if (isHeaderFn(itemIndex)) {
-            return 0;
-        }
-        // Calculate column for regular items
-        let colInRow = 0;
-        for (let i = 0; i <= itemIndex; i++) {
-            const isHeader = isHeaderFn(i);
-            if (isHeader) {
-                // Header: reset column counter
-                colInRow = 0;
-            }
-            else {
-                if (i === itemIndex) {
-                    return colInRow;
-                }
-                colInRow++;
-                if (colInRow >= columns) {
-                    colInRow = 0;
-                }
-            }
-        }
-        return colInRow;
-    };
-    /**
-     * Get the flat item range [start, end] for a range of rows.
-     *
-     * rowStart and rowEnd are inclusive row indices.
-     * The returned end is clamped to totalItems - 1.
-     * When isHeaderFn is provided, this accounts for headers disrupting the grid flow.
-     */
-    const getItemRange = (rowStart, rowEnd, totalItems) => {
-        if (totalItems <= 0)
-            return { start: 0, end: -1 };
-        if (!isHeaderFn) {
-            // Simple O(1) calculation for regular grids
-            const start = Math.max(0, rowStart * columns);
-            const end = Math.min(totalItems - 1, (rowEnd + 1) * columns - 1);
-            return { start, end };
-        }
-        // Groups-aware calculation - find items that fall in the row range
-        let start = -1;
-        let end = -1;
-        let currentRow = 0;
-        let colInRow = 0;
-        for (let i = 0; i < totalItems; i++) {
-            const isHeader = isHeaderFn(i);
-            if (isHeader) {
-                // Header: start new row if not at beginning
-                if (colInRow) {
-                    currentRow++;
-                    colInRow = 0;
-                }
-                // Check if this header's row is in range
-                if (currentRow >= rowStart && currentRow <= rowEnd) {
-                    if (start < 0)
-                        start = i;
-                    end = i;
-                }
-                currentRow++;
-                colInRow = 0;
-            }
-            else {
-                // Regular item
-                if (currentRow >= rowStart && currentRow <= rowEnd) {
-                    if (start < 0)
-                        start = i;
-                    end = i;
-                }
-                colInRow++;
-                if (colInRow >= columns) {
-                    currentRow++;
-                    colInRow = 0;
-                }
-            }
-            // Early exit if we're past the end row
-            if (currentRow > rowEnd && !colInRow) {
-                break;
-            }
-        }
-        // If no items found in range, return empty range
-        if (start < 0) {
-            return { start: 0, end: -1 };
-        }
-        return { start, end };
-    };
-    /**
-     * Get the flat item index from a row and column.
-     * Returns -1 if the position is out of bounds.
-     */
-    const getItemIndex = (row, col, totalItems) => {
-        if (col < 0 || col >= columns)
-            return -1;
-        const index = row * columns + col;
-        if (index < 0 || index >= totalItems)
-            return -1;
-        return index;
-    };
-    /**
-     * Calculate column width given the container's inner width.
-     * Distributes gaps evenly: totalGapWidth = (columns - 1) * gap
-     * columnWidth = (containerWidth - totalGapWidth) / columns
-     */
-    const getColumnWidth = (containerWidth) => {
-        const totalGap = (columns - 1) * gap;
-        return Math.max(0, (containerWidth - totalGap) / columns);
-    };
-    /**
-     * Calculate the X pixel offset for a given column index.
-     * offset = col * (columnWidth + gap)
-     */
-    const getColumnOffset = (col, containerWidth) => {
-        const colWidth = getColumnWidth(containerWidth);
-        return col * (colWidth + gap);
-    };
-    /**
-     * Update grid configuration without recreating the layout.
-     * This is more efficient than destroying and recreating.
-     */
-    const updateConfig = (newConfig) => {
-        if (newConfig.columns !== undefined) {
-            columns = Math.max(1, Math.floor(newConfig.columns));
-        }
-        if (newConfig.gap !== undefined) {
-            gap = newConfig.gap;
-        }
-        if (newConfig.isHeaderFn !== undefined) {
-            isHeaderFn = newConfig.isHeaderFn;
-        }
-    };
-    return {
-        get columns() {
-            return columns;
-        },
-        get gap() {
-            return gap;
-        },
-        update: updateConfig,
-        getTotalRows,
-        getPosition,
-        getRow,
-        getCol,
-        getItemRange,
-        getItemIndex,
-        getColumnWidth,
-        getColumnOffset,
-    };
-};