vlist 1.6.1 → 1.6.2

package/README.github.md

@@ -2,46 +2,19 @@
 
 The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 10.5 KB.
 
-**v1.6.1** — [Changelog](./changelog.txt)
-
 [![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)
 [![license](https://img.shields.io/npm/l/vlist.svg)](https://github.com/floor/vlist/blob/main/LICENSE)
 
-- **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
+- **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
 - **Constant memory** — ~0.1 MB overhead at any scale, from 10K to 1M+ items
-- **Grid, masonry, table, groups, async, selection, scale** — all opt-in
-- **Vertical & horizontal** — dimension-agnostic API, every layout mode works in both orientations
-
-**18 interactive examples, docs & benchmarks → [vlist.io](https://vlist.io)**
-
-## Why vlist
-
-| | vlist | TanStack Virtual | react-virtuoso | virtua | vue-virtual-scroller |
-|---|---|---|---|---|---|
-| **A11y built-in** | WAI-ARIA + 2D keyboard | None (DIY) | Partial | Minimal | None |
-| **Grid + Masonry + Table** | All | Grid only | Grid + Table | Grid only | None |
-| **Vue** | 0.6 KB adapter | Yes | — | Yes | 11.8 KB |
-| **Svelte** | 0.5 KB adapter | Yes | — | Yes | — |
-| **Solid** | 0.5 KB adapter | Yes | — | Yes | — |
-| **Vanilla JS** | Native | Yes | — | — | — |
-| **Constant memory** | ~0.1 MB at 1M | No | No | No | No |
-
-## Framework Adapters
 
-| Framework | Package | Size |
-|-----------|---------|------|
-| Vanilla JS | `vlist` | Native — no adapter needed |
-| Vue | [`vlist-vue`](https://github.com/floor/vlist-vue) | 0.6 KB gzip |
-| Svelte | [`vlist-svelte`](https://github.com/floor/vlist-svelte) | 0.5 KB gzip |
-| SolidJS | [`vlist-solidjs`](https://github.com/floor/vlist-solidjs) | 0.5 KB gzip |
-| React | [`vlist-react`](https://github.com/floor/vlist-react) | 0.6 KB gzip |
+## Install
 
 ```bash
-npm install vlist              # vanilla JS
-npm install vlist vlist-vue    # or vlist-svelte / vlist-solidjs / vlist-react
+npm install vlist
 ```
 
 ## Quick Start
@@ -62,303 +35,49 @@ const list = vlist({
     template: (item) => `<div>${item.name}</div>`,
   },
 }).build()
-
-list.scrollToIndex(10)
-list.setItems(newItems)
-list.on('item:click', ({ item }) => console.log(item))
 ```
 
-## Builder Pattern
-
-Start with the base, add only what you need:
+Add features with the builder pattern:
 
 ```typescript
-import { vlist, withGrid, withGroups, withSelection } from 'vlist'
+import { vlist, withGrid, withSelection } from 'vlist'
 
-const list = vlist({
-  container: '#app',
-  items: photos,
-  item: { height: 200, template: renderPhoto },
-})
+const list = vlist({ container: '#app', items, item: { height: 200, template: render } })
   .use(withGrid({ columns: 4, gap: 16 }))
-  .use(withGroups({
-    getGroupForIndex: (i) => photos[i].category,
-    header: { height: 40, template: (cat) => `<h2>${cat}</h2>` },
-  }))
   .use(withSelection({ mode: 'multiple' }))
   .build()
 ```
 
-### Features
+## Features
 
 | Feature | Size | Description |
 |---------|------|-------------|
-| **Base** | 10.5 KB | Core virtualization, gap, padding, ARIA live region, baseline keyboard nav |
-| `withGrid()` | +3.8 KB | 2D grid layout with context injection |
-| `withMasonry()` | +3.3 KB | Pinterest-style masonry layout with lane-aware nav |
-| `withGroups()` | +2.7 KB | Grouped lists with sticky/inline headers |
-| `withAsync()` | +4.5 KB | Lazy loading with adapters |
-| `withSelection()` | +2.7 KB | Single/multiple selection + 2D keyboard nav |
+| **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 |
+| `withSelection()` | +2.7 KB | Single/multiple selection with 2D keyboard nav |
 | `withScale()` | +3.1 KB | 1M+ items via scroll compression |
-| `withScrollbar()` | +1.1 KB | Custom scrollbar UI |
-| `withTable()` | +5.5 KB | Data table with columns, resize, sort, groups |
 | `withAutoSize()` | +0.9 KB | Auto-measure items via ResizeObserver |
-| `withPage()` | +0.4 KB | Document-level scrolling |
-| `withSnapshots()` | +0.7 KB | Scroll save/restore with autoSave |
-
-## Examples
-
-More examples at **[vlist.io](https://vlist.io)**.
-
-### Data Table
-
-```typescript
-import { vlist, withTable, withSelection } from 'vlist'
-
-const table = vlist({
-  container: '#my-table',
-  items: contacts,
-  item: { height: 36, template: () => '' },
-})
-  .use(withTable({
-    columns: [
-      { key: 'name',   label: 'Name',   width: 200, sortable: true },
-      { key: 'email',  label: 'Email',  width: 260, sortable: true },
-      { key: 'role',   label: 'Role',   width: 160, sortable: true },
-      { key: 'status', label: 'Status', width: 100, align: 'center' },
-    ],
-    rowHeight: 36,
-    headerHeight: 36,
-    resizable: true,
-  }))
-  .use(withSelection({ mode: 'single' }))
-  .build()
-
-table.on('column:sort', ({ key, direction }) => { /* re-sort data */ })
-table.on('column:resize', ({ key, width }) => { /* persist widths */ })
-```
-
-### Grid Layout
-
-```typescript
-import { vlist, withGrid, withScrollbar } from 'vlist'
-
-const gallery = vlist({
-  container: '#gallery',
-  items: photos,
-  item: {
-    height: 200,
-    template: (photo) => `
-      <div class="card">
-        <img src="${photo.url}" />
-        <span>${photo.title}</span>
-      </div>
-    `,
-  },
-})
-  .use(withGrid({ columns: 4, gap: 16 }))
-  .use(withScrollbar({ autoHide: true }))
-  .build()
-```
-
-### Async Loading
-
-```typescript
-import { vlist, withAsync } from 'vlist'
-
-const list = vlist({
-  container: '#list',
-  item: {
-    height: 64,
-    template: (item) => item
-      ? `<div>${item.name}</div>`
-      : `<div class="placeholder">Loading…</div>`,
-  },
-})
-  .use(withAsync({
-    adapter: {
-      read: async ({ offset, limit }) => {
-        const res = await fetch(`/api/users?offset=${offset}&limit=${limit}`)
-        const data = await res.json()
-        return { items: data.items, total: data.total, hasMore: data.hasMore }
-      },
-    },
-  }))
-  .build()
-```
-
-## Accessibility
-
-Every vlist is accessible by default following the [WAI-ARIA listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/):
-
-- **Arrow keys** move focus between items with a visible focus ring
-- **2D navigation** in grids and masonry — Up/Down by row, Left/Right by cell
-- **Masonry lane-aware nav** — arrows stay in the same visual column
-- **Home/End, PageUp/PageDown, Ctrl+Home/End** — full keyboard coverage
-- **Screen-reader DOM ordering** — items reordered on scroll idle for correct reading order
-- **ARIA live region** — announces loading state changes
-- **Focus recovery** — maintains focus when items are removed
-
-Set `interactive: false` for display-only lists (log viewers, activity feeds) where items contain their own interactive elements.
-
-## API
-
-```typescript
-const list = vlist(config).use(...features).build()
-```
-
-### Data
-
-| Method | Description |
-|--------|-------------|
-| `list.setItems(items)` | Replace all items |
-| `list.appendItems(items)` | Add to end (auto-scrolls in reverse mode) |
-| `list.prependItems(items)` | Add to start (preserves scroll position) |
-| `list.updateItem(index, partial)` | Update a single item by index |
-| `list.removeItem(index)` | Remove by index |
-| `list.getItemAt(index)` | Get item at index |
-| `list.getIndexById(id)` | Get index by item ID |
-| `list.reload()` | Re-fetch from adapter (async) |
-
-### Navigation
-
-| Method | Description |
-|--------|-------------|
-| `list.scrollToIndex(i, align?)` | Scroll to index (`'start'` \| `'center'` \| `'end'`) |
-| `list.scrollToIndex(i, opts?)` | With `{ align, behavior: 'smooth', duration }` |
-| `list.cancelScroll()` | Cancel smooth scroll animation |
-| `list.getScrollPosition()` | Current scroll offset |
-
-### Selection (with `withSelection()`)
-
-| Method | Description |
-|--------|-------------|
-| `list.select(...ids)` | Select item(s) |
-| `list.deselect(...ids)` | Deselect item(s) |
-| `list.toggleSelect(id)` | Toggle |
-| `list.selectAll()` / `list.clearSelection()` | Bulk operations |
-| `list.getSelected()` | Array of selected IDs |
-| `list.getSelectedItems()` | Array of selected items |
-
-### Events
-
-`list.on()` returns an unsubscribe function. You can also use `list.off(event, handler)`.
-
-```typescript
-list.on('scroll', ({ scrollPosition, direction }) => {})
-list.on('range:change', ({ range }) => {})
-list.on('item:click', ({ item, index, event }) => {})
-list.on('item:dblclick', ({ item, index, event }) => {})
-list.on('selection:change', ({ selectedIds, selectedItems }) => {})
-list.on('load:start', ({ offset, limit }) => {})
-list.on('load:end', ({ items, offset, total }) => {})
-list.on('load:error', ({ error, offset, limit }) => {})
-```
-
-### Properties
-
-| Property | Description |
-|----------|-------------|
-| `list.element` | Root DOM element |
-| `list.items` | Current items (readonly) |
-| `list.total` | Total item count |
-| `list.destroy()` | Cleanup and remove from DOM |
-
-## Feature Configuration
-
-Each feature's config is fully typed — hover in your IDE for details.
-
-```typescript
-withGrid({ columns: 4, gap: 16 })
-withMasonry({ columns: 4, gap: 16 })
-withGroups({ getGroupForIndex, header: { height, template }, sticky?: true })
-withSelection({ mode: 'single' | 'multiple', initial?: [...ids] })
-withAsync({ adapter: { read }, loading?: { cancelThreshold? } })
-withTable({ columns, rowHeight, headerHeight?, resizable? })
-withAutoSize()                        // auto-measure items (requires estimatedHeight)
-withScale()                           // auto-activates at 16.7M px
-withScrollbar({ autoHide?, autoHideDelay?, minThumbSize? })
-withPage()                            // no config — uses document scroll
-withSnapshots({ autoSave: 'key' })    // automatic sessionStorage save/restore
-```
-
-Full configuration reference → **[vlist.io](https://vlist.io)**
-
-## Base Configuration
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `overscan` | `3` | Extra items rendered outside viewport |
-| `ariaLabel` | — | Accessible label for the listbox |
-| `orientation` | `'vertical'` | `'vertical'` or `'horizontal'` scroll direction |
-| `padding` | `0` | Content inset — number, `[v, h]`, or `[top, right, bottom, left]` |
-| `interactive` | `true` | Enable built-in keyboard navigation |
-| `reverse` | `false` | Reverse mode for chat UIs |
-| `scroll.wrap` | `false` | Wrap focus around at boundaries |
-
-## Styling
-
-```typescript
-import 'vlist/styles'           // core (always required)
-import 'vlist/styles/grid'      // when using withGrid()
-import 'vlist/styles/masonry'   // when using withMasonry()
-import 'vlist/styles/table'     // when using withTable()
-import 'vlist/styles/extras'    // optional (variants, loading states, animations)
-```
-
-Dark mode works out of the box via `prefers-color-scheme`, Tailwind's `.dark` class, or `data-theme-mode="dark"`. Override CSS custom properties to match your design system. See [vlist.io/tutorials/styling](https://vlist.io/tutorials/styling) for the full guide.
-
-## Performance
-
-| Dataset Size | After Render | Scroll Delta |
-|--------------|-------------|--------------|
-| 10K items | 0.07 MB | ~0 MB |
-| 100K items | 0.08 MB | ~0 MB |
-| 1M items | 0.09 MB | 0.19 MB |
-
-- **Initial render:** ~8ms (constant, regardless of item count)
-- **Scroll:** 120 FPS at any scale
-- **DOM nodes:** ~26 in document with 100K items (visible + overscan only)
-
-Live benchmarks against 9 competitors → **[vlist.io/benchmarks](https://vlist.io/benchmarks)**
-
-## TypeScript
-
-Fully typed. Generic over your item type:
-
-```typescript
-import { vlist, withGrid, type VList } from 'vlist'
+| `withScrollbar()` | +1.1 KB | Custom scrollbar UI |
+| `withPage()` | +0.9 KB | Window-level scrolling |
+| `withSnapshots()` | +0.7 KB | Scroll position save/restore |
 
-interface Photo { id: number; url: string; title: string }
+## Framework Adapters
 
-const list: VList<Photo> = vlist<Photo>({
-  container: '#gallery',
-  items: photos,
-  item: {
-    height: 200,
-    template: (photo) => `<img src="${photo.url}" />`,
-  },
-})
-  .use(withGrid({ columns: 4 }))
-  .build()
-```
+| Framework | Package | Size |
+|-----------|---------|------|
+| Vue | [`vlist-vue`](https://github.com/floor/vlist-vue) | 0.6 KB |
+| Svelte | [`vlist-svelte`](https://github.com/floor/vlist-svelte) | 0.5 KB |
+| SolidJS | [`vlist-solidjs`](https://github.com/floor/vlist-solidjs) | 0.5 KB |
+| React | [`vlist-react`](https://github.com/floor/vlist-react) | 0.6 KB |
 
-## Contributing
+## Docs & Examples
 
-1. Fork → branch → make changes → add tests → pull request
-2. Run `bun test` and `bun run build` before submitting
+**18 interactive examples, full API reference, tutorials, and live benchmarks → [vlist.io](https://vlist.io)**
 
 ## License
 
-[MIT](LICENSE)
-
-## Links
-
-- **Docs & Examples:** [vlist.io](https://vlist.io)
-- **GitHub:** [github.com/floor/vlist](https://github.com/floor/vlist)
-- **NPM:** [vlist](https://www.npmjs.com/package/vlist)
-- **Issues:** [GitHub Issues](https://github.com/floor/vlist/issues)
-
----
-
-Built by [Floor IO](https://floor.io)
+[MIT](LICENSE) — Built by [Floor IO](https://floor.io)

package/README.md

@@ -62,7 +62,7 @@ const list = vlist({ container: '#app', items, item: { height: 200, template: re
 | `withScale()` | +3.1 KB | 1M+ items via scroll compression |
 | `withAutoSize()` | +0.9 KB | Auto-measure items via ResizeObserver |
 | `withScrollbar()` | +1.1 KB | Custom scrollbar UI |
-| `withPage()` | +0.4 KB | Window-level scrolling |
+| `withPage()` | +0.9 KB | Window-level scrolling |
 | `withSnapshots()` | +0.7 KB | Scroll position save/restore |
 
 ## Framework Adapters

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

@@ -13,11 +13,56 @@
  * - Uses window.innerWidth/innerHeight for container dimensions
  * - Listens to window resize events instead of ResizeObserver
  * - Adjusts DOM styles (overflow: visible, height: auto)
+ * - Optionally accounts for fixed/sticky chrome via scrollPadding
+ * - Uses behavior: "instant" on all scrollTo calls to override CSS
+ *   scroll-behavior: smooth that may be set on the page
  *
  * Bundle impact: ~0.3 KB gzipped when used
  */
 import type { VListItem } from "../../types";
 import type { VListFeature } from "../../builder/types";
+/**
+ * Options for the window scroll mode feature.
+ */
+export interface WithPageOptions {
+    /**
+     * Scroll padding — insets from the viewport edges where fixed/sticky
+     * elements (headers, footers, toolbars) live.
+     *
+     * When keyboard focus moves an item behind a sticky bar, the list
+     * auto-scrolls to keep it within the visible (unobstructed) area.
+     * Also affects `scrollToIndex` alignment (start/center/end).
+     *
+     * Mirrors CSS `scroll-padding` semantics: defines the optimal viewing
+     * region within the scrollport.
+     *
+     * Values can be numbers (pixels) or functions that return pixels
+     * (useful when the sticky element's height is dynamic).
+     *
+     * @example
+     * ```ts
+     * withPage({
+     *   scrollPadding: { top: 60, bottom: 50 }
+     * })
+     * ```
+     *
+     * @example Dynamic values
+     * ```ts
+     * withPage({
+     *   scrollPadding: {
+     *     top: () => document.getElementById('sticky-header')!.offsetHeight,
+     *     bottom: 50
+     *   }
+     * })
+     * ```
+     */
+    scrollPadding?: {
+        top?: number | (() => number);
+        bottom?: number | (() => number);
+        left?: number | (() => number);
+        right?: number | (() => number);
+    };
+}
 /**
  * Create a window scroll mode feature.
  *
@@ -38,6 +83,17 @@ import type { VListFeature } from "../../builder/types";
  * .build()
  * ```
  *
+ * @example With scroll padding for sticky chrome
+ * ```ts
+ * const feed = vlist({
+ *   container: '#infinite-feed',
+ *   item: { height: 200, template: renderPost },
+ *   items: posts
+ * })
+ * .use(withPage({ scrollPadding: { top: 60, bottom: 50 } }))
+ * .build()
+ * ```
+ *
  * @example Horizontal window scrolling
  * ```ts
  * const timeline = vlist({
@@ -49,5 +105,5 @@ import type { VListFeature } from "../../builder/types";
  * .build()
  * ```
  */
-export declare const withPage: <T extends VListItem = VListItem>() => VListFeature<T>;
+export declare const withPage: <T extends VListItem = VListItem>(options?: WithPageOptions) => VListFeature<T>;
 //# sourceMappingURL=feature.d.ts.map

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

@@ -4,5 +4,6 @@
  * Entry point for the window scroll feature.
  */
 export { withPage } from "./feature";
+export type { WithPageOptions } from "./feature";
 export type { VListFeature } from "../../builder/types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export type { ScaleConfig } from "./features/scale";
 export { withAsync } from "./features/async";
 export { withScrollbar } from "./features/scrollbar";
 export { withPage } from "./features/page";
+export type { WithPageOptions } from "./features/page";
 export { withGroups } from "./features/groups";
 export { withGrid } from "./features/grid";
 export { withMasonry } from "./features/masonry";