vlist 1.6.2 → 1.6.4

package/README.github.md

@@ -1,6 +1,6 @@
 # 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 10.6 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)
@@ -8,7 +8,7 @@ The virtual list library for every framework. Accessible by default, batteries-i
 
 - **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.5 KB gzipped** — composable features with perfect tree-shaking
+- **10.6 KB gzipped** — composable features with perfect tree-shaking
 - **Constant memory** — ~0.1 MB overhead at any scale, from 10K to 1M+ items
 
 ## Install
@@ -52,18 +52,18 @@ const list = vlist({ container: '#app', items, item: { height: 200, template: re
 
 | Feature | Size | Description |
 |---------|------|-------------|
-| **Base** | 10.5 KB | Virtualization, ARIA, keyboard nav, gap, padding |
-| `withGrid()` | +3.8 KB | 2D grid layout |
-| `withMasonry()` | +3.3 KB | Pinterest-style masonry with lane-aware keyboard nav |
-| `withTable()` | +5.5 KB | Data table with columns, resize, sort |
-| `withGroups()` | +2.7 KB | Sticky/inline headers |
-| `withAsync()` | +4.5 KB | Lazy loading with velocity-aware fetching |
+| **Base** | 10.6 KB | Virtualization, ARIA, keyboard nav, gap, padding |
+| `withAsync()` | +4.6 KB | Lazy loading with velocity-aware fetching |
 | `withSelection()` | +2.7 KB | Single/multiple selection with 2D keyboard nav |
 | `withScale()` | +3.1 KB | 1M+ items via scroll compression |
+| `withGroups()` | +2.7 KB | Sticky/inline headers |
 | `withAutoSize()` | +0.9 KB | Auto-measure items via ResizeObserver |
-| `withScrollbar()` | +1.1 KB | Custom scrollbar UI |
-| `withPage()` | +0.9 KB | Window-level scrolling |
-| `withSnapshots()` | +0.7 KB | Scroll position save/restore |
+| `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 |
+| `withTable()` | +5.5 KB | Data table with columns, resize, sort |
+| `withPage()` | +0.8 KB | Window-level scrolling |
+| `withSnapshots()` | +0.8 KB | Scroll position save/restore |
 
 ## Framework Adapters
 

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.5 KB.
+The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 10.6 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)
@@ -8,7 +8,7 @@ The virtual list library for every framework. Accessible by default, batteries-i
 
 - **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.5 KB gzipped** — composable features with perfect tree-shaking
+- **10.6 KB gzipped** — composable features with perfect tree-shaking
 - **Constant memory** — ~0.1 MB overhead at any scale, from 10K to 1M+ items
 
 ## Install
@@ -52,18 +52,18 @@ const list = vlist({ container: '#app', items, item: { height: 200, template: re
 
 | Feature | Size | Description |
 |---------|------|-------------|
-| **Base** | 10.5 KB | Virtualization, ARIA, keyboard nav, gap, padding |
-| `withGrid()` | +3.8 KB | 2D grid layout |
-| `withMasonry()` | +3.3 KB | Pinterest-style masonry with lane-aware keyboard nav |
-| `withTable()` | +5.5 KB | Data table with columns, resize, sort |
-| `withGroups()` | +2.7 KB | Sticky/inline headers |
-| `withAsync()` | +4.5 KB | Lazy loading with velocity-aware fetching |
+| **Base** | 10.6 KB | Virtualization, ARIA, keyboard nav, gap, padding |
+| `withAsync()` | +4.6 KB | Lazy loading with velocity-aware fetching |
 | `withSelection()` | +2.7 KB | Single/multiple selection with 2D keyboard nav |
 | `withScale()` | +3.1 KB | 1M+ items via scroll compression |
+| `withGroups()` | +2.7 KB | Sticky/inline headers |
 | `withAutoSize()` | +0.9 KB | Auto-measure items via ResizeObserver |
-| `withScrollbar()` | +1.1 KB | Custom scrollbar UI |
-| `withPage()` | +0.9 KB | Window-level scrolling |
-| `withSnapshots()` | +0.7 KB | Scroll position save/restore |
+| `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 |
+| `withTable()` | +5.5 KB | Data table with columns, resize, sort |
+| `withPage()` | +0.8 KB | Window-level scrolling |
+| `withSnapshots()` | +0.8 KB | Scroll position save/restore |
 
 ## Framework Adapters
 

package/dist/builder/a11y.d.ts

@@ -12,5 +12,5 @@ import type { DOMStructure } from "./dom";
  * Wire up baseline single-select ARIA keyboard navigation.
  * Registers focus/blur listeners, keydown handler, click handler, and destroy cleanup.
  */
-export declare const setupBaselineA11y: <T extends VListItem>($: MRefs<T>, dom: DOMStructure, cp: string, ap: string, hz: boolean, ps: number, pe: number, wr: boolean, methods: Map<string, Function>, rendered: Map<number, HTMLElement>, keydownHandlers: Array<(event: KeyboardEvent) => void>, clickHandlers: Array<(event: MouseEvent) => void>, destroyHandlers: Array<() => void>) => void;
+export declare const setupBaselineA11y: <T extends VListItem>($: MRefs<T>, dom: DOMStructure, cp: string, ap: string, hz: boolean, ps: number, pe: number, wr: boolean, methods: Map<string, Function>, rendered: Map<number, HTMLElement>, keydownHandlers: Array<(event: KeyboardEvent) => void>, clickHandlers: Array<(event: MouseEvent) => void>, destroyHandlers: Array<() => void>, foc: boolean) => void;
 //# sourceMappingURL=a11y.d.ts.map

package/dist/builder/types.d.ts

@@ -94,6 +94,17 @@ export interface BuilderConfig<T extends VListItem = VListItem> {
      * Replaces the former `accessible` option.
      */
     interactive?: boolean;
+    /**
+     * Show focus ring on mouse click (default: false).
+     * By default, clicking an item updates the focused index but does not
+     * show the focus ring — matching the web platform's :focus-visible
+     * convention. Set to true for file-manager or spreadsheet-style UIs
+     * where the focus indicator doubles as a "current item" marker.
+     *
+     * Applies to the baseline single-select keyboard navigation. When
+     * using withSelection(), pass focusOnClick in its own config instead.
+     */
+    focusOnClick?: boolean;
     /** @deprecated Use `interactive` instead */
     accessible?: boolean;
     /** Reverse mode for chat UIs */

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

@@ -40,6 +40,27 @@ export interface ScrollbarFeatureConfig {
      * When false, the scrollbar only appears on scroll or hover near edge.
      */
     showOnViewportEnter?: boolean;
+    /**
+     * Reserve layout space for the scrollbar (default: false).
+     * When true, content shrinks to make room for the scrollbar track so it
+     * never overlaps items. Equivalent to CSS `scrollbar-gutter: stable`.
+     */
+    gutter?: boolean;
+    /**
+     * Padding between the scrollbar track and the viewport edges in pixels (default: 1).
+     * Insets the track from the right wall and from the top and bottom, so the scrollbar
+     * floats rather than sitting flush against the edges. Also adjusts the thumb travel
+     * range to keep position accurate.
+     * Can also be set globally via the `--vlist-custom-scrollbar-padding` CSS variable.
+     */
+    padding?: number;
+    /**
+     * Behavior when clicking on the scrollbar track (not the thumb) (default: 'jump').
+     * - `'jump'`  — jumps directly to the clicked position (centers the thumb there).
+     * - `'page'`  — scrolls by one page (containerSize) toward the clicked position,
+     *               matching macOS native scrollbar behavior.
+     */
+    clickBehavior?: 'jump' | 'page';
 }
 /**
  * Create a scrollbar feature for the builder.

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

@@ -12,6 +12,8 @@
  * - CSS variables for customization
  * - Horizontal mode support (direction-aware axis)
  */
+import type { ScrollbarPadding } from "../../types";
+export type { ScrollbarPadding } from "../../types";
 /** Scrollbar configuration */
 export interface ScrollbarConfig {
     /** Enable scrollbar (default: true when compressed) */
@@ -20,7 +22,10 @@ export interface ScrollbarConfig {
     autoHide?: boolean;
     /** Auto-hide delay in milliseconds (default: 1000) */
     autoHideDelay?: number;
-    /** Minimum thumb size in pixels (default: 30) */
+    /**
+     * Minimum thumb size in pixels (default: 15).
+     * Can also be set globally via the `--vlist-custom-scrollbar-min-thumb-size` CSS variable.
+     */
     minThumbSize?: number;
     /**
      * Show scrollbar when hovering near the scrollbar edge (default: true).
@@ -30,10 +35,13 @@ export interface ScrollbarConfig {
      */
     showOnHover?: boolean;
     /**
-     * Width of the invisible hover zone in pixels (default: 16).
-     * Only used when `showOnHover` is true.
-     * A wider zone makes the scrollbar easier to discover;
-     * a narrower zone avoids interference with content near the edge.
+     * Width of the edge zone in pixels (default: `wallPadding + 16`).
+     * The edge zone covers the scrollbar edge including the padding margin, making
+     * the full area clickable regardless of `showOnHover`. When `showOnHover` is
+     * true, it also acts as the hover-to-reveal target.
+     * Defaults to wall-side padding (`right` for vertical, `bottom` for horizontal)
+     * plus 16px reach, so the zone always covers the full inset track plus a
+     * comfortable buffer.
      */
     hoverZoneWidth?: number;
     /**
@@ -42,6 +50,24 @@ export interface ScrollbarConfig {
      * near the scrollbar edge (if `showOnHover` is true).
      */
     showOnViewportEnter?: boolean;
+    /**
+     * Padding between the scrollbar track and the viewport edges (default: 2).
+     * Insets the track from the edges so the scrollbar floats rather than sitting flush.
+     * Also adjusts the thumb travel range to keep position accurate.
+     *
+     * Accepts a single number (all sides) or an object for per-side control:
+     * `{ top?, right?, bottom?, left? }` — omitted sides default to 2px.
+     *
+     * Can also be set globally via the `--vlist-custom-scrollbar-padding-{side}` CSS variables.
+     */
+    padding?: ScrollbarPadding;
+    /**
+     * Behavior when clicking on the scrollbar track (not the thumb) (default: 'page').
+     * - `'page'`  — scrolls by one page (containerSize) toward the clicked position,
+     *               matching macOS native scrollbar behavior. Hold to scroll continuously.
+     * - `'jump'`  — jumps directly to the clicked position (centers the thumb there).
+     */
+    clickBehavior?: 'jump' | 'page';
 }
 /** Scrollbar instance */
 export interface Scrollbar {

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

@@ -55,6 +55,14 @@ export interface SelectionFeatureConfig {
      * Shift+Click, or Ctrl+Shift+Home/End.
      */
     shiftArrowToggle?: "origin" | "destination";
+    /**
+     * Show focus ring on mouse click (default: false).
+     * By default, clicking an item selects it but does not show the focus
+     * ring — matching the web platform's :focus-visible convention.
+     * Set to true for file-manager or spreadsheet-style UIs where the
+     * focus indicator doubles as a "current item" marker.
+     */
+    focusOnClick?: boolean;
 }
 /**
  * Create a selection feature for the builder.

package/dist/index.d.ts

@@ -24,6 +24,6 @@ export { withTable } from "./features/table";
 export { withAutoSize } from "./features/autosize";
 export { createStats } from "./utils/stats";
 export type { Stats, StatsConfig, StatsState } from "./utils/stats";
-export type { VListItem, VListEvents, ItemConfig, ItemTemplate, ItemState, SelectionMode, SelectionConfig, SelectionState, ScrollbarConfig, ScrollbarOptions, ScrollConfig, ScrollToOptions, ScrollSnapshot, VListAdapter, AdapterParams, AdapterResponse, Range, ViewportState, EventHandler, Unsubscribe, GridConfig, MasonryConfig, GroupsConfig, GroupHeaderConfig, GridSizeContext, GridHeightContext, } from "./types";
+export type { VListItem, VListEvents, ItemConfig, ItemTemplate, ItemState, SelectionMode, SelectionConfig, SelectionState, ScrollbarConfig, ScrollbarPadding, ScrollbarOptions, ScrollConfig, ScrollToOptions, ScrollSnapshot, VListAdapter, AdapterParams, AdapterResponse, Range, ViewportState, EventHandler, Unsubscribe, GridConfig, MasonryConfig, GroupsConfig, GroupHeaderConfig, GridSizeContext, GridHeightContext, } from "./types";
 export type { VListBuilder, VList, BuilderConfig, VListConfig, VListFeature, BuilderContext, ReloadOptions, } from "./builder";
 //# sourceMappingURL=index.d.ts.map