From b6590ecfe6090a6a9b0bc9dcf40a8b92d082ebe3 Mon Sep 17 00:00:00 2001
From: Thorsten Luenborg <t.luenborg@googlemail.com>
Date: Sun, 18 Dec 2022 16:50:50 +0100
Subject: [PATCH 1/2] feat: new wrapper slots:

- #itemWrapper (each vnode)
- #sourceWrapper (per each portal source)
- #outerWrapper (one wrapper around all content of this portalTarget
---
 docs/api/portal-target.md                     | 109 ++++++++++++--
 .../components/transitions/transitions.vue    |   2 +-
 .../__snapshots__/portal-target.spec.ts.snap  |   5 -
 .../__snapshots__/the-portal.spec.ts.snap     |   5 -
 src/__tests__/portal-target.spec.ts           | 139 ++++++++++++++++--
 src/__tests__/the-portal.spec.ts              |   4 +-
 src/__tests__/wormhole.spec.ts                |   7 +-
 src/components/portal-target.ts               |  64 ++++----
 src/wormhole.ts                               |   4 +-
 9 files changed, 269 insertions(+), 70 deletions(-)
 delete mode 100644 src/__tests__/__snapshots__/portal-target.spec.ts.snap
 delete mode 100644 src/__tests__/__snapshots__/the-portal.spec.ts.snap

diff --git a/docs/api/portal-target.md b/docs/api/portal-target.md
index 13f1c94..cfd32b0 100644
--- a/docs/api/portal-target.md
+++ b/docs/api/portal-target.md
@@ -138,29 +138,116 @@ Example:
 <p>This is rendered when no other content is available.</p>
 ```
 
-### `wrapper`
+### `v-slot:sourceWrapper`
 
-This slot can be used to define markup that should wrap the content received from a `<portal>`. This is usually only useful in combination with [`multiple`](#multiple), as for content from a single portal, you can just wrap the `<portal-target>` as a whole.
+This Slot allows to wrap each individual item from a portal (or `multiple` portals) in additional markup. The slot receives an array of `VNodes`:
+
+```html
+<portal to="wrapped-target">
+  <p>Some inline content</p>
+  <p>Some more content</p>
+</portal>
+
+<portal to="wrapped-target">
+  <p>Some content from a second portal</p>
+</portal>
 
-The slot receives an array as its only prop, which contains the raw vnodes representing the content sent from the source portal(s).
+<div class="flex">
+  <portal-vue to="wrapped-target" multiple>
+    <template v-slot:item-wrapper="nodes">
+      <div class="flex-item">
+        <component v-for="node in nodes" :is="node" />
+      </div>
+    </template>
+  </portal-vue>
+</div>
+```
 
-These vnodes can be rendered with Vue's dynamic component syntax:
+**Result**
+
+```html
+<div class="flex">
+  <div class="flex-item"> <!-- content from first portal wrapped together -->
+    <p>Some inline content</p>
+    <p>Some more content</p>
+  </div>
+  <div class="flex-item"> <!-- content from second portal in a second wrapper -->
+    <p>Some content from a second portal</p>
+  </div>
+    
+</div>
+```
+
+### `v-slot:itemWrapper`
+
+This slot can be used to define markup that should wrap the content received from a `<portal>`. This is usually only useful in combination with [`multiple`](#multiple), as for content from a single portal, you can just wrap the `<portal-target>` as a whole.
+
+The slot receives a single vnode as its only prop. These vnodes can be rendered with Vue's dynamic component syntax:
 
 `<component :is="node">`
 
-Example:
+```html
+<portal to="wrapped-target">
+  <p>Some inline content</p>
+  <p>Some more content</p>
+</portal>
+
+<portal to="wrapped-target">
+  <p>Some content from a second portal</p>
+</portal>
+
+<div class="flex">
+  <portal-vue to="wrapped-target" multiple>
+    <template v-slot:item-wrapper="node">
+      <div class="flex-item"> <!-- will be applied around each individual <p> !! -->
+        <component :is="node" />
+      </div>
+    </template>
+  </portal-vue>
+</div>
+```
+
+**Result**
+
+```html
+<div class="flex">
+  <div class="flex-item">
+    <p>Some inline content</p>
+  </div>
+  <div class="flex-item">
+    <p>Some more content</p>
+  </div>
+  <div class="flex-item">
+    <p>Some content from a second portal</p>
+  </div>
+    
+</div>
+```
+
+### `v-slot:outerWrapper`
+
+This slot is similar to `itemWrapper`, but it will be called only once, and receive *all* vnodes in an array. That allows you to wrap all received content in a shared wrapper element.
+
+Usually, this slot is not very useful as you can instead just put the wrapper around the `<portal-target>`itself. But it's useful for transition groups which would otherwie conflict with the `<portal-target>`'s own root element:
 
-**Source**
-<!-- prettier-ignore -->
 ```html
