@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-options-api-best-practices/reference/ts-options-api-arrow-functions-validators.md

@@ -0,0 +1,141 @@
+---
+title: Use Arrow Functions for Prop Validators in TypeScript < 4.7
+impact: HIGH
+impactDescription: Regular functions in prop validators can break type inference for the entire component in TypeScript versions before 4.7
+type: gotcha
+tags: [vue3, typescript, options-api, props, type-inference, defineComponent, legacy]
+---
+
+# Use Arrow Functions for Prop Validators in TypeScript < 4.7
+
+> **LEGACY CONCERN:** This issue was fixed in TypeScript 4.7 (released May 2022). Most modern projects using TypeScript 4.7+ do not need this workaround. If you're starting a new project or have upgraded TypeScript recently, you can safely use regular functions in prop validators. This rule is primarily relevant for legacy codebases still running TypeScript < 4.7.
+
+**Impact: HIGH** - If your TypeScript version is less than 4.7, using regular functions for `validator` and `default` prop options can cause TypeScript to fail when inferring the type of `this`, which breaks type inference for the ENTIRE component, not just the prop.
+
+## Task Checklist
+
+- [ ] Check your TypeScript version (`tsc --version`)
+- [ ] If TypeScript < 4.7, use arrow functions for all `validator` and `default` prop options
+- [ ] Consider upgrading to TypeScript 4.7+ to avoid this limitation entirely
+
+## The Problem
+
+TypeScript needs to infer the type of `this` inside regular functions. In Vue's Options API context, this inference can fail in versions before 4.7, causing cascading type inference failures.
+
+**BAD - Can break type inference in TS < 4.7:**
+```typescript
+import { defineComponent, PropType } from 'vue'
+
+interface Book {
+  title: string
+  author: string
+  year: number
+}
+
+export default defineComponent({
+  props: {
+    book: {
+      type: Object as PropType<Book>,
+      required: true,
+      // Regular function - causes inference issues in TS < 4.7
+      validator: function(book: Book) {
+        return book.title.length > 0
+      }
+    },
+    count: {
+      type: Number,
+      // Regular function - causes inference issues in TS < 4.7
+      default: function() {
+        return 0
+      }
+    }
+  },
+  // Type inference for computed, methods, etc. may break!
+  computed: {
+    bookTitle() {
+      // 'this' might be typed as 'any' due to broken inference
+      return this.book.title
+    }
+  }
+})
+```
+
+**GOOD - Use arrow functions:**
+```typescript
+import { defineComponent, PropType } from 'vue'
+
+interface Book {
+  title: string
+  author: string
+  year: number
+}
+
+export default defineComponent({
+  props: {
+    book: {
+      type: Object as PropType<Book>,
+      required: true,
+      // Arrow function - safe for all TS versions
+      validator: (book: Book) => book.title.length > 0
+    },
+    count: {
+      type: Number,
+      // Arrow function - safe for all TS versions
+      default: () => 0
+    }
+  },
+  computed: {
+    bookTitle() {
+      // 'this' is properly typed
+      return this.book.title  // Type: string
+    }
+  }
+})
+```
+
+## Why Arrow Functions Work
+
+Arrow functions don't have their own `this` binding, so TypeScript doesn't need to infer a `this` type for them. This avoids the type inference bug that affects regular functions in older TypeScript versions.
+
+## For Object/Array Default Values
+
+Arrow functions are especially important for object and array defaults (which Vue requires to be functions anyway):
+
+```typescript
+props: {
+  config: {
+    type: Object as PropType<Config>,
+    // Must be a function, use arrow syntax
+    default: () => ({
+      enabled: true,
+      maxItems: 10
+    })
+  },
+  tags: {
+    type: Array as PropType<string[]>,
+    // Must be a function, use arrow syntax
+    default: () => []
+  }
+}
+```
+
+## When You Can Ignore This
+
+- **TypeScript 4.7+**: This issue was fixed in TypeScript 4.7 (May 2022). If your project uses 4.7 or later, regular functions work fine. Since TypeScript 4.7 has been available for over 3 years, most actively maintained projects have already upgraded and do not need this workaround.
+- **New projects**: If you're starting a new Vue project in 2024 or later, you'll almost certainly be using TypeScript 4.7+ by default and can ignore this rule entirely.
+- **Arrow functions are still fine**: While not required in modern TypeScript, using arrow functions for validators and defaults remains a valid stylistic choice and causes no issues.
+
+## Checking Your TypeScript Version
+
+```bash
+# Check installed TypeScript version
+npx tsc --version
+
+# Or check package.json
+grep typescript package.json
+```
+
+## Reference
+
+- [Vue.js TypeScript with Options API](https://vuejs.org/guide/typescript/options-api.html#caveats)
+- [TypeScript 4.7 Release Notes](https://devblogs.microsoft.com/typescript/announcing-typescript-4-7/)

package/skills/vue-options-api-best-practices/reference/ts-options-api-computed-return-types.md

@@ -0,0 +1,192 @@
+---
+title: Explicitly Annotate Computed Property Return Types
+impact: LOW
+impactDescription: While Vue usually infers computed types correctly, explicit annotations prevent circular inference issues and improve code documentation
+type: best-practice
+tags: [vue3, typescript, options-api, computed, type-inference]
+---
+
+# Explicitly Annotate Computed Property Return Types
+
+**Impact: LOW** - Vue can usually infer computed property return types automatically. However, explicit return type annotations prevent edge cases involving circular inference loops and serve as documentation for complex computed properties.
+
+## Task Checklist
+
+- [ ] Consider adding return types to computed properties, especially complex ones
+- [ ] Always add return types when TypeScript inference fails or shows incorrect types
+- [ ] Add return types for writable computed properties (getter and setter)
+
+## When Explicit Types Are Helpful
+
+### 1. Complex Computed Properties
+
+```typescript
+import { defineComponent } from 'vue'
+
+interface CartItem {
+  id: number
+  name: string
+  price: number
+  quantity: number
+}
+
+export default defineComponent({
+  data() {
+    return {
+      items: [] as CartItem[],
+      discountPercent: 10
+    }
+  },
+  computed: {
+    // Without annotation - works but intent unclear
+    cartSummary() {
+      return {
+        subtotal: this.items.reduce((sum, item) => sum + item.price * item.quantity, 0),
+        itemCount: this.items.reduce((sum, item) => sum + item.quantity, 0)
+      }
+    },
+
+    // With annotation - clear intent, documented type
+    cartSummaryTyped(): { subtotal: number; itemCount: number; discount: number; total: number } {
+      const subtotal = this.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
+      const discount = subtotal * (this.discountPercent / 100)
+      return {
+        subtotal,
+        itemCount: this.items.reduce((sum, item) => sum + item.quantity, 0),
+        discount,
+        total: subtotal - discount
+      }
+    }
+  }
+})
+```
+
+### 2. Circular Inference Issues
+
+Sometimes computed properties that reference each other can cause TypeScript inference to fail:
+
+```typescript
+export default defineComponent({
+  data() {
+    return {
+      firstName: 'John',
+      lastName: 'Doe'
+    }
+  },
+  computed: {
+    // Explicit return type breaks potential circular inference
+    fullName(): string {
+      return `${this.firstName} ${this.lastName}`
+    },
+
+    // References fullName - explicit type prevents inference issues
+    greeting(): string {
+      return `Hello, ${this.fullName}!`
+    }
+  }
+})
+```
+
+### 3. Writable Computed Properties
+
+Always annotate writable computed properties for clarity:
+
+```typescript
+export default defineComponent({
+  data() {
+    return {
+      firstName: 'John',
+      lastName: 'Doe'
+    }
+  },
+  computed: {
+    // Writable computed - explicit types for getter and setter
+    fullName: {
+      get(): string {
+        return `${this.firstName} ${this.lastName}`
+      },
+      set(newValue: string) {
+        const parts = newValue.split(' ')
+        this.firstName = parts[0] || ''
+        this.lastName = parts.slice(1).join(' ') || ''
+      }
+    }
+  }
+})
+```
+
+## When You Can Skip Explicit Types
+
+Simple computed properties that TypeScript infers correctly:
+
+```typescript
+computed: {
+  // Simple string - TypeScript infers correctly
+  upperName() {
+    return this.name.toUpperCase()
+  },
+
+  // Simple boolean - TypeScript infers correctly
+  isEmpty() {
+    return this.items.length === 0
+  },
+
+  // Simple number - TypeScript infers correctly
+  totalCount() {
+    return this.items.length
+  }
+}
+```
+
+## Interface for Complex Return Types
+
+For complex computed return types, define interfaces:
+
+```typescript
+interface PaginationInfo {
+  currentPage: number
+  totalPages: number
+  hasNext: boolean
+  hasPrev: boolean
+  pageItems: Item[]
+}
+
+export default defineComponent({
+  computed: {
+    pagination(): PaginationInfo {
+      const totalPages = Math.ceil(this.items.length / this.pageSize)
+      const start = (this.currentPage - 1) * this.pageSize
+
+      return {
+        currentPage: this.currentPage,
+        totalPages,
+        hasNext: this.currentPage < totalPages,
+        hasPrev: this.currentPage > 1,
+        pageItems: this.items.slice(start, start + this.pageSize)
+      }
+    }
+  }
+})
+```
+
+## Debugging Type Inference
+
+If you're unsure what TypeScript infers, hover over the computed property in your IDE, or add a temporary annotation to see errors:
+
+```typescript
+computed: {
+  // Hover over 'mystery' in IDE to see inferred type
+  mystery() {
+    return this.someComplexCalculation()
+  },
+
+  // Or add annotation to verify
+  mystery(): ExpectedType {  // Error if inference differs
+    return this.someComplexCalculation()
+  }
+}
+```
+
+## Reference
+
+- [Vue.js TypeScript with Options API - Typing Computed Properties](https://vuejs.org/guide/typescript/options-api.html#typing-computed-properties)

package/skills/vue-options-api-best-practices/reference/ts-options-api-proptype-complex-types.md

@@ -0,0 +1,212 @@
+---
+title: Use PropType for Complex Prop Types in Options API
+impact: MEDIUM
+impactDescription: Vue's runtime prop types cannot express complex TypeScript types without PropType, leading to 'any' type inference
+type: best-practice
+tags: [vue3, typescript, options-api, props, PropType, type-safety]
+---
+
+# Use PropType for Complex Prop Types in Options API
+
+**Impact: MEDIUM** - Vue's runtime `props` option only supports basic constructor functions (String, Number, etc.). To type complex props like interfaces, function signatures, or union types, you must use Vue's `PropType` utility type.
+
+## Task Checklist
+
+- [ ] Import `PropType` from 'vue' for complex prop types
+- [ ] Use `as PropType<YourType>` after `Object`, `Array`, or `Function`
+- [ ] Define interfaces for your complex types
+- [ ] Remember: PropType is purely for TypeScript - runtime validation only checks the constructor
+
+## The Problem
+
+Vue's runtime prop system uses JavaScript constructor functions, which can't express complex TypeScript types:
+
+```typescript
+// What runtime props support:
+props: {
+  name: String,       // OK: string
+  count: Number,      // OK: number
+  enabled: Boolean,   // OK: boolean
+  items: Array,       // Problem: any[]
+  config: Object,     // Problem: Record<string, any>
+  handler: Function   // Problem: (...args: any[]) => any
+}
+```
+
+## Using PropType for Complex Types
+
+**Import and use PropType:**
+```typescript
+import { defineComponent, PropType } from 'vue'
+// or
+import type { PropType } from 'vue'
+
+interface User {
+  id: number
+  name: string
+  email: string
+}
+
+interface Config {
+  theme: 'light' | 'dark'
+  maxItems: number
+}
+
+export default defineComponent({
+  props: {
+    // Object with interface
+    user: {
+      type: Object as PropType<User>,
+      required: true
+    },
+
+    // Array of typed items
+    users: {
+      type: Array as PropType<User[]>,
+      default: () => []
+    },
+
+    // Object with union type
+    config: {
+      type: Object as PropType<Config>,
+      default: () => ({ theme: 'light', maxItems: 10 })
+    },
+
+    // Typed function
+    onSubmit: {
+      type: Function as PropType<(data: User) => Promise<void>>,
+      required: true
+    },
+
+    // Union of primitives
+    id: {
+      type: [String, Number] as PropType<string | number>,
+      required: true
+    },
+
+    // Literal union type
+    status: {
+      type: String as PropType<'pending' | 'active' | 'completed'>,
+      default: 'pending'
+    }
+  },
+
+  methods: {
+    async handleSubmit() {
+      // Full type inference!
+      await this.onSubmit(this.user)  // onSubmit is properly typed
+      console.log(this.user.email)    // user.email is string
+      console.log(this.config.theme)  // theme is 'light' | 'dark'
+    }
+  }
+})
+```
+
+## Important: Runtime vs Compile-Time
+
+PropType only affects TypeScript compilation. At runtime, Vue still only validates using the constructor:
+
+```typescript
+props: {
+  user: {
+    type: Object as PropType<User>,
+    required: true
+  }
+}
+
+// Runtime: Vue only checks typeof value === 'object'
+// It does NOT validate { id, name, email } structure
+
+// To add runtime validation, use validator:
+props: {
+  user: {
+    type: Object as PropType<User>,
+    required: true,
+    validator: (user: User) => {
+      return typeof user.id === 'number' &&
+             typeof user.name === 'string' &&
+             typeof user.email === 'string'
+    }
+  }
+}
+```
+
+## Common PropType Patterns
+
+### Nullable Props
+
+```typescript
+props: {
+  // Optional object that can be null
+  selectedItem: {
+    type: Object as PropType<Item | null>,
+    default: null
+  }
+}
+```
+
+### Enum-like Props
+
+```typescript
+type ButtonVariant = 'primary' | 'secondary' | 'danger'
+
+props: {
+  variant: {
+    type: String as PropType<ButtonVariant>,
+    default: 'primary',
+    validator: (v: ButtonVariant) =>
+      ['primary', 'secondary', 'danger'].includes(v)
+  }
+}
+```
+
+### Generic-like Props with Multiple Types
+
+```typescript
+props: {
+  // Accept string, number, or object with id
+  value: {
+    type: [String, Number, Object] as PropType<string | number | { id: string }>,
+    required: true
+  }
+}
+```
+
+### Event Handler Props
+
+```typescript
+interface ClickEventData {
+  item: Item
+  index: number
+}
+
+props: {
+  onClick: {
+    type: Function as PropType<(data: ClickEventData) => void>,
+    required: false
+  }
+}
+```
+
+## Why Not Just Use `as`?
+
+You might think to skip `PropType`:
+
+```typescript
+// WRONG - doesn't work as expected
+props: {
+  user: Object as User  // TypeScript error or incorrect inference
+}
+
+// CORRECT - use PropType
+props: {
+  user: Object as PropType<User>
+}
+```
+
+`PropType<T>` is specifically designed to work with Vue's prop type system.
+
+## Reference
+
+- [Vue.js TypeScript with Options API - Typing Component Props](https://vuejs.org/guide/typescript/options-api.html#typing-component-props)
+- [Vue.js Props Documentation](https://vuejs.org/guide/components/props.html)

package/skills/vue-options-api-best-practices/reference/ts-options-api-provide-inject-limitations.md

@@ -0,0 +1,135 @@
+---
+title: Provide/Inject Has Limited Type Inference in Options API
+impact: MEDIUM
+impactDescription: Injected properties in Options API are not automatically typed, requiring manual type assertions or type augmentation
+type: gotcha
+tags: [vue3, typescript, options-api, provide-inject, type-safety]
+---
+
+# Provide/Inject Has Limited Type Inference in Options API
+
+**Impact: MEDIUM** - When using `provide/inject` with the Options API and TypeScript, injected properties won't be automatically typed. TypeScript will show errors that the property doesn't exist on the component, even though it works at runtime.
+
+## Task Checklist
+
+- [ ] Be aware that Options API inject has limited type support
+- [ ] Use type augmentation to add types to injected values
+- [ ] Consider using typed computed wrappers for injected values
+
+## The Problem
+
+```typescript
+// Provider component (parent)
+import { defineComponent } from 'vue'
+
+export default defineComponent({
+  provide() {
+    return {
+      theme: 'dark',
+      user: { id: 1, name: 'John' }
+    }
+  }
+})
+```
+
+```typescript
+// Consumer component (child) - Options API
+import { defineComponent } from 'vue'
+
+export default defineComponent({
+  inject: ['theme', 'user'],
+
+  mounted() {
+    // TypeScript Error: Property 'theme' does not exist on type...
+    console.log(this.theme)
+
+    // TypeScript Error: Property 'user' does not exist on type...
+    console.log(this.user.name)
+  }
+})
+```
+
+## Solution 1: Type Augmentation
+
+Augment the component type to include injected properties:
+
+```typescript
+// types/injections.d.ts
+import 'vue'
+
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    theme: 'light' | 'dark'
+    user: { id: number; name: string }
+  }
+}
+
+export {}
+```
+
+```typescript
+// Consumer component - now typed
+import { defineComponent } from 'vue'
+
+export default defineComponent({
+  inject: ['theme', 'user'],
+
+  mounted() {
+    // Now works - typed from ComponentCustomProperties
+    console.log(this.theme)  // 'light' | 'dark'
+    console.log(this.user.name)  // string
+  }
+})
+```
+
+**Note**: This adds types globally to ALL components, not just those that inject these values.
+
+## Solution 2: Typed Computed Wrappers
+
+Use the object syntax with computed property wrappers for type safety:
+
+```typescript
+import { defineComponent } from 'vue'
+
+interface User {
+  id: number
+  name: string
+}
+
+export default defineComponent({
+  inject: {
+    theme: {
+      from: 'theme',
+      default: 'light'
+    },
+    user: {
+      from: 'user',
+      default: () => ({ id: 0, name: 'Guest' })
+    }
+  },
+
+  computed: {
+    // Type via computed wrapper
+    typedTheme(): 'light' | 'dark' {
+      return this.theme as 'light' | 'dark'
+    },
+    typedUser(): User {
+      return this.user as User
+    }
+  },
+
+  mounted() {
+    console.log(this.typedTheme)
+    console.log(this.typedUser.name)
+  }
+})
+```
+
+## Why This Happens
+
+The Options API `inject` array syntax `inject: ['theme']` doesn't provide type information to TypeScript. Vue knows about the injection at runtime, but TypeScript's static analysis can't trace the provide/inject relationship across components.
+
+## Reference
+
+- [Vue.js Provide/Inject](https://vuejs.org/guide/components/provide-inject.html)
+- [GitHub Issue: Add type inference to Options API provide/inject](https://github.com/vuejs/core/issues/3031)