@floor/vlist 0.8.1 → 0.9.0

package/dist/rendering/viewport.d.ts

@@ -4,7 +4,7 @@
  *
  * Compression support is NOT imported here — it's injected via
  * CompressionState parameters. When compression is inactive
- * (the common case), all calculations use simple height-cache math
+ * (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 plugin
@@ -12,15 +12,15 @@
  * separately and pass the state in.
  */
 import type { Range, ViewportState } from "../types";
-import type { HeightCache } from "./heights";
+import type { SizeCache } from "./sizes";
 /** Compression calculation result */
 export interface CompressionState {
     /** Whether compression is active */
     isCompressed: boolean;
-    /** The actual total height */
-    actualHeight: number;
-    /** The virtual height (capped at MAX_VIRTUAL_HEIGHT) */
-    virtualHeight: number;
+    /** The actual total size (uncompressed) */
+    actualSize: number;
+    /** The virtual size (capped at MAX_VIRTUAL_HEIGHT) */
+    virtualSize: number;
     /** Compression ratio (1 = no compression, <1 = compressed) */
     ratio: number;
 }
@@ -30,23 +30,23 @@ export interface CompressionState {
  */
 export declare const NO_COMPRESSION: CompressionState;
 /**
- * Create a trivial compression state from a height cache.
+ * 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, heightCache: HeightCache) => CompressionState;
+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 = (scrollTop: number, containerHeight: number, heightCache: HeightCache, totalItems: number, compression: CompressionState, out: Range) => Range;
+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, heightCache: HeightCache, containerHeight: number, totalItems: number, compression: CompressionState, align: "start" | "center" | "end") => number;
+export type ScrollToIndexFn = (index: number, sizeCache: SizeCache, containerHeight: number, totalItems: number, compression: CompressionState, align: "start" | "center" | "end") => number;
 /**
- * Calculate visible range using height cache lookups.
+ * 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.
  */
@@ -59,27 +59,27 @@ export declare const simpleVisibleRange: VisibleRangeFn;
 export declare const calculateRenderRange: (visibleRange: Range, overscan: number, totalItems: number, out: Range) => Range;
 /**
  * Simple scroll-to-index calculation (non-compressed).
- * Uses height cache offsets directly.
+ * Uses size cache offsets directly.
  */
 export declare const simpleScrollToIndex: ScrollToIndexFn;
 /**
  * Calculate total content height.
- * Uses compression's virtualHeight when compressed, raw height otherwise.
+ * Uses compression's virtualSize when compressed, raw height otherwise.
  */
-export declare const calculateTotalHeight: (_totalItems: number, heightCache: HeightCache, compression?: CompressionState | null) => number;
+export declare const calculateTotalSize: (_totalItems: number, sizeCache: SizeCache, compression?: CompressionState | null) => number;
 /**
- * Calculate actual total height (without compression cap)
+ * Calculate actual total size (without compression cap)
  */
-export declare const calculateActualHeight: (_totalItems: number, heightCache: HeightCache) => number;
+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, heightCache: HeightCache) => number;
+export declare const calculateItemOffset: (index: number, sizeCache: SizeCache) => number;
 /**
  * Clamp scroll position to valid range
  */
-export declare const clampScrollPosition: (scrollTop: number, totalHeight: number, containerHeight: number) => number;
+export declare const clampScrollPosition: (scrollPosition: number, totalHeight: number, containerHeight: number) => number;
 /**
  * Determine scroll direction
  */
@@ -90,29 +90,29 @@ export declare const getScrollDirection: (currentScrollTop: number, previousScro
  * Accepts an optional `visibleRangeFn` so that compression-aware callers
  * can inject the compressed version. Defaults to `simpleVisibleRange`.
  */
-export declare const createViewportState: (containerHeight: number, heightCache: HeightCache, totalItems: number, overscan: number, compression: CompressionState, visibleRangeFn?: VisibleRangeFn) => ViewportState;
+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, scrollTop: number, heightCache: HeightCache, totalItems: number, overscan: number, compression: CompressionState, visibleRangeFn?: VisibleRangeFn) => ViewportState;
+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, heightCache: HeightCache, totalItems: number, overscan: number, compression: CompressionState, visibleRangeFn?: VisibleRangeFn) => ViewportState;
+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, heightCache: HeightCache, totalItems: number, overscan: number, compression: CompressionState, visibleRangeFn?: VisibleRangeFn) => ViewportState;
+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, heightCache: HeightCache, containerHeight: number, totalItems: number, align: "start" | "center" | "end" | undefined, compression: CompressionState, scrollToIndexFn?: ScrollToIndexFn) => number;
+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
  */

package/dist/types.d.ts

