vlist 3.0.0-next.2 → 3.0.0-next.4

package/README.github.md

@@ -2,16 +2,16 @@
 
 The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins.
 
-**v3.0.0-next.2** (prerelease on the npm `next` tag) — Native scrolling by default, opt-in `vlist/synthetic`, and removal of deprecated scroll configuration and plugin hooks. See the [changelog](https://github.com/floor/vlist/blob/next/CHANGELOG.md).
+**v3.0.0-next.4** (prerelease on the npm `next` tag) — Native scrolling by default, opt-in `vlist/synthetic`, and removal of deprecated scroll configuration and plugin hooks. See the [changelog](https://github.com/floor/vlist/blob/next/CHANGELOG.md).
 
 [![npm version](https://img.shields.io/npm/v/vlist.svg)](https://www.npmjs.com/package/vlist)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/vlist)](https://bundlephobia.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
+- **Accessible** — `a11y()` or a selection mode adds WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
 - **Zero dependencies** — framework-agnostic core with tiny adapters for Vue, Svelte, Solid, React
-- **9.3 KB gzipped (3.0 prerelease)** — composable plugins with perfect tree-shaking
+- **10.0 KB gzipped (3.0 prerelease)** — composable plugins with perfect tree-shaking
 - **Constant memory** — ~0.1 MB overhead at any scale, from 10K to 1M+ items
 - **Tree, grid, masonry, carousel, table, groups, data, selection, search, sortable, transition** — all opt-in
 - **Axis-neutral** — vertical and horizontal scrolling through a single code path, all plugins work in both orientations
@@ -22,7 +22,7 @@ The virtual list library for every framework. Ultra efficient, batteries-include
 
 | | vlist | TanStack Virtual | react-virtuoso | virtua | vue-virtual-scroller |
 |---|---|---|---|---|---|
-| **A11y built-in** | WAI-ARIA + 2D keyboard | None (DIY) | Partial | Minimal | None |
+| **A11y** | WAI-ARIA + 2D keyboard, one plugin | 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 | — |
@@ -108,7 +108,7 @@ const list = createVList({
 
 ## Scroll input
 
-Native scrolling is the default: import `createVList` and plugins from `vlist`. This preserves browser scrollbars, native touch momentum, boundary handoff and native assistive-technology scrolling. Carousel, sortable and horizontal RTL lists work with this factory. Carousel supplies its private wrap runway only when the plugin is imported; bounded scrolling is no longer a public mode.
+Native scrolling is the default: import `createVList` and plugins from `vlist`. This preserves browser scrollbars, native touch momentum, boundary handoff and native assistive-technology scrolling. Carousel and sortable work with this factory; horizontal RTL lists are rejected by both entries. Carousel supplies its private wrap runway only when the plugin is imported; bounded scrolling is no longer a public mode.
 
 | Entry | Input model | Use |
 |---|---|---|
@@ -134,9 +134,11 @@ const list = createVList({
 
 `page()` uses native document scrolling through an external source with either entry. Its content must fit the 16,777,216 px document element limit; creation throws above that limit when the size is known, and later growth warns once. A deferred custom renderer whose size is first committed during rendering also warns once. Use `vlist/synthetic` viewport scrolling for larger lists. Default native viewport lists warn once when content exceeds their browser-size safety limit, pointing to that entry.
 
+`carousel()` works with either entry. Synthetic carousel folds preserve touch motion and smooth snapping across whole laps. `page()` and carousel remain incompatible. The shared carousel plugin includes its native wrap handler even when used with synthetic input; the combined size is reported below.
+
 Synthetic input limitations:
 
-- `carousel()`, `sortable()` and horizontal RTL lists throw with instructions to use `vlist`. Vertical lists and tables support `dir="rtl"`, including cross-axis wheel movement, aligned table headers and keyboard column navigation.
+- Horizontal RTL lists throw at creation — in this entry and in `vlist`. Vertical lists and tables support `dir="rtl"` in both, including cross-axis wheel movement, aligned table headers and keyboard column navigation.
 - Same-axis touch stops at either boundary with no parent handoff, including gestures starting inside an edge-pinned list. Use the native default when boundary gestures must scroll the parent page.
 - There is no native main-axis scrollbar. Add `scrollbar()` for an accessible custom scrollbar. The synthetic entry rejects the `"native"` and `"none"` scrollbar strings.
 - Inertia initializes its frame clock on the first frame after release, adding up to one frame of release latency.
@@ -144,6 +146,19 @@ Synthetic input limitations:
 
 Measurement corrections from autosize preserve ongoing synthetic motion. Existing plugin conflicts still apply. See the [scroll input contract](https://vlist.io/docs/rfcs/RFC-014-Scroll-Input-Model).
 
+### Sortable gestures
+
+`sortable()` works with either input entry. Mouse and trackpad dragging still starts after `dragThreshold` (5 px by default). Touch and pen without a handle use `touchDelay`, a 350 ms long press; moving at least `dragThreshold` pixels in any direction before it completes yields to scrolling. This delay separates a deliberate hold from a quick flick. With `handle`, dragging starts at the threshold without waiting; touches elsewhere scroll.
+
+```typescript
+sortable({ touchDelay: 350, dragThreshold: 5 })
+sortable({ handle: '.drag-handle' })
+```
+
+A touch during scrolling catches the motion and does not arm a hold for that contact. Lift and press again once the list is at rest. A second finger or `pointercancel` cancels the pending press or active drag. Edge auto-scroll uses the list's logical position and stops on drop.
+
+The touch-only `.vlist-item--touch-sort` class suppresses selection and callouts on the pressed item. A claimed touch/pen drag adds `.vlist-sort-ghost--touch` to the ghost as a visual cue; override that class in CSS to customize it. Keyboard reordering remains Space to grab/drop, arrows to move and Escape to cancel.
+
 ## Migrating to 3.0
 
 `3.0.0-next.1` used synthetic input by default. `3.0.0-next.2` restores the 2.x default. Import `vlist/synthetic` explicitly to retain synthetic behavior across these prereleases. `vlist/native` remains a deprecated compatibility alias; its `NativeScrollConfig` and `NativeCreateVListConfig` types alias the standard `ScrollConfig` and `CreateVListConfig`.
@@ -153,36 +168,39 @@ Measurement corrections from autosize preserve ongoing synthetic motion. Existin
 | `scroll.mode` (all values, both entries) | Omit it. `vlist` provides native scrolling; import `vlist/synthetic` for synthetic input. |
 | `scroll.runway` (both entries) | Remove it. For huge lists use `vlist/synthetic`, which needs no native runway. |
 | `scroll.scrollbar: "native"` or `"none"` | Retained in default `ScrollConfig`. With synthetic input, omit the string and optionally install `scrollbar()`. |
-| `PluginContext.setScrollFns`, `disableDefaultScroll` | Use `setScrollSource` to supply an external position source and commit callback. |
+| `PluginContext.setScrollFns`, `disableDefaultScroll` | Use `ctx.scroll.setSource` to supply an external position source and commit callback. |
+| Flat `PluginContext` members (`registerMethod`, `forceRender`, `sizeCache`, `scrollTo`, …) | Grouped by capability: `ctx.hooks.method`, `ctx.render.force`, `ctx.sizes.cache`, `ctx.scroll.to`, `ctx.items.all`. `pool`, `config`, `emitter`, `template` and `getState()` stay at the top level. |
 | `scale()` and `ScalePluginConfig` | Remove them; use `vlist/synthetic` for the full logical range. Config no longer installs a scale stub. |
 
-Removed mode/runway options throw a migration error before creating DOM. `vlist/config` retains scrollbar omission/options convenience and its top-level `scrollbar: "none"` option. `baseOffset` stays private engine state; plugins use `ctx.scroll.getRenderOrigin()`. Custom wrap providers now supply their handler factory as the second argument of `ctx.setBoundedWrap`.
+Removed mode/runway options throw a migration error before creating DOM. `vlist/config` wires only what the config asks for: `selection`, the custom scrollbar, `snapshots` and `a11y` are each opt-in, so an adapter list matches a core list built from the same options. It keeps the scrollbar options convenience and its top-level `scrollbar: "none"`; pass `scrollbar: true` for the overlay scrollbar earlier versions added to every list. `baseOffset` stays private engine state; plugins use `ctx.scroll.getRenderOrigin()`. Custom wrap providers now supply their handler factory as the second argument of `ctx.scroll.setBoundedWrap`.
 
 ## Plugins
 
 | Entry / export | Minified | Gzipped |
 |---|---:|---:|
-| **Base (`vlist`)** | 25.4 KB | 9.3 KB |
-| `vlist/synthetic` | 31.1 KB | 11.4 KB |
-| `vlist/native` (alias) | 25.4 KB | 9.3 KB |
-| `a11y()` | 28.7 KB | 10.5 KB |
-| `selection()` | 34.8 KB | 12.1 KB |
-| `data()` | 39.0 KB | 14.1 KB |
-| `scrollbar()` | 33.6 KB | 12.2 KB |
-| `sortable()` | 34.9 KB | 12.2 KB |
-| `groups()` | 41.3 KB | 14.6 KB |
-| `page()` | 27.9 KB | 10.2 KB |
-| `snapshots()` | 28.7 KB | 10.4 KB |
-| `transition()` | 32.1 KB | 11.3 KB |
-| `autosize()` | 28.5 KB | 10.3 KB |
-| `grid()` | 32.5 KB | 11.8 KB |
-| `table()` | 43.8 KB | 15.2 KB |
-| `masonry()` | 36.8 KB | 13.4 KB |
-| `tree()` | 40.6 KB | 14.3 KB |
-| `search()` | 34.5 KB | 12.4 KB |
-| `carousel()` | 38.0 KB | 13.7 KB |
-
-Sizes are tree-shaken totals from `bun run size`, not additive plugin costs. Plugin rows include the native default factory plus that plugin. The base is **9,523 bytes gzipped**, below the 9.9 KB target; synthetic input is **11,687 bytes** before plugins. The alias row measures the same source factory; the distributed alias re-exports it without duplicating the implementation.
+| **Base (`vlist`)** | 26.9 KB | 10.0 KB |
+| `vlist/synthetic` | 33.8 KB | 12.6 KB |
+| `vlist/native` (alias) | 26.9 KB | 10.0 KB |
+| `a11y()` | 30.7 KB | 11.3 KB |
+| `selection()` | 36.4 KB | 12.9 KB |
+| `data()` | 40.6 KB | 14.8 KB |
+| `scrollbar()` | 35.1 KB | 12.8 KB |
+| `sortable()` | 38.7 KB | 13.4 KB |
+| `groups()` | 43.0 KB | 15.4 KB |
+| `page()` | 29.5 KB | 10.9 KB |
+| `snapshots()` | 30.2 KB | 11.1 KB |
+| `transition()` | 33.7 KB | 12.0 KB |
+| `autosize()` | 30.1 KB | 11.1 KB |
+| `grid()` | 34.4 KB | 12.5 KB |
+| `table()` | 45.4 KB | 15.9 KB |
+| `masonry()` | 39.0 KB | 14.4 KB |
+| `tree()` | 43.1 KB | 15.3 KB |
+| `search()` | 36.5 KB | 13.3 KB |
+| `carousel()` | 41.7 KB | 15.1 KB |
+| `vlist/synthetic` + `carousel()` | 47.8 KB | 17.4 KB |
+| `vlist/synthetic` + `sortable()` | 45.7 KB | 16.1 KB |
+
+Sizes are tree-shaken totals from `bun run size`, not additive plugin costs. Plugin rows include the native default factory plus that plugin. The base is **10,200 bytes gzipped**, within the 10.0 KB budget (10,240 bytes). `bun run size` fails if a scenario fails to build, an unused plugin leaks into a bundle, or any published size exceeds its gzip budget. Synthetic input is **12,889 bytes** before plugins. The alias row measures the same source factory; the distributed alias re-exports it without duplicating the implementation.
 
 ## Examples
 
@@ -307,6 +325,13 @@ const list = createVList({
 ])
 ```
 
+Search filters client-side over the items the list holds, so it cannot be
+combined with `data()` — creating a list with both throws. With an adapter, the
+rows in memory are only the loaded window; query the remote dataset through the
+adapter instead. It cannot be combined with `tree()` either: filtering a tree
+means keeping the ancestors of each match, which belongs to the plugin that
+owns the layout, and `tree()` offers no such hook.
+
 ## Custom scrollbar (3.0 preview)
 
 On `next`, `scrollbar()` remains a plugin. macOS and Android default to thin,
@@ -367,7 +392,9 @@ colors take priority while forced colors are active.
 
 ## Accessibility
 
-Every vlist is accessible by default following the [WAI-ARIA listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/):
+Accessibility is a plugin, not a default. Add `a11y()`, or a `selection()` mode
+other than `"none"` which brings the same behaviour, and the list follows 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
@@ -376,7 +403,9 @@ Every vlist is accessible by default following the [WAI-ARIA listbox pattern](ht
 - **Screen-reader DOM ordering** — items reordered on scroll idle for correct reading order
 - **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.
+A list created without either stays display-only: `role="list"`, no item roles
+and out of the tab order. That is the right shape for log viewers and activity
+feeds, and for items carrying their own interactive elements.
 
 ## API
 
@@ -390,7 +419,7 @@ const list = createVList(config, [plugin1(), plugin2()])
 |--------|-------------|
 | `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.prependItems(items)` | Add to start (in reverse mode, the visible rows hold their position) |
 | `list.updateItem(id, partial)` | Update a single item by ID |
 | `list.insertItem(item, index?)` | Insert at index (animated with `transition`) |
 | `list.removeItem(id)` | Remove by ID (animated with `transition`) |
@@ -410,12 +439,14 @@ const list = createVList(config, [plugin1(), plugin2()])
 
 | Method | Description |
 |--------|-------------|
-| `list.select(...ids)` | Select item(s) |
+| `list.select(...ids)` | Select item(s) without moving the viewport |
 | `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 |
+| `list.selectNext()` | Select the next item and scroll it into view |
+| `list.selectPrevious()` | Select the previous item and scroll it into view |
 
 ### Events
 
@@ -434,6 +465,10 @@ list.on('sort:end', ({ fromIndex, toIndex }) => {})
 list.on('sort:cancel', ({ originalItems }) => {})
 ```
 
+The `index` on `item:click`, `item:dblclick` and `item:contextmenu` is the data
+index — the one `getItemAt`, `scrollToIndex` and `removeItem` take — not the
+layout index, which counts group headers and carousel laps.
+
 ### Properties
 
 | Property | Description |
@@ -481,8 +516,7 @@ Full configuration reference → **[vlist.io](https://vlist.io)**
 | `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 |
+| `reverse` | `false` | The list reads bottom-up (chat UIs): a view sitting at the end stays there as `appendItems` adds to it, `prependItems` holds the visible rows in place as older history loads above them, arrow keys invert, and `transition()` animates from the bottom. Item order is yours to supply; the layout itself is not reversed. `masonry()` and `table()` reject it |
 
 ## Styling
 
@@ -512,23 +546,38 @@ Live benchmarks against 9 competitors → **[vlist.io/benchmarks](https://vlist.
 
 ## TypeScript
 
-Fully typed. Generic over your item type:
+Fully typed and generic over your item type. An item only needs an `id`, so ordinary
+interfaces work:
 
 ```typescript
-import { createVList, grid, type VList } from 'vlist'
+import { createVList, grid, selection, type CreateVListConfig } from 'vlist'
 
 interface Photo { id: number; url: string; title: string }
 
-const list: VList<Photo> = createVList<Photo>({
+const config: CreateVListConfig<Photo> = {
   container: '#gallery',
   items: photos,
   item: {
     height: 200,
     template: (photo) => `<img src="${photo.url}" />`,
   },
-}, [grid({ columns: 4 })])
+}
+
+const list = createVList(config, [grid({ columns: 4 }), selection<Photo>({ mode: 'multiple' })])
+
+list.select(photos[0].id)                      // typed: selection is in the array
+const chosen: Photo[] = list.getSelectedItems()
+// list.expand(1)                              // compile error: no tree plugin here
 ```
 
+`createVList` infers the methods each plugin adds, so a list exposes exactly what its
+plugins provide, and a mistyped call does not compile.
+
+TypeScript does not allow a partial type argument list. Writing
+`createVList<Photo>(config, plugins)` supplies the item type and leaves the plugin list on
+its default, so plugin methods are not inferred. Type the config as above, or let the item
+type come from your data.
+
 ## Migrating from v1
 
 v2 is a ground-up rewrite — simpler API, 55% smaller base bundle, zero-allocation scroll path. [Full announcement →](https://vlist.io/blog/v2)

package/README.md

@@ -2,16 +2,16 @@
 
 The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins.
 
-**v3.0.0-next.2** (prerelease on the npm `next` tag) — Native scrolling by default, opt-in `vlist/synthetic`, and removal of deprecated scroll configuration and plugin hooks. See the [changelog](https://github.com/floor/vlist/blob/next/CHANGELOG.md).
+**v3.0.0-next.4** (prerelease on the npm `next` tag) — Native scrolling by default, opt-in `vlist/synthetic`, and removal of deprecated scroll configuration and plugin hooks. See the [changelog](https://github.com/floor/vlist/blob/next/CHANGELOG.md).
 
 [![npm version](https://img.shields.io/npm/v/vlist.svg)](https://www.npmjs.com/package/vlist)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/vlist)](https://bundlephobia.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
+- **Accessible** — `a11y()` or a selection mode adds WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
 - **Zero dependencies** — framework-agnostic core, tiny adapters for Vue, Svelte, Solid, React
-- **9.3 KB gzipped (3.0 prerelease)** — composable plugins with perfect tree-shaking
+- **10.0 KB gzipped (3.0 prerelease)** — composable plugins with perfect tree-shaking
 - **Constant memory** — ~0.1 MB overhead at any scale, from 10K to 1M+ items
 - **Axis-neutral** — vertical and horizontal scrolling through a single code path, all plugins work in both orientations
 
@@ -55,7 +55,7 @@ const list = createVList({ container: '#app', items, item: { height: 200, templa
 
 ## Scroll input
 
-Native scrolling is the default: import `createVList` and plugins from `vlist`. This preserves browser scrollbars, native touch momentum, boundary handoff and native assistive-technology scrolling. Carousel, sortable and horizontal RTL lists work with this factory. Carousel supplies its private wrap runway only when the plugin is imported; bounded scrolling is no longer a public mode.
+Native scrolling is the default: import `createVList` and plugins from `vlist`. This preserves browser scrollbars, native touch momentum, boundary handoff and native assistive-technology scrolling. Carousel and sortable work with this factory; horizontal RTL lists are rejected by both entries. Carousel supplies its private wrap runway only when the plugin is imported; bounded scrolling is no longer a public mode.
 
 | Entry | Input model | Use |
 |---|---|---|
@@ -81,9 +81,11 @@ const list = createVList({
 
 `page()` uses native document scrolling through an external source with either entry. Its content must fit the 16,777,216 px document element limit; creation throws above that limit when the size is known, and later growth warns once. A deferred custom renderer whose size is first committed during rendering also warns once. Use `vlist/synthetic` viewport scrolling for larger lists. Default native viewport lists warn once when content exceeds their browser-size safety limit, pointing to that entry.
 
+`carousel()` works with either entry. Synthetic carousel folds preserve touch motion and smooth snapping across whole laps. `page()` and carousel remain incompatible. The shared carousel plugin includes its native wrap handler even when used with synthetic input; the combined size is reported below.
+
 Synthetic input limitations:
 
-- `carousel()`, `sortable()` and horizontal RTL lists throw with instructions to use `vlist`. Vertical lists and tables support `dir="rtl"`, including cross-axis wheel movement, aligned table headers and keyboard column navigation.
+- Horizontal RTL lists throw at creation — in this entry and in `vlist`. Vertical lists and tables support `dir="rtl"` in both, including cross-axis wheel movement, aligned table headers and keyboard column navigation.
 - Same-axis touch stops at either boundary with no parent handoff, including gestures starting inside an edge-pinned list. Use the native default when boundary gestures must scroll the parent page.
 - There is no native main-axis scrollbar. Add `scrollbar()` for an accessible custom scrollbar. The synthetic entry rejects the `"native"` and `"none"` scrollbar strings.
 - Inertia initializes its frame clock on the first frame after release, adding up to one frame of release latency.
@@ -91,6 +93,19 @@ Synthetic input limitations:
 
 Measurement corrections from autosize preserve ongoing synthetic motion. Existing plugin conflicts still apply. See the [scroll input contract](https://vlist.io/docs/rfcs/RFC-014-Scroll-Input-Model).
 
+### Sortable gestures
+
+`sortable()` works with either input entry. Mouse and trackpad dragging still starts after `dragThreshold` (5 px by default). Touch and pen without a handle use `touchDelay`, a 350 ms long press; moving at least `dragThreshold` pixels in any direction before it completes yields to scrolling. This delay separates a deliberate hold from a quick flick. With `handle`, dragging starts at the threshold without waiting; touches elsewhere scroll.
+
+```typescript
+sortable({ touchDelay: 350, dragThreshold: 5 })
+sortable({ handle: '.drag-handle' })
+```
+
+A touch during scrolling catches the motion and does not arm a hold for that contact. Lift and press again once the list is at rest. A second finger or `pointercancel` cancels the pending press or active drag. Edge auto-scroll uses the list's logical position and stops on drop.
+
+The touch-only `.vlist-item--touch-sort` class suppresses selection and callouts on the pressed item. A claimed touch/pen drag adds `.vlist-sort-ghost--touch` to the ghost as a visual cue; override that class in CSS to customize it. Keyboard reordering remains Space to grab/drop, arrows to move and Escape to cancel.
+
 ## Migrating to 3.0
 
 `3.0.0-next.1` used synthetic input by default. `3.0.0-next.2` restores the 2.x default. Import `vlist/synthetic` explicitly to retain synthetic behavior across these prereleases. `vlist/native` remains a deprecated compatibility alias; its `NativeScrollConfig` and `NativeCreateVListConfig` types alias the standard `ScrollConfig` and `CreateVListConfig`.
@@ -103,33 +118,35 @@ Measurement corrections from autosize preserve ongoing synthetic motion. Existin
 | `PluginContext.setScrollFns`, `disableDefaultScroll` | Use `setScrollSource` to supply an external position source and commit callback. |
 | `scale()` and `ScalePluginConfig` | Remove them; use `vlist/synthetic` for the full logical range. Config no longer installs a scale stub. |
 
-Removed mode/runway options throw a migration error before creating DOM. `vlist/config` retains scrollbar omission/options convenience and its top-level `scrollbar: "none"` option. `baseOffset` stays private engine state; plugins use `ctx.scroll.getRenderOrigin()`. Custom wrap providers now supply their handler factory as the second argument of `ctx.setBoundedWrap`.
+Removed mode/runway options throw a migration error before creating DOM. `vlist/config` wires only what the config asks for: `selection`, the custom scrollbar, `snapshots` and `a11y` are each opt-in, so an adapter list matches a core list built from the same options. It keeps the scrollbar options convenience and its top-level `scrollbar: "none"`; pass `scrollbar: true` for the overlay scrollbar earlier versions added to every list. `baseOffset` stays private engine state; plugins use `ctx.scroll.getRenderOrigin()`. Custom wrap providers now supply their handler factory as the second argument of `ctx.scroll.setBoundedWrap`.
 
 ## Plugins
 
 | Entry / export | Minified | Gzipped |
 |---|---:|---:|
-| **Base (`vlist`)** | 25.4 KB | 9.3 KB |
-| `vlist/synthetic` | 31.1 KB | 11.4 KB |
-| `vlist/native` (alias) | 25.4 KB | 9.3 KB |
-| `a11y()` | 28.7 KB | 10.5 KB |
-| `selection()` | 34.8 KB | 12.1 KB |
-| `data()` | 39.0 KB | 14.1 KB |
-| `scrollbar()` | 33.6 KB | 12.2 KB |
-| `sortable()` | 34.9 KB | 12.2 KB |
-| `groups()` | 41.3 KB | 14.6 KB |
-| `page()` | 27.9 KB | 10.2 KB |
-| `snapshots()` | 28.7 KB | 10.4 KB |
-| `transition()` | 32.1 KB | 11.3 KB |
-| `autosize()` | 28.5 KB | 10.3 KB |
-| `grid()` | 32.5 KB | 11.8 KB |
-| `table()` | 43.8 KB | 15.2 KB |
-| `masonry()` | 36.8 KB | 13.4 KB |
-| `tree()` | 40.6 KB | 14.3 KB |
-| `search()` | 34.5 KB | 12.4 KB |
-| `carousel()` | 38.0 KB | 13.7 KB |
-
-Sizes are tree-shaken totals from `bun run size`, not additive plugin costs. Plugin rows include the native default factory plus that plugin. The base is **9,523 bytes gzipped**, below the 9.9 KB target; synthetic input is **11,687 bytes** before plugins. The alias row measures the same source factory; the distributed alias re-exports it without duplicating the implementation.
+| **Base (`vlist`)** | 26.9 KB | 10.0 KB |
+| `vlist/synthetic` | 33.8 KB | 12.6 KB |
+| `vlist/native` (alias) | 26.9 KB | 10.0 KB |
+| `a11y()` | 30.7 KB | 11.3 KB |
+| `selection()` | 36.4 KB | 12.9 KB |
+| `data()` | 40.6 KB | 14.8 KB |
+| `scrollbar()` | 35.1 KB | 12.8 KB |
+| `sortable()` | 38.7 KB | 13.4 KB |
+| `groups()` | 43.0 KB | 15.4 KB |
+| `page()` | 29.5 KB | 10.9 KB |
+| `snapshots()` | 30.2 KB | 11.1 KB |
+| `transition()` | 33.7 KB | 12.0 KB |
+| `autosize()` | 30.1 KB | 11.1 KB |
+| `grid()` | 34.4 KB | 12.5 KB |
+| `table()` | 45.4 KB | 15.9 KB |
+| `masonry()` | 39.0 KB | 14.4 KB |
+| `tree()` | 43.1 KB | 15.3 KB |
+| `search()` | 36.5 KB | 13.3 KB |
+| `carousel()` | 41.7 KB | 15.1 KB |
+| `vlist/synthetic` + `carousel()` | 47.8 KB | 17.4 KB |
+| `vlist/synthetic` + `sortable()` | 45.7 KB | 16.1 KB |
+
+Sizes are tree-shaken totals from `bun run size`, not additive plugin costs. Plugin rows include the native default factory plus that plugin. The base is **10,200 bytes gzipped**, within the 10.0 KB budget (10,240 bytes). `bun run size` fails if a scenario fails to build, an unused plugin leaks into a bundle, or any published size exceeds its gzip budget. Synthetic input is **12,889 bytes** before plugins. The alias row measures the same source factory; the distributed alias re-exports it without duplicating the implementation.
 
 ## Framework Adapters
 

package/dist/config.d.ts

@@ -17,11 +17,20 @@
  */
 import type { VListItem, GroupsConfig, VListAdapter, ScrollConfig } from "./types";
 import { createVList } from "./core/create";
-import type { CreateVListConfig, VList, VListPlugin } from "./core/types";
+import type { CreateVListConfig, VList, VListPlugin, PluginMethods } from "./core/types";
+import type { AutosizeMethods } from "./plugins/autosize/plugin";
+import type { DataMethods } from "./plugins/data/plugin";
+import type { GridMethods } from "./plugins/grid/plugin";
+import type { MasonryMethods } from "./plugins/masonry/plugin";
+import type { GroupsMethods } from "./plugins/groups/plugin";
+import type { SelectionMethods } from "./plugins/selection/plugin";
+import type { ScrollbarMethods } from "./plugins/scrollbar/plugin";
+import type { SnapshotsMethods } from "./plugins/snapshots/plugin";
 import type { DataPluginConfig } from "./plugins/data";
 import type { GridPluginConfig } from "./plugins/grid";
 import type { MasonryPluginConfig } from "./plugins/masonry";
 import type { SelectionPluginConfig } from "./plugins/selection";
+import type { A11yPluginConfig } from "./plugins/a11y";
 import type { ScrollbarPluginConfig } from "./plugins/scrollbar";
 /** List creation function injected by an adapter consumer. */
 export type VListFactory<T extends VListItem = VListItem> = typeof createVList<T>;
@@ -43,11 +52,32 @@ export interface VListConfig<T extends VListItem = VListItem> extends Omit<Creat
     /** Masonry layout options — applied when `layout: "masonry"`. */
     masonry?: MasonryPluginConfig;
     /** Sticky group headers. */
-    groups?: GroupsConfig;
-    /** Row selection (single / multi). */
+    groups?: GroupsConfig<T>;
+    /**
+     * Row selection (single / multi). Omit it for a display-only list: nothing
+     * is wired then, so the list keeps `role="list"` and stays out of the tab
+     * order, exactly like a core list created without the plugin.
+     */
     selection?: SelectionPluginConfig;
-    /** Custom scrollbar options, or `"none"` to disable the custom scrollbar. */
-    scrollbar?: ScrollbarPluginConfig | "none";
+    /**
+     * Keyboard navigation, focus management and the WAI-ARIA listbox roles.
+     * Off by default, as in core: pass `true` for the defaults or an object to
+     * tune it. A selection mode other than `"none"` already provides both, so a
+     * list with one does not need this as well.
+     */
+    a11y?: A11yPluginConfig | boolean;
+    /**
+     * Custom overlay scrollbar. Off by default, as in core, which leaves the
+     * browser's native scrollbar in place: pass `true` for the defaults or an
+     * object to tune them. `"none"` is accepted for symmetry with
+     * `scroll.scrollbar` and wires nothing.
+     */
+    scrollbar?: ScrollbarPluginConfig | "none" | boolean;
+    /**
+     * Scroll position save/restore (`saveScroll` / `restoreScroll`).
+     * Off by default, as in core.
+     */
+    snapshots?: boolean;
     /** Async data source — enables the data plugin. */
     adapter?: VListAdapter<T>;
     /** Async loading tuning (used together with `adapter`). */
@@ -57,23 +87,110 @@ export interface VListConfig<T extends VListItem = VListItem> extends Omit<Creat
      * the convenience fields: a plugin whose `name` matches an auto-wired one
      * (e.g. passing `grid()` while `layout: "grid"` is set) replaces it rather
      * than duplicating; plugins with new names are appended.
+     *
+     * Looser than `createVList`'s plugin list: a plugin explicitly typed for a
+     * different item, such as `groups<Other>()`, is accepted with no check.
      */
-    plugins?: VListPlugin<T>[];
+    plugins?: VListPlugin<any, any>[];
 }
 /**
  * Translate a {@link VListConfig} into the ordered plugin array that the core
- * `createVList` expects. Mirrors the adapters' historical behavior exactly:
- * `snapshots` is always included, and `selection` is always
- * present (in `"none"` mode when unset) so its API is available. Any user
- * `plugins` are appended last as an escape hatch.
+ * `createVList` expects. Every plugin comes from a field the caller set, so a
+ * config with no feature fields resolves to no plugins and an adapter list
+ * behaves like a core list given the same options. Any user `plugins` are
+ * appended last as an escape hatch.
  */
 export declare function resolvePlugins<T extends VListItem = VListItem>(config: VListConfig<T>): VListPlugin<T>[];
+/** A field value that wires no plugin. `"none"` is the scrollbar's spelling of off. */
+type Off = false | undefined | null | "none";
+/**
+ * The methods a field adds when it is on. Distributive on purpose: a widened
+ * `boolean` is `true | false`, so the result is `M | {}` and a call on it is a
+ * type error — the honest answer when the compiler cannot know whether the
+ * plugin is seated. Narrow the config, or spell the field as a literal.
+ */
+type OnOff<V, M> = V extends Off ? {} : M;
+/**
+ * The methods field `K` adds, or nothing when the config has no such field.
+ * Indexing `C[K]` directly would fall back to the constraint's type for an
+ * absent key and hand a plain config every plugin's methods.
+ */
+type Field<C, K extends PropertyKey, M> = C extends Record<K, infer V> ? OnOff<V, M> : {};
+/** Whether the item spec carries an estimate, which wires autosize(). */
+type Estimated<C> = C extends {
+    item: {
+        estimatedHeight: number;
+    } | {
+        estimatedWidth: number;
+    };
+} ? C extends {
+    item: {
+        height: number;
+    } | {
+        width: number;
+    };
+} ? {} : AutosizeMethods : {};
+/**
+ * The plugin methods a {@link VListConfig} wires, derived from its fields the
+ * same way {@link resolvePlugins} derives the plugins — the two are the type
+ * and runtime halves of one mapping, and `test/types/config.ts` asserts they
+ * agree. This is what lets an adapter list carry `select()` or `reload()` the
+ * way a core list built with `createVList(config, [selection()])` does.
+ */
+export type ConfigMethods<T extends VListItem, C extends VListConfig<T>> = Field<C, "adapter", DataMethods> & (C extends {
+    layout: "grid";
+} ? GridMethods : {}) & (C extends {
+    layout: "masonry";
+} ? MasonryMethods : {}) & Field<C, "groups", GroupsMethods<T>> & Field<C, "selection", SelectionMethods<T>> & Field<C, "scrollbar", ScrollbarMethods> & Field<C, "snapshots", SnapshotsMethods> & Estimated<C> & (C extends {
+    plugins: infer P extends readonly unknown[];
+} ? PluginMethods<P> : {});
+/**
+ * The item type a config is written for: the element type of its `items`, else
+ * the parameter of its template. `VListConfig<infer T>` would do neither
+ * reliably — a config with no `items` inferred `any`.
+ */
+export type ConfigItem<C> = C extends {
+    items: readonly (infer T extends VListItem)[];
+} ? T : C extends {
+    item: {
+        template: (item: infer T extends VListItem, ...rest: never[]) => unknown;
+    };
+} ? T : VListItem;
+/**
+ * {@link VListConfig} with everything but `items` blocked as an inference site,
+ * so `items` decides the item type and every callback is *checked* against it.
+ *
+ * Blocking the template alone was not enough: a grouping callback annotated for
+ * a supertype (`entity?: Entity` on a list of `Row`) is a second candidate, and
+ * it widened the whole list to `Entity` — `getItemAt()` lost `category`, and
+ * `setItems()` accepted an item without it. A callback for a supertype is still
+ * accepted, as it should be: it safely takes every `Row`.
+ */
+type CheckedConfig<T extends VListItem> = VListConfig<NoInfer<T>>;
 /**
  * Create a vlist instance from a high-level {@link VListConfig}, resolving its
  * feature fields into plugins via {@link resolvePlugins}. This is the single
  * entry point every framework adapter delegates to.
+ *
+ * The item type comes from `items` when present, otherwise the template, and
+ * the list's methods from the config's feature fields ({@link ConfigMethods}).
+ * Do not pass a type argument — `createVListFromConfig<Row>` does not compile
+ * (TypeScript requires both parameters), so the partial-argument trap
+ * `createVList<Row>` falls into stays closed.
+ *
+ * `groups.getGroupForIndex` is typed with that item: an inline callback
+ * receives `item?: T`, not `any`, and a callback written for a different
+ * item type is a type error, including when `groups` is optional on the
+ * input type.
  */
-export declare function createVListFromConfig<T extends VListItem = VListItem>(config: VListConfig<T> & {
+export declare function createVListFromConfig<T extends VListItem, const C extends CheckedConfig<T> & {
+    container: HTMLElement | string;
+    items: readonly T[];
+}>(config: {
+    items: readonly T[];
+} & CheckedConfig<T> & C): VList<T> & ConfigMethods<T, C>;
+export declare function createVListFromConfig<T extends VListItem, const C extends VListConfig<T> & {
     container: HTMLElement | string;
-}): VList<T>;
+}>(config: VListConfig<T> & C): VList<T> & ConfigMethods<T, C>;
+export {};
 //# sourceMappingURL=config.d.ts.map