@wordpress/compose 8.1.0 → 8.1.2-next.v.202606191442.0

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

@@ -0,0 +1,78 @@
+/**
+ * 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';
+
+/**
+ * Hook to manage drag events with proper event handling
+ *
+ * @param props             Drag handlers
+ * @param props.onDragStart
+ * @param props.onDragMove
+ * @param props.onDragEnd
+ * @return Drag state and handlers
+ */
+export default function useDragging( {
+	onDragStart,
+	onDragMove,
+	onDragEnd,
+}: DraggingProps ): DraggingReturn {
+	const [ isDragging, setIsDragging ] = useState( false );
+
+	const eventsRef = useRef< DraggingProps >( {
+		onDragStart,
+		onDragMove,
+		onDragEnd,
+	} );
+	useIsomorphicLayoutEffect( () => {
+		eventsRef.current.onDragStart = onDragStart;
+		eventsRef.current.onDragMove = onDragMove;
+		eventsRef.current.onDragEnd = onDragEnd;
+	}, [ onDragStart, onDragMove, onDragEnd ] );
+
+	const onMouseMove = useCallback( ( event: MouseEvent ): void => {
+		eventsRef.current.onDragMove?.( event );
+	}, [] );
+
+	const endDrag = useCallback(
+		function endDrag( event?: MouseEvent ): void {
+			eventsRef.current.onDragEnd?.( event );
+			document.removeEventListener( 'mousemove', onMouseMove );
+			document.removeEventListener( 'mouseup', endDrag );
+			setIsDragging( false );
+		},
+		[ onMouseMove ]
+	);
+
+	const startDrag = useCallback(
+		( event: React.MouseEvent ): void => {
+			eventsRef.current.onDragStart?.( event );
+			document.addEventListener( 'mousemove', onMouseMove );
+			document.addEventListener( 'mouseup', endDrag );
+			setIsDragging( true );
+		},
+		[ onMouseMove, endDrag ]
+	);
+
+	// Remove the global events when unmounting if needed.
+	useEffect( () => {
+		return () => {
+			if ( isDragging ) {
+				document.removeEventListener( 'mousemove', onMouseMove );
+				document.removeEventListener( 'mouseup', endDrag );
+			}
+		};
+	}, [ isDragging, onMouseMove, endDrag ] );
+
+	return {
+		startDrag,
+		endDrag,
+		isDragging,
+	};
+}

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

@@ -0,0 +1,11 @@
+export interface DraggingProps {
+	onDragStart?: ( e: React.MouseEvent ) => void;
+	onDragMove?: ( e: MouseEvent ) => void;
+	onDragEnd?: ( e?: MouseEvent ) => void;
+}
+
+export interface DraggingReturn {
+	startDrag: ( e: React.MouseEvent ) => void;
+	endDrag: ( e?: MouseEvent ) => void;
+	isDragging: boolean;
+}

package/src/hooks/use-drop-zone/README.md

@@ -2,7 +2,7 @@
 
 A hook to facilitate drag and drop handling within a designated drop zone area. An optional `dropZoneElement` can be provided, however by default the drop zone is bound by the area where the returned `ref` is assigned.
 
-When using a `dropZoneElement`, it is expected that the `ref` will be attached to a node that is a descendent of the `dropZoneElement`. Additionally, the element passed to `dropZoneElement` should be stored in state rather than a plain ref to ensure reactive updating when it changes.
+When using a `dropZoneElement`, it is expected that the `ref` will be attached to a node that is a descendant of the `dropZoneElement`. Additionally, the element passed to `dropZoneElement` should be stored in state rather than a plain ref to ensure reactive updating when it changes.
 
 ## Usage
 

package/src/hooks/use-drop-zone/{index.js → index.ts}

@@ -3,21 +3,13 @@
  */
 import useRefEffect from '../use-ref-effect';
 import useEvent from '../use-event';
