# Playbook de Migração React 18 → 19

## Fase 1: Atualizar para React 18.3 e corrigir avisos de depreciação (S)
- npm install react@18.3 react-dom@18.3
- Execute o app e corrija todos os avisos de depreciação no console:
  - Remova string refs em src/legacy/OldModal.tsx, src/legacy/OldTooltip.tsx
  - Substitua ReactDOM.findDOMNode em src/legacy/DropdownMenu.tsx
- Execute o conjunto de testes para confirmar que não há regressões
- Validação: Zero avisos de depreciação no console de desenvolvimento, todos os testes passam

## Fase 2: Migrar forwardRef para ref-as-prop (M)
- Remova os wrappers forwardRef de 23 componentes em src/components/ui/:
  - Button.tsx, Input.tsx, Select.tsx, TextArea.tsx (uso alto)
  - Modal.tsx, Popover.tsx, Tooltip.tsx (uso médio)
  - +16 componentes adicionais (lista completa abaixo)
- Passe ref como uma prop regular em vez de envolver em forwardRef
- Atualize os tipos TypeScript: altere RefObject<T> para RefObject<T> | null
- Atualize src/types/refs.d.ts para corresponder à nova semântica de ref do React 19
- Validação: Todos os componentes com ref-forwarding renderizam, gerenciamento de foco funciona

## Fase 3: Remover APIs depreciadas (M)
- Substitua o Context legado (contextTypes/getChildContext) em:
  - src/legacy/ThemeProvider.tsx → já usa createContext (sem alteração)
  - src/legacy/LocaleContext.tsx → converter para o padrão createContext
- Remova propTypes de 12 arquivos (TypeScript cuida da validação)
- Remova defaultProps de componentes de função (use padrões do JS)
- Validação: Valores de Context propagam corretamente, sem avisos em tempo de execução

## Fase 4: Atualizar padrões de busca de dados e Suspense (L)
- Revise os limites de Suspense em src/components/layouts/
- Atualize quaisquer componentes que dependam de mudanças no comportamento de fallback
- Teste rotas carregadas de forma lazy em src/routes/ com a nova semântica de Suspense
- Validação: Todas as rotas lazy carregam, estados de carregamento renderizam corretamente

## Fase 5: Instalar React 19 e adotar novos recursos (M)
- npm install react@19 react-dom@19
- Substitua useFormState por useActionState em src/hooks/useFormField.ts
- Atualize os imports do react-dom: ReactDOM.render → já usando createRoot
- Ative a nova transformação JSX se ainda não estiver ativa
- Validação: Conjunto completo de testes passa, app executa sem erros

## Fase 6: Atualizar bibliotecas de terceiros (L)
- react-hook-form → atualizar para v8 (compatível com React 19)
- @radix-ui/react-* → atualizar para a versão mais recente (suporte a ref-as-prop)
- react-router-dom → verificar compatibilidade com v6.4+
- Validação: Formulários são enviados corretamente, primitivos de UI renderizam, roteamento funciona

## Riscos
- A remoção do forwardRef é a mudança de maior volume — 23 componentes, muitos
  consumidos por outras equipes
- Mudanças nos tipos de ref do TypeScript podem expor problemas de null safety
- O react-hook-form v8 tem suas próprias breaking changes — teste a validação
  de formulários minuciosamente