vlist 1.9.1 → 2.0.0

package/dist/plugins/async/placeholder.js

@@ -0,0 +1,154 @@
+/**
+ * vlist - Placeholder System
+ * Smart placeholder generation for loading states
+ *
+ * Key features:
+ * - Captures per-item field lengths from the first loaded batch
+ * - Cycles through real data profiles for natural size variance
+ * - Same item template renders both real and placeholder items
+ * - Renderer adds CSS class for visual styling (no JS branching needed)
+ */
+import { PLACEHOLDER_FLAG, PLACEHOLDER_ID_PREFIX, MASK_CHARACTER, MAX_SAMPLE_SIZE, } from "../../constants";
+// =============================================================================
+// Placeholder Manager
+// =============================================================================
+/**
+ * Create a placeholder manager that generates realistic placeholder items
+ * by capturing per-item field lengths from the first loaded data batch.
+ *
+ * Placeholders carry the same field names as real items, filled with
+ * mask characters sized to match actual data. The renderer detects
+ * placeholders via the `_isPlaceholder` flag and applies a CSS class
+ * — no template branching required.
+ */
+export const createPlaceholderManager = (config = {}) => {
+    const { maskCharacter = MASK_CHARACTER, maxSampleSize = MAX_SAMPLE_SIZE, } = config;
+    // State
+    let lengthProfiles = [];
+    let hasAnalyzed = false;
+    // ==========================================================================
+    // Structure Analysis
+    // ==========================================================================
+    /**
+     * Capture per-item field lengths from the first loaded batch.
+     * Each sampled item produces one LengthProfile that records the
+     * string length of every non-internal field. When generating
+     * placeholder #N, we cycle through these profiles so that size
+     * variance mirrors the real data distribution.
+     */
+    const analyzeStructure = (items) => {
+        if (hasAnalyzed || items.length === 0)
+            return;
+        const sampleSize = Math.min(items.length, maxSampleSize);
+        for (let i = 0; i < sampleSize; i++) {
+            const item = items[i];
+            if (!item || typeof item !== "object")
+                continue;
+            const profile = {};
+            let hasFields = false;
+            for (const [field, value] of Object.entries(item)) {
+                // Skip internal fields and id
+                if (field.startsWith("_") || field === "id")
+                    continue;
+                profile[field] = String(value ?? "").length;
+                hasFields = true;
+            }
+            // Only store profiles that have at least one field —
+            // id-only items produce empty profiles which aren't useful
+            if (hasFields) {
+                lengthProfiles.push(profile);
+            }
+        }
+        hasAnalyzed = true;
+    };
+    /**
+     * Check if structure has been analyzed
+     */
+    const hasAnalyzedStructure = () => hasAnalyzed;
+    // ==========================================================================
+    // Placeholder Generation
+    // ==========================================================================
+    /**
+     * Generate a single placeholder item.
+     * Uses the length profile at `index % profiles.length` so each
+     * placeholder has a unique but realistic field size distribution.
+     */
+    const generate = (index) => {
+        const placeholder = {
+            id: `${PLACEHOLDER_ID_PREFIX}${index}`,
+            [PLACEHOLDER_FLAG]: true,
+            _index: index,
+        };
+        // No profiles yet — basic fallback
+        if (lengthProfiles.length === 0) {
+            placeholder.label = maskCharacter.repeat(12);
+            return placeholder;
+        }
+        // Cycle through captured profiles
+        const profile = lengthProfiles[index % lengthProfiles.length];
+        for (const [field, length] of Object.entries(profile)) {
+            placeholder[field] = maskCharacter.repeat(Math.max(1, length));
+        }
+        return placeholder;
+    };
+    /**
+     * Generate multiple placeholder items
+     */
+    const generateRange = (start, end) => {
+        const items = [];
+        for (let i = start; i <= end; i++) {
+            items.push(generate(i));
+        }
+        return items;
+    };
+    // ==========================================================================
+    // Lifecycle
+    // ==========================================================================
+    /**
+     * Clear analyzed structure
+     */
+    const clear = () => {
+        lengthProfiles = [];
+        hasAnalyzed = false;
+    };
+    // ==========================================================================
+    // Return Public API
+    // ==========================================================================
+    return {
+        analyzeStructure,
+        hasAnalyzedStructure,
+        generate,
+        generateRange,
+        clear,
+    };
+};
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Check if an item is a placeholder
+ */
+export const isPlaceholderItem = (item) => {
+    if (!item || typeof item !== "object") {
+        return false;
+    }
+    return item[PLACEHOLDER_FLAG] === true;
+};
+/**
+ * Filter out placeholder items from an array
+ */
+export const filterPlaceholders = (items) => {
+    return items.filter((item) => !isPlaceholderItem(item));
+};
+/**
+ * Count non-placeholder items in an array
+ */
+export const countRealItems = (items) => {
+    let count = 0;
+    for (const item of items) {
+        if (item !== undefined && !isPlaceholderItem(item)) {
+            count++;
+        }
+    }
+    return count;
+};

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

