vlist 1.6.4 → 1.7.0

package/README.github.md

@@ -1,20 +1,47 @@
 # vlist
 
-The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 10.6 KB.
+The virtual list library for every framework. Accessible by default, batteries-included, with composable features — in 10.5 KB.
+
+**v1.7.0** — [Changelog](./changelog.txt)
 
 [![npm version](https://img.shields.io/npm/v/vlist.svg)](https://www.npmjs.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)
 
-- **Zero dependencies** — framework-agnostic core, tiny adapters for Vue, Svelte, Solid, React
-- **Accessible** — WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
+- **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
 - **10.6 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, scale** — all opt-in
+- **Vertical & horizontal** — dimension-agnostic API, every layout mode works in both orientations
+
+**18 interactive examples, docs & benchmarks → [vlist.io](https://vlist.io)**
+
+## Why vlist
+
+| | vlist | TanStack Virtual | react-virtuoso | virtua | vue-virtual-scroller |
+|---|---|---|---|---|---|
+| **A11y built-in** | WAI-ARIA + 2D keyboard | None (DIY) | Partial | Minimal | None |
+| **Grid + Masonry + Table** | All | Grid only | Grid + Table | Grid only | None |
+| **Vue** | 0.6 KB adapter | Yes | — | Yes | 11.8 KB |
+| **Svelte** | 0.5 KB adapter | Yes | — | Yes | — |
+| **Solid** | 0.5 KB adapter | Yes | — | Yes | — |
+| **Vanilla JS** | Native | Yes | — | — | — |
+| **Constant memory** | ~0.1 MB at 1M | No | No | No | No |
+
+## Framework Adapters
 
-## Install
+| Framework | Package | Size |
+|-----------|---------|------|
+| Vanilla JS | `vlist` | Native — no adapter needed |
+| 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 |
+| React | [`vlist-react`](https://github.com/floor/vlist-react) | 0.6 KB gzip |
 
 ```bash
-npm install vlist
+npm install vlist              # vanilla JS
+npm install vlist vlist-vue    # or vlist-svelte / vlist-solidjs / vlist-react
 ```
 
 ## Quick Start
@@ -35,27 +62,41 @@ const list = vlist({
     template: (item) => `<div>${item.name}</div>`,
   },
 }).build()
+
+list.scrollToIndex(10)
+list.setItems(newItems)
+list.on('item:click', ({ item }) => console.log(item))
 ```
 
-Add features with the builder pattern:
+## Builder Pattern
+
+Start with the base, add only what you need:
 
 ```typescript
-import { vlist, withGrid, withSelection } from 'vlist'
+import { vlist, withGrid, withGroups, withSelection } from 'vlist'
 
-const list = vlist({ container: '#app', items, item: { height: 200, template: render } })
+const list = vlist({
+  container: '#app',
+  items: photos,
+  item: { height: 200, template: renderPhoto },
+})
   .use(withGrid({ columns: 4, gap: 16 }))
+  .use(withGroups({
+    getGroupForIndex: (i) => photos[i].category,
+    header: { height: 40, template: (cat) => `<h2>${cat}</h2>` },
+  }))
   .use(withSelection({ mode: 'multiple' }))
   .build()
 ```
 
-## Features
+### Features
 
 | Feature | Size | Description |
 |---------|------|-------------|
 | **Base** | 10.6 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.1 KB | 1M+ items via scroll compression |
+| `withScale()` | +3.7 KB | 1M+ items via scroll compression |
 | `withGroups()` | +2.7 KB | Sticky/inline headers |
 | `withAutoSize()` | +0.9 KB | Auto-measure items via ResizeObserver |
 | `withScrollbar()` | +1.7 KB | Custom scrollbar UI |
@@ -65,19 +106,260 @@ const list = vlist({ container: '#app', items, item: { height: 200, template: re
 | `withPage()` | +0.8 KB | Window-level scrolling |
 | `withSnapshots()` | +0.8 KB | Scroll position save/restore |
 
-## Framework Adapters
+## Examples
 
-| Framework | Package | Size |
-|-----------|---------|------|
-| Vue | [`vlist-vue`](https://github.com/floor/vlist-vue) | 0.6 KB |
-| Svelte | [`vlist-svelte`](https://github.com/floor/vlist-svelte) | 0.5 KB |
-| SolidJS | [`vlist-solidjs`](https://github.com/floor/vlist-solidjs) | 0.5 KB |
-| React | [`vlist-react`](https://github.com/floor/vlist-react) | 0.6 KB |
+More examples at **[vlist.io](https://vlist.io)**.
+
+### Data Table
+
+```typescript
+import { vlist, withTable, withSelection } from 'vlist'
+
+const table = vlist({
+  container: '#my-table',
+  items: contacts,
+  item: { height: 36, template: () => '' },
+})
+  .use(withTable({
+    columns: [
+      { key: 'name',   label: 'Name',   width: 200, sortable: true },
+      { key: 'email',  label: 'Email',  width: 260, sortable: true },
+      { key: 'role',   label: 'Role',   width: 160, sortable: true },
+      { key: 'status', label: 'Status', width: 100, align: 'center' },
+    ],
+    rowHeight: 36,
+    headerHeight: 36,
+    resizable: true,
+  }))
+  .use(withSelection({ mode: 'single' }))
+  .build()
+
+table.on('column:sort', ({ key, direction }) => { /* re-sort data */ })
+table.on('column:resize', ({ key, width }) => { /* persist widths */ })
+```
+
+### Grid Layout
+
+```typescript
+import { vlist, withGrid, withScrollbar } from 'vlist'
+
+const gallery = vlist({
+  container: '#gallery',
+  items: photos,
+  item: {
+    height: 200,
+    template: (photo) => `
+      <div class="card">
+        <img src="${photo.url}" />
+        <span>${photo.title}</span>
+      </div>
+    `,
+  },
+})
+  .use(withGrid({ columns: 4, gap: 16 }))
+  .use(withScrollbar({ autoHide: true }))
+  .build()
+```
+
+### Async Loading
+
+```typescript
+import { vlist, withAsync } from 'vlist'
 
-## Docs & Examples
+const list = vlist({
+  container: '#list',
+  item: {
+    height: 64,
+    template: (item) => item
+      ? `<div>${item.name}</div>`
+      : `<div class="placeholder">Loading…</div>`,
+  },
+})
+  .use(withAsync({
+    adapter: {
+      read: async ({ offset, limit }) => {
+        const res = await fetch(`/api/users?offset=${offset}&limit=${limit}`)
+        const data = await res.json()
+        return { items: data.items, total: data.total, hasMore: data.hasMore }
+      },
+    },
+  }))
+  .build()
+```
+
+## Accessibility
+
+Every vlist is accessible by default following the [WAI-ARIA listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/):
+
+- **Arrow keys** move focus between items with a visible focus ring
+- **2D navigation** in grids and masonry — Up/Down by row, Left/Right by cell
+- **Masonry lane-aware nav** — arrows stay in the same visual column
+- **Home/End, PageUp/PageDown, Ctrl+Home/End** — full keyboard coverage
+- **Screen-reader DOM ordering** — items reordered on scroll idle for correct reading order
+- **ARIA live region** — announces loading state changes
+- **Focus recovery** — maintains focus when items are removed
+
+Set `interactive: false` for display-only lists (log viewers, activity feeds) where items contain their own interactive elements.
+
+## API
+
+```typescript
+const list = vlist(config).use(...features).build()
+```
 
-**18 interactive examples, full API reference, tutorials, and live benchmarks → [vlist.io](https://vlist.io)**
+### Data
+
+| Method | Description |
+|--------|-------------|
+| `list.setItems(items)` | Replace all items |
+| `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.getItemAt(index)` | Get item at index |
+| `list.getIndexById(id)` | Get index by item ID |
+| `list.reload()` | Re-fetch from adapter (async) |
+
+### Navigation
+
+| Method | Description |
+|--------|-------------|
+| `list.scrollToIndex(i, align?)` | Scroll to index (`'start'` \| `'center'` \| `'end'`) |
+| `list.scrollToIndex(i, opts?)` | With `{ align, behavior: 'smooth', duration }` |
+| `list.cancelScroll()` | Cancel smooth scroll animation |
+| `list.getScrollPosition()` | Current scroll offset |
+
+### Selection (with `withSelection()`)
+
+| Method | Description |
+|--------|-------------|
+| `list.select(...ids)` | Select item(s) |
+| `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 |
+
+### Events
+
+`list.on()` returns an unsubscribe function. You can also use `list.off(event, handler)`.
+
+```typescript
+list.on('scroll', ({ scrollPosition, direction }) => {})
+list.on('range:change', ({ range }) => {})
+list.on('item:click', ({ item, index, event }) => {})
+list.on('item:dblclick', ({ item, index, event }) => {})
+list.on('selection:change', ({ selectedIds, selectedItems }) => {})
+list.on('load:start', ({ offset, limit }) => {})
+list.on('load:end', ({ items, offset, total }) => {})
+list.on('load:error', ({ error, offset, limit }) => {})
+```
+
+### Properties
+
+| Property | Description |
+|----------|-------------|
+| `list.element` | Root DOM element |
+| `list.items` | Current items (readonly) |
+| `list.total` | Total item count |
+| `list.destroy()` | Cleanup and remove from DOM |
+
+## Feature Configuration
+
+Each feature's config is fully typed — hover in your IDE for details.
+
+```typescript
+withGrid({ columns: 4, gap: 16 })
+withMasonry({ columns: 4, gap: 16 })
+withGroups({ getGroupForIndex, header: { height, template }, sticky?: true })
+withSelection({ mode: 'single' | 'multiple', initial?: [...ids] })
+withAsync({ adapter: { read }, loading?: { cancelThreshold? } })
+withTable({ columns, rowHeight, headerHeight?, resizable? })
+withAutoSize()                        // auto-measure items (requires estimatedHeight)
+withScale()                           // auto-activates at 16.7M px
+withScrollbar({ autoHide?, autoHideDelay?, minThumbSize? })
+withPage()                            // no config — uses document scroll
+withSnapshots({ autoSave: 'key' })    // automatic sessionStorage save/restore
+```
+
+Full configuration reference → **[vlist.io](https://vlist.io)**
+
+## Base Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `overscan` | `3` | Extra items rendered outside viewport |
+| `ariaLabel` | — | Accessible label for the listbox |
+| `orientation` | `'vertical'` | `'vertical'` or `'horizontal'` scroll direction |
+| `padding` | `0` | Content inset — number, `[v, h]`, or `[top, right, bottom, left]` |
+| `interactive` | `true` | Enable built-in keyboard navigation |
+| `reverse` | `false` | Reverse mode for chat UIs |
+| `scroll.wrap` | `false` | Wrap focus around at boundaries |
+
+## Styling
+
+```typescript
+import 'vlist/styles'           // core (always required)
+import 'vlist/styles/grid'      // when using withGrid()
+import 'vlist/styles/masonry'   // when using withMasonry()
+import 'vlist/styles/table'     // when using withTable()
+import 'vlist/styles/extras'    // optional (variants, loading states, animations)
+```
+
+Dark mode works out of the box via `prefers-color-scheme`, Tailwind's `.dark` class, or `data-theme-mode="dark"`. Override CSS custom properties to match your design system. See [vlist.io/tutorials/styling](https://vlist.io/tutorials/styling) for the full guide.
+
+## Performance
+
+| Dataset Size | After Render | Scroll Delta |
+|--------------|-------------|--------------|
+| 10K items | 0.07 MB | ~0 MB |
+| 100K items | 0.08 MB | ~0 MB |
+| 1M items | 0.09 MB | 0.19 MB |
+
+- **Initial render:** ~8ms (constant, regardless of item count)
+- **Scroll:** 120 FPS at any scale
+- **DOM nodes:** ~26 in document with 100K items (visible + overscan only)
+
+Live benchmarks against 9 competitors → **[vlist.io/benchmarks](https://vlist.io/benchmarks)**
+
+## TypeScript
+
+Fully typed. Generic over your item type:
+
+```typescript
+import { vlist, withGrid, type VList } from 'vlist'
+
+interface Photo { id: number; url: string; title: string }
+
+const list: VList<Photo> = vlist<Photo>({
+  container: '#gallery',
+  items: photos,
+  item: {
+    height: 200,
+    template: (photo) => `<img src="${photo.url}" />`,
+  },
+})
+  .use(withGrid({ columns: 4 }))
+  .build()
+```
+
+## Contributing
+
+1. Fork → branch → make changes → add tests → pull request
+2. Run `bun test` and `bun run build` before submitting
 
 ## License
 
-[MIT](LICENSE) — Built by [Floor IO](https://floor.io)
+[MIT](LICENSE)
+
+## Links
+
+- **Docs & Examples:** [vlist.io](https://vlist.io)
+- **Staging:** [staging.vlist.io](https://staging.vlist.io)
+- **GitHub:** [github.com/floor/vlist](https://github.com/floor/vlist)
+- **NPM:** [vlist](https://www.npmjs.com/package/vlist)
+- **Issues:** [GitHub Issues](https://github.com/floor/vlist/issues)
+
+---
+
+Built by [FloorIO](https://floor.io)

package/README.md

@@ -55,7 +55,7 @@ const list = vlist({ container: '#app', items, item: { height: 200, template: re
 | **Base** | 10.6 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.1 KB | 1M+ items via scroll compression |
+| `withScale()` | +3.7 KB | 1M+ items via scroll compression |
 | `withGroups()` | +2.7 KB | Sticky/inline headers |
 | `withAutoSize()` | +0.9 KB | Auto-measure items via ResizeObserver |
 | `withScrollbar()` | +1.7 KB | Custom scrollbar UI |

package/dist/builder/types.d.ts

@@ -476,6 +476,7 @@ export interface VList<T extends VListItem = VListItem> {
     selectPrevious?: () => void;
     getScrollSnapshot?: () => ScrollSnapshot;
     restoreScroll?: (snapshot: ScrollSnapshot) => void;
+    isSorting?: () => boolean;
     [key: string]: unknown;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,95 @@
+/**
+ * vlist/sortable - Builder Feature
+ * Drag-and-drop reordering for virtual lists.
+ *
+ * Priority: 55 (runs after selection at 50, before scrollbar at 60)
+ *
+ * What it wires:
+ * - Pointer event handlers on the items container for drag initiation
+ * - Creates a drag ghost element that follows the pointer
+ * - Items shift via CSS transforms to make room (like iOS list reordering)
+ * - Auto-scrolls when dragging near viewport edges
+ * - Keyboard reordering: Space to grab, arrows to move, Space to drop, Escape to cancel
+ * - ARIA attributes (aria-roledescription, aria-describedby) and live region announcements
+ * - Emits sort:start, sort:end, and sort:cancel events
+ *
+ * The feature is purely visual during drag — it does NOT reorder data.
+ * On drop, it emits a `sort:end` event with `{ fromIndex, toIndex }`.
+ * The consumer is responsible for reordering their data array and
+ * calling `setItems()` with the new order.
+ *
+ * Keyboard reordering emits `sort:end` per arrow key press (incremental moves).
+ * On Escape, it emits `sort:cancel` with `{ originalItems }` so the consumer
+ * can restore the original order via `setItems(originalItems)`.
+ *
+ * When composed with withSelection, Space is intercepted for grab/drop.
+ * Use Enter to toggle selection on focused items.
+ *
+ * IMPORTANT: vlist positions items via `style.transform: translateY(offset)`.
+ * The shift must ADD to that existing offset, not replace it.
+ *
+ * Added methods: isSorting
+ * Added events: sort:start, sort:end, sort:cancel
+ */
+import type { VListItem } from "../../types";
+import type { VListFeature } from "../../builder/types";
+/** Sortable feature configuration */
+export interface SortableConfig {
+    /**
+     * CSS selector for the drag handle within each item.
+     * When set, only elements matching this selector initiate a drag.
+     * When omitted, the entire item is draggable.
+     *
+     * ```ts
+     * withSortable({ handle: '.drag-handle' })
+     * ```
+     */
+    handle?: string;
+    /**
+     * CSS class added to the drag ghost element (default: 'vlist-sort-ghost').
+     * The ghost is a clone of the dragged item that follows the pointer.
+     */
+    ghostClass?: string;
+    /**
+     * Transition duration for item shift animations in milliseconds (default: 150).
+     * Set to 0 for instant shifts.
+     */
+    shiftDuration?: number;
+    /**
+     * Size of the auto-scroll zone at viewport edges in pixels (default: 40).
+     * When the pointer enters this zone during drag, the list auto-scrolls.
+     */
+    edgeScrollZone?: number;
+    /**
+     * Auto-scroll speed in pixels per frame (default: 8).
+     */
+    edgeScrollSpeed?: number;
+    /**
+     * Minimum distance in pixels the pointer must move before drag starts (default: 5).
+     * Prevents accidental drags on click.
+     */
+    dragThreshold?: number;
+}
+/**
+ * Create a sortable feature for the builder.
+ *
+ * Enables drag-and-drop reordering of items in the virtual list.
+ *
+ * ```ts
+ * import { vlist } from 'vlist'
+ * import { withSortable } from 'vlist/sortable'
+ *
+ * const list = vlist({ ... })
+ *   .use(withSortable({ handle: '.drag-handle' }))
+ *   .build()
+ *
+ * list.on('sort:end', ({ fromIndex, toIndex }) => {
+ *   const reordered = [...items]
+ *   const [moved] = reordered.splice(fromIndex, 1)
+ *   reordered.splice(toIndex, 0, moved)
+ *   list.setItems(reordered)
+ * })
+ * ```
+ */
+export declare const withSortable: <T extends VListItem = VListItem>(config?: SortableConfig) => VListFeature<T>;
+//# sourceMappingURL=feature.d.ts.map

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

@@ -0,0 +1,6 @@
+/**
+ * vlist - Sortable Domain
+ * Drag-and-drop reordering for virtual lists
+ */
+export { withSortable, type SortableConfig } from "./feature";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/table/header.d.ts

@@ -37,7 +37,6 @@ import type { TableHeader, ColumnSortEvent, ColumnClickEvent } from "./types";
  * Create a TableHeader instance.
  *
  * @param root - The vlist root element (.vlist)
- * @param viewport - The vlist viewport element (for scroll sync)
  * @param headerHeight - Height of the header row in pixels
  * @param classPrefix - CSS class prefix (default: 'vlist')
  * @param onResize - Callback when a column is resized (receives column index and new width)
@@ -45,5 +44,5 @@ import type { TableHeader, ColumnSortEvent, ColumnClickEvent } from "./types";
  * @param onClick - Callback when any header cell is clicked
  * @returns TableHeader instance
  */
-export declare const createTableHeader: <T extends VListItem = VListItem>(root: HTMLElement, viewport: HTMLElement, headerHeight: number, classPrefix: string, onResize: (columnIndex: number, newWidth: number) => void, onSort?: (event: ColumnSortEvent) => void, onClick?: (event: ColumnClickEvent) => void) => TableHeader<T>;
+export declare const createTableHeader: <T extends VListItem = VListItem>(root: HTMLElement, headerHeight: number, classPrefix: string, onResize: (columnIndex: number, newWidth: number) => void, onSort?: (event: ColumnSortEvent) => void, onClick?: (event: ColumnClickEvent) => void) => TableHeader<T>;
 //# sourceMappingURL=header.d.ts.map

package/dist/index.d.ts

@@ -21,6 +21,8 @@ export { withMasonry } from "./features/masonry";
 export { withSelection } from "./features/selection";
 export { withSnapshots } from "./features/snapshots";
 export { withTable } from "./features/table";
+export { withSortable } from "./features/sortable";
+export type { SortableConfig } from "./features/sortable";
 export { withAutoSize } from "./features/autosize";
 export { createStats } from "./utils/stats";
 export type { Stats, StatsConfig, StatsState } from "./utils/stats";