@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/select-initial-value-ios-bug.md

@@ -0,0 +1,91 @@
+---
+title: Select Element iOS Bug - Always Include Disabled Placeholder Option
+impact: HIGH
+impactDescription: On iOS, users cannot select the first option if v-model initial value doesn't match any option
+type: capability
+tags: [vue3, v-model, forms, select, ios, mobile, accessibility]
+---
+
+# Select Element iOS Bug - Always Include Disabled Placeholder Option
+
+**Impact: HIGH** - When a `<select>` element's v-model initial value doesn't match any option, iOS renders it as "unselected" and users CANNOT select the first item. iOS doesn't fire a change event when selecting an already-visually-selected option, leaving users stuck.
+
+This is a platform-specific bug that only manifests on iOS Safari. Desktop browsers and Android handle this gracefully, making it easy to miss during development. The fix is simple: always include a disabled placeholder option.
+
+## Task Checklist
+
+- [ ] Always add a disabled placeholder option with empty value to select elements
+- [ ] Ensure v-model initial value is empty string to match the placeholder
+- [ ] Test select inputs on iOS devices or simulators
+- [ ] Consider this for any user-facing forms, especially on mobile-first apps
+
+**Problem - iOS users cannot select first option:**
+```html
+<script setup>
+import { ref } from 'vue'
+
+// Initial value is empty string, doesn't match any option
+const selected = ref('')
+</script>
+
+<template>
+  <!-- PROBLEM: On iOS, "Apple" appears selected but user cannot actually select it -->
+  <!-- Tapping "Apple" does nothing because iOS doesn't fire change event -->
+  <select v-model="selected">
+    <option value="apple">Apple</option>
+    <option value="banana">Banana</option>
+    <option value="orange">Orange</option>
+  </select>
+
+  <!-- selected remains '' even though "Apple" appears highlighted -->
+</template>
+```
+
+**Solution - Add disabled placeholder option:**
+```html
+<script setup>
+import { ref } from 'vue'
+
+const selected = ref('')  // Matches the placeholder option
+</script>
+
+<template>
+  <!-- CORRECT: Disabled placeholder ensures user must actively select -->
+  <select v-model="selected">
+    <option disabled value="">Please select a fruit</option>
+    <option value="apple">Apple</option>
+    <option value="banana">Banana</option>
+    <option value="orange">Orange</option>
+  </select>
+</template>
+```
+
+```html
+<!-- Variant with required attribute for form validation -->
+<select v-model="selected" required>
+  <option disabled value="">-- Select an option --</option>
+  <option value="a">Option A</option>
+  <option value="b">Option B</option>
+</select>
+```
+
+```html
+<!-- If you MUST have a pre-selected default, set the initial value to match -->
+<script setup>
+import { ref } from 'vue'
+
+// Set initial value to match an actual option
+const country = ref('us')  // Pre-selects "United States"
+</script>
+
+<template>
+  <select v-model="country">
+    <option value="us">United States</option>
+    <option value="uk">United Kingdom</option>
+    <option value="ca">Canada</option>
+  </select>
+</template>
+```
+
+## Reference
+- [Vue.js Form Input Bindings - Select](https://vuejs.org/guide/essentials/forms.html#select)

package/skills/vue-debug-guides/reference/self-referencing-component-name.md

@@ -0,0 +1,157 @@
+---
+title: Self-Referencing Components Use Filename as Implicit Name
+impact: LOW
+impactDescription: Understanding this avoids confusion with recursive components
+type: gotcha
+tags: [vue3, component-registration, self-reference, recursive-components, sfc]
+---
+
+# Self-Referencing Components Use Filename as Implicit Name
+
+**Impact: LOW** - In Single-File Components (SFC), a component can reference itself in its own template using its filename as the component name. This is useful for recursive components like tree structures or nested comments. However, this implicit registration has lower priority than explicitly imported components, which can cause confusion.
+
+## Task Checklist
+
+- [ ] Use the filename (without extension) to self-reference a component
+- [ ] Be aware that imported components take precedence over self-reference
+- [ ] For clarity in recursive components, consider explicit naming
+
+**Example:**
+```vue
+<!-- TreeItem.vue -->
+<script setup>
+defineProps({
+  item: Object
+})
+</script>
+
+<template>
+  <div class="tree-item">
+    <span>{{ item.name }}</span>
+    <!-- Self-reference using filename -->
+    <TreeItem
+      v-for="child in item.children"
+      :key="child.id"
+      :item="child"
+    />
+  </div>
+</template>
+```
+
+```vue
+<!-- Comment.vue - recursive comments -->
+<script setup>
+defineProps({
+  comment: Object
+})
+</script>
+
+<template>
+  <div class="comment">
+    <p>{{ comment.text }}</p>
+    <div class="replies" v-if="comment.replies?.length">
+      <!-- Self-reference for nested replies -->
+      <Comment
+        v-for="reply in comment.replies"
+        :key="reply.id"
+        :comment="reply"
+      />
+    </div>
+  </div>
+</template>
+```
+
+## Priority: Imports Override Self-Reference
+
+```vue
+<!-- FooBar.vue -->
+<script setup>
+// If you import a component named FooBar, it takes precedence
+import FooBar from './different/FooBar.vue'
+</script>
+
+<template>
+  <!-- This renders the IMPORTED FooBar, not this file -->
+  <FooBar />
+</template>
+```
+
+To explicitly self-reference when there's a naming conflict:
+
+```vue
+<!-- FooBar.vue -->
+<script setup>
+import OtherFooBar from './different/FooBar.vue'
+// No way to explicitly import "self" in script setup
+// Must rename the import to avoid conflict
+</script>
+
+<template>
+  <OtherFooBar />
+  <!-- FooBar still refers to self (this file) because
+       the import was aliased -->
+  <FooBar />
+</template>
+```
+
+## Options API: Explicit Name Option
+
+```vue
+<!-- RecursiveList.vue -->
+<script>
+export default {
+  name: 'RecursiveList', // Explicit name for self-reference
+  props: {
+    items: Array
+  }
+}
+</script>
+
+<template>
+  <ul>
+    <li v-for="item in items" :key="item.id">
+      {{ item.name }}
+      <RecursiveList v-if="item.children" :items="item.children" />
+    </li>
+  </ul>
+</template>
+```
+
+## Common Use Cases for Self-Reference
+
+1. **Tree structures** - File explorers, org charts
+2. **Nested comments** - Reddit-style comment threads
+3. **Menu navigation** - Recursive dropdown menus
+4. **Category hierarchies** - Product categories, taxonomies
+
+## Avoid Infinite Recursion
+
+```vue
+<!-- TreeNode.vue -->
+<script setup>
+defineProps({
+  node: Object,
+  maxDepth: { type: Number, default: 10 },
+  currentDepth: { type: Number, default: 0 }
+})
+</script>
+
+<template>
+  <div class="node">
+    {{ node.name }}
+    <!-- Guard against infinite recursion -->
+    <template v-if="node.children && currentDepth < maxDepth">
+      <TreeNode
+        v-for="child in node.children"
+        :key="child.id"
+        :node="child"
+        :max-depth="maxDepth"
+        :current-depth="currentDepth + 1"
+      />
+    </template>
+  </div>
+</template>
+```
+
+## Reference
+- [Vue.js Component Registration](https://vuejs.org/guide/components/registration.html)

package/skills/vue-debug-guides/reference/sfc-named-exports-forbidden.md

@@ -0,0 +1,184 @@
+---
+title: SFC Script Block Must Use Default Export Only
+impact: HIGH
+impactDescription: Named exports in SFC script blocks will fail silently or cause build errors - Vue expects exactly one default export
+type: gotcha
+tags: [vue3, sfc, export, script-block, composition-api]
+---
+
+# SFC Script Block Must Use Default Export Only
+
+**Impact: HIGH** - Vue Single-File Components expect exactly one default export from the `<script>` block. Using named exports for your component will cause build failures or runtime errors because Vue's tooling is designed to process a single default-exported component definition per `.vue` file.
+
+## Task Checklist
+
+- [ ] Always use `export default` in `<script>` blocks (Options API)
+- [ ] Use `<script setup>` which handles exports automatically (Composition API)
+- [ ] Move shared utilities to separate `.js`/`.ts` files, not the component's script block
+- [ ] If you need to export types, use a separate `<script>` block alongside `<script setup>`
+
+**Problematic Code:**
+```vue
+<!-- MyComponent.vue -->
+<script>
+// BAD: Named exports don't work for the component itself
+export const MyComponent = {
+  data() {
+    return { count: 0 }
+  }
+}
+
+// BAD: Exporting multiple things from component script
+export const CONSTANT = 42
+export function helper() { }
+</script>
+
+<template>
+  <div>{{ count }}</div>
+</template>
+```
+
+**Correct Code:**
+```vue
+<!-- MyComponent.vue - Options API -->
+<script>
+// GOOD: Single default export
+export default {
+  data() {
+    return { count: 0 }
+  }
+}
+</script>
+
+<template>
+  <div>{{ count }}</div>
+</template>
+```
+
+```vue
+<!-- MyComponent.vue - Composition API with script setup -->
+<script setup>
+// GOOD: No export needed, component is auto-exported
+import { ref } from 'vue'
+
+const count = ref(0)
+</script>
+
+<template>
+  <div>{{ count }}</div>
+</template>
+```
+
+## Exporting Types Alongside Script Setup
+
+For TypeScript, use a separate regular script block for type exports:
+
+```vue
+<script lang="ts">
+// Regular script block for exports
+export interface User {
+  id: number
+  name: string
+}
+
+export type Status = 'pending' | 'active' | 'inactive'
+</script>
+
+<script setup lang="ts">
+// Setup script for component logic
+import { ref } from 'vue'
+
+const users = ref<User[]>([])
+</script>
+
+<template>
+  <ul>
+    <li v-for="user in users" :key="user.id">{{ user.name }}</li>
+  </ul>
+</template>
+```
+
+## Sharing Utilities Across Components
+
+Don't put shared code in component script blocks. Create separate files:
+
+```typescript
+// utils/constants.ts
+export const ITEMS_PER_PAGE = 20
+export const API_BASE_URL = '/api/v1'
+
+// utils/helpers.ts
+export function formatDate(date: Date): string {
+  return date.toLocaleDateString()
+}
+
+export function formatCurrency(amount: number): string {
+  return `$${amount.toFixed(2)}`
+}
+```
+
+```vue
+<!-- ProductList.vue -->
+<script setup>
+// GOOD: Import shared utilities from external files
+import { ITEMS_PER_PAGE } from '@/utils/constants'
+import { formatCurrency } from '@/utils/helpers'
+import { ref } from 'vue'
+
+const products = ref([])
+</script>
+```
+
+## Why This Restriction Exists
+
+Vue's SFC compiler and build tools expect:
+
+1. **One component per file**: The `.vue` file format is designed for single-component definitions
+2. **Predictable structure**: Tools like Volar, vue-tsc, and bundler plugins assume default export
+3. **Hot Module Replacement**: HMR relies on the single-component-per-file convention
+
+```javascript
+// How Vue tooling processes SFCs internally
+import MyComponent from './MyComponent.vue'
+// ^ Always expects the default export to be the component
+```
+
+## Common Mistake: Reusing Code via SFC Exports
+
+```vue
+<!-- BAD PATTERN: Trying to reuse code from components -->
+<script>
+// This won't work as expected
+export const sharedLogic = () => { ... }
+
+export default {
+  // component definition
+}
+</script>
+```
+
+Instead, use composables:
+
+```typescript
+// composables/useSharedLogic.ts
+export function useSharedLogic() {
+  // Shared reactive logic
+  const state = ref(0)
+  const increment = () => state.value++
+
+  return { state, increment }
+}
+```
+
+```vue
+<!-- ComponentA.vue -->
+<script setup>
+import { useSharedLogic } from '@/composables/useSharedLogic'
+
+const { state, increment } = useSharedLogic()
+</script>
+```
+
+## Reference
+- [Vue.js SFC Specification](https://vuejs.org/api/sfc-spec.html)
+- [Vue.js Composition API - Composables](https://vuejs.org/guide/reusability/composables.html)

package/skills/vue-debug-guides/reference/sfc-scoped-css-child-component-styling.md

@@ -0,0 +1,156 @@
+---
+title: Use Deep Selectors for Styling Child Component Elements
+impact: HIGH
+impactDescription: Scoped styles cannot target elements inside child components without deep selectors, leading to silently broken styles
+type: gotcha
+tags: [vue3, sfc, scoped-css, deep-selector, child-components]
+---
+
+# Use Deep Selectors for Styling Child Component Elements
+
+**Impact: HIGH** - When using scoped CSS in Vue SFCs, styles do not penetrate into child components. Without using deep selectors (`:deep()`), your styles will silently fail to apply to elements rendered by child components or third-party libraries.
+
+## Task Checklist
+
+- [ ] Use `:deep()` selector to style elements inside child components
+- [ ] Never use deprecated `>>>` or `/deep/` selectors (Vue 3 only supports `:deep()`)
+- [ ] Scope deep selectors to a parent class when possible to limit impact
+- [ ] Consider using unscoped styles or CSS modules for heavily nested styling
+
+**Problematic Code:**
+```vue
+<template>
+  <div class="container">
+    <ThirdPartyDatePicker />
+  </div>
+</template>
+
+<style scoped>
+/* BAD: These styles won't apply to elements inside ThirdPartyDatePicker */
+.container .date-input {
+  border-color: blue;
+}
+
+.container .calendar-popup {
+  background: white;
+}
+</style>
+```
+
+**Correct Code:**
+```vue
+<template>
+  <div class="container">
+    <ThirdPartyDatePicker />
+  </div>
+</template>
+
+<style scoped>
+/* GOOD: Use :deep() to style child component elements */
+.container :deep(.date-input) {
+  border-color: blue;
+}
+
+.container :deep(.calendar-popup) {
+  background: white;
+}
+
+/* Also correct: deep selector at root level */
+:deep(.date-picker-wrapper) {
+  padding: 1rem;
+}
+</style>
+```
+
+## How Scoped CSS Works
+
+Vue scoped CSS adds a unique data attribute to all elements in the component's template and appends it to CSS selectors:
+
+```vue
+<!-- Template output -->
+<div class="container" data-v-7ba5bd90>
+  <!-- Child component elements DON'T get data-v-7ba5bd90 -->
+  <div class="date-input">...</div>
+</div>
+```
+
+```css
+/* Generated scoped CSS */
+.container[data-v-7ba5bd90] .date-input[data-v-7ba5bd90] { ... }
+/* ^ This won't match because .date-input doesn't have the attribute */
+```
+
+## Vue 3 Deep Selector Syntax
+
+```vue
+<style scoped>
+/* Vue 3 recommended syntax */
+.parent :deep(.child-class) {
+  color: red;
+}
+
+/* DEPRECATED - don't use these in Vue 3 */
+.parent >>> .child-class { }   /* Won't work in SCSS */
+.parent /deep/ .child-class { } /* Deprecated */
+.parent ::v-deep .child-class { } /* Old syntax */
+</style>
+```
+
+## Scoping Deep Selectors for Safety
+
+Always scope `:deep()` to a parent selector to limit its reach:
+
+```vue
+<style scoped>
+/* BAD: Affects ALL .btn elements in child components globally */
+:deep(.btn) {
+  background: blue;
+}
+
+/* GOOD: Only affects .btn inside .my-component */
+.my-component :deep(.btn) {
+  background: blue;
+}
+</style>
+```
+
+## Child Component Root Element Exception
+
+Note: A child component's root element IS affected by parent scoped CSS. This is intentional for layout purposes:
+
+```vue
+<!-- Parent.vue -->
+<template>
+  <ChildComponent class="styled-child" />
+</template>
+
+<style scoped>
+/* This WILL work - targets child's root element */
+.styled-child {
+  margin: 1rem;
+  border: 1px solid gray;
+}
+</style>
+```
+
+## Performance Consideration
+
+Using `:deep()` with element selectors can be slower:
+
+```vue
+<style scoped>
+/* SLOWER: Element selector with deep */
+.container :deep(p) {
+  color: red;
+}
+
+/* FASTER: Class selector with deep */
+.container :deep(.paragraph) {
+  color: red;
+}
+</style>
+```
+
+## Reference
+- [Vue.js Scoped CSS - Deep Selectors](https://vuejs.org/api/sfc-css-features.html#deep-selectors)
+- [Vue Loader Scoped CSS](https://vue-loader.vuejs.org/guide/scoped-css.html)