feat: enhance portal support with flexible target options

Introduced `usePortal` composable to standardize portal handling across components, supporting `boolean`, `string`, and `HTMLElement` types. Updated various components to leverage this composable, improving configurability and integration with custom portal targets. Default behavior remains backward compatible.

Author: menthol

src/runtime/components/App.vue

@@ -6,6 +6,7 @@ export interface AppProps<T extends Messages = Messages> extends Omit<ConfigProv
   tooltip?: TooltipProviderProps
   toaster?: ToasterProps | null
   locale?: Locale<T>
+  portal?: string | HTMLElement
 }
 
 export interface AppSlots {
@@ -18,10 +19,11 @@ export default {
 </script>
 
 <script setup lang="ts" generic="T extends Messages">
-import { toRef, useId, provide } from 'vue'
+import { toRef, useId, provide, computed } from 'vue'
 import { ConfigProvider, TooltipProvider, useForwardProps } from 'reka-ui'
 import { reactivePick } from '@vueuse/core'
 import { localeContextInjectionKey } from '../composables/useLocale'
+import { portalTargetInjectionKey } from '../composables/usePortal'
 import UToaster from './Toaster.vue'
 import UOverlayProvider from './OverlayProvider.vue'
 
@@ -34,6 +36,9 @@ const toasterProps = toRef(() => props.toaster)
 
 const locale = toRef(() => props.locale)
 provide(localeContextInjectionKey, locale)
+
+const portal = computed(() => ({ portal: props.portal ?? 'body' }))
+provide(portalTargetInjectionKey, portal)
 </script>
 
 <template>

src/runtime/components/ContextMenu.vue

@@ -66,7 +66,7 @@ export interface ContextMenuProps<T extends ArrayOrNested<ContextMenuItem> = Arr
    * Render the menu in a portal.
    * @defaultValue true
    */
-  portal?: boolean
+  portal?: boolean | string | HTMLElement
   /**
    * The key used to get the label from the item.
    * @defaultValue 'label'

src/runtime/components/ContextMenuContent.vue

@@ -9,7 +9,7 @@ type ContextMenu = ComponentConfig<typeof theme, AppConfig, 'contextMenu'>
 
 interface ContextMenuContentProps<T extends ArrayOrNested<ContextMenuItem>> extends Omit<RekaContextMenuContentProps, 'as' | 'asChild' | 'forceMount'> {
   items?: T
-  portal?: boolean
+  portal?: boolean | string | HTMLElement
   sub?: boolean
   labelKey: keyof NestedItem<T>
   /**
@@ -39,6 +39,7 @@ import { useForwardPropsEmits } from 'reka-ui'
 import { reactiveOmit, createReusableTemplate } from '@vueuse/core'
 import { useAppConfig } from '#imports'
 import { useLocale } from '../composables/useLocale'
+import { usePortal } from '../composables/usePortal'
 import { omit, get, isArrayOfArray } from '../utils'
 import { pickLinkProps } from '../utils/link'
 import ULinkBase from './LinkBase.vue'
@@ -69,6 +70,8 @@ const groups = computed<ContextMenuItem[][]>(() =>
       : [props.items]
     : []
 )
+
+const { target: portalTarget, disabled: portalDisabled } = usePortal(props)
 </script>
 
 <template>
@@ -103,7 +106,7 @@ const groups = computed<ContextMenuItem[][]>(() =>
     </slot>
   </DefineItemTemplate>
 
-  <ContextMenu.Portal :disabled="!portal">
+  <ContextMenu.Portal :disabled="portalDisabled" :to="portalTarget">
     <component :is="sub ? ContextMenu.SubContent : ContextMenu.Content" :class="props.class" v-bind="contentProps">
       <ContextMenu.Group v-for="(group, groupIndex) in groups" :key="`group-${groupIndex}`" :class="ui.group({ class: uiOverride?.group })">
         <template v-for="(item, index) in group" :key="`group-${groupIndex}-${index}`">

src/runtime/components/Drawer.vue

@@ -36,7 +36,7 @@ export interface DrawerProps extends Pick<DrawerRootProps, 'activeSnapPoint' | '
    * Render the drawer in a portal.
    * @defaultValue true
    */
-  portal?: boolean
+  portal?: boolean | string | HTMLElement
   class?: any
   ui?: Drawer['slots']
 }
@@ -60,6 +60,7 @@ import { useForwardPropsEmits } from 'reka-ui'
 import { DrawerRoot, DrawerTrigger, DrawerPortal, DrawerOverlay, DrawerContent, DrawerTitle, DrawerDescription, DrawerHandle } from 'vaul-vue'
 import { reactivePick } from '@vueuse/core'
 import { useAppConfig } from '#imports'
+import { usePortal } from '../composables/usePortal'
 import { tv } from '../utils/tv'
 
 const props = withDefaults(defineProps<DrawerProps>(), {
@@ -85,6 +86,8 @@ const ui = computed(() => tv({ extend: tv(theme), ...(appConfig.ui?.drawer || {}
   direction: props.direction,
   inset: props.inset
 }))
+
+const { target: portalTarget, disabled: portalDisabled } = usePortal(props)
 </script>
 
 <template>
@@ -93,7 +96,7 @@ const ui = computed(() => tv({ extend: tv(theme), ...(appConfig.ui?.drawer || {}
       <slot />
     </DrawerTrigger>
 
-    <DrawerPortal :disabled="!portal">
+    <DrawerPortal :disabled="portalDisabled" :to="portalTarget">
       <DrawerOverlay v-if="overlay" :class="ui.overlay({ class: props.ui?.overlay })" />
 
       <DrawerContent :class="ui.content({ class: [!slots.default && props.class, props.ui?.content] })" v-bind="contentProps" v-on="contentEvents">

src/runtime/components/DropdownMenu.vue

@@ -74,7 +74,7 @@ export interface DropdownMenuProps<T extends ArrayOrNested<DropdownMenuItem> = A
    * Render the menu in a portal.
    * @defaultValue true
    */
-  portal?: boolean
+  portal?: boolean | string | HTMLElement
   /**
    * The key used to get the label from the item.
    * @defaultValue 'label'

src/runtime/components/DropdownMenuContent.vue

@@ -10,7 +10,7 @@ type DropdownMenu = ComponentConfig<typeof theme, AppConfig, 'dropdownMenu'>
 
 interface DropdownMenuContentProps<T extends ArrayOrNested<DropdownMenuItem>> extends Omit<RekaDropdownMenuContentProps, 'as' | 'asChild' | 'forceMount'> {
   items?: T
-  portal?: boolean
+  portal?: boolean | string | HTMLElement
   sub?: boolean
   labelKey: keyof NestedItem<T>
   /**
@@ -45,6 +45,7 @@ import { useForwardPropsEmits } from 'reka-ui'
 import { reactiveOmit, createReusableTemplate } from '@vueuse/core'
 import { useAppConfig } from '#imports'
 import { useLocale } from '../composables/useLocale'
+import { usePortal } from '../composables/usePortal'
 import { omit, get, isArrayOfArray } from '../utils'
 import { pickLinkProps } from '../utils/link'
 import ULinkBase from './LinkBase.vue'
@@ -75,6 +76,8 @@ const groups = computed<DropdownMenuItem[][]>(() =>
       : [props.items]
     : []
 )
+
+const { target: portalTarget, disabled: portalDisabled } = usePortal(props)
 </script>
 
 <template>
@@ -109,7 +112,7 @@ const groups = computed<DropdownMenuItem[][]>(() =>
     </slot>
   </DefineItemTemplate>
 
-  <DropdownMenu.Portal :disabled="!portal">
+  <DropdownMenu.Portal :disabled="portalDisabled" :to="portalTarget">
     <component :is="sub ? DropdownMenu.SubContent : DropdownMenu.Content" :class="props.class" v-bind="contentProps">
       <DropdownMenu.Group v-for="(group, groupIndex) in groups" :key="`group-${groupIndex}`" :class="ui.group({ class: uiOverride?.group })">
         <template v-for="(item, index) in group" :key="`group-${groupIndex}-${index}`">

src/runtime/components/InputMenu.vue

@@ -86,7 +86,7 @@ export interface InputMenuProps<T extends ArrayOrNested<InputMenuItem> = ArrayOr
    * Render the menu in a portal.
    * @defaultValue true
    */
-  portal?: boolean
+  portal?: boolean | string | HTMLElement
   /**
    * When `items` is an array of objects, select the field to use as the value instead of the object itself.
    * @defaultValue undefined
@@ -177,6 +177,7 @@ import { useButtonGroup } from '../composables/useButtonGroup'
 import { useComponentIcons } from '../composables/useComponentIcons'
 import { useFormField } from '../composables/useFormField'
 import { useLocale } from '../composables/useLocale'
+import { usePortal } from '../composables/usePortal'
 import { compare, get, isArrayOfArray } from '../utils'
 import { tv } from '../utils/tv'
 import UIcon from './Icon.vue'
@@ -376,6 +377,8 @@ function isInputItem(item: InputMenuItem): item is _InputMenuItem {
 defineExpose({
   inputRef
 })
+
+const { target: portalTarget, disabled: portalDisabled } = usePortal(props)
 </script>
 
 <!-- eslint-disable vue/no-template-shadow -->
@@ -474,7 +477,7 @@ defineExpose({
       </ComboboxTrigger>
     </ComboboxAnchor>
 
-    <ComboboxPortal :disabled="!portal">
+    <ComboboxPortal :disabled="portalDisabled" :to="portalTarget">
       <ComboboxContent :class="ui.content({ class: props.ui?.content })" v-bind="contentProps">
         <ComboboxEmpty :class="ui.empty({ class: props.ui?.empty })">
           <slot name="empty" :search-term="searchTerm">

src/runtime/components/Modal.vue

@@ -31,7 +31,7 @@ export interface ModalProps extends DialogRootProps {
    * Render the modal in a portal.
    * @defaultValue true
    */
-  portal?: boolean
+  portal?: boolean | string | HTMLElement
   /**
    * Display a close button to dismiss the modal.
    * `{ size: 'md', color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
@@ -75,6 +75,7 @@ import { DialogRoot, DialogTrigger, DialogPortal, DialogOverlay, DialogContent,
 import { reactivePick } from '@vueuse/core'
 import { useAppConfig } from '#imports'
 import { useLocale } from '../composables/useLocale'
+import { usePortal } from '../composables/usePortal'
 import { tv } from '../utils/tv'
 import UButton from './Button.vue'
 
@@ -115,6 +116,8 @@ const ui = computed(() => tv({ extend: tv(theme), ...(appConfig.ui?.modal || {})
   transition: props.transition,
   fullscreen: props.fullscreen
 }))
+
+const { target: portalTarget, disabled: portalDisabled } = usePortal(props)
 </script>
 
 <template>
@@ -123,7 +126,7 @@ const ui = computed(() => tv({ extend: tv(theme), ...(appConfig.ui?.modal || {})
       <slot :open="open" />
     </DialogTrigger>
 
-    <DialogPortal :disabled="!portal">
+    <DialogPortal :disabled="portalDisabled" :to="portalTarget">
       <DialogOverlay v-if="overlay" :class="ui.overlay({ class: props.ui?.overlay })" />
 
       <DialogContent :class="ui.content({ class: [!slots.default && props.class, props.ui?.content] })" v-bind="contentProps" @after-leave="emits('after:leave')" v-on="contentEvents">

src/runtime/components/Popover.vue

@@ -26,7 +26,7 @@ export interface PopoverProps extends PopoverRootProps, Pick<HoverCardRootProps,
    * Render the popover in a portal.
    * @defaultValue true
    */
-  portal?: boolean
+  portal?: boolean | string | HTMLElement
   /**
    * When `false`, the popover will not close when clicking outside or pressing escape.
    * @defaultValue true
@@ -51,6 +51,7 @@ import { useForwardPropsEmits } from 'reka-ui'
 import { Popover, HoverCard } from 'reka-ui/namespaced'
 import { reactivePick } from '@vueuse/core'
 import { useAppConfig } from '#imports'
+import { usePortal } from '../composables/usePortal'
 import { tv } from '../utils/tv'
 
 const props = withDefaults(defineProps<PopoverProps>(), {
@@ -87,6 +88,8 @@ const ui = computed(() => tv({ extend: tv(theme), ...(appConfig.ui?.popover || {
 }))
 
 const Component = computed(() => props.mode === 'hover' ? HoverCard : Popover)
+
+const { target: portalTarget, disabled: portalDisabled } = usePortal(props)
 </script>
 
 <template>
@@ -95,7 +98,7 @@ const Component = computed(() => props.mode === 'hover' ? HoverCard : Popover)
       <slot :open="open" />
     </Component.Trigger>
 
-    <Component.Portal :disabled="!portal">
+    <Component.Portal :disabled="portalDisabled" :to="portalTarget">
       <Component.Content v-bind="contentProps" :class="ui.content({ class: [!slots.default && props.class, props.ui?.content] })" v-on="contentEvents">
         <slot name="content" />
 

src/runtime/components/Select.vue

@@ -70,7 +70,7 @@ export interface SelectProps<T extends ArrayOrNested<SelectItem> = ArrayOrNested
    * Render the menu in a portal.
    * @defaultValue true
    */
-  portal?: boolean
+  portal?: boolean | string | HTMLElement
   /**
    * When `items` is an array of objects, select the field to use as the value.
    * @defaultValue 'value'
@@ -138,6 +138,7 @@ import { useAppConfig } from '#imports'
 import { useButtonGroup } from '../composables/useButtonGroup'
 import { useComponentIcons } from '../composables/useComponentIcons'
 import { useFormField } from '../composables/useFormField'
+import { usePortal } from '../composables/usePortal'
 import { compare, get, isArrayOfArray } from '../utils'
 import { tv } from '../utils/tv'
 import UIcon from './Icon.vue'
@@ -219,6 +220,8 @@ function onUpdateOpen(value: boolean) {
 function isSelectItem(item: SelectItem): item is SelectItemBase {
   return typeof item === 'object' && item !== null
 }
+
+const { target: portalTarget, disabled: portalDisabled } = usePortal(props)
 </script>
 
 <!-- eslint-disable vue/no-template-shadow -->
@@ -260,7 +263,7 @@ function isSelectItem(item: SelectItem): item is SelectItemBase {
       </span>
     </SelectTrigger>
 
-    <SelectPortal :disabled="!portal">
+    <SelectPortal :disabled="portalDisabled" :to="portalTarget">
       <SelectContent :class="ui.content({ class: props.ui?.content })" v-bind="contentProps">
         <SelectViewport :class="ui.viewport({ class: props.ui?.viewport })">
           <SelectGroup v-for="(group, groupIndex) in groups" :key="`group-${groupIndex}`" :class="ui.group({ class: props.ui?.group })">