-<portal-target name="target">
-  <template v-slot:wrapper="nodes">
-    <component :is="node" v-for="node in nodes" />
+<portal-target name="wrapped-with-transition-group" multiple>
+  <template v-slot:outer-wrapper="{ nodes }">
+    <transition-group name="fade">
+      <component v-for="node in nodes" :is="node">
+    </transition-group
   </template>
 </portal-target>
 ```
 
-This slot is also useful to [add transitions (see advanced Guide)](../guide/advanced#transitions ).
+### `v-slot:wrapper` <Badge type="warning">deprecated</Badge>
+
+::: warn This feature is deprecated. Do not use.
+
+This slot has been deprecated in version `3.1` when we introduced to additional slots, in order to provide more clarity in naming. Please use `v-slot:sourceWrapper` instead, which works 100% the same as `v-slot:wrapper` did - or check out the new `v-slot:sourceWrapper` and `v-slot:outerWrapper` slots.
+
+:::
+
 ## Events API
 
 ### `change`
diff --git a/example/components/transitions/transitions.vue b/example/components/transitions/transitions.vue
index 3f27c59..4f5dc71 100644
--- a/example/components/transitions/transitions.vue
+++ b/example/components/transitions/transitions.vue
@@ -43,7 +43,7 @@
 
         <div style="position: relative">
           <portal-target name="group-transition">
-            <template #wrapper="nodes">
+            <template #sourceWrapper="nodes">
               <transition-group name="fade">
                 <component :is="node" v-for="node in nodes" :key="node" />
               </transition-group>
diff --git a/src/__tests__/__snapshots__/portal-target.spec.ts.snap b/src/__tests__/__snapshots__/portal-target.spec.ts.snap
deleted file mode 100644
index cf1a106..0000000
--- a/src/__tests__/__snapshots__/portal-target.spec.ts.snap
+++ /dev/null
@@ -1,5 +0,0 @@
-// Vitest Snapshot v1
-
-exports[`PortalTarget > renders slot content when no other content is available 1`] = `"<p class=\\"default\\">Test</p>"`;
-
-exports[`PortalTarget renders slot content when no other content is available 1`] = `"<p class=\\"default\\">Test</p>"`;
diff --git a/src/__tests__/__snapshots__/the-portal.spec.ts.snap b/src/__tests__/__snapshots__/the-portal.spec.ts.snap
deleted file mode 100644
index 830345a..0000000
--- a/src/__tests__/__snapshots__/the-portal.spec.ts.snap
+++ /dev/null
@@ -1,5 +0,0 @@
-// Vitest Snapshot v1
-
-exports[`Portal > renders locally when \`disabled\` prop is true 1`] = `"<span class=\\"test-span\\">Test</span>"`;
-
-exports[`Portal renders locally when \`disabled\` prop is true 1`] = `"<span class=\\"test-span\\">Test</span>"`;
diff --git a/src/__tests__/portal-target.spec.ts b/src/__tests__/portal-target.spec.ts
index cf68627..b9e1061 100644
--- a/src/__tests__/portal-target.spec.ts
+++ b/src/__tests__/portal-target.spec.ts
@@ -1,5 +1,5 @@
-import { describe, it, expect, vi } from 'vitest'
-import { type Slot, h, nextTick } from 'vue'
+import { describe, it, test, expect, vi } from 'vitest'
+import { type Slot, h, nextTick, type VNode } from 'vue'
 import { mount } from '@vue/test-utils'
 import PortalTarget from '../components/portal-target'
 import { wormholeSymbol } from '../composables/wormhole'
