@floor/vlist 0.5.1

package/dist/plugins/data/manager.d.ts

@@ -0,0 +1,103 @@
+/**
+ * vlist - Data Management
+ * Handles data with sparse storage for million+ item support
+ */
+import type { VListItem, VListAdapter, Range } from "../../types";
+import { type SparseStorage, type SparseStorageConfig } from "./sparse";
+import { type PlaceholderConfig, type PlaceholderManager } from "./placeholder";
+/** Data manager configuration */
+export interface DataManagerConfig<T extends VListItem = VListItem> {
+    /** Async data adapter */
+    adapter?: VListAdapter<T>;
+    /** Initial items (optional) */
+    initialItems?: T[];
+    /** Initial total count (if known) */
+    initialTotal?: number;
+    /** Sparse storage configuration */
+    storage?: SparseStorageConfig;
+    /** Placeholder configuration */
+    placeholder?: PlaceholderConfig;
+    /** Items per load request (default: 50) */
+    pageSize?: number;
+    /** Callback when state changes */
+    onStateChange?: (state: DataState<T>) => void;
+    /** Callback when items are loaded */
+    onItemsLoaded?: (items: T[], offset: number, total: number) => void;
+    /** Callback when items are evicted */
+    onItemsEvicted?: (count: number) => void;
+}
+/** Data state */
+export interface DataState<_T extends VListItem = VListItem> {
+    /** Total items (declared, may be larger than loaded) */
+    total: number;
+    /** Number of items in memory */
+    cached: number;
+    /** Whether data is loading */
+    isLoading: boolean;
+    /** Pending load ranges */
+    pendingRanges: Range[];
+    /** Error from last operation */
+    error: Error | undefined;
+    /** Whether more items exist */
+    hasMore: boolean;
+    /** Current cursor (for cursor pagination) */
+    cursor: string | undefined;
+}
+/** Data manager instance */
+export interface DataManager<T extends VListItem = VListItem> {
+    /** Get current state */
+    getState: () => DataState<T>;
+    /** Get total item count (direct getter, no allocation) */
+    getTotal: () => number;
+    /** Get cached item count (direct getter, no allocation) */
+    getCached: () => number;
+    /** Check if currently loading (direct getter, no allocation) */
+    getIsLoading: () => boolean;
+    /** Check if more items available (direct getter, no allocation) */
+    getHasMore: () => boolean;
+    /** Get sparse storage */
+    getStorage: () => SparseStorage<T>;
+    /** Get placeholder manager */
+    getPlaceholders: () => PlaceholderManager<T>;
+    /** Get item at index (may return placeholder if not loaded) */
+    getItem: (index: number) => T | undefined;
+    /** Get item by ID */
+    getItemById: (id: string | number) => T | undefined;
+    /** Get index by ID (-1 if not found) */
+    getIndexById: (id: string | number) => number;
+    /** Check if item at index is loaded (not placeholder) */
+    isItemLoaded: (index: number) => boolean;
+    /** Get items in range (includes placeholders for unloaded) */
+    getItemsInRange: (start: number, end: number) => T[];
+    /** Set total item count */
+    setTotal: (total: number) => void;
+    /** Set items at offset */
+    setItems: (items: T[], offset?: number, total?: number) => void;
+    /** Update item by ID */
+    updateItem: (id: string | number, updates: Partial<T>) => boolean;
+    /** Remove item by ID */
+    removeItem: (id: string | number) => boolean;
+    /** Load items for a range */
+    loadRange: (start: number, end: number) => Promise<void>;
+    /** Ensure range is loaded (no-op if already loaded) */
+    ensureRange: (start: number, end: number) => Promise<void>;
+    /** Load initial data */
+    loadInitial: () => Promise<void>;
+    /** Load more items (infinite scroll) */
+    loadMore: () => Promise<boolean>;
+    /** Reload all data */
+    reload: () => Promise<void>;
+    /** Evict items far from visible range */
+    evictDistant: (visibleStart: number, visibleEnd: number) => void;
+    /** Clear all data */
+    clear: () => void;
+    /** Reset to initial state */
+    reset: () => void;
+}
+/**
+ * Create a data manager with sparse storage support
+ */
+export declare const createDataManager: <T extends VListItem = VListItem>(config?: DataManagerConfig<T>) => DataManager<T>;
+export { mergeRanges, calculateMissingRanges } from "./sparse";
+export { isPlaceholderItem, filterPlaceholders, countRealItems, } from "./placeholder";
+//# sourceMappingURL=manager.d.ts.map

