@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/template-functions-no-side-effects.md

@@ -0,0 +1,187 @@
+---
+title: Template Functions Must Be Pure Without Side Effects
+impact: MEDIUM
+impactDescription: Functions with side effects in templates cause unpredictable behavior on every re-render
+type: efficiency
+tags: [vue3, template, functions, performance, side-effects]
+---
+
+# Template Functions Must Be Pure Without Side Effects
+
+**Impact: MEDIUM** - Functions called in templates execute on every component re-render. Functions with side effects (modifying data, API calls, logging) will cause unpredictable behavior, performance issues, and difficult-to-debug bugs.
+
+Template expressions including function calls are evaluated whenever the component updates. This makes them unsuitable for operations that should only happen once or that modify state.
+
+## Task Checklist
+
+- [ ] Keep template functions pure (same input = same output)
+- [ ] Never modify reactive state inside template functions
+- [ ] Never make API calls or async operations in template functions
+- [ ] Move side effects to event handlers, watchers, or lifecycle hooks
+- [ ] Use computed properties for derived values instead of functions when possible
+- [ ] Avoid expensive computations; use computed properties for caching
+
+**Incorrect:**
+```vue
+<template>
+  <!-- BAD: Modifies state on every render -->
+  <p>{{ incrementAndGet() }}</p>
+
+  <!-- BAD: API call on every render -->
+  <div>{{ fetchUserName() }}</div>
+
+  <!-- BAD: Logging side effect -->
+  <span>{{ logAndFormat(date) }}</span>
+
+  <!-- BAD: Expensive computation without caching -->
+  <ul>
+    <li v-for="item in filterAndSort(items)" :key="item.id">
+      {{ item.name }}
+    </li>
+  </ul>
+
+  <!-- BAD: Random values change on every render -->
+  <p>{{ getRandomGreeting() }}</p>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const count = ref(0)
+const items = ref([/* large array */])
+
+// BAD: Has side effect - modifies state
+function incrementAndGet() {
+  count.value++  // Side effect!
+  return count.value
+}
+
+// BAD: Async operation in template
+async function fetchUserName() {
+  const res = await fetch('/api/user')  // Side effect!
+  return (await res.json()).name
+}
+
+// BAD: Logging is a side effect
+function logAndFormat(date) {
+  console.log('Formatting date:', date)  // Side effect!
+  return new Date(date).toLocaleDateString()
+}
+
+// BAD: Expensive, runs every render without caching
+function filterAndSort(items) {
+  return items
+    .filter(i => i.active)
+    .sort((a, b) => a.name.localeCompare(b.name))
+}
+
+// BAD: Non-deterministic
+function getRandomGreeting() {
+  const greetings = ['Hello', 'Hi', 'Hey']
+  return greetings[Math.floor(Math.random() * greetings.length)]
+}
+</script>
+```
+
+**Correct:**
+```vue
+<template>
+  <!-- OK: Pure formatting function -->
+  <p>Count: {{ count }}</p>
+  <button @click="increment">Increment</button>
+
+  <!-- OK: Data fetched via lifecycle/watcher -->
+  <div>{{ userName }}</div>
+
+  <!-- OK: Pure function, no side effects -->
+  <span>{{ formatDate(date) }}</span>
+
+  <!-- OK: Computed property caches result -->
+  <ul>
+    <li v-for="item in filteredAndSortedItems" :key="item.id">
+      {{ item.name }}
+    </li>
+  </ul>
+
+  <!-- OK: Random value set once -->
+  <p>{{ greeting }}</p>
+</template>
+
+<script setup>
+import { ref, computed, onMounted } from 'vue'
+
+const count = ref(0)
+const userName = ref('')
+const date = ref(new Date())
+const items = ref([/* large array */])
+
+// Side effects in event handlers
+function increment() {
+  count.value++
+}
+
+// Fetch data in lifecycle hook
+onMounted(async () => {
+  const res = await fetch('/api/user')
+  userName.value = (await res.json()).name
+})
+
+// Pure function - same input, same output
+function formatDate(date) {
+  return new Date(date).toLocaleDateString()
+}
+
+// Computed property - cached, only recalculates when dependencies change
+const filteredAndSortedItems = computed(() => {
+  return items.value
+    .filter(i => i.active)
+    .sort((a, b) => a.name.localeCompare(b.name))
+})
+
+// Set random value once, not on every render
+const greetings = ['Hello', 'Hi', 'Hey']
+const greeting = ref(greetings[Math.floor(Math.random() * greetings.length)])
+</script>
+```
+
+## Pure Function Guidelines
+
+A pure function:
+1. Given the same inputs, always returns the same output
+2. Does not modify any external state
+3. Does not perform I/O operations (network, console, file system)
+4. Does not depend on mutable external state
+
+```javascript
+// PURE - safe for templates
+function formatCurrency(amount, currency = 'USD') {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(amount)
+}
+
+function fullName(first, last) {
+  return `${first} ${last}`
+}
+
+function isExpired(date) {
+  return new Date(date) < new Date()
+}
+
+// IMPURE - unsafe for templates
+function logAndReturn(value) {
+  console.log(value)  // I/O
+  return value
+}
+
+function getFromLocalStorage(key) {
+  return localStorage.getItem(key)  // External state
+}
+
+function updateAndReturn(obj, key, value) {
+  obj[key] = value  // Mutation
+  return obj
+}
+```
+
+## Reference
+- [Vue.js Template Syntax - Calling Functions](https://vuejs.org/guide/essentials/template-syntax.html#calling-functions)
+- [Vue.js Computed Properties](https://vuejs.org/guide/essentials/computed.html)

package/skills/vue-debug-guides/reference/template-ref-null-with-v-if.md

@@ -0,0 +1,123 @@
+---
+title: Template Refs Become Null When Elements Are Unmounted
+impact: MEDIUM
+impactDescription: Refs become null when conditionally rendered elements are removed, causing errors if not handled
+type: gotcha
+tags: [vue3, template-refs, v-if, watchers, conditional-rendering]
+---
+
+# Template Refs Become Null When Elements Are Unmounted
+
+**Impact: MEDIUM** - When using template refs with `v-if`, the ref becomes `null` when the element is unmounted. Watchers and effects that access these refs must handle the null case to avoid runtime errors.
+
+This is especially tricky with `watchEffect` since it runs automatically and may execute when the ref is null.
+
+## Task Checklist
+
+- [ ] Always check for null before accessing ref properties when using v-if
+- [ ] In watchers, explicitly handle the null case (element unmounted or not yet mounted)
+- [ ] Consider whether v-show is more appropriate if you need persistent ref access
+- [ ] Use optional chaining (?.) when accessing ref properties in uncertain contexts
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref, watchEffect } from 'vue'
+
+const inputEl = ref(null)
+const showInput = ref(true)
+
+// WRONG: No null check - will error when v-if is false
+watchEffect(() => {
+  inputEl.value.focus() // TypeError when showInput is false
+})
+</script>
+
+<template>
+  <input v-if="showInput" ref="inputEl" />
+  <button @click="showInput = !showInput">Toggle</button>
+</template>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref, watchEffect } from 'vue'
+
+const inputEl = ref(null)
+const showInput = ref(true)
+
+// CORRECT: Handle both mounted and unmounted states
+watchEffect(() => {
+  if (inputEl.value) {
+    inputEl.value.focus()
+  } else {
+    // Element not mounted yet, or unmounted by v-if
+    console.log('Input element not available')
+  }
+})
+</script>
+
+<template>
+  <input v-if="showInput" ref="inputEl" />
+  <button @click="showInput = !showInput">Toggle</button>
+</template>
+```
+
+```vue
+<script setup>
+import { ref, watch } from 'vue'
+
+const inputEl = ref(null)
+const showInput = ref(true)
+
+// CORRECT: Watch the ref and handle null explicitly
+watch(inputEl, (el) => {
+  if (el) {
+    el.focus()
+  }
+})
+</script>
+
+<template>
+  <input v-if="showInput" ref="inputEl" />
+</template>
+```
+
+```vue
+<script setup>
+import { useTemplateRef, watchEffect } from 'vue'
+
+// Vue 3.5+ approach
+const input = useTemplateRef('my-input')
+
+// CORRECT: Use optional chaining for safe access
+watchEffect(() => {
+  input.value?.focus()
+})
+</script>
+
+<template>
+  <input v-if="showInput" ref="my-input" />
+</template>
+```
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const inputEl = ref(null)
+const showInput = ref(true)
+
+// ALTERNATIVE: Use v-show if you need consistent ref access
+// v-show keeps element in DOM, just hides it with CSS
+</script>
+
+<template>
+  <!-- Element always exists in DOM, ref is never null -->
+  <input v-show="showInput" ref="inputEl" />
+</template>
+```
+
+## Reference
+- [Vue.js Template Refs](https://vuejs.org/guide/essentials/template-refs.html)

package/skills/vue-debug-guides/reference/template-ref-unwrapping-top-level.md

@@ -0,0 +1,104 @@
+---
+title: Template Ref Unwrapping Only Works for Top-Level Properties
+impact: MEDIUM
+impactDescription: Nested refs in template expressions render as [object Object] instead of their values
+type: capability
+tags: [vue3, reactivity, ref, template, unwrapping]
+---
+
+# Template Ref Unwrapping Only Works for Top-Level Properties
+
+**Impact: MEDIUM** - Vue only auto-unwraps refs that are top-level properties in the template render context. Nested refs (refs inside objects) are NOT unwrapped in expressions, causing `[object Object]` rendering or calculation errors.
+
+This caveat trips up developers when they store refs inside reactive objects or plain objects and try to use them in template expressions like `{{ object.count + 1 }}`.
+
+## Task Checklist
+
+- [ ] Keep refs at the top level of your setup return or script setup
+- [ ] Destructure nested refs to top-level variables before using in expressions
+- [ ] Be aware that text interpolation `{{ object.ref }}` DOES unwrap, but expressions `{{ object.ref + 1 }}` do NOT
+- [ ] Consider restructuring data to avoid nested refs in templates
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const count = ref(0)
+const object = { id: ref(1) }
+</script>
+
+<template>
+  <!-- WRONG: Nested ref in expression - does NOT unwrap -->
+  <p>ID + 1 = {{ object.id + 1 }}</p>
+  <!-- Renders: "ID + 1 = [object Object]1" -->
+
+  <!-- Surprisingly, plain interpolation DOES work -->
+  <p>ID = {{ object.id }}</p>
+  <!-- Renders: "ID = 1" (unwrapped because it's the final expression) -->
+</template>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const count = ref(0)
+const object = { id: ref(1) }
+
+// SOLUTION 1: Destructure to top-level
+const { id } = object
+</script>
+
+<template>
+  <!-- CORRECT: Top-level ref unwraps in all expressions -->
+  <p>Count + 1 = {{ count + 1 }}</p>
+  <!-- Renders: "Count + 1 = 1" -->
+
+  <!-- CORRECT: Destructured ref is now top-level -->
+  <p>ID + 1 = {{ id + 1 }}</p>
+  <!-- Renders: "ID + 1 = 2" -->
+</template>
+```
+
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+
+const object = { id: ref(1) }
+
+// SOLUTION 2: Use computed for derived values
+const idPlusOne = computed(() => object.id.value + 1)
+</script>
+
+<template>
+  <!-- CORRECT: Computed handles the .value access -->
+  <p>ID + 1 = {{ idPlusOne }}</p>
+</template>
+```
+
+```vue
+<script setup>
+import { reactive } from 'vue'
+
+// SOLUTION 3: Use reactive object instead (refs inside reactive auto-unwrap)
+const object = reactive({ id: 1 })
+</script>
+
+<template>
+  <!-- CORRECT: Plain reactive property works in expressions -->
+  <p>ID + 1 = {{ object.id + 1 }}</p>
+</template>
+```
+
+```javascript
+// WHY this happens:
+// - Template compilation only adds .value to top-level identifiers
+// - {{ count + 1 }} compiles to: count.value + 1
+// - {{ object.id + 1 }} compiles to: object.id + 1 (no .value added!)
+// - Plain {{ object.id }} has special handling for display purposes
+```
+
+## Reference
+- [Vue.js Reactivity Fundamentals - Caveat when Unwrapping in Templates](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#caveat-when-unwrapping-in-templates)

package/skills/vue-debug-guides/reference/template-ref-v-for-order.md

@@ -0,0 +1,172 @@
+---
+title: Template Ref Array Order Not Guaranteed in v-for
+impact: MEDIUM
+impactDescription: Refs collected from v-for may not match source array order, causing index-based bugs
+type: gotcha
+tags: [vue3, template-refs, v-for, arrays, ordering]
+---
+
+# Template Ref Array Order Not Guaranteed in v-for
+
+**Impact: MEDIUM** - When using template refs inside `v-for`, Vue collects the element references into an array. However, this array does NOT guarantee the same order as the source array. Relying on index-based access can lead to subtle bugs.
+
+This caveat is not obvious and can cause hard-to-debug issues when you assume the ref array matches your data order.
+
+> **Warning: `useTemplateRef()` does NOT work with v-for refs in Vue 3.5**
+>
+> The `useTemplateRef()` API returns `null` when used with refs inside `v-for`. This is a known limitation. You must use the legacy pattern with `ref()` and a matching template ref name:
+>
+> ```ts
+> // Does NOT work with v-for - returns null
+> const itemRefs = useTemplateRef('items')
+>
+> // Works with v-for - use this pattern instead
+> const items = ref([])  // name must match ref="items" in template
+> ```
+>
+> The examples in this rule show `useTemplateRef()` for illustration, but in practice you should use the legacy `ref()` pattern for v-for scenarios until this limitation is addressed.
+
+## Task Checklist
+
+- [ ] Never assume ref array indices match source data array indices
+- [ ] Use data attributes or other identifiers to correlate refs with data
+- [ ] Consider function refs for complex scenarios requiring ordered access
+- [ ] Test with dynamic list operations (add, remove, reorder) to verify behavior
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref, useTemplateRef, onMounted } from 'vue'
+
+const items = ref(['First', 'Second', 'Third'])
+const itemRefs = useTemplateRef('items')
+
+onMounted(() => {
+  // WRONG: Assuming itemRefs[0] corresponds to items[0]
+  // The order is NOT guaranteed to match!
+  items.value.forEach((item, index) => {
+    console.log(`${item}: `, itemRefs.value[index]) // May be wrong element!
+  })
+})
+</script>
+
+<template>
+  <ul>
+    <li v-for="item in items" ref="items" :key="item">
+      {{ item }}
+    </li>
+  </ul>
+</template>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref, useTemplateRef, onMounted } from 'vue'
+
+const items = ref([
+  { id: 1, text: 'First' },
+  { id: 2, text: 'Second' },
+  { id: 3, text: 'Third' }
+])
+const itemRefs = useTemplateRef('items')
+
+onMounted(() => {
+  // CORRECT: Use data attributes to identify elements
+  itemRefs.value.forEach(el => {
+    const id = el.dataset.id
+    const item = items.value.find(i => i.id === Number(id))
+    console.log(`${item.text}: `, el)
+  })
+})
+</script>
+
+<template>
+  <ul>
+    <li
+      v-for="item in items"
+      ref="items"
+      :key="item.id"
+      :data-id="item.id"
+    >
+      {{ item.text }}
+    </li>
+  </ul>
+</template>
+```
+
+```vue
+<script setup>
+import { ref, onMounted, onBeforeUpdate } from 'vue'
+
+const items = ref(['First', 'Second', 'Third'])
+const itemRefs = ref(new Map())
+
+// CORRECT: Use function refs for precise control
+function setItemRef(el, item) {
+  if (el) {
+    itemRefs.value.set(item, el)
+  } else {
+    itemRefs.value.delete(item)
+  }
+}
+
+// Reset before each update to handle removed items
+onBeforeUpdate(() => {
+  itemRefs.value.clear()
+})
+
+onMounted(() => {
+  // Access refs by their associated data item
+  items.value.forEach(item => {
+    const el = itemRefs.value.get(item)
+    console.log(`${item}: `, el)
+  })
+})
+</script>
+
+<template>
+  <ul>
+    <li
+      v-for="item in items"
+      :key="item"
+      :ref="(el) => setItemRef(el, item)"
+    >
+      {{ item }}
+    </li>
+  </ul>
+</template>
+```
+
+```vue
+<script setup>
+import { ref, useTemplateRef, onMounted } from 'vue'
+
+const items = ref(['First', 'Second', 'Third'])
+const itemRefs = useTemplateRef('items')
+
+// CORRECT: If order matters, sort refs by DOM position
+onMounted(() => {
+  const sortedRefs = [...itemRefs.value].sort((a, b) => {
+    // Sort by DOM order using compareDocumentPosition
+    return a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1
+  })
+
+  // Now sortedRefs matches visual/DOM order
+  sortedRefs.forEach((el, index) => {
+    console.log(`Position ${index}: `, el.textContent)
+  })
+})
+</script>
+
+<template>
+  <ul>
+    <li v-for="item in items" ref="items" :key="item">
+      {{ item }}
+    </li>
+  </ul>
+</template>
+```
+
+## Reference
+- [Vue.js Template Refs - Refs inside v-for](https://vuejs.org/guide/essentials/template-refs.html#refs-inside-v-for)

package/skills/vue-debug-guides/reference/textarea-no-interpolation.md

@@ -0,0 +1,72 @@
+---
+title: Textarea Interpolation is One-Way Only - Use v-model for Two-Way Binding
+impact: HIGH
+impactDescription: Using {{ text }} inside textarea displays initial value but user input does NOT update the ref
+type: capability
+tags: [vue3, v-model, forms, textarea, interpolation, template]
+---
+
+# Textarea Interpolation is One-Way Only - Use v-model for Two-Way Binding
+
+**Impact: HIGH** - Interpolation in textarea (`{{ text }}`) provides one-way binding only - it displays the initial value but user input does NOT update the ref. This creates a confusing disconnect where the textarea shows content but edits are silently lost.
+
+Unlike v-model which provides two-way binding, interpolation only renders the initial ref value into the textarea. When users type, the ref remains unchanged, making form submissions return stale data. Always use v-model for two-way binding in textareas.
+
+## Task Checklist
+
+- [ ] Never use interpolation inside textarea tags
+- [ ] Always use v-model for textarea two-way binding
+- [ ] Search codebase for `<textarea>{{` patterns that may be silently broken
+- [ ] Add linting rules to catch this pattern if possible
+
+**Incorrect:**
+```html
+<script setup>
+import { ref } from 'vue'
+
+const message = ref('Hello World')
+</script>
+
+<template>
+  <!-- WRONG: One-way binding only! Shows initial value but edits don't update ref -->
+  <textarea>{{ message }}</textarea>
+
+  <!-- Also WRONG: User can type but changes are lost -->
+  <textarea>{{ userBio }}</textarea>
+
+  <!-- The textarea displays content but ref never updates -->
+</template>
+```
+
+**Correct:**
+```html
+<script setup>
+import { ref } from 'vue'
+
+const message = ref('Hello World')
+</script>
+
+<template>
+  <!-- CORRECT: Use v-model for textarea -->
+  <textarea v-model="message"></textarea>
+
+  <!-- For read-only display, still use v-model or :value -->
+  <textarea v-model="message" readonly></textarea>
+
+  <!-- Or one-way binding with :value -->
+  <textarea :value="message" readonly></textarea>
+</template>
+```
+
+```html
+<!-- With placeholder and other attributes -->
+<textarea
+  v-model="message"
+  placeholder="Enter your message..."
+  rows="5"
+  maxlength="500"
+></textarea>
+```
+
+## Reference
+- [Vue.js Form Input Bindings - Multiline text](https://vuejs.org/guide/essentials/forms.html#multiline-text)