@atlaskit/teams-app-internal-popup-adaptor 1.1.0

package/package.json

@@ -0,0 +1,81 @@
+{
+	"atlassian": {
+		"team": "People and Teams Collective"
+	},
+	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-monorepo",
+	"main": "dist/cjs/index.js",
+	"module": "dist/esm/index.js",
+	"module:es2019": "dist/es2019/index.js",
+	"types": "dist/types/index.d.ts",
+	"typesVersions": {
+		">=4.5 <5.9": {
+			"*": [
+				"dist/types-ts4.5/*",
+				"dist/types-ts4.5/index.d.ts"
+			]
+		}
+	},
+	"sideEffects": [
+		"*.compiled.css"
+	],
+	"atlaskit:src": "src/PopupTriggerWithHover.tsx",
+	"dependencies": {
+		"@atlaskit/popup": "^4.19.0",
+		"@atlaskit/spinner": "^19.1.0",
+		"@atlassian/entry-point-types": "^0.0.0",
+		"@atlassian/internal-entry-point-container": "^1.1.0",
+		"@atlassian/react-async": "^0.21.0",
+		"@atlassian/relay-environment-provider": "^8.2.0",
+		"@babel/runtime": "^7.0.0",
+		"@compiled/react": "^0.20.0",
+		"bind-event-listener": "^3.0.0",
+		"react-relay": "^20.1.1",
+		"use-callback-ref": "^1.2.3"
+	},
+	"peerDependencies": {
+		"react": "^18.2.0"
+	},
+	"devDependencies": {
+		"@atlassian/feature-flags-test-utils": "^1.1.0",
+		"@atlassian/testing-library": "^0.5.0",
+		"react-dom": "^18.2.0",
+		"relay-test-utils": "^20.1.1"
+	},
+	"techstack": {
+		"@atlassian/frontend": {
+			"import-structure": [
+				"atlassian-conventions"
+			],
+			"circular-dependencies": [
+				"file-and-folder-level"
+			]
+		},
+		"@repo/internal": {
+			"dom-events": "use-bind-event-listener",
+			"design-tokens": [
+				"color"
+			],
+			"theming": [
+				"react-context"
+			],
+			"ui-components": [
+				"lite-mode"
+			],
+			"styling": [
+				"static",
+				"compiled"
+			],
+			"imports": [
+				"import-no-extraneous-disable-for-examples-and-docs"
+			]
+		}
+	},
+	"name": "@atlaskit/teams-app-internal-popup-adaptor",
+	"version": "1.1.0",
+	"description": "Internal popup trigger adapter shared by People and Teams profile card packages (hover/click/preload behavior)",
+	"author": "Atlassian Pty Ltd",
+	"publishConfig": {
+		"registry": "https://packages.atlassian.com/api/npm/npm-remote"
+	},
+	"platform-feature-flags": {}
+}

package/popup-trigger-with-hover/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@atlaskit/teams-app-internal-popup-adaptor/popup-trigger-with-hover",
+  "main": "../dist/cjs/PopupTriggerWithHover.js",
+  "module": "../dist/esm/PopupTriggerWithHover.js",
+  "module:es2019": "../dist/es2019/PopupTriggerWithHover.js",
+  "sideEffects": [
+    "*.compiled.css"
+  ],
+  "types": "../dist/types/PopupTriggerWithHover.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.9": {
+      "*": [
+        "../dist/types-ts4.5/PopupTriggerWithHover.d.ts"
+      ]
+    }
+  }
+}

package/src/PopupTriggerWithHover.tsx

