vlist 2.3.0 → 2.4.1

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

@@ -1,121 +0,0 @@
-/**
- * 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" | "left" | "right";
-/** 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;
-    /**
-     * Primary axis is X (horizontal scrolling mode).
-     * When true, the controller reads scrollLeft instead of scrollTop,
-     * uses clientWidth instead of clientHeight, and maps wheel deltaX.
-     */
-    isX?: 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/rendering/measured.d.ts

@@ -1,52 +0,0 @@
-/**
- * vlist - Measured Size Cache
- * Auto-measurement support for items with unknown sizes (Mode B)
- *
- * Wraps the existing variable SizeCache with measurement tracking.
- * Once an item is measured, it behaves identically to Mode A (known size).
- * Unmeasured items use the estimated size as a fallback.
- *
- * Fully axis-neutral: works identically for vertical (estimatedHeight)
- * and horizontal (estimatedWidth) orientations. This cache stores plain
- * numbers representing the main-axis dimension — it never knows whether
- * those numbers are heights or widths. The axis-specific translation
- * happens in builder/core.ts at the DOM boundary.
- *
- * Implements the SizeCache interface so all downstream code
- * (viewport, scale, features) works unchanged.
- */
-import type { SizeCache } from "./sizes";
-/** Extended SizeCache with measurement tracking */
-export interface MeasuredSizeCache extends SizeCache {
-    /** Record actual measured size for an item */
-    setMeasuredSize(index: number, size: number): void;
-    /** Check if an item has been measured */
-    isMeasured(index: number): boolean;
-    /** Get the estimated size (used for unmeasured items) */
-    getEstimatedSize(): number;
-    /** Number of items that have been measured */
-    measuredCount(): number;
-}
-/**
- * Create a measured size cache for auto-measurement (Mode B)
- *
- * Works for both orientations:
- *   - Vertical:   estimatedSize = estimatedHeight, measures block size
- *   - Horizontal: estimatedSize = estimatedWidth, measures inline size
- *
- * The cache itself is axis-neutral — it only stores numbers. The caller
- * (builder/core.ts) is responsible for reading the correct axis from
- * the config and from ResizeObserver entries (blockSize vs inlineSize).
- *
- * Internally maintains a Map of measured sizes keyed by item index.
- * Unmeasured items fall back to the estimated size. The underlying
- * prefix-sum array is rebuilt when measurements change.
- *
- * The size function fed into the variable SizeCache becomes:
- *   (index) => measuredSizes.has(index) ? measuredSizes.get(index) : estimatedSize
- *
- * This means all existing viewport, compression, and range calculations
- * work unchanged — they only see a SizeCache with variable sizes.
- */
-export declare const createMeasuredSizeCache: (estimatedSize: number, initialTotal: number) => MeasuredSizeCache;
-//# sourceMappingURL=measured.d.ts.map

package/dist/rendering/renderer.d.ts

