@floor/vlist 0.5.7 → 0.6.0

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

@@ -0,0 +1,29 @@
+/**
+ * vlist - Grid Layout
+ * Pure O(1) calculations for mapping between flat item indices and grid positions.
+ *
+ * The grid transforms a flat list into rows:
+ *   Items:  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+ *   Grid (columns=4):
+ *     Row 0: [0, 1, 2, 3]
+ *     Row 1: [4, 5, 6, 7]
+ *     Row 2: [8, 9]          ← partially filled last row
+ *
+ * All operations are O(1) — integer division and modulo only.
+ */
+import type { GridConfig, GridLayout } from "./types";
+/**
+ * Extended grid config with optional groups support
+ */
+export interface GridConfigWithGroups extends GridConfig {
+    /** Optional: check if an item index is a group header (for groups-aware layout) */
+    isHeaderFn?: (index: number) => boolean;
+}
+/**
+ * Create a GridLayout instance.
+ *
+ * @param config - Grid configuration (columns, gap, optional isHeaderFn)
+ * @returns GridLayout with O(1) mapping functions (or groups-aware if isHeaderFn provided)
+ */
+export declare const createGridLayout: (config: GridConfigWithGroups) => GridLayout;
+//# sourceMappingURL=layout.d.ts.map

package/dist/features/grid/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/features/grid/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAA2B,MAAM,SAAS,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,UAAU;IACtD,mFAAmF;IACnF,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CACzC;AAMD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,oBAAoB,KAAG,UA4R/D,CAAC"}

package/dist/features/grid/plugin.d.ts

@@ -0,0 +1,48 @@
+/**
+ * vlist/grid - Builder Plugin
+ * Switches from list layout to a 2D grid with configurable columns and gap.
+ *
+ * Priority: 10 (runs first — replaces the renderer before anything else renders)
+ *
+ * What it wires:
+ * - Replaces renderer — swaps the list renderer with a grid renderer
+ * - Redefines virtual total — the virtualizer sees rows, not items
+ * - Column width calculation — recalculated on resize
+ * - Item positioning — each item gets translateX (column) and translateY (row)
+ * - CSS class — adds .vlist--grid to the root element
+ *
+ * Restrictions:
+ * - Cannot be combined with direction: 'horizontal'
+ * - Cannot be combined with reverse: true
+ *
+ * Can be combined with withGroups for grouped 2D layouts.
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../builder/types";
+/** Grid plugin configuration */
+export interface GridPluginConfig {
+    /** Number of columns (required, >= 1) */
+    columns: number;
+    /** Gap between items in pixels (default: 0) */
+    gap?: number;
+}
+/**
+ * Create a grid plugin for the builder.
+ *
+ * Switches from list layout to a 2D grid with configurable columns and gap.
+ *
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withGrid } from 'vlist/grid'
+ *
+ * const gallery = vlist({
+ *   container: '#gallery',
+ *   item: { height: 200, template: renderPhoto },
+ *   items: photos,
+ * })
+ * .use(withGrid({ columns: 4, gap: 8 }))
+ * .build()
+ * ```
+ */
+export declare const withGrid: <T extends VListItem = VListItem>(config: GridPluginConfig) => VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/features/grid/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/features/grid/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAUvE,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAEhB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,SAAS,GAAG,SAAS,EACtD,QAAQ,gBAAgB,KACvB,WAAW,CAAC,CAAC,CA4Zf,CAAC"}

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

