vlist 1.9.1 → 2.0.0

package/dist/plugins/table/layout.js

@@ -0,0 +1,211 @@
+/**
+ * vlist/table - Layout
+ * Manages column widths, offsets, and resize operations.
+ *
+ * Column width resolution strategy:
+ * 1. Columns with explicit `width` get their requested width (clamped to min/max)
+ * 2. Remaining container space is distributed equally among columns without `width`
+ * 3. If all columns have explicit widths and total < container, no stretching occurs
+ * 4. If total column width > container, the table scrolls horizontally
+ *
+ * All offset calculations are O(n) where n = number of columns (typically small).
+ * Resize operations recalculate offsets for columns after the resized one.
+ */
+// =============================================================================
+// Defaults
+// =============================================================================
+const MIN_COLUMN_WIDTH = 50;
+const MAX_COLUMN_WIDTH = Infinity;
+// =============================================================================
+// Factory
+// =============================================================================
+/**
+ * Create a TableLayout instance.
+ *
+ * @param columnDefs - Column definitions from config
+ * @param globalMinWidth - Default min column width (from TableConfig.minColumnWidth)
+ * @param globalMaxWidth - Default max column width (from TableConfig.maxColumnWidth)
+ * @param globalResizable - Default resizable flag (from TableConfig.resizable)
+ * @returns TableLayout with column resolution and resize capabilities
+ */
+export const createTableLayout = (columnDefs, globalMinWidth = MIN_COLUMN_WIDTH, globalMaxWidth = MAX_COLUMN_WIDTH, globalResizable = true) => {
+    let defs = columnDefs;
+    let resolved = [];
+    let totalWidth = 0;
+    // =========================================================================
+    // Column Resolution
+    // =========================================================================
+    /**
+     * Build resolved columns from definitions.
+     * Does NOT compute widths yet — call resolve(containerWidth) for that.
+     */
+    const buildResolved = () => {
+        resolved = defs.map((def, index) => ({
+            def,
+            index,
+            width: 0,
+            minWidth: clampPositive(def.minWidth ?? globalMinWidth, 1),
+            maxWidth: def.maxWidth ?? globalMaxWidth,
+            resizable: def.resizable ?? globalResizable,
+            offset: 0,
+        }));
+    };
+    /**
+     * Resolve column widths given the available container width.
+     *
+     * Strategy:
+     * - Columns with explicit `width` are assigned that width (clamped)
+     * - Remaining space goes to columns without explicit `width`
+     * - If no columns lack a width, total is just the sum of assigned widths
+     * - Widths are always clamped to [minWidth, maxWidth]
+     */
+    const resolve = (containerWidth) => {
+        if (resolved.length === 0) {
+            totalWidth = 0;
+            return;
+        }
+        let usedWidth = 0;
+        let flexCount = 0;
+        // First pass: assign explicit widths, count flex columns
+        for (let i = 0; i < resolved.length; i++) {
+            const col = resolved[i];
+            const def = col.def;
+            if (def.width !== undefined) {
+                col.width = clamp(def.width, col.minWidth, col.maxWidth);
+                usedWidth += col.width;
+            }
+            else {
+                flexCount++;
+            }
+        }
+        // Second pass: distribute remaining space to flex columns
+        if (flexCount) {
+            const remaining = Math.max(0, containerWidth - usedWidth);
+            const flexWidth = remaining / flexCount;
+            for (let i = 0; i < resolved.length; i++) {
+                const col = resolved[i];
+                if (col.def.width === undefined) {
+                    col.width = clamp(flexWidth, col.minWidth, col.maxWidth);
+                }
+            }
+        }
+        // Third pass: compute cumulative offsets and total width
+        recalculateOffsets();
+    };
+    /**
+     * Recalculate offsets from column widths.
+     * Called after resolve() and after any resize operation.
+     */
+    const recalculateOffsets = () => {
+        let offset = 0;
+        for (let i = 0; i < resolved.length; i++) {
+            const col = resolved[i];
+            col.offset = offset;
+            offset += col.width;
+        }
+        totalWidth = offset;
+    };
+    // =========================================================================
+    // Resize
+    // =========================================================================
+    /**
+     * Resize a column to a new width.
+     * Clamps to the column's min/max bounds.
+     * Recalculates offsets for all subsequent columns.
+     *
+     * @returns The actual new width after clamping
+     */
+    const resizeColumn = (columnIndex, newWidth) => {
+        if (columnIndex < 0 || columnIndex >= resolved.length)
+            return 0;
+        const col = resolved[columnIndex];
+        if (!col.resizable)
+            return col.width;
+        const clamped = clamp(newWidth, col.minWidth, col.maxWidth);
+        col.width = clamped;
+        // Recalculate offsets from this column onward
+        recalculateOffsets();
+        return clamped;
+    };
+    // =========================================================================
+    // Accessors
+    // =========================================================================
+    const getColumn = (index) => {
+        return resolved[index];
+    };
+    const getColumnAtX = (x) => {
+        // Binary search for the column containing x
+        if (resolved.length === 0)
+            return undefined;
+        if (x < 0)
+            return resolved[0];
+        if (x >= totalWidth)
+            return resolved[resolved.length - 1];
+        let lo = 0;
+        let hi = resolved.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            const col = resolved[mid];
+            if (x < col.offset) {
+                hi = mid - 1;
+            }
+            else if (x >= col.offset + col.width) {
+                lo = mid + 1;
+            }
+            else {
+                return col;
+            }
+        }
+        return resolved[lo];
+    };
+    const getColumnOffset = (columnIndex) => {
+        if (columnIndex < 0 || columnIndex >= resolved.length)
+            return 0;
+        return resolved[columnIndex].offset;
+    };
+    const getColumnWidth = (columnIndex) => {
+        if (columnIndex < 0 || columnIndex >= resolved.length)
+            return 0;
+        return resolved[columnIndex].width;
+    };
+    // =========================================================================
+    // Update
+    // =========================================================================
+    /**
+     * Replace column definitions and rebuild.
+     * The caller must call resolve(containerWidth) after this to compute widths.
+     */
+    const updateColumns = (columns) => {
+        defs = columns;
+        buildResolved();
+    };
+    // =========================================================================
+    // Initialize
+    // =========================================================================
+    buildResolved();
+    // =========================================================================
+    // Return
+    // =========================================================================
+    return {
+        get columns() {
+            return resolved;
+        },
+        get totalWidth() {
+            return totalWidth;
+        },
+        resolve,
+        updateColumns,
+        resizeColumn,
+        getColumn,
+        getColumnAtX,
+        getColumnOffset,
+        getColumnWidth,
+    };
+};
+// =============================================================================
+// Helpers
+// =============================================================================
+/** Clamp a value to [min, max] */
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/** Ensure a positive value (at least `floor`) */
+const clampPositive = (value, floor) => Math.max(floor, value);