@@ -1,113 +0,0 @@
-/**
- * vlist - DOM Rendering
- * Efficient DOM rendering with element pooling
- * Supports compression for large lists (1M+ items)
- */
-import type { VListItem, ItemTemplate, Range } from "../types";
-import type { CompressionState } from "./viewport";
-import type { SizeCache } from "./sizes";
-/**
- * Optional compression position calculator.
- * Injected by the monolithic factory or the withCompression feature.
- * When not provided, the renderer uses simple sizeCache offsets.
- */
-export type CompressedPositionFn = (index: number, scrollTop: number, sizeCache: SizeCache, totalItems: number, containerHeight: number, compression: CompressionState, rangeStart?: number) => number;
-/**
- * Optional compression state getter.
- * Injected by the monolithic factory or the withCompression feature.
- * When not provided, the renderer assumes no compression.
- */
-export type CompressionStateFn = (totalItems: number, sizeCache: SizeCache) => CompressionState;
-/** Element pool for recycling DOM elements */
-export interface ElementPool {
-    /** Get an element from the pool (or create new) */
-    acquire: () => HTMLElement;
-    /** Return an element to the pool */
-    release: (element: HTMLElement) => void;
-    /** Clear the pool */
-    clear: () => void;
-    /** Get pool statistics */
-    stats: () => {
-        poolSize: number;
-        created: number;
-        reused: number;
-    };
-}
-/** Compression context for positioning */
-export interface CompressionContext {
-    scrollPosition: number;
-    totalItems: number;
-    containerSize: number;
-    rangeStart: number;
-    /** Pre-computed compression state (includes force flag) */
-    compression?: CompressionState;
-}
-/** DOM structure created by createDOMStructure */
-export interface DOMStructure {
-    root: HTMLElement;
-    viewport: HTMLElement;
-    content: HTMLElement;
-    items: HTMLElement;
-    /** Visually-hidden live region for screen reader announcements */
-    liveRegion: HTMLElement;
-}
-/** Renderer instance */
-export interface Renderer<T extends VListItem = VListItem> {
-    /** Render items for a range */
-    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 index */
-    getElement: (index: number) => HTMLElement | undefined;
-    /**
-     * Reorder DOM children to match logical item order (by data-index).
-     * Called on scroll idle so screen readers encounter items in the correct
-     * sequence. Items are position:absolute so visual layout is unaffected.
-     */
-    sortDOM: () => void;
-    /** Clear all rendered items */
-    clear: () => void;
-    /** Destroy renderer and cleanup */
-    destroy: () => void;
-}
-/**
- * Create an element pool for recycling DOM elements
- * Reduces garbage collection and improves performance
- */
-export declare const createElementPool: (tagName?: string, maxSize?: number) => ElementPool;
-/**
- * Create a renderer for managing DOM elements
- * Supports compression for large lists
- */
-export declare const createRenderer: <T extends VListItem = VListItem>(itemsContainer: HTMLElement, template: ItemTemplate<T>, sizeCache: SizeCache, classPrefix: string, totalItemsGetter?: () => number, ariaIdPrefix?: string, isX?: boolean, crossAxisSize?: number, compressionFns?: {
-    getState: CompressionStateFn;
-    getPosition: CompressedPositionFn;
-}, striped?: boolean | "data" | "even" | "odd", stripeIndexFn?: () => (index: number) => number, ariaPosInSetGetter?: (layoutIndex: number) => number, interactive?: boolean) => Renderer<T>;
-/**
- * Create the vlist DOM structure
- */
-export declare const createDOMStructure: (container: HTMLElement, classPrefix: string, ariaLabel?: string, isX?: boolean, interactive?: boolean) => DOMStructure;
-/**
- * Update content height for virtual scrolling
- */
-export declare const updateContentHeight: (content: HTMLElement, totalHeight: number) => void;
-/**
- * Update content width for horizontal virtual scrolling
- */
-export declare const updateContentWidth: (content: HTMLElement, totalWidth: number) => void;
-/**
- * Get container dimensions
- */
-export declare const getContainerDimensions: (viewport: HTMLElement) => {
-    width: number;
-    height: number;
-};
-/**
- * Resolve container from selector or element
- */
-export declare const resolveContainer: (container: HTMLElement | string) => HTMLElement;
-//# sourceMappingURL=renderer.d.ts.map

package/dist/rendering/scale.d.ts

