vlist 1.8.3 → 1.9.0

package/README.github.md

@@ -1,19 +1,20 @@
 # vlist
 
-The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 11.0 KB.
+The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 11.2 KB.
 
-**v1.8.3** — [Changelog](./CHANGELOG.md)
+**v1.9.0** — [Changelog](./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)
 
-- **New: 11.0 KB base** — optimized from 11.2 KB, every feature bundle reduced
+- **New: `withTransition()`** — FLIP-based enter/exit animations for insert and remove, with batch `removeItems()` for simultaneous multi-item transitions
 - **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
-- **11.0 KB gzipped** — composable features with perfect tree-shaking
+- **11.2 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, sortable, scale** — all opt-in
+- **Grid, masonry, table, groups, async, selection, sortable, transition, scale** — all opt-in
 - **Vertical & horizontal** — single axis-neutral code path, every feature works in both orientations
 
 **18 interactive examples, docs & benchmarks → [vlist.io](https://vlist.io)**
@@ -94,19 +95,20 @@ const list = vlist({
 
 | Feature | Size | Description |
 |---------|------|-------------|
-| **Base** | 11.0 KB | Virtualization, ARIA, keyboard nav, gap, padding |
-| `withAsync()` | +4.5 KB | Lazy loading with velocity-aware fetching |
-| `withSelection()` | +3.0 KB | Single/multiple selection with 2D keyboard nav |
+| **Base** | 11.2 KB | Virtualization, ARIA, keyboard nav, gap, padding |
+| `withAsync()` | +4.6 KB | Lazy loading with velocity-aware fetching |
+| `withSelection()` | +2.7 KB | Single/multiple selection with 2D keyboard nav |
 | `withScale()` | +3.6 KB | 1M+ items via scroll compression |
-| `withGroups()` | +4.5 KB | Sticky/inline headers with async group discovery |
+| `withGroups()` | +4.7 KB | Sticky/inline headers with async group discovery |
 | `withAutoSize()` | +0.9 KB | Auto-measure items via ResizeObserver |
-| `withScrollbar()` | +1.9 KB | Custom scrollbar UI |
+| `withScrollbar()` | +1.8 KB | Custom scrollbar UI |
 | `withGrid()` | +4.1 KB | 2D grid layout |
-| `withMasonry()` | +3.5 KB | Pinterest-style masonry with lane-aware keyboard nav |
+| `withMasonry()` | +3.4 KB | Pinterest-style masonry with lane-aware keyboard nav |
 | `withTable()` | +5.8 KB | Data table with columns, resize, sort |
 | `withPage()` | +0.7 KB | Window-level scrolling |
 | `withSortable()` | +2.9 KB | Drag-and-drop reordering with auto-scroll |
 | `withSnapshots()` | +1.2 KB | Scroll position save/restore |
+| `withTransition()` | +2.1 KB | FLIP-based enter/exit animations for insert & remove |
 
 ## Examples
 
@@ -163,6 +165,30 @@ const gallery = vlist({
   .build()
 ```
 
+### Animated Insert & Remove
+
+```typescript
+import { vlist, withTransition, withSelection } from 'vlist'
+
+const list = vlist({
+  container: '#playlist',
+  items: tracks,
+  item: { height: 64, template: renderTrack },
+})
+  .use(withTransition({ duration: 200 }))
+  .use(withSelection({ mode: 'multiple' }))
+  .build()
+
+// Single item — collapses with fade-out, siblings slide up
+list.removeItem(trackId)
+
+// Batch — all items animate simultaneously
+list.removeItems(list.getSelected())
+
+// Insert — expands in, siblings slide down
+list.insertItem({ id: 42, title: 'New Track' }, 0)
+```
+
 ### Async Loading
 
 ```typescript
@@ -217,7 +243,9 @@ const list = vlist(config).use(...features).build()
 | `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.insertItem(item, index?)` | Insert at index (animated with `withTransition`) |
+| `list.removeItem(id)` | Remove by ID (animated with `withTransition`) |
+| `list.removeItems(ids)` | Batch remove (simultaneous animations) |
 | `list.getItemAt(index)` | Get item at index |
 | `list.getIndexById(id)` | Get index by item ID |
 | `list.reload()` | Re-fetch from adapter (async) |
@@ -282,6 +310,7 @@ withTable({ columns, rowHeight, headerHeight?, resizable? })
 withAutoSize()                        // auto-measure items (requires estimatedHeight)
 withScale()                           // auto-activates at 16.7M px
 withScrollbar({ autoHide?, autoHideDelay?, minThumbSize? })
+withTransition({ duration?: 200, insert?: timing, remove?: timing })
 withSortable({ handle?: '.drag-handle' })  // drag-and-drop reordering
 withPage()                            // no config — uses document scroll
 withSnapshots({ autoSave: 'key' })    // automatic sessionStorage save/restore

package/README.md

@@ -1,17 +1,18 @@
 # vlist
 
-The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 11.0 KB.
+The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 11.2 KB.
 
-**v1.8.2** — [Changelog](https://github.com/floor/vlist/blob/main/CHANGELOG.md)
+**v1.9.0** — [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)
 [![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)
 
-- **New: 11.0 KB base** — optimized from 11.2 KB, every feature bundle reduced
+- **New: `withTransition()`** — FLIP-based enter/exit animations for insert and remove
 - **Zero dependencies** — framework-agnostic core, tiny adapters for Vue, Svelte, Solid, React
 - **Accessible** — WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
-- **11.0 KB gzipped** — composable features with perfect tree-shaking
+- **11.2 KB gzipped** — composable features with perfect tree-shaking
 - **Constant memory** — ~0.1 MB overhead at any scale, from 10K to 1M+ items
 - **Vertical & horizontal** — single axis-neutral code path, every feature works in both orientations
 
@@ -56,19 +57,20 @@ const list = vlist({ container: '#app', items, item: { height: 200, template: re
 
 | Feature | Size | Description |
 |---------|------|-------------|
-| **Base** | 11.0 KB | Virtualization, ARIA, keyboard nav, gap, padding |
-| `withAsync()` | +4.5 KB | Lazy loading with velocity-aware fetching |
-| `withSelection()` | +3.0 KB | Single/multiple selection with 2D keyboard nav |
+| **Base** | 11.2 KB | Virtualization, ARIA, keyboard nav, gap, padding |
+| `withAsync()` | +4.6 KB | Lazy loading with velocity-aware fetching |
+| `withSelection()` | +2.7 KB | Single/multiple selection with 2D keyboard nav |
 | `withScale()` | +3.6 KB | 1M+ items via scroll compression |
-| `withGroups()` | +4.5 KB | Sticky/inline headers with async group discovery |
+| `withGroups()` | +4.7 KB | Sticky/inline headers with async group discovery |
 | `withAutoSize()` | +0.9 KB | Auto-measure items via ResizeObserver |
-| `withScrollbar()` | +1.9 KB | Custom scrollbar UI |
+| `withScrollbar()` | +1.8 KB | Custom scrollbar UI |
 | `withGrid()` | +4.1 KB | 2D grid layout |
-| `withMasonry()` | +3.5 KB | Pinterest-style masonry with lane-aware keyboard nav |
+| `withMasonry()` | +3.4 KB | Pinterest-style masonry with lane-aware keyboard nav |
 | `withTable()` | +5.8 KB | Data table with columns, resize, sort |
 | `withPage()` | +0.7 KB | Window-level scrolling |
 | `withSortable()` | +2.9 KB | Drag-and-drop reordering with auto-scroll |
 | `withSnapshots()` | +1.2 KB | Scroll position save/restore |
+| `withTransition()` | +2.1 KB | FLIP-based enter/exit animations for insert & remove |
 
 ## Framework Adapters
 

package/dist/builder/data.d.ts

@@ -42,6 +42,7 @@ export interface SimpleDataManager<T extends VListItem = VListItem> {
     setTotal: (total: number) => void;
     setItems: (items: T[], offset?: number, total?: number) => void;
     updateItem: (index: number, updates: Partial<T>) => boolean;
+    insertItem: (item: T, index: number) => void;
     removeItem: (id: string | number) => boolean;
     loadRange: (start: number, end: number) => Promise<void>;
     ensureRange: (start: number, end: number) => Promise<void>;

package/dist/builder/types.d.ts

@@ -481,7 +481,11 @@ export interface VList<T extends VListItem = VListItem> {
     appendItems: (items: T[]) => void;
     prependItems: (items: T[]) => void;
     updateItem: (id: string | number, updates: Partial<T>) => void;
+    insertItem: (item: T, index?: number) => void;
+    /** @deprecated Use `insertItem` instead. */
+    addItem: (item: T, index?: number) => void;
     removeItem: (id: string | number) => void;
+    removeItems: (ids: ReadonlyArray<string | number>) => number;
     getItemAt: (index: number) => T | undefined;
     getIndexById: (id: string | number) => number;
     reload: (options?: ReloadOptions) => Promise<void>;

package/dist/features/async/manager.d.ts

@@ -75,6 +75,8 @@ export interface DataManager<T extends VListItem = VListItem> {
     setItems: (items: T[], offset?: number, total?: number) => void;
     /** Update item at index */
     updateItem: (index: number, updates: Partial<T>) => boolean;
+    /** Insert item at index */
+    insertItem: (item: T, index: number) => void;
     /** Remove item by ID */
     removeItem: (id: string | number) => boolean;
     /** Load items for a range */

package/dist/features/async/sparse.d.ts

@@ -45,6 +45,8 @@ export interface SparseStorage<T extends VListItem = VListItem> {
     set: (index: number, item: T) => void;
     /** Set multiple items starting at offset */
     setRange: (offset: number, items: T[]) => void;
+    /** Insert item at index, shifting subsequent items up by 1 */
+    insert: (index: number, item: T) => void;
     /** Delete item at index */
     delete: (index: number) => boolean;
     /** Get items in range (includes undefined for unloaded) */
@@ -57,8 +59,10 @@ export interface SparseStorage<T extends VListItem = VListItem> {
     findUnloadedRanges: (start: number, end: number) => Range[];
     /** Get chunk index for item index */
     getChunkIndex: (itemIndex: number) => number;
-    /** Check if chunk is loaded */
+    /** Check if chunk is loaded (has any items) */
     isChunkLoaded: (chunkIndex: number) => boolean;
+    /** Check if chunk has all expected items (count matches expected for total) */
+    isChunkFullyLoaded: (chunkIndex: number) => boolean;
     /** Mark chunk as accessed (for LRU) */
     touchChunk: (chunkIndex: number) => void;
     /** Mark all chunks in a range as accessed with a single Date.now() call */

package/dist/features/groups/async-bridge.d.ts

@@ -48,6 +48,8 @@ export interface AsyncGroupBridge {
     getGroupAtLayoutIndex(layoutIndex: number): GroupBoundary;
     /** Get the group boundary at a data index */
     getGroupAtDataIndex(dataIndex: number): GroupBoundary;
+    /** Insert item at data index — shifts group keys up and rebuilds */
+    insertAt(dataIndex: number, item: VListItem): void;
     /** Remove item at data index — shifts group keys and rebuilds */
     removeAt(dataIndex: number): void;
     /** Reset all state (e.g. on reload) */

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

@@ -0,0 +1,30 @@
+/**
+ * withTransition — FLIP-based enter/exit animations for insertItem and removeItem.
+ *
+ * Opt-in feature that replaces the immediate insert/remove with animated versions:
+ * - removeItem: clone collapses via scaleY(0), siblings slide up
+ * - insertItem: new element expands in, siblings slide down
+ *
+ * Without this feature, insert/remove are instantaneous.
+ */
+import type { VListItem } from "../../types";
+import type { VListFeature } from "../../builder/types";
+/** Per-animation timing overrides. */
+export interface TransitionTiming {
+    /** Duration in ms */
+    duration?: number;
+    /** CSS easing function */
+    easing?: string;
+}
+export interface TransitionConfig {
+    /** Shared duration in ms (default: 200). Overridden by add/remove sub-configs. */
+    duration?: number;
+    /** Shared CSS easing (default: MD3 emphasized). Overridden by add/remove sub-configs. */
+    easing?: string;
+    /** Insert animation config, or `false` to disable. */
+    insert?: TransitionTiming | false;
+    /** Remove animation config, or `false` to disable. */
+    remove?: TransitionTiming | false;
+}
+export declare function withTransition<T extends VListItem = VListItem>(config?: TransitionConfig): VListFeature<T>;
+//# sourceMappingURL=feature.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * vlist/transition — FLIP-based enter/exit animations
+ * Opt-in animated add/remove for smooth list transitions
+ *
+ * Usage: import { withTransition } from 'vlist'
+ */
+export { withTransition } from "./feature";
+export type { TransitionConfig, TransitionTiming } from "./feature";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export { withTable } from "./features/table";
 export { withSortable } from "./features/sortable";
 export type { SortableConfig } from "./features/sortable";
 export { withAutoSize } from "./features/autosize";
+export { withTransition } from "./features/transition";
+export type { TransitionConfig, TransitionTiming } from "./features/transition";
 export { createStats } from "./utils/stats";
 export type { Stats, StatsConfig, StatsState } from "./utils/stats";
 export type { VListItem, VListEvents, ItemConfig, ItemTemplate, ItemState, SelectionMode, SelectionConfig, SelectionState, ScrollbarConfig, ScrollbarPadding, ScrollbarOptions, ScrollConfig, ScrollToOptions, ScrollSnapshot, VListAdapter, AdapterParams, AdapterResponse, Range, ViewportState, EventHandler, Unsubscribe, GridConfig, MasonryConfig, GroupsConfig, GroupHeaderConfig, GridSizeContext, GridHeightContext, } from "./types";