mdk-skills 2.2.2 → 2.2.3

package/.claude/backups/20260510.145651/skills/vue/references/gotchas.md

@@ -1,438 +0,0 @@
-# Vue Common Gotchas & Edge Cases
-
-Critical Vue 3 gotchas that cause silent failures or hard-to-debug issues.
-
-> Based on [vuejs-ai/skills](https://github.com/vuejs-ai/skills) vue-best-practices. For comprehensive coverage (200+ rules), see the upstream repo.
-
-## Reactivity
-
-### Always Use `.value` When Accessing ref() in Scripts
-
-**Impact: HIGH** - Forgetting `.value` causes silent failures.
-
-```ts
-const count = ref(0)
-
-// WRONG
-count++           // Tries to increment the ref object
-count = 5         // Reassigns variable, loses reactivity
-items.push(4)     // Error: push is not a function
-
-// CORRECT
-count.value++
-count.value = 5
-items.value.push(4)
-
-// In templates - NO .value needed (Vue unwraps automatically)
-// {{ count }} works, not {{ count.value }}
-```
-
-### Never Destructure reactive() Objects Directly
-
-**Impact: HIGH** - Destructuring breaks reactive connection.
-
-```ts
-const state = reactive({ count: 0, name: 'Vue' })
-
-// WRONG - destructured variables lose reactivity
-const { count, name } = state
-state.count++
-console.log(count)  // Still 0!
-
-// CORRECT - use toRefs()
-const { count, name } = toRefs(state)
-state.count++
-console.log(count.value)  // 1
-
-// BEST - just use ref() instead of reactive()
-const count = ref(0)
-const name = ref('Vue')
-```
-
-### Proxy Identity Hazard with reactive()
-
-```ts
-const raw = {}
-const proxy = reactive(raw)
-
-// WRONG - comparing different objects
-console.log(proxy === raw) // false
-
-// WRONG - creating multiple proxies
-const a = reactive({})
-const b = reactive(a)  // Returns same proxy
-console.log(a === b) // true (same object)
-
-// GOTCHA - nested objects get proxied too
-const nested = reactive({ obj: {} })
-console.log(nested.obj === nested.obj) // true (same proxy)
-```
-
-## Computed Properties
-
-### No Side Effects in Computed Getters
-
-**Impact: HIGH** - Side effects break reactivity model.
-
-```ts
-// WRONG - mutates state
-const doubled = computed(() => {
-  count.value++  // Side effect!
-  return count.value * 2
-})
-
-// WRONG - async operation
-const data = computed(async () => {
-  return await fetch('/api')  // Side effect!
-})
-
-// CORRECT - pure computation only
-const doubled = computed(() => count.value * 2)
-
-// For side effects, use watch:
-watch(count, (newVal) => {
-  document.title = `Count: ${newVal}`
-})
-```
-
-### Computed Returns Are Read-Only
-
-```ts
-const fullName = computed(() => `${first.value} ${last.value}`)
-
-// WRONG - computed values are read-only
-fullName.value = 'John Doe'  // Error!
-
-// CORRECT - use writable computed
-const fullName = computed({
-  get: () => `${first.value} ${last.value}`,
-  set: (val) => {
-    const [f, l] = val.split(' ')
-    first.value = f
-    last.value = l
-  }
-})
-```
-
-## Watchers
-
-### Clean Up Async Operations to Prevent Race Conditions
-
-**Impact: HIGH** - Stale requests can overwrite newer data.
-
-```ts
-const query = ref('')
-const results = ref([])
-
-// WRONG - race condition
-watch(query, async (q) => {
-  const res = await fetch(`/api?q=${q}`)
-  results.value = await res.json()  // May overwrite newer results!
-})
-
-// CORRECT - use onWatcherCleanup (Vue 3.5+)
-watch(query, async (q) => {
-  const controller = new AbortController()
-  onWatcherCleanup(() => controller.abort())
-
-  try {
-    const res = await fetch(`/api?q=${q}`, { signal: controller.signal })
-    results.value = await res.json()
-  } catch (e) {
-    if (e.name !== 'AbortError') throw e
-  }
-})
-
-// Or use onCleanup parameter
-watch(query, async (q, oldQ, onCleanup) => {
-  const controller = new AbortController()
-  onCleanup(() => controller.abort())
-  // ... same as above
-})
-```
-
-### Deep Watch Returns Same Object Reference
-
-```ts
-const obj = reactive({ nested: { count: 0 } })
-
-// GOTCHA - oldValue === newValue for deep watches
-watch(obj, (newVal, oldVal) => {
-  console.log(newVal === oldVal)  // true! Same object
-}, { deep: true })
-
-// If you need old value, clone first:
-watch(
-  () => structuredClone(obj),
-  (newVal, oldVal) => { /* now different */ }
-)
-```
-
-## Props
-
-### Props Are Read-Only - Never Mutate
-
-**Impact: HIGH** - Breaks one-way data flow.
-
-```ts
-const props = defineProps<{ count: number; user: User }>()
-
-// WRONG - direct mutation
-props.count++  // Vue warning
-props.user.name = 'New'  // No warning but still wrong!
-
-// CORRECT - emit to parent
-const emit = defineEmits(['update:count', 'update-user'])
-emit('update:count', props.count + 1)
-emit('update-user', { ...props.user, name: 'New' })
-
-// Or create local copy
-const localUser = ref({ ...props.user })
-```
-
-### Destructured Props Don't Update Watchers (pre-3.5)
-
-```ts
-// WRONG (Vue < 3.5)
-const { count } = defineProps<{ count: number }>()
-watch(count, () => {})  // Won't trigger!
-
-// CORRECT - use getter
-const props = defineProps<{ count: number }>()
-watch(() => props.count, () => {})
-
-// Vue 3.5+ - destructuring works with reactive props
-const { count } = defineProps<{ count: number }>()
-watch(() => count, () => {})  // Works in 3.5+
-```
-
-## Lifecycle Hooks
-
-### Register Hooks Synchronously During Setup
-
-**Impact: HIGH** - Async hooks silently fail.
-
-```ts
-// WRONG - hook registered after await
-async setup() {
-  const data = await fetchData()
-  onMounted(() => {})  // Will NEVER run!
-}
-
-// WRONG - hook in setTimeout
-setup() {
-  setTimeout(() => {
-    onMounted(() => {})  // Will NEVER run!
-  }, 100)
-}
-
-// CORRECT - register synchronously, async inside
-setup() {
-  onMounted(async () => {
-    const data = await fetchData()
-  })
-}
-```
-
-## Templates
-
-### Never Use v-if with v-for on Same Element
-
-**Impact: HIGH** - Vue 2/3 precedence differs.
-
-```vue
-<!-- WRONG - ambiguous precedence -->
-<li v-for="user in users" v-if="user.active" :key="user.id">
-
-<!-- Vue 3: v-if runs FIRST, 'user' undefined! -->
-
-<!-- CORRECT - computed filter -->
-<li v-for="user in activeUsers" :key="user.id">
-
-<script setup>
-const activeUsers = computed(() => users.filter(u => u.active))
-</script>
-
-<!-- CORRECT - template wrapper -->
-<template v-for="user in users" :key="user.id">
-  <li v-if="user.active">{{ user.name }}</li>
-</template>
-```
-
-### Template Refs Are Null with v-if
-
-```ts
-const inputRef = ref<HTMLInputElement | null>(null)
-
-// GOTCHA - ref is null when element hidden
-<input v-if="show" ref="inputRef" />
-
-// WRONG - may be null
-inputRef.value.focus()  // Error if !show
-
-// CORRECT - null check
-inputRef.value?.focus()
-
-// Or use watchEffect with flush: 'post'
-watchEffect(() => {
-  inputRef.value?.focus()
-}, { flush: 'post' })
-```
-
-## defineModel
-
-### Object Mutations Don't Emit
-
-```ts
-const model = defineModel<{ name: string }>()
-
-// WRONG - mutation doesn't notify parent
-model.value.name = 'New'  // Parent won't know!
-
-// CORRECT - replace entire object
-model.value = { ...model.value, name: 'New' }
-```
-
-### Updated Value Needs nextTick
-
-```ts
-const model = defineModel<string>()
-
-// WRONG - value not updated yet
-model.value = 'new'
-console.log(model.value)  // Still old value!
-
-// CORRECT - wait for nextTick
-model.value = 'new'
-await nextTick()
-console.log(model.value)  // Now 'new'
-```
-
-## Component Events
-
-### Undeclared Emits Can Fire Twice
-
-```ts
-// WRONG - missing emit declaration causes double firing
-const emit = defineEmits([])  // 'click' not declared
-<button @click="emit('click')">  // Fires twice!
-
-// CORRECT - declare all custom events
-const emit = defineEmits(['click'])
-```
-
-### Events Don't Bubble Through Components
-
-```vue
-<!-- Parent can't listen to grandchild events directly -->
-<Grandparent>
-  <Parent>
-    <Child @custom="handler" />  <!-- Only Parent can listen -->
-  </Parent>
-</Grandparent>
-
-<!-- Solution: re-emit or use provide/inject -->
-```
-
-## Provide/Inject
-
-### Reactivity Not Automatic
-
-```ts
-// Provider
-const count = ref(0)
-provide('count', count)  // Pass the ref, not .value
-
-// Consumer
-const count = inject('count')  // Receives the ref
-console.log(count.value)  // Reactive!
-
-// WRONG - loses reactivity
-provide('count', count.value)  // Just passes number
-```
-
-### Must Call Provide Synchronously
-
-```ts
-// WRONG - provide after async
-async setup() {
-  await fetchData()
-  provide('key', value)  // Silently fails!
-}
-
-// CORRECT
-setup() {
-  provide('key', value)  // Synchronous
-  onMounted(async () => {
-    await fetchData()
-  })
-}
-```
-
-## SSR
-
-### Lifecycle Hooks Don't Run on Server
-
-```ts
-// onMounted, onUpdated, onUnmounted - client only
-onMounted(() => {
-  // Only runs in browser
-  window.addEventListener('resize', handler)
-})
-
-// For SSR, use onServerPrefetch for data
-onServerPrefetch(async () => {
-  data.value = await fetchData()
-})
-```
-
-### Hydration Mismatch Causes
-
-Common causes:
-
-- Browser-only APIs (`window`, `localStorage`)
-- Different timestamps
-- Random values
-- User-agent specific rendering
-
-```ts
-// WRONG
-const width = ref(window.innerWidth)  // undefined on server
-
-// CORRECT
-const width = ref(0)
-onMounted(() => {
-  width.value = window.innerWidth
-})
-```
-
-## Performance
-
-### Use shallowRef for Large Non-Reactive Data
-
-```ts
-// WRONG - deep reactivity overhead
-const hugeList = ref(thousandsOfItems)
-
-// CORRECT - only track .value assignment
-const hugeList = shallowRef(thousandsOfItems)
-
-// Trigger update by replacing entire array
-hugeList.value = [...hugeList.value, newItem]
-```
-
-### markRaw for Non-Reactive Objects
-
-```ts
-// WRONG - Chart.js instance becomes reactive (breaks it)
-const chart = ref(new Chart(ctx, config))
-
-// CORRECT - mark as non-reactive
-const chart = ref(markRaw(new Chart(ctx, config)))
-```
-
-## References
-
-- [vuejs-ai/skills vue-best-practices](https://github.com/vuejs-ai/skills/tree/main/skills/vue-best-practices) - Full 200+ rules
-- [Vue Style Guide](https://vuejs.org/style-guide/)
-- [Vue 3 Migration Guide](https://v3-migration.vuejs.org/)

package/.claude/backups/20260510.145651/skills/vue/references/provide-inject.md

@@ -1,174 +0,0 @@
----
-name: Provide / Inject
-description: Pass data through component tree without prop drilling
----
-
-# Provide / Inject
-
-Provide data from ancestor components to any descendant, avoiding prop drilling.
-
-## Basic Usage
-
-```vue
-<!-- Provider.vue -->
-<script setup lang="ts">
-import { provide, ref } from 'vue'
-
-const message = ref('hello')
-provide('message', message)
-</script>
-```
-
-```vue
-<!-- DeepChild.vue (any level deep) -->
-<script setup lang="ts">
-import { inject } from 'vue'
-
-const message = inject('message')
-</script>
-```
-
-## Typing with InjectionKey
-
-Use `InjectionKey` for type safety between provider and injector:
-
-```ts
-// keys.ts
-import type { InjectionKey, Ref } from 'vue'
-
-export const messageKey = Symbol() as InjectionKey<Ref<string>>
-export const countKey = Symbol() as InjectionKey<number>
-```
-
-```vue
-<!-- Provider.vue -->
-<script setup lang="ts">
-import { provide, ref } from 'vue'
-import { messageKey } from './keys'
-
-const message = ref('hello')
-provide(messageKey, message)
-</script>
-```
-
-```vue
-<!-- Injector.vue -->
-<script setup lang="ts">
-import { inject } from 'vue'
-import { messageKey } from './keys'
-
-const message = inject(messageKey) // Ref<string> | undefined
-</script>
-```
-
-## Default Values
-
-```ts
-// Simple default
-const value = inject('message', 'default value')
-
-// Factory function (for expensive defaults)
-const value = inject('key', () => new ExpensiveClass(), true)
-//                                                       ^ treat as factory
-```
-
-## App-Level Provide
-
-Available to all components:
-
-```ts
-// main.ts
-import { createApp } from 'vue'
-
-const app = createApp(App)
-app.provide('globalConfig', { theme: 'dark' })
-```
-
-## Reactive Provide/Inject
-
-Provide reactive values for automatic updates:
-
-```vue
-<!-- Provider.vue -->
-<script setup lang="ts">
-import { provide, ref } from 'vue'
-
-const count = ref(0)
-provide('count', count)
-</script>
-```
-
-The injected value maintains reactivity connection.
-
-## Mutations Best Practice
-
-Keep mutations in the provider, expose update functions:
-
-```vue
-<!-- Provider.vue -->
-<script setup lang="ts">
-import { provide, ref, readonly } from 'vue'
-
-const location = ref('North Pole')
-
-function updateLocation(newLocation: string) {
-  location.value = newLocation
-}
-
-provide('location', {
-  location: readonly(location), // Prevent direct mutation
-  updateLocation
-})
-</script>
-```
-
-```vue
-<!-- Injector.vue -->
-<script setup lang="ts">
-import { inject } from 'vue'
-
-const { location, updateLocation } = inject('location')!
-</script>
-
-<template>
-  <button @click="updateLocation('South Pole')">
-    {{ location }}
-  </button>
-</template>
-```
-
-## Using Symbol Keys
-
-Recommended for libraries and large apps to avoid collisions:
-
-```ts
-// keys.ts
-export const myKey = Symbol('myKey')
-
-// provider
-provide(myKey, value)
-
-// injector
-inject(myKey)
-```
-
-## Type Helpers
-
-```ts
-// String key with explicit type
-const foo = inject<string>('foo')
-//    ^? string | undefined
-
-// With default (removes undefined)
-const foo = inject<string>('foo', 'default')
-//    ^? string
-
-// Force non-undefined (use when certain it's provided)
-const foo = inject('foo') as string
-```
-
-<!--
-Source references:
-- https://vuejs.org/guide/components/provide-inject.html
-- https://vuejs.org/guide/typescript/composition-api.html#typing-provide-inject
--->