package/dist/plugins/data/manager.d.ts.map

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

package/dist/plugins/data/placeholder.d.ts

@@ -0,0 +1,62 @@
+/**
+ * vlist - Placeholder System
+ * Smart placeholder generation for loading states
+ *
+ * Key features:
+ * - Analyzes loaded data to generate realistic placeholders
+ * - Supports masked text with configurable character
+ * - Random length variance for natural appearance
+ * - Efficient placeholder detection
+ */
+import type { VListItem } from "../../types";
+/** Placeholder configuration */
+export interface PlaceholderConfig {
+    /** Enable placeholder generation (default: true) */
+    enabled?: boolean;
+    /** Character used for masking text (default: '█') */
+    maskCharacter?: string;
+    /** Add random variance to text lengths (default: true) */
+    randomVariance?: boolean;
+    /** Maximum items to sample for structure analysis (default: 20) */
+    maxSampleSize?: number;
+    /** Custom placeholder generator */
+    customGenerator?: (index: number) => VListItem;
+}
+/** Placeholder manager instance */
+export interface PlaceholderManager<T extends VListItem = VListItem> {
+    /** Analyze data structure from sample items */
+    analyzeStructure: (items: T[]) => void;
+    /** Check if structure has been analyzed */
+    hasAnalyzedStructure: () => boolean;
+    /** Generate a single placeholder item */
+    generate: (index: number) => T;
+    /** Generate multiple placeholder items */
+    generateRange: (start: number, end: number) => T[];
+    /** Check if an item is a placeholder */
+    isPlaceholder: (item: unknown) => boolean;
+    /** Get the placeholder flag key */
+    getPlaceholderKey: () => string;
+    /** Clear analyzed structure */
+    clear: () => void;
+}
+/**
+ * Create a placeholder manager
+ */
+export declare const createPlaceholderManager: <T extends VListItem = VListItem>(config?: PlaceholderConfig) => PlaceholderManager<T>;
+/**
+ * Check if an item is a placeholder (standalone function)
+ */
+export declare const isPlaceholderItem: (item: unknown) => boolean;
+/**
+ * Filter out placeholder items from an array
+ */
+export declare const filterPlaceholders: <T extends VListItem>(items: T[]) => T[];
+/**
+ * Count non-placeholder items in an array
+ */
+export declare const countRealItems: <T extends VListItem>(items: (T | undefined)[]) => number;
+/**
+ * Replace placeholders in a sparse array with real items
+ */
+export declare const replacePlaceholders: <T extends VListItem>(target: (T | undefined)[], items: T[], offset: number) => number;
+//# sourceMappingURL=placeholder.d.ts.map

package/dist/plugins/data/placeholder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder.d.ts","sourceRoot":"","sources":["../../../src/plugins/data/placeholder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C,gCAAgC;AAChC,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,mCAAmC;IACnC,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,CAAC;CAChD;AAiBD,mCAAmC;AACnC,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IACjE,+CAA+C;IAC/C,gBAAgB,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;IAEvC,2CAA2C;IAC3C,oBAAoB,EAAE,MAAM,OAAO,CAAC;IAEpC,yCAAyC;IACzC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC;IAE/B,0CAA0C;IAC1C,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC,EAAE,CAAC;IAEnD,wCAAwC;IACxC,aAAa,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1C,mCAAmC;IACnC,iBAAiB,EAAE,MAAM,MAAM,CAAC;IAEhC,+BAA+B;IAC/B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAeD;;GAEG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,SAAS,SAAS,GAAG,SAAS,EACtE,SAAQ,iBAAsB,KAC7B,kBAAkB,CAAC,CAAC,CA+OtB,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,OAAO,KAAG,OAMjD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,SAAS,EAAE,OAAO,CAAC,EAAE,KAAG,CAAC,EAErE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,SAAS,EAChD,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,KACvB,MAUF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,SAAS,EACrD,QAAQ,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,EACzB,OAAO,CAAC,EAAE,EACV,QAAQ,MAAM,KACb,MAiBF,CAAC"}

