Always use the Composition API with <script setup lang="ts">.
Never use the Options API (data(), methods, computed, watch options).
Use ref() and reactive() for state, computed() for derived values,
and watch()/watchEffect() for side effects.

<!-- ❌ Bad: Options API in a Vue 3 project -->
<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  data() {
    return {
      search: '',
      items: [] as any[],
      loading: false,
    }
  },
  computed: {
    filteredItems() {
      return this.items.filter(i => i.name.includes(this.search))
    }
  },
  methods: {
    async fetchItems() {
      this.loading = true
      const res = await fetch('/api/items')
      this.items = await res.json()
      this.loading = false
    }
  },
  mounted() {
    this.fetchItems()
  }
})
</script>

<!-- ✅ Good: Composition API with script setup -->
<script setup lang="ts">
import { ref, computed, onMounted } from 'vue'

interface Item {
  id: string
  name: string
}

const search = ref('')
const items = ref<Item[]>([])
const loading = ref(false)

const filteredItems = computed(() =>
  items.value.filter(i => i.name.includes(search.value))
)

async function fetchItems() {
  loading.value = true
  const res = await fetch('/api/items')
  items.value = await res.json()
  loading.value = false
}

onMounted(fetchItems)
</script>

Always use TypeScript-based prop and emit declarations with
defineProps<T>() and defineEmits<T>(). Never use the runtime
array syntax (['title', 'count']) or object syntax without types.
Define interfaces for complex prop shapes.

<!-- ❌ Bad: no types, no defaults, no safety -->
<script setup>
const props = defineProps(['title', 'items', 'onSelect'])

const emit = defineEmits(['update', 'delete'])

function handleClick(item) {
  emit('update', item)
}
</script>

<!-- ✅ Good: fully typed props and emits -->
<script setup lang="ts">
interface Item {
  id: string
  label: string
}

const props = withDefaults(
  defineProps<{
    title: string
    items: Item[]
    maxVisible?: number
  }>(),
  { maxVisible: 10 }
)

const emit = defineEmits<{
  update: [item: Item]
  delete: [id: string]
}>()

function handleClick(item: Item) {
  emit('update', item)
}
</script>

Extract reusable logic into composables (use*.ts files).
A composable should encapsulate reactive state + logic for a
single concern. Components should orchestrate composables,
not contain raw business logic. Keep components focused on
template rendering and user interaction.

<!-- ❌ Bad: component does everything -->
<script setup lang="ts">
import { ref, watch } from 'vue'

const query = ref('')
const results = ref<Product[]>([])
const loading = ref(false)
const error = ref<string | null>(null)
const page = ref(1)
const hasMore = ref(true)
const debounceTimer = ref<ReturnType<typeof setTimeout>>()

watch(query, (val) => {
  clearTimeout(debounceTimer.value)
  debounceTimer.value = setTimeout(() => {
    page.value = 1
    search(val)
  }, 300)
})

async function search(term: string) {
  loading.value = true
  error.value = null
  try {
    const res = await fetch(`/api/search?q=${term}&page=${page.value}`)
    if (!res.ok) throw new Error('Search failed')
    const data = await res.json()
    results.value = page.value === 1 ? data.items : [...results.value, ...data.items]
    hasMore.value = data.hasMore
  } catch (e) {
    error.value = e instanceof Error ? e.message : 'Unknown error'
  } finally {
    loading.value = false
  }
}

function loadMore() {
  page.value++
  search(query.value)
}
</script>

// ✅ Good: composable handles the concern
// composables/useSearch.ts
import { ref, watch } from 'vue'
import { useDebounceFn } from '@vueuse/core'

export function useSearch<T>(endpoint: string) {
  const query = ref('')
  const results = ref<T[]>([])
  const loading = ref(false)
  const error = ref<string | null>(null)
  const page = ref(1)
  const hasMore = ref(true)

  async function search() {
    loading.value = true
    error.value = null
    try {
      const res = await fetch(`${endpoint}?q=${query.value}&page=${page.value}`)
      if (!res.ok) throw new Error('Search failed')
      const data = await res.json()
      results.value = page.value === 1 ? data.items : [...results.value, ...data.items]
      hasMore.value = data.hasMore
    } catch (e) {
      error.value = e instanceof Error ? e.message : 'Unknown error'
    } finally {
      loading.value = false
    }
  }

  const debouncedSearch = useDebounceFn(() => {
    page.value = 1
    search()
  }, 300)

  watch(query, () => debouncedSearch())

  function loadMore() {
    page.value++
    search()
  }

  return { query, results, loading, error, hasMore, loadMore }
}

<!-- ✅ Good: component just wires things up -->
<script setup lang="ts">
import { useSearch } from '@/composables/useSearch'

const { query, results, loading, error, hasMore, loadMore } = useSearch<Product>('/api/search')
</script>

