npm - @pdanpdan/virtual-scroll - Versions diffs - 0.7.0 → 0.9.0 - Mend

@pdanpdan/virtual-scroll 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/README.md +99 -6
package/dist/index.cjs +1 -1
package/dist/index.cjs.map +1 -1
package/dist/index.d.ts +295 -31
package/dist/index.js +1 -1
package/dist/index.js.map +1 -1
package/dist/index.mjs +954 -878
package/dist/index.mjs.map +1 -1
package/dist/virtual-scroll.css +1 -1
package/package.json +7 -2
package/src/components/VirtualScroll.vue +301 -209
package/src/components/VirtualScrollbar.vue +8 -8
package/src/composables/useVirtualScroll.ts +261 -521
package/src/composables/useVirtualScrollSizes.ts +448 -0
package/src/composables/useVirtualScrollbar.ts +30 -35
package/src/index.ts +1 -0
package/src/types.ts +25 -2
package/src/utils/scroll.ts +14 -14
package/src/utils/virtual-scroll-logic.ts +305 -1

package/src/utils/scroll.ts CHANGED Viewed

@@ -18,50 +18,50 @@ export const BROWSER_MAX_SIZE = 10000000;
 /**
  * Checks if the container is the window object.
  *
- * @param container - The container element or window to check.
+ * @param container - The container element or window to check. Optional.
  * @returns `true` if the container is the global window object.
  */
