feat(tooltip, popover2): Share the overlay focus-return suppression:

* Extract the detection into `ɵintentionalFocus$`, driven by the CDK `FocusMonitor`.
* Add `focusSilently` for an application moving the focus itself.
* Require both a `program` origin and a return from a foreign overlay pane.
* Restore the popover2 trigger focus through a `program` origin.
* Drop the popover2 `#skipNextFocus` flag.
* Drop the tooltip `(focus)` and `(focusout)` host listeners.
* Cover both components with focus-return story tests.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: fbasmaison-lucca

packages/ng/popover2/content/popover-content/popover-content.component.ts

@@ -1,3 +1,4 @@
+import { FocusMonitor } from '@angular/cdk/a11y';
 import { CdkObserveContent } from '@angular/cdk/observers';
 import { AfterViewInit, ChangeDetectionStrategy, Component, DestroyRef, ElementRef, inject, Injector, input, OnDestroy, ViewEncapsulation } from '@angular/core';
 import { ButtonComponent } from '@lucca-front/ng/button';
@@ -35,6 +36,8 @@ export class PopoverContentComponent implements AfterViewInit, OnDestroy {
 
 	content = this.config.content;
 
+	#focusMonitor = inject(FocusMonitor);
+
 	#focusManager = new PopoverFocusTrap(this.#elementRef.nativeElement, this.config.triggerElement, inject(Injector));
 
 	readonly closed$ = new Subject<void>();
@@ -75,8 +78,9 @@ export class PopoverContentComponent implements AfterViewInit, OnDestroy {
 
 	close(): void {
 		if (!this.config.disableInitialTriggerFocus) {
-			// Focus initial trigger element
-			this.config.triggerElement.focus();
+			// - The `program` origin tells this handover apart from the user reaching the trigger.
+			// - It reopens neither the popover nor a tooltip the trigger carries.
+			this.#focusMonitor.focusVia(this.config.triggerElement, 'program');
 		}
 		// Tell the directive we're closed now
 		this.#destroyEvents();

packages/ng/popover2/popover.directive.ts

@@ -21,6 +21,7 @@ import {
 } from '@angular/core';
 import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
 import { getPushPanelViewportMargin, intlInputOptions, isNotNil, luBooleanAttribute, luNumberAttribute } from '@lucca-front/ng/core';
+import { ɵintentionalFocus$ } from '@lucca/prisme/core';
 import { combineLatest, debounce, filter, map, merge, Subject, switchMap, take, timer } from 'rxjs';
 import { PopoverContentComponent } from './content/popover-content/popover-content.component';
 import { POPOVER_CONFIG, PopoverConfig } from './popover-tokens';
@@ -75,7 +76,6 @@ const defaultPositionPairs: Record<PopoverPosition, ConnectionPositionPair> = {
 		'[attr.aria-controls]': 'ariaControls',
 		'(click)': 'onMouseClick()',
 		'(mouseleave)': 'onMouseLeave()',
-		'(focus)': 'onFocus()',
 		'(mouseenter)': 'onMouseEnter()',
 		'(keydown.Tab)': 'focusBackToContent($event)',
 		'(keydown.Shift.Tab)': 'focusOutBefore()',
@@ -151,7 +151,6 @@ export class PopoverDirective implements OnDestroy {
 
 	#listenToMouseLeave = false;
 	#listenToMouseEnter = true;
-	#skipNextFocus = false;
 
 	#overlayRef: OverlayRef;
 
@@ -169,6 +168,10 @@ export class PopoverDirective implements OnDestroy {
 	protected additionalProviders: Provider[] = [];
 
 	constructor() {
+		ɵintentionalFocus$(this.elementRef)
+			.pipe(takeUntilDestroyed())
+			.subscribe(() => this.onFocus());
+
 		combineLatest([toObservable(this.luPopoverOpenDelay), toObservable(this.luPopoverCloseDelay), toObservable(this.luPopoverTrigger)])
 			.pipe(
 				filter(([, , trigger]) => {
@@ -213,13 +216,8 @@ export class PopoverDirective implements OnDestroy {
 
 	onFocus() {
 		if (this.luPopoverTrigger().includes('focus')) {
-			if (this.#skipNextFocus) {
-				this.#skipNextFocus = false;
-			} else {
-				this.open$.next('focus');
-				this.#listenToMouseLeave = true;
-				this.#skipNextFocus = true;
-			}
+			this.open$.next('focus');
+			this.#listenToMouseLeave = true;
 		}
 	}
 
@@ -325,7 +323,6 @@ export class PopoverDirective implements OnDestroy {
 			this.#componentRef.mouseEnter$.pipe(takeUntilDestroyed(this.#componentRef.destroyRef), takeUntilDestroyed(this.#destroyRef)).subscribe(() => this.open$.next('hover'));
 			this.#componentRef.closed$.pipe(take(1), takeUntilDestroyed(this.#componentRef.destroyRef), takeUntilDestroyed(this.#destroyRef)).subscribe(() => {
 				this.opened.set(false);
-				this.#skipNextFocus = false;
 				this.luPopoverClosed.emit();
 				this.#listenToMouseLeave = false;
 				if (this.#screenReaderDescription) {

packages/prisme/core/overlay/index.ts

@@ -1 +1,2 @@
+export * from './intentional-focus';
 export * from './push-panel';

packages/prisme/core/overlay/intentional-focus.ts

@@ -0,0 +1,71 @@
+import { FocusMonitor, FocusOrigin } from '@angular/cdk/a11y';
+import { DestroyRef, ElementRef, inject } from '@angular/core';
+import { Observable } from 'rxjs';
+import { filter } from 'rxjs/operators';
+import { isNotNil } from '../misc';
+
+function paneOf(element: Element): Element | null {
+	// A trigger inside an overlay keeps its own behaviour when the focus moves within that same overlay.
+	return element.closest('.cdk-overlay-pane');
+}
+
+const silentRequests = new WeakSet<HTMLElement>();
+
+/**
+ * Focuses `element` the way a closing overlay does.
+ *
+ * - Whatever a user focus reveals — a tooltip, a popover panel — stays hidden.
+ * - Use it when an application moves the focus itself and wants none of that.
+ * - Keep `element.focus()` when it wants that reveal.
+ * - To reveal from an actual overlay handover, focus through `inject(FocusMonitor).focusVia(element, 'keyboard')`.
+ */
+export function focusSilently(element: HTMLElement): void {
+	if (element.ownerDocument.activeElement !== element) {
+		silentRequests.add(element);
+	}
+
+	element.focus();
+}
+
+/**
+ * Emits every focus arrival on `host` that was aimed at `host` itself.
+ *
+ * - Skips the handover an overlay performs when it hands the focus back to its trigger on close.
+ * - Skips the calls to `focusSilently`.
+ * - Pointer, touch and keyboard arrivals always emit.
+ * - An application calling `focus()` on the trigger emits too: it stays a request to focus it.
+ * - Must be called in an injection context.
+ * - Monitoring stops when that context is destroyed.
+ */
+export function ɵintentionalFocus$(host: ElementRef<HTMLElement>): Observable<FocusOrigin> {
+	const element = host.nativeElement;
+	const focusMonitor = inject(FocusMonitor);
+
+	// Some overlays dispose their pane before handing the focus back, leaving nothing to inspect on the return leg.
+	let leftToPane: Element | null = null;
+	const trackDeparture = ({ relatedTarget }: FocusEvent) => {
+		leftToPane = relatedTarget instanceof Element ? paneOf(relatedTarget) : null;
+	};
+	element.addEventListener('focusout', trackDeparture);
+
+	inject(DestroyRef).onDestroy(() => {
+		element.removeEventListener('focusout', trackDeparture);
+		focusMonitor.stopMonitoring(host);
+	});
+
+	return focusMonitor.monitor(host).pipe(
+		// `null` is the blur, which every trigger already handles on its own.
+		filter(isNotNil),
+		filter((origin) => {
+			const cameBackFromPane = leftToPane;
+			leftToPane = null;
+
+			if (silentRequests.delete(element)) {
+				return false;
+			}
+
+			// A handover comes back from the pane of another overlay, where an application's own `focus()` does not.
+			return origin !== 'program' || cameBackFromPane === null || cameBackFromPane === paneOf(element);
+		}),
+	);
+}

packages/prisme/tooltip/trigger/tooltip-trigger.directive.ts

@@ -30,7 +30,7 @@ import {
 } from '@angular/core';
 import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
 import { SafeHtml } from '@angular/platform-browser';
-import { getPushPanelViewportMargin, isNil, isNotNil, ɵeffectWithDeps } from '@lucca/prisme/core';
+import { getPushPanelViewportMargin, isNil, isNotNil, ɵeffectWithDeps, ɵintentionalFocus$ } from '@lucca/prisme/core';
 import { startWith, timer } from 'rxjs';
 import { debounce, filter, map, tap } from 'rxjs/operators';
 import { LuTooltipPanelComponent } from '../panel';
@@ -51,8 +51,6 @@ let nextId = 0;
 		'[attr.id]': 'id()',
 		'(mouseenter)': 'onMouseEnter()',
 		'(mouseleave)': 'onMouseLeave()',
-		'(focus)': 'onFocus()',
-		'(focusout)': 'onFocusOut($event)',
 		'(blur)': 'onBlur()',
 		'(keydown.escape)': 'onEscape($event)',
 	},
@@ -156,12 +154,13 @@ export class LuTooltipTriggerDirective implements OnDestroy {
 
 	#effectRef?: EffectRef;
 
-	// pane the focus moved into when it last left this trigger, or null
-	#focusLeftToPane: Element | null = null;
-
 	constructor() {
 		this.#destroyRef.onDestroy(() => (this.#destroyed = true));
 
+		ɵintentionalFocus$(this.#host)
+			.pipe(takeUntilDestroyed())
+			.subscribe(() => this.onFocus());
+
 		// Action debounce pipeline — kept as Observable since signals can't debounce
 		toObservable(this.#realAction)
 			.pipe(
@@ -304,36 +303,11 @@ export class LuTooltipTriggerDirective implements OnDestroy {
 	}
 
 	onFocus() {
-		const leftToPane = this.#focusLeftToPane;
-		this.#focusLeftToPane = null;
-
-		// A closing overlay hands the focus back to its trigger.
-		// That is not the user reaching the trigger, so the tooltip stays closed.
-		if (this.#isForeignPane(leftToPane)) {
-			return;
-		}
-
 		if (this.#host.nativeElement.getAttribute('aria-expanded') !== 'true') {
 			this.#action.set('open');
 		}
 	}
 
-	onFocusOut(event: FocusEvent) {
-		// Captured on the way out.
-		// Some overlays dispose their pane before handing the focus back, leaving nothing to inspect.
-		this.#focusLeftToPane = event.relatedTarget instanceof Element ? this.#paneOf(event.relatedTarget) : null;
-	}
-
-	#isForeignPane(pane: Element | null): boolean {
-		// Panes, not the whole container.
-		// A trigger inside an overlay keeps its tooltip when the focus moves within that same overlay.
-		return isNotNil(pane) && pane !== this.#paneOf(this.#host.nativeElement);
-	}
-
-	#paneOf(element: Element): Element | null {
-		return element.closest('.cdk-overlay-pane');
-	}
-
 	onBlur() {
 		this.#action.set('close');
 	}

stories/documentation/overlays/popover2/popover2-focus-return.stories.ts

@@ -0,0 +1,83 @@
+import { ButtonComponent } from '@lucca-front/ng/button';
+import { configureLuPopover, PopoverDirective } from '@lucca-front/ng/popover2';
+import { applicationConfig, Meta, moduleMetadata, StoryObj } from '@storybook/angular-vite';
+import { waitForAngular } from '@/helpers/test';
+import { expect, screen, userEvent, waitFor, within } from 'storybook/test';
+import { createTestStory } from '../../../helpers/stories';
+
+export default {
+	title: 'Documentation/Overlays/Popover2/Retour de focus depuis le panneau',
+	component: PopoverDirective,
+	decorators: [
+		applicationConfig({
+			providers: [configureLuPopover()],
+		}),
+		moduleMetadata({
+			imports: [ButtonComponent, PopoverDirective],
+		}),
+	],
+} as Meta;
+
+export const FocusReturn: StoryObj<PopoverDirective> = {
+	render: () => ({
+		template: `<p>Le panneau s’ouvre au focus. À sa fermeture, le focus revient sur le déclencheur sans le réouvrir.</p>
+
+<button type="button" luButton="text">Point de départ</button>
+
+<button
+	type="button"
+	luButton
+	[luPopover2]="contentRef"
+	luPopoverTrigger="hover+focus"
+	[luPopoverOpenDelay]="0"
+	[luPopoverCloseDelay]="0"
+>Déclencheur</button>
+
+<ng-template #contentRef>
+	<p>Contenu du panneau.</p>
+</ng-template>
+`,
+	}),
+};
+
+export const FocusReturnTEST = createTestStory(FocusReturn, async ({ canvasElement, step }) => {
+	await waitForAngular();
+
+	const canvas = within(canvasElement);
+	const start = () => canvas.getByRole('button', { name: /Point de départ/ });
+	const trigger = () => canvas.getByRole('button', { name: /Déclencheur/ });
+	const panel = () => screen.queryByText(/Contenu du panneau/);
+
+	const tabToTrigger = async () => {
+		await userEvent.click(start());
+		await userEvent.tab();
+		await expect(trigger()).toHaveFocus();
+	};
+
+	await step('La navigation au clavier ouvre le panneau', async () => {
+		await tabToTrigger();
+		await waitFor(() => expect(panel()).toBeVisible());
+	});
+
+	await step('Le retour du focus après une fermeture laisse le panneau fermé', async () => {
+		await userEvent.tab();
+		await userEvent.click(await screen.findByRole('button', { name: /Fermer/ }));
+		await waitForAngular();
+		await expect(trigger()).toHaveFocus();
+		await new Promise((resolve) => setTimeout(resolve, 400));
+		await expect(panel()).toBeNull();
+	});
+
+	await step('Un focus programmatique, hors retour d’overlay, ouvre le panneau', async () => {
+		start().focus();
+		trigger().focus();
+		await waitFor(() => expect(panel()).toBeVisible());
+		await userEvent.click(await screen.findByRole('button', { name: /Fermer/ }));
+		await waitForAngular();
+	});
+
+	await step('Une nouvelle navigation au clavier réouvre le panneau', async () => {
+		await tabToTrigger();
+		await waitFor(() => expect(panel()).toBeVisible());
+	});
+});