vlist 1.9.1 → 2.0.0

package/dist/rendering/renderer.js

@@ -0,0 +1,586 @@
+/**
+ * vlist - DOM Rendering
+ * Efficient DOM rendering with element pooling
+ * Supports compression for large lists (1M+ items)
+ */
+import { PLACEHOLDER_ID_PREFIX } from "../constants";
+import { sortRenderedDOM } from "./sort";
+// =============================================================================
+// Element Pool
+// =============================================================================
+/**
+ * Create an element pool for recycling DOM elements
+ * Reduces garbage collection and improves performance
+ */
+export const createElementPool = (tagName = "div", maxSize = 100) => {
+    const pool = [];
+    let created = 0;
+    let reused = 0;
+    const acquire = () => {
+        const element = pool.pop();
+        if (element) {
+            reused++;
+            return element;
+        }
+        created++;
+        const newElement = document.createElement(tagName);
+        // Set static attributes once per element lifetime (never change)
+        newElement.setAttribute("role", "option");
+        return newElement;
+    };
+    const release = (element) => {
+        if (pool.length < maxSize) {
+            // Reset element state
+            element.className = "";
+            element.textContent = "";
+            element.removeAttribute("style");
+            element.removeAttribute("data-index");
+            element.removeAttribute("data-id");
+            pool.push(element);
+        }
+    };
+    const clear = () => {
+        pool.length = 0;
+    };
+    const stats = () => ({
+        poolSize: pool.length,
+        created,
+        reused,
+    });
+    return { acquire, release, clear, stats };
+};
+// =============================================================================
+// Release grace period
+// =============================================================================
+/**
+ * Number of render cycles to keep an item alive after it leaves the visible range.
+ * Prevents boundary thrashing: items near the overscan edge aren't recycled
+ * on small scroll deltas, preserving DOM element hover state and avoiding
+ * CSS transition replays.
+ */
+const RELEASE_GRACE = 2;
+// =============================================================================
+// Renderer
+// =============================================================================
+/**
+ * Create a renderer for managing DOM elements
+ * Supports compression for large lists
+ */
+export const createRenderer = (itemsContainer, template, sizeCache, classPrefix, totalItemsGetter, ariaIdPrefix, horizontal, crossAxisSize, compressionFns, striped, stripeIndexFn, ariaPosInSetGetter, interactive) => {
+    const pool = createElementPool("div");
+    const rendered = new Map();
+    // Cache compression state to avoid recalculating
+    let cachedCompression = null;
+    let cachedTotalItems = 0;
+    // Frame counter for release grace period
+    let frameCounter = 0;
+    // Cached stripe index function — resolved once per render frame, not per item
+    let cachedStripeFn = null;
+    // Track aria-setsize to avoid redundant updates on existing items
+    let lastAriaSetSize = "";
+    let lastAriaTotal = -1;
+    /**
+     * Get or update compression state.
+     * When compression functions are not injected, returns a trivial
+     * "not compressed" state — no compression module imported.
+     */
+    const getCompression = (totalItems) => {
+        if (cachedCompression && cachedTotalItems === totalItems) {
+            return cachedCompression;
+        }
+        if (compressionFns) {
+            cachedCompression = compressionFns.getState(totalItems, sizeCache);
+        }
+        else {
+            const h = sizeCache.getTotalSize();
+            cachedCompression = {
+                isCompressed: false,
+                actualSize: h,
+                virtualSize: h,
+                ratio: 1,
+            };
+        }
+        cachedTotalItems = totalItems;
+        return cachedCompression;
+    };
+    /**
+     * Reusable item state object to avoid allocation per render
+     * Note: Templates should not store or mutate this object reference
+     */
+    const reusableItemState = { selected: false, focused: false };
+    /**
+     * Get item state for template (reuses single object to reduce GC pressure)
+     */
+    const getItemState = (isSelected, isFocused) => {
+        reusableItemState.selected = isSelected;
+        reusableItemState.focused = isFocused;
+        return reusableItemState;
+    };
+    /**
+     * Apply template result to element
+     * Uses replaceChildren() for efficient HTMLElement replacement
+     */
+    const applyTemplate = (element, result) => {
+        if (typeof result === "string") {
+            element.innerHTML = result;
+        }
+        else {
+            // replaceChildren() is more efficient than innerHTML="" + appendChild()
+            // It's a single DOM operation instead of two
+            element.replaceChildren(result);
+        }
+    };
+    /**
+     * Apply static styles to an element (called once when element is created/recycled)
+     * Only sets height — position/top/left/right are already in .vlist-item CSS
+     * For variable heights, the height depends on the item index.
+     */
+    const applyStaticStyles = (element, index) => {
+        if (horizontal) {
+            element.style.width = `${sizeCache.getSize(index)}px`;
+            if (crossAxisSize != null) {
+                element.style.height = `${crossAxisSize}px`;
+            }
+        }
+        else {
+            element.style.height = `${sizeCache.getSize(index)}px`;
+        }
+    };
+    /**
+     * Calculate the offset for an element
+     * Uses compression-aware positioning for large lists
+     */
+    const calculateOffset = (index, compressionCtx) => {
+        if (compressionCtx) {
+            const compression = getCompression(compressionCtx.totalItems);
+            if (compression.isCompressed && compressionFns) {
+                // Use compression-aware positioning (injected)
+                return compressionFns.getPosition(index, compressionCtx.scrollPosition, sizeCache, compressionCtx.totalItems, compressionCtx.containerSize, compression, compressionCtx.rangeStart);
+            }
+        }
+        // Normal positioning (non-compressed or no context)
+        return sizeCache.getOffset(index);
+    };
+    // Pre-computed class names for toggle operations
+    const baseClass = `${classPrefix}-item`;
+    const groupHeaderClass = `${classPrefix}-group-header`;
+    const selectedClass = `${classPrefix}-item--selected`;
+    const focusedClass = `${classPrefix}-item--focused`;
+    const placeholderClass = `${classPrefix}-item--placeholder`;
+    const replacedClass = `${classPrefix}-item--replaced`;
+    const oddClass = `${classPrefix}-item--odd`;
+    /**
+     * Apply classes to element based on state
+     * Uses classList.toggle() for efficient incremental updates
+     */
+    const applyClasses = (element, isSelected, isFocused) => {
+        element.classList.toggle(selectedClass, isSelected);
+        element.classList.toggle(focusedClass, isFocused);
+    };
+    /**
+     * Render a single item — returns a TrackedItem for change tracking.
+     */
+    const renderItem = (index, item, isSelected, isFocused, compressionCtx) => {
+        const element = pool.acquire();
+        const isGH = !!item.__groupHeader;
+        const state = getItemState(isSelected, isFocused);
+        // Apply static styles once (position, dimensions)
+        applyStaticStyles(element, index);
+        // Group headers get a distinct class and role
+        element.className = isGH ? groupHeaderClass : baseClass;
+        // Set data attributes using dataset (faster than setAttribute)
+        element.dataset.index = String(index);
+        element.dataset.id = String(item.id);
+        if (isGH) {
+            element.setAttribute("role", "presentation");
+            element.removeAttribute("aria-selected");
+            element.removeAttribute("aria-setsize");
+            element.removeAttribute("aria-posinset");
+            element.removeAttribute("id");
+        }
+        else if (interactive !== false) {
+            element.setAttribute("role", "option");
+            element.ariaSelected = String(isSelected);
+            if (ariaIdPrefix) {
+                element.id = `${ariaIdPrefix}-item-${index}`;
+            }
+            if (totalItemsGetter) {
+                const total = totalItemsGetter();
+                if (total !== lastAriaTotal) {
+                    lastAriaTotal = total;
+                    lastAriaSetSize = String(total);
+                }
+                element.setAttribute("aria-setsize", lastAriaSetSize);
+                const posInSet = ariaPosInSetGetter ? ariaPosInSetGetter(index) : index + 1;
+                element.setAttribute("aria-posinset", String(posInSet));
+            }
+        }
+        else {
+            element.setAttribute("role", "listitem");
+            element.removeAttribute("aria-selected");
+            if (totalItemsGetter) {
+                const total = totalItemsGetter();
+                if (total !== lastAriaTotal) {
+                    lastAriaTotal = total;
+                    lastAriaSetSize = String(total);
+                }
+                element.setAttribute("aria-setsize", lastAriaSetSize);
+                const posInSet = ariaPosInSetGetter ? ariaPosInSetGetter(index) : index + 1;
+                element.setAttribute("aria-posinset", String(posInSet));
+            }
+        }
+        // Apply template
+        const result = template(item, index, state);
+        applyTemplate(element, result);
+        // Apply state-dependent classes (selected, focused)
+        applyClasses(element, isSelected, isFocused);
+        // Placeholder class — detected via ID prefix
+        if (String(item.id).startsWith(PLACEHOLDER_ID_PREFIX)) {
+            element.classList.add(placeholderClass);
+        }
+        // Striped: toggle odd class based on logical index (not DOM order)
+        // String modes ("data"/"even"/"odd"): use cachedStripeFn to map layout index → stripe index
+        if (striped) {
+            if (cachedStripeFn) {
+                const si = cachedStripeFn(index);
+                if (si < 0)
+                    element.classList.remove(oddClass);
+                else
+                    element.classList.toggle(oddClass, (si & 1) === 1);
+            }
+            else {
+                element.classList.toggle(oddClass, (index & 1) === 1);
+            }
+        }
+        const offset = calculateOffset(index, compressionCtx);
+        element.style.transform = horizontal
+            ? `translateX(${Math.round(offset)}px)`
+            : `translateY(${Math.round(offset)}px)`;
+        return {
+            element,
+            lastItemId: item.id,
+            lastSelected: isSelected,
+            lastFocused: isFocused,
+            lastOffset: offset,
+            lastSeenFrame: frameCounter,
+        };
+    };
+    /**
+     * Render items for a range.
+     *
+     * Optimizations vs. naive approach:
+     * - Release grace period: items outside the range keep their DOM element for
+     *   RELEASE_GRACE extra render cycles, preventing hover blink and CSS
+     *   transition replay on boundary items.
+     * - Change tracking: template re-evaluation, class toggles, position updates,
+     *   and aria writes are all skipped when the tracked state hasn't changed.
+     * - Lazy DocumentFragment: only allocated when new items actually enter the
+     *   viewport — zero allocation on scroll-only frames.
+     */
+    const render = (items, range, selectedIds, focusedIndex, compressionCtx) => {
+        frameCounter++;
+        // Release items outside the new range, with grace period to prevent
+        // boundary thrashing (hover blink, CSS transition replay).
+        // Items that just left the visible range keep their DOM element for
+        // RELEASE_GRACE extra render cycles — if they re-enter, the same
+        // element is reused with :hover state intact.
+        for (const [index, tracked] of rendered) {
+            if (index >= range.start && index <= range.end) {
+                tracked.lastSeenFrame = frameCounter;
+            }
+            else if (frameCounter - tracked.lastSeenFrame > RELEASE_GRACE) {
+                tracked.element.remove();
+                pool.release(tracked.element);
+                rendered.delete(index);
+            }
+        }
+        // Check if aria-setsize changed (total items mutated) — update existing items only when needed
+        let setSizeChanged = false;
+        if (totalItemsGetter) {
+            const total = totalItemsGetter();
+            if (total !== lastAriaTotal) {
+                lastAriaTotal = total;
+                lastAriaSetSize = String(total);
+                setSizeChanged = true;
+            }
+        }
+        // Resolve stripe function once per frame (not per item)
+        cachedStripeFn = (typeof striped === "string" && stripeIndexFn) ? stripeIndexFn() : null;
+        // DocumentFragment for batched DOM insertion — only allocated when needed
+        let fragment = null;
+        // Add/update items in range
+        for (let i = range.start; i <= range.end; i++) {
+            // Items array is 0-indexed relative to range.start
+            const itemIndex = i - range.start;
+            const item = items[itemIndex];
+            if (!item)
+                continue;
+            const isSelected = selectedIds.has(item.id);
+            const isFocused = i === focusedIndex;
+            const existing = rendered.get(i);
+            if (existing) {
+                // ── Fast path: skip work when nothing changed ──
+                const idChanged = existing.lastItemId !== item.id;
+                const selectedChanged = existing.lastSelected !== isSelected;
+                const focusedChanged = existing.lastFocused !== isFocused;
+                if (idChanged) {
+                    const existingId = String(existing.lastItemId);
+                    const newId = String(item.id);
+                    const wasPlaceholder = existingId.startsWith(PLACEHOLDER_ID_PREFIX);
+                    const isPlaceholder = newId.startsWith(PLACEHOLDER_ID_PREFIX);
+                    // Re-apply template when item data changes (placeholder -> real data)
+                    const state = getItemState(isSelected, isFocused);
+                    const result = template(item, i, state);
+                    applyTemplate(existing.element, result);
+                    existing.element.dataset.id = newId;
+                    // Update height in case variable heights differ for the new item
+                    applyStaticStyles(existing.element, i);
+                    // Toggle placeholder class
+                    existing.element.classList.toggle(placeholderClass, isPlaceholder);
+                    // Fade-in animation when placeholder is replaced with real data
+                    if (wasPlaceholder && !isPlaceholder) {
+                        existing.element.classList.add(replacedClass);
+                        setTimeout(() => {
+                            existing.element.classList.remove(replacedClass);
+                        }, 300);
+                    }
+                    existing.lastItemId = item.id;
+                    // Refresh aria-posinset when element is reused for a different item
+                    const isGH = !!item.__groupHeader;
+                    if (!isGH) {
+                        const posInSet = ariaPosInSetGetter ? ariaPosInSetGetter(i) : i + 1;
+                        existing.element.setAttribute("aria-posinset", String(posInSet));
+                    }
+                }
+                // Class + aria updates only when selection/focus changed
+                if (idChanged || selectedChanged || focusedChanged) {
+                    applyClasses(existing.element, isSelected, isFocused);
+                    existing.element.ariaSelected = String(isSelected);
+                    existing.lastSelected = isSelected;
+                    existing.lastFocused = isFocused;
+                }
+                // Position update only when offset changed
+                const offset = calculateOffset(i, compressionCtx);
+                if (existing.lastOffset !== offset) {
+                    existing.element.style.transform = horizontal
+                        ? `translateX(${Math.round(offset)}px)`
+                        : `translateY(${Math.round(offset)}px)`;
+                    existing.lastOffset = offset;
+                }
+                // Update aria-setsize on existing items only when total changed (rare)
+                if (setSizeChanged && !item.__groupHeader) {
+                    existing.element.setAttribute("aria-setsize", lastAriaSetSize);
+                }
+            }
+            else {
+                // Render new item — collect in fragment for batched insertion
+                const tracked = renderItem(i, item, isSelected, isFocused, compressionCtx);
+                if (!fragment)
+                    fragment = document.createDocumentFragment();
+                fragment.appendChild(tracked.element);
+                rendered.set(i, tracked);
+            }
+        }
+        // Single DOM insertion for all new elements — minimizes reflows
+        if (fragment) {
+            itemsContainer.appendChild(fragment);
+        }
+    };
+    /**
+     * Update positions of all rendered items (for compressed scrolling).
+     * Leverages change tracking — skips items whose offset hasn't changed.
+     */
+    const updatePositions = (compressionCtx) => {
+        for (const [index, tracked] of rendered) {
+            const offset = calculateOffset(index, compressionCtx);
+            if (tracked.lastOffset !== offset) {
+                tracked.element.style.transform = horizontal
+                    ? `translateX(${Math.round(offset)}px)`
+                    : `translateY(${Math.round(offset)}px)`;
+                tracked.lastOffset = offset;
+            }
+        }
+    };
+    /**
+     * Update a single item (explicit API call).
+     * Always re-applies the template because the caller signals that the item
+     * data has changed — even when the id stays the same (e.g. name update).
+     * Updates TrackedItem fields so subsequent scroll frames skip redundant work.
+     */
+    const updateItem = (index, item, isSelected, isFocused) => {
+        const existing = rendered.get(index);
+        if (!existing)
+            return;
+        const state = getItemState(isSelected, isFocused);
+        const result = template(item, index, state);
+        applyTemplate(existing.element, result);
+        applyClasses(existing.element, isSelected, isFocused);
+        existing.element.dataset.id = String(item.id);
+        existing.element.ariaSelected = String(isSelected);
+        existing.lastItemId = item.id;
+        existing.lastSelected = isSelected;
+        existing.lastFocused = isFocused;
+    };
+    /**
+     * Update only CSS classes on a rendered item (no template re-evaluation).
+     * Leverages change tracking — skips work when state is already current.
+     */
+    const updateItemClasses = (index, isSelected, isFocused) => {
+        const existing = rendered.get(index);
+        if (!existing)
+            return;
+        const selectedChanged = existing.lastSelected !== isSelected;
+        const focusedChanged = existing.lastFocused !== isFocused;
+        if (selectedChanged || focusedChanged) {
+            applyClasses(existing.element, isSelected, isFocused);
+            existing.lastSelected = isSelected;
+            existing.lastFocused = isFocused;
+        }
+    };
+    /**
+     * Get element by index
+     */
+    const getElement = (index) => {
+        return rendered.get(index)?.element;
+    };
+    /**
+     * Reorder DOM children so they follow logical data-index order.
+     * Called on scroll idle for accessibility — screen readers traverse
+     * DOM order, not visual (transform) order. Since items are
+     * position:absolute, this has zero visual impact.
+     */
+    const sortDOM = () => {
+        sortRenderedDOM(itemsContainer, rendered.keys(), (key) => rendered.get(key)?.element);
+    };
+    /**
+     * Clear all rendered items
+     */
+    const clear = () => {
+        for (const [, tracked] of rendered) {
+            tracked.element.remove();
+            pool.release(tracked.element);
+        }
+        rendered.clear();
+    };
+    /**
+     * Destroy renderer
+     */
+    const destroy = () => {
+        clear();
+        pool.clear();
+    };
+    return {
+        render,
+        updatePositions,
+        updateItem,
+        updateItemClasses,
+        getElement,
+        sortDOM,
+        clear,
+        destroy,
+    };
+};
+// =============================================================================
+// DOM Helpers
+// =============================================================================
+/**
+ * Create the vlist DOM structure
+ */
+export const createDOMStructure = (container, classPrefix, ariaLabel, horizontal, interactive) => {
+    // Root element
+    const root = document.createElement("div");
+    root.className = `${classPrefix}`;
+    if (horizontal) {
+        root.classList.add(`${classPrefix}--horizontal`);
+    }
+    // Viewport (scrollable container)
+    const viewport = document.createElement("div");
+    viewport.className = `${classPrefix}-viewport`;
+    viewport.setAttribute("tabindex", "-1");
+    viewport.style.height = "100%";
+    viewport.style.width = "100%";
+    if (horizontal) {
+        viewport.style.overflowX = "auto";
+        viewport.style.overflowY = "hidden";
+    }
+    else {
+        viewport.style.overflow = "auto";
+    }
+    // Content (sets the total scrollable size)
+    const content = document.createElement("div");
+    content.className = `${classPrefix}-content`;
+    content.style.position = "relative";
+    if (horizontal) {
+        content.style.height = "100%";
+        // Width will be set by updateContentWidth
+    }
+    else {
+        content.style.width = "100%";
+        // Height will be set by updateContentHeight
+    }
+    // Items container (holds rendered items)
+    const items = document.createElement("div");
+    items.className = `${classPrefix}-items`;
+    items.setAttribute("role", interactive !== false ? "listbox" : "list");
+    if (interactive !== false)
+        items.setAttribute("tabindex", "0");
+    if (ariaLabel)
+        items.setAttribute("aria-label", ariaLabel);
+    if (horizontal)
+        items.setAttribute("aria-orientation", "horizontal");
+    items.style.position = "relative";
+    if (horizontal) {
+        items.style.height = "100%";
+    }
+    else {
+        items.style.width = "100%";
+    }
+    // Live region for screen reader announcements
+    const liveRegion = document.createElement("div");
+    liveRegion.className = `${classPrefix}-live`;
+    liveRegion.style.cssText =
+        "position:absolute;width:1px;height:1px;padding:0;margin:-1px;" +
+            "overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0";
+    liveRegion.setAttribute("aria-live", "polite");
+    liveRegion.setAttribute("aria-atomic", "true");
+    liveRegion.setAttribute("role", "status");
+    // Assemble structure
+    content.appendChild(items);
+    viewport.appendChild(content);
+    root.appendChild(liveRegion);
+    root.appendChild(viewport);
+    container.appendChild(root);
+    return { root, viewport, content, items, liveRegion };
+};
+/**
+ * Update content height for virtual scrolling
+ */
+export const updateContentHeight = (content, totalHeight) => {
+    content.style.height = `${totalHeight}px`;
+};
+/**
+ * Update content width for horizontal virtual scrolling
+ */
+export const updateContentWidth = (content, totalWidth) => {
+    content.style.width = `${totalWidth}px`;
+};
+/**
+ * Get container dimensions
+ */
+export const getContainerDimensions = (viewport) => ({
+    width: viewport.clientWidth,
+    height: viewport.clientHeight,
+});
+/**
+ * Resolve container from selector or element
+ */
+export const resolveContainer = (container) => {
+    if (typeof container === "string") {
+        const element = document.querySelector(container);
+        if (!element) {
+            throw new Error(`[vlist] Container not found: ${container}`);
+        }
+        return element;
+    }
+    return container;
+};