package/dist/plugins/table/plugin.d.ts

@@ -0,0 +1,20 @@
+/**
+ * vlist v2 — Table Plugin
+ *
+ * Switches from list layout to a data table with columns, resizable headers,
+ * sticky header row, and cell-based rendering.
+ *
+ * Priority 10 — runs before selection (50) so layout is ready.
+ *
+ * Restrictions:
+ * - Cannot be combined with grid or masonry plugins
+ * - Cannot be combined with horizontal orientation
+ * - Cannot be combined with reverse mode
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../core/types";
+import type { TableConfig } from "./types";
+export interface TablePluginConfig<T extends VListItem = VListItem> extends TableConfig<T> {
+}
+export declare function table<T extends VListItem = VListItem>(config: TablePluginConfig<T>): VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/table/plugin.js

@@ -0,0 +1,391 @@
+/**
+ * vlist v2 — Table Plugin
+ *
+ * Switches from list layout to a data table with columns, resizable headers,
+ * sticky header row, and cell-based rendering.
+ *
+ * Priority 10 — runs before selection (50) so layout is ready.
+ *
+ * Restrictions:
+ * - Cannot be combined with grid or masonry plugins
+ * - Cannot be combined with horizontal orientation
+ * - Cannot be combined with reverse mode
+ */
+import { createTableLayout } from "./layout";
+import { createTableHeader } from "./header";
+import { createTableRenderer } from "./renderer";
+// =============================================================================
+// Config
+// =============================================================================
+const EMPTY_ID_SET = new Set();
+// =============================================================================
+// Factory
+// =============================================================================
+export function table(config) {
+    if (!config.columns?.length) {
+        throw new Error("[vlist] table: columns must be a non-empty array");
+    }
+    if (config.rowHeight === undefined && config.estimatedRowHeight === undefined) {
+        throw new Error("[vlist] table: either rowHeight or estimatedRowHeight is required");
+    }
+    let tableLayout = null;
+    let tableHeader = null;
+    let tableRenderer = null;
+    let engineState;
+    let sizeCache;
+    let storedCtx = null;
+    let selectedIdsGetter = null;
+    let focusedIndexGetter = null;
+    let selectionResolved = false;
+    let lastScrollPosition = -1;
+    let lastContainerSize = -1;
+    let lastTotalItems = -1;
+    let forceNextRender = true;
+    let lastAriaRowCount = -1;
+    function resolveSelectionMethods() {
+        if (selectionResolved || !storedCtx)
+            return;
+        selectionResolved = true;
+        selectedIdsGetter = storedCtx.getMethod("_getSelectedIds") ?? null;
+        focusedIndexGetter = storedCtx.getMethod("_getFocusedIndex") ?? null;
+    }
+    // =========================================================================
+    // Render Functions
+    // =========================================================================
+    // Persistent per-render buffers — hoisted to avoid per-frame allocation
+    const rangeItems = [];
+    const range = { start: 0, end: 0 };
+    function tableRenderIfNeeded() {
+        if (engineState.destroyed || !storedCtx || !tableRenderer || !tableLayout)
+            return;
+        const scrollPos = engineState.scrollPosition;
+        const containerSize = engineState.containerSize;
+        const totalItems = engineState.totalItems;
+        if (!forceNextRender &&
+            scrollPos === lastScrollPosition &&
+            containerSize === lastContainerSize &&
+            totalItems === lastTotalItems) {
+            return;
+        }
+        lastScrollPosition = scrollPos;
+        lastContainerSize = containerSize;
+        lastTotalItems = totalItems;
+        forceNextRender = false;
+        if (containerSize <= 0 || totalItems === 0)
+            return;
+        // Update aria-rowcount when item count changes (+1 for header row)
+        const ariaRowCount = totalItems + 1;
+        if (ariaRowCount !== lastAriaRowCount) {
+            lastAriaRowCount = ariaRowCount;
+            storedCtx.dom.root.setAttribute("aria-rowcount", `${ariaRowCount}`);
+        }
+        // Calculate visible range
+        let visStart = sizeCache.indexAtOffset(scrollPos);
+        let visEnd = sizeCache.indexAtOffset(scrollPos + containerSize);
+        if (visEnd < totalItems - 1)
+            visEnd++;
+        visStart = Math.max(0, visStart);
+        visEnd = Math.min(totalItems - 1, visEnd);
+        const overscan = storedCtx.config.overscan;
+        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;
+        }
+        resolveSelectionMethods();
+        const selectedIds = selectedIdsGetter?.() ?? EMPTY_ID_SET;
+        const focusedIndex = focusedIndexGetter?.() ?? -1;
+        rangeItems.length = 0;
+        for (let i = renderStart; i <= renderEnd; i++) {
+            const item = storedCtx.getItem(i);
+            if (item)
+                rangeItems.push(item);
+        }
+        range.start = renderStart;
+        range.end = renderEnd;
+        tableRenderer.render(rangeItems, range, selectedIds, focusedIndex);
+        // Update engine state
+        engineState.prevRangeStart = renderStart;
+        engineState.prevRangeEnd = renderEnd;
+        engineState.renderPending = false;
+        const count = renderEnd - renderStart + 1;
+        engineState.visibleCount = Math.min(count, engineState.capacity);
+        engineState.startIndex = renderStart;
+        for (let i = 0; i < engineState.visibleCount; i++) {
+            const idx = renderStart + i;
+            engineState.visibleIndices[i] = idx;
+            engineState.visibleOffsets[i] = sizeCache.getOffset(idx);
+            engineState.visibleSizes[i] = sizeCache.getSize(idx);
+        }
+        // Update content size
+        storedCtx.dom.content.style.height = sizeCache.getTotalSize() + "px";
+    }
+    function tableForceRender() {
+        if (engineState.destroyed)
+            return;
+        engineState.prevRangeStart = -1;
+        engineState.prevRangeEnd = -1;
+        engineState.renderPending = true;
+        forceNextRender = true;
+        tableRenderIfNeeded();
+    }
+    // =========================================================================
+    // Plugin
+    // =========================================================================
+    return {
+        name: "table",
+        priority: 10,
+        conflicts: ["grid", "masonry"],
+        setup(ctx) {
+            storedCtx = ctx;
+            engineState = ctx.getState();
+            sizeCache = ctx.sizeCache;
+            const { dom, config: resolvedConfig, emitter } = ctx;
+            const { classPrefix } = resolvedConfig;
+            if (resolvedConfig.horizontal) {
+                throw new Error("[vlist] table: cannot be used with horizontal orientation");
+            }
+            if (resolvedConfig.reverse) {
+                throw new Error("[vlist] table: cannot be used with reverse mode");
+            }
+            // ── Resolve config ──────────────────────────────────────────
+            const resizable = config.resizable ?? true;
+            const minColumnWidth = config.minColumnWidth ?? 50;
+            const maxColumnWidth = config.maxColumnWidth ?? Infinity;
+            const rowBorders = config.rowBorders ?? true;
+            const rowHeight = config.rowHeight;
+            const headerHeight = config.headerHeight ??
+                (typeof rowHeight === "number" ? rowHeight : 40);
+            // ── Sort state ──────────────────────────────────────────────
+            let sortKey = config.sort?.key ?? null;
+            let sortDirection = config.sort?.direction ?? "asc";
+            // ── Create table layout ─────────────────────────────────────
+            tableLayout = createTableLayout(config.columns, minColumnWidth, maxColumnWidth, resizable);
+            // ── Set row height ──────────────────────────────────────────
+            if (typeof rowHeight === "function" || typeof rowHeight === "number") {
+                ctx.setSizeConfig(rowHeight);
+            }
+            ctx.rebuildSizeCache();
+            // ── CSS classes ─────────────────────────────────────────────
+            dom.root.classList.add(`${classPrefix}--table`);
+            if (rowBorders)
+                dom.root.classList.add(`${classPrefix}--table-row-borders`);
+            if (config.columnBorders)
+                dom.root.classList.add(`${classPrefix}--table-col-borders`);
+            // ── ARIA ────────────────────────────────────────────────────
+            if (resolvedConfig.interactive) {
+                dom.root.setAttribute("tabindex", "0");
+            }
+            dom.root.setAttribute("role", "grid");
+            dom.root.setAttribute("aria-colcount", `${config.columns.length}`);
+            dom.viewport.setAttribute("role", "none");
+            dom.content.setAttribute("role", "rowgroup");
+            // ── Resolve initial column widths ───────────────────────────
+            const containerWidth = engineState.crossSize;
+            tableLayout.resolve(containerWidth);
+            // ── Content width ───────────────────────────────────────────
+            const updateContentWidth = () => {
+                if (!tableLayout)
+                    return;
+                dom.content.style.minWidth = `${tableLayout.totalWidth}px`;
+            };
+            // ── Column resize handler ───────────────────────────────────
+            const onColumnResize = (columnIndex, newWidth) => {
+                if (!tableLayout)
+                    return;
+                const col = tableLayout.getColumn(columnIndex);
+                if (!col)
+                    return;
+                const previousWidth = col.width;
+                const actualWidth = tableLayout.resizeColumn(columnIndex, newWidth);
+                tableHeader?.update(tableLayout);
+                tableRenderer?.updateColumnLayout(tableLayout);
+                updateContentWidth();
+                emitter.emit("column:resize", {
+                    key: col.def.key,
+                    index: columnIndex,
+                    previousWidth,
+                    width: actualWidth,
+                });
+            };
+            // ── Column sort handler ─────────────────────────────────────
+            const onColumnSort = (event) => {
+                sortKey = event.direction === null ? null : event.key;
+                sortDirection = event.direction ?? "asc";
+                tableHeader?.updateSort(sortKey, sortDirection);
+                emitter.emit("column:sort", event);
+            };
+            // ── Create table header ─────────────────────────────────────
+            tableHeader = createTableHeader(dom.root, headerHeight, classPrefix, onColumnResize, onColumnSort);
+            tableHeader.rebuild(tableLayout);
+            if (sortKey)
+                tableHeader.updateSort(sortKey, sortDirection);
+            updateContentWidth();
+            // ── Create table renderer ───────────────────────────────────
+            tableRenderer = createTableRenderer(dom.content, () => sizeCache, tableLayout, config.columns, classPrefix, classPrefix, () => engineState.totalItems, resolvedConfig.striped || undefined);
+            // ── Wire render pipeline ────────────────────────────────────
+            ctx.setRenderFn(tableRenderIfNeeded, tableForceRender);
+            // ── Header scroll sync ──────────────────────────────────────
+            const headerWithSync = tableHeader;
+            let lastSyncedScrollLeft = -1;
+            const syncHeaderScroll = () => {
+                const scrollLeft = dom.viewport.scrollLeft;
+                if (scrollLeft !== lastSyncedScrollLeft) {
+                    lastSyncedScrollLeft = scrollLeft;
+                    headerWithSync?.syncScroll?.(scrollLeft);
+                }
+            };
+            dom.viewport.addEventListener("scroll", syncHeaderScroll, { passive: true });
+            // ── Public methods ──────────────────────────────────────────
+            ctx.registerMethod("updateColumns", (columns) => {
+                if (!tableLayout || !tableHeader)
+                    return;
+                tableLayout.updateColumns(columns);
+                tableLayout.resolve(engineState.crossSize);
+                tableHeader.rebuild(tableLayout);
+                if (sortKey)
+                    tableHeader.updateSort(sortKey, sortDirection);
+                updateContentWidth();
+                tableRenderer?.updateColumnLayout(tableLayout);
+                tableRenderer?.clear();
+                ctx.forceRender();
+            });
+            ctx.registerMethod("resizeColumn", (keyOrIndex, width) => {
+                if (!tableLayout)
+                    return;
+                let columnIndex;
+                if (typeof keyOrIndex === "string") {
+                    const cols = tableLayout.columns;
+                    columnIndex = -1;
+                    for (let i = 0; i < cols.length; i++) {
+                        if (cols[i].def.key === keyOrIndex) {
+                            columnIndex = i;
+                            break;
+                        }
+                    }
+                    if (columnIndex === -1)
+                        return;
+                }
+                else {
+                    columnIndex = keyOrIndex;
+                }
+                onColumnResize(columnIndex, width);
+            });
+            ctx.registerMethod("getColumnWidths", () => {
+                if (!tableLayout)
+                    return {};
+                const result = {};
+                const cols = tableLayout.columns;
+                for (let i = 0; i < cols.length; i++) {
+                    result[cols[i].def.key] = cols[i].width;
+                }
+                return result;
+            });
+            ctx.registerMethod("setSort", (key, direction) => {
+                sortKey = key;
+                sortDirection = direction ?? "asc";
+                tableHeader?.updateSort(sortKey, sortDirection);
+            });
+            ctx.registerMethod("getSort", () => {
+                return { key: sortKey, direction: sortDirection };
+            });
+            ctx.registerMethod("_getTableLayout", () => tableLayout);
+            ctx.registerMethod("_getTableHeaderHeight", () => headerHeight);
+            ctx.registerMethod("_updateRenderedItem", (index, item, isSelected, isFocused) => {
+                tableRenderer?.updateItem(index, item, isSelected, isFocused);
+            });
+            ctx.registerMethod("_replaceTableRenderer", (newRenderer) => {
+                tableRenderer = newRenderer;
+            });
+            ctx.registerMethod("_updateTableForGroups", (isHeaderFn, headerTemplate) => {
+                tableRenderer?.setGroupHeaderFn(isHeaderFn, headerTemplate);
+            });
+            // Replace item-class updater for selection integration
+            ctx.registerMethod("_updateItemClasses", (index, isSelected, isFocused) => {
+                tableRenderer?.updateItemClasses(index, isSelected, isFocused);
+            });
+            // ── Keyboard horizontal scroll ─────────────────────────────
+            ctx.registerKeydownHandler((event) => {
+                if (event.key !== "ArrowLeft" && event.key !== "ArrowRight")
+                    return;
+                if (!tableLayout)
+                    return;
+                const cols = tableLayout.columns;
+                if (cols.length === 0)
+                    return;
+                const viewportWidth = dom.viewport.clientWidth;
+                if (tableLayout.totalWidth <= viewportWidth)
+                    return;
+                const scrollLeft = dom.viewport.scrollLeft;
+                if (event.key === "ArrowRight") {
+                    for (let i = 0; i < cols.length; i++) {
+                        if (cols[i].offset > scrollLeft + 1) {
+                            dom.viewport.scrollLeft = cols[i].offset;
+                            event.preventDefault();
+                            return;
+                        }
+                    }
+                }
+                else {
+                    for (let i = cols.length - 1; i >= 0; i--) {
+                        if (cols[i].offset < scrollLeft - 1) {
+                            dom.viewport.scrollLeft = cols[i].offset;
+                            event.preventDefault();
+                            return;
+                        }
+                    }
+                    if (scrollLeft > 0) {
+                        dom.viewport.scrollLeft = 0;
+                        event.preventDefault();
+                    }
+                }
+            });
+            // ── Cleanup ─────────────────────────────────────────────────
+            ctx.registerDestroyHandler(() => {
+                dom.viewport.removeEventListener("scroll", syncHeaderScroll);
+                tableHeader?.destroy();
+                tableHeader = null;
+                tableRenderer?.destroy();
+                tableRenderer = null;
+                dom.content.style.minWidth = "";
+                dom.root.classList.remove(`${classPrefix}--table`);
+                dom.root.classList.remove(`${classPrefix}--table-row-borders`);
+                dom.root.classList.remove(`${classPrefix}--table-col-borders`);
+                dom.root.removeAttribute("role");
+                dom.root.removeAttribute("aria-colcount");
+                dom.root.removeAttribute("aria-rowcount");
+                dom.root.removeAttribute("tabindex");
+                dom.viewport.removeAttribute("role");
+                dom.content.removeAttribute("role");
+            });
+        },
+        hooks: {
+            onResize(_width, _height) {
+                if (!tableLayout || !storedCtx)
+                    return;
+                const newCross = engineState.crossSize;
+                tableLayout.resolve(newCross);
+                tableHeader?.update(tableLayout);
+                tableRenderer?.updateColumnLayout(tableLayout);
+                if (tableLayout) {
+                    storedCtx.dom.content.style.minWidth = `${tableLayout.totalWidth}px`;
+                }
+            },
+            onAfterScroll() {
+                if (!storedCtx || !tableHeader)
+                    return;
+                const h = tableHeader;
+                h?.syncScroll?.(storedCtx.dom.viewport.scrollLeft);
+            },
+        },
+        destroy() {
+            tableHeader?.destroy();
+            tableHeader = null;
+            tableRenderer?.destroy();
+            tableRenderer = null;
+            storedCtx = null;
+        },
+    };
+}