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

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+## 1.1.0
+
+### Minor Changes
+
+- [`780c4e073e406`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/780c4e073e406) -
+  Add adaptor components
+
+### Patch Changes
+
+- Updated dependencies

package/README.md

@@ -0,0 +1,17 @@
+# Teams App Internal Popup Adaptor
+
+Internal popup trigger adapter shared by People and Teams profile card packages
+(`@atlassian/team-profilecard`, `@atlassian/user-profile-card`).
+
+Provides the `PopupTriggerWithHover` component plus the underlying hover/click/preload trigger ref
+hooks used to lazily load and open profile card popups via Relay entry points.
+
+This package is intended for internal use within the People and Teams Collective only.
+
+## Exports
+
+- `@atlaskit/teams-app-internal-popup-adaptor/popup-trigger-with-hover` - the `PopupTriggerWithHover`
+  component along with the `PopupTriggerWithHoverProps` and `TriggerMode` types.
+
+The hover/click/preload trigger ref hooks and DOM helper utilities are internal implementation
+details of `PopupTriggerWithHover` and are not exposed.

package/__tests__/unit/PopupTriggerWithHover.test.tsx

@@ -0,0 +1,141 @@
+import React from 'react';
+
+import { act, fireEvent, render, screen, userEvent } from '@atlassian/testing-library';
+
+import { PopupTriggerWithHover } from '../../src/PopupTriggerWithHover';
+
+jest.mock('@atlassian/relay-environment-provider', () => ({
+	useRelayEnvironmentProvider: () => ({}),
+}));
+
+jest.mock('react-relay', () => ({
+	loadEntryPoint: () => ({
+		dispose: jest.fn(),
+		entryPoints: {},
+		extraProps: null,
+		getPreloadProps: () => ({}),
+	}),
+}));
+
+jest.mock('@atlassian/internal-entry-point-container', () => ({
+	InternalEntryPointContainer: ({ runtimeProps }: { runtimeProps: Record<string, unknown> }) => (
+		<div data-testid="popup-content" data-runtime-props={JSON.stringify(Object.keys(runtimeProps))}>
+			popup content
+		</div>
+	),
+}));
+
+const buildEntryPoint = () => ({
+	root: {
+		getModuleName: () => 'test-entry-point',
+	},
+	getPreloadProps: () => ({ entryPoints: {}, queries: {}, extraProps: null }),
+});
+
+const renderTrigger = (
+	overrides: Partial<React.ComponentProps<typeof PopupTriggerWithHover>> = {},
+) =>
+	render(
+		<PopupTriggerWithHover
+			entryPoint={buildEntryPoint() as never}
+			placement="bottom-start"
+			trigger={({ ref, ...triggerProps }) => (
+				<button ref={ref} {...triggerProps} type="button" data-testid="trigger">
+					open
+				</button>
+			)}
+			{...overrides}
+		/>,
+	);
+
+beforeEach(() => {
+	jest.useFakeTimers();
+});
+
+afterEach(() => {
+	jest.useRealTimers();
+});
+
+test('renders only the trigger before the popup is opened', () => {
+	renderTrigger();
+
+	expect(screen.getByTestId('trigger')).toBeInTheDocument();
+	expect(screen.queryByTestId('popup-content')).not.toBeInTheDocument();
+});
+
+test('clicking the trigger opens the popup and reports the open method', async () => {
+	const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
+	const onOpen = jest.fn();
+
+	renderTrigger({ onOpen });
+
+	await user.click(screen.getByTestId('trigger'));
+
+	expect(screen.getByTestId('popup-content')).toBeInTheDocument();
+	expect(onOpen).toHaveBeenCalledWith('click');
+});
+
+test('clicking the trigger again closes the popup', async () => {
+	const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
+
+	renderTrigger();
+
+	await user.click(screen.getByTestId('trigger'));
+	expect(screen.getByTestId('popup-content')).toBeInTheDocument();
+
+	await user.click(screen.getByTestId('trigger'));
+	expect(screen.queryByTestId('popup-content')).not.toBeInTheDocument();
+});
+
+test('hover triggerMode opens the popup after the hover delay', () => {
+	const onOpen = jest.fn();
+
+	renderTrigger({ onOpen, triggerMode: 'hover' });
+
+	fireEvent.mouseEnter(screen.getByTestId('trigger'));
+	act(() => {
+		jest.advanceTimersByTime(800);
+	});
+
+	expect(screen.getByTestId('popup-content')).toBeInTheDocument();
+	expect(onOpen).toHaveBeenCalledWith('hover');
+});
+
+test('hover triggerMode does not open on click', () => {
+	const onOpen = jest.fn();
+
+	renderTrigger({ onOpen, triggerMode: 'hover' });
+
+	fireEvent.click(screen.getByTestId('trigger'));
+
+	expect(screen.queryByTestId('popup-content')).not.toBeInTheDocument();
+	expect(onOpen).not.toHaveBeenCalled();
+});
+
+test('triggerMode array of click and hover supports both interactions', async () => {
+	const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
+	const onOpen = jest.fn();
+
+	renderTrigger({ onOpen, triggerMode: ['click', 'hover'] });
+
+	await user.click(screen.getByTestId('trigger'));
+	expect(onOpen).toHaveBeenLastCalledWith('click');
+});
+
+test('the popup content receives onClose and onContentResized in its runtime props', async () => {
+	const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
+
+	renderTrigger();
+
+	await user.click(screen.getByTestId('trigger'));
+
+	const runtimeProps = JSON.parse(
+		screen.getByTestId('popup-content').getAttribute('data-runtime-props') ?? '[]',
+	);
+	expect(runtimeProps).toEqual(expect.arrayContaining(['onContentResized', 'onClose']));
+});
+
+test('capture and report a11y violations', async () => {
+	const { container } = renderTrigger();
+	await expect(container).toBeAccessible();
+});

