@wordpress/dataviews 13.1.1-next.v.202603102151.0 → 14.0.0

package/src/hooks/use-data.ts

@@ -1,45 +1,312 @@
 /**
  * WordPress dependencies
  */
-import { useEffect, useRef, useState } from '@wordpress/element';
+import { useState, useEffect, useMemo, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { View } from '../types';
 
 type PaginationInfo = {
 	totalItems: number;
 	totalPages: number;
-	infiniteScrollHandler?: () => void;
 };
 
-export default function useData< Item >(
-	data: Item[],
-	isLoading: boolean | undefined,
-	paginationInfo: PaginationInfo
-): {
+interface UseDataParams< Item > {
+	view: View;
 	data: Item[];
+	getItemId: ( item: Item ) => string;
+	isLoading?: boolean;
+	paginationInfo: PaginationInfo;
+	selection?: string[];
+}
+
+interface UseDataResult< Item > {
+	data: ( Item & { position?: number } )[];
 	paginationInfo: PaginationInfo;
 	hasInitiallyLoaded: boolean;
-} {
-	const previousDataRef = useRef< Item[] >( data );
-	const previousPaginationInfoRef =
-		useRef< PaginationInfo >( paginationInfo );
+	setVisibleEntries?: React.Dispatch< React.SetStateAction< number[] > >;
+}
+
+/**
+ * Hook to manage data for DataViews.
+ *
+ * When infinite scroll is enabled, this hook handles:
+ * - Loading more data when scrolling up or down
+ * - Maintaining stable positions for items
+ * - Unloading items that are no longer visible (with a buffer)
+ *
+ * When infinite scroll is disabled, it preserves the previous data and
+ * pagination info while loading, so the UI doesn't flash empty.
+ *
+ * In both cases, it tracks whether data has initially loaded.
+ *
+ * @param params                - Configuration parameters
+ * @param params.view           - Current view configuration
+ * @param params.data           - Current page of data
+ * @param params.getItemId      - Function to extract item ID
+ * @param params.isLoading      - Whether data is currently loading
+ * @param params.paginationInfo - Pagination info (totalItems, totalPages)
+ * @param params.selection      - Currently selected item IDs
+ * @return Object containing data, paginationInfo, hasInitiallyLoaded,
+ *         and optional setVisibleEntries callback
+ */
+export default function useData< Item >( {
+	view,
+	data: shownData,
+	getItemId,
+	isLoading,
+	paginationInfo,
+	selection,
+}: UseDataParams< Item > ): UseDataResult< Item > {
+	const isInfiniteScrollEnabled = view.infiniteScrollEnabled;
+
 	const [ hasInitiallyLoaded, setHasInitiallyLoaded ] = useState(
 		! isLoading
 	);
 	useEffect( () => {
 		if ( ! isLoading ) {
-			previousDataRef.current = data;
-			previousPaginationInfoRef.current = paginationInfo;
 			setHasInitiallyLoaded( true );
 		}
-	}, [ data, isLoading, paginationInfo ] );
-	return {
-		data:
+	}, [ isLoading ] );
+
+	const previousDataRef = useRef< Item[] >( shownData );
+	const previousPaginationInfoRef =
+		useRef< PaginationInfo >( paginationInfo );
+	useEffect( () => {
+		if ( ! isLoading ) {
+			previousDataRef.current = shownData;
+			previousPaginationInfoRef.current = paginationInfo;
+		}
+	}, [ shownData, isLoading, paginationInfo ] );
+
+	// Infinite scroll state.
+	const [ visibleEntries, setVisibleEntries ] = useState< number[] >( [] );
+
+	// Track the mapping of item IDs to their positions in the full dataset
+	const positionMapRef = useRef< Map< string, number > >( new Map() );
+
+	// Store accumulated records in a ref for persistence across renders
+	const allLoadedRecordsRef = useRef< Item[] >( [] );
+
+	// Track previous view parameters to detect when we need to reset
+	const prevViewParamsRef = useRef< {
+		search: string | undefined;
+		filters: string | undefined;
+		perPage: number | undefined;
+	} >( {
+		search: undefined,
+		filters: undefined,
+		perPage: undefined,
+	} );
+
+	// Determine scroll direction based on position changes
+	const scrollDirectionRef = useRef< 'up' | 'down' | undefined >( undefined );
+	const prevStartPositionRef = useRef< number | undefined >( undefined );
+
+	// Track whether we've done initial load
+	const hasInitializedRef = useRef( false );
+
+	// Compute data synchronously during render using useMemo
+	// This ensures the returned data is always in sync with shownData
+	const allLoadedRecords = useMemo( () => {
+		// Update scroll direction based on position changes
+		if (
+			view.startPosition !== undefined &&
+			prevStartPositionRef.current !== undefined
+		) {
+			if ( view.startPosition < prevStartPositionRef.current ) {
+				scrollDirectionRef.current = 'up';
+			} else if ( view.startPosition > prevStartPositionRef.current ) {
+				scrollDirectionRef.current = 'down';
+			}
+		}
+		prevStartPositionRef.current = view.startPosition;
+
+		// Serialize filters for comparison
+		const currentFiltersKey = JSON.stringify( view.filters ?? [] );
+		const prevFiltersKey = prevViewParamsRef.current.filters;
+
+		// Check if view parameters that require a reset have changed
+		const shouldReset =
+			! hasInitializedRef.current ||
+			! view.infiniteScrollEnabled ||
+			view.search !== prevViewParamsRef.current.search ||
+			currentFiltersKey !== prevFiltersKey ||
+			view.perPage !== prevViewParamsRef.current.perPage;
+		hasInitializedRef.current = true;
+		// Update tracked view parameters
+		prevViewParamsRef.current = {
+			search: view.search,
+			filters: currentFiltersKey,
+			perPage: view.perPage,
+		};
+
+		if ( shouldReset ) {
+			// Reset - clear position map and replace all data
+			positionMapRef.current.clear();
+			// Reset scroll direction to prevent stale directional filtering
+			scrollDirectionRef.current = undefined;
+			// Use the view's startPosition if defined, otherwise default to 1
+			const startPosition = view.search ? 1 : view.startPosition ?? 1;
+			const records = shownData.map( ( record, index ) => {
+				const position = startPosition + index;
+				positionMapRef.current.set( getItemId( record ), position );
+				return {
+					...record,
+					position,
+				};
+			} );
+			allLoadedRecordsRef.current = records;
+			return records;
+		}
+
+		// Subsequent pages - merge with existing data
+		const prev = allLoadedRecordsRef.current;
+		const shownDataIds = new Set( shownData.map( getItemId ) );
+		const scrollDirection = scrollDirectionRef.current;
+
+		// The position for each item in shownData should be based on the
+		// current startPosition from the view, which reflects the actual
+		// offset in the dataset. This ensures aria-posinset values are
+		// semantically correct - if startPosition is 40, there are exactly
+		// 39 items before the first item in shownData.
+		// When there's an active search, always start from position 1 since
+		// search results are a filtered subset, not a paginated view.
+		const basePosition = view.search ? 1 : view.startPosition ?? 1;
+		const newRecords = shownData.map( ( record, index ) => {
+			const itemId = getItemId( record );
+			const position = view.infiniteScrollEnabled
+				? basePosition + index
+				: undefined;
+
+			// Always update the position map with the correct position
+			// based on the current query's startPosition
+			if ( position !== undefined ) {
+				positionMapRef.current.set( itemId, position );
+			}
+
+			return {
+				...record,
+				position,
+			};
+		} );
+
+		if ( newRecords.length === 0 ) {
+			return prev;
+		}
+
+		// Remove duplicates from prev, keeping only records not in shownData
+		const prevWithoutDuplicates = prev.filter(
+			( record ) => ! shownDataIds.has( getItemId( record ) )
+		);
+
+		// Update the loaded range
+		const allRecords =
+			scrollDirection === 'up'
+				? [ ...newRecords, ...prevWithoutDuplicates ]
+				: [ ...prevWithoutDuplicates, ...newRecords ];
+
+		// Sort all records by position to ensure correct order
+		// This is crucial when items are reloaded after scrolling in different directions
+		allRecords.sort( ( a, b ) => {
+			const posA = ( a as Item & { position: number } ).position;
+			const posB = ( b as Item & { position: number } ).position;
+			return posA - posB;
+		} );
+
+		let result = allRecords;
+
+		if ( visibleEntries.length > 0 ) {
+			const visibleMin = Math.min( ...visibleEntries );
+			const visibleMax = Math.max( ...visibleEntries );
+			// Buffer size balances allowing new items to render (when prepended
+			// during scroll up) while unloading items no longer on screen.
+			// Use a larger buffer to prevent scrollbar from jumping when items
+			// are unloaded, which could trigger unwanted scroll events.
+			const buffer = 20;
+
+			const recordPositions = allRecords.map(
+				( r ) => ( r as Item & { position: number } ).position
+			);
+			const minRecordPos = Math.min( ...recordPositions );
+			const maxRecordPos = Math.max( ...recordPositions );
+
+			// Check if there's any overlap between visible range and actual record positions
+			// to avoid filtering when visibleEntries are stale (e.g., after search/filter reset)
+			const hasOverlap = ! (
+				maxRecordPos < visibleMin - buffer ||
+				minRecordPos > visibleMax + buffer
+			);
+
+			if ( hasOverlap ) {
+				result = allRecords.filter( ( record ) => {
+					const itemId = getItemId( record );
+					const isSelected = selection?.includes( itemId );
+					// Never unload selected items, even if outside visible range
+					if ( isSelected ) {
+						return true;
+					}
+
+					const itemPosition = (
+						record as Item & { position: number }
+					 ).position;
+					// When scrolling, only trim items from the end we're scrolling away from
+					if ( scrollDirection === 'up' ) {
+						// When scrolling up, only trim items below the visible range
+						return itemPosition <= visibleMax + buffer;
+					} else if ( scrollDirection === 'down' ) {
+						// When scrolling down, only trim items above the visible range
+						return itemPosition >= visibleMin - buffer;
+					}
+					// When not scrolling or first load, keep items within buffer range
+					return (
+						itemPosition >= visibleMin - buffer &&
+						itemPosition <= visibleMax + buffer
+					);
+				} );
+			}
+		}
+
+		allLoadedRecordsRef.current = result;
+		return result;
+	}, [
+		shownData,
+		view.search,
+		view.filters,
+		view.perPage,
+		view.startPosition,
+		view.infiniteScrollEnabled,
+		visibleEntries,
+		selection,
+		getItemId,
+	] );
+
+	// When infinite scroll is disabled, preserve previous data while loading
+	if ( ! isInfiniteScrollEnabled ) {
+		const dataToReturn =
 			isLoading && previousDataRef.current?.length
 				? previousDataRef.current
-				: data,
-		paginationInfo:
-			isLoading && previousDataRef.current?.length
-				? previousPaginationInfoRef.current
-				: paginationInfo,
+				: shownData;
+		return {
+			data: dataToReturn.map( ( item ) => ( {
+				...item,
+				position: undefined,
+			} ) ) as ( Item & { position?: number } )[],
+			paginationInfo:
+				isLoading && previousDataRef.current?.length
+					? previousPaginationInfoRef.current
+					: paginationInfo,
+			hasInitiallyLoaded,
+			setVisibleEntries: undefined,
+		};
+	}
+
+	return {
+		data: allLoadedRecords as ( Item & { position?: number } )[],
+		paginationInfo,
 		hasInitiallyLoaded,
+		setVisibleEntries,
 	};
 }

package/src/hooks/use-infinite-scroll.ts

@@ -0,0 +1,304 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	useCallback,
+	useEffect,
+	useLayoutEffect,
+	useRef,
+} from '@wordpress/element';
+import { throttle } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import type { View } from '../types';
+
+/**
+ * Captures an anchor element for scroll position preservation.
+ * Finds the element closest to the center of the viewport and stores its position.
+ *
+ * @param container        The scrollable container element.
+ * @param anchorElementRef Ref to store the anchor element data.
+ * @param direction        The scroll direction ('up' or 'down').
+ * @return Whether an anchor element was successfully captured.
+ */
+function captureAnchorElement(
+	container: HTMLElement,
+	anchorElementRef: React.MutableRefObject< {
+		posinset: number;
+		viewportOffset: number;
+		direction: 'up' | 'down' | null;
+	} | null >,
+	direction: 'up' | 'down'
+): boolean {
+	// Find a visible element to use as anchor - prefer one in the middle of the viewport
+	const containerRect = container.getBoundingClientRect();
+	const centerY = containerRect.top + containerRect.height / 2;
+
+	// Query all items with aria-posinset and find the one closest to center
+	const items = Array.from( container.querySelectorAll( '[aria-posinset]' ) );
+
+	if ( items.length === 0 ) {
+		return false;
+	}
+
+	// Find the item closest to the center of the viewport
+	const bestAnchor = items.reduce( ( best, item ) => {
+		const itemRect = item.getBoundingClientRect();
+		const itemCenterY = itemRect.top + itemRect.height / 2;
+		const distance = Math.abs( itemCenterY - centerY );
+
+		const bestRect = best.getBoundingClientRect();
+		const bestCenterY = bestRect.top + bestRect.height / 2;
+		const bestDistance = Math.abs( bestCenterY - centerY );
+
+		return distance < bestDistance ? item : best;
+	} );
+
+	const posinset = Number( bestAnchor.getAttribute( 'aria-posinset' ) );
+	const anchorRect = bestAnchor.getBoundingClientRect();
+	anchorElementRef.current = {
+		posinset,
+		viewportOffset: anchorRect.top - containerRect.top,
+		direction,
+	};
+	return true;
+}
+
+type UseInfiniteScrollProps = {
+	view: View;
+	onChangeView: ( view: View ) => void;
+	isLoading: boolean;
+	paginationInfo: {
+		totalItems: number;
+		totalPages: number;
+	};
+	containerRef: React.MutableRefObject< HTMLDivElement | null >;
+	setVisibleEntries?: React.Dispatch< React.SetStateAction< number[] > >;
+};
+
+type UseInfiniteScrollResult = {
+	intersectionObserver?: IntersectionObserver | null;
+};
+
+export function useInfiniteScroll( {
+	view,
+	onChangeView,
+	isLoading,
+	paginationInfo,
+	containerRef,
+	setVisibleEntries,
+}: UseInfiniteScrollProps ): UseInfiniteScrollResult {
+	// Track an anchor element for scroll position preservation
+	// This approach is robust even when items are added/removed from both ends simultaneously
+	const anchorElementRef = useRef< {
+		posinset: number;
+		viewportOffset: number;
+		direction: 'up' | 'down' | null;
+	} | null >( null );
+	const viewRef = useRef( view );
+	const isLoadingRef = useRef( isLoading );
+	const onChangeViewRef = useRef( onChangeView );
+	const totalItemsRef = useRef( paginationInfo.totalItems );
+
+	useLayoutEffect( () => {
+		viewRef.current = view;
+		isLoadingRef.current = isLoading;
+		onChangeViewRef.current = onChangeView;
+		totalItemsRef.current = paginationInfo.totalItems;
+	}, [ view, isLoading, onChangeView, paginationInfo.totalItems ] );
+
+	const intersectionObserverCallback: IntersectionObserverCallback =
+		useCallback(
+			( entries: IntersectionObserverEntry[] ) => {
+				// Calculate new visible entries outside of setState
+				if ( ! setVisibleEntries ) {
+					return;
+				}
+				setVisibleEntries( ( prev: number[] ) => {
+					const newVisibleEntries = new Set( prev );
+					let hasChanged = false;
+
+					entries.forEach( ( entry ) => {
+						const posInSet = Number(
+							entry.target?.attributes?.getNamedItem(
+								'aria-posinset'
+							)?.value
+						);
+						if ( isNaN( posInSet ) ) {
+							return;
+						}
+						if ( entry.isIntersecting ) {
+							if ( ! newVisibleEntries.has( posInSet ) ) {
+								newVisibleEntries.add( posInSet );
+								hasChanged = true;
+							}
+						} else if ( newVisibleEntries.has( posInSet ) ) {
+							newVisibleEntries.delete( posInSet );
+							hasChanged = true;
+						}
+					} );
+
+					// Only return new array if something actually changed
+					return hasChanged
+						? Array.from( newVisibleEntries ).sort()
+						: prev;
+				} );
+			},
+			[ setVisibleEntries ]
+		);
+
+	// Preserve scroll position when items are added or removed during infinite scroll
+	// Uses anchor element approach: find the same element after render and restore its viewport position
+	useLayoutEffect( () => {
+		const container = containerRef.current;
+		const anchor = anchorElementRef.current;
+
+		if (
+			! container ||
+			! view.infiniteScrollEnabled ||
+			! anchor ||
+			isLoading
+		) {
+			return;
+		}
+
+		// Find the anchor element by its posinset
+		const anchorElement = container.querySelector(
+			`[aria-posinset="${ anchor.posinset }"]`
+		);
+
+		if ( anchorElement ) {
+			const containerRect = container.getBoundingClientRect();
+			const anchorRect = anchorElement.getBoundingClientRect();
+			const currentOffset = anchorRect.top - containerRect.top;
+
+			// Calculate how much the anchor has moved and adjust scroll to compensate
+			const scrollAdjustment = currentOffset - anchor.viewportOffset;
+
+			if ( Math.abs( scrollAdjustment ) > 1 ) {
+				container.scrollTop += scrollAdjustment;
+			}
+		}
+
+		// Reset the anchor state now that we've adjusted
+		anchorElementRef.current = null;
+	}, [ containerRef, isLoading, view.infiniteScrollEnabled ] );
+
+	// Create and expose a shared IntersectionObserver for provider-level reuse.
+	const intersectionObserverRef = useRef< IntersectionObserver | null >(
+		null
+	);
+	useEffect( () => {
+		if ( ! view.infiniteScrollEnabled || ! intersectionObserverCallback ) {
+			if ( intersectionObserverRef.current ) {
+				intersectionObserverRef.current.disconnect();
+				intersectionObserverRef.current = null;
+			}
+			return;
+		}
+
+		intersectionObserverRef.current = new IntersectionObserver(
+			intersectionObserverCallback,
+			{ root: null, rootMargin: '0px', threshold: 0.1 }
+		);
+
+		return () => {
+			if ( intersectionObserverRef.current ) {
+				intersectionObserverRef.current.disconnect();
+				intersectionObserverRef.current = null;
+			}
+		};
+	}, [ view.infiniteScrollEnabled, intersectionObserverCallback ] );
+
+	// Attach scroll event listener for infinite scroll
+	useEffect( () => {
+		if ( ! view.infiniteScrollEnabled || ! containerRef.current ) {
+			return;
+		}
+
+		let lastScrollTop = 0;
+		// Use larger thresholds to trigger loading earlier during fast scrolling
+		const BOTTOM_THRESHOLD = 600; // px from bottom to trigger load
+		const TOP_THRESHOLD = 800; // px from top to trigger load
+
+		const handleScroll = throttle( ( event: unknown ) => {
+			const currentView = viewRef.current;
+			const totalItems = totalItemsRef.current;
+			const target = ( event as Event ).target as HTMLElement;
+			const scrollTop = target.scrollTop;
+			const scrollHeight = target.scrollHeight;
+			const clientHeight = target.clientHeight;
+
+			// Determine scroll direction
+			const scrollDirection = scrollTop > lastScrollTop ? 'down' : 'up';
+			lastScrollTop = scrollTop;
+
+			// Don't trigger if already loading
+			if ( isLoadingRef.current ) {
+				return;
+			}
+
+			const currentStartPosition = currentView.startPosition || 1;
+			const batchSize = currentView.perPage || 10;
+			const currentEndPosition = Math.min(
+				currentStartPosition + batchSize,
+				totalItems
+			);
+
+			// Check if user has scrolled near the bottom
+			if (
+				scrollDirection === 'down' &&
+				scrollTop + clientHeight >= scrollHeight - BOTTOM_THRESHOLD
+			) {
+				// Check if there's more data to load
+				if ( currentEndPosition < totalItems ) {
+					const newStartPosition = currentEndPosition;
+
+					// Capture anchor element for scroll position preservation
+					captureAnchorElement( target, anchorElementRef, 'down' );
+
+					onChangeViewRef.current( {
+						...currentView,
+						startPosition: newStartPosition,
+					} );
+				}
+			}
+
+			// Check if user has scrolled near the top
+			if ( scrollDirection === 'up' && scrollTop <= TOP_THRESHOLD ) {
+				// Check if there's more data to load
+				if ( currentStartPosition > 1 ) {
+					// Round to 1 if we're close to the beginning to avoid tiny batches
+					const calculatedStartPosition =
+						currentStartPosition - batchSize;
+					const newStartPosition =
+						calculatedStartPosition < 6
+							? 1
+							: calculatedStartPosition;
+
+					// Capture anchor element for scroll position preservation
+					captureAnchorElement( target, anchorElementRef, 'up' );
+
+					onChangeViewRef.current( {
+						...currentView,
+						startPosition: newStartPosition,
+					} );
+				}
+			}
+		}, 50 ); // Faster throttle (50ms) for better response to fast scrolling
+
+		const container = containerRef.current;
+		container.addEventListener( 'scroll', handleScroll );
+
+		return () => {
+			container.removeEventListener( 'scroll', handleScroll );
+			handleScroll.cancel(); // Cancel any pending throttled calls
+		};
+	}, [ containerRef, view.infiniteScrollEnabled ] );
+
+	return {
+		intersectionObserver: intersectionObserverRef.current,
+	};
+}

