fix(toast): prevent toasts from collapsing when pointer is hovering (#2771)

* fix(toast): prevent toasts from collapsing when pointer is hovering

When dismissing a toast by clicking the close button while the mouse
is hovering over the toast group, the toasts would immediately collapse
even though the cursor was still within the group. This was caused by
focus restoration triggering browser hover state recalculation.

This fix adds pointer tracking to only restore focus and collapse toasts
when the pointer has actually left the toast group, maintaining the
expected hover behavior.

Changes:
- Add isPointerWithin ref to track mouse position over toast group
- Update REGION.BLUR handler to check pointer position before collapsing
- Add guards: isPointerOut, isOverlappingAndPointerOut
- Add actions: setPointerWithin, clearPointerWithin, clearFocusWithin
- Only restore focus when pointer has left the group

Fixes chakra-ui/ark#3628

* chore: add changeset

* chore: reformat changeset

* fix: toast issue in firefox

* chore: cleanup

* refactor: setTimeout -> raf

* refactor: use animation frame class

---------

Co-authored-by: Segun Adebayo <[email protected]>

Author: alii13

.changeset/neat-pigs-dance.md

@@ -0,0 +1,6 @@
+---
+"@zag-js/toast": patch
+---
+
+Fix issue where toasts collapse immediately when dismissing while hovering, by tracking pointer state and temporarily
+ignoring spurious mouse events during DOM mutations using requestAnimationFrame.

packages/machines/toast/src/toast-group.connect.ts

@@ -39,10 +39,16 @@ export function groupConnect<T extends PropTypes, O = any>(
         "aria-live": "polite",
         role: "region",
         style: getGroupPlacementStyle(service, placement),
+        onMouseEnter() {
+          if (refs.get("ignoreMouseTimer").isActive()) return
+          send({ type: "REGION.POINTER_ENTER", placement })
+        },
         onMouseMove() {
+          if (refs.get("ignoreMouseTimer").isActive()) return
           send({ type: "REGION.POINTER_ENTER", placement })
         },
         onMouseLeave() {
+          if (refs.get("ignoreMouseTimer").isActive()) return
           send({ type: "REGION.POINTER_LEAVE", placement })
         },
         onFocus(event) {

packages/machines/toast/src/toast-group.machine.ts

@@ -1,11 +1,14 @@
-import { createMachine } from "@zag-js/core"
+import { setup } from "@zag-js/core"
 import { trackDismissableBranch } from "@zag-js/dismissable"
-import { addDomEvent } from "@zag-js/dom-query"
+import { addDomEvent, AnimationFrame } from "@zag-js/dom-query"
 import { uuid } from "@zag-js/utils"
 import * as dom from "./toast.dom"
 import type { ToastGroupSchema } from "./toast.types"
 
-export const groupMachine = createMachine<ToastGroupSchema>({
+const { guards, createMachine } = setup<ToastGroupSchema>()
+const { and } = guards
+
+export const groupMachine = createMachine({
   props({ props }) {
     return {
       dir: "ltr",
@@ -23,6 +26,8 @@ export const groupMachine = createMachine<ToastGroupSchema>({
     return {
       lastFocusedEl: null,
       isFocusWithin: false,
+      isPointerWithin: false,
+      ignoreMouseTimer: AnimationFrame.create(),
       dismissableCleanup: undefined,
     }
   },
@@ -57,25 +62,29 @@ export const groupMachine = createMachine<ToastGroupSchema>({
     })
   },
 
-  exit: ["clearDismissableBranch", "clearLastFocusedEl"],
+  exit: ["clearDismissableBranch", "clearLastFocusedEl", "clearMouseEventTimer"],
 
   on: {
     "DOC.HOTKEY": {
       actions: ["focusRegionEl"],
     },
     "REGION.BLUR": [
       {
-        guard: "isOverlapping",
+        guard: and("isOverlapping", "isPointerOut"),
         target: "overlap",
-        actions: ["collapseToasts", "resumeToasts", "restoreLastFocusedEl"],
+        actions: ["collapseToasts", "resumeToasts", "restoreFocusIfPointerOut"],
       },
       {
+        guard: "isPointerOut",
         target: "stack",
-        actions: ["resumeToasts", "restoreLastFocusedEl"],
+        actions: ["resumeToasts", "restoreFocusIfPointerOut"],
+      },
+      {
+        actions: ["clearFocusWithin"],
       },
     ],
     "TOAST.REMOVE": {
-      actions: ["removeToast", "removeHeight"],
+      actions: ["removeToast", "removeHeight", "ignoreMouseEventsTemporarily"],
     },
     "TOAST.PAUSE": {
       actions: ["pauseToasts"],
@@ -89,10 +98,10 @@ export const groupMachine = createMachine<ToastGroupSchema>({
           {
             guard: "isOverlapping",
             target: "overlap",
-            actions: ["resumeToasts", "collapseToasts"],
+            actions: ["clearPointerWithin", "resumeToasts", "collapseToasts"],
           },
           {
-            actions: ["resumeToasts"],
+            actions: ["clearPointerWithin", "resumeToasts"],
           },
         ],
         "REGION.OVERLAP": {
@@ -103,7 +112,7 @@ export const groupMachine = createMachine<ToastGroupSchema>({
           actions: ["setLastFocusedEl", "pauseToasts"],
         },
         "REGION.POINTER_ENTER": {
-          actions: ["pauseToasts"],
+          actions: ["setPointerWithin", "pauseToasts"],
         },
       },
     },
@@ -116,7 +125,7 @@ export const groupMachine = createMachine<ToastGroupSchema>({
         },
         "REGION.POINTER_ENTER": {
           target: "stack",
-          actions: ["pauseToasts", "expandToasts"],
+          actions: ["setPointerWithin", "pauseToasts", "expandToasts"],
         },
         "REGION.FOCUS": {
           target: "stack",
@@ -129,6 +138,7 @@ export const groupMachine = createMachine<ToastGroupSchema>({
   implementations: {
     guards: {
       isOverlapping: ({ computed }) => computed("overlap"),
+      isPointerOut: ({ refs }) => !refs.get("isPointerWithin"),
     },
 
     effects: {
@@ -227,18 +237,37 @@ export const groupMachine = createMachine<ToastGroupSchema>({
         refs.set("isFocusWithin", true)
         refs.set("lastFocusedEl", event.target)
       },
-      restoreLastFocusedEl({ refs }) {
-        if (!refs.get("lastFocusedEl")) return
+      restoreFocusIfPointerOut({ refs }) {
+        if (!refs.get("lastFocusedEl") || refs.get("isPointerWithin")) return
         refs.get("lastFocusedEl")?.focus({ preventScroll: true })
         refs.set("lastFocusedEl", null)
         refs.set("isFocusWithin", false)
       },
+      setPointerWithin({ refs }) {
+        refs.set("isPointerWithin", true)
+      },
+      clearPointerWithin({ refs }) {
+        refs.set("isPointerWithin", false)
+        if (refs.get("lastFocusedEl") && !refs.get("isFocusWithin")) {
+          refs.get("lastFocusedEl")?.focus({ preventScroll: true })
+          refs.set("lastFocusedEl", null)
+        }
+      },
+      clearFocusWithin({ refs }) {
+        refs.set("isFocusWithin", false)
+      },
       clearLastFocusedEl({ refs }) {
         if (!refs.get("lastFocusedEl")) return
         refs.get("lastFocusedEl")?.focus({ preventScroll: true })
         refs.set("lastFocusedEl", null)
         refs.set("isFocusWithin", false)
       },
+      ignoreMouseEventsTemporarily({ refs }) {
+        refs.get("ignoreMouseTimer").request()
+      },
+      clearMouseEventTimer({ refs }) {
+        refs.get("ignoreMouseTimer").cancel()
+      },
     },
   },
 })

packages/machines/toast/src/toast.types.ts

@@ -1,5 +1,6 @@
 import type { CommonProperties, Direction, DirectionProperty, PropTypes, Required, RequiredBy } from "@zag-js/types"
 import type { EventObject, Machine, Service } from "@zag-js/core"
+import type { AnimationFrame } from "@zag-js/dom-query"
 
 /* -----------------------------------------------------------------------------
  * Base types
@@ -246,6 +247,8 @@ export type ToastGroupSchema = {
     dismissableCleanup?: VoidFunction | undefined
     lastFocusedEl: HTMLElement | null
     isFocusWithin: boolean
+    isPointerWithin: boolean
+    ignoreMouseTimer: AnimationFrame
   }
   guard: string
   effect: string

packages/utilities/dom-query/src/raf.ts

@@ -1,3 +1,43 @@
+export class AnimationFrame {
+  static create() {
+    return new AnimationFrame()
+  }
+
+  private id: number | null = null
+  private fn_cleanup: VoidFunction | undefined | void
+
+  request(fn?: VoidFunction | (() => VoidFunction)) {
+    this.cancel()
+    this.id = globalThis.requestAnimationFrame(() => {
+      this.id = null
+      this.fn_cleanup = fn?.()
+    })
+  }
+
+  cancel() {
+    if (this.id !== null) {
+      globalThis.cancelAnimationFrame(this.id)
+      this.id = null
+    }
+    this.fn_cleanup?.()
+    this.fn_cleanup = undefined
+  }
+
+  isActive() {
+    return this.id !== null
+  }
+
+  cleanup = () => {
+    this.cancel()
+  }
+}
+
+export function raf(fn: VoidFunction | (() => VoidFunction)) {
+  const frame = AnimationFrame.create()
+  frame.request(fn)
+  return frame.cleanup
+}
+
 export function nextTick(fn: VoidFunction) {
   const set = new Set<VoidFunction>()
   function raf(fn: VoidFunction) {
@@ -10,17 +50,6 @@ export function nextTick(fn: VoidFunction) {
   }
 }
 
-export function raf(fn: VoidFunction | (() => VoidFunction)) {
-  let cleanup: VoidFunction | undefined | void
-  const id = globalThis.requestAnimationFrame(() => {
-    cleanup = fn()
-  })
-  return () => {
-    globalThis.cancelAnimationFrame(id)
-    cleanup?.()
-  }
-}
-
 export function queueBeforeEvent(el: EventTarget, type: string, cb: () => void) {
   const cancelTimer = raf(() => {
     el.removeEventListener(type, exec, true)