@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/computed-array-mutation.md

@@ -0,0 +1,148 @@
+---
+title: Avoid Mutating Methods on Arrays in Computed Properties
+impact: HIGH
+impactDescription: Array mutating methods in computed modify source data causing unexpected behavior
+type: capability
+tags: [vue3, computed, arrays, mutation, sort, reverse]
+---
+
+# Avoid Mutating Methods on Arrays in Computed Properties
+
+**Impact: HIGH** - JavaScript array methods like `reverse()`, `sort()`, `splice()`, `push()`, `pop()`, `shift()`, and `unshift()` mutate the original array. Using them directly on reactive arrays inside computed properties will modify your source data, causing unexpected side effects and bugs.
+
+## Task Checklist
+
+- [ ] Always create a copy of arrays before using mutating methods
+- [ ] Use spread operator `[...array]` or `slice()` to copy arrays
+- [ ] Prefer non-mutating alternatives when available
+- [ ] Be aware which array methods mutate vs return new arrays
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+
+const items = ref([3, 1, 4, 1, 5, 9, 2, 6])
+const users = ref([
+  { name: 'Alice', age: 30 },
+  { name: 'Bob', age: 25 }
+])
+
+// BAD: sort() mutates the original array!
+const sortedItems = computed(() => {
+  return items.value.sort((a, b) => a - b)
+})
+
+// BAD: reverse() mutates the original array!
+const reversedItems = computed(() => {
+  return items.value.reverse()
+})
+
+// BAD: Both arrays now point to the same mutated data
+// items.value and sortedItems.value are the SAME array
+// items.value and reversedItems.value are the SAME array
+
+// BAD: Chained mutations
+const sortedUsers = computed(() => {
+  return users.value.sort((a, b) => a.age - b.age)
+})
+</script>
+
+<template>
+  <!-- Original array is corrupted! -->
+  <div>Original: {{ items }}</div>
+  <div>Sorted: {{ sortedItems }}</div>
+</template>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+
+const items = ref([3, 1, 4, 1, 5, 9, 2, 6])
+const users = ref([
+  { name: 'Alice', age: 30 },
+  { name: 'Bob', age: 25 }
+])
+
+// GOOD: Spread operator creates a copy first
+const sortedItems = computed(() => {
+  return [...items.value].sort((a, b) => a - b)
+})
+
+// GOOD: slice() also creates a copy
+const reversedItems = computed(() => {
+  return items.value.slice().reverse()
+})
+
+// GOOD: Copy before sorting objects
+const sortedUsers = computed(() => {
+  return [...users.value].sort((a, b) => a.age - b.age)
+})
+
+// GOOD: Use toSorted() (ES2023) - non-mutating
+const sortedItemsModern = computed(() => {
+  return items.value.toSorted((a, b) => a - b)
+})
+
+// GOOD: Use toReversed() (ES2023) - non-mutating
+const reversedItemsModern = computed(() => {
+  return items.value.toReversed()
+})
+</script>
+
+<template>
+  <!-- Original array stays intact -->
+  <div>Original: {{ items }}</div>
+  <div>Sorted: {{ sortedItems }}</div>
+  <div>Reversed: {{ reversedItems }}</div>
+</template>
+```
+
+## Mutating vs Non-Mutating Array Methods
+
+| Mutating (Avoid in Computed) | Non-Mutating (Safe) |
+|------------------------------|---------------------|
+| `sort()` | `toSorted()` (ES2023) |
+| `reverse()` | `toReversed()` (ES2023) |
+| `splice()` | `toSpliced()` (ES2023) |
+| `push()` | `concat()` |
+| `pop()` | `slice(0, -1)` |
+| `shift()` | `slice(1)` |
+| `unshift()` | `[item, ...array]` |
+| `fill()` | `map()` with new values |
+
+## ES2023 Non-Mutating Alternatives
+
+Modern JavaScript (ES2023) provides non-mutating versions of common array methods:
+
+```javascript
+// These return NEW arrays, safe for computed properties
+const sorted = array.toSorted((a, b) => a - b)
+const reversed = array.toReversed()
+const spliced = array.toSpliced(1, 2, 'new')
+const withReplaced = array.with(0, 'newFirst')
+```
+
+## Deep Copy for Nested Arrays
+
+For arrays of objects where you might mutate nested properties:
+
+```javascript
+const items = ref([{ name: 'A', values: [1, 2, 3] }])
+
+// Shallow copy - nested arrays still shared
+const copied = computed(() => [...items.value])
+
+// Deep copy if you need to mutate nested structures
+const deepCopied = computed(() => {
+  return JSON.parse(JSON.stringify(items.value))
+  // Or use structuredClone():
+  // return structuredClone(items.value)
+})
+```
+
+## Reference
+- [Vue.js Computed Properties - Avoid Mutating Computed Value](https://vuejs.org/guide/essentials/computed.html#avoid-mutating-computed-value)
+- [MDN Array Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)

package/skills/vue-debug-guides/reference/computed-conditional-dependencies.md

@@ -0,0 +1,147 @@
+---
+title: Ensure All Dependencies Are Accessed in Computed Properties
+impact: HIGH
+impactDescription: Conditional logic can prevent dependency tracking causing stale computed values
+type: capability
+tags: [vue3, computed, reactivity, dependency-tracking, gotcha]
+---
+
+# Ensure All Dependencies Are Accessed in Computed Properties
+
+**Impact: HIGH** - Vue tracks computed property dependencies by monitoring which reactive properties are accessed during execution. If conditional logic prevents a property from being accessed on the first run, Vue won't track it as a dependency, causing the computed property to not update when that property changes.
+
+This is a subtle but common source of bugs, especially with short-circuit evaluation (`&&`, `||`) and early returns.
+
+## Task Checklist
+
+- [ ] Access all reactive dependencies before any conditional logic
+- [ ] Be cautious with short-circuit operators (`&&`, `||`) that may skip property access
+- [ ] Store all dependencies in variables at the start of the computed getter
+- [ ] Test computed properties with different initial states
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+
+const isEnabled = ref(false)
+const data = ref('important data')
+
+// BAD: If isEnabled is false initially, data.value is never accessed
+// Vue won't track 'data' as a dependency!
+const result = computed(() => {
+  if (!isEnabled.value) {
+    return 'disabled'
+  }
+  return data.value  // This dependency may not be tracked
+})
+
+// BAD: Short-circuit prevents second access
+const password = ref('')
+const confirmPassword = ref('')
+
+const isValid = computed(() => {
+  // If password is empty, confirmPassword is never accessed
+  return password.value && password.value === confirmPassword.value
+})
+
+// BAD: Early return prevents dependency access
+const user = ref(null)
+const permissions = ref(['read', 'write'])
+
+const canEdit = computed(() => {
+  if (!user.value) {
+    return false  // permissions.value never accessed when user is null
+  }
+  return permissions.value.includes('write')
+})
+</script>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+
+const isEnabled = ref(false)
+const data = ref('important data')
+
+// GOOD: Access all dependencies first
+const result = computed(() => {
+  const enabled = isEnabled.value
+  const currentData = data.value  // Always accessed
+
+  if (!enabled) {
+    return 'disabled'
+  }
+  return currentData
+})
+
+// GOOD: Access both values before comparison
+const password = ref('')
+const confirmPassword = ref('')
+
+const isValid = computed(() => {
+  const pwd = password.value
+  const confirm = confirmPassword.value  // Always accessed
+
+  return pwd && pwd === confirm
+})
+
+// GOOD: Access all reactive sources upfront
+const user = ref(null)
+const permissions = ref(['read', 'write'])
+
+const canEdit = computed(() => {
+  const currentUser = user.value
+  const currentPermissions = permissions.value  // Always accessed
+
+  if (!currentUser) {
+    return false
+  }
+  return currentPermissions.includes('write')
+})
+</script>
+```
+
+## The Dependency Tracking Mechanism
+
+Vue's reactivity system works by tracking which reactive properties are accessed when a computed property runs:
+
+```javascript
+// How Vue tracks dependencies (simplified):
+// 1. Start tracking
+// 2. Run the getter function
+// 3. Record every .value or reactive property access
+// 4. Stop tracking
+
+const computed = computed(() => {
+  // Vue starts tracking here
+  if (conditionA.value) {      // conditionA is tracked
+    return valueB.value        // valueB is ONLY tracked if conditionA is true
+  }
+  return 'default'             // If conditionA is false, valueB is NOT tracked!
+})
+```
+
+## Pattern: Destructure All Dependencies First
+
+```javascript
+// GOOD PATTERN: Destructure/access everything at the top
+const result = computed(() => {
+  // Access all potential dependencies
+  const { user, settings, items } = toRefs(store)
+  const userVal = user.value
+  const settingsVal = settings.value
+  const itemsVal = items.value
+
+  // Now use conditional logic safely
+  if (!userVal) return []
+  if (!settingsVal.enabled) return []
+  return itemsVal.filter(i => i.active)
+})
+```
+
+## Reference
+- [Vue.js Reactivity in Depth](https://vuejs.org/guide/extras/reactivity-in-depth.html)
+- [GitHub Discussion: Dependency collection gotcha with conditionals](https://github.com/vuejs/Discussion/issues/15)

package/skills/vue-debug-guides/reference/computed-no-parameters.md

@@ -0,0 +1,159 @@
+---
+title: Computed Properties Cannot Accept Parameters
+impact: MEDIUM
+impactDescription: Attempting to pass arguments to computed properties fails or defeats caching
+type: capability
+tags: [vue3, computed, methods, parameters, common-mistake]
+---
+
+# Computed Properties Cannot Accept Parameters
+
+**Impact: MEDIUM** - Computed properties are designed to derive values from reactive state without parameters. Attempting to pass arguments defeats the caching mechanism or causes errors. Use methods or computed properties that return functions instead.
+
+## Task Checklist
+
+- [ ] Use methods when you need to pass parameters
+- [ ] Consider if the parameter can be reactive state instead
+- [ ] If you must parameterize, understand that returning a function loses caching benefits
+- [ ] Prefer method calls in templates for parameterized operations
+
+**Incorrect:**
+```vue
+<template>
+  <!-- BAD: Computed properties don't accept parameters like this -->
+  <p>{{ filteredItems('active') }}</p>
+  <p>{{ formattedPrice(100, 'USD') }}</p>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+const items = ref([/* ... */])
+
+// BAD: This won't work as expected
+// Computed is called once, not per parameter
+const filteredItems = computed((status) => {  // status will be undefined or previous value
+  return items.value.filter(i => i.status === status)
+})
+</script>
+```
+
+```vue
+<script>
+export default {
+  data() {
+    return { items: [/* ... */] }
+  },
+  computed: {
+    // BAD: Computed doesn't receive arguments
+    filteredItems(status) {  // 'status' is actually 'this' or undefined
+      return this.items.filter(i => i.status === status)
+    }
+  }
+}
+</script>
+```
+
+**Correct:**
+```vue
+<template>
+  <!-- GOOD: Use method for parameterized operations -->
+  <p>{{ getFilteredItems('active') }}</p>
+  <p>{{ formatPrice(100, 'USD') }}</p>
+
+  <!-- GOOD: Or use computed with reactive filter state -->
+  <select v-model="statusFilter">
+    <option value="active">Active</option>
+    <option value="inactive">Inactive</option>
+  </select>
+  <p>{{ filteredItems }}</p>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+const items = ref([/* ... */])
+const statusFilter = ref('active')
+
+// GOOD: Method for parameterized operations
+function getFilteredItems(status) {
+  return items.value.filter(i => i.status === status)
+}
+
+function formatPrice(amount, currency) {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency
+  }).format(amount)
+}
+
+// GOOD: Computed with reactive parameter
+const filteredItems = computed(() => {
+  return items.value.filter(i => i.status === statusFilter.value)
+})
+</script>
+```
+
+## Workaround: Computed Returning a Function
+
+If you need something computed-like with parameters, you can return a function. **However, this defeats the caching benefit:**
+
+```vue
+<template>
+  <p>{{ getItemsByStatus('active') }}</p>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+const items = ref([/* ... */])
+
+// This works but provides NO caching benefit
+// The inner function runs every time it's called
+const getItemsByStatus = computed(() => {
+  return (status) => items.value.filter(i => i.status === status)
+})
+
+// This is essentially equivalent to just using a method
+// Only useful if you need to compose with other computed properties
+</script>
+```
+
+## When to Use Each Approach
+
+| Scenario | Approach | Caching |
+|----------|----------|---------|
+| Fixed filter based on reactive state | Computed | Yes |
+| Dynamic filter passed as argument | Method | No |
+| Filter options from user selection | Computed + reactive param | Yes |
+| Formatting with variable parameters | Method | No |
+| Composed derivation with argument | Computed returning function | Partial |
+
+## Make Parameters Reactive
+
+The best pattern is often to make the "parameter" a reactive value:
+
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+
+const items = ref([/* ... */])
+
+// Instead of passing 'status' as a parameter:
+const currentStatus = ref('active')
+
+// Make a computed that uses the reactive status
+const filteredItems = computed(() => {
+  return items.value.filter(i => i.status === currentStatus.value)
+})
+
+// Change the filter by updating the ref
+function filterByStatus(status) {
+  currentStatus.value = status
+}
+</script>
+```
+
+## Reference
+- [Vue.js Computed Properties](https://vuejs.org/guide/essentials/computed.html)
+- [Vue.js Methods](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#declaring-methods)

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

@@ -0,0 +1,107 @@
+---
+title: Computed Property Getters Must Be Side-Effect Free
+impact: HIGH
+impactDescription: Side effects in computed getters break reactivity and cause unpredictable behavior
+type: efficiency
+tags: [vue3, computed, reactivity, side-effects, best-practices]
+---
+
+# Computed Property Getters Must Be Side-Effect Free
+
+**Impact: HIGH** - Computed getter functions should only perform pure computation. Side effects in computed getters break Vue's reactivity model and cause bugs that are difficult to trace.
+
+Computed properties are designed to declaratively describe how to derive a value from other reactive state. They are not meant to perform actions or modify state.
+
+## Task Checklist
+
+- [ ] Never mutate other reactive state inside a computed getter
+- [ ] Never make async requests or API calls inside a computed getter
+- [ ] Never perform DOM mutations inside a computed getter
+- [ ] Use watchers for reacting to state changes with side effects
+- [ ] Use event handlers for user-triggered actions
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+
+const items = ref([])
+const count = ref(0)
+const lastFetch = ref(null)
+
+// BAD: Mutates other state
+const doubledCount = computed(() => {
+  count.value++  // Side effect - modifying state!
+  return count.value * 2
+})
+
+// BAD: Makes async request
+const userData = computed(async () => {
+  const response = await fetch('/api/user')  // Side effect - API call!
+  return response.json()
+})
+
+// BAD: Modifies DOM
+const highlightedItems = computed(() => {
+  document.title = `${items.value.length} items`  // Side effect - DOM mutation!
+  return items.value.filter(i => i.highlighted)
+})
+
+// BAD: Writes to external state
+const processedData = computed(() => {
+  lastFetch.value = new Date()  // Side effect - modifying state!
+  return items.value.map(i => i.name)
+})
+</script>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref, computed, watch, onMounted } from 'vue'
+
+const items = ref([])
+const count = ref(0)
+const userData = ref(null)
+
+// GOOD: Pure computation only
+const doubledCount = computed(() => {
+  return count.value * 2
+})
+
+// GOOD: Use lifecycle hook for initial fetch
+onMounted(async () => {
+  const response = await fetch('/api/user')
+  userData.value = await response.json()
+})
+
+// GOOD: Pure filtering
+const highlightedItems = computed(() => {
+  return items.value.filter(i => i.highlighted)
+})
+
+// GOOD: Use watcher for side effects
+watch(items, (newItems) => {
+  document.title = `${newItems.length} items`
+}, { immediate: true })
+
+// Increment count through event handler, not computed
+function increment() {
+  count.value++
+}
+</script>
+```
+
+## What Counts as a Side Effect
+
+| Side Effect Type | Example | Alternative |
+|-----------------|---------|-------------|
+| State mutation | `otherRef.value = x` | Use watcher |
+| API calls | `fetch()`, `axios()` | Use watcher or lifecycle hook |
+| DOM manipulation | `document.title = x` | Use watcher |
+| Console logging | `console.log()` | Remove or use watcher |
+| Storage access | `localStorage.setItem()` | Use watcher |
+| Timer setup | `setTimeout()` | Use lifecycle hook |
+
+## Reference
+- [Vue.js Computed Properties - Getters Should Be Side-Effect Free](https://vuejs.org/guide/essentials/computed.html#getters-should-be-side-effect-free)