diff --git a/web/vue/package.json b/web/vue/package.json index f6da998..6db9ad4 100644 --- a/web/vue/package.json +++ b/web/vue/package.json @@ -1,6 +1,6 @@ { "name": "@robonen/vue", - "version": "0.0.10", + "version": "0.0.11", "license": "Apache-2.0", "description": "Collection of powerful tools for Vue", "keywords": [ diff --git a/web/vue/src/composables/unrefElement/index.test.ts b/web/vue/src/composables/unrefElement/index.test.ts new file mode 100644 index 0000000..5e247e0 --- /dev/null +++ b/web/vue/src/composables/unrefElement/index.test.ts @@ -0,0 +1,61 @@ +import { describe, expect, it } from 'vitest'; +import { computed, defineComponent, nextTick, ref, shallowRef } from 'vue'; +import { mount } from '@vue/test-utils' +import { unrefElement } from '.'; + +describe('unrefElement', () => { + it('returns a plain element when passed a raw element', () => { + const htmlEl = document.createElement('div'); + const svgEl = document.createElementNS('http://www.w3.org/2000/svg', 'svg'); + + expect(unrefElement(htmlEl)).toBe(htmlEl); + expect(unrefElement(svgEl)).toBe(svgEl); + }); + + it('returns element when passed a ref or shallowRef to an element', () => { + const el = document.createElement('div'); + const elRef = ref(el); + const shallowElRef = shallowRef(el); + + expect(unrefElement(elRef)).toBe(el); + expect(unrefElement(shallowElRef)).toBe(el); + }); + + it('returns element when passed a computed ref or getter function', () => { + const el = document.createElement('div'); + const computedElRef = computed(() => el); + const elGetter = () => el; + + expect(unrefElement(computedElRef)).toBe(el); + expect(unrefElement(elGetter)).toBe(el); + }); + + it('returns component $el when passed a component instance', async () => { + const Child = defineComponent({ + template: `child`, + }); + + const Parent = defineComponent({ + components: { Child }, + template: ``, + }); + + const wrapper = mount(Parent); + await nextTick(); + + const childInstance = (wrapper.vm as any).$refs.childRef; + const result = unrefElement(childInstance); + + expect(result).toBe(childInstance.$el); + expect((result as HTMLElement).classList.contains('child-el')).toBe(true); + }); + + it('handles null and undefined values', () => { + expect(unrefElement(undefined)).toBe(undefined); + expect(unrefElement(null)).toBe(null); + expect(unrefElement(ref(null))).toBe(null); + expect(unrefElement(ref(undefined))).toBe(undefined); + expect(unrefElement(() => null)).toBe(null); + expect(unrefElement(() => undefined)).toBe(undefined); + }); +}); diff --git a/web/vue/src/composables/unrefElement/index.ts b/web/vue/src/composables/unrefElement/index.ts new file mode 100644 index 0000000..2cca254 --- /dev/null +++ b/web/vue/src/composables/unrefElement/index.ts @@ -0,0 +1,33 @@ +import type { ComponentPublicInstance, MaybeRef, MaybeRefOrGetter } from 'vue'; +import { toValue } from 'vue'; + +export type VueInstance = ComponentPublicInstance; +export type MaybeElement = HTMLElement | SVGElement | VueInstance | undefined | null; + +export type MaybeElementRef = MaybeRef; +export type MaybeComputedElementRef = MaybeRefOrGetter; + +export type UnRefElementReturn = T extends VueInstance ? Exclude : T | undefined; + +/** + * @name unrefElement + * @category Components + * @description Unwraps a Vue element reference to get the underlying instance or DOM element. + * + * @param {MaybeComputedElementRef} elRef - The element reference to unwrap. + * @returns {UnRefElementReturn} - The unwrapped element or undefined. + * + * @example + * const element = useTemplateRef('element'); + * const result = unrefElement(element); // result is the element instance + * + * @example + * const component = useTemplateRef('component'); + * const result = unrefElement(component); // result is the component instance + * + * @since 0.0.11 + */ +export function unrefElement(elRef: MaybeComputedElementRef): UnRefElementReturn { + const plain = toValue(elRef); + return (plain as VueInstance)?.$el ?? plain; +} \ No newline at end of file