@pdanpdan/virtual-scroll 0.9.1 → 0.10.1

package/src/types.ts

@@ -87,6 +87,25 @@ export interface ScrollToIndexOptions {
    * @internal
    */
   isCorrection?: boolean;
+
+  /**
+   * If true, only calculates the target position without performing the actual scroll.
+   * Useful for extensions that need to validate if a snap is necessary.
+   * @default false
+   */
+  dryRun?: boolean;
+}
+
+/** Result of the `scrollToIndex` method. */
+export interface ScrollToIndexResult {
+  /** Target relative horizontal position in virtual units (VU). */
+  targetX: number;
+  /** Target relative vertical position in virtual units (VU). */
+  targetY: number;
+  /** Target display horizontal position (DU). */
+  displayTargetX: number;
+  /** Target display vertical position (DU). */
+  displayTargetY: number;
 }
 
 /** Represents an item currently rendered in the virtual scroll area. */
@@ -192,9 +211,10 @@ export type PaddingValue = number | { x?: number; y?: number; };
  * - 'start': Aligns the first visible item to the viewport start if at least 50% visible, otherwise aligns the next item.
  * - 'center': Aligns the item that intersects the viewport center to the center.
  * - 'end': Aligns the last visible item to the viewport end if at least 50% visible, otherwise aligns the previous item.
+ * - 'next': Snaps to the next (closest) snap position in the direction of the scroll.
  * - 'auto': Intelligent snapping based on scroll direction. Acts as 'end' when scrolling towards start, and 'start' when scrolling towards end.
  */
