refactor(VAlert): rename duration to timeout, share dismiss logic

Addresses review feedback on vuetifyjs#22947:

- Rename the `VAlert` `duration` prop to `timeout` so it matches
  `VSnackbar` and avoids the cognitive load of two differently-named
  props with the same behavior.
- Extract the auto-dismiss timeout and pause-on-hover/focus handling
  that was duplicated between `VSnackbar` and `VAlert` into a shared
  `useAutoDismiss` composable. `VSnackbar` keeps driving its visual
  countdown timer through the composable's `onStart`/`onClear` hooks.

A `timeout` of `0` or less keeps the alert visible (default), so the
behavior remains backwards compatible.

Author: eldardada

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

@@ -6,7 +6,6 @@
     "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.",
@@ -15,6 +14,7 @@
     "modelValue": "Controls whether the component is visible or hidden.",
     "prominent": "Displays a larger vertically centered icon to draw more attention.",
     "tile": "Removes the component's border-radius.",
+    "timeout": "Time (in milliseconds) to wait until the alert is automatically dismissed. A value of `0` or less keeps the alert visible. Changes to this property will reset the countdown.",
     "type": "Create a specialized alert that uses a contextual color and has a pre-defined icon.",
     "width": "Sets the width for the component."
   },

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

@@ -8,6 +8,7 @@ import { VDefaultsProvider } from '@/components/VDefaultsProvider'
 import { VIcon } from '@/components/VIcon'
 
 // Composables
+import { useAutoDismiss } from '@/composables/autoDismiss'
 import { useTextColor } from '@/composables/color'
 import { makeComponentProps } from '@/composables/component'
 import { makeDensityProps, useDensity } from '@/composables/density'
@@ -25,7 +26,7 @@ import { makeThemeProps, provideTheme } from '@/composables/theme'
 import { genOverlays, makeVariantProps, useVariant } from '@/composables/variant'
 
 // Utilities
-import { onMounted, onScopeDispose, shallowRef, toRef, watch } from 'vue'
+import { toRef } from 'vue'
 import { genericComponent, propsFactory } from '@/util'
 
 // Types
