@pdanpdan/virtual-scroll 0.2.1 → 0.4.0

package/src/utils/scroll.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+
+import { getPaddingX, getPaddingY, isBody, isElement, isScrollableElement, isScrollToIndexOptions, isWindow, isWindowLike } from './scroll';
+
+describe('scroll utils', () => {
+  describe('isWindow', () => {
+    it('should return true for null', () => {
+      expect(isWindow(null)).toBe(true);
+    });
+
+    it('should return 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);
+    });
+  });
+
+  describe('isBody', () => {
+    it('should return true for document.body', () => {
+      expect(isBody(document.body)).toBe(true);
+    });
+
+    it('should return false for null', () => {
+      expect(isBody(null)).toBe(false);
+    });
+
+    it('should return false for undefined', () => {
+      expect(isBody(undefined)).toBe(false);
+    });
+
+    it('should return false for a string', () => {
+      // @ts-expect-error testing invalid input
+      expect(isBody('not an object')).toBe(false);
+    });
+
+    it('should return false for a plain object', () => {
+      // @ts-expect-error testing invalid input
+      expect(isBody({})).toBe(false);
+    });
+
+    it('should return false for a div', () => {
+      const el = document.createElement('div');
+      expect(isBody(el)).toBe(false);
+    });
+
+    it('should return false for window', () => {
+      expect(isBody(window)).toBe(false);
+    });
+  });
+
+  describe('isWindowLike', () => {
+    it('should return true for window', () => {
+      expect(isWindowLike(window)).toBe(true);
+    });
+
+    it('should return true for body', () => {
+      expect(isWindowLike(document.body)).toBe(true);
+    });
+
+    it('should return true for null', () => {
+      expect(isWindowLike(null)).toBe(true);
+    });
+
+    it('should return false for a div', () => {
+      const el = document.createElement('div');
+      expect(isWindowLike(el)).toBe(false);
+    });
+  });
+
+  describe('isElement', () => {
+    it('should return true for a div', () => {
+      const el = document.createElement('div');
+      expect(isElement(el)).toBe(true);
+    });
+
+    it('should return false for window', () => {
+      expect(isElement(window)).toBe(false);
+    });
+
+    it('should return false for null', () => {
+      expect(isElement(null)).toBe(false);
+    });
+  });
+
+  describe('isScrollableElement', () => {
+    it('should return true for a div', () => {
+      const el = document.createElement('div');
+      expect(isScrollableElement(el)).toBe(true);
+    });
+
+    it('should return false for null', () => {
+      expect(isScrollableElement(null)).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);
+    });
+
+    it('should return false for other values', () => {
+      expect(isScrollToIndexOptions(null)).toBe(false);
+      expect(isScrollToIndexOptions('start')).toBe(false);
+      expect(isScrollToIndexOptions({})).toBe(false);
+    });
+  });
+
+  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('should handle object padding', () => {
+      expect(getPaddingX({ x: 15 }, 'vertical')).toBe(15);
+      expect(getPaddingX({ y: 20 }, 'horizontal')).toBe(0);
+    });
+
+    it('should return 0 for undefined', () => {
+      expect(getPaddingX(undefined)).toBe(0);
+    });
+  });
+
+  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('should handle object padding', () => {
+      expect(getPaddingY({ y: 15 }, 'horizontal')).toBe(15);
+      expect(getPaddingY({ x: 20 }, 'vertical')).toBe(0);
+    });
+
+    it('should return 0 for undefined', () => {
+      expect(getPaddingY(undefined)).toBe(0);
+    });
+  });
+});

package/src/utils/scroll.ts

@@ -1,37 +1,67 @@
-import type { ScrollDirection, ScrollToIndexOptions } from '../composables/useVirtualScroll';
+import type { ScrollDirection, ScrollToIndexOptions } from '../types';
 
 /**
- * Checks if the container has a bounding client rect method.
+ * Checks if the container is the window object.
  *
  * @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 the global window object.
+ */
+export function isWindow(container: HTMLElement | Window | null | undefined): container is Window {
+  return container === null || (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 && 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 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;
 }
 
 /**
- * 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;
 }
 
 /**
- * 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);
 }
 
 /**
- * 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 +71,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.