vlist 1.9.0 → 2.0.0

package/dist/plugins/selection/state.js

@@ -0,0 +1,332 @@
+/**
+ * vlist - Selection State Management
+ * Pure functions for managing selection state
+ */
+import { PLACEHOLDER_ID_PREFIX } from "../../constants";
+// =============================================================================
+// Placeholder Selection Transfer
+// =============================================================================
+/**
+ * Transfer selection from a placeholder ID to a real item ID.
+ *
+ * When select-all or shift-click ranges include unloaded async items, the
+ * selection Set contains index-based placeholder IDs (`__placeholder_{index}`).
+ * When those items load, this function swaps the placeholder entry for the
+ * real item ID so the item renders as selected.
+ *
+ * @returns `true` if a transfer occurred (the item was selected via its placeholder).
+ */
+export const claimPlaceholderSelection = (selectedIds, index, itemId) => {
+    if (String(itemId).startsWith(PLACEHOLDER_ID_PREFIX))
+        return false;
+    const phId = PLACEHOLDER_ID_PREFIX + index;
+    if (selectedIds.has(phId)) {
+        selectedIds.delete(phId);
+        selectedIds.add(itemId);
+        return true;
+    }
+    return false;
+};
+// =============================================================================
+// State Creation
+// =============================================================================
+/**
+ * Create initial selection state
+ * Pure function - no side effects
+ */
+export const createSelectionState = (initial) => ({
+    selected: new Set(initial ?? []),
+    focusedIndex: -1,
+    focusVisible: false,
+});
+// =============================================================================
+// Selection Operations
+// =============================================================================
+/**
+ * Select items by ID
+ * Pure function - returns new state
+ */
+export const selectItems = (state, ids, mode) => {
+    if (mode === "none")
+        return state;
+    const newSelected = new Set(state.selected);
+    if (mode === "single") {
+        // Single mode: replace selection
+        newSelected.clear();
+        if (ids.length > 0) {
+            newSelected.add(ids[0]);
+        }
+    }
+    else {
+        // Multiple mode: add to selection
+        for (const id of ids) {
+            newSelected.add(id);
+        }
+    }
+    return {
+        ...state,
+        selected: newSelected,
+    };
+};
+/**
+ * Deselect items by ID
+ * Pure function - returns new state
+ */
+export const deselectItems = (state, ids) => {
+    const newSelected = new Set(state.selected);
+    for (const id of ids) {
+        newSelected.delete(id);
+    }
+    return {
+        ...state,
+        selected: newSelected,
+    };
+};
+/**
+ * Toggle item selection
+ * Pure function - returns new state
+ */
+export const toggleSelection = (state, id, mode) => {
+    if (mode === "none")
+        return state;
+    if (state.selected.has(id)) {
+        return deselectItems(state, [id]);
+    }
+    else {
+        return selectItems(state, [id], mode);
+    }
+};
+/**
+ * Select all items
+ * Pure function - returns new state
+ */
+export const selectAll = (state, items, mode) => {
+    if (mode !== "multiple")
+        return state;
+    return {
+        ...state,
+        selected: new Set(items.map((item) => item.id)),
+    };
+};
+/**
+ * Clear all selection
+ * Pure function - returns new state
+ */
+export const clearSelection = (state) => ({
+    ...state,
+    selected: new Set(),
+});
+// =============================================================================
+// Focus Management
+// =============================================================================
+/**
+ * Set focused index
+ * Mutates state in-place to avoid allocation on hot path
+ */
+export const setFocusedIndex = (state, index) => {
+    state.focusedIndex = index;
+    return state;
+};
+/**
+ * Move focus up
+ * Mutates state in-place to avoid allocation on hot path
+ * @param delta - Number of items to move by (default 1). Useful for grid layouts where row navigation moves by `columns`.
+ */
+export const moveFocusUp = (state, totalItems, wrap = false, delta = 1) => {
+    if (totalItems === 0)
+        return state;
+    let newIndex = state.focusedIndex - delta;
+    if (newIndex < 0) {
+        newIndex = wrap ? totalItems - 1 : 0;
+    }
+    state.focusedIndex = newIndex;
+    return state;
+};
+/**
+ * Move focus down
+ * Mutates state in-place to avoid allocation on hot path
+ * @param delta - Number of items to move by (default 1). Useful for grid layouts where row navigation moves by `columns`.
+ */
+export const moveFocusDown = (state, totalItems, wrap = false, delta = 1) => {
+    if (totalItems === 0)
+        return state;
+    let newIndex = state.focusedIndex + delta;
+    if (newIndex >= totalItems) {
+        newIndex = wrap ? 0 : totalItems - 1;
+    }
+    state.focusedIndex = newIndex;
+    return state;
+};
+/**
+ * Move focus to first item
+ * Mutates state in-place to avoid allocation on hot path
+ */
+export const moveFocusToFirst = (state, totalItems) => {
+    if (totalItems === 0)
+        return state;
+    state.focusedIndex = 0;
+    return state;
+};
+/**
+ * Move focus to last item
+ * Mutates state in-place to avoid allocation on hot path
+ */
+export const moveFocusToLast = (state, totalItems) => {
+    if (totalItems === 0)
+        return state;
+    state.focusedIndex = totalItems - 1;
+    return state;
+};
+/**
+ * Move focus by page (for Page Up/Down)
+ * Mutates state in-place to avoid allocation on hot path
+ */
+export const moveFocusByPage = (state, totalItems, pageSize, direction) => {
+    if (totalItems === 0)
+        return state;
+    let newIndex = direction === "up"
+        ? state.focusedIndex - pageSize
+        : state.focusedIndex + pageSize;
+    // Clamp to valid range
+    newIndex = Math.max(0, Math.min(totalItems - 1, newIndex));
+    state.focusedIndex = newIndex;
+    return state;
+};
+// =============================================================================
+// Queries
+// =============================================================================
+/**
+ * Check if an item is selected
+ * Pure function - no side effects
+ */
+export const isSelected = (state, id) => {
+    return state.selected.has(id);
+};
+/**
+ * Get selected IDs as array
+ * Pure function - no side effects
+ */
+export const getSelectedIds = (state) => {
+    return Array.from(state.selected);
+};
+/**
+ * Get selected items using ID lookup (O(k) where k = selected count)
+ * Pure function - no side effects
+ */
+export const getSelectedItems = (state, getItemById) => {
+    const items = [];
+    for (const id of state.selected) {
+        const item = getItemById(id);
+        if (item) {
+            items.push(item);
+        }
+    }
+    return items;
+};
+/**
+ * Get selection count
+ * Pure function - no side effects
+ */
+export const getSelectionCount = (state) => {
+    return state.selected.size;
+};
+/**
+ * Check if selection is empty
+ * Pure function - no side effects
+ */
+export const isSelectionEmpty = (state) => {
+    return state.selected.size === 0;
+};
+// =============================================================================
+// Keyboard Selection Helpers
+// =============================================================================
+/**
+ * Handle keyboard selection (Space/Enter on focused item)
+ * Pure function - returns new state
+ */
+export const selectFocused = (state, items, mode) => {
+    if (mode === "none" ||
+        state.focusedIndex < 0 ||
+        state.focusedIndex >= items.length) {
+        return state;
+    }
+    const item = items[state.focusedIndex];
+    if (!item)
+        return state;
+    return toggleSelection(state, item.id, mode);
+};
+/**
+ * Handle shift+click range selection
+ * Pure function - returns new state
+ */
+export const selectRange = (state, items, fromIndex, toIndex, mode) => {
+    if (mode !== "multiple")
+        return state;
+    const start = Math.min(fromIndex, toIndex);
+    const end = Math.max(fromIndex, toIndex);
+    const idsToSelect = [];
+    for (let i = start; i <= end; i++) {
+        const item = items[i];
+        if (item) {
+            idsToSelect.push(item.id);
+        }
+    }
+    return selectItems(state, idsToSelect, mode);
+};
+// =============================================================================
+// v2 Plugin Helpers — mutable, zero-allocation variants for hot path
+// =============================================================================
+export function selectOne(selected, id, mode) {
+    if (mode === "single")
+        selected.clear();
+    if (mode !== "none")
+        selected.add(id);
+}
+export function toggleOne(selected, id, mode) {
+    if (mode === "none")
+        return;
+    if (selected.has(id)) {
+        selected.delete(id);
+    }
+    else {
+        if (mode === "single")
+            selected.clear();
+        selected.add(id);
+    }
+}
+export function selectAllItems(selected, items) {
+    for (let i = 0; i < items.length; i++)
+        selected.add(items[i].id);
+}
+export function selectRangeMut(selected, items, fromIndex, toIndex) {
+    const start = Math.min(fromIndex, toIndex);
+    const end = Math.max(fromIndex, toIndex);
+    for (let i = start; i <= end; i++) {
+        const item = items[i];
+        if (item)
+            selected.add(item.id);
+    }
+}
+export function moveFocus(state, delta, totalItems, reverse) {
+    if (totalItems === 0)
+        return;
+    const d = reverse ? -delta : delta;
+    let idx = state.focusedIndex + d;
+    if (idx < 0)
+        idx = 0;
+    if (idx >= totalItems)
+        idx = totalItems - 1;
+    state.focusedIndex = idx;
+}
+export function getSelectedArray(selected) {
+    return Array.from(selected);
+}
+export { getSelectedItems as getSelectedItemsImmutable };
+export function getSelectedItemsMut(selected, items) {
+    const result = [];
+    for (const item of items) {
+        if (selected.has(item.id))
+            result.push(item);
+    }
+    return result;
+}