@@ -0,0 +1,55 @@
+/**
+ * vlist - Grid Renderer
+ * Renders items in a 2D grid layout within the virtual scroll container.
+ *
+ * Extends the base renderer pattern but positions items using both
+ * row offsets (translateY from the height cache) and column offsets
+ * (translateX calculated from column index and container width).
+ *
+ * Key differences from the list renderer:
+ * - Items are positioned with translate(x, y) instead of just translateY(y)
+ * - Item width is set to columnWidth (containerWidth / columns - gaps)
+ * - The "index" in the rendered map is the FLAT ITEM INDEX (not row index)
+ * - Row offsets come from the height cache (which operates on row indices)
+ * - Column offsets are calculated from itemIndex % columns
+ */
+import type { VListItem, ItemTemplate, Range } from "../../types";
+import type { HeightCache } from "../../rendering/heights";
+import type { CompressionContext } from "../../rendering/renderer";
+import type { GridLayout } from "./types";
+/** Grid renderer instance */
+export interface GridRenderer<T extends VListItem = VListItem> {
+    /** Render items for a flat item range, positioned in a 2D grid */
+    render: (items: T[], range: Range, selectedIds: Set<string | number>, focusedIndex: number, compressionCtx?: CompressionContext) => void;
+    /** Update item positions (for compressed scrolling) */
+    updatePositions: (compressionCtx: CompressionContext) => void;
+    /** Update a single item */
+    updateItem: (index: number, item: T, isSelected: boolean, isFocused: boolean) => void;
+    /** Update only CSS classes on a rendered item (no template re-evaluation) */
+    updateItemClasses: (index: number, isSelected: boolean, isFocused: boolean) => void;
+    /** Get rendered item element by flat item index */
+    getElement: (index: number) => HTMLElement | undefined;
+    /** Update container width (call on resize) */
+    updateContainerWidth: (width: number) => void;
+    /** Clear all rendered items */
+    clear: () => void;
+    /** Destroy renderer and cleanup */
+    destroy: () => void;
+}
+/**
+ * Create a grid renderer for managing DOM elements in a 2D layout.
+ *
+ * The grid renderer receives flat item ranges (not row ranges) and
+ * positions each item at the correct (row, col) coordinate.
+ *
+ * @param itemsContainer - The DOM element that holds rendered items
+ * @param template - Item template function
+ * @param heightCache - Height cache operating on ROW indices
+ * @param gridLayout - Grid layout for row/col calculations
+ * @param classPrefix - CSS class prefix
+ * @param initialContainerWidth - Initial container width for column sizing
+ * @param totalItemsGetter - Optional getter for total item count (for aria-setsize)
+ * @param ariaIdPrefix - Optional unique prefix for element IDs (for aria-activedescendant)
+ */
+export declare const createGridRenderer: <T extends VListItem = VListItem>(itemsContainer: HTMLElement, template: ItemTemplate<T>, heightCache: HeightCache, gridLayout: GridLayout, classPrefix: string, initialContainerWidth: number, totalItemsGetter?: () => number, ariaIdPrefix?: string) => GridRenderer<T>;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/features/grid/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../src/features/grid/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EAEZ,KAAK,EAEN,MAAM,aAAa,CAAC;AAOrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAO1C,6BAA6B;AAC7B,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAC3D,kEAAkE;IAClE,MAAM,EAAE,CACN,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EACjC,YAAY,EAAE,MAAM,EACpB,cAAc,CAAC,EAAE,kBAAkB,KAChC,IAAI,CAAC;IAEV,uDAAuD;IACvD,eAAe,EAAE,CAAC,cAAc,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAE9D,2BAA2B;IAC3B,UAAU,EAAE,CACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,EACP,UAAU,EAAE,OAAO,EACnB,SAAS,EAAE,OAAO,KACf,IAAI,CAAC;IAEV,6EAA6E;IAC7E,iBAAiB,EAAE,CACjB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,OAAO,EACnB,SAAS,EAAE,OAAO,KACf,IAAI,CAAC;IAEV,mDAAmD;IACnD,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;IAEvD,8CAA8C;IAC9C,oBAAoB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9C,+BAA+B;IAC/B,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB,mCAAmC;IACnC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAoDD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,SAAS,GAAG,SAAS,EAChE,gBAAgB,WAAW,EAC3B,UAAU,YAAY,CAAC,CAAC,CAAC,EACzB,aAAa,WAAW,EACxB,YAAY,UAAU,EACtB,aAAa,MAAM,EACnB,uBAAuB,MAAM,EAC7B,mBAAmB,MAAM,MAAM,EAC/B,eAAe,MAAM,KACpB,YAAY,CAAC,CAAC,CAmahB,CAAC"}

