vlist 2.0.0 → 2.0.2

package/dist/plugins/groups/sticky.js

@@ -1,255 +0,0 @@
-/**
- * vlist - Sticky Header
- *
- * Manages a floating header that sticks to the viewport edge and transitions
- * smoothly when the next group's header approaches (push-out effect).
- *
- * Two permanent slot elements are recycled — content is swapped via a
- * caller-provided `renderInto` callback, keeping the sticky header
- * template-agnostic (same pattern as item rendering).
- *
- * Header offsets and sizes are pre-cached into flat arrays on rebuild,
- * keeping the per-tick scroll handler free of function calls.
- *
- *   .vlist-sticky-header (position: relative, overflow: hidden)
- *   ├── .sticky-group  (active slot — translated during push)
- *   └── .sticky-group  (standby slot — translated during push)
- */
-/**
- * Create the sticky header container element upfront (before data arrives)
- * so the DOM structure is stable and doesn't cause a visual shift.
- */
-export const createStickyContainer = (root, classPrefix, horizontal, headerHeight, stickyOffset = 0) => {
-    const mainProp = horizontal ? "width" : "height";
-    const container = document.createElement("div");
-    container.className = `${classPrefix}-sticky-header`;
-    container.setAttribute("role", "presentation");
-    container.setAttribute("aria-hidden", "true");
-    container.style.cssText =
-        `position:relative;z-index:5;pointer-events:none;overflow:hidden;` +
-            (horizontal
-                ? `top:0;bottom:0;left:${stickyOffset || 0}px`
-                : `top:${stickyOffset || 0}px`);
-    container.style[mainProp] = `${headerHeight}px`;
-    root.insertBefore(container, root.firstChild);
-    return container;
-};
-export const createStickyHeader = (root, layout, sizeCache, renderInto, classPrefix, horizontal = false, stickyOffset = 0, getCompressionRatio, existingContainer) => {
-    // Orientation helpers — resolved once
-    const mainProp = horizontal ? "width" : "height";
-    const crossProp = horizontal ? "height" : "width";
-    const translateAxis = horizontal ? "X" : "Y";
-    const setMain = (el, px) => {
-        el.style[mainProp] = `${px}px`;
-    };
-    // DOM setup — reuse pre-created container if provided
-    const container = existingContainer ?? createStickyContainer(root, classPrefix, horizontal, 0, stickyOffset);
-    const mkSlot = () => {
-        const s = document.createElement("div");
-        s.className = "sticky-group";
-        s.style.position = "absolute";
-        s.style.willChange = "transform";
-        s.style[crossProp] = "100%";
-        return s;
-    };
-    const slotA = mkSlot();
-    const slotB = mkSlot();
-    container.append(slotA, slotB);
-    // Slot references — swap roles after each completed transition
-    let active = slotA;
-    let standby = slotB;
-    // Pre-cached arrays — rebuilt in cacheGroups(), read on every scroll tick
-    // offsets & vSizes are in virtual (scroll) space for binary search / push detection.
-    // sizes are in actual pixels for DOM rendering.
-    let groups = layout.groups;
-    let offsets = [];
-    let sizes = [];
-    let vSizes = [];
-    let groupCount = 0;
-    const cacheGroups = () => {
-        groups = layout.groups;
-        groupCount = groups.length;
-        offsets = new Array(groupCount);
-        sizes = new Array(groupCount);
-        vSizes = new Array(groupCount);
-        const ratio = getCompressionRatio ? getCompressionRatio() : 1;
-        for (let i = 0; i < groupCount; i++) {
-            offsets[i] = sizeCache.getOffset(groups[i].headerLayoutIndex) * ratio;
-            sizes[i] = layout.getHeaderHeight(i);
-            vSizes[i] = sizes[i] * ratio;
-        }
-    };
-    cacheGroups();
-    // Mutable state
-    let curGroup = -1;
-    let curSize = 0;
-    let curVSize = 0;
-    let nxtGroup = -1;
-    let visible = false;
-    let lastOffset = 0;
-    let transitioning = false;
-    // Slot content — delegate to caller-provided renderInto
-    const fill = (slot, gi) => {
-        renderInto(slot, gi);
-        const sz = sizes[gi];
-        setMain(slot, sz);
-        return sz;
-    };
-    const clear = (slot) => {
-        slot.replaceChildren();
-        slot.style.transform = "";
-    };
-    // Current group
-    const setCurrent = (gi) => {
-        if (gi === curGroup)
-            return;
-        curGroup = gi;
-        curSize = 0;
-        curVSize = 0;
-        if (gi < 0 || gi >= groupCount) {
-            clear(active);
-            return;
-        }
-        curSize = fill(active, gi);
-        curVSize = vSizes[gi];
-        setMain(container, curSize);
-        active.style.transform = "";
-    };
-    // Push transition
-    const applyPush = (offset) => {
-        if (offset === lastOffset)
-            return;
-        lastOffset = offset;
-        const r = Math.round(offset);
-        active.style.transform = `translate${translateAxis}(${r}px)`;
-        standby.style.transform = `translate${translateAxis}(${r + curSize}px)`;
-    };
-    const resetTransforms = () => {
-        lastOffset = 0;
-        active.style.transform = "";
-        standby.style.transform = "";
-    };
-    const complete = () => {
-        if (!transitioning)
-            return;
-        const prev = active;
-        active = standby;
-        standby = prev;
-        curGroup = nxtGroup;
-        curSize = curGroup >= 0 ? sizes[curGroup] : 0;
-        curVSize = curGroup >= 0 ? vSizes[curGroup] : 0;
-        setMain(container, curSize);
-        clear(standby);
-        nxtGroup = -1;
-        transitioning = false;
-        resetTransforms();
-    };
-    const cancel = () => {
-        if (!transitioning)
-            return;
-        clear(standby);
-        nxtGroup = -1;
-        transitioning = false;
-        resetTransforms();
-    };
-    // Visibility — when a pre-created container is reused, use visibility
-    // instead of display to preserve layout (the viewport is sized with
-    // calc(100% - headerHeight) and relies on the container occupying space).
-    const preserveLayout = !!existingContainer;
-    const show = () => {
-        if (visible)
-            return;
-        visible = true;
-        if (preserveLayout)
-            container.style.visibility = "";
-        else
-            container.style.display = "";
-    };
-    const hide = () => {
-        if (!visible)
-            return;
-        visible = false;
-        if (preserveLayout)
-            container.style.visibility = "hidden";
-        else
-            container.style.display = "none";
-        clear(active);
-        curGroup = -1;
-        curSize = 0;
-        curVSize = 0;
-        cancel();
-    };
-    // Scroll handler — hot path
-    const update = (scroll) => {
-        if (groupCount === 0) {
-            hide();
-            return;
-        }
-        if (scroll < offsets[0]) {
-            hide();
-            return;
-        }
-        // Binary search — pure array reads, no function calls
-        // offsets and vSizes are in virtual (scroll) space
-        let lo = 0, hi = groupCount - 1;
-        while (lo < hi) {
-            const mid = (lo + hi + 1) >>> 1;
-            if (offsets[mid] + vSizes[mid] <= scroll)
-                lo = mid;
-            else
-                hi = mid - 1;
-        }
-        if (!visible)
-            show();
-        setCurrent(lo);
-        // Push transition check — dist is in virtual space,
-        // scaled to actual pixels for DOM transforms
-        const nxt = lo + 1;
-        if (nxt < groupCount) {
-            const dist = offsets[nxt] - scroll;
-            if (dist <= 0 && dist > -curVSize) {
-                if (nxtGroup !== nxt || !transitioning) {
-                    nxtGroup = nxt;
-                    fill(standby, nxt);
-                    transitioning = true;
-                }
-                const pxDist = curVSize > 0 ? (dist / curVSize) * curSize : dist;
-                applyPush(pxDist);
-            }
-            else if (dist <= -curVSize) {
-                if (transitioning)
-                    complete();
-            }
-            else {
-                if (transitioning)
-                    cancel();
-            }
-        }
-        else {
-            if (transitioning)
-                cancel();
-        }
-    };
-    const refresh = () => {
-        cacheGroups();
-        const prev = curGroup;
-        curGroup = -1;
-        curSize = 0;
-        curVSize = 0;
-        if (prev >= 0)
-            setCurrent(prev);
-    };
-    const destroy = () => {
-        container.remove();
-        curGroup = -1;
-        curSize = 0;
-        curVSize = 0;
-        nxtGroup = -1;
-        visible = false;
-        transitioning = false;
-    };
-    if (!existingContainer) {
-        container.style.display = "none";
-    }
-    return { update, refresh, show, hide, destroy };
-};