@@ -1,121 +0,0 @@
-/**
- * vlist - Compression Module
- * Pure functions for handling large lists that exceed browser size limits
- *
- * When a list's total size (sum of all item sizes) exceeds the browser's
- * maximum element size (~16.7M pixels), we "compress" the virtual scroll space.
- *
- * Key concepts:
- * - actualSize: The true size if all items were rendered
- * - virtualSize: The capped size used for the scroll container (≤ MAX_VIRTUAL_SIZE)
- * - compressionRatio: virtualSize / actualSize (1 = no compression, <1 = compressed)
- *
- * When compressed:
- * - Scroll position maps to item index via ratio, not pixel math
- * - Item positions are calculated relative to a "virtual index" at current scroll
- * - Near-bottom interpolation ensures the last items are reachable
- */
-import type { Range } from "../types";
-import { MAX_VIRTUAL_SIZE } from "../constants";
-import type { SizeCache } from "./sizes";
-export { MAX_VIRTUAL_SIZE };
-/** Compression calculation result */
-export interface CompressionState {
-    /** Whether compression is active */
-    isCompressed: boolean;
-    /** The actual total size (uncompressed) */
-    actualSize: number;
-    /** The virtual size (capped at MAX_VIRTUAL_SIZE) */
-    virtualSize: number;
-    /** Compression ratio (1 = no compression, <1 = compressed) */
-    ratio: number;
-}
-/**
- * Calculate compression state for a list
- * Pure function - no side effects
- *
- * @param _totalItems - Total number of items
- * @param sizeCache - Size cache for item sizes/offsets
- * @param force - When true, enables compressed mode even if total size is under the limit.
- *   Useful for testing, consistent UX, or preemptively enabling compression
- *   before the list grows past the browser limit.
- */
-export declare const getCompressionState: (_totalItems: number, sizeCache: SizeCache, force?: boolean) => CompressionState;
-/**
- * Calculate visible range with compression support
- * Pure function - no side effects
- *
- * @param scrollTop - Current scroll position
- * @param containerHeight - Viewport container height
- * @param sizeCache - Size cache for item sizes/offsets
- * @param totalItems - Total number of items
- * @param compression - Compression state
- * @param out - Output range to mutate (avoids allocation on hot path)
- */
-export declare const calculateCompressedVisibleRange: (scrollPosition: number, containerHeight: number, sizeCache: SizeCache, totalItems: number, compression: CompressionState, out: Range) => Range;
-/**
- * Calculate render range with compression support (adds overscan)
- * Pure function - no side effects
- *
- * @param out - Output range to mutate (avoids allocation on hot path)
- */
-export declare const calculateCompressedRenderRange: (visibleRange: Range, overscan: number, totalItems: number, out: Range) => Range;
-/**
- * Calculate item position (translateY) with compression support
- * Pure function - no side effects
- *
- * In compressed mode (manual wheel scrolling, overflow: hidden), items are
- * positioned RELATIVE TO THE VIEWPORT. The scroll container doesn't actually
- * scroll - we intercept wheel events and manually position items.
- *
- * Key insight:
- * - Calculate a "virtual scroll index" from the scroll ratio
- * - Items are positioned relative to this virtual index using actual heights
- * - Each item keeps its full height for proper rendering
- *
- * @param index - Item index
- * @param scrollTop - Current (virtual) scroll position
- * @param sizeCache - Size cache for item sizes/offsets
- * @param totalItems - Total number of items
- * @param containerHeight - Viewport container height
- * @param compression - Compression state
- */
-export declare const calculateCompressedItemPosition: (index: number, scrollPosition: number, sizeCache: SizeCache, totalItems: number, _containerHeight: number, compression: CompressionState, _rangeStart?: number) => number;
-/**
- * Calculate scroll position to bring an index into view (with compression)
- * Pure function - no side effects
- *
- * @param index - Target item index
- * @param sizeCache - Size cache for item sizes/offsets
- * @param containerHeight - Viewport container height
- * @param totalItems - Total number of items
- * @param compression - Compression state
- * @param align - Alignment within viewport
- */
-export declare const calculateCompressedScrollToIndex: (index: number, sizeCache: SizeCache, containerHeight: number, totalItems: number, compression: CompressionState, align?: "start" | "center" | "end") => number;
-/**
- * Calculate the approximate item index at a given scroll position
- * Useful for debugging and scroll position restoration
- * Pure function - no side effects
- */
-export declare const calculateIndexFromScrollPosition: (scrollPosition: number, sizeCache: SizeCache, totalItems: number, compression: CompressionState) => number;
-/**
- * Check if compression is needed for a list configuration
- * Pure function - no side effects
- *
- * Note: This overload accepts a HeightCache for variable heights.
- * For simple fixed-height checks, use needsCompressionFixed().
- */
-export declare const needsCompression: (totalItems: number, heightOrCache: number | SizeCache) => boolean;
-/**
- * Calculate maximum items supported without compression
- * Only meaningful for fixed-height items
- * Pure function - no side effects
- */
-export declare const getMaxItemsWithoutCompression: (itemSize: number) => number;
-/**
- * Get human-readable compression info for debugging
- * Pure function - no side effects
- */
-export declare const getCompressionInfo: (totalItems: number, sizeCache: SizeCache, force?: boolean) => string;
-//# sourceMappingURL=scale.d.ts.map