package/__tests__/unit/useHoverDelay.test.tsx

@@ -0,0 +1,99 @@
+import React, { useEffect } from 'react';
+
+import { act, render } from '@atlassian/testing-library';
+
+import { useHoverDelay } from '../../src/useHoverDelay';
+
+const HoverDelayTrigger = ({
+	callback,
+	delay,
+	action,
+}: {
+	callback: () => void;
+	delay: number;
+	action: 'schedule' | 'clear' | 'scheduleAndClear' | 'scheduleTwice';
+}) => {
+	const { schedule, clear } = useHoverDelay(callback, delay);
+
+	useEffect(() => {
+		if (action === 'schedule') {
+			schedule();
+		} else if (action === 'clear') {
+			schedule();
+			clear();
+		} else if (action === 'scheduleTwice') {
+			schedule();
+			setTimeout(() => schedule(), 100);
+		}
+	}, [action, schedule, clear]);
+
+	return <div data-testid="harness" />;
+};
+
+beforeEach(() => {
+	jest.useFakeTimers();
+});
+
+afterEach(() => {
+	jest.useRealTimers();
+});
+
+test('schedule fires the callback after the configured delay', () => {
+	const callback = jest.fn();
+
+	render(<HoverDelayTrigger callback={callback} delay={500} action="schedule" />);
+	expect(callback).not.toHaveBeenCalled();
+
+	act(() => {
+		jest.advanceTimersByTime(499);
+	});
+	expect(callback).not.toHaveBeenCalled();
+
+	act(() => {
+		jest.advanceTimersByTime(1);
+	});
+	expect(callback).toHaveBeenCalledTimes(1);
+});
+
+test('clear cancels a pending callback', () => {
+	const callback = jest.fn();
+
+	render(<HoverDelayTrigger callback={callback} delay={200} action="clear" />);
+
+	act(() => {
+		jest.advanceTimersByTime(1000);
+	});
+
+	expect(callback).not.toHaveBeenCalled();
+});
+
+test('schedule replaces an in-flight timer rather than stacking it', () => {
+	const callback = jest.fn();
+
+	render(<HoverDelayTrigger callback={callback} delay={300} action="scheduleTwice" />);
+
+	// At 100ms the second schedule() fires, resetting the 300ms timer
+	act(() => {
+		jest.advanceTimersByTime(399);
+	});
+	expect(callback).not.toHaveBeenCalled();
+
+	act(() => {
+		jest.advanceTimersByTime(1);
+	});
+	expect(callback).toHaveBeenCalledTimes(1);
+});
+
+test('unmounting clears any pending timer', () => {
+	const callback = jest.fn();
+
+	const { unmount } = render(<HoverDelayTrigger callback={callback} delay={100} action="schedule" />);
+
+	unmount();
+
+	act(() => {
+		jest.advanceTimersByTime(1000);
+	});
+
+	expect(callback).not.toHaveBeenCalled();
+});

