feat(VAlert): add duration prop to auto-dismiss alerts

Add a `duration` prop that automatically dismisses the alert after the
given time in milliseconds. A value of `0` (default) preserves the
current behavior and never auto-dismisses. The timer restarts when the
alert becomes visible or the duration changes, pauses while the alert is
hovered or focused, and is cleared on manual close and on unmount —
mirroring VSnackbar's timeout handling.

resolves #20409

Author: eldardada

packages/api-generator/src/locale/en/VAlert.json

@@ -6,6 +6,7 @@
     "closable": "Adds a close icon that can hide the alert.",
     "closeIcon": "Change the default icon used for **closable** alerts.",
     "closeLabel": "Text used for *aria-label* on **closable** alerts. Can also be customized globally in [Internationalization](/customization/internationalization).",
+    "duration": "Time (in milliseconds) to wait until the alert is automatically dismissed. A value of `0` keeps the alert visible.",
     "height": "Sets the height for the component.",
     "maxHeight": "Sets the maximum height for the component.",
     "maxWidth": "Sets the maximum width for the component.",

packages/vuetify/src/components/VAlert/VAlert.tsx

@@ -25,7 +25,7 @@ import { makeThemeProps, provideTheme } from '@/composables/theme'
 import { genOverlays, makeVariantProps, useVariant } from '@/composables/variant'
 
 // Utilities
-import { toRef } from 'vue'
+import { onMounted, onScopeDispose, shallowRef, toRef, watch } from 'vue'
 import { genericComponent, propsFactory } from '@/util'
 
 // Types
@@ -57,6 +57,10 @@ export const makeVAlertProps = propsFactory({
     type: String,
     default: '$vuetify.close',
   },
+  duration: {
+    type: [Number, String],
+    default: 0,
+  },
   icon: {
     type: [Boolean, String, Function, Object] as PropType<false | IconValue>,
     default: null,
@@ -107,6 +111,58 @@ export const VAlert = genericComponent<VAlertSlots>()({
 
   setup (props, { emit, slots }) {
     const isActive = useProxiedModel(props, 'modelValue')
+    const isHovering = shallowRef(false)
+    const isFocused = shallowRef(false)
+
+    let activeTimeout = -1
+    function startTimeout () {
+      window.clearTimeout(activeTimeout)
+      const duration = Number(props.duration)
+
+      if (!isActive.value || !duration || duration < 0 || isHovering.value || isFocused.value) return
+
+      activeTimeout = window.setTimeout(() => {
+        isActive.value = false
+      }, duration)
+    }
+
+    function clearTimeout () {
+      window.clearTimeout(activeTimeout)
+    }
+
+    function onPointerenter () {
+      isHovering.value = true
+      clearTimeout()
+    }
+
+    function onPointerleave () {
+      isHovering.value = false
+      startTimeout()
+    }
+
+    function onFocusin () {
+      isFocused.value = true
+      clearTimeout()
+    }
+
+    function onFocusout (e: FocusEvent) {
+      if (e.relatedTarget && (e.currentTarget as HTMLElement | null)?.contains(e.relatedTarget as Node)) return
+
+      isFocused.value = false
+      startTimeout()
+    }
+
+    watch(isActive, startTimeout)
+    watch(() => props.duration, startTimeout)
+
+    onMounted(() => {
+      if (isActive.value) startTimeout()
+    })
+
+    onScopeDispose(() => {
+      window.clearTimeout(activeTimeout)
+    })
+
     const icon = toRef(() => {
       if (props.icon === false) return undefined
       if (!props.type) return props.icon
@@ -179,6 +235,10 @@ export const VAlert = genericComponent<VAlertSlots>()({
             props.style,
           ]}
           role="alert"
+          onPointerenter={ onPointerenter }
+          onPointerleave={ onPointerleave }
+          onFocusin={ onFocusin }
+          onFocusout={ onFocusout }
         >
           { genOverlays(false, 'v-alert') }
 

packages/vuetify/src/components/VAlert/__tests__/VAlert.spec.browser.tsx

@@ -1,7 +1,7 @@
 import { VAlert } from '..'
 
 // Utilities
-import { render, screen, showcase } from '@test'
+import { render, screen, showcase, userEvent, wait } from '@test'
 
 const defaultColors = ['success', 'info', 'warning', 'error', 'invalid']
 
@@ -40,5 +40,53 @@ describe('VAlert', () => {
     })
   })
 
+  describe('duration', () => {
+    it('keeps the alert visible until the duration elapses, then dismisses it', async () => {
+      render(() => <VAlert text="auto dismiss" duration={ 300 } />)
+
+      await screen.findByCSS('.v-alert')
+
+      // should not be dismissed before the duration elapses
+      await wait(100)
+      expect(document.querySelector('.v-alert')).not.toBeNull()
+
+      // should be dismissed after the duration
+      await expect.poll(() => document.querySelector('.v-alert'), { timeout: 2000 }).toBeNull()
+    })
+
+    it('emits update:modelValue when auto-dismissed', async () => {
+      const onUpdate = vi.fn()
+
+      render(() => <VAlert text="auto dismiss" duration={ 150 } { ...{ 'onUpdate:modelValue': onUpdate } } />)
+
+      await expect.poll(() => onUpdate.mock.calls.length, { timeout: 2000 }).toBeGreaterThan(0)
+      expect(onUpdate).toHaveBeenLastCalledWith(false)
+    })
+
+    it('pauses the timer while hovered and resumes on leave', async () => {
+      render(() => <VAlert text="hover" duration={ 500 } />)
+
+      const alert = await screen.findByCSS('.v-alert')
+
+      await userEvent.hover(alert)
+      // stays visible past its duration while hovered
+      await wait(700)
+      expect(document.querySelector('.v-alert')).not.toBeNull()
+
+      // resumes and dismisses once the pointer leaves
+      await userEvent.unhover(alert)
+      await expect.poll(() => document.querySelector('.v-alert'), { timeout: 2000 }).toBeNull()
+    })
+
+    it('does not auto-dismiss by default', async () => {
+      render(() => <VAlert text="persistent" />)
+
+      await screen.findByCSS('.v-alert')
+      await wait(300)
+
+      expect(document.querySelector('.v-alert')).not.toBeNull()
+    })
+  })
+
   showcase({ stories, props, component: VAlert })
 })