@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/transition-type-when-mixed.md

@@ -0,0 +1,172 @@
+---
+title: Specify Transition Type When Mixing CSS Transitions and Animations
+impact: MEDIUM
+impactDescription: Vue may detect the wrong transition end event when both CSS transitions and animations are applied, causing timing issues
+type: gotcha
+tags: [vue3, transition, animation, css, type, timing]
+---
+
+# Specify Transition Type When Mixing CSS Transitions and Animations
+
+**Impact: MEDIUM** - When you have both CSS transitions and CSS animations applied to the same element (for example, a Vue-triggered animation combined with a hover transition effect), Vue cannot automatically determine which end event to listen for. You must explicitly tell Vue which type to prioritize using the `type` attribute with a value of either `"animation"` or `"transition"`.
+
+## Task Checklist
+
+- [ ] Check if your element has both `transition` and `animation` CSS properties
+- [ ] Determine which timing should control when Vue considers the transition complete
+- [ ] Add `type="animation"` or `type="transition"` to the `<Transition>` component
+- [ ] The type should match whichever animation/transition is longer or more important
+
+**Problematic Code:**
+```vue
+<template>
+  <!-- BAD: Both transition and animation present, Vue might pick wrong end event -->
+  <Transition name="bounce">
+    <div v-if="show" class="box">
+      Hover me for additional effect
+    </div>
+  </Transition>
+</template>
+
+<style>
+/* Vue-triggered CSS animation */
+.bounce-enter-active {
+  animation: bounce-in 0.5s;
+}
+
+.bounce-leave-active {
+  animation: bounce-out 0.3s;
+}
+
+@keyframes bounce-in {
+  0% { transform: scale(0); }
+  50% { transform: scale(1.2); }
+  100% { transform: scale(1); }
+}
+
+@keyframes bounce-out {
+  0% { transform: scale(1); }
+  100% { transform: scale(0); }
+}
+
+/* Additional hover transition on same element */
+.box {
+  transition: background-color 0.2s ease, box-shadow 0.2s ease;
+}
+
+.box:hover {
+  background-color: #f0f0f0;
+  box-shadow: 0 4px 8px rgba(0,0,0,0.1);
+}
+</style>
+```
+
+**Correct Code:**
+```vue
+<template>
+  <!-- GOOD: Explicitly specify that animation controls timing -->
+  <Transition name="bounce" type="animation">
+    <div v-if="show" class="box">
+      Hover me for additional effect
+    </div>
+  </Transition>
+</template>
+
+<style>
+/* Vue-triggered CSS animation - this is what we care about */
+.bounce-enter-active {
+  animation: bounce-in 0.5s;
+}
+
+.bounce-leave-active {
+  animation: bounce-out 0.3s;
+}
+
+@keyframes bounce-in {
+  0% { transform: scale(0); }
+  50% { transform: scale(1.2); }
+  100% { transform: scale(1); }
+}
+
+@keyframes bounce-out {
+  0% { transform: scale(1); }
+  100% { transform: scale(0); }
+}
+
+/* Additional hover transition - unrelated to Vue transition timing */
+.box {
+  transition: background-color 0.2s ease, box-shadow 0.2s ease;
+}
+
+.box:hover {
+  background-color: #f0f0f0;
+  box-shadow: 0 4px 8px rgba(0,0,0,0.1);
+}
+</style>
+```
+
+## When to Use Each Type
+
+### Use `type="animation"` when:
+- Your enter/leave effects use `@keyframes` animations
+- The animation is longer than any transitions
+- You want precise control over multi-step animations
+
+```vue
+<Transition name="fancy" type="animation">
+  <div v-if="show" class="animated-element" />
+</Transition>
+
+<style>
+.fancy-enter-active {
+  animation: fancy-entrance 1s ease-out;
+}
+
+.animated-element {
+  /* This shorter transition should not affect timing */
+  transition: color 0.2s;
+}
+</style>
+```
+
+### Use `type="transition"` when:
+- Your enter/leave effects use CSS `transition` property
+- You have decorative animations that shouldn't affect timing
+
+```vue
+<Transition name="slide" type="transition">
+  <div v-if="show" class="sliding-element" />
+</Transition>
+
+<style>
+.slide-enter-active,
+.slide-leave-active {
+  transition: transform 0.3s ease;
+}
+
+.slide-enter-from,
+.slide-leave-to {
+  transform: translateX(-100%);
+}
+
+/* Decorative infinite animation should not affect timing */
+.sliding-element {
+  animation: pulse 2s infinite;
+}
+
+@keyframes pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.8; }
+}
+</style>
+```
+
+## Common Symptoms Without Type Specification
+
+1. Transition ends too early (element snaps to final position)
+2. Transition hangs or takes too long to complete
+3. Element disappears before animation finishes
+4. CSS classes remain applied after transition should be complete
+
+## Reference
+- [Vue.js Transition Documentation](https://vuejs.org/guide/built-ins/transition.html#css-based-transitions)

package/skills/vue-debug-guides/reference/transition-unmount-hook-timing.md

@@ -0,0 +1,149 @@
+---
+title: Unmount Hooks May Not Fire Inside Transitions During Fast Replacement
+impact: MEDIUM
+impactDescription: Components inside transitions can be destroyed without unmount hooks firing under race conditions
+type: gotcha
+tags: [vue3, lifecycle, transition, onUnmounted, unmounted, cleanup, race-condition]
+---
+
+# Unmount Hooks May Not Fire Inside Transitions During Fast Replacement
+
+**Impact: MEDIUM** - When a component inside a `<transition>` is replaced by another component during the transition's loading phase, the unmount hooks (`onBeforeUnmount`, `onUnmounted`) may not be called even though the component is removed from the DOM. This can cause memory leaks and resource leaks from unclean side effects.
+
+This is a known edge case that occurs when the timing is specific - if a parent component with a child inside a transition is replaced while the child is still mounting. The child's mount hooks fire, but unmount hooks never do.
+
+## Task Checklist
+
+- [ ] Be aware that unmount hooks are not 100% guaranteed inside transitions
+- [ ] For critical cleanup, consider alternative cleanup strategies
+- [ ] Use `mode="out-in"` on transitions to ensure old component fully unmounts before new mounts
+- [ ] For essential resources, consider cleanup at parent component level
+- [ ] Test component replacement scenarios during development
+
+**Problematic Scenario:**
+```vue
+<!-- Parent component with lazy-loaded child in transition -->
+<template>
+  <transition>
+    <Suspense>
+      <component :is="currentComponent" />
+    </Suspense>
+  </transition>
+</template>
+```
+
+```javascript
+// Child component - unmount hooks may not fire if parent changes quickly
+export default {
+  setup() {
+    const socket = new WebSocket('wss://example.com')
+
+    onMounted(() => {
+      console.log('Mounted - this will run')
+      socket.connect()
+    })
+
+    onUnmounted(() => {
+      // WARNING: This may NOT run if component is inside transition
+      // and parent navigates away during mounting phase!
+      console.log('Unmounted - might not run')
+      socket.close()
+    })
+  }
+}
+```
+
+**Safer Patterns:**
+```vue
+<!-- SAFER: Use out-in mode to ensure proper sequencing -->
+<template>
+  <transition mode="out-in">
+    <component :is="currentComponent" :key="currentKey" />
+  </transition>
+</template>
+```
+
+```javascript
+// SAFER: Cleanup at parent level for critical resources
+// Parent component
+export default {
+  setup() {
+    const childSocket = ref(null)
+
+    // Parent controls resource lifecycle
+    provide('registerSocket', (socket) => {
+      childSocket.value = socket
+    })
+
+    onUnmounted(() => {
+      // Parent ensures cleanup even if child unmount hook doesn't fire
+      childSocket.value?.close()
+    })
+  }
+}
+
+// Child component
+export default {
+  setup() {
+    const registerSocket = inject('registerSocket')
+    const socket = new WebSocket('wss://example.com')
+
+    // Register with parent for backup cleanup
+    registerSocket(socket)
+
+    onMounted(() => {
+      socket.connect()
+    })
+
+    onUnmounted(() => {
+      socket.close() // Still attempt cleanup here
+    })
+  }
+}
+```
+
+```javascript
+// SAFER: Use AbortController pattern for cancellable operations
+export default {
+  setup() {
+    const abortController = new AbortController()
+
+    onMounted(() => {
+      fetch('/api/data', { signal: abortController.signal })
+        .then(handleData)
+        .catch(err => {
+          if (err.name !== 'AbortError') {
+            handleError(err)
+          }
+        })
+    })
+
+    onUnmounted(() => {
+      // If this doesn't fire, request continues but response is ignored
+      // Not a memory leak - just potentially wasted network call
+      abortController.abort()
+    })
+  }
+}
+```
+
+## Testing for This Issue
+
+```javascript
+// Test by rapidly switching components during async loading
+async function testUnmountHooks() {
+  // Mount component A (has async setup)
+  await mountComponent('A')
+
+  // Immediately switch to B before A finishes mounting
+  await mountComponent('B')
+
+  // Check if A's unmount hooks fired
+  // They may not have!
+}
+```
+
+## Reference
+- [Vue.js GitHub Issue #6260](https://github.com/vuejs/core/issues/6260)
+- [Vue.js Transition](https://vuejs.org/guide/built-ins/transition.html)
+- [Vue.js Lifecycle Hooks](https://vuejs.org/guide/essentials/lifecycle.html)

package/skills/vue-debug-guides/reference/ts-defineprops-boolean-default-false.md

@@ -0,0 +1,225 @@
+---
+title: Boolean Props Default to false, Not undefined
+impact: MEDIUM
+impactDescription: TypeScript expects optional boolean to be undefined but Vue defaults it to false, causing type confusion
+type: gotcha
+tags: [vue3, typescript, props, boolean, defineProps]
+---
+
+# Boolean Props Default to false, Not undefined
+
+**Impact: MEDIUM** - When using type-based `defineProps`, optional boolean props (marked with `?`) behave differently than TypeScript expects. Vue treats boolean props specially: an absent boolean prop defaults to `false`, not `undefined`. This can cause confusion when TypeScript thinks the type is `boolean | undefined`.
+
+## Task Checklist
+
+- [ ] Understand that Vue's boolean casting makes absent booleans `false`
+- [ ] Use `withDefaults()` to be explicit about boolean defaults
+- [ ] Consider using non-boolean types if `undefined` is a meaningful state
+- [ ] Document this Vue-specific behavior for your team
+
+## The Gotcha
+
+```vue
+<script setup lang="ts">
+interface Props {
+  disabled?: boolean  // TypeScript sees: boolean | undefined
+}
+
+const props = defineProps<Props>()
+
+// TypeScript thinks props.disabled could be undefined
+if (props.disabled === undefined) {
+  console.log('This will NEVER run!')
+  // Vue's boolean casting means disabled is false, not undefined
+}
+</script>
+
+<template>
+  <!-- When used without the prop -->
+  <MyComponent />
+  <!-- disabled is false, NOT undefined -->
+</template>
+```
+
+## Why This Happens
+
+Vue has special "boolean casting" behavior inherited from HTML boolean attributes:
+
+```vue
+<!-- All of these make disabled = true -->
+<MyComponent disabled />
+<MyComponent :disabled="true" />
+<MyComponent disabled="" />
+
+<!-- This makes disabled = false (NOT undefined) -->
+<MyComponent />
+
+<!-- Explicit false -->
+<MyComponent :disabled="false" />
+```
+
+This is by design to match how HTML works:
+```html
+<!-- HTML: presence means true, absence means false -->
+<button disabled>Can't click</button>
+<button>Can click</button>
+```
+
+## Solutions
+
+### Solution 1: Be Explicit with withDefaults
+
+Make your intention clear:
+
+```vue
+<script setup lang="ts">
+interface Props {
+  disabled?: boolean
+}
+
+// Explicitly document the default
+const props = withDefaults(defineProps<Props>(), {
+  disabled: false  // Now it's clear this defaults to false
+})
+</script>
+```
+
+### Solution 2: Use a Three-State Type
+
+If you actually need to distinguish "not set" from "explicitly false":
+
+```vue
+<script setup lang="ts">
+interface Props {
+  // Use a union type instead of optional boolean
+  state?: 'enabled' | 'disabled' | undefined
+
+  // Or use undefined explicitly
+  toggleState?: boolean | undefined
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  state: undefined,  // Can actually be undefined
+  toggleState: undefined
+})
+
+// Now you can check for undefined
+if (props.state === undefined) {
+  // Use parent's state
+} else if (props.state === 'disabled') {
+  // Explicitly disabled
+}
+</script>
+```
+
+### Solution 3: Use null for "Not Set"
+
+```vue
+<script setup lang="ts">
+interface Props {
+  // null = not set, false = explicitly off, true = explicitly on
+  selected: boolean | null
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  selected: null
+})
+
+// Three distinct states
+if (props.selected === null) {
+  console.log('Selection not specified')
+} else if (props.selected) {
+  console.log('Selected')
+} else {
+  console.log('Explicitly not selected')
+}
+</script>
+```
+
+## Boolean Casting Order
+
+Vue also has special behavior when Boolean and String are both valid:
+
+```typescript
+// Order matters in runtime declaration!
+defineProps({
+  // Boolean first: empty string becomes true
+  disabled: [Boolean, String]
+})
+
+// <MyComponent disabled /> → disabled = true
+// <MyComponent disabled="" /> → disabled = true
+```
+
+```typescript
+defineProps({
+  // String first: empty string stays as string
+  disabled: [String, Boolean]
+})
+
+// <MyComponent disabled /> → disabled = ''
+// <MyComponent disabled="" /> → disabled = ''
+```
+
+With type-based declaration, Boolean always takes priority for absent props.
+
+## Common Bug Pattern
+
+```vue
+<!-- Parent.vue -->
+<script setup lang="ts">
+const userPreferences = ref({
+  darkMode: undefined as boolean | undefined
+})
+
+// Fetch preferences...
+onMounted(async () => {
+  userPreferences.value = await fetchPreferences()
+})
+</script>
+
+<template>
+  <!-- Bug: undefined becomes false, not "inherit system preference" -->
+  <ThemeToggle :darkMode="userPreferences.darkMode" />
+</template>
+```
+
+**Fix:**
+
+```vue
+<script setup lang="ts">
+const userPreferences = ref<{
+  darkMode: boolean | null
+}>({
+  darkMode: null  // Use null for "not yet loaded"
+})
+</script>
+
+<template>
+  <!-- Now ThemeToggle can distinguish between null and false -->
+  <ThemeToggle :darkMode="userPreferences.darkMode" />
+</template>
+```
+
+## TypeScript Type Accuracy
+
+The Vue type system handles this, but it can be confusing:
+
+```typescript
+interface Props {
+  disabled?: boolean
+}
+
+const props = defineProps<Props>()
+
+// At compile time: boolean | undefined
+// At runtime: boolean (never undefined due to Vue's boolean casting)
+
+// TypeScript is technically "wrong" here, but the withDefaults usage
+// or explicit false default can help align expectations
+```
+
+## Reference
+- [Vue.js Props - Boolean Casting](https://vuejs.org/guide/components/props.html#boolean-casting)
+- [GitHub Issue: Boolean props default to false](https://github.com/vuejs/core/issues/8576)
+- [TypeScript Vue 3 Props](https://madewithlove.com/blog/typescript-vue-3-and-strongly-typed-props/)