feat: enhance popover reference (#1826)

* feat: enhance popover reference

* docs: improve docs

* fix: fix for test cases

* style: cleanup

* docs: update docs

packages/varlet-ui/src/menu-select/MenuSelect.vue

@@ -56,10 +56,11 @@ import { props } from './props'
 import { createNamespace, formatElevation } from '../utils/components'
 import { useMenuOptions, type MenuSelectProvider } from './provide'
 import { useSelectController } from '../select/useSelectController'
-import { type MenuOptionProvider } from '../menu-option/provide'
 import { call, preventDefault } from '@varlet/shared'
 import { useEventListener, useVModel } from '@varlet/use'
 import { focusChildElementByKey } from '../utils/elements'
+import { type MenuOptionProvider } from '../menu-option/provide'
+import { type Reference } from '../menu/usePopover'
 
 const { name, n, classes } = createNamespace('menu-select')
 
@@ -139,6 +140,11 @@ export default defineComponent({
       menu.value?.resize()
     }
 
+    // expose
+    function setReference(reference: Reference) {
+      menu.value?.setReference(reference)
+    }
+
     return {
       show,
       menu,
@@ -149,6 +155,7 @@ export default defineComponent({
       open,
       close,
       resize,
+      setReference,
     }
   },
 })

packages/varlet-ui/src/menu-select/docs/en-US.md

@@ -300,7 +300,7 @@ const options = ref([
 | `teleport`      | The location of the menu mount                                                                                               | _TeleportProps['to'] \| false_ | `body`            |
 | `disabled`      | Whether to disable the menu                                                                                                  | _boolean_            | `false`           |
 | `trigger`       | Menu trigger method, optional value is `click` `hover` `manual` | _string_  | `click`           |
-| `reference`       | The associated trigger element selector is used to specify specific child elements as trigger elements | _string_              | `-`           |
+| `reference` | The trigger element associated with the menu, the `string` type is the descendant element selector of the menu component, the `HTMLElement` type is any specified element node | _string \| HTMLElement_ | `-` |
 | `elevation` | Elevation level, options `true` `false` and level of `0-24` | _string \| number \| boolean_|   `true`    |
 | `same-width`    | Whether to same width as trigger element                                                                                     | _boolean_ | `false`           |
 | `popover-class` | Class of the popover                                                    | _string_             | `-`            |
@@ -361,6 +361,7 @@ const options = ref([
 | `open` | Open Menu                       | `-` | `-` |
 | `close` | Close Menu                      | `-` | `-` |
 | `resize` | This method can be called to redraw when the default slot element of Menu select changes its position and size | `-` | `-` |
+| `setReference` ***3.7.2*** | Set the trigger element associated with the menu | `reference: consistent with the reference of the component attribute` | `-` |
 
 ### Events
 

packages/varlet-ui/src/menu-select/docs/zh-CN.md

@@ -300,7 +300,7 @@ const options = ref([
 | `teleport`      | 菜单挂载的位置                                                     | _TeleportProps['to'] \| false_ | `body`            |
 | `disabled`      | 是否禁用菜单                                                      | _boolean_             | `false`           |
 | `trigger`       | 菜单触发方式，可选值为 `click` `hover` `manual` | _string_              | `click`           |
-| `reference`       | 菜单关联的触发元素选择器，用于指定菜单的特定子元素为触发元素 | _string_              | `-`           |
+| `reference`       | 菜单关联的触发元素，`string` 类型为菜单组件的子孙元素选择器， `HTMLElement` 类型为任意指定的元素节点 | _string \| HTMLElement_ | `-`           |
 | `elevation` | 海拔高度，可选值为 `true` `false` 和 `0-24` 的等级 | _string \| number \| boolean_|   `true`    |
 | `same-width`    | 是否与触发元素同宽                                                   | _boolean_             | `false`           |
 | `popover-class` | 弹出层的 class                                                    | _string_             | `-`            |
@@ -361,6 +361,7 @@ const options = ref([
 | `open` | 打开 MenuSelect | `-` | `-` |
 | `close` | 关闭 MenuSelect | `-` | `-` |
 | `resize` | MenuSelect 默认插槽元素产生位置大小变化时可以调用此方法进行重绘 | `-` | `-` |
+| `setReference` ***3.7.2*** | 设置 MenuSelect 关联的触发元素 | `reference: 与组件属性的 reference 一致` | `-` |
 
 ### 事件
 

packages/varlet-ui/src/menu/Menu.vue

@@ -1,11 +1,5 @@
 <template>
-  <div
-    ref="host"
-    :class="classes(n(), n('$--box'))"
-    @click="handleHostClick"
-    @mouseenter="handleHostMouseenter"
-    @mouseleave="handleHostMouseleave"
-  >
+  <div ref="host" :class="classes(n(), n('$--box'))">
     <slot />
 
     <Teleport :to="teleport === false ? undefined : teleport" :disabled="teleportDisabled || teleport === false">
@@ -14,7 +8,7 @@
           ref="popover"
           :style="{
             zIndex,
-            width: sameWidth ? toSizeUnit(Math.ceil(hostSize.width)) : undefined,
+            width: sameWidth ? toSizeUnit(Math.ceil(referenceSize.width)) : undefined,
           }"
           :class="
             classes(
@@ -54,12 +48,9 @@ export default defineComponent({
     const {
       popover,
       host,
-      hostSize,
+      referenceSize,
       show,
       zIndex,
-      handleHostClick,
-      handleHostMouseenter,
-      handleHostMouseleave,
       handlePopoverMouseenter,
       handlePopoverMouseleave,
       handlePopoverClose,
@@ -70,29 +61,29 @@ export default defineComponent({
       close,
       // expose
       resize,
+      // expose
+      setReference,
     } = usePopover(props)
 
     return {
       popover,
       host,
-      hostSize,
+      referenceSize,
       show,
       zIndex,
       teleportDisabled,
       formatElevation,
       toSizeUnit,
       n,
       classes,
-      handleHostClick,
-      handleHostMouseenter,
-      handleHostMouseleave,
       handlePopoverMouseenter,
       handlePopoverMouseleave,
       handlePopoverClose,
       handleClosed,
       resize,
       open,
       close,
+      setReference,
     }
   },
 })

packages/varlet-ui/src/menu/docs/en-US.md

@@ -231,6 +231,7 @@ it is recommended to wrap a `block` element.
 | `disabled`      | Whether to disable the menu                                                                                                  | _boolean_            | `false`           |
 | `trigger`       | Menu trigger method, optional value is `click` `hover` `manual`  | _string_  | `click`           |
 | `reference`       | The associated trigger element selector is used to specify specific child elements as trigger elements | _string_              | `-`           |
+| `reference` | The trigger element associated with the menu, the `string` type is the descendant element selector of the menu component, the `HTMLElement` type is any specified element node | _string \| HTMLElement_ | `-` |
 | `elevation` | Elevation level, options `true` `false` and level of `0-24` | _string \| number \| boolean_|   `true`    |
 | `same-width`    | Whether to same width as trigger element                                                                                     | _boolean_ | `false`           |
 | `default-style` | Whether to enable default styles                                                                                             | _boolean_ | `true`            |
@@ -264,11 +265,13 @@ it is recommended to wrap a `block` element.
 | `cover-right` | Right center position, overlay trigger |
 
 ### Methods
+
 | Method   | Description                     | Arguments | Return |
 | --- |---------------------------------| --- | --- |
 | `open` | Open Menu                       | `-` | `-` |
 | `close` | Close Menu                      | `-` | `-` |
 | `resize` | This method can be called to redraw when the default slot element of Menu changes its position and size | `-` | `-` |
+| `setReference` ***3.7.2*** | Set the trigger element associated with the menu | `reference: consistent with the reference of the component attribute` | `-` |
 
 ### Events
 

packages/varlet-ui/src/menu/docs/zh-CN.md

@@ -226,7 +226,7 @@ Menu 是一个 `inline-block` 元素，通过默认插槽点击时显示菜单
 | `teleport`      | 菜单挂载的位置                                                     | _TeleportProps['to'] \| false_ | `body`            |
 | `disabled`      | 是否禁用菜单                                                      | _boolean_             | `false`           |
 | `trigger`       | 菜单触发方式，可选值为 `click` `hover` `manual` | _string_              | `click`           |
-| `reference`       | 菜单关联的触发元素选择器，用于指定菜单的特定子元素为触发元素 | _string_              | `-`           |
+| `reference`       | 菜单关联的触发元素，`string` 类型为菜单组件的子孙元素选择器， `HTMLElement` 类型为任意指定的元素节点 | _string \| HTMLElement_              | `-`           |
 | `elevation` | 海拔高度，可选值为 `true` `false` 和 `0-24` 的等级 | _string \| number \| boolean_|   `true`    |
 | `same-width`    | 是否与触发元素同宽                                                   | _boolean_             | `false`           |
 | `default-style` | 是否启用默认样式                                                    | _boolean_             | `true`            |
@@ -260,11 +260,13 @@ Menu 是一个 `inline-block` 元素，通过默认插槽点击时显示菜单
 | `cover-right` | 右侧位置, 覆盖触发器 |
 
 ### 方法
+
 | 方法名 | 说明 | 参数 | 返回值 |
 | --- | --- | --- | --- |
 | `open` | 打开 Menu | `-` | `-` |
 | `close` | 关闭 Menu | `-` | `-` |
 | `resize` | Menu 默认插槽元素产生位置大小变化时可以调用此方法进行重绘 | `-` | `-` |
+| `setReference` ***3.7.2*** | 设置菜单关联的触发元素 | `reference: 与组件属性的 reference 一致` | `-` |
 
 ### 事件
 

packages/varlet-ui/src/menu/example/index.vue

@@ -30,12 +30,12 @@ const placementOptions = ref([
   'cover-right',
 ])
 
+watchLang(use)
+onThemeChange()
+
 function closeMenu() {
   show.value = false
 }
-
-watchLang(use)
-onThemeChange()
 </script>
 
 <template>

packages/varlet-ui/src/menu/props.ts

@@ -1,5 +1,5 @@
 import { type PropType, type TeleportProps } from 'vue'
-import { type Placement, type Trigger } from './usePopover'
+import { type Placement, type Trigger, type Reference } from './usePopover'
 import { type PositioningStrategy } from '@popperjs/core'
 import { defineListenerProp } from '../utils/components'
 
@@ -10,7 +10,7 @@ export const props = {
     type: String as PropType<Trigger>,
     default: 'click',
   },
-  reference: String,
+  reference: [String, Object] as PropType<Reference>,
   placement: {
     type: String as PropType<Placement>,
     default: 'cover-top-start',