vlist 3.1.8 → 3.3.0

package/README.github.md

@@ -2,7 +2,7 @@
 
 The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins.
 
-**v3.1.8** — `scroll.mode` on the one `vlist` entry: the default, `"auto"`, scrolls natively and hands a list past the browser's size limit to synthetic input, which draws its own scrollbar. Vue, Svelte, Solid and React entries in the package itself (`vlist/vue`, `vlist/svelte`, `vlist/solid`, `vlist/react`), feature-first and tree-shaken like the vanilla builder; the separate adapter packages are deprecated. See the [changelog](https://github.com/floor/vlist/blob/main/CHANGELOG.md).
+**v3.3.0** — `scroll.mode` on the one `vlist` entry: the default, `"auto"`, scrolls natively and hands a list past the browser's size limit to synthetic input, which draws its own scrollbar. Vue, Svelte, Solid and React entries in the package itself (`vlist/vue`, `vlist/svelte`, `vlist/solid`, `vlist/react`), feature-first and tree-shaken like the vanilla builder; the separate adapter packages are deprecated. See the [changelog](https://github.com/floor/vlist/blob/main/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)
@@ -11,7 +11,7 @@ The virtual list library for every framework. Ultra efficient, batteries-include
 
 - **Accessible** — `a11y()` or a selection mode adds WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
 - **Zero dependencies** — framework-agnostic core, with Vue, Svelte, Solid and React entries in the same package
