vlist 1.9.0 → 2.0.0

package/dist/plugins/groups/sticky.js

@@ -0,0 +1,255 @@
+/**
+ * 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

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

@@ -0,0 +1,8 @@
+/**
+ * vlist v2 — Masonry Plugin
+ */
+export { masonry, type MasonryPluginConfig, type MasonryContext } from "./plugin";
+export { createMasonryLayout } from "./layout";
+export { createMasonryRenderer, type MasonryRenderer, type GetItemFn } from "./renderer";
+export type { MasonryConfig, MasonryLayout, ItemPlacement } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/masonry/index.js

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

package/dist/plugins/masonry/layout.js

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

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

@@ -0,0 +1,32 @@
+/**
+ * vlist v2 — Masonry Plugin
+ *
+ * Switches from list layout to masonry/Pinterest-style layout with
+ * shortest-lane placement. Each item is positioned in the shortest
+ * column, creating an organic packed layout.
+ *
+ * Priority 10 — runs before selection (50) so layout is ready.
+ *
+ * Restrictions:
+ * - Cannot be combined with grid or table plugins
+ * - Cannot be combined with reverse: true
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../core/types";
+export interface MasonryPluginConfig {
+    columns: number;
+    gap?: number;
+    /**
+     * Optional size function for responsive sizing relative to column width.
+     * If omitted, reads sizes from the main config's item.height/width.
+     */
+    size?: (index: number, context: MasonryContext) => number;
+}
+export interface MasonryContext {
+    columnWidth: number;
+    columns: number;
+    gap: number;
+    containerWidth: number;
+}
+export declare function masonry<T extends VListItem = VListItem>(config: MasonryPluginConfig): VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map