@wordpress/compose 8.4.0 → 8.6.0

package/src/hooks/use-dialog/index.ts

@@ -1,21 +1,10 @@
-/**
- * External dependencies
- */
 import type {
 	KeyboardEvent,
 	KeyboardEventHandler,
 	RefCallback,
 	SyntheticEvent,
 } from 'react';
-
-/**
- * WordPress dependencies
- */
 import { useRef, useEffect, useCallback } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import useConstrainedTabbing from '../use-constrained-tabbing';
 import { useFocusOnMount } from '../use-focus-on-mount';
 import useFocusReturn from '../use-focus-return';

package/src/hooks/use-dialog/test/index.tsx

@@ -1,13 +1,6 @@
-/**
- * External dependencies
- */
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { createPortal } from 'react-dom';
-
-/**
- * Internal dependencies
- */
 import useDialog from '..';
 
 function Dialog( { onClose }: { onClose?: () => void } ) {

package/src/hooks/use-disabled/index.ts

@@ -1,6 +1,3 @@
-/**
- * Internal dependencies
- */
 import { debounce } from '../../utils/debounce';
 import useRefEffect from '../use-ref-effect';
 

package/src/hooks/use-disabled/test/index.js

@@ -1,16 +1,5 @@
-/**
- * External dependencies
- */
 import { render, screen, waitFor } from '@testing-library/react';
-
-/**
- * WordPress dependencies
- */
 import { forwardRef } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import useDisabled from '../';
 
 describe( 'useDisabled', () => {

package/src/hooks/use-dragging/README.md

@@ -54,9 +54,6 @@ A boolean value, when true it means dragging is currently taking place; when fal
 The following example allows us to drag & drop a red square around the entire viewport.
 
 ```jsx
-/**
- * WordPress dependencies
- */
 import { useState, useCallback } from 'react';
 import { __experimentalUseDragging as useDragging } from '@wordpress/compose';
 

package/src/hooks/use-dragging/index.ts

@@ -1,11 +1,4 @@
-/**
- * WordPress dependencies
- */
 import { useCallback, useEffect, useRef, useState } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import useIsomorphicLayoutEffect from '../use-isomorphic-layout-effect';
 import type { DraggingProps, DraggingReturn } from './types';
 

package/src/hooks/use-drop-zone/index.ts

@@ -1,6 +1,3 @@
-/**
- * Internal dependencies
- */
 import useRefEffect from '../use-ref-effect';
 import useEvent from '../use-event';
 import type { UseDropZoneProps } from './types';

package/src/hooks/use-drop-zone/test/index.js

@@ -1,16 +1,5 @@
-/**
- * External dependencies
- */
 import { render, screen } from '@testing-library/react';
-
-/**
- * WordPress dependencies
- */
 import { useState } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import useDropZone from '../';
 
 describe( 'useDropZone', () => {

package/src/hooks/use-event/index.ts

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { useRef, useInsertionEffect, useCallback } from '@wordpress/element';
 
 /**

package/src/hooks/use-fixed-window-list/index.ts

@@ -1,19 +1,12 @@
-/**
- * WordPress dependencies
- */
-import { useState, useLayoutEffect } from '@wordpress/element';
+import { useState, useLayoutEffect, useRef } from '@wordpress/element';
 import { getScrollContainer } from '@wordpress/dom';
 import { PAGEUP, PAGEDOWN, HOME, END } from '@wordpress/keycodes';
-
-/**
- * Internal dependencies
- */
-import { debounce } from '../../utils/debounce';
+import useEvent from '../use-event';
 
 const DEFAULT_INIT_WINDOW_SIZE = 30;
 
 interface FixedWindowList {
-	/** Items visible in the current viewport */
+	/** Items visible in the viewport, as of the last rendered window */
 	visibleItems: number;
 	/** Start index of the window */
 	start: number;
@@ -51,8 +44,12 @@ export default function useFixedWindowList(
 	FixedWindowList,
 	React.Dispatch< React.SetStateAction< FixedWindowList > >,
 ] {
-	const initWindowSize = options?.initWindowSize ?? DEFAULT_INIT_WINDOW_SIZE;
-	const useWindowing = options?.useWindowing ?? true;
+	const {
+		windowOverscan,
+		useWindowing = true,
+		initWindowSize = DEFAULT_INIT_WINDOW_SIZE,
+		expandedState,
+	} = options ?? {};
 
 	const [ fixedListWindow, setFixedListWindow ] = useState< FixedWindowList >(
 		{
@@ -65,137 +62,152 @@ export default function useFixedWindowList(
 		}
 	);
 
-	useLayoutEffect( () => {
-		if ( ! useWindowing ) {
+	// Kept out of state so that measuring the list does not, on its own, force a
+	// re-render. Only the rendered window does that.
+	const visibleItemsRef = useRef( initWindowSize );
+
+	// The measuring effect re-runs whenever the list changes, so the effect
+	// running can't on its own tell the very first measurement from later ones.
+	const isFirstMeasurementRef = useRef( true );
+
+	// Stable identity, so the listeners below never have to be re-attached, and
+	// reads the latest props on every call.
+	const measureWindow = useEvent( ( initRender?: boolean ) => {
+		const scrollContainer = getScrollContainer( elementRef.current );
+		if ( ! scrollContainer ) {
 			return;
 		}
-		const scrollContainer = getScrollContainer( elementRef.current );
-		/**
-		 *  Measures and sets the window of items to render based on the scroll position
-		 *
-		 * @param {boolean} [initRender] Indicates if this is the initial render
-		 * @return {void}
-		 */
-		const measureWindow = ( initRender?: boolean ) => {
-			if ( ! scrollContainer ) {
-				return;
-			}
-			const visibleItems = Math.ceil(
-				scrollContainer.clientHeight / itemHeight
-			);
-			// Aim to keep opening list view fast, afterward we can optimize for scrolling.
-			const windowOverscan = initRender
-				? visibleItems
-				: options?.windowOverscan ?? visibleItems;
-			const firstViewableIndex = Math.floor(
-				scrollContainer.scrollTop / itemHeight
-			);
-			const start = Math.max( 0, firstViewableIndex - windowOverscan );
-			const end = Math.min(
-				totalItems - 1,
-				firstViewableIndex + visibleItems + windowOverscan
-			);
-			setFixedListWindow( ( lastWindow ) => {
-				const nextWindow = {
-					visibleItems,
-					start,
-					end,
-					itemInView: ( index: number ) => {
-						return start <= index && index <= end;
-					},
-				};
-				if (
-					lastWindow.start !== nextWindow.start ||
-					lastWindow.end !== nextWindow.end ||
-					lastWindow.visibleItems !== nextWindow.visibleItems
-				) {
-					return nextWindow;
-				}
-				return lastWindow;
-			} );
-		};
-
-		measureWindow( true );
-		const debounceMeasureList = debounce( () => {
-			measureWindow();
-		}, 16 );
-		scrollContainer?.addEventListener( 'scroll', debounceMeasureList );
-		scrollContainer?.ownerDocument?.defaultView?.addEventListener(
-			'resize',
-			debounceMeasureList
+		const visibleItems = Math.ceil(
+			scrollContainer.clientHeight / itemHeight
 		);
-		scrollContainer?.ownerDocument?.defaultView?.addEventListener(
-			'resize',
-			debounceMeasureList
+		visibleItemsRef.current = visibleItems;
+		const isFirstMeasurement = isFirstMeasurementRef.current;
+		isFirstMeasurementRef.current = false;
+		// Aim to keep opening list view fast, afterward we can optimize for scrolling.
+		const overscan = initRender
+			? visibleItems
+			: windowOverscan ?? visibleItems;
+		const firstViewableIndex = Math.floor(
+			scrollContainer.scrollTop / itemHeight
 		);
+		const start = Math.max( 0, firstViewableIndex - overscan );
+		const end = Math.min(
+			totalItems - 1,
+			firstViewableIndex + visibleItems + overscan
+		);
+		setFixedListWindow( ( lastWindow ) => {
+			// Rendering the window is the expensive part, and for the items in
+			// `lastWindow` it is already paid for. When the next window has
+			// nothing to add, keep the current one: a window that only shrinks
+			// drops nodes that are known to be needed again and forces another
+			// style recalculation, with nothing new to show for it.
+			if ( lastWindow.start <= start && lastWindow.end >= end ) {
+				return lastWindow;
+			}
+			// The first window is rendered before the list can be measured, so
+			// it is sized by `initWindowSize` rather than by the viewport, and
+			// the measured window is normally wider than it by the overscan.
+			// Nothing has painted yet though, so there is no scrolling for the
+			// overscan to absorb: covering the visible items is enough, and
+			// keeping that window saves a render pass while the list opens.
+			if (
+				isFirstMeasurement &&
+				lastWindow.start <= firstViewableIndex &&
+				lastWindow.end >= firstViewableIndex + visibleItems
+			) {
+				return lastWindow;
+			}
+			return {
+				visibleItems,
+				start,
+				end,
+				itemInView: ( index: number ) => {
+					return start <= index && index <= end;
+				},
+			};
+		} );
+	} );
 
-		return () => {
-			scrollContainer?.removeEventListener(
-				'scroll',
-				debounceMeasureList
-			);
-			scrollContainer?.ownerDocument?.defaultView?.removeEventListener(
-				'resize',
-				debounceMeasureList
-			);
-		};
-	}, [
-		itemHeight,
-		elementRef,
-		totalItems,
-		options?.expandedState,
-		options?.windowOverscan,
-		useWindowing,
-	] );
-
-	useLayoutEffect( () => {
-		if ( ! useWindowing ) {
-			return;
-		}
-		const scrollContainer = getScrollContainer( elementRef.current );
-		const handleKeyDown = ( event: KeyboardEvent ) => {
+	const handleKeyDown = useEvent(
+		( event: KeyboardEvent, scrollContainer: Element ) => {
 			switch ( event.keyCode ) {
 				case HOME: {
-					return scrollContainer?.scrollTo( { top: 0 } );
+					return scrollContainer.scrollTo( { top: 0 } );
 				}
 				case END: {
-					return scrollContainer?.scrollTo( {
+					return scrollContainer.scrollTo( {
 						top: totalItems * itemHeight,
 					} );
 				}
 				case PAGEUP: {
-					return scrollContainer?.scrollTo( {
+					return scrollContainer.scrollTo( {
 						top:
 							scrollContainer.scrollTop -
-							fixedListWindow.visibleItems * itemHeight,
+							visibleItemsRef.current * itemHeight,
 					} );
 				}
 				case PAGEDOWN: {
-					return scrollContainer?.scrollTo( {
+					return scrollContainer.scrollTo( {
 						top:
 							scrollContainer.scrollTop +
-							fixedListWindow.visibleItems * itemHeight,
+							visibleItemsRef.current * itemHeight,
 					} );
 				}
 			}
-		};
-		scrollContainer?.ownerDocument?.defaultView?.addEventListener(
-			'keydown',
-			handleKeyDown
-		);
+		}
+	);
+
+	// Measure whenever something that the window is derived from changes.
+	useLayoutEffect( () => {
+		if ( ! useWindowing ) {
+			return;
+		}
+		measureWindow( true );
+	}, [
+		useWindowing,
+		measureWindow,
+		itemHeight,
+		totalItems,
+		windowOverscan,
+		expandedState,
+	] );
+
+	// Only ever attaches and detaches listeners. The deps are the things that
+	// can change which element the scroll container is, or whether there is one
+	// at all: a list that is too short to overflow has no scroll container to
+	// attach to, and it grows into one by gaining items or by being expanded.
+	useLayoutEffect( () => {
+		if ( ! useWindowing ) {
+			return;
+		}
+		const scrollContainer = getScrollContainer( elementRef.current );
+		if ( ! scrollContainer ) {
+			return;
+		}
+		const { defaultView } = scrollContainer.ownerDocument;
+		// `scroll` and `resize` already fire at about the rendering rate, so
+		// there is nothing to gain from debouncing them.
+		const onMeasure = () => measureWindow();
+		const onKeyDown = ( event: KeyboardEvent ) =>
+			handleKeyDown( event, scrollContainer );
+
+		scrollContainer.addEventListener( 'scroll', onMeasure );
+		defaultView?.addEventListener( 'resize', onMeasure );
+		defaultView?.addEventListener( 'keydown', onKeyDown );
+
 		return () => {
-			scrollContainer?.ownerDocument?.defaultView?.removeEventListener(
-				'keydown',
-				handleKeyDown
-			);
+			scrollContainer.removeEventListener( 'scroll', onMeasure );
+			defaultView?.removeEventListener( 'resize', onMeasure );
+			defaultView?.removeEventListener( 'keydown', onKeyDown );
 		};
 	}, [
-		totalItems,
-		itemHeight,
-		elementRef,
-		fixedListWindow.visibleItems,
 		useWindowing,
-		options?.expandedState,
+		elementRef,
+		itemHeight,
+		totalItems,
+		expandedState,
+		measureWindow,
+		handleKeyDown,
 	] );
 
 	return [ fixedListWindow, setFixedListWindow ];

package/src/hooks/use-focus-outside/index.ts

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { useCallback, useEffect, useRef } from '@wordpress/element';
 
 /**

package/src/hooks/use-focus-outside/test/index.js

@@ -1,12 +1,5 @@
-/**
- * External dependencies
- */
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-
-/**
- * Internal dependencies
- */
 import useFocusOutside from '../';
 
 const FocusOutsideComponent = ( { onFocusOutside: callback } ) => (

package/src/hooks/use-focus-return/index.ts

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { useRef, useEffect, useCallback } from '@wordpress/element';
 
 let origin: Element | null = null;

package/src/hooks/use-focusable-iframe/index.ts

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { RefCallback } from 'react';
-
-/**
- * Internal dependencies
- */
 import useRefEffect from '../use-ref-effect';
 
 /**

package/src/hooks/use-instance-id/README.md

@@ -5,9 +5,6 @@ Some components need to generate a unique id for each instance. This could serve
 ## Usage
 
 ```jsx
-/**
- * WordPress dependencies
- */
 import { useInstanceId } from '@wordpress/compose';
 
 function MyCustomElement() {

package/src/hooks/use-instance-id/index.ts

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { useMemo } from '@wordpress/element';
 
 const instanceMap = new WeakMap< object, number >();

package/src/hooks/use-instance-id/test/index.js

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import { render } from '@testing-library/react';
-
-/**
- * Internal dependencies
- */
 import useInstanceId from '../';
 
 describe( 'useInstanceId', () => {

package/src/hooks/use-isomorphic-layout-effect/index.ts

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { useEffect, useLayoutEffect } from '@wordpress/element';
 
 /**

package/src/hooks/use-keyboard-shortcut/index.ts

@@ -1,13 +1,6 @@
-/**
- * External dependencies
- */
 import Mousetrap from 'mousetrap';
 import 'mousetrap/plugins/global-bind/mousetrap-global-bind.js';
 import type { ExtendedKeyboardEvent } from 'mousetrap';
-
-/**
- * WordPress dependencies
- */
 import type { RefObject } from '@wordpress/element';
 import { useEffect, useRef } from '@wordpress/element';
 import { isAppleOS } from '@wordpress/keycodes';

package/src/hooks/use-media-query/index.ts

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { useSyncExternalStore } from '@wordpress/element';
 
 type MQLSubscriber = {

package/src/hooks/use-media-query/test/index.js

@@ -1,12 +1,5 @@
-/**
- * External dependencies
- */
 import { act, render } from '@testing-library/react';
 import { matchMedia, setMedia } from 'mock-match-media';
-
-/**
- * Internal dependencies
- */
 import useMediaQuery from '../';
 
 const TestComponent = ( { query } ) => {

package/src/hooks/use-media-query/test/ssr.js

@@ -1,15 +1,7 @@
 /**
  * @jest-environment node
  */
-
-/**
- * External dependencies
- */
 import { renderToString } from 'react-dom/server';
-
-/**
- * Internal dependencies
- */
 import useMediaQuery from '../';
 import useViewportMatch from '../../use-viewport-match';
 

package/src/hooks/use-merge-refs/index.ts

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { useRef, useCallback, useLayoutEffect } from '@wordpress/element';
 import type { MutableRefObject, Ref, RefCallback } from 'react';
 

package/src/hooks/use-merge-refs/test/index.js

@@ -1,16 +1,5 @@
-/**
- * External dependencies
- */
 import { render, screen, fireEvent } from '@testing-library/react';
-
-/**
- * WordPress dependencies
- */
 import { useCallback, useState } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import useMergeRefs from '../';
 
 describe( 'useMergeRefs', () => {

package/src/hooks/use-observable-value/index.ts

@@ -1,11 +1,4 @@
-/**
- * WordPress dependencies
- */
 import { useMemo, useSyncExternalStore } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import type { ObservableMap } from '../../utils/observable-map';
 
 /**

package/src/hooks/use-observable-value/test/index.js

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import { render, screen, act } from '@testing-library/react';
-
-/**
- * Internal dependencies
- */
 import { observableMap } from '../../../utils/observable-map';
 import useObservableValue from '..';
 

package/src/hooks/use-previous/README.md

@@ -5,9 +5,6 @@ Sometimes you need to get the value something had on the previous render. `usePr
 ## Usage
 
 ```jsx
-/**
- * WordPress dependencies
- */
 import { useEffect, useState } from 'react';
 import { usePrevious } from '@wordpress/compose';
 

package/src/hooks/use-previous/index.ts

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { useEffect, useRef } from '@wordpress/element';
 
 /**

package/src/hooks/use-reduced-motion/index.ts

@@ -1,6 +1,3 @@
-/**
- * Internal dependencies
- */
 import useMediaQuery from '../use-media-query';
 
 /**

package/src/hooks/use-ref-effect/index.ts

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { DependencyList, RefCallback } from 'react';
-
-/**
- * WordPress dependencies
- */
 import { useCallback, useRef } from '@wordpress/element';
 
 /**

package/src/hooks/use-resize-observer/index.ts

@@ -1,13 +1,7 @@
-/**
- * Internal dependencies
- */
+import type { ReactElement } from 'react';
 import { useResizeObserver as _useResizeObserver } from './use-resize-observer';
 import type { ObservedSize } from './legacy';
 import _useLegacyResizeObserver from './legacy';
-/**
- * External dependencies
- */
-import type { ReactElement } from 'react';
 
 /**
  * Sets up a [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Resize_Observer_API)

package/src/hooks/use-resize-observer/legacy/index.tsx

@@ -1,15 +1,5 @@
-/**
- * External dependencies
- */
 import type { ReactElement } from 'react';
-
-/**
- * WordPress dependencies
- */
 import { useCallback, useRef, useState } from '@wordpress/element';
-/**
- * Internal dependencies
- */
 import { useResizeObserver } from '../use-resize-observer';
 
 export type ObservedSize = {