@floor/vlist 0.5.8 → 0.6.0

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

@@ -0,0 +1,60 @@
+/**
+ * vlist/data - Builder Plugin
+ * Wraps async data loading with sparse storage into a VListPlugin for the composable builder.
+ *
+ * Priority: 20 (runs before scrollbar and selection, after grid/groups)
+ *
+ * What it wires:
+ * - Replaces data manager — swaps the simple in-memory store with sparse storage
+ * - Scroll boundary detection — triggers loadMore() near the bottom (or top in reverse)
+ * - Velocity-aware loading — skips data fetching during fast scrolling, loads on idle
+ * - Placeholder generation — creates skeleton items for unloaded ranges
+ * - Request deduplication — prevents duplicate fetches for the same range
+ * - Idle handler — loads any pending ranges when scrolling stops
+ *
+ * Added methods: reload
+ * Added events: load:start, load:end, error
+ */
+import type { VListItem, VListAdapter } from "../../types";
+import type { VListPlugin } from "../../builder/types";
+/** Data plugin configuration */
+export interface DataPluginConfig<T extends VListItem = VListItem> {
+    /** Async data source (required) */
+    adapter: VListAdapter<T>;
+    /** Loading behavior configuration */
+    loading?: {
+        /** Velocity threshold above which data loading is skipped (px/ms). Default: 25 */
+        cancelThreshold?: number;
+        /** Velocity threshold for preloading (px/ms). Default: 2 */
+        preloadThreshold?: number;
+        /** Number of items to preload in scroll direction. Default: 50 */
+        preloadAhead?: number;
+    };
+}
+/**
+ * Create a data plugin for the builder.
+ *
+ * Adds async data loading with sparse storage, placeholders, and infinite scroll.
+ *
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withData } from 'vlist/data'
+ *
+ * const list = vlist({
+ *   container: '#app',
+ *   item: { height: 48, template: renderItem },
+ * })
+ * .use(withData({
+ *   adapter: {
+ *     read: async ({ offset, limit }) => {
+ *       const res = await fetch(`/api/items?offset=${offset}&limit=${limit}`)
+ *       const data = await res.json()
+ *       return { items: data.items, total: data.total, hasMore: data.hasMore }
+ *     }
+ *   }
+ * }))
+ * .build()
+ * ```
+ */
+export declare const withAsync: <T extends VListItem = VListItem>(config: DataPluginConfig<T>) => VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/features/async/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/features/async/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAS,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAiBvE,gCAAgC;AAChC,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAC/D,mCAAmC;IACnC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAEzB,qCAAqC;IACrC,OAAO,CAAC,EAAE;QACR,kFAAkF;QAClF,eAAe,CAAC,EAAE,MAAM,CAAC;QAEzB,4DAA4D;QAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAE1B,kEAAkE;QAClE,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,SAAS,GAAG,SAAS,EACvD,QAAQ,gBAAgB,CAAC,CAAC,CAAC,KAC1B,WAAW,CAAC,CAAC,CAiOf,CAAC"}

package/dist/features/async/sparse.d.ts

