vlist 1.7.4 → 1.7.5

package/README.github.md

@@ -2,7 +2,7 @@
 
 The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 10.5 KB.
 
-**v1.7.4** — [Changelog](./CHANGELOG.md)
+**v1.7.5** — [Changelog](./CHANGELOG.md)
 
 [![npm version](https://img.shields.io/npm/v/vlist.svg)](https://www.npmjs.com/package/vlist)
 [![CI](https://github.com/floor/vlist/actions/workflows/ci.yml/badge.svg)](https://github.com/floor/vlist/actions/workflows/ci.yml)
@@ -95,10 +95,10 @@ const list = vlist({
 | Feature | Size | Description |
 |---------|------|-------------|
 | **Base** | 10.6 KB | Virtualization, ARIA, keyboard nav, gap, padding |
-| `withAsync()` | +4.6 KB | Lazy loading with velocity-aware fetching |
+| `withAsync()` | +4.7 KB | Lazy loading with velocity-aware fetching |
 | `withSelection()` | +3.0 KB | Single/multiple selection with 2D keyboard nav |
 | `withScale()` | +3.7 KB | 1M+ items via scroll compression |
-| `withGroups()` | +2.7 KB | Sticky/inline headers |
+| `withGroups()` | +4.2 KB | Sticky/inline headers with async group discovery |
 | `withAutoSize()` | +0.9 KB | Auto-measure items via ResizeObserver |
 | `withScrollbar()` | +1.7 KB | Custom scrollbar UI |
 | `withGrid()` | +3.9 KB | 2D grid layout |

package/README.md

@@ -55,10 +55,10 @@ const list = vlist({ container: '#app', items, item: { height: 200, template: re
 | Feature | Size | Description |
 |---------|------|-------------|
 | **Base** | 10.6 KB | Virtualization, ARIA, keyboard nav, gap, padding |
-| `withAsync()` | +4.6 KB | Lazy loading with velocity-aware fetching |
+| `withAsync()` | +4.7 KB | Lazy loading with velocity-aware fetching |
 | `withSelection()` | +3.0 KB | Single/multiple selection with 2D keyboard nav |
 | `withScale()` | +3.7 KB | 1M+ items via scroll compression |
-| `withGroups()` | +2.7 KB | Sticky/inline headers |
+| `withGroups()` | +4.2 KB | Sticky/inline headers with async group discovery |
 | `withAutoSize()` | +0.9 KB | Auto-measure items via ResizeObserver |
 | `withScrollbar()` | +1.7 KB | Custom scrollbar UI |
 | `withGrid()` | +3.9 KB | 2D grid layout |
@@ -87,4 +87,4 @@ const list = vlist({ container: '#app', items, item: { height: 200, template: re
 
 ## Acknowledgments
 
-Thanks to [Alexander Klaiber](https://github.com/aklaiber) for graciously transferring the `vlist` package name on npm.
+Thanks to Alexander Klaiber for graciously transferring the `vlist` package name on npm.

package/dist/builder/data.d.ts

@@ -36,6 +36,7 @@ export interface SimpleDataManager<T extends VListItem = VListItem> {
     getStorage: () => unknown;
     getPlaceholders: () => unknown;
     getItem: (index: number) => T | undefined;
+    getIndexById: (id: string | number) => number;
     isItemLoaded: (index: number) => boolean;
     getItemsInRange: (start: number, end: number) => T[];
     setTotal: (total: number) => void;

package/dist/features/groups/async-bridge.d.ts

@@ -0,0 +1,68 @@
+/**
+ * vlist - Async Group Bridge
+ * Virtual group layer that bridges withAsync's sparse data manager with
+ * withGroups' layout system.
+ *
+ * Instead of physically inserting header pseudo-items into the data array
+ * (which is impossible with sparse storage), this bridge:
+ * - Observes items as they load via onItemsLoaded callbacks
+ * - Discovers group boundaries incrementally from loaded data
+ * - Maps between "data indices" (what the async manager knows) and
+ *   "layout indices" (what the renderer sees, including header slots)
+ * - Provides header/item resolution at render time
+ *
+ * Group boundaries are only computed for contiguous loaded ranges.
+ * Unloaded gaps have no headers — placeholders render as regular items.
+ * When gaps fill in, boundaries are recomputed.
+ */
+import type { VListItem } from "../../types";
+import type { GroupBoundary, GroupHeaderItem } from "./types";
+/** Configuration for the async group bridge */
+export interface AsyncBridgeConfig {
+    /** Determine group key for an item */
+    getGroupForIndex: (index: number, item?: any) => string;
+    /** Header height in pixels (resolved for current orientation) */
+    headerHeight: number;
+}
+/** Async group bridge instance */
+export interface AsyncGroupBridge {
+    /** Process newly loaded items — updates group boundaries */
+    onItemsLoaded(items: VListItem[], offset: number, total: number): void;
+    /** Total layout entries (data items + discovered headers) */
+    readonly totalEntries: number;
+    /** Number of discovered groups */
+    readonly groupCount: number;
+    /** All discovered group boundaries */
+    readonly groups: readonly GroupBoundary[];
+    /** Check if a layout index is a group header */
+    isHeader(layoutIndex: number): boolean;
+    /** Get the group header item at a layout index (undefined if not a header) */
+    getHeaderItem(layoutIndex: number): GroupHeaderItem | undefined;
+    /** Map layout index → data index (-1 if it's a header) */
+    layoutToDataIndex(layoutIndex: number): number;
+    /** Map data index → layout index */
+    dataToLayoutIndex(dataIndex: number): number;
+    /** Get header height for a group */
+    getHeaderHeight(groupIndex: number): number;
+    /** Get the group boundary at a layout index */
+    getGroupAtLayoutIndex(layoutIndex: number): GroupBoundary;
+    /** Get the group boundary at a data index */
+    getGroupAtDataIndex(dataIndex: number): GroupBoundary;
+    /** Remove item at data index — shifts group keys and rebuilds */
+    removeAt(dataIndex: number): void;
+    /** Reset all state (e.g. on reload) */
+    reset(): void;
+}
+/**
+ * Create an async group bridge.
+ *
+ * The bridge discovers group boundaries incrementally as items load from
+ * the async adapter. It maintains a mapping between data indices (sparse
+ * storage) and layout indices (data items + group headers).
+ *
+ * @param config - Bridge configuration
+ * @param getItem - Item accessor from the async data manager
+ * @param isItemLoaded - Check if an item at index is loaded (not placeholder)
+ */
+export declare const createAsyncGroupBridge: (config: AsyncBridgeConfig, _getItem: (index: number) => VListItem | undefined, _isItemLoaded: (index: number) => boolean) => AsyncGroupBridge;
+//# sourceMappingURL=async-bridge.d.ts.map

package/dist/features/groups/feature.d.ts

@@ -17,6 +17,7 @@
  *
  * Can be combined with:
  * - withGrid for grouped 2D layouts
+ * - withAsync for grouped lists with async pagination
  * - reverse: true (sticky header shows current section as you scroll up through history)
  * - orientation: 'horizontal' (sticky headers stick to left edge, push left when next header approaches)
  */
@@ -25,7 +26,7 @@ import type { VListFeature } from "../../builder/types";
 /** Groups feature configuration */
 export interface GroupsFeatureConfig {
     /** Returns group key for item at index (required) */
-    getGroupForIndex: (index: number) => string;
+    getGroupForIndex: (index: number, item?: any) => string;
     /** Group header configuration — mirrors the `item` config shape */
     header?: {
         /** Header size in pixels — vertical scrolling (default) */

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

@@ -7,4 +7,5 @@ export type { GroupsConfig, GroupBoundary, LayoutEntry, GroupHeaderItem, GroupLa
 export { isGroupHeader } from "./types";
 export { createGroupLayout, buildLayoutItems, createGroupedSizeFn, } from "./layout";
 export { createStickyHeader } from "./sticky";
+export { createAsyncGroupBridge, type AsyncBridgeConfig, type AsyncGroupBridge } from "./async-bridge";
 //# sourceMappingURL=index.d.ts.map

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

@@ -43,5 +43,5 @@ export declare const createGroupedSizeFn: (layout: GroupLayout, itemSize: number
  * @param itemCount - Number of data items
  * @param config - Groups configuration
  */
-export declare const createGroupLayout: (itemCount: number, config: GroupsConfig) => GroupLayout;
+export declare const createGroupLayout: (itemCount: number, config: GroupsConfig, getItem?: (index: number) => any) => GroupLayout;
 //# sourceMappingURL=layout.d.ts.map

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

@@ -67,8 +67,11 @@ export interface GroupLayout {
     /**
      * Rebuild the layout from scratch.
      * Call when items change (setItems, append, prepend, remove, etc.)
+     *
+     * @param itemCount - Number of data items
+     * @param getItem - Optional item accessor for passing items to getGroupForIndex
      */
-    rebuild: (itemCount: number) => void;
+    rebuild: (itemCount: number, getItem?: (index: number) => any) => void;
 }
 /** Sticky header manager */
 export interface StickyHeader {