@pdanpdan/virtual-scroll 0.4.0 → 0.6.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/scroll.test.ts

@@ -1,148 +1,228 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 
-import { getPaddingX, getPaddingY, isBody, isElement, isScrollableElement, isScrollToIndexOptions, isWindow, isWindowLike } from './scroll';
+import { getPaddingX, getPaddingY, isBody, isElement, isScrollableElement, isScrollToIndexOptions, isWindow, isWindowLike, scrollTo } from './scroll';
 
 describe('scroll utils', () => {
-  describe('isWindow', () => {
-    it('should return true for null', () => {
-      expect(isWindow(null)).toBe(true);
-    });
+  describe('element type guards', () => {
+    describe('is window', () => {
+      it('returns true for null', () => {
+        expect(isWindow(null)).toBe(true);
+      });
 
-    it('should return true for window object', () => {
-      expect(isWindow(window)).toBe(true);
-    });
+      it('returns true for window object', () => {
+        expect(isWindow(window)).toBe(true);
+      });
 
-    it('should return false for an element', () => {
-      const el = document.createElement('div');
-      expect(isWindow(el)).toBe(false);
-    });
-  });
+      it('returns true for document.documentelement object', () => {
+        expect(isWindow(document.documentElement)).toBe(true);
+      });
 
-  describe('isBody', () => {
-    it('should return true for document.body', () => {
-      expect(isBody(document.body)).toBe(true);
-    });
+      it('returns false for an element', () => {
+        const el = document.createElement('div');
+        expect(isWindow(el)).toBe(false);
+      });
 
-    it('should return false for null', () => {
-      expect(isBody(null)).toBe(false);
+      it('returns false for undefined', () => {
+        expect(isWindow(undefined)).toBe(false);
+      });
     });
 
-    it('should return false for undefined', () => {
-      expect(isBody(undefined)).toBe(false);
-    });
+    describe('is body', () => {
+      it('returns true for document.body', () => {
+        expect(isBody(document.body)).toBe(true);
+      });
 
-    it('should return false for a string', () => {
-      // @ts-expect-error testing invalid input
-      expect(isBody('not an object')).toBe(false);
-    });
+      it('returns false for null', () => {
+        expect(isBody(null)).toBe(false);
+      });
 
-    it('should return false for a plain object', () => {
-      // @ts-expect-error testing invalid input
-      expect(isBody({})).toBe(false);
-    });
+      it('returns false for undefined', () => {
+        expect(isBody(undefined)).toBe(false);
+      });
 
-    it('should return false for a div', () => {
-      const el = document.createElement('div');
-      expect(isBody(el)).toBe(false);
-    });
+      it('returns false for a string', () => {
+        // @ts-expect-error testing invalid input
+        expect(isBody('not an object')).toBe(false);
+      });
 
-    it('should return false for window', () => {
-      expect(isBody(window)).toBe(false);
-    });
-  });
+      it('returns false for a plain object', () => {
+        // @ts-expect-error testing invalid input
+        expect(isBody({})).toBe(false);
+      });
 
-  describe('isWindowLike', () => {
-    it('should return true for window', () => {
-      expect(isWindowLike(window)).toBe(true);
-    });
+      it('returns false for a div', () => {
+        const el = document.createElement('div');
+        expect(isBody(el)).toBe(false);
+      });
 
-    it('should return true for body', () => {
-      expect(isWindowLike(document.body)).toBe(true);
-    });
+      it('returns false for window', () => {
+        expect(isBody(window)).toBe(false);
+      });
 
-    it('should return true for null', () => {
-      expect(isWindowLike(null)).toBe(true);
+      it('returns false for document.documentelement', () => {
+        expect(isBody(document.documentElement)).toBe(false);
+      });
     });
 
-    it('should return false for a div', () => {
-      const el = document.createElement('div');
-      expect(isWindowLike(el)).toBe(false);
-    });
-  });
+    describe('is window like', () => {
+      it('returns true for window', () => {
+        expect(isWindowLike(window)).toBe(true);
+      });
 
-  describe('isElement', () => {
-    it('should return true for a div', () => {
-      const el = document.createElement('div');
-      expect(isElement(el)).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);
+      });
     });
 
-    it('should return false for window', () => {
-      expect(isElement(window)).toBe(false);
+    describe('is element', () => {
+      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);
+      });
     });
 
-    it('should return false for null', () => {
-      expect(isElement(null)).toBe(false);
+    describe('is scrollable element', () => {
+      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('isScrollableElement', () => {
-    it('should return true for a div', () => {
-      const el = document.createElement('div');
-      expect(isScrollableElement(el)).toBe(true);
-    });
+  describe('options type guards', () => {
+    describe('is scroll to index options', () => {
+      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('should return false for null', () => {
-      expect(isScrollableElement(null)).toBe(false);
+      it('returns false for other values', () => {
+        expect(isScrollToIndexOptions(null)).toBe(false);
+        expect(isScrollToIndexOptions('start')).toBe(false);
+        expect(isScrollToIndexOptions({})).toBe(false);
+      });
     });
   });
 
-  describe('isScrollToIndexOptions', () => {
-    it('should return true for valid options', () => {
-      expect(isScrollToIndexOptions({ align: 'start' })).toBe(true);
-      expect(isScrollToIndexOptions({ behavior: 'smooth' })).toBe(true);
-      expect(isScrollToIndexOptions({ isCorrection: true })).toBe(true);
+  describe('padding utilities', () => {
+    describe('get padding x', () => {
+      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('get padding y', () => {
+      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);
+      });
     });
+  });
 
-    it('should return false for other values', () => {
-      expect(isScrollToIndexOptions(null)).toBe(false);
-      expect(isScrollToIndexOptions('start')).toBe(false);
-      expect(isScrollToIndexOptions({})).toBe(false);
+  describe('scrollTo utility', () => {
+    it('does nothing if container is undefined', () => {
+      const spy = vi.spyOn(window, 'scrollTo');
+      scrollTo(undefined, { top: 100 });
+      expect(spy).not.toHaveBeenCalled();
     });
-  });
 
-  describe('getPaddingX', () => {
-    it('should handle 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('scrolls the window if container is null', () => {
+      const spy = vi.spyOn(window, 'scrollTo');
+      scrollTo(null, { top: 100 });
+      expect(spy).toHaveBeenCalledWith({ top: 100 });
     });
 
-    it('should handle object padding', () => {
-      expect(getPaddingX({ x: 15 }, 'vertical')).toBe(15);
-      expect(getPaddingX({ y: 20 }, 'horizontal')).toBe(0);
+    it('scrolls the window if container is window', () => {
+      const spy = vi.spyOn(window, 'scrollTo');
+      scrollTo(window, { top: 100 });
+      expect(spy).toHaveBeenCalledWith({ top: 100 });
     });
 
-    it('should return 0 for undefined', () => {
-      expect(getPaddingX(undefined)).toBe(0);
+    it('scrolls the window if container is document.documentElement', () => {
+      const spy = vi.spyOn(window, 'scrollTo');
+      scrollTo(document.documentElement, { top: 100 });
+      expect(spy).toHaveBeenCalledWith({ top: 100 });
     });
-  });
 
-  describe('getPaddingY', () => {
-    it('should handle 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('scrolls an element using scrollTo if available', () => {
+      const el = document.createElement('div');
+      const spy = vi.fn();
+      el.scrollTo = spy;
+      scrollTo(el, { left: 50, top: 100 });
+      expect(spy).toHaveBeenCalledWith({ left: 50, top: 100 });
     });
 
-    it('should handle object padding', () => {
-      expect(getPaddingY({ y: 15 }, 'horizontal')).toBe(15);
-      expect(getPaddingY({ x: 20 }, 'vertical')).toBe(0);
+    it('scrolls an element using scrollLeft/scrollTop if scrollTo is missing', () => {
+      const el = document.createElement('div');
+      // @ts-expect-error forcing missing scrollTo
+      el.scrollTo = undefined;
+      scrollTo(el, { left: 50, top: 100 });
+      expect(el.scrollLeft).toBe(50);
+      expect(el.scrollTop).toBe(100);
     });
 
-    it('should return 0 for undefined', () => {
-      expect(getPaddingY(undefined)).toBe(0);
+    it('does not set undefined values on scrollLeft/scrollTop', () => {
+      const el = document.createElement('div');
+      el.scrollLeft = 10;
+      el.scrollTop = 20;
+      // @ts-expect-error forcing missing scrollTo
+      el.scrollTo = undefined;
+      scrollTo(el, { behavior: 'smooth' });
+      expect(el.scrollLeft).toBe(10);
+      expect(el.scrollTop).toBe(20);
     });
   });
 });

package/src/utils/scroll.ts

@@ -1,5 +1,20 @@
+/**
+ * Utilities for scroll management and element type detection.
+ * Provides helper functions for checking Window and Body elements,
+ * and a universal scrollTo function.
+ */
+
 import type { ScrollDirection, ScrollToIndexOptions } from '../types';
 
+/* global ScrollToOptions */
+
+/**
+ * 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.
  *
@@ -7,7 +22,7 @@ import type { ScrollDirection, ScrollToIndexOptions } from '../types';
  * @returns `true` if the container is the global window object.
  */
 export function isWindow(container: HTMLElement | Window | null | undefined): container is Window {
-  return container === null || (typeof window !== 'undefined' && container === window);
+  return container === null || container === document.documentElement || (typeof window !== 'undefined' && container === window);
 }
 
 /**
@@ -17,7 +32,7 @@ export function isWindow(container: HTMLElement | Window | null | undefined): co
  * @returns `true` if the container is the `<body>` element.
  */
 export function isBody(container: HTMLElement | Window | null | undefined): container is HTMLElement {
-  return !!container && typeof container === 'object' && 'tagName' in container && container.tagName === 'BODY';
+  return container != null && typeof container === 'object' && 'tagName' in container && container.tagName === 'BODY';
 }
 
 /**
@@ -37,7 +52,7 @@ export function isWindowLike(container: HTMLElement | Window | null | undefined)
  * @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;
 }
 
 /**
@@ -47,7 +62,30 @@ export function isElement(container: HTMLElement | Window | null | undefined): c
  * @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;
+}
+
+/**
+ * Universal scroll function that handles both Window and HTMLElements.
+ *
+ * @param container - The container to scroll.
+ * @param options - Scroll options.
+ */
+export function scrollTo(container: HTMLElement | Window | null | undefined, options: ScrollToOptions) {
+  if (isWindow(container)) {
+    window.scrollTo(options);
+  } else if (container != null && isScrollableElement(container)) {
+    if (typeof container.scrollTo === 'function') {
+      container.scrollTo(options);
+    } else {
+      if (options.left !== undefined) {
+        container.scrollLeft = options.left;
+      }
+      if (options.top !== undefined) {
+        container.scrollTop = options.top;
+      }
+    }
+  }
 }
 
 /**
@@ -57,7 +95,7 @@ export function isScrollableElement(target: EventTarget | null): target is HTMLE
  * @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);
 }
 
 /**