Eventos nativos e eventos customizados

Os controles GovBR-DS usam eventos da plataforma quando reproduzem a semântica de um controle HTML. Assim, br-input, br-select, checkbox, radio, switch, slider, datetime, upload e tags selecionáveis podem ser consumidos como elementos nativos: o estado fica no event.target.

campo.addEventListener('input', (event) => console.log(event.target.value))
checkbox.addEventListener('change', (event) => console.log(event.target.checked))

Qual evento usar

Evento	Use quando	Estado
input	o valor muda continuamente, como digitação ou arraste	target.value, checked, files ou rangeValue
change	a edição é confirmada ou uma opção é selecionada	o mesmo estado público do host
focus / blur	o consumidor precisa reagir à entrada ou saída do controle	o host do Web Component; blur não é delegável
focusin / focusout	um contêiner precisa delegar foco de controles descendentes	o host e seus descendentes no caminho do evento
click, submit, reset, invalid, toggle	a interação tem exatamente a semântica HTML correspondente	propriedades do elemento/evento
CustomEvent	a ação é de domínio, ciclo de vida ou precisa de payload próprio	event.detail

Eventos como brNavigate, pageChange e brWizardComplete continuam customizados: chamar qualquer um deles de change apagaria informação importante e contrariaria a semântica da plataforma.

Vantagens e limites

Eventos nativos reduzem a API que o consumidor precisa aprender, integram-se melhor com formulários e frameworks e permitem ler o estado diretamente do elemento. Eles não servem, porém, para payload arbitrário nem para qualquer mudança visual. Um nome nativo só deve ser usado quando seu significado for o mesmo do HTML.

Em Shadow DOM, bubbles controla a propagação pela árvore e composed permite atravessar o limite da shadow root. A biblioteca redispara no host um único evento composto; ouvir simultaneamente o elemento interno e o host causaria duplicidade. Consulte Event.composed.

Os testes com render() cobrem componentes isolados. Os testes que usam createBrowserTestFixture() simulam uma página com custom elements registrados, Shadow DOM profundo e bundle de distribuição. Por isso os targets E2E, plataforma e acessibilidade dependem de build:dist; executar Vitest diretamente sem esse target pode carregar um dist antigo.

Um evento redisparado no host é sintético: ele preserva o contrato documentado de tipo, flags e estado público, mas não preserva isTrusted nem necessariamente todos os campos específicos da instância nativa interna. Para controles, ouça blur diretamente no componente e use focusout quando precisar de delegação.

Escritas externas são silenciosas

Definir element.value, atualizar ngModel/FormControl, alterar uma prop React/Vue ou restaurar/redefinir um formulário atualiza o componente sem emitir input ou change. Eventos representam interação ou commit, não simples sincronização de estado; isso evita loops de two-way binding.

Frameworks

Angular

<br-input [(ngModel)]="nome"></br-input>
<br-checkbox formControlName="aceite"></br-checkbox>

React

<br-input value={nome} onInput={(event) => setNome(event.currentTarget.value)} />

Vue

<br-input v-model="nome" />

Os wrappers apenas traduzem esses contratos para a convenção do framework; o Web Component continua utilizável sem wrapper.