package/__tests__/unit/useHoverTriggerRef.test.tsx

@@ -0,0 +1,121 @@
+import React, { type MutableRefObject, useRef, useState } from 'react';
+
+import { act, fireEvent, render, screen } from '@atlassian/testing-library';
+
+import { useHoverTriggerRef } from '../../src/useHoverTriggerRef';
+
+const HoverTrigger = ({
+	onOpen,
+	onClose,
+	isDisabled = false,
+	openedByRef,
+}: {
+	onOpen: () => void;
+	onClose?: () => void;
+	isDisabled?: boolean;
+	openedByRef?: MutableRefObject<'hover' | 'click' | null>;
+}) => {
+	const [open, setOpen] = useState(false);
+	const fallbackRef = useRef<'hover' | 'click' | null>(null);
+	const { triggerRef, contentRef } = useHoverTriggerRef({
+		onOpen: () => {
+			setOpen(true);
+			onOpen();
+		},
+		onClose: () => {
+			setOpen(false);
+			onClose?.();
+		},
+		isOpen: open,
+		isDisabled,
+		openedByRef: openedByRef ?? fallbackRef,
+	});
+
+	return (
+		<>
+			<button type="button" ref={triggerRef} data-testid="trigger">
+				open
+			</button>
+			{open && (
+				<div ref={contentRef} data-testid="content">
+					popup content
+				</div>
+			)}
+		</>
+	);
+};
+
+beforeEach(() => {
+	jest.useFakeTimers();
+});
+
+afterEach(() => {
+	jest.useRealTimers();
+});
+
+test('hovering the trigger opens the popup after the open delay', () => {
+	const onOpen = jest.fn();
+	const openedByRef: MutableRefObject<'hover' | 'click' | null> = { current: null };
+
+	render(<HoverTrigger onOpen={onOpen} openedByRef={openedByRef} />);
+
+	fireEvent.mouseEnter(screen.getByTestId('trigger'));
+
+	act(() => {
+		jest.advanceTimersByTime(800);
+	});
+
+	expect(onOpen).toHaveBeenCalledTimes(1);
+	expect(openedByRef.current).toBe('hover');
+});
+
+test('leaving the trigger before the open delay cancels the open', () => {
+	const onOpen = jest.fn();
+
+	render(<HoverTrigger onOpen={onOpen} />);
+
+	fireEvent.mouseEnter(screen.getByTestId('trigger'));
+	act(() => {
+		jest.advanceTimersByTime(400);
+	});
+	fireEvent.mouseLeave(screen.getByTestId('trigger'));
+	act(() => {
+		jest.advanceTimersByTime(2000);
+	});
+
+	expect(onOpen).not.toHaveBeenCalled();
+});
+
+test('hovering content keeps the popup open even after leaving the trigger', () => {
+	const onOpen = jest.fn();
+	const onClose = jest.fn();
+
+	render(<HoverTrigger onOpen={onOpen} onClose={onClose} />);
+
+	fireEvent.mouseEnter(screen.getByTestId('trigger'));
+	act(() => {
+		jest.advanceTimersByTime(800);
+	});
+	expect(onOpen).toHaveBeenCalledTimes(1);
+
+	fireEvent.mouseLeave(screen.getByTestId('trigger'));
+	fireEvent.mouseEnter(screen.getByTestId('content'));
+	act(() => {
+		jest.advanceTimersByTime(1000);
+	});
+
+	expect(onClose).not.toHaveBeenCalled();
+});
+
+test('isDisabled prevents hover from opening the popup', () => {
+	const onOpen = jest.fn();
+
+	render(<HoverTrigger onOpen={onOpen} isDisabled />);
+
+	fireEvent.mouseEnter(screen.getByTestId('trigger'));
+	act(() => {
+		jest.advanceTimersByTime(2000);
+	});
+
+	expect(onOpen).not.toHaveBeenCalled();
+});