package/dist/rendering/scroll.d.ts

@@ -1,23 +0,0 @@
-/**
- * vlist - Smart Edge Scroll
- * Shared scroll utility used by both core baseline and withSelection feature.
- * Only scrolls when the target item is outside the viewport; aligns to nearest edge.
- *
- * Split into two functions for tree-shaking:
- * - scrollToFocusSimple: normal mode only (used by base builder)
- * - scrollToFocus: handles both normal and compressed modes (used by features)
- */
-import type { SizeCache } from "./sizes";
-import type { CompressionState } from "./scale";
-import type { Range } from "../types";
-/**
- * Simple scroll-to-focus: normal (non-compressed) mode only.
- * Padding-aware: accounts for CSS padding on the content element.
- */
-export declare const scrollToFocusSimple: (index: number, sizeCache: SizeCache, scrollPosition: number, containerSize: number, startPadding?: number, endPadding?: number) => number;
-/**
- * Full scroll-to-focus: handles both normal and compressed (withScale) modes.
- * Used by withSelection feature which must work with compression.
- */
-export declare const scrollToFocus: (index: number, sizeCache: SizeCache, scrollPosition: number, containerSize: number, startPadding?: number, endPadding?: number, compression?: CompressionState | null, totalItems?: number, visibleRange?: Range | null) => number;
-//# sourceMappingURL=scroll.d.ts.map

package/dist/rendering/viewport.d.ts

