vlist 1.9.1 → 2.0.0

package/dist/plugins/masonry/renderer.js

@@ -0,0 +1,354 @@
+/**
+ * vlist - Masonry Renderer
+ * Renders items in a masonry/Pinterest-style layout with absolute positioning.
+ *
+ * Unlike grid renderer (which uses row-based positioning), masonry renderer
+ * positions each item using its pre-calculated coordinates from the layout phase.
+ *
+ * Key differences from grid:
+ * - Items positioned using cached x/y coordinates (not row/col calculations)
+ * - Each item can have different height/width
+ * - No row alignment - items flow into shortest column/row
+ * - Visibility determined by checking each item's absolute position
+ *
+ * Performance:
+ * - Element pooling avoids createElement cost
+ * - Template re-evaluation skipped when item data + state unchanged
+ * - O(1) Set-based visibility diffing (not O(n) .some())
+ * - Release grace period prevents boundary thrashing (hover blink, transition replay)
+ * - Released elements removed from DOM immediately
+ */
+import { sortRenderedDOM } from "../../rendering/sort";
+const createElementPool = (maxSize = 200) => {
+    const pool = [];
+    const acquire = () => {
+        const element = pool.pop();
+        if (element) {
+            return element;
+        }
+        const newElement = document.createElement("div");
+        newElement.setAttribute("role", "option");
+        return newElement;
+    };
+    const release = (element) => {
+        // Remove from DOM immediately — prevents blank divs in the container
+        element.remove();
+        if (pool.length < maxSize) {
+            element.className = "";
+            element.textContent = "";
+            element.removeAttribute("style");
+            element.removeAttribute("data-index");
+            element.removeAttribute("data-id");
+            element.removeAttribute("data-lane");
+            pool.push(element);
+        }
+    };
+    const clear = () => {
+        pool.length = 0;
+    };
+    return { acquire, release, clear };
+};
+// =============================================================================
+// Release grace period
+// =============================================================================
+/**
+ * Number of render cycles to keep an item alive after it leaves the visible set.
+ * Prevents boundary thrashing: items near the overscan edge aren't recycled
+ * on small scroll deltas, preserving DOM element hover state and avoiding
+ * CSS transition replays.
+ */
+const RELEASE_GRACE = 1;
+// =============================================================================
+// Masonry Renderer Factory
+// =============================================================================
+/**
+ * Create a masonry renderer for managing DOM elements with absolute positioning.
+ *
+ * @param itemsContainer - The DOM element that holds rendered items
+ * @param template - Item template function
+ * @param classPrefix - CSS class prefix
+ * @param isHorizontal - Whether layout is horizontal (scrolls right)
+ * @param totalItemsGetter - Optional getter for total item count (for aria-setsize)
+ * @param ariaIdPrefix - Optional unique prefix for element IDs (for aria-activedescendant)
+ */
+export const createMasonryRenderer = (itemsContainer, template, classPrefix, isHorizontal = false, totalItemsGetter, ariaIdPrefix, ariaPosInSetGetter, interactive) => {
+    const pool = createElementPool();
+    const rendered = new Map();
+    // ── Reusable visibleSet — cleared and repopulated each frame (no allocation) ──
+    const visibleSet = new Set();
+    // ── Frame counter for release grace period ──
+    let frameCounter = 0;
+    // Track aria-setsize to avoid redundant updates
+    let lastAriaSetSize = "";
+    let lastAriaTotal = -1;
+    // Reusable item state to avoid allocation per render
+    const reusableItemState = { selected: false, focused: false };
+    const getItemState = (isSelected, isFocused) => {
+        reusableItemState.selected = isSelected;
+        reusableItemState.focused = isFocused;
+        return reusableItemState;
+    };
+    // Pre-computed class names
+    const baseClass = `${classPrefix}-item ${classPrefix}-masonry-item`;
+    const groupHeaderClass = `${classPrefix}-group-header`;
+    const selectedClass = `${classPrefix}-item--selected`;
+    const focusedClass = `${classPrefix}-item--focused`;
+    /**
+     * Apply template result to element
+     */
+    const applyTemplate = (element, result) => {
+        if (typeof result === "string") {
+            element.innerHTML = result;
+        }
+        else {
+            element.replaceChildren(result);
+        }
+    };
+    /**
+     * Apply state-dependent classes
+     */
+    const applyClasses = (element, isSelected, isFocused) => {
+        element.classList.toggle(selectedClass, isSelected);
+        element.classList.toggle(focusedClass, isFocused);
+    };
+    const positionElement = (element, placement) => {
+        if (isHorizontal) {
+            element.style.transform = `translate(${Math.round(placement.y)}px, ${Math.round(placement.x)}px)`;
+        }
+        else {
+            element.style.transform = `translate(${Math.round(placement.x)}px, ${Math.round(placement.y)}px)`;
+        }
+    };
+    /**
+     * Apply size styles to an element.
+     */
+    const applySizeStyles = (element, placement) => {
+        if (isHorizontal) {
+            element.style.width = `${placement.size}px`;
+            element.style.height = `${placement.crossSize}px`;
+        }
+        else {
+            element.style.width = `${placement.crossSize}px`;
+            element.style.height = `${placement.size}px`;
+        }
+    };
+    /**
+     * Render a single masonry item (new element from pool)
+     */
+    const renderItem = (itemIndex, item, placement, isSelected, isFocused) => {
+        const element = pool.acquire();
+        const isGH = item.__groupHeader;
+        const state = getItemState(isSelected, isFocused);
+        // Group headers get a distinct class and role
+        element.className = isGH ? groupHeaderClass : baseClass;
+        // Set data attributes
+        element.dataset.index = String(itemIndex);
+        element.dataset.id = String(item.id);
+        element.dataset.lane = String(placement.lane);
+        if (isGH) {
+            element.setAttribute("role", "presentation");
+            element.removeAttribute("aria-selected");
+            element.removeAttribute("aria-setsize");
+            element.removeAttribute("aria-posinset");
+            element.removeAttribute("id");
+        }
+        else if (interactive !== false) {
+            element.setAttribute("role", "option");
+            element.ariaSelected = String(isSelected);
+            if (ariaIdPrefix) {
+                element.id = `${ariaIdPrefix}-item-${itemIndex}`;
+            }
+            if (totalItemsGetter) {
+                const total = totalItemsGetter();
+                if (total !== lastAriaTotal) {
+                    lastAriaTotal = total;
+                    lastAriaSetSize = String(total);
+                }
+                element.setAttribute("aria-setsize", lastAriaSetSize);
+                const posInSet = ariaPosInSetGetter ? ariaPosInSetGetter(itemIndex) : itemIndex + 1;
+                element.setAttribute("aria-posinset", String(posInSet));
+            }
+        }
+        else {
+            element.setAttribute("role", "listitem");
+            element.removeAttribute("aria-selected");
+            if (totalItemsGetter) {
+                const total = totalItemsGetter();
+                if (total !== lastAriaTotal) {
+                    lastAriaTotal = total;
+                    lastAriaSetSize = String(total);
+                }
+                element.setAttribute("aria-setsize", lastAriaSetSize);
+                const posInSet = ariaPosInSetGetter ? ariaPosInSetGetter(itemIndex) : itemIndex + 1;
+                element.setAttribute("aria-posinset", String(posInSet));
+            }
+        }
+        // Apply sizing
+        applySizeStyles(element, placement);
+        // Apply template
+        const result = template(item, itemIndex, state);
+        applyTemplate(element, result);
+        // Apply state classes and position
+        applyClasses(element, isSelected, isFocused);
+        positionElement(element, placement);
+        return {
+            element,
+            lastItemId: item.id,
+            lastSelected: isSelected,
+            lastFocused: isFocused,
+            lastY: placement.y,
+            lastX: placement.x,
+            lastSize: placement.size,
+            lastCrossSize: placement.crossSize,
+            lastSeenFrame: frameCounter,
+        };
+    };
+    /**
+     * Render visible items using pre-calculated placements.
+     *
+     * Performance characteristics:
+     * - Uses Set for O(1) visibility check (not O(n) .some())
+     * - Skips template re-evaluation when item id + state unchanged
+     * - Only updates position when coordinates changed
+     * - Release grace period prevents boundary thrashing
+     * - Released elements removed from DOM immediately
+     */
+    const render = (getItem, placements, selectedIds, focusedIndex) => {
+        frameCounter++;
+        // Repopulate reusable visibleSet — O(k) clear + O(k) add, no allocation
+        visibleSet.clear();
+        for (let i = 0; i < placements.length; i++) {
+            visibleSet.add(placements[i].index);
+        }
+        // Release items no longer visible, with grace period to prevent
+        // boundary thrashing (hover blink, CSS transition replay).
+        // Items that just left the visible set keep their DOM element for
+        // RELEASE_GRACE extra render cycles — if they re-enter, the same
+        // element is reused with :hover state intact.
+        for (const [index, tracked] of rendered) {
+            if (visibleSet.has(index)) {
+                tracked.lastSeenFrame = frameCounter;
+            }
+            else if (frameCounter - tracked.lastSeenFrame > RELEASE_GRACE) {
+                pool.release(tracked.element);
+                rendered.delete(index);
+            }
+        }
+        // DocumentFragment for batched DOM insertion of new elements
+        // (matches core renderer and grid renderer patterns)
+        let fragment = null;
+        // Render new or update existing items
+        for (let pi = 0; pi < placements.length; pi++) {
+            const placement = placements[pi];
+            const itemIndex = placement.index;
+            const item = getItem(itemIndex);
+            if (!item)
+                continue;
+            const isSelected = selectedIds.has(item.id);
+            const isFocused = itemIndex === focusedIndex;
+            const existing = rendered.get(itemIndex);
+            if (existing) {
+                // ── Fast path: skip work when nothing changed ──
+                const idChanged = existing.lastItemId !== item.id;
+                const selectedChanged = existing.lastSelected !== isSelected;
+                const focusedChanged = existing.lastFocused !== isFocused;
+                const posChanged = existing.lastY !== placement.y ||
+                    existing.lastX !== placement.x;
+                const sizeChanged = existing.lastSize !== placement.size ||
+                    existing.lastCrossSize !== placement.crossSize;
+                // Template re-evaluation only when item data actually changed
+                // (NOT on selection/focus change — that would destroy loaded images)
+                if (idChanged) {
+                    const state = getItemState(isSelected, isFocused);
+                    const result = template(item, itemIndex, state);
+                    applyTemplate(existing.element, result);
+                    // Update data attributes
+                    existing.element.dataset.id = String(item.id);
+                    existing.lastItemId = item.id;
+                    // Refresh aria-posinset when element is reused for a different item
+                    const isGH = item.__groupHeader;
+                    if (!isGH) {
+                        const posInSet = ariaPosInSetGetter ? ariaPosInSetGetter(itemIndex) : itemIndex + 1;
+                        existing.element.setAttribute("aria-posinset", String(posInSet));
+                    }
+                }
+                // Class + aria updates only when selection/focus changed
+                if (idChanged || selectedChanged || focusedChanged) {
+                    applyClasses(existing.element, isSelected, isFocused);
+                    existing.element.ariaSelected = String(isSelected);
+                    existing.lastSelected = isSelected;
+                    existing.lastFocused = isFocused;
+                }
+                // Size update when cross-axis or main-axis size changed (e.g. container resize)
+                if (sizeChanged) {
+                    applySizeStyles(existing.element, placement);
+                    existing.lastSize = placement.size;
+                    existing.lastCrossSize = placement.crossSize;
+                }
+                // Position update only when coordinates changed
+                if (posChanged) {
+                    positionElement(existing.element, placement);
+                    existing.lastY = placement.y;
+                    existing.lastX = placement.x;
+                }
+            }
+            else {
+                // Render new item — collect in fragment for batched insertion
+                const tracked = renderItem(itemIndex, item, placement, isSelected, isFocused);
+                if (!fragment)
+                    fragment = document.createDocumentFragment();
+                fragment.appendChild(tracked.element);
+                rendered.set(itemIndex, tracked);
+            }
+        }
+        // Single DOM insertion for all new elements — minimizes reflows
+        if (fragment)
+            itemsContainer.appendChild(fragment);
+    };
+    /**
+     * Clear all rendered items.
+     */
+    const clear = () => {
+        for (const tracked of rendered.values()) {
+            pool.release(tracked.element);
+        }
+        rendered.clear();
+        itemsContainer.innerHTML = "";
+    };
+    /**
+     * Destroy renderer and cleanup.
+     */
+    const destroy = () => {
+        clear();
+        pool.clear();
+    };
+    /**
+     * Reorder DOM children so they follow logical data-index order.
+     * Called on scroll idle for accessibility — screen readers traverse
+     * DOM order, not visual (transform) order. Since items are
+     * position:absolute, this has zero visual impact.
+     */
+    const sortDOM = () => {
+        sortRenderedDOM(itemsContainer, rendered.keys(), (key) => rendered.get(key)?.element);
+    };
+    const updateItemClasses = (index, isSelected, isFocused) => {
+        const existing = rendered.get(index);
+        if (!existing)
+            return;
+        const selectedChanged = existing.lastSelected !== isSelected;
+        const focusedChanged = existing.lastFocused !== isFocused;
+        if (selectedChanged || focusedChanged) {
+            applyClasses(existing.element, isSelected, isFocused);
+            existing.lastSelected = isSelected;
+            existing.lastFocused = isFocused;
+        }
+    };
+    return {
+        render,
+        getElement: (index) => rendered.get(index)?.element,
+        updateItemClasses,
+        sortDOM,
+        clear,
+        destroy,
+    };
+};

