# Vue 3 — Composition API Best Practices

> Extraído de skills: `vue` + `vue-composition-api-best-practices`

## `<script setup>` Padrão Ouro

```vue
<script setup lang="ts">
// ✅ Importações no topo — tree-shakeable
import { ref, computed, onMounted } from 'vue'
import { useUserStore } from '@/stores/user'

// ✅ Composables começam com `use`
const user = useUserStore()
const selectedId = ref<number | null>(null)

// ✅ Estado + getters no mesmo lugar
const filteredUsers = computed(() =>
  user.list.filter(u => u.active)
)

// ✅ Lifecycle no fim
onMounted(() => user.fetchAll())
</script>

<template>
  <button v-if="filteredUsers.length > 0" @click="selectedId = null">
    Clear
  </button>
</template>
```

## Composables — `useXxx` Pattern

```ts
// composables/usePagination.ts
export function usePagination<T>(items: T[], pageSize = 20) {
  const page = ref(1)
  const totalPages = computed(() => Math.ceil(items.value.length / pageSize))
  const paginated = computed(() =>
    items.value.slice((page.value - 1) * pageSize, page.value * pageSize)
  )
  return { page, totalPages, paginated }
}
```

## <script setup> Deep Dive

```vue
<!-- ✅ BOM — validade automática, minificado -->
<script setup lang="ts">
defineProps<{ msg: string }>()
const emit = defineEmits<{ (e: 'update', id: number): void }>()
</script>

<!-- ❌ RUIM — option API misturado -->
<script lang="ts">
export default {
  data() { return { x: 1 } },
  methods: { /* ... */ }
}
</script>
```

## State Management — Pinia
```ts
// stores/counter.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  const double = computed(() => count.value * 2)
  function increment() { count.value++ }
  return { count, double, increment }
})
```

## Reactividade — Principais Armadilhas
- `ref` vs `reactive`: use `ref` por padrão (tipagem simples); `reactive` para objetos grandes
- Perda de reatividade ao desestruturar — usar `toRefs()` ou `storeToRefs()`
- `watch` vs `watchEffect`: `watch` é mais controlado; `watchEffect` é automático mas menos previsível
- `v-if` vs `v-show`: `v-if` remove do DOM; `v-show` togglea `display`

## Type-Safe Vue
```vue
<script setup lang="ts">
// Props tipadas — importa de arquivo separado se for reutilizável
const props = defineProps<{
  userId: number
  items: Item[]
  requiredValue: string
}>()
const emit = defineEmits<{
  (e: 'delete', id: number): void
  (e: 'save', data: FormData): void
}>()
</script>
```

## Vue Router Traps
- `useRoute()` para rota atual — reativa, usar em setup
- `useRouter()` para navegação — `router.push('/path')`
- Guards: `beforeEach`, `beforeResolve`, `afterEach` — retornar `false` cancela
- `<RouterView>` com named views — múltiplas views por rota

## Common Mistakes
- `key` em `v-for` é obrigatório — `v-for="item in items" :key="item.id"`
- Ordem de event modifiers importa — `.prevent.stop` ≠ `.stop.prevent`
- `Teleport` para modais — `<Teleport to="body">` renderiza fora da árvore