package/dist/plugins/groups/types.js

@@ -1,12 +0,0 @@
-/**
- * vlist - Group Types
- * Types for sticky headers and grouped lists
- */
-/**
- * Type guard: check if an item is a group header pseudo-item
- */
-export const isGroupHeader = (item) => {
-    return (item !== null &&
-        typeof item === "object" &&
-        item.__groupHeader === true);
-};

package/dist/plugins/masonry/index.js

@@ -1,6 +0,0 @@
-/**
- * vlist v2 — Masonry Plugin
- */
-export { masonry } from "./plugin";
-export { createMasonryLayout } from "./layout";
-export { createMasonryRenderer } from "./renderer";

package/dist/plugins/masonry/layout.js

@@ -1,261 +0,0 @@
-/**
- * vlist - Masonry Layout
- * Shortest-lane placement algorithm for masonry/Pinterest-style layouts.
- *
- * Algorithm:
- * 1. Track the size (height/width) of each lane (column/row)
- * 2. For each item:
- *    - Find the shortest lane
- *    - Place item at the end of that lane
- *    - Update lane size
- * 3. Cache all item positions for O(1) lookup during rendering
- *
- * Complexity:
- * - Layout calculation: O(n) where n = total items
- * - Position lookup: O(1) using cached placements
- * - Visibility check: O(k * log(n/k)) using per-lane binary search
- *   where k = columns, n = total items
- */
-// =============================================================================
-// Factory
-// =============================================================================
-/**
- * Create a MasonryLayout instance.
- *
- * @param config - Masonry configuration (columns, gap, containerSize)
- * @returns MasonryLayout with placement algorithm
- */
-export const createMasonryLayout = (config) => {
-    let columns = Math.max(1, Math.floor(config.columns));
-    let gap = config.gap ?? 0;
-    let containerSize = config.containerSize;
-    // ── Cached derived values ──
-    // Recomputed when columns, gap, or containerSize change.
-    let crossAxisSize = 0;
-    let laneOffsets = [];
-    const recomputeDerived = () => {
-        const totalGap = (columns - 1) * gap;
-        crossAxisSize = Math.max(0, (containerSize - totalGap) / columns);
-        laneOffsets = new Array(columns);
-        const stride = crossAxisSize + gap;
-        for (let i = 0; i < columns; i++) {
-            laneOffsets[i] = i * stride;
-        }
-    };
-    // Initial computation
-    recomputeDerived();
-    // ── Per-lane placement indices (for binary search in getVisibleItems) ──
-    // Built by calculateLayout, consumed by getVisibleItems.
-    let lanePlacements = [];
-    // ── Cached total size from last calculateLayout ──
-    let cachedTotalSize = 0;
-    // ── Pooled visible-items array ──
-    // Reused by getVisibleItems to avoid allocation per scroll frame.
-    // Single-consumer contract: caller must finish reading before the next call.
-    let visiblePool = [];
-    /**
-     * Calculate layout for all items using shortest-lane algorithm.
-     * Returns array of item placements with cached positions.
-     *
-     * Also caches:
-     * - Total size (tallest lane) — retrievable via getTotalSize([])
-     * - Per-lane placement index lists — used by getVisibleItems for binary search
-     */
-    const calculateLayout = (totalItems, getSizeForItem) => {
-        if (totalItems <= 0) {
-            cachedTotalSize = 0;
-            lanePlacements = [];
-            return [];
-        }
-        // Initialize lane sizes (accumulated height/width for each column/row)
-        const laneSizes = new Array(columns).fill(0);
-        // Per-lane placement indices (for binary search later)
-        const lanes = new Array(columns);
-        for (let c = 0; c < columns; c++) {
-            lanes[c] = [];
-        }
-        // Array to store all item placements
-        const placements = new Array(totalItems);
-        // Place each item in the shortest lane
-        for (let i = 0; i < totalItems; i++) {
-            // Find shortest lane
-            let lane = 0;
-            let shortestSize = laneSizes[0];
-            for (let c = 1; c < columns; c++) {
-                const currentSize = laneSizes[c];
-                if (currentSize < shortestSize) {
-                    shortestSize = currentSize;
-                    lane = c;
-                }
-            }
-            // Get item size in main axis
-            const itemSize = getSizeForItem(i);
-            // Position: use precomputed lane offset, current lane accumulator
-            const mainOffset = laneSizes[lane];
-            // Create placement (flat structure — no nested position object)
-            placements[i] = {
-                index: i,
-                x: laneOffsets[lane],
-                y: mainOffset,
-                lane,
-                size: itemSize,
-                crossSize: crossAxisSize,
-            };
-            // Track placement index per lane
-            lanes[lane].push(i);
-            // Update lane size (add item size + gap)
-            laneSizes[lane] = mainOffset + itemSize + gap;
-        }
-        // Cache per-lane placements for binary search
-        lanePlacements = lanes;
-        // Cache total size (max lane extent, minus trailing gap)
-        let maxExtent = 0;
-        for (let c = 0; c < columns; c++) {
-            const laneSize = laneSizes[c];
-            // laneSizes includes a trailing gap after the last item — subtract it
-            // unless the lane is empty (size === 0)
-            const extent = laneSize > 0 ? laneSize - gap : 0;
-            if (extent > maxExtent)
-                maxExtent = extent;
-        }
-        cachedTotalSize = maxExtent;
-        return placements;
-    };
-    /**
-     * Get total size in main axis (tallest column height or widest row width).
-     * This determines the total scroll size.
-     *
-     * When called with the result of calculateLayout, returns the cached value
-     * computed during layout (O(1)). Falls back to recomputation for external
-     * placement arrays.
-     */
-    const getTotalSize = (placements) => {
-        // Fast path: return cached value when called with the layout result
-        // (the common case — feature.ts always passes cachedPlacements)
-        if (placements.length === 0)
-            return cachedTotalSize;
-        // If the first placement matches our cached data, use cached total
-        // This avoids the O(n) scan in the normal flow
-        if (cachedTotalSize)
-            return cachedTotalSize;
-        // Fallback: recompute (only for externally-constructed placements)
-        const laneSizes = new Array(columns).fill(0);
-        for (const placement of placements) {
-            const extent = placement.y + placement.size;
-            const currentSize = laneSizes[placement.lane];
-            if (extent > currentSize) {
-                laneSizes[placement.lane] = extent;
-            }
-        }
-        let max = 0;
-        for (let c = 0; c < columns; c++) {
-            if (laneSizes[c] > max)
-                max = laneSizes[c];
-        }
-        return max;
-    };
-    /**
-     * Get items visible within the given main-axis range.
-     * Uses per-lane binary search for O(k * log(n/k)) performance
-     * where k = columns and n = total items.
-     *
-     * Within each lane, items are sorted by Y position (guaranteed by the
-     * shortest-lane algorithm). We binary search each lane to find the first
-     * item whose bottom edge enters the viewport and the last item whose
-     * top edge is before the viewport end.
-     */
-    const getVisibleItems = (placements, mainAxisStart, mainAxisEnd) => {
-        if (placements.length === 0 || mainAxisEnd <= mainAxisStart) {
-            visiblePool.length = 0;
-            return visiblePool;
-        }
-        // If per-lane data isn't available (external placements), fall back to linear scan
-        if (lanePlacements.length === 0 || lanePlacements.length !== columns) {
-            return getVisibleItemsLinear(placements, mainAxisStart, mainAxisEnd);
-        }
-        // Reuse pooled array — reset length to 0 (no allocation)
-        visiblePool.length = 0;
-        for (let c = 0; c < columns; c++) {
-            const laneIndices = lanePlacements[c];
-            const laneLen = laneIndices.length;
-            if (!laneLen)
-                continue;
-            // Binary search: find first item in this lane where itemEnd > mainAxisStart
-            // i.e., the item's bottom edge is past the viewport top
-            let lo = 0;
-            let hi = laneLen;
-            while (lo < hi) {
-                const mid = (lo + hi) >>> 1;
-                const p = placements[laneIndices[mid]];
-                if (p.y + p.size <= mainAxisStart) {
-                    lo = mid + 1;
-                }
-                else {
-                    hi = mid;
-                }
-            }
-            // Collect visible items from this lane starting at `lo`
-            for (let j = lo; j < laneLen; j++) {
-                const p = placements[laneIndices[j]];
-                // Once the item's top edge is past the viewport bottom, stop
-                if (p.y >= mainAxisEnd)
-                    break;
-                visiblePool.push(p);
-            }
-        }
-        return visiblePool;
-    };
-    /**
-     * Linear fallback for getVisibleItems when per-lane data is unavailable.
-     * Used only for externally-constructed placement arrays.
-     */
-    const getVisibleItemsLinear = (placements, mainAxisStart, mainAxisEnd) => {
-        visiblePool.length = 0;
-        for (const placement of placements) {
-            const itemEnd = placement.y + placement.size;
-            if (itemEnd > mainAxisStart && placement.y < mainAxisEnd) {
-                visiblePool.push(placement);
-            }
-        }
-        return visiblePool;
-    };
-    /**
-     * Update masonry configuration without recreating the layout.
-     */
-    const updateConfig = (newConfig) => {
-        let changed = false;
-        if (newConfig.columns !== undefined) {
-            const newCols = Math.max(1, Math.floor(newConfig.columns));
-            if (newCols !== columns) {
-                columns = newCols;
-                changed = true;
-            }
-        }
-        if (newConfig.gap !== undefined && newConfig.gap !== gap) {
-            gap = newConfig.gap;
-            changed = true;
-        }
-        if (newConfig.containerSize !== undefined && newConfig.containerSize !== containerSize) {
-            containerSize = newConfig.containerSize;
-            changed = true;
-        }
-        if (changed) {
-            recomputeDerived();
-        }
-    };
-    return {
-        get columns() {
-            return columns;
-        },
-        get gap() {
-            return gap;
-        },
-        get containerSize() {
-            return containerSize;
-        },
-        update: updateConfig,
-        calculateLayout,
-        getTotalSize,
-        getVisibleItems,
-    };
-};