@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/v-model-number-modifier-behavior.md

@@ -0,0 +1,124 @@
+---
+title: v-model.number Uses parseFloat Not valueAsNumber
+impact: MEDIUM
+impactDescription: .number modifier returns empty string for empty input and uses parseFloat, not native valueAsNumber
+type: capability
+tags: [vue3, v-model, forms, input, number, type-coercion, modifiers]
+---
+
+# v-model.number Uses parseFloat Not valueAsNumber
+
+**Impact: MEDIUM** - The `.number` modifier doesn't behave like the native `valueAsNumber` property. It returns an empty string (not NaN) for empty inputs, and uses `parseFloat()` which has different parsing rules. This can cause unexpected type issues in calculations and validations.
+
+Understanding these differences is crucial when working with numeric forms, especially for calculations, min/max validation, or when interfacing with APIs that expect strict number types.
+
+## Task Checklist
+
+- [ ] Expect empty string (not 0 or NaN) when input is cleared with `.number` modifier
+- [ ] Handle the empty string case in your validation and calculations
+- [ ] Remember `.number` uses parseFloat - "123abc" becomes 123, not NaN
+- [ ] For strict numeric parsing, add custom validation
+
+**Key Differences:**
+
+| Scenario | `.number` modifier | Native `valueAsNumber` |
+|----------|-------------------|----------------------|
+| Empty input | `''` (empty string) | `NaN` |
+| `"123"` | `123` | `123` |
+| `"123.45"` | `123.45` | `123.45` |
+| `"123abc"` | `123` | `NaN` |
+| `"abc"` | `'abc'` (original string) | `NaN` |
+
+**Problem - Unexpected types:**
+```html
+<script setup>
+import { ref, computed } from 'vue'
+
+const price = ref(0)
+const quantity = ref(1)
+
+const total = computed(() => {
+  // PROBLEM: price might be '' (empty string) when input is cleared
+  return price.value * quantity.value  // '' * 1 = 0, but typeof is still number
+})
+
+function validatePrice() {
+  // PROBLEM: This check fails when input is empty
+  if (typeof price.value !== 'number') {
+    // Never enters here! '' is still treated as "processed"
+  }
+
+  // PROBLEM: parseFloat("$100") returns NaN, but "100abc" returns 100
+}
+</script>
+
+<template>
+  <input v-model.number="price" type="number">
+  <!-- When user clears input, price.value becomes '' not 0 or NaN -->
+</template>
+```
+
+**Solution - Handle empty string explicitly:**
+```html
+<script setup>
+import { ref, computed } from 'vue'
+
+const price = ref(0)
+const quantity = ref(1)
+
+const total = computed(() => {
+  // CORRECT: Handle empty string case
+  const priceNum = price.value === '' ? 0 : price.value
+  return priceNum * quantity.value
+})
+
+// Or use a wrapper computed for safer access
+const safePrice = computed(() => {
+  if (price.value === '' || price.value === null) return 0
+  return Number(price.value) || 0
+})
+</script>
+
+<template>
+  <input v-model.number="price" type="number" min="0">
+  <p>Total: ${{ total.toFixed(2) }}</p>
+</template>
+```
+
+**Solution - Custom input handling for strict parsing:**
+```html
+<script setup>
+import { ref } from 'vue'
+
+const price = ref(0)
+
+function handlePriceInput(event) {
+  const value = event.target.value
+
+  // Strict parsing - only accept valid numbers
+  const parsed = parseFloat(value)
+
+  if (value === '') {
+    price.value = 0  // Or null, depending on your needs
+  } else if (!isNaN(parsed) && isFinite(parsed)) {
+    // Additional check: ensure entire string is numeric
+    if (/^-?\d*\.?\d+$/.test(value.trim())) {
+      price.value = parsed
+    }
+  }
+  // Invalid input - keep previous value
+}
+</script>
+
+<template>
+  <!-- Manual binding for strict numeric control -->
+  <input
+    :value="price"
+    @input="handlePriceInput"
+    type="number"
+  >
+</template>
+```
+
+## Reference
+- [Vue.js Form Input Bindings - .number](https://vuejs.org/guide/essentials/forms.html#number)

package/skills/vue-debug-guides/reference/v-show-template-limitation.md

@@ -0,0 +1,124 @@
+---
+title: v-show Does Not Work on template or With v-else
+impact: MEDIUM
+impactDescription: Using v-show on template silently fails, element is always rendered
+type: capability
+tags: [vue3, conditional-rendering, v-show, template, limitations]
+---
+
+# v-show Does Not Work on template or With v-else
+
+**Impact: MEDIUM** - `v-show` cannot be used on `<template>` elements because templates don't render to the DOM (so there's nothing to apply `display: none` to). Additionally, `v-show` does not support `v-else`. Using these incorrectly results in elements that are always visible or else branches that never work.
+
+## Task Checklist
+
+- [ ] Never use v-show on `<template>` elements - use v-if instead
+- [ ] Never use v-else with v-show - use separate v-show with negated condition
+- [ ] Remember v-show only works on actual DOM elements
+- [ ] If you need to toggle multiple elements frequently, wrap in a real element (div, span)
+
+**Incorrect:**
+```html
+<!-- WRONG: v-show on <template> - silently does nothing -->
+<template>
+  <template v-show="isVisible">
+    <h1>Title</h1>
+    <p>Content</p>
+  </template>
+  <!-- These elements will ALWAYS be visible -->
+</template>
+```
+
+```html
+<!-- WRONG: v-else with v-show - v-else is not supported -->
+<template>
+  <div v-show="isLoggedIn">Welcome!</div>
+  <div v-else>Please log in</div>  <!-- This v-else won't work -->
+</template>
+```
+
+```html
+<!-- WRONG: Mixing v-show and v-else expectations -->
+<template>
+  <span v-show="status === 'success'">Success!</span>
+  <span v-else-if="status === 'error'">Error</span>  <!-- Not supported -->
+</template>
+```
+
+**Correct:**
+```html
+<!-- CORRECT: Use v-if on <template> for multiple elements -->
+<template>
+  <template v-if="isVisible">
+    <h1>Title</h1>
+    <p>Content</p>
+  </template>
+</template>
+```
+
+```html
+<!-- CORRECT: Use negated v-show for "else" behavior -->
+<template>
+  <div v-show="isLoggedIn">Welcome!</div>
+  <div v-show="!isLoggedIn">Please log in</div>
+</template>
+```
+
+```html
+<!-- CORRECT: Wrap in a real element if you need v-show for multiple elements -->
+<template>
+  <div v-show="isVisible">
+    <h1>Title</h1>
+    <p>Content</p>
+  </div>
+</template>
+```
+
+```html
+<!-- CORRECT: Use v-if/v-else when you need else branches -->
+<template>
+  <div v-if="status === 'success'">Success!</div>
+  <div v-else-if="status === 'error'">Error</div>
+  <div v-else>Loading...</div>
+</template>
+```
+
+```html
+<!-- CORRECT: Multiple v-show conditions -->
+<template>
+  <span v-show="status === 'success'">Success!</span>
+  <span v-show="status === 'error'">Error</span>
+  <span v-show="status === 'loading'">Loading...</span>
+</template>
+```
+
+## Why This Limitation Exists
+
+```javascript
+// v-show works by toggling the CSS display property
+// This requires an actual DOM element
+
+// <template> is a virtual element - it doesn't render to DOM
+// It's just a wrapper for Vue's rendering logic
+
+// After compilation:
+// <template v-if="show"><p>Hi</p></template>
+// Renders as: <p>Hi</p> (when show is true)
+// Template itself is gone
+
+// v-show needs a real element to set display: none on
+// Since <template> doesn't exist in DOM, v-show has nothing to work with
+```
+
+## When to Choose Each
+
+| Need | Use |
+|------|-----|
+| Toggle multiple elements with CSS | Wrap in real element + `v-show` |
+| Toggle multiple elements without wrapper | `<template v-if>` |
+| Need v-else branches | `v-if`/`v-else` |
+| Frequent toggle, single element | `v-show` |
+| Frequent toggle, need "else" | Two `v-show` with negated conditions |
+
+## Reference
+- [Vue.js Conditional Rendering - v-show](https://vuejs.org/guide/essentials/conditional.html#v-show)

package/skills/vue-debug-guides/reference/watch-async-cleanup.md

@@ -0,0 +1,180 @@
+---
+title: Clean Up Async Operations in Watchers to Prevent Race Conditions
+impact: HIGH
+impactDescription: Stale async requests can overwrite newer data, causing incorrect UI state and hard-to-debug issues
+type: capability
+tags: [vue3, watch, watchers, async, cleanup, race-condition, abort]
+---
+
+# Clean Up Async Operations in Watchers to Prevent Race Conditions
+
+**Impact: HIGH** - When a watched value changes rapidly, multiple async operations run concurrently. Without cleanup, a slow earlier request can complete after a faster later request, overwriting current data with stale results.
+
+Always use `onWatcherCleanup` or the `onCleanup` callback parameter to cancel pending async operations when the watcher re-runs or the component unmounts.
+
+## Task Checklist
+
+- [ ] Use `onWatcherCleanup()` or `onCleanup` parameter in async watchers
+- [ ] Use `AbortController` to cancel pending fetch requests
+- [ ] Cancel any setTimeout/setInterval calls in cleanup
+- [ ] Invalidate previous async operation results with flags
+- [ ] Consider debouncing rapid changes before fetching
+
+**Incorrect:**
+```javascript
+import { ref, watch } from 'vue'
+
+const searchQuery = ref('')
+const results = ref([])
+
+// BAD: Race condition - slow request for "a" can finish after fast request for "ab"
+watch(searchQuery, async (query) => {
+  if (query) {
+    const response = await fetch(`/api/search?q=${query}`)
+    results.value = await response.json()  // May overwrite newer results!
+  }
+})
+
+// BAD: No cleanup for timeouts
+watch(searchQuery, (query) => {
+  // Previous timeout keeps running even when query changes
+  setTimeout(() => {
+    performExpensiveSearch(query)
+  }, 500)
+})
+```
+
+**Correct:**
+```javascript
+import { ref, watch, onWatcherCleanup } from 'vue'
+
+const searchQuery = ref('')
+const results = ref([])
+const loading = ref(false)
+
+// CORRECT: Using onWatcherCleanup (Vue 3.5+)
+watch(searchQuery, async (query) => {
+  if (!query) {
+    results.value = []
+    return
+  }
+
+  const controller = new AbortController()
+
+  // Register cleanup to abort on re-run or unmount
+  onWatcherCleanup(() => {
+    controller.abort()
+  })
+
+  loading.value = true
+  try {
+    const response = await fetch(`/api/search?q=${query}`, {
+      signal: controller.signal
+    })
+    results.value = await response.json()
+  } catch (err) {
+    if (err.name !== 'AbortError') {
+      console.error('Search failed:', err)
+    }
+  } finally {
+    loading.value = false
+  }
+})
+```
+
+## Using onCleanup Parameter
+
+```javascript
+import { ref, watch } from 'vue'
+
+const userId = ref(1)
+const userData = ref(null)
+
+// CORRECT: Using onCleanup callback parameter
+watch(userId, (newId, oldId, onCleanup) => {
+  const controller = new AbortController()
+
+  fetch(`/api/users/${newId}`, { signal: controller.signal })
+    .then(res => res.json())
+    .then(data => {
+      userData.value = data
+    })
+    .catch(err => {
+      if (err.name !== 'AbortError') {
+        console.error(err)
+      }
+    })
+
+  onCleanup(() => {
+    controller.abort()
+  })
+})
+```
+
+## Cleanup with Timeouts
+
+```javascript
+import { ref, watch, onWatcherCleanup } from 'vue'
+
+const input = ref('')
+
+// CORRECT: Cancel previous timeout on new input
+watch(input, (value) => {
+  const timeoutId = setTimeout(() => {
+    performExpensiveOperation(value)
+  }, 300)
+
+  onWatcherCleanup(() => {
+    clearTimeout(timeoutId)
+  })
+})
+```
+
+## Invalidation Flag Pattern
+
+```javascript
+import { ref, watch } from 'vue'
+
+const id = ref(1)
+const data = ref(null)
+
+// CORRECT: Invalidation flag for non-abortable operations
+watch(id, async (newId, oldId, onCleanup) => {
+  let cancelled = false
+
+  onCleanup(() => {
+    cancelled = true
+  })
+
+  const result = await someNonAbortableAsyncOperation(newId)
+
+  // Check if this watch run is still valid
+  if (!cancelled) {
+    data.value = result
+  }
+})
+```
+
+## watchEffect Cleanup
+
+```javascript
+import { ref, watchEffect, onWatcherCleanup } from 'vue'
+
+const resourceId = ref('abc')
+
+watchEffect(async () => {
+  const id = resourceId.value
+  const controller = new AbortController()
+
+  onWatcherCleanup(() => {
+    controller.abort()
+  })
+
+  const data = await fetchResource(id, { signal: controller.signal })
+  processData(data)
+})
+```
+
+## Reference
+- [Vue.js Watchers - Callback Flush Timing](https://vuejs.org/guide/essentials/watchers.html#callback-flush-timing)
+- [Vue.js Watchers - Side Effect Cleanup](https://vuejs.org/api/reactivity-core.html#watcheffect)

package/skills/vue-debug-guides/reference/watch-async-creation-memory-leak.md

@@ -0,0 +1,176 @@
+---
+title: Watchers Created Asynchronously Must Be Manually Stopped
+impact: HIGH
+impactDescription: Async-created watchers are not bound to component lifecycle and cause memory leaks
+type: capability
+tags: [vue3, watch, watchers, async, memory-leak, lifecycle, cleanup]
+---
+
+# Watchers Created Asynchronously Must Be Manually Stopped
+
+**Impact: HIGH** - Watchers created inside async callbacks (setTimeout, Promise.then, async/await) are not automatically bound to the component instance. They continue running after the component unmounts, causing memory leaks and errors.
+
+Always manually stop watchers that are created asynchronously, or restructure your code to create watchers synchronously with conditional logic.
+
+## Task Checklist
+
+- [ ] Create watchers synchronously in setup() or lifecycle hooks when possible
+- [ ] If async creation is unavoidable, store and call the unwatch function
+- [ ] Use `onUnmounted` to clean up async-created watchers
+- [ ] Consider using conditional logic inside a sync watcher instead
+- [ ] Watch for this pattern in setTimeout, Promise callbacks, and after await
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref, watch, watchEffect, onMounted } from 'vue'
+
+const data = ref(null)
+
+// BAD: Watcher created in setTimeout won't auto-stop
+onMounted(() => {
+  setTimeout(() => {
+    watchEffect(() => {
+      console.log(data.value)  // Keeps running after unmount!
+    })
+  }, 1000)
+})
+
+// BAD: Watcher created after await won't auto-stop
+onMounted(async () => {
+  await loadInitialData()
+
+  // This watcher is NOT bound to component lifecycle
+  watch(data, (newVal) => {
+    processData(newVal)  // Memory leak!
+  })
+})
+
+// BAD: Watcher in Promise callback
+fetch('/api/config').then(() => {
+  watch(data, () => {
+    // Leaks memory!
+  })
+})
+</script>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref, watch, watchEffect, onMounted, onUnmounted } from 'vue'
+
+const data = ref(null)
+const isDataLoaded = ref(false)
+let asyncWatcherCleanup = null
+
+// CORRECT: Synchronous watcher with conditional logic
+watch(
+  data,
+  (newVal) => {
+    if (isDataLoaded.value && newVal) {
+      processData(newVal)
+    }
+  }
+)
+
+onMounted(async () => {
+  await loadInitialData()
+  isDataLoaded.value = true
+})
+
+// CORRECT: Manual cleanup for async-created watcher
+onMounted(() => {
+  setTimeout(() => {
+    const unwatch = watchEffect(() => {
+      console.log(data.value)
+    })
+
+    // Store for cleanup
+    asyncWatcherCleanup = unwatch
+  }, 1000)
+})
+
+onUnmounted(() => {
+  // Clean up async watcher
+  if (asyncWatcherCleanup) {
+    asyncWatcherCleanup()
+  }
+})
+</script>
+```
+
+## Preferred Pattern: Conditional Watch Logic
+
+```vue
+<script setup>
+import { ref, watch, onMounted } from 'vue'
+
+const config = ref(null)
+const userData = ref(null)
+
+// BEST: Create watcher synchronously, handle async condition inside
+watch(
+  userData,
+  (newData) => {
+    // Only process when config is loaded
+    if (config.value && newData) {
+      applyUserSettings(config.value, newData)
+    }
+  }
+)
+
+onMounted(async () => {
+  config.value = await fetchConfig()
+  // Watcher will start processing once config is loaded
+})
+</script>
+```
+
+## Using watchEffect with Conditional Logic
+
+```vue
+<script setup>
+import { ref, watchEffect, onMounted } from 'vue'
+
+const apiData = ref(null)
+const isReady = ref(false)
+
+// GOOD: Synchronous watchEffect with condition
+watchEffect(() => {
+  if (isReady.value && apiData.value) {
+    // This pattern avoids async watcher creation
+    doSomethingWithData(apiData.value)
+  }
+})
+
+onMounted(async () => {
+  apiData.value = await fetchData()
+  isReady.value = true
+})
+</script>
+```
+
+## Tracking Multiple Async Watchers
+
+```vue
+<script setup>
+import { ref, watch, onUnmounted } from 'vue'
+
+const unwatchers = []
+
+function createDynamicWatcher(source, callback) {
+  const unwatch = watch(source, callback)
+  unwatchers.push(unwatch)
+  return unwatch
+}
+
+// Clean up all dynamic watchers
+onUnmounted(() => {
+  unwatchers.forEach(unwatch => unwatch())
+})
+</script>
+```
+
+## Reference
+- [Vue.js Watchers - Stopping a Watcher](https://vuejs.org/guide/essentials/watchers.html#stopping-a-watcher)