@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/ts-withdefaults-mutable-factory-function.md

@@ -0,0 +1,171 @@
+---
+title: Wrap Mutable Default Values in Factory Functions
+impact: HIGH
+impactDescription: Without factory functions, all component instances share the same mutable reference causing cross-contamination bugs
+type: gotcha
+tags: [vue3, typescript, props, withDefaults, mutable-types]
+---
+
+# Wrap Mutable Default Values in Factory Functions
+
+**Impact: HIGH** - When using `withDefaults()` with type-based props declaration, default values for mutable types (arrays and objects) MUST be wrapped in factory functions. Without this, all component instances share the same reference, causing bugs where modifying the prop in one instance affects all others.
+
+## Task Checklist
+
+- [ ] Always wrap array defaults in factory functions: `() => []`
+- [ ] Always wrap object defaults in factory functions: `() => ({})`
+- [ ] Primitive types (string, number, boolean) do NOT need factory functions
+- [ ] Review existing components for this pattern
+
+## The Problem: Shared Mutable References
+
+**WRONG - Shared reference across instances:**
+```vue
+<script setup lang="ts">
+interface Props {
+  items?: string[]
+  config?: { theme: string }
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  items: ['default'],           // WRONG! All instances share this array
+  config: { theme: 'light' }    // WRONG! All instances share this object
+})
+</script>
+```
+
+When you have multiple instances of this component:
+```vue
+<template>
+  <!-- Both share the SAME items array! -->
+  <MyComponent ref="comp1" />
+  <MyComponent ref="comp2" />
+</template>
+
+<script setup>
+// If comp1 modifies its items, comp2's items change too!
+comp1.value.items.push('new item')  // comp2 also has 'new item' now
+</script>
+```
+
+## The Solution: Factory Functions
+
+**CORRECT - Unique instance per component:**
+```vue
+<script setup lang="ts">
+interface Props {
+  items?: string[]
+  config?: { theme: string }
+  nested?: { data: { values: number[] } }
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  items: () => ['default'],                      // Factory function!
+  config: () => ({ theme: 'light' }),            // Factory function!
+  nested: () => ({ data: { values: [] } })       // Factory function!
+})
+</script>
+```
+
+## When Factory Functions Are Required
+
+| Type | Factory Required | Example Default |
+|------|-----------------|-----------------|
+| `string` | No | `'hello'` |
+| `number` | No | `42` |
+| `boolean` | No | `false` |
+| `string[]` | **Yes** | `() => []` |
+| `number[]` | **Yes** | `() => [1, 2, 3]` |
+| `object` | **Yes** | `() => ({})` |
+| `Map` | **Yes** | `() => new Map()` |
+| `Set` | **Yes** | `() => new Set()` |
+| `Date` | **Yes** | `() => new Date()` |
+
+## Complete Example
+
+```vue
+<script setup lang="ts">
+interface User {
+  id: string
+  name: string
+}
+
+interface Props {
+  // Primitives - no factory needed
+  title?: string
+  count?: number
+  disabled?: boolean
+
+  // Mutable types - factory required
+  items?: string[]
+  users?: User[]
+  metadata?: Record<string, unknown>
+  selectedIds?: Set<string>
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  // Primitives
+  title: 'Default Title',
+  count: 0,
+  disabled: false,
+
+  // Mutable types with factory functions
+  items: () => [],
+  users: () => [],
+  metadata: () => ({}),
+  selectedIds: () => new Set()
+})
+</script>
+```
+
+## Vue 3.5+ Reactive Props Destructure
+
+Vue 3.5 introduces reactive props destructure, which handles this automatically:
+
+```vue
+<script setup lang="ts">
+interface Props {
+  items?: string[]
+  config?: { theme: string }
+}
+
+// Vue 3.5+ - defaults work correctly without explicit factory functions
+const {
+  items = ['default'],        // Each instance gets its own array
+  config = { theme: 'light' } // Each instance gets its own object
+} = defineProps<Props>()
+</script>
+```
+
+Note: Under the hood, Vue 3.5 handles the instance isolation for you.
+
+## Common Bug Pattern
+
+This bug often appears in list/table components:
+
+```vue
+<!-- ListItem.vue - BUGGY -->
+<script setup lang="ts">
+interface Props {
+  selectedRows?: number[]
+}
+
+// All ListItems share the same selectedRows array!
+const props = withDefaults(defineProps<Props>(), {
+  selectedRows: []  // BUG: Missing factory function
+})
+</script>
+```
+
+Users report: "Selecting a row in one table selects it in all tables!"
+
+**Fix:**
+```typescript
+const props = withDefaults(defineProps<Props>(), {
+  selectedRows: () => []  // Now each instance has its own array
+})
+```
+
+## Reference
+- [Vue.js TypeScript with Composition API - Default Props](https://vuejs.org/guide/typescript/composition-api.html#props-default-values)
+- [Vue RFC - Reactive Props Destructure](https://github.com/vuejs/rfcs/discussions/502)

package/skills/vue-debug-guides/reference/undeclared-emits-double-firing.md

@@ -0,0 +1,195 @@
+---
+title: Undeclared Emits Cause Double Event Firing
+impact: HIGH
+impactDescription: Native events re-emitted without declaration fire twice - once from emit() and once from native listener on root element
+type: gotcha
+tags: [vue3, emits, defineEmits, events, native-events, fallthrough]
+---
+
+# Undeclared Emits Cause Double Event Firing
+
+**Impact: HIGH** - When a component re-emits a native DOM event (like `click`) without declaring it in `emits`, the event can fire twice. This happens because undeclared event listeners become part of `$attrs` and fall through to the root element, where they listen for native events while your `emit()` call also fires.
+
+This is a common bug when wrapping native elements or migrating from Vue 2 to Vue 3.
+
+## Task Checklist
+
+- [ ] Declare all emitted events in `defineEmits()` or `emits` option
+- [ ] Pay special attention when re-emitting native events (click, input, change, etc.)
+- [ ] Check for double firing if component wraps native elements
+- [ ] Understand that undeclared listeners fall through to `$attrs`
+
+## The Problem
+
+**Incorrect - Undeclared emit causes double firing:**
+```vue
+<!-- MyButton.vue -->
+<script setup>
+// NO defineEmits declaration!
+</script>
+
+<template>
+  <!-- Native click listener from parent falls through to button -->
+  <!-- PLUS we re-emit click -->
+  <button @click="$emit('click', $event)">
+    <slot></slot>
+  </button>
+</template>
+```
+
+```vue
+<!-- Parent.vue -->
+<template>
+  <!-- This handler fires TWICE on each click! -->
+  <MyButton @click="handleClick">Click me</MyButton>
+</template>
+
+<script setup>
+function handleClick() {
+  console.log('clicked') // Logs twice!
+}
+</script>
+```
+
+**What happens:**
+1. User clicks the button
+2. Native click event fires on the button element
+3. `@click` falls through to button (because 'click' isn't in emits), triggering `handleClick`
+4. The button's `@click="$emit('click', $event)"` also fires, emitting a component event
+5. Parent's `@click="handleClick"` receives the emitted event, triggering `handleClick` again
+
+## The Solution
+
+**Correct - Declare the emit:**
+```vue
+<!-- MyButton.vue -->
+<script setup>
+// Declare 'click' as a component event
+const emit = defineEmits(['click'])
+</script>
+
+<template>
+  <!-- Now @click="handleClick" in parent only listens to emit() -->
+  <button @click="emit('click', $event)">
+    <slot></slot>
+  </button>
+</template>
+```
+
+```vue
+<!-- Parent.vue -->
+<template>
+  <!-- Now fires only once -->
+  <MyButton @click="handleClick">Click me</MyButton>
+</template>
+```
+
+When you declare `click` in `emits`:
+- Vue knows `@click` on the component is listening for a component event
+- The listener does NOT fall through to the root element
+- Only your explicit `emit('click')` triggers the parent's handler
+
+## Options API Version
+
+**Correct - Using emits option:**
+```vue
+<script>
+export default {
+  emits: ['click', 'input', 'change'],
+
+  methods: {
+    handleClick(event) {
+      this.$emit('click', event)
+    }
+  }
+}
+</script>
+```
+
+## Common Scenarios
+
+### Wrapping Form Inputs
+
+```vue
+<!-- CustomInput.vue -->
+<script setup>
+// Declare all events you re-emit
+const emit = defineEmits(['input', 'change', 'focus', 'blur'])
+</script>
+
+<template>
+  <input
+    @input="emit('input', $event)"
+    @change="emit('change', $event)"
+    @focus="emit('focus', $event)"
+    @blur="emit('blur', $event)"
+  />
+</template>
+```
+
+### Wrapper Components
+
+```vue
+<!-- IconButton.vue -->
+<script setup>
+const emit = defineEmits(['click'])
+</script>
+
+<template>
+  <button @click="emit('click', $event)">
+    <Icon :name="icon" />
+    <slot></slot>
+  </button>
+</template>
+```
+
+## Alternative: Don't Re-emit, Let It Fall Through
+
+If your component has a single root element and you want native event behavior:
+
+```vue
+<!-- MyButton.vue -->
+<script setup>
+// Don't declare 'click' - let it fall through naturally
+const emit = defineEmits(['custom-action'])
+</script>
+
+<template>
+  <!-- Native @click from parent falls through to this button -->
+  <button>
+    <slot></slot>
+  </button>
+</template>
+```
+
+```vue
+<!-- Parent.vue -->
+<template>
+  <!-- This native click falls through to the button -->
+  <MyButton @click="handleClick">Click me</MyButton>
+</template>
+```
+
+This works because:
+- You don't re-emit 'click' explicitly
+- The native click listener falls through to the single root button
+- Native click fires once when button is clicked
+
+## Debugging Double Firing
+
+```vue
+<script setup>
+function handleClick(event) {
+  console.log('Event type:', event?.type)
+  console.log('Is native:', event instanceof Event)
+  console.trace('Click handler called')
+}
+</script>
+```
+
+If you see two stack traces with different origins, you have the double-firing issue.
+
+## Reference
+- [Vue 3 Migration - emits Option](https://v3-migration.vuejs.org/breaking-changes/emits-option)
+- [Vue.js Component Events](https://vuejs.org/guide/components/events.html)
+- [Vue.js Fallthrough Attributes](https://vuejs.org/guide/components/attrs.html)

package/skills/vue-debug-guides/reference/use-template-ref-vue35.md

@@ -0,0 +1,158 @@
+---
+title: Use useTemplateRef for Template Refs in Vue 3.5+
+impact: MEDIUM
+impactDescription: Legacy ref pattern is error-prone due to name matching requirement
+type: best-practice
+tags: [vue3, vue35, template-refs, useTemplateRef, composition-api]
+---
+
+# Use useTemplateRef for Template Refs in Vue 3.5+
+
+**Impact: MEDIUM** - Before Vue 3.5, template refs required declaring a `ref()` with a name exactly matching the template's ref attribute. This fragile connection breaks silently during refactoring. Vue 3.5's `useTemplateRef()` eliminates this issue with explicit binding and better TypeScript support.
+
+The legacy pattern causes no errors or warnings when names don't match - the ref simply stays null, leading to confusing debugging sessions.
+
+## Task Checklist
+
+- [ ] Use `useTemplateRef('ref-name')` in Vue 3.5+ projects
+- [ ] The first argument must exactly match the ref attribute value in the template
+- [ ] IDE support provides auto-completion for available ref names
+- [ ] TypeScript automatically infers the element type
+
+**Incorrect (Legacy Pattern):**
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+
+// FRAGILE: Variable name MUST match template ref value exactly
+const input = ref(null)
+
+// DANGER: After refactoring, names may not match
+const inputElement = ref(null) // Renamed variable...
+
+onMounted(() => {
+  // NO ERROR - just silently null!
+  inputElement.value?.focus() // Does nothing
+})
+</script>
+
+<template>
+  <!-- But template still uses old name -->
+  <input ref="input" />
+</template>
+```
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+// TYPO: 'inupt' instead of 'input' - no warning!
+const inupt = ref(null)
+</script>
+
+<template>
+  <input ref="input" />
+  <!-- inupt.value will always be null -->
+</template>
+```
+
+**Correct (Vue 3.5+):**
+```vue
+<script setup>
+import { useTemplateRef, onMounted } from 'vue'
+
+// CORRECT: Explicit binding - argument matches template ref
+const inputElement = useTemplateRef('my-input')
+
+onMounted(() => {
+  inputElement.value?.focus()
+})
+</script>
+
+<template>
+  <!-- ref name is explicitly connected via useTemplateRef argument -->
+  <input ref="my-input" />
+</template>
+```
+
+```vue
+<script setup>
+import { useTemplateRef, onMounted } from 'vue'
+
+// BENEFITS:
+// 1. Variable name is independent of ref attribute
+// 2. IDE auto-completes available ref names
+// 3. TypeScript infers correct element type
+// 4. Typos in argument cause visible errors
+
+const searchInput = useTemplateRef('search-box')
+const submitButton = useTemplateRef('submit-btn')
+
+onMounted(() => {
+  // TypeScript knows these are HTMLInputElement and HTMLButtonElement
+  searchInput.value?.focus()
+  submitButton.value?.disabled = false
+})
+</script>
+
+<template>
+  <input ref="search-box" type="search" />
+  <button ref="submit-btn">Submit</button>
+</template>
+```
+
+## Limitation: v-for Refs
+
+`useTemplateRef()` does **NOT** work with `v-for` refs. You must use the legacy `ref()` pattern for collecting multiple element references in a loop.
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+
+// CORRECT: Legacy pattern required for v-for refs
+const itemRefs = ref([])
+
+onMounted(() => {
+  // itemRefs.value is an array of DOM elements
+  itemRefs.value.forEach(el => {
+    console.log(el.textContent)
+  })
+})
+</script>
+
+<template>
+  <ul>
+    <li v-for="item in items" ref="itemRefs" :key="item.id">
+      {{ item.text }}
+    </li>
+  </ul>
+</template>
+```
+
+**Why this limitation exists:** When using `v-for`, Vue populates the ref with an array of elements. The `useTemplateRef()` API was designed for single element references and does not support the array population mechanism that `v-for` requires.
+
+## Migration Guide
+
+```vue
+<!-- BEFORE (Vue < 3.5) -->
+<script setup>
+import { ref } from 'vue'
+const myElement = ref(null) // Name must match template
+</script>
+<template>
+  <div ref="myElement"></div>
+</template>
+
+<!-- AFTER (Vue 3.5+) -->
+<script setup>
+import { useTemplateRef } from 'vue'
+const element = useTemplateRef('my-element') // Any variable name
+</script>
+<template>
+  <div ref="my-element"></div>
+</template>
+```
+
+## Reference
+- [Vue.js Template Refs - Composition API](https://vuejs.org/guide/essentials/template-refs.html#accessing-the-refs)
+- [Vue 3.5 Release Notes](https://blog.vuejs.org/posts/vue-3-5)

package/skills/vue-debug-guides/reference/v-else-must-follow-v-if.md

@@ -0,0 +1,136 @@
+---
+title: v-else Must Immediately Follow v-if or v-else-if
+impact: MEDIUM
+impactDescription: Misplaced v-else causes a compile-time error in SFCs, or renders unconditionally with runtime template compilation
+type: capability
+tags: [vue3, conditional-rendering, v-if, v-else, v-else-if]
+---
+
+# v-else Must Immediately Follow v-if or v-else-if
+
+**Impact: MEDIUM** - A `v-else` or `v-else-if` element must immediately follow a `v-if` or `v-else-if` element in the DOM. If there's any element in between:
+
+- **SFC compilation (Vite/vue-loader):** Vue throws a **compile-time SyntaxError** - the code won't build at all
+- **Runtime template compilation:** The element renders unconditionally (always visible), losing its conditional behavior
+
+In most modern Vue projects using Single File Components, this is caught at build time.
+
+## Task Checklist
+
+- [ ] Place v-else immediately after the v-if element (no elements in between)
+- [ ] Place v-else-if immediately after v-if or another v-else-if
+- [ ] Use `<template>` wrapper if you need to group multiple elements within a branch
+- [ ] If you need content between conditions, restructure using nested conditionals or computed
+
+**Incorrect:**
+```html
+<!-- WRONG: v-else not immediately after v-if -->
+<template>
+  <div v-if="isLoggedIn">
+    Welcome back!
+  </div>
+
+  <p>Some other content in between</p>
+
+  <div v-else>
+    <!-- This v-else is NOT recognized! It will ALWAYS render (unconditionally) -->
+    Please log in
+  </div>
+</template>
+```
+
+```html
+<!-- WRONG: Comment or whitespace element between -->
+<template>
+  <span v-if="status === 'loading'">Loading...</span>
+  <!-- This comment breaks the chain! -->
+  <span v-else-if="status === 'error'">Error occurred</span>
+  <span v-else>Done</span>
+</template>
+```
+
+```html
+<!-- WRONG: Text node between conditions -->
+<template>
+  <div v-if="showA">A</div>
+  Just some text here
+  <div v-else>B</div>  <!-- Not recognized, always renders -->
+</template>
+```
+
+**Correct:**
+```html
+<!-- CORRECT: v-else immediately follows v-if -->
+<template>
+  <div v-if="isLoggedIn">
+    Welcome back!
+  </div>
+  <div v-else>
+    Please log in
+  </div>
+
+  <p>Some other content (placed after the conditional block)</p>
+</template>
+```
+
+```html
+<!-- CORRECT: Full v-if/v-else-if/v-else chain -->
+<template>
+  <span v-if="status === 'loading'">Loading...</span>
+  <span v-else-if="status === 'error'">Error: {{ errorMessage }}</span>
+  <span v-else-if="status === 'empty'">No data found</span>
+  <span v-else>{{ data }}</span>
+</template>
+```
+
+```html
+<!-- CORRECT: Using <template> for multiple elements per branch -->
+<template>
+  <template v-if="isLoggedIn">
+    <h1>Welcome back!</h1>
+    <p>Your dashboard</p>
+    <UserStats />
+  </template>
+  <template v-else>
+    <h1>Please log in</h1>
+    <LoginForm />
+  </template>
+</template>
+```
+
+```html
+<!-- CORRECT: Restructure if you need content between conditions -->
+<template>
+  <div class="conditional-section">
+    <div v-if="isLoggedIn">Welcome back!</div>
+    <div v-else>Please log in</div>
+  </div>
+
+  <div class="always-shown">
+    Some other content
+  </div>
+
+  <div class="another-conditional">
+    <div v-if="showMore">More info</div>
+    <div v-else>Click to expand</div>
+  </div>
+</template>
+```
+
+## Debugging Tips
+
+```html
+<!-- If v-else is always visible (rendering unconditionally), check for: -->
+
+<!-- 1. Elements between v-if and v-else -->
+<!-- 2. HTML comments that break the chain -->
+<!-- 3. Text nodes (including whitespace in some cases) -->
+<!-- 4. Component tags that render content between -->
+
+<!-- SFC compilation throws: "v-else/v-else-if has no adjacent v-if or v-else-if" (build fails) -->
+<!-- Runtime template compilation shows a warning but renders the element unconditionally -->
+<!-- Vue DevTools will show the v-else element as not part of the condition chain -->
+```
+
+## Reference
+- [Vue.js Conditional Rendering - v-else](https://vuejs.org/guide/essentials/conditional.html#v-else)