@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/transition-group-flip-inline-elements.md

@@ -0,0 +1,152 @@
+---
+title: TransitionGroup FLIP Animations Do Not Work With Inline Elements
+impact: MEDIUM
+impactDescription: Move animations silently fail on inline elements, causing items to jump
+type: gotcha
+tags: [vue3, transition-group, animation, flip, css, display, inline-block]
+---
+
+# TransitionGroup FLIP Animations Do Not Work With Inline Elements
+
+**Impact: MEDIUM** - The FLIP (First, Last, Invert, Play) animation technique that Vue uses for `<TransitionGroup>` move transitions does not work with elements that have `display: inline`. The move animation will silently fail, and items will jump to their new positions instead of smoothly transitioning.
+
+This is a CSS limitation, not a Vue bug. CSS transforms (which FLIP uses internally) do not apply to inline elements per the CSS specification.
+
+## Task Checklist
+
+- [ ] Ensure list items are not `display: inline` elements
+- [ ] Use `display: inline-block` or `display: block` for list items
+- [ ] Use flexbox or grid containers which make children block-level
+- [ ] Check if inherited styles are setting `display: inline`
+
+**Incorrect - Inline elements break move animations:**
+```vue
+<template>
+  <!-- BROKEN: span elements are inline by default -->
+  <TransitionGroup name="tag" tag="div" class="tag-container">
+    <span v-for="tag in tags" :key="tag.id" class="tag">
+      {{ tag.name }}
+    </span>
+  </TransitionGroup>
+</template>
+
+<style>
+.tag-move {
+  transition: transform 0.3s ease;
+  /* This won't work because spans are inline! */
+}
+</style>
+```
+
+**Correct - Use inline-block:**
+```vue
+<template>
+  <TransitionGroup name="tag" tag="div" class="tag-container">
+    <span v-for="tag in tags" :key="tag.id" class="tag">
+      {{ tag.name }}
+    </span>
+  </TransitionGroup>
+</template>
+
+<style>
+.tag {
+  display: inline-block; /* REQUIRED for FLIP animations */
+}
+
+.tag-move {
+  transition: transform 0.3s ease;
+}
+</style>
+```
+
+**Correct - Use flexbox container:**
+```vue
+<template>
+  <TransitionGroup name="tag" tag="div" class="tag-container">
+    <span v-for="tag in tags" :key="tag.id" class="tag">
+      {{ tag.name }}
+    </span>
+  </TransitionGroup>
+</template>
+
+<style>
+.tag-container {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+/* Flex children are block-level, FLIP works automatically */
+.tag-move {
+  transition: transform 0.3s ease;
+}
+</style>
+```
+
+**Correct - Use block elements:**
+```vue
+<template>
+  <!-- div elements are block by default -->
+  <TransitionGroup name="item" tag="div">
+    <div v-for="item in items" :key="item.id" class="item">
+      {{ item.name }}
+    </div>
+  </TransitionGroup>
+</template>
+
+<style>
+.item-move {
+  transition: transform 0.3s ease;
+}
+</style>
+```
+
+## Why Inline Elements Don't Work
+
+Per CSS specifications, the `transform` property does not apply to inline boxes. Since FLIP animations use CSS transforms to animate element positions:
+
+```css
+/* Vue internally applies something like this during move */
+.item {
+  transform: translateX(-50px) translateY(-20px);
+  /* Then transitions to transform: none */
+}
+```
+
+This transform is ignored on inline elements, so no animation occurs.
+
+## Elements That Are Inline by Default
+
+Be aware of these common inline elements that need `display: inline-block`:
+
+- `<span>`
+- `<a>`
+- `<em>`, `<strong>`, `<i>`, `<b>`
+- `<code>`, `<kbd>`
+- `<label>`
+- `<button>` (inline-block by default, but verify)
+
+## Move Animations Also Require Transform Transition
+
+The `.move` class must have `transform` in its `transition` property:
+
+```css
+/* CORRECT */
+.list-move {
+  transition: transform 0.3s ease;
+}
+
+/* ALSO CORRECT */
+.list-move {
+  transition: all 0.3s ease; /* 'all' includes transform */
+}
+
+/* WRONG - transform not included */
+.list-move {
+  transition: opacity 0.3s ease; /* Move won't animate! */
+}
+```
+
+## Reference
+- [Vue.js TransitionGroup Move Transitions](https://vuejs.org/guide/built-ins/transition-group.html#move-transitions)
+- [MDN CSS Transform - Formal Definition](https://developer.mozilla.org/en-US/docs/Web/CSS/transform#formal_definition)

package/skills/vue-debug-guides/reference/transition-group-move-animation-position-absolute.md

@@ -0,0 +1,130 @@
+---
+title: TransitionGroup Move Animation Requires Position Absolute on Leaving Items
+impact: HIGH
+impactDescription: Without position absolute, surrounding items jump instead of smoothly animating
+type: gotcha
+tags: [vue3, transition-group, animation, move-transition, css, list-animation]
+---
+
+# TransitionGroup Move Animation Requires Position Absolute on Leaving Items
+
+**Impact: HIGH** - When items are added or removed from a list with `<TransitionGroup>`, surrounding items will instantly "jump" to their new positions instead of smoothly animating. This creates a jarring user experience and is one of the most common mistakes with list animations.
+
+The fix is to set `position: absolute` on the `leave-active` class so leaving items are taken out of the layout flow, allowing other items to smoothly animate into their new positions.
+
+## Task Checklist
+
+- [ ] Add `.list-move` class (or `.[name]-move`) for smooth repositioning
+- [ ] Set `position: absolute` on `.list-leave-active` class
+- [ ] Ensure the parent container has `position: relative` if needed
+- [ ] Test with rapid add/remove operations to verify smooth animations
+
+**Incorrect - Items jump instead of moving:**
+```vue
+<template>
+  <TransitionGroup name="list" tag="ul">
+    <li v-for="item in items" :key="item.id">
+      {{ item.name }}
+    </li>
+  </TransitionGroup>
+</template>
+
+<style>
+/* INCOMPLETE: Missing move class and position absolute */
+.list-enter-active,
+.list-leave-active {
+  transition: all 0.5s ease;
+}
+
+.list-enter-from,
+.list-leave-to {
+  opacity: 0;
+  transform: translateX(30px);
+}
+</style>
+```
+
+**Correct - Smooth move transitions:**
+```vue
+<template>
+  <TransitionGroup name="list" tag="ul">
+    <li v-for="item in items" :key="item.id">
+      {{ item.name }}
+    </li>
+  </TransitionGroup>
+</template>
+
+<style>
+/* CORRECT: Full set of classes for smooth animations */
+
+/* Apply transition to moving elements */
+.list-move,
+.list-enter-active,
+.list-leave-active {
+  transition: all 0.5s ease;
+}
+
+.list-enter-from,
+.list-leave-to {
+  opacity: 0;
+  transform: translateX(30px);
+}
+
+/* CRITICAL: Take leaving items out of layout flow */
+.list-leave-active {
+  position: absolute;
+}
+</style>
+```
+
+## Why This Works
+
+The FLIP animation technique Vue uses internally needs to calculate element positions. When an item leaves:
+
+1. Without `position: absolute`: The leaving item still occupies space in the DOM
+2. Other items can't move until the leaving item is fully removed
+3. Result: Items snap to new positions after leave animation completes
+
+With `position: absolute`:
+
+1. Leaving item is removed from normal layout flow immediately
+2. Other items can begin moving into the vacated space
+3. Result: Leaving animation and move animation happen simultaneously
+
+## Visual Diagram
+
+```
+Without position: absolute:
+[A] [B] [C] [D]  <- Remove B
+[A]     [C] [D]  <- B fading out, C/D waiting
+[A] [C] [D]      <- B gone, C/D jump instantly
+
+With position: absolute:
+[A] [B] [C] [D]  <- Remove B
+[A][B][C] [D]    <- B fading (absolute), C/D sliding left
+[A] [C] [D]      <- Smooth completion
+```
+
+## Additional Considerations
+
+**Container Width:** When using `position: absolute`, items may need explicit widths:
+
+```css
+.list-leave-active {
+  position: absolute;
+  width: 100%; /* Or specific width to maintain layout during leave */
+}
+```
+
+**Stacking Context:** Leaving items with `position: absolute` may stack above other elements:
+
+```css
+.list-leave-active {
+  position: absolute;
+  z-index: -1; /* Optional: put behind other items */
+}
+```
+
+## Reference
+- [Vue.js TransitionGroup Move Transitions](https://vuejs.org/guide/built-ins/transition-group.html#move-transitions)
+- [FLIP Animation Technique](https://aerotwist.com/blog/flip-your-animations/)

package/skills/vue-debug-guides/reference/transition-group-no-default-wrapper-vue3.md

@@ -0,0 +1,152 @@
+---
+title: TransitionGroup No Longer Renders Default Wrapper Element in Vue 3
+impact: MEDIUM
+impactDescription: Vue 2 to Vue 3 migration may break layouts relying on the default span wrapper
+type: gotcha
+tags: [vue3, transition-group, migration, vue2, breaking-change, wrapper-element]
+---
+
+# TransitionGroup No Longer Renders Default Wrapper Element in Vue 3
+
+**Impact: MEDIUM** - In Vue 2, `<transition-group>` always rendered a wrapper element (default `<span>`), but in Vue 3, it renders no wrapper element by default thanks to fragment support. This breaking change can cause layout issues and broken styles when migrating from Vue 2.
+
+If your code relies on the wrapper element for styling or layout, you must explicitly specify the `tag` prop in Vue 3.
+
+## Task Checklist
+
+- [ ] When migrating from Vue 2, add explicit `tag` prop to all `<TransitionGroup>` components
+- [ ] Review CSS selectors that targeted the wrapper element
+- [ ] Update parent component styles that expected a wrapper element
+- [ ] Consider if the wrapper element is actually needed in Vue 3
+
+**Vue 2 Behavior (wrapper element by default):**
+```vue
+<template>
+  <transition-group name="list">
+    <div v-for="item in items" :key="item.id">{{ item }}</div>
+  </transition-group>
+</template>
+
+<!-- Renders as: -->
+<span>  <!-- Default wrapper in Vue 2 -->
+  <div>Item 1</div>
+  <div>Item 2</div>
+</span>
+```
+
+**Vue 3 Behavior (no wrapper by default):**
+```vue
+<template>
+  <TransitionGroup name="list">
+    <div v-for="item in items" :key="item.id">{{ item }}</div>
+  </TransitionGroup>
+</template>
+
+<!-- Renders as (fragment): -->
+<div>Item 1</div>
+<div>Item 2</div>
+<!-- No wrapper element! -->
+```
+
+**Vue 3 - Explicitly specify wrapper:**
+```vue
+<template>
+  <!-- Use tag prop to specify wrapper element -->
+  <TransitionGroup name="list" tag="ul">
+    <li v-for="item in items" :key="item.id">{{ item }}</li>
+  </TransitionGroup>
+</template>
+
+<!-- Renders as: -->
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+</ul>
+```
+
+## Migration Scenarios
+
+### Layout Depending on Wrapper
+
+**Vue 2 code that breaks in Vue 3:**
+```vue
+<template>
+  <transition-group class="grid-container" name="list">
+    <div v-for="item in items" :key="item.id">{{ item }}</div>
+  </transition-group>
+</template>
+
+<style>
+.grid-container {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+}
+</style>
+```
+
+In Vue 3, the class is not applied to anything because there's no wrapper element.
+
+**Fixed for Vue 3:**
+```vue
+<template>
+  <TransitionGroup class="grid-container" name="list" tag="div">
+    <div v-for="item in items" :key="item.id">{{ item }}</div>
+  </TransitionGroup>
+</template>
+```
+
+### Semantic HTML Lists
+
+**Vue 2:**
+```vue
+<transition-group tag="ul" name="list">
+  <li v-for="item in items" :key="item.id">{{ item }}</li>
+</transition-group>
+```
+
+**Vue 3 (same syntax, but now tag is more important):**
+```vue
+<TransitionGroup tag="ul" name="list">
+  <li v-for="item in items" :key="item.id">{{ item }}</li>
+</TransitionGroup>
+```
+
+### When You Don't Need a Wrapper
+
+Vue 3's fragment support means you might not need a wrapper at all:
+
+```vue
+<template>
+  <div class="parent-with-styles">
+    <!-- No tag needed if parent handles layout -->
+    <TransitionGroup name="fade">
+      <span v-for="item in items" :key="item.id">{{ item }}</span>
+    </TransitionGroup>
+  </div>
+</template>
+
+<style>
+.parent-with-styles {
+  display: flex;
+  gap: 8px;
+}
+</style>
+```
+
+## In-DOM Template Syntax
+
+When using in-DOM templates (not SFCs), remember to use kebab-case:
+
+```html
+<!-- In-DOM template -->
+<transition-group tag="ul" name="list">
+  <li v-for="item in items" :key="item.id">{{ item }}</li>
+</transition-group>
+
+<!-- NOT -->
+<TransitionGroup tag="ul" name="list">  <!-- Won't work in DOM templates -->
+```
+
+## Reference
+- [Vue 3 Migration Guide - TransitionGroup Root Element](https://v3-migration.vuejs.org/breaking-changes/transition-group.html)
+- [Vue.js TransitionGroup](https://vuejs.org/guide/built-ins/transition-group.html)

package/skills/vue-debug-guides/reference/transition-js-hooks-done-callback.md

@@ -0,0 +1,251 @@
+---
+title: JavaScript Transition Hooks Require done() Callback with css="false"
+impact: HIGH
+impactDescription: Without calling done(), JavaScript-only transitions complete immediately, skipping the animation entirely
+type: gotcha
+tags: [vue3, transition, javascript, animation, hooks, gsap, done-callback]
+---
+
+# JavaScript Transition Hooks Require done() Callback with css="false"
+
+**Impact: HIGH** - When using JavaScript-only transitions (with `:css="false"`), the `@enter` and `@leave` hooks **must** call the `done()` callback to signal when the animation completes. Without calling `done()`, Vue considers the transition finished immediately, causing elements to appear/disappear without animation.
+
+This is especially important when using animation libraries like GSAP, Anime.js, or the Web Animations API.
+
+## Task Checklist
+
+- [ ] When using `:css="false"`, always call `done()` in `@enter` and `@leave` hooks
+- [ ] Call `done()` when your JavaScript animation completes (in the `onComplete` callback)
+- [ ] Remember: `done()` is optional when CSS handles the transition, but **required** with `:css="false"`
+- [ ] Use `:css="false"` to prevent CSS rules from interfering with JS animations
+
+**Problematic Code:**
+```vue
+<template>
+  <!-- BAD: No done() callback - animation is skipped! -->
+  <Transition :css="false" @enter="onEnter" @leave="onLeave">
+    <div v-if="show" class="box">Content</div>
+  </Transition>
+</template>
+
+<script setup>
+import gsap from 'gsap'
+
+function onEnter(el) {
+  // Animation starts but Vue doesn't wait for it!
+  gsap.from(el, {
+    opacity: 0,
+    y: 50,
+    duration: 0.5
+  })
+  // Missing done() call - element appears with no animation
+}
+
+function onLeave(el) {
+  gsap.to(el, {
+    opacity: 0,
+    y: -50,
+    duration: 0.5
+  })
+  // Missing done() call - element removed immediately!
+}
+</script>
+```
+
+**Correct Code:**
+```vue
+<template>
+  <!-- GOOD: done() callback signals animation completion -->
+  <Transition :css="false" @enter="onEnter" @leave="onLeave">
+    <div v-if="show" class="box">Content</div>
+  </Transition>
+</template>
+
+<script setup>
+import gsap from 'gsap'
+
+function onEnter(el, done) {
+  gsap.from(el, {
+    opacity: 0,
+    y: 50,
+    duration: 0.5,
+    onComplete: done  // Tell Vue animation is complete
+  })
+}
+
+function onLeave(el, done) {
+  gsap.to(el, {
+    opacity: 0,
+    y: -50,
+    duration: 0.5,
+    onComplete: done  // Element removed after animation
+  })
+}
+</script>
+```
+
+## Why Use `:css="false"`?
+
+1. **Prevents CSS interference**: Vue won't add transition classes that might conflict
+2. **Slight performance benefit**: Skips CSS transition detection
+3. **Clearer intent**: Makes it explicit that JS controls the animation
+
+```vue
+<template>
+  <!-- Without :css="false", Vue adds v-enter-active etc. classes -->
+  <!-- These can interfere with your JS animation timing -->
+  <Transition @enter="onEnter" @leave="onLeave">
+    <div v-if="show">May have CSS conflicts</div>
+  </Transition>
+
+  <!-- With :css="false", no classes added - full JS control -->
+  <Transition :css="false" @enter="onEnter" @leave="onLeave">
+    <div v-if="show">Pure JS animation</div>
+  </Transition>
+</template>
+```
+
+## Complete JavaScript Transition Example
+
+```vue
+<template>
+  <Transition
+    :css="false"
+    @before-enter="onBeforeEnter"
+    @enter="onEnter"
+    @after-enter="onAfterEnter"
+    @enter-cancelled="onEnterCancelled"
+    @before-leave="onBeforeLeave"
+    @leave="onLeave"
+    @after-leave="onAfterLeave"
+    @leave-cancelled="onLeaveCancelled"
+  >
+    <div v-if="show" class="animated-box">Content</div>
+  </Transition>
+</template>
+
+<script setup>
+import gsap from 'gsap'
+import { ref } from 'vue'
+
+const show = ref(false)
+let enterAnimation = null
+let leaveAnimation = null
+
+function onBeforeEnter(el) {
+  // Set initial state before animation
+  el.style.opacity = 0
+  el.style.transform = 'translateY(50px)'
+}
+
+function onEnter(el, done) {
+  // Store animation reference for potential cancellation
+  enterAnimation = gsap.to(el, {
+    opacity: 1,
+    y: 0,
+    duration: 0.5,
+    ease: 'power2.out',
+    onComplete: done  // REQUIRED with :css="false"
+  })
+}
+
+function onAfterEnter(el) {
+  // Cleanup after enter completes
+  enterAnimation = null
+}
+
+function onEnterCancelled() {
+  // Handle interruption (e.g., user toggles quickly)
+  if (enterAnimation) {
+    enterAnimation.kill()
+    enterAnimation = null
+  }
+}
+
+function onBeforeLeave(el) {
+  // Set state before leaving
+}
+
+function onLeave(el, done) {
+  leaveAnimation = gsap.to(el, {
+    opacity: 0,
+    y: -50,
+    duration: 0.5,
+    ease: 'power2.in',
+    onComplete: done  // REQUIRED with :css="false"
+  })
+}
+
+function onAfterLeave(el) {
+  leaveAnimation = null
+}
+
+function onLeaveCancelled() {
+  if (leaveAnimation) {
+    leaveAnimation.kill()
+    leaveAnimation = null
+  }
+}
+</script>
+```
+
+## Using Web Animations API
+
+```vue
+<script setup>
+function onEnter(el, done) {
+  const animation = el.animate([
+    { opacity: 0, transform: 'scale(0.9)' },
+    { opacity: 1, transform: 'scale(1)' }
+  ], {
+    duration: 300,
+    easing: 'ease-out'
+  })
+
+  animation.onfinish = done  // Call done when animation ends
+}
+
+function onLeave(el, done) {
+  const animation = el.animate([
+    { opacity: 1, transform: 'scale(1)' },
+    { opacity: 0, transform: 'scale(0.9)' }
+  ], {
+    duration: 300,
+    easing: 'ease-in'
+  })
+
+  animation.onfinish = done
+}
+</script>
+```
+
+## Common Mistakes
+
+```javascript
+// WRONG: Calling done() immediately instead of after animation
+function onEnter(el, done) {
+  gsap.from(el, { opacity: 0, duration: 0.5 })
+  done() // Called immediately - animation skipped!
+}
+
+// WRONG: Forgetting done() parameter
+function onEnter(el) {  // No 'done' parameter
+  gsap.from(el, {
+    opacity: 0,
+    onComplete: done  // Error: done is not defined!
+  })
+}
+
+// CORRECT: Pass done to animation callback
+function onEnter(el, done) {
+  gsap.from(el, {
+    opacity: 0,
+    duration: 0.5,
+    onComplete: done  // Called after 0.5s
+  })
+}
+```
+
+## Reference
+- [Vue.js Transition - JavaScript Hooks](https://vuejs.org/guide/built-ins/transition.html#javascript-hooks)
+- [GSAP with Vue](https://gsap.com/resources/vue/)