@wordpress/compose 7.40.1-next.v.202602271551.0 → 7.40.1

package/src/hooks/use-copy-on-click/test/index.tsx

@@ -0,0 +1,162 @@
+/**
+ * External dependencies
+ */
+import { render, screen, act } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * WordPress dependencies
+ */
+import deprecated from '@wordpress/deprecated';
+import { useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import useCopyOnClick from '../';
+
+jest.mock( '@wordpress/deprecated' );
+
+interface TestComponentProps {
+	text: string | ( () => string );
+	timeout?: number;
+}
+
+describe( 'useCopyOnClick', () => {
+	const TestComponent = ( { text, timeout = 4000 }: TestComponentProps ) => {
+		const ref = useRef< HTMLButtonElement >( null );
+		const hasCopied = useCopyOnClick( ref, text, timeout );
+		return (
+			<button ref={ ref } type="button">
+				{ hasCopied ? 'Copied!' : 'Copy' }
+			</button>
+		);
+	};
+
+	it( 'should call deprecated when the hook is used', () => {
+		jest.mocked( deprecated ).mockClear();
+		render( <TestComponent text="test text" /> );
+
+		expect( deprecated ).toHaveBeenCalledWith(
+			'wp.compose.useCopyOnClick',
+			{
+				since: '5.8',
+				alternative: 'wp.compose.useCopyToClipboard',
+			}
+		);
+	} );
+
+	it( 'should copy text on click', async () => {
+		const user = userEvent.setup();
+		render( <TestComponent text="test text" /> );
+
+		const writeTextMock = jest
+			.spyOn( navigator.clipboard, 'writeText' )
+			.mockResolvedValue();
+
+		await user.click( screen.getByRole( 'button' ) );
+
+		expect( writeTextMock ).toHaveBeenCalledTimes( 1 );
+		expect( writeTextMock ).toHaveBeenCalledWith( 'test text' );
+	} );
+
+	it( 'should set hasCopied to true when copy succeeds', async () => {
+		const user = userEvent.setup();
+		render( <TestComponent text="test text" /> );
+
+		jest.spyOn( navigator.clipboard, 'writeText' ).mockResolvedValue();
+
+		expect( screen.getByRole( 'button' ) ).toHaveTextContent( 'Copy' );
+
+		await user.click( screen.getByRole( 'button' ) );
+
+		await act( async () => {
+			await new Promise( ( resolve ) => setTimeout( resolve, 0 ) );
+		} );
+
+		expect( screen.getByRole( 'button' ) ).toHaveTextContent( 'Copied!' );
+	} );
+
+	it( 'should reset hasCopied after timeout', async () => {
+		jest.useFakeTimers();
+		const user = userEvent.setup( {
+			advanceTimers: jest.advanceTimersByTime,
+		} );
+		render( <TestComponent text="test text" timeout={ 1000 } /> );
+
+		jest.spyOn( navigator.clipboard, 'writeText' ).mockResolvedValue();
+
+		await user.click( screen.getByRole( 'button' ) );
+
+		await act( async () => {
+			const p = new Promise( ( resolve ) => setTimeout( resolve, 0 ) );
+			jest.advanceTimersByTime( 0 );
+			await p;
+		} );
+		expect( screen.getByRole( 'button' ) ).toHaveTextContent( 'Copied!' );
+
+		act( () => {
+			jest.advanceTimersByTime( 1000 );
+		} );
+		expect( screen.getByRole( 'button' ) ).toHaveTextContent( 'Copy' );
+
+		jest.useRealTimers();
+	} );
+
+	it( 'should not set hasCopied when copy fails', async () => {
+		const user = userEvent.setup();
+		render( <TestComponent text="test text" /> );
+
+		jest.spyOn( navigator.clipboard, 'writeText' ).mockRejectedValue(
+			new Error()
+		);
+
+		await user.click( screen.getByRole( 'button' ) );
+
+		await act( async () => {
+			await new Promise( ( resolve ) => setTimeout( resolve, 0 ) );
+		} );
+
+		expect( screen.getByRole( 'button' ) ).toHaveTextContent( 'Copy' );
+	} );
+
+	it( 'should not update hasCopied after unmount', async () => {
+		const renderSpy = jest.fn();
+
+		const SpyComponent = ( { text }: { text: string } ) => {
+			const ref = useRef< HTMLButtonElement >( null );
+			const hasCopied = useCopyOnClick( ref, text );
+			renderSpy( hasCopied );
+			return (
+				<button ref={ ref } type="button">
+					{ hasCopied ? 'Copied!' : 'Copy' }
+				</button>
+			);
+		};
+
+		let resolvePromise: () => void;
+		const delayedPromise = new Promise< void >( ( resolve ) => {
+			resolvePromise = resolve;
+		} );
+		jest.spyOn( navigator.clipboard, 'writeText' ).mockReturnValue(
+			delayedPromise as Promise< void >
+		);
+
+		const user = userEvent.setup();
+		const { unmount } = render( <SpyComponent text="test" /> );
+
+		expect( renderSpy ).toHaveBeenLastCalledWith( false );
+		const renderCountBeforeUnmount = renderSpy.mock.calls.length;
+
+		await user.click( screen.getByRole( 'button' ) );
+		unmount();
+
+		await act( async () => {
+			resolvePromise();
+			await new Promise( ( resolve ) => setTimeout( resolve, 0 ) );
+		} );
+
+		// No additional renders after unmount — setHasCopied(true) was not called.
+		expect( renderSpy ).toHaveBeenCalledTimes( renderCountBeforeUnmount );
+	} );
+} );

package/src/hooks/use-copy-to-clipboard/index.ts

@@ -0,0 +1,120 @@
+/**
+ * WordPress dependencies
+ */
+import { useRef, useLayoutEffect } from '@wordpress/element';
+import type { MutableRefObject, RefCallback } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import useRefEffect from '../use-ref-effect';
+
+/**
+ * Copies text to the clipboard using the Clipboard API when available,
+ * with a fallback for non-secure contexts (e.g. HTTP) and older browsers.
+ *
+ * @param text    The text to copy.
+ * @param trigger The element that triggered the copy.
+ * @return Resolves to true if successful, false otherwise.
+ */
+export async function copyToClipboard(
+	text: string,
+	trigger: Element | null
+): Promise< boolean > {
+	if ( ! trigger ) {
+		return false;
+	}
+	const { ownerDocument } = trigger;
+	if ( ! ownerDocument ) {
+		return false;
+	}
+	const { defaultView } = ownerDocument;
+	try {
+		if ( defaultView?.navigator?.clipboard?.writeText ) {
+			await defaultView.navigator.clipboard.writeText( text );
+			return true;
+		}
+		// Fallback for non-secure contexts (HTTP) and older browsers.
+		const textarea = ownerDocument.createElement( 'textarea' );
+		textarea.value = text;
+		textarea.setAttribute( 'readonly', '' );
+		textarea.style.position = 'fixed';
+		textarea.style.left = '-9999px';
+		textarea.style.top = '-9999px';
+		ownerDocument.body.appendChild( textarea );
+		textarea.select();
+		const success = ownerDocument.execCommand( 'copy' );
+		textarea.remove();
+		return success;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Clears the current selection and restores focus to the trigger element.
+ *
+ * @param trigger The element that triggered the copy.
+ */
+export function clearSelection( trigger: Element ): void {
+	if ( 'focus' in trigger && typeof trigger.focus === 'function' ) {
+		trigger.focus();
+	}
+	trigger.ownerDocument?.defaultView?.getSelection()?.removeAllRanges();
+}
+
+/**
+ * @template T
+ * @param    value
+ * @return   A ref to assign to the target element.
+ */
+function useUpdatedRef< T >( value: T ): MutableRefObject< T > {
+	const ref = useRef< T >( value );
+	useLayoutEffect( () => {
+		ref.current = value;
+	}, [ value ] );
+	return ref;
+}
+
+/**
+ * Copies the given text to the clipboard when the element is clicked.
+ *
+ * @template T
+ * @param    text      The text to copy. Use a function if not
+ *                     already available and expensive to compute.
+ * @param    onSuccess Called when to text is copied.
+ *
+ * @return   A ref to assign to the target element.
+ */
+export default function useCopyToClipboard< T extends HTMLElement >(
+	text: string | ( () => string ),
+	onSuccess?: () => void
+): RefCallback< T > {
+	const textRef = useUpdatedRef( text );
+	const onSuccessRef = useUpdatedRef( onSuccess );
+	return useRefEffect( ( node ) => {
+		// Flag to prevent callbacks after unmount when the Promise resolves.
+		let isActive = true;
+		const handleClick = async () => {
+			const textToCopy =
+				typeof textRef.current === 'function'
+					? textRef.current()
+					: textRef.current || '';
+			const success = await copyToClipboard( textToCopy, node );
+			if ( ! isActive ) {
+				return;
+			}
+			if ( success ) {
+				clearSelection( node );
+				if ( onSuccessRef.current ) {
+					onSuccessRef.current();
+				}
+			}
+		};
+		node.addEventListener( 'click', handleClick );
+		return () => {
+			isActive = false;
+			node.removeEventListener( 'click', handleClick );
+		};
+	}, [] );
+}

package/src/hooks/use-copy-to-clipboard/test/index.tsx

@@ -0,0 +1,144 @@
+/**
+ * External dependencies
+ */
+import { render, screen, act } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * Internal dependencies
+ */
+import useCopyToClipboard, { copyToClipboard, clearSelection } from '../';
+
+interface TestComponentProps {
+	text: string | ( () => string );
+	onSuccess?: () => void;
+}
+
+describe( 'useCopyToClipboard', () => {
+	const TestComponent = ( { text, onSuccess }: TestComponentProps ) => {
+		const ref = useCopyToClipboard( text, onSuccess );
+		return <button ref={ ref }>Copy</button>;
+	};
+
+	it( 'should copy text on click', async () => {
+		const user = userEvent.setup();
+		render( <TestComponent text="test text" /> );
+
+		const writeTextMock = jest
+			.spyOn( navigator.clipboard, 'writeText' )
+			.mockResolvedValue();
+
+		await user.click( screen.getByRole( 'button' ) );
+
+		expect( writeTextMock ).toHaveBeenCalledTimes( 1 );
+		expect( writeTextMock ).toHaveBeenCalledWith( 'test text' );
+	} );
+
+	it( 'should call onSuccess when copy succeeds', async () => {
+		const user = userEvent.setup();
+		const onSuccess = jest.fn();
+		render( <TestComponent text="test text" onSuccess={ onSuccess } /> );
+
+		await user.click( screen.getByRole( 'button' ) );
+
+		expect( onSuccess ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	it( 'should call onSuccess when copy empty text', async () => {
+		const user = userEvent.setup();
+		const onSuccess = jest.fn();
+		render( <TestComponent text="" onSuccess={ onSuccess } /> );
+
+		await user.click( screen.getByRole( 'button' ) );
+
+		expect( onSuccess ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	it( 'should not call onSuccess when copy fails', async () => {
+		const user = userEvent.setup();
+		const onSuccess = jest.fn();
+		render( <TestComponent text="test text" onSuccess={ onSuccess } /> );
+
+		jest.spyOn( navigator.clipboard, 'writeText' ).mockRejectedValue(
+			new Error()
+		);
+
+		await user.click( screen.getByRole( 'button' ) );
+
+		expect( onSuccess ).not.toHaveBeenCalled();
+	} );
+
+	it( 'should not call onSuccess after unmount', async () => {
+		let resolvePromise: () => void;
+		const delayedPromise = new Promise< void >( ( resolve ) => {
+			resolvePromise = resolve;
+		} );
+		jest.spyOn( navigator.clipboard, 'writeText' ).mockReturnValue(
+			delayedPromise
+		);
+
+		const user = userEvent.setup();
+		const onSuccess = jest.fn();
+		const { unmount } = render(
+			<TestComponent text="test" onSuccess={ onSuccess } />
+		);
+
+		await user.click( screen.getByRole( 'button' ) );
+		unmount();
+
+		await act( async () => {
+			resolvePromise();
+			await new Promise( ( resolve ) => setTimeout( resolve, 0 ) );
+		} );
+
+		expect( onSuccess ).not.toHaveBeenCalled();
+	} );
+} );
+
+describe( 'copyToClipboard', () => {
+	it( 'should use execCommand fallback when clipboard API is not available', async () => {
+		const trigger = document.createElement( 'button' );
+		document.body.appendChild( trigger );
+
+		const originalClipboard = navigator.clipboard;
+		Object.defineProperty( navigator, 'clipboard', {
+			value: undefined,
+			configurable: true,
+		} );
+
+		// JSDOM does not implement execCommand; add a mock for the fallback path.
+		// See: https://github.com/jsdom/jsdom/issues/1742
+		const execCommandMock = jest.fn().mockReturnValue( true );
+		Object.defineProperty( document, 'execCommand', {
+			value: execCommandMock,
+			configurable: true,
+			writable: true,
+		} );
+
+		const result = await copyToClipboard( 'fallback text', trigger );
+
+		expect( result ).toBe( true );
+		expect( execCommandMock ).toHaveBeenCalledWith( 'copy' );
+
+		delete ( document as { execCommand?: unknown } ).execCommand;
+		Object.defineProperty( navigator, 'clipboard', {
+			value: originalClipboard,
+			configurable: true,
+		} );
+		document.body.removeChild( trigger );
+	} );
+} );
+
+describe( 'clearSelection', () => {
+	it( 'should focus the trigger element', () => {
+		const trigger = document.createElement( 'button' );
+		document.body.appendChild( trigger );
+		const focusMock = jest.spyOn( trigger, 'focus' );
+
+		clearSelection( trigger );
+
+		expect( focusMock ).toHaveBeenCalledTimes( 1 );
+
+		document.body.removeChild( trigger );
+	} );
+} );

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

@@ -13,24 +13,21 @@ import { ESCAPE } from '@wordpress/keycodes';
  * Internal dependencies
  */
 import useConstrainedTabbing from '../use-constrained-tabbing';
-import { useFocusOnMount } from '../use-focus-on-mount';
+import useFocusOnMount from '../use-focus-on-mount';
 import useFocusReturn from '../use-focus-return';
 import useFocusOutside from '../use-focus-outside';
 import useMergeRefs from '../use-merge-refs';
 
 type DialogOptions = {
 	/**
-	 * Determines focus behavior when the dialog mounts.
-	 *
-	 * - `"firstElement"` focuses the first tabbable element within.
-	 * - `"firstInputElement"` focuses the first value control within.
-	 * - `true` focuses the element itself.
-	 * - `false` does nothing and _should not be used unless an accessible
-	 *    substitute behavior is implemented_.
+	 * Determines whether focus should be automatically moved to the popover
+	 * when it mounts. `false` causes no focus shift, `true` causes the popover
+	 * itself to gain focus, and `firstElement` focuses the first focusable
+	 * element within the popover.
 	 *
 	 * @default 'firstElement'
 	 */
-	focusOnMount?: useFocusOnMount.Mode;
+	focusOnMount?: Parameters< typeof useFocusOnMount >[ 0 ];
 	/**
 	 * Determines whether tabbing is constrained to within the popover,
 	 * preventing keyboard focus from leaving the popover content without

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

@@ -1,15 +1,19 @@
+/**
+ * WordPress dependencies
+ */
+import { useRef, useEffect } from '@wordpress/element';
 import { focus } from '@wordpress/dom';
-import { useEffect, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
 import useRefEffect from '../use-ref-effect';
 
 /**
- * Determines focus behavior when the element mounts.
+ * Hook used to focus the first tabbable element on mount.
  *
- * @param focusOnMount Behavioral mode. Defaults to `"firstElement"` which focuses the
- *                     first tabbable element within; `"firstInputElement"` focuses the
- *                     first value control within; `true` focuses the element itself;
- *                     `false` does nothing.
- * @return Ref callback.
+ * @param {boolean | 'firstElement' | 'firstInputElement'} focusOnMount Focus on mount mode.
+ * @return {React.RefCallback<HTMLElement>} Ref callback.
  *
  * @example
  * ```js
@@ -26,17 +30,16 @@ import useRefEffect from '../use-ref-effect';
  * }
  * ```
  */
-export function useFocusOnMount(
-	focusOnMount: useFocusOnMount.Mode = 'firstElement'
-) {
+export default function useFocusOnMount( focusOnMount = 'firstElement' ) {
 	const focusOnMountRef = useRef( focusOnMount );
 
 	/**
 	 * Sets focus on a DOM element.
 	 *
-	 * @param target The DOM element to set focus to.
+	 * @param {HTMLElement} target The DOM element to set focus to.
+	 * @return {void}
 	 */
-	const setFocus = ( target: HTMLElement ): void => {
+	const setFocus = ( target ) => {
 		target.focus( {
 			// When focusing newly mounted dialogs,
 			// the position of the popover is often not right on the first render
@@ -45,12 +48,15 @@ export function useFocusOnMount(
 		} );
 	};
 
+	/** @type {React.MutableRefObject<ReturnType<setTimeout> | undefined>} */
+	const timerIdRef = useRef( undefined );
+
 	useEffect( () => {
 		focusOnMountRef.current = focusOnMount;
 	}, [ focusOnMount ] );
 
-	return useRefEffect< HTMLElement >( ( node ) => {
-		if ( focusOnMountRef.current === false ) {
+	return useRefEffect( ( node ) => {
+		if ( ! node || focusOnMountRef.current === false ) {
 			return;
 		}
 
@@ -66,12 +72,19 @@ export function useFocusOnMount(
 			return;
 		}
 
-		const timerId = setTimeout( () => {
+		timerIdRef.current = setTimeout( () => {
 			// For 'firstInputElement' mode, try to find a form input element first
 			if ( focusOnMountRef.current === 'firstInputElement' ) {
-				const formInput = node.querySelector< HTMLElement >(
-					'input:not([type="hidden"]):not([disabled]), select:not([disabled]), textarea:not([disabled])'
-				);
+				/** @type {HTMLElement | null} */
+				let formInput = null;
+				if (
+					typeof window !== 'undefined' &&
+					node instanceof window.Element
+				) {
+					formInput = node.querySelector(
+						'input:not([type="hidden"]):not([disabled]), select:not([disabled]), textarea:not([disabled])'
+					);
+				}
 
 				if ( formInput ) {
 					setFocus( formInput );
@@ -87,11 +100,9 @@ export function useFocusOnMount(
 		}, 0 );
 
 		return () => {
-			clearTimeout( timerId );
+			if ( timerIdRef.current ) {
+				clearTimeout( timerIdRef.current );
+			}
 		};
 	}, [] );
 }
-
-export namespace useFocusOnMount {
-	export type Mode = boolean | 'firstElement' | 'firstInputElement';
-}

package/src/hooks/use-media-query/{index.js → index.ts}

@@ -3,30 +3,38 @@
  */
 import { useMemo, useSyncExternalStore } from '@wordpress/element';
 
-const matchMediaCache = new Map();
+type MQLCache = Map< string, MediaQueryList >;
+
+const perWindowCache = new WeakMap< Window, MQLCache >();
 
 /**
  * A new MediaQueryList object for the media query
  *
- * @param {string} [query] Media Query.
- * @return {MediaQueryList|null} A new object for the media query
+ * @param view    Window.
+ * @param [query] Media Query.
  */
-function getMediaQueryList( query ) {
+function getMediaQueryList(
+	view: Window,
+	query?: string
+): MediaQueryList | null {
 	if ( ! query ) {
 		return null;
 	}
 
+	const matchMediaCache: MQLCache = perWindowCache.get( view ) ?? new Map();
+
+	if ( ! perWindowCache.has( view ) ) {
+		perWindowCache.set( view, matchMediaCache );
+	}
+
 	let match = matchMediaCache.get( query );
 
 	if ( match ) {
 		return match;
 	}
 
-	if (
-		typeof window !== 'undefined' &&
-		typeof window.matchMedia === 'function'
-	) {
-		match = window.matchMedia( query );
+	if ( typeof view?.matchMedia === 'function' ) {
+		match = view.matchMedia( query );
 		matchMediaCache.set( query, match );
 		return match;
 	}
@@ -37,16 +45,19 @@ function getMediaQueryList( query ) {
 /**
  * Runs a media query and returns its value when it changes.
  *
- * @param {string} [query] Media Query.
- * @return {boolean} return value of the media query.
+ * @param [query] Media Query.
+ * @param [view]  Window instance, else default to global window
+ * @return return value of the media query.
  */
-export default function useMediaQuery( query ) {
+export default function useMediaQuery(
+	query?: string,
+	view: Window = window
+): boolean {
 	const source = useMemo( () => {
-		const mediaQueryList = getMediaQueryList( query );
+		const mediaQueryList = getMediaQueryList( view, query );
 
 		return {
-			/** @type {(onStoreChange: () => void) => () => void} */
-			subscribe( onStoreChange ) {
+			subscribe( onStoreChange: any ) {
 				if ( ! mediaQueryList ) {
 					return () => {};
 				}
@@ -64,7 +75,7 @@ export default function useMediaQuery( query ) {
 				return mediaQueryList?.matches ?? false;
 			},
 		};
-	}, [ query ] );
+	}, [ view, query ] );
 
 	return useSyncExternalStore(
 		source.subscribe,

package/src/hooks/use-viewport-match/index.js

@@ -64,6 +64,7 @@ ViewportMatchWidthContext.displayName = 'ViewportMatchWidthContext';
  *
  * @param {WPBreakpoint}       breakpoint      Breakpoint size name.
  * @param {WPViewportOperator} [operator=">="] Viewport operator.
+ * @param {Window}             [view=window]   Window instance in which to perform viewport matching.
  *
  * @example
  *
@@ -74,12 +75,12 @@ ViewportMatchWidthContext.displayName = 'ViewportMatchWidthContext';
  *
  * @return {boolean} Whether viewport matches query.
  */
-const useViewportMatch = ( breakpoint, operator = '>=' ) => {
+const useViewportMatch = ( breakpoint, operator = '>=', view = window ) => {
 	const simulatedWidth = useContext( ViewportMatchWidthContext );
 	const mediaQuery =
 		! simulatedWidth &&
 		`(${ CONDITIONS[ operator ] }: ${ BREAKPOINTS[ breakpoint ] }px)`;
-	const mediaQueryResult = useMediaQuery( mediaQuery || undefined );
+	const mediaQueryResult = useMediaQuery( mediaQuery || undefined, view );
 	if ( simulatedWidth ) {
 		return OPERATOR_EVALUATORS[ operator ](
 			BREAKPOINTS[ breakpoint ],