Never destructure reactive() objects directly — it breaks reactivity.
Use toRefs() or storeToRefs() when destructuring. For ref() values,
always access .value in script. Prefer ref() over reactive() for
primitive values. Use shallowRef() for large objects that replace
rather than mutate.

<!-- ❌ Bad: reactivity is silently broken -->
<script setup lang="ts">
import { reactive } from 'vue'

const state = reactive({
  count: 0,
  name: 'initial',
})

// ❌ These are plain values now — changes won't update the template
const { count, name } = state

function increment() {
  count++ // Does nothing in the template
}
</script>

<template>
  <p>{{ count }}</p> <!-- Stuck at 0 forever -->
  <button @click="increment">+1</button>
</template>

<!-- ✅ Good: reactivity preserved with toRefs -->
<script setup lang="ts">
import { reactive, toRefs } from 'vue'

const state = reactive({
  count: 0,
  name: 'initial',
})

const { count, name } = toRefs(state)

function increment() {
  count.value++
}
</script>

<template>
  <p>{{ count }}</p> <!-- Updates correctly -->
  <button @click="increment">+1</button>
</template>

Use defineModel() for two-way binding instead of manual prop +
emit patterns. For custom v-model modifiers, use the modifiers
option. For multiple v-model bindings, use named models.
Never manually emit update:modelValue when defineModel handles it.

<!-- ❌ Bad: manual v-model boilerplate -->
<script setup lang="ts">
const props = defineProps<{
  modelValue: string
  title: string
}>()

const emit = defineEmits<{
  'update:modelValue': [value: string]
  'update:title': [value: string]
}>()

function onInput(e: Event) {
  emit('update:modelValue', (e.target as HTMLInputElement).value)
}

function onTitleChange(val: string) {
  emit('update:title', val)
}
</script>

<template>
  <input :value="modelValue" @input="onInput" />
  <input :value="title" @input="onTitleChange($event.target.value)" />
</template>

<!-- ✅ Good: defineModel handles everything -->
<script setup lang="ts">
const modelValue = defineModel<string>({ required: true })
const title = defineModel<string>('title', { required: true })
</script>

<template>
  <input v-model="modelValue" />
  <input v-model="title" />
</template>

Always type template refs with the correct component or element type.
Use ref<InstanceType<typeof Component> | null>(null) for component refs.
Use ref<HTMLInputElement | null>(null) for DOM element refs.
Always type provide/inject with InjectionKey<T> for type safety.
Never use string keys for provide/inject.

<!-- ❌ Bad: untyped refs and stringly-typed injection -->
<script setup>
import { ref, provide, inject } from 'vue'

const inputRef = ref(null)
const formRef = ref(null)

provide('theme', { primary: '#000', secondary: '#fff' })

// In child component:
const theme = inject('theme') // type: unknown
</script>

<template>
  <input ref="inputRef" />
  <MyForm ref="formRef" />
</template>

<!-- ✅ Good: fully typed refs and injection -->
<script setup lang="ts">
import { ref, provide } from 'vue'
import type { InjectionKey } from 'vue'
import MyForm from './MyForm.vue'

interface Theme {
  primary: string
  secondary: string
}

export const themeKey: InjectionKey<Theme> = Symbol('theme')

const inputRef = ref<HTMLInputElement | null>(null)
const formRef = ref<InstanceType<typeof MyForm> | null>(null)

provide(themeKey, { primary: '#000', secondary: '#fff' })

// In child component:
// const theme = inject(themeKey) // type: Theme | undefined
</script>

<template>
  <input ref="inputRef" />
  <MyForm ref="formRef" />
</template>

# Vue 3 Code Rules

## Composition API
- Always use <script setup lang="ts">
- Never use Options API (data, methods, computed, watch options)
- Use ref() for primitives, reactive() for objects
- Use computed() for derived values, watch() for side effects

## Props and Emits
- Use defineProps<T>() with TypeScript generics, never array syntax
- Use defineEmits<T>() with typed event signatures
- Use withDefaults() for default prop values

## Composables
- Extract reusable logic into composables (use*.ts)
- One concern per composable
- Components should orchestrate composables, not contain business logic

## Reactivity
- Never destructure reactive() objects without toRefs()
- Always access .value for ref() in script
- Use shallowRef() for large objects that are replaced, not mutated
- Use storeToRefs() when destructuring Pinia stores

## v-model
- Use defineModel() for two-way binding (Vue 3.4+)
- Never manually emit update:modelValue when defineModel works
- Use named models for multiple v-model bindings

## Type Safety
- Type template refs: ref<HTMLElement | null>(null)
- Type component refs: ref<InstanceType<typeof Comp> | null>(null)
- Use InjectionKey<T> for provide/inject, never string keys