@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/slot-forwarding-to-child-components.md

@@ -0,0 +1,143 @@
+---
+title: Forward Slots to Child Components Correctly
+impact: MEDIUM
+impactDescription: Wrapper components that don't forward slots break slot functionality for consumers
+type: best-practice
+tags: [vue3, slots, component-composition, wrapper-components, slot-forwarding]
+---
+
+# Forward Slots to Child Components Correctly
+
+**Impact: MEDIUM** - When creating wrapper components that enhance or extend other components, you need to forward slots from the parent to the wrapped child. Without proper slot forwarding, consumers of your wrapper cannot customize the inner component's slots.
+
+## Task Checklist
+
+- [ ] Use `v-for` with `$slots` to iterate over all provided slots
+- [ ] Use dynamic slot names with `v-slot:[slotName]`
+- [ ] Pass slot props through with `v-bind="slotProps"`
+- [ ] Handle cases where slotProps might be undefined
+
+**Basic Slot Forwarding Pattern:**
+```vue
+<!-- EnhancedButton.vue - Wrapper component -->
+<script setup>
+import BaseButton from './BaseButton.vue'
+</script>
+
+<template>
+  <div class="button-wrapper">
+    <BaseButton v-bind="$attrs">
+      <!-- Forward all slots to BaseButton -->
+      <template v-for="(_, slotName) in $slots" v-slot:[slotName]="slotProps">
+        <slot :name="slotName" v-bind="slotProps ?? {}" />
+      </template>
+    </BaseButton>
+  </div>
+</template>
+```
+
+**Usage:**
+```vue
+<script setup>
+import EnhancedButton from './EnhancedButton.vue'
+</script>
+
+<template>
+  <!-- Slots pass through to BaseButton -->
+  <EnhancedButton>
+    <template #icon>
+      <IconCheck />
+    </template>
+    <template #default>
+      Click me
+    </template>
+  </EnhancedButton>
+</template>
+```
+
+## Handling Scoped Slots
+
+When the child component provides slot props, you must forward them:
+
+```vue
+<!-- DataTableWrapper.vue -->
+<script setup>
+import DataTable from './DataTable.vue'
+
+const props = defineProps(['data'])
+</script>
+
+<template>
+  <div class="table-container">
+    <DataTable :items="data">
+      <!-- Forward slots including scoped slot props -->
+      <template v-for="(_, slotName) in $slots" v-slot:[slotName]="slotProps">
+        <slot :name="slotName" v-bind="slotProps ?? {}" />
+      </template>
+    </DataTable>
+  </div>
+</template>
+```
+
+```vue
+<!-- Consumer can use scoped slot props -->
+<DataTableWrapper :data="users">
+  <template #row="{ item, index }">
+    <tr>
+      <td>{{ index + 1 }}</td>
+      <td>{{ item.name }}</td>
+    </tr>
+  </template>
+</DataTableWrapper>
+```
+
+## Alternative: Handling Undefined slotProps
+
+Some scenarios require checking if slotProps exists:
+
+```vue
+<template>
+  <ChildComponent>
+    <template v-for="(_, name) in $slots" v-slot:[name]="slotProps">
+      <!-- Handle both scoped and non-scoped slots -->
+      <slot v-if="slotProps" :name="name" v-bind="slotProps" />
+      <slot v-else :name="name" />
+    </template>
+  </ChildComponent>
+</template>
+```
+
+## Forwarding Specific Slots Only
+
+If you only want to forward certain slots:
+
+```vue
+<template>
+  <ChildComponent>
+    <!-- Only forward header and footer slots -->
+    <template v-if="$slots.header" #header="slotProps">
+      <slot name="header" v-bind="slotProps ?? {}" />
+    </template>
+
+    <template v-if="$slots.footer" #footer="slotProps">
+      <slot name="footer" v-bind="slotProps ?? {}" />
+    </template>
+
+    <!-- Default slot handled differently -->
+    <slot />
+  </ChildComponent>
+</template>
+```
+
+## Common Mistakes
+
+| Mistake | Problem | Solution |
+|---------|---------|----------|
+| Not using `v-bind="slotProps"` | Scoped slot data lost | Always bind slotProps |
+| Forgetting `?? {}` or null check | Error when slotProps undefined | Add nullish coalescing |
+| Static slot names in loop | Only forwards one slot | Use `v-slot:[slotName]` dynamic syntax |
+| Missing `v-for` key warning | Vue warning (non-critical) | Keys not needed for slot functions |
+
+## Reference
+- [Vue Land FAQ - Forwarding Slots](https://vue-land.github.io/faq/forwarding-slots)
+- [Vue.js Slots - Scoped Slots](https://vuejs.org/guide/components/slots.html#scoped-slots)

package/skills/vue-debug-guides/reference/slot-implicit-default-content.md

@@ -0,0 +1,155 @@
+---
+title: Non-Template Content Is Implicitly Default Slot Content
+impact: LOW
+impactDescription: Unexpected content placement when mixing named slots with loose content
+type: gotcha
+tags: [vue3, slots, named-slots, default-slot, implicit-behavior]
+---
+
+# Non-Template Content Is Implicitly Default Slot Content
+
+**Impact: LOW** - When using named slots, any top-level content not wrapped in a `<template>` tag is automatically treated as default slot content. This implicit behavior can cause confusion about where content will render.
+
+## Task Checklist
+
+- [ ] Understand that loose content goes to the default slot
+- [ ] Use explicit `<template #default>` when clarity matters
+- [ ] Keep slot content organization intentional
+
+**The Implicit Behavior:**
+```vue
+<script setup>
+import BaseLayout from './BaseLayout.vue'
+</script>
+
+<template>
+  <BaseLayout>
+    <template #header>
+      <h1>Page Title</h1>
+    </template>
+
+    <!-- These are IMPLICITLY in the default slot -->
+    <p>First paragraph of main content.</p>
+    <p>Second paragraph of main content.</p>
+
+    <template #footer>
+      <p>Footer content</p>
+    </template>
+  </BaseLayout>
+</template>
+```
+
+The two `<p>` elements are automatically placed in `<slot>` (the default slot) in the child component.
+
+**Equivalent Explicit Version:**
+```vue
+<template>
+  <BaseLayout>
+    <template #header>
+      <h1>Page Title</h1>
+    </template>
+
+    <!-- Explicit default slot -->
+    <template #default>
+      <p>First paragraph of main content.</p>
+      <p>Second paragraph of main content.</p>
+    </template>
+
+    <template #footer>
+      <p>Footer content</p>
+    </template>
+  </BaseLayout>
+</template>
+```
+
+## When Implicit Behavior Causes Confusion
+
+**Scattered Content:**
+```vue
+<template>
+  <BaseLayout>
+    <template #header>
+      <h1>Title</h1>
+    </template>
+
+    <p>Content A</p>  <!-- Goes to default slot -->
+
+    <template #sidebar>
+      <nav>Navigation</nav>
+    </template>
+
+    <p>Content B</p>  <!-- Also goes to default slot! -->
+
+    <template #footer>
+      <p>Footer</p>
+    </template>
+
+    <p>Content C</p>  <!-- Also goes to default slot! -->
+  </BaseLayout>
+</template>
+```
+
+All three `<p>` elements end up in the default slot together, which may not be the intended order or grouping.
+
+**Clearer with Explicit Default:**
+```vue
+<template>
+  <BaseLayout>
+    <template #header>
+      <h1>Title</h1>
+    </template>
+
+    <template #default>
+      <p>Content A</p>
+      <p>Content B</p>
+      <p>Content C</p>
+    </template>
+
+    <template #sidebar>
+      <nav>Navigation</nav>
+    </template>
+
+    <template #footer>
+      <p>Footer</p>
+    </template>
+  </BaseLayout>
+</template>
+```
+
+## Best Practices
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Only default slot used | Implicit is fine |
+| Mixed named + default slots | Consider explicit `#default` |
+| Complex layouts | Always use explicit templates |
+| Team/shared codebase | Prefer explicit for clarity |
+
+## The Child Component
+
+```vue
+<!-- BaseLayout.vue -->
+<template>
+  <div class="layout">
+    <header>
+      <slot name="header"></slot>
+    </header>
+
+    <aside>
+      <slot name="sidebar"></slot>
+    </aside>
+
+    <main>
+      <!-- All implicit content ends up here -->
+      <slot></slot>
+    </main>
+
+    <footer>
+      <slot name="footer"></slot>
+    </footer>
+  </div>
+</template>
+```
+
+## Reference
+- [Vue.js Slots - Named Slots](https://vuejs.org/guide/components/slots.html#named-slots)

package/skills/vue-debug-guides/reference/slot-name-reserved-prop.md

@@ -0,0 +1,109 @@
+---
+title: Slot Name is Reserved and Not Included in Slot Props
+impact: LOW
+impactDescription: Expecting 'name' in scoped slot props when it's reserved causes confusion
+type: gotcha
+tags: [vue3, slots, scoped-slots, reserved-props, naming]
+---
+
+# Slot Name is Reserved and Not Included in Slot Props
+
+**Impact: LOW** - When using scoped slots, the `name` attribute on the `<slot>` element is reserved for identifying the slot. It is not passed as part of the slot props to the parent component.
+
+## Task Checklist
+
+- [ ] Don't expect `name` in slot props - it's reserved
+- [ ] Use a different prop name if you need to pass a name value
+- [ ] Remember only explicitly bound attributes become slot props
+
+**Incorrect Expectation:**
+```vue
+<!-- ChildComponent.vue -->
+<template>
+  <div>
+    <slot name="header" title="Welcome"></slot>
+  </div>
+</template>
+```
+
+```vue
+<!-- ParentComponent.vue -->
+<ChildComponent>
+  <template #header="props">
+    <!-- props = { title: "Welcome" } -->
+    <!-- 'name' is NOT included! -->
+    {{ props.name }}  <!-- undefined -->
+    {{ props.title }} <!-- "Welcome" -->
+  </template>
+</ChildComponent>
+```
+
+**If You Need to Pass a "Name" Value:**
+```vue
+<!-- ChildComponent.vue -->
+<template>
+  <div>
+    <!-- Use a different prop name like 'slotName' or 'label' -->
+    <slot name="header" :label="slotLabel" :title="title"></slot>
+  </div>
+</template>
+
+<script setup>
+const slotLabel = 'header'
+const title = 'Welcome'
+</script>
+```
+
+```vue
+<!-- ParentComponent.vue -->
+<ChildComponent>
+  <template #header="{ label, title }">
+    <h2>{{ title }}</h2>
+    <span>Section: {{ label }}</span>
+  </template>
+</ChildComponent>
+```
+
+## What Gets Passed as Slot Props
+
+| Attribute on `<slot>` | Passed to Parent? |
+|----------------------|-------------------|
+| `name` | No (reserved for slot identification) |
+| `:text="message"` | Yes, as `text` |
+| `:count="5"` | Yes, as `count` |
+| `v-bind="object"` | Yes, spreads object properties |
+| `class="..."` | No (not bound with `:`) |
+
+## Multiple Named Slots Example
+
+```vue
+<!-- TabPanel.vue -->
+<template>
+  <div class="tabs">
+    <slot name="tab1" :active="activeTab === 1" :label="'First Tab'"></slot>
+    <slot name="tab2" :active="activeTab === 2" :label="'Second Tab'"></slot>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const activeTab = ref(1)
+</script>
+```
+
+```vue
+<!-- Usage -->
+<TabPanel>
+  <template #tab1="{ active, label }">
+    <!-- 'name' not available, but 'label' is -->
+    <button :class="{ active }">{{ label }}</button>
+  </template>
+
+  <template #tab2="{ active, label }">
+    <button :class="{ active }">{{ label }}</button>
+  </template>
+</TabPanel>
+```
+
+## Reference
+- [Vue.js Slots - Scoped Slots](https://vuejs.org/guide/components/slots.html#scoped-slots)

package/skills/vue-debug-guides/reference/slot-named-scoped-explicit-default.md

@@ -0,0 +1,95 @@
+---
+title: Use Explicit Default Template When Mixing Named and Scoped Slots
+impact: HIGH
+impactDescription: Mixing v-slot on component with named slots inside causes ambiguous scope and compilation errors
+type: gotcha
+tags: [vue3, slots, scoped-slots, named-slots, compilation-error]
+---
+
+# Use Explicit Default Template When Mixing Named and Scoped Slots
+
+**Impact: HIGH** - When a component uses both the default scoped slot and named slots, you must use an explicit `<template #default>` for the default slot. Using `v-slot` directly on the component while having nested named slot templates causes scope ambiguity and compilation errors.
+
+## Task Checklist
+
+- [ ] When using named slots alongside a default slot with props, always use explicit `<template #default>`
+- [ ] Never mix `v-slot` on the component element with `<template #name>` inside
+- [ ] Keep slot scope clear and unambiguous
+
+**Incorrect:**
+```vue
+<script setup>
+import MyComponent from './MyComponent.vue'
+</script>
+
+<template>
+  <!-- BAD: v-slot on component + named template inside causes ambiguity -->
+  <MyComponent v-slot="{ message }">
+    <p>{{ message }}</p>
+
+    <template #footer>
+      <!-- Ambiguous: Is 'message' available here? Vue can't determine -->
+      <p>Footer: {{ message }}</p>
+    </template>
+  </MyComponent>
+</template>
+```
+
+This causes a compilation error because Vue cannot determine:
+1. Whether `message` from the default slot should be available in the footer slot
+2. Which scope applies to the non-template content
+
+**Correct:**
+```vue
+<script setup>
+import MyComponent from './MyComponent.vue'
+</script>
+
+<template>
+  <!-- GOOD: Explicit template for each slot with clear scope -->
+  <MyComponent>
+    <template #default="{ message }">
+      <p>{{ message }}</p>
+    </template>
+
+    <template #footer>
+      <!-- Clear: footer slot has its own scope, no access to default's 'message' -->
+      <p>Footer content here</p>
+    </template>
+  </MyComponent>
+</template>
+```
+
+**Correct - When Footer Also Has Props:**
+```vue
+<script setup>
+import MyComponent from './MyComponent.vue'
+</script>
+
+<template>
+  <MyComponent>
+    <template #default="{ message }">
+      <p>{{ message }}</p>
+    </template>
+
+    <template #footer="{ year }">
+      <!-- Each slot receives its own props -->
+      <p>Copyright {{ year }}</p>
+    </template>
+  </MyComponent>
+</template>
+```
+
+## The Rule
+
+When you have **any** named slots (`<template #name>`), always use explicit templates for **all** slots, including the default slot. This makes scope boundaries clear and prevents compilation errors.
+
+| Pattern | Valid? | Notes |
+|---------|--------|-------|
+| `v-slot` on component only | Yes | Single default scoped slot |
+| Named templates only | Yes | Multiple named slots |
+| `v-slot` on component + named templates | No | Ambiguous scope |
+| All explicit templates | Yes | Clear scope for each slot |
+
+## Reference
+- [Vue.js Slots - Named Scoped Slots](https://vuejs.org/guide/components/slots.html#named-scoped-slots)

package/skills/vue-debug-guides/reference/slot-render-scope-parent-only.md

@@ -0,0 +1,135 @@
+---
+title: Slot Content Only Has Access to Parent Component Scope
+impact: HIGH
+impactDescription: Attempting to access child component data in slot content results in undefined values or errors
+type: gotcha
+tags: [vue3, slots, scope, reactivity, common-mistake]
+---
+
+# Slot Content Only Has Access to Parent Component Scope
+
+**Impact: HIGH** - Slot content is compiled in the parent component's scope and cannot access data defined in the child component. This follows JavaScript's lexical scoping rules and is a common source of confusion.
+
+When you provide content for a slot, that content is defined in your parent template and can only access data available in the parent component. The child component's internal state is not accessible unless explicitly passed via scoped slots.
+
+## Task Checklist
+
+- [ ] Remember that slot content is compiled in parent scope
+- [ ] Never try to access child component data directly in slot content
+- [ ] Use scoped slots when child data needs to be exposed to parent
+- [ ] Check that all template expressions reference data available in the current component
+
+**Incorrect:**
+```vue
+<!-- Parent.vue -->
+<script setup>
+import SubmitButton from './SubmitButton.vue'
+</script>
+
+<template>
+  <!-- BAD: Trying to access child's buttonText - this will be undefined -->
+  <SubmitButton>{{ buttonText }}</SubmitButton>
+
+  <!-- BAD: Trying to access child's isLoading state -->
+  <SubmitButton>
+    <span v-if="isLoading">Loading...</span>
+    <span v-else>Submit</span>
+  </SubmitButton>
+</template>
+```
+
+```vue
+<!-- SubmitButton.vue (Child) -->
+<script setup>
+import { ref } from 'vue'
+
+const buttonText = ref('Click me')  // Not accessible in parent's slot content
+const isLoading = ref(false)        // Not accessible in parent's slot content
+</script>
+
+<template>
+  <button>
+    <slot></slot>
+  </button>
+</template>
+```
+
+**Correct - Use Scoped Slots:**
+```vue
+<!-- SubmitButton.vue (Child) - Expose data via slot props -->
+<script setup>
+import { ref } from 'vue'
+
+const buttonText = ref('Click me')
+const isLoading = ref(false)
+</script>
+
+<template>
+  <button>
+    <!-- Pass child data as slot props -->
+    <slot :text="buttonText" :loading="isLoading"></slot>
+  </button>
+</template>
+```
+
+```vue
+<!-- Parent.vue -->
+<script setup>
+import SubmitButton from './SubmitButton.vue'
+</script>
+
+<template>
+  <!-- GOOD: Receive child data via scoped slot -->
+  <SubmitButton v-slot="{ text, loading }">
+    <span v-if="loading">Loading...</span>
+    <span v-else>{{ text }}</span>
+  </SubmitButton>
+</template>
+```
+
+**Correct - Use Parent Data:**
+```vue
+<!-- Parent.vue -->
+<script setup>
+import { ref } from 'vue'
+import SubmitButton from './SubmitButton.vue'
+
+// Define data in parent where slot content is compiled
+const message = ref('Submit Form')
+const isSubmitting = ref(false)
+</script>
+
+<template>
+  <!-- GOOD: Using parent's own data in slot content -->
+  <SubmitButton>
+    <span v-if="isSubmitting">Processing...</span>
+    <span v-else>{{ message }}</span>
+  </SubmitButton>
+</template>
+```
+
+## The Function Analogy
+
+Think of slots as function parameters:
+
+```javascript
+// Slot content is like a callback defined in parent scope
+function Parent() {
+  const parentData = 'Hello'
+
+  // This callback can only see parentData, not childData
+  Child((slotProps) => {
+    return parentData + (slotProps?.text || '')
+  })
+}
+
+function Child(slotCallback) {
+  const childData = 'World'  // Not visible to callback
+
+  // Must explicitly pass data via slot props
+  return slotCallback({ text: childData })
+}
+```
+
+## Reference
+- [Vue.js Slots - Render Scope](https://vuejs.org/guide/components/slots.html#render-scope)