vlist 2.0.0 → 2.0.2

package/dist/plugins/groups/plugin.js

@@ -1,571 +0,0 @@
-/**
- * vlist v2 — Groups Plugin
- *
- * Adds grouped lists with sticky headers.
- * Priority 10 — runs before selection (50).
- *
- * Architecture:
- * - Transforms items list: inserts group header pseudo-items at group boundaries
- * - Replaces size function: headers use header height, items use item height
- * - Replaces render pipeline: handles grouped layout rendering
- * - Sticky header: floating header that updates on scroll
- * - CSS class: adds .vlist--grouped to root
- *
- * Restrictions:
- * - Items must be pre-sorted by group
- */
-import { createGroupLayout, } from "./layout";
-import { createStickyHeader, createStickyContainer } from "./sticky";
-const itemState = { selected: false, focused: false };
-const DEBUG = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
-export function groups(config) {
-    if (!config.getGroupForIndex) {
-        throw new Error("[vlist] groups: getGroupForIndex is required");
-    }
-    const headerHeightRaw = config.header?.height ?? config.header?.width ?? config.headerHeight;
-    if (headerHeightRaw == null || (typeof headerHeightRaw === "number" && headerHeightRaw <= 0)) {
-        throw new Error("[vlist] groups: header height/width must be a positive number or function");
-    }
-    const rawHeaderTemplate = config.header?.template ?? config.headerTemplate;
-    if (!rawHeaderTemplate) {
-        throw new Error("[vlist] groups: header.template is required");
-    }
-    const headerTemplate = rawHeaderTemplate;
-    let layout;
-    let stickyHeader = null;
-    let sizeCache;
-    let engineState;
-    let pool;
-    let contentElement;
-    let rootElement;
-    let userTemplate;
-    let ctxGetItem;
-    let getLoadedItem = null;
-    let horizontal;
-    let classPrefix;
-    let overscan;
-    let resolveItemState = null;
-    let groupItemClass;
-    let groupHeaderClass;
-    let getMethod = null;
-    let interactive;
-    const rendered = new Map();
-    // Track which layout indices currently show placeholder content
-    const placeholderIndices = new Set();
-    // Elements detached during boundary changes, keyed by data-id.
-    // Reused in the next render pass to avoid pool round-trip (which clears innerHTML).
-    const detached = new Map();
-    let lastScrollPosition = -1;
-    let lastContainerSize = -1;
-    let forceNextRender = true;
-    let lastDataCount = -1;
-    let lastRebuildLoadedCount = 0;
-    let getLoadedCount = null;
-    let origSizeCacheRebuild;
-    function getLayoutItemCount() {
-        return layout.totalEntries;
-    }
-    // Only rebuilds layout when the data total changes (initial load, reload).
-    // Item content updates (placeholder → real) are handled by the render loop
-    // updating existing DOM elements in-place — no layout rebuild needed.
-    function syncLayoutIfNeeded() {
-        const dataCount = engineState.totalItems;
-        if (dataCount === lastDataCount)
-            return;
-        if (DEBUG) {
-            console.log(`[groups] syncLayout: ${lastDataCount} → ${dataCount}`);
-        }
-        const wasLoaded = lastDataCount > 0;
-        lastDataCount = dataCount;
-        layout.rebuild(dataCount, getLoadedItem ?? ctxGetItem);
-        origSizeCacheRebuild(layout.totalEntries);
-        const totalSize = sizeCache.getTotalSize();
-        contentElement.style[horizontal ? "width" : "height"] = totalSize + "px";
-        if (stickyHeader) {
-            stickyHeader.refresh();
-            stickyHeader.update(engineState.scrollPosition);
-        }
-        // Layout indices shifted — detach elements (keyed by data-id) so the
-        // render loop can reclaim them without a pool round-trip that clears innerHTML.
-        if (wasLoaded) {
-            detachAll();
-        }
-        const getSb = getMethod?.("_scrollbar:getInstance");
-        if (getSb) {
-            const sb = getSb();
-            sb?.updateBounds(totalSize, engineState.containerSize);
-        }
-    }
-    function buildTransform(layoutIndex) {
-        const offset = sizeCache.getOffset(layoutIndex);
-        if (horizontal) {
-            return `translate(${Math.round(offset)}px, 0)`;
-        }
-        return `translate(0, ${Math.round(offset)}px)`;
-    }
-    function applySizeStyles(element, layoutIndex) {
-        const size = sizeCache.getSize(layoutIndex);
-        if (horizontal) {
-            element.style.width = `${size}px`;
-        }
-        else {
-            element.style.height = `${size}px`;
-        }
-    }
-    function detachAll() {
-        rendered.forEach((element) => {
-            element.remove();
-            const id = element.getAttribute("data-id");
-            if (id) {
-                detached.set(id, element);
-            }
-            else {
-                pool.release(element);
-            }
-        });
-        rendered.clear();
-        placeholderIndices.clear();
-    }
-    function drainDetached() {
-        if (detached.size > 0) {
-            detached.forEach((element) => pool.release(element));
-            detached.clear();
-        }
-    }
-    function renderItemContent(element, entry, isf, layoutIndex) {
-        if (entry.type === "header") {
-            const headerId = `__group_header_${entry.group.groupIndex}`;
-            if (element.getAttribute("data-id") === headerId) {
-                return true;
-            }
-            element.className = groupHeaderClass;
-            element.setAttribute("role", "presentation");
-            element.removeAttribute("aria-selected");
-            element.setAttribute("data-id", headerId);
-            const content = headerTemplate(entry.group.key, entry.group.groupIndex);
-            if (typeof content === "string") {
-                element.innerHTML = content;
-            }
-            else {
-                element.innerHTML = "";
-                element.appendChild(content);
-            }
-            return true;
-        }
-        // Data item
-        const dataIndex = entry.dataIndex;
-        const item = ctxGetItem(dataIndex);
-        if (!item) {
-            element.innerHTML = "";
-            return false;
-        }
-        const isPlaceholder = item._isPlaceholder === true;
-        const itemId = String(item.id);
-        // Element already shows this item with real content — skip template
-        if (!isPlaceholder && element.getAttribute("data-id") === itemId) {
-            if (interactive) {
-                element.id = `${classPrefix}-item-${layoutIndex}`;
-                element.setAttribute("aria-posinset", String(dataIndex + 1));
-                element.setAttribute("aria-setsize", String(engineState.totalItems));
-            }
-            return true;
-        }
-        element.className = groupItemClass;
-        element.setAttribute("role", "option");
-        element.setAttribute("data-id", itemId);
-        if (interactive) {
-            element.id = `${classPrefix}-item-${layoutIndex}`;
-            element.setAttribute("aria-posinset", String(dataIndex + 1));
-            element.setAttribute("aria-setsize", String(engineState.totalItems));
-        }
-        if (isPlaceholder) {
-            element.classList.add(`${classPrefix}-item--placeholder`);
-        }
-        if (isf)
-            isf(layoutIndex, itemState);
-        else {
-            itemState.selected = false;
-            itemState.focused = false;
-        }
-        const content = userTemplate(item, dataIndex, itemState);
-        if (typeof content === "string") {
-            element.innerHTML = content;
-        }
-        else {
-            element.innerHTML = "";
-            element.appendChild(content);
-        }
-        return !isPlaceholder;
-    }
-    function groupsRenderIfNeeded() {
-        if (engineState.destroyed)
-            return;
-        syncLayoutIfNeeded();
-        const scrollPos = engineState.scrollPosition;
-        const cs = engineState.containerSize;
-        if (!forceNextRender && scrollPos === lastScrollPosition && cs === lastContainerSize) {
-            return;
-        }
-        lastScrollPosition = scrollPos;
-        lastContainerSize = cs;
-        const isForced = forceNextRender;
-        forceNextRender = false;
-        const totalItems = getLayoutItemCount();
-        if (cs <= 0 || totalItems === 0) {
-            if (rendered.size > 0) {
-                rendered.forEach((element) => {
-                    element.remove();
-                    pool.release(element);
-                });
-                rendered.clear();
-                placeholderIndices.clear();
-            }
-            return;
-        }
-        let visStart = sizeCache.indexAtOffset(scrollPos);
-        let visEnd = sizeCache.indexAtOffset(scrollPos + cs);
-        if (visEnd < totalItems - 1)
-            visEnd++;
-        visStart = Math.max(0, visStart);
-        visEnd = Math.min(totalItems - 1, Math.max(0, visEnd));
-        const renderStart = Math.max(0, visStart - overscan);
-        const renderEnd = Math.min(totalItems - 1, visEnd + overscan);
-        if (renderStart === engineState.prevRangeStart && renderEnd === engineState.prevRangeEnd && !engineState.renderPending) {
-            return;
-        }
-        // Recycle elements outside the new range
-        rendered.forEach((element, idx) => {
-            if (idx < renderStart || idx > renderEnd) {
-                element.remove();
-                pool.release(element);
-                rendered.delete(idx);
-                placeholderIndices.delete(idx);
-            }
-        });
-        const isf = resolveItemState?.() ?? null;
-        const selClass = isf ? `${classPrefix}-item--selected` : "";
-        const focClass = isf ? `${classPrefix}-item--focused` : "";
-        let fragment = null;
-        for (let i = renderStart; i <= renderEnd; i++) {
-            let element = rendered.get(i);
-            let isHeader = false;
-            if (element === undefined) {
-                // ── New element ──
-                const entry = layout.getEntry(i);
-                isHeader = entry.type === "header";
-                // Try to reclaim a detached element with matching data-id
-                // (avoids pool round-trip that destroys innerHTML / images)
-                let expectedId;
-                if (entry.type === "header") {
-                    expectedId = `__group_header_${entry.group.groupIndex}`;
-                }
-                else {
-                    const item = ctxGetItem(entry.dataIndex);
-                    if (item && item._isPlaceholder !== true) {
-                        expectedId = String(item.id);
-                    }
-                }
-                if (expectedId !== undefined) {
-                    const reused = detached.get(expectedId);
-                    if (reused) {
-                        detached.delete(expectedId);
-                        element = reused;
-                    }
-                }
-                if (!element) {
-                    element = pool.acquire();
-                }
-                element.setAttribute("data-index", String(i));
-                const hasContent = renderItemContent(element, entry, isf, i);
-                if (hasContent)
-                    placeholderIndices.delete(i);
-                else
-                    placeholderIndices.add(i);
-                applySizeStyles(element, i);
-                element.style.transform = buildTransform(i);
-                rendered.set(i, element);
-                if (!fragment)
-                    fragment = document.createDocumentFragment();
-                fragment.appendChild(element);
-            }
-            else if (isForced && placeholderIndices.has(i)) {
-                // ── Existing placeholder — check if real data arrived ──
-                const entry = layout.getEntry(i);
-                if (entry.type === "item") {
-                    const hasContent = renderItemContent(element, entry, isf, i);
-                    if (hasContent)
-                        placeholderIndices.delete(i);
-                    else
-                        placeholderIndices.add(i);
-                }
-            }
-            else {
-                // ── Existing unchanged element — fast path ──
-                isHeader = element.classList.contains(groupHeaderClass);
-            }
-            if (!isHeader && isf) {
-                isf(i, itemState);
-                element.classList.toggle(selClass, itemState.selected);
-                element.classList.toggle(focClass, itemState.focused);
-                if (itemState.selected)
-                    element.setAttribute("aria-selected", "true");
-                else
-                    element.removeAttribute("aria-selected");
-            }
-        }
-        if (fragment) {
-            contentElement.appendChild(fragment);
-        }
-        drainDetached();
-        const totalSize = sizeCache.getTotalSize();
-        contentElement.style[horizontal ? "width" : "height"] = totalSize + "px";
-        engineState.prevRangeStart = renderStart;
-        engineState.prevRangeEnd = renderEnd;
-        engineState.renderPending = false;
-        // Fill engine state with DATA indices so the async plugin loads
-        // the correct items (it reads startIndex/visibleCount as data indices).
-        let dataFillCount = 0;
-        let firstDataIndex = 0;
-        let foundFirst = false;
-        for (let i = renderStart; i <= renderEnd && dataFillCount < engineState.capacity; i++) {
-            const entry = layout.getEntry(i);
-            if (entry.type === "item") {
-                if (!foundFirst) {
-                    firstDataIndex = entry.dataIndex;
-                    foundFirst = true;
-                }
-                engineState.visibleIndices[dataFillCount] = entry.dataIndex;
-                engineState.visibleOffsets[dataFillCount] = sizeCache.getOffset(i);
-                engineState.visibleSizes[dataFillCount] = sizeCache.getSize(i);
-                dataFillCount++;
-            }
-        }
-        engineState.visibleCount = dataFillCount;
-        engineState.startIndex = firstDataIndex;
-    }
-    function groupsForceRender() {
-        if (engineState.destroyed)
-            return;
-        if (DEBUG) {
-            console.log(`[groups] forceRender, placeholders: ${placeholderIndices.size}, rendered: ${rendered.size}`);
-        }
-        // When async data arrives, group boundaries may change. But forceRender
-        // is also called on every scale-plugin lerp tick (60fps), so we must NOT
-        // run the expensive layout.rebuild on every call. O(1) check: compare
-        // loaded item count — only changes when async plugin delivers new data.
-        const currentLoaded = getLoadedCount?.() ?? 0;
-        if (currentLoaded !== lastRebuildLoadedCount) {
-            lastRebuildLoadedCount = currentLoaded;
-            const prevGroups = layout.groups;
-            const prevGroupCount = prevGroups.length;
-            layout.rebuild(lastDataCount, getLoadedItem ?? ctxGetItem);
-            const newGroups = layout.groups;
-            let boundariesChanged = newGroups.length !== prevGroupCount;
-            if (!boundariesChanged) {
-                for (let i = 0; i < prevGroupCount; i++) {
-                    if (newGroups[i].headerLayoutIndex !== prevGroups[i].headerLayoutIndex) {
-                        boundariesChanged = true;
-                        break;
-                    }
-                }
-            }
-            if (boundariesChanged) {
-                origSizeCacheRebuild(layout.totalEntries);
-                const totalSize = sizeCache.getTotalSize();
-                contentElement.style[horizontal ? "width" : "height"] = totalSize + "px";
-                if (stickyHeader) {
-                    stickyHeader.refresh();
-                    stickyHeader.update(engineState.scrollPosition);
-                }
-                // Only clear DOM if the boundary shift affects the rendered range.
-                // Preload-ahead data often creates new groups far from the viewport
-                // — no reason to destroy visible elements for that.
-                let firstShift = Infinity;
-                const minG = Math.min(prevGroupCount, newGroups.length);
-                for (let g = 0; g < minG; g++) {
-                    if (newGroups[g].headerLayoutIndex !== prevGroups[g].headerLayoutIndex) {
-                        firstShift = Math.min(newGroups[g].headerLayoutIndex, prevGroups[g].headerLayoutIndex);
-                        break;
-                    }
-                }
-                if (newGroups.length > prevGroupCount && minG < newGroups.length) {
-                    firstShift = Math.min(firstShift, newGroups[minG].headerLayoutIndex);
-                }
-                else if (prevGroupCount > newGroups.length && minG < prevGroupCount) {
-                    firstShift = Math.min(firstShift, prevGroups[minG].headerLayoutIndex);
-                }
-                if (firstShift <= engineState.prevRangeEnd) {
-                    detachAll();
-                }
-                const getSb = getMethod?.("_scrollbar:getInstance");
-                if (getSb) {
-                    const sb = getSb();
-                    sb?.updateBounds(totalSize, engineState.containerSize);
-                }
-            }
-        }
-        engineState.prevRangeStart = -1;
-        engineState.prevRangeEnd = -1;
-        engineState.renderPending = true;
-        forceNextRender = true;
-        groupsRenderIfNeeded();
-    }
-    return {
-        name: "groups",
-        priority: 10,
-        setup(ctx) {
-            sizeCache = ctx.sizeCache;
-            engineState = ctx.getState();
-            pool = ctx.pool;
-            contentElement = ctx.dom.content;
-            rootElement = ctx.dom.root;
-            userTemplate = ctx.template;
-            horizontal = ctx.config.horizontal;
-            classPrefix = ctx.config.classPrefix;
-            overscan = ctx.config.overscan;
-            ctxGetItem = ctx.getItem.bind(ctx);
-            resolveItemState = () => ctx.getItemStateFn();
-            getMethod = ctx.getMethod.bind(ctx);
-            interactive = ctx.config.interactive;
-            groupItemClass = `${classPrefix}-item`;
-            groupHeaderClass = `${classPrefix}-group-header`;
-            // Resolve raw storage accessor (async plugin) — returns undefined for
-            // unloaded items without generating placeholder objects. Used in
-            // buildGroups to skip unloaded items efficiently.
-            queueMicrotask(() => {
-                const fn = getMethod?.("_getLoadedItem");
-                if (fn)
-                    getLoadedItem = fn;
-                const countFn = getMethod?.("_getLoadedCount");
-                if (countFn)
-                    getLoadedCount = countFn;
-            });
-            const dataCount = engineState.totalItems;
-            layout = createGroupLayout(dataCount, config, getLoadedItem ?? ctxGetItem);
-            lastDataCount = dataCount;
-            const getHeaderHeight = typeof headerHeightRaw === "number"
-                ? (_groupIndex) => headerHeightRaw
-                : (groupIndex) => {
-                    const group = layout.groups[groupIndex];
-                    if (!group)
-                        return 0;
-                    return headerHeightRaw(group.key, groupIndex);
-                };
-            const origGetSize = sizeCache.getSize;
-            const groupedSizeFn = (layoutIndex) => {
-                const entry = layout.getEntry(layoutIndex);
-                if (entry.type === "header") {
-                    if (config.sticky !== false && entry.group.groupIndex === 0)
-                        return 0;
-                    return getHeaderHeight(entry.group.groupIndex);
-                }
-                return origGetSize(entry.dataIndex);
-            };
-            ctx.setSizeConfig(groupedSizeFn);
-            // Intercept sizeCache.rebuild: external callers (async plugin) pass
-            // data count, but groups needs layout count. Always use layout.totalEntries
-            // to keep prefix sums consistent with the grouped layout.
-            origSizeCacheRebuild = sizeCache.rebuild;
-            sizeCache.rebuild = (_n) => {
-                origSizeCacheRebuild(layout.totalEntries);
-            };
-            sizeCache.rebuild(layout.totalEntries);
-            ctx.setVirtualTotalFn(() => layout.totalEntries);
-            rootElement.classList.add(`${classPrefix}--grouped`);
-            if (config.sticky !== false) {
-                const renderInto = (slot, groupIndex) => {
-                    const group = layout.groups[groupIndex];
-                    if (!group)
-                        return;
-                    const result = headerTemplate(group.key, groupIndex);
-                    if (typeof result === "string") {
-                        slot.innerHTML = result;
-                    }
-                    else {
-                        slot.replaceChildren(result);
-                    }
-                };
-                const headerH = layout.getHeaderHeight(0);
-                const stickyContainer = createStickyContainer(rootElement, classPrefix, horizontal, headerH);
-                stickyHeader = createStickyHeader(rootElement, layout, sizeCache, renderInto, classPrefix, horizontal, 0, undefined, stickyContainer);
-                stickyHeader.update(engineState.scrollPosition);
-                if (!horizontal) {
-                    ctx.dom.viewport.style.height = `calc(100% - ${headerH}px)`;
-                }
-                else {
-                    ctx.dom.viewport.style.width = `calc(100% - ${headerH}px)`;
-                }
-            }
-            ctx.setRenderFn(groupsRenderIfNeeded, groupsForceRender);
-            ctx.registerMethod("getGroupLayout", () => layout);
-            ctx.registerMethod("_dataToLayoutIndex", (dataIndex) => layout.dataToLayoutIndex(dataIndex));
-            ctx.registerMethod("_layoutToDataIndex", (layoutIndex) => layout.layoutToDataIndex(layoutIndex));
-            ctx.registerMethod("_getRenderedElement", (layoutIndex) => rendered.get(layoutIndex) ?? null);
-            ctx.registerMethod("_isGroupHeader", (layoutIndex) => {
-                const entry = layout.getEntry(layoutIndex);
-                return entry.type === "header";
-            });
-            ctx.registerMethod("scrollToIndex", (index, alignOrOptions = "start") => {
-                const layoutIndex = layout.dataToLayoutIndex(index);
-                const totalLayout = layout.totalEntries;
-                if (totalLayout === 0)
-                    return;
-                const clamped = Math.max(0, Math.min(layoutIndex, totalLayout - 1));
-                const offset = sizeCache.getOffset(clamped);
-                const itemSize = sizeCache.getSize(clamped);
-                const cs = engineState.containerSize;
-                const totalSize = sizeCache.getTotalSize();
-                const maxScroll = Math.max(0, totalSize - cs);
-                const align = typeof alignOrOptions === "string" ? alignOrOptions : (alignOrOptions.align ?? "start");
-                const behavior = typeof alignOrOptions === "object" ? alignOrOptions.behavior : undefined;
-                const duration = typeof alignOrOptions === "object" ? alignOrOptions.duration : undefined;
-                let pos;
-                switch (align) {
-                    case "center":
-                        pos = offset - (cs - itemSize) / 2;
-                        break;
-                    case "end":
-                        pos = offset - cs + itemSize;
-                        break;
-                    default:
-                        pos = offset;
-                }
-                pos = Math.max(0, Math.min(pos, maxScroll));
-                if (behavior === "smooth" && duration && duration > 0) {
-                    ctx.smoothScrollTo(pos, duration);
-                }
-                else {
-                    ctx.scrollTo(pos);
-                }
-            });
-            ctx.registerDestroyHandler(() => {
-                for (const [, element] of rendered) {
-                    element.remove();
-                }
-                rendered.clear();
-                placeholderIndices.clear();
-                if (stickyHeader) {
-                    stickyHeader.destroy();
-                    stickyHeader = null;
-                }
-                rootElement.classList.remove(`${classPrefix}--grouped`);
-            });
-        },
-        hooks: {
-            onAfterScroll(scrollPosition, _direction) {
-                if (stickyHeader) {
-                    stickyHeader.update(scrollPosition);
-                }
-            },
-        },
-        destroy() {
-            if (stickyHeader) {
-                stickyHeader.destroy();
-                stickyHeader = null;
-            }
-            rendered.clear();
-            placeholderIndices.clear();
-            detached.clear();
-        },
-    };
-}