@floor/vlist 1.0.1 → 1.1.0

package/README.md

@@ -9,7 +9,7 @@ Lightweight, high-performance virtual list with zero dependencies and dimension-
 
 - **Zero dependencies** — no external libraries
 - **Ultra memory efficient** — ~0.1-0.2 MB constant overhead regardless of dataset size
-- **8–12 KB gzipped** — pay only for features you use (vs 20 KB+ monolithic alternatives)
+- **~8 KB gzipped** — pay only for features you use (vs 20 KB+ monolithic alternatives)
 - **Builder API** — composable features with perfect tree-shaking
 - **Grid, masonry, sections, async, selection, scale** — all opt-in
 - **Horizontal & vertical** — semantically correct orientation support
@@ -19,13 +19,14 @@ Lightweight, high-performance virtual list with zero dependencies and dimension-
 
 **30+ interactive examples → [vlist.dev](https://vlist.dev)**
 
-## v1.0.0 Highlights
+## Highlights
 
-- 🧱 **Masonry layout** — Pinterest-style shortest-lane placement via `withMasonry()`
-- ⚡ **Performance optimized** — 13-pattern optimization playbook applied across the entire rendering pipeline
-- ✨ **Dimension-agnostic API** — semantically correct terminology for both orientations
-- 🎯 **Horizontal sections** — sticky headers work in horizontal carousels
-- 🎨 **Horizontal grid layouts** — 2D grids work in both orientations
+
+- **Dimension-agnostic API** — semantically correct terminology for both orientations
+- **Performance optimized** — 13-pattern optimization playbook applied across the entire rendering pipeline
+- **Horizontal sections** — sticky headers work in horizontal carousels
+- **Horizontal grid layouts** — 2D grids work in both orientations
+- **Masonry** — shortest-lane placement via `withMasonry()`
 
 ## Installation
 
@@ -79,20 +80,20 @@ const list = vlist({
   .build()
 ```
 
-### Plugins
+### Features
 
 | Feature | Size | Description |
 |---------|------|-------------|
-| **Base** | 7.7 KB | Core virtualization |
-| `withGrid()` | +4.0 KB | 2D grid layout |
-| `withMasonry()` | +2.9 KB | Pinterest-style masonry layout |
-| `withSections()` | +4.6 KB | Grouped lists with sticky/inline headers |
-| `withAsync()` | +5.3 KB | Lazy loading with adapters |
-| `withSelection()` | +2.3 KB | Single/multiple selection + keyboard nav |
-| `withScale()` | +2.2 KB | 1M+ items via scroll compression |
-| `withScrollbar()` | +1.0 KB | Custom scrollbar UI |
-| `withPage()` | +0.9 KB | Document-level scrolling |
-| `withSnapshots()` | included | Scroll save/restore |
+| **Base** | 8.1 KB | Core virtualization |
+| `withGrid()` | +3.8 KB | 2D grid layout |
+| `withMasonry()` | +2.3 KB | Pinterest-style masonry layout |
+| `withSections()` | +4.1 KB | Grouped lists with sticky/inline headers |
+| `withAsync()` | +3.9 KB | Lazy loading with adapters |
+| `withSelection()` | +1.6 KB | Single/multiple selection + keyboard nav |
+| `withScale()` | +2.6 KB | 1M+ items via scroll compression |
+| `withScrollbar()` | +1.2 KB | Custom scrollbar UI |
+| `withPage()` | +0.4 KB | Document-level scrolling |
+| `withSnapshots()` | +0.5 KB | Scroll save/restore |
 
 ## Examples
 
@@ -190,7 +191,7 @@ See **[vlist.dev](https://vlist.dev)** for live demos of each.
 ## API
 
 ```typescript
-const list = vlist(config).use(...plugins).build()
+const list = vlist(config).use(...features).build()
 ```
 
 ### Data
@@ -212,7 +213,11 @@ const list = vlist(config).use(...plugins).build()
 | `list.scrollToIndex(i, opts?)` | With `{ align, behavior: 'smooth', duration }` |
 | `list.cancelScroll()` | Cancel smooth scroll animation |
 | `list.getScrollPosition()` | Current scroll offset |
-| `list.getVisibleRange()` | `{ start, end }` of visible indices |
+
+### Snapshots (with `withSnapshots()`)
+
+| Method | Description |
+|--------|-------------|
 | `list.getScrollSnapshot()` | Save scroll state (for SPA navigation) |
 | `list.restoreScroll(snapshot)` | Restore saved scroll state |
 
@@ -220,11 +225,11 @@ const list = vlist(config).use(...plugins).build()
 
 | Method | Description |
 |--------|-------------|
-| `list.selectItem(id)` | Select item |
-| `list.deselectItem(id)` | Deselect item |
-| `list.toggleSelection(id)` | Toggle |
+| `list.select(...ids)` | Select item(s) |
+| `list.deselect(...ids)` | Deselect item(s) |
+| `list.toggleSelect(id)` | Toggle |
 | `list.selectAll()` / `list.clearSelection()` | Bulk operations |
-| `list.getSelectedIds()` | Array of selected IDs |
+| `list.getSelected()` | Array of selected IDs |
 | `list.getSelectedItems()` | Array of selected items |
 
 ### Grid (with `withGrid()`)
@@ -263,9 +268,9 @@ list.on('velocity:change', ({ velocity, reliable }) => {})
 list.destroy()
 ```
 
-## Plugin Configuration
+## Feature Configuration
 
-Each plugin's config is fully typed — hover in your IDE for details.
+Each feature's config is fully typed — hover in your IDE for details.
 
 ```typescript
 withGrid({ columns: 4, gap: 16 })
@@ -288,9 +293,10 @@ Full configuration reference → **[vlist.dev](https://vlist.dev)**
 | React | [`vlist-react`](https://github.com/floor/vlist-react) | 0.6 KB gzip |
 | Vue | [`vlist-vue`](https://github.com/floor/vlist-vue) | 0.6 KB gzip |
 | Svelte | [`vlist-svelte`](https://github.com/floor/vlist-svelte) | 0.5 KB gzip |
+| SolidJS | [`vlist-solidjs`](https://github.com/floor/vlist-solidjs) | 0.5 KB gzip |
 
 ```bash
-npm install @floor/vlist vlist-react   # or vlist-vue / vlist-svelte
+npm install @floor/vlist vlist-react   # or vlist-vue / vlist-svelte / vlist-solidjs
 ```
 
 Each adapter README has setup examples and API docs.
@@ -331,11 +337,10 @@ This makes the codebase clearer and eliminates semantic confusion when working w
 
 | Configuration | Gzipped |
 |---------------|---------|
-| Base only | 7.7 KB |
-| + Grid | 11.7 KB |
-| + Sections | 12.3 KB |
-| + Async | 13.5 KB |
-| All plugins | ~16 KB |
+| Base only | 8.1 KB |
+| + Grid | 11.9 KB |
+| + Sections | 12.2 KB |
+| + Async | 12.0 KB |
 
 ### Memory Efficiency
 
@@ -406,4 +411,4 @@ See [CHANGELOG.md](https://vlist.dev/docs/CHANGELOG.md) for the full release his
 
 ---
 
-Built by [Floor IO](https://floor.io)
+Built by [Floor IO](https://floor.io)

package/dist/builder/index.d.ts

@@ -21,5 +21,5 @@
  * @packageDocumentation
  */
 export { vlist } from "./core";
-export type { VListBuilder, BuiltVList, BuilderConfig, VListFeature, FeatureFactory, BuilderContext, BuilderState, ResolvedBuilderConfig, } from "./types";
+export type { VListBuilder, VList, BuilderConfig, VListFeature, FeatureFactory, BuilderContext, BuilderState, ResolvedBuilderConfig, } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/builder/types.d.ts

@@ -243,10 +243,17 @@ export interface VListBuilder<T extends VListItem = VListItem> {
     /** Register a feature. Chainable. */
     use(feature: VListFeature<T>): VListBuilder<T>;
     /** Materialize the virtual list. Creates DOM, initializes features, returns API. */
-    build(): BuiltVList<T>;
+    build(): VList<T>;
 }
-/** Base API always available from builder (data methods, scroll methods, events, lifecycle) */
-export interface BuiltVList<T extends VListItem = VListItem> {
+/**
+ * VList instance API — returned by `vlist(config).build()`.
+ *
+ * Always-available methods (data, scroll, events, lifecycle) are required.
+ * Feature methods (selection, snapshots, grid, etc.) are optional —
+ * they exist on the instance only when the corresponding feature is
+ * registered via `.use()`.
+ */
+export interface VList<T extends VListItem = VListItem> {
     /** The root DOM element */
     readonly element: HTMLElement;
     /** Current items */

package/dist/index.d.ts

@@ -15,8 +15,8 @@ export { withGrid } from "./features/grid";
 export { withMasonry } from "./features/masonry";
 export { withSelection } from "./features/selection";
 export { withSnapshots } from "./features/snapshots";
-export type { VList, VListConfig, VListItem, VListEvents, ItemTemplate, ItemState, SelectionMode, SelectionConfig, SelectionState, ScrollbarConfig, ScrollbarOptions, ScrollConfig, ScrollToOptions, ScrollSnapshot, VListAdapter, AdapterParams, AdapterResponse, Range, ViewportState, EventHandler, Unsubscribe, } from "./types";
-export type { VListBuilder, BuiltVList, BuilderConfig, VListFeature, BuilderContext, } from "./builder";
+export type { VListItem, VListEvents, ItemTemplate, ItemState, SelectionMode, SelectionConfig, SelectionState, ScrollbarConfig, ScrollbarOptions, ScrollConfig, ScrollToOptions, ScrollSnapshot, VListAdapter, AdapterParams, AdapterResponse, Range, ViewportState, EventHandler, Unsubscribe, } from "./types";
+export type { VListBuilder, VList, BuilderConfig, VListFeature, BuilderContext, } from "./builder";
 export { createGroupLayout as createSectionLayout, buildLayoutItems, createGroupedSizeFn as createSectionedSizeFn, createStickyHeader, isGroupHeader as isSectionHeader, type GroupsConfig as SectionsConfig, type GroupBoundary as SectionBoundary, type LayoutEntry, type GroupHeaderItem as SectionHeaderItem, type GroupLayout as SectionLayout, type StickyHeader, } from "./features/sections";
 export { createGridLayout, createGridRenderer, type GridConfig, type GridLayout, type GridPosition, type GridRenderer, type ItemRange, } from "./features/grid";
 export { createMasonryLayout, createMasonryRenderer, type MasonryConfig, type MasonryLayout, type MasonryRenderer, type GetItemFn, type ItemPlacement, } from "./features/masonry";

package/dist/types.d.ts

@@ -146,171 +146,6 @@ export interface ItemConfig<T extends VListItem = VListItem> {
     /** Template function to render each item */
     template: ItemTemplate<T>;
 }
-/** Main configuration for createVList */
-export interface VListConfig<T extends VListItem = VListItem> {
-    /** Container element or selector */
-    container: HTMLElement | string;
-    /**
-     * Layout orientation (default: 'vertical').
-     *
-     * - `'vertical'` — Standard top-to-bottom scrolling (default)
-     * - `'horizontal'` — Left-to-right scrolling (carousel, timeline, etc.)
-     *
-     * When `'horizontal'`:
-     * - `item.width` is required (main-axis size for virtualization)
-     * - `item.height` is optional (cross-axis size, can be set via CSS)
-     * - Items are positioned with `translateX` instead of `translateY`
-     * - The viewport scrolls on the X axis
-     *
-     * Cannot be combined with `groups`, `grid`, or `reverse`.
-     */
-    orientation?: "vertical" | "horizontal";
-    /** Item configuration (height and template) */
-    item: ItemConfig<T>;
-    /** Static items array (optional if using adapter) */
-    items?: T[];
-    /** Async data adapter for infinite scroll */
-    adapter?: VListAdapter<T>;
-    /** Number of extra items to render outside viewport (default: 3) */
-    overscan?: number;
-    /** Selection configuration */
-    selection?: SelectionConfig;
-    /**
-     * External scroll element for document/window scrolling.
-     * @deprecated Use `scroll.element` instead.
-     */
-    scrollElement?: Window;
-    /** Scroll behavior configuration */
-    scroll?: ScrollConfig;
-    /**
-     * Custom scrollbar configuration.
-     * @deprecated Use `scroll.scrollbar` instead.
-     */
-    scrollbar?: ScrollbarConfig;
-    /** Loading behavior configuration */
-    loading?: LoadingConfig;
-    /**
-     * Scroll idle detection timeout in ms (default: 150).
-     * @deprecated Use `scroll.idleTimeout` instead.
-     */
-    idleTimeout?: number;
-    /** Custom CSS class prefix (default: 'vlist') */
-    classPrefix?: string;
-    /** Accessible label for the listbox (sets aria-label on the root element) */
-    ariaLabel?: string;
-    /**
-     * Groups configuration for sticky headers / grouped lists.
-     * When set, items are automatically grouped and section headers
-     * are inserted at group boundaries.
-     *
-     * Items MUST be pre-sorted by group — a new header is inserted
-     * whenever `getGroupForIndex` returns a different value.
-     */
-    groups?: GroupsConfig;
-    /**
-     * Layout mode (default: 'list').
-     * - `'list'` — Standard vertical list (one item per row)
-     * - `'grid'` — 2D grid layout (multiple items per row, requires `grid` config)
-     *
-     * In grid mode:
-     * - Virtualization operates on ROWS, not individual items
-     * - Each row contains `grid.columns` items side by side
-     * - Item width is automatically calculated: (containerWidth - gaps) / columns
-     * - Compression applies to row count, not item count
-     */
-    layout?: "list" | "grid";
-    /**
-     * Grid configuration (required when `layout: 'grid'`).
-     *
-     * ```ts
-     * createVList({
-     *   container: '#gallery',
-     *   layout: 'grid',
-     *   grid: { columns: 4, gap: 8 },
-     *   item: {
-     *     height: 200,
-     *     template: (item) => `<img src="${item.thumbnail}" />`,
-     *   },
-     *   items: photos,
-     * });
-     * ```
-     */
-    grid?: GridConfig;
-    /**
-     * Reverse mode for chat-style UIs.
-     * When enabled:
-     * - The list starts scrolled to the bottom (newest items visible)
-     * - `appendItems()` auto-scrolls to bottom if the user was already at bottom
-     * - `prependItems()` preserves scroll position (older messages load above without jumping)
-     * - With an adapter, "load more" triggers near the TOP (loading older content)
-     *
-     * Items stay in chronological order (oldest = index 0, newest = last).
-     * Cannot be combined with `groups` or `grid` layout.
-     *
-     * ```ts
-     * const chat = createVList({
-     *   container: '#messages',
-     *   reverse: true,
-     *   item: { height: 60, template: messageTemplate },
-     *   items: messages,
-     * });
-     *
-     * chat.appendItems([newMessage]);   // auto-scrolls to bottom
-     * chat.prependItems(olderMessages); // scroll position preserved
-     * ```
-     */
-    reverse?: boolean;
-}
-/**
- * Configuration options that can be updated dynamically without recreating the instance.
- * Used by the update() method.
- */
-export interface VListUpdateConfig {
-    /**
-     * Grid configuration (columns and gap).
-     * Only applicable when layout is 'grid'.
-     */
-    grid?: {
-        columns?: number;
-        gap?: number;
-    };
-    /**
-     * Item height (for variable height updates).
-     * Can be a number or a function.
-     */
-    itemHeight?: number | ((index: number) => number);
-    /**
-     * Selection mode.
-     * Changes selection behavior without recreating the list.
-     */
-    selectionMode?: SelectionMode;
-    /**
-     * Overscan value (number of items to render outside viewport).
-     */
-    overscan?: number;
-}
-/** Loading behavior configuration */
-export interface LoadingConfig {
-    /**
-     * Velocity threshold above which data loading is skipped (px/ms)
-     * When scrolling faster than this, loading is deferred until scroll stops.
-     * Default: 25 px/ms
-     */
-    cancelThreshold?: number;
-    /**
-     * Velocity threshold for preloading (px/ms)
-     * When scrolling faster than this but slower than cancelThreshold,
-     * extra items are preloaded in the scroll direction.
-     * Default: 2 px/ms
-     */
-    preloadThreshold?: number;
-    /**
-     * Number of extra items to preload ahead of scroll direction
-     * Only applies when velocity is between preloadThreshold and cancelThreshold.
-     * Default: 50 items
-     */
-    preloadAhead?: number;
-}
 /** Scroll position snapshot for save/restore */
 export interface ScrollSnapshot {
     /** First visible item index */
@@ -533,76 +368,4 @@ export interface VListEvents<T extends VListItem = VListItem> extends EventMap {
 export type EventHandler<T> = (payload: T) => void;
 /** Unsubscribe function */
 export type Unsubscribe = () => void;
-/** VList instance API */
-export interface VList<T extends VListItem = VListItem> {
-    /** The root DOM element */
-    readonly element: HTMLElement;
-    /** Current items */
-    readonly items: readonly T[];
-    /** Total item count */
-    readonly total: number;
-    /** Set items (replaces all) */
-    setItems: (items: T[]) => void;
-    /** Append items */
-    appendItems: (items: T[]) => void;
-    /** Prepend items */
-    prependItems: (items: T[]) => void;
-    /** Update a single item by ID */
-    updateItem: (id: string | number, updates: Partial<T>) => void;
-    /** Remove item by ID */
-    removeItem: (id: string | number) => void;
-    /** Reload data (clears and re-fetches if using adapter) */
-    reload: () => Promise<void>;
-    /** Load data for the currently visible range without resetting (used by restoreScroll) */
-    loadVisibleRange: () => Promise<void>;
-    /** Update configuration without recreating the instance */
-    update: (config: Partial<VListUpdateConfig>) => void;
-    /** Scroll to specific index */
-    scrollToIndex: (index: number, alignOrOptions?: "start" | "center" | "end" | ScrollToOptions) => void;
-    /** Scroll to specific item by ID */
-    scrollToItem: (id: string | number, alignOrOptions?: "start" | "center" | "end" | ScrollToOptions) => void;
-    /** Cancel any in-progress smooth scroll animation */
-    cancelScroll: () => void;
-    /** Get current scroll position */
-    getScrollPosition: () => number;
-    /** Get a snapshot of the current scroll position for save/restore */
-    getScrollSnapshot: () => ScrollSnapshot;
-    /** Restore scroll position (and optionally selection) from a snapshot */
-    restoreScroll: (snapshot: ScrollSnapshot) => void;
-    /** Select item(s) by ID */
-    select: (...ids: Array<string | number>) => void;
-    /** Deselect item(s) by ID */
-    deselect: (...ids: Array<string | number>) => void;
-    /** Toggle selection */
-    toggleSelect: (id: string | number) => void;
-    /** Select all items */
-    selectAll: () => void;
-    /** Clear selection */
-    clearSelection: () => void;
-    /** Get selected item IDs */
-    getSelected: () => Array<string | number>;
-    /** Get selected items */
-    getSelectedItems: () => T[];
-    /** Subscribe to an event */
-    on: <K extends keyof VListEvents<T>>(event: K, handler: EventHandler<VListEvents<T>[K]>) => Unsubscribe;
-    /** Unsubscribe from an event */
-    off: <K extends keyof VListEvents<T>>(event: K, handler: EventHandler<VListEvents<T>[K]>) => void;
-    /** Destroy the instance and cleanup */
-    destroy: () => void;
-}
-/** Internal state */
-export interface InternalState<T extends VListItem = VListItem> {
-    items: T[];
-    total: number;
-    viewport: ViewportState;
-    selection: SelectionState;
-    isLoading: boolean;
-    cursor?: string;
-    hasMore: boolean;
-}
-/** Rendered item tracking */
-export interface RenderedItem {
-    index: number;
-    element: HTMLElement;
-}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floor/vlist",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Lightweight, high-performance virtual list with zero dependencies",
   "author": {
     "name": "Floor IO",
@@ -52,6 +52,7 @@
     "dev": "bun run build.ts --watch",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
+    "size": "bun run scripts/measure-size.ts",
     "prepublishOnly": "bun run build --types"
   },
   "bugs": {