refactor: cleanup property names for clarity, type code properly

src/lib/SizeAndPositionManager.ts

@@ -202,11 +202,11 @@ export default class SizeAndPositionManager {
 		return Math.max(0, Math.min(totalSize - containerSize, idealOffset));
 	}
 
-	getVisibleRange(containerSize: number = 0, offset: number, overscanCount: number): VirtualRange {
+	getVisibleRange(containerSize: number = 0, offset: number, windowOverPadding: number): VirtualRange {
 		const totalSize = this.getTotalSize();
 
 		if (totalSize === 0) {
-			return {};
+			return { start: 0, end: 0 };
 		}
 
 		const maxOffset = offset + containerSize;
@@ -226,9 +226,9 @@ export default class SizeAndPositionManager {
 			offset += this.getSizeAndPositionForIndex(end).size;
 		}
 
-		if (overscanCount) {
-			start = Math.max(0, start - overscanCount);
-			end = Math.min(end + overscanCount, this.itemCount - 1);
+		if (windowOverPadding) {
+			start = Math.max(0, start - windowOverPadding);
+			end = Math.min(end + windowOverPadding, this.itemCount - 1);
 		}
 
 		return {

src/lib/VirtualList.svelte

@@ -38,7 +38,7 @@
 		SCROLL_CHANGE_REASON,
 		type AfterScrollEvent,
 		type RowAttributes,
-		type VirtualRange,
+		type VirtualRangeEvent,
 		type VirtualRowSize
 	} from '.';
 
@@ -62,16 +62,16 @@
 		// positioning
 		scrollToIndex?: number | undefined;
 		scrollOffset?: number | undefined;
-		overscanCount?: number;
+		windowOverPadding?: number;
 		scrollDirection?: DIRECTION;
 		scrollToAlignment?: ALIGNMENT;
 		scrollToBehaviour?: SCROLL_BEHAVIOR;
-		//snippets
+		// snippets
 		header?: Snippet;
 		row: Snippet<[RowAttributes]>;
 		footer?: Snippet;
-		// callbacks
-		onVisibleRangeUpdate?: (range: VirtualRange) => void;
+		// events
+		onVisibleRangeUpdate?: (range: VirtualRangeEvent) => void;
 		onAfterScroll?: (event: AfterScrollEvent) => void;
 	}
 
@@ -86,7 +86,7 @@
 		// positioning
 		scrollToIndex,
 		scrollOffset,
-		overscanCount = 3,
+		windowOverPadding = 3,
 		scrollDirection = DIRECTION.VERTICAL,
 		scrollToAlignment = ALIGNMENT.AUTO,
 		scrollToBehaviour = SCROLL_BEHAVIOR.INSTANT,
@@ -96,9 +96,8 @@
 		row,
 		header,
 
-		// callback
-		//TODO rename to visibleRangeUpdated
-		onVisibleRangeUpdate: onVisibleRangeUpdate = () => null,
+		// events
+		onVisibleRangeUpdate = () => null,
 		onAfterScroll = () => null
 	}: Props = $props();
 
@@ -261,7 +260,7 @@
 			//@ts-expect-error wrong type assignment
 			scrollDirection === DIRECTION.VERTICAL ? height : width,
 			offset,
-			overscanCount
+			windowOverPadding
 		);
 
 		let updatedItems = [];
@@ -285,8 +284,7 @@
 				});
 			}
 
-			// TODO: carefull, stop is not named the same as end, maybe rename stop->end
-			onVisibleRangeUpdate({ start, end });
+			onVisibleRangeUpdate({ type: 'range.update', start, end });
 		}
 
 		items = updatedItems;
@@ -341,7 +339,7 @@
 			scrollChangeReason: SCROLL_CHANGE_REASON.OBSERVED
 		};
 
-		onAfterScroll({ offset, event });
+		onAfterScroll({ type: 'scroll.update', offset, event });
 	};
 
 	function getEstimatedItemSize(): number {

src/lib/index.ts

@@ -2,8 +2,11 @@ export type VirtualRowSize = number | number[] | ((index: number) => number);
 
 export { default as VirtualList } from './VirtualList.svelte';
 
+// use by the row() snippet
 export interface RowAttributes {
+	// the index of the row being rendered, from the original dataset
 	index: number;
+	// the calculated style for this row
 	style: string;
 }
 
@@ -13,13 +16,21 @@ export interface VirtualPosition {
 }
 
 export interface VirtualRange {
-	start?: number;
-	end?: number;
+	// index of the first visible item
+	start: number;
+	// index of the last visible item
+	end: number;
+}
+
+export interface VirtualRangeEvent extends VirtualRange {
+	type: 'range.update';
 }
 
 export interface AfterScrollEvent {
+	type: 'scroll.update';
+	// either the value of `wrapper.scrollTop` or `wrapper.scrollLeft`
 	offset: number | string;
-	// original event
+	// the original event
 	event: Event;
 }