package/__tests__/unit/usePreloadRef.test.tsx

@@ -0,0 +1,118 @@
+import React, { useEffect, useRef } from 'react';
+
+import { fireEvent, render, screen } from '@atlassian/testing-library';
+
+import { type OnLoad, usePreloadRef } from '../../src/usePreloadRef';
+
+type FakeReference = { dispose: jest.Mock };
+
+const buildReference = (): FakeReference => ({ dispose: jest.fn() });
+
+const PreloadTrigger = ({
+	load,
+	onLoad,
+	openOnMount = false,
+}: {
+	load: () => FakeReference;
+	onLoad: OnLoad<FakeReference>;
+	openOnMount?: boolean;
+}) => {
+	const ref = usePreloadRef({ load, onLoad });
+	const openedRef = useRef(false);
+
+	useEffect(() => {
+		if (openOnMount && !openedRef.current) {
+			openedRef.current = true;
+			ref.loadAndOpen();
+		}
+	}, [openOnMount, ref]);
+
+	return (
+		<button type="button" ref={ref} data-testid="trigger">
+			open
+		</button>
+	);
+};
+
+beforeEach(() => {
+	jest.useFakeTimers();
+});
+
+afterEach(() => {
+	jest.useRealTimers();
+});
+
+test('loadAndOpen invokes load and onLoad immediately when no preload is in flight', () => {
+	const reference = buildReference();
+	const load = jest.fn(() => reference);
+	const onLoad = jest.fn();
+
+	render(<PreloadTrigger load={load} onLoad={onLoad} openOnMount />);
+
+	expect(load).toHaveBeenCalledTimes(1);
+	expect(onLoad).toHaveBeenCalledTimes(1);
+	expect(onLoad).toHaveBeenCalledWith(expect.objectContaining({ reference }));
+});
+
+test('hovering the trigger schedules a preload after the intent delay', () => {
+	const reference = buildReference();
+	const load = jest.fn(() => reference);
+	const onLoad = jest.fn();
+
+	render(<PreloadTrigger load={load} onLoad={onLoad} />);
+
+	fireEvent.mouseEnter(screen.getByTestId('trigger'));
+	expect(load).not.toHaveBeenCalled();
+
+	jest.advanceTimersByTime(200);
+	expect(load).toHaveBeenCalledTimes(1);
+	expect(onLoad).not.toHaveBeenCalled();
+});
+
+test('mouseleave before the intent delay cancels the preload', () => {
+	const reference = buildReference();
+	const load = jest.fn(() => reference);
+	const onLoad = jest.fn();
+
+	render(<PreloadTrigger load={load} onLoad={onLoad} />);
+
+	fireEvent.mouseEnter(screen.getByTestId('trigger'));
+	jest.advanceTimersByTime(100);
+	fireEvent.mouseLeave(screen.getByTestId('trigger'));
+	jest.advanceTimersByTime(1000);
+
+	expect(load).not.toHaveBeenCalled();
+});
+
+test('preloaded reference is reused by loadAndOpen instead of loading again', () => {
+	const reference = buildReference();
+	const load = jest.fn(() => reference);
+	const onLoad = jest.fn();
+
+	const { rerender } = render(<PreloadTrigger load={load} onLoad={onLoad} />);
+
+	fireEvent.mouseEnter(screen.getByTestId('trigger'));
+	jest.advanceTimersByTime(200);
+	expect(load).toHaveBeenCalledTimes(1);
+
+	rerender(<PreloadTrigger load={load} onLoad={onLoad} openOnMount />);
+
+	expect(load).toHaveBeenCalledTimes(1);
+	expect(onLoad).toHaveBeenCalledTimes(1);
+	expect(onLoad).toHaveBeenCalledWith(expect.objectContaining({ reference }));
+});
+
+test('a stale preload is disposed after the max-age timeout', () => {
+	const reference = buildReference();
+	const load = jest.fn(() => reference);
+	const onLoad = jest.fn();
+
+	render(<PreloadTrigger load={load} onLoad={onLoad} />);
+
+	fireEvent.mouseEnter(screen.getByTestId('trigger'));
+	jest.advanceTimersByTime(200);
+	expect(load).toHaveBeenCalledTimes(1);
+
+	jest.advanceTimersByTime(5 * 60 * 1000);
+	expect(reference.dispose).toHaveBeenCalledTimes(1);
+});

