vue-unwrap 1.1.0 → 2.0.0

package/README.md

@@ -31,11 +31,14 @@ import { getNodeElement, Unwrap } from 'vue-unwrap'
 
 const ctx = useTemplateRef<typeof Unwrap>('ctx')
 
-const $children = computed(() => ctx.value?.children.map(getNodeElement))
+const childElements = computed(() => ctx.value?.children.map(getNodeElement))
+const rootElement = computed(() => ctx.value?.root)
 </script>
 
 <template>
-  <Unwrap ref="ctx" />
+  <Unwrap ref="ctx" is="div">
+    <p>Lorem ipsum</p>
+  </Unwrap>
 </template>
 
 ```
@@ -45,25 +48,21 @@ const $children = computed(() => ctx.value?.children.map(getNodeElement))
 ```vue
 <script setup lang="ts">
 import type { ComponentPublicInstance } from 'vue'
-import { useUnwrap } from 'vue-unwrap'
+import { computed } from 'vue'
+import { useUnwrap, type NodeRef } from 'vue-unwrap'
 
 // your component props definition
-type PropsType = { foo: string } 
+type PropsType = { foo: string }
 
 // your child nodes definition
-type CustomNodeType = (
-  | ComponentPublicInstance<{ bar: string }>
-  | ComponentPublicInstance
-  | Element
-  | null
-)
+type CustomNodeType = ComponentPublicInstance<{ bar: string }> | NodeRef
 
 const props = defineProps<PropsType>()
 