@@ -0,0 +1,91 @@
+/**
+ * vlist - Sparse Storage
+ * Efficient storage for million+ item virtual lists
+ */
+import type { VListItem, Range } from "../../types";
+/** Configuration for sparse storage */
+export interface SparseStorageConfig {
+    /** Number of items per chunk (default: 100) */
+    chunkSize?: number;
+    /** Maximum items to keep in memory (default: 5000) */
+    maxCachedItems?: number;
+    /** Extra items to keep around visible range during eviction (default: 200) */
+    evictionBuffer?: number;
+    /** Callback when items are evicted */
+    onEvict?: (evictedCount: number, evictedRanges: number[]) => void;
+}
+/** Storage statistics */
+export interface SparseStorageStats {
+    /** Total items declared (may be larger than loaded) */
+    totalItems: number;
+    /** Number of items currently in memory */
+    cachedItems: number;
+    /** Number of chunks in memory */
+    cachedChunks: number;
+    /** Chunk size */
+    chunkSize: number;
+    /** Maximum cached items allowed */
+    maxCachedItems: number;
+    /** Memory efficiency (cachedItems / totalItems) */
+    memoryEfficiency: number;
+}
+/** Sparse storage instance */
+export interface SparseStorage<T extends VListItem = VListItem> {
+    readonly chunkSize: number;
+    readonly maxCachedItems: number;
+    /** Get total item count */
+    getTotal: () => number;
+    /** Set total item count (for virtual scrolling height) */
+    setTotal: (total: number) => void;
+    /** Get item at index (undefined if not loaded) */
+    get: (index: number) => T | undefined;
+    /** Check if item at index is loaded */
+    has: (index: number) => boolean;
+    /** Set item at index */
+    set: (index: number, item: T) => void;
+    /** Set multiple items starting at offset */
+    setRange: (offset: number, items: T[]) => void;
+    /** Delete item at index */
+    delete: (index: number) => boolean;
+    /** Get items in range (includes undefined for unloaded) */
+    getRange: (start: number, end: number) => (T | undefined)[];
+    /** Check if range is fully loaded */
+    isRangeLoaded: (start: number, end: number) => boolean;
+    /** Get loaded ranges */
+    getLoadedRanges: () => Range[];
+    /** Find unloaded ranges within a given range */
+    findUnloadedRanges: (start: number, end: number) => Range[];
+    /** Get chunk index for item index */
+    getChunkIndex: (itemIndex: number) => number;
+    /** Check if chunk is loaded */
+    isChunkLoaded: (chunkIndex: number) => boolean;
+    /** Mark chunk as accessed (for LRU) */
+    touchChunk: (chunkIndex: number) => void;
+    /** Mark all chunks in a range as accessed with a single Date.now() call */
+    touchChunksForRange: (start: number, end: number) => void;
+    /** Evict chunks far from visible range */
+    evictDistant: (visibleStart: number, visibleEnd: number) => number;
+    /** Force eviction to meet memory limit */
+    evictToLimit: () => number;
+    /** Get storage statistics */
+    getStats: () => SparseStorageStats;
+    /** Get cached item count */
+    getCachedCount: () => number;
+    /** Clear all data */
+    clear: () => void;
+    /** Reset to initial state */
+    reset: () => void;
+}
+/**
+ * Create sparse storage for efficient large list handling
+ */
+export declare const createSparseStorage: <T extends VListItem = VListItem>(config?: SparseStorageConfig) => SparseStorage<T>;
+/**
+ * Merge adjacent/overlapping ranges
+ */
+export declare const mergeRanges: (ranges: Range[]) => Range[];
+/**
+ * Calculate ranges that need to be loaded
+ */
+export declare const calculateMissingRanges: (needed: Range, loaded: Range[], chunkSize: number) => Range[];
+//# sourceMappingURL=sparse.d.ts.map

package/dist/features/async/sparse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparse.d.ts","sourceRoot":"","sources":["../../../src/features/async/sparse.ts"],"names":[],"mappings":"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"}

package/dist/features/grid/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * vlist - Grid Domain
+ * 2D grid/card layout with virtualized rows
+ */
+export { withGrid, type GridPluginConfig } from "./plugin";
+export { createGridLayout } from "./layout";
+export { createGridRenderer, type GridRenderer } from "./renderer";
+export type { GridConfig, GridLayout, GridPosition, ItemRange } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/grid/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/grid/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAG3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAG5C,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAGnE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC"}

package/dist/features/grid/layout.d.ts

@@ -0,0 +1,29 @@
+/**
+ * vlist - Grid Layout
+ * Pure O(1) calculations for mapping between flat item indices and grid positions.
+ *
+ * The grid transforms a flat list into rows:
+ *   Items:  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+ *   Grid (columns=4):
+ *     Row 0: [0, 1, 2, 3]
+ *     Row 1: [4, 5, 6, 7]
+ *     Row 2: [8, 9]          ← partially filled last row
+ *
+ * All operations are O(1) — integer division and modulo only.
+ */
+import type { GridConfig, GridLayout } from "./types";
+/**
+ * Extended grid config with optional groups support
+ */
+export interface GridConfigWithGroups extends GridConfig {
+    /** Optional: check if an item index is a group header (for groups-aware layout) */
+    isHeaderFn?: (index: number) => boolean;
+}
+/**
+ * Create a GridLayout instance.
+ *
+ * @param config - Grid configuration (columns, gap, optional isHeaderFn)
+ * @returns GridLayout with O(1) mapping functions (or groups-aware if isHeaderFn provided)
+ */
+export declare const createGridLayout: (config: GridConfigWithGroups) => GridLayout;
+//# sourceMappingURL=layout.d.ts.map

