@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/teleport-scoped-styles-limitation.md

@@ -0,0 +1,191 @@
+---
+title: Scoped Styles May Not Apply to Teleported Content
+impact: MEDIUM
+impactDescription: Scoped styles can fail to apply to teleported elements due to data attribute limitations
+type: gotcha
+tags: [vue3, teleport, scoped-styles, css]
+---
+
+# Scoped Styles May Not Apply to Teleported Content
+
+**Impact: MEDIUM** - When using scoped styles with Teleport, the styles may not apply correctly to teleported elements. This is a known limitation related to how Vue's scoped style attributes work with elements rendered outside the component's DOM tree.
+
+## Task Checklist
+
+- [ ] Test scoped styles on teleported content
+- [ ] Use `:deep()` selector or non-scoped styles for teleported content
+- [ ] Consider CSS modules as an alternative
+- [ ] Keep teleported content styles in a separate non-scoped style block
+
+**Problem - Scoped Styles Not Applied:**
+```vue
+<template>
+  <Teleport to="body">
+    <div class="modal">
+      <p class="modal-text">This text may not be styled!</p>
+    </div>
+  </Teleport>
+</template>
+
+<style scoped>
+/* These styles may NOT apply to teleported content */
+.modal {
+  background: white;
+  padding: 20px;
+}
+
+.modal-text {
+  color: blue;  /* May not work */
+}
+</style>
+```
+
+**Solution 1 - Use Non-Scoped Styles for Teleported Content:**
+```vue
+<template>
+  <Teleport to="body">
+    <div class="my-modal">
+      <p class="my-modal-text">This text will be styled</p>
+    </div>
+  </Teleport>
+</template>
+
+<style scoped>
+/* Component-specific styles */
+.button { color: blue; }
+</style>
+
+<style>
+/* Non-scoped styles for teleported content */
+/* Use specific class names to avoid conflicts */
+.my-modal {
+  background: white;
+  padding: 20px;
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+}
+
+.my-modal-text {
+  color: blue;
+}
+</style>
+```
+
+**Solution 2 - Use :deep() Selector:**
+```vue
+<template>
+  <Teleport to="body">
+    <div class="modal">
+      <p class="modal-text">Styled with :deep()</p>
+    </div>
+  </Teleport>
+</template>
+
+<style scoped>
+:deep(.modal) {
+  background: white;
+  padding: 20px;
+}
+
+:deep(.modal-text) {
+  color: blue;
+}
+</style>
+```
+
+**Solution 3 - CSS Modules:**
+```vue
+<template>
+  <Teleport to="body">
+    <div :class="$style.modal">
+      <p :class="$style.modalText">Styled with CSS modules</p>
+    </div>
+  </Teleport>
+</template>
+
+<style module>
+.modal {
+  background: white;
+  padding: 20px;
+}
+
+.modalText {
+  color: blue;
+}
+</style>
+```
+
+## Multi-Root Components with Teleport
+
+Using Teleport as one of multiple root nodes causes additional issues:
+
+```vue
+<template>
+  <!-- Multi-root component -->
+  <button @click="open = true">Open</button>
+  <Teleport to="body">
+    <div class="modal">Content</div>
+  </Teleport>
+</template>
+
+<!-- Warning: class/style attributes may not be inherited -->
+```
+
+Pass classes explicitly to avoid inheritance issues:
+
+```vue
+<template>
+  <button @click="open = true">Open</button>
+  <Teleport to="body">
+    <div :class="['modal', $attrs.class]" :style="$attrs.style">
+      Content
+    </div>
+  </Teleport>
+</template>
+```
+
+## Best Practice: Dedicated Modal Styles
+
+Create a dedicated stylesheet for modal/overlay components:
+
+```css
+/* modal-styles.css */
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.5);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.modal-content {
+  background: white;
+  border-radius: 8px;
+  padding: 24px;
+  max-width: 500px;
+  width: 90%;
+}
+```
+
+```vue
+<script setup>
+import './modal-styles.css'
+</script>
+
+<template>
+  <Teleport to="body">
+    <div v-if="open" class="modal-overlay">
+      <div class="modal-content">
+        <slot />
+      </div>
+    </div>
+  </Teleport>
+</template>
+```
+
+## Reference
+- [Vue.js SFC CSS Features - Scoped CSS](https://vuejs.org/api/sfc-css-features.html#scoped-css)
+- [GitHub Issue #2047 - Scoped styles and teleport](https://github.com/vuejs/core/issues/2047)

package/skills/vue-debug-guides/reference/teleport-ssr-hydration.md

@@ -0,0 +1,152 @@
+---
+title: Handle Teleport SSR Hydration Carefully
+impact: HIGH
+impactDescription: Teleported content causes hydration mismatches in SSR/SSG applications
+type: gotcha
+tags: [vue3, teleport, ssr, nuxt, hydration]
+---
+
+# Handle Teleport SSR Hydration Carefully
+
+**Impact: HIGH** - Teleports require special handling during SSR. The teleported content is not part of the server-rendered HTML string, causing hydration mismatches that can break the application or cause content to disappear.
+
+This is a critical issue for Nuxt, Quasar SSR, and custom Vue SSR setups.
+
+## Task Checklist
+
+- [ ] Wrap Teleport in `<ClientOnly>` component (Nuxt) for client-only rendering
+- [ ] Use conditional rendering based on mount state for non-Nuxt SSR
+- [ ] Use `data-allow-mismatch` attribute in Vue 3.5+ when intentional
+- [ ] Test SSR applications thoroughly for hydration issues
+
+**Problem - SSR Hydration Mismatch:**
+```vue
+<template>
+  <!-- Server renders nothing for teleported content -->
+  <!-- Client expects teleported content at #modals -->
+  <!-- = Hydration mismatch -->
+  <Teleport to="#modals">
+    <div v-if="showModal" class="modal">
+      Modal content
+    </div>
+  </Teleport>
+</template>
+```
+
+Common error messages:
+```
+[Vue warn]: Hydration children mismatch in <div>:
+server rendered element contains fewer child nodes than client vdom.
+```
+
+**Solution 1 - Nuxt ClientOnly:**
+```vue
+<template>
+  <button @click="showModal = true">Open Modal</button>
+
+  <!-- Only render on client, avoiding SSR -->
+  <ClientOnly>
+    <Teleport to="body">
+      <div v-if="showModal" class="modal">
+        Modal content
+      </div>
+    </Teleport>
+  </ClientOnly>
+</template>
+```
+
+**Solution 2 - Manual Client Detection:**
+```vue
+<template>
+  <button @click="showModal = true">Open Modal</button>
+
+  <!-- Only render after component mounts on client -->
+  <Teleport v-if="isMounted" to="body">
+    <div v-if="showModal" class="modal">
+      Modal content
+    </div>
+  </Teleport>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const showModal = ref(false)
+const isMounted = ref(false)
+
+onMounted(() => {
+  isMounted.value = true
+})
+</script>
+```
+
+**Solution 3 - Vue 3.5+ data-allow-mismatch:**
+```vue
+<template>
+  <!-- Suppress hydration warnings for intentional mismatches -->
+  <div data-allow-mismatch>
+    <Teleport to="body">
+      <div v-if="showModal" class="modal">
+        Modal content
+      </div>
+    </Teleport>
+  </div>
+</template>
+```
+
+## SSR with Multiple Teleports
+
+Multiple teleports to the same target can cause additional hydration issues:
+
+```vue
+<!-- Parent.vue -->
+<template>
+  <!-- First teleport -->
+  <Teleport to="#modals">
+    <NotificationBanner />
+  </Teleport>
+
+  <ChildComponent />
+</template>
+
+<!-- ChildComponent.vue -->
+<template>
+  <!-- Second teleport to same target - order matters! -->
+  <Teleport to="#modals">
+    <Modal />
+  </Teleport>
+</template>
+```
+
+For SSR, ensure consistent ordering or wrap each in `ClientOnly`.
+
+## Element Plus and UI Library SSR
+
+Many UI libraries use Teleport internally. Element Plus components that use Teleport include:
+- ElDialog
+- ElDrawer
+- ElTooltip
+- ElDropdown
+- ElSelect
+- ElDatePicker
+
+```vue
+<template>
+  <!-- These need special SSR handling -->
+  <ClientOnly>
+    <ElDialog v-model="visible">
+      Dialog content
+    </ElDialog>
+  </ClientOnly>
+</template>
+```
+
+## Known Vue Issues
+
+- Disabled teleports in fragments can cause hydration mismatches (Vue issue #6152)
+- Nested teleports may cause app to break on hydration (Vue issue #5242)
+
+## Reference
+- [Vue.js SSR - Teleports](https://vuejs.org/guide/scaling-up/ssr.html#teleports)
+- [Element Plus SSR Guide](https://element-plus.org/en-US/guide/ssr.html)
+- [Nuxt ClientOnly Component](https://nuxt.com/docs/api/components/client-only)

package/skills/vue-debug-guides/reference/teleport-target-must-exist.md

@@ -0,0 +1,113 @@
+---
+title: Teleport Target Must Exist Before Mount
+impact: HIGH
+impactDescription: Teleport will fail silently or throw errors if target element doesn't exist when component mounts
+type: gotcha
+tags: [vue3, teleport, modal, dom, lifecycle]
+---
+
+# Teleport Target Must Exist Before Mount
+
+**Impact: HIGH** - The teleport `to` target must already exist in the DOM when the `<Teleport>` component is mounted. If the target doesn't exist, Vue will throw an error and the teleported content won't render.
+
+This is a common source of bugs when using modals, tooltips, or other teleported UI elements, especially when targeting Vue-rendered elements.
+
+## Task Checklist
+
+- [ ] Ensure teleport target exists in the DOM before `<Teleport>` mounts
+- [ ] Place teleport containers (e.g., `#modals`, `#tooltips`) in `index.html` outside the Vue app
+- [ ] If targeting Vue-rendered elements, ensure they mount before the Teleport
+- [ ] Use Vue 3.5+ `defer` prop when target is rendered later in the same component tree
+
+**Incorrect:**
+```vue
+<template>
+  <!-- ERROR: Target doesn't exist yet when Teleport mounts -->
+  <Teleport to="#modal-container">
+    <div class="modal">Modal content</div>
+  </Teleport>
+
+  <!-- Target is defined after the Teleport -->
+  <div id="modal-container"></div>
+</template>
+```
+
+**Correct - Option 1: External container in index.html:**
+```html
+<!-- index.html -->
+<body>
+  <div id="app"></div>
+  <!-- Container exists before Vue app mounts -->
+  <div id="modals"></div>
+  <div id="tooltips"></div>
+</body>
+```
+
+```vue
+<template>
+  <!-- Safe: #modals exists before any Vue component mounts -->
+  <Teleport to="#modals">
+    <div v-if="showModal" class="modal">Modal content</div>
+  </Teleport>
+</template>
+```
+
+**Correct - Option 2: Teleport to body:**
+```vue
+<template>
+  <!-- Safe: body always exists -->
+  <Teleport to="body">
+    <div v-if="showModal" class="modal">Modal content</div>
+  </Teleport>
+</template>
+```
+
+**Correct - Option 3: Vue 3.5+ defer prop:**
+```vue
+<template>
+  <!-- Works in Vue 3.5+: defer resolves target after other parts mount -->
+  <Teleport defer to="#late-container">
+    <div class="modal">Modal content</div>
+  </Teleport>
+
+  <!-- Target rendered later in template -->
+  <div id="late-container"></div>
+</template>
+```
+
+## Defer Prop Limitations (Vue 3.5+)
+
+The `defer` prop only waits for elements rendered in the **same mount/update tick**:
+
+```vue
+<template>
+  <!-- ERROR: defer won't help if target mounts asynchronously -->
+  <Teleport defer to="#async-container">
+    <div>Content</div>
+  </Teleport>
+
+  <!-- If this component loads asynchronously, defer won't work -->
+  <Suspense>
+    <AsyncComponent />  <!-- Contains #async-container -->
+  </Suspense>
+</template>
+```
+
+## Common Patterns
+
+### Recommended: Centralized Teleport Containers
+```html
+<!-- index.html -->
+<body>
+  <div id="app"></div>
+
+  <!-- Teleport destinations outside Vue app -->
+  <div id="modals" aria-live="polite"></div>
+  <div id="notifications" aria-live="assertive"></div>
+  <div id="tooltips"></div>
+</body>
+```
+
+## Reference
+- [Vue.js Teleport - Using with Vue-rendered Targets](https://vuejs.org/guide/built-ins/teleport.html#using-with-vue-rendered-targets)
+- [Vue.js Teleport - Deferred Teleport](https://vuejs.org/guide/built-ins/teleport.html#deferred-teleport)

package/skills/vue-debug-guides/reference/template-expressions-restrictions.md

@@ -0,0 +1,114 @@
+---
+title: Template Expressions Must Be Single Expressions
+impact: MEDIUM
+impactDescription: Using statements instead of expressions in templates causes compilation errors
+type: capability
+tags: [vue3, template, expressions, interpolation, syntax]
+---
+
+# Template Expressions Must Be Single Expressions
+
+**Impact: MEDIUM** - Vue templates only support single JavaScript expressions, not statements. Using variable declarations, if statements, or multiple statements will cause template compilation errors.
+
+Template interpolation `{{ }}` and directive bindings evaluate JavaScript expressions that produce a value. Statements like `if`, `for`, variable declarations, or multi-line code blocks are not allowed.
+
+## Task Checklist
+
+- [ ] Use only single expressions in `{{ }}` interpolation
+- [ ] Use ternary operators instead of if/else statements
+- [ ] Move complex logic to computed properties or methods
+- [ ] Avoid variable declarations in templates
+- [ ] Use `v-if`/`v-else` directives for conditional rendering
+
+**Incorrect:**
+```vue
+<template>
+  <!-- ERROR: Variable declaration is a statement, not expression -->
+  <p>{{ var greeting = 'Hello' }}</p>
+  <p>{{ let x = 1 }}</p>
+  <p>{{ const name = 'Vue' }}</p>
+
+  <!-- ERROR: if statement not allowed -->
+  <p>{{ if (ok) { return message } }}</p>
+  <p>{{ if (user) return user.name }}</p>
+
+  <!-- ERROR: Multiple statements not allowed -->
+  <p>{{ count++; return count }}</p>
+  <p>{{ items.push(newItem); items.length }}</p>
+
+  <!-- ERROR: for/while loops not allowed -->
+  <p>{{ for (let i = 0; i < 5; i++) { } }}</p>
+</template>
+```
+
+**Correct:**
+```vue
+<template>
+  <!-- OK: Simple expressions -->
+  <p>{{ message }}</p>
+  <p>{{ count + 1 }}</p>
+  <p>{{ items.length }}</p>
+
+  <!-- OK: Ternary operators for conditionals -->
+  <p>{{ ok ? 'YES' : 'NO' }}</p>
+  <p>{{ user ? user.name : 'Guest' }}</p>
+  <p>{{ score >= 60 ? 'Pass' : 'Fail' }}</p>
+
+  <!-- OK: Method/function calls -->
+  <p>{{ formatDate(date) }}</p>
+  <p>{{ items.filter(i => i.active).length }}</p>
+
+  <!-- OK: Chained expressions -->
+  <p>{{ message.split('').reverse().join('') }}</p>
+
+  <!-- OK: Template literals -->
+  <p>{{ `Hello, ${name}!` }}</p>
+
+  <!-- OK: Object/array expressions -->
+  <p>{{ { name: 'Vue', version: 3 } }}</p>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+
+const ok = ref(true)
+const message = ref('Hello')
+const user = ref({ name: 'Alice' })
+const score = ref(85)
+
+// Move complex logic to computed properties
+const greeting = computed(() => {
+  if (user.value) {
+    return `Welcome back, ${user.value.name}!`
+  }
+  return 'Hello, Guest!'
+})
+
+// Or use methods for reusable logic
+function formatDate(date) {
+  return new Date(date).toLocaleDateString()
+}
+</script>
+```
+
+## Use Directives for Control Flow
+
+```vue
+<template>
+  <!-- Instead of if/else in expressions, use v-if/v-else -->
+  <p v-if="user">Welcome, {{ user.name }}!</p>
+  <p v-else>Please log in</p>
+
+  <!-- Instead of loops in expressions, use v-for -->
+  <ul>
+    <li v-for="item in items" :key="item.id">{{ item.name }}</li>
+  </ul>
+
+  <!-- Conditional display without removing from DOM -->
+  <p v-show="isVisible">This toggles visibility</p>
+</template>
+```
+
+## Reference
+- [Vue.js Template Syntax - Using JavaScript Expressions](https://vuejs.org/guide/essentials/template-syntax.html#using-javascript-expressions)
+- [Vue.js Conditional Rendering](https://vuejs.org/guide/essentials/conditional.html)