Hovercards: Add hideOnTargetClick option & Remove hovercards after calling the detach()

Author: Welly Shen

web/packages/hovercards/README.md

@@ -187,6 +187,10 @@ Determines whether the hovercard's placement should automatically flip when ther
 
 Determines whether the hovercard's placement should automatically shift when there is not enough display space.
 
+##### `hideOnTargetClick: boolean = false`
+
+Hides the hovercard when its trigger element is clicked.
+
 ##### `offset: number = 10`
 
 The offset of the hovercard relative to the target element, in pixels.

web/packages/hovercards/playground/core.ts

@@ -9,6 +9,7 @@ addEventListener( 'DOMContentLoaded', () => {
 		placement: 'top',
 		// To test the empty about me case
 		myHash: '99c3338797c95c418d9996bd39931506',
+		hideOnTargetClick: true,
 		onCanShowHovercard: ( hash ) => {
 			if ( hash === 'a2bb8d897bb538896708195dd9eb162f585654611c50a3a1c9a16a7b64f33270' ) {
 				return false;
@@ -179,6 +180,11 @@ addEventListener( 'DOMContentLoaded', () => {
 		)
 	);
 
+	// To test detach
+	document.getElementById( 'detach' )?.addEventListener( 'click', () => {
+		hovercards.detach();
+	} );
+
 	// To test hovercard skeleton
 	document.getElementById( 'hovercard-skeleton' )?.appendChild( Hovercards.createHovercardSkeleton() );
 

web/packages/hovercards/playground/index.html

@@ -76,6 +76,7 @@
 					height="60"
 				/>
 				<div id="attr" data-gravatar-hash="c3bb8d897bb538896708195dd9eb162f585654611c50a3a1c9a16a7b64f33270?s=60&d=retro&r=g">@WellyTest</div>
+				<button id="detach">Detach</button>
 			</div>
 			<div id="react-app"></div>
 			<div id="inline">

web/packages/hovercards/playground/react.tsx

@@ -1,7 +1,7 @@
 /* eslint-disable import/no-unresolved */
 
 import { createRoot } from 'react-dom/client';
-import React, { useRef, useEffect, useState } from 'react';
+import { useRef, useEffect, useState } from 'react';
 
 import type { HovercardsProps } from '../dist/index.react.d';
 import { useHovercards, Hovercards } from '../dist/index.react';
@@ -11,13 +11,15 @@ const props: HovercardsProps = {
 	// attach: document.body,
 	// placement: 'top',
 	// ignoreSelector: '#grav-img-1',
+	hideOnTargetClick: true,
 	i18n: {
 		'View profile →': 'Voir le profil →',
 	},
 };
 
 function App() {
 	const { attach } = useHovercards( {
+		hideOnTargetClick: true,
 		// eslint-disable-next-line no-console
 		onFetchProfileSuccess: ( hash ) => console.log( hash ),
 		onCanShowHovercard: ( hash ) => {

web/packages/hovercards/src/core.ts

@@ -112,6 +112,7 @@ export type Options = Partial< {
 	offset: number;
 	autoFlip: boolean;
 	autoShift: boolean;
+	hideOnTargetClick: boolean;
 	delayToShow: number;
 	delayToHide: number;
 	additionalClass: string;
@@ -133,6 +134,7 @@ interface HovercardRef {
 	ref: HTMLElement;
 	onEnter: ( e: MouseEvent ) => void;
 	onLeave: ( e: MouseEvent ) => void;
+	onClick: ( e: MouseEvent ) => void;
 }
 
 const BASE_API_URL = 'https://api.gravatar.com/v3/profiles';
@@ -145,6 +147,7 @@ export default class Hovercards {
 	_offset: number;
 	_autoFlip: boolean;
 	_autoShift: boolean;
+	_hideOnTargetClick: boolean;
 	_delayToShow: number;
 	_delayToHide: number;
 	_additionalClass: string;
@@ -166,9 +169,10 @@ export default class Hovercards {
 
 	constructor( {
 		placement = 'right-start',
+		offset = 10,
 		autoFlip = true,
 		autoShift = true,
-		offset = 10,
+		hideOnTargetClick = false,
 		delayToShow = 500,
 		delayToHide = 300,
 		additionalClass = '',
@@ -183,9 +187,10 @@ export default class Hovercards {
 		i18n = {},
 	}: Options = {} ) {
 		this._placement = placement;
+		this._offset = offset;
 		this._autoFlip = autoFlip;
 		this._autoShift = autoShift;
-		this._offset = offset;
+		this._hideOnTargetClick = hideOnTargetClick;
 		this._delayToShow = delayToShow;
 		this._delayToHide = delayToHide;
 		this._additionalClass = additionalClass;
@@ -291,6 +296,7 @@ export default class Hovercards {
 				...hovercardRef,
 				onEnter: ( e: MouseEvent ) => this._handleMouseEnter( e, hovercardRef ),
 				onLeave: ( e: MouseEvent ) => this._handleMouseLeave( e, hovercardRef ),
+				onClick: () => this._handleMouseClick( hovercardRef ),
 			} ) );
 
 		return this._hovercardRefs;
@@ -881,19 +887,20 @@ export default class Hovercards {
 	/**
 	 * Waits for a specified delay and hides the hovercard.
 	 *
-	 * @param {string} id - The ID associated with the hovercard.
+	 * @param {string} id      - The ID associated with the hovercard.
+	 * @param {number} [delay] - The delay in milliseconds before hiding the hovercard.
 	 * @return {void}
 	 * @private
 	 */
-	_hideHovercard( id: string ): void {
+	_hideHovercard( id: string, delay = this._delayToHide ): void {
 		const timeoutId = setTimeout( () => {
 			const hovercard = dc.getElementById( id );
 
 			if ( hovercard ) {
 				hovercard.remove();
 				this._onHovercardHidden( id, hovercard as HTMLDivElement );
 			}
-		}, this._delayToHide );
+		}, delay );
 
 		this._hideHovercardTimeoutIds.set( id, timeoutId );
 	}
@@ -938,6 +945,23 @@ export default class Hovercards {
 		this._hideHovercard( id );
 	}
 
+	/**
+	 * Handles the click event for hovercard refs.
+	 *
+	 * @param {HovercardRef} hovercardRef    - The hovercard ref object.
+	 * @param {string}       hovercardRef.id - The ID associated with the hovercard.
+	 * @return {void}
+	 * @private
+	 */
+	_handleMouseClick( { id }: HovercardRef ): void {
+		if ( 'ontouchstart' in dc || ! this._hideOnTargetClick ) {
+			return;
+		}
+
+		clearInterval( this._showHovercardTimeoutIds.get( id ) );
+		this._hideHovercard( id, 0 );
+	}
+
 	/**
 	 * Attaches event listeners on or within the target element.
 	 *
@@ -957,6 +981,7 @@ export default class Hovercards {
 		this._queryHovercardRefs( target, dataAttributeName, ignoreSelector ).forEach( ( hovercardRef ) => {
 			hovercardRef.ref.addEventListener( 'mouseenter', hovercardRef.onEnter );
 			hovercardRef.ref.addEventListener( 'mouseleave', hovercardRef.onLeave );
+			hovercardRef.ref.addEventListener( 'click', hovercardRef.onClick );
 		} );
 	};
 
@@ -973,6 +998,11 @@ export default class Hovercards {
 		this._hovercardRefs.forEach( ( hovercardRef ) => {
 			hovercardRef.ref.removeEventListener( 'mouseenter', hovercardRef.onEnter );
 			hovercardRef.ref.removeEventListener( 'mouseleave', hovercardRef.onLeave );
+			hovercardRef.ref.removeEventListener( 'click', hovercardRef.onClick );
+
+			// Clear the hovercard show timeout and remove the hovercard element.
+			clearInterval( this._showHovercardTimeoutIds.get( hovercardRef.id ) );
+			dc.getElementById( hovercardRef.id )?.remove();
 		} );
 
 		this._hovercardRefs = [];

web/packages/hovercards/src/use-hovercards.ts

@@ -17,6 +17,7 @@ export default function useHovercards( {
 	offset,
 	autoFlip,
 	autoShift,
+	hideOnTargetClick,
 	delayToShow,
 	delayToHide,
 	additionalClass,
@@ -47,6 +48,7 @@ export default function useHovercards( {
 				offset,
 				autoFlip,
 				autoShift,
+				hideOnTargetClick,
 				delayToShow,
 				delayToHide,
 				additionalClass,
@@ -65,6 +67,7 @@ export default function useHovercards( {
 			offset,
 			autoFlip,
 			autoShift,
+			hideOnTargetClick,
 			delayToShow,
 			delayToHide,
 			additionalClass,