vlist 2.2.0 → 2.4.0

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