@@ -0,0 +1,48 @@
+/**
+ * vlist v2 — Async Plugin
+ *
+ * Enables async data loading with sparse storage, placeholders, and infinite scroll.
+ * Priority 20 — runs before scrollbar and selection, after layout plugins.
+ *
+ * Features:
+ * - Replaces default data source with async adapter-backed storage
+ * - Lazy-loads data in chunks on scroll + idle detection
+ * - Shows placeholders for unloaded items
+ * - Deduplicates concurrent fetch requests
+ * - Velocity-aware loading: skips loads during fast scrolling, loads on idle
+ * - Infinite scroll: loads next page when scrolling near bottom
+ * - Public methods: reload(), loadVisibleRange()
+ * - Emits: load:start, load:end, error events
+ */
+import type { VListItem, VListAdapter } from "../../types";
+import type { VListPlugin } from "../../core/types";
+export interface DataPluginConfig<T extends VListItem = VListItem> {
+    /** Async data source (required) */
+    adapter: VListAdapter<T>;
+    /** Total number of items (optional - if not provided, adapter must return it) */
+    total?: number;
+    /** Whether to automatically load initial data (default: true) */
+    autoLoad?: boolean;
+    /** Storage configuration */
+    storage?: {
+        /** Number of items per chunk (default: 100) */
+        chunkSize?: number;
+        /** Maximum cached items before eviction (default: 10000) */
+        maxCachedItems?: number;
+        /** Extra items to keep around visible range (default: 500) */
+        evictionBuffer?: number;
+    };
+    /** Loading behavior configuration */
+    loading?: {
+        /** Velocity threshold above which data loading is cancelled (px/ms) */
+        cancelThreshold?: number;
+        /** Velocity threshold for preloading (px/ms) */
+        preloadThreshold?: number;
+        /** Number of items to preload in scroll direction */
+        preloadAhead?: number;
+        /** Maximum concurrent chunk requests (0 = unlimited, default: 6) */
+        maxConcurrent?: number;
+    };
+}
+export declare function data<T extends VListItem = VListItem>(config: DataPluginConfig<T>): VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/async/plugin.js

