vlist 1.9.0 → 2.0.0

package/dist/plugins/autosize/plugin.js

@@ -0,0 +1,185 @@
+/**
+ * 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.d.ts

@@ -0,0 +1,7 @@
+/**
+ * vlist v2 — Grid Plugin
+ */
+export { grid, type GridPluginConfig } from "./plugin";
+export { createGridLayout, type GridConfigWithGroups, } from "./layout";
+export type { GridLayout, GridPosition, ItemRange, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/grid/index.js

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

package/dist/plugins/grid/layout.js

@@ -0,0 +1,275 @@
+/**
+ * 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,
+    };
+};

package/dist/plugins/grid/plugin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * vlist v2 — Grid Plugin
+ *
+ * Switches from list layout to a 2D grid with configurable columns and gap.
+ * Priority 10 — runs before selection (50) so layout is ready for other plugins.
+ *
+ * Architecture:
+ * - Replaces the default 1D render pipeline with a grid-aware render
+ * - Size cache operates in ROW space (each row has height = itemHeight + gap)
+ * - Visible range is calculated in row space, then expanded to flat item indices
+ * - Items are positioned with translate(colOffset, rowOffset)
+ *
+ * Restrictions:
+ * - Cannot be combined with masonry or table plugins
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../core/types";
+export interface GridPluginConfig {
+    columns: number;
+    gap?: number;
+}
+export declare function grid<T extends VListItem = VListItem>(config: GridPluginConfig): VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map