@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/ts-shallowref-for-dynamic-components.md

@@ -0,0 +1,218 @@
+---
+title: Use shallowRef for Dynamic Component References
+impact: MEDIUM
+impactDescription: Storing components in reactive() or ref() triggers Vue warnings and can cause performance issues
+type: gotcha
+tags: [typescript, shallowRef, dynamic-components, reactivity, performance]
+---
+
+# Use shallowRef for Dynamic Component References
+
+**Impact: MEDIUM** - When storing Vue components in reactive state for dynamic rendering, using `ref()` or `reactive()` causes Vue warnings and unnecessary reactivity overhead. Use `shallowRef()` instead.
+
+## Task Checklist
+
+- [ ] Use `shallowRef` for storing component references
+- [ ] Use `markRaw` when storing components in reactive objects
+- [ ] Avoid wrapping component definitions with deep reactivity
+- [ ] Check console for "[Vue warn]: Vue received a Component that was made a reactive object"
+
+## The Problem
+
+Vue components are objects with internal properties that should not be made reactive. When you store a component in `ref()` or `reactive()`, Vue traverses all properties deeply, which:
+
+1. Triggers a console warning
+2. Creates unnecessary reactive proxies
+3. Can cause subtle bugs with component identity
+4. Impacts performance
+
+**Incorrect - Using ref() for components:**
+```typescript
+import { ref } from 'vue'
+import ComponentA from './ComponentA.vue'
+import ComponentB from './ComponentB.vue'
+
+// BAD: Vue will warn about making component reactive
+const currentComponent = ref(ComponentA)
+
+function switchComponent() {
+  currentComponent.value = ComponentB
+}
+```
+
+**Console warning:**
+```
+[Vue warn]: Vue received a Component that was made a reactive object.
+This can lead to unnecessary performance overhead and should be avoided
+by marking the component with `markRaw` or using `shallowRef` instead of `ref`.
+```
+
+## Solution 1: Use shallowRef
+
+`shallowRef` only makes the `.value` reference reactive, not the contents:
+
+```typescript
+import { shallowRef, type Component } from 'vue'
+import ComponentA from './ComponentA.vue'
+import ComponentB from './ComponentB.vue'
+
+// CORRECT: shallowRef doesn't deep-proxy the component
+const currentComponent = shallowRef<Component>(ComponentA)
+
+function switchComponent() {
+  currentComponent.value = ComponentB
+}
+```
+
+```vue
+<template>
+  <component :is="currentComponent" />
+</template>
+```
+
+## Solution 2: Use markRaw in Reactive Objects
+
+When components are part of a larger reactive object:
+
+```typescript
+import { reactive, markRaw, type Component } from 'vue'
+import TabHome from './TabHome.vue'
+import TabProfile from './TabProfile.vue'
+import TabSettings from './TabSettings.vue'
+
+interface Tab {
+  name: string
+  component: Component
+}
+
+// CORRECT: markRaw prevents reactivity on component objects
+const tabs = reactive<Tab[]>([
+  { name: 'Home', component: markRaw(TabHome) },
+  { name: 'Profile', component: markRaw(TabProfile) },
+  { name: 'Settings', component: markRaw(TabSettings) }
+])
+
+const activeTab = shallowRef<Tab>(tabs[0])
+```
+
+```vue
+<template>
+  <div class="tabs">
+    <button
+      v-for="tab in tabs"
+      :key="tab.name"
+      @click="activeTab = tab"
+    >
+      {{ tab.name }}
+    </button>
+  </div>
+  <component :is="activeTab.component" />
+</template>
+```
+
+## TypeScript Typing
+
+For proper TypeScript support with dynamic components:
+
+```typescript
+import { shallowRef, type Component, type DefineComponent } from 'vue'
+
+// Generic component type
+const currentComponent = shallowRef<Component | null>(null)
+
+// Or more specific with props
+interface MyComponentProps {
+  title: string
+}
+
+const currentComponent = shallowRef<DefineComponent<MyComponentProps> | null>(null)
+```
+
+## Dynamic Import with shallowRef
+
+When using dynamic imports for code splitting:
+
+```typescript
+import { shallowRef, defineAsyncComponent, type Component } from 'vue'
+
+const currentComponent = shallowRef<Component | null>(null)
+
+async function loadComponent(name: string) {
+  const component = defineAsyncComponent(
+    () => import(`./components/${name}.vue`)
+  )
+  currentComponent.value = component
+}
+```
+
+## Component Registry Pattern
+
+For tab systems or wizard-like interfaces:
+
+```typescript
+import { shallowRef, markRaw, type Component } from 'vue'
+
+// Type-safe component registry
+const componentRegistry = {
+  home: markRaw(defineAsyncComponent(() => import('./Home.vue'))),
+  about: markRaw(defineAsyncComponent(() => import('./About.vue'))),
+  contact: markRaw(defineAsyncComponent(() => import('./Contact.vue')))
+} as const
+
+type ComponentKey = keyof typeof componentRegistry
+
+const currentView = shallowRef<ComponentKey>('home')
+
+// Computed to get current component
+const currentComponent = computed(() => componentRegistry[currentView.value])
+```
+
+```vue
+<template>
+  <component :is="currentComponent" />
+</template>
+```
+
+## When to Use Each Approach
+
+| Scenario | Solution |
+|----------|----------|
+| Single dynamic component reference | `shallowRef` |
+| Component in reactive array/object | `markRaw` on component |
+| Component map/registry | `markRaw` each component |
+| Async components | `defineAsyncComponent` + `shallowRef` |
+
+## Common Mistakes
+
+### Mistake 1: Using computed with ref
+
+```typescript
+// BAD: Still triggers warning
+const components = ref([ComponentA, ComponentB])
+const current = computed(() => components.value[index.value])
+
+// GOOD: Use shallowRef for the array
+const components = shallowRef([ComponentA, ComponentB])
+```
+
+### Mistake 2: Forgetting markRaw in map
+
+```typescript
+// BAD: Components in map become reactive
+const routes = reactive(new Map([
+  ['home', HomeComponent],
+  ['about', AboutComponent]
+]))
+
+// GOOD: Mark each component as raw
+const routes = reactive(new Map([
+  ['home', markRaw(HomeComponent)],
+  ['about', markRaw(AboutComponent)]
+]))
+```
+
+## Reference
+
+- [Vue.js Reactivity in Depth - Reducing Reactivity Overhead](https://vuejs.org/guide/extras/reactivity-in-depth.html#reducing-reactivity-overhead-for-large-immutable-structures)
+- [Vue.js API - shallowRef](https://vuejs.org/api/reactivity-advanced.html#shallowref)
+- [Vue.js API - markRaw](https://vuejs.org/api/reactivity-advanced.html#markraw)

package/skills/vue-debug-guides/reference/ts-template-ref-null-handling.md

@@ -0,0 +1,249 @@
+---
+title: Template Refs Are Null Until Mounted
+impact: HIGH
+impactDescription: Accessing template ref before mount or after unmount causes runtime errors
+type: gotcha
+tags: [vue3, typescript, template-refs, lifecycle, null-safety]
+---
+
+# Template Refs Are Null Until Mounted
+
+**Impact: HIGH** - Template refs have an initial value of `null` and remain null until the component mounts. They can also become null again if the referenced element is removed by `v-if`. Always account for this in TypeScript with union types and optional chaining.
+
+## Task Checklist
+
+- [ ] Always type template refs with `| null` union
+- [ ] Only access refs inside `onMounted` or after
+- [ ] Use optional chaining (`?.`) when accessing ref properties
+- [ ] Handle `v-if` scenarios where ref can become null again
+- [ ] Consider using `useTemplateRef` in Vue 3.5+
+
+## The Problem
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+
+// WRONG: Doesn't account for null
+const inputRef = ref<HTMLInputElement>()
+
+// WRONG: Will crash if accessed before mount
+inputRef.value.focus()  // Error: Cannot read properties of null
+
+// WRONG: Accessed in setup, element doesn't exist yet
+console.log(inputRef.value.value)  // Error!
+</script>
+
+<template>
+  <input ref="inputRef" />
+</template>
+```
+
+## The Solution
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+
+// CORRECT: Include null in the type
+const inputRef = ref<HTMLInputElement | null>(null)
+
+// CORRECT: Access in onMounted when DOM exists
+onMounted(() => {
+  inputRef.value?.focus()  // Safe with optional chaining
+})
+
+// CORRECT: Guard before accessing
+function focusInput() {
+  if (inputRef.value) {
+    inputRef.value.focus()
+  }
+}
+</script>
+
+<template>
+  <input ref="inputRef" />
+</template>
+```
+
+## Vue 3.5+: useTemplateRef
+
+Vue 3.5 introduces `useTemplateRef` with better type inference:
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef, onMounted } from 'vue'
+
+// Type is automatically inferred for static refs
+const inputRef = useTemplateRef<HTMLInputElement>('input')
+
+onMounted(() => {
+  inputRef.value?.focus()
+})
+</script>
+
+<template>
+  <input ref="input" />
+</template>
+```
+
+## Handling v-if Scenarios
+
+Refs can become `null` when elements are conditionally rendered:
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+
+const showModal = ref(false)
+const modalRef = ref<HTMLDivElement | null>(null)
+
+// WRONG: Assuming ref always exists after first mount
+function closeModal() {
+  modalRef.value.classList.remove('open')  // May be null!
+}
+
+// CORRECT: Always guard access
+function closeModal() {
+  modalRef.value?.classList.remove('open')
+}
+
+// CORRECT: Watch for ref changes
+watch(modalRef, (newRef) => {
+  if (newRef) {
+    // Modal element just mounted
+    newRef.focus()
+  }
+  // If null, modal was unmounted
+})
+</script>
+
+<template>
+  <div v-if="showModal" ref="modalRef" class="modal">
+    Modal content
+  </div>
+</template>
+```
+
+## Component Refs
+
+For component refs, use `InstanceType`:
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import ChildComponent from './ChildComponent.vue'
+
+// Component ref with null
+const childRef = ref<InstanceType<typeof ChildComponent> | null>(null)
+
+onMounted(() => {
+  // Access exposed methods/properties
+  childRef.value?.exposedMethod()
+})
+</script>
+
+<template>
+  <ChildComponent ref="childRef" />
+</template>
+```
+
+Remember: Child components must use `defineExpose` to expose methods:
+
+```vue
+<!-- ChildComponent.vue -->
+<script setup lang="ts">
+function exposedMethod() {
+  console.log('Called from parent')
+}
+
+defineExpose({
+  exposedMethod
+})
+</script>
+```
+
+## Multiple Refs with v-for
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+
+const items = ref(['a', 'b', 'c'])
+
+// Array of refs for v-for
+const itemRefs = ref<(HTMLLIElement | null)[]>([])
+
+onMounted(() => {
+  // Access specific item
+  itemRefs.value[0]?.focus()
+
+  // Iterate safely
+  itemRefs.value.forEach(el => {
+    el?.classList.add('mounted')
+  })
+})
+</script>
+
+<template>
+  <ul>
+    <li
+      v-for="(item, index) in items"
+      :key="item"
+      :ref="el => { itemRefs[index] = el as HTMLLIElement }"
+    >
+      {{ item }}
+    </li>
+  </ul>
+</template>
+```
+
+## Async Operations and Refs
+
+Be careful with async operations:
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+
+const containerRef = ref<HTMLDivElement | null>(null)
+
+onMounted(async () => {
+  // containerRef.value exists here
+
+  await fetchData()
+
+  // CAREFUL: Component might have unmounted during await
+  // Always re-check before accessing
+  if (containerRef.value) {
+    containerRef.value.scrollTop = 0
+  }
+})
+</script>
+```
+
+## Type Guard Pattern
+
+Create a reusable type guard for cleaner code:
+
+```typescript
+// utils/refs.ts
+export function assertRef<T>(
+  ref: Ref<T | null>,
+  message = 'Ref is not available'
+): asserts ref is Ref<T> {
+  if (ref.value === null) {
+    throw new Error(message)
+  }
+}
+
+// Usage in component
+function mustFocus() {
+  assertRef(inputRef, 'Input element not mounted')
+  inputRef.value.focus()  // TypeScript knows it's not null here
+}
+```
+
+## Reference
+- [Vue.js TypeScript with Composition API - Template Refs](https://vuejs.org/guide/typescript/composition-api.html#typing-template-refs)
+- [Vue.js Template Refs](https://vuejs.org/guide/essentials/template-refs.html)

package/skills/vue-debug-guides/reference/ts-template-type-casting.md

@@ -0,0 +1,214 @@
+---
+title: Use Type Casting in Templates for Union Types
+impact: MEDIUM
+impactDescription: Template expressions with union types cause TypeScript errors even when the runtime type is known
+type: gotcha
+tags: [typescript, templates, type-casting, union-types, script-setup]
+---
+
+# Use Type Casting in Templates for Union Types
+
+**Impact: MEDIUM** - When using `lang="ts"` in Vue Single File Components, template expressions get strict type checking. If a variable has a union type, you may need inline type casting to access type-specific methods or properties.
+
+## Task Checklist
+
+- [ ] Use `(value as Type)` syntax for type casting in templates
+- [ ] Consider narrowing types in script before using in template
+- [ ] Remember template type checking requires `lang="ts"` attribute
+- [ ] For Vue CLI/webpack: ensure vue-loader >= 16.8.0
+
+## The Problem
+
+When a variable has a union type, TypeScript cannot know which specific type it is at template compile time:
+
+**Template with type error:**
+```vue
+<script setup lang="ts">
+// Union type: could be string OR number
+let x: string | number = 1
+</script>
+
+<template>
+  <!-- ERROR: Property 'toFixed' does not exist on type 'string | number' -->
+  {{ x.toFixed(2) }}
+</template>
+```
+
+TypeScript correctly identifies that `toFixed()` only exists on `number`, not `string`.
+
+## Solution 1: Inline Type Casting
+
+Use `(value as Type)` syntax directly in the template:
+
+```vue
+<script setup lang="ts">
+let x: string | number = 1
+</script>
+
+<template>
+  <!-- CORRECT: Cast to number to access toFixed -->
+  {{ (x as number).toFixed(2) }}
+</template>
+```
+
+## Solution 2: Computed Property (Preferred)
+
+Create a computed property that narrows or transforms the type:
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+
+const value = ref<string | number>(1)
+
+const formattedValue = computed(() => {
+  if (typeof value.value === 'number') {
+    return value.value.toFixed(2)
+  }
+  return value.value
+})
+</script>
+
+<template>
+  <!-- Clean template, type-safe logic in script -->
+  {{ formattedValue }}
+</template>
+```
+
+## Solution 3: Type Guard Function
+
+Define a type guard and use it in the template:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const data = ref<string | number | null>(null)
+
+function isNumber(val: unknown): val is number {
+  return typeof val === 'number'
+}
+
+function formatNumber(val: number): string {
+  return val.toFixed(2)
+}
+</script>
+
+<template>
+  <div v-if="isNumber(data)">
+    {{ formatNumber(data) }}
+  </div>
+  <div v-else-if="data !== null">
+    {{ data }}
+  </div>
+</template>
+```
+
+## Common Use Cases
+
+### API Response Data
+
+```vue
+<script setup lang="ts">
+interface ApiResponse {
+  status: 'success' | 'error'
+  data?: UserData
+  error?: string
+}
+
+const response = ref<ApiResponse | null>(null)
+</script>
+
+<template>
+  <div v-if="response?.status === 'success'">
+    <!-- Cast to access data safely -->
+    {{ (response as { data: UserData }).data.name }}
+  </div>
+</template>
+```
+
+**Better approach with computed:**
+```vue
+<script setup lang="ts">
+const userData = computed(() => {
+  if (response.value?.status === 'success') {
+    return response.value.data
+  }
+  return null
+})
+</script>
+
+<template>
+  <div v-if="userData">
+    {{ userData.name }}
+  </div>
+</template>
+```
+
+### Event Handlers with Event Types
+
+```vue
+<script setup lang="ts">
+function handleInput(event: Event) {
+  // Cast to HTMLInputElement to access 'value'
+  const value = (event.target as HTMLInputElement).value
+  console.log(value)
+}
+</script>
+
+<template>
+  <input @input="handleInput" />
+</template>
+```
+
+### Array Item Access
+
+```vue
+<script setup lang="ts">
+const items = ref<(string | number)[]>([1, 'two', 3])
+</script>
+
+<template>
+  <ul>
+    <li v-for="item in items" :key="item">
+      <!-- Cast when you know the type -->
+      <span v-if="typeof item === 'number'">
+        Number: {{ (item as number).toFixed(1) }}
+      </span>
+      <span v-else>
+        String: {{ (item as string).toUpperCase() }}
+      </span>
+    </li>
+  </ul>
+</template>
+```
+
+## When Type Casting is Needed
+
+| Scenario | Solution |
+|----------|----------|
+| Union types | Cast to specific type |
+| Nullable types | Use optional chaining or cast after null check |
+| Event targets | Cast `event.target` to specific element type |
+| Array methods | Cast when TS can't narrow array item types |
+
+## Important Notes
+
+### Template Type Checking Requirements
+
+Template type checking is enabled when:
+1. `<script lang="ts">` or `<script setup lang="ts">` is used
+2. Vue Language Server (Volar) is active in your IDE
+3. For webpack: vue-loader >= 16.8.0 is required
+
+### Avoid Excessive Casting
+
+If you find yourself casting frequently in templates, consider:
+- Moving logic to computed properties
+- Using type guards in the script section
+- Refactoring data structures to be more specific
+
+## Reference
+
+- [Vue.js TypeScript Overview - TypeScript in Templates](https://vuejs.org/guide/typescript/overview.html#typescript-in-templates)
+- [Vue.js TypeScript with Composition API](https://vuejs.org/guide/typescript/composition-api.html)