@@ -35,7 +35,7 @@ function createWrapper(props = {}, options = {}) {
 }
 
 function generateSlotFn(text = '') {
-  return (() => h('div', { class: 'testnode' }, text) as unknown) as Slot
+  return (() => [h('div', { class: 'testnode' }, text) as unknown]) as Slot
 }
 
 describe('PortalTarget', () => {
@@ -50,22 +50,26 @@ describe('PortalTarget', () => {
 
     await nextTick()
 
-    expect(wrapper.html()).toBe(
-      `<div style="display: none;"></div>
-<div class="testnode"></div>`
+    expect(wrapper.html()).toMatchInlineSnapshot(
+      `
+      "<div style=\\"display: none;\\"></div>
+      <div class=\\"testnode\\"></div>"
+    `
     )
   })
 
-  it('renders slot content when no other content is available', function () {
+  it('renders default slot content when no other content is available', function () {
     const { wrapper } = createWrapper(
       {},
       {
         slots: {
-          default: h('p', { class: 'default' }, 'Test'),
+          default: () => [h('p', { class: 'default' }, 'Test')],
         },
       }
     )
-    expect(wrapper.html()).toMatchSnapshot()
+    expect(wrapper.html()).toMatchInlineSnapshot(
+      '"<p class=\\"default\\">Test</p>"'
+    )
     expect(wrapper.find('p.default').exists()).toBe(true)
   })
 
@@ -90,4 +94,121 @@ describe('PortalTarget', () => {
       },
     ])
   })
+
+  describe('Wrapper slots', () => {
+    test('v-slot:itemWrapper', async () => {
+      const { wrapper, wh } = createWrapper(
+        {
+          multiple: true,
+        },
+        {
+          slots: {
+            itemWrapper: (nodes: VNode[]) => [
+              h('div', { class: 'itemWrapper' }, nodes),
+            ],
+          },
+        }
+      )
+      wh.open({
+        from: 'source1',
+        to: 'target',
+        content: () => [
+          h('div', { class: 'testnode' }, 'source1-1'),
+          h('div', { class: 'testnode' }, 'source1-2'),
+        ],
+      })
+      wh.open({
+        from: 'source2',
+        to: 'target',
+        content: generateSlotFn('source2'),
+      })
+
+      await nextTick()
+
+      expect(wrapper.html()).toMatchInlineSnapshot(`
+        "<div style=\\"display: none;\\"></div>
+        <div class=\\"itemWrapper\\">
+          <div class=\\"testnode\\">source1-1</div>
+        </div>
+        <div class=\\"itemWrapper\\">
+          <div class=\\"testnode\\">source1-2</div>
+        </div>
+        <div class=\\"itemWrapper\\">
+          <div class=\\"testnode\\">source2</div>
+        </div>"
+      `)
+    })
+
+    test('v-slot:sourceWrapper', async () => {
+      const { wrapper, wh } = createWrapper(
+        {
+          multiple: true,
+        },
+        {
+          slots: {
+            sourceWrapper: (nodes: VNode[]) => [
+              h('div', { class: 'sourceWrapper' }, nodes),
+            ],
+          },
+        }
+      )
+      wh.open({
+        from: 'source1',
+        to: 'target',
+        content: generateSlotFn('source1'),
+      })
+      wh.open({
+        from: 'source2',
+        to: 'target',
+        content: generateSlotFn('source2'),
+      })
+
+      await nextTick()
+
+      expect(wrapper.html()).toMatchInlineSnapshot(`
+        "<div style=\\"display: none;\\"></div>
+        <div class=\\"sourceWrapper\\">
+          <div class=\\"testnode\\">source1</div>
+        </div>
+        <div class=\\"sourceWrapper\\">
+          <div class=\\"testnode\\">source2</div>
+        </div>"
+      `)
+    })
+
+    test('v-slot:outerWrapper', async () => {
+      const { wrapper, wh } = createWrapper(
+        {
+          multiple: true,
+        },
+        {
+          slots: {
+            outerWrapper: (nodes: VNode[]) => [
+              h('div', { class: 'outerWrapper' }, nodes),
+            ],
+          },
+        }
+      )
+      wh.open({
+        from: 'source1',
+        to: 'target',
+        content: generateSlotFn('source1'),
+      })
+      wh.open({
+        from: 'source2',
+        to: 'target',
+        content: generateSlotFn('source2'),
+      })
+
+      await nextTick()
+
+      expect(wrapper.html()).toMatchInlineSnapshot(`
+        "<div style=\\"display: none;\\"></div>
+        <div class=\\"outerWrapper\\">
+          <div class=\\"testnode\\">source1</div>
+          <div class=\\"testnode\\">source2</div>
+        </div>"
+      `)
+    })
+  })
 })