package/dist/plugins/data/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 withData: <T extends VListItem = VListItem>(config: DataPluginConfig<T>) => VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/data/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/data/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,QAAQ,GAAI,CAAC,SAAS,SAAS,GAAG,SAAS,EACtD,QAAQ,gBAAgB,CAAC,CAAC,CAAC,KAC1B,WAAW,CAAC,CAAC,CAiOf,CAAC"}

package/dist/plugins/data/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/plugins/data/sparse.d.ts.map

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

package/dist/plugins/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/plugins/grid/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/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/plugins/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/plugins/grid/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/plugins/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/plugins/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/plugins/grid/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/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,CA8Zf,CAAC"}

package/dist/plugins/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 "../../render/heights";
+import type { CompressionContext } from "../../render/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/plugins/grid/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../src/plugins/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,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,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/plugins/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/plugins/grid/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/plugins/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/plugins/groups/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * vlist - Groups Domain
+ * Sticky headers and grouped lists
+ */
+export { withGroups, type GroupsPluginConfig } from "./plugin";
+export type { GroupsConfig, GroupBoundary, LayoutEntry, GroupHeaderItem, GroupLayout, StickyHeader, } from "./types";
+export { isGroupHeader } from "./types";
+export { createGroupLayout, buildLayoutItems, createGroupedHeightFn, } from "./layout";
+export { createStickyHeader } from "./sticky";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/groups/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/groups/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,UAAU,EAAE,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAG/D,YAAY,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EACX,eAAe,EACf,WAAW,EACX,YAAY,GACb,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC"}

package/dist/plugins/groups/layout.d.ts

@@ -0,0 +1,46 @@
+/**
+ * vlist - Group Layout
+ * Computes group boundaries and maps between data indices and layout indices.
+ *
+ * The layout transforms a flat items array into a "layout" that includes
+ * group header pseudo-items interspersed at group boundaries:
+ *
+ *   Data:   [item0, item1, item2, item3, item4, item5]
+ *   Groups: [  A,     A,     A,     B,     B,     C  ]
+ *   Layout: [headerA, item0, item1, item2, headerB, item3, item4, headerC, item5]
+ *   Index:  [  0,       1,     2,     3,      4,      5,     6,      7,      8  ]
+ *
+ * All lookups are O(log g) where g = number of groups, using binary search
+ * on the sorted group boundaries array.
+ */
+import type { GroupsConfig, GroupBoundary, GroupLayout, GroupHeaderItem } from "./types";
+import type { VListItem } from "../../types";
+/**
+ * Build the transformed layout items array with header pseudo-items inserted
+ * at group boundaries.
+ *
+ * @param items - Original data items
+ * @param groups - Computed group boundaries
+ * @returns Array of items and header pseudo-items in layout order
+ */
+export declare const buildLayoutItems: <T extends VListItem>(items: T[], groups: readonly GroupBoundary[]) => Array<T | GroupHeaderItem>;
+/**
+ * Create a height function for the layout that returns the correct height
+ * for both group headers and data items.
+ *
+ * @param layout - The group layout instance
+ * @param itemHeight - Original item height config (number or function)
+ * @returns A height function (layoutIndex) => number suitable for HeightCache
+ */
+export declare const createGroupedHeightFn: (layout: GroupLayout, itemHeight: number | ((index: number) => number)) => ((layoutIndex: number) => number);
+/**
+ * Create a GroupLayout instance.
+ *
+ * The layout computes group boundaries from items and provides efficient
+ * O(log g) mappings between data indices and layout indices.
+ *
+ * @param itemCount - Number of data items
+ * @param config - Groups configuration
+ */
+export declare const createGroupLayout: (itemCount: number, config: GroupsConfig) => GroupLayout;
+//# sourceMappingURL=layout.d.ts.map

package/dist/plugins/groups/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/plugins/groups/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EAEX,eAAe,EAChB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AA+G7C;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,SAAS,EAClD,OAAO,CAAC,EAAE,EACV,QAAQ,SAAS,aAAa,EAAE,KAC/B,KAAK,CAAC,CAAC,GAAG,eAAe,CA0B3B,CAAC;AAMF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,WAAW,EACnB,YAAY,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,KAC/C,CAAC,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAelC,CAAC;AAMF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAC5B,WAAW,MAAM,EACjB,QAAQ,YAAY,KACnB,WAkIF,CAAC"}