package/dist/plugins/masonry/types.js

@@ -0,0 +1,9 @@
+/**
+ * vlist - Masonry Types
+ * Types for masonry/Pinterest-style layout mode
+ *
+ * Masonry layout arranges items in columns (vertical) or rows (horizontal)
+ * where items flow into the shortest column/row, creating a packed layout
+ * with no alignment across the cross-axis.
+ */
+export {};

package/dist/plugins/page/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * vlist/page - Window Scroll Mode
+ */
+export { page, type PagePluginConfig } from "./plugin";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/page/index.js

@@ -0,0 +1,5 @@
+/**
+ * vlist/page - Window Scroll Mode
+ */
+// v2 plugin
+export { page } from "./plugin";

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

@@ -0,0 +1,21 @@
+/**
+ * vlist v2 — Page (Window Scroll) Plugin
+ *
+ * Redirects scroll from the viewport to the window, enabling
+ * the list to scroll with the page. Useful for infinite feeds,
+ * full-page lists, and document-integrated virtual scrolling.
+ *
+ * Priority: 5 (runs early, before plugins that depend on scroll)
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../core/types";
+export interface PagePluginConfig {
+    scrollPadding?: {
+        top?: number | (() => number);
+        bottom?: number | (() => number);
+        left?: number | (() => number);
+        right?: number | (() => number);
+    };
+}
+export declare function page<T extends VListItem = VListItem>(config?: PagePluginConfig): VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/page/plugin.js

@@ -0,0 +1,166 @@
+/**
+ * vlist v2 — Page (Window Scroll) Plugin
+ *
+ * Redirects scroll from the viewport to the window, enabling
+ * the list to scroll with the page. Useful for infinite feeds,
+ * full-page lists, and document-integrated virtual scrolling.
+ *
+ * Priority: 5 (runs early, before plugins that depend on scroll)
+ */
+// =============================================================================
+// Helpers
+// =============================================================================
+const resolvePad = (v) => v == null ? 0 : typeof v === "function" ? v() : v;
+// =============================================================================
+// Factory
+// =============================================================================
+export function page(config) {
+    const scrollPadding = config?.scrollPadding;
+    let cleanupResize;
+    let cleanupScroll;
+    return {
+        name: "page",
+        priority: 5,
+        setup(ctx) {
+            const { dom, sizeCache, config: cfg, emitter } = ctx;
+            const hz = cfg.horizontal;
+            const win = window;
+            const state = ctx.getState();
+            // ── 1. Disable default viewport scroll & resize ────────────
+            ctx.disableDefaultScroll();
+            ctx.disableDefaultResize();
+            // ── 2. Modify DOM for window scroll ────────────────────────
+            dom.root.style.overflow = "visible";
+            dom.root.style.height = "auto";
+            if (hz) {
+                dom.viewport.style.overflowX = "visible";
+                dom.viewport.style.overflowY = "visible";
+            }
+            else {
+                dom.viewport.style.overflow = "visible";
+            }
+            dom.viewport.classList.remove(`${cfg.classPrefix}-viewport--custom-scrollbar`);
+            // ── 3. Override scroll position get/set ─────────────────────
+            ctx.setScrollFns(() => {
+                const rect = dom.viewport.getBoundingClientRect();
+                return Math.max(0, hz ? -rect.left : -rect.top);
+            }, (pos) => {
+                const rect = dom.viewport.getBoundingClientRect();
+                const target = (hz ? rect.left + win.scrollX : rect.top + win.scrollY) + pos;
+                if (hz) {
+                    win.scrollTo({ left: target, top: win.scrollY, behavior: "instant" });
+                }
+                else {
+                    win.scrollTo({ left: win.scrollX, top: target, behavior: "instant" });
+                }
+            });
+            // ── 4. Set container size from window ──────────────────────
+            state.containerSize = hz ? win.innerWidth : win.innerHeight;
+            state.crossSize = hz ? win.innerHeight : win.innerWidth;
+            // ── 5. Window scroll listener ──────────────────────────────
+            let idleTimer = null;
+            const onWindowScroll = () => {
+                const rect = dom.viewport.getBoundingClientRect();
+                const pos = Math.max(0, hz ? -rect.left : -rect.top);
+                state.prevScrollPosition = state.scrollPosition;
+                state.scrollPosition = pos;
+                state.scrollDirection = pos > state.prevScrollPosition ? 1
+                    : pos < state.prevScrollPosition ? -1 : 0;
+                ctx.onScrollFrame();
+                if (idleTimer !== null)
+                    clearTimeout(idleTimer);
+                idleTimer = setTimeout(() => {
+                    idleTimer = null;
+                    ctx.onScrollIdle();
+                }, 150);
+            };
+            win.addEventListener("scroll", onWindowScroll, { passive: true });
+            cleanupScroll = () => win.removeEventListener("scroll", onWindowScroll);
+            // ── 6. Window resize listener ──────────────────────────────
+            let prevW = win.innerWidth;
+            let prevH = win.innerHeight;
+            const onWindowResize = () => {
+                const w = win.innerWidth;
+                const h = win.innerHeight;
+                const sizeDelta = hz ? Math.abs(w - prevW) : Math.abs(h - prevH);
+                if (sizeDelta < 1)
+                    return;
+                prevW = w;
+                prevH = h;
+                state.containerSize = hz ? w : h;
+                state.crossSize = hz ? h : w;
+                ctx.forceRender();
+                emitter.emit("resize", { width: w, height: h });
+            };
+            win.addEventListener("resize", onWindowResize);
+            cleanupResize = () => win.removeEventListener("resize", onWindowResize);
+            // ── 7. Scroll padding (scrollToIndex adjustments) ──────────
+            if (scrollPadding) {
+                ctx.setScrollToPosFn((index, sc, containerSize, totalItems, align) => {
+                    const startPad = resolvePad(hz ? scrollPadding.left : scrollPadding.top);
+                    const endPad = resolvePad(hz ? scrollPadding.right : scrollPadding.bottom);
+                    if (totalItems === 0)
+                        return 0;
+                    const clamped = Math.max(0, Math.min(index, totalItems - 1));
+                    const offset = sc.getOffset(clamped);
+                    const itemSize = sc.getSize(clamped);
+                    const totalSize = sc.getTotalSize();
+                    const maxScroll = Math.max(0, totalSize - containerSize + endPad);
+                    let pos;
+                    switch (align) {
+                        case "center":
+                            pos = offset - startPad - (containerSize - startPad - endPad - itemSize) / 2;
+                            break;
+                        case "end":
+                            pos = offset - containerSize + itemSize + endPad;
+                            break;
+                        default:
+                            pos = offset - startPad;
+                    }
+                    return Math.max(-startPad, Math.min(pos, maxScroll));
+                });
+                ctx.registerMethod("_scrollItemIntoView", (index) => {
+                    const containerSize = hz ? win.innerWidth : win.innerHeight;
+                    const startPad = resolvePad(hz ? scrollPadding.left : scrollPadding.top);
+                    const endPad = resolvePad(hz ? scrollPadding.right : scrollPadding.bottom);
+                    const rect = dom.viewport.getBoundingClientRect();
+                    const domScroll = hz ? win.scrollX : win.scrollY;
+                    const listScreenPos = hz ? rect.left : rect.top;
+                    const listDocPos = listScreenPos + domScroll;
+                    const itemOffset = sizeCache.getOffset(index);
+                    const itemSize = sizeCache.getSize(index);
+                    const itemScreenStart = listScreenPos + itemOffset;
+                    const safeEnd = containerSize - endPad;
+                    let newTarget = domScroll;
+                    if (itemScreenStart < startPad) {
+                        newTarget = listDocPos + itemOffset - startPad;
+                    }
+                    else if (itemScreenStart + itemSize > safeEnd) {
+                        newTarget = listDocPos + itemOffset + itemSize - safeEnd;
+                    }
+                    if (newTarget !== domScroll) {
+                        if (hz) {
+                            win.scrollTo({ left: newTarget, top: win.scrollY, behavior: "instant" });
+                        }
+                        else {
+                            win.scrollTo({ left: win.scrollX, top: newTarget, behavior: "instant" });
+                        }
+                    }
+                });
+            }
+            // ── 8. Register cleanup ────────────────────────────────────
+            ctx.registerDestroyHandler(() => {
+                cleanupScroll?.();
+                cleanupResize?.();
+                if (idleTimer !== null)
+                    clearTimeout(idleTimer);
+            });
+        },
+        destroy() {
+            cleanupScroll?.();
+            cleanupResize?.();
+            cleanupScroll = undefined;
+            cleanupResize = undefined;
+        },
+    };
+}

package/dist/plugins/scale/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * vlist v2 — Scale Plugin
+ */
+export { scale, type ScalePluginConfig } from "./plugin";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/scale/index.js

@@ -0,0 +1,4 @@
+/**
+ * vlist v2 — Scale Plugin
+ */
+export { scale } from "./plugin";

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

@@ -0,0 +1,24 @@
+/**
+ * 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 type { VListItem } from "../../types";
+import type { VListPlugin } from "../../core/types";
+export interface ScalePluginConfig {
+    force?: boolean;
+}
+export declare function scale<T extends VListItem = VListItem>(config?: ScalePluginConfig): VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map