@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/v-for-component-props.md

@@ -0,0 +1,95 @@
+---
+title: Always Pass v-for Data to Components via Props
+impact: MEDIUM
+impactDescription: Components have isolated scope - v-for iteration data is not automatically available inside child components
+type: gotcha
+tags: [vue3, v-for, components, props, list-rendering]
+---
+
+# Always Pass v-for Data to Components via Props
+
+**Impact: MEDIUM** - Vue components have isolated scope by design. When using `v-for` to render components, the iteration variable (e.g., `item`) is NOT automatically available inside the child component. You must explicitly pass the data through props.
+
+This isolation is intentional - it keeps components reusable and their data dependencies explicit. Forgetting to pass props results in `undefined` data or errors about missing properties.
+
+## Task Checklist
+
+- [ ] Always bind iteration data to component props explicitly
+- [ ] Pass both the item and index if the component needs them
+- [ ] Always include a unique `:key` when rendering components with v-for
+- [ ] Define corresponding props in the child component to receive the data
+
+**Incorrect:**
+```html
+<!-- WRONG: Component cannot access 'todo' - it's not in scope -->
+<TodoItem v-for="todo in todos" :key="todo.id" />
+
+<!-- Inside TodoItem.vue: this.todo or todo is undefined! -->
+```
+
+```html
+<!-- WRONG: Key provided but no data passed -->
+<UserCard
+  v-for="user in users"
+  :key="user.id"
+/>
+<!-- UserCard has no user data to display -->
+```
+
+**Correct:**
+```html
+<!-- CORRECT: Explicitly pass the item as a prop -->
+<TodoItem
+  v-for="todo in todos"
+  :key="todo.id"
+  :todo="todo"
+/>
+```
+
+```html
+<!-- CORRECT: Pass multiple pieces of data -->
+<UserCard
+  v-for="(user, index) in users"
+  :key="user.id"
+  :user="user"
+  :index="index"
+  :is-first="index === 0"
+/>
+```
+
+```vue
+<!-- Child component: UserCard.vue -->
+<script setup>
+defineProps({
+  user: {
+    type: Object,
+    required: true
+  },
+  index: {
+    type: Number,
+    required: true
+  },
+  isFirst: {
+    type: Boolean,
+    default: false
+  }
+})
+</script>
+
+<template>
+  <div class="user-card">
+    <span>{{ index + 1 }}. {{ user.name }}</span>
+    <span v-if="isFirst">(First User)</span>
+  </div>
+</template>
+```
+
+## Why Explicit Props?
+
+1. **Clear data flow**: Makes dependencies explicit and traceable
+2. **Reusability**: Components work anywhere, not just inside specific v-for loops
+3. **Type safety**: Props can be validated with type and required checks
+4. **Maintainability**: Easier to understand what data a component needs
+
+## Reference
+- [Vue.js List Rendering - v-for with Components](https://vuejs.org/guide/essentials/list.html#v-for-with-a-component)

package/skills/vue-debug-guides/reference/v-for-computed-reverse-sort.md

@@ -0,0 +1,86 @@
+---
+title: Copy Arrays Before reverse() or sort() in Computed Properties
+impact: MEDIUM
+impactDescription: reverse() and sort() mutate the original array, causing unintended side effects in computed getters
+type: gotcha
+tags: [vue3, v-for, computed, array, mutation, list-rendering]
+---
+
+# Copy Arrays Before reverse() or sort() in Computed Properties
+
+**Impact: MEDIUM** - The `reverse()` and `sort()` methods mutate the original array in-place. When used directly in a computed property getter, this causes the source array to be modified, leading to infinite reactivity loops or incorrect data state.
+
+Computed properties should be pure - they calculate a value without side effects. Mutating the source data inside a computed getter violates this principle and causes unpredictable behavior.
+
+## Task Checklist
+
+- [ ] Always create a copy of the array before calling `reverse()` or `sort()` in computed properties
+- [ ] Use spread operator `[...array]` or `Array.from(array)` or `array.slice()` to copy
+- [ ] This applies to any in-place mutation method used in computed getters
+- [ ] Consider using `toSorted()` and `toReversed()` (ES2023) which return new arrays
+
+**Incorrect:**
+```javascript
+const numbers = ref([1, 2, 3, 4, 5])
+
+// WRONG: Mutates the original array
+const reversedNumbers = computed(() => {
+  return numbers.value.reverse()  // Modifies numbers.value!
+})
+
+// WRONG: Same issue with sort
+const sortedItems = computed(() => {
+  return items.value.sort((a, b) => a.name.localeCompare(b.name))
+})
+```
+
+**Correct:**
+```javascript
+const numbers = ref([1, 2, 3, 4, 5])
+
+// CORRECT: Create a copy first with spread operator
+const reversedNumbers = computed(() => {
+  return [...numbers.value].reverse()
+})
+
+// CORRECT: Create a copy before sorting
+const sortedItems = computed(() => {
+  return [...items.value].sort((a, b) => a.name.localeCompare(b.name))
+})
+
+// CORRECT: Using slice() to copy
+const reversedNumbers = computed(() => {
+  return numbers.value.slice().reverse()
+})
+
+// CORRECT: ES2023 non-mutating methods (if supported)
+const reversedNumbers = computed(() => {
+  return numbers.value.toReversed()
+})
+
+const sortedItems = computed(() => {
+  return items.value.toSorted((a, b) => a.price - b.price)
+})
+```
+
+## Also Applies to Methods Used in Templates
+
+When using methods to filter/sort in nested v-for loops, the same rule applies:
+
+```javascript
+// CORRECT: Method that doesn't mutate
+function getSortedChildren(parent) {
+  return [...parent.children].sort((a, b) => a.order - b.order)
+}
+```
+
+```html
+<ul v-for="parent in parents" :key="parent.id">
+  <li v-for="child in getSortedChildren(parent)" :key="child.id">
+    {{ child.name }}
+  </li>
+</ul>
+```
+
+## Reference
+- [Vue.js List Rendering - Displaying Filtered/Sorted Results](https://vuejs.org/guide/essentials/list.html#displaying-filtered-sorted-results)

package/skills/vue-debug-guides/reference/v-for-key-attribute.md

@@ -0,0 +1,90 @@
+---
+title: Always Provide Unique Keys in v-for Loops
+impact: HIGH
+impactDescription: Missing or improper keys cause hard-to-debug bugs when list items have state, components, or animations
+type: gotcha
+tags: [vue3, v-for, list-rendering, key, state, components]
+---
+
+# Always Provide Unique Keys in v-for Loops
+
+**Impact: HIGH** - Without proper keys, Vue cannot track element identity when lists change. This causes component state loss, incorrect animations, form input values jumping between items, and bugs that are extremely difficult to debug.
+
+The `key` attribute tells Vue how your data relates to the DOM elements it renders. When data ordering changes (via sort, filter, add, or remove), Vue uses keys to determine what to update, remove, or create. Without unique keys, Vue reuses DOM elements in-place which can cause one item's state to incorrectly appear on another item.
+
+## Task Checklist
+
+- [ ] Always provide `:key` with unique, stable identifiers (database IDs, UUIDs)
+- [ ] Never use array index as key - indices shift when items are added/removed
+- [ ] Use primitive values only (strings or numbers) - never use objects as keys
+- [ ] On `<template v-for>`, place the key on the `<template>` tag itself (Vue 3 change)
+- [ ] When using components in v-for, keys are mandatory, not optional
+
+**Incorrect:**
+```html
+<!-- WRONG: No key provided -->
+<li v-for="item in items">{{ item.name }}</li>
+
+<!-- WRONG: Using array index as key - shifts when list changes -->
+<li v-for="(item, index) in items" :key="index">
+  <input v-model="item.value" />
+</li>
+
+<!-- WRONG: Object as key -->
+<li v-for="item in items" :key="item">{{ item.name }}</li>
+
+<!-- WRONG (Vue 3): Key on child instead of template -->
+<template v-for="item in items">
+  <li :key="item.id">{{ item.name }}</li>
+</template>
+```
+
+```javascript
+// Bug demonstration: Using index as key
+// Initial: ['Alice', 'Bob', 'Charlie'] at indices [0, 1, 2]
+// After removing 'Bob': ['Alice', 'Charlie'] at indices [0, 1]
+// Charlie now has index 1, so Vue reuses Bob's DOM/component state for Charlie!
+```
+
+**Correct:**
+```html
+<!-- CORRECT: Unique identifier as key -->
+<li v-for="item in items" :key="item.id">
+  {{ item.name }}
+</li>
+
+<!-- CORRECT: With components -->
+<MyComponent
+  v-for="item in items"
+  :key="item.id"
+  :item="item"
+/>
+
+<!-- CORRECT (Vue 3): Key on template tag -->
+<template v-for="item in items" :key="item.id">
+  <li>{{ item.name }}</li>
+  <span>{{ item.description }}</span>
+</template>
+
+<!-- CORRECT: With stateful elements -->
+<div v-for="user in users" :key="user.id">
+  <input v-model="user.email" />
+  <select v-model="user.role">
+    <option value="admin">Admin</option>
+    <option value="user">User</option>
+  </select>
+</div>
+```
+
+## When Keys Are Critical
+
+Keys are absolutely required when v-for loops contain:
+- Components with local state
+- Form elements (`<input>`, `<select>`, `<textarea>`)
+- Elements with initialization logic (mounted/created hooks)
+- Animations or transitions
+- Direct DOM manipulation
+
+## Reference
+- [Vue.js List Rendering - Key](https://vuejs.org/guide/essentials/list.html#maintaining-state-with-key)
+- [Vue 3 Migration Guide - Key on Template](https://v3-migration.vuejs.org/breaking-changes/key-attribute)

package/skills/vue-debug-guides/reference/v-for-range-starts-at-one.md

@@ -0,0 +1,66 @@
+---
+title: v-for Range Iteration Starts at 1, Not 0
+impact: LOW
+impactDescription: v-for with a number range starts at 1, unlike JavaScript arrays which start at 0
+type: gotcha
+tags: [vue3, v-for, list-rendering, range]
+---
+
+# v-for Range Iteration Starts at 1, Not 0
+
+**Impact: LOW** - When using `v-for` with a number (range iteration), the iteration starts at `1`, not `0`. This differs from typical JavaScript behavior where arrays are 0-indexed.
+
+This gotcha commonly causes off-by-one errors when the generated numbers are used for calculations or array indexing.
+
+## Task Checklist
+
+- [ ] Remember `v-for="n in 10"` produces 1 through 10, not 0 through 9
+- [ ] When using range values for array indexing, subtract 1: `items[n - 1]`
+- [ ] Consider creating a computed array if you need 0-based indices
+
+**Incorrect Assumption:**
+```html
+<!-- Developer expects 0-9, but gets 1-10 -->
+<span v-for="n in 10">{{ n }}</span>
+<!-- Output: 1 2 3 4 5 6 7 8 9 10 -->
+
+<!-- WRONG: Off-by-one error when used for array access -->
+<li v-for="n in items.length" :key="n">
+  {{ items[n].name }}  <!-- Error! items[10] is undefined when length is 10 -->
+</li>
+```
+
+**Correct:**
+```html
+<!-- Correct understanding: 1-based range -->
+<span v-for="n in 10" :key="n">{{ n }}</span>
+<!-- Output: 1 2 3 4 5 6 7 8 9 10 -->
+
+<!-- CORRECT: Adjust index for array access -->
+<li v-for="n in items.length" :key="n">
+  {{ items[n - 1].name }}  <!-- n-1 converts to 0-based -->
+</li>
+
+<!-- BETTER: Just iterate the array directly -->
+<li v-for="(item, index) in items" :key="item.id">
+  {{ index + 1 }}. {{ item.name }}  <!-- index is 0-based, add 1 for display -->
+</li>
+```
+
+```html
+<!-- Range for repeating elements (no array involved) -->
+<div v-for="n in 3" :key="n" class="skeleton-row">
+  Loading placeholder {{ n }} of 3...
+</div>
+<!-- Output: Loading placeholder 1 of 3, 2 of 3, 3 of 3 -->
+```
+
+## When Range Iteration Is Useful
+
+- Rendering a fixed number of placeholder/skeleton elements
+- Creating pagination buttons: `v-for="page in totalPages"`
+- Generating star ratings: `v-for="star in 5"`
+- Repeating template structures a set number of times
+
+## Reference
+- [Vue.js List Rendering - v-for with a Range](https://vuejs.org/guide/essentials/list.html#v-for-with-a-range)

package/skills/vue-debug-guides/reference/v-if-null-check-order.md

@@ -0,0 +1,171 @@
+---
+title: Check for Null/Undefined Before Accessing Properties in v-if
+impact: MEDIUM
+impactDescription: Accessing properties on null/undefined causes runtime errors and crashes
+type: capability
+tags: [vue3, conditional-rendering, v-if, null-check, defensive-programming]
+---
+
+# Check for Null/Undefined Before Accessing Properties in v-if
+
+**Impact: MEDIUM** - Accessing properties on null or undefined objects in `v-if` conditions causes "Cannot read property of undefined" runtime errors. This commonly occurs when data is loaded asynchronously or when optional object properties are accessed without null checks.
+
+## Task Checklist
+
+- [ ] Always check that an object exists before accessing its properties
+- [ ] Use optional chaining (?.) in Vue 3 templates for cleaner null checks
+- [ ] Consider using computed properties for complex conditional logic
+- [ ] Handle loading states explicitly rather than relying on undefined checks
+
+**Incorrect:**
+```html
+<!-- WRONG: Accessing property before checking object exists -->
+<template>
+  <div v-if="user.isAdmin">
+    Admin Panel
+  </div>
+  <!-- Error if user is null/undefined: Cannot read property 'isAdmin' of undefined -->
+</template>
+```
+
+```html
+<!-- WRONG: Nested property access without checks -->
+<template>
+  <div v-if="order.customer.address.city === 'NYC'">
+    Local delivery available
+  </div>
+  <!-- Error if any level is undefined -->
+</template>
+```
+
+```html
+<!-- WRONG: Array access without existence check -->
+<template>
+  <div v-if="items[0].name === 'Featured'">
+    {{ items[0].description }}
+  </div>
+  <!-- Error if items is empty array -->
+</template>
+```
+
+**Correct:**
+```html
+<!-- CORRECT: Check object exists first with && -->
+<template>
+  <div v-if="user && user.isAdmin">
+    Admin Panel
+  </div>
+</template>
+```
+
+```html
+<!-- CORRECT: Optional chaining (Vue 3) -->
+<template>
+  <div v-if="user?.isAdmin">
+    Admin Panel
+  </div>
+</template>
+```
+
+```html
+<!-- CORRECT: Optional chaining for nested properties -->
+<template>
+  <div v-if="order?.customer?.address?.city === 'NYC'">
+    Local delivery available
+  </div>
+</template>
+```
+
+```html
+<!-- CORRECT: Array length check before access -->
+<template>
+  <div v-if="items.length > 0 && items[0].name === 'Featured'">
+    {{ items[0].description }}
+  </div>
+
+  <!-- Or with optional chaining -->
+  <div v-if="items?.[0]?.name === 'Featured'">
+    {{ items[0].description }}
+  </div>
+</template>
+```
+
+```html
+<!-- CORRECT: Explicit loading state handling -->
+<template>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="error">Error: {{ error.message }}</div>
+  <div v-else-if="user">
+    <h1>Welcome, {{ user.name }}</h1>
+    <div v-if="user.isAdmin">Admin Panel</div>
+  </div>
+  <div v-else>No user data</div>
+</template>
+```
+
+## Using Computed Properties for Complex Checks
+
+```javascript
+// CORRECT: Move complex checks to computed properties
+<script setup>
+import { computed } from 'vue'
+
+const props = defineProps(['user', 'permissions'])
+
+const canAccessAdmin = computed(() => {
+  return props.user?.isAdmin &&
+         props.permissions?.includes('admin_panel') &&
+         !props.user?.isDisabled
+})
+
+const userDisplayName = computed(() => {
+  return props.user?.profile?.displayName ||
+         props.user?.name ||
+         'Anonymous'
+})
+</script>
+
+<template>
+  <div v-if="canAccessAdmin">
+    Admin Panel
+  </div>
+  <span>{{ userDisplayName }}</span>
+</template>
+```
+
+## Common Async Data Pattern
+
+```javascript
+// CORRECT: Handle async data loading properly
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const user = ref(null)
+const isLoading = ref(true)
+const error = ref(null)
+
+onMounted(async () => {
+  try {
+    user.value = await fetchUser()
+  } catch (e) {
+    error.value = e
+  } finally {
+    isLoading.value = false
+  }
+})
+</script>
+
+<template>
+  <div v-if="isLoading">Loading user...</div>
+  <div v-else-if="error">Failed to load user</div>
+  <div v-else-if="user">
+    <!-- Safe to access user properties here -->
+    <h1>{{ user.name }}</h1>
+    <p v-if="user.bio">{{ user.bio }}</p>
+  </div>
+</template>
+```
+
+## Reference
+- [Vue.js Conditional Rendering](https://vuejs.org/guide/essentials/conditional.html)
+- [MDN - Optional Chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining)

package/skills/vue-debug-guides/reference/v-model-ignores-html-attributes.md

@@ -0,0 +1,83 @@
+---
+title: v-model Ignores Initial HTML Attributes
+impact: HIGH
+impactDescription: v-model ignores value, checked, and selected HTML attributes - initial state must be set in JavaScript
+type: capability
+tags: [vue3, v-model, forms, input, checkbox, select, initialization]
+---
+
+# v-model Ignores Initial HTML Attributes
+
+**Impact: HIGH** - Setting initial values via HTML `value`, `checked`, or `selected` attributes has no effect when using v-model. The form will appear empty or in an unexpected state, confusing users and potentially causing data loss.
+
+Vue's v-model always treats the bound JavaScript state as the single source of truth. Any initial attributes in the HTML are completely ignored. This is a common mistake when migrating from plain HTML forms or when copying HTML templates.
+
+## Task Checklist
+
+- [ ] Never rely on HTML `value`, `checked`, or `selected` attributes when using v-model
+- [ ] Always declare initial values in JavaScript using `ref()` or `reactive()`
+- [ ] When migrating plain HTML forms to Vue, move all default values to JavaScript state
+- [ ] Audit existing forms for hardcoded HTML default values that may be silently ignored
+
+**Incorrect:**
+```html
+<script setup>
+import { ref } from 'vue'
+
+const username = ref('')  // Empty!
+const isSubscribed = ref(false)  // Not checked!
+const country = ref('')  // No default selection!
+</script>
+
+<template>
+  <!-- WRONG: These HTML attributes are completely ignored -->
+  <input v-model="username" value="default_user">
+
+  <input type="checkbox" v-model="isSubscribed" checked>
+
+  <select v-model="country">
+    <option value="us" selected>United States</option>
+    <option value="uk">United Kingdom</option>
+  </select>
+</template>
+```
+
+**Correct:**
+```html
+<script setup>
+import { ref } from 'vue'
+
+// CORRECT: Set initial values in JavaScript
+const username = ref('default_user')
+const isSubscribed = ref(true)
+const country = ref('us')
+</script>
+
+<template>
+  <!-- HTML attributes not needed - JavaScript state controls everything -->
+  <input v-model="username">
+
+  <input type="checkbox" v-model="isSubscribed">
+
+  <select v-model="country">
+    <option value="us">United States</option>
+    <option value="uk">United Kingdom</option>
+  </select>
+</template>
+```
+
+```javascript
+// Options API equivalent
+export default {
+  data() {
+    return {
+      username: 'default_user',
+      isSubscribed: true,
+      country: 'us'
+    }
+  }
+}
+```
+
+## Reference
+- [Vue.js Form Input Bindings](https://vuejs.org/guide/essentials/forms.html)

package/skills/vue-debug-guides/reference/v-model-ime-composition.md

@@ -0,0 +1,83 @@
+---
+title: v-model Does Not Update During IME Composition
+impact: MEDIUM
+impactDescription: v-model won't capture intermediate input for Chinese, Japanese, Korean and other IME languages
+type: capability
+tags: [vue3, v-model, forms, input, ime, internationalization, i18n, cjk]
+---
+
+# v-model Does Not Update During IME Composition
+
+**Impact: MEDIUM** - When users type in languages that require an Input Method Editor (Chinese, Japanese, Korean, etc.), v-model won't update until the composition is complete. This breaks real-time validation, character counters, and live search features for international users.
+
+IME (Input Method Editor) allows users to compose complex characters by typing multiple keystrokes. During this composition phase, v-model deliberately waits until the user confirms their selection before updating. This is usually desired, but can break features that need every keystroke.
+
+## Task Checklist
+
+- [ ] Test forms with IME input if your app serves CJK (Chinese, Japanese, Korean) users
+- [ ] For real-time features (live search, character counters), use manual event binding instead of v-model
+- [ ] Consider both behaviors when designing - sometimes waiting for composition completion IS correct
+- [ ] Document expected behavior for international users
+
+**Problem - v-model waits for composition:**
+```html
+<script setup>
+import { ref } from 'vue'
+
+const searchQuery = ref('')
+const charCount = ref(0)
+</script>
+
+<template>
+  <!-- PROBLEM: During IME composition, searchQuery won't update -->
+  <!-- Chinese user types "ni hao" -> sees no results until they press space/enter -->
+  <input v-model="searchQuery" placeholder="Live search...">
+  <p>{{ searchQuery.length }} characters</p>
+
+  <!-- Character counter stays at 0 during IME input -->
+</template>
+```
+
+**Solution - Manual event binding for real-time updates:**
+```html
+<script setup>
+import { ref } from 'vue'
+
+const searchQuery = ref('')
+
+// This captures EVERY input event, including during IME composition
+function handleInput(event) {
+  searchQuery.value = event.target.value
+}
+</script>
+
+<template>
+  <!-- CORRECT: Manual binding captures all input, including IME composition -->
+  <input
+    :value="searchQuery"
+    @input="handleInput"
+    placeholder="Live search..."
+  >
+  <p>{{ searchQuery.length }} characters</p>
+</template>
+```
+
+```html
+<!-- Shorter inline version -->
+<input
+  :value="searchQuery"
+  @input="event => searchQuery = event.target.value"
+>
+```
+
+**When v-model behavior IS correct:**
+```html
+<!-- For form submission, waiting for composition IS usually better -->
+<!-- User expects to confirm their character selection before it's "official" -->
+<input v-model="formName" placeholder="Enter your name">
+
+<!-- The final composed characters will be submitted, not intermediate states -->
+```
+
+## Reference
+- [Vue.js Form Input Bindings](https://vuejs.org/guide/essentials/forms.html)