package/dist/plugins/snapshots/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * vlist/snapshots - Scroll Save/Restore
+ */
+export { snapshots, type SnapshotsPluginConfig } from "./plugin";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/snapshots/index.js

@@ -0,0 +1,5 @@
+/**
+ * vlist/snapshots - Scroll Save/Restore
+ */
+// v2 plugin
+export { snapshots } from "./plugin";

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

@@ -0,0 +1,17 @@
+/**
+ * vlist v2 — Snapshots Plugin
+ *
+ * Scroll save/restore for SPA navigation and tab switching.
+ * Captures the first visible item index + sub-pixel offset,
+ * surviving list recreation and compression mode changes.
+ *
+ * Priority: 50 (runs late — needs other plugins initialized)
+ */
+import type { VListItem, ScrollSnapshot } from "../../types";
+import type { VListPlugin } from "../../core/types";
+export interface SnapshotsPluginConfig {
+    restore?: ScrollSnapshot;
+    autoSave?: string;
+}
+export declare function snapshots<T extends VListItem = VListItem>(config?: SnapshotsPluginConfig): VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/snapshots/plugin.js

@@ -0,0 +1,301 @@
+/**
+ * vlist v2 — Snapshots Plugin
+ *
+ * Scroll save/restore for SPA navigation and tab switching.
+ * Captures the first visible item index + sub-pixel offset,
+ * surviving list recreation and compression mode changes.
+ *
+ * Priority: 50 (runs late — needs other plugins initialized)
+ */
+// =============================================================================
+// Helpers
+// =============================================================================
+const readSnapshot = (key) => {
+    try {
+        const raw = sessionStorage.getItem(key);
+        if (!raw)
+            return undefined;
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+};
+// =============================================================================
+// Factory
+// =============================================================================
+export function snapshots(config) {
+    const autoSaveKey = config?.autoSave;
+    const restoreSnapshot = autoSaveKey
+        ? readSnapshot(autoSaveKey)
+        : config?.restore;
+    let disposed = false;
+    let saveToStorage = null;
+    return {
+        name: "snapshots",
+        priority: 50,
+        setup(ctx) {
+            const { sizeCache, emitter } = ctx;
+            const state = ctx.getState();
+            // ── getScrollSnapshot ──────────────────────────────────────
+            const getScrollSnapshot = () => {
+                const scrollTop = state.scrollPosition;
+                const totalItems = state.totalItems;
+                const getSelected = ctx.getMethod("getSelected");
+                const selectedIds = getSelected?.();
+                if (totalItems === 0) {
+                    const snap = { index: 0, offsetInItem: 0, total: 0 };
+                    if (selectedIds?.length)
+                        snap.selectedIds = selectedIds;
+                    return snap;
+                }
+                let index;
+                let offsetInItem;
+                if (state.isCompressed && state.compressionRatio !== 1) {
+                    const virtualSize = state.totalSize;
+                    const scrollRatio = scrollTop / virtualSize;
+                    const exactIndex = scrollRatio * totalItems;
+                    index = Math.max(0, Math.min(Math.floor(exactIndex), totalItems - 1));
+                    const fraction = exactIndex - index;
+                    offsetInItem = fraction * sizeCache.getSize(index);
+                }
+                else {
+                    index = sizeCache.indexAtOffset(scrollTop);
+                    offsetInItem = scrollTop - sizeCache.getOffset(index);
+                }
+                offsetInItem = Math.max(0, offsetInItem);
+                const snap = {
+                    index,
+                    offsetInItem,
+                    total: totalItems,
+                    scrollTop,
+                };
+                const itemSize = sizeCache.getSize(index);
+                if (itemSize)
+                    snap.offsetRatio = offsetInItem / itemSize;
+                const layoutToData = ctx.getMethod("_layoutToDataIndex");
+                if (layoutToData) {
+                    let di = layoutToData(index);
+                    if (di < 0) {
+                        for (let i = index + 1; i < totalItems; i++) {
+                            di = layoutToData(i);
+                            if (di >= 0)
+                                break;
+                        }
+                    }
+                    if (di >= 0)
+                        snap.dataIndex = di;
+                }
+                const getDataTotal = ctx.getMethod("_getTotal");
+                if (getDataTotal)
+                    snap.dataTotal = getDataTotal();
+                if (selectedIds?.length)
+                    snap.selectedIds = selectedIds;
+                const getFocusedId = ctx.getMethod("_getFocusedId");
+                if (getFocusedId) {
+                    const focusedId = getFocusedId();
+                    if (focusedId !== undefined)
+                        snap.focusedId = focusedId;
+                }
+                return snap;
+            };
+            ctx.registerMethod("getScrollSnapshot", getScrollSnapshot);
+            // ── restoreScroll ──────────────────────────────────────────
+            const restoreScroll = (snapshot, restoreSelection = true) => {
+                const { index, offsetInItem, selectedIds, focusedId } = snapshot;
+                let effectiveTotal = state.totalItems;
+                const bootstrapTotal = snapshot.dataTotal ?? snapshot.total;
+                if (effectiveTotal === 0 && bootstrapTotal && bootstrapTotal > 0) {
+                    const setTotal = ctx.getMethod("_setTotal");
+                    if (setTotal) {
+                        setTotal(bootstrapTotal);
+                        effectiveTotal = state.totalItems;
+                    }
+                    sizeCache.rebuild(effectiveTotal);
+                    const updateCompression = ctx.getMethod("_updateCompressionMode");
+                    if (updateCompression)
+                        updateCompression();
+                    if (!state.isCompressed) {
+                        ctx.updateContentSize(sizeCache.getTotalSize());
+                    }
+                }
+                if (effectiveTotal === 0)
+                    return;
+                if (!Number.isFinite(index) || !Number.isFinite(offsetInItem))
+                    return;
+                const sizeCacheTotal = sizeCache.getTotal();
+                if (sizeCacheTotal !== effectiveTotal) {
+                    sizeCache.rebuild(effectiveTotal);
+                    const updateCompression = ctx.getMethod("_updateCompressionMode");
+                    if (updateCompression)
+                        updateCompression();
+                    if (!state.isCompressed) {
+                        ctx.updateContentSize(sizeCache.getTotalSize());
+                    }
+                }
+                const dataToLayout = ctx.getMethod("_dataToLayoutIndex");
+                let resolvedIndex = index;
+                if (snapshot.dataIndex !== undefined && snapshot.dataIndex >= 0) {
+                    resolvedIndex = dataToLayout
+                        ? dataToLayout(snapshot.dataIndex)
+                        : snapshot.dataIndex;
+                }
+                else if (dataToLayout) {
+                    resolvedIndex = dataToLayout(index);
+                }
+                const safeIndex = Math.max(0, Math.min(resolvedIndex, effectiveTotal - 1));
+                const currentItemSize = sizeCache.getSize(safeIndex);
+                const resolvedOffset = snapshot.offsetRatio !== undefined
+                    ? snapshot.offsetRatio * currentItemSize
+                    : Math.min(offsetInItem, currentItemSize);
+                let scrollPosition;
+                if (state.isCompressed && state.compressionRatio !== 1) {
+                    const currentDataTotal = ctx.getMethod("_getTotal")?.();
+                    const dataTotalMatch = currentDataTotal !== undefined
+                        && snapshot.dataTotal === currentDataTotal;
+                    if (snapshot.scrollTop !== undefined && (snapshot.total === effectiveTotal || dataTotalMatch)) {
+                        scrollPosition = snapshot.scrollTop;
+                    }
+                    else {
+                        const fraction = currentItemSize ? resolvedOffset / currentItemSize : 0;
+                        scrollPosition =
+                            ((safeIndex + fraction) / effectiveTotal) * state.totalSize;
+                    }
+                }
+                else {
+                    scrollPosition = sizeCache.getOffset(safeIndex) + resolvedOffset;
+                }
+                const maxScroll = Math.max(0, state.totalSize - state.containerSize);
+                scrollPosition = Math.max(0, Math.min(scrollPosition, maxScroll));
+                const usedShortcut = scrollPosition === snapshot.scrollTop;
+                if (snapshot.dataIndex !== undefined && snapshot.dataIndex >= 0) {
+                    const fraction = currentItemSize ? resolvedOffset / currentItemSize : 0;
+                    ctx.registerMethod("_restoreAnchor", {
+                        dataIndex: snapshot.dataIndex,
+                        fraction,
+                        skipAdjust: usedShortcut,
+                    });
+                    ctx.registerMethod("_suppressSave", 1);
+                }
+                ctx.scrollTo(scrollPosition);
+                if (restoreSelection && selectedIds?.length) {
+                    const selectFn = ctx.getMethod("select");
+                    if (selectFn)
+                        selectFn(...selectedIds);
+                }
+                const loadVisibleFn = ctx.getMethod("loadVisibleRange");
+                const restoreFocus = () => {
+                    if (focusedId === undefined)
+                        return;
+                    const focusByIdFn = ctx.getMethod("_focusById");
+                    if (focusByIdFn)
+                        focusByIdFn(focusedId);
+                };
+                if (loadVisibleFn) {
+                    let polls = 0;
+                    const pollUntilReady = () => {
+                        if (state.containerSize > 0) {
+                            if (Math.abs(state.scrollPosition - scrollPosition) > 1) {
+                                ctx.scrollTo(scrollPosition);
+                            }
+                            loadVisibleFn().then(restoreFocus);
+                        }
+                        else if (++polls < 10) {
+                            requestAnimationFrame(pollUntilReady);
+                        }
+                    };
+                    requestAnimationFrame(pollUntilReady);
+                }
+                else {
+                    const reloadFn = ctx.getMethod("reload");
+                    if (reloadFn) {
+                        requestAnimationFrame(() => { reloadFn().then(restoreFocus); });
+                    }
+                    else {
+                        requestAnimationFrame(restoreFocus);
+                    }
+                }
+            };
+            ctx.registerMethod("restoreScroll", restoreScroll);
+            // ── Auto-save ──────────────────────────────────────────────
+            let restoreGuard = !!(restoreSnapshot && autoSaveKey);
+            ctx.registerDestroyHandler(() => { disposed = true; });
+            if (autoSaveKey) {
+                saveToStorage = () => {
+                    if (disposed || restoreGuard || ctx.getMethod("_suppressSave"))
+                        return;
+                    const snap = getScrollSnapshot();
+                    try {
+                        sessionStorage.setItem(autoSaveKey, JSON.stringify(snap));
+                    }
+                    catch { /* sessionStorage full or unavailable */ }
+                };
+                ctx.registerMethod("_saveSnapshot", saveToStorage);
+                let saveTimer = 0;
+                const debouncedSave = () => {
+                    if (saveTimer)
+                        return;
+                    saveTimer = requestAnimationFrame(() => {
+                        saveTimer = 0;
+                        saveToStorage();
+                    });
+                };
+                emitter.on("selection:change", debouncedSave);
+                emitter.on("focus:change", debouncedSave);
+                let scrollSaveTimer = 0;
+                const scrollSaveCallback = () => {
+                    scrollSaveTimer = 0;
+                    saveToStorage();
+                };
+                const debouncedScrollSave = () => {
+                    if (scrollSaveTimer)
+                        clearTimeout(scrollSaveTimer);
+                    scrollSaveTimer = setTimeout(scrollSaveCallback, 300);
+                };
+                emitter.on("scroll", debouncedScrollSave);
+                const onBeforeUnload = () => { saveToStorage?.(); };
+                window.addEventListener("beforeunload", onBeforeUnload);
+                ctx.registerDestroyHandler(() => {
+                    if (scrollSaveTimer)
+                        clearTimeout(scrollSaveTimer);
+                    window.removeEventListener("beforeunload", onBeforeUnload);
+                });
+                if (restoreSnapshot && restoreSnapshot.total && restoreSnapshot.total > 0) {
+                    const cancelAutoLoad = ctx.getMethod("_cancelAutoLoad");
+                    if (cancelAutoLoad)
+                        cancelAutoLoad();
+                    const setTotal = ctx.getMethod("_setTotal");
+                    if (setTotal)
+                        setTotal(restoreSnapshot.total);
+                }
+            }
+            // ── Auto-restore ───────────────────────────────────────────
+            if (restoreSnapshot) {
+                let restoreSelection = true;
+                if (restoreSnapshot.selectedIds?.length) {
+                    const seedFn = ctx.getMethod("_seedSelection");
+                    if (seedFn) {
+                        seedFn(restoreSnapshot.selectedIds);
+                        restoreSelection = false;
+                    }
+                }
+                queueMicrotask(() => {
+                    restoreScroll(restoreSnapshot, restoreSelection);
+                    restoreGuard = false;
+                    if (saveToStorage)
+                        saveToStorage();
+                });
+            }
+        },
+        hooks: {
+            onIdle() {
+                if (saveToStorage && !disposed)
+                    saveToStorage();
+            },
+        },
+        destroy() {
+            disposed = true;
+            saveToStorage = null;
+        },
+    };
+}

package/dist/plugins/sortable/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * vlist - Sortable Domain
+ * Drag-and-drop reordering for virtual lists
+ */
+export { sortable, type SortablePluginConfig } from "./plugin";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/sortable/index.js

@@ -0,0 +1,6 @@
+/**
+ * vlist - Sortable Domain
+ * Drag-and-drop reordering for virtual lists
+ */
+// v2 Plugin
+export { sortable } from "./plugin";