@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/sfc-scoped-css-dynamic-content.md

@@ -0,0 +1,193 @@
+---
+title: Scoped CSS Does Not Apply to Dynamically Added Content
+impact: HIGH
+impactDescription: Programmatically inserted DOM elements won't receive scoped style data attributes, causing styles to fail silently
+type: gotcha
+tags: [vue3, sfc, scoped-css, dynamic-content, v-html]
+---
+
+# Scoped CSS Does Not Apply to Dynamically Added Content
+
+**Impact: HIGH** - Vue's scoped CSS works by adding data attributes to elements at compile time. Content added dynamically at runtime (via `v-html`, JavaScript DOM manipulation, or third-party libraries) won't have these attributes, so scoped styles won't apply.
+
+## Task Checklist
+
+- [ ] For `v-html` content, use `:deep()` selectors or unscoped styles
+- [ ] Avoid programmatic DOM manipulation; prefer Vue's reactive template system
+- [ ] When DOM manipulation is unavoidable, use global styles with unique class prefixes
+- [ ] Consider CSS modules for content that mixes static and dynamic elements
+
+**Problematic Code:**
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const htmlContent = ref('<p class="dynamic">This is dynamic content</p>')
+</script>
+
+<template>
+  <div class="container">
+    <div v-html="htmlContent"></div>
+  </div>
+</template>
+
+<style scoped>
+/* BAD: Won't apply to the dynamic <p> element! */
+.dynamic {
+  color: red;
+  font-weight: bold;
+}
+</style>
+```
+
+**Correct Code:**
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const htmlContent = ref('<p class="dynamic">This is dynamic content</p>')
+</script>
+
+<template>
+  <div class="container">
+    <div v-html="htmlContent"></div>
+  </div>
+</template>
+
+<style scoped>
+/* GOOD: Use :deep() for v-html content */
+.container :deep(.dynamic) {
+  color: red;
+  font-weight: bold;
+}
+</style>
+```
+
+## Why This Happens
+
+Vue scoped CSS adds a unique data attribute (e.g., `data-v-7ba5bd90`) to:
+1. All elements in the component's template (at compile time)
+2. All CSS selectors
+
+```html
+<!-- What Vue generates at compile time -->
+<div class="container" data-v-7ba5bd90>
+  <div data-v-7ba5bd90>
+    <!-- v-html content is inserted at runtime WITHOUT the attribute -->
+    <p class="dynamic">This is dynamic content</p>
+  </div>
+</div>
+```
+
+```css
+/* Generated scoped CSS */
+.dynamic[data-v-7ba5bd90] { color: red; }
+/* ^ Won't match because the dynamic <p> doesn't have data-v-7ba5bd90 */
+```
+
+## Alternative: Global Styles with Unique Prefix
+
+```vue
+<script setup>
+import { ref } from 'vue'
+const htmlContent = ref('<p class="my-component-dynamic">Dynamic text</p>')
+</script>
+
+<template>
+  <div class="my-component">
+    <div v-html="htmlContent"></div>
+  </div>
+</template>
+
+<!-- Use unscoped styles with unique prefixes -->
+<style>
+.my-component .my-component-dynamic {
+  color: red;
+}
+</style>
+```
+
+## Programmatic DOM Manipulation
+
+When using third-party libraries that manipulate the DOM:
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const editorRef = ref(null)
+
+onMounted(() => {
+  // Third-party editor that injects its own DOM elements
+  initRichEditor(editorRef.value)
+})
+</script>
+
+<template>
+  <div class="editor-wrapper">
+    <div ref="editorRef"></div>
+  </div>
+</template>
+
+<style scoped>
+/* BAD: Won't reach injected editor elements */
+.editor-toolbar { ... }
+.editor-content { ... }
+</style>
+
+<style>
+/* GOOD: Global styles scoped by parent class */
+.editor-wrapper .editor-toolbar {
+  background: #f5f5f5;
+}
+.editor-wrapper .editor-content {
+  padding: 1rem;
+}
+</style>
+```
+
+## Best Practice: Prefer Reactive Templates
+
+Instead of dynamic HTML, use Vue's reactive system when possible:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+// BAD: Dynamic HTML that needs special style handling
+const badHtml = ref('<span class="highlight">text</span>')
+
+// GOOD: Reactive data that templates handle
+const items = ref([
+  { text: 'Item 1', isHighlighted: true },
+  { text: 'Item 2', isHighlighted: false }
+])
+</script>
+
+<template>
+  <!-- BAD -->
+  <div v-html="badHtml"></div>
+
+  <!-- GOOD: Scoped styles work normally -->
+  <ul>
+    <li
+      v-for="item in items"
+      :key="item.text"
+      :class="{ highlight: item.isHighlighted }"
+    >
+      {{ item.text }}
+    </li>
+  </ul>
+</template>
+
+<style scoped>
+/* Works perfectly with reactive template */
+.highlight {
+  background: yellow;
+}
+</style>
+```
+
+## Reference
+- [Vue.js Scoped CSS](https://vuejs.org/api/sfc-css-features.html#scoped-css)
+- [GitHub Issue: Scoped CSS not applied for programmatically added elements](https://github.com/vuejs/vue/issues/7649)

package/skills/vue-debug-guides/reference/sfc-scoped-css-slot-content.md

@@ -0,0 +1,242 @@
+---
+title: Scoped CSS Cannot Style Slot Content Directly
+impact: HIGH
+impactDescription: Slot content receives the parent component's scope, not the child's, causing styles to fail unexpectedly
+type: gotcha
+tags: [vue3, sfc, scoped-css, slots, deep-selector]
+---
+
+# Scoped CSS Cannot Style Slot Content Directly
+
+**Impact: HIGH** - When a parent passes content through a slot, that content receives the parent component's scoped style attributes, not the child component's. This means the child component cannot style slot content with regular scoped CSS.
+
+## Task Checklist
+
+- [ ] Use `:deep()` selector in the wrapper component to style slot content
+- [ ] Alternatively, use `:slotted()` pseudo-selector to target slotted elements
+- [ ] For complex slot styling, consider using CSS modules or unscoped styles
+- [ ] Document expected slot content structure when styling assumptions exist
+
+**Problematic Code:**
+```vue
+<!-- Card.vue (child component) -->
+<template>
+  <div class="card">
+    <div class="card-body">
+      <slot />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.card-body {
+  padding: 1rem;
+}
+
+/* BAD: Won't apply to slot content! */
+.card-body h2 {
+  color: #333;
+  margin-bottom: 0.5rem;
+}
+
+.card-body p {
+  color: #666;
+}
+</style>
+```
+
+```vue
+<!-- Parent.vue -->
+<template>
+  <Card>
+    <!-- This h2 and p won't be styled by Card's scoped CSS -->
+    <h2>Card Title</h2>
+    <p>Card description text.</p>
+  </Card>
+</template>
+```
+
+**Correct Code:**
+```vue
+<!-- Card.vue - Using :slotted() -->
+<template>
+  <div class="card">
+    <div class="card-body">
+      <slot />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.card-body {
+  padding: 1rem;
+}
+
+/* GOOD: :slotted() targets slot content */
+:slotted(h2) {
+  color: #333;
+  margin-bottom: 0.5rem;
+}
+
+:slotted(p) {
+  color: #666;
+}
+</style>
+```
+
+## Using :deep() Alternative
+
+```vue
+<!-- Card.vue - Using :deep() -->
+<style scoped>
+.card-body {
+  padding: 1rem;
+}
+
+/* :deep() also works for slot content */
+.card-body :deep(h2) {
+  color: #333;
+}
+
+.card-body :deep(p) {
+  color: #666;
+}
+</style>
+```
+
+## Why This Happens
+
+Slot content is compiled in the parent component's scope:
+
+```vue
+<!-- Parent template compiles to: -->
+<Card>
+  <h2 data-v-parent123>Card Title</h2>
+  <p data-v-parent123>Card description</p>
+</Card>
+
+<!-- Card template compiles to: -->
+<div class="card" data-v-card456>
+  <div class="card-body" data-v-card456>
+    <slot />  <!-- Content inserted WITHOUT data-v-card456 -->
+  </div>
+</div>
+```
+
+The `<h2>` has `data-v-parent123`, but Card's scoped CSS expects `data-v-card456`.
+
+## :slotted() vs :deep() for Slots
+
+Both work, but have subtle differences:
+
+```vue
+<style scoped>
+/* :slotted() - Specifically for slot content */
+/* Only targets direct slotted elements */
+:slotted(h2) {
+  color: blue;
+}
+
+/* :deep() - More general deep selector */
+/* Can target nested elements within slot content */
+.card-body :deep(h2) {
+  color: blue;
+}
+
+/* For nested elements in slot content, must use :deep() */
+:slotted(.wrapper h2) { }  /* Won't work for nested h2 */
+.card-body :deep(.wrapper h2) { }  /* Works for nested */
+</style>
+```
+
+## Combining with Named Slots
+
+```vue
+<template>
+  <div class="card">
+    <header class="card-header">
+      <slot name="header" />
+    </header>
+    <div class="card-body">
+      <slot />
+    </div>
+    <footer class="card-footer">
+      <slot name="footer" />
+    </footer>
+  </div>
+</template>
+
+<style scoped>
+/* Style specific slot content */
+.card-header :slotted(h1),
+.card-header :slotted(h2) {
+  margin: 0;
+  font-size: 1.25rem;
+}
+
+.card-body :slotted(p) {
+  margin-bottom: 1rem;
+}
+
+.card-footer :slotted(button) {
+  margin-right: 0.5rem;
+}
+</style>
+```
+
+## Performance Tip: Use Classes
+
+Element selectors with `:slotted()` can be slower:
+
+```vue
+<style scoped>
+/* SLOWER: Element selector */
+:slotted(p) {
+  color: gray;
+}
+
+/* FASTER: Class selector */
+:slotted(.card-text) {
+  color: gray;
+}
+</style>
+```
+
+## When to Use Unscoped Styles
+
+For complex slot styling, unscoped styles may be cleaner:
+
+```vue
+<template>
+  <article class="article-card">
+    <slot />
+  </article>
+</template>
+
+<style>
+/* Unscoped with unique prefix for complex content styling */
+.article-card h1,
+.article-card h2,
+.article-card h3 {
+  font-family: Georgia, serif;
+  line-height: 1.2;
+}
+
+.article-card p {
+  line-height: 1.6;
+}
+
+.article-card img {
+  max-width: 100%;
+}
+
+.article-card blockquote {
+  border-left: 3px solid #ccc;
+  padding-left: 1rem;
+}
+</style>
+```
+
+## Reference
+- [Vue.js Scoped CSS - Slotted Selectors](https://vuejs.org/api/sfc-css-features.html#slotted-selectors)
+- [Vue.js Deep Selectors](https://vuejs.org/api/sfc-css-features.html#deep-selectors)

package/skills/vue-debug-guides/reference/sfc-script-setup-reactivity.md

@@ -0,0 +1,195 @@
+---
+title: Variables in Script Setup Are Not Reactive by Default
+impact: HIGH
+impactDescription: Forgetting to wrap variables with ref() or reactive() causes silent reactivity failures in script setup
+type: gotcha
+tags: [vue3, sfc, script-setup, reactivity, ref, composition-api]
+---
+
+# Variables in Script Setup Are Not Reactive by Default
+
+**Impact: HIGH** - Unlike Options API's `data()` which automatically makes properties reactive, variables declared in `<script setup>` are plain JavaScript values. You must explicitly use `ref()` or `reactive()` to make them reactive. Forgetting this causes the UI to not update when values change.
+
+## Task Checklist
+
+- [ ] Always wrap primitive values (strings, numbers, booleans) with `ref()`
+- [ ] Use `reactive()` for objects when you don't need to reassign the whole object
+- [ ] Remember to access `.value` on refs in script (not needed in templates)
+- [ ] Use `computed()` from Vue, not a plain function, for derived reactive state
+
+**Problematic Code:**
+```vue
+<script setup>
+// BAD: These are NOT reactive!
+let count = 0
+let message = 'Hello'
+let user = { name: 'John', age: 30 }
+
+function increment() {
+  count++  // This change won't update the UI!
+}
+
+function updateMessage() {
+  message = 'World'  // UI won't reflect this change!
+}
+</script>
+
+<template>
+  <div>
+    <!-- Will always show initial values -->
+    <p>Count: {{ count }}</p>
+    <p>Message: {{ message }}</p>
+    <button @click="increment">Increment</button>
+    <button @click="updateMessage">Update</button>
+  </div>
+</template>
+```
+
+**Correct Code:**
+```vue
+<script setup>
+import { ref, reactive, computed } from 'vue'
+
+// GOOD: Primitives wrapped with ref()
+const count = ref(0)
+const message = ref('Hello')
+
+// GOOD: Object with reactive()
+const user = reactive({ name: 'John', age: 30 })
+
+// GOOD: Computed for derived state
+const doubleCount = computed(() => count.value * 2)
+
+function increment() {
+  count.value++  // Use .value for refs in script
+}
+
+function updateMessage() {
+  message.value = 'World'
+}
+
+function updateUser() {
+  user.name = 'Jane'  // No .value needed for reactive objects
+}
+</script>
+
+<template>
+  <div>
+    <!-- No .value needed in templates - Vue unwraps automatically -->
+    <p>Count: {{ count }}</p>
+    <p>Double: {{ doubleCount }}</p>
+    <p>Message: {{ message }}</p>
+    <p>User: {{ user.name }}</p>
+    <button @click="increment">Increment</button>
+  </div>
+</template>
+```
+
+## Common Mistake: Plain Computed
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const items = ref([1, 2, 3, 4, 5])
+
+// BAD: Plain function, not reactive - won't update when items change
+const total = items.value.reduce((sum, n) => sum + n, 0)
+
+// BAD: Arrow function - recalculates but Vue doesn't track it
+const getTotal = () => items.value.reduce((sum, n) => sum + n, 0)
+</script>
+
+<template>
+  <!-- total never updates, getTotal works but isn't optimal -->
+  <p>Total: {{ total }}</p>
+</template>
+```
+
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+
+const items = ref([1, 2, 3, 4, 5])
+
+// GOOD: computed() tracks dependencies and caches result
+const total = computed(() => items.value.reduce((sum, n) => sum + n, 0))
+</script>
+
+<template>
+  <p>Total: {{ total }}</p>  <!-- Updates when items change -->
+</template>
+```
+
+## When to Use ref() vs reactive()
+
+```vue
+<script setup>
+import { ref, reactive } from 'vue'
+
+// Use ref() for:
+// - Primitives (string, number, boolean)
+// - Values you might reassign entirely
+const count = ref(0)
+const isLoading = ref(false)
+const selectedId = ref<number | null>(null)
+
+// Use reactive() for:
+// - Objects/arrays you'll mutate but not reassign
+// - When you want to avoid .value
+const form = reactive({
+  name: '',
+  email: '',
+  errors: []
+})
+
+// Gotcha: Can't reassign reactive objects
+const user = reactive({ name: 'John' })
+// user = { name: 'Jane' }  // This breaks reactivity!
+// user.name = 'Jane'       // This works
+
+// Use ref() if you need to reassign objects
+const userData = ref({ name: 'John' })
+userData.value = { name: 'Jane' }  // This works
+</script>
+```
+
+## Template Automatic Unwrapping
+
+Vue automatically unwraps refs in templates:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const count = ref(0)
+const user = ref({ name: 'John' })
+</script>
+
+<template>
+  <!-- All of these work - no .value needed -->
+  <p>{{ count }}</p>
+  <p>{{ user.name }}</p>
+  <input v-model="count" type="number">
+  <button @click="count++">Increment</button>
+</template>
+```
+
+But in event handlers written inline, you might still need `.value`:
+
+```vue
+<template>
+  <!-- This works (Vue handles it) -->
+  <button @click="count++">+1</button>
+
+  <!-- For complex logic, .value may be needed -->
+  <button @click="() => { count.value = Math.max(0, count.value - 1) }">
+    -1 (min 0)
+  </button>
+</template>
+```
+
+## Reference
+- [Vue.js Reactivity Fundamentals](https://vuejs.org/guide/essentials/reactivity-fundamentals.html)
+- [Vue.js ref()](https://vuejs.org/api/reactivity-core.html#ref)
+- [Vue.js reactive()](https://vuejs.org/api/reactivity-core.html#reactive)