@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/transition-nested-duration.md

@@ -0,0 +1,182 @@
+---
+title: Specify Explicit Duration for Nested Transitions
+impact: MEDIUM
+impactDescription: Nested transitions with different timings may end prematurely when Vue detects only the root element's transition end
+type: gotcha
+tags: [vue3, transition, animation, duration, nested, timing]
+---
+
+# Specify Explicit Duration for Nested Transitions
+
+**Impact: MEDIUM** - When transitioning elements that contain nested child elements with different animation timings, Vue by default listens only for the first `transitionend` or `animationend` event on the **root** transition element. This means if inner elements have longer or delayed animations, they may be cut off when the root element's transition completes.
+
+## Task Checklist
+
+- [ ] Identify if your transition contains nested elements with different animation durations
+- [ ] Use the `:duration` prop to specify the total time Vue should wait
+- [ ] Consider using separate enter and leave durations if they differ
+- [ ] Test animations to ensure nested elements complete fully
+
+**Problematic Code:**
+```vue
+<template>
+  <!-- BAD: Inner element has longer animation that gets cut off -->
+  <Transition name="nested">
+    <div v-if="show" class="outer">
+      <div class="inner">Hello</div>
+    </div>
+  </Transition>
+</template>
+
+<style>
+.nested-enter-active .outer,
+.nested-leave-active .outer {
+  transition: opacity 0.3s ease;
+}
+
+.nested-enter-active .inner,
+.nested-leave-active .inner {
+  /* This 0.5s animation gets cut off at 0.3s when outer finishes! */
+  transition: transform 0.5s ease 0.2s; /* 0.2s delay + 0.5s = 0.7s total */
+}
+
+.nested-enter-from .outer,
+.nested-leave-to .outer {
+  opacity: 0;
+}
+
+.nested-enter-from .inner,
+.nested-leave-to .inner {
+  transform: translateX(-30px);
+}
+</style>
+```
+
+**Correct Code:**
+```vue
+<template>
+  <!-- GOOD: Explicit duration ensures all nested animations complete -->
+  <Transition name="nested" :duration="700">
+    <div v-if="show" class="outer">
+      <div class="inner">Hello</div>
+    </div>
+  </Transition>
+</template>
+
+<style>
+.nested-enter-active .outer,
+.nested-leave-active .outer {
+  transition: opacity 0.3s ease;
+}
+
+.nested-enter-active .inner,
+.nested-leave-active .inner {
+  /* Now this animation completes fully */
+  transition: transform 0.5s ease 0.2s;
+}
+
+.nested-enter-from .outer,
+.nested-leave-to .outer {
+  opacity: 0;
+}
+
+.nested-enter-from .inner,
+.nested-leave-to .inner {
+  transform: translateX(-30px);
+}
+</style>
+```
+
+## Different Enter and Leave Durations
+
+```vue
+<template>
+  <!-- GOOD: Separate durations for enter and leave -->
+  <Transition
+    name="complex"
+    :duration="{ enter: 500, leave: 800 }"
+  >
+    <div v-if="show" class="container">
+      <h1 class="title">Title</h1>
+      <p class="content">Content with staggered animation</p>
+    </div>
+  </Transition>
+</template>
+
+<style>
+/* Enter: title first, then content */
+.complex-enter-active .title {
+  transition: opacity 0.3s ease, transform 0.3s ease;
+}
+
+.complex-enter-active .content {
+  transition: opacity 0.3s ease 0.2s, transform 0.3s ease 0.2s;
+}
+
+/* Leave: content first, then title (reverse order) */
+.complex-leave-active .content {
+  transition: opacity 0.3s ease, transform 0.3s ease;
+}
+
+.complex-leave-active .title {
+  transition: opacity 0.5s ease 0.3s, transform 0.5s ease 0.3s;
+}
+
+.complex-enter-from .title,
+.complex-enter-from .content,
+.complex-leave-to .title,
+.complex-leave-to .content {
+  opacity: 0;
+  transform: translateY(20px);
+}
+</style>
+```
+
+## Choreographed Staggered Animations
+
+```vue
+<template>
+  <Transition name="stagger" :duration="800">
+    <div v-if="show" class="card">
+      <img class="card-image" src="..." />
+      <h2 class="card-title">Title</h2>
+      <p class="card-body">Body text...</p>
+      <button class="card-action">Action</button>
+    </div>
+  </Transition>
+</template>
+
+<style>
+/* Staggered entrance: image -> title -> body -> action */
+.stagger-enter-active .card-image { transition: all 0.3s ease; }
+.stagger-enter-active .card-title { transition: all 0.3s ease 0.1s; }
+.stagger-enter-active .card-body { transition: all 0.3s ease 0.2s; }
+.stagger-enter-active .card-action { transition: all 0.3s ease 0.3s; }
+/* Total: 0.3s delay + 0.3s animation = 0.6s, but use 800ms for safety */
+
+.stagger-enter-from .card-image,
+.stagger-enter-from .card-title,
+.stagger-enter-from .card-body,
+.stagger-enter-from .card-action {
+  opacity: 0;
+  transform: translateY(10px);
+}
+</style>
+```
+
+## Calculating Duration
+
+Use this formula to calculate the correct duration:
+```
+duration = max(delay + animation_duration) for all nested elements
+```
+
+Example:
+- Element A: no delay, 300ms duration = 300ms total
+- Element B: 100ms delay, 300ms duration = 400ms total
+- Element C: 200ms delay, 500ms duration = 700ms total
+
+**Required `:duration`**: 700 (or slightly higher for safety margin)
+
+## Reference
+- [Vue.js Transition - Nested Transitions](https://vuejs.org/guide/built-ins/transition.html#nested-transitions-and-explicit-transition-durations)

package/skills/vue-debug-guides/reference/transition-reusable-scoped-style.md

@@ -0,0 +1,245 @@
+---
+title: Avoid Scoped Styles in Reusable Transition Components
+impact: MEDIUM
+impactDescription: Scoped styles in transition wrapper components won't apply to slotted content, breaking the transition animation
+type: gotcha
+tags: [vue3, transition, scoped-css, slot, reusable-component]
+---
+
+# Avoid Scoped Styles in Reusable Transition Components
+
+**Impact: MEDIUM** - When creating reusable transition wrapper components, using `<style scoped>` will prevent the transition CSS classes from applying to slotted content. Scoped styles only affect elements directly in the component's template, not content passed through slots. Your transition animations will silently fail.
+
+## Task Checklist
+
+- [ ] In reusable transition components, use `<style>` without `scoped`
+- [ ] Alternatively, use unique class name prefixes to avoid global conflicts
+- [ ] Or use CSS modules with `:global()` for transition classes
+- [ ] Test that transitions work when component is used in different contexts
+
+**Problematic Code:**
+```vue
+<!-- MyFadeTransition.vue -->
+<template>
+  <Transition name="my-fade">
+    <slot />
+  </Transition>
+</template>
+
+<!-- BAD: Scoped styles won't apply to slot content! -->
+<style scoped>
+.my-fade-enter-active,
+.my-fade-leave-active {
+  transition: opacity 0.3s ease;
+}
+
+.my-fade-enter-from,
+.my-fade-leave-to {
+  opacity: 0;
+}
+</style>
+```
+
+```vue
+<!-- Parent component using the transition -->
+<template>
+  <MyFadeTransition>
+    <div v-if="show">This won't animate!</div>
+  </MyFadeTransition>
+</template>
+
+<!--
+The <div> is slotted content, so .my-fade-* classes
+applied by Vue won't match the scoped CSS selectors
+-->
+```
+
+**Correct Code:**
+```vue
+<!-- MyFadeTransition.vue -->
+<template>
+  <Transition name="my-fade">
+    <slot />
+  </Transition>
+</template>
+
+<!-- GOOD: Unscoped styles apply to any element -->
+<style>
+.my-fade-enter-active,
+.my-fade-leave-active {
+  transition: opacity 0.3s ease;
+}
+
+.my-fade-enter-from,
+.my-fade-leave-to {
+  opacity: 0;
+}
+</style>
+```
+
+## Alternative: Use Unique Prefixed Class Names
+
+To avoid global style conflicts, use distinctive prefixes:
+
+```vue
+<!-- FadeTransition.vue -->
+<template>
+  <Transition name="v-fade-transition">
+    <slot />
+  </Transition>
+</template>
+
+<style>
+/* Unique prefix reduces collision risk */
+.v-fade-transition-enter-active,
+.v-fade-transition-leave-active {
+  transition: opacity 0.3s ease;
+}
+
+.v-fade-transition-enter-from,
+.v-fade-transition-leave-to {
+  opacity: 0;
+}
+</style>
+```
+
+## Alternative: CSS Modules with :global()
+
+```vue
+<!-- FadeTransition.vue -->
+<template>
+  <Transition name="fade">
+    <slot />
+  </Transition>
+</template>
+
+<style module>
+/* Use :global() for transition classes */
+:global(.fade-enter-active),
+:global(.fade-leave-active) {
+  transition: opacity 0.3s ease;
+}
+
+:global(.fade-enter-from),
+:global(.fade-leave-to) {
+  opacity: 0;
+}
+</style>
+```
+
+## Alternative: Custom Transition Classes
+
+Use the custom class props to apply scoped classes:
+
+```vue
+<!-- FadeTransition.vue -->
+<template>
+  <Transition
+    :enter-active-class="$style.enterActive"
+    :leave-active-class="$style.leaveActive"
+    :enter-from-class="$style.enterFrom"
+    :leave-to-class="$style.leaveTo"
+  >
+    <slot />
+  </Transition>
+</template>
+
+<style module>
+.enterActive,
+.leaveActive {
+  transition: opacity 0.3s ease;
+}
+
+.enterFrom,
+.leaveTo {
+  opacity: 0;
+}
+</style>
+```
+
+## Complete Reusable Transition Component Example
+
+```vue
+<!-- transitions/SlideTransition.vue -->
+<template>
+  <Transition
+    name="slide"
+    :mode="mode"
+    :appear="appear"
+    @before-enter="$emit('before-enter', $event)"
+    @enter="$emit('enter', $event)"
+    @after-enter="$emit('after-enter', $event)"
+    @before-leave="$emit('before-leave', $event)"
+    @leave="$emit('leave', $event)"
+    @after-leave="$emit('after-leave', $event)"
+  >
+    <slot />
+  </Transition>
+</template>
+
+<script setup>
+defineProps({
+  mode: {
+    type: String,
+    default: 'out-in',
+    validator: (v) => ['out-in', 'in-out', ''].includes(v)
+  },
+  appear: {
+    type: Boolean,
+    default: false
+  }
+})
+
+defineEmits([
+  'before-enter', 'enter', 'after-enter',
+  'before-leave', 'leave', 'after-leave'
+])
+</script>
+
+<!-- Unscoped so styles apply to slotted content -->
+<style>
+.slide-enter-active,
+.slide-leave-active {
+  transition: transform 0.3s ease, opacity 0.3s ease;
+}
+
+.slide-enter-from {
+  opacity: 0;
+  transform: translateX(-20px);
+}
+
+.slide-leave-to {
+  opacity: 0;
+  transform: translateX(20px);
+}
+</style>
+```
+
+Usage:
+```vue
+<template>
+  <SlideTransition>
+    <div v-if="show" class="content">
+      This will properly animate!
+    </div>
+  </SlideTransition>
+</template>
+```
+
+## Why This Happens
+
+Vue's scoped styles work by adding a unique data attribute (e.g., `data-v-7ba5bd90`) to elements and selectors:
+
+```css
+/* What you write */
+.my-fade-enter-active { ... }
+
+/* What Vue generates (scoped) */
+.my-fade-enter-active[data-v-7ba5bd90] { ... }
+```
+
+Slotted content comes from the parent component and gets the parent's data attribute, not the transition component's attribute. So the selectors never match.
+
+## Reference
+- [Vue.js Reusable Transitions](https://vuejs.org/guide/built-ins/transition.html#reusable-transitions)
+- [Vue.js Scoped CSS](https://vuejs.org/api/sfc-css-features.html#scoped-css)

package/skills/vue-debug-guides/reference/transition-router-view-appear.md

@@ -0,0 +1,193 @@
+---
+title: RouterView Transitions Always Apply Despite Missing appear Prop
+impact: LOW
+impactDescription: Initial page load with RouterView triggers transition animation even without the appear prop due to async navigation
+type: gotcha
+tags: [vue3, transition, vue-router, appear, initial-load, navigation]
+---
+
+# RouterView Transitions Always Apply Despite Missing appear Prop
+
+**Impact: LOW** - When using `<Transition>` with Vue Router's `<RouterView>`, the enter transition animation runs on initial page load even if you haven't added the `appear` prop. This differs from normal Transition behavior where `appear` is required for initial render animations. This happens because Vue Router's navigations are asynchronous, causing the component to mount after the initial render.
+
+## Task Checklist
+
+- [ ] Be aware that RouterView transitions always animate on initial load
+- [ ] If you want NO animation on initial load, you need to handle this explicitly
+- [ ] Don't add `appear` prop expecting it to change behavior - it's already effectively enabled
+- [ ] Consider whether initial animation is desired for your UX
+
+**Expected Behavior (Normal Transition):**
+```vue
+<template>
+  <!-- Without appear: No animation on initial render -->
+  <Transition name="fade">
+    <div v-if="show">Content</div>
+  </Transition>
+
+  <!-- With appear: Animates on initial render -->
+  <Transition name="fade" appear>
+    <div v-if="show">Content</div>
+  </Transition>
+</template>
+```
+
+**RouterView Behavior (Different!):**
+```vue
+<template>
+  <!-- RouterView transitions ALWAYS animate on initial load -->
+  <!-- The appear prop has no effect here -->
+  <RouterView v-slot="{ Component }">
+    <Transition name="fade">
+      <component :is="Component" />
+    </Transition>
+  </RouterView>
+</template>
+
+<!--
+On initial page load:
+1. Vue renders the app
+2. Router resolves the route (async)
+3. Component mounts AFTER initial render
+4. Enter transition triggers (as if toggled from v-if="false" to v-if="true")
+-->
+```
+
+## Why This Happens
+
+Vue Router navigations are asynchronous. The sequence is:
+
+1. Vue application mounts with empty RouterView
+2. Router resolves the initial route
+3. Route component is inserted into RouterView
+4. This insertion triggers the enter transition
+
+Since the component wasn't present in the initial render and is "inserted" afterward, Vue treats it as a normal enter transition, not an initial render.
+
+## If You Want to Disable Initial Animation
+
+```vue
+<template>
+  <RouterView v-slot="{ Component }">
+    <Transition :name="isInitialLoad ? '' : 'fade'" mode="out-in">
+      <component :is="Component" />
+    </Transition>
+  </RouterView>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+import { useRouter } from 'vue-router'
+
+const isInitialLoad = ref(true)
+const router = useRouter()
+
+// After first navigation completes, enable transitions
+router.isReady().then(() => {
+  // Small delay to ensure initial render is complete
+  setTimeout(() => {
+    isInitialLoad.value = false
+  }, 0)
+})
+</script>
+```
+
+## Alternative: Use CSS to Skip First Animation
+
+```vue
+<template>
+  <RouterView v-slot="{ Component }">
+    <Transition name="fade" mode="out-in">
+      <component :is="Component" :class="{ 'skip-initial': isInitialLoad }" />
+    </Transition>
+  </RouterView>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { useRouter } from 'vue-router'
+
+const isInitialLoad = ref(true)
+const router = useRouter()
+
+router.isReady().then(() => {
+  isInitialLoad.value = false
+})
+</script>
+
+<style>
+.fade-enter-active,
+.fade-leave-active {
+  transition: opacity 0.3s ease;
+}
+
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+}
+
+/* Skip animation on initial load */
+.skip-initial.fade-enter-active {
+  transition: none;
+}
+</style>
+```
+
+## Standard RouterView Transition Pattern
+
+If you're fine with initial animation (often desired), use the standard pattern:
+
+```vue
+<template>
+  <RouterView v-slot="{ Component, route }">
+    <Transition :name="route.meta.transition || 'fade'" mode="out-in">
+      <component :is="Component" :key="route.path" />
+    </Transition>
+  </RouterView>
+</template>
+
+<style>
+.fade-enter-active,
+.fade-leave-active {
+  transition: opacity 0.3s ease;
+}
+
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+}
+
+/* Route-specific transitions via meta */
+.slide-enter-active,
+.slide-leave-active {
+  transition: transform 0.3s ease;
+}
+
+.slide-enter-from {
+  transform: translateX(100%);
+}
+
+.slide-leave-to {
+  transform: translateX(-100%);
+}
+</style>
+```
+
+```javascript
+// router.js
+const routes = [
+  {
+    path: '/',
+    component: Home
+  },
+  {
+    path: '/about',
+    component: About,
+    meta: { transition: 'slide' }  // Custom transition for this route
+  }
+]
+```
+
+## Reference
+- [Vue Router Transitions](https://router.vuejs.org/guide/advanced/transitions.html)
+- [Vue.js Transition appear](https://vuejs.org/guide/built-ins/transition.html#transition-on-appear)