diff --git a/src/__tests__/the-portal.spec.ts b/src/__tests__/the-portal.spec.ts
index 951d506..0e725f4 100644
--- a/src/__tests__/the-portal.spec.ts
+++ b/src/__tests__/the-portal.spec.ts
@@ -76,6 +76,8 @@ describe('Portal', function () {
   it('renders locally when `disabled` prop is true', () => {
     const { wrapper } = createWrapper({ disabled: true })
     expect(wrapper.find('span').exists()).toBe(true)
-    expect(wrapper.html()).toMatchSnapshot()
+    expect(wrapper.html()).toMatchInlineSnapshot(
+      '"<span class=\\"test-span\\">Test</span>"'
+    )
   })
 })
diff --git a/src/__tests__/wormhole.spec.ts b/src/__tests__/wormhole.spec.ts
index 6e13854..eb9d1ef 100644
--- a/src/__tests__/wormhole.spec.ts
+++ b/src/__tests__/wormhole.spec.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { Slot, h } from 'vue'
+import { type Slot, h } from 'vue'
 import { createWormhole } from '@/wormhole'
 
 const createSlotFn = () => (() => h('div')) as unknown as Slot
@@ -32,7 +32,10 @@ describe('Wormhole', () => {
 
     wormhole.open(content)
     expect(wormhole.transports.get('target')?.get('test-portal')).toMatchObject(
-      content
+      {
+        ...content,
+        content: expect.any(Function),
+      }
     )
 
     wormhole.close({
diff --git a/src/components/portal-target.ts b/src/components/portal-target.ts
index f7f3eb0..ae43010 100644
--- a/src/components/portal-target.ts
+++ b/src/components/portal-target.ts
@@ -1,10 +1,9 @@
 import {
   type FunctionalComponent,
   type VNode,
-  computed,
   defineComponent,
   h,
-  watch,
+  onMounted,
 } from 'vue'
 import { useWormhole } from '../composables/wormhole'
 
@@ -23,39 +22,36 @@ export default defineComponent({
   emits: ['change'],
   setup(props, { emit, slots }) {
     const wormhole = useWormhole()
+    let mounted = false
+    const slotVnodes = () => {
+      const transports = wormhole.getContentForTarget(
+        props.name,
+        props.multiple
+      )
+      const sourceWrapperSlot = slots.sourceWrapper ?? slots.wrapper
+      let vnodes = transports
+        .map((t) => {
+          const content = t
+            .content(props.slotProps)
+            .map((vnode) => slots.itemWrapper?.(vnode)[0] ?? vnode)
+          return sourceWrapperSlot ? sourceWrapperSlot(content) : content
+        })
+        .flat(1)
+      vnodes = slots.outerWrapper ? slots.outerWrapper(vnodes) : vnodes
+      mounted && emitSlotChange(vnodes)
+      return vnodes
+    }
 
-    const slotVnodes = computed<{ vnodes: VNode[]; vnodesFn: () => VNode[] }>(
-      () => {
-        const transports = wormhole.getContentForTarget(
-          props.name,
-          props.multiple
-        )
-        const wrapperSlot = slots.wrapper
-        const rawNodes = transports.map((t) => t.content(props.slotProps))
-        const vnodes = wrapperSlot
-          ? rawNodes.flatMap((nodes) =>
-              nodes.length ? wrapperSlot(nodes) : []
-            )
-          : rawNodes.flat(1)
-        return {
-          vnodes,
-          vnodesFn: () => vnodes, // just to make Vue happy. raw vnodes in a slot give a DEV warning
-        }
-      }
-    )
-
-    watch(
-      slotVnodes,
-      ({ vnodes }) => {
-        const hasContent = vnodes.length > 0
-        const content = wormhole.transports.get(props.name)
-        const sources = content ? [...content.keys()] : []
-        emit('change', { hasContent, sources })
-      },
-      { flush: 'post' }
-    )
+    const emitSlotChange = (vnodes: VNode[]) => {
+      const hasContent = vnodes.length > 0
+      const content = wormhole.transports.get(props.name)
+      const sources = content ? [...content.keys()] : []
+      emit('change', { hasContent, sources })
+    }
+    onMounted(() => (mounted = true))
     return () => {
-      const hasContent = !!slotVnodes.value.vnodes.length
+      const vnodes = slotVnodes()
+      const hasContent = !!vnodes.length
       if (hasContent) {
         return [
           // this node is a necessary hack to force Vue to change the scoped-styles boundary
@@ -67,7 +63,7 @@ export default defineComponent({
           // we wrap the slot content in a functional component
           // so that transitions in the slot can properly determine first render
           // for `appear` behavior to work properly
-          h(PortalTargetContent, slotVnodes.value.vnodesFn),
+          h(PortalTargetContent, () => vnodes),
         ]
       } else {
         return slots.default?.()
diff --git a/src/wormhole.ts b/src/wormhole.ts
index d7dcac0..6b3b710 100644
--- a/src/wormhole.ts
+++ b/src/wormhole.ts
@@ -1,4 +1,4 @@
-import { reactive, readonly } from 'vue'
+import { reactive, readonly, type VNode } from 'vue'
 import type {
   Name,
   Transport,
@@ -26,7 +26,7 @@ export function createWormhole(asReadonly = true): Wormhole {
     const newTransport = {
       to,
       from,
-      content,
+      content: (...args) => ([] as VNode[]).concat(content(...args)),
       order,
     } as Transport
 

From 5a869eea868b8589edde84887bca6e365a6d0ab2 Mon Sep 17 00:00:00 2001
From: Thorsten Luenborg <t.luenborg@googlemail.com>
Date: Sun, 18 Dec 2022 17:10:54 +0100
Subject: [PATCH 2/2] docs: adjust advanced section in guide to use
 outerWrapper slot

---
 docs/guide/advanced.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/guide/advanced.md b/docs/guide/advanced.md
index 5a5f6ca..96ab53a 100644
--- a/docs/guide/advanced.md
+++ b/docs/guide/advanced.md
@@ -61,12 +61,13 @@ You can pass transitions to a `<portal>` without problems. It will behave just t
 ```
 
 However, if you use a `<portal-target>` for multiple `<portal>`s, you likely want to define the transition on the target end instead. This is also supported.
+
 #### PortalTarget Transitions
 
 <!-- prettier-ignore -->
 ```html
 <portal-target name="target">
-  <template v-slot:default="nodes">
+  <template v-slot:outerWrapper="nodes">
     <transition name="fade" mode="out-in">
       <component :is="nodes[0]" />
     </transition>
@@ -76,7 +77,7 @@ However, if you use a `<portal-target>` for multiple `<portal>`s, you likely wan
 
 Transitions for Targets underwent a redesign in PortalVue `3.0`. The new syntax is admittedly a bit more verbose and has a hack-ish feel to it, but it's a valid use of Vue's v-slot syntax and was necessary to get rid of some nasty edge cases with target Transitions that we had in PortalVue `2.*`.
 
-Basically, you pass a transition to a slot named `wrapper` and get an array called `nodes` from its slot props.
+Basically, you pass a transition to a [slot named `outerWrapper`](../api/portal-target.md#v-slot-outerwrapper) and get an array called `nodes` from its slot props.
 
 You can the use Vue'S `<component :is="">` to turn those into the content of the transition.
 
@@ -85,7 +86,7 @@ Here's a second example, using a `<transition-group>` instead:
 <!-- prettier-ignore -->
 ```html
 <portal-target name="target">
-  <template #default="nodes">
+  <template #outerWrapper="nodes">
     <transition-group name="fade">
       <component :is="node" v-for="node in nodes" :key="node" />
     </transition-group>