vue-unwrap 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# vue-unwrap
+
+Less wrappers, more control!
+
+## What/why
+
+When building reusable Vue components, it is common to encapsulate logic that needs access to the rendered DOM of its children — whether to observe layout changes, measure elements, coordinate animations/interactions, or perform low-level DOM operations.
+
+In many cases, this creates an awkward tradeoff: either manually coordinate refs across component boundaries, or introduce an extra wrapper element purely as an implementation detail.
+
+Neither option is ideal.
+
+__Unwrap__ is a conditional wrapper component for Vue 3 with child ref aggregation that removes that friction by making child DOM access predictable while keeping wrapper elements optional. Components can stay focused on behavior rather than structure, avoiding unnecessary DOM nodes unless they are actually required.
+
+The result is cleaner markup, simpler reusable abstractions, and more control over how components render.
+
+## Getting started
+
+```bash
+npm i vue-unwrap@latest
+```
+
+## Basic usage
+
+### With Unwrap component
+
+```vue
+<script setup lang="ts">
+import { computed, useTemplateRef } from 'vue'
+import { getNodeElement, Unwrap } from 'vue-unwrap'
+
+const ctx = useTemplateRef<typeof Unwrap>('ctx')
+
+const $children = computed(() => ctx.value?.children.map(getNodeElement))
+</script>
+
+<template>
+  <Unwrap ref="ctx" />
+</template>
+
+```
+
+### With useUnwrap composable (for more control)
+
+```vue
+<script setup lang="ts">
+import type { ComponentPublicInstance } from 'vue'
+import { useUnwrap } from 'vue-unwrap'
+
+// your component props definition
+type PropsType = { foo: string } 
+
+// your child nodes definition
+type CustomNodeType = (
+  | ComponentPublicInstance<{ bar: string }>
+  | ComponentPublicInstance
+  | Element
+  | null
+)
+
+const props = defineProps<PropsType>()
+
+const { $el, children, Unwrap } = useUnwrap<CustomNodeType, PropsType>()
+
+const bars = computed(() => (
+  children?
+    .map(child => (
+      (child && 'bar' in child)
+        ? `${props.foo}-${child.bar}`
+        : undefined
+    ))
+    .filter(Boolean)
+))
+</script>
+
+<template>
+  <Unwrap is="div" />
+</template>
+
+```
+
+## Development
+
+- Install dependencies:
+
+```bash
+npm install
+```
+
+- Run the playground:
+
+```bash
+npm run playground
+```
+
+- Run the unit tests:
+
+```bash
+npm run test
+```
+
+- Build the library:
+
+```bash
+npm run build
+```

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import * as _$vue from "vue";
+import { ComponentPublicInstance, SetupContext } from "vue";
+
+//#region src/useUnwrap.d.ts
+type NodeRef = Element | ComponentPublicInstance | null;
+declare function getNodeElement<N = NodeRef>(node: N): Element | null;
+declare function useUnwrap<N = NodeRef, P = Record<string, any>>(propTypes?: Record<string, any>): {
+  $el: _$vue.ShallowRef<Element | null, Element | null>;
+  children: _$vue.ShallowReactive<N[]>;
+  Unwrap: {
+    (props: P, context: SetupContext): _$vue.VNode<_$vue.RendererNode, _$vue.RendererElement, {
+      [key: string]: any;
+    }> | _$vue.VNode<_$vue.RendererNode, _$vue.RendererElement, {
+      [key: string]: any;
+    }>[];
+    inheritAttrs: boolean;
+    props: {
+      [x: string]: any;
+    };
+  };
+};
+//#endregion
+//#region src/Unwrap.vue.d.ts
+declare const __VLS_export: _$vue.DefineComponent<{}, {
+  $el: _$vue.ShallowRef<Element | null, Element | null>;
+  children: _$vue.ShallowReactive<NodeRef[]>;
+}, {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {}, string, _$vue.PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, _$vue.ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+//#endregion
+export { NodeRef, _default as Unwrap, getNodeElement, useUnwrap };

package/dist/index.js

@@ -0,0 +1,44 @@
+import { cloneVNode, createBlock, defineComponent, h, openBlock, shallowReactive, shallowRef, unref, useSlots } from "vue";
+//#region src/useUnwrap.ts
+function getNodeElement(node) {
+	const el = node?.$el || node;
+	return el instanceof Element ? el : null;
+}
+function useUnwrap(propTypes) {
+	const $el = shallowRef(null);
+	const children = shallowReactive([]);
+	const slots = useSlots();
+	const trackChildRef = (index) => (node) => children[index] = node;
+	const trackWrapperRef = (node) => $el.value = getNodeElement(node);
+	function Unwrap(props, context) {
+		const { is, ...attrs } = context.attrs;
+		const nodes = (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;
+	}
+	Unwrap.inheritAttrs = false;
+	Unwrap.props = { ...propTypes };
+	return {
+		$el,
+		children,
+		Unwrap
+	};
+}
+//#endregion
+//#region src/Unwrap.vue
+var Unwrap_default = /* @__PURE__ */ defineComponent({
+	__name: "Unwrap",
+	setup(__props, { expose: __expose }) {
+		const { $el, children, Unwrap } = useUnwrap();
+		__expose({
+			$el,
+			children
+		});
+		return (_ctx, _cache) => {
+			return openBlock(), createBlock(unref(Unwrap));
+		};
+	}
+});
+//#endregion
+export { Unwrap_default as Unwrap, getNodeElement, useUnwrap };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "vue-unwrap",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Conditional wrapper component for Vue 3 with child ref aggregation.",
+  "author": "Andrea 'Fiad' Fiadone <hello@fiad.one>",
+  "license": "MIT",
+  "homepage": "https://github.com/fiadone/vue-unwrap#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fiadone/vue-unwrap.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fiadone/vue-unwrap/issues"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "play": "vite",
+    "test": "vitest",
+    "typecheck": "vue-tsc --noEmit",
+    "release": "bumpp",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@tsdown/css": "^0.22.0",
+    "@types/node": "^25.6.2",
+    "@vitejs/plugin-vue": "^6.0.6",
+    "@vitest/browser-playwright": "^4.1.5",
+    "bumpp": "^11.1.0",
+    "commitizen": "^4.3.1",
+    "cz-conventional-changelog": "^3.3.0",
+    "playwright": "^1.59.1",
+    "semantic-release": "^25.0.3",
+    "tsdown": "^0.22.0",
+    "typescript": "^6.0.3",
+    "unrun": "^0.2.39",
+    "vite": "^8.0.11",
+    "vitest": "^4.1.5",
+    "vitest-browser-vue": "^2.1.0",
+    "vue": "^3.5.34",
+    "vue-tsc": "^3.2.8"
+  }
+}