@@ -1,139 +0,0 @@
-/**
- * vlist - Virtual Scrolling Core
- * Pure functions for virtual scroll calculations
- *
- * Compression support is NOT imported here — it's injected via
- * CompressionState parameters. When compression is inactive
- * (the common case), all calculations use simple size-cache math
- * with zero dependency on the compression module.
- *
- * This keeps the builder core lightweight. The withCompression feature
- * and the monolithic createVList entry point import compression
- * separately and pass the state in.
- */
-import type { Range, ViewportState } from "../types";
-import type { SizeCache } from "./sizes";
-/** Compression calculation result */
-export interface CompressionState {
-    /** Whether compression is active */
-    isCompressed: boolean;
-    /** The actual total size (uncompressed) */
-    actualSize: number;
-    /** The virtual size (capped at MAX_VIRTUAL_SIZE) */
-    virtualSize: number;
-    /** Compression ratio (1 = no compression, <1 = compressed) */
-    ratio: number;
-}
-/**
- * A "no compression" state for lists that don't need it.
- * Used by the builder core when withCompression is not installed.
- */
-export declare const NO_COMPRESSION: CompressionState;
-/**
- * Create a trivial compression state from a size cache.
- * No compression logic — just reads the total height.
- * For use when the full compression module is not loaded.
- */
-export declare const getSimpleCompressionState: (_totalItems: number, sizeCache: SizeCache) => CompressionState;
-/**
- * Signature for the function that calculates the visible item range.
- * The compression module provides a version that handles compressed scroll;
- * virtual.ts provides a simple fallback for non-compressed lists.
- */
-export type VisibleRangeFn = (scrollPosition: number, containerHeight: number, sizeCache: SizeCache, totalItems: number, compression: CompressionState, out: Range) => Range;
-/**
- * Signature for the scroll-to-index calculator.
- */
-export type ScrollToIndexFn = (index: number, sizeCache: SizeCache, containerHeight: number, totalItems: number, compression: CompressionState, align: "start" | "center" | "end") => number;
-/**
- * Calculate visible range using size cache lookups.
- * Fast path for lists that don't need compression (< ~350 000 items at 48px).
- * Mutates `out` to avoid allocation on the scroll hot path.
- */
-export declare const simpleVisibleRange: VisibleRangeFn;
-/**
- * Calculate render range (adds overscan around visible range).
- * This function is compression-agnostic — works for both paths.
- * Mutates `out` to avoid allocation on the scroll hot path.
- */
-export declare const calculateRenderRange: (visibleRange: Range, overscan: number, totalItems: number, out: Range) => Range;
-/**
- * Simple scroll-to-index calculation (non-compressed).
- * Uses size cache offsets directly.
- */
-export declare const simpleScrollToIndex: ScrollToIndexFn;
-/**
- * Calculate total content height.
- * Uses compression's virtualSize when compressed, raw height otherwise.
- */
-export declare const calculateTotalSize: (_totalItems: number, sizeCache: SizeCache, compression?: CompressionState | null) => number;
-/**
- * Calculate actual total size (without compression cap)
- */
-export declare const calculateActualSize: (_totalItems: number, sizeCache: SizeCache) => number;
-/**
- * Calculate the offset (translateY) for an item
- * For non-compressed lists only
- */
-export declare const calculateItemOffset: (index: number, sizeCache: SizeCache) => number;
-/**
- * Clamp scroll position to valid range
- */
-export declare const clampScrollPosition: (scrollPosition: number, totalHeight: number, containerHeight: number) => number;
-/**
- * Determine scroll direction
- */
-export declare const getScrollDirection: (currentScrollTop: number, previousScrollTop: number, isX?: boolean) => "up" | "down" | "left" | "right";
-/**
- * Create initial viewport state.
- *
- * Accepts an optional `visibleRangeFn` so that compression-aware callers
- * can inject the compressed version. Defaults to `simpleVisibleRange`.
- */
-export declare const createViewportState: (containerHeight: number, sizeCache: SizeCache, totalItems: number, overscan: number, compression: CompressionState, visibleRangeFn?: VisibleRangeFn) => ViewportState;
-/**
- * Update viewport state after scroll.
- * Mutates state in place for performance on the scroll hot path.
- */
-export declare const updateViewportState: (state: ViewportState, scrollPosition: number, sizeCache: SizeCache, totalItems: number, overscan: number, compression: CompressionState, visibleRangeFn?: VisibleRangeFn) => ViewportState;
-/**
- * Update viewport state when container resizes.
- * Mutates state in place for performance.
- */
-export declare const updateViewportSize: (state: ViewportState, containerHeight: number, sizeCache: SizeCache, totalItems: number, overscan: number, compression: CompressionState, visibleRangeFn?: VisibleRangeFn) => ViewportState;
-/**
- * Update viewport state when total items changes.
- * Mutates state in place for performance.
- */
-export declare const updateViewportItems: (state: ViewportState, sizeCache: SizeCache, totalItems: number, overscan: number, compression: CompressionState, visibleRangeFn?: VisibleRangeFn) => ViewportState;
-/**
- * Calculate scroll position to bring an index into view.
- *
- * Accepts an optional `scrollToIndexFn` so that compression-aware callers
- * can inject the compressed version. Defaults to `simpleScrollToIndex`.
- */
-export declare const calculateScrollToIndex: (index: number, sizeCache: SizeCache, containerHeight: number, totalItems: number, align: "start" | "center" | "end" | undefined, compression: CompressionState, scrollToIndexFn?: ScrollToIndexFn) => number;
-/**
- * Check if two ranges are equal
- */
-export declare const rangesEqual: (a: Range, b: Range) => boolean;
-/**
- * Check if an index is within a range
- */
-export declare const isInRange: (index: number, range: Range) => boolean;
-/**
- * Get the count of items in a range
- */
-export declare const getRangeCount: (range: Range) => number;
-/**
- * Create an array of indices from a range
- */
-export declare const rangeToIndices: (range: Range) => number[];
-/**
- * Calculate which indices need to be added/removed when range changes
- */
-export declare const diffRanges: (oldRange: Range, newRange: Range) => {
-    add: number[];
-    remove: number[];
-};
-//# sourceMappingURL=viewport.d.ts.map