@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/ts-defineprops-imported-types-limitations.md

@@ -0,0 +1,281 @@
+---
+title: Imported Types Have Limitations in defineProps
+impact: MEDIUM
+impactDescription: Complex imported types like conditional types can cause compiler errors in defineProps
+type: gotcha
+tags: [vue3, typescript, defineProps, imported-types, vue3.3]
+---
+
+# Imported Types Have Limitations in defineProps
+
+**Impact: MEDIUM** - While Vue 3.3+ supports imported types in `defineProps<>()`, certain complex types are not fully supported. Conditional types, mapped types that require full type analysis, and global ambient types can cause "Unresolvable type reference" errors.
+
+## Task Checklist
+
+- [ ] Understand which type patterns are supported vs unsupported
+- [ ] Keep prop type definitions simple and explicit
+- [ ] Move complex type logic outside of defineProps
+- [ ] Export interfaces explicitly rather than using global declarations
+
+## Supported Patterns (Vue 3.3+)
+
+```typescript
+// types/user.ts
+export interface User {
+  id: string
+  name: string
+  email?: string
+}
+
+export interface ListProps<T> {
+  items: T[]
+  selectedItem?: T
+}
+
+export type Status = 'pending' | 'active' | 'completed'
+```
+
+```vue
+<script setup lang="ts">
+import type { User, Status } from '@/types/user'
+
+// WORKS: Simple imported interface
+defineProps<{
+  user: User
+}>()
+
+// WORKS: Imported union type
+defineProps<{
+  status: Status
+}>()
+
+// WORKS: Direct imported interface
+defineProps<User>()
+</script>
+```
+
+## Unsupported Patterns
+
+### Conditional Types for Entire Props Object
+
+```typescript
+// types/conditional.ts
+export type ConditionalProps<T> = T extends string
+  ? { value: string; onChange: (v: string) => void }
+  : { value: number; onChange: (v: number) => void }
+```
+
+```vue
+<script setup lang="ts">
+import type { ConditionalProps } from '@/types/conditional'
+
+// ERROR: Conditional types not supported for entire props object
+defineProps<ConditionalProps<string>>()
+</script>
+```
+
+**Workaround:**
+```vue
+<script setup lang="ts">
+// Define the resolved type directly
+interface StringProps {
+  value: string
+  onChange: (v: string) => void
+}
+
+defineProps<StringProps>()
+</script>
+```
+
+### Conditional Types for Individual Props ARE Supported
+
+```vue
+<script setup lang="ts">
+// This WORKS - conditional type on individual prop
+interface Props {
+  value: SomeType extends string ? string : number  // OK
+}
+
+defineProps<Props>()
+</script>
+```
+
+### Global Ambient Types
+
+```typescript
+// global.d.ts (ambient declaration without export)
+interface GlobalUser {
+  id: string
+  name: string
+}
+
+// No export statement - this is an ambient declaration
+```
+
+```vue
+<script setup lang="ts">
+// ERROR: "Unresolvable type reference"
+defineProps<{
+  user: GlobalUser  // Can't resolve ambient global type
+}>()
+</script>
+```
+
+**Workaround:**
+```typescript
+// types/user.ts - Use explicit export
+export interface GlobalUser {
+  id: string
+  name: string
+}
+```
+
+```vue
+<script setup lang="ts">
+import type { GlobalUser } from '@/types/user'
+
+// WORKS: Explicitly imported
+defineProps<{
+  user: GlobalUser
+}>()
+</script>
+```
+
+### Complex Mapped Types
+
+```typescript
+// types/complex.ts
+export type DeepReadonly<T> = {
+  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P]
+}
+
+export interface User {
+  id: string
+  profile: { name: string }
+}
+```
+
+```vue
+<script setup lang="ts">
+import type { DeepReadonly, User } from '@/types/complex'
+
+// May fail or produce incorrect types
+defineProps<{
+  user: DeepReadonly<User>
+}>()
+</script>
+```
+
+**Workaround:**
+```typescript
+// Resolve the type explicitly
+export interface ReadonlyUser {
+  readonly id: string
+  readonly profile: { readonly name: string }
+}
+```
+
+### Union of Imported Interfaces
+
+```typescript
+// types/forms.ts
+export interface TextInput { type: 'text'; value: string }
+export interface NumberInput { type: 'number'; value: number }
+```
+
+```vue
+<script setup lang="ts">
+import type { TextInput, NumberInput } from '@/types/forms'
+
+// Can cause issues in some Vue versions
+defineProps<{
+  input: TextInput | NumberInput
+}>()
+</script>
+```
+
+**Workaround:**
+```typescript
+// Define the union in the types file
+export type AnyInput = TextInput | NumberInput
+```
+
+```vue
+<script setup lang="ts">
+import type { AnyInput } from '@/types/forms'
+
+defineProps<{
+  input: AnyInput
+}>()
+</script>
+```
+
+## Best Practices
+
+### Keep Props Types Simple
+
+```typescript
+// GOOD: Simple, explicit interface
+export interface ButtonProps {
+  variant: 'primary' | 'secondary' | 'danger'
+  size: 'sm' | 'md' | 'lg'
+  disabled?: boolean
+  loading?: boolean
+}
+
+// AVOID: Over-engineered generic types
+export type ButtonProps<V extends string, S extends string> = {
+  variant: V
+  size: S
+  // ...complex type gymnastics
+}
+```
+
+### Resolve Types Before Export
+
+```typescript
+// Instead of exporting generic utilities
+// export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
+
+// Export the resolved type
+export interface CreateUserProps {
+  name: string
+  email: string
+  age?: number  // Made optional
+  role?: 'admin' | 'user'  // Made optional
+}
+```
+
+### Use Dual Script Blocks for Complex Cases
+
+```vue
+<script lang="ts">
+// Regular script block for complex type definitions
+import type { ComplexType } from '@/types'
+
+// Resolve the type here
+type ResolvedProps = ComplexType extends SomeCondition
+  ? { a: string }
+  : { b: number }
+</script>
+
+<script setup lang="ts">
+// Use the resolved type
+defineProps<ResolvedProps>()
+</script>
+```
+
+## Version-Specific Behavior
+
+| Vue Version | Imported Types | Complex Types |
+|-------------|---------------|---------------|
+| 3.2 | Not supported | Not supported |
+| 3.3 | Supported | Limited |
+| 3.4+ | Supported | Better support |
+
+Always check the Vue changelog for updates to type support in defineProps.
+
+## Reference
+- [Vue.js TypeScript with Composition API](https://vuejs.org/guide/typescript/composition-api.html)
+- [GitHub Issue: defineProps with imported interfaces](https://github.com/vuejs/core/issues/8612)
+- [GitHub Issue: Union types in defineProps](https://github.com/vuejs/core/issues/5804)

package/skills/vue-debug-guides/reference/ts-event-handler-explicit-typing.md

@@ -0,0 +1,213 @@
+---
+title: Always Explicitly Type Event Handlers
+impact: MEDIUM
+impactDescription: Without explicit typing, event parameters have implicit 'any' type causing TypeScript errors in strict mode
+type: gotcha
+tags: [vue3, typescript, events, dom-events, composition-api]
+---
+
+# Always Explicitly Type Event Handlers
+
+**Impact: MEDIUM** - Native DOM event handlers in Vue components have implicit `any` type for the `event` parameter. In TypeScript strict mode, this causes errors. You must explicitly type event parameters and use type assertions for `event.target`.
+
+## Task Checklist
+
+- [ ] Always type the `event` parameter explicitly (e.g., `Event`, `MouseEvent`)
+- [ ] Use type assertions when accessing element-specific properties
+- [ ] Consider using inline handlers for simple cases
+- [ ] Be aware of Vue's synthetic event system
+
+## The Problem
+
+```vue
+<script setup lang="ts">
+// WRONG: event has implicit 'any' type
+function handleChange(event) {  // Error in strict mode!
+  console.log(event.target.value)  // Also error: target might be null
+}
+
+// WRONG: Missing type assertion for element access
+function handleInput(event: Event) {
+  console.log(event.target.value)  // Error: 'value' doesn't exist on EventTarget
+}
+</script>
+
+<template>
+  <input @change="handleChange" @input="handleInput" />
+</template>
+```
+
+## The Solution
+
+```vue
+<script setup lang="ts">
+// CORRECT: Explicit Event type + type assertion
+function handleChange(event: Event) {
+  const target = event.target as HTMLInputElement
+  console.log(target.value)
+}
+
+// CORRECT: Specific event type when needed
+function handleClick(event: MouseEvent) {
+  console.log(event.clientX, event.clientY)
+}
+
+function handleKeydown(event: KeyboardEvent) {
+  if (event.key === 'Enter') {
+    submitForm()
+  }
+}
+
+function handleSubmit(event: SubmitEvent) {
+  event.preventDefault()
+  const formData = new FormData(event.target as HTMLFormElement)
+}
+</script>
+
+<template>
+  <input @change="handleChange" />
+  <button @click="handleClick">Click</button>
+  <input @keydown="handleKeydown" />
+  <form @submit="handleSubmit">...</form>
+</template>
+```
+
+## Common Event Types
+
+| Event | Type | Common Properties |
+|-------|------|-------------------|
+| click, dblclick | `MouseEvent` | clientX, clientY, button |
+| keydown, keyup, keypress | `KeyboardEvent` | key, code, ctrlKey, shiftKey |
+| input, change | `Event` | target (needs assertion) |
+| focus, blur | `FocusEvent` | relatedTarget |
+| submit | `SubmitEvent` | submitter |
+| drag, dragstart, drop | `DragEvent` | dataTransfer |
+| wheel, scroll | `WheelEvent` | deltaX, deltaY |
+| touch events | `TouchEvent` | touches, changedTouches |
+
+## Element-Specific Type Assertions
+
+```vue
+<script setup lang="ts">
+// HTMLInputElement for text, number, checkbox, radio inputs
+function handleTextInput(event: Event) {
+  const input = event.target as HTMLInputElement
+  console.log(input.value, input.checked)
+}
+
+// HTMLSelectElement for select dropdowns
+function handleSelect(event: Event) {
+  const select = event.target as HTMLSelectElement
+  console.log(select.value, select.selectedIndex)
+}
+
+// HTMLTextAreaElement for textareas
+function handleTextarea(event: Event) {
+  const textarea = event.target as HTMLTextAreaElement
+  console.log(textarea.value, textarea.selectionStart)
+}
+
+// HTMLFormElement for forms
+function handleFormSubmit(event: SubmitEvent) {
+  event.preventDefault()
+  const form = event.target as HTMLFormElement
+  const formData = new FormData(form)
+}
+</script>
+```
+
+## Inline Event Handler Pattern
+
+For simple cases, inline handlers with type annotations work well:
+
+```vue
+<template>
+  <!-- Inline with type assertion -->
+  <input
+    @input="(event: Event) => {
+      const input = event.target as HTMLInputElement
+      searchQuery = input.value
+    }"
+  />
+
+  <!-- Or with $event cast -->
+  <input @input="searchQuery = ($event.target as HTMLInputElement).value" />
+</template>
+```
+
+## Generic Handler Pattern
+
+Create reusable typed handlers:
+
+```typescript
+// utils/events.ts
+export function getInputValue(event: Event): string {
+  return (event.target as HTMLInputElement).value
+}
+
+export function getSelectValue(event: Event): string {
+  return (event.target as HTMLSelectElement).value
+}
+
+export function getCheckboxChecked(event: Event): boolean {
+  return (event.target as HTMLInputElement).checked
+}
+```
+
+```vue
+<script setup lang="ts">
+import { getInputValue, getCheckboxChecked } from '@/utils/events'
+
+const name = ref('')
+const agreed = ref(false)
+</script>
+
+<template>
+  <input @input="e => name = getInputValue(e)" />
+  <input type="checkbox" @change="e => agreed = getCheckboxChecked(e)" />
+</template>
+```
+
+## Vue Component Events
+
+For Vue component events (not DOM events), use `defineEmits` for type safety:
+
+```vue
+<script setup lang="ts">
+const emit = defineEmits<{
+  'custom-event': [data: { id: number; name: string }]
+}>()
+
+// Handler for child component event
+function handleChildEvent(data: { id: number; name: string }) {
+  console.log(data.id, data.name)
+}
+</script>
+
+<template>
+  <!-- Custom component event - properly typed -->
+  <ChildComponent @custom-event="handleChildEvent" />
+</template>
+```
+
+## Avoiding currentTarget vs target Confusion
+
+```typescript
+function handleClick(event: MouseEvent) {
+  // target: The element that triggered the event (could be a child)
+  const target = event.target as HTMLElement
+
+  // currentTarget: The element the listener is attached to
+  const currentTarget = event.currentTarget as HTMLButtonElement
+
+  // Be explicit about which you need
+  if (target.tagName === 'SPAN') {
+    // Clicked on span inside button
+  }
+}
+```
+
+## Reference
+- [Vue.js TypeScript with Composition API - Event Handlers](https://vuejs.org/guide/typescript/composition-api.html#typing-event-handlers)
+- [MDN Event Reference](https://developer.mozilla.org/en-US/docs/Web/Events)
+- [TypeScript DOM Types](https://github.com/microsoft/TypeScript/blob/main/lib/lib.dom.d.ts)

package/skills/vue-debug-guides/reference/ts-reactive-no-generic-argument.md

@@ -0,0 +1,196 @@
+---
+title: Do Not Use Generic Argument with reactive()
+impact: MEDIUM
+impactDescription: The generic argument type differs from the actual return type due to ref unwrapping, causing type mismatches
+type: gotcha
+tags: [vue3, typescript, reactive, ref-unwrapping, composition-api]
+---
+
+# Do Not Use Generic Argument with reactive()
+
+**Impact: MEDIUM** - It is NOT recommended to use the generic argument of `reactive()` because the returned type, which handles nested ref unwrapping, is different from the generic argument type. Use interface annotation on the variable instead.
+
+## Task Checklist
+
+- [ ] Use type annotation on the variable, not generic argument
+- [ ] Understand that `reactive()` unwraps nested refs
+- [ ] For generic composables, use `shallowRef` or explicit `Ref<T>` typing
+- [ ] Prefer `ref()` for simple values to avoid these issues
+
+## The Problem
+
+```vue
+<script setup lang="ts">
+import { reactive, ref } from 'vue'
+
+interface Book {
+  title: string
+  year: number
+  author: Ref<string>  // Nested ref
+}
+
+// WRONG: Generic argument doesn't account for ref unwrapping
+const book = reactive<Book>({
+  title: 'Vue 3 Guide',
+  year: 2024,
+  author: ref('John Doe')
+})
+
+// TypeScript thinks book.author is Ref<string>
+// But at runtime, it's unwrapped to just string!
+book.author.value  // TypeScript: OK, Runtime: ERROR (author is a string, not a ref)
+</script>
+```
+
+## The Solution: Interface Annotation
+
+```vue
+<script setup lang="ts">
+import { reactive, ref } from 'vue'
+
+interface Book {
+  title: string
+  year?: number
+}
+
+// CORRECT: Annotate the variable, not the generic
+const book: Book = reactive({
+  title: 'Vue 3 Guide'
+})
+
+book.title = 'New Title'  // TypeScript knows this is string
+book.year = 2024         // TypeScript knows this is number | undefined
+</script>
+```
+
+## Why This Happens
+
+When you use `reactive()`, Vue automatically unwraps any nested refs:
+
+```typescript
+import { reactive, ref, Ref } from 'vue'
+
+const name = ref('John')
+const state = reactive({
+  name: name  // This is a Ref<string>
+})
+
+// At runtime, state.name is 'John' (string), NOT a Ref
+console.log(state.name)       // 'John' (not ref object)
+console.log(state.name.value) // Runtime error: .value doesn't exist
+
+// The ACTUAL return type is different from what you'd expect
+// reactive<{ name: Ref<string> }>() does NOT return { name: Ref<string> }
+// It returns { name: string } due to automatic unwrapping
+```
+
+## Correct Patterns
+
+### Pattern 1: Simple Interface Annotation
+
+```vue
+<script setup lang="ts">
+interface FormState {
+  name: string
+  email: string
+  age: number
+}
+
+const form: FormState = reactive({
+  name: '',
+  email: '',
+  age: 0
+})
+</script>
+```
+
+### Pattern 2: Partial for Optional Fields
+
+```vue
+<script setup lang="ts">
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+// Start with partial data
+const user: Partial<User> = reactive({})
+
+// Fill in later
+user.id = '123'
+user.name = 'John'
+</script>
+```
+
+### Pattern 3: Use ref() Instead
+
+For simpler cases, prefer `ref()` which has more predictable typing:
+
+```vue
+<script setup lang="ts">
+interface User {
+  id: string
+  name: string
+}
+
+// ref() works well with generics
+const user = ref<User>({
+  id: '1',
+  name: 'John'
+})
+
+// Access with .value - clear and predictable
+user.value.name = 'Jane'
+</script>
+```
+
+## Generic Composables: Use Ref<T> or shallowRef
+
+When working with generic type parameters in composables:
+
+```typescript
+// PROBLEM: Generic T with ref() causes UnwrapRef issues
+function useBroken<T>(initial: T) {
+  const state = ref(initial)  // Type becomes Ref<UnwrapRef<T>>
+  state.value = initial       // Error: T is not assignable to UnwrapRef<T>
+  return state
+}
+
+// SOLUTION 1: Use explicit Ref<T> type
+function useFixed1<T>(initial: T) {
+  const state: Ref<T> = ref(initial) as Ref<T>
+  return state
+}
+
+// SOLUTION 2: Use shallowRef (no unwrapping)
+function useFixed2<T>(initial: T) {
+  const state = shallowRef(initial)  // Properly typed as ShallowRef<T>
+  return state
+}
+```
+
+## When Generic Argument IS Safe
+
+For simple non-ref values without nested reactivity, the generic is safe:
+
+```typescript
+// Safe: no nested refs
+const state = reactive<{ count: number; name: string }>({
+  count: 0,
+  name: ''
+})
+
+// Also safe: explicit simple types
+const list = reactive<string[]>([])
+const map = reactive<Map<string, number>>(new Map())
+```
+
+The issue only arises when:
+1. You have nested Ref types in your interface
+2. You're using generic type parameters that might contain refs
+
+## Reference
+- [Vue.js TypeScript with Composition API - Typing reactive()](https://vuejs.org/guide/typescript/composition-api.html#typing-reactive)
+- [GitHub Issue: ref with generic type](https://github.com/vuejs/core/discussions/9564)
+- [Vue TypeScript Caveats Gist](https://gist.github.com/LinusBorg/e041ff635994b50b7cec9383c3a067f1)