vlist 2.0.0 → 2.0.1

package/dist/plugins/table/renderer.js

@@ -1,625 +0,0 @@
-/**
- * vlist/table - Renderer
- * Renders virtualized rows with cell-based layout within the virtual scroll container.
- *
- * Each row is an absolutely positioned element (like the list renderer),
- * containing child elements for each cell. Cells are sized and positioned
- * according to the resolved column layout from TableLayout.
- *
- * Key design decisions:
- * - Rows are the unit of virtualization (same as list mode — 1:1 with items)
- * - Each row contains N cell elements (one per column)
- * - Row positioning is translateY-based (from the size cache)
- * - Cell positioning uses absolute left + width from the column layout
- * - Element pooling avoids createElement cost (row-level pooling)
- * - Change tracking skips template re-evaluation when data + state unchanged
- * - Release grace period prevents boundary thrashing (hover blink, transition replay)
- * - DocumentFragment batched insertion for new elements
- *
- * Performance:
- * - O(1) Set-based visibility diffing (not O(n) .some())
- * - Template re-evaluation skipped when item id + selection/focus state unchanged
- * - Position update skipped when coordinates unchanged (position tracking)
- * - Cell widths are only updated when column layout changes (not every scroll frame)
- * - Released elements removed from DOM immediately, pooled for reuse
- *
- * DOM structure per row:
- *   .vlist-item.vlist-table-row (position: absolute, translateY)
- *   ├── .vlist-table-cell [col 0] (position: absolute, left, width)
- *   ├── .vlist-table-cell [col 1]
- *   └── ...
- */
-import { calculateCompressedItemPosition } from "../../rendering/scale";
-import { claimPlaceholderSelection } from "../../plugins/selection/state";
-// =============================================================================
-// Element Pool (row-level)
-// =============================================================================
-const createElementPool = () => {
-    const pool = [];
-    return {
-        acquire: () => pool.pop() || document.createElement("div"),
-        release: (el) => {
-            el.parentNode?.removeChild(el);
-            if (pool.length < 200) {
-                el.className = "";
-                el.removeAttribute("data-id");
-                el.removeAttribute("data-index");
-                el.removeAttribute("aria-selected");
-                el.removeAttribute("aria-rowindex");
-                el.removeAttribute("role");
-                el.style.cssText = "";
-                el.textContent = "";
-                pool.push(el);
-            }
-        },
-        clear: () => { pool.length = 0; },
-    };
-};
-// =============================================================================
-// Factory
-// =============================================================================
-/**
- * Create a TableRenderer instance.
- *
- * @param container - The .vlist-items container element
- * @param sizeCache - Size cache for row offset lookups
- * @param layout - Table layout for column widths/offsets
- * @param columns - Column definitions (for cell templates)
- * @param classPrefix - CSS class prefix
- * @param ariaIdPrefix - Prefix for ARIA IDs
- * @param columnBorders - Whether to show vertical borders between cells
- * @param rowBorders - Whether to show horizontal borders between rows
- * @param getTotalItems - Function to get total item count (for ARIA)
- * @returns TableRendererInstance
- */
-export const createTableRenderer = (container, getSizeCache, layout, _columns, classPrefix, ariaIdPrefix, getTotalItems, striped, stripeIndexFn) => {
-    const pool = createElementPool();
-    const rendered = new Map();
-    let lastAriaSetSize = -1;
-    let currentLayout = layout;
-    // Cached stripe index function — resolved once per render frame, not per row
-    let cachedStripeFn = null;
-    // ── Group header support ──
-    // When groups are active, the renderer needs to handle group header
-    // pseudo-items differently: full-width row, no cells, custom template.
-    let groupHeaderFn = null;
-    let groupHeaderTemplate = null;
-    const setGroupHeaderFn = (fn, template) => {
-        groupHeaderFn = fn;
-        groupHeaderTemplate = template;
-    };
-    // =========================================================================
-    // Helpers
-    // =========================================================================
-    /** Toggle aria-selected attribute */
-    const setAriaSelected = (el, selected) => {
-        selected ? el.setAttribute("aria-selected", "true") : el.removeAttribute("aria-selected");
-    };
-    /** Set common row data attributes */
-    const setRowAttrs = (el, role, id, index) => {
-        el.setAttribute("role", role);
-        el.setAttribute("data-id", String(id));
-        el.setAttribute("data-index", String(index));
-    };
-    /** Check if an item id represents a placeholder (async loading) */
-    const isPH = (id) => String(id).startsWith("__placeholder_");
-    // =========================================================================
-    // CSS Classes (precomputed)
-    // =========================================================================
-    const rowClass = `${classPrefix}-item ${classPrefix}-table-row`;
-    const selectedClass = `${classPrefix}-item--selected`;
-    const focusedClass = `${classPrefix}-item--focused`;
-    const cellClass = `${classPrefix}-table-cell`;
-    const cellCenterClass = `${classPrefix}-table-cell--center`;
-    const cellRightClass = `${classPrefix}-table-cell--right`;
-    const oddClass = `${classPrefix}-item--odd`;
-    const placeholderClass = `${classPrefix}-item--placeholder`;
-    const replacedClass = `${classPrefix}-item--replaced`;
-    const groupHeaderRowClass = `${classPrefix}-item ${classPrefix}-table-row ${classPrefix}-table-group-header`;
-    const groupHeaderContentClass = `${classPrefix}-table-group-header-content`;
-    // =========================================================================
-    // Cell Template Application
-    // =========================================================================
-    /**
-     * Render a cell's content using the column's cell template or default accessor.
-     */
-    const applyCellTemplate = (cell, item, col, rowIndex, isPlaceholder = false) => {
-        if (col.def.cell) {
-            const result = col.def.cell(item, col.def, rowIndex);
-            if (typeof result === "string") {
-                cell.innerHTML = result;
-            }
-            else {
-                cell.replaceChildren(result);
-            }
-        }
-        else {
-            // Default: show item[column.key] as text
-            const value = item[col.def.key];
-            const text = value != null ? String(value) : "";
-            if (isPlaceholder && text) {
-                // Wrap in <span> so CSS skeleton styling can target the element
-                // (bare text nodes can't be styled with background/border-radius)
-                cell.innerHTML = `<span>${text}</span>`;
-            }
-            else {
-                cell.textContent = text;
-            }
-        }
-    };
-    /**
-     * Apply CSS classes to a row element based on state.
-     */
-    const applyRowClasses = (element, index, isSelected, isFocused, isPlaceholder = false) => {
-        let className = rowClass;
-        if (striped) {
-            if (cachedStripeFn) {
-                const si = cachedStripeFn(index);
-                if (si >= 0 && (si & 1) === 1)
-                    className += ` ${oddClass}`;
-            }
-            else if ((index & 1) === 1) {
-                className += ` ${oddClass}`;
-            }
-        }
-        if (isPlaceholder)
-            className += ` ${placeholderClass}`;
-        if (isSelected)
-            className += ` ${selectedClass}`;
-        if (isFocused)
-            className += ` ${focusedClass}`;
-        element.className = className;
-    };
-    // =========================================================================
-    // Row Positioning (compression-aware)
-    // =========================================================================
-    /**
-     * Calculate the Y offset for a row.
-     * Uses compression-aware positioning for large datasets (withScale).
-     */
-    const calculateRowOffset = (index, sc, compressionCtx) => {
-        if (compressionCtx?.compression?.isCompressed) {
-            return Math.round(calculateCompressedItemPosition(index, compressionCtx.scrollPosition, sc, compressionCtx.totalItems, compressionCtx.containerSize, compressionCtx.compression, compressionCtx.rangeStart));
-        }
-        return sc.getOffset(index);
-    };
-    // =========================================================================
-    // Cell Sizing & Positioning
-    // =========================================================================
-    /**
-     * Apply alignment style to a cell based on column definition.
-     */
-    const applyCellAlign = (cell, col) => {
-        const align = col.def.align;
-        if (align === "center") {
-            cell.classList.add(cellCenterClass);
-            cell.classList.remove(cellRightClass);
-        }
-        else if (align === "right") {
-            cell.classList.add(cellRightClass);
-            cell.classList.remove(cellCenterClass);
-        }
-        else {
-            cell.classList.remove(cellCenterClass, cellRightClass);
-        }
-    };
-    // =========================================================================
-    // Row Building
-    // =========================================================================
-    /**
-     * Create or reuse cells for a row element, matching the current column count.
-     */
-    const ensureCells = (rowElement, existingCells) => {
-        const cols = currentLayout.columns;
-        const targetCount = cols.length;
-        // Reuse existing cells where possible
-        if (existingCells.length === targetCount) {
-            return existingCells;
-        }
-        const cells = [];
-        for (let i = 0; i < targetCount; i++) {
-            let cell;
-            if (i < existingCells.length) {
-                cell = existingCells[i];
-            }
-            else {
-                cell = document.createElement("div");
-                cell.className = cellClass;
-                rowElement.appendChild(cell);
-            }
-            cells.push(cell);
-        }
-        // Remove excess cells
-        for (let i = targetCount; i < existingCells.length; i++) {
-            existingCells[i].remove();
-        }
-        return cells;
-    };
-    /**
-     * Render a group header row: full-width, no cells, custom template.
-     */
-    const renderGroupHeaderRow = (item, index, sc, compressionCtx) => {
-        const element = pool.acquire();
-        const headerItem = item;
-        const height = sc.getSize(index);
-        const offset = calculateRowOffset(index, sc, compressionCtx);
-        // Set all styles in one operation (element was reset by pool.release)
-        element.style.cssText = `width:${currentLayout.totalWidth}px;height:${height}px;transform:translateY(${offset}px)`;
-        element.className = groupHeaderRowClass;
-        // ARIA — group header is presentational, not a data row
-        setRowAttrs(element, "presentation", item.id, index);
-        element.removeAttribute("aria-selected");
-        element.removeAttribute("aria-rowindex");
-        // Clear any leftover cells from pooled element reuse
-        element.replaceChildren();
-        // Create the single content container
-        const content = document.createElement("div");
-        content.className = groupHeaderContentClass;
-        if (groupHeaderTemplate) {
-            const result = groupHeaderTemplate(headerItem.groupKey, headerItem.groupIndex);
-            if (typeof result === "string") {
-                content.innerHTML = result;
-            }
-            else {
-                content.appendChild(result);
-            }
-        }
-        element.appendChild(content);
-        return {
-            element,
-            cells: [], // No cells for group headers
-            index,
-            isGroupHeader: true,
-            lastItemId: item.id,
-            lastSelected: false,
-            lastFocused: false,
-            lastOffset: offset,
-            lastHeight: height,
-        };
-    };
-    /**
-     * Render a full row: create element, set cells, apply state.
-     * Returns a TrackedRow for the rendered map.
-     */
-    const renderRow = (item, index, isSelected, isFocused, sc, compressionCtx) => {
-        const element = pool.acquire();
-        const height = sc.getSize(index);
-        const offset = calculateRowOffset(index, sc, compressionCtx);
-        const isPlaceholder = isPH(item.id);
-        // Set all row styles in one operation (element was reset by pool.release)
-        element.style.cssText = `width:${currentLayout.totalWidth}px;height:${height}px;transform:translateY(${offset}px)`;
-        applyRowClasses(element, index, isSelected, isFocused, isPlaceholder);
-        // ARIA attributes
-        setRowAttrs(element, "row", item.id, index);
-        element.id = `${ariaIdPrefix}-item-${index}`;
-        element.setAttribute("aria-rowindex", String(index + 2)); // +2: header is row 1
-        setAriaSelected(element, isSelected);
-        // Create cells
-        const cells = ensureCells(element, []);
-        const cols = currentLayout.columns;
-        for (let i = 0; i < cells.length && i < cols.length; i++) {
-            const cell = cells[i];
-            const col = cols[i];
-            cell.style.cssText = `left:${col.offset}px;width:${col.width}px`;
-            cell.setAttribute("role", "gridcell");
-            cell.setAttribute("aria-colindex", String(i + 1));
-            applyCellAlign(cell, col);
-            applyCellTemplate(cell, item, col, index, isPlaceholder);
-        }
-        return {
-            element,
-            cells,
-            index,
-            isGroupHeader: false,
-            lastItemId: item.id,
-            lastSelected: isSelected,
-            lastFocused: isFocused,
-            lastOffset: offset,
-            lastHeight: height,
-        };
-    };
-    // =========================================================================
-    // Main Render
-    // =========================================================================
-    /**
-     * Render rows for a range of items.
-     *
-     * Called by the feature's tableRenderIfNeeded() on each scroll frame.
-     *
-     * Performs incremental updates:
-     * - New rows: created and positioned
-     * - Existing rows with same item: state/position update only
-     * - Existing rows with different item: full template re-evaluation
-     * - Rows outside range: released after grace period
-     */
-    const render = (items, range, selectedIds, focusedIndex, compressionCtx) => {
-        // Release items outside the new range immediately.
-        // Tables don't need a grace period — row hover is a simple background
-        // change with no CSS transitions to preserve, and each graced row
-        // carries N cell elements so the DOM cost is high.
-        for (const [index, tracked] of rendered) {
-            if (index < range.start || index > range.end) {
-                pool.release(tracked.element);
-                rendered.delete(index);
-            }
-        }
-        // Check if aria-setsize changed
-        let setSizeChanged = false;
-        const total = getTotalItems();
-        if (total !== lastAriaSetSize) {
-            lastAriaSetSize = total;
-            setSizeChanged = true;
-        }
-        // DocumentFragment for batched DOM insertion of new elements
-        let fragment = null;
-        // Resolve size cache and stripe function once per frame (not per item)
-        const sc = getSizeCache();
-        cachedStripeFn = (typeof striped === "string" && stripeIndexFn) ? stripeIndexFn() : null;
-        // Render each item 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;
-            let isSelected = selectedIds.has(item.id);
-            const isFocused = i === focusedIndex;
-            // ── Check if this item is a group header ──
-            const isHeader = groupHeaderFn ? groupHeaderFn(item) : false;
-            const existing = rendered.get(i);
-            if (existing) {
-                // ── Check if row type changed (data row ↔ group header) ──
-                if (existing.isGroupHeader !== isHeader) {
-                    // Type changed — release old element, create new one
-                    pool.release(existing.element);
-                    rendered.delete(i);
-                    const tracked = isHeader
-                        ? renderGroupHeaderRow(item, i, sc, compressionCtx)
-                        : renderRow(item, i, isSelected, isFocused, sc, compressionCtx);
-                    rendered.set(i, tracked);
-                    if (!fragment)
-                        fragment = document.createDocumentFragment();
-                    fragment.appendChild(tracked.element);
-                    continue;
-                }
-                if (isHeader) {
-                    // ── Group header fast path ──
-                    const idChanged = existing.lastItemId !== item.id;
-                    if (idChanged) {
-                        // Different group header — re-render content
-                        const headerItem = item;
-                        const content = existing.element.firstElementChild;
-                        if (content && groupHeaderTemplate) {
-                            const result = groupHeaderTemplate(headerItem.groupKey, headerItem.groupIndex);
-                            if (typeof result === "string") {
-                                content.innerHTML = result;
-                            }
-                            else {
-                                content.replaceChildren(result);
-                            }
-                        }
-                        existing.element.setAttribute("data-id", String(item.id));
-                        existing.lastItemId = item.id;
-                    }
-                    // Position update (compression-aware)
-                    const offset = calculateRowOffset(i, sc, compressionCtx);
-                    if (existing.lastOffset !== offset) {
-                        existing.lastOffset = offset;
-                        existing.element.style.transform = `translateY(${offset}px)`;
-                    }
-                    // Height update (only when changed)
-                    const height = sc.getSize(i);
-                    if (existing.lastHeight !== height) {
-                        existing.lastHeight = height;
-                        existing.element.style.height = `${height}px`;
-                    }
-                }
-                else {
-                    // ── Data row path (existing logic) ──
-                    const idChanged = existing.lastItemId !== item.id;
-                    const selectedChanged = existing.lastSelected !== isSelected;
-                    const focusedChanged = existing.lastFocused !== isFocused;
-                    if (idChanged) {
-                        // Different item at this index — full re-render of cells
-                        const wasPlaceholder = existing.lastItemId != null && isPH(existing.lastItemId);
-                        const isPlaceholder = isPH(item.id);
-                        // Transfer selection from placeholder → real item ID (async loading)
-                        if (!isPlaceholder && claimPlaceholderSelection(selectedIds, i, item.id)) {
-                            isSelected = true;
-                        }
-                        const cols = currentLayout.columns;
-                        for (let c = 0; c < existing.cells.length && c < cols.length; c++) {
-                            applyCellTemplate(existing.cells[c], item, cols[c], i, isPlaceholder);
-                        }
-                        applyRowClasses(existing.element, i, isSelected, isFocused, isPlaceholder);
-                        existing.element.setAttribute("data-id", String(item.id));
-                        setAriaSelected(existing.element, isSelected);
-                        // 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;
-                        existing.lastSelected = isSelected;
-                        existing.lastFocused = isFocused;
-                    }
-                    else if (selectedChanged || focusedChanged) {
-                        // Same item — only update classes/aria if state changed
-                        applyRowClasses(existing.element, i, isSelected, isFocused, isPH(item.id));
-                        setAriaSelected(existing.element, isSelected);
-                        existing.lastSelected = isSelected;
-                        existing.lastFocused = isFocused;
-                    }
-                    // Position update only when offset changed (compression-aware)
-                    const offset = calculateRowOffset(i, sc, compressionCtx);
-                    if (existing.lastOffset !== offset) {
-                        existing.lastOffset = offset;
-                        existing.element.style.transform = `translateY(${offset}px)`;
-                    }
-                    // Update row height only when changed
-                    const height = sc.getSize(i);
-                    if (existing.lastHeight !== height) {
-                        existing.lastHeight = height;
-                        existing.element.style.height = `${height}px`;
-                    }
-                    // Update ARIA set size if changed
-                    if (setSizeChanged) {
-                        existing.element.setAttribute("aria-rowindex", String(i + 2));
-                    }
-                }
-            }
-            else {
-                // Transfer selection from placeholder → real item ID (async loading)
-                if (claimPlaceholderSelection(selectedIds, i, item.id)) {
-                    isSelected = true;
-                }
-                // New row — create and collect in fragment for batched insertion
-                const tracked = isHeader
-                    ? renderGroupHeaderRow(item, i, sc, compressionCtx)
-                    : renderRow(item, i, isSelected, isFocused, sc, compressionCtx);
-                rendered.set(i, tracked);
-                if (!fragment)
-                    fragment = document.createDocumentFragment();
-                fragment.appendChild(tracked.element);
-            }
-        }
-        // Single DOM insertion for all new elements — minimizes reflows
-        if (fragment) {
-            container.appendChild(fragment);
-        }
-    };
-    // =========================================================================
-    // Position Update (compressed scrolling)
-    // =========================================================================
-    /**
-     * Update positions of all rendered rows (for compressed scrolling).
-     * Called when the scroll position changed but the visible range didn't —
-     * in compressed mode, items are positioned relative to the viewport so
-     * they must be repositioned on every scroll frame.
-     */
-    const updatePositions = (compressionCtx) => {
-        const sc = getSizeCache();
-        for (const [index, tracked] of rendered) {
-            const offset = calculateRowOffset(index, sc, compressionCtx);
-            if (tracked.lastOffset !== offset) {
-                tracked.lastOffset = offset;
-                tracked.element.style.transform = `translateY(${offset}px)`;
-            }
-        }
-    };
-    // =========================================================================
-    // Single Item Update
-    // =========================================================================
-    /**
-     * Update a single row (explicit API call).
-     * Always re-applies cell templates because the caller signals that the item
-     * data has changed — even when the id stays the same (e.g. cover 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;
-        // Group headers are not selectable — skip state updates
-        if (existing.isGroupHeader)
-            return;
-        const cols = currentLayout.columns;
-        for (let c = 0; c < existing.cells.length && c < cols.length; c++) {
-            applyCellTemplate(existing.cells[c], item, cols[c], index);
-        }
-        existing.element.setAttribute("data-id", String(item.id));
-        existing.lastItemId = item.id;
-        applyRowClasses(existing.element, index, isSelected, isFocused);
-        setAriaSelected(existing.element, isSelected);
-        existing.lastSelected = isSelected;
-        existing.lastFocused = isFocused;
-    };
-    /**
-     * Update only CSS classes on a rendered row (no template re-evaluation).
-     */
-    const updateItemClasses = (index, isSelected, isFocused) => {
-        const existing = rendered.get(index);
-        if (!existing)
-            return;
-        // Group headers are not selectable — skip state updates
-        if (existing.isGroupHeader)
-            return;
-        const selectedChanged = existing.lastSelected !== isSelected;
-        const focusedChanged = existing.lastFocused !== isFocused;
-        if (selectedChanged || focusedChanged) {
-            applyRowClasses(existing.element, index, isSelected, isFocused);
-            setAriaSelected(existing.element, isSelected);
-            existing.lastSelected = isSelected;
-            existing.lastFocused = isFocused;
-        }
-    };
-    // =========================================================================
-    // Column Layout Update
-    // =========================================================================
-    /**
-     * Update cell positions and widths for all rendered rows.
-     * Called after column resize or layout change.
-     */
-    const updateColumnLayout = (layout) => {
-        currentLayout = layout;
-        const cols = layout.columns;
-        for (const [, tracked] of rendered) {
-            // Update row width (applies to both data rows and group headers)
-            tracked.element.style.width = `${layout.totalWidth}px`;
-            // Update each cell's position and width (skip group headers — no cells)
-            if (tracked.cells.length > 0) {
-                for (let i = 0; i < tracked.cells.length && i < cols.length; i++) {
-                    const cell = tracked.cells[i];
-                    const col = cols[i];
-                    cell.style.left = `${col.offset}px`;
-                    cell.style.width = `${col.width}px`;
-                }
-            }
-        }
-    };
-    // =========================================================================
-    // Accessors
-    // =========================================================================
-    /**
-     * Get a rendered row element by item index.
-     */
-    const getElement = (index) => {
-        return rendered.get(index)?.element;
-    };
-    // =========================================================================
-    // Clear & Destroy
-    // =========================================================================
-    /**
-     * Clear all rendered rows — return them to the pool.
-     */
-    const clear = () => {
-        for (const [, tracked] of rendered) {
-            pool.release(tracked.element);
-        }
-        rendered.clear();
-        lastAriaSetSize = -1;
-    };
-    /**
-     * Destroy renderer and cleanup all resources.
-     */
-    const destroy = () => {
-        clear();
-        pool.clear();
-    };
-    // =========================================================================
-    // Return
-    // =========================================================================
-    return {
-        render,
-        updatePositions,
-        updateItem,
-        updateItemClasses,
-        getElement,
-        updateColumnLayout,
-        setGroupHeaderFn,
-        clear,
-        destroy,
-    };
-};

package/dist/plugins/table/types.js

@@ -1,12 +0,0 @@
-/**
- * vlist/table - Types
- * Types for data table layout with columns, resizable headers, and cell rendering.
- *
- * A table transforms a flat list of items into rows of cells:
- * - Each row corresponds to one item (1:1 mapping, unlike grid)
- * - Each cell is positioned horizontally according to its column definition
- * - A sticky header row displays column labels and resize handles
- * - Columns can be resized by dragging header borders
- * - Variable row heights are supported (Mode A and Mode B)
- */
-export {};

package/dist/plugins/transition/index.js

@@ -1,5 +0,0 @@
-/**
- * vlist/transition — FLIP-based enter/exit animations
- */
-// v2 plugin
-export { transition } from "./plugin";