package/__tests__/unit/usePressableTriggerRef.test.tsx

@@ -0,0 +1,104 @@
+import React, { type MutableRefObject, useRef } from 'react';
+
+import { fireEvent, render, screen, userEvent } from '@atlassian/testing-library';
+
+import { usePressableTriggerRef } from '../../src/usePressableTriggerRef';
+
+const PressableTrigger = ({
+	onOpen,
+	onClose,
+	isOpen = false,
+	isDisabled = false,
+	openedByRef,
+}: {
+	onOpen: () => void;
+	onClose?: () => void;
+	isOpen?: boolean;
+	isDisabled?: boolean;
+	openedByRef?: MutableRefObject<'hover' | 'click' | null>;
+}) => {
+	const fallbackRef = useRef<'hover' | 'click' | null>(null);
+	const ref = usePressableTriggerRef({
+		onOpen,
+		onClose,
+		isOpen,
+		isDisabled,
+		openedByRef: openedByRef ?? fallbackRef,
+	});
+
+	return (
+		<button type="button" ref={ref} data-testid="trigger">
+			open
+		</button>
+	);
+};
+
+test('clicking the trigger opens the popup and records the open method as click', () => {
+	const onOpen = jest.fn();
+	const openedByRef: MutableRefObject<'hover' | 'click' | null> = { current: null };
+
+	render(<PressableTrigger onOpen={onOpen} openedByRef={openedByRef} />);
+
+	fireEvent.click(screen.getByTestId('trigger'));
+
+	expect(onOpen).toHaveBeenCalledTimes(1);
+	expect(openedByRef.current).toBe('click');
+});
+
+test('clicking again when already open invokes onClose instead of onOpen', () => {
+	const onOpen = jest.fn();
+	const onClose = jest.fn();
+
+	render(<PressableTrigger onOpen={onOpen} onClose={onClose} isOpen />);
+
+	fireEvent.click(screen.getByTestId('trigger'));
+
+	expect(onOpen).not.toHaveBeenCalled();
+	expect(onClose).toHaveBeenCalledTimes(1);
+});
+
+test('isDisabled stops click from triggering onOpen', () => {
+	const onOpen = jest.fn();
+
+	render(<PressableTrigger onOpen={onOpen} isDisabled />);
+
+	fireEvent.click(screen.getByTestId('trigger'));
+
+	expect(onOpen).not.toHaveBeenCalled();
+});
+
+test('pressing Enter on the trigger opens the popup', async () => {
+	const user = userEvent.setup();
+	const onOpen = jest.fn();
+
+	render(<PressableTrigger onOpen={onOpen} />);
+
+	screen.getByTestId('trigger').focus();
+	await user.keyboard('{Enter}');
+
+	expect(onOpen).toHaveBeenCalledTimes(1);
+});
+
+test('pressing Space on the trigger opens the popup', async () => {
+	const user = userEvent.setup();
+	const onOpen = jest.fn();
+
+	render(<PressableTrigger onOpen={onOpen} />);
+
+	screen.getByTestId('trigger').focus();
+	await user.keyboard(' ');
+
+	expect(onOpen).toHaveBeenCalledTimes(1);
+});
+
+test('keyboard activation works even when click is disabled, preserving accessibility', async () => {
+	const user = userEvent.setup();
+	const onOpen = jest.fn();
+
+	render(<PressableTrigger onOpen={onOpen} isDisabled />);
+
+	screen.getByTestId('trigger').focus();
+	await user.keyboard('{Enter}');
+
+	expect(onOpen).toHaveBeenCalledTimes(1);
+});

