@pdanpdan/virtual-scroll 0.3.0 → 0.5.0

package/src/utils/fenwick-tree.test.ts

@@ -4,15 +4,15 @@ import { FenwickTree } from './fenwick-tree';
 
 describe('fenwickTree', () => {
   describe('initialization', () => {
-    it('should initialize with correct size', () => {
+    it('initializes with correct size', () => {
       const tree = new FenwickTree(5);
       expect(tree.query(5)).toBe(0);
       expect(tree.length).toBe(5);
     });
   });
 
-  describe('query and update', () => {
-    it('should update and query values', () => {
+  describe('updates & queries', () => {
+    it('updates and queries values', () => {
       const tree = new FenwickTree(5);
       tree.update(0, 10);
       tree.update(1, 20);
@@ -24,7 +24,7 @@ describe('fenwickTree', () => {
       expect(tree.query(3)).toBe(60);
     });
 
-    it('should handle updates to existing indices', () => {
+    it('handles updates to existing indices', () => {
       const tree = new FenwickTree(3);
       tree.update(1, 10);
       expect(tree.query(2)).toBe(10);
@@ -32,7 +32,7 @@ describe('fenwickTree', () => {
       expect(tree.query(2)).toBe(15);
     });
 
-    it('should ignore updates for out of bounds indices', () => {
+    it('ignores updates for out of bounds indices', () => {
       const tree = new FenwickTree(5);
       tree.update(-1, 10);
       tree.update(5, 10);
@@ -40,22 +40,29 @@ describe('fenwickTree', () => {
     });
   });
 
-  describe('search and bounds', () => {
-    it('should find lower bound correctly', () => {
-      const tree = new FenwickTree(5);
-      tree.update(0, 10); // sum up to 1: 10
-      tree.update(1, 10); // sum up to 2: 20
-      tree.update(2, 10); // sum up to 3: 30
+  describe('value access', () => {
+    it('returns the individual value at an index', () => {
+      const tree = new FenwickTree(3);
+      tree.update(0, 10);
+      expect(tree.get(0)).toBe(10);
+      expect(tree.get(-1)).toBe(0);
+      expect(tree.get(10)).toBe(0);
+    });
 
-      expect(tree.findLowerBound(5)).toBe(0);
-      expect(tree.findLowerBound(15)).toBe(1);
-      expect(tree.findLowerBound(25)).toBe(2);
-      expect(tree.findLowerBound(35)).toBe(5); // Returns size when not found
+    it('returns the underlying values array', () => {
+      const tree = new FenwickTree(3);
+      tree.update(0, 10);
+      tree.update(1, 20);
+      const values = tree.getValues();
+      expect(values).toBeInstanceOf(Float64Array);
+      expect(values[ 0 ]).toBe(10);
+      expect(values[ 1 ]).toBe(20);
+      expect(values[ 2 ]).toBe(0);
     });
   });
 
-  describe('rebuild and resize', () => {
-    it('should set and rebuild correctly', () => {
+  describe('rebuild & resize', () => {
+    it('sets and rebuilds correctly', () => {
       const tree = new FenwickTree(5);
       tree.set(0, 10);
       tree.set(1, 20);
@@ -67,7 +74,7 @@ describe('fenwickTree', () => {
       expect(tree.query(3)).toBe(60);
     });
 
-    it('should resize and preserve existing values', () => {
+    it('resizes and preserves existing values', () => {
       const tree = new FenwickTree(5);
       tree.update(0, 10);
       tree.resize(10);
@@ -77,36 +84,29 @@ describe('fenwickTree', () => {
     });
   });
 
-  describe('values access', () => {
-    it('should return the individual value at an index', () => {
-      const tree = new FenwickTree(3);
-      tree.update(0, 10);
-      expect(tree.get(0)).toBe(10);
-      expect(tree.get(-1)).toBe(0);
-      expect(tree.get(10)).toBe(0);
-    });
+  describe('search & bounds', () => {
+    it('finds lower bound correctly', () => {
+      const tree = new FenwickTree(5);
+      tree.update(0, 10); // sum up to 1: 10
+      tree.update(1, 10); // sum up to 2: 20
+      tree.update(2, 10); // sum up to 3: 30
 
-    it('should return the underlying values array', () => {
-      const tree = new FenwickTree(3);
-      tree.update(0, 10);
-      tree.update(1, 20);
-      const values = tree.getValues();
-      expect(values).toBeInstanceOf(Float64Array);
-      expect(values[ 0 ]).toBe(10);
-      expect(values[ 1 ]).toBe(20);
-      expect(values[ 2 ]).toBe(0);
+      expect(tree.findLowerBound(5)).toBe(0);
+      expect(tree.findLowerBound(15)).toBe(1);
+      expect(tree.findLowerBound(25)).toBe(2);
+      expect(tree.findLowerBound(35)).toBe(5); // Returns size when not found
     });
   });
 
-  describe('shift', () => {
-    it('should do nothing when offset is 0', () => {
+  describe('shift operations', () => {
+    it('does nothing when offset is 0', () => {
       const tree = new FenwickTree(3);
       tree.update(0, 10);
       tree.shift(0);
       expect(tree.get(0)).toBe(10);
     });
 
-    it('should shift values forward when offset is positive', () => {
+    it('shifts values forward when offset is positive', () => {
       const tree = new FenwickTree(5);
       tree.update(0, 10);
       tree.update(1, 20);
@@ -119,7 +119,7 @@ describe('fenwickTree', () => {
       expect(tree.query(4)).toBe(30);
     });
 
-    it('should shift values backward when offset is negative', () => {
+    it('shifts values backward when offset is negative', () => {
       const tree = new FenwickTree(5);
       tree.update(2, 10);
       tree.update(3, 20);

package/src/utils/fenwick-tree.ts

@@ -1,20 +1,28 @@
 /**
  * Fenwick Tree (Binary Indexed Tree) implementation for efficient
  * prefix sum calculations and updates.
+ *
+ * Provides O(log n) time complexity for both point updates and prefix sum queries.
  */
 export class FenwickTree {
   private tree: Float64Array;
   private values: Float64Array;
 
+  /**
+   * Creates a new Fenwick Tree with the specified size.
+   *
+   * @param size - The number of elements in the tree.
+   */
   constructor(size: number) {
     this.tree = new Float64Array(size + 1);
     this.values = new Float64Array(size);
   }
 
   /**
-   * Update the value at a specific index and propagate changes.
-   * @param index 0-based index
-   * @param delta The change in value (new value - old value)
+   * Update the value at a specific index and propagate changes throughout the tree.
+   *
+   * @param index - The 0-based index to update.
+   * @param delta - The change in value (new value - old value).
    */
   update(index: number, delta: number): void {
     if (index < 0 || index >= this.values.length) {
@@ -31,8 +39,9 @@ export class FenwickTree {
 
   /**
    * Get the prefix sum up to a specific index (exclusive).
-   * @param index 0-based index. query(n) returns sum of values from 0 to n-1.
-   * @returns Sum of values in range [0, index)
+   *
+   * @param index - 0-based index. `query(n)` returns sum of values from index 0 to n-1.
+   * @returns Sum of values in range [0, index).
    */
   query(index: number): number {
     let sum = 0;
@@ -44,8 +53,11 @@ export class FenwickTree {
   }
 
   /**
-   * Set the individual value at an index without updating the tree.
-   * Call rebuild() after multiple sets to update the tree efficiently.
+   * Set the individual value at an index without updating the prefix sum tree.
+   * Call `rebuild()` after multiple sets to update the tree efficiently in O(n).
+   *
+   * @param index - The 0-based index.
+   * @param value - The new value.
    */
   set(index: number, value: number): void {
     if (index < 0 || index >= this.values.length) {
@@ -62,14 +74,19 @@ export class FenwickTree {
   }
 
   /**
-   * Get the individual value at an index.
+   * Get the individual value at a specific index.
+   *
+   * @param index - The 0-based index.
+   * @returns The value at the specified index.
    */
   get(index: number): number {
     return this.values[ index ] || 0;
   }
 
   /**
-   * Get the underlying values array.
+   * Get the underlying values array as a read-only Float64Array.
+   *
+   * @returns The read-only values array.
    */
   getValues(): Readonly<Float64Array> {
     return this.values;
@@ -77,9 +94,10 @@ export class FenwickTree {
 
   /**
    * Find the largest index such that the prefix sum is less than or equal to the given value.
-   * Useful for finding which item is at a specific scroll offset.
-   * @param value The prefix sum value to search for
-   * @returns The 0-based index
+   * Highly efficient search used to find which item is at a specific scroll offset.
+   *
+   * @param value - The prefix sum value to search for.
+   * @returns The 0-based index.
    */
   findLowerBound(value: number): number {
     let index = 0;
@@ -101,8 +119,8 @@ export class FenwickTree {
   }
 
   /**
-   * Rebuild the entire tree from the current values array in O(N).
-   * Useful after bulk updates to the values array.
+   * Rebuild the entire prefix sum tree from the current values array.
+   * Time complexity: O(n).
    */
   rebuild(): void {
     this.tree.fill(0);
@@ -118,8 +136,9 @@ export class FenwickTree {
   }
 
   /**
-   * Resize the tree while preserving existing values.
-   * @param size New size of the tree
+   * Resize the tree while preserving existing values and rebuilding the prefix sums.
+   *
+   * @param size - The new size of the tree.
    */
   resize(size: number): void {
     if (size === this.values.length) {
@@ -135,8 +154,9 @@ export class FenwickTree {
 
   /**
    * Shift values by a given offset and rebuild the tree.
-   * Useful when items are prepended to the list.
-   * @param offset Number of positions to shift (positive for prepending)
+   * Useful when items are prepended to the list to maintain existing measurements.
+   *
+   * @param offset - Number of positions to shift. Positive for prepending (shifts right).
    */
   shift(offset: number): void {
     if (offset === 0) {

package/src/utils/scroll.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, it } from 'vitest';
+
+import { getPaddingX, getPaddingY, isBody, isElement, isScrollableElement, isScrollToIndexOptions, isWindow, isWindowLike } from './scroll';
+
+describe('scroll utils', () => {
+  describe('element type guards', () => {
+    describe('iswindow', () => {
+      it('returns true for null', () => {
+        expect(isWindow(null)).toBe(true);
+      });
+
+      it('returns true for window object', () => {
+        expect(isWindow(window)).toBe(true);
+      });
+
+      it('returns true for document.documentelement object', () => {
+        expect(isWindow(document.documentElement)).toBe(true);
+      });
+
+      it('returns false for an element', () => {
+        const el = document.createElement('div');
+        expect(isWindow(el)).toBe(false);
+      });
+
+      it('returns false for undefined', () => {
+        expect(isWindow(undefined)).toBe(false);
+      });
+    });
+
+    describe('isbody', () => {
+      it('returns true for document.body', () => {
+        expect(isBody(document.body)).toBe(true);
+      });
+
+      it('returns false for null', () => {
+        expect(isBody(null)).toBe(false);
+      });
+
+      it('returns false for undefined', () => {
+        expect(isBody(undefined)).toBe(false);
+      });
+
+      it('returns false for a string', () => {
+        // @ts-expect-error testing invalid input
+        expect(isBody('not an object')).toBe(false);
+      });
+
+      it('returns false for a plain object', () => {
+        // @ts-expect-error testing invalid input
+        expect(isBody({})).toBe(false);
+      });
+
+      it('returns false for a div', () => {
+        const el = document.createElement('div');
+        expect(isBody(el)).toBe(false);
+      });
+
+      it('returns false for window', () => {
+        expect(isBody(window)).toBe(false);
+      });
+
+      it('returns false for document.documentelement', () => {
+        expect(isBody(document.documentElement)).toBe(false);
+      });
+    });
+
+    describe('iswindowlike', () => {
+      it('returns true for window', () => {
+        expect(isWindowLike(window)).toBe(true);
+      });
+
+      it('returns true for document.documentelement', () => {
+        expect(isWindowLike(document.documentElement)).toBe(true);
+      });
+
+      it('returns true for body', () => {
+        expect(isWindowLike(document.body)).toBe(true);
+      });
+
+      it('returns true for null', () => {
+        expect(isWindowLike(null)).toBe(true);
+      });
+
+      it('returns false for a div', () => {
+        const el = document.createElement('div');
+        expect(isWindowLike(el)).toBe(false);
+      });
+    });
+
+    describe('iselement', () => {
+      it('returns true for a div', () => {
+        const el = document.createElement('div');
+        expect(isElement(el)).toBe(true);
+      });
+
+      it('returns true for document.documentelement', () => {
+        expect(isElement(document.documentElement)).toBe(true);
+      });
+
+      it('returns false for window', () => {
+        expect(isElement(window)).toBe(false);
+      });
+
+      it('returns false for null', () => {
+        expect(isElement(null)).toBe(false);
+      });
+    });
+
+    describe('isscrollableelement', () => {
+      it('returns true for a div', () => {
+        const el = document.createElement('div');
+        expect(isScrollableElement(el)).toBe(true);
+      });
+
+      it('returns false for null', () => {
+        expect(isScrollableElement(null)).toBe(false);
+      });
+    });
+  });
+
+  describe('options type guards', () => {
+    describe('isscrolltoindexoptions', () => {
+      it('returns true for valid options', () => {
+        expect(isScrollToIndexOptions({ align: 'start' })).toBe(true);
+        expect(isScrollToIndexOptions({ behavior: 'smooth' })).toBe(true);
+        expect(isScrollToIndexOptions({ isCorrection: true })).toBe(true);
+      });
+
+      it('returns false for other values', () => {
+        expect(isScrollToIndexOptions(null)).toBe(false);
+        expect(isScrollToIndexOptions('start')).toBe(false);
+        expect(isScrollToIndexOptions({})).toBe(false);
+      });
+    });
+  });
+
+  describe('padding utilities', () => {
+    describe('getpaddingx', () => {
+      it('handles numeric padding', () => {
+        expect(getPaddingX(10, 'horizontal')).toBe(10);
+        expect(getPaddingX(10, 'both')).toBe(10);
+        expect(getPaddingX(10, 'vertical')).toBe(0);
+        expect(getPaddingX(0, 'horizontal')).toBe(0);
+      });
+
+      it('handles object padding', () => {
+        expect(getPaddingX({ x: 15 }, 'vertical')).toBe(15);
+        expect(getPaddingX({ y: 20 }, 'horizontal')).toBe(0);
+      });
+
+      it('returns 0 for undefined', () => {
+        expect(getPaddingX(undefined)).toBe(0);
+      });
+    });
+
+    describe('getpaddingy', () => {
+      it('handles numeric padding', () => {
+        expect(getPaddingY(10, 'vertical')).toBe(10);
+        expect(getPaddingY(10, 'both')).toBe(10);
+        expect(getPaddingY(10, 'horizontal')).toBe(0);
+        expect(getPaddingY(0, 'vertical')).toBe(0);
+      });
+
+      it('handles object padding', () => {
+        expect(getPaddingY({ y: 15 }, 'horizontal')).toBe(15);
+        expect(getPaddingY({ x: 20 }, 'vertical')).toBe(0);
+      });
+
+      it('returns 0 for undefined', () => {
+        expect(getPaddingY(undefined)).toBe(0);
+      });
+    });
+  });
+});

package/src/utils/scroll.ts

@@ -1,37 +1,74 @@
-import type { ScrollDirection, ScrollToIndexOptions } from '../composables/useVirtualScroll';
+import type { ScrollDirection, ScrollToIndexOptions } from '../types';
 
 /**
- * Checks if the container has a bounding client rect method.
+ * Maximum size (in pixels) for an element that most browsers can handle reliably.
+ * Beyond this size, we use scaling for the scrollable area.
+ * @default 10000000
+ */
+export const BROWSER_MAX_SIZE = 10000000;
+
+/**
+ * Checks if the container is the window object.
+ *
+ * @param container - The container element or window to check.
+ * @returns `true` if the container is the global window object.
+ */
+export function isWindow(container: HTMLElement | Window | null | undefined): container is Window {
+  return container === null || container === document.documentElement || (typeof window !== 'undefined' && container === window);
+}
+
+/**
+ * Checks if the container is the document body element.
+ *
+ * @param container - The container element or window to check.
+ * @returns `true` if the container is the `<body>` element.
+ */
+export function isBody(container: HTMLElement | Window | null | undefined): container is HTMLElement {
+  return container != null && typeof container === 'object' && 'tagName' in container && container.tagName === 'BODY';
+}
+
+/**
+ * Checks if the container is window-like (global window or document body).
  *
  * @param container - The container element or window to check.
- * @returns True if the container is an HTMLElement with getBoundingClientRect.
+ * @returns `true` if the container is window or body.
+ */
+export function isWindowLike(container: HTMLElement | Window | null | undefined): boolean {
+  return isWindow(container) || isBody(container);
+}
+
+/**
+ * Checks if the container is a valid HTML Element with bounding rect support.
+ *
+ * @param container - The container to check.
+ * @returns `true` if the container is an `HTMLElement`.
  */
 export function isElement(container: HTMLElement | Window | null | undefined): container is HTMLElement {
-  return !!container && 'getBoundingClientRect' in container;
+  return container != null && 'getBoundingClientRect' in container;
 }
 
 /**
- * Checks if the target is an element with scroll properties.
+ * Checks if the target is an element that supports scrolling.
  *
  * @param target - The event target to check.
- * @returns True if the target is an HTMLElement with scroll properties.
+ * @returns `true` if the target is an `HTMLElement` with scroll properties.
  */
 export function isScrollableElement(target: EventTarget | null): target is HTMLElement {
-  return !!target && 'scrollLeft' in target;
+  return target != null && 'scrollLeft' in target;
 }
 
 /**
- * Helper to determine if an options argument is the full ScrollToIndexOptions object.
+ * Helper to determine if an options argument is a full `ScrollToIndexOptions` object.
  *
  * @param options - The options object to check.
- * @returns True if the options object contains scroll-to-index specific properties.
+ * @returns `true` if the options object contains scroll-to-index specific properties.
  */
 export function isScrollToIndexOptions(options: unknown): options is ScrollToIndexOptions {
-  return typeof options === 'object' && options !== null && ('align' in options || 'behavior' in options || 'isCorrection' in options);
+  return typeof options === 'object' && options != null && ('align' in options || 'behavior' in options || 'isCorrection' in options);
 }
 
 /**
- * Extracts the horizontal padding from a padding value or object.
+ * Extracts the horizontal padding from a padding configuration.
  *
  * @param p - The padding value (number or object with x/y).
  * @param direction - The current scroll direction.
@@ -41,11 +78,11 @@ export function getPaddingX(p: number | { x?: number; y?: number; } | undefined,
   if (typeof p === 'object' && p !== null) {
     return p.x || 0;
   }
-  return direction === 'horizontal' ? (p || 0) : 0;
+  return (direction === 'horizontal' || direction === 'both') ? (p || 0) : 0;
 }
 
 /**
- * Extracts the vertical padding from a padding value or object.
+ * Extracts the vertical padding from a padding configuration.
  *
  * @param p - The padding value (number or object with x/y).
  * @param direction - The current scroll direction.