-export function isWindow(container: HTMLElement | Window | null | undefined): container is Window {
+export function isWindow(container?: HTMLElement | Window | null): 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.
+ * @param container - The container element or window to check. Optional.
  * @returns `true` if the container is the `<body>` element.
  */
-export function isBody(container: HTMLElement | Window | null | undefined): container is HTMLElement {
+export function isBody(container?: HTMLElement | Window | null): 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.
+ * @param container - The container element or window to check. Optional.
  * @returns `true` if the container is window or body.
  */
-export function isWindowLike(container: HTMLElement | Window | null | undefined): boolean {
+export function isWindowLike(container?: HTMLElement | Window | null): 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.
+ * @param container - The container to check. Optional.
  * @returns `true` if the container is an `HTMLElement`.
  */
-export function isElement(container: HTMLElement | Window | null | undefined): container is HTMLElement {
+export function isElement(container?: HTMLElement | Window | null): container is HTMLElement {
   return container != null && 'getBoundingClientRect' in container;
 }
 /**
  * Checks if the target is an element that supports scrolling.
  *
- * @param target - The event target to check.
+ * @param target - The event target to check. Optional.
  * @returns `true` if the target is an `HTMLElement` with scroll properties.
  */
-export function isScrollableElement(target: EventTarget | null): target is HTMLElement {
+export function isScrollableElement(target?: EventTarget | null): target is HTMLElement {
   return target != null && 'scrollLeft' in target;
 }
@@ -101,11 +101,11 @@ export function isScrollToIndexOptions(options: unknown): options is ScrollToInd
 /**
  * Extracts the horizontal padding from a padding configuration.
  *
- * @param p - The padding value (number or object with x/y).
+ * @param p - The padding value (number or object with x/y). Optional.
  * @param direction - The current scroll direction.
  * @returns The horizontal padding in pixels.
  */
-export function getPaddingX(p: number | { x?: number; y?: number; } | undefined, direction?: ScrollDirection) {
+export function getPaddingX(p?: number | { x?: number; y?: number; } | null, direction?: ScrollDirection) {
   if (typeof p === 'object' && p !== null) {
     return p.x || 0;
   }
@@ -115,11 +115,11 @@ export function getPaddingX(p: number | { x?: number; y?: number; } | undefined,
 /**
  * Extracts the vertical padding from a padding configuration.
  *
- * @param p - The padding value (number or object with x/y).
+ * @param p - The padding value (number or object with x/y). Optional.
  * @param direction - The current scroll direction.
  * @returns The vertical padding in pixels.
  */
-export function getPaddingY(p: number | { x?: number; y?: number; } | undefined, direction?: ScrollDirection) {
+export function getPaddingY(p?: number | { x?: number; y?: number; } | null, direction?: ScrollDirection) {
   if (typeof p === 'object' && p !== null) {
     return p.y || 0;
   }

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

@@ -5,9 +5,12 @@ import type {
   RangeParams,
   ScrollAlignment,
   ScrollAlignmentOptions,
+  ScrollDirection,
   ScrollTargetParams,
   ScrollTargetResult,
   ScrollToIndexOptions,
+  SnapMode,
+  SSRRange,
   StickyParams,
   TotalSizeParams,
 } from '../types';
@@ -38,6 +41,14 @@ interface AxisAlignmentParams {
   stickyOffsetEnd: number;
 }
+/** Snap result. */
+export interface SnapResult {
+  /** Target index. */
+  index: number;
+  /** Alignment. */
+  align: 'start' | 'center' | 'end';
+}
 // --- Internal Helpers ---
 /**
@@ -212,7 +223,7 @@ function calculateAxisAlignment({
  * @param query - Prefix sum resolver.
  * @returns Total size.
  */
-function calculateAxisSize(
+export function calculateAxisSize(
   count: number,
   fixedSize: number | null,
   gap: number,
@@ -227,6 +238,54 @@ function calculateAxisSize(
   return Math.max(0, query(count) - gap);
 }
+/**
+ * Helper to calculate size for a range on a single axis.
+ *
+ * @param start - Start index.
+ * @param end - End index.
+ * @param fixedSize - Fixed size if any.
+ * @param gap - Gap size.
+ * @param query - Prefix sum resolver.
+ * @returns Range size.
+ */
+export function calculateRangeSize(
+  start: number,
+  end: number,
+  fixedSize: number | null,
+  gap: number,
+  query: (index: number) => number,
+): number {
+  const count = end - start;
+  if (count <= 0) {
+    return 0;
+  }
+  if (fixedSize !== null) {
+    return Math.max(0, count * (fixedSize + gap) - gap);
+  }
+  return Math.max(0, query(end) - query(start) - gap);
+}
+/**
+ * Helper to calculate offset at a specific index.
+ *
+ * @param index - Item index.
+ * @param fixedSize - Fixed size if any.
+ * @param gap - Gap size.
+ * @param query - Prefix sum resolver.
+ * @returns Offset at index.
+ */
+export function calculateOffsetAt(
+  index: number,
+  fixedSize: number | null,
+  gap: number,
+  query: (index: number) => number,
+): number {
+  if (fixedSize !== null) {
+    return index * (fixedSize + gap);
+  }
+  return query(index);
+}
 /**
  * Helper to calculate target scroll position for a single axis.
  *
@@ -363,6 +422,35 @@ export function isItemVisible(
   return itemPos <= usableStart + 0.5 && (itemPos + itemSize) >= usableEnd - 0.5;
 }
+/**
+ * Calculates the coordinate scaling factor between virtual and display units.
+ *
+ * @param isWindow - If the container is the window.
+ * @param totalSize - Total virtual size (VU).
+ * @param viewportSize - Viewport size (DU).
+ * @returns Scaling factor (VU/DU).
+ */
+export function calculateScale(isWindow: boolean, totalSize: number, viewportSize: number): number {
+  if (isWindow || totalSize <= BROWSER_MAX_SIZE) {
+    return 1;
+  }
+  const displaySize = Math.min(totalSize, BROWSER_MAX_SIZE);
+  const realRange = totalSize - viewportSize;
+  const displayRange = displaySize - viewportSize;
+  return displayRange > 0 ? realRange / displayRange : 1;
+}
+/**
+ * Calculates the physical size to be rendered in the DOM.
+ *
+ * @param isWindow - If the container is the window.
+ * @param totalSize - Total virtual size (VU).
+ * @returns Physical size (DU).
+ */
+export function calculateRenderedSize(isWindow: boolean, totalSize: number): number {
+  return isWindow ? totalSize : Math.min(totalSize, BROWSER_MAX_SIZE);
+}
 /**
  * Maps a display scroll position to a virtual content position.
  *
@@ -877,6 +965,72 @@ export function calculateItemStyle<T = unknown>({
   return style;
 }
+/**
+ * Calculates the SSR offsets for items based on the configured SSR range and direction.
+ *
+ * @param direction - Scroll direction.
+ * @param ssrRange - SSR configuration.
+ * @param fixedItemSize - Fixed item size (VU).
+ * @param fixedColumnWidth - Fixed column width (VU).
+ * @param gap - Item gap (VU).
+ * @param columnGap - Column gap (VU).
+ * @param queryY - Resolver for vertical offset (VU).
+ * @param queryX - Resolver for horizontal offset (VU).
+ * @param queryColumn - Resolver for column offset (VU).
+ * @returns Offset X and Y (VU).
+ */
+export function calculateSSROffsets(
+  direction: ScrollDirection,
+  ssrRange: SSRRange,
+  fixedItemSize: number | null,
+  fixedColumnWidth: number | null,
+  gap: number,
+  columnGap: number,
+  queryY: (index: number) => number,
+  queryX: (index: number) => number,
+  queryColumn: (index: number) => number,
+): { x: number; y: number; } {
+  const ssrStartRow = ssrRange.start || 0;
+  const ssrStartCol = ssrRange.colStart || 0;
+  let x = 0;
+  const y = (direction !== 'horizontal')
+    ? calculateOffsetAt(ssrStartRow, fixedItemSize, gap, queryY)
+    : 0;
+  if (direction === 'horizontal') {
+    x = calculateOffsetAt(ssrStartCol, fixedItemSize, columnGap, queryX);
+  } else if (direction === 'both') {
+    x = calculateOffsetAt(ssrStartCol, fixedColumnWidth, columnGap, queryColumn);
+  }
+  return { x, y };
+}
+/**
+ * Detects how many items were prepended to the list based on item identity.
+ *
+ * @param oldItems - Previous items list.
+ * @param newItems - Current items list.
+ * @returns Number of prepended items.
+ */
+export function calculatePrependCount<T>(oldItems: T[], newItems: T[]): number {
+  if (oldItems.length === 0 || newItems.length <= oldItems.length) {
+    return 0;
+  }
+  const oldFirstItem = oldItems[ 0 ];
+  if (oldFirstItem === undefined) {
+    return 0;
+  }
+  const limit = newItems.length - oldItems.length;
+  for (let i = 1; i <= limit; i++) {
+    if (newItems[ i ] === oldFirstItem) {
+      return i;
+    }
+  }
+  return 0;
+}
 /**
  * Calculates the total width and height of the virtualized content.
  *
@@ -932,3 +1086,153 @@ export function calculateTotalSize({
     height: isBoth ? Math.max(height, usableHeight) : height,
   };
 }
+/**
+ * Calculates the next step in an inertia animation.
+ *
+ * @param velocity - Current velocity.
+ * @param velocity.x - Horizontal velocity.
+ * @param velocity.y - Vertical velocity.
+ * @param friction - Friction coefficient (0-1).
+ * @param frameTime - Time elapsed since last frame in ms (default 16ms).
+ * @returns Next velocity and distance to move.
+ */
+export function calculateInertiaStep(
+  velocity: { x: number; y: number; },
+  friction: number,
+  frameTime: number = 16,
+) {
+  const nextVelocity = {
+    x: velocity.x * friction,
+    y: velocity.y * friction,
+  };
+  return {
+    nextVelocity,
+    delta: {
+      x: nextVelocity.x * frameTime,
+      y: nextVelocity.y * frameTime,
+    },
+  };
+}
+/**
+ * Calculates instantaneous velocity from position change.
+ *
+ * @param lastPos - Previous position.
+ * @param lastPos.x - Horizontal position.
+ * @param lastPos.y - Vertical position.
+ * @param currentPos - Current position.
+ * @param currentPos.x - Horizontal position.
+ * @param currentPos.y - Vertical position.
+ * @param dt - Time delta in ms.
+ * @returns Calculated velocity {x, y}.
+ */
+export function calculateInstantaneousVelocity(
+  lastPos: { x: number; y: number; },
+  currentPos: { x: number; y: number; },
+  dt: number,
+) {
+  if (dt <= 0) {
+    return { x: 0, y: 0 };
+  }
+  return {
+    x: (lastPos.x - currentPos.x) / dt,
+    y: (lastPos.y - currentPos.y) / dt,
+  };
+}
+/**
+ * Resolves the target index and alignment for snapping on a single axis.
+ *
+ * @param mode - The snap mode ('start', 'center', 'end', 'auto').
+ * @param dir - The scroll direction on this axis.
+ * @param currentIdx - The current first visible index.
+ * @param currentEndIdx - The current last visible index.
+ * @param relScroll - The current virtual scroll offset.
+ * @param viewSize - The viewport dimension.
+ * @param count - Total number of items/columns.
+ * @param getSize - Resolver for item size.
+ * @param getQuery - Resolver for item prefix sum.
+ * @param getIndexAt - Resolver for index at a virtual offset.
+ * @returns Snap result or null.
+ */
+export function resolveSnap(
+  mode: SnapMode,
+  dir: 'start' | 'end' | null,
+  currentIdx: number,
+  currentEndIdx: number,
+  relScroll: number,
+  viewSize: number,
+  count: number,
+  getSize: (i: number) => number,
+  getQuery: (i: number) => number,
+  getIndexAt: (o: number) => number,
+): SnapResult | null {
+  let effectiveMode = mode;
+  if (mode === 'auto') {
+    if (dir === 'start') {
+      effectiveMode = 'end';
+    } else if (dir === 'end') {
+      effectiveMode = 'start';
+    } else {
+      return null;
+    }
+  }
+  if (effectiveMode === 'start') {
+    const size = getSize(currentIdx);
+    // Ignore items larger than viewport to prevent jarring jumps
+    if (size > viewSize) {
+      return null;
+    }
+    const visibleAmount = getQuery(currentIdx) + size - relScroll;
+    return {
+      index: Math.min(count - 1, visibleAmount / size >= 0.5 ? currentIdx : currentIdx + 1),
+      align: 'start' as const,
+    };
+  }
+  if (effectiveMode === 'end') {
+    const size = getSize(currentEndIdx);
+    if (size > viewSize) {
+      return null;
+    }
+    const visibleAmount = relScroll + viewSize - getQuery(currentEndIdx);
+    return {
+      index: Math.max(0, visibleAmount / size >= 0.5 ? currentEndIdx : currentEndIdx - 1),
+      align: 'end' as const,
+    };
+  }
+  if (effectiveMode === 'center') {
+    const center = relScroll + viewSize / 2;
+    const idx = Math.max(0, Math.min(count - 1, getIndexAt(center)));
+    const size = getSize(idx);
+    if (size > viewSize) {
+      return null;
+    }
+    return { index: idx, align: 'center' as const };
+  }
+  return null;
+}
+/**
+ * Helper to get the index at a virtual offset.
+ *
+ * @param offset - Virtual offset.
+ * @param fixedSize - Fixed size if any.
+ * @param gap - Gap size.
+ * @param findLowerBound - Binary search resolver.
+ * @returns Index at offset.
+ */
+export function calculateIndexAt(
+  offset: number,
+  fixedSize: number | null,
+  gap: number,
+  findLowerBound: (offset: number) => number,
+): number {
+  const step = (fixedSize || 0) + gap;
+  if (fixedSize !== null && step > 0) {
+    return Math.floor(offset / step);
+  }
+  return findLowerBound(offset);
+}