vlist 1.9.0 → 2.0.0

package/dist/plugins/grid/plugin.js

@@ -0,0 +1,347 @@
+/**
+ * vlist v2 — Grid Plugin
+ *
+ * Switches from list layout to a 2D grid with configurable columns and gap.
+ * Priority 10 — runs before selection (50) so layout is ready for other plugins.
+ *
+ * Architecture:
+ * - Replaces the default 1D render pipeline with a grid-aware render
+ * - Size cache operates in ROW space (each row has height = itemHeight + gap)
+ * - Visible range is calculated in row space, then expanded to flat item indices
+ * - Items are positioned with translate(colOffset, rowOffset)
+ *
+ * Restrictions:
+ * - Cannot be combined with masonry or table plugins
+ */
+import { createGridLayout } from "./layout";
+// =============================================================================
+// Reusable state singleton — no allocation per frame
+// =============================================================================
+const itemState = { selected: false, focused: false };
+// =============================================================================
+// Factory
+// =============================================================================
+export function grid(config) {
+    if (!config.columns || config.columns < 1) {
+        throw new Error("[vlist] grid: columns must be >= 1");
+    }
+    let layout;
+    let sizeCache;
+    let engineState;
+    let pool;
+    let contentElement;
+    let template;
+    let getItem;
+    let horizontal;
+    let classPrefix;
+    let overscan;
+    let resolveItemState = null;
+    const rendered = new Map();
+    let containerWidth = 0;
+    // Mutable range objects — reused across frames
+    let lastScrollPosition = -1;
+    let lastContainerSize = -1;
+    let forceNextRender = true;
+    function getRowCount() {
+        return layout.getTotalRows(engineState.totalItems);
+    }
+    function buildTransform(itemIndex) {
+        const row = layout.getRow(itemIndex);
+        const col = layout.getCol(itemIndex);
+        const x = layout.getColumnOffset(col, containerWidth);
+        const y = sizeCache.getOffset(row);
+        if (horizontal) {
+            return `translate(${Math.round(y)}px, ${Math.round(x)}px)`;
+        }
+        return `translate(${Math.round(x)}px, ${Math.round(y)}px)`;
+    }
+    function applySizeStyles(element, itemIndex) {
+        const row = layout.getRow(itemIndex);
+        const colWidth = layout.getColumnWidth(containerWidth);
+        const rowHeight = sizeCache.getSize(row) - layout.gap;
+        if (horizontal) {
+            element.style.width = `${rowHeight}px`;
+            element.style.height = `${colWidth}px`;
+        }
+        else {
+            element.style.width = `${colWidth}px`;
+            element.style.height = `${rowHeight}px`;
+        }
+    }
+    function applyTemplate(el, item, index, isf) {
+        if (isf)
+            isf(index, itemState);
+        else {
+            itemState.selected = false;
+            itemState.focused = false;
+        }
+        const result = template(item, index, itemState);
+        if (typeof result === "string") {
+            el.innerHTML = result;
+        }
+        else {
+            el.innerHTML = "";
+            el.appendChild(result);
+        }
+    }
+    function gridRenderIfNeeded() {
+        if (engineState.destroyed)
+            return;
+        const scrollPos = engineState.scrollPosition;
+        const cs = engineState.containerSize;
+        if (!forceNextRender && scrollPos === lastScrollPosition && cs === lastContainerSize) {
+            return;
+        }
+        lastScrollPosition = scrollPos;
+        lastContainerSize = cs;
+        forceNextRender = false;
+        const totalRows = getRowCount();
+        if (cs <= 0 || totalRows === 0)
+            return;
+        // Visible row range
+        let visStart = sizeCache.indexAtOffset(scrollPos);
+        let visEnd = sizeCache.indexAtOffset(scrollPos + cs);
+        if (visEnd < totalRows - 1)
+            visEnd++;
+        visStart = Math.max(0, visStart);
+        visEnd = Math.min(totalRows - 1, Math.max(0, visEnd));
+        // Overscan in row space
+        const renderStart = Math.max(0, visStart - overscan);
+        const renderEnd = Math.min(totalRows - 1, visEnd + overscan);
+        // Range-unchanged fast path
+        if (renderStart === engineState.prevRangeStart && renderEnd === engineState.prevRangeEnd && !engineState.renderPending) {
+            return;
+        }
+        // Convert row range → flat item range
+        const itemRange = layout.getItemRange(renderStart, renderEnd, engineState.totalItems);
+        // Release items outside the new range
+        rendered.forEach((tracked, idx) => {
+            if (idx < itemRange.start || idx > itemRange.end) {
+                tracked.el.remove();
+                pool.release(tracked.el);
+                rendered.delete(idx);
+            }
+        });
+        // Render items in range
+        const gridItemClass = `${classPrefix}-item ${classPrefix}-grid-item`;
+        const isf = resolveItemState?.() ?? null;
+        const selClass = isf ? `${classPrefix}-item--selected` : "";
+        const focClass = isf ? `${classPrefix}-item--focused` : "";
+        for (let i = itemRange.start; i <= itemRange.end; i++) {
+            const item = getItem(i);
+            if (!item)
+                continue;
+            let tracked = rendered.get(i);
+            if (tracked === undefined) {
+                const el = pool.acquire();
+                el.className = gridItemClass;
+                el.setAttribute("data-index", String(i));
+                el.setAttribute("data-id", String(item.id));
+                applyTemplate(el, item, i, isf);
+                tracked = { el, lastId: item.id };
+                rendered.set(i, tracked);
+                contentElement.appendChild(el);
+            }
+            else if (tracked.lastId !== item.id) {
+                tracked.el.setAttribute("data-id", String(item.id));
+                tracked.lastId = item.id;
+                applyTemplate(tracked.el, item, i, isf);
+            }
+            if (isf) {
+                isf(i, itemState);
+                tracked.el.classList.toggle(selClass, itemState.selected);
+                tracked.el.classList.toggle(focClass, itemState.focused);
+                if (itemState.selected)
+                    tracked.el.setAttribute("aria-selected", "true");
+                else
+                    tracked.el.removeAttribute("aria-selected");
+            }
+            applySizeStyles(tracked.el, i);
+            tracked.el.style.transform = buildTransform(i);
+        }
+        // Update content size for scrollbar
+        const totalSize = sizeCache.getTotalSize();
+        contentElement.style[horizontal ? "width" : "height"] = totalSize + "px";
+        // Update engine state for other hooks/plugins
+        engineState.prevRangeStart = renderStart;
+        engineState.prevRangeEnd = renderEnd;
+        engineState.renderPending = false;
+        // Fill EngineState buffers for plugins that read them
+        const count = itemRange.end - itemRange.start + 1;
+        engineState.visibleCount = Math.min(count, engineState.capacity);
+        engineState.startIndex = itemRange.start;
+        for (let i = 0; i < engineState.visibleCount; i++) {
+            const idx = itemRange.start + i;
+            const row = layout.getRow(idx);
+            engineState.visibleIndices[i] = idx;
+            engineState.visibleOffsets[i] = sizeCache.getOffset(row);
+            engineState.visibleSizes[i] = sizeCache.getSize(row);
+        }
+    }
+    function gridForceRender() {
+        if (engineState.destroyed)
+            return;
+        sizeCache.rebuild(getRowCount());
+        engineState.prevRangeStart = -1;
+        engineState.prevRangeEnd = -1;
+        engineState.renderPending = true;
+        forceNextRender = true;
+        gridRenderIfNeeded();
+    }
+    return {
+        name: "grid",
+        priority: 10,
+        conflicts: ["masonry", "table"],
+        setup(ctx) {
+            const gap = config.gap ?? 0;
+            layout = createGridLayout({ columns: config.columns, gap });
+            sizeCache = ctx.sizeCache;
+            engineState = ctx.getState();
+            pool = ctx.pool;
+            contentElement = ctx.dom.content;
+            template = ctx.template;
+            horizontal = ctx.config.horizontal;
+            classPrefix = ctx.config.classPrefix;
+            overscan = ctx.config.overscan;
+            getItem = ctx.getItem.bind(ctx);
+            resolveItemState = () => ctx.getItemStateFn();
+            // Initialize container width
+            containerWidth = engineState.crossSize;
+            // Size cache in ROW space: each row = itemHeight + gap
+            // Inject grid context into dynamic height functions
+            const rawSpec = ctx.rawSizeSpec;
+            let baseRowSize;
+            if (typeof rawSpec === "function") {
+                const colWidth = layout.getColumnWidth(containerWidth);
+                const gridCtx = { columnWidth: colWidth, columns: config.columns, gap };
+                baseRowSize = rawSpec(0, gridCtx);
+                ctx.setSizeConfig((rowIndex) => {
+                    gridCtx.columnWidth = layout.getColumnWidth(containerWidth);
+                    const firstItem = rowIndex * config.columns;
+                    return rawSpec(firstItem, gridCtx) + gap;
+                });
+            }
+            else {
+                baseRowSize = rawSpec;
+                if (gap > 0) {
+                    ctx.setSizeConfig(baseRowSize + gap);
+                }
+            }
+            // Size cache must have rowCount entries, not totalItems.
+            // setSizeConfig creates with state.totalItems — fix immediately.
+            sizeCache.rebuild(getRowCount());
+            // Fix trailing gap: last row's cached size includes gap that
+            // shouldn't add empty space at the bottom.
+            if (gap > 0) {
+                const origGetTotalSize = sizeCache.getTotalSize;
+                sizeCache.getTotalSize = () => {
+                    const t = origGetTotalSize();
+                    return t > 0 ? t - gap : 0;
+                };
+            }
+            // Virtual total = row count (not item count)
+            ctx.setVirtualTotalFn(() => getRowCount());
+            // Add CSS class
+            ctx.dom.root.classList.add(`${classPrefix}--grid`);
+            // Replace render pipeline
+            ctx.setRenderFn(gridRenderIfNeeded, gridForceRender);
+            // ── Public methods ─────────────────────────────────────────
+            ctx.registerMethod("getGridLayout", () => layout);
+            ctx.registerMethod("updateGrid", (newConfig) => {
+                if (newConfig.columns !== undefined) {
+                    if (!Number.isInteger(newConfig.columns) || newConfig.columns < 1) {
+                        throw new Error("[vlist] updateGrid: columns must be >= 1");
+                    }
+                }
+                if (newConfig.gap !== undefined && newConfig.gap < 0) {
+                    throw new Error("[vlist] updateGrid: gap must be >= 0");
+                }
+                layout.update(newConfig);
+                if (newConfig.gap !== undefined || newConfig.columns !== undefined) {
+                    const newGap = layout.gap;
+                    if (typeof rawSpec === "function") {
+                        const gridCtx = { columnWidth: layout.getColumnWidth(containerWidth), columns: layout.columns, gap: newGap };
+                        ctx.setSizeConfig((rowIndex) => {
+                            gridCtx.columnWidth = layout.getColumnWidth(containerWidth);
+                            const firstItem = rowIndex * layout.columns;
+                            return rawSpec(firstItem, gridCtx) + newGap;
+                        });
+                    }
+                    else {
+                        ctx.setSizeConfig(baseRowSize + newGap);
+                    }
+                    sizeCache.rebuild(getRowCount());
+                }
+                if (newConfig.columns !== undefined) {
+                    ctx.setNavConfig({ ud: layout.columns });
+                }
+                containerWidth = engineState.crossSize;
+                gridForceRender();
+            });
+            // Override scrollToIndex: item index → row index
+            ctx.registerMethod("scrollToIndex", (index, alignOrOptions = "start") => {
+                const rowIndex = layout.getRow(index);
+                const totalRows = getRowCount();
+                if (totalRows === 0)
+                    return;
+                const safeRow = Math.max(0, Math.min(rowIndex, totalRows - 1));
+                const offset = sizeCache.getOffset(safeRow);
+                const rowHeight = sizeCache.getSize(safeRow);
+                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 - rowHeight) / 2;
+                        break;
+                    case "end":
+                        pos = offset - cs + rowHeight;
+                        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);
+                }
+            });
+            // ── 2D keyboard navigation ─────────────────────────────────
+            ctx.setNavConfig({
+                total: () => engineState.totalItems,
+                ud: config.columns,
+                lr: 1,
+                scrollIndex: (itemIndex) => layout.getRow(itemIndex),
+            });
+            // ── Cleanup ────────────────────────────────────────────────
+            ctx.registerDestroyHandler(() => {
+                for (const [, tracked] of rendered) {
+                    tracked.el.remove();
+                }
+                rendered.clear();
+                ctx.dom.root.classList.remove(`${classPrefix}--grid`);
+            });
+        },
+        hooks: {
+            onResize(_width, _height) {
+                const newCross = engineState.crossSize;
+                if (Math.abs(newCross - containerWidth) < 1)
+                    return;
+                containerWidth = newCross;
+                rendered.forEach((tracked, index) => {
+                    applySizeStyles(tracked.el, index);
+                    tracked.el.style.transform = buildTransform(index);
+                });
+            },
+        },
+        destroy() {
+            rendered.clear();
+        },
+    };
+}