@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/in-dom-template-parsing-caveats.md

@@ -0,0 +1,149 @@
+---
+title: In-DOM Template Parsing Caveats
+impact: HIGH
+impactDescription: Browser HTML parsing before Vue compilation causes case sensitivity, self-closing tag, and element nesting issues
+type: gotcha
+tags: [vue3, templates, in-dom, html-parsing, kebab-case, self-closing-tags]
+---
+
+# In-DOM Template Parsing Caveats
+
+**Impact: HIGH** - When writing Vue templates directly in the DOM (not in `.vue` files), the browser's native HTML parser processes the template BEFORE Vue sees it. This causes three critical issues: case sensitivity problems, self-closing tag failures, and element placement restrictions.
+
+These issues do NOT apply to Single-File Components (SFCs) or string templates where Vue's compiler handles parsing directly.
+
+## Task Checklist
+
+- [ ] Use kebab-case for component names in in-DOM templates
+- [ ] Use kebab-case for prop names in in-DOM templates
+- [ ] Use explicit closing tags (not self-closing) in in-DOM templates
+- [ ] Use `is="vue:component-name"` for components inside restricted elements
+- [ ] Prefer SFCs to avoid all in-DOM parsing issues
+
+## Issue 1: Case Insensitivity
+
+HTML is case-insensitive. The browser lowercases everything before Vue sees it.
+
+**Incorrect (in-DOM template):**
+```html
+<!-- Browser converts to: <blogpost posttitle="hello"> -->
+<BlogPost postTitle="hello" @updatePost="onUpdate"></BlogPost>
+```
+
+**Correct (in-DOM template):**
+```html
+<!-- Use kebab-case for everything -->
+<blog-post post-title="hello" @update-post="onUpdate"></blog-post>
+```
+
+**In SFCs, PascalCase works fine:**
+```vue
+<!-- BlogPost.vue - PascalCase recommended -->
+<template>
+  <BlogPost postTitle="hello" @updatePost="onUpdate" />
+</template>
+```
+
+## Issue 2: Self-Closing Tags Fail
+
+HTML only allows self-closing syntax for void elements (`<input>`, `<img>`, etc.). For all others, the browser expects closing tags.
+
+**Incorrect (in-DOM template):**
+```html
+<!-- Browser thinks the tag never closed, breaks nesting -->
+<my-component />
+<another-component />
+```
+
+**Correct (in-DOM template):**
+```html
+<!-- Explicit closing tags required -->
+<my-component></my-component>
+<another-component></another-component>
+```
+
+**In SFCs, self-closing works fine:**
+```vue
+<template>
+  <MyComponent />
+  <AnotherComponent />
+</template>
+```
+
+## Issue 3: Element Placement Restrictions
+
+Some HTML elements have strict rules about valid children. Invalid elements are hoisted out by the browser before Vue sees the template.
+
+**Restricted parent elements:**
+- `<ul>`, `<ol>` - only allow `<li>`
+- `<table>` - only allows `<thead>`, `<tbody>`, `<tfoot>`, `<tr>`, `<caption>`, `<colgroup>`
+- `<tr>` - only allows `<td>`, `<th>`
+- `<select>` - only allows `<option>`, `<optgroup>`
+
+**Incorrect (in-DOM template):**
+```html
+<!-- Browser hoists blog-post-row outside the table -->
+<table>
+  <blog-post-row v-for="post in posts" :post="post"></blog-post-row>
+</table>
+
+<!-- Renders as: -->
+<blog-post-row></blog-post-row>
+<blog-post-row></blog-post-row>
+<table></table>
+```
+
+**Correct (in-DOM template):**
+```html
+<!-- Use is="vue:component-name" on a valid native element -->
+<table>
+  <tr is="vue:blog-post-row" v-for="post in posts" :key="post.id" :post="post"></tr>
+</table>
+```
+
+```html
+<ul>
+  <li is="vue:todo-item" v-for="todo in todos" :key="todo.id" :todo="todo"></li>
+</ul>
+```
+
+**Important:** The `vue:` prefix is required! Without it, `is` is treated as a native customized built-in element attribute.
+
+```html
+<!-- WRONG: Missing vue: prefix -->
+<tr is="blog-post-row"></tr>
+
+<!-- CORRECT: With vue: prefix -->
+<tr is="vue:blog-post-row"></tr>
+```
+
+## When Do These Apply?
+
+| Template Type | Affected? | Example |
+|---------------|-----------|---------|
+| Single-File Component (`.vue`) | No | `<template>` section |
+| String template | No | `template: '<div>...</div>'` |
+| In-DOM template | **Yes** | `<div id="app">...</div>` |
+| `<script type="text/x-template">` | **Yes** | Browser parses the script content |
+
+## Best Practice: Use SFCs
+
+The simplest solution is to use Single-File Components (`.vue` files) which completely avoid in-DOM parsing issues:
+
+```vue
+<!-- MyComponent.vue - All issues avoided -->
+<script setup>
+import BlogPost from './BlogPost.vue'
+</script>
+
+<template>
+  <BlogPost postTitle="hello" @updatePost="onUpdate" />
+
+  <table>
+    <BlogPostRow v-for="post in posts" :key="post.id" :post="post" />
+  </table>
+</template>
+```
+
+## Reference
+- [Vue.js - In-DOM Template Parsing Caveats](https://vuejs.org/guide/essentials/component-basics.html#in-dom-template-parsing-caveats)

package/skills/vue-debug-guides/reference/inheritattrs-false-for-wrapper-components.md

@@ -0,0 +1,230 @@
+# Use inheritAttrs: false for Wrapper Components
+
+## Rule
+
+When building wrapper components where attributes should be applied to an inner element instead of the root element, always set `inheritAttrs: false` and explicitly bind `$attrs` to the target element.
+
+## Why This Matters
+
+- By default, Vue applies all non-prop attributes to the root element
+- Wrapper components often have a non-semantic root (div wrapper, label wrapper)
+- Attributes like `id`, `aria-*`, `data-*`, and event listeners should target the functional element
+- Without `inheritAttrs: false`, accessibility and functionality can break
+
+## Bad Code
+
+```vue
+<!-- BaseInput.vue - WRONG: attrs go to wrapper div, not input -->
+<template>
+  <div class="input-wrapper">
+    <label>{{ label }}</label>
+    <input type="text" />
+  </div>
+</template>
+
+<script setup>
+defineProps(['label'])
+</script>
+
+<!-- Parent usage -->
+<BaseInput
+  id="email"
+  placeholder="Enter email"
+  aria-describedby="email-help"
+  @focus="handleFocus"
+/>
+
+<!--
+  RESULT: All attrs go to the wrapper div!
+  <div class="input-wrapper" id="email" placeholder="Enter email" ...>
+    <label>...</label>
+    <input type="text" />  <!-- No id, placeholder, or aria! -->
+  </div>
+-->
+```
+
+## Good Code
+
+```vue
+<!-- BaseInput.vue - CORRECT: attrs bound to input element -->
+<script setup>
+defineProps(['label'])
+
+defineOptions({
+  inheritAttrs: false
+})
+</script>
+
+<template>
+  <div class="input-wrapper">
+    <label>{{ label }}</label>
+    <input type="text" v-bind="$attrs" />
+  </div>
+</template>
+
+<!-- Parent usage -->
+<BaseInput
+  id="email"
+  placeholder="Enter email"
+  aria-describedby="email-help"
+  @focus="handleFocus"
+/>
+
+<!--
+  RESULT: Attrs correctly applied to input
+  <div class="input-wrapper">
+    <label>...</label>
+    <input type="text" id="email" placeholder="Enter email"
+           aria-describedby="email-help" />
+  </div>
+-->
+```
+
+## Setting inheritAttrs in Different Syntaxes
+
+### Script Setup (Vue 3.3+)
+
+```vue
+<script setup>
+defineOptions({
+  inheritAttrs: false
+})
+</script>
+```
+
+### Script Setup (Before Vue 3.3)
+
+```vue
+<script>
+export default {
+  inheritAttrs: false
+}
+</script>
+
+<script setup>
+// Your setup code here
+</script>
+```
+
+### Options API
+
+```vue
+<script>
+export default {
+  inheritAttrs: false,
+  // other options...
+}
+</script>
+```
+
+## Common Wrapper Component Patterns
+
+### Form Input Wrapper
+
+```vue
+<script setup>
+import { useAttrs, computed } from 'vue'
+
+defineProps({
+  label: String,
+  error: String
+})
+
+defineOptions({
+  inheritAttrs: false
+})
+
+const attrs = useAttrs()
+
+// Separate class/style for wrapper vs input
+const inputAttrs = computed(() => {
+  const { class: _, style: __, ...rest } = attrs
+  return rest
+})
+</script>
+
+<template>
+  <div class="form-field" :class="{ 'has-error': error }">
+    <label v-if="label">{{ label }}</label>
+    <input v-bind="inputAttrs" />
+    <span v-if="error" class="error">{{ error }}</span>
+  </div>
+</template>
+```
+
+### Button with Icon Wrapper
+
+```vue
+<script setup>
+defineProps({
+  icon: String,
+  iconPosition: {
+    type: String,
+    default: 'left'
+  }
+})
+
+defineOptions({
+  inheritAttrs: false
+})
+</script>
+
+<template>
+  <button class="icon-button" v-bind="$attrs">
+    <span v-if="icon && iconPosition === 'left'" class="icon">{{ icon }}</span>
+    <slot />
+    <span v-if="icon && iconPosition === 'right'" class="icon">{{ icon }}</span>
+  </button>
+</template>
+```
+
+### Link Wrapper Component
+
+```vue
+<script setup>
+defineProps({
+  to: String,
+  external: Boolean
+})
+
+defineOptions({
+  inheritAttrs: false
+})
+</script>
+
+<template>
+  <a
+    v-if="external"
+    :href="to"
+    target="_blank"
+    rel="noopener noreferrer"
+    v-bind="$attrs"
+  >
+    <slot />
+  </a>
+  <router-link v-else :to="to" v-bind="$attrs">
+    <slot />
+  </router-link>
+</template>
+```
+
+## When NOT to Use inheritAttrs: false
+
+- Simple components with a single semantic root element
+- Components where the root element should receive all attributes
+- Components that don't wrap other functional elements
+
+```vue
+<!-- SimpleCard.vue - No need for inheritAttrs: false -->
+<template>
+  <article class="card">
+    <slot />
+  </article>
+</template>
+<!-- Passing class, id, or data-* to the root article is fine -->
+```
+
+## References
+
+- [Fallthrough Attributes - Disabling Attribute Inheritance](https://vuejs.org/guide/components/attrs.html#disabling-attribute-inheritance)
+- [Build Advanced Components in Vue 3 using $attrs](https://www.thisdot.co/blog/build-advanced-components-in-vue-3-using-usdattrs)

package/skills/vue-debug-guides/reference/keepalive-router-nested-double-mount.md

@@ -0,0 +1,222 @@
+---
+title: KeepAlive with Nested Routes Double Mount Issue
+impact: HIGH
+impactDescription: Using KeepAlive with nested Vue Router routes can cause child components to mount twice
+type: gotcha
+tags: [vue3, keepalive, vue-router, nested-routes, double-mount, bug]
+---
+
+# KeepAlive with Nested Routes Double Mount Issue
+
+**Impact: HIGH** - When using `<KeepAlive>` with nested Vue Router routes, child route components may mount twice. This is a known issue that can cause duplicate API calls, broken state, and confusing behavior.
+
+## Task Checklist
+
+- [ ] Test nested routes thoroughly when using KeepAlive
+- [ ] Avoid mixing KeepAlive with deeply nested route structures
+- [ ] Use workarounds if double mount is observed
+- [ ] Consider alternative caching strategies for nested routes
+
+## The Problem
+
+```vue
+<!-- App.vue -->
+<template>
+  <router-view v-slot="{ Component }">
+    <KeepAlive>
+      <component :is="Component" />
+    </KeepAlive>
+  </router-view>
+</template>
+```
+
+```javascript
+// router.js
+const routes = [
+  {
+    path: '/parent',
+    component: Parent,
+    children: [
+      {
+        path: 'child',
+        component: Child  // This may mount TWICE!
+      }
+    ]
+  }
+]
+```
+
+**Symptoms:**
+- `onMounted` called twice in child component
+- Duplicate API requests
+- State initialization runs twice
+- Console logs appear doubled
+
+## Diagnosis
+
+Add logging to confirm the issue:
+
+```vue
+<!-- Child.vue -->
+<script setup>
+import { onMounted, onActivated } from 'vue'
+
+let mountCount = 0
+
+onMounted(() => {
+  mountCount++
+  console.log('Child mounted - count:', mountCount)
+  // If you see "count: 2", you have the double mount issue
+})
+
+onActivated(() => {
+  console.log('Child activated')
+})
+</script>
+```
+
+## Workarounds
+
+### Option 1: Use `useActivatedRoute` Pattern
+
+Don't use `useRoute()` directly with KeepAlive:
+
+```vue
+<script setup>
+import { ref, onActivated } from 'vue'
+import { useRoute } from 'vue-router'
+
+// Problem: useRoute() can cause issues with KeepAlive
+// const route = useRoute()
+
+// Solution: Get route info in onActivated
+const routeParams = ref({})
+
+onActivated(() => {
+  const route = useRoute()
+  routeParams.value = { ...route.params }
+})
+</script>
+```
+
+### Option 2: Avoid KeepAlive for Nested Route Parents
+
+Only cache leaf routes, not parent layouts:
+
+```vue
+<script setup>
+import { computed } from 'vue'
+import { useRoute } from 'vue-router'
+
+const route = useRoute()
+
+// Only cache specific leaf routes
+const cachedRoutes = computed(() => {
+  // Don't cache parent routes that have children
+  return ['UserProfile', 'UserSettings'] // Only leaf components
+})
+</script>
+
+<template>
+  <router-view v-slot="{ Component, route: currentRoute }">
+    <KeepAlive :include="cachedRoutes">
+      <component :is="Component" :key="currentRoute.fullPath" />
+    </KeepAlive>
+  </router-view>
+</template>
+```
+
+### Option 3: Guard Against Double Initialization
+
+Protect your component from double mount effects:
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const isInitialized = ref(false)
+
+onMounted(() => {
+  if (isInitialized.value) {
+    console.warn('Double mount detected, skipping initialization')
+    return
+  }
+  isInitialized.value = true
+
+  // Safe to initialize
+  fetchData()
+  setupEventListeners()
+})
+</script>
+```
+
+### Option 4: Use Route-Level Cache Control
+
+```vue
+<!-- App.vue -->
+<script setup>
+import { computed } from 'vue'
+import { useRoute } from 'vue-router'
+
+const route = useRoute()
+
+// Define which routes should be cached in route meta
+const shouldCache = computed(() => {
+  return route.meta.keepAlive !== false
+})
+</script>
+
+<template>
+  <router-view v-slot="{ Component }">
+    <KeepAlive v-if="shouldCache">
+      <component :is="Component" />
+    </KeepAlive>
+    <component v-else :is="Component" />
+  </router-view>
+</template>
+```
+
+```javascript
+// router.js
+const routes = [
+  {
+    path: '/parent',
+    component: Parent,
+    meta: { keepAlive: false }, // Don't cache parent routes
+    children: [
+      {
+        path: 'child',
+        component: Child,
+        meta: { keepAlive: true } // Cache leaf routes
+      }
+    ]
+  }
+]
+```
+
+### Option 5: Flatten Route Structure
+
+Avoid nesting if possible:
+
+```javascript
+// Instead of nested routes
+const routes = [
+  // Flat structure avoids the issue
+  { path: '/users', component: UserList },
+  { path: '/users/:id', component: UserDetail },
+  { path: '/users/:id/settings', component: UserSettings }
+]
+```
+
+## Key Points
+
+1. **Known Vue Router issue** - Double mount with KeepAlive + nested routes
+2. **Watch for symptoms** - Duplicate API calls, doubled logs
+3. **Avoid caching parent routes** - Only cache leaf components
+4. **Add initialization guards** - Protect against double execution
+5. **Test thoroughly** - This issue may not appear immediately
+
+## Reference
+- [Vue Router Issue #626: keep-alive in nested route mounted twice](https://github.com/vuejs/router/issues/626)
+- [GitHub: vue3-keep-alive-component workaround](https://github.com/emiyalee1005/vue3-keep-alive-component)
+- [Vue.js KeepAlive Documentation](https://vuejs.org/guide/built-ins/keep-alive.html)