@coreui/vue-pro 4.9.0-beta.2 → 5.0.0-alpha.0

package/src/components/popover/CPopover.ts

@@ -1,30 +1,54 @@
 import { defineComponent, h, PropType, ref, RendererElement, Teleport, Transition } from 'vue'
-import { createPopper, Placement } from '@popperjs/core'
+import type { Placement } from '@popperjs/core'
 
+import { usePopper } from '../../composables'
+import type { Placements, Triggers } from '../../types'
 import { executeAfterTransition } from '../../utils/transition'
-import { isRTL } from '../../utils'
-
-const getPlacement = (placement: string, element: HTMLDivElement | null): Placement => {
-  switch (placement) {
-    case 'right': {
-      return isRTL(element) ? 'left' : 'right'
-    }
-    case 'left': {
-      return isRTL(element) ? 'right' : 'left'
-    }
-    default: {
-      return placement as Placement
-    }
-  }
-}
+import { getRTLPlacement } from '../../utils'
 
 const CPopover = defineComponent({
   name: 'CPopover',
   props: {
+    /**
+     * Apply a CSS fade transition to the popover.
+     *
+     * @since 4.9.0
+     */
+    animation: {
+      type: Boolean,
+      default: true,
+    },
     /**
      * Content for your component. If you want to pass non-string value please use dedicated slot `<template #content>...</template>`
      */
     content: String,
+    /**
+     * The delay for displaying and hiding the popover (in milliseconds). When a numerical value is provided, the delay applies to both the hide and show actions. The object structure for specifying the delay is as follows: delay: `{ 'show': 500, 'hide': 100 }`.
+     *
+     * @since 4.9.0
+     */
+    delay: {
+      type: [Number, Object] as PropType<number | { show: number; hide: number }>,
+      default: 0,
+    },
+    /**
+     * Specify the desired order of fallback placements by providing a list of placements as an array. The placements should be prioritized based on preference.
+     *
+     * @since 4.9.0
+     */
+    fallbackPlacements: {
+      type: [String, Array] as PropType<Placements | Placements[]>,
+      default: () => ['top', 'right', 'bottom', 'left'],
+      validator: (value: Placements | Placements[]) => {
+        if (typeof value === 'string') {
+          return ['top', 'right', 'bottom', 'left'].includes(value)
+        }
+        if (Array.isArray(value)) {
+          return value.every((e) => ['top', 'right', 'bottom', 'left'].includes(e))
+        }
+        return false
+      },
+    },
     /**
      * Offset of the popover relative to its target.
      */
@@ -52,9 +76,9 @@ const CPopover = defineComponent({
      * @values 'click', 'focus', 'hover'
      */
     trigger: {
-      type: [String, Array] as PropType<string | string[]>,
+      type: [String, Array] as PropType<Triggers | Triggers[]>,
       default: 'click',
-      validator: (value: string | string[]) => {
+      validator: (value: Triggers | Triggers[]) => {
         if (typeof value === 'string') {
           return ['click', 'focus', 'hover'].includes(value)
         }
@@ -82,12 +106,39 @@ const CPopover = defineComponent({
   setup(props, { attrs, slots, emit }) {
     const togglerRef = ref()
     const popoverRef = ref()
-    const popper = ref()
     const visible = ref(props.visible)
+    const { initPopper, destroyPopper } = usePopper()
+
+    const delay =
+      typeof props.delay === 'number' ? { show: props.delay, hide: props.delay } : props.delay
+
+    const popperConfig = {
+      modifiers: [
+        {
+          name: 'arrow',
+          options: {
+            element: '.popover-arrow',
+          },
+        },
+        {
+          name: 'flip',
+          options: {
+            fallbackPlacements: props.fallbackPlacements,
+          },
+        },
+        {
+          name: 'offset',
+          options: {
+            offset: props.offset,
+          },
+        },
+      ],
+      placement: getRTLPlacement(props.placement, togglerRef.value),
+    }
 
     const handleEnter = (el: RendererElement, done: () => void) => {
       emit('show')
-      initPopper()
+      initPopper(togglerRef.value, popoverRef.value, popperConfig)
       el.classList.add('show')
       executeAfterTransition(() => done(), el as HTMLElement)
     }
@@ -101,32 +152,18 @@ const CPopover = defineComponent({
       }, el as HTMLElement)
     }
 
-    const handleToggle = (event: Event) => {
+    const toggleVisible = (event: Event, _visible: boolean) => {
       togglerRef.value = event.target
-      visible.value = !visible.value
-    }
-
-    const initPopper = () => {
-      if (togglerRef.value) {
-        popper.value = createPopper(togglerRef.value, popoverRef.value, {
-          placement: getPlacement(props.placement, togglerRef.value),
-          modifiers: [
-            {
-              name: 'offset',
-              options: {
-                offset: props.offset,
-              },
-            },
-          ],
-        })
+      if (_visible) {
+        setTimeout(() => {
+          visible.value = true
+        }, delay.show)
+        return
       }
-    }
 
-    const destroyPopper = () => {
-      if (popper.value) {
-        popper.value.destroy()
-      }
-      popper.value = undefined
+      setTimeout(() => {
+        visible.value = false
+      }, delay.hide)
     }
 
     return () => [
@@ -146,13 +183,19 @@ const CPopover = defineComponent({
             h(
               'div',
               {
-                class: 'popover fade bs-popover-auto',
+                class: [
+                  'popover',
+                  'bs-popover-auto',
+                  {
+                    fade: props.animation,
+                  },
+                ],
                 ref: popoverRef,
                 role: 'tooltip',
                 ...attrs,
               },
               [
-                h('div', { class: 'popover-arrow', 'data-popper-arrow': '' }),
+                h('div', { class: 'popover-arrow' }),
                 (props.title || slots.title) &&
                   h(
                     'div',
@@ -176,11 +219,14 @@ const CPopover = defineComponent({
       slots.toggler &&
         slots.toggler({
           on: {
-            click: (event: Event) => props.trigger.includes('click') && handleToggle(event),
-            blur: (event: Event) => props.trigger.includes('focus') && handleToggle(event),
-            focus: (event: Event) => props.trigger.includes('focus') && handleToggle(event),
-            mouseenter: (event: Event) => props.trigger.includes('hover') && handleToggle(event),
-            mouseleave: (event: Event) => props.trigger.includes('hover') && handleToggle(event),
+            click: (event: Event) =>
+              props.trigger.includes('click') && toggleVisible(event, !visible.value),
+            blur: (event: Event) => props.trigger.includes('focus') && toggleVisible(event, false),
+            focus: (event: Event) => props.trigger.includes('focus') && toggleVisible(event, true),
+            mouseenter: (event: Event) =>
+              props.trigger.includes('hover') && toggleVisible(event, true),
+            mouseleave: (event: Event) =>
+              props.trigger.includes('hover') && toggleVisible(event, false),
           },
         }),
     ]

package/src/components/tooltip/CTooltip.ts

@@ -1,30 +1,54 @@
 import { defineComponent, h, PropType, ref, RendererElement, Teleport, Transition } from 'vue'
-import { createPopper, Placement } from '@popperjs/core'
+import type { Placement } from '@popperjs/core'
 
+import { usePopper } from '../../composables'
+import type { Placements, Triggers } from '../../types'
 import { executeAfterTransition } from '../../utils/transition'
-import { isRTL } from '../../utils'
-
-const getPlacement = (placement: string, element: HTMLDivElement | null): Placement => {
-  switch (placement) {
-    case 'right': {
-      return isRTL(element) ? 'left' : 'right'
-    }
-    case 'left': {
-      return isRTL(element) ? 'right' : 'left'
-    }
-    default: {
-      return placement as Placement
-    }
-  }
-}
+import { getRTLPlacement } from '../../utils'
 
 const CTooltip = defineComponent({
   name: 'CTooltip',
   props: {
+    /**
+     * Apply a CSS fade transition to the tooltip.
+     *
+     * @since 4.9.0
+     */
+    animation: {
+      type: Boolean,
+      default: true,
+    },
     /**
      * Content for your component. If you want to pass non-string value please use dedicated slot `<template #content>...</template>`
      */
     content: String,
+    /**
+     * The delay for displaying and hiding the popover (in milliseconds). When a numerical value is provided, the delay applies to both the hide and show actions. The object structure for specifying the delay is as follows: delay: `{ 'show': 500, 'hide': 100 }`.
+     *
+     * @since 4.9.0
+     */
+    delay: {
+      type: [Number, Object] as PropType<number | { show: number; hide: number }>,
+      default: 0,
+    },
+    /**
+     * Specify the desired order of fallback placements by providing a list of placements as an array. The placements should be prioritized based on preference.
+     *
+     * @since 4.9.0
+     */
+    fallbackPlacements: {
+      type: [String, Array] as PropType<Placements | Placements[]>,
+      default: () => ['top', 'right', 'bottom', 'left'],
+      validator: (value: Placements | Placements[]) => {
+        if (typeof value === 'string') {
+          return ['top', 'right', 'bottom', 'left'].includes(value)
+        }
+        if (Array.isArray(value)) {
+          return value.every((e) => ['top', 'right', 'bottom', 'left'].includes(e))
+        }
+        return false
+      },
+    },
     /**
      * Offset of the tooltip relative to its target.
      */
@@ -48,9 +72,9 @@ const CTooltip = defineComponent({
      * @values 'click', 'focus', 'hover'
      */
     trigger: {
-      type: [String, Array] as PropType<string | string[]>,
-      default: 'hover',
-      validator: (value: string | string[]) => {
+      type: [String, Array] as PropType<Triggers | Triggers[]>,
+      default: () => ['hover', 'focus'],
+      validator: (value: Triggers | Triggers[]) => {
         if (typeof value === 'string') {
           return ['click', 'focus', 'hover'].includes(value)
         }
@@ -78,12 +102,39 @@ const CTooltip = defineComponent({
   setup(props, { attrs, slots, emit }) {
     const togglerRef = ref()
     const tooltipRef = ref()
-    const popper = ref()
     const visible = ref(props.visible)
+    const { initPopper, destroyPopper } = usePopper()
+    
+    const delay =
+      typeof props.delay === 'number' ? { show: props.delay, hide: props.delay } : props.delay
+
+    const popperConfig = {
+      modifiers: [
+        {
+          name: 'arrow',
+          options: {
+            element: '.tooltip-arrow',
+          },
+        },
+        {
+          name: 'flip',
+          options: {
+            fallbackPlacements: props.fallbackPlacements,
+          },
+        },
+        {
+          name: 'offset',
+          options: {
+            offset: props.offset,
+          },
+        },
+      ],
+      placement: getRTLPlacement(props.placement, togglerRef.value),
+    }
 
     const handleEnter = (el: RendererElement, done: () => void) => {
       emit('show')
-      initPopper()
+      initPopper(togglerRef.value, tooltipRef.value, popperConfig)
       el.classList.add('show')
       executeAfterTransition(() => done(), el as HTMLElement)
     }
@@ -97,32 +148,18 @@ const CTooltip = defineComponent({
       }, el as HTMLElement)
     }
 
-    const handleToggle = (event: Event) => {
+    const toggleVisible = (event: Event, _visible: boolean) => {
       togglerRef.value = event.target
-      visible.value = !visible.value
-    }
-
-    const initPopper = () => {
-      if (togglerRef.value) {
-        popper.value = createPopper(togglerRef.value, tooltipRef.value, {
-          placement: getPlacement(props.placement, togglerRef.value),
-          modifiers: [
-            {
-              name: 'offset',
-              options: {
-                offset: props.offset,
-              },
-            },
-          ],
-        })
+      if (_visible) {
+        setTimeout(() => {
+          visible.value = true
+        }, delay.show)
+        return
       }
-    }
 
-    const destroyPopper = () => {
-      if (popper.value) {
-        popper.value.destroy()
-      }
-      popper.value = undefined
+      setTimeout(() => {
+        visible.value = false
+      }, delay.hide)
     }
 
     return () => [
@@ -142,13 +179,19 @@ const CTooltip = defineComponent({
             h(
               'div',
               {
-                class: 'tooltip fade bs-tooltip-auto',
+                class: [
+                  'tooltip',
+                  'bs-tooltip-auto',
+                  {
+                    fade: props.animation,
+                  },
+                ],
                 ref: tooltipRef,
                 role: 'tooltip',
                 ...attrs,
               },
               [
-                h('div', { class: 'tooltip-arrow', 'data-popper-arrow': '' }),
+                h('div', { class: 'tooltip-arrow' }),
                 (props.content || slots.content) &&
                   h(
                     'div',
@@ -164,11 +207,14 @@ const CTooltip = defineComponent({
       slots.toggler &&
         slots.toggler({
           on: {
-            click: (event: Event) => props.trigger.includes('click') && handleToggle(event),
-            blur: (event: Event) => props.trigger.includes('focus') && handleToggle(event),
-            focus: (event: Event) => props.trigger.includes('focus') && handleToggle(event),
-            mouseenter: (event: Event) => props.trigger.includes('hover') && handleToggle(event),
-            mouseleave: (event: Event) => props.trigger.includes('hover') && handleToggle(event),
+            click: (event: Event) =>
+              props.trigger.includes('click') && toggleVisible(event, !visible.value),
+            blur: (event: Event) => props.trigger.includes('focus') && toggleVisible(event, false),
+            focus: (event: Event) => props.trigger.includes('focus') && toggleVisible(event, true),
+            mouseenter: (event: Event) =>
+              props.trigger.includes('hover') && toggleVisible(event, true),
+            mouseleave: (event: Event) =>
+              props.trigger.includes('hover') && toggleVisible(event, false),
           },
         }),
     ]

package/src/composables/index.ts

@@ -1,3 +1,4 @@
 import { useColorModes } from './useColorModes'
+import { usePopper } from './usePopper'
 
-export { useColorModes }
+export { useColorModes, usePopper }

package/src/composables/useColorModes.ts

@@ -2,6 +2,7 @@ import { onBeforeMount, ref, watch } from 'vue'
 
 const getStoredTheme = (localStorageItemName: string) =>
   typeof window !== 'undefined' && localStorage.getItem(localStorageItemName)
+
 const setStoredTheme = (localStorageItemName: string, colorMode: string) =>
   localStorage.setItem(localStorageItemName, colorMode)
 
@@ -53,7 +54,7 @@ export const useColorModes = (localStorageItemName = 'coreui-vue-color-scheme')
   })
 
   return {
-    getColorMode: () => colorMode.value,
+    colorMode,
     isColorModeSet: () => Boolean(getStoredTheme(localStorageItemName)),
     setColorMode: (mode: string) => {
       colorMode.value = mode

package/src/composables/usePopper.ts

@@ -0,0 +1,25 @@
+import { ref } from 'vue'
+import { createPopper } from '@popperjs/core'
+import type { Instance, Options } from '@popperjs/core'
+
+export const usePopper = () => {
+  const _popper = ref<Instance>()
+
+  const initPopper = (reference: HTMLElement, popper: HTMLElement, options: Partial<Options>) => {
+    _popper.value = createPopper(reference, popper, options)
+  }
+
+  const destroyPopper = () => {
+    if (_popper.value) {
+      _popper.value.destroy()
+    }
+
+    _popper.value = undefined
+  }
+
+  return {
+    popper: _popper.value,
+    initPopper,
+    destroyPopper,
+  }
+}

package/src/types.ts

@@ -35,7 +35,7 @@ export type Placements =
   | 'left-start'
   | 'left'
   | 'left-end'
-  | undefined
+  | string
 
 export type Shapes =
   | 'rounded'

package/src/utils/getRTLPlacement.ts

@@ -0,0 +1,18 @@
+import { Placement } from '@popperjs/core'
+import { isRTL } from '../utils'
+
+const getRTLPlacement = (placement: string, element: HTMLDivElement | null): Placement => {
+  switch (placement) {
+    case 'right': {
+      return isRTL(element) ? 'left' : 'right'
+    }
+    case 'left': {
+      return isRTL(element) ? 'right' : 'left'
+    }
+    default: {
+      return placement as Placement
+    }
+  }
+}
+
+export default getRTLPlacement

package/src/utils/index.ts

@@ -1,6 +1,7 @@
+import getRTLPlacement from './getRTLPlacement'
 import getUID from './getUID'
 import isInViewport from './isInViewport'
 import isObjectInArray from './isObjectInArray'
 import isRTL from './isRTL'
 
-export { getUID, isInViewport, isObjectInArray, isRTL }
+export { getRTLPlacement, getUID, isInViewport, isObjectInArray, isRTL }