@wordpress/compose 7.40.1-next.v.202602241322.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-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 ],

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

@@ -44,15 +44,18 @@ describe( 'useViewportMatch', () => {
 		expect( useMediaQueryMock ).toHaveBeenCalledTimes( 3 );
 		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
 			1,
-			'(max-width: 1280px)'
+			'(max-width: 1280px)',
+			window
 		);
 		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
 			2,
-			'(min-width: 782px)'
+			'(min-width: 782px)',
+			window
 		);
 		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
 			3,
-			'(min-width: 600px)'
+			'(min-width: 600px)',
+			window
 		);
 	} );
 
@@ -76,15 +79,18 @@ describe( 'useViewportMatch', () => {
 		expect( useMediaQueryMock ).toHaveBeenCalledTimes( 3 );
 		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
 			1,
-			'(min-width: 1440px)'
+			'(min-width: 1440px)',
+			window
 		);
 		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
 			2,
-			'(max-width: 960px)'
+			'(max-width: 960px)',
+			window
 		);
 		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
 			3,
-			'(max-width: 480px)'
+			'(max-width: 480px)',
+			window
 		);
 	} );
 
@@ -121,9 +127,25 @@ describe( 'useViewportMatch', () => {
 
 		expect( useMediaQueryMock ).toHaveBeenCalledTimes( 4 );
 		// `useMediaQuery` is expected to receive `undefined` when simulating width.
-		expect( useMediaQueryMock ).toHaveBeenNthCalledWith( 1, undefined );
-		expect( useMediaQueryMock ).toHaveBeenNthCalledWith( 2, undefined );
-		expect( useMediaQueryMock ).toHaveBeenNthCalledWith( 3, undefined );
-		expect( useMediaQueryMock ).toHaveBeenNthCalledWith( 4, undefined );
+		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
+			1,
+			undefined,
+			window
+		);
+		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
+			2,
+			undefined,
+			window
+		);
+		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
+			3,
+			undefined,
+			window
+		);
+		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
+			4,
+			undefined,
+			window
+		);
 	} );
 } );

package/src/hooks/use-copy-on-click/index.js

@@ -1,75 +0,0 @@
-/**
- * External dependencies
- */
-import Clipboard from 'clipboard';
-
-/**
- * WordPress dependencies
- */
-import { useRef, useEffect, useState } from '@wordpress/element';
-import deprecated from '@wordpress/deprecated';
-
-/**
- * Copies the text to the clipboard when the element is clicked.
- *
- * @deprecated
- *
- * @param {React.RefObject<string | Element | NodeListOf<Element>>} ref       Reference with the element.
- * @param {string|Function}                                         text      The text to copy.
- * @param {number}                                                  [timeout] Optional timeout to reset the returned
- *                                                                            state. 4 seconds by default.
- *
- * @return {boolean} Whether or not the text has been copied. Resets after the
- *                   timeout.
- */
-export default function useCopyOnClick( ref, text, timeout = 4000 ) {
-	deprecated( 'wp.compose.useCopyOnClick', {
-		since: '5.8',
-		alternative: 'wp.compose.useCopyToClipboard',
-	} );
-
-	/** @type {React.MutableRefObject<Clipboard | undefined>} */
-	const clipboardRef = useRef( undefined );
-	const [ hasCopied, setHasCopied ] = useState( false );
-
-	useEffect( () => {
-		/** @type {number | undefined} */
-		let timeoutId;
-
-		if ( ! ref.current ) {
-			return;
-		}
-
-		// Clipboard listens to click events.
-		clipboardRef.current = new Clipboard( ref.current, {
-			text: () => ( typeof text === 'function' ? text() : text ),
-		} );
-
-		clipboardRef.current.on( 'success', ( { clearSelection, trigger } ) => {
-			// Clearing selection will move focus back to the triggering button,
-			// ensuring that it is not reset to the body, and further that it is
-			// kept within the rendered node.
-			clearSelection();
-
-			// Handle ClipboardJS focus bug, see https://github.com/zenorocha/clipboard.js/issues/680
-			if ( trigger ) {
-				/** @type {HTMLElement} */ ( trigger ).focus();
-			}
-
-			if ( timeout ) {
-				setHasCopied( true );
-				clearTimeout( timeoutId );
-				timeoutId = setTimeout( () => setHasCopied( false ), timeout );
-			}
-		} );
-
-		return () => {
-			if ( clipboardRef.current ) {
-				clipboardRef.current.destroy();
-			}
-			clearTimeout( timeoutId );
-		};
-	}, [ text, timeout, setHasCopied ] );
-
-	return hasCopied;
-}