package/__tests__/unit/utils.test.tsx

@@ -0,0 +1,86 @@
+import {
+	getChildPortalFromParentPopup,
+	hasRelatedTarget,
+	isMovingToKudos,
+} from '../../src/utils';
+
+const buildEventWithRelatedTarget = (relatedTarget: EventTarget | null): Event => {
+	return new MouseEvent('mouseleave', { relatedTarget } as MouseEventInit);
+};
+
+test('hasRelatedTarget reports true for events that carry a relatedTarget', () => {
+	const button = document.createElement('button');
+	const event = buildEventWithRelatedTarget(button);
+
+	expect(hasRelatedTarget(event)).toBe(true);
+});
+
+test('hasRelatedTarget reports false for events without a relatedTarget property', () => {
+	const event = new Event('focus');
+
+	expect(hasRelatedTarget(event)).toBe(false);
+});
+
+test('isMovingToKudos returns false when relatedTarget is not an HTMLElement', () => {
+	expect(isMovingToKudos(null)).toBe(false);
+});
+
+test('isMovingToKudos returns true when relatedTarget contains a give-kudos iframe inside an atlaskit portal', () => {
+	const portal = document.createElement('div');
+	portal.classList.add('atlaskit-portal');
+	const iframe = document.createElement('iframe');
+	iframe.title = 'give kudos dialog';
+	iframe.src = 'https://give-kudos.example.com';
+	portal.appendChild(iframe);
+	document.body.appendChild(portal);
+
+	expect(isMovingToKudos(portal)).toBe(true);
+
+	document.body.removeChild(portal);
+});
+
+test('isMovingToKudos returns false when the iframe inside the portal is unrelated', () => {
+	const portal = document.createElement('div');
+	portal.classList.add('atlaskit-portal');
+	const iframe = document.createElement('iframe');
+	iframe.title = 'unrelated content';
+	iframe.src = 'https://example.com/other';
+	portal.appendChild(iframe);
+	document.body.appendChild(portal);
+
+	expect(isMovingToKudos(portal)).toBe(false);
+
+	document.body.removeChild(portal);
+});
+
+test('getChildPortalFromParentPopup returns null when no parent popup is provided', () => {
+	const portal = document.createElement('div');
+	portal.classList.add('atlaskit-portal');
+
+	expect(getChildPortalFromParentPopup(portal, null)).toBeNull();
+});
+
+test('getChildPortalFromParentPopup returns the portal when a trigger inside the popup controls a child in that portal', () => {
+	const popup = document.createElement('div');
+	const trigger = document.createElement('button');
+	trigger.setAttribute('aria-controls', 'child-popup');
+	popup.appendChild(trigger);
+
+	const portal = document.createElement('div');
+	portal.classList.add('atlaskit-portal');
+	const child = document.createElement('div');
+	child.id = 'child-popup';
+	portal.appendChild(child);
+	document.body.appendChild(portal);
+
+	expect(getChildPortalFromParentPopup(portal, popup)).toBe(portal);
+
+	document.body.removeChild(portal);
+});
+
+test('getChildPortalFromParentPopup returns null when the related element is not inside an atlaskit portal', () => {
+	const popup = document.createElement('div');
+	const unrelated = document.createElement('button');
+
+	expect(getChildPortalFromParentPopup(unrelated, popup)).toBeNull();
+});