@floor/vlist 1.1.2 → 1.2.1

package/README.md

@@ -2,19 +2,21 @@
 
 Lightweight, high-performance virtual list with zero dependencies and dimension-agnostic architecture.
 
+**v1.2.0** — [Changelog](./changelog.txt)
+
 [![npm version](https://img.shields.io/npm/v/%40floor%2Fvlist.svg)](https://www.npmjs.com/package/@floor/vlist)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/@floor/vlist)](https://bundlephobia.com/package/@floor/vlist)
-[![tests](https://img.shields.io/badge/tests-2268%20passing-brightgreen)](https://github.com/floor/vlist)
+[![tests](https://img.shields.io/badge/tests-2268_passing-brightgreen)](https://github.com/floor/vlist)
 [![license](https://img.shields.io/npm/l/vlist.svg)](https://github.com/floor/vlist/blob/main/LICENSE)
 
 - **Zero dependencies** — no external libraries
 - **Ultra memory efficient** — ~0.1-0.2 MB constant overhead regardless of dataset size
-- **~8 KB gzipped** — pay only for features you use (vs 20 KB+ monolithic alternatives)
+- **~8.4 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
+- **Grid, masonry, groups, async, selection, scale** — all opt-in
 - **Horizontal & vertical** — semantically correct orientation support
 - **Reverse, page-scroll, wrap** — every layout mode
-- **Accessible** — WAI-ARIA, keyboard navigation, screen-reader friendly
+- **Accessible** — WAI-ARIA, keyboard navigation, focus-visible, screen-reader friendly
 - **React, Vue, Svelte** — framework adapters available
 
 **30+ interactive examples → [vlist.dev](https://vlist.dev)**
@@ -24,9 +26,11 @@ Lightweight, high-performance virtual list with zero dependencies and dimension-
 
 - **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 groups** — sticky headers work in horizontal carousels
 - **Horizontal grid layouts** — 2D grids work in both orientations
 - **Masonry** — shortest-lane placement via `withMasonry()`
+- **Keyboard accessible** — focus-visible outlines, arrow/Home/End navigation, Tab support
+- **Responsive grid & masonry** — context-injected `columnWidth` auto-recalculates on resize
 
 ## Installation
 
@@ -63,7 +67,7 @@ list.on('item:click', ({ item }) => console.log(item))
 Start with the base, add only what you need:
 
 ```typescript
-import { vlist, withGrid, withSections, withSelection } from '@floor/vlist'
+import { vlist, withGrid, withGroups, withSelection } from '@floor/vlist'
 
 const list = vlist({
   container: '#app',
@@ -71,7 +75,7 @@ const list = vlist({
   item: { height: 200, template: renderPhoto },
 })
   .use(withGrid({ columns: 4, gap: 16 }))
-  .use(withSections({
+  .use(withGroups({
     getGroupForIndex: (i) => photos[i].category,
     headerHeight: 40,
     headerTemplate: (cat) => `<h2>${cat}</h2>`,
@@ -84,12 +88,12 @@ const list = vlist({
 
 | Feature | Size | Description |
 |---------|------|-------------|
-| **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 |
+| **Base** | 8.4 KB | Core virtualization |
+| `withGrid()` | +3.9 KB | 2D grid layout with context injection |
+| `withMasonry()` | +2.4 KB | Pinterest-style masonry layout |
+| `withGroups()` | +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 |
+| `withSelection()` | +1.7 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 |
@@ -125,7 +129,7 @@ const gallery = vlist({
 ### Sticky Headers
 
 ```typescript
-import { vlist, withSections } from '@floor/vlist'
+import { vlist, withGroups } from '@floor/vlist'
 
 const contacts = vlist({
   container: '#contacts',
@@ -135,7 +139,7 @@ const contacts = vlist({
     template: (contact) => `<div>${contact.name}</div>`,
   },
 })
-  .use(withSections({
+  .use(withGroups({
     getGroupForIndex: (i) => sortedContacts[i].lastName[0].toUpperCase(),
     headerHeight: 36,
     headerTemplate: (letter) => `<div class="header">${letter}</div>`,
@@ -176,9 +180,9 @@ const list = vlist({
 
 | Pattern | Key options |
 |---------|------------|
-| **Chat UI** | `reverse: true` + `withSections({ sticky: false })` |
+| **Chat UI** | `reverse: true` + `withGroups({ sticky: false })` |
 | **Horizontal carousel** | `orientation: 'horizontal'`, `item.width` |
-| **Horizontal sections** | `orientation: 'horizontal'` + `withSections()` |
+| **Horizontal groups** | `orientation: 'horizontal'` + `withGroups()` |
 | **Horizontal grid** | `orientation: 'horizontal'` + `withGrid()` |
 | **Masonry** | `withMasonry({ columns: 4, gap: 16 })` |
 | **Page-level scroll** | `withPage()` |
@@ -275,7 +279,7 @@ Each feature's config is fully typed — hover in your IDE for details.
 ```typescript
 withGrid({ columns: 4, gap: 16 })
 withMasonry({ columns: 4, gap: 16 })
-withSections({ getGroupForIndex, headerHeight, headerTemplate, sticky?: true })
+withGroups({ getGroupForIndex, headerHeight, headerTemplate, sticky?: true })
 withSelection({ mode: 'single' | 'multiple', initial?: [...ids] })
 withAsync({ adapter: { read }, loading?: { cancelThreshold? } })
 withScale()                           // no config — auto-activates at 16.7M px
@@ -337,10 +341,10 @@ This makes the codebase clearer and eliminates semantic confusion when working w
 
 | Configuration | Gzipped |
 |---------------|---------|
-| Base only | 8.1 KB |
-| + Grid | 11.9 KB |
-| + Sections | 12.2 KB |
-| + Async | 12.0 KB |
+| Base only | 8.4 KB |
+| + Grid | 12.3 KB |
+| + Groups | 12.6 KB |
+| + Async | 12.4 KB |
 
 ### Memory Efficiency
 

package/dist/builder/scroll.d.ts

@@ -2,7 +2,7 @@
  * vlist/builder — Scroll Utilities
  * Easing, scroll-argument resolution, and smooth scroll animation.
  *
- * Shared by builder/core.ts, grid feature, and sections feature to
+ * Shared by builder/core.ts, grid feature, and groups feature to
  * avoid duplicating ~70 lines of scroll helpers in each consumer.
  */
 import type { ScrollToOptions } from "../types";

package/dist/builder/types.d.ts

@@ -2,7 +2,7 @@
  * vlist/builder - Types
  * Feature interface, builder config, builder context, and return types
  */
-import type { VListItem, VListEvents, ItemConfig, ItemTemplate, Range, ViewportState, EventHandler, Unsubscribe, ScrollToOptions, ScrollSnapshot, VListAdapter, GridConfig, GroupsConfig, SelectionConfig, ScrollbarOptions } from "../types";
+import type { VListItem, VListEvents, ItemConfig, ItemTemplate, Range, ViewportState, EventHandler, Unsubscribe, ScrollToOptions, ScrollSnapshot, VListAdapter, GridConfig, MasonryConfig, GroupsConfig, SelectionConfig, ScrollbarOptions } from "../types";
 import type { DOMStructure, Renderer, SizeCache, CompressionContext } from "../rendering";
 import type { CompressionState } from "../rendering/viewport";
 import type { SimpleDataManager } from "./data";
@@ -54,10 +54,12 @@ export interface VListConfig<T extends VListItem = VListItem> extends Omit<Build
         /** Scrollbar mode (shorthand — same as top-level `scrollbar`). */
         scrollbar?: "native" | "none" | ScrollbarOptions;
     };
-    /** Layout mode (default: list). Set to `'grid'` with `grid` config to enable `withGrid()`. */
-    layout?: "list" | "grid";
+    /** Layout mode (default: list). Set to `'grid'` or `'masonry'` with matching config. */
+    layout?: "list" | "grid" | "masonry";
     /** Grid configuration — used when `layout` is `'grid'`. */
     grid?: GridConfig;
+    /** Masonry configuration — used when `layout` is `'masonry'`. */
+    masonry?: MasonryConfig;
     /** Async data adapter — enables `withAsync()`. Omit `items` when using an adapter. */
     adapter?: VListAdapter<T>;
     /** Loading behavior for async adapter. */
@@ -69,7 +71,7 @@ export interface VListConfig<T extends VListItem = VListItem> extends Omit<Build
         /** Number of items to preload in scroll direction. Default: 50 */
         preloadAhead?: number;
     };
-    /** Section grouping configuration — enables `withSections()`. */
+    /** Section grouping configuration — enables `withGroups()`. */
     groups?: GroupsConfig;
     /** Selection configuration — enables `withSelection()`. */
     selection?: SelectionConfig;

package/dist/features/{sections → groups}/feature.d.ts

@@ -1,6 +1,6 @@
 /**
  * vlist/groups - Builder Feature
- * Adds grouped lists with sticky section headers.
+ * Adds grouped lists with sticky headers.
  *
  * Priority: 10 (runs first — transforms item list and height function before rendering)
  *
@@ -39,8 +39,7 @@ export interface GroupsFeatureConfig {
  * Adds grouped lists with sticky section headers.
  *
  * ```ts
- * import { vlist } from 'vlist/builder'
- * import { withGroups } from 'vlist/groups'
+ * import { vlist, withGroups } from '@floor/vlist'
  *
  * const contacts = vlist({
  *   container: '#contacts',
@@ -60,5 +59,5 @@ export interface GroupsFeatureConfig {
  * .build()
  * ```
  */
-export declare const withSections: <T extends VListItem = VListItem>(config: GroupsFeatureConfig) => VListFeature<T>;
+export declare const withGroups: <T extends VListItem = VListItem>(config: GroupsFeatureConfig) => VListFeature<T>;
 //# sourceMappingURL=feature.d.ts.map

package/dist/features/{sections → groups}/index.d.ts

@@ -2,9 +2,9 @@
  * vlist - Groups Domain
  * Sticky headers and grouped lists
  */
-export { withSections, type GroupsFeatureConfig } from "./feature";
+export { withGroups, type GroupsFeatureConfig } from "./feature";
 export type { GroupsConfig, GroupBoundary, LayoutEntry, GroupHeaderItem, GroupLayout, StickyHeader, } from "./types";
-export { isGroupHeader, isGroupHeader as isSectionHeader } from "./types";
+export { isGroupHeader } from "./types";
 export { createGroupLayout, buildLayoutItems, createGroupedSizeFn, } from "./layout";
 export { createStickyHeader } from "./sticky";
 //# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,67 @@
+/**
+ * vlist/table - Builder Feature
+ * Switches from list layout to a data table with columns, resizable headers,
+ * sticky header row, and cell-based rendering.
+ *
+ * Priority: 10 (runs first — replaces the renderer before anything else renders)
+ *
+ * What it wires:
+ * - Replaces render functions — swaps the core render loop with table-aware rendering
+ * - Sticky header — creates a fixed header row above the viewport
+ * - Column layout — manages column widths, offsets, and resize logic
+ * - Resize interaction — drag handles on header column borders
+ * - Sort events — click on sortable header emits column:sort
+ * - Horizontal scroll sync — header scrolls in sync with the viewport
+ * - CSS class — adds .vlist--table to the root element
+ * - Variable row heights — supports fixed and function-based heights
+ *
+ * Critical design: This feature uses ctx.setRenderFns() to completely replace
+ * the core's render loop, NOT ctx.replaceRenderer() which is a no-op in the
+ * materialize context. This follows the same pattern as withGrid.
+ *
+ * Restrictions:
+ * - Cannot be combined with withGrid or withMasonry (conflicting layout modes)
+ * - Cannot be combined with orientation: 'horizontal' (tables are always vertical)
+ *
+ * Can be combined with:
+ * - withSelection (row selection works as-is)
+ * - withScrollbar (custom scrollbar)
+ * - withAsync (async data loading)
+ * - withSnapshots (scroll position save/restore)
+ * - withScale (large dataset compression)
+ */
+import type { VListItem } from "../../types";
+import type { VListFeature } from "../../builder/types";
+import type { TableConfig } from "./types";
+/** Table feature configuration — re-exported as TableFeatureConfig */
+export type TableFeatureConfig<T extends VListItem = VListItem> = TableConfig<T>;
+/**
+ * Create a table feature for the builder.
+ *
+ * Switches from list layout to a data table with column headers, resizable
+ * columns, and cell-based row rendering.
+ *
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withTable } from 'vlist/table'
+ *
+ * const table = vlist({
+ *   container: '#my-table',
+ *   item: { height: 40, template: () => '' },
+ *   items: users,
+ * })
+ * .use(withTable({
+ *   columns: [
+ *     { key: 'name',   label: 'Name',   width: 200 },
+ *     { key: 'email',  label: 'Email',  width: 300 },
+ *     { key: 'role',   label: 'Role',   width: 120 },
+ *   ],
+ *   rowHeight: 40,
+ *   headerHeight: 44,
+ *   resizable: true,
+ * }))
+ * .build()
+ * ```
+ */
+export declare const withTable: <T extends VListItem = VListItem>(config: TableFeatureConfig<T>) => VListFeature<T>;
+//# sourceMappingURL=feature.d.ts.map

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

@@ -0,0 +1,49 @@
+/**
+ * vlist/table - Header
+ * Manages the sticky header row that sits above the scrolling viewport.
+ *
+ * The header is a positioned DOM element inserted into the vlist root
+ * container (above the viewport, like the sticky group header). It contains
+ * one cell per column, each showing the column label. Resize handles are
+ * rendered at the right edge of each resizable column's header cell.
+ *
+ * Layout:
+ *   .vlist (root, position: relative)
+ *   ├── .vlist-table-header (position: absolute, top: 0, z-index: 5)
+ *   │   ├── .vlist-table-header-cell [col 0]
+ *   │   │   ├── .vlist-table-header-content (label)
+ *   │   │   ├── .vlist-table-header-sort (sort indicator)
+ *   │   │   └── .vlist-table-header-resize (drag handle)
+ *   │   ├── .vlist-table-header-cell [col 1]
+ *   │   │   └── ...
+ *   │   └── ...
+ *   └── .vlist-viewport (scrollable, top offset by headerHeight)
+ *
+ * Resize interaction:
+ *   mousedown on handle → pointermove updates column width → pointerup commits
+ *   During drag, a class is added to the root for cursor override.
+ *
+ * Sort interaction:
+ *   click on a sortable header cell emits column:sort via the provided callback.
+ *   The header renders a visual indicator (▲/▼) for the active sort column.
+ *
+ * Horizontal scroll sync:
+ *   The header's scrollLeft is kept in sync with the viewport's scrollLeft
+ *   via the `syncScroll` method, called from the feature's afterScroll hook.
+ */
+import type { VListItem } from "../../types";
+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)
+ * @param onSort - Callback when a sortable header is clicked
+ * @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>;
+//# sourceMappingURL=header.d.ts.map

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

@@ -0,0 +1,10 @@
+/**
+ * vlist - Table Domain
+ * Data table layout with columns, resizable headers, and cell rendering
+ */
+export { withTable, type TableFeatureConfig } from "./feature";
+export { createTableLayout } from "./layout";
+export { createTableHeader } from "./header";
+export { createTableRenderer, type TableRendererInstance } from "./renderer";
+export type { TableConfig, TableColumn, TableLayout, TableHeader, TableRenderer, ResolvedColumn, ColumnResizeEvent, ColumnSortEvent, ColumnClickEvent, } from "./types";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,26 @@
+/**
+ * vlist/table - Layout
+ * Manages column widths, offsets, and resize operations.
+ *
+ * Column width resolution strategy:
+ * 1. Columns with explicit `width` get their requested width (clamped to min/max)
+ * 2. Remaining container space is distributed equally among columns without `width`
+ * 3. If all columns have explicit widths and total < container, no stretching occurs
+ * 4. If total column width > container, the table scrolls horizontally
+ *
+ * All offset calculations are O(n) where n = number of columns (typically small).
+ * Resize operations recalculate offsets for columns after the resized one.
+ */
+import type { VListItem } from "../../types";
+import type { TableColumn, TableLayout } from "./types";
+/**
+ * Create a TableLayout instance.
+ *
+ * @param columnDefs - Column definitions from config
+ * @param globalMinWidth - Default min column width (from TableConfig.minColumnWidth)
+ * @param globalMaxWidth - Default max column width (from TableConfig.maxColumnWidth)
+ * @param globalResizable - Default resizable flag (from TableConfig.resizable)
+ * @returns TableLayout with column resolution and resize capabilities
+ */
+export declare const createTableLayout: <T extends VListItem = VListItem>(columnDefs: TableColumn<T>[], globalMinWidth?: number, globalMaxWidth?: number, globalResizable?: boolean) => TableLayout<T>;
+//# sourceMappingURL=layout.d.ts.map

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

@@ -0,0 +1,67 @@
+/**
+ * vlist/table - Renderer
+ * Renders virtualized rows with cell-based layout within the virtual scroll container.
+ *
+ * Each row is an absolutely positioned element (like the list renderer),
+ * containing child elements for each cell. Cells are sized and positioned
+ * according to the resolved column layout from TableLayout.
+ *
+ * Key design decisions:
+ * - Rows are the unit of virtualization (same as list mode — 1:1 with items)
+ * - Each row contains N cell elements (one per column)
+ * - Row positioning is translateY-based (from the size cache)
+ * - Cell positioning uses absolute left + width from the column layout
+ * - Element pooling avoids createElement cost (row-level pooling)
+ * - Change tracking skips template re-evaluation when data + state unchanged
+ * - Release grace period prevents boundary thrashing (hover blink, transition replay)
+ * - DocumentFragment batched insertion for new elements
+ *
+ * Performance:
+ * - O(1) Set-based visibility diffing (not O(n) .some())
+ * - Template re-evaluation skipped when item id + selection/focus state unchanged
+ * - Position update skipped when coordinates unchanged (position tracking)
+ * - Cell widths are only updated when column layout changes (not every scroll frame)
+ * - Released elements removed from DOM immediately, pooled for reuse
+ *
+ * DOM structure per row:
+ *   .vlist-item.vlist-table-row (position: absolute, translateY)
+ *   ├── .vlist-table-cell [col 0] (position: absolute, left, width)
+ *   ├── .vlist-table-cell [col 1]
+ *   └── ...
+ */
+import type { VListItem, Range } from "../../types";
+import type { SizeCache } from "../../rendering/sizes";
+import type { TableLayout, TableColumn } from "./types";
+/** Table renderer instance */
+export interface TableRendererInstance<T extends VListItem = VListItem> {
+    /** Render rows for a range, with cell-based layout */
+    render: (items: T[], range: Range, selectedIds: Set<string | number>, focusedIndex: number) => void;
+    /** Update a single row (e.g., after selection change) */
+    updateItem: (index: number, item: T, isSelected: boolean, isFocused: boolean) => void;
+    /** Update only CSS classes on a rendered row */
+    updateItemClasses: (index: number, isSelected: boolean, isFocused: boolean) => void;
+    /** Get rendered row element by item index */
+    getElement: (index: number) => HTMLElement | undefined;
+    /** Update cell positions and widths after column resize */
+    updateColumnLayout: (layout: TableLayout<T>) => void;
+    /** Clear all rendered rows */
+    clear: () => void;
+    /** Destroy renderer and cleanup */
+    destroy: () => void;
+}
+/**
+ * Create a TableRenderer instance.
+ *
+ * @param container - The .vlist-items container element
+ * @param sizeCache - Size cache for row offset lookups
+ * @param layout - Table layout for column widths/offsets
+ * @param columns - Column definitions (for cell templates)
+ * @param classPrefix - CSS class prefix
+ * @param ariaIdPrefix - Prefix for ARIA IDs
+ * @param columnBorders - Whether to show vertical borders between cells
+ * @param rowBorders - Whether to show horizontal borders between rows
+ * @param getTotalItems - Function to get total item count (for ARIA)
+ * @returns TableRendererInstance
+ */
+export declare const createTableRenderer: <T extends VListItem = VListItem>(container: HTMLElement, sizeCache: SizeCache, layout: TableLayout<T>, _columns: TableColumn<T>[], classPrefix: string, ariaIdPrefix: string, getTotalItems: () => number) => TableRendererInstance<T>;
+//# sourceMappingURL=renderer.d.ts.map