@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/dynamic-argument-constraints.md

@@ -0,0 +1,146 @@
+---
+title: Dynamic Directive Arguments Have Syntax Constraints
+impact: MEDIUM
+impactDescription: Invalid dynamic arguments cause silent failures or browser compatibility issues
+type: capability
+tags: [vue3, template, directives, v-bind, v-on, dynamic-arguments]
+---
+
+# Dynamic Directive Arguments Have Syntax Constraints
+
+**Impact: MEDIUM** - Dynamic directive arguments (e.g., `:[attributeName]`, `@[eventName]`) have value and syntax constraints that can cause silent failures. In-DOM templates also have case sensitivity issues with browsers lowercasing attribute names.
+
+Dynamic arguments allow runtime determination of which attribute or event to bind, but they have restrictions that differ from static arguments.
+
+## Task Checklist
+
+- [ ] Ensure dynamic arguments evaluate to strings or `null`
+- [ ] Avoid spaces and quotes inside dynamic argument brackets
+- [ ] Use computed properties for complex dynamic argument expressions
+- [ ] In in-DOM templates, use lowercase attribute names or switch to SFCs
+- [ ] Use `null` to explicitly remove a binding
+
+**Incorrect:**
+```vue
+<template>
+  <!-- ERROR: Spaces and quotes not allowed in dynamic arguments -->
+  <a :[' foo' + bar]="value">Link</a>
+  <a :["data-" + name]="value">Link</a>
+
+  <!-- WARNING: Non-string values (except null) trigger warnings -->
+  <a :[123]="value">Link</a>
+  <a :[someObject]="value">Link</a>
+
+  <!-- BUG in in-DOM templates: Browsers lowercase attribute names -->
+  <!-- This becomes :[someattr] which won't match someAttr -->
+  <a :[someAttr]="url">Link</a>
+</template>
+
+<script setup>
+// If component expects someAttr but browser lowercases to someattr
+// the binding silently fails
+const someAttr = 'href'
+</script>
+```
+
+**Correct:**
+```vue
+<template>
+  <!-- OK: Simple variable reference -->
+  <a :[attributeName]="url">Link</a>
+
+  <!-- OK: Use computed property for complex expressions -->
+  <a :[dynamicAttr]="value">Link</a>
+
+  <!-- OK: null removes the binding -->
+  <button :[disabledAttr]="isDisabled">Submit</button>
+
+  <!-- OK: Dynamic event names -->
+  <button @[eventName]="handler">Click</button>
+
+  <!-- OK: In SFCs, case is preserved -->
+  <a :[someAttr]="url">Link</a>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+// Simple string variable
+const attributeName = ref('href')
+const url = ref('https://vuejs.org')
+
+// Complex expression via computed property
+const prefix = ref('data')
+const name = ref('id')
+const dynamicAttr = computed(() => `${prefix.value}-${name.value}`)
+
+// Conditional binding with null
+const isDisabled = ref(false)
+const disabledAttr = computed(() => isDisabled.value ? 'disabled' : null)
+
+// Dynamic events
+const useTouch = ref(false)
+const eventName = computed(() => useTouch.value ? 'touchstart' : 'click')
+
+function handler() {
+  console.log('Event triggered')
+}
+</script>
+```
+
+## In-DOM Template Workaround
+
+When writing templates directly in HTML (not SFCs), use lowercase:
+
+```html
+<!-- In-DOM template (index.html) -->
+<div id="app">
+  <!-- Use lowercase to avoid browser issues -->
+  <a :[attrname]="url">Link</a>
+</div>
+
+<script type="module">
+import { createApp, ref } from 'vue'
+
+createApp({
+  setup() {
+    // Match the lowercase used in template
+    const attrname = ref('href')
+    const url = ref('https://vuejs.org')
+    return { attrname, url }
+  }
+}).mount('#app')
+</script>
+```
+
+## SFC vs In-DOM Templates
+
+| Feature | SFC (.vue files) | In-DOM (HTML) |
+|---------|------------------|---------------|
+| Case sensitivity | Preserved | Lowercased by browser |
+| Dynamic arguments | Full support | Lowercase only |
+| Recommendation | Preferred | Use for progressive enhancement |
+
+## Valid Dynamic Argument Values
+
+```vue
+<script setup>
+// String values - OK
+const attr1 = 'href'
+const attr2 = 'data-custom'
+
+// null - OK (removes binding)
+const attr3 = null
+
+// undefined - OK (removes binding)
+const attr4 = undefined
+
+// Numbers, objects, arrays - WARNING
+const attr5 = 123        // Warning: should be string
+const attr6 = { foo: 1 } // Warning: should be string
+</script>
+```
+
+## Reference
+- [Vue.js Template Syntax - Dynamic Arguments](https://vuejs.org/guide/essentials/template-syntax.html#dynamic-arguments)
+- [Vue.js Template Syntax - Dynamic Argument Value Constraints](https://vuejs.org/guide/essentials/template-syntax.html#dynamic-argument-value-constraints)

package/skills/vue-debug-guides/reference/dynamic-component-registration-vite.md

@@ -0,0 +1,147 @@
+---
+title: Use import.meta.glob for Dynamic Component Registration in Vite
+impact: MEDIUM
+impactDescription: require.context from Webpack doesn't work in Vite projects
+type: gotcha
+tags: [vue3, component-registration, vite, dynamic-import, migration, webpack]
+---
+
+# Use import.meta.glob for Dynamic Component Registration in Vite
+
+**Impact: MEDIUM** - When migrating from Webpack to Vite or starting a new Vite project, the `require.context` pattern for dynamically registering components won't work. Vite uses `import.meta.glob` instead. Using the wrong approach will cause build errors or runtime failures.
+
+## Task Checklist
+
+- [ ] Replace `require.context` with `import.meta.glob` in Vite projects
+- [ ] Update component registration patterns when migrating from Vue CLI to Vite
+- [ ] Use `{ eager: true }` for synchronous loading when needed
+- [ ] Handle async components appropriately with `defineAsyncComponent`
+
+**Incorrect (Webpack pattern - doesn't work in Vite):**
+```javascript
+// main.js - WRONG for Vite
+import { createApp } from 'vue'
+import App from './App.vue'
+
+const app = createApp(App)
+
+// This Webpack-specific API doesn't exist in Vite
+const requireComponent = require.context(
+  './components/base',
+  false,
+  /Base[A-Z]\w+\.vue$/
+)
+
+requireComponent.keys().forEach(fileName => {
+  const componentConfig = requireComponent(fileName)
+  const componentName = fileName
+    .split('/')
+    .pop()
+    .replace(/\.\w+$/, '')
+
+  app.component(componentName, componentConfig.default || componentConfig)
+})
+
+app.mount('#app')
+```
+
+**Correct (Vite pattern):**
+```javascript
+// main.js - Correct for Vite
+import { createApp } from 'vue'
+import App from './App.vue'
+
+const app = createApp(App)
+
+// Vite's glob import - eager loading for synchronous registration
+const modules = import.meta.glob('./components/base/Base*.vue', { eager: true })
+
+for (const path in modules) {
+  // Extract component name from path: './components/base/BaseButton.vue' -> 'BaseButton'
+  const componentName = path.split('/').pop().replace('.vue', '')
+  app.component(componentName, modules[path].default)
+}
+
+app.mount('#app')
+```
+
+## Lazy Loading with Async Components
+
+```javascript
+// main.js - Lazy loading variant
+import { createApp, defineAsyncComponent } from 'vue'
+import App from './App.vue'
+
+const app = createApp(App)
+
+// Without { eager: true }, returns functions that return Promises
+const modules = import.meta.glob('./components/base/Base*.vue')
+
+for (const path in modules) {
+  const componentName = path.split('/').pop().replace('.vue', '')
+  // Wrap in defineAsyncComponent for lazy loading
+  app.component(componentName, defineAsyncComponent(modules[path]))
+}
+
+app.mount('#app')
+```
+
+## Glob Pattern Examples
+
+```javascript
+// All .vue files in a directory (not recursive)
+import.meta.glob('./components/*.vue', { eager: true })
+
+// All .vue files recursively
+import.meta.glob('./components/**/*.vue', { eager: true })
+
+// Specific naming pattern
+import.meta.glob('./components/Base*.vue', { eager: true })
+
+// Multiple patterns
+import.meta.glob([
+  './components/Base*.vue',
+  './components/App*.vue'
+], { eager: true })
+
+// Exclude patterns
+import.meta.glob('./components/**/*.vue', {
+  eager: true,
+  ignore: ['**/*.test.vue', '**/*.spec.vue']
+})
+```
+
+## TypeScript Support
+
+```typescript
+// main.ts - with proper typing
+import { createApp, Component } from 'vue'
+import App from './App.vue'
+
+const app = createApp(App)
+
+const modules = import.meta.glob<{ default: Component }>(
+  './components/base/Base*.vue',
+  { eager: true }
+)
+
+for (const path in modules) {
+  const componentName = path.split('/').pop()!.replace('.vue', '')
+  app.component(componentName, modules[path].default)
+}
+
+app.mount('#app')
+```
+
+## Migration Checklist (Webpack to Vite)
+
+| Webpack | Vite |
+|---------|------|
+| `require.context(dir, recursive, regex)` | `import.meta.glob(pattern, options)` |
+| Synchronous by default | Use `{ eager: true }` for sync |
+| `.keys()` returns array | Returns object with paths as keys |
+| Returns module directly | Access via `.default` for ES modules |
+
+## Reference
+- [Vite - Glob Import](https://vitejs.dev/guide/features.html#glob-import)
+- [Vue.js Component Registration](https://vuejs.org/guide/components/registration.html)

package/skills/vue-debug-guides/reference/event-modifier-order-matters.md

@@ -0,0 +1,101 @@
+---
+title: Event Modifier Order Matters
+impact: MEDIUM
+impactDescription: Modifier order affects event handling behavior - wrong order causes unexpected propagation or prevention
+type: gotcha
+tags: [vue3, events, modifiers, v-on, click, form]
+---
+
+# Event Modifier Order Matters
+
+**Impact: MEDIUM** - When chaining event modifiers, the order determines behavior because Vue generates code in the same sequence. Using `.prevent.self` vs `.self.prevent` produces different results that can cause subtle bugs in event handling.
+
+## Task Checklist
+
+- [ ] Always consider modifier order when chaining multiple modifiers
+- [ ] Use `.prevent.self` to prevent default on element AND children
+- [ ] Use `.self.prevent` to prevent default ONLY on the element itself
+- [ ] Test event behavior on both the element and its children
+
+**Incorrect:**
+```html
+<!-- WRONG: Unintended behavior - prevents clicks on children too -->
+<template>
+  <div @click.prevent.self="handleClick">
+    <button>Child Button</button> <!-- Default also prevented here! -->
+  </div>
+</template>
+```
+
+```html
+<!-- WRONG: Assuming order doesn't matter -->
+<template>
+  <!-- Developer expects only self clicks to be handled -->
+  <!-- But .prevent runs first, affecting all clicks -->
+  <a href="/page" @click.prevent.self="navigate">
+    <span>Click me</span>
+  </a>
+</template>
+```
+
+**Correct:**
+```html
+<!-- CORRECT: Only prevent default on the element itself -->
+<template>
+  <div @click.self.prevent="handleClick">
+    <button>Child Button</button> <!-- Default NOT prevented here -->
+  </div>
+</template>
+```
+
+```html
+<!-- CORRECT: Prevent default on element and children -->
+<template>
+  <form @submit.prevent.self="onSubmit">
+    <button type="submit">Submit</button>
+  </form>
+</template>
+```
+
+```html
+<!-- CORRECT: Explicit intent with separate handlers when needed -->
+<template>
+  <div @click.self="handleSelfClick">
+    <button @click.prevent="handleChildClick">
+      Child with prevented default
+    </button>
+  </div>
+</template>
+```
+
+## How Modifier Order Works
+
+```javascript
+// Vue compiles modifiers in order, so:
+
+// @click.prevent.self compiles to:
+// event.preventDefault()
+// if (event.target !== event.currentTarget) return
+// handler()
+
+// @click.self.prevent compiles to:
+// if (event.target !== event.currentTarget) return
+// event.preventDefault()
+// handler()
+```
+
+## Common Modifier Combinations
+
+```html
+<!-- Stop propagation AND prevent default -->
+<a @click.stop.prevent="handleClick">Link</a>
+
+<!-- Capture mode with once -->
+<div @click.capture.once="handleOnce">...</div>
+
+<!-- Only exact modifier key combination -->
+<button @click.ctrl.exact="onCtrlClick">Ctrl+Click Only</button>
+```
+
+## Reference
+- [Vue.js Event Handling - Event Modifiers](https://vuejs.org/guide/essentials/event-handling.html#event-modifiers)

package/skills/vue-debug-guides/reference/exact-modifier-for-precise-shortcuts.md

@@ -0,0 +1,155 @@
+---
+title: Use .exact Modifier for Precise Keyboard/Mouse Shortcuts
+impact: MEDIUM
+impactDescription: Without .exact, shortcuts fire even when additional modifier keys are pressed, causing unintended behavior
+type: best-practice
+tags: [vue3, events, keyboard, modifiers, shortcuts, accessibility]
+---
+
+# Use .exact Modifier for Precise Keyboard/Mouse Shortcuts
+
+**Impact: MEDIUM** - By default, Vue's modifier key handlers (`.ctrl`, `.alt`, `.shift`, `.meta`) fire even when other modifier keys are also pressed. Use `.exact` to require that ONLY the specified modifiers are pressed, preventing accidental triggering of shortcuts.
+
+## Task Checklist
+
+- [ ] Use `.exact` when you need precise modifier combinations
+- [ ] Without `.exact`: `@click.ctrl` fires for Ctrl+Click AND Ctrl+Shift+Click
+- [ ] With `.exact`: `@click.ctrl.exact` fires ONLY for Ctrl+Click
+- [ ] Use `@click.exact` for plain clicks with no modifiers
+
+**Incorrect:**
+```html
+<!-- WRONG: Fires even with additional modifiers -->
+<template>
+  <button @click.ctrl="copyItem">Copy</button>
+  <!-- Also fires on Ctrl+Shift+Click, Ctrl+Alt+Click, etc. -->
+
+  <button @click.ctrl.shift="copyAll">Copy All</button>
+  <!-- User expects Ctrl+Shift, but also fires on Ctrl+Shift+Alt -->
+</template>
+```
+
+```html
+<!-- WRONG: Conflicting shortcuts without .exact -->
+<template>
+  <div>
+    <button @click.ctrl="copy">Copy (Ctrl+Click)</button>
+    <button @click.ctrl.shift="copyAll">Copy All (Ctrl+Shift+Click)</button>
+    <!-- Both fire when user does Ctrl+Shift+Click! -->
+  </div>
+</template>
+```
+
+**Correct:**
+```html
+<!-- CORRECT: Precise modifier matching with .exact -->
+<template>
+  <button @click.ctrl.exact="copyItem">Copy (Ctrl only)</button>
+  <!-- Only fires on Ctrl+Click, not Ctrl+Shift+Click -->
+
+  <button @click.ctrl.shift.exact="copyAll">Copy All (Ctrl+Shift only)</button>
+  <!-- Only fires on Ctrl+Shift+Click, not Ctrl+Shift+Alt+Click -->
+</template>
+```
+
+```html
+<!-- CORRECT: Plain click without any modifiers -->
+<template>
+  <button @click.exact="selectItem">Select</button>
+  <!-- Only fires when NO modifier keys are pressed -->
+  <!-- Ctrl+Click, Shift+Click, etc. will NOT trigger this -->
+</template>
+```
+
+```html
+<!-- CORRECT: Non-conflicting shortcuts -->
+<template>
+  <div class="editor">
+    <div
+      @click.exact="selectItem"
+      @click.ctrl.exact="addToSelection"
+      @click.shift.exact="extendSelection"
+      @click.ctrl.shift.exact="selectRange"
+    >
+      Click, Ctrl+Click, Shift+Click, or Ctrl+Shift+Click
+    </div>
+  </div>
+</template>
+```
+
+## Behavior Comparison
+
+```javascript
+// WITHOUT .exact
+@click.ctrl="handler"
+// Fires when: Ctrl+Click, Ctrl+Shift+Click, Ctrl+Alt+Click, Ctrl+Shift+Alt+Click
+// Does NOT fire: Click (without Ctrl)
+
+// WITH .exact
+@click.ctrl.exact="handler"
+// Fires when: ONLY Ctrl+Click
+// Does NOT fire: Ctrl+Shift+Click, Ctrl+Alt+Click, Click
+
+// ONLY .exact (no other modifiers)
+@click.exact="handler"
+// Fires when: Plain click with NO modifiers
+// Does NOT fire: Ctrl+Click, Shift+Click, Alt+Click
+```
+
+## Practical Example: File Browser Selection
+
+```vue
+<template>
+  <ul class="file-list">
+    <li
+      v-for="file in files"
+      :key="file.id"
+      @click.exact="selectSingle(file)"
+      @click.ctrl.exact="toggleSelection(file)"
+      @click.shift.exact="selectRange(file)"
+      @click.ctrl.shift.exact="addRangeToSelection(file)"
+      :class="{ selected: isSelected(file) }"
+    >
+      {{ file.name }}
+    </li>
+  </ul>
+</template>
+
+<script setup>
+// Each click type has distinct, non-overlapping behavior
+function selectSingle(file) {
+  // Clear selection and select only this file
+}
+
+function toggleSelection(file) {
+  // Add or remove this file from current selection
+}
+
+function selectRange(file) {
+  // Select all files from last selected to this one
+}
+
+function addRangeToSelection(file) {
+  // Add range to existing selection
+}
+</script>
+```
+
+## Keyboard Shortcuts with .exact
+
+```html
+<template>
+  <div
+    tabindex="0"
+    @keydown.ctrl.s.exact.prevent="save"
+    @keydown.ctrl.shift.s.exact.prevent="saveAs"
+    @keydown.ctrl.z.exact.prevent="undo"
+    @keydown.ctrl.shift.z.exact.prevent="redo"
+  >
+    <!-- Each shortcut is precisely defined -->
+  </div>
+</template>
+```
+
+## Reference
+- [Vue.js Event Handling - .exact Modifier](https://vuejs.org/guide/essentials/event-handling.html#exact-modifier)

package/skills/vue-debug-guides/reference/fallthrough-attrs-overwrite-vue3.md

@@ -0,0 +1,159 @@
+# Fallthrough Attributes Overwrite Explicit Attributes in Vue 3
+
+## Rule
+
+In Vue 3, fallthrough attributes overwrite explicitly set attributes on the root element (except `class` and `style` which are merged). This is a breaking change from Vue 2. To preserve explicit attribute values, use `inheritAttrs: false` and manually bind `$attrs` before the explicit attribute.
+
+## Why This Matters
+
+- Silent behavior change from Vue 2 to Vue 3
+- Can cause unexpected attribute values in migrated codebases
+- Only `class` and `style` merge intelligently; other attributes are overwritten
+- Affects component composition patterns and wrapper components
+
+## Bad Code
+
+```vue
+<!-- Parent.vue -->
+<template>
+  <Child msg="Passed from Parent" />
+</template>
+
+<!-- Child.vue - UNEXPECTED BEHAVIOR -->
+<template>
+  <GrandChild msg="Set in Child" />
+</template>
+
+<!--
+  Vue 3 Result: GrandChild receives msg="Passed from Parent"
+  The fallthrough attribute OVERWRITES the explicit one!
+
+  Vue 2 Result: GrandChild receives msg="Set in Child"
+  The explicit attribute took precedence
+-->
+```
+
+### Another common case with data attributes
+
+```vue
+<!-- Parent.vue -->
+<template>
+  <Button data-testid="parent-button" />
+</template>
+
+<!-- Button.vue - WRONG: explicit data-testid is overwritten -->
+<template>
+  <button data-testid="submit-btn">Submit</button>
+</template>
+
+<!-- Result: <button data-testid="parent-button">Submit</button> -->
+<!-- The component's intended test ID is lost! -->
+```
+
+## Good Code
+
+### Option 1: Control attribute order with inheritAttrs: false
+
+```vue
+<!-- Child.vue - CORRECT: Control attribute precedence -->
+<script setup>
+defineOptions({
+  inheritAttrs: false
+})
+</script>
+
+<template>
+  <!-- v-bind="$attrs" FIRST, then explicit attribute -->
+  <GrandChild v-bind="$attrs" msg="Set in Child" />
+</template>
+
+<!--
+  Result: GrandChild receives msg="Set in Child"
+  Explicit attribute overrides fallthrough because it comes last
+-->
+```
+
+### Option 2: Exclude specific attrs from fallthrough
+
+```vue
+<script setup>
+import { computed, useAttrs } from 'vue'
+
+defineOptions({
+  inheritAttrs: false
+})
+
+const attrs = useAttrs()
+
+// Filter out attributes you want to control explicitly
+const filteredAttrs = computed(() => {
+  const { msg, ...rest } = attrs
+  return rest
+})
+</script>
+
+<template>
+  <GrandChild v-bind="filteredAttrs" msg="Set in Child" />
+</template>
+```
+
+### Option 3: For wrapper components, declare as prop
+
+```vue
+<!-- Button.vue - BEST: Declare attributes you need to control -->
+<script setup>
+const props = defineProps({
+  dataTestid: {
+    type: String,
+    default: 'submit-btn'
+  }
+})
+
+defineOptions({
+  inheritAttrs: false
+})
+</script>
+
+<template>
+  <button :data-testid="dataTestid" v-bind="$attrs">
+    <slot />
+  </button>
+</template>
+```
+
+## Class and Style Are Special
+
+Unlike other attributes, `class` and `style` merge rather than overwrite:
+
+```vue
+<!-- Parent.vue -->
+<template>
+  <Button class="large" style="color: red" />
+</template>
+
+<!-- Button.vue -->
+<template>
+  <button class="btn" style="padding: 10px">Submit</button>
+</template>
+
+<!--
+  Result: <button class="btn large" style="padding: 10px; color: red">
+  Both classes and styles are MERGED, not overwritten
+-->
+```
+
+## Vue 2 to Vue 3 Migration Checklist
+
+When migrating components that rely on attribute precedence:
+
+1. Identify components that set explicit attributes on root elements
+2. Check if parent components pass the same attributes
+3. If explicit values should take precedence:
+   - Add `inheritAttrs: false`
+   - Use `v-bind="$attrs"` before explicit attributes
+
+## References
+
+- [Fallthrough Attributes](https://vuejs.org/guide/components/attrs.html)
+- [Vue 3 Migration Guide - Attribute Coercion Behavior](https://v3-migration.vuejs.org/breaking-changes/)
+- [Vue Fallthrough Attributes behaviour changes from Vue 2 to Vue 3](https://lukes.tips/posts/vue-3-fallthough-attributes-changes/)