-const { $el, children, Unwrap } = useUnwrap<CustomNodeType, PropsType>()
+const { root, children, Unwrap } = useUnwrap<CustomNodeType, PropsType>()
 
 const bars = computed(() => (
-  children?
+  children
     .map(child => (
       (child && 'bar' in child)
         ? `${props.foo}-${child.bar}`
@@ -79,6 +78,63 @@ const bars = computed(() => (
 
 ```
 
+## API
+
+### `Unwrap`
+
+Conditional wrapper component. Pass **`is`** to render a wrapper element or component; omit it to render slot children directly with no extra DOM node.
+
+When used with a template ref, the component instance exposes:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `children` | `NodeRef[]` | Reactive refs to each unwrapped child node |
+| `root` | `Element \| null` | The wrapper DOM element when `is` is set; otherwise `null` |
+
+Remaining attributes (except `is`) are forwarded to the wrapper when one is rendered.
+
+### `useUnwrap<N, P>(propTypes?)`
+
+Composable for building custom wrapper components. Returns `{ children, root, Unwrap }` with the same semantics as the component above.
+
+- **`N`** — type of each entry in `children` (defaults to `NodeRef`)
+- **`P`** — props type passed to the default slot render function
+- **`propTypes`** — optional Vue props definition merged onto the returned `Unwrap` render function, so declared props are forwarded to slot content
+
+```vue
+<script setup lang="ts">
+import { useUnwrap, type NodeRef } from 'vue-unwrap'
+
+const { Unwrap } = useUnwrap<NodeRef, { count: number }>({
+  count: { type: Number, default: 0 },
+})
+</script>
+
+<template>
+  <Unwrap :count="3" v-slot="{ count }">
+    <span>{{ count }} items</span>
+  </Unwrap>
+</template>
+```
+
+Use the returned **`Unwrap`** in your template as the render target (typically with `<Unwrap />` and a default slot).
+
+### `NodeRef`
+
+```ts
+type NodeRef = Element | ComponentPublicInstance | null
+```
+
+Default type for entries in `children`.
+
+### `getNodeElement(node)`
+
+Resolves a child ref to its DOM `Element`. For component instances, returns `$el`; for plain elements, returns the element itself; otherwise returns `null`.
+
+### `unwrapVNodes(vnodes)`
+
+Utility that flattens slot VNodes into a flat array, unwrapping `Fragment` nodes and skipping comments and empty values. Used internally by `useUnwrap`; exported for advanced custom render logic.
+
 ## Development
 
 - Install dependencies:
@@ -90,7 +146,7 @@ npm install
 - Run the playground:
 
 ```bash
-npm run playground
+npm run play
 ```
 
 - Run the unit tests:

package/dist/index.d.ts

@@ -1,21 +1,17 @@
 import * as _$vue from "vue";
 import { ComponentPublicInstance, SetupContext, VNode, VNodeArrayChildren } from "vue";
 
-//#region src/useUnwrap.d.ts
+//#region src/types.d.ts
 type NodeRef = Element | ComponentPublicInstance | null;
-declare function getNodeElement<N = NodeRef>(node: N): Element | null;
-declare function unwrapVNodes(vnodes: VNodeArrayChildren): VNode[];
+//#endregion
+//#region src/useUnwrap.d.ts
 declare function useUnwrap<N = NodeRef, P = Record<string, any>>(propTypes?: Record<string, any>): {
-  $el: _$vue.ShallowRef<Element | null, Element | null>;
   children: _$vue.ShallowReactive<N[]>;
-  dom: _$vue.ComputedRef<{
-    el: Element | null;
-    children: _$vue.ShallowReactive<N[]>;
-  }>;
+  root: _$vue.ShallowRef<Element | null, Element | null>;
   Unwrap: {
-    (props: P, context: SetupContext): VNode<_$vue.RendererNode, _$vue.RendererElement, {
+    (props: P, context: SetupContext): _$vue.VNode<_$vue.RendererNode, _$vue.RendererElement, {
       [key: string]: any;
-    }> | VNode<_$vue.RendererNode, _$vue.RendererElement, {
+    }> | _$vue.VNode<_$vue.RendererNode, _$vue.RendererElement, {
       [key: string]: any;
     }>[];
     inheritAttrs: boolean;
@@ -25,30 +21,15 @@ declare function useUnwrap<N = NodeRef, P = Record<string, any>>(propTypes?: Rec
   };
 };
 //#endregion
+//#region src/utils.d.ts
+declare function getNodeElement<N = NodeRef>(node: N): Element | null;
+declare function unwrapVNodes(vnodes: VNodeArrayChildren): VNode[];
+//#endregion
 //#region src/Unwrap.vue.d.ts
-declare const dom: _$vue.ComputedRef<{
-  el: Element | null;
-  children: _$vue.ShallowReactive<NodeRef[]>;
-}>;
-type __VLS_Slots = {
-  default(props: {
-    dom: typeof dom;
-  }): any;
-};
-declare const __VLS_base: _$vue.DefineComponent<{}, {
-  $el: _$vue.ShallowRef<Element | null, Element | null>;
+declare const __VLS_export: _$vue.DefineComponent<{}, {
   children: _$vue.ShallowReactive<NodeRef[]>;
-  dom: _$vue.ComputedRef<{
-    el: Element | null;
-    children: _$vue.ShallowReactive<NodeRef[]>;
-  }>;
+  root: _$vue.ShallowRef<Element | null, Element | null>;
 }, {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {}, string, _$vue.PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, _$vue.ComponentProvideOptions, true, {}, any>;
-declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
-type __VLS_WithSlots<T, S> = T & {
-  new (): {
-    $slots: S;
-  };
-};
 //#endregion
 export { NodeRef, _default as Unwrap, getNodeElement, unwrapVNodes, useUnwrap };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { Comment, Fragment, cloneVNode, computed, createBlock, defineComponent, h, isVNode, openBlock, shallowReactive, shallowRef, unref, useSlots } from "vue";
-//#region src/useUnwrap.ts
+import { Comment, Fragment, cloneVNode, createBlock, defineComponent, h, isVNode, openBlock, shallowReactive, shallowRef, unref, useSlots } from "vue";
+//#region src/utils.ts
 function getNodeElement(node) {
 	const el = node?.$el || node;
 	return el instanceof Element ? el : null;
@@ -18,29 +18,26 @@ function unwrapVNodes(vnodes) {
 	}
 	return nodes;
 }
+//#endregion
+//#region src/useUnwrap.ts
 function useUnwrap(propTypes) {
-	const $el = shallowRef(null);
 	const children = shallowReactive([]);
-	const dom = computed(() => ({
-		el: $el.value,
-		children
-	}));
+	const root = shallowRef(null);
 	const slots = useSlots();
 	const trackChildRef = (index) => (node) => children[index] = node;
-	const trackWrapperRef = (node) => $el.value = getNodeElement(node);
+	const trackRootRef = (node) => root.value = getNodeElement(node);
 	function Unwrap(props, context) {
 		const { is, ...attrs } = context.attrs;
-		const nodes = unwrapVNodes(slots.default?.(props) ?? []).map((node, i) => cloneVNode(node, { ref: trackChildRef(i) }, true));
-		const wrapper = is ? cloneVNode(h(is, attrs, nodes), { ref: trackWrapperRef }, true) : null;
-		children.splice(nodes.length);
-		return wrapper || nodes;
+		const childNodes = unwrapVNodes(slots.default?.(props) ?? []).map((node, i) => cloneVNode(node, { ref: trackChildRef(i) }, true));
+		const rootNode = is ? cloneVNode(h(is, attrs, childNodes), { ref: trackRootRef }, true) : null;
+		children.splice(childNodes.length);
+		return rootNode || childNodes;
 	}
 	Unwrap.inheritAttrs = false;
 	Unwrap.props = { ...propTypes };
 	return {
-		$el,
 		children,
-		dom,
+		root,
 		Unwrap
 	};
 }
@@ -49,14 +46,13 @@ function useUnwrap(propTypes) {
 var Unwrap_default = /* @__PURE__ */ defineComponent({
 	__name: "Unwrap",
 	setup(__props, { expose: __expose }) {
-		const { $el, children, dom, Unwrap } = useUnwrap();
+		const { children, root, Unwrap } = useUnwrap();
 		__expose({
-			$el,
 			children,
-			dom
+			root
 		});
 		return (_ctx, _cache) => {
-			return openBlock(), createBlock(unref(Unwrap), { dom: unref(dom) }, null, 8, ["dom"]);
+			return openBlock(), createBlock(unref(Unwrap));
 		};
 	}
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vue-unwrap",
   "type": "module",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Conditional wrapper component for Vue 3 with child ref aggregation.",
   "author": "Andrea 'Fiad' Fiadone <hello@fiad.one>",
   "license": "MIT",