@@ -0,0 +1,240 @@
+import React, {
+	type ReactNode,
+	useCallback,
+	useEffect,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+	useState,
+} from 'react';
+
+import { loadEntryPoint } from 'react-relay';
+import { mergeRefs } from 'use-callback-ref';
+
+import { type ContentProps, Popup, type PopupProps, type TriggerProps } from '@atlaskit/popup';
+import Spinner from '@atlaskit/spinner';
+import type {
+	AnyEntryPoint,
+	EntryPointRef,
+	GetRuntimePropsFromEntryPoint,
+	ParamsOfEntryPoint,
+	RuntimePropsOfEntryPoint,
+} from '@atlassian/entry-point-types';
+import {
+	type ErrorCallback,
+	type ErrorFallback,
+	InternalEntryPointContainer,
+} from '@atlassian/internal-entry-point-container';
+import type { JSResourceReference } from '@atlassian/react-async';
+import { useRelayEnvironmentProvider } from '@atlassian/relay-environment-provider';
+
+import { useHoverTriggerRef } from './useHoverTriggerRef';
+import { usePreloadRef } from './usePreloadRef';
+import { usePressableTriggerRef } from './usePressableTriggerRef';
+
+export type TriggerMode = 'hover' | 'click' | Array<'hover' | 'click'>;
+
+const emptyEntryPointParams = {} as ParamsOfEntryPoint<AnyEntryPoint>;
+const emptyEntryPointProps = {} as RuntimePropsOfEntryPoint<AnyEntryPoint>;
+
+type UnionOmit<T, K extends string | number | symbol> = T extends unknown ? Omit<T, K> : never;
+
+type CustomPopupProps = UnionOmit<PopupProps, 'isOpen' | 'content'>;
+type EntryPointPropsType<TEntryPoint> = GetRuntimePropsFromEntryPoint<TEntryPoint>;
+
+const FallbackComponent = ({
+	fallback,
+	onUnmount,
+}: {
+	fallback?: ReactNode;
+	onUnmount: () => void;
+}) => {
+	useEffect(() => {
+		return () => onUnmount();
+	}, [onUnmount]);
+
+	return <>{fallback || <Spinner />}</>;
+};
+
+export type PopupTriggerWithHoverProps<TEntryPoint> = {
+	entryPoint: TEntryPoint;
+	entryPointParams?: ParamsOfEntryPoint<TEntryPoint>;
+	entryPointProps?: Omit<EntryPointPropsType<TEntryPoint>, 'onClose' | 'onContentResized'> & {
+		onClose?: () => void;
+		onContentResized?: ContentProps['update'];
+	};
+	errorFallback?: ErrorFallback;
+	fallback?: ReactNode;
+	forcedReportErrorUFO?: boolean;
+	onError?: ErrorCallback;
+	onOpen?: (method: 'hover' | 'click') => void;
+	trigger: (triggerProps: TriggerProps) => ReactNode;
+	/**
+	 * How the popup should be triggered. Defaults to `'click'` when omitted.
+	 */
+	triggerMode?: TriggerMode;
+} & CustomPopupProps;
+
+export function PopupTriggerWithHover<TEntryPoint extends AnyEntryPoint>({
+	trigger,
+	triggerMode = 'click',
+	entryPoint,
+	entryPointParams,
+	entryPointProps,
+	fallback,
+	errorFallback,
+	onError,
+	forcedReportErrorUFO,
+	onOpen,
+	onClose,
+	...popupProps
+}: PopupTriggerWithHoverProps<TEntryPoint>): React.JSX.Element {
+	const environmentProvider = useRelayEnvironmentProvider();
+
+	const id = useMemo((): string => {
+		return (entryPoint.root as JSResourceReference<unknown>).getModuleName() || 'unknown';
+	}, [entryPoint]);
+
+	const [isOpen, setIsOpen] = useState(false);
+	const [content, setContent] = useState<ReactNode | null>(null);
+
+	const updateRef = useRef<(() => void) | null>(null);
+	const openedByRef = useRef<'hover' | 'click' | null>(null);
+	const isOpenRef = useRef(isOpen);
+	const triggers = Array.isArray(triggerMode) ? triggerMode : [triggerMode];
+
+	useLayoutEffect(() => {
+		isOpenRef.current = isOpen;
+	}, [isOpen]);
+
+	const handleOpen = useCallback(
+		(method: 'hover' | 'click' | null) => {
+			setIsOpen(true);
+			if (method) {
+				onOpen?.(method);
+			}
+		},
+		[onOpen],
+	);
+
+	const handleClose = useCallback(
+		(
+			event?: Event | React.MouseEvent<Element, MouseEvent> | React.KeyboardEvent<Element> | null,
+			currentLevel?: any,
+		) => {
+			setIsOpen(false);
+			onClose?.(event ?? null, currentLevel);
+		},
+		[onClose],
+	);
+
+	const load = useCallback(
+		() =>
+			loadEntryPoint<TEntryPoint>(
+				environmentProvider,
+				entryPoint,
+				entryPointParams ?? emptyEntryPointParams,
+			),
+		[entryPoint, entryPointParams, environmentProvider],
+	);
+
+	const onLoad = useCallback(
+		({ reference: entryPointReference }: { reference: EntryPointRef<TEntryPoint> }) => {
+			if (isOpenRef.current) {
+				return;
+			}
+
+			handleOpen(openedByRef.current);
+
+			setContent(
+				<InternalEntryPointContainer
+					id={id}
+					entryPointReference={entryPointReference}
+					fallback={
+						<FallbackComponent fallback={fallback} onUnmount={() => updateRef.current?.()} />
+					}
+					errorFallback={errorFallback}
+					runtimeProps={
+						{
+							...(entryPointProps ?? emptyEntryPointProps),
+							onContentResized: () => {
+								updateRef.current?.();
+							},
+							onClose: handleClose,
+						} as unknown as EntryPointPropsType<TEntryPoint>
+					}
+					onError={onError}
+					forcedError={forcedReportErrorUFO}
+				/>,
+			);
+		},
+		[
+			setContent,
+			id,
+			entryPointProps,
+			fallback,
+			forcedReportErrorUFO,
+			errorFallback,
+			handleOpen,
+			onError,
+			handleClose,
+		],
+	);
+
+	const preloadRef = usePreloadRef<EntryPointRef<TEntryPoint>>({
+		load,
+		onLoad,
+	});
+
+	const pressableRef = usePressableTriggerRef({
+		onOpen: preloadRef.loadAndOpen,
+		onClose: handleClose,
+		isOpen,
+		isDisabled: !triggers.includes('click'),
+		openedByRef,
+	});
+
+	const { triggerRef: hoverTriggerRef, contentRef: hoverContentRef } = useHoverTriggerRef({
+		onOpen: preloadRef.loadAndOpen,
+		onClose: handleClose,
+		isOpen,
+		isDisabled: !triggers.includes('hover'),
+		openedByRef,
+	});
+
+	useEffect(() => {
+		if (!isOpen) {
+			openedByRef.current = null;
+		}
+	}, [isOpen]);
+
+	const popupTrigger = useCallback(
+		(triggerProps: TriggerProps) => {
+			const mergedRef = mergeRefs([preloadRef, pressableRef, hoverTriggerRef, triggerProps.ref]);
+			return trigger({ ...triggerProps, ref: mergedRef });
+		},
+		[trigger, preloadRef, pressableRef, hoverTriggerRef],
+	);
+
+	const popupContent = useCallback(
+		({ update }: ContentProps) => {
+			updateRef.current = update;
+			return (
+				<div ref={hoverContentRef} role="none">
+					{content}
+				</div>
+			);
+		},
+		[content, hoverContentRef],
+	);
+
+	return (
+		<Popup
+			{...popupProps}
+			isOpen={isOpen}
+			onClose={handleClose}
+			trigger={popupTrigger}
+			content={popupContent}
+		/>
+	);
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export {
+	PopupTriggerWithHover,
+	type PopupTriggerWithHoverProps,
+	type TriggerMode,
+} from './PopupTriggerWithHover';

package/src/useHoverDelay.ts

@@ -0,0 +1,42 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+/**
+ * Hook for managing delayed hover actions with timeout management.
+ */
+function useHoverDelay(
+	callback: () => void,
+	delay: number,
+): {
+	schedule: () => void;
+	clear: () => void;
+} {
+	const timeoutRef = useRef<number | null>(null);
+
+	const callbackRef = useRef(callback);
+
+	useEffect(() => {
+		callbackRef.current = callback;
+	}, [callback]);
+
+	const clear = useCallback((): void => {
+		if (timeoutRef.current) {
+			clearTimeout(timeoutRef.current);
+			timeoutRef.current = null;
+		}
+	}, []);
+
+	const schedule = useCallback((): void => {
+		clear();
+		timeoutRef.current = window.setTimeout(() => {
+			callbackRef.current();
+		}, delay);
+	}, [delay, clear]);
+
+	useEffect(() => {
+		return () => clear();
+	}, [clear]);
+
+	return { schedule, clear };
+}
+
+export { useHoverDelay };

package/src/useHoverTriggerRef.ts

@@ -0,0 +1,177 @@
+import { type MutableRefObject, useCallback, useEffect, useLayoutEffect, useRef } from 'react';
+
+import { bind, type UnbindFn } from 'bind-event-listener';
+
+import { useHoverDelay } from './useHoverDelay';
+import { getChildPortalFromParentPopup, hasRelatedTarget, isMovingToKudos } from './utils';
+
+const HOVER_OPEN_DELAY = 800;
+const HOVER_CLOSE_DELAY = 200;
+
+export type UseHoverTriggerRefProps = {
+	onOpen: () => void;
+	onClose?: () => void;
+	isOpen?: boolean;
+	isDisabled?: boolean;
+	openedByRef?: MutableRefObject<'hover' | 'click' | null>;
+	delays?: {
+		hoverOpen?: number;
+		hoverClose?: number;
+	};
+};
+
+/**
+ * Hover behavior for popup trigger and content with delayed open/close.
+ */
+export function useHoverTriggerRef({
+	onOpen,
+	onClose,
+	isOpen = false,
+	isDisabled = false,
+	openedByRef,
+	delays = {},
+}: UseHoverTriggerRefProps): {
+	triggerRef: (element: HTMLElement | null) => void;
+	contentRef: (element: HTMLElement | null) => void;
+} {
+	const { hoverOpen = HOVER_OPEN_DELAY, hoverClose = HOVER_CLOSE_DELAY } = delays;
+
+	const triggerNodeRef = useRef<HTMLElement | null>(null);
+	const triggerListeners = useRef<UnbindFn[]>([]);
+	const contentNodeRef = useRef<HTMLElement | null>(null);
+	const contentListeners = useRef<Map<Element, UnbindFn>>(new Map());
+	const isOpenRef = useRef(isOpen);
+
+	useLayoutEffect(() => {
+		isOpenRef.current = isOpen;
+	}, [isOpen]);
+
+	const openDelay = useHoverDelay(() => {
+		if (isOpenRef.current) {
+			return;
+		}
+		if (openedByRef) {
+			openedByRef.current = 'hover';
+		}
+		onOpen();
+	}, hoverOpen);
+
+	const closeDelay = useHoverDelay(() => {
+		if (!isOpenRef.current) {
+			return;
+		}
+		if (!openedByRef || openedByRef.current === 'hover') {
+			onClose?.();
+		}
+	}, hoverClose);
+
+	const openDelayRef = useRef(openDelay);
+	const closeDelayRef = useRef(closeDelay);
+	openDelayRef.current = openDelay;
+	closeDelayRef.current = closeDelay;
+
+	const handleTriggerEnter = useCallback(() => {
+		closeDelayRef.current.clear();
+		openDelayRef.current.schedule();
+	}, []);
+
+	const handleTriggerLeave = useCallback(() => {
+		openDelayRef.current.clear();
+		closeDelayRef.current.schedule();
+	}, []);
+
+	const triggerRef = useCallback(
+		(element: HTMLElement | null): void => {
+			if (element === triggerNodeRef.current) {
+				return;
+			}
+
+			triggerListeners.current.forEach((unbind) => unbind());
+			triggerListeners.current = [];
+			triggerNodeRef.current = element;
+
+			if (element && !isDisabled) {
+				triggerListeners.current.push(
+					bind(element, { type: 'mouseenter', listener: handleTriggerEnter }),
+					bind(element, { type: 'mouseleave', listener: handleTriggerLeave }),
+				);
+			}
+		},
+		[handleTriggerEnter, handleTriggerLeave, isDisabled],
+	);
+
+	const handleContentEnter = useCallback(() => {
+		closeDelayRef.current.clear();
+	}, []);
+
+	const cleanupContentListeners = useCallback(() => {
+		contentListeners.current.forEach((unbind) => unbind());
+		contentListeners.current.clear();
+	}, []);
+
+	const attachContentListeners = useCallback(
+		(element: Element) => {
+			if (contentListeners.current.has(element)) {
+				return;
+			}
+
+			const handleMouseLeave = (event: Event) => {
+				if (!hasRelatedTarget(event)) {
+					return;
+				}
+
+				const relatedTarget = event.relatedTarget;
+
+				if (isMovingToKudos(relatedTarget)) {
+					return;
+				}
+
+				const childPortal = getChildPortalFromParentPopup(relatedTarget, contentNodeRef.current);
+				if (childPortal) {
+					attachContentListeners(childPortal);
+					return;
+				}
+
+				closeDelayRef.current.schedule();
+			};
+
+			const unbindEnter = bind(element, { type: 'mouseenter', listener: handleContentEnter });
+			const unbindLeave = bind(element, { type: 'mouseleave', listener: handleMouseLeave });
+
+			contentListeners.current.set(element, () => {
+				unbindEnter();
+				unbindLeave();
+			});
+		},
+		[handleContentEnter],
+	);
+
+	const contentRef = useCallback(
+		(element: HTMLElement | null): void => {
+			if (element === contentNodeRef.current) {
+				return;
+			}
+
+			cleanupContentListeners();
+			contentNodeRef.current = element;
+
+			if (element && !isDisabled) {
+				attachContentListeners(element);
+			}
+		},
+		[attachContentListeners, cleanupContentListeners, isDisabled],
+	);
+
+	useEffect(() => {
+		const listeners = contentListeners.current;
+		const triggers = triggerListeners.current;
+		return () => {
+			openDelayRef.current.clear();
+			closeDelayRef.current.clear();
+			triggers.forEach((unbind) => unbind());
+			listeners.forEach((unbind) => unbind());
+		};
+	}, []);
+
+	return { triggerRef, contentRef };
+}

package/src/usePreloadRef.ts

@@ -0,0 +1,152 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { bind, type UnbindFn } from 'bind-event-listener';
+
+const PRELOAD_MAX_AGE = 5 * 60 * 1000;
+const TIME_TO_INTENT = 200;
+
+export type OnLoad<T> = (obj: { dispose: () => void; reference: T }) => void;
+
+export type UsePreloadRefProps<T> = {
+	load: () => T;
+	onLoad: OnLoad<T>;
+};
+
+export function usePreloadRef<T extends { dispose: () => void }>({
+	load,
+	onLoad,
+}: UsePreloadRefProps<T>): ((element: HTMLElement | null) => void) & {
+	loadAndOpen: () => void;
+} {
+	const nodeRef = useRef<HTMLElement | null>(null);
+	const eventListeners = useRef<UnbindFn[]>([]);
+
+	const { loadAndOpen, preloadReference, cancelPreload } = useMemo(() => {
+		const request: {
+			load?: { dispose: () => void; reference: T };
+			preload?: { dispose: () => void; reference: T };
+			preloadIntentTimeout?: ReturnType<typeof setTimeout>;
+			preloadMaxAgeTimeout?: ReturnType<typeof setTimeout>;
+		} = {};
+
+		const clearPreloadTimeouts = () => {
+			if (request.preloadIntentTimeout != null) {
+				clearTimeout(request.preloadIntentTimeout);
+				delete request.preloadIntentTimeout;
+			}
+
+			if (request.preloadMaxAgeTimeout != null) {
+				clearTimeout(request.preloadMaxAgeTimeout);
+				delete request.preloadMaxAgeTimeout;
+			}
+		};
+
+		const cancelPreload = () => {
+			clearPreloadTimeouts();
+			request.preload?.dispose();
+		};
+
+		const loadReference = () => {
+			if (request.load) {
+				return request.load;
+			}
+
+			const reference = request.preload?.reference ?? load();
+			if (request.preload) {
+				delete request.preload;
+			}
+
+			request.load = {
+				reference,
+				dispose() {
+					reference.dispose();
+					delete request.load;
+				},
+			};
+
+			return request.load;
+		};
+
+		const loadAndOpen = () => {
+			clearPreloadTimeouts();
+			onLoad(loadReference());
+		};
+
+		const preloadReference = () => {
+			if (request.preloadIntentTimeout || request.preload) {
+				return;
+			}
+
+			request.preloadIntentTimeout = setTimeout(() => {
+				delete request.preloadIntentTimeout;
+
+				const reference = load();
+
+				request.preload = {
+					reference,
+					dispose() {
+						reference.dispose();
+						delete request.preload;
+					},
+				};
+
+				request.preloadMaxAgeTimeout = setTimeout(() => {
+					delete request.preloadMaxAgeTimeout;
+					request.preload?.dispose();
+				}, PRELOAD_MAX_AGE);
+			}, TIME_TO_INTENT);
+		};
+
+		return {
+			loadAndOpen,
+			preloadReference,
+			cancelPreload,
+		};
+	}, [load, onLoad]);
+
+	const cleanUpEventListeners = useCallback(() => {
+		eventListeners.current.forEach((unbind) => {
+			unbind();
+		});
+		eventListeners.current = [];
+	}, []);
+
+	const addEventListener = useCallback(
+		(element: HTMLElement, type: string, callback: EventListener) => {
+			const unbind = bind(element, {
+				type,
+				listener: callback,
+			});
+
+			eventListeners.current.push(unbind);
+		},
+		[],
+	);
+
+	const refCallback = useCallback(
+		(element: HTMLElement | null) => {
+			if (element !== nodeRef.current) {
+				if (nodeRef.current) {
+					cancelPreload();
+					cleanUpEventListeners();
+				}
+				if (element) {
+					addEventListener(element, 'mouseenter', preloadReference);
+					addEventListener(element, 'mouseleave', cancelPreload);
+				}
+				nodeRef.current = element;
+			}
+		},
+		[preloadReference, cancelPreload, addEventListener, cleanUpEventListeners],
+	);
+
+	useEffect(() => {
+		return () => {
+			cleanUpEventListeners();
+		};
+	}, [cleanUpEventListeners]);
+
+	return Object.assign(refCallback, {
+		loadAndOpen,
+	});
+}