vlist 1.7.5 → 1.7.7

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.5** — [Changelog](./CHANGELOG.md)
+**v1.7.7** — [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.7 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()` | +4.2 KB | Sticky/inline headers with async group discovery |
+| `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.7 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()` | +4.2 KB | Sticky/inline headers with async group discovery |
+| `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
 

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

@@ -17,5 +17,10 @@
  */
 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;
+/**
+ * Create the sticky header container element upfront (before data arrives)
+ * so the DOM structure is stable and doesn't cause a visual shift.
+ */
+export declare const createStickyContainer: (root: HTMLElement, classPrefix: string, horizontal: boolean, headerHeight: number, stickyOffset?: number) => HTMLElement;
+export declare const createStickyHeader: (root: HTMLElement, layout: GroupLayout, sizeCache: SizeCache, renderInto: (slot: HTMLElement, groupIndex: number) => void, classPrefix: string, horizontal?: boolean, stickyOffset?: number, getCompressionRatio?: () => number, existingContainer?: HTMLElement) => StickyHeader;
 //# sourceMappingURL=sticky.d.ts.map

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

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

@@ -89,11 +89,12 @@ export type ScrollCallback = (position: number) => void;
 /**
  * Create a scrollbar instance
  *
- * @param viewport - The viewport element to attach scrollbar to
+ * @param viewport - The viewport element (used for events and CSS variables)
  * @param onScroll - Callback when scrollbar interaction causes scroll
  * @param config - Scrollbar configuration
  * @param classPrefix - CSS class prefix (default: 'vlist')
  * @param horizontal - Whether the scrollbar is horizontal (default: false)
+ * @param parent - Element to append scrollbar DOM to (default: viewport)
  */
-export declare const createScrollbar: (viewport: HTMLElement, onScroll: ScrollCallback, config?: ScrollbarConfig, classPrefix?: string, horizontal?: boolean) => Scrollbar;
+export declare const createScrollbar: (viewport: HTMLElement, onScroll: ScrollCallback, config?: ScrollbarConfig, classPrefix?: string, horizontal?: boolean, parent?: HTMLElement) => Scrollbar;
 //# sourceMappingURL=scrollbar.d.ts.map