package/dist/features/grid/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * vlist - Grid Types
+ * Types for grid/card layout mode
+ *
+ * Grid layout transforms a flat list of items into a 2D grid where:
+ * - Virtualization operates on ROWS (not individual items)
+ * - Each row contains `columns` items side by side
+ * - Items are positioned using row/column coordinates
+ * - Compression applies to row count, not item count
+ */
+import type { GridConfig } from "../../types";
+export type { GridConfig };
+/** Row/column position of an item */
+export interface GridPosition {
+    /** Row index (0-based) */
+    row: number;
+    /** Column index (0-based) */
+    col: number;
+}
+/** Flat item range corresponding to a row range */
+export interface ItemRange {
+    /** First item index (inclusive) */
+    start: number;
+    /** Last item index (inclusive) */
+    end: number;
+}
+/**
+ * GridLayout — maps between flat item indices and row/column positions.
+ *
+ * The virtualizer sees "rows" as its unit of work. Each row contains
+ * up to `columns` items. The last row may be partially filled.
+ *
+ * All operations are O(1) — just integer division and modulo.
+ */
+export interface GridLayout {
+    /** Number of columns */
+    readonly columns: number;
+    /** Gap between items in pixels */
+    readonly gap: number;
+    /** Update grid configuration without recreating the layout */
+    update: (config: Partial<GridConfig>) => void;
+    /** Get total number of rows for a given item count */
+    getTotalRows: (totalItems: number) => number;
+    /** Get the row/col position for a flat item index */
+    getPosition: (itemIndex: number) => GridPosition;
+    /** Get the row index for a flat item index */
+    getRow: (itemIndex: number) => number;
+    /** Get the column index for a flat item index */
+    getCol: (itemIndex: number) => number;
+    /**
+     * Get the flat item range for a range of rows.
+     * The last row may be partially filled (end is clamped to totalItems - 1).
+     */
+    getItemRange: (rowStart: number, rowEnd: number, totalItems: number) => ItemRange;
+    /**
+     * Get the flat item index from a row and column.
+     * Returns -1 if out of bounds.
+     */
+    getItemIndex: (row: number, col: number, totalItems: number) => number;
+    /**
+     * Calculate column width given container width.
+     * Accounts for gaps: width = (containerWidth - (columns - 1) * gap) / columns
+     */
+    getColumnWidth: (containerWidth: number) => number;
+    /**
+     * Calculate the X offset for a column index.
+     * offset = col * (columnWidth + gap)
+     */
+    getColumnOffset: (col: number, containerWidth: number) => number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/features/grid/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/features/grid/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,YAAY,EAAE,UAAU,EAAE,CAAC;AAM3B,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IAEZ,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IAEd,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,kCAAkC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,8DAA8D;IAC9D,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IAE9C,sDAAsD;IACtD,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAE7C,qDAAqD;IACrD,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,YAAY,CAAC;IAEjD,8CAA8C;IAC9C,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAEtC,iDAAiD;IACjD,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAEtC;;;OAGG;IACH,YAAY,EAAE,CACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,KACf,SAAS,CAAC;IAEf;;;OAGG;IACH,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAEvE;;;OAGG;IACH,cAAc,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,MAAM,CAAC;IAEnD;;;OAGG;IACH,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,KAAK,MAAM,CAAC;CAClE"}

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

@@ -0,0 +1,8 @@
+/**
+ * vlist/window - Window Scroll Mode Plugin
+ *
+ * Entry point for the window scroll plugin.
+ */
+export { withPage } from "./plugin";
+export type { VListPlugin } from "../../builder/types";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/page/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/page/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/features/page/plugin.d.ts

@@ -0,0 +1,53 @@
+/**
+ * vlist/window - Window Scroll Mode Plugin
+ *
+ * Enables the list to scroll with the page instead of in its own container.
+ * Useful for infinite feeds, full-page lists, and chat UIs that integrate
+ * with page scroll.
+ *
+ * Priority: 5 (runs early, before other plugins that depend on scroll)
+ *
+ * What it does:
+ * - Uses window as scroll target instead of viewport element
+ * - Calculates scroll position relative to document
+ * - Uses window.innerWidth/innerHeight for container dimensions
+ * - Listens to window resize events instead of ResizeObserver
+ * - Adjusts DOM styles (overflow: visible, height: auto)
+ *
+ * Bundle impact: ~0.3 KB gzipped when used
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../builder/types";
+/**
+ * Create a window scroll mode plugin.
+ *
+ * Use this when you want your list to scroll with the page instead of
+ * in a fixed-height container.
+ *
+ * @example
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withWindow } from 'vlist/window'
+ *
+ * const feed = vlist({
+ *   container: '#infinite-feed',
+ *   item: { height: 200, template: renderPost },
+ *   items: posts
+ * })
+ * .use(withWindow())
+ * .build()
+ * ```
+ *
+ * @example Horizontal window scrolling
+ * ```ts
+ * const timeline = vlist({
+ *   container: '#timeline',
+ *   item: { height: 100, template: renderEvent },
+ *   direction: 'horizontal'
+ * })
+ * .use(withWindow())
+ * .build()
+ * ```
+ */
+export declare const withPage: <T extends VListItem = VListItem>() => VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/features/page/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/features/page/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,QAAQ,GACnB,CAAC,SAAS,SAAS,GAAG,SAAS,OAC5B,WAAW,CAAC,CAAC,CA6HjB,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * vlist - Compression Sub-module
+ * Re-exports compression utilities for tree-shakeable imports
+ *
+ * Usage: import { getCompressionInfo } from 'vlist/compression'
+ * Usage: import { withScale } from 'vlist/compression'
+ */
+export { MAX_VIRTUAL_HEIGHT, getCompressionState, needsCompression, getMaxItemsWithoutCompression, getCompressionInfo, calculateCompressedVisibleRange, calculateCompressedRenderRange, calculateCompressedItemPosition, calculateCompressedScrollToIndex, calculateIndexFromScrollPosition, type CompressionState, } from "../../rendering/scale";
+export { withScale } from "./plugin";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/scale/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/scale/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,6BAA6B,EAC7B,kBAAkB,EAClB,+BAA+B,EAC/B,8BAA8B,EAC9B,+BAA+B,EAC/B,gCAAgC,EAChC,gCAAgC,EAChC,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/features/scale/plugin.d.ts

@@ -0,0 +1,42 @@
+/**
+ * vlist/compression - Builder Plugin
+ * Enables support for lists with 1M+ items by compressing the scroll space
+ * when the total height exceeds the browser's ~16.7M pixel limit.
+ *
+ * Priority: 20 (runs before scrollbar, after grid/groups)
+ *
+ * What it wires:
+ * - Scroll mode switch — transitions from native to compressed scrolling when needed
+ * - Scroll position mapping — maps compressed scroll positions to item indices
+ * - Item positioning — positions items relative to viewport in compressed mode
+ * - Custom scrollbar fallback — forces custom scrollbar in compressed mode
+ * - Near-bottom interpolation — smooth blending near the end of the list
+ * - Cached compression state — recalculates only when total item count changes
+ *
+ * No configuration needed — compression activates automatically when the total
+ * height exceeds the browser limit, and deactivates when items are removed.
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../builder/types";
+/**
+ * Create a compression plugin for the builder.
+ *
+ * Enables support for lists with 1M+ items. No configuration needed —
+ * compression activates automatically when the total height exceeds
+ * the browser's ~16.7M pixel limit.
+ *
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withCompression } from 'vlist/compression'
+ *
+ * const list = vlist({
+ *   container: '#app',
+ *   item: { height: 48, template: renderItem },
+ *   items: millionItems,
+ * })
+ * .use(withCompression())
+ * .build()
+ * ```
+ */
+export declare const withScale: <T extends VListItem = VListItem>() => VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/features/scale/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/features/scale/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAevE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,SAAS,GACpB,CAAC,SAAS,SAAS,GAAG,SAAS,OAC5B,WAAW,CAAC,CAAC,CA2QjB,CAAC"}

package/dist/features/scrollbar/controller.d.ts

@@ -0,0 +1,121 @@
+/**
+ * vlist - Scroll Controller
+ * Handles both native scrolling and manual wheel-based scrolling for compressed lists
+ *
+ * When compression is active (large lists exceeding browser height limits),
+ * we switch from native scrolling to manual wheel event handling.
+ * This allows smooth scrolling through millions of items.
+ */
+import type { CompressionState } from "../../rendering/scale";
+/** Scroll direction */
+export type ScrollDirection = "up" | "down";
+/** Scroll event data */
+export interface ScrollEventData {
+    scrollTop: number;
+    direction: ScrollDirection;
+    velocity: number;
+}
+/** Scroll controller configuration */
+export interface ScrollControllerConfig {
+    /** Enable compressed scroll mode (manual wheel handling) */
+    compressed?: boolean;
+    /** Compression state for calculating bounds */
+    compression?: CompressionState;
+    /**
+     * External scroll element for window/document scrolling.
+     * When set, the controller listens to this element's scroll events
+     * and computes list-relative positions from the viewport's bounding rect.
+     */
+    scrollElement?: Window;
+    /** Allow mouse wheel to scroll (default: true) */
+    wheel?: boolean;
+    /** Wheel sensitivity multiplier (default: 1) */
+    sensitivity?: number;
+    /** Enable smooth scrolling interpolation */
+    smoothing?: boolean;
+    /** Scroll idle detection timeout in ms (default: 150) */
+    idleTimeout?: number;
+    /**
+     * Enable horizontal scrolling mode.
+     * When true, the controller reads scrollLeft instead of scrollTop,
+     * uses clientWidth instead of clientHeight, and maps wheel deltaX.
+     */
+    horizontal?: boolean;
+    /** Callback when scroll position changes */
+    onScroll?: (data: ScrollEventData) => void;
+    /** Callback when scrolling becomes idle */
+    onIdle?: () => void;
+}
+/** Scroll controller instance */
+export interface ScrollController {
+    /** Get current scroll position */
+    getScrollTop: () => number;
+    /** Set scroll position */
+    scrollTo: (position: number, smooth?: boolean) => void;
+    /** Scroll by delta */
+    scrollBy: (delta: number) => void;
+    /** Check if at top */
+    isAtTop: () => boolean;
+    /** Check if at bottom */
+    isAtBottom: (threshold?: number) => boolean;
+    /** Get scroll percentage (0-1) */
+    getScrollPercentage: () => number;
+    /** Get current scroll velocity (px/ms, absolute value) */
+    getVelocity: () => number;
+    /**
+     * Check if the velocity tracker is actively tracking with enough samples.
+     * Returns false during ramp-up (first few frames of a new scroll gesture)
+     * when the tracker doesn't have enough samples yet.
+     */
+    isTracking: () => boolean;
+    /** Check if currently scrolling */
+    isScrolling: () => boolean;
+    /** Update configuration (e.g., when compression state changes) */
+    updateConfig: (config: Partial<ScrollControllerConfig>) => void;
+    /** Enable compressed mode */
+    enableCompression: (compression: CompressionState) => void;
+    /** Disable compressed mode (revert to native scroll) */
+    disableCompression: () => void;
+    /** Check if compressed mode is active */
+    isCompressed: () => boolean;
+    /** Check if in window scroll mode */
+    isWindowMode: () => boolean;
+    /**
+     * Update the container height used for scroll calculations.
+     * In window mode, call this when the window resizes.
+     */
+    updateContainerHeight: (height: number) => void;
+    /** Destroy and cleanup */
+    destroy: () => void;
+}
+/**
+ * Create a scroll controller for a viewport element
+ *
+ * Supports two modes:
+ * 1. Native scrolling (default) - uses browser's built-in scroll
+ * 2. Compressed scrolling - manual wheel handling for large lists
+ */
+export declare const createScrollController: (viewport: HTMLElement, config?: ScrollControllerConfig) => ScrollController;
+/**
+ * Throttle scroll handler using requestAnimationFrame
+ */
+export declare const rafThrottle: <T extends (...args: any[]) => void>(fn: T) => ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+/**
+ * Check if scroll position is at bottom
+ */
+export declare const isAtBottom: (scrollTop: number, scrollHeight: number, clientHeight: number, threshold?: number) => boolean;
+/**
+ * Check if scroll position is at top
+ */
+export declare const isAtTop: (scrollTop: number, threshold?: number) => boolean;
+/**
+ * Get scroll percentage (0-1)
+ */
+export declare const getScrollPercentage: (scrollTop: number, scrollHeight: number, clientHeight: number) => number;
+/**
+ * Check if a range is visible in the scroll viewport
+ */
+export declare const isRangeVisible: (rangeStart: number, rangeEnd: number, visibleStart: number, visibleEnd: number) => boolean;
+//# sourceMappingURL=controller.d.ts.map

package/dist/features/scrollbar/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../src/features/scrollbar/controller.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,8 @@
+/**
+ * vlist - Scroll Domain
+ * Scroll controller and custom scrollbar
+ */
+export { withScrollbar, type ScrollbarPluginConfig } from "./plugin";
+export { createScrollController, rafThrottle, isAtBottom, isAtTop, getScrollPercentage, isRangeVisible, type ScrollController, type ScrollControllerConfig, type ScrollEventData, type ScrollDirection, } from "./controller";
+export { createScrollbar, type Scrollbar, type ScrollbarConfig, type ScrollCallback, } from "./scrollbar";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/scrollbar/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/scrollbar/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,aAAa,EAAE,KAAK,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGrE,OAAO,EACL,sBAAsB,EACtB,WAAW,EACX,UAAU,EACV,OAAO,EACP,mBAAmB,EACnB,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC"}

package/dist/features/scrollbar/plugin.d.ts

@@ -0,0 +1,60 @@
+/**
+ * vlist/scroll - Builder Plugin
+ * Wraps the custom scrollbar into a VListPlugin for the composable builder.
+ *
+ * Priority: 30 (runs after renderer/data setup but before selection)
+ *
+ * What it wires:
+ * - DOM elements — track, thumb, and optional hover zone appended to viewport
+ * - CSS class — .vlist-viewport--custom-scrollbar hides native scrollbar
+ * - Drag handlers — mousedown on thumb, mousemove/mouseup on document
+ * - Track click — click on track to jump to position
+ * - Hover handlers — mouseenter/leave on track, hover zone, and viewport
+ * - Scroll sync — updates thumb position on every scroll frame
+ * - Resize sync — updates thumb size when container or content height changes
+ *
+ * No public methods are added — the scrollbar is entirely automatic.
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../builder/types";
+/** Scrollbar plugin configuration */
+export interface ScrollbarPluginConfig {
+    /** Auto-hide scrollbar after idle (default: true) */
+    autoHide?: boolean;
+    /** Auto-hide delay in milliseconds (default: 1000) */
+    autoHideDelay?: number;
+    /** Minimum thumb size in pixels (default: 30) */
+    minThumbSize?: number;
+    /**
+     * Show scrollbar when hovering near the scrollbar edge (default: true).
+     * When true, an invisible hover zone is placed along the scrollbar edge.
+     */
+    showOnHover?: boolean;
+    /**
+     * Width of the invisible hover zone in pixels (default: 16).
+     * Only used when `showOnHover` is true.
+     */
+    hoverZoneWidth?: number;
+    /**
+     * Show scrollbar when the mouse enters the list viewport (default: true).
+     * When false, the scrollbar only appears on scroll or hover near edge.
+     */
+    showOnViewportEnter?: boolean;
+}
+/**
+ * Create a scrollbar plugin for the builder.
+ *
+ * Replaces the native browser scrollbar with a custom, cross-browser
+ * consistent scrollbar.
+ *
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withScrollbar } from 'vlist/scroll'
+ *
+ * const list = vlist({ ... })
+ *   .use(withScrollbar({ autoHide: true, autoHideDelay: 1000 }))
+ *   .build()
+ * ```
+ */
+export declare const withScrollbar: <T extends VListItem = VListItem>(config?: ScrollbarPluginConfig) => VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/features/scrollbar/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/features/scrollbar/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAQvE,qCAAqC;AACrC,MAAM,WAAW,qBAAqB;IACpC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,SAAS,GAAG,SAAS,EAC3D,SAAS,qBAAqB,KAC7B,WAAW,CAAC,CAAC,CAgFf,CAAC"}

package/dist/features/scrollbar/scrollbar.d.ts

@@ -0,0 +1,73 @@
+/**
+ * vlist - Custom Scrollbar
+ * Provides visual scroll indication for compressed mode where native scrollbar is hidden
+ *
+ * Features:
+ * - Visual track and thumb
+ * - Thumb size proportional to visible content
+ * - Click on track to jump to position
+ * - Drag thumb to scroll
+ * - Auto-hide after idle (optional)
+ * - Show on hover with configurable hover zone (optional)
+ * - CSS variables for customization
+ * - Horizontal mode support (direction-aware axis)
+ */
+/** Scrollbar configuration */
+export interface ScrollbarConfig {
+    /** Enable scrollbar (default: true when compressed) */
+    enabled?: boolean;
+    /** Auto-hide scrollbar after idle (default: true) */
+    autoHide?: boolean;
+    /** Auto-hide delay in milliseconds (default: 1000) */
+    autoHideDelay?: number;
+    /** Minimum thumb size in pixels (default: 30) */
+    minThumbSize?: number;
+    /**
+     * Show scrollbar when hovering near the scrollbar edge (default: true).
+     * When true, an invisible hover zone is placed along the scrollbar edge.
+     * Moving the mouse into this zone reveals the scrollbar; it stays visible
+     * as long as the cursor remains over the zone or the track.
+     */
+    showOnHover?: boolean;
+    /**
+     * Width of the invisible hover zone in pixels (default: 16).
+     * Only used when `showOnHover` is true.
+     * A wider zone makes the scrollbar easier to discover;
+     * a narrower zone avoids interference with content near the edge.
+     */
+    hoverZoneWidth?: number;
+    /**
+     * Show scrollbar when the mouse enters the list viewport (default: true).
+     * When false, the scrollbar only appears on scroll or when hovering
+     * near the scrollbar edge (if `showOnHover` is true).
+     */
+    showOnViewportEnter?: boolean;
+}
+/** Scrollbar instance */
+export interface Scrollbar {
+    /** Show the scrollbar */
+    show: () => void;
+    /** Hide the scrollbar */
+    hide: () => void;
+    /** Update scrollbar dimensions based on content/container size */
+    updateBounds: (totalHeight: number, containerHeight: number) => void;
+    /** Update thumb position based on scroll position */
+    updatePosition: (scrollTop: number) => void;
+    /** Check if scrollbar is visible */
+    isVisible: () => boolean;
+    /** Destroy and cleanup */
+    destroy: () => void;
+}
+/** Callback for scroll position changes */
+export type ScrollCallback = (position: number) => void;
+/**
+ * Create a scrollbar instance
+ *
+ * @param viewport - The viewport element to attach scrollbar to
+ * @param onScroll - Callback when scrollbar interaction causes scroll
+ * @param config - Scrollbar configuration
+ * @param classPrefix - CSS class prefix (default: 'vlist')
+ * @param horizontal - Whether the scrollbar is horizontal (default: false)
+ */
+export declare const createScrollbar: (viewport: HTMLElement, onScroll: ScrollCallback, config?: ScrollbarConfig, classPrefix?: string, horizontal?: boolean) => Scrollbar;
+//# sourceMappingURL=scrollbar.d.ts.map

package/dist/features/scrollbar/scrollbar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrollbar.d.ts","sourceRoot":"","sources":["../../../src/features/scrollbar/scrollbar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,yBAAyB;AACzB,MAAM,WAAW,SAAS;IACxB,yBAAyB;IACzB,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB,yBAAyB;IACzB,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB,kEAAkE;IAClE,YAAY,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC;IAErE,qDAAqD;IACrD,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAE5C,oCAAoC;IACpC,SAAS,EAAE,MAAM,OAAO,CAAC;IAEzB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;AAiBxD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,WAAW,EACrB,UAAU,cAAc,EACxB,SAAQ,eAAoB,EAC5B,oBAAqB,EACrB,oBAAkB,KACjB,SA4XF,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * vlist - Groups Domain
+ * Sticky headers and grouped lists
+ */
+export { withSections, type GroupsPluginConfig } from "./plugin";
+export type { GroupsConfig, GroupBoundary, LayoutEntry, GroupHeaderItem, GroupLayout, StickyHeader, } from "./types";
+export { isGroupHeader, isGroupHeader as isSectionHeader } from "./types";
+export { createGroupLayout, buildLayoutItems, createGroupedHeightFn, } from "./layout";
+export { createStickyHeader } from "./sticky";
+//# sourceMappingURL=index.d.ts.map