A platform for community discussion. Free, open, simple.
DEV: Add a hover grace period to FloatKit tooltips and menus (#42455)
Sérgio Saquetim843d2a9bd4bb
diff --git a/frontend/discourse/float-kit/components/d-float-body.gts b/frontend/discourse/float-kit/components/d-float-body.gtsindex ceeedfda920..a9c5d4e5ff4 100644--- a/frontend/discourse/float-kit/components/d-float-body.gts+++ b/frontend/discourse/float-kit/components/d-float-body.gts@@ -80,6 +80,49 @@ export default class DFloatBody extends Component<DFloatBodySignature> {};});+ /**+ * Extends the trigger's grace period across the content itself, so hovering onto the+ * float keeps it open and leaving it starts the close. Focus moving within the+ * content is not a departure, so it holds the lock rather than scheduling a close.+ */+ hoverGrace = modifierFn((element: HTMLElement) => {+ const instance = this.args.instance;++ const onPointerEnter = () => instance.cancelHoverClose();+ const onPointerLeave = () => instance.scheduleHoverClose();+ const onFocusIn = () => instance.lockHoverCloseForFocus();+ const onFocusOut = (event: FocusEvent) => {+ const nextFocused = event.relatedTarget;+ if (nextFocused instanceof Node && element.contains(nextFocused)) {+ return;+ }+ instance.unlockHoverCloseForFocus();+ instance.scheduleHoverClose();+ };++ element.addEventListener("pointerenter", onPointerEnter, { passive: true });+ element.addEventListener("pointerleave", onPointerLeave, { passive: true });+ element.addEventListener("focusin", onFocusIn, { passive: true });+ element.addEventListener("focusout", onFocusOut, { passive: true });++ return () => {+ element.removeEventListener("pointerenter", onPointerEnter);+ element.removeEventListener("pointerleave", onPointerLeave);+ element.removeEventListener("focusin", onFocusIn);+ element.removeEventListener("focusout", onFocusOut);+ };+ });++ /**+ * Whether to install the grace-period listeners on the content. Only meaningful while+ * the float is open, and only when a grace period is configured.+ *+ * @returns `true` when the content should participate in the grace period.+ */+ get supportsHoverGrace(): boolean {+ return this.args.instance.expanded && this.options.hoverGracePeriod > 0;+ }+get contentAriaLabelledby(): string | null | undefined {if (this.#hasPresentationalRole) {return;@@ -160,6 +203,7 @@ export default class DFloatBody extends Component<DFloatBodySignature> {(modifier FloatKitCloseOnEscape @instance.close))}}{{(if this.supportsCloseOnScroll (modifier this.closeOnScroll))}}+ {{(if this.supportsHoverGrace (modifier this.hoverGrace))}}style={{this.style}}...attributes>diff --git a/frontend/discourse/float-kit/lib/constants.ts b/frontend/discourse/float-kit/lib/constants.tsindex 6bb8fb81bd1..cb2712cba39 100644--- a/frontend/discourse/float-kit/lib/constants.ts+++ b/frontend/discourse/float-kit/lib/constants.ts@@ -126,6 +126,9 @@ export interface TooltipOptions {/** Whether FloatKit attaches the trigger event listeners itself, rather than the caller driving it through the service API. */listeners: boolean;+ /** How long to keep an interactive float open after the pointer leaves it. */+ hoverGracePeriod: number;+/*** The maximum width of the content: a number in pixels, or any CSS `max-width` value. Pass* `"none"` alongside `matchTriggerWidth` — the two are both applied inline, so a numeric cap@@ -339,6 +342,7 @@ export const TOOLTIP: { options: TooltipOptions; portalOutletId: string } = {inline: null,interactive: false,listeners: false,+ hoverGracePeriod: 0,maxWidth: 350,data: null,offset: 10,@@ -373,6 +377,7 @@ export const MENU: { options: MenuOptions; portalOutletId: string } = {identifier: null,interactive: true,listeners: false,+ hoverGracePeriod: 0,maxWidth: 400,data: null,offset: 10,diff --git a/frontend/discourse/float-kit/lib/d-menu-instance.ts b/frontend/discourse/float-kit/lib/d-menu-instance.tsindex 7cd65f90c7e..d597ecf4440 100644--- a/frontend/discourse/float-kit/lib/d-menu-instance.ts+++ b/frontend/discourse/float-kit/lib/d-menu-instance.ts@@ -86,6 +86,7 @@ export default class DMenuInstance extends FloatKitInstance {@actionasync close(options = { focusTrigger: true }) {+ this.resetHoverCloseState();this.openedByDelayedHover = false;if (isDestroying(getOwner(this)!)) {@@ -140,9 +141,14 @@ export default class DMenuInstance extends FloatKitInstance {@actionasync onPointerLeave(event: PointerEvent) {- if (this.untriggers.includes("hover")) {- await this.onUntrigger(event);+ if (!this.untriggers.includes("hover")) {+ return;+ }+ if (this.hasHoverGracePeriod) {+ this.scheduleHoverClose();+ return;}+ await this.onUntrigger(event);}@actiondiff --git a/frontend/discourse/float-kit/lib/d-tooltip-instance.ts b/frontend/discourse/float-kit/lib/d-tooltip-instance.tsindex 0e8c9950160..8e4be2d385e 100644--- a/frontend/discourse/float-kit/lib/d-tooltip-instance.ts+++ b/frontend/discourse/float-kit/lib/d-tooltip-instance.ts@@ -74,6 +74,7 @@ export default class DTooltipInstance extends FloatKitInstance {@actionasync close() {+ this.resetHoverCloseState();this.openedByDelayedHover = false;await this.tooltip.close(this);@@ -111,9 +112,14 @@ export default class DTooltipInstance extends FloatKitInstance {@actionasync onPointerLeave(event: PointerEvent) {- if (this.untriggers.includes("hover")) {- await this.onUntrigger(event);+ if (!this.untriggers.includes("hover")) {+ return;+ }+ if (this.hasHoverGracePeriod) {+ this.scheduleHoverClose();+ return;}+ await this.onUntrigger(event);}@actiondiff --git a/frontend/discourse/float-kit/lib/float-kit-instance.ts b/frontend/discourse/float-kit/lib/float-kit-instance.tsindex c7f3752b2da..be4287da112 100644--- a/frontend/discourse/float-kit/lib/float-kit-instance.ts+++ b/frontend/discourse/float-kit/lib/float-kit-instance.ts@@ -62,6 +62,12 @@ export default abstract class FloatKitInstance {declare openedByDelayedHover: boolean;+ /** The pending grace-period close, if one is scheduled. */+ #hoverCloseTimer: ReturnType<typeof discourseLater> | null = null;++ /** Whether focus inside the content is currently suppressing the grace-period close. */+ #hoverFocusLocked = false;+/** Whether THIS instance renders in a mobile modal (see {@link resolveRenderInModal}). */get renderInModal(): boolean {return FloatKitInstance.resolveRenderInModal(@@ -82,6 +88,26 @@ export default abstract class FloatKitInstance {/** The element the rendered float body is portalled into. */abstract get portalOutletElement(): HTMLElement | null;+ /**+ * How long, in milliseconds, the float stays open after the pointer leaves it.+ *+ * @returns The configured grace period, or `0` when the feature is off.+ */+ get hoverGracePeriod(): number {+ return this.options?.hoverGracePeriod ?? 0;+ }++ /**+ * Whether a grace period is configured. When it is, the trigger keeps its+ * `pointerleave` listener even on an interactive float, because the delayed close+ * replaces the immediate one rather than being skipped.+ *+ * @returns `true` when the grace period is greater than zero.+ */+ get hasHoverGracePeriod(): boolean {+ return this.hoverGracePeriod > 0;+ }+abstract onClick(event: MouseEvent): Promise<void>;abstract onPointerMove(event: PointerEvent): Promise<void>;abstract onPointerLeave(event: PointerEvent): Promise<void>;@@ -97,9 +123,69 @@ export default abstract class FloatKitInstance {// refocus its trigger); the base close has no trigger to refocus, so it ignores it.// eslint-disable-next-line @typescript-eslint/no-unused-varsasync close(options?: { focusTrigger?: boolean }) {+ this.resetHoverCloseState();await this.options.onClose?.();}+ /** Drops any pending grace-period close, so the float stays open. */+ @action+ cancelHoverClose() {+ cancel(this.#hoverCloseTimer);+ this.#hoverCloseTimer = null;+ }++ /**+ * Clears both the pending close and the focus lock. Called whenever the float+ * closes, so a lock taken while focus was inside the content cannot outlive it and+ * suppress a later close.+ */+ resetHoverCloseState() {+ this.cancelHoverClose();+ this.#hoverFocusLocked = false;+ }++ /**+ * Starts the grace period after which the float closes. Re-entering the trigger or+ * the content cancels it, which is what lets the pointer cross the gap between them+ * without the float closing underneath it.+ *+ * Does nothing when no grace period is configured, or while focus is held inside the+ * content: a keyboard user is not "hovering away" and must not be closed out.+ */+ @action+ scheduleHoverClose() {+ if (!this.hasHoverGracePeriod || this.#hoverFocusLocked) {+ return;+ }++ this.cancelHoverClose();+ this.#hoverCloseTimer = discourseLater(() => {+ this.#hoverCloseTimer = null;+ if (!this.#hoverFocusLocked) {+ this.close();+ }+ }, this.hoverGracePeriod);+ }++ /** Cancels a pending close when the pointer returns to the trigger. */+ @action+ onPointerEnterTrigger() {+ this.cancelHoverClose();+ }++ /** Holds the float open while focus is inside its content, regardless of the pointer. */+ @action+ lockHoverCloseForFocus() {+ this.#hoverFocusLocked = true;+ this.cancelHoverClose();+ }++ /** Releases the focus lock, letting the pointer govern closing again. */+ @action+ unlockHoverCloseForFocus() {+ this.#hoverFocusLocked = false;+ }+@actionasync onFocus(event: FocusEvent) {await this.onTrigger(event);@@ -164,6 +250,7 @@ export default abstract class FloatKitInstance {@actiononDelayedHoverEnter(event: PointerEvent) {cancel(this.delayedHoverTimeout);+ this.cancelHoverClose();this.delayedHoverTimeout = discourseLater(() => {if (this.expanded) {return;@@ -176,6 +263,9 @@ export default abstract class FloatKitInstance {@actiononDelayedHoverLeave() {cancel(this.delayedHoverTimeout);+ if (this.expanded && this.hasHoverGracePeriod) {+ this.scheduleHoverClose();+ }}@bind@@ -193,6 +283,8 @@ export default abstract class FloatKitInstance {}tearDownListeners() {+ this.resetHoverCloseState();+const element = this.triggerElement;if (element) {element.removeEventListener("pointerdown", this.trapPointerDown);@@ -219,9 +311,15 @@ export default abstract class FloatKitInstance {break;case "hover":element.removeEventListener("pointermove", this.onPointerMove);- if (!this.options.interactive) {+ if (this.hasHoverGracePeriod || !this.options.interactive) {element.removeEventListener("pointerleave", this.onPointerLeave);}+ if (this.hasHoverGracePeriod) {+ element.removeEventListener(+ "pointerenter",+ this.onPointerEnterTrigger+ );+ }break;case "delayed-hover":@@ -285,11 +383,18 @@ export default abstract class FloatKitInstance {element.addEventListener("pointermove", this.onPointerMove, {passive: true,});- if (!this.options.interactive) {+ if (this.hasHoverGracePeriod || !this.options.interactive) {element.addEventListener("pointerleave", this.onPointerLeave, {passive: true,});}+ if (this.hasHoverGracePeriod) {+ element.addEventListener(+ "pointerenter",+ this.onPointerEnterTrigger,+ { passive: true }+ );+ }break;case "delayed-hover":diff --git a/frontend/discourse/tests/integration/components/float-kit/d-menu-test.gjs b/frontend/discourse/tests/integration/components/float-kit/d-menu-test.gjsindex 0f63852fbec..9e26daf7060 100644--- a/frontend/discourse/tests/integration/components/float-kit/d-menu-test.gjs+++ b/frontend/discourse/tests/integration/components/float-kit/d-menu-test.gjs@@ -1131,4 +1131,71 @@ module("Integration | Component | FloatKit | DMenu", function (hooks) {minWidth: "200px",});});++ test("@hoverGracePeriod keeps the menu open while the pointer crosses to the content", async function (assert) {+ await render(+ <template>+ <DMenu+ @inline={{true}}+ @label="label"+ @triggers={{array "hover"}}+ @untriggers={{array "hover"}}+ @hoverGracePeriod={{150}}+ @content="content"+ />+ </template>+ );++ await triggerEvent(".fk-d-menu__trigger", "pointermove");+ assert.dom(".fk-d-menu").exists();++ const trigger = document.querySelector(".fk-d-menu__trigger");+ const content = document.querySelector(".fk-d-menu");+ trigger.dispatchEvent(new PointerEvent("pointerleave"));+ content.dispatchEvent(new PointerEvent("pointerenter"));+ await settled();++ assert.dom(".fk-d-menu").exists();+ });++ test("@hoverGracePeriod closes the menu after the grace period when the pointer leaves entirely", async function (assert) {+ await render(+ <template>+ <DMenu+ @inline={{true}}+ @label="label"+ @triggers={{array "hover"}}+ @untriggers={{array "hover"}}+ @hoverGracePeriod={{150}}+ @content="content"+ />+ </template>+ );++ await triggerEvent(".fk-d-menu__trigger", "pointermove");+ await triggerEvent(".fk-d-menu__trigger", "pointerleave");++ assert.dom(".fk-d-menu").doesNotExist();+ });++ test("default hoverGracePeriod (0) does not install hover-close on interactive menus", async function (assert) {+ await render(+ <template>+ <DMenu+ @inline={{true}}+ @label="label"+ @triggers={{array "hover"}}+ @untriggers={{array "hover"}}+ @content="content"+ />+ </template>+ );++ await triggerEvent(".fk-d-menu__trigger", "pointermove");+ await triggerEvent(".fk-d-menu__trigger", "pointerleave");++ assert+ .dom(".fk-d-menu")+ .exists("interactive menu stays open without grace period");+ });});diff --git a/frontend/discourse/tests/integration/components/float-kit/d-tooltip-test.gjs b/frontend/discourse/tests/integration/components/float-kit/d-tooltip-test.gjsindex 26a3a152466..11dc07fbdb7 100644--- a/frontend/discourse/tests/integration/components/float-kit/d-tooltip-test.gjs+++ b/frontend/discourse/tests/integration/components/float-kit/d-tooltip-test.gjs@@ -5,6 +5,7 @@ import didInsert from "@ember/render-modifiers/modifiers/did-insert";import {click,render,+ settled,triggerEvent,triggerKeyEvent,} from "@ember/test-helpers";@@ -440,6 +441,150 @@ module("Integration | Component | FloatKit | DTooltip", function (hooks) {}});+ test("@hoverGracePeriod keeps the tooltip open while the pointer crosses to the content", async function (assert) {+ await render(+ <template>+ <DTooltip+ @inline={{true}}+ @label="label"+ @hoverGracePeriod={{150}}+ ><:content>content</:content></DTooltip>+ </template>+ );++ await hover();+ assert.dom(".fk-d-tooltip__content").exists();++ const trigger = document.querySelector(".fk-d-tooltip__trigger");+ const content = document.querySelector(".fk-d-tooltip__content");+ // The two events must dispatch synchronously so the close timer+ // started by pointerleave can be cancelled by pointerenter on the+ // content before settled() advances the runloop.+ trigger.dispatchEvent(new PointerEvent("pointerleave"));+ content.dispatchEvent(new PointerEvent("pointerenter"));+ await settled();++ assert.dom(".fk-d-tooltip__content").exists();+ });++ test("@hoverGracePeriod closes after the grace period when the pointer leaves entirely", async function (assert) {+ await render(+ <template>+ <DTooltip @inline={{true}} @label="label" @hoverGracePeriod={{150}} />+ </template>+ );++ await hover();+ await leave();++ assert.dom(".fk-d-tooltip__content").doesNotExist();+ });++ test("@hoverGracePeriod cancels the pending close when re-entering the trigger", async function (assert) {+ await render(+ <template>+ <DTooltip+ @inline={{true}}+ @label="label"+ @hoverGracePeriod={{150}}+ ><:content>content</:content></DTooltip>+ </template>+ );++ await hover();++ const trigger = document.querySelector(".fk-d-tooltip__trigger");+ trigger.dispatchEvent(new PointerEvent("pointerleave"));+ trigger.dispatchEvent(new PointerEvent("pointerenter"));+ await settled();++ assert.dom(".fk-d-tooltip__content").exists();+ });++ test("@hoverGracePeriod closes after the grace period when the pointer leaves the content", async function (assert) {+ await render(+ <template>+ <DTooltip+ @inline={{true}}+ @label="label"+ @hoverGracePeriod={{150}}+ ><:content>content</:content></DTooltip>+ </template>+ );++ await hover();+ await triggerEvent(".fk-d-tooltip__content", "pointerleave");++ assert.dom(".fk-d-tooltip__content").doesNotExist();+ });++ test("@hoverGracePeriod keeps the tooltip open while focus is inside the content", async function (assert) {+ await render(+ <template>+ <DTooltip @inline={{true}} @label="label" @hoverGracePeriod={{150}}>+ <:content>+ <button type="button" class="focusable">click</button>+ </:content>+ </DTooltip>+ </template>+ );++ await hover();+ await triggerEvent(".focusable", "focusin");+ await triggerEvent(".fk-d-tooltip__trigger", "pointerleave");++ assert+ .dom(".fk-d-tooltip__content")+ .exists("stays open while focus is inside");++ await triggerEvent(".focusable", "focusout");++ assert+ .dom(".fk-d-tooltip__content")+ .doesNotExist("closes after focus leaves and grace elapses");+ });++ test("@hoverGracePeriod releases its focus lock when the tooltip closes", async function (assert) {+ this.api = null;+ this.onRegisterApi = (api) => (this.api = api);++ await render(+ <template>+ <DTooltip+ @inline={{true}}+ @label="label"+ @hoverGracePeriod={{10}}+ @onRegisterApi={{this.onRegisterApi}}+ >+ <:content>+ <button type="button" class="focusable">click</button>+ </:content>+ </DTooltip>+ </template>+ );++ await hover();+ await triggerEvent(".focusable", "focusin");+ await this.api.close();++ await hover();+ await leave();++ assert+ .dom(".fk-d-tooltip__content")+ .doesNotExist("a reopened tooltip can close after its trigger is left");+ });++ test("default hoverGracePeriod (0) keeps immediate close behavior", async function (assert) {+ await render(+ <template><DTooltip @inline={{true}} @label="label" /></template>+ );+ await hover();+ assert.dom(".fk-d-tooltip__content").exists();+ await leave();+ assert.dom(".fk-d-tooltip__content").doesNotExist();+ });+test("@portalOutletElement", async function (assert) {this.set("portalOutletElement", null);this.setPortalOutletElement = (element) => {