package/dist/features/grid/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/features/grid/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAA2B,MAAM,SAAS,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,UAAU;IACtD,mFAAmF;IACnF,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CACzC;AAMD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,oBAAoB,KAAG,UA4R/D,CAAC"}

package/dist/features/grid/plugin.d.ts

@@ -0,0 +1,48 @@
+/**
+ * vlist/grid - Builder Plugin
+ * Switches from list layout to a 2D grid with configurable columns and gap.
+ *
+ * Priority: 10 (runs first — replaces the renderer before anything else renders)
+ *
+ * What it wires:
+ * - Replaces renderer — swaps the list renderer with a grid renderer
+ * - Redefines virtual total — the virtualizer sees rows, not items
+ * - Column width calculation — recalculated on resize
+ * - Item positioning — each item gets translateX (column) and translateY (row)
+ * - CSS class — adds .vlist--grid to the root element
+ *
+ * Restrictions:
+ * - Cannot be combined with direction: 'horizontal'
+ * - Cannot be combined with reverse: true
+ *
+ * Can be combined with withGroups for grouped 2D layouts.
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../builder/types";
+/** Grid plugin configuration */
+export interface GridPluginConfig {
+    /** Number of columns (required, >= 1) */
+    columns: number;
+    /** Gap between items in pixels (default: 0) */
+    gap?: number;
+}
+/**
+ * Create a grid plugin for the builder.
+ *
+ * Switches from list layout to a 2D grid with configurable columns and gap.
+ *
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withGrid } from 'vlist/grid'
+ *
+ * const gallery = vlist({
+ *   container: '#gallery',
+ *   item: { height: 200, template: renderPhoto },
+ *   items: photos,
+ * })
+ * .use(withGrid({ columns: 4, gap: 8 }))
+ * .build()
+ * ```
+ */
+export declare const withGrid: <T extends VListItem = VListItem>(config: GridPluginConfig) => VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/features/grid/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/features/grid/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAUvE,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAEhB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,SAAS,GAAG,SAAS,EACtD,QAAQ,gBAAgB,KACvB,WAAW,CAAC,CAAC,CA4Zf,CAAC"}