package/src/hooks/use-selected-items.ts

@@ -0,0 +1,72 @@
+/**
+ * WordPress dependencies
+ */
+import { useMemo, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { View } from '../types';
+
+/**
+ * Hook to get selected items, with support for infinite scroll.
+ *
+ * When infinite scroll is enabled, items that scroll out of view are cached
+ * so they remain available for bulk actions even when not in the current data set.
+ *
+ * @param view      The current view configuration.
+ * @param data      The current page of data items.
+ * @param selection Array of selected item IDs.
+ * @param getItemId Function to get the ID of an item.
+ * @param filterFn  Optional filter function to apply to selected items (e.g., for selectability).
+ * @return Array of selected items.
+ */
+export default function useSelectedItems< Item >(
+	view: View,
+	data: Item[],
+	selection: string[],
+	getItemId: ( item: Item ) => string,
+	filterFn?: ( item: Item ) => boolean
+): Item[] {
+	// With infinite scroll enabled items scroll out of view, but we want to keep the selection unaltered,
+	// unlike page-based navigation where we might clear selection upon navigating to a different page.
+	const selectedItemsCacheRef = useRef< Map< string, Item > >( new Map() );
+
+	return useMemo( () => {
+		const selectionSet = new Set( selection );
+
+		if ( view.infiniteScrollEnabled ) {
+			// Selection array contains selected item IDs
+			// Cache selected items so they remain available when scrolled out of view
+			data.forEach( ( item ) => {
+				const id = getItemId( item );
+				if ( selectionSet.has( id ) ) {
+					const passesFilter = filterFn ? filterFn( item ) : true;
+					if ( passesFilter ) {
+						selectedItemsCacheRef.current.set( id, item );
+					}
+				}
+			} );
+
+			// Remove items from cache that are no longer selected
+			selectedItemsCacheRef.current.forEach( ( _, id ) => {
+				if ( ! selectionSet.has( id ) ) {
+					selectedItemsCacheRef.current.delete( id );
+				}
+			} );
+
+			// Return all cached selected items
+			return Array.from( selectedItemsCacheRef.current.values() );
+		}
+
+		// Non-infinite scroll mode
+		return data.filter( ( item ) => {
+			const id = getItemId( item );
+			if ( ! selectionSet.has( id ) ) {
+				return false;
+			}
+			// Apply optional filter (e.g., selectability check for bulk actions)
+			return filterFn ? filterFn( item ) : true;
+		} );
+	}, [ view.infiniteScrollEnabled, selection, getItemId, data, filterFn ] );
+}