vlist 1.7.4 → 1.7.6

package/README.github.md

@@ -1,8 +1,8 @@
 # vlist
 
-The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 10.5 KB.
+The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 11.2 KB.
 
-**v1.7.4** — [Changelog](./CHANGELOG.md)
+**v1.7.6** — [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)
@@ -11,7 +11,7 @@ The virtual list library for every framework. Accessible by default, batteries-i
 - **New: `withSortable()`** — drag-and-drop reordering with auto-scroll, keyboard support, and ARIA announcements
 - **Accessible** — WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering, ARIA live region
 - **Zero dependencies** — framework-agnostic core with tiny adapters for Vue, Svelte, Solid, React
-- **10.6 KB gzipped** — composable features with perfect tree-shaking
+- **11.2 KB gzipped** — composable features with perfect tree-shaking
 - **Constant memory** — ~0.1 MB overhead at any scale, from 10K to 1M+ items
 - **Grid, masonry, table, groups, async, selection, sortable, scale** — all opt-in
 - **Vertical & horizontal** — single axis-neutral code path, every feature works in both orientations
@@ -94,19 +94,19 @@ 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 |
-| `withSelection()` | +3.0 KB | Single/multiple selection with 2D keyboard nav |
+| **Base** | 11.2 KB | Virtualization, ARIA, keyboard nav, gap, padding |
+| `withAsync()` | +4.5 KB | Lazy loading with velocity-aware fetching |
+| `withSelection()` | +3.2 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.6 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 |
-| `withMasonry()` | +3.3 KB | Pinterest-style masonry with lane-aware keyboard nav |
+| `withScrollbar()` | +1.8 KB | Custom scrollbar UI |
+| `withGrid()` | +4.0 KB | 2D grid layout |
+| `withMasonry()` | +3.5 KB | Pinterest-style masonry with lane-aware keyboard nav |
 | `withTable()` | +5.5 KB | Data table with columns, resize, sort |
-| `withPage()` | +0.8 KB | Window-level scrolling |
+| `withPage()` | +0.7 KB | Window-level scrolling |
 | `withSortable()` | +3.0 KB | Drag-and-drop reordering with auto-scroll |
-| `withSnapshots()` | +1.1 KB | Scroll position save/restore |
+| `withSnapshots()` | +1.3 KB | Scroll position save/restore |
 
 ## Examples
 

package/README.md

@@ -1,6 +1,6 @@
 # vlist
 
