vlist 1.9.1 → 2.0.0

package/dist/plugins/groups/plugin.js

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