vlist 2.7.2 → 2.8.1

package/README.github.md

@@ -1,8 +1,8 @@
 # vlist
 
-The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins — in 9.7 KB.
+The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins — in 9.9 KB.
 
-**v2.7.2** — [Changelog](./CHANGELOG.md) · Tree keeps the bounded runway for large trees; the scale() deprecation link works; bounded-mode touch limitation documented.
+**v2.8.1** — [Changelog](./CHANGELOG.md) · deprecation notices corrected for the revised 3.0 shape (native stays the default, synthetic input stays opt-in, the scrollbar strings are not deprecated); carousel slots follow container resizes; prerelease-aware publish workflow.
 
 [![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)
@@ -45,6 +45,22 @@ npm install vlist              # vanilla JS
 npm install vlist vlist-vue    # or vlist-svelte / vlist-solidjs / vlist-react
 ```
 
+With vlist 2.8 and an adapter that forwards the `factory` option, opt into synthetic input explicitly:
+
+```ts
+import { useVList } from "vlist-react";
+import { createVList } from "vlist/synthetic";
+
+useVList({
+  factory: createVList,
+  scroll: { mode: "synthetic" },
+  items,
+  item: { height: 48, template: item => String(item.id) },
+});
+```
+
+The same factory option is available to the other adapters. `vlist/config` keeps the synthetic driver out of its default bundle; importing the factory opts in. The factory is structural configuration: changing it requires recreating the list.
+
 ## Quick Start
 
 ```typescript
@@ -121,6 +137,19 @@ Known limitations:
 
 Measurement corrections from autosize preserve ongoing motion. Synthetic input adds **2.6 KB gzipped** over the base entry (**12.5 KB** total before plugins); ordinary `vlist` imports exclude this driver. See [RFC-014](https://github.com/floor/vlist/discussions/127).
 
+## Deprecated in 2.8, removed in 3.0
+
+These notices prepare the 3.0 migration; 2.x behavior and defaults stay unchanged. Native scrolling stays the default in 3.0, and synthetic input stays the opt-in `vlist/synthetic` entry. Bounded mode remains supported in 2.x, including carousel and sortable; it emits no deprecation warning.
+
+| Option or API | In 3.0 | Since |
+|---|---|---|
+| `scroll.mode` | Removed. `vlist` is native by default; for lists beyond the browser's element size limit, import `createVList` from `vlist/synthetic` instead of using bounded mode. | 2.8 |
+| `scroll.runway` | Removed with bounded mode. | 2.8 |
+| `PluginContext.setScrollFns`, `disableDefaultScroll` | Removed; use `setScrollSource`. | 2.8 |
+| `scale()` | Removed; use `vlist/synthetic` for huge lists. | 2.4 |
+
+`scroll.scrollbar: "native"` and `"none"` are not deprecated: they stay available on the native default in 3.0. Only explicit `scale()` calls warn, once per process, and 3.0's `vlist/config` no longer installs the scale compatibility stub. Release 2.8.0 described native scrolling and the scrollbar strings as moving to a `vlist/native` entry in 3.0; that plan was revised. See the [v2 to v3 migration guide](https://vlist.io/docs/migration-v3).
+
 ## Plugins
 
 | Plugin | Size | Description |
@@ -135,12 +164,12 @@ Measurement corrections from autosize preserve ongoing motion. Synthetic input a
 | `scrollbar()` | +2.0 KB | Custom scrollbar UI |
 | `grid()` | +2.5 KB | 2D grid layout |
 | `masonry()` | +4.1 KB | Pinterest-style masonry with lane-aware keyboard nav |
-| `carousel()` | +3.5 KB | Paged horizontal carousel with snap and keyboard nav |
+| `carousel()` | +3.6 KB | Paged horizontal carousel with snap and keyboard nav |
 | `table()` | +5.8 KB | Data table with columns, resize, sort |
 | `tree()` | +5.0 KB | Collapsible tree with async loading and indent guides |
 | `page()` | +0.8 KB | Window-level scrolling |
 | `sortable()` | +3.0 KB | Drag-and-drop reordering with auto-scroll |
-| `snapshots()` | +1.1 KB | Scroll position save/restore |
+| `snapshots()` | +1.2 KB | Scroll position save/restore |
 | `transition()` | +2.0 KB | FLIP-based enter/exit animations for insert & remove |
 
 ## Examples
@@ -355,7 +384,7 @@ groups({ getGroupForIndex, header: { height, template }, sticky?: true })
 selection({ mode: 'single' | 'multiple', initial?: [...ids] })
 data({ adapter: { read }, loading?: { cancelThreshold? } })
 table({ columns, rowHeight, headerHeight?, resizable? })
-autosize()                        // auto-measure items (requires estimatedHeight)
+autosize()                        // auto-measure items (requires estimatedHeight); list.remeasure(index?) after late content
 scrollbar({ autoHide?, autoHideDelay?, minThumbSize? })
 transition({ duration?: 200, insert?: timing, remove?: timing })
 sortable({ handle?: '.drag-handle' })  // drag-and-drop reordering
@@ -363,6 +392,15 @@ page()                            // no config — uses document scroll
 snapshots({ autoSave: 'key' })    // automatic sessionStorage save/restore
 ```
 
+### Autosize
+
+With `autosize()` and `item.estimatedHeight` (or `estimatedWidth` for horizontal lists), call `remeasure(i)` after content changes size without a `load` or `error` event, such as expanding text or changing a font. Call `remeasure()` to discard every cached measurement: visible items are measured again, and offscreen items use estimates until they render. Unknown or unmeasured indices are a no-op.
+
+```javascript
+list.remeasure(12); // Re-measure one item after its content changes.
+list.remeasure();   // Invalidate all sizes and measure items as they render.
+```
+
 Full configuration reference → **[vlist.io](https://vlist.io)**
 
 ## Base Configuration

package/README.md

@@ -1,8 +1,8 @@
 # vlist
 
-The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins — in 9.7 KB.
+The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins — in 9.9 KB.
 
-**v2.7.2** — [Changelog](https://github.com/floor/vlist/blob/main/CHANGELOG.md) · Tree keeps the bounded runway for large trees; the scale() deprecation link works; bounded-mode touch limitation documented.
+**v2.8.1** — [Changelog](https://github.com/floor/vlist/blob/main/CHANGELOG.md) · deprecation notices corrected for the revised 3.0 shape (native stays the default, synthetic input stays opt-in, the scrollbar strings are not deprecated); carousel slots follow container resizes; prerelease-aware publish workflow.
 
 [![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)
@@ -83,6 +83,19 @@ Known limitations:
 
 Measurement corrections from autosize preserve ongoing motion. Synthetic input adds **2.6 KB gzipped** over the base entry (**12.5 KB** total before plugins); ordinary `vlist` imports exclude this driver. See [RFC-014](https://github.com/floor/vlist/discussions/127).
 
+## Deprecated in 2.8, removed in 3.0
+
+These notices prepare the 3.0 migration; 2.x behavior and defaults stay unchanged. Native scrolling stays the default in 3.0, and synthetic input stays the opt-in `vlist/synthetic` entry. Bounded mode remains supported in 2.x, including carousel and sortable; it emits no deprecation warning.
+
+| Option or API | In 3.0 | Since |
+|---|---|---|
+| `scroll.mode` | Removed. `vlist` is native by default; for lists beyond the browser's element size limit, import `createVList` from `vlist/synthetic` instead of using bounded mode. | 2.8 |
+| `scroll.runway` | Removed with bounded mode. | 2.8 |
+| `PluginContext.setScrollFns`, `disableDefaultScroll` | Removed; use `setScrollSource`. | 2.8 |
+| `scale()` | Removed; use `vlist/synthetic` for huge lists. | 2.4 |
+
+`scroll.scrollbar: "native"` and `"none"` are not deprecated: they stay available on the native default in 3.0. Only explicit `scale()` calls warn, once per process, and 3.0's `vlist/config` no longer installs the scale compatibility stub. Release 2.8.0 described native scrolling and the scrollbar strings as moving to a `vlist/native` entry in 3.0; that plan was revised. See the [v2 to v3 migration guide](https://vlist.io/docs/migration-v3).
+
 ## Plugins
 
 | Plugin | Size | Description |
@@ -97,12 +110,12 @@ Measurement corrections from autosize preserve ongoing motion. Synthetic input a
 | `scrollbar()` | +2.0 KB | Custom scrollbar UI |
 | `grid()` | +2.5 KB | 2D grid layout |
 | `masonry()` | +4.1 KB | Pinterest-style masonry with lane-aware keyboard nav |
-| `carousel()` | +3.5 KB | Paged horizontal carousel with snap and keyboard nav |
+| `carousel()` | +3.6 KB | Paged horizontal carousel with snap and keyboard nav |
 | `table()` | +5.8 KB | Data table with columns, resize, sort |
 | `tree()` | +5.0 KB | Collapsible tree with async loading and indent guides |
 | `page()` | +0.8 KB | Window-level scrolling |
 | `sortable()` | +3.0 KB | Drag-and-drop reordering with auto-scroll |
-| `snapshots()` | +1.1 KB | Scroll position save/restore |
+| `snapshots()` | +1.2 KB | Scroll position save/restore |
 | `transition()` | +2.0 KB | FLIP-based enter/exit animations for insert & remove |
 
 ## Framework Adapters
@@ -114,6 +127,22 @@ Measurement corrections from autosize preserve ongoing motion. Synthetic input a
 | SolidJS | [`vlist-solidjs`](https://github.com/floor/vlist-solidjs) | 0.5 KB |
 | React | [`vlist-react`](https://github.com/floor/vlist-react) | 0.6 KB |
 
+With vlist 2.8 and an adapter that forwards the `factory` option, opt into synthetic input explicitly:
+
+```ts
+import { useVList } from "vlist-react";
+import { createVList } from "vlist/synthetic";
+
+useVList({
+  factory: createVList,
+  scroll: { mode: "synthetic" },
+  items,
+  item: { height: 48, template: item => String(item.id) },
+});
+```
+
+The same factory option is available to the other adapters. `vlist/config` keeps the synthetic driver out of its default bundle; importing the factory opts in. The factory is structural configuration: changing it requires recreating the list.
+
 ## Docs & Examples
 
 **18 interactive examples, full API reference, tutorials, and live benchmarks → [vlist.io](https://vlist.io)**

package/dist/config.d.ts

@@ -15,20 +15,29 @@
  * lean and tree-shakeable; only consumers that opt into the batteries-included
  * config (the adapters) pull in this module and, with it, every plugin it wires.
  */
-import type { VListItem, GroupsConfig, VListAdapter } from "./types";
+import type { VListItem, GroupsConfig, VListAdapter, ScrollConfig } from "./types";
+import { createVList } from "./core/create";
 import type { CreateVListConfig, VList, VListPlugin } from "./core/types";
 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 { ScrollbarPluginConfig } from "./plugins/scrollbar";
+/** List creation function injected by an adapter consumer. */
+export type VListFactory<T extends VListItem = VListItem> = typeof createVList<T>;
 /**
  * High-level, declarative vlist configuration accepted by the framework
  * adapters. It is the core `CreateVListConfig` (minus `container`, which the
  * adapter owns via a ref/node) plus the convenience "feature fields" that are
  * translated into plugins by {@link resolvePlugins}.
  */
-export interface VListConfig<T extends VListItem = VListItem> extends Omit<CreateVListConfig<T>, "container"> {
+export interface VListConfig<T extends VListItem = VListItem> extends Omit<CreateVListConfig<T>, "container" | "scroll"> {
+    /** Synthetic mode requires a factory imported from vlist/synthetic. */
+    scroll?: Omit<ScrollConfig, "mode"> & {
+        mode?: ScrollConfig["mode"] | "synthetic";
+    };
+    /** List factory; defaults to core createVList. Fixed for this instance. */
+    factory?: VListFactory<T>;
     /** Layout mode. Wires the grid or masonry plugin from `grid`/`masonry`. */
     layout?: "grid" | "masonry";
     /** Grid layout options — applied when `layout: "grid"`. */