-- **10.3 KB gzipped** — composable plugins with perfect tree-shaking (Bundlephobia's badge measures the root entry with every plugin at once)
+- **10.5 KB gzipped** — composable plugins with perfect tree-shaking (Bundlephobia's badge measures the root entry with every plugin at once)
 - **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
@@ -264,36 +264,36 @@ The touch-only `.vlist-item--touch-sort` class suppresses selection and callouts
 
 | Entry / export | Minified | Gzipped |
 |---|---:|---:|
-| **Base (`vlist`)** | 27.3 KB | 10.3 KB |
-| `vlist/synthetic` (deprecated) | 34.2 KB | 12.9 KB |
-| `vlist/native` (alias) | 27.3 KB | 10.3 KB |
-| `a11y()` | 32.4 KB | 12.2 KB |
-| `selection()` | 37.8 KB | 13.6 KB |
-| `data()` | 41.0 KB | 15.1 KB |
-| `scrollbar()` | 35.5 KB | 13.2 KB |
-| `sortable()` | 39.2 KB | 13.9 KB |
-| `groups()` | 43.5 KB | 15.7 KB |
-| `page()` | 29.9 KB | 11.2 KB |
-| `snapshots()` | 30.6 KB | 11.4 KB |
-| `transition()` | 34.1 KB | 12.3 KB |
-| `autosize()` | 31.7 KB | 11.9 KB |
-| `grid()` | 34.7 KB | 12.9 KB |
-| `table()` | 46.4 KB | 16.4 KB |
-| `masonry()` | 39.4 KB | 14.7 KB |
-| `tree()` | 43.1 KB | 15.6 KB |
-| `search()` | 36.9 KB | 13.6 KB |
-| `carousel()` | 43.2 KB | 15.8 KB |
-| `vlist/synthetic` + `carousel()` | 49.3 KB | 18.1 KB |
-| `vlist/synthetic` + `sortable()` | 46.1 KB | 16.5 KB |
-| `vlist/vue` `useVList` | 27.7 KB | 10.5 KB |
-| `vlist/svelte` `vlist` | 27.5 KB | 10.4 KB |
-| `vlist/solid` `createVList` | 27.6 KB | 10.4 KB |
-| `vlist/react` `useVList` | 27.8 KB | 10.5 KB |
-| `vlist/react` + `grid()` | 35.2 KB | 13.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; framework rows add the entry, with the framework itself external. The base is **10,539 bytes gzipped**, within the 10.3 KB budget (10,547 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 **13,192 bytes** before plugins; with `scroll.mode`, a `vlist` list downloads the driver and its scrollbar as `synthetic-driver.js` (6.2 KB gzipped) only when it goes synthetic. The alias row measures the same source factory; the distributed alias re-exports it without duplicating the implementation.
-
-Bundlephobia's badge measures the package's root entry, which re-exports every plugin, minified and gzipped as one bundle. With a tree-shaking bundler, an app that imports named exports from `vlist` bundles the base (**10.3 KB gzipped**) and the features it uses; the table's rows are each a combined size, not amounts to add up.
+| **Base (`vlist`)** | 27.9 KB | 10.5 KB |
+| `vlist/synthetic` (deprecated) | 34.8 KB | 13.1 KB |
+| `vlist/native` (alias) | 27.9 KB | 10.5 KB |
+| `a11y()` | 32.9 KB | 12.4 KB |
+| `selection()` | 38.4 KB | 13.8 KB |
+| `data()` | 41.5 KB | 15.3 KB |
+| `scrollbar()` | 36.1 KB | 13.4 KB |
+| `sortable()` | 39.8 KB | 14.1 KB |
+| `groups()` | 44.2 KB | 15.9 KB |
+| `page()` | 30.4 KB | 11.4 KB |
+| `snapshots()` | 31.2 KB | 11.6 KB |
+| `transition()` | 34.6 KB | 12.5 KB |
+| `autosize()` | 32.3 KB | 12.1 KB |
+| `grid()` | 35.4 KB | 13.1 KB |
+| `table()` | 47.0 KB | 16.6 KB |
+| `masonry()` | 40.1 KB | 14.9 KB |
+| `tree()` | 43.7 KB | 15.8 KB |
+| `search()` | 37.5 KB | 13.8 KB |
+| `carousel()` | 43.9 KB | 16.0 KB |
+| `vlist/synthetic` + `carousel()` | 50.0 KB | 18.3 KB |
+| `vlist/synthetic` + `sortable()` | 46.7 KB | 16.7 KB |
+| `vlist/vue` `useVList` | 28.3 KB | 10.7 KB |
+| `vlist/svelte` `vlist` | 28.1 KB | 10.6 KB |
+| `vlist/solid` `createVList` | 28.2 KB | 10.6 KB |
+| `vlist/react` `useVList` | 28.3 KB | 10.7 KB |
+| `vlist/react` + `grid()` | 35.8 KB | 13.3 KB |
+
+Sizes are tree-shaken totals from `bun run size`, not additive plugin costs. Plugin rows include the native default factory plus that plugin; framework rows add the entry, with the framework itself external. The base is **10,735 bytes gzipped**, within the 10.59 KB budget (10,844 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 **13,402 bytes** before plugins; with `scroll.mode`, a `vlist` list downloads the driver and its scrollbar as `synthetic-driver.js` (6.2 KB gzipped) only when it goes synthetic. The alias row measures the same source factory; the distributed alias re-exports it without duplicating the implementation.
+
+Bundlephobia's badge measures the package's root entry, which re-exports every plugin, minified and gzipped as one bundle. With a tree-shaking bundler, an app that imports named exports from `vlist` bundles the base (**10.5 KB gzipped**) and the features it uses; the table's rows are each a combined size, not amounts to add up.
 
 ## Examples
 
@@ -336,6 +336,17 @@ cell, which sorts the column when it is sortable: give the control `tabindex`, o
 Enter and Space emit `column:sort` on a sortable header and never `column:click`, so an action a
 keyboard user must reach should be a `button` supplied in the header label.
 
+Table rows use configured heights and are not automatically measured, so
+`autosize()` cannot be combined with `table()`;
+the `vlist/config` route wires `autosize()` when only an estimate is given (`item.estimatedHeight`)
+and throws at creation. Give the table a fixed `rowHeight` and the config a fixed `item.height` instead.
+
+`estimatedRowHeight` is deprecated in 3.3.0 and will be removed in 4.0 (#345).
+It remains accepted but does not size or measure rows; non-production builds warn
+once per `table()` call. Use a numeric `rowHeight` for fixed rows or a `rowHeight`
+function for variable row sizes. For heights that change after creation, the
+`remeasureItem(index)` API in 3.3.0 works with a `rowHeight` function (#347).
+
 ### Grid Layout
 
 ```typescript
@@ -528,6 +539,7 @@ const list = createVList(config, [plugin1(), plugin2()])
 | `list.removeItems(ids)` | Batch remove (simultaneous animations) |
 | `list.getItemAt(index)` | Get item at index |
 | `list.getIndexById(id)` | Get index by item ID |
+| `list.remeasureItem(index)` | Ask the size source to re-read one item after its content changed; returns `false` when the size model cannot address it |
 
 ### Navigation
 
@@ -608,6 +620,8 @@ list.remeasure(12); // Re-measure one item after its content changes.
 list.remeasure();   // Invalidate all sizes and measure items as they render.
 ```
 
+A measured item size cannot be combined with `masonry()`: masonry places items from the size cache it is handed at layout time, so an `autosize()` measurement never reaches the placements. The `vlist/config` route wires `autosize()` when only an estimate is given (`item.estimatedHeight`) and throws at creation; give the items a fixed `item.height` instead. The same holds for `carousel()`, whose slide steps are built from the size read at setup.
+
 Full configuration reference → **[vlist.io](https://vlist.io)**
 
 ## Base Configuration

package/README.md

@@ -2,7 +2,7 @@
 
 The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins.
 
-**v3.1.8** — `scroll.mode` on the one `vlist` entry: the default, `"auto"`, scrolls natively and hands a list past the browser's size limit to synthetic input, which draws its own scrollbar. Vue, Svelte, Solid and React entries in the package itself (`vlist/vue`, `vlist/svelte`, `vlist/solid`, `vlist/react`), feature-first and tree-shaken like the vanilla builder; the separate adapter packages are deprecated. See the [changelog](https://github.com/floor/vlist/blob/main/CHANGELOG.md).
+**v3.3.0** — `scroll.mode` on the one `vlist` entry: the default, `"auto"`, scrolls natively and hands a list past the browser's size limit to synthetic input, which draws its own scrollbar. Vue, Svelte, Solid and React entries in the package itself (`vlist/vue`, `vlist/svelte`, `vlist/solid`, `vlist/react`), feature-first and tree-shaken like the vanilla builder; the separate adapter packages are deprecated. See the [changelog](https://github.com/floor/vlist/blob/main/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)
@@ -11,7 +11,7 @@ The virtual list library for every framework. Ultra efficient, batteries-include
 
 - **Accessible** — `a11y()` or a selection mode adds WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
 - **Zero dependencies** — framework-agnostic core, with Vue, Svelte, Solid and React entries in the same package
-- **10.3 KB gzipped** — composable plugins with perfect tree-shaking (Bundlephobia's badge measures the root entry with every plugin at once)
+- **10.5 KB gzipped** — composable plugins with perfect tree-shaking (Bundlephobia's badge measures the root entry with every plugin at once)
 - **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
 
@@ -131,36 +131,43 @@ The touch-only `.vlist-item--touch-sort` class suppresses selection and callouts
 
 | Entry / export | Minified | Gzipped |
 |---|---:|---:|
-| **Base (`vlist`)** | 27.3 KB | 10.3 KB |
-| `vlist/synthetic` (deprecated) | 34.2 KB | 12.9 KB |
-| `vlist/native` (alias) | 27.3 KB | 10.3 KB |
-| `a11y()` | 32.4 KB | 12.2 KB |
-| `selection()` | 37.8 KB | 13.6 KB |
-| `data()` | 41.0 KB | 15.1 KB |
-| `scrollbar()` | 35.5 KB | 13.2 KB |
-| `sortable()` | 39.2 KB | 13.9 KB |
-| `groups()` | 43.5 KB | 15.7 KB |
-| `page()` | 29.9 KB | 11.2 KB |
-| `snapshots()` | 30.6 KB | 11.4 KB |
-| `transition()` | 34.1 KB | 12.3 KB |
-| `autosize()` | 31.7 KB | 11.9 KB |
-| `grid()` | 34.7 KB | 12.9 KB |
-| `table()` | 46.4 KB | 16.4 KB |
-| `masonry()` | 39.4 KB | 14.7 KB |
-| `tree()` | 43.1 KB | 15.6 KB |
-| `search()` | 36.9 KB | 13.6 KB |
-| `carousel()` | 43.2 KB | 15.8 KB |
-| `vlist/synthetic` + `carousel()` | 49.3 KB | 18.1 KB |
-| `vlist/synthetic` + `sortable()` | 46.1 KB | 16.5 KB |
-| `vlist/vue` `useVList` | 27.7 KB | 10.5 KB |
-| `vlist/svelte` `vlist` | 27.5 KB | 10.4 KB |
-| `vlist/solid` `createVList` | 27.6 KB | 10.4 KB |
-| `vlist/react` `useVList` | 27.8 KB | 10.5 KB |
-| `vlist/react` + `grid()` | 35.2 KB | 13.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; framework rows add the entry, with the framework itself external. The base is **10,539 bytes gzipped**, within the 10.3 KB budget (10,547 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 **13,192 bytes** before plugins; with `scroll.mode`, a `vlist` list downloads the driver and its scrollbar as `synthetic-driver.js` (6.2 KB gzipped) only when it goes synthetic. The alias row measures the same source factory; the distributed alias re-exports it without duplicating the implementation.
-
-Bundlephobia's badge measures the package's root entry, which re-exports every plugin, minified and gzipped as one bundle. With a tree-shaking bundler, an app that imports named exports from `vlist` bundles the base (**10.3 KB gzipped**) and the features it uses; the table's rows are each a combined size, not amounts to add up.
+| **Base (`vlist`)** | 27.9 KB | 10.5 KB |
+| `vlist/synthetic` (deprecated) | 34.8 KB | 13.1 KB |
+| `vlist/native` (alias) | 27.9 KB | 10.5 KB |
+| `a11y()` | 32.9 KB | 12.4 KB |
+| `selection()` | 38.4 KB | 13.8 KB |
+| `data()` | 41.5 KB | 15.3 KB |
+| `scrollbar()` | 36.1 KB | 13.4 KB |
+| `sortable()` | 39.8 KB | 14.1 KB |
+| `groups()` | 44.2 KB | 15.9 KB |
+| `page()` | 30.4 KB | 11.4 KB |
+| `snapshots()` | 31.2 KB | 11.6 KB |
+| `transition()` | 34.6 KB | 12.5 KB |
+| `autosize()` | 32.3 KB | 12.1 KB |
+| `grid()` | 35.4 KB | 13.1 KB |
+| `table()` | 47.0 KB | 16.6 KB |
+| `masonry()` | 40.1 KB | 14.9 KB |
+| `tree()` | 43.7 KB | 15.8 KB |
+| `search()` | 37.5 KB | 13.8 KB |
+| `carousel()` | 43.9 KB | 16.0 KB |
+| `vlist/synthetic` + `carousel()` | 50.0 KB | 18.3 KB |
+| `vlist/synthetic` + `sortable()` | 46.7 KB | 16.7 KB |
+| `vlist/vue` `useVList` | 28.3 KB | 10.7 KB |
+| `vlist/svelte` `vlist` | 28.1 KB | 10.6 KB |
+| `vlist/solid` `createVList` | 28.2 KB | 10.6 KB |
+| `vlist/react` `useVList` | 28.3 KB | 10.7 KB |
+| `vlist/react` + `grid()` | 35.8 KB | 13.3 KB |
+
+Sizes are tree-shaken totals from `bun run size`, not additive plugin costs. Plugin rows include the native default factory plus that plugin; framework rows add the entry, with the framework itself external. The base is **10,735 bytes gzipped**, within the 10.59 KB budget (10,844 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 **13,402 bytes** before plugins; with `scroll.mode`, a `vlist` list downloads the driver and its scrollbar as `synthetic-driver.js` (6.2 KB gzipped) only when it goes synthetic. The alias row measures the same source factory; the distributed alias re-exports it without duplicating the implementation.
+
+Bundlephobia's badge measures the package's root entry, which re-exports every plugin, minified and gzipped as one bundle. With a tree-shaking bundler, an app that imports named exports from `vlist` bundles the base (**10.5 KB gzipped**) and the features it uses; the table's rows are each a combined size, not amounts to add up.
+
+`table()`'s `estimatedRowHeight` is deprecated in 3.3.0 and will be removed in 4.0
+(#345). It remains accepted but does not size or measure rows; non-production
+builds warn once per `table()` call. Use `rowHeight` for fixed rows or a `rowHeight`
+function with the `remeasureItem(index)` API in 3.3.0 for heights that
+change after creation (#347). Table rows are not automatically measured and
+`table()` remains incompatible with `autosize()`.
 
 ## Frameworks
 

package/dist/config.js

@@ -1 +1 @@
-import{createVList as u,page as g,autosize as m,data as f,grid as C,masonry as y,groups as h,selection as T,a11y as r,scrollbar as l,snapshots as c}from"./index.js";function L(t){let e=[];if(typeof window<"u"&&t.scroll?.element===window)e.push(g());let i=t.item,n=t.orientation==="horizontal",a=n?i.width!=null:i.height!=null,p=n?i.estimatedWidth!=null:i.estimatedHeight!=null;if(!a&&p){if(t.layout==="grid")throw Error('[vlist] config: layout: "grid" needs a fixed item size. An estimate wires autosize(), which grid() cannot combine with: grid indexes its size cache by row, autosize measures items. Use item.height (item.width when horizontal).');e.push(m())}if(t.adapter)e.push(f({adapter:t.adapter,...t.loading&&{loading:t.loading}}));if(t.layout==="grid"){if(!t.grid)throw Error('[vlist] config: layout: "grid" requires a `grid` option, e.g. { columns: 3 }');e.push(C(t.grid))}if(t.layout==="masonry"){if(!t.masonry)throw Error('[vlist] config: layout: "masonry" requires a `masonry` option, e.g. { columns: 3 }');e.push(y(t.masonry))}if(t.groups)e.push(h(t.groups));if(t.selection)e.push(T(t.selection));if(t.a11y)e.push(t.a11y===!0?r():r(t.a11y));let s=t.scroll?.scrollbar??t.scrollbar;if(s===!0)e.push(l({}));else if(s&&typeof s==="object")e.push(l(s));if(t.snapshots)e.push(c());if(t.plugins&&t.plugins.length>0){let d=new Set(t.plugins.map((o)=>o.name));return[...e.filter((o)=>!d.has(o.name)),...t.plugins]}return e}function M(t){let{factory:e,...i}=t;return(e??u)(i,L(t))}export{M as createVListFromConfig,L as resolvePlugins};
+import{createVList as C,page as c,autosize as T,data as L,grid as V,masonry as x,groups as b,selection as w,a11y as p,scrollbar as u,snapshots as M}from"./index.js";function z(e){let t=[];if(typeof window<"u"&&e.scroll?.element===window)t.push(c());let s=e.item,o=e.orientation==="horizontal",g=o?s.width!=null:s.height!=null,f=o?s.estimatedWidth!=null:s.estimatedHeight!=null;if(!g&&f){if(e.layout==="grid")throw Error('[vlist] config: layout: "grid" needs a fixed item size. An estimate wires autosize(), which grid() cannot combine with: grid indexes its size cache by row, autosize measures items. Use item.height (item.width when horizontal).');let n=e.plugins??[];if(!n.some((i)=>i.name==="autosize")){let i=n.find((a)=>a.name!=="autosize"&&a.conflicts?.includes("autosize"))?.name,y=e.layout==="masonry"&&!n.some((a)=>a.name==="masonry"),l=i??(y?"masonry":void 0),d=o?"item.estimatedWidth":"item.estimatedHeight",m=o?"item.width":"item.height";if(l==="table"){if(o)throw Error("[vlist] table: cannot be used with horizontal orientation");throw Error("[vlist] config: item.estimatedHeight cannot be combined with table(): an estimated item size asks for measured rows, and table() gives every row a fixed height. Give the table a fixed rowHeight and drop the estimate. Use item.height.")}if(l==="masonry")throw Error(`[vlist] config: ${d} cannot be combined with `+(i==="masonry"?"masonry()":'layout: "masonry"')+`: an estimated item size asks for measured items, and masonry() lays every item out from the size cache it is handed. Give the items a fixed ${m} and drop the estimate.`);if(l==="carousel")throw Error(`[vlist] config: ${d} cannot be combined with carousel(): an estimated item size asks for measured slides, and carousel() builds its slide steps from the item size it is given. Give the slides a fixed ${m} and drop the estimate.`)}t.push(T())}if(e.adapter)t.push(L({adapter:e.adapter,...e.loading&&{loading:e.loading}}));if(e.layout==="grid"){if(!e.grid)throw Error('[vlist] config: layout: "grid" requires a `grid` option, e.g. { columns: 3 }');t.push(V(e.grid))}if(e.layout==="masonry"){if(!e.masonry)throw Error('[vlist] config: layout: "masonry" requires a `masonry` option, e.g. { columns: 3 }');t.push(x(e.masonry))}if(e.groups)t.push(b(e.groups));if(e.selection)t.push(w(e.selection));if(e.a11y)t.push(e.a11y===!0?p():p(e.a11y));let r=e.scroll?.scrollbar??e.scrollbar;if(r===!0)t.push(u({}));else if(r&&typeof r==="object")t.push(u(r));if(e.snapshots)t.push(M());if(e.plugins&&e.plugins.length>0){let n=new Set(e.plugins.map((i)=>i.name));return[...t.filter((i)=>!n.has(i.name)),...e.plugins]}return t}function I(e){let{factory:t,...s}=e;return(t??C)(s,z(e))}export{I as createVListFromConfig,z as resolvePlugins};

package/dist/core/types.d.ts

@@ -255,6 +255,19 @@ export interface VList<T extends VListItem = VListItem> {
     appendItems(items: T[]): void;
     prependItems(items: T[]): void;
     updateItem(id: string | number, updates: Partial<T>): void;
+    /**
+     * Ask whichever per-item size source owns the list to re-read item `index`,
+     * then make the list observe the result: content size, scroll anchor and any
+     * plugin state derived from offsets. The item data is not written, so a
+     * mounted row keeps its DOM — and a focused control inside it.
+     *
+     * @param index Data index, in `[0, total)`. Never throws for an index.
+     * @returns `true` when a size source was asked (the size may be unchanged),
+     *   `false` when the index is not an integer or out of range, the layout's
+     *   size model cannot address one data item (`grid()`, `masonry()`,
+     *   `carousel()`), or the item spec is fixed.
+     */
+    remeasureItem(index: number): boolean;
     insertItem(item: T, index?: number): void;
     removeItem(id: string | number): void;
     removeItems(ids: ReadonlyArray<string | number>): number;