-The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 10.6 KB.
+The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 11.2 KB.
 
 [![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)
@@ -9,7 +9,7 @@ The virtual list library for every framework. Accessible by default, batteries-i
 - **New: `withSortable()`** — drag-and-drop reordering with auto-scroll, keyboard support, and ARIA announcements
 - **Zero dependencies** — framework-agnostic core, tiny adapters for Vue, Svelte, Solid, React
 - **Accessible** — WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
-- **10.6 KB gzipped** — composable features with perfect tree-shaking
+- **11.2 KB gzipped** — composable features with perfect tree-shaking
 - **Constant memory** — ~0.1 MB overhead at any scale, from 10K to 1M+ items
 - **Vertical & horizontal** — single axis-neutral code path, every feature works in both orientations
 
@@ -54,19 +54,19 @@ 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 |
-| `withSelection()` | +3.0 KB | Single/multiple selection with 2D keyboard nav |
+| **Base** | 11.2 KB | Virtualization, ARIA, keyboard nav, gap, padding |
+| `withAsync()` | +4.5 KB | Lazy loading with velocity-aware fetching |
+| `withSelection()` | +3.2 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.6 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 |
-| `withMasonry()` | +3.3 KB | Pinterest-style masonry with lane-aware keyboard nav |
+| `withScrollbar()` | +1.8 KB | Custom scrollbar UI |
+| `withGrid()` | +4.0 KB | 2D grid layout |
+| `withMasonry()` | +3.5 KB | Pinterest-style masonry with lane-aware keyboard nav |
 | `withTable()` | +5.5 KB | Data table with columns, resize, sort |
-| `withPage()` | +0.8 KB | Window-level scrolling |
+| `withPage()` | +0.7 KB | Window-level scrolling |
 | `withSortable()` | +3.0 KB | Drag-and-drop reordering with auto-scroll |
-| `withSnapshots()` | +1.1 KB | Scroll position save/restore |
+| `withSnapshots()` | +1.3 KB | Scroll position save/restore |
 
 ## Framework Adapters
 
@@ -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/builder/materialize.d.ts

@@ -162,5 +162,5 @@ export interface MDeps<T extends VListItem = VListItem> {
 }
 export declare const createMaterializeCtx: <T extends VListItem = VListItem>($: MRefs<T>, deps: MDeps<T>) => BuilderContext<T>;
 export declare const createDefaultDataProxy: <T extends VListItem = VListItem>($: MRefs<T>, deps: Pick<MDeps<T>, "rendered" | "itemState" | "contentSizeHandlers" | "applyTemplate" | "updateContentSize">, ctx: BuilderContext<T>) => any;
-export declare const createDefaultScrollProxy: <T extends VListItem = VListItem>($: MRefs<T>, deps: Pick<MDeps<T>, "dom" | "classPrefix">) => any;
+export declare const createDefaultScrollProxy: <T extends VListItem = VListItem>($: MRefs<T>, deps: Pick<MDeps<T>, "dom" | "classPrefix" | "onScrollFrame">) => any;
 //# sourceMappingURL=materialize.d.ts.map

package/dist/builder/types.d.ts

@@ -346,6 +346,15 @@ export interface BuilderContext<T extends VListItem = VListItem> {
      * native DOM scrollTop (which can't represent compressed scroll space).
      */
     setScrollFns(getTop: () => number, setTop: (pos: number) => void): void;
+    /**
+     * Trigger the full scroll pipeline (render, events, afterScroll, velocity
+     * tracking, idle scheduling) using the current scroll position from $.sgt().
+     *
+     * Use this from animation loops (e.g. scale feature's smooth scroll) instead
+     * of scrollController.scrollTo() — it avoids the double-render caused by the
+     * scrollTo proxy calling $.rfn() after $.sst already triggered onScrollFrame.
+     */
+    triggerScrollFrame(): void;
     /**
      * Set the scroll target element (default: viewport).
      * Used by window mode feature to use window instead of viewport for scroll events.

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

@@ -67,5 +67,5 @@ export interface GridRenderer<T extends VListItem = VListItem> {
  * @param ariaIdPrefix - Optional unique prefix for element IDs (for aria-activedescendant)
  * @param isHorizontal - Whether layout is horizontal (scrolls right)
  */
-export declare const createGridRenderer: <T extends VListItem = VListItem>(itemsContainer: HTMLElement, template: ItemTemplate<T>, sizeCache: SizeCache, gridLayout: GridLayout, classPrefix: string, initialContainerWidth: number, totalItemsGetter?: () => number, ariaIdPrefix?: string, isHorizontal?: boolean) => GridRenderer<T>;
+export declare const createGridRenderer: <T extends VListItem = VListItem>(itemsContainer: HTMLElement, template: ItemTemplate<T>, sizeCache: SizeCache, gridLayout: GridLayout, classPrefix: string, initialContainerWidth: number, totalItemsGetter?: () => number, ariaIdPrefix?: string, isHorizontal?: boolean, ariaPosInSetGetter?: (layoutIndex: number) => number) => GridRenderer<T>;
 //# sourceMappingURL=renderer.d.ts.map

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/sticky.d.ts

@@ -17,5 +17,5 @@
  */
 import type { GroupLayout, StickyHeader } from "./types";
 import type { SizeCache } from "../../rendering/sizes";
-export declare const createStickyHeader: (root: HTMLElement, layout: GroupLayout, sizeCache: SizeCache, renderInto: (slot: HTMLElement, groupIndex: number) => void, classPrefix: string, horizontal?: boolean, stickyOffset?: number) => StickyHeader;
+export declare const createStickyHeader: (root: HTMLElement, layout: GroupLayout, sizeCache: SizeCache, renderInto: (slot: HTMLElement, groupIndex: number) => void, classPrefix: string, horizontal?: boolean, stickyOffset?: number, getCompressionRatio?: () => number) => StickyHeader;
 //# sourceMappingURL=sticky.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 {

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

@@ -51,5 +51,5 @@ export interface MasonryRenderer<T extends VListItem = VListItem> {
  * @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 createMasonryRenderer: <T extends VListItem = VListItem>(itemsContainer: HTMLElement, template: ItemTemplate<T>, classPrefix: string, isHorizontal?: boolean, totalItemsGetter?: () => number, ariaIdPrefix?: string) => MasonryRenderer<T>;
+export declare const createMasonryRenderer: <T extends VListItem = VListItem>(itemsContainer: HTMLElement, template: ItemTemplate<T>, classPrefix: string, isHorizontal?: boolean, totalItemsGetter?: () => number, ariaIdPrefix?: string, ariaPosInSetGetter?: (layoutIndex: number) => number) => MasonryRenderer<T>;
 //# sourceMappingURL=renderer.d.ts.map