@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/checkbox-true-false-value-form-submission.md

@@ -0,0 +1,118 @@
+---
+title: Checkbox true-value/false-value Not Submitted in Forms
+impact: MEDIUM
+impactDescription: true-value and false-value attributes don't affect form submission - unchecked boxes send nothing
+type: capability
+tags: [vue3, v-model, forms, checkbox, form-submission]
+---
+
+# Checkbox true-value/false-value Not Submitted in Forms
+
+**Impact: MEDIUM** - Vue's `true-value` and `false-value` attributes only affect the JavaScript binding, NOT the actual form submission. Unchecked checkboxes are never included in form submissions by browsers, regardless of `false-value`.
+
+This is a browser limitation, not a Vue issue. If you need to submit one of two values (like "yes"/"no" or "active"/"inactive"), use radio buttons instead of a checkbox.
+
+## Task Checklist
+
+- [ ] Don't rely on `false-value` for form submissions - it won't be sent
+- [ ] Use radio buttons when you need to submit one of exactly two values
+- [ ] Remember `true-value`/`false-value` are for JavaScript state only
+- [ ] For form submissions with custom values, handle the transformation server-side or in submit handler
+
+**Problem - false-value not submitted:**
+```html
+<script setup>
+import { ref } from 'vue'
+
+const status = ref('no')  // JavaScript value works correctly
+</script>
+
+<template>
+  <form action="/api/update" method="POST">
+    <!-- PROBLEM: When unchecked, nothing is submitted for this field -->
+    <!-- Server receives no "status" field at all, not "no" -->
+    <input
+      type="checkbox"
+      v-model="status"
+      true-value="yes"
+      false-value="no"
+      name="status"
+    >
+    <label>Active</label>
+
+    <!-- status.value correctly shows "yes" or "no" in Vue -->
+    <!-- But form submission only sends "status=yes" when checked -->
+    <!-- When unchecked, "status" field is completely missing -->
+  </form>
+</template>
+```
+
+**Solution 1 - Use radio buttons for two-value submission:**
+```html
+<script setup>
+import { ref } from 'vue'
+
+const status = ref('no')
+</script>
+
+<template>
+  <form action="/api/update" method="POST">
+    <!-- CORRECT: Radio buttons always submit a value -->
+    <label>
+      <input type="radio" v-model="status" value="yes" name="status">
+      Active
+    </label>
+    <label>
+      <input type="radio" v-model="status" value="no" name="status">
+      Inactive
+    </label>
+
+    <!-- Form always submits "status=yes" or "status=no" -->
+  </form>
+</template>
+```
+
+**Solution 2 - Handle in submit handler (for SPA/AJAX):**
+```html
+<script setup>
+import { ref } from 'vue'
+
+const isActive = ref(false)
+
+async function submitForm() {
+  // Transform checkbox state to desired value before sending
+  const payload = {
+    status: isActive.value ? 'yes' : 'no'
+  }
+
+  await fetch('/api/update', {
+    method: 'POST',
+    body: JSON.stringify(payload)
+  })
+}
+</script>
+
+<template>
+  <!-- For AJAX submission, checkbox is fine - transform in handler -->
+  <input type="checkbox" v-model="isActive">
+  <label>Active</label>
+
+  <button @click="submitForm">Save</button>
+</template>
+```
+
+**Solution 3 - Hidden input fallback:**
+```html
+<template>
+  <form action="/api/update" method="POST">
+    <!-- Hidden input provides fallback value -->
+    <input type="hidden" name="status" value="no">
+    <!-- Checkbox overrides with "yes" when checked -->
+    <input type="checkbox" name="status" value="yes" v-model="isActive">
+    <label>Active</label>
+  </form>
+</template>
+```
+
+## Reference
+- [Vue.js Form Input Bindings - Checkbox](https://vuejs.org/guide/essentials/forms.html#checkbox)

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

@@ -0,0 +1,172 @@
+---
+title: Clean Up Event Listeners and Intervals in onUnmounted
+impact: HIGH
+impactDescription: Failing to clean up side effects causes memory leaks and ghost event handlers
+type: capability
+tags: [vue3, lifecycle, memory-leak, event-listeners, intervals, cleanup]
+---
+
+# Clean Up Event Listeners and Intervals in onUnmounted
+
+**Impact: HIGH** - Failing to clean up event listeners, intervals, timeouts, and subscriptions when a component unmounts causes memory leaks and ghost handlers that continue running, leading to performance degradation and subtle bugs in Single Page Applications.
+
+When using custom events, timers, WebSocket connections, or third-party libraries, always clean up in `onUnmounted` (Composition API) or `unmounted` (Options API).
+
+## Task Checklist
+
+- [ ] Track all addEventListener calls and remove them in onUnmounted
+- [ ] Clear all setInterval and setTimeout calls in onUnmounted
+- [ ] Unsubscribe from external event emitters and observables
+- [ ] Disconnect WebSocket connections and third-party library instances
+- [ ] Use `onBeforeUnmount` if cleanup must happen before DOM removal
+
+**Incorrect:**
+```javascript
+// Composition API - WRONG: No cleanup
+import { onMounted } from 'vue'
+
+export default {
+  setup() {
+    onMounted(() => {
+      // These keep running after component unmounts!
+      window.addEventListener('resize', handleResize)
+      setInterval(pollServer, 5000)
+      socket.on('message', handleMessage)
+    })
+  }
+}
+```
+
+```javascript
+// Options API - WRONG: No cleanup
+export default {
+  mounted() {
+    window.addEventListener('scroll', this.handleScroll)
+    this.timer = setInterval(this.refresh, 10000)
+  }
+  // Component unmounts, but listeners and timers persist!
+}
+```
+
+**Correct:**
+```javascript
+// Composition API - CORRECT: Proper cleanup
+import { onMounted, onUnmounted, ref } from 'vue'
+
+export default {
+  setup() {
+    const intervalId = ref(null)
+
+    const handleResize = () => {
+      // handle resize
+    }
+
+    const handleMessage = (msg) => {
+      // handle message
+    }
+
+    onMounted(() => {
+      window.addEventListener('resize', handleResize)
+      intervalId.value = setInterval(pollServer, 5000)
+      socket.on('message', handleMessage)
+    })
+
+    onUnmounted(() => {
+      // Clean up everything!
+      window.removeEventListener('resize', handleResize)
+
+      if (intervalId.value) {
+        clearInterval(intervalId.value)
+      }
+
+      socket.off('message', handleMessage)
+    })
+  }
+}
+```
+
+```javascript
+// Options API - CORRECT: Proper cleanup
+export default {
+  data() {
+    return {
+      timer: null
+    }
+  },
+  mounted() {
+    window.addEventListener('scroll', this.handleScroll)
+    this.timer = setInterval(this.refresh, 10000)
+  },
+  unmounted() {
+    window.removeEventListener('scroll', this.handleScroll)
+    if (this.timer) {
+      clearInterval(this.timer)
+    }
+  },
+  methods: {
+    handleScroll() { /* ... */ },
+    refresh() { /* ... */ }
+  }
+}
+```
+
+## Using Composable Pattern for Auto-Cleanup
+
+```javascript
+// Reusable composable with automatic cleanup
+import { onMounted, onUnmounted } from 'vue'
+
+export function useEventListener(target, event, handler) {
+  onMounted(() => {
+    target.addEventListener(event, handler)
+  })
+
+  onUnmounted(() => {
+    target.removeEventListener(event, handler)
+  })
+}
+
+export function useInterval(callback, delay) {
+  let intervalId = null
+
+  onMounted(() => {
+    intervalId = setInterval(callback, delay)
+  })
+
+  onUnmounted(() => {
+    if (intervalId) clearInterval(intervalId)
+  })
+}
+
+// Usage - cleanup is automatic
+import { useEventListener, useInterval } from './composables'
+
+export default {
+  setup() {
+    useEventListener(window, 'resize', handleResize)
+    useInterval(pollServer, 5000)
+    // No manual cleanup needed!
+  }
+}
+```
+
+## VueUse Alternative
+
+```javascript
+// VueUse provides cleanup-aware composables
+import { useEventListener, useIntervalFn } from '@vueuse/core'
+
+export default {
+  setup() {
+    // Automatically cleaned up on unmount
+    useEventListener(window, 'resize', handleResize)
+
+    const { pause, resume } = useIntervalFn(pollServer, 5000)
+    // Also provides pause/resume controls
+  }
+}
+```
+
+## Reference
+- [Vue.js Lifecycle Hooks](https://vuejs.org/guide/essentials/lifecycle.html)
+- [VueUse - useEventListener](https://vueuse.org/core/useEventListener/)

package/skills/vue-debug-guides/reference/click-events-on-components.md

@@ -0,0 +1,180 @@
+---
+title: Click Events on Custom Components Require Emit or Fallthrough
+impact: HIGH
+impactDescription: Native click events on custom components won't work without proper emit declaration or attribute fallthrough
+type: gotcha
+tags: [vue3, events, components, emit, click, migration]
+---
+
+# Click Events on Custom Components Require Emit or Fallthrough
+
+**Impact: HIGH** - Unlike native HTML elements, custom Vue components don't automatically forward native DOM events like `click`. You must either emit the event explicitly, rely on attribute fallthrough to a single root element, or use the `.native` modifier (Vue 2 only, removed in Vue 3). This is a common source of confusion and migration issues.
+
+## Task Checklist
+
+- [ ] Declare emitted events using `defineEmits` in child components
+- [ ] Emit click events from child component when needed
+- [ ] Understand that single-root components automatically forward attrs to root
+- [ ] Remove `.native` modifier when migrating from Vue 2 to Vue 3
+- [ ] For multi-root components, explicitly bind `$attrs` or emit events
+
+**Incorrect:**
+```html
+<!-- WRONG: Expecting native click to work on custom component -->
+<template>
+  <MyButton @click="handleClick">Click me</MyButton>
+  <!-- This may not work as expected! -->
+</template>
+```
+
+```html
+<!-- WRONG: Vue 2 .native modifier doesn't exist in Vue 3 -->
+<template>
+  <MyButton @click.native="handleClick">Click me</MyButton>
+  <!-- Error in Vue 3: .native modifier removed -->
+</template>
+```
+
+```html
+<!-- WRONG: Multi-root component with no attr binding -->
+<!-- MyButton.vue -->
+<template>
+  <span>Icon</span>
+  <button>{{ label }}</button>
+  <!-- No root element to receive click! -->
+</template>
+```
+
+**Correct:**
+```html
+<!-- CORRECT: Child component emits the click event -->
+<!-- MyButton.vue -->
+<template>
+  <button @click="$emit('click', $event)">
+    <slot></slot>
+  </button>
+</template>
+
+<script setup>
+defineEmits(['click'])
+</script>
+
+<!-- Parent.vue -->
+<template>
+  <MyButton @click="handleClick">Click me</MyButton>
+</template>
+```
+
+```html
+<!-- CORRECT: Single root element with automatic fallthrough -->
+<!-- MyButton.vue -->
+<template>
+  <button>
+    <slot></slot>
+  </button>
+  <!-- @click from parent automatically falls through to button -->
+</template>
+
+<!-- Parent.vue -->
+<template>
+  <MyButton @click="handleClick">Click me</MyButton>
+</template>
+```
+
+```html
+<!-- CORRECT: Multi-root component with explicit $attrs binding -->
+<!-- MyButton.vue -->
+<template>
+  <span>Icon</span>
+  <button v-bind="$attrs">
+    <slot></slot>
+  </button>
+</template>
+
+<script setup>
+defineOptions({
+  inheritAttrs: false
+})
+</script>
+```
+
+## Component Events Don't Bubble
+
+```javascript
+// Important: Component-emitted events do NOT bubble
+// You can only listen to events from direct children
+
+// WRONG: Trying to catch grandchild events
+<GrandParent @child-event="handle">  <!-- Won't receive! -->
+  <Parent>
+    <Child @click="$emit('child-event')" />
+  </Parent>
+</GrandParent>
+
+// CORRECT: Each level must relay the event
+<GrandParent @child-event="handle">
+  <Parent @child-event="$emit('child-event', $event)">
+    <Child @click="$emit('child-event')" />
+  </Parent>
+</GrandParent>
+```
+
+## Vue 3 Native Event Behavior
+
+```javascript
+// In Vue 3, if you declare an event in emits:
+defineEmits(['click'])
+
+// Then @click on the component ONLY listens to emitted events
+// NOT native click events
+
+// If you don't declare 'click' in emits:
+defineEmits(['custom-event'])
+
+// Then @click on single-root component will:
+// 1. Fall through to root element as native listener
+// 2. Fire on native click
+```
+
+## Composition API Emit Pattern
+
+```vue
+<script setup>
+// Define what events this component emits
+const emit = defineEmits(['click', 'update', 'delete'])
+
+function handleClick(event) {
+  // Do component logic
+  processClick()
+
+  // Then emit to parent
+  emit('click', event)
+}
+</script>
+
+<template>
+  <button @click="handleClick">
+    <slot></slot>
+  </button>
+</template>
+```
+
+## Migration from Vue 2
+
+```html
+<!-- Vue 2: Used .native for native events on components -->
+<MyComponent @click.native="handleClick" />
+
+<!-- Vue 3: Remove .native, ensure component handles the event -->
+<MyComponent @click="handleClick" />
+
+<!-- Make sure MyComponent either:
+     1. Has single root that receives fallthrough attrs
+     2. Explicitly emits 'click' event
+     3. Uses v-bind="$attrs" on intended element -->
+```
+
+## Reference
+- [Vue.js Component Events](https://vuejs.org/guide/components/events.html)
+- [Vue.js Fallthrough Attributes](https://vuejs.org/guide/components/attrs.html)
+- [Vue 3 Migration - .native Modifier Removed](https://v3-migration.vuejs.org/breaking-changes/v-on-native-modifier-removed.html)

package/skills/vue-debug-guides/reference/component-naming-conflicts.md

@@ -0,0 +1,159 @@
+---
+title: Avoid Component Naming Conflicts Between Global and Local
+impact: HIGH
+impactDescription: Naming conflicts cause unexpected component rendering and hard-to-debug issues
+type: gotcha
+tags: [vue3, component-registration, naming-conflicts, global-local, debugging]
+---
+
+# Avoid Component Naming Conflicts Between Global and Local
+
+**Impact: HIGH** - When a global component and a local component have the same name (or resolve to the same name due to casing differences), unexpected behavior occurs. The precedence rules can be confusing, and the wrong component may render silently without any error. This is particularly problematic when using third-party component libraries.
+
+## Task Checklist
+
+- [ ] Use unique, prefixed names for global components (e.g., `BaseButton`, `AppHeader`)
+- [ ] Check for naming conflicts when adding global components
+- [ ] Explicitly alias local components if there's potential conflict
+- [ ] When overriding third-party components, document and test thoroughly
+
+**Incorrect:**
+```javascript
+// main.js
+import { createApp } from 'vue'
+import Button from './components/Button.vue'
+
+const app = createApp(App)
+app.component('Button', Button) // Global Button
+```
+
+```vue
+<!-- SomeComponent.vue -->
+<script setup>
+// This local Button might conflict with global Button
+import Button from './local/Button.vue'
+</script>
+
+<template>
+  <!-- Which Button renders? Behavior may be unexpected -->
+  <Button>Click me</Button>
+</template>
+```
+
+```vue
+<!-- Another confusing scenario -->
+<script setup>
+// Registering with camelCase
+import MyButton from './MyButton.vue'
+</script>
+
+<template>
+  <!-- Using kebab-case - might match a global 'my-button' instead -->
+  <my-button>Click</my-button>
+</template>
+```
+
+**Correct:**
+```javascript
+// main.js - use prefixes for global components
+import { createApp } from 'vue'
+import BaseButton from './components/BaseButton.vue'
+import BaseIcon from './components/BaseIcon.vue'
+
+const app = createApp(App)
+app.component('BaseButton', BaseButton)
+app.component('BaseIcon', BaseIcon)
+```
+
+```vue
+<!-- SomeComponent.vue -->
+<script setup>
+// Local components have distinct names
+import SubmitButton from './local/SubmitButton.vue'
+</script>
+
+<template>
+  <!-- No ambiguity - each name is unique -->
+  <BaseButton>Generic button</BaseButton>
+  <SubmitButton>Submit form</SubmitButton>
+</template>
+```
+
+## Explicit Aliasing for Clarity
+
+When you intentionally want to override or have similar names, use explicit aliasing:
+
+```vue
+<script setup>
+// Explicit alias to avoid confusion
+import { default as LocalButton } from './Button.vue'
+</script>
+
+<template>
+  <LocalButton>Local version</LocalButton>
+</template>
+```
+
+```vue
+<!-- Options API with explicit component name -->
+<script>
+import ThirdPartyModal from 'some-library'
+import CustomModal from './CustomModal.vue'
+
+export default {
+  components: {
+    // Explicit names prevent ambiguity
+    LibraryModal: ThirdPartyModal,
+    CustomModal
+  }
+}
+</script>
+```
+
+## Resolution Order
+
+Understanding Vue's component resolution order helps debug issues:
+
+1. **Local registration** takes precedence over global
+2. **Exact case match** takes precedence over case-insensitive match
+3. Self-referencing component name (file name) has lowest priority
+
+```vue
+<!-- If all exist: GlobalButton, local Button, and file is Button.vue -->
+<script setup>
+import Button from './Button.vue' // Local registration
+</script>
+
+<template>
+  <!-- Resolves to locally imported Button, not global -->
+  <Button />
+</template>
+```
+
+## Third-Party Library Conflicts
+
+```vue
+<script setup>
+// Be explicit when using components from multiple libraries
+import { Button as AntButton } from 'ant-design-vue'
+import { Button as ElButton } from 'element-plus'
+</script>
+
+<template>
+  <AntButton>Ant Design</AntButton>
+  <ElButton>Element Plus</ElButton>
+</template>
+```
+
+## Naming Convention Strategy
+
+| Component Type | Naming Pattern | Example |
+|----------------|---------------|---------|
+| Base/Global | `Base*` or `App*` prefix | `BaseButton`, `AppHeader` |
+| Domain-specific | Domain prefix | `UserCard`, `ProductList` |
+| Page components | `*Page` or `*View` suffix | `HomePage`, `UserView` |
+| Layout components | `*Layout` suffix | `DefaultLayout`, `AdminLayout` |
+
+## Reference
+- [Vue.js Component Registration](https://vuejs.org/guide/components/registration.html)
+- [GitHub Issue: Global component naming conflicts](https://github.com/vuejs/vue/issues/4434)