mdk-skills 2.1.3

package/.claude/skills/vue/references/components.md

@@ -0,0 +1,323 @@
+# Vue Components
+
+Patterns for Vue 3 components using Composition API with `<script setup>`.
+
+## Quick Reference
+
+| Pattern               | Syntax                                                          |
+| --------------------- | --------------------------------------------------------------- |
+| Props (destructured)  | `const { name = 'default' } = defineProps<{ name?: string }>()` |
+| Props (template-only) | `defineProps<{ name: string }>()`                               |
+| Emits                 | `const emit = defineEmits<{ click: [id: number] }>()`           |
+| Two-way binding       | `const model = defineModel<string>()`                           |
+| Slots shorthand       | `<template #header>` not `<template v-slot:header>`             |
+
+## Naming
+
+**Files:** PascalCase (`UserProfile.vue`) OR kebab-case (`user-profile.vue`) - be consistent
+
+**Component names in code:** Always PascalCase
+
+**Composition:** General → Specific: `SearchButtonClear.vue` not `ClearSearchButton.vue`
+
+## Props
+
+**Destructure with defaults (Vue 3.5+)** when used in script or need defaults:
+
+```ts
+const { count = 0, message = 'Hello' } = defineProps<{
+  count?: number
+  message?: string
+  required: boolean
+}>()
+
+// Use directly - maintains reactivity
+console.log(count + 1)
+
+// ⚠️ When passing to watchers/functions, wrap in getter:
+watch(() => count, (newVal) => { ... }) // ✅ Correct
+watch(count, (newVal) => { ... })        // ❌ Won't work
+```
+
+**Non-destructured** only if props ONLY used in template:
+
+```ts
+defineProps<{ count: number }>()
+// Template: {{ count }}
+```
+
+**Same-name shorthand (Vue 3.4+):** `:count` instead of `:count="count"`
+
+```vue
+<MyComponent :count :user :items />
+<!-- Same as: :count="count" :user="user" :items="items" -->
+```
+
+[Reactive destructuring docs](https://vuejs.org/guide/components/props#reactive-props-destructure)
+
+## Emits
+
+Type-safe event definitions:
+
+```ts
+const emit = defineEmits<{
+  update: [id: number, value: string] // multiple args
+  close: [] // no args
+}>()
+
+// Usage
+emit('update', 123, 'new value')
+emit('close')
+```
+
+**Template syntax:** kebab-case (`@update-item`) vs camelCase in script (`updateItem`)
+
+## Slots
+
+**Always use shorthand:** `<template #header>` not `<template v-slot:header>`
+
+**Always explicit `<template>` tags** for all slots
+
+```vue
+<template>
+  <Card>
+    <template #header>
+      <h2>Title</h2>
+    </template>
+    <template #default>
+      Content
+    </template>
+  </Card>
+</template>
+```
+
+## defineModel() - Two-Way Binding
+
+Replaces manual `modelValue` prop + `update:modelValue` emit.
+
+### Basic
+
+```vue
+<script setup lang="ts">
+const title = defineModel<string>()
+</script>
+
+<template>
+  <input v-model="title">
+</template>
+```
+
+### With Options
+
+```vue
+<script setup lang="ts">
+const [title, modifiers] = defineModel<string>({
+  default: 'default value',
+  required: true,
+  get: (value) => value.trim(),
+  set: (value) => {
+    if (modifiers.capitalize) {
+      return value.charAt(0).toUpperCase() + value.slice(1)
+    }
+    return value
+  },
+})
+</script>
+```
+
+**⚠️ Warning:** When using `default` without parent providing a value, parent and child can de-sync (parent `undefined`, child has default). Always provide matching defaults in parent or make prop required.
+
+**Prevent double-emit with `required: true`:**
+
+```ts
+// ❌ Without required - emits twice (undefined then value)
+const model = defineModel<Item>()
+
+// ✅ With required - single emit
+const model = defineModel<Item>({ required: true })
+```
+
+Use `required: true` when the model should always have a value to avoid the double-emit issue during initialization.
+
+### Multiple Models
+
+Default assumes `modelValue` prop. For multiple bindings, use explicit names:
+
+```vue
+<script setup lang="ts">
+const firstName = defineModel<string>('firstName')
+const age = defineModel<number>('age')
+</script>
+
+<!-- Usage -->
+<UserForm v-model:first-name="user.firstName" v-model:age="user.age" />
+```
+
+[v-model modifiers docs](https://vuejs.org/guide/components/v-model#handling-v-model-modifiers)
+
+## Reusable Templates
+
+For typed, scoped template snippets within a component:
+
+```vue
+<script setup lang="ts">
+import { createReusableTemplate } from '@vueuse/core'
+
+const [DefineItem, UseItem] = createReusableTemplate<{
+  item: SearchItem
+  icon: string
+  color?: 'red' | 'green' | 'blue'
+}>()
+</script>
+
+<template>
+  <DefineItem v-slot="{ item, icon, color }">
+    <div :class="color">
+      <Icon :name="icon" />
+      {{ item.name }}
+    </div>
+  </DefineItem>
+
+  <!-- Reuse multiple times -->
+  <UseItem v-for="item in items" :key="item.id" :item :icon="getIcon(item)" />
+</template>
+```
+
+## Template Refs (Vue 3.5+)
+
+Use `useTemplateRef()` for type-safe template references with IDE support:
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef, onMounted } from 'vue'
+
+const input = useTemplateRef<HTMLInputElement>('my-input')
+
+onMounted(() => {
+  input.value?.focus()
+})
+</script>
+
+<template>
+  <input ref="my-input">
+</template>
+```
+
+**Benefits over `ref()`:**
+
+- Type-safe with generics
+- Better IDE autocomplete and refactoring
+- Explicit ref name as string literal
+
+**Dynamic refs:**
+
+```vue
+<script setup lang="ts">
+const items = ref(['a', 'b', 'c'])
+const itemRefs = useTemplateRef<HTMLElement>('item')
+
+// Access refs after mount
+onMounted(() => {
+  console.log(itemRefs.value) // Array of elements
+})
+</script>
+
+<template>
+  <div v-for="item in items" :key="item" ref="item">
+    {{ item }}
+  </div>
+</template>
+```
+
+**Component refs with generics:**
+
+For generic components, use `ComponentExposed` from `vue-component-type-helpers`:
+
+```ts
+import type { ComponentExposed } from 'vue-component-type-helpers'
+import MyGenericComponent from './MyGenericComponent.vue'
+
+// Get exposed methods/properties with correct generic types
+const compRef = useTemplateRef<ComponentExposed<typeof MyGenericComponent>>('comp')
+
+onMounted(() => {
+  compRef.value?.someExposedMethod() // Typed!
+})
+```
+
+Install: `pnpm add -D vue-component-type-helpers`
+
+## SSR Hydration (Vue 3.5+)
+
+**Suppress hydration mismatches** for values that differ between server/client:
+
+```vue
+<template>
+  <!-- Client-side only values -->
+  <span data-allow-mismatch>{{ new Date().toLocaleString() }}</span>
+
+  <!-- Specific mismatch types -->
+  <span data-allow-mismatch="text">{{ timestamp }}</span>
+  <span data-allow-mismatch="children">
+    <ClientOnly>...</ClientOnly>
+  </span>
+  <span data-allow-mismatch="style">...</span>
+  <span data-allow-mismatch="class">...</span>
+  <span data-allow-mismatch="attribute">...</span>
+</template>
+```
+
+**Generate SSR-stable IDs:**
+
+```vue
+<script setup lang="ts">
+import { useId } from 'vue'
+
+const id = useId() // Stable across server/client renders
+</script>
+
+<template>
+  <label :for="id">Name</label>
+  <input :id="id">
+</template>
+```
+
+## Deferred Teleport (Vue 3.5+)
+
+Teleport to elements rendered later in the same cycle:
+
+```vue
+<template>
+  <!-- This renders first -->
+  <Teleport defer to="#late-div">
+    <span>Deferred content</span>
+  </Teleport>
+
+  <!-- This renders after, but Teleport waits -->
+  <div id="late-div"></div>
+</template>
+```
+
+Without `defer`, teleport to `#late-div` would fail since it doesn't exist yet.
+
+## Common Mistakes
+
+**Using `const props =` with destructured values:**
+
+```ts
+// ❌ Wrong
+const props = defineProps<{ count: number }>()
+const { count } = props // Loses reactivity
+```
+
+**Forgetting TypeScript types:**
+
+```ts
+// ❌ Wrong
+const emit = defineEmits(['update'])
+
+// ✅ Correct
+const emit = defineEmits<{ update: [id: number] }>()
+```
+
+**Components >300 lines:** Split into smaller components or extract logic to composables

package/.claude/skills/vue/references/composables.md

@@ -0,0 +1,358 @@
+# Vue Composables
+
+Reusable functions encapsulating stateful logic using Composition API.
+
+## Core Rules
+
+1. **VueUse first** - check [vueuse.org](https://vueuse.org) before writing custom
+2. **No async composables** - lose lifecycle context when awaited in other composables
+3. **Top-level only** - never call in event handlers, conditionals, or loops
+4. **readonly() exports** - protect internal state from external mutation
+5. **useState() for SSR** - use Nuxt's `useState()` not global refs
+
+## Quick Reference
+
+| Pattern   | Example                                          |
+| --------- | ------------------------------------------------ |
+| Naming    | `useAuth`, `useCounter`, `useDebounce`           |
+| State     | `const count = ref(0)`                           |
+| Computed  | `const double = computed(() => count.value * 2)` |
+| Lifecycle | `onMounted(() => ...)`, `onUnmounted(() => ...)` |
+| Return    | `return { count, increment }`                    |
+
+## Structure
+
+```ts
+// composables/useCounter.ts
+import { readonly, ref } from 'vue'
+
+export function useCounter(initialValue = 0) {
+  const count = ref(initialValue)
+
+  function increment() { count.value++ }
+  function decrement() { count.value-- }
+  function reset() { count.value = initialValue }
+
+  return {
+    count: readonly(count), // readonly if shouldn't be mutated
+    increment,
+    decrement,
+    reset,
+  }
+}
+```
+
+## Naming
+
+**Always prefix with `use`:** `useAuth`, `useLocalStorage`, `useDebounce`
+
+**File = function:** `useAuth.ts` exports `useAuth`
+
+## Best Practices
+
+**Do:**
+
+- Return object with named properties (destructuring-friendly)
+- Accept options object for configuration
+- Use `readonly()` for state that shouldn't mutate
+- Handle cleanup (`onUnmounted`, `onScopeDispose`)
+- Add JSDoc for complex functions
+
+## Lifecycle
+
+Hooks execute in component context:
+
+```ts
+export function useEventListener(target: EventTarget, event: string, handler: Function) {
+  onMounted(() => target.addEventListener(event, handler))
+  onUnmounted(() => target.removeEventListener(event, handler))
+}
+```
+
+**Watcher cleanup (Vue 3.5+):**
+
+```ts
+import { watch, onWatcherCleanup } from 'vue'
+
+export function usePolling(url: Ref<string>) {
+  watch(url, (newUrl) => {
+    const interval = setInterval(() => {
+      fetch(newUrl).then(/* ... */)
+    }, 1000)
+
+    // Cleanup when watcher re-runs or stops
+    onWatcherCleanup(() => {
+      clearInterval(interval)
+    })
+  })
+}
+```
+
+**Benefits of `onWatcherCleanup()`:**
+
+- Cleaner than returning cleanup functions
+- Works with async watchers
+- Can be called multiple times in same watcher
+
+## Async Pattern
+
+```ts
+export function useAsyncData<T>(fetcher: () => Promise<T>) {
+  const data = ref<T | null>(null)
+  const error = ref<Error | null>(null)
+  const loading = ref(false)
+
+  async function execute() {
+    loading.value = true
+    error.value = null
+    try {
+      data.value = await fetcher()
+    }
+    catch (e) {
+      error.value = e as Error
+    }
+    finally {
+      loading.value = false
+    }
+  }
+
+  execute()
+  return { data, error, loading, refetch: execute }
+}
+```
+
+**Data fetching:** Prefer Pinia Colada queries over custom composables.
+
+## VueUse
+
+> For VueUse composable reference, use the `vueuse` skill.
+
+Check VueUse before writing custom composables - most patterns already implemented.
+
+> **For Nuxt-specific composables** (useFetch, useRequestURL): see `nuxt` skill nuxt-composables.md
+
+## Advanced Patterns
+
+### Singleton Composable
+
+Share state across all components using the same composable:
+
+```ts
+import { createSharedComposable } from '@vueuse/core'
+
+function useMapControlsBase() {
+  const mapInstance = ref<Map | null>(null)
+  const flyTo = (coords: [number, number]) => mapInstance.value?.flyTo(coords)
+  return { mapInstance, flyTo }
+}
+
+export const useMapControls = createSharedComposable(useMapControlsBase)
+```
+
+### Cancellable Fetch with AbortController
+
+```ts
+export function useSearch() {
+  let abortController: AbortController | null = null
+
+  watch(query, async (newQuery) => {
+    abortController?.abort()
+    abortController = new AbortController()
+
+    try {
+      const data = await $fetch('/api/search', {
+        query: { q: newQuery },
+        signal: abortController.signal,
+      })
+    }
+    catch (e) {
+      if (e.name !== 'AbortError')
+        throw e
+    }
+  })
+}
+```
+
+### Step-Based State Machine
+
+```ts
+export function useSendFlow() {
+  const step = ref<'input' | 'confirm' | 'success'>('input')
+  const amount = ref('')
+
+  const next = () => {
+    if (step.value === 'input')
+      step.value = 'confirm'
+    else if (step.value === 'confirm')
+      step.value = 'success'
+  }
+
+  return { step, amount, next }
+}
+```
+
+### Client-Only Guards
+
+```ts
+export function useUserLocation() {
+  const location = ref<GeolocationPosition | null>(null)
+
+  if (import.meta.client) {
+    navigator.geolocation.getCurrentPosition(pos => location.value = pos)
+  }
+
+  return { location }
+}
+```
+
+### Custom Element Composables (Vue 3.5+)
+
+For custom element components, use built-in helpers:
+
+```ts
+import { useHost, useShadowRoot } from 'vue'
+
+export function useCustomElement() {
+  const host = useHost() // Host element reference
+  const shadowRoot = useShadowRoot() // Shadow DOM root
+
+  onMounted(() => {
+    console.log('Host:', host)
+    console.log('Shadow:', shadowRoot)
+  })
+
+  return { host, shadowRoot }
+}
+```
+
+**Available in:**
+
+- Components using `<script setup>` in custom elements
+- Access via `this.$host` in Options API
+
+### Auto-Save with Debounce
+
+```ts
+export function useAutoSave(content: Ref<string>) {
+  const hasChanges = ref(false)
+
+  const save = useDebounceFn(async () => {
+    if (!hasChanges.value)
+      return
+    await $fetch('/api/save', { method: 'POST', body: { content: content.value } })
+    hasChanges.value = false
+  }, 1000)
+
+  watch(content, () => {
+    hasChanges.value = true
+    save()
+  })
+
+  return { hasChanges }
+}
+```
+
+### Tagged Logger
+
+```ts
+import { consola } from 'consola'
+
+export function useSearch() {
+  const logger = consola.withTag('search')
+
+  watch(query, (q) => {
+    logger.info('Query changed:', q)
+  })
+}
+```
+
+## Reactivity Gotchas
+
+### Ref Unwrapping in Reactive
+
+Refs auto-unwrap in `reactive()` objects but **NOT** in arrays, Maps, or Sets:
+
+```ts
+// ✅ Object - auto unwraps
+const state = reactive({ count: ref(0) })
+state.count++ // No .value needed
+
+// ❌ Array - NO unwrapping
+const arr = reactive([ref(1)])
+arr[0].value // Need .value!
+
+// ❌ Map/Set - NO unwrapping
+const map = reactive(new Map([['key', ref(1)]]))
+map.get('key').value // Need .value!
+```
+
+### watchEffect Conditional Tracking
+
+Dependencies inside conditional branches are **not tracked** when condition is false:
+
+```ts
+// ❌ Wrong - dep not tracked when condition false
+watchEffect(() => {
+  if (condition.value) {
+    console.log(dep.value) // Only tracked when condition=true
+  }
+})
+
+// ✅ Correct - use explicit watch for conditional deps
+watch([condition, dep], ([cond, d]) => {
+  if (cond) console.log(d)
+})
+```
+
+### Cleanup Patterns
+
+**For keep-alive components** - use `onDeactivated`:
+
+```ts
+export function usePolling() {
+  let interval: NodeJS.Timeout
+
+  onMounted(() => { interval = setInterval(poll, 5000) })
+  onUnmounted(() => clearInterval(interval))
+  onDeactivated(() => clearInterval(interval)) // Pause when deactivated
+  onActivated(() => { interval = setInterval(poll, 5000) }) // Resume
+}
+```
+
+**For scope-aware cleanup** - use `tryOnScopeDispose` from VueUse:
+
+```ts
+import { tryOnScopeDispose } from '@vueuse/core'
+
+export function useEventSource(url: string) {
+  const source = new EventSource(url)
+
+  // Cleans up when effect scope disposes (component unmount, watcher stop)
+  tryOnScopeDispose(() => source.close())
+
+  return { source }
+}
+```
+
+## Common Mistakes
+
+**Not using `readonly()` for internal state:**
+
+```ts
+// ❌ Wrong - exposes mutable ref
+return { count }
+
+// ✅ Correct - prevents external mutation
+return { count: readonly(count) }
+```
+
+**Missing cleanup:**
+
+```ts
+// ❌ Wrong - listener never removed
+onMounted(() => target.addEventListener('click', handler))
+
+// ✅ Correct - cleanup on unmount
+onMounted(() => target.addEventListener('click', handler))
+onUnmounted(() => target.removeEventListener('click', handler))
+```