@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/define-model-default-value-sync.md

@@ -0,0 +1,139 @@
+---
+title: defineModel Default Value Can Cause Parent-Child Desync
+impact: HIGH
+impactDescription: Default values in defineModel don't sync back to parent, causing state inconsistency
+type: capability
+tags: [vue3, v-model, defineModel, components, props, two-way-binding]
+---
+
+# defineModel Default Value Can Cause Parent-Child Desync
+
+**Impact: HIGH** - When using `defineModel()` with a default value and the parent doesn't provide a value, the parent and child components will have different values. The parent's ref stays `undefined` while the child uses the default, breaking the two-way binding contract.
+
+This subtle bug can cause confusing behavior where the parent component shows one value while the child shows another, and updates may not propagate correctly.
+
+## Task Checklist
+
+- [ ] Always provide initial values from the parent when using v-model
+- [ ] Don't rely on defineModel defaults as the primary source of truth
+- [ ] If defaults are needed, also set them in the parent component
+- [ ] Test components with and without v-model props provided
+
+**Problem - Parent and child out of sync:**
+```html
+<!-- ChildComponent.vue -->
+<script setup>
+// Default value of 1 if parent doesn't provide value
+const model = defineModel({ default: 1 })
+</script>
+
+<template>
+  <input v-model="model" type="number">
+  <!-- Shows: 1 (from default) -->
+</template>
+```
+
+```html
+<!-- ParentComponent.vue -->
+<script setup>
+import { ref } from 'vue'
+import ChildComponent from './ChildComponent.vue'
+
+// PROBLEM: Parent ref is undefined, not synced with child's default
+const myValue = ref()  // undefined
+</script>
+
+<template>
+  <ChildComponent v-model="myValue" />
+
+  <!-- DESYNC: Child shows 1, but parent shows undefined -->
+  <p>Parent value: {{ myValue }}</p>  <!-- Shows: undefined -->
+
+  <!-- Even after child changes value, parent may not update correctly -->
+</template>
+```
+
+**Solution 1 - Always provide initial value from parent:**
+```html
+<!-- ParentComponent.vue -->
+<script setup>
+import { ref } from 'vue'
+import ChildComponent from './ChildComponent.vue'
+
+// CORRECT: Parent provides the initial value
+const myValue = ref(1)  // Match the expected default
+</script>
+
+<template>
+  <ChildComponent v-model="myValue" />
+  <p>Parent value: {{ myValue }}</p>  <!-- Shows: 1, stays in sync -->
+</template>
+```
+
+**Solution 2 - Child emits default on mount (if parent control not possible):**
+```html
+<!-- ChildComponent.vue -->
+<script setup>
+import { onMounted } from 'vue'
+
+const model = defineModel({ default: 1 })
+
+// Sync default value back to parent on mount
+onMounted(() => {
+  if (model.value === 1) {  // Is using default
+    // Force emit to sync parent
+    model.value = 1
+  }
+})
+</script>
+
+<template>
+  <input v-model="model" type="number">
+</template>
+```
+
+**Solution 3 - Use required prop or explicit undefined handling:**
+```html
+<!-- ChildComponent.vue -->
+<script setup>
+import { computed } from 'vue'
+
+// Mark as required - TypeScript will warn if not provided
+const model = defineModel({ required: true })
+
+// Or handle undefined explicitly
+const safeModel = computed({
+  get: () => model.value ?? 1,  // Provide fallback
+  set: (val) => { model.value = val }
+})
+</script>
+
+<template>
+  <input v-model="safeModel" type="number">
+</template>
+```
+
+**Best Practice - Document expected initial values:**
+```html
+<!-- ChildComponent.vue -->
+<script setup>
+/**
+ * @prop modelValue - The numeric value (parent should initialize to 1 or desired default)
+ */
+const model = defineModel({
+  type: Number,
+  default: 1,
+  // Adding validator helps catch issues in development
+  validator: (value) => {
+    if (value === undefined) {
+      console.warn('ChildComponent: v-model value is undefined. Provide initial value from parent.')
+    }
+    return true
+  }
+})
+</script>
+```
+
+## Reference
+- [Vue.js Component v-model](https://vuejs.org/guide/components/v-model.html)
+- [Vue School - defineModel Guide](https://vueschool.io/articles/vuejs-tutorials/v-model-and-definemodel-a-comprehensive-guide-to-two-way-binding-in-vue-js-3/)

package/skills/vue-debug-guides/reference/defineEmits-must-be-top-level.md

@@ -0,0 +1,164 @@
+---
+title: defineEmits Must Be Used at Top Level of script setup
+impact: HIGH
+impactDescription: Using defineEmits inside functions causes compilation errors - macros must be at module scope
+type: gotcha
+tags: [vue3, defineEmits, script-setup, macros, composition-api]
+---
+
+# defineEmits Must Be Used at Top Level of script setup
+
+**Impact: HIGH** - The `defineEmits()` macro can only be used directly within `<script setup>` at the top level. It cannot be placed inside functions, conditionals, or any other nested scope. Vue's compiler hoists these macros to module scope during compilation.
+
+This applies to all Vue macros: `defineProps`, `defineEmits`, `defineExpose`, `defineOptions`, and `defineSlots`.
+
+## Task Checklist
+
+- [ ] Place `defineEmits()` directly in `<script setup>`, not inside functions
+- [ ] Do not wrap macro calls in conditionals or loops
+- [ ] Do not reference local variables in macro arguments
+- [ ] Store the emit function and reuse it throughout the component
+
+## The Problem
+
+**Incorrect - Inside a function:**
+```vue
+<script setup>
+function useEvents() {
+  // ERROR: defineEmits cannot be used inside a function
+  const emit = defineEmits(['submit', 'cancel'])
+  return emit
+}
+
+const emit = useEvents() // This fails at compile time
+</script>
+```
+
+**Incorrect - Inside a conditional:**
+```vue
+<script setup>
+if (someCondition) {
+  // ERROR: Cannot use defineEmits in conditional
+  const emit = defineEmits(['eventA'])
+} else {
+  const emit = defineEmits(['eventB'])
+}
+</script>
+```
+
+**Incorrect - Referencing local variables:**
+```vue
+<script setup>
+const eventNames = ['submit', 'cancel']
+
+// ERROR: Cannot reference local variables
+const emit = defineEmits(eventNames)
+</script>
+```
+
+## Correct Usage
+
+**Correct - Top level declaration:**
+```vue
+<script setup>
+// CORRECT: defineEmits at top level of script setup
+const emit = defineEmits(['submit', 'cancel', 'update'])
+
+function handleSubmit() {
+  emit('submit', data)
+}
+
+function handleCancel() {
+  emit('cancel')
+}
+</script>
+```
+
+**Correct - With TypeScript types:**
+```vue
+<script setup lang="ts">
+// CORRECT: Type-based declaration at top level
+const emit = defineEmits<{
+  submit: [data: FormData]
+  cancel: []
+  'update:modelValue': [value: string]
+}>()
+
+function handleSubmit(data: FormData) {
+  emit('submit', data)
+}
+</script>
+```
+
+**Correct - Using constant arrays (compile-time constant):**
+```vue
+<script setup>
+// CORRECT: Literal array is fine
+const emit = defineEmits(['submit', 'cancel'])
+</script>
+```
+
+## Why This Restriction Exists
+
+Vue's compiler processes `<script setup>` macros at compile time, not runtime. The arguments must be statically analyzable so Vue can:
+
+1. Generate the correct component options
+2. Provide TypeScript type inference
+3. Enable IDE support for event autocompletion
+4. Validate emitted events
+
+Since the macro is hoisted out of `<script setup>` during compilation, it cannot access anything that only exists at runtime.
+
+## Using emit in Composables
+
+If you want to share emit logic in a composable, pass the emit function as an argument:
+
+**Correct - Pass emit to composable:**
+```vue
+<script setup>
+const emit = defineEmits(['submit', 'cancel', 'validate'])
+
+// Pass emit to composable
+const { handleSubmit, handleCancel } = useFormEvents(emit)
+</script>
+```
+
+```js
+// composables/useFormEvents.js
+export function useFormEvents(emit) {
+  function handleSubmit(data) {
+    emit('submit', data)
+  }
+
+  function handleCancel() {
+    emit('cancel')
+  }
+
+  return { handleSubmit, handleCancel }
+}
+```
+
+## ESLint Rule
+
+The `eslint-plugin-vue` provides the `vue/valid-define-emits` rule that catches these errors:
+
+```js
+// eslint.config.js
+export default [
+  {
+    rules: {
+      'vue/valid-define-emits': 'error'
+    }
+  }
+]
+```
+
+This rule reports:
+- `defineEmits` used inside functions
+- `defineEmits` referencing local variables
+- Multiple `defineEmits` calls in the same component
+- `defineEmits` used outside `<script setup>`
+
+## Reference
+- [Vue.js SFC script setup](https://vuejs.org/api/sfc-script-setup.html#defineprops-defineemits)
+- [ESLint vue/valid-define-emits](https://eslint.vuejs.org/rules/valid-define-emits)

package/skills/vue-debug-guides/reference/defineEmits-no-runtime-and-type-mixed.md

@@ -0,0 +1,170 @@
+---
+title: Cannot Mix Runtime and Type Declarations in defineEmits
+impact: HIGH
+impactDescription: Using both array/object syntax AND TypeScript generics in defineEmits causes compile errors
+type: gotcha
+tags: [vue3, defineEmits, typescript, compilation-error, script-setup]
+---
+
+# Cannot Mix Runtime and Type Declarations in defineEmits
+
+**Impact: HIGH** - `defineEmits` supports two declaration styles: runtime (array/object syntax) and type-based (TypeScript generics). You CANNOT use both at the same time. Attempting to do so results in a compile-time error.
+
+This is a common mistake when learning Vue 3 with TypeScript.
+
+## Task Checklist
+
+- [ ] Choose ONE declaration style: runtime OR type-based
+- [ ] For TypeScript projects, prefer type-based declaration
+- [ ] For JavaScript projects, use runtime (array/object) declaration
+- [ ] Never pass arguments when using generic type parameter
+
+## The Problem
+
+**Incorrect - Mixing both styles:**
+```vue
+<script setup lang="ts">
+// ERROR: Cannot use both type argument and runtime argument
+const emit = defineEmits<{
+  submit: [data: FormData]
+}>(['submit'])  // This array argument causes the error!
+</script>
+```
+
+**Compiler error:**
+```
+defineEmits() cannot accept both type and non-type arguments at the same time.
+Use one or the other.
+```
+
+**Also incorrect:**
+```vue
+<script setup lang="ts">
+// ERROR: Same problem with object syntax
+const emit = defineEmits<{
+  submit: [data: FormData]
+}>({
+  submit: (data) => !!data
+})
+</script>
+```
+
+## Correct: Type-Based Declaration (TypeScript)
+
+```vue
+<script setup lang="ts">
+// CORRECT: Type argument only, no runtime argument
+const emit = defineEmits<{
+  submit: [data: FormData]
+  cancel: []
+  'update:modelValue': [value: string]
+}>()
+
+emit('submit', formData)  // TypeScript validates this
+emit('cancel')
+emit('unknown')  // TypeScript error: unknown event
+</script>
+```
+
+**Alternative call signature syntax:**
+```vue
+<script setup lang="ts">
+const emit = defineEmits<{
+  (e: 'submit', data: FormData): void
+  (e: 'cancel'): void
+  (e: 'update:modelValue', value: string): void
+}>()
+</script>
+```
+
+## Correct: Runtime Declaration (JavaScript or Simple Cases)
+
+**Array syntax:**
+```vue
+<script setup>
+// CORRECT: Runtime array, no type argument
+const emit = defineEmits(['submit', 'cancel', 'update:modelValue'])
+
+emit('submit', formData)
+emit('cancel')
+</script>
+```
+
+**Object syntax with validation:**
+```vue
+<script setup>
+// CORRECT: Runtime object for validation
+const emit = defineEmits({
+  submit: (data) => {
+    if (!data?.email) {
+      console.warn('Missing email')
+      return false
+    }
+    return true
+  },
+  cancel: null  // No validation
+})
+</script>
+```
+
+## Adding Validation to Type-Based Emits
+
+If you want TypeScript types AND runtime validation, define the validator separately:
+
+```vue
+<script setup lang="ts">
+interface FormData {
+  email: string
+  message: string
+}
+
+// Type-based declaration for TypeScript
+const emit = defineEmits<{
+  submit: [data: FormData]
+}>()
+
+// Separate validation function
+function emitSubmit(data: FormData) {
+  if (!data.email.includes('@')) {
+    console.warn('Invalid email format')
+    return
+  }
+  emit('submit', data)
+}
+</script>
+
+<template>
+  <button @click="emitSubmit(formData)">Submit</button>
+</template>
+```
+
+## Choosing Between Styles
+
+| Style | Use When | Benefits |
+|-------|----------|----------|
+| Type-based | TypeScript project | Compile-time checking, IDE support |
+| Array | JavaScript, simple events | Simple, no types needed |
+| Object | Need runtime validation | Validates payloads at runtime |
+
+**Recommendation:** In TypeScript projects, use type-based declaration. It provides the best developer experience with autocompletion and type checking.
+
+## Same Rule Applies to defineProps
+
+This restriction also applies to `defineProps`:
+
+```vue
+<script setup lang="ts">
+// ERROR: Cannot mix
+const props = defineProps<{ name: string }>({ name: String })
+
+// CORRECT: Type-based only
+const props = defineProps<{ name: string }>()
+
+// CORRECT: Runtime only
+const props = defineProps({ name: String })
+</script>
+```
+
+## Reference
+- [Vue.js SFC script setup - defineEmits](https://vuejs.org/api/sfc-script-setup.html#defineprops-defineemits)
+- [Vue.js TypeScript with Composition API](https://vuejs.org/guide/typescript/composition-api.html#typing-component-emits)

package/skills/vue-debug-guides/reference/definemodel-object-mutation-no-emit.md

@@ -0,0 +1,148 @@
+---
+title: defineModel Object Properties Must Be Replaced, Not Mutated
+impact: HIGH
+impactDescription: Mutating object properties via defineModel doesn't emit update events, breaking parent sync
+type: gotcha
+tags: [vue3, v-model, defineModel, objects, reactivity, two-way-binding]
+---
+
+# defineModel Object Properties Must Be Replaced, Not Mutated
+
+**Impact: HIGH** - When using `defineModel()` with objects or arrays, directly mutating nested properties like `model.value.prop = x` does NOT emit the `update:modelValue` event. The parent component never receives the change notification, causing silent sync failures.
+
+This happens because Vue only detects when the `model.value` reference itself changes, not when properties of the object are mutated in place.
+
+## Task Checklist
+
+- [ ] Never mutate object properties directly: `model.value.prop = x`
+- [ ] Always create a new object reference when updating: `model.value = {...model.value, prop: x}`
+- [ ] For arrays, use spread or slice: `model.value = [...model.value, newItem]`
+- [ ] Consider using structuredClone for deeply nested objects
+
+**Incorrect - Mutation without event emission:**
+```vue
+<script setup>
+// Child component with object v-model
+const model = defineModel<{ name: string; age: number }>()
+
+function updateName(newName: string) {
+  // WRONG: This mutates the object in place
+  // Parent receives NO update:modelValue event!
+  model.value.name = newName
+}
+
+function addToList() {
+  // WRONG: Push mutates the array
+  model.value.items.push('new item')  // Parent not notified
+}
+</script>
+```
+
+**Correct - Replace object reference to trigger event:**
+```vue
+<script setup>
+const model = defineModel<{ name: string; age: number }>()
+
+function updateName(newName: string) {
+  // CORRECT: Create new object reference
+  // This triggers update:modelValue event to parent
+  model.value = {
+    ...model.value,
+    name: newName
+  }
+}
+
+function addToList() {
+  // CORRECT: Create new array reference
+  model.value = {
+    ...model.value,
+    items: [...model.value.items, 'new item']
+  }
+}
+</script>
+```
+
+## Deep Nesting Requires Full Path Replacement
+
+```vue
+<script setup>
+const model = defineModel<{
+  user: {
+    address: {
+      city: string
+    }
+  }
+}>()
+
+// WRONG: Deep mutation
+model.value.user.address.city = 'New York'
+
+// CORRECT: Replace entire chain
+model.value = {
+  ...model.value,
+  user: {
+    ...model.value.user,
+    address: {
+      ...model.value.user.address,
+      city: 'New York'
+    }
+  }
+}
+
+// ALTERNATIVE: Use structuredClone for complex updates
+function updateCity(city: string) {
+  const updated = structuredClone(model.value)
+  updated.user.address.city = city
+  model.value = updated  // New reference triggers event
+}
+</script>
+```
+
+## Race Condition Warning with Spread Operator
+
+When multiple updates occur rapidly, earlier changes can be lost:
+
+```vue
+<script setup>
+const model = defineModel<{ a: string; b: string }>()
+
+// CAUTION: Race condition if called in same tick
+function updateBothWrong() {
+  model.value = { ...model.value, a: 'new-a' }  // First update
+  model.value = { ...model.value, b: 'new-b' }  // May use stale model.value!
+}
+
+// CORRECT: Batch updates into single assignment
+function updateBothCorrect() {
+  model.value = {
+    ...model.value,
+    a: 'new-a',
+    b: 'new-b'
+  }
+}
+</script>
+```
+
+## Alternative: VueUse's useVModel with Deep Option
+
+For complex objects, consider VueUse:
+
+```vue
+<script setup>
+import { useVModel } from '@vueuse/core'
+
+const props = defineProps<{ modelValue: { name: string } }>()
+const emit = defineEmits(['update:modelValue'])
+
+// Deep tracking with passive updates
+const model = useVModel(props, 'modelValue', emit, { deep: true, passive: true })
+
+// Now direct mutations work
+model.value.name = 'New Name'  // Properly syncs with parent
+</script>
+```
+
+## Reference
+- [Vue.js Component v-model](https://vuejs.org/guide/components/v-model.html)
+- [GitHub Discussion: defineModel with objects](https://github.com/orgs/vuejs/discussions/10538)
+- [SIMPL Engineering: Vue defineModel Pitfalls](https://engineering.simpl.de/post/vue_definemodel/)

package/skills/vue-debug-guides/reference/dom-update-timing-nexttick.md

@@ -0,0 +1,90 @@
+---
+title: Use nextTick() to Wait for DOM Updates
+impact: MEDIUM
+impactDescription: DOM updates are batched and asynchronous - direct DOM access after state changes sees stale values
+type: capability
+tags: [vue3, dom, nextTick, reactivity, async]
+---
+
+# Use nextTick() to Wait for DOM Updates
+
+**Impact: MEDIUM** - Vue batches DOM updates asynchronously for performance. If you access the DOM immediately after changing reactive state, you'll see the old values. Use `nextTick()` to wait for the DOM to update.
+
+When you modify reactive state, Vue doesn't update the DOM synchronously. Instead, it buffers changes and applies them in the next "tick" of the event loop. This is a performance optimization, but it can cause bugs when you need to read from or manipulate the DOM after state changes.
+
+## Task Checklist
+
+- [ ] Use `await nextTick()` when you need to access updated DOM elements after state changes
+- [ ] Use `nextTick()` when measuring DOM elements (heights, widths) after data changes
+- [ ] Use `nextTick()` when focusing inputs or scrolling after content updates
+- [ ] Consider if you really need DOM access - often you can work with reactive data instead
+
+**Incorrect:**
+```javascript
+import { ref } from 'vue'
+
+const message = ref('Hello')
+const messageEl = ref(null)
+
+function updateMessage() {
+  message.value = 'Updated!'
+
+  // WRONG: DOM still shows "Hello" at this point
+  console.log(messageEl.value.textContent) // "Hello" - stale!
+
+  // WRONG: Scrolling/focusing may not work correctly
+  scrollContainer.value.scrollTop = scrollContainer.value.scrollHeight
+}
+```
+
+**Correct:**
+```javascript
+import { ref, nextTick } from 'vue'
+
+const message = ref('Hello')
+const messageEl = ref(null)
+
+async function updateMessage() {
+  message.value = 'Updated!'
+
+  // CORRECT: Wait for DOM to update
+  await nextTick()
+
+  // Now the DOM is updated
+  console.log(messageEl.value.textContent) // "Updated!"
+
+  // Scrolling and focusing now work correctly
+  scrollContainer.value.scrollTop = scrollContainer.value.scrollHeight
+}
+
+// Alternative: callback syntax
+function updateWithCallback() {
+  message.value = 'Updated!'
+
+  nextTick(() => {
+    console.log(messageEl.value.textContent) // "Updated!"
+  })
+}
+```
+
+```vue
+<script setup>
+import { ref, nextTick } from 'vue'
+
+const items = ref([])
+const listRef = ref(null)
+
+async function addItem() {
+  items.value.push({ id: Date.now(), text: 'New item' })
+
+  await nextTick()
+
+  // Now we can safely scroll to the new item
+  listRef.value.lastElementChild?.scrollIntoView({ behavior: 'smooth' })
+}
+</script>
+```
+
+## Reference
+- [Vue.js Reactivity Fundamentals - DOM Update Timing](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#dom-update-timing)
+- [Vue.js nextTick API](https://vuejs.org/api/general.html#nexttick)