@@ -85,8 +85,8 @@ export interface ItemConfig<T extends VListItem = VListItem> {
      * }
      * ```
      *
-     * Required when `direction` is `'vertical'` (default).
-     * Optional when `direction` is `'horizontal'` (used as cross-axis size).
+     * Required when `orientation` is `'vertical'` (default).
+     * Optional when `orientation` is `'horizontal'` (used as cross-axis size).
      */
     height?: number | ((index: number, context?: GridHeightContext) => number);
     /**
@@ -95,8 +95,8 @@ export interface ItemConfig<T extends VListItem = VListItem> {
      * - `number` — Fixed width for all items (fast path, zero overhead)
      * - `(index: number) => number` — Variable width per item (prefix-sum based lookups)
      *
-     * Required when `direction` is `'horizontal'`.
-     * Ignored when `direction` is `'vertical'` (default).
+     * Required when `orientation` is `'horizontal'`.
+     * Ignored when `orientation` is `'vertical'` (default).
      */
     width?: number | ((index: number) => number);
     /** Template function to render each item */
@@ -107,7 +107,7 @@ export interface VListConfig<T extends VListItem = VListItem> {
     /** Container element or selector */
     container: HTMLElement | string;
     /**
-     * Scroll direction (default: 'vertical').
+     * Layout orientation (default: 'vertical').
      *
      * - `'vertical'` — Standard top-to-bottom scrolling (default)
      * - `'horizontal'` — Left-to-right scrolling (carousel, timeline, etc.)
@@ -120,7 +120,7 @@ export interface VListConfig<T extends VListItem = VListItem> {
      *
      * Cannot be combined with `groups`, `grid`, or `reverse`.
      */
-    direction?: "vertical" | "horizontal";
+    orientation?: "vertical" | "horizontal";
     /** Item configuration (height and template) */
     item: ItemConfig<T>;
     /** Static items array (optional if using adapter) */
@@ -411,14 +411,14 @@ export interface Range {
 }
 /** Viewport state */
 export interface ViewportState {
-    /** Current scroll position */
-    scrollTop: number;
-    /** Container height */
-    containerHeight: number;
-    /** Total content height (may be capped for compression) */
-    totalHeight: number;
-    /** Actual total height without compression (totalItems × itemHeight) */
-    actualHeight: number;
+    /** Current scroll position along main axis (scrollTop for vertical, scrollLeft for horizontal) */
+    scrollPosition: number;
+    /** Container size along main axis (height for vertical, width for horizontal) */
+    containerSize: number;
+    /** Total content size (may be capped for compression) */
+    totalSize: number;
+    /** Actual total size without compression */
+    actualSize: number;
     /** Whether compression is active */
     isCompressed: boolean;
     /** Compression ratio (1 = no compression, <1 = compressed) */
@@ -449,7 +449,7 @@ export interface VListEvents<T extends VListItem = VListItem> extends EventMap {
     };
     /** Scroll position changed */
     scroll: {
-        scrollTop: number;
+        scrollPosition: number;
         direction: "up" | "down";
     };
     /** Scroll velocity changed */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floor/vlist",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Lightweight, high-performance virtual list with zero dependencies",
   "author": {
     "name": "Floor IO",

package/dist/rendering/heights.d.ts

@@ -1,63 +0,0 @@
-/**
- * vlist - Height Cache
- * Efficient height management for fixed and variable item heights
- *
- * Provides two implementations:
- * - Fixed: O(1) operations using multiplication (zero overhead, matches existing behavior)
- * - Variable: O(1) offset lookup via prefix sums, O(log n) binary search for index-at-offset
- *
- * The HeightCache abstraction allows all virtual scrolling and compression code
- * to work identically with both fixed and variable heights.
- */
-/** Height cache for efficient offset/index lookups */
-export interface HeightCache {
-    /** Get offset (Y position) for an item index — O(1) */
-    getOffset(index: number): number;
-    /** Get height of a specific item */
-    getHeight(index: number): number;
-    /** Find item index at a scroll offset — O(1) fixed, O(log n) variable */
-    indexAtOffset(offset: number): number;
-    /** Total content height */
-    getTotalHeight(): number;
-    /** Current total item count */
-    getTotal(): number;
-    /** Rebuild cache (call when items change) */
-    rebuild(totalItems: number): void;
-    /** Whether heights are variable (false = fixed fast path) */
-    isVariable(): boolean;
-}
-/**
- * Create a height cache — returns fixed or variable implementation
- *
- * When height is a number, returns a zero-overhead fixed implementation.
- * When height is a function, builds a prefix-sum array for efficient lookups.
- */
-export declare const createHeightCache: (height: number | ((index: number) => number), initialTotal: number) => HeightCache;
-/**
- * Count how many items fit in a given container height starting from startIndex
- * Used for compressed mode visible range calculations
- *
- * For fixed heights: O(1) via division
- * For variable heights: O(k) where k = visible item count (typically 10-50)
- */
-export declare const countVisibleItems: (heightCache: HeightCache, startIndex: number, containerHeight: number, totalItems: number) => number;
-/**
- * Count how many items fit starting from the bottom of the list
- * Used for near-bottom interpolation in compressed mode
- *
- * For fixed heights: O(1) via division
- * For variable heights: O(k) where k = items fitting (typically 10-50)
- */
-export declare const countItemsFittingFromBottom: (heightCache: HeightCache, containerHeight: number, totalItems: number) => number;
-/**
- * Calculate the pixel offset for a fractional virtual scroll index
- *
- * In compressed mode, the scroll position maps to a fractional item index
- * (e.g., 5.3 means 30% into item 5). This function calculates the actual
- * pixel offset for such a fractional position using variable heights.
- *
- * For fixed heights this reduces to: virtualIndex * itemHeight
- * For variable heights: offset(floor) + frac * height(floor)
- */
-export declare const getOffsetForVirtualIndex: (heightCache: HeightCache, virtualIndex: number, totalItems: number) => number;
-//# sourceMappingURL=heights.d.ts.map