feat(migration): transition-group (close #648)

src/api/built-in-components.md

@@ -107,7 +107,7 @@
 
 - **Props:**
 
-  - `tag` - `string`, defaults to `span`.
+  - `tag` - `string`, if not defined, renders without a root element.
   - `move-class` - overwrite CSS class applied during moving transition.
   - exposes the same props as `<transition>` except `mode`.
 
@@ -117,7 +117,7 @@
 
 - **Usage:**
 
-  `<transition-group>` serve as transition effects for **multiple** elements/components. The `<transition-group>` renders a real DOM element. By default it renders a `<span>`, and you can configure what element it should render via the `tag` attribute.
+  `<transition-group>` provides transition effects for **multiple** elements/components. By default it doesn't render a wrapper DOM element, but one can be defined via the `tag` attribute.
 
   Note that every child in a `<transition-group>` must be [**uniquely keyed**](./special-attributes.html#key) for the animations to work properly.
 

src/guide/migration/introduction.md

@@ -101,6 +101,7 @@ The following consists a list of breaking changes from 2.x:
 - [The `data` option from mixins is now merged shallowly](/guide/migration/data-option.html#mixin-merge-behavior-change)
 - [Attributes coercion strategy changed](/guide/migration/attribute-coercion.html)
 - [Some transition classes got a rename](/guide/migration/transition.html)
+- [`<TransitionGroup>` now renders no wrapper element by default](/guide/migration/transition-group.html)
 - [When watching an array, the callback will only trigger when the array is replaced. If you need to trigger on mutation, the `deep` option must be specified.](/guide/migration/watch.html)
 - `<template>` tags with no special directives (`v-if/else-if/else`, `v-for`, or `v-slot`) are now treated as plain elements and will result in a native `<template>` element instead of rendering its inner content.
 - In Vue 2.x, application root container's `outerHTML` is replaced with root component template (or eventually compiled to a template, if root component has no template/render option). Vue 3.x now uses application container's `innerHTML` instead - this means the container itself is no longer considered part of the template.

src/guide/migration/transition-group.md

@@ -0,0 +1,40 @@
+---
+title: Transition Group root Element
+badges:
+  - breaking
+---
+
+# {{ $frontmatter.title }} <MigrationBadges :badges="$frontmatter.badges" />
+
+## Overview
+
+`<transition-group>` no longer renders a root element by default, but can still create one with the `tag` prop.
+
+## 2.x Syntax
+
+In Vue 2, `<transition-group>`, like other custom components, needed a root element, which by default was a `<span>` but was customizable via the `tag` prop.
+
+```html
+<transition-group tag="ul">
+  <li v-for="item in items" :key="item">
+    {{ item }}
+  </li>
+</transition-group>
+```
+
+## 3.x Syntax
+
+In Vue 3, we have [fragment support](/guide/migration/fragments.html), so components no longer _need_ a root node. Consequently, `<transition-group>` no longer renders one by default.
+
+- If you already have the `tag` prop defined in your Vue 2 code, like in the example above, everything will work as before
+- If you didn't have one defined _and_ your styling or other behaviors relied on the presence of the `<span>` root element to work properly, simply add `tag="span"` to the `<transition-group>`:
+
+```html
+<transition-group tag="span">
+  <!-- -->
+</transition-group>
+```
+
+## See also
+
+- [Some transition classes got a rename](/guide/migration/transition.html)

src/guide/migration/transition.md

@@ -59,4 +59,8 @@ The `<transition>` component's related prop names are also changed:
 
 1. Replace instances of `.v-enter` to `.v-enter-from`
 2. Replace instances of `.v-leave` to `.v-leave-from`
-3. Replace instances of related prop names, as above.
+3. Replace instances of related prop names, as above.
+
+## See also
+
+- [`<TransitionGroup>` now renders no wrapper element by default](/guide/migration/transition-group.html)

src/guide/transitions-list.md

@@ -7,7 +7,7 @@ So far, we've managed transitions for:
 
 So what about for when we have a whole list of items we want to render simultaneously, for example with `v-for`? In this case, we'll use the `<transition-group>` component. Before we dive into an example though, there are a few things that are important to know about this component:
 
-- Unlike `<transition>`, it renders an actual element: a `<span>` by default. You can change the element that's rendered with the `tag` attribute.
+- By default, it doesn't render a wrapper element, but you can specify an element to be rendered with the `tag` attribute.
 - [Transition modes](/guide/transitions-enterleave#transition-modes) are not available, because we are no longer alternating between mutually exclusive elements.
 - Elements inside are **always required** to have a unique `key` attribute.
 - CSS transition classes will be applied to inner elements and not to the group/container itself.