vlist 1.7.3 → 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.3** — [Changelog](./changelog.txt)
+**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,18 +95,18 @@ 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()` | +2.9 KB | Single/multiple selection with 2D keyboard nav |
+| `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.8 KB | Custom scrollbar UI |
+| `withScrollbar()` | +1.7 KB | Custom scrollbar UI |
 | `withGrid()` | +3.9 KB | 2D grid layout |
-| `withMasonry()` | +3.4 KB | Pinterest-style masonry with lane-aware keyboard nav |
+| `withMasonry()` | +3.3 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 |
 | `withSortable()` | +3.0 KB | Drag-and-drop reordering with auto-scroll |
-| `withSnapshots()` | +0.9 KB | Scroll position save/restore |
+| `withSnapshots()` | +1.1 KB | Scroll position save/restore |
 
 ## Examples
 

package/README.md

@@ -55,18 +55,18 @@ 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()` | +2.9 KB | Single/multiple selection with 2D keyboard nav |
+| `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.8 KB | Custom scrollbar UI |
+| `withScrollbar()` | +1.7 KB | Custom scrollbar UI |
 | `withGrid()` | +3.9 KB | 2D grid layout |
-| `withMasonry()` | +3.4 KB | Pinterest-style masonry with lane-aware keyboard nav |
+| `withMasonry()` | +3.3 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 |
 | `withSortable()` | +3.0 KB | Drag-and-drop reordering with auto-scroll |
-| `withSnapshots()` | +0.9 KB | Scroll position save/restore |
+| `withSnapshots()` | +1.1 KB | Scroll position save/restore |
 
 ## Framework Adapters
 
@@ -84,3 +84,7 @@ const list = vlist({ container: '#app', items, item: { height: 200, template: re
 ## License
 
 [MIT](LICENSE) — Built by [Floor IO](https://floor.io)
+
+## Acknowledgments
+
+Thanks to Alexander Klaiber for graciously transferring the `vlist` package name on npm.

package/dist/builder/api.d.ts

@@ -17,5 +17,5 @@ import type { DOMStructure } from "./dom";
 import type { createElementPool } from "./pool";
 import type { BuilderContext, VListFeature, VList } from "./types";
 import type { MRefs } from "./materialize";
-export declare const createApi: <T extends VListItem = VListItem>($: MRefs<T>, dom: DOMStructure, emitter: Emitter<VListEvents<T>>, rendered: Map<number, HTMLElement>, pool: ReturnType<typeof createElementPool>, methods: Map<string, Function>, sortedFeatures: VListFeature<T>[], destroyHandlers: Array<() => void>, ctx: BuilderContext<T>, isReverse: boolean, wrapEnabled: boolean, handleClick: (event: MouseEvent) => void, handleDblClick: (event: MouseEvent) => void, handleKeydown: (event: KeyboardEvent) => void, onScrollFrame: () => void, resizeObserver: ResizeObserver, disconnectItemObserver: () => void, clearIdleTimer: () => void) => VList<T>;
+export declare const createApi: <T extends VListItem = VListItem>($: MRefs<T>, dom: DOMStructure, emitter: Emitter<VListEvents<T>>, rendered: Map<number, HTMLElement>, pool: ReturnType<typeof createElementPool>, methods: Map<string, Function>, sortedFeatures: VListFeature<T>[], destroyHandlers: Array<() => void>, ctx: BuilderContext<T>, isReverse: boolean, wrapEnabled: boolean, handleClick: (event: MouseEvent) => void, handleDblClick: (event: MouseEvent) => void, handleContextMenu: (event: MouseEvent) => void, handleKeydown: (event: KeyboardEvent) => void, onScrollFrame: () => void, resizeObserver: ResizeObserver, disconnectItemObserver: () => void, clearIdleTimer: () => void) => VList<T>;
 //# sourceMappingURL=api.d.ts.map

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

@@ -146,6 +146,7 @@ export interface MDeps<T extends VListItem = VListItem> {
     readonly idleHandlers: Array<() => void>;
     readonly afterScroll: Array<(scrollPosition: number, direction: string) => void>;
     readonly clickHandlers: Array<(event: MouseEvent) => void>;
+    readonly contextMenuHandlers: Array<(event: MouseEvent) => void>;
     readonly keydownHandlers: Array<(event: KeyboardEvent) => void>;
     readonly resizeHandlers: Array<(width: number, height: number) => void>;
     readonly destroyHandlers: Array<() => void>;

package/dist/builder/types.d.ts

@@ -240,6 +240,7 @@ export interface BuilderContext<T extends VListItem = VListItem> {
      * These are attached as DOM event listeners during .build().
      */
     clickHandlers: Array<(event: MouseEvent) => void>;
+    contextMenuHandlers: Array<(event: MouseEvent) => void>;
     keydownHandlers: Array<(event: KeyboardEvent) => void>;
     resizeHandlers: Array<(width: number, height: number) => void>;
     contentSizeHandlers: Array<() => 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 {

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

@@ -63,6 +63,14 @@ export interface SelectionFeatureConfig {
      * focus indicator doubles as a "current item" marker.
      */
     focusOnClick?: boolean;
+    /**
+     * How right-click affects selection (default: 'select').
+     * - `'select'` — if the item is not selected, clear selection and select it;
+     *   if already selected, keep current selection (file explorer behavior).
+     * - `'keep'` — never change selection on right-click.
+     * - `false` — don't register a contextmenu handler at all.
+     */
+    contextMenu?: "select" | "keep" | false;
 }
 /**
  * Create a selection feature for the builder.