@@ -57,7 +58,7 @@ export const makeVAlertProps = propsFactory({
     type: String,
     default: '$vuetify.close',
   },
-  duration: {
+  timeout: {
     type: [Number, String],
     default: 0,
   },
@@ -111,57 +112,13 @@ 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 {
+      onPointerenter,
+      onPointerleave,
+      onFocusin,
+      onFocusout,
+    } = useAutoDismiss(isActive, () => Number(props.timeout))
 
     const icon = toRef(() => {
       if (props.icon === false) return undefined

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

@@ -40,36 +40,36 @@ describe('VAlert', () => {
     })
   })
 
-  describe('duration', () => {
-    it('keeps the alert visible until the duration elapses, then dismisses it', async () => {
-      render(() => <VAlert text="auto dismiss" duration={ 300 } />)
+  describe('timeout', () => {
+    it('keeps the alert visible until the timeout elapses, then dismisses it', async () => {
+      render(() => <VAlert text="auto dismiss" timeout={ 300 } />)
 
       await screen.findByCSS('.v-alert')
 
-      // should not be dismissed before the duration elapses
+      // should not be dismissed before the timeout elapses
       await wait(100)
       expect(document.querySelector('.v-alert')).not.toBeNull()
 
-      // should be dismissed after the duration
+      // should be dismissed after the timeout
       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 } } />)
+      render(() => <VAlert text="auto dismiss" timeout={ 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 } />)
+      render(() => <VAlert text="hover" timeout={ 500 } />)
 
       const alert = await screen.findByCSS('.v-alert')
 
       await userEvent.hover(alert)
-      // stays visible past its duration while hovered
+      // stays visible past its timeout while hovered
       await wait(700)
       expect(document.querySelector('.v-alert')).not.toBeNull()
 

packages/vuetify/src/components/VSnackbar/VSnackbar.tsx

@@ -13,6 +13,7 @@ import { useSnackbarItem } from '@/components/VSnackbarQueue/queue'
 
 // Composables
 import { useLayout } from '@/composables'
+import { useAutoDismiss } from '@/composables/autoDismiss'
 import { forwardRefs } from '@/composables/forwardRefs'
 import { IconValue } from '@/composables/icons'
 import { VuetifyLayoutKey } from '@/composables/layout'
@@ -26,7 +27,7 @@ import { useToggleScope } from '@/composables/toggleScope'
 import { genOverlays, makeVariantProps, useVariant } from '@/composables/variant'
 
 // Utilities
-import { computed, inject, mergeProps, nextTick, onMounted, onScopeDispose, ref, shallowRef, watch, watchEffect } from 'vue'
+import { computed, inject, mergeProps, nextTick, onScopeDispose, ref, shallowRef, watchEffect } from 'vue'
 import { convertToUnit, genericComponent, noop, omit, propsFactory, refElement, useRender } from '@/util'
 
 // Types
@@ -147,8 +148,6 @@ export const VSnackbar = genericComponent<VSnackbarSlots>()({
     let _lastOffset: string
 
     const timerRef = ref<VProgressLinear>()
-    const isHovering = shallowRef(false)
-    const isFocused = shallowRef(false)
     const startY = shallowRef(0)
     const mainStyles = ref()
     const hasLayout = inject(VuetifyLayoutKey, undefined)
@@ -161,61 +160,19 @@ export const VSnackbar = genericComponent<VSnackbarSlots>()({
       })
     })
 
-    watch(isActive, startTimeout)
-    watch(() => props.timeout, startTimeout)
-
-    onMounted(() => {
-      if (isActive.value) startTimeout()
+    const {
+      isHovering,
+      isFocused,
+      onPointerenter,
+      onPointerleave,
+      onFocusin,
+      onFocusout,
+    } = useAutoDismiss(isActive, () => Number(props.timeout), {
+      getContentEl: () => overlay.value?.contentEl,
+      onClear: () => countdown.reset(),
+      onStart: () => nextTick(() => countdown.start(refElement(timerRef.value))),
     })
 
-    let activeTimeout = -1
-    function startTimeout () {
-      countdown.clear()
-      window.clearTimeout(activeTimeout)
-      const timeout = Number(props.timeout)
-
-      if (!isActive.value || timeout === -1) return
-
-      countdown.reset()
-
-      const element = refElement(timerRef.value)
-
-      nextTick(() => countdown.start(element))
-
-      activeTimeout = window.setTimeout(() => {
-        isActive.value = false
-      }, timeout)
-    }
-
-    function clearTimeout () {
-      countdown.reset()
-      window.clearTimeout(activeTimeout)
-    }
-
-    function onPointerenter () {
-      isHovering.value = true
-      clearTimeout()
-    }
-
-    function onPointerleave () {
-      isHovering.value = false
-      if (!isFocused.value) startTimeout()
-    }
-
-    function onFocusin () {
-      isFocused.value = true
-      clearTimeout()
-    }
-
-    function onFocusout (event: FocusEvent) {
-      const contentEl = overlay.value?.contentEl
-      if (contentEl?.contains(event.relatedTarget as Node)) {
-        return
-      }
-      isFocused.value = false
-      if (!isHovering.value) startTimeout()
-    }
-
     function onTouchstart (event: TouchEvent) {
       startY.value = event.touches[0].clientY
     }

packages/vuetify/src/composables/autoDismiss.ts

@@ -0,0 +1,94 @@
+// Utilities
+import { onMounted, onScopeDispose, shallowRef, watch } from 'vue'
+
+// Types
+import type { Ref } from 'vue'
+
+export interface AutoDismissOptions {
+  /** Called when the timeout (re)starts */
+  onStart?: () => void
+  /** Called when the pending timeout is cleared */
+  onClear?: () => void
+  /** Element scoping the focusout containment check, defaults to the event's currentTarget */
+  getContentEl?: () => HTMLElement | null | undefined
+}
+
+/**
+ * Toggles `isActive` off after `timeout` ms, pausing while hovered or focused.
+ * A `timeout` of `0` or less never dismisses. Shared by VSnackbar and VAlert.
+ */
+export function useAutoDismiss (
+  isActive: Ref<boolean>,
+  timeout: () => number,
+  options: AutoDismissOptions = {},
+) {
+  const isHovering = shallowRef(false)
+  const isFocused = shallowRef(false)
+
+  let activeTimeout = -1
+
+  function startTimeout () {
+    options.onClear?.()
+    window.clearTimeout(activeTimeout)
+
+    const value = timeout()
+
+    if (!isActive.value || value <= 0 || isHovering.value || isFocused.value) return
+
+    options.onStart?.()
+
+    activeTimeout = window.setTimeout(() => {
+      isActive.value = false
+    }, value)
+  }
+
+  function clearTimeout () {
+    options.onClear?.()
+    window.clearTimeout(activeTimeout)
+  }
+
+  function onPointerenter () {
+    isHovering.value = true
+    clearTimeout()
+  }
+
+  function onPointerleave () {
+    isHovering.value = false
+    if (!isFocused.value) startTimeout()
+  }
+
+  function onFocusin () {
+    isFocused.value = true
+    clearTimeout()
+  }
+
+  function onFocusout (e: FocusEvent) {
+    const contentEl = options.getContentEl?.() ?? (e.currentTarget as HTMLElement | null)
+    if (contentEl?.contains(e.relatedTarget as Node)) return
+
+    isFocused.value = false
+    if (!isHovering.value) startTimeout()
+  }
+
+  watch(isActive, startTimeout)
+  watch(timeout, startTimeout)
+
+  onMounted(() => {
+    if (isActive.value) startTimeout()
+  })
+
+  onScopeDispose(() => {
+    window.clearTimeout(activeTimeout)
+  })
+
+  return {
+    isHovering,
+    isFocused,
+    startTimeout,
+    clearTimeout,
+    onPointerenter,
+    onPointerleave,
+    onFocusin,
+    onFocusout,
+  }
+}