@@ -0,0 +1,311 @@
+/**
+ * vlist v2 — Async Plugin
+ *
+ * Enables async data loading with sparse storage, placeholders, and infinite scroll.
+ * Priority 20 — runs before scrollbar and selection, after layout plugins.
+ *
+ * Features:
+ * - Replaces default data source with async adapter-backed storage
+ * - Lazy-loads data in chunks on scroll + idle detection
+ * - Shows placeholders for unloaded items
+ * - Deduplicates concurrent fetch requests
+ * - Velocity-aware loading: skips loads during fast scrolling, loads on idle
+ * - Infinite scroll: loads next page when scrolling near bottom
+ * - Public methods: reload(), loadVisibleRange()
+ * - Emits: load:start, load:end, error events
+ */
+import { createDataManager } from "./manager";
+import { INITIAL_LOAD_SIZE, LOAD_VELOCITY_THRESHOLD, PRELOAD_VELOCITY_THRESHOLD, PRELOAD_AHEAD, MAX_CONCURRENT_LOADS, } from "../../constants";
+// =============================================================================
+// Factory
+// =============================================================================
+export function data(config) {
+    const { adapter, total, autoLoad = true, storage } = config;
+    const cancelThreshold = config.loading?.cancelThreshold ?? LOAD_VELOCITY_THRESHOLD;
+    const preloadThreshold = config.loading?.preloadThreshold ?? PRELOAD_VELOCITY_THRESHOLD;
+    const preloadAhead = config.loading?.preloadAhead ?? PRELOAD_AHEAD;
+    const maxConcurrent = config.loading?.maxConcurrent ?? MAX_CONCURRENT_LOADS;
+    let dataManager;
+    let engineState;
+    let sizeCache;
+    let emitter;
+    let dom;
+    let forceRender;
+    let pendingRange = null;
+    let decelerationTimer = null;
+    let idleTimer = null;
+    let currentVelocity = 0;
+    let autoLoadCancelled = false;
+    // Track last requested chunk range to skip redundant ensure() calls
+    let lastFirstChunk = -1;
+    let lastLastChunk = -1;
+    const chunkSize = storage?.chunkSize ?? INITIAL_LOAD_SIZE;
+    // ============================================================================
+    // Helpers
+    // ============================================================================
+    const resetDeceleration = () => {
+        pendingRange = null;
+        if (decelerationTimer !== null) {
+            clearTimeout(decelerationTimer);
+            decelerationTimer = null;
+        }
+    };
+    const ensure = (start, end) => {
+        return dataManager.ensureRange(start, end);
+    };
+    const emitLoadStart = (offset, limit = INITIAL_LOAD_SIZE) => {
+        emitter.emit("load:start", { offset, limit });
+    };
+    const onEnsureError = (error) => {
+        emitter.emit("error", { error, context: "ensureRange" });
+    };
+    const loadPendingRange = () => {
+        if (!pendingRange) {
+            return;
+        }
+        pendingRange = null;
+        const currentRange = {
+            start: engineState.startIndex,
+            end: engineState.startIndex + Math.max(0, engineState.visibleCount - 1),
+        };
+        if (currentRange.end < currentRange.start) {
+            return;
+        }
+        ensure(currentRange.start, currentRange.end).catch(onEnsureError);
+    };
+    // ============================================================================
+    // Plugin Definition
+    // ============================================================================
+    return {
+        name: "data",
+        priority: 20,
+        setup(ctx) {
+            engineState = ctx.getState();
+            sizeCache = ctx.sizeCache;
+            emitter = ctx.emitter;
+            dom = ctx.dom;
+            forceRender = ctx.forceRender.bind(ctx);
+            // Create data manager — but first wire up virtualTotalFn
+            // so scrollToIndex and api.total reflect the async data total
+            let dataManagerRef = null;
+            ctx.setVirtualTotalFn(() => dataManagerRef?.getTotal() ?? 0);
+            dataManager = dataManagerRef = createDataManager({
+                adapter,
+                ...(total !== undefined && { initialTotal: total }),
+                pageSize: storage?.chunkSize ?? INITIAL_LOAD_SIZE,
+                maxConcurrent,
+                ...(storage && {
+                    storage: {
+                        ...(storage.chunkSize !== undefined && { chunkSize: storage.chunkSize }),
+                        ...(storage.maxCachedItems !== undefined && { maxCachedItems: storage.maxCachedItems }),
+                        ...(storage.evictionBuffer !== undefined && { evictionBuffer: storage.evictionBuffer }),
+                    },
+                }),
+                onDataChange: () => {
+                    if (engineState.initialized) {
+                        const newTotal = dataManager.getTotal();
+                        engineState.totalItems = newTotal;
+                        const oldTotal = sizeCache.getTotal();
+                        if (newTotal !== oldTotal) {
+                            sizeCache.rebuild(newTotal);
+                        }
+                        ctx.updateContentSize(sizeCache.getTotalSize());
+                        ctx.renderIfNeeded();
+                    }
+                },
+                onItemsLoaded: (loadedItems) => {
+                    if (engineState.initialized) {
+                        forceRender();
+                        emitter.emit("load:end", { items: loadedItems, total: dataManager.getTotal() });
+                    }
+                },
+            });
+            // Bridge async data manager to the render pipeline
+            ctx.setGetItemFn((index) => dataManager.getItem(index));
+            ctx.setRemoveItemFn((id) => {
+                const index = dataManager.getIndexById(id);
+                if (index < 0)
+                    return -1;
+                const removed = dataManager.removeItem(id);
+                if (!removed)
+                    return -1;
+                return index;
+            });
+            ctx.setInsertItemFn((item, index) => {
+                dataManager.insertItem(item, index);
+            });
+            ctx.setUpdateItemFn((id, updates) => {
+                const index = dataManager.getIndexById(id);
+                if (index < 0)
+                    return false;
+                return dataManager.updateItem(index, updates);
+            });
+            // Register public methods
+            ctx.registerMethod("reload", async () => {
+                pendingRange = null;
+                lastFirstChunk = -1;
+                lastLastChunk = -1;
+                ctx.forceRender();
+                await dataManager.reload();
+                ctx.scrollTo(0);
+                if (autoLoad) {
+                    emitLoadStart(0);
+                    await dataManager.loadInitial();
+                    ctx.forceRender();
+                }
+            });
+            ctx.registerMethod("loadVisibleRange", async () => {
+                pendingRange = null;
+                ctx.forceRender();
+                const total = dataManager.getTotal();
+                if (engineState.visibleCount > 0 && engineState.startIndex < total) {
+                    const end = Math.min(engineState.startIndex + engineState.visibleCount - 1, total - 1);
+                    emitLoadStart(engineState.startIndex, end - engineState.startIndex + 1);
+                    await ensure(engineState.startIndex, end);
+                }
+            });
+            ctx.registerMethod("getTotal", () => {
+                return dataManager.getTotal();
+            });
+            ctx.registerMethod("setTotal", (total) => {
+                dataManager.setTotal(total);
+            });
+            ctx.registerMethod("_getTotal", () => dataManager.getTotal());
+            ctx.registerMethod("_setTotal", (t) => {
+                dataManager.setTotal(t);
+            });
+            ctx.registerMethod("_cancelAutoLoad", () => {
+                autoLoadCancelled = true;
+            });
+            ctx.registerMethod("_getLoadedItem", (index) => {
+                return dataManager.getStorage().get(index);
+            });
+            ctx.registerMethod("_getLoadedCount", () => dataManager.getCached());
+            // ARIA: aria-busy for loading state
+            emitter.on("load:start", () => {
+                dom.root.setAttribute("aria-busy", "true");
+            });
+            emitter.on("load:end", () => {
+                dom.root.removeAttribute("aria-busy");
+            });
+            ctx.registerDestroyHandler(() => {
+                if (idleTimer !== null) {
+                    clearTimeout(idleTimer);
+                    idleTimer = null;
+                }
+                resetDeceleration();
+            });
+            // Track velocity for load gating
+            emitter.on("velocity:change", ({ velocity }) => {
+                currentVelocity = Math.abs(velocity);
+            });
+            // Network recovery
+            const handleOnline = () => {
+                if (engineState.destroyed)
+                    return;
+                if (engineState.visibleCount > 0 && engineState.startIndex < dataManager.getTotal()) {
+                    const end = Math.min(engineState.startIndex + engineState.visibleCount - 1, dataManager.getTotal() - 1);
+                    ensure(engineState.startIndex, end).catch(onEnsureError);
+                }
+                loadPendingRange();
+            };
+            window.addEventListener("online", handleOnline);
+            ctx.registerDestroyHandler(() => {
+                window.removeEventListener("online", handleOnline);
+            });
+            // Load initial data (if autoLoad is enabled)
+            if (autoLoad) {
+                queueMicrotask(() => {
+                    if (autoLoadCancelled)
+                        return;
+                    emitLoadStart(0);
+                    dataManager.loadInitial().catch((error) => {
+                        emitter.emit("error", { error, context: "loadInitial" });
+                    });
+                });
+            }
+            else if (total !== undefined) {
+                dataManager.setTotal(total);
+            }
+        },
+        hooks: {
+            onAfterScroll() {
+                if (engineState.destroyed)
+                    return;
+                const visEnd = engineState.startIndex + Math.max(0, engineState.visibleCount - 1);
+                // Fast scrolling (above cancelThreshold): skip loading, defer to idle
+                if (currentVelocity > cancelThreshold) {
+                    if (decelerationTimer !== null) {
+                        clearTimeout(decelerationTimer);
+                        decelerationTimer = null;
+                    }
+                    pendingRange = { start: engineState.startIndex, end: visEnd };
+                    return;
+                }
+                // Moderate scrolling (between preloadThreshold and cancelThreshold):
+                // load visible range immediately, debounce preload-ahead only
+                if (currentVelocity > preloadThreshold) {
+                    const fc = Math.floor(engineState.startIndex / chunkSize);
+                    const lc = Math.floor(visEnd / chunkSize);
+                    if (fc !== lastFirstChunk || lc !== lastLastChunk) {
+                        lastFirstChunk = fc;
+                        lastLastChunk = lc;
+                        if (visEnd >= engineState.startIndex) {
+                            ensure(engineState.startIndex, visEnd).catch(onEnsureError);
+                        }
+                    }
+                    let loadStart = engineState.startIndex;
+                    let loadEnd = visEnd;
+                    const dir = engineState.scrollDirection;
+                    if (dir > 0) {
+                        loadEnd = Math.min(loadEnd + preloadAhead, dataManager.getTotal() - 1);
+                    }
+                    else if (dir < 0) {
+                        loadStart = Math.max(0, loadStart - preloadAhead);
+                    }
+                    pendingRange = { start: loadStart, end: loadEnd };
+                    if (decelerationTimer !== null) {
+                        clearTimeout(decelerationTimer);
+                    }
+                    decelerationTimer = setTimeout(() => {
+                        decelerationTimer = null;
+                        if (engineState.destroyed || !pendingRange)
+                            return;
+                        const { start, end } = pendingRange;
+                        pendingRange = null;
+                        if (end >= start) {
+                            ensure(start, end).catch(onEnsureError);
+                        }
+                    }, 100);
+                    return;
+                }
+                // Slow scrolling (below preloadThreshold): load visible range immediately
+                resetDeceleration();
+                const fc = Math.floor(engineState.startIndex / chunkSize);
+                const lc = Math.floor(visEnd / chunkSize);
+                if (fc !== lastFirstChunk || lc !== lastLastChunk) {
+                    lastFirstChunk = fc;
+                    lastLastChunk = lc;
+                    if (visEnd >= engineState.startIndex) {
+                        ensure(engineState.startIndex, visEnd).catch(onEnsureError);
+                    }
+                }
+            },
+            onIdle() {
+                if (engineState.destroyed)
+                    return;
+                currentVelocity = 0;
+                lastFirstChunk = -1;
+                lastLastChunk = -1;
+                loadPendingRange();
+                resetDeceleration();
+            },
+        },
+        destroy() {
+            if (idleTimer !== null) {
+                clearTimeout(idleTimer);
+            }
+            resetDeceleration();
+        },
+    };
+}