+import type { UseDropZoneProps } from './types';
 
 /**
  * A hook to facilitate drag and drop handling.
  *
- * @param {Object}                  props                   Named parameters.
- * @param {?HTMLElement}            [props.dropZoneElement] Optional element to be used as the drop zone.
- * @param {boolean}                 [props.isDisabled]      Whether or not to disable the drop zone.
- * @param {(e: DragEvent) => void}  [props.onDragStart]     Called when dragging has started.
- * @param {(e: DragEvent) => void}  [props.onDragEnter]     Called when the zone is entered.
- * @param {(e: DragEvent) => void}  [props.onDragOver]      Called when the zone is moved within.
- * @param {(e: DragEvent) => void}  [props.onDragLeave]     Called when the zone is left.
- * @param {(e: MouseEvent) => void} [props.onDragEnd]       Called when dragging has ended.
- * @param {(e: DragEvent) => void}  [props.onDrop]          Called when dropping in the zone.
- *
- * @return {React.RefCallback<HTMLElement>} Ref callback to be passed to the drop zone element.
+ * @param {UseDropZoneProps} props Hook options
+ * @return Ref callback to be passed to the drop zone element.
  */
 export default function useDropZone( {
 	dropZoneElement,
@@ -28,7 +20,7 @@ export default function useDropZone( {
 	onDragLeave: _onDragLeave,
 	onDragEnd: _onDragEnd,
 	onDragOver: _onDragOver,
-} ) {
+}: UseDropZoneProps ): React.RefCallback< HTMLElement > {
 	const onDropEvent = useEvent( _onDrop );
 	const onDragStartEvent = useEvent( _onDragStart );
 	const onDragEnterEvent = useEvent( _onDragEnter );
@@ -37,7 +29,7 @@ export default function useDropZone( {
 	const onDragOverEvent = useEvent( _onDragOver );
 
 	return useRefEffect(
-		( elem ) => {
+		( elem: HTMLElement ) => {
 			if ( isDisabled ) {
 				return;
 			}
@@ -58,7 +50,9 @@ export default function useDropZone( {
 			 *
 			 * @return {boolean} True if in drop zone, false if not.
 			 */
-			function isElementInZone( targetToCheck ) {
+			function isElementInZone(
+				targetToCheck: EventTarget | null
+			): boolean {
 				const { defaultView } = ownerDocument;
 
 				if (
@@ -70,8 +64,7 @@ export default function useDropZone( {
 					return false;
 				}
 
-				/** @type {HTMLElement|null} */
-				let elementToCheck = targetToCheck;
+				let elementToCheck: HTMLElement | null = targetToCheck;
 
 				do {
 					if ( elementToCheck.dataset.isDropZone ) {
@@ -82,7 +75,7 @@ export default function useDropZone( {
 				return false;
 			}
 
-			function maybeDragStart( /** @type {DragEvent} */ event ) {
+			function maybeDragStart( event: DragEvent ): void {
 				if ( isDragging ) {
 					return;
 				}
@@ -101,18 +94,14 @@ export default function useDropZone( {
 				}
 			}
 
-			function onDragEnter( /** @type {DragEvent} */ event ) {
+			function onDragEnter( event: DragEvent ): void {
 				event.preventDefault();
 
 				// The `dragenter` event will also fire when entering child
 				// elements, but we only want to call `onDragEnter` when
 				// entering the drop zone, which means the `relatedTarget`
 				// (element that has been left) should be outside the drop zone.
-				if (
-					element.contains(
-						/** @type {Node} */ ( event.relatedTarget )
-					)
-				) {
+				if ( element.contains( event.relatedTarget as Node ) ) {
 					return;
 				}
 
@@ -121,18 +110,15 @@ export default function useDropZone( {
 				}
 			}
 
-			function onDragOver( /** @type {DragEvent} */ event ) {
-				// Only call onDragOver for the innermost hovered drop zones.
+			function onDragOver( event: DragEvent ): void {
 				if ( ! event.defaultPrevented && _onDragOver ) {
 					onDragOverEvent( event );
 				}
 
-				// Prevent the browser default while also signalling to parent
-				// drop zones that `onDragOver` is already handled.
 				event.preventDefault();
 			}
 
-			function onDragLeave( /** @type {DragEvent} */ event ) {
+			function onDragLeave( event: DragEvent ): void {
 				// The `dragleave` event will also fire when leaving child
 				// elements, but we only want to call `onDragLeave` when
 				// leaving the drop zone, which means the `relatedTarget`
@@ -150,7 +136,7 @@ export default function useDropZone( {
 				}
 			}
 
-			function onDrop( /** @type {DragEvent} */ event ) {
+			function onDrop( event: DragEvent ): void {
 				// Don't handle drop if an inner drop zone already handled it.
 				if ( event.defaultPrevented ) {
 					return;
@@ -173,7 +159,7 @@ export default function useDropZone( {
 				maybeDragEnd( event );
 			}
 
-			function maybeDragEnd( /** @type {MouseEvent} */ event ) {
+			function maybeDragEnd( event: Event ): void {
 				if ( ! isDragging ) {
 					return;
 				}
@@ -184,7 +170,7 @@ export default function useDropZone( {
 				ownerDocument.removeEventListener( 'mousemove', maybeDragEnd );
 
 				if ( _onDragEnd ) {
-					onDragEndEvent( event );
+					onDragEndEvent( event as MouseEvent );
 				}
 			}
 

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

@@ -0,0 +1,34 @@
+export interface UseDropZoneProps {
+	/**
+	 * Optional element to be used as the drop zone.
+	 */
+	dropZoneElement?: HTMLElement | null;
+	/**
+	 * Whether or not to disable the drop zone.
+	 */
+	isDisabled?: boolean;
+	/**
+	 * Called when dragging has started.
+	 */
+	onDragStart?: ( e: DragEvent ) => void;
+	/**
+	 *  Called when the zone is entered.
+	 */
+	onDragEnter?: ( e: DragEvent ) => void;
+	/**
+	 * Called when the zone is moved within.
+	 */
+	onDragOver?: ( e: DragEvent ) => void;
+	/**
+	 * Called when the zone is left.
+	 */
+	onDragLeave?: ( e: DragEvent ) => void;
+	/**
+	 * Called when dragging has ended.
+	 */
+	onDragEnd?: ( e: MouseEvent ) => void;
+	/**
+	 * Called when dropping in the zone.
+	 */
+	onDrop?: ( e: DragEvent ) => void;
+}

package/src/hooks/use-fixed-window-list/{index.js → index.ts}

@@ -12,49 +12,58 @@ import { debounce } from '../../utils/debounce';
 
 const DEFAULT_INIT_WINDOW_SIZE = 30;
 
-/**
- * @typedef {Object} WPFixedWindowList
- *
- * @property {number}                  visibleItems Items visible in the current viewport
- * @property {number}                  start        Start index of the window
- * @property {number}                  end          End index of the window
- * @property {(index:number)=>boolean} itemInView   Returns true if item is in the window
- */
+interface FixedWindowList {
+	/** Items visible in the current viewport */
+	visibleItems: number;
+	/** Start index of the window */
+	start: number;
+	/** End index of the window */
+	end: number;
+	/** Returns true if item is in the window */
+	itemInView: ( index: number ) => boolean;
+}
 
-/**
- * @typedef {Object} WPFixedWindowListOptions
- *
- * @property {number}  [windowOverscan] Renders windowOverscan number of items before and after the calculated visible window.
- * @property {boolean} [useWindowing]   When false avoids calculating the window size
- * @property {number}  [initWindowSize] Initial window size to use on first render before we can calculate the window size.
- * @property {any}     [expandedState]  Used to recalculate the window size when the expanded state of a list changes.
- */
+interface FixedWindowListOptions {
+	/** Renders windowOverscan number of items before and after the calculated visible window. */
+	windowOverscan?: number;
+	/** When false avoids calculating the window size */
+	useWindowing?: boolean;
+	/** Initial window size to use on first render before we can calculate the window size. */
+	initWindowSize?: number;
+	/** Used to recalculate the window size when the expanded state of a list changes. */
+	expandedState?: any;
+}
 
 /**
  *
- * @param {React.RefObject<HTMLElement>} elementRef Used to find the closest scroll container that contains element.
- * @param { number }                     itemHeight Fixed item height in pixels
- * @param { number }                     totalItems Total items in list
- * @param { WPFixedWindowListOptions }   [options]  Options object
- * @return {[ WPFixedWindowList, setFixedListWindow:(nextWindow:WPFixedWindowList)=>void]} Array with the fixed window list and setter
+ * @param elementRef Used to find the closest scroll container that contains element.
+ * @param itemHeight Fixed item height in pixels
+ * @param totalItems Total items in list
+ * @param [options]  Options object
+ * @return Array with the fixed window list and setter
  */
 export default function useFixedWindowList(
-	elementRef,
-	itemHeight,
-	totalItems,
-	options
-) {
+	elementRef: React.RefObject< HTMLElement >,
+	itemHeight: number,
+	totalItems: number,
+	options?: FixedWindowListOptions
+): [
+	FixedWindowList,
+	React.Dispatch< React.SetStateAction< FixedWindowList > >,
+] {
 	const initWindowSize = options?.initWindowSize ?? DEFAULT_INIT_WINDOW_SIZE;
 	const useWindowing = options?.useWindowing ?? true;
 
-	const [ fixedListWindow, setFixedListWindow ] = useState( {
-		visibleItems: initWindowSize,
-		start: 0,
-		end: initWindowSize,
-		itemInView: ( /** @type {number} */ index ) => {
-			return index >= 0 && index <= initWindowSize;
-		},
-	} );
+	const [ fixedListWindow, setFixedListWindow ] = useState< FixedWindowList >(
+		{
+			visibleItems: initWindowSize,
+			start: 0,
+			end: initWindowSize,
+			itemInView: ( index: number ) => {
+				return index >= 0 && index <= initWindowSize;
+			},
+		}
+	);
 
 	useLayoutEffect( () => {
 		if ( ! useWindowing ) {
@@ -67,7 +76,7 @@ export default function useFixedWindowList(
 		 * @param {boolean} [initRender] Indicates if this is the initial render
 		 * @return {void}
 		 */
-		const measureWindow = ( initRender ) => {
+		const measureWindow = ( initRender?: boolean ) => {
 			if ( ! scrollContainer ) {
 				return;
 			}
@@ -91,7 +100,7 @@ export default function useFixedWindowList(
 					visibleItems,
 					start,
 					end,
-					itemInView: ( /** @type {number} */ index ) => {
+					itemInView: ( index: number ) => {
 						return start <= index && index <= end;
 					},
 				};
@@ -144,7 +153,7 @@ export default function useFixedWindowList(
 			return;
 		}
 		const scrollContainer = getScrollContainer( elementRef.current );
-		const handleKeyDown = ( /** @type {KeyboardEvent} */ event ) => {
+		const handleKeyDown = ( event: KeyboardEvent ) => {
 			switch ( event.keyCode ) {
 				case HOME: {
 					return scrollContainer?.scrollTo( { top: 0 } );

package/src/hooks/use-focus-return/{index.js → index.ts}

@@ -3,18 +3,17 @@
  */
 import { useRef, useEffect, useCallback } from '@wordpress/element';
 
-/** @type {Element|null} */
-let origin = null;
+let origin: Element | null = null;
 
 /**
  * Adds the unmount behavior of returning focus to the element which had it
  * previously as is expected for roles like menus or dialogs.
  *
- * @param {() => void} [onFocusReturn] Overrides the default return behavior.
- * @return {React.RefCallback<HTMLElement>} Element Ref.
+ * @param onFocusReturn Overrides the default return behavior.
+ * @return Element Ref.
  *
  * @example
- * ```js
+ * ```ts
  * import { useFocusReturn } from '@wordpress/compose';
  *
  * const WithFocusReturn = () => {
@@ -28,23 +27,26 @@ let origin = null;
  * }
  * ```
  */
-function useFocusReturn( onFocusReturn ) {
-	/** @type {React.MutableRefObject<null | HTMLElement>} */
-	const ref = useRef( null );
-	/** @type {React.MutableRefObject<null | Element>} */
-	const focusedBeforeMount = useRef( null );
-	const onFocusReturnRef = useRef( onFocusReturn );
+function useFocusReturn(
+	onFocusReturn?: () => void
+): React.RefCallback< HTMLElement > {
+	const ref = useRef< HTMLElement | null >( null );
+	const focusedBeforeMountRef = useRef< Element | null >( null );
+	const onFocusReturnRef = useRef< ( () => void ) | undefined >(
+		onFocusReturn
+	);
+
 	useEffect( () => {
 		onFocusReturnRef.current = onFocusReturn;
 	}, [ onFocusReturn ] );
 
-	return useCallback( ( node ) => {
+	return useCallback( ( node: HTMLElement | null ) => {
 		if ( node ) {
 			// Set ref to be used when unmounting.
 			ref.current = node;
 
 			// Only set when the node mounts.
-			if ( focusedBeforeMount.current ) {
+			if ( focusedBeforeMountRef.current ) {
 				return;
 			}
 
@@ -54,14 +56,15 @@ function useFocusReturn( onFocusReturn ) {
 					? node.ownerDocument.activeElement.contentDocument
 					: node.ownerDocument;
 
-			focusedBeforeMount.current = activeDocument?.activeElement ?? null;
-		} else if ( focusedBeforeMount.current ) {
+			focusedBeforeMountRef.current =
+				activeDocument?.activeElement ?? null;
+		} else if ( focusedBeforeMountRef.current ) {
 			const isFocused = ref.current?.contains(
-				ref.current?.ownerDocument.activeElement
+				ref.current?.ownerDocument.activeElement ?? null
 			);
 
 			if ( ref.current?.isConnected && ! isFocused ) {
-				origin ??= focusedBeforeMount.current;
+				origin ??= focusedBeforeMountRef.current;
 				return;
 			}
 
@@ -72,11 +75,13 @@ function useFocusReturn( onFocusReturn ) {
 			if ( onFocusReturnRef.current ) {
 				onFocusReturnRef.current();
 			} else {
-				/** @type {null|HTMLElement} */ (
-					! focusedBeforeMount.current.isConnected
+				const elementToFocus = (
+					! focusedBeforeMountRef.current.isConnected
 						? origin
-						: focusedBeforeMount.current
-				)?.focus();
+						: focusedBeforeMountRef.current
+				) as HTMLElement | SVGElement | null;
+
+				elementToFocus?.focus();
 			}
 			origin = null;
 		}

package/src/hooks/use-keyboard-shortcut/{index.js → index.ts}

@@ -3,44 +3,59 @@
  */
 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';
 
-/**
- * A block selection object.
- *
- * @typedef {Object} WPKeyboardShortcutConfig
- *
- * @property {boolean}                             [bindGlobal] Handle keyboard events anywhere including inside textarea/input fields.
- * @property {string}                              [eventName]  Event name used to trigger the handler, defaults to keydown.
- * @property {boolean}                             [isDisabled] Disables the keyboard handler if the value is true.
- * @property {React.RefObject<HTMLElement | null>} [target]     React reference to the DOM element used to catch the keyboard event.
- */
+type KeyboardShortcutConfig = {
+	/**
+	 * Handle keyboard events anywhere including inside textarea/input fields.
+	 */
+	bindGlobal: boolean;
+	/**
+	 * Event name used to trigger the handler, defaults to keydown.
+	 */
+	eventName: string;
+	/**
+	 * Disables the keyboard handler if the value is true.
+	 */
+	isDisabled: boolean;
+	/**
+	 * React reference to the DOM element used to catch the keyboard event.
+	 */
+	target: RefObject< HTMLElement >;
+};
 
 /**
  * Attach a keyboard shortcut handler.
  *
  * @see https://craig.is/killing/mice#api.bind for information about the `callback` parameter.
  *
- * @param {string[]|string}                                             shortcuts Keyboard Shortcuts.
- * @param {(e: Mousetrap.ExtendedKeyboardEvent, combo: string) => void} callback  Shortcut callback.
- * @param {WPKeyboardShortcutConfig}                                    options   Shortcut options.
+ * @param shortcuts          Keyboard Shortcuts.
+ * @param callback           Shortcut callback.
+ * @param options            Shortcut options.
+ * @param options.bindGlobal
+ * @param options.eventName
+ * @param options.isDisabled
+ * @param options.target
  */
 function useKeyboardShortcut(
-	shortcuts,
-	callback,
+	shortcuts: string[] | string,
+	callback: ( e: ExtendedKeyboardEvent, combo: string ) => void,
 	{
 		bindGlobal = false,
 		eventName = 'keydown',
-		isDisabled = false, // This is important for performance considerations.
+		isDisabled = false,
 		target,
-	} = {}
+	}: Partial< KeyboardShortcutConfig > = {}
 ) {
 	const currentCallbackRef = useRef( callback );
+
 	useEffect( () => {
 		currentCallbackRef.current = callback;
 	}, [ callback ] );
@@ -49,29 +64,28 @@ function useKeyboardShortcut(
 		if ( isDisabled ) {
 			return;
 		}
+
 		const mousetrap = new Mousetrap(
 			target && target.current
 				? target.current
 				: // We were passing `document` here previously, so to successfully cast it to Element we must cast it first to `unknown`.
 				  // Not sure if this is a mistake but it was the behavior previous to the addition of types so we're just doing what's
 				  // necessary to maintain the existing behavior.
-				  /** @type {Element} */ ( /** @type {unknown} */ ( document ) )
+				  ( document as unknown as Element )
 		);
+
 		const shortcutsArray = Array.isArray( shortcuts )
 			? shortcuts
 			: [ shortcuts ];
-		shortcutsArray.forEach( ( shortcut ) => {
+
+		shortcutsArray.forEach( ( shortcut: string ) => {
 			const keys = shortcut.split( '+' );
-			// Determines whether a key is a modifier by the length of the string.
-			// E.g. if I add a pass a shortcut Shift+Cmd+M, it'll determine that
-			// the modifiers are Shift and Cmd because they're not a single character.
 			const modifiers = new Set(
 				keys.filter( ( value ) => value.length > 1 )
 			);
 			const hasAlt = modifiers.has( 'alt' );
 			const hasShift = modifiers.has( 'shift' );
 
-			// This should be better moved to the shortcut registration instead.
 			if (
 				isAppleOS() &&
 				( ( modifiers.size === 1 && hasAlt ) ||
@@ -83,12 +97,13 @@ function useKeyboardShortcut(
 			}
 
 			const bindFn = bindGlobal ? 'bindGlobal' : 'bind';
-			// @ts-ignore `bindGlobal` is an undocumented property
-			mousetrap[ bindFn ](
+			// `@ts-expect-error` Mousetrap typings don’t include `bindGlobal`
+			// It exists at runtime via the plugin
+			// `any` is used here to allow dynamic access via `bindFn`
+			( mousetrap as any )[ bindFn ](
 				shortcut,
-				(
-					/** @type {[e: import('mousetrap').ExtendedKeyboardEvent, combo: string]} */ ...args
-				) => currentCallbackRef.current( ...args ),
+				( ...args: [ Mousetrap.ExtendedKeyboardEvent, string ] ) =>
+					currentCallbackRef.current( ...args ),
 				eventName
 			);
 		} );

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

@@ -19,8 +19,11 @@ const EMPTY_SUBSCRIBER: MQLSubscriber = {
 	getValue: () => false,
 };
 
-function getMQLSubscriber( view: Window, query?: string ): MQLSubscriber {
-	if ( ! query || typeof view?.matchMedia !== 'function' ) {
+function getMQLSubscriber(
+	view: Window | undefined,
+	query?: string
+): MQLSubscriber {
+	if ( ! view || ! query || typeof view.matchMedia !== 'function' ) {
 		return EMPTY_SUBSCRIBER;
 	}
 
@@ -75,7 +78,11 @@ function getMQLSubscriber( view: Window, query?: string ): MQLSubscriber {
  */
 export default function useMediaQuery(
 	query?: string,
-	view: Window = window
+	// Resolve the default lazily so SSR (where `window` is undeclared) does not
+	// throw a ReferenceError when this default expression is evaluated.
+	view: Window | undefined = typeof window !== 'undefined'
+		? window
+		: undefined
 ): boolean {
 	const source = getMQLSubscriber( view, query );