vlist 3.0.0-next.3 → 3.0.0-next.5

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.0.0-next.3** (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.5** (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)
@@ -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 tiny adapters for Vue, Svelte, Solid, React
-- **9.5 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
@@ -178,29 +178,29 @@ Removed mode/runway options throw a migration error before creating DOM. `vlist/
 
 | Entry / export | Minified | Gzipped |
 |---|---:|---:|
-| **Base (`vlist`)** | 25.7 KB | 9.5 KB |
-| `vlist/synthetic` | 31.7 KB | 11.7 KB |
-| `vlist/native` (alias) | 25.7 KB | 9.5 KB |
-| `a11y()` | 29.0 KB | 10.7 KB |
-| `selection()` | 35.1 KB | 12.3 KB |
-| `data()` | 39.4 KB | 14.3 KB |
-| `scrollbar()` | 33.9 KB | 12.4 KB |
-| `sortable()` | 37.5 KB | 13.0 KB |
-| `groups()` | 41.5 KB | 14.7 KB |
-| `page()` | 28.2 KB | 10.4 KB |
-| `snapshots()` | 29.0 KB | 10.6 KB |
-| `transition()` | 32.4 KB | 11.5 KB |
-| `autosize()` | 28.7 KB | 10.5 KB |
-| `grid()` | 32.5 KB | 11.9 KB |
-| `table()` | 44.1 KB | 15.4 KB |
-| `masonry()` | 36.9 KB | 13.6 KB |
-| `tree()` | 41.0 KB | 14.5 KB |
-| `search()` | 34.7 KB | 12.6 KB |
-| `carousel()` | 38.5 KB | 13.9 KB |
-| `vlist/synthetic` + `carousel()` | 44.4 KB | 16.2 KB |
-| `vlist/synthetic` + `sortable()` | 43.5 KB | 15.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. The base is **9,914 bytes gzipped**, below the 9.9 KB target. `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 **11,960 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
 
@@ -439,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
 

package/README.md

@@ -2,7 +2,7 @@
 
 The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins.
 
-**v3.0.0-next.3** (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.5** (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)
@@ -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, tiny adapters for Vue, Svelte, Solid, React
-- **9.4 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
 
@@ -124,29 +124,29 @@ Removed mode/runway options throw a migration error before creating DOM. `vlist/
 
 | Entry / export | Minified | Gzipped |
 |---|---:|---:|
-| **Base (`vlist`)** | 25.7 KB | 9.4 KB |
-| `vlist/synthetic` | 31.7 KB | 11.7 KB |
-| `vlist/native` (alias) | 25.7 KB | 9.5 KB |
-| `a11y()` | 29.0 KB | 10.7 KB |
-| `selection()` | 35.1 KB | 12.3 KB |
-| `data()` | 39.4 KB | 14.3 KB |
-| `scrollbar()` | 33.9 KB | 12.3 KB |
-| `sortable()` | 37.4 KB | 12.9 KB |
-| `groups()` | 41.4 KB | 14.7 KB |
-| `page()` | 28.2 KB | 10.3 KB |
-| `snapshots()` | 29.0 KB | 10.6 KB |
-| `transition()` | 32.4 KB | 11.4 KB |
-| `autosize()` | 28.8 KB | 10.5 KB |
-| `grid()` | 32.6 KB | 11.8 KB |
-| `table()` | 44.2 KB | 15.3 KB |
-| `masonry()` | 37.0 KB | 13.5 KB |
-| `tree()` | 41.0 KB | 14.5 KB |
-| `search()` | 34.7 KB | 12.6 KB |
-| `carousel()` | 38.5 KB | 13.9 KB |
-| `vlist/synthetic` + `carousel()` | 44.4 KB | 16.1 KB |
-| `vlist/synthetic` + `sortable()` | 43.4 KB | 15.2 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,914 bytes gzipped**, below the 9.9 KB target. `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 **11,960 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

@@ -52,7 +52,7 @@ export interface VListConfig<T extends VListItem = VListItem> extends Omit<Creat
     /** Masonry layout options — applied when `layout: "masonry"`. */
     masonry?: MasonryPluginConfig;
     /** Sticky group headers. */
-    groups?: GroupsConfig;
+    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
@@ -87,8 +87,11 @@ 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
@@ -138,7 +141,7 @@ export type ConfigMethods<T extends VListItem, C extends VListConfig<T>> = Field
     layout: "grid";
 } ? GridMethods : {}) & (C extends {
     layout: "masonry";
-} ? MasonryMethods : {}) & Field<C, "groups", GroupsMethods> & Field<C, "selection", SelectionMethods<T>> & Field<C, "scrollbar", ScrollbarMethods> & Field<C, "snapshots", SnapshotsMethods> & Estimated<C> & (C extends {
+} ? 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> : {});
 /**
@@ -153,19 +156,41 @@ export type ConfigItem<C> = C extends {
         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.
  *
- * One type parameter, the config itself: the item type comes from its `items`
- * or `template`, and the list's methods from its feature fields
- * ({@link ConfigMethods}). Do not pass a type argument — `createVListFromConfig<Row>`
- * would name a config type, not an item type, and fail to compile; the same
- * trap `createVList<Row>` falls into is closed here by having no second slot.
+ * 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<const C extends VListConfig<any> & {
+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;
-}>(config: C): VList<ConfigItem<C>> & ConfigMethods<ConfigItem<C>, C>;
+}>(config: VListConfig<T> & C): VList<T> & ConfigMethods<T, C>;
 export {};
 //# sourceMappingURL=config.d.ts.map