Skip to content

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.gts
index 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.ts
index 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.ts
index 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 {
@action
async close(options = { focusTrigger: true }) {
+ this.resetHoverCloseState();
this.openedByDelayedHover = false;
if (isDestroying(getOwner(this)!)) {
@@ -140,9 +141,14 @@ export default class DMenuInstance extends FloatKitInstance {
@action
async 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);
}
@action
diff --git a/frontend/discourse/float-kit/lib/d-tooltip-instance.ts b/frontend/discourse/float-kit/lib/d-tooltip-instance.ts
index 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 {
@action
async close() {
+ this.resetHoverCloseState();
this.openedByDelayedHover = false;
await this.tooltip.close(this);
@@ -111,9 +112,14 @@ export default class DTooltipInstance extends FloatKitInstance {
@action
async 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);
}
@action
diff --git a/frontend/discourse/float-kit/lib/float-kit-instance.ts b/frontend/discourse/float-kit/lib/float-kit-instance.ts
index 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-vars
async 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;
+ }
+
@action
async onFocus(event: FocusEvent) {
await this.onTrigger(event);
@@ -164,6 +250,7 @@ export default abstract class FloatKitInstance {
@action
onDelayedHoverEnter(event: PointerEvent) {
cancel(this.delayedHoverTimeout);
+ this.cancelHoverClose();
this.delayedHoverTimeout = discourseLater(() => {
if (this.expanded) {
return;
@@ -176,6 +263,9 @@ export default abstract class FloatKitInstance {
@action
onDelayedHoverLeave() {
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.gjs
index 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.gjs
index 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) => {