package/dist/features/grid/renderer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * vlist - Grid Renderer
+ * Renders items in a 2D grid layout within the virtual scroll container.
+ *
+ * Extends the base renderer pattern but positions items using both
+ * row offsets (translateY from the height cache) and column offsets
+ * (translateX calculated from column index and container width).
+ *
+ * Key differences from the list renderer:
+ * - Items are positioned with translate(x, y) instead of just translateY(y)
+ * - Item width is set to columnWidth (containerWidth / columns - gaps)
+ * - The "index" in the rendered map is the FLAT ITEM INDEX (not row index)
+ * - Row offsets come from the height cache (which operates on row indices)
+ * - Column offsets are calculated from itemIndex % columns
+ */
+import type { VListItem, ItemTemplate, Range } from "../../types";
+import type { HeightCache } from "../../rendering/heights";
+import type { CompressionContext } from "../../rendering/renderer";
+import type { GridLayout } from "./types";
+/** Grid renderer instance */
+export interface GridRenderer<T extends VListItem = VListItem> {
+    /** Render items for a flat item range, positioned in a 2D grid */
+    render: (items: T[], range: Range, selectedIds: Set<string | number>, focusedIndex: number, compressionCtx?: CompressionContext) => void;
+    /** Update item positions (for compressed scrolling) */
+    updatePositions: (compressionCtx: CompressionContext) => void;
+    /** Update a single item */
+    updateItem: (index: number, item: T, isSelected: boolean, isFocused: boolean) => void;
+    /** Update only CSS classes on a rendered item (no template re-evaluation) */
+    updateItemClasses: (index: number, isSelected: boolean, isFocused: boolean) => void;
+    /** Get rendered item element by flat item index */
+    getElement: (index: number) => HTMLElement | undefined;
+    /** Update container width (call on resize) */
+    updateContainerWidth: (width: number) => void;
+    /** Clear all rendered items */
+    clear: () => void;
+    /** Destroy renderer and cleanup */
+    destroy: () => void;
+}
+/**
+ * Create a grid renderer for managing DOM elements in a 2D layout.
+ *
+ * The grid renderer receives flat item ranges (not row ranges) and
+ * positions each item at the correct (row, col) coordinate.
+ *
+ * @param itemsContainer - The DOM element that holds rendered items
+ * @param template - Item template function
+ * @param heightCache - Height cache operating on ROW indices
+ * @param gridLayout - Grid layout for row/col calculations
+ * @param classPrefix - CSS class prefix
+ * @param initialContainerWidth - Initial container width for column sizing
+ * @param totalItemsGetter - Optional getter for total item count (for aria-setsize)
+ * @param ariaIdPrefix - Optional unique prefix for element IDs (for aria-activedescendant)
+ */
+export declare const createGridRenderer: <T extends VListItem = VListItem>(itemsContainer: HTMLElement, template: ItemTemplate<T>, heightCache: HeightCache, gridLayout: GridLayout, classPrefix: string, initialContainerWidth: number, totalItemsGetter?: () => number, ariaIdPrefix?: string) => GridRenderer<T>;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/features/grid/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../src/features/grid/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EAEZ,KAAK,EAEN,MAAM,aAAa,CAAC;AAOrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAO1C,6BAA6B;AAC7B,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAC3D,kEAAkE;IAClE,MAAM,EAAE,CACN,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EACjC,YAAY,EAAE,MAAM,EACpB,cAAc,CAAC,EAAE,kBAAkB,KAChC,IAAI,CAAC;IAEV,uDAAuD;IACvD,eAAe,EAAE,CAAC,cAAc,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAE9D,2BAA2B;IAC3B,UAAU,EAAE,CACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,EACP,UAAU,EAAE,OAAO,EACnB,SAAS,EAAE,OAAO,KACf,IAAI,CAAC;IAEV,6EAA6E;IAC7E,iBAAiB,EAAE,CACjB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,OAAO,EACnB,SAAS,EAAE,OAAO,KACf,IAAI,CAAC;IAEV,mDAAmD;IACnD,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;IAEvD,8CAA8C;IAC9C,oBAAoB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9C,+BAA+B;IAC/B,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB,mCAAmC;IACnC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAoDD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,SAAS,GAAG,SAAS,EAChE,gBAAgB,WAAW,EAC3B,UAAU,YAAY,CAAC,CAAC,CAAC,EACzB,aAAa,WAAW,EACxB,YAAY,UAAU,EACtB,aAAa,MAAM,EACnB,uBAAuB,MAAM,EAC7B,mBAAmB,MAAM,MAAM,EAC/B,eAAe,MAAM,KACpB,YAAY,CAAC,CAAC,CAmahB,CAAC"}

package/dist/features/grid/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * vlist - Grid Types
+ * Types for grid/card layout mode
+ *
+ * Grid layout transforms a flat list of items into a 2D grid where:
+ * - Virtualization operates on ROWS (not individual items)
+ * - Each row contains `columns` items side by side
+ * - Items are positioned using row/column coordinates
+ * - Compression applies to row count, not item count
+ */
+import type { GridConfig } from "../../types";
+export type { GridConfig };
+/** Row/column position of an item */
+export interface GridPosition {
+    /** Row index (0-based) */
+    row: number;
+    /** Column index (0-based) */
+    col: number;
+}
+/** Flat item range corresponding to a row range */
+export interface ItemRange {
+    /** First item index (inclusive) */
+    start: number;
+    /** Last item index (inclusive) */
+    end: number;
+}
+/**
+ * GridLayout — maps between flat item indices and row/column positions.
+ *
+ * The virtualizer sees "rows" as its unit of work. Each row contains
+ * up to `columns` items. The last row may be partially filled.
+ *
+ * All operations are O(1) — just integer division and modulo.
+ */
+export interface GridLayout {
+    /** Number of columns */
+    readonly columns: number;
+    /** Gap between items in pixels */
+    readonly gap: number;
+    /** Update grid configuration without recreating the layout */
+    update: (config: Partial<GridConfig>) => void;
+    /** Get total number of rows for a given item count */
+    getTotalRows: (totalItems: number) => number;
+    /** Get the row/col position for a flat item index */
+    getPosition: (itemIndex: number) => GridPosition;
+    /** Get the row index for a flat item index */
+    getRow: (itemIndex: number) => number;
+    /** Get the column index for a flat item index */
+    getCol: (itemIndex: number) => number;
+    /**
+     * Get the flat item range for a range of rows.
+     * The last row may be partially filled (end is clamped to totalItems - 1).
+     */
+    getItemRange: (rowStart: number, rowEnd: number, totalItems: number) => ItemRange;
+    /**
+     * Get the flat item index from a row and column.
+     * Returns -1 if out of bounds.
+     */
+    getItemIndex: (row: number, col: number, totalItems: number) => number;
+    /**
+     * Calculate column width given container width.
+     * Accounts for gaps: width = (containerWidth - (columns - 1) * gap) / columns
+     */
+    getColumnWidth: (containerWidth: number) => number;
+    /**
+     * Calculate the X offset for a column index.
+     * offset = col * (columnWidth + gap)
+     */
+    getColumnOffset: (col: number, containerWidth: number) => number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/features/grid/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/features/grid/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,YAAY,EAAE,UAAU,EAAE,CAAC;AAM3B,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IAEZ,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IAEd,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,kCAAkC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,8DAA8D;IAC9D,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IAE9C,sDAAsD;IACtD,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAE7C,qDAAqD;IACrD,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,YAAY,CAAC;IAEjD,8CAA8C;IAC9C,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAEtC,iDAAiD;IACjD,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAEtC;;;OAGG;IACH,YAAY,EAAE,CACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,KACf,SAAS,CAAC;IAEf;;;OAGG;IACH,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAEvE;;;OAGG;IACH,cAAc,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,MAAM,CAAC;IAEnD;;;OAGG;IACH,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,KAAK,MAAM,CAAC;CAClE"}

package/dist/features/page/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * vlist/window - Window Scroll Mode Plugin
+ *
+ * Entry point for the window scroll plugin.
+ */
+export { withPage } from "./plugin";
+export type { VListPlugin } from "../../builder/types";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/page/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/page/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/features/page/plugin.d.ts

@@ -0,0 +1,53 @@
+/**
+ * vlist/window - Window Scroll Mode Plugin
+ *
+ * Enables the list to scroll with the page instead of in its own container.
+ * Useful for infinite feeds, full-page lists, and chat UIs that integrate
+ * with page scroll.
+ *
+ * Priority: 5 (runs early, before other plugins that depend on scroll)
+ *
+ * What it does:
+ * - Uses window as scroll target instead of viewport element
+ * - Calculates scroll position relative to document
+ * - Uses window.innerWidth/innerHeight for container dimensions
+ * - Listens to window resize events instead of ResizeObserver
+ * - Adjusts DOM styles (overflow: visible, height: auto)
+ *
+ * Bundle impact: ~0.3 KB gzipped when used
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../builder/types";
+/**
+ * Create a window scroll mode plugin.
+ *
+ * Use this when you want your list to scroll with the page instead of
+ * in a fixed-height container.
+ *
+ * @example
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withWindow } from 'vlist/window'
+ *
+ * const feed = vlist({
+ *   container: '#infinite-feed',
+ *   item: { height: 200, template: renderPost },
+ *   items: posts
+ * })
+ * .use(withWindow())
+ * .build()
+ * ```
+ *
+ * @example Horizontal window scrolling
+ * ```ts
+ * const timeline = vlist({
+ *   container: '#timeline',
+ *   item: { height: 100, template: renderEvent },
+ *   direction: 'horizontal'
+ * })
+ * .use(withWindow())
+ * .build()
+ * ```
+ */
+export declare const withPage: <T extends VListItem = VListItem>() => VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/features/page/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/features/page/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,QAAQ,GACnB,CAAC,SAAS,SAAS,GAAG,SAAS,OAC5B,WAAW,CAAC,CAAC,CA6HjB,CAAC"}

package/dist/features/scale/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * vlist - Compression Sub-module
+ * Re-exports compression utilities for tree-shakeable imports
+ *
+ * Usage: import { getCompressionInfo } from 'vlist/compression'
+ * Usage: import { withScale } from 'vlist/compression'
+ */
+export { MAX_VIRTUAL_HEIGHT, getCompressionState, needsCompression, getMaxItemsWithoutCompression, getCompressionInfo, calculateCompressedVisibleRange, calculateCompressedRenderRange, calculateCompressedItemPosition, calculateCompressedScrollToIndex, calculateIndexFromScrollPosition, type CompressionState, } from "../../rendering/scale";
+export { withScale } from "./plugin";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/scale/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/scale/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,6BAA6B,EAC7B,kBAAkB,EAClB,+BAA+B,EAC/B,8BAA8B,EAC9B,+BAA+B,EAC/B,gCAAgC,EAChC,gCAAgC,EAChC,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/features/scale/plugin.d.ts

@@ -0,0 +1,42 @@
+/**
+ * vlist/compression - Builder Plugin
+ * Enables support for lists with 1M+ items by compressing the scroll space
+ * when the total height exceeds the browser's ~16.7M pixel limit.
+ *
+ * Priority: 20 (runs before scrollbar, after grid/groups)
+ *
+ * What it wires:
+ * - Scroll mode switch — transitions from native to compressed scrolling when needed
+ * - Scroll position mapping — maps compressed scroll positions to item indices
+ * - Item positioning — positions items relative to viewport in compressed mode
+ * - Custom scrollbar fallback — forces custom scrollbar in compressed mode
+ * - Near-bottom interpolation — smooth blending near the end of the list
+ * - Cached compression state — recalculates only when total item count changes
+ *
+ * No configuration needed — compression activates automatically when the total
+ * height exceeds the browser limit, and deactivates when items are removed.
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../builder/types";
+/**
+ * Create a compression plugin for the builder.
+ *
+ * Enables support for lists with 1M+ items. No configuration needed —
+ * compression activates automatically when the total height exceeds
+ * the browser's ~16.7M pixel limit.
+ *
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withCompression } from 'vlist/compression'
+ *
+ * const list = vlist({
+ *   container: '#app',
+ *   item: { height: 48, template: renderItem },
+ *   items: millionItems,
+ * })
+ * .use(withCompression())
+ * .build()
+ * ```
+ */
+export declare const withScale: <T extends VListItem = VListItem>() => VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/features/scale/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/features/scale/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAevE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,SAAS,GACpB,CAAC,SAAS,SAAS,GAAG,SAAS,OAC5B,WAAW,CAAC,CAAC,CA2QjB,CAAC"}

package/dist/features/scrollbar/controller.d.ts

@@ -0,0 +1,121 @@
+/**
+ * vlist - Scroll Controller
+ * Handles both native scrolling and manual wheel-based scrolling for compressed lists
+ *
+ * When compression is active (large lists exceeding browser height limits),
+ * we switch from native scrolling to manual wheel event handling.
+ * This allows smooth scrolling through millions of items.
+ */
+import type { CompressionState } from "../../rendering/scale";
+/** Scroll direction */
+export type ScrollDirection = "up" | "down";
+/** Scroll event data */
+export interface ScrollEventData {
+    scrollTop: number;
+    direction: ScrollDirection;
+    velocity: number;
+}
+/** Scroll controller configuration */
+export interface ScrollControllerConfig {
+    /** Enable compressed scroll mode (manual wheel handling) */
+    compressed?: boolean;
+    /** Compression state for calculating bounds */
+    compression?: CompressionState;
+    /**
+     * External scroll element for window/document scrolling.
+     * When set, the controller listens to this element's scroll events
+     * and computes list-relative positions from the viewport's bounding rect.
+     */
+    scrollElement?: Window;
+    /** Allow mouse wheel to scroll (default: true) */
+    wheel?: boolean;
+    /** Wheel sensitivity multiplier (default: 1) */
+    sensitivity?: number;
+    /** Enable smooth scrolling interpolation */
+    smoothing?: boolean;
+    /** Scroll idle detection timeout in ms (default: 150) */
+    idleTimeout?: number;
+    /**
+     * Enable horizontal scrolling mode.
+     * When true, the controller reads scrollLeft instead of scrollTop,
+     * uses clientWidth instead of clientHeight, and maps wheel deltaX.
+     */
+    horizontal?: boolean;
+    /** Callback when scroll position changes */
+    onScroll?: (data: ScrollEventData) => void;
+    /** Callback when scrolling becomes idle */
+    onIdle?: () => void;
+}
+/** Scroll controller instance */
+export interface ScrollController {
+    /** Get current scroll position */
+    getScrollTop: () => number;
+    /** Set scroll position */
+    scrollTo: (position: number, smooth?: boolean) => void;
+    /** Scroll by delta */
+    scrollBy: (delta: number) => void;
+    /** Check if at top */
+    isAtTop: () => boolean;
+    /** Check if at bottom */
+    isAtBottom: (threshold?: number) => boolean;
+    /** Get scroll percentage (0-1) */
+    getScrollPercentage: () => number;
+    /** Get current scroll velocity (px/ms, absolute value) */
+    getVelocity: () => number;
+    /**
+     * Check if the velocity tracker is actively tracking with enough samples.
+     * Returns false during ramp-up (first few frames of a new scroll gesture)
+     * when the tracker doesn't have enough samples yet.
+     */
+    isTracking: () => boolean;
+    /** Check if currently scrolling */
+    isScrolling: () => boolean;
+    /** Update configuration (e.g., when compression state changes) */
+    updateConfig: (config: Partial<ScrollControllerConfig>) => void;
+    /** Enable compressed mode */
+    enableCompression: (compression: CompressionState) => void;
+    /** Disable compressed mode (revert to native scroll) */
+    disableCompression: () => void;
+    /** Check if compressed mode is active */
+    isCompressed: () => boolean;
+    /** Check if in window scroll mode */
+    isWindowMode: () => boolean;
+    /**
+     * Update the container height used for scroll calculations.
+     * In window mode, call this when the window resizes.
+     */
+    updateContainerHeight: (height: number) => void;
+    /** Destroy and cleanup */
+    destroy: () => void;
+}
+/**
+ * Create a scroll controller for a viewport element
+ *
+ * Supports two modes:
+ * 1. Native scrolling (default) - uses browser's built-in scroll
+ * 2. Compressed scrolling - manual wheel handling for large lists
+ */
+export declare const createScrollController: (viewport: HTMLElement, config?: ScrollControllerConfig) => ScrollController;
+/**
+ * Throttle scroll handler using requestAnimationFrame
+ */
+export declare const rafThrottle: <T extends (...args: any[]) => void>(fn: T) => ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+/**
+ * Check if scroll position is at bottom
+ */
+export declare const isAtBottom: (scrollTop: number, scrollHeight: number, clientHeight: number, threshold?: number) => boolean;
+/**
+ * Check if scroll position is at top
+ */
+export declare const isAtTop: (scrollTop: number, threshold?: number) => boolean;
+/**
+ * Get scroll percentage (0-1)
+ */
+export declare const getScrollPercentage: (scrollTop: number, scrollHeight: number, clientHeight: number) => number;
+/**
+ * Check if a range is visible in the scroll viewport
+ */
+export declare const isRangeVisible: (rangeStart: number, rangeEnd: number, visibleStart: number, visibleEnd: number) => boolean;
+//# sourceMappingURL=controller.d.ts.map