-export type SnapMode = boolean | 'start' | 'center' | 'end' | 'auto';
+export type SnapMode = boolean | 'start' | 'center' | 'end' | 'next' | 'auto';
 
 /** Base configuration properties shared between the component and the composable. */
 export interface VirtualScrollBaseProps<T = unknown> {
@@ -205,7 +225,7 @@ export interface VirtualScrollBaseProps<T = unknown> {
    * Fixed size of each item in virtual units (VU) or a function that returns the size of an item.
    * Pass `0`, `null` or `undefined` for automatic dynamic size detection via `ResizeObserver`.
    */
-  itemSize?: number | ((item: T, index: number) => number) | null | undefined;
+  itemSize?: number | (number | null | undefined)[] | ((item: T, index: number) => number) | null | undefined;
 
   /**
    * Direction of the virtual scroll.
@@ -246,7 +266,7 @@ export interface VirtualScrollBaseProps<T = unknown> {
    * Fixed width of columns in VU, an array of widths, or a function returning widths.
    * Pass `0`, `null` or `undefined` for dynamic column detection.
    */
-  columnWidth?: number | number[] | ((index: number) => number) | null | undefined;
+  columnWidth?: number | (number | null | undefined)[] | ((index: number) => number) | null | undefined;
 
   /**
    * Pixel padding at the start of the scroll container in display pixels (DU).
@@ -283,11 +303,13 @@ export interface VirtualScrollBaseProps<T = unknown> {
 
   /**
    * Whether data is currently loading.
+   * While true, the loading slot is shown and `load` events are suppressed.
    */
   loading?: boolean | undefined;
 
   /**
-   * Whether to automatically restore and maintain scroll position when items are prepended to the array.
+   * Whether to automatically maintain scroll position when items are prepended to the array.
+   * Useful for "load more" chat interfaces.
    */
   restoreScrollOnPrepend?: boolean | undefined;
 
@@ -342,6 +364,7 @@ export interface VirtualScrollBaseProps<T = unknown> {
 
   /**
    * Whether to snap to items after scrolling stops.
+   * Options: false, true, 'auto', 'next', 'start', 'center', 'end'.
    * @default false
    */
   snap?: SnapMode | undefined;
@@ -514,10 +537,20 @@ export interface VirtualScrollComponentProps<T = unknown> extends VirtualScrollB
   /** The HTML tag to use for each item. */
   itemTag?: string;
   /** Whether the content in the 'header' slot is sticky. */
+  /**
+   * If true, measures the header slot size and adds it to the scroll padding.
+   * Can be combined with CSS for sticky headers.
+   */
   stickyHeader?: boolean;
-  /** Whether the content in the 'footer' slot is sticky. */
+  /**
+   * If true, measures the footer slot size and adds it to the scroll padding.
+   * Can be combined with CSS for sticky footers.
+   */
   stickyFooter?: boolean;
-  /** Whether to use virtual scrollbars for styling purposes. */
+  /**
+   * Whether to use virtual scrollbars.
+   * Automatically enabled when content size exceeds browser limits.
+   */
   virtualScrollbar?: boolean;
 }
 
@@ -547,8 +580,12 @@ export interface VirtualScrollInstance<T = unknown> extends VirtualScrollCompone
   getItemOffset: (index: number) => number;
   /** Helper to get the size of a specific item along the scroll axis. */
   getItemSize: (index: number) => number;
+  /** Whether the component is in table mode. */
+  isTable: boolean;
+  /** The tag used for rendering items. */
+  itemTag: string;
   /** Programmatically scroll to a specific row and/or column. */
-  scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
+  scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => ScrollToIndexResult;
   /** Programmatically scroll to a specific pixel offset. */
   scrollToOffset: (x?: number | null, y?: number | null, options?: { behavior?: 'auto' | 'smooth'; }) => void;
   /** Resets all dynamic measurements and re-initializes from props. */
@@ -681,6 +718,8 @@ export interface RangeParams {
   usableHeight: number;
   /** Total item count. */
   itemsLength: number;
+  /** Column count (for grid mode). */
+  columnCount?: number;
   /** Buffer items before. */
   bufferBefore: number;
   /** Buffer items after. */
@@ -796,7 +835,7 @@ export interface ItemStyleParams<T = unknown> {
   /** Scroll direction. */
   direction: ScrollDirection;
   /** Configured item size logic. */
-  itemSize: number | ((item: T, index: number) => number) | null | undefined;
+  itemSize: number | (number | null | undefined)[] | ((item: T, index: number) => number) | null | undefined;
   /** Parent container tag. */
   containerTag: string;
   /** Padding start on X axis. */

package/src/utils/scroll.ts

@@ -22,7 +22,7 @@ export const BROWSER_MAX_SIZE = 10000000;
  * @returns `true` if the container is the global window object.
  */
 export function isWindow(container?: HTMLElement | Window | null): container is Window {
-  return container === null || container === document.documentElement || (typeof window !== 'undefined' && container === window);
+  return container === null || (typeof document !== 'undefined' && container === document.documentElement) || (typeof window !== 'undefined' && container === window);
 }
 
 /**
@@ -95,7 +95,7 @@ export function scrollTo(container: HTMLElement | Window | null | undefined, opt
  * @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 || 'dryRun' in options);
 }
 
 /**

package/src/utils/virtual-scroll-logic.ts

@@ -1189,6 +1189,48 @@ export function resolveSnap(
     }
   }
 
+  if (mode === 'next') {
+    if (dir === 'end') {
+      // Scrolling items UP (towards end of list) -> snap to NEXT item start
+      const size = getSize(currentIdx);
+      if (size > viewSize) {
+        return null;
+      }
+      const scrolledOut = relScroll - getQuery(currentIdx);
+      const threshold = Math.min(5, size * 0.1);
+      if (scrolledOut <= threshold) {
+        return {
+          index: currentIdx,
+          align: 'start' as const,
+        };
+      }
+      return {
+        index: Math.min(count - 1, currentIdx + 1),
+        align: 'start' as const,
+      };
+    } else if (dir === 'start') {
+      // Scrolling items DOWN (towards start of list) -> snap to PREVIOUS item end
+      const size = getSize(currentEndIdx);
+      if (size > viewSize) {
+        return null;
+      }
+      const scrolledOutBottom = (getQuery(currentEndIdx) + size) - (relScroll + viewSize);
+      const threshold = Math.min(5, size * 0.1);
+      if (scrolledOutBottom <= threshold) {
+        return {
+          index: currentEndIdx,
+          align: 'end' as const,
+        };
+      }
+      return {
+        index: Math.max(0, currentEndIdx - 1),
+        align: 'end' as const,
+      };
+    } else {
+      return null;
+    }
+  }
+
   if (effectiveMode === 'start') {
     const size = getSize(currentIdx);
     // Ignore items larger than viewport to prevent jarring jumps