feat(popper): arrow option & docs consistency across components (#875)

docs/components/content/examples/ContextMenuExampleArrow.vue

@@ -0,0 +1,35 @@
+<script setup>
+const { x, y } = useMouse()
+const { y: windowY } = useWindowScroll()
+
+const isOpen = ref(false)
+const virtualElement = ref({ getBoundingClientRect: () => ({}) })
+
+function onContextMenu () {
+  const top = unref(y) - unref(windowY)
+  const left = unref(x)
+
+  virtualElement.value.getBoundingClientRect = () => ({
+    width: 0,
+    height: 0,
+    top,
+    left
+  })
+
+  isOpen.value = true
+}
+</script>
+
+<template>
+  <div class="w-full" @contextmenu.prevent="onContextMenu">
+    <Placeholder class="h-96 select-none w-full flex items-center justify-center">
+      Right click here
+    </Placeholder>
+
+    <UContextMenu v-model="isOpen" :virtual-element="virtualElement" :popper="{ arrow: true, placement: 'right' }">
+      <div class="p-4">
+        Menu
+      </div>
+    </UContextMenu>
+  </div>
+</template>

docs/components/content/examples/ContextMenuExampleOffset.vue

@@ -0,0 +1,35 @@
+<script setup>
+const { x, y } = useMouse()
+const { y: windowY } = useWindowScroll()
+
+const isOpen = ref(false)
+const virtualElement = ref({ getBoundingClientRect: () => ({}) })
+
+function onContextMenu () {
+  const top = unref(y) - unref(windowY)
+  const left = unref(x)
+
+  virtualElement.value.getBoundingClientRect = () => ({
+    width: 0,
+    height: 0,
+    top,
+    left
+  })
+
+  isOpen.value = true
+}
+</script>
+
+<template>
+  <div class="w-full" @contextmenu.prevent="onContextMenu">
+    <Placeholder class="h-96 select-none w-full flex items-center justify-center">
+      Right click here
+    </Placeholder>
+
+    <UContextMenu v-model="isOpen" :virtual-element="virtualElement" :popper="{ offset: 0 }">
+      <div class="p-4">
+        Menu
+      </div>
+    </UContextMenu>
+  </div>
+</template>

docs/components/content/examples/ContextMenuExamplePlacement.vue

@@ -0,0 +1,35 @@
+<script setup>
+const { x, y } = useMouse()
+const { y: windowY } = useWindowScroll()
+
+const isOpen = ref(false)
+const virtualElement = ref({ getBoundingClientRect: () => ({}) })
+
+function onContextMenu () {
+  const top = unref(y) - unref(windowY)
+  const left = unref(x)
+
+  virtualElement.value.getBoundingClientRect = () => ({
+    width: 0,
+    height: 0,
+    top,
+    left
+  })
+
+  isOpen.value = true
+}
+</script>
+
+<template>
+  <div class="w-full" @contextmenu.prevent="onContextMenu">
+    <Placeholder class="h-96 select-none w-full flex items-center justify-center">
+      Right click here
+    </Placeholder>
+
+    <UContextMenu v-model="isOpen" :virtual-element="virtualElement" :popper="{ placement: 'right-start' }">
+      <div class="p-4">
+        Menu
+      </div>
+    </UContextMenu>
+  </div>
+</template>

docs/components/content/examples/DropdownExampleArrow.vue

@@ -0,0 +1,16 @@
+<script setup>
+const items = [
+  [{
+    label: 'Profile',
+    avatar: {
+      src: 'https://avatars.githubusercontent.com/u/739984?v=4'
+    }
+  }]
+]
+</script>
+
+<template>
+  <UDropdown :items="items" :popper="{ arrow: true }">
+    <UButton color="white" label="Options" trailing-icon="i-heroicons-chevron-down-20-solid" />
+  </UDropdown>
+</template>

docs/components/content/examples/DropdownExampleOffset.vue

@@ -0,0 +1,16 @@
+<script setup>
+const items = [
+  [{
+    label: 'Profile',
+    avatar: {
+      src: 'https://avatars.githubusercontent.com/u/739984?v=4'
+    }
+  }]
+]
+</script>
+
+<template>
+  <UDropdown :items="items" :popper="{ offsetDistance: 0, placement: 'right-start' }">
+    <UButton color="white" label="Options" trailing-icon="i-heroicons-chevron-down-20-solid" />
+  </UDropdown>
+</template>

docs/components/content/examples/DropdownExamplePlacement.vue

@@ -0,0 +1,16 @@
+<script setup>
+const items = [
+  [{
+    label: 'Profile',
+    avatar: {
+      src: 'https://avatars.githubusercontent.com/u/739984?v=4'
+    }
+  }]
+]
+</script>
+
+<template>
+  <UDropdown :items="items" :popper="{ placement: 'right-start' }">
+    <UButton color="white" label="Options" trailing-icon="i-heroicons-chevron-down-20-solid" />
+  </UDropdown>
+</template>

docs/components/content/examples/PopoverExampleArrow.vue

@@ -0,0 +1,11 @@
+<template>
+  <UPopover :popper="{ arrow: true }">
+    <UButton color="white" label="Open" trailing-icon="i-heroicons-chevron-down-20-solid" />
+
+    <template #panel>
+      <div class="p-4">
+        <Placeholder class="h-20 w-48" />
+      </div>
+    </template>
+  </UPopover>
+</template>

docs/components/content/examples/PopoverExampleOffset.vue

@@ -0,0 +1,11 @@
+<template>
+  <UPopover :popper="{ offsetDistance: 0 }">
+    <UButton color="white" label="Open" trailing-icon="i-heroicons-chevron-down-20-solid" />
+
+    <template #panel>
+      <div class="p-4">
+        <Placeholder class="h-20 w-48" />
+      </div>
+    </template>
+  </UPopover>
+</template>

docs/components/content/examples/PopoverExamplePlacement.vue

@@ -0,0 +1,11 @@
+<template>
+  <UPopover :popper="{ placement: 'top-end' }">
+    <UButton color="white" label="Open" trailing-icon="i-heroicons-chevron-down-20-solid" />
+
+    <template #panel>
+      <div class="p-4">
+        <Placeholder class="h-20 w-48" />
+      </div>
+    </template>
+  </UPopover>
+</template>

docs/components/content/examples/SelectMenuExampleArrow.vue

@@ -0,0 +1,9 @@
+<script setup>
+const people = ['Wade Cooper', 'Arlene Mccoy', 'Devon Webb', 'Tom Cook', 'Tanya Fox', 'Hellen Schmidt', 'Caroline Schultz', 'Mason Heaney', 'Claudie Smitham', 'Emil Schaefer']
+
+const selected = ref(people[0])
+</script>
+
+<template>
+  <USelectMenu v-model="selected" :options="people" :popper="{ arrow: true }" />
+</template>

docs/components/content/examples/SelectMenuExampleOffset.vue

@@ -0,0 +1,9 @@
+<script setup>
+const people = ['Wade Cooper', 'Arlene Mccoy', 'Devon Webb', 'Tom Cook', 'Tanya Fox', 'Hellen Schmidt', 'Caroline Schultz', 'Mason Heaney', 'Claudie Smitham', 'Emil Schaefer']
+
+const selected = ref(people[0])
+</script>
+
+<template>
+  <USelectMenu v-model="selected" :options="people" :popper="{ offsetDistance: 0 }" />
+</template>

docs/components/content/examples/SelectMenuExamplePlacement.vue

@@ -0,0 +1,9 @@
+<script setup>
+const people = ['Wade Cooper', 'Arlene Mccoy', 'Devon Webb', 'Tom Cook', 'Tanya Fox', 'Hellen Schmidt', 'Caroline Schultz', 'Mason Heaney', 'Claudie Smitham', 'Emil Schaefer']
+
+const selected = ref(people[0])
+</script>
+
+<template>
+  <USelectMenu v-model="selected" :options="people" :popper="{ placement: 'left-end' }" />
+</template>

docs/content/2.elements/6.dropdown.md

@@ -32,6 +32,22 @@ Use the `mode` prop to switch between `click` and `hover` modes.
 
 :component-example{component="dropdown-example-mode"}
 
+## Popper
+
+Use the `popper` prop to customize the popper instance.
+
+### Arrow
+
+:component-example{component="dropdown-example-arrow"}
+
+### Placement
+
+:component-example{component="dropdown-example-placement"}
+
+### Offset
+
+:component-example{component="dropdown-example-offset"}
+
 ## Slots
 
 ### `item`

docs/content/3.forms/4.select-menu.md

@@ -91,6 +91,22 @@ Try to search for something that doesn't exist in the example below.
 
 :component-example{component="select-menu-example-creatable" :componentProps='{"class": "w-full lg:w-40"}'}
 
+## Popper
+
+Use the `popper` prop to customize the popper instance.
+
+### Arrow
+
+:component-example{component="select-menu-example-arrow"}
+
+### Placement
+
+:component-example{component="select-menu-example-placement"}
+
+### Offset
+
+:component-example{component="select-menu-example-offset"}
+
 ## Slots
 
 ### `label`

docs/content/6.overlays/3.popover.md

@@ -25,6 +25,22 @@ Use the `open` prop to manually control showing the panel.
 
 :component-example{component="popover-example-open"}
 
+## Popper
+
+Use the `popper` prop to customize the popper instance.
+
+### Arrow
+
+:component-example{component="popover-example-arrow"}
+
+### Placement
+
+:component-example{component="popover-example-placement"}
+
+### Offset
+
+:component-example{component="popover-example-offset"}
+
 ## Slots
 
 ### `panel`

docs/content/6.overlays/4.tooltip.md

@@ -12,7 +12,7 @@ links:
 
 ## Popper
 
-Use the `popper` prop to customize the tootip.
+Use the `popper` prop to customize the popper instance.
 
 ### Arrow
 

docs/content/6.overlays/5.context-menu.md

@@ -11,6 +11,22 @@ links:
 
 :component-example{component="context-menu-example"}
 
+## Popper
+
+Use the `popper` prop to customize the popper instance.
+
+### Arrow
+
+:component-example{component="context-menu-example-arrow"}
+
+### Placement
+
+:component-example{component="context-menu-example-placement"}
+
+### Offset
+
+:component-example{component="context-menu-example-offset"}
+
 ## Props
 
 :component-props

src/runtime/components/elements/Dropdown.vue

@@ -17,6 +17,8 @@
 
     <div v-if="open && items.length" ref="container" :class="[ui.container, ui.width]" :style="containerStyle" @mouseover="onMouseOver">
       <Transition appear v-bind="ui.transition">
+        <div>
+          <div v-if="popper.arrow" data-popper-arrow :class="['invisible before:visible before:block before:rotate-45 before:z-[-1]', Object.values(ui.arrow)]" />
           <HMenuItems :class="[ui.base, ui.divide, ui.ring, ui.rounded, ui.shadow, ui.background, ui.height]" static>
             <div v-for="(subItems, index) of items" :key="index" :class="ui.padding">
               <HMenuItem v-for="(item, subIndex) of subItems" :key="subIndex" v-slot="{ active, disabled: itemDisabled }" :disabled="item.disabled">
@@ -39,6 +41,7 @@
               </HMenuItem>
             </div>
           </HMenuItems>
+        </div>
       </Transition>
     </div>
   </HMenu>
@@ -185,6 +188,8 @@ export default defineComponent({
       // eslint-disable-next-line vue/no-dupe-keys
       ui,
       attrs,
+      // eslint-disable-next-line vue/no-dupe-keys
+      popper,
       trigger,
       container,
       containerStyle,

src/runtime/components/forms/SelectMenu.vue

@@ -52,6 +52,8 @@
 
     <div v-if="open" ref="container" :class="[uiMenu.container, uiMenu.width]">
       <Transition appear v-bind="uiMenu.transition">
+        <div>
+          <div v-if="popper.arrow" data-popper-arrow :class="['invisible before:visible before:block before:rotate-45 before:z-[-1]', Object.values(uiMenu.arrow)]" />
           <component :is="searchable ? 'HComboboxOptions' : 'HListboxOptions'" static :class="[uiMenu.base, uiMenu.divide, uiMenu.ring, uiMenu.rounded, uiMenu.shadow, uiMenu.background, uiMenu.padding, uiMenu.height]">
             <HComboboxInput
               v-if="searchable"
@@ -110,6 +112,7 @@
               </slot>
             </p>
           </component>
+        </div>
       </Transition>
     </div>
   </component>
@@ -449,6 +452,8 @@ export default defineComponent({
       // eslint-disable-next-line vue/no-dupe-keys
       name,
       inputId,
+      // eslint-disable-next-line vue/no-dupe-keys
+      popper,
       trigger,
       container,
       isLeading,

src/runtime/components/overlays/ContextMenu.vue

@@ -1,9 +1,12 @@
 <template>
   <div v-if="isOpen" ref="container" :class="wrapperClass" v-bind="attrs">
     <Transition appear v-bind="ui.transition">
+      <div>
+        <div v-if="popper.arrow" data-popper-arrow :class="['invisible before:visible before:block before:rotate-45 before:z-[-1]', Object.values(ui.arrow)]" />
         <div :class="[ui.base, ui.ring, ui.rounded, ui.shadow, ui.background]">
           <slot />
         </div>
+      </div>
     </Transition>
   </div>
 </template>
@@ -85,6 +88,8 @@ export default defineComponent({
       attrs,
       isOpen,
       wrapperClass,
+      // eslint-disable-next-line vue/no-dupe-keys
+      popper,
       container
     }
   }

src/runtime/components/overlays/Popover.vue

@@ -17,9 +17,12 @@
 
     <div v-if="(open !== undefined) ? open : headlessOpen" ref="container" :class="[ui.container, ui.width]" :style="containerStyle" @mouseover="onMouseOver">
       <Transition appear v-bind="ui.transition">
+        <div>
+          <div v-if="popper.arrow" data-popper-arrow :class="['invisible before:visible before:block before:rotate-45 before:z-[-1]', Object.values(ui.arrow)]" />
           <HPopoverPanel :class="[ui.base, ui.background, ui.ring, ui.rounded, ui.shadow]" static>
             <slot name="panel" :open="(open !== undefined) ? open : headlessOpen" :close="close" />
           </HPopoverPanel>
+        </div>
       </Transition>
     </div>
   </HPopover>
@@ -162,6 +165,8 @@ export default defineComponent({
       ui,
       attrs,
       popover,
+      // eslint-disable-next-line vue/no-dupe-keys
+      popper,
       trigger,
       container,
       containerStyle,

src/runtime/ui.config.ts

@@ -1,5 +1,14 @@
 // Data
 
+const _popperArrowPresets = {
+  base: 'before:w-2 before:h-2',
+  ring: 'before:ring-1 before:ring-gray-200 dark:before:ring-gray-800',
+  rounded: 'before:rounded-sm',
+  background: 'before:bg-gray-200 dark:before:bg-gray-800',
+  shadow: 'before:shadow',
+  placement: 'group-data-[popper-placement*="right"]:-left-1 group-data-[popper-placement*="left"]:-right-1 group-data-[popper-placement*="top"]:-bottom-1 group-data-[popper-placement*="bottom"]:-top-1'
+}
+
 export const table = {
   wrapper: 'relative overflow-x-auto',
   base: 'min-w-full table-fixed',
@@ -250,7 +259,7 @@ export const buttonGroup = {
 
 export const dropdown = {
   wrapper: 'relative inline-flex text-left rtl:text-right',
-  container: 'z-20',
+  container: 'z-20 group',
   width: 'w-48',
   height: '',
   background: 'bg-white dark:bg-gray-800',
@@ -291,6 +300,11 @@ export const dropdown = {
   popper: {
     placement: 'bottom-end',
     strategy: 'fixed'
+  },
+  arrow: {
+    ..._popperArrowPresets,
+    ring: 'before:ring-1 before:ring-gray-200 dark:before:ring-gray-700',
+    background: 'before:bg-white dark:before:bg-gray-700'
   }
 }
 
@@ -525,7 +539,7 @@ export const select = {
 }
 
 export const selectMenu = {
-  container: 'z-20',
+  container: 'z-20 group',
   width: 'w-full',
   height: 'max-h-60',
   base: 'relative focus:outline-none overflow-y-auto scroll-py-1',
@@ -576,6 +590,11 @@ export const selectMenu = {
   },
   default: {
     selectedIcon: 'i-heroicons-check-20-solid'
+  },
+  arrow: {
+    ..._popperArrowPresets,
+    ring: 'before:ring-1 before:ring-gray-200 dark:before:ring-gray-700',
+    background: 'before:bg-white dark:before:bg-gray-700'
   }
 }
 
@@ -1009,25 +1028,18 @@ export const tooltip = {
   popper: {
     strategy: 'fixed'
   },
-  arrow: {
+  arrow: _popperArrowPresets
-    base: 'before:w-2 before:h-2',
-    ring: 'before:ring-1 before:ring-gray-200 dark:before:ring-gray-800',
-    rounded: 'before:rounded-sm',
-    background: 'before:bg-white dark:before:bg-gray-900',
-    shadow: 'before:shadow',
-    placement: 'group-data-[popper-placement=right]:-left-1 group-data-[popper-placement=left]:-right-1 group-data-[popper-placement=top]:-bottom-1 group-data-[popper-placement=bottom]:-top-1'
-  }
 }
 
 export const popover = {
   wrapper: 'relative',
-  container: 'z-20',
+  container: 'z-20 group',
   width: '',
   background: 'bg-white dark:bg-gray-900',
   shadow: 'shadow-lg',
   rounded: 'rounded-md',
   ring: 'ring-1 ring-gray-200 dark:ring-gray-800',
-  base: 'overflow-hidden focus:outline-none',
+  base: 'overflow-hidden focus:outline-none relative',
   // Syntax for `<Transition>` component https://vuejs.org/guide/built-ins/transition.html#css-based-transitions
   transition: {
     enterActiveClass: 'transition ease-out duration-200',
@@ -1039,18 +1051,19 @@ export const popover = {
   },
   popper: {
     strategy: 'fixed'
-  }
+  },
+  arrow: _popperArrowPresets
 }
 
 export const contextMenu = {
   wrapper: 'relative',
-  container: 'z-20',
+  container: 'z-20 group',
   width: '',
   background: 'bg-white dark:bg-gray-900',
   shadow: 'shadow-lg',
   rounded: 'rounded-md',
   ring: 'ring-1 ring-gray-200 dark:ring-gray-800',
-  base: 'overflow-hidden focus:outline-none',
+  base: 'overflow-hidden focus:outline-none relative',
   // Syntax for `<Transition>` component https://vuejs.org/guide/built-ins/transition.html#css-based-transitions
   transition: {
     enterActiveClass: 'transition ease-out duration-200',
@@ -1063,7 +1076,8 @@ export const contextMenu = {
   popper: {
     placement: 'bottom-start',
     scroll: false
-  }
+  },
+  arrow: _popperArrowPresets
 }
 
 export const notification = {