Ciclo de Vida

Assim como frameworks como React ou Angular possuem seus métodos e hooks de ciclo de vida (lifecycle), os Web Components baseados na especificação nativa do navegador (CustomElements) possuem o seu próprio ciclo de vida.

Entender esses ciclos é vital para compreender como e quando manipular propriedades, inserir filhos (via Slots) ou interagir com a DOM gerada (Shadow DOM). A biblioteca do GovBR-DS utiliza o compilador Stencil, que abstrai e adiciona ciclos assíncronos de forma semelhante à forma que o React opera.

Métodos de Ciclo de Vida Nativos (Custom Elements)

Quando você insere um componente <br-button> no HTML, o navegador aciona os seguintes eventos básicos na classe registrada:

1. connectedCallback(): Invocado sempre que o componente é inserido no DOM.
2. disconnectedCallback(): Invocado sempre que o componente é removido do DOM (útil para limpeza de eventos).
3. attributeChangedCallback(): Acionado quando um atributo observado é adicionado, modificado, removido ou substituído.

O Ciclo Assíncrono do GovBR-DS (Stencil)

Porque nossos componentes são criados usando StencilJS, as atualizações na tela ocorrem de forma assíncrona para garantir performance e agrupamento (batching) de renderização.

Isso significa que modificar uma propriedade não causa uma atualização visual imediata, síncrona. Ela agenda uma renderização para o próximo frame.

Fluxo de Inicialização

1. Invocação / Criação (constructor): Os estados internos e as propriedades padrão recebem seus valores iniciais.
2. componentWillLoad(): Método onde você (ou nós da biblioteca) podemos disparar requisições ou ler configurações antes do primeiro 'desenho' na tela.
3. Renderização (render): O Shadow DOM inicial e o JSX são transformados no DOM final do componente.
4. componentDidLoad(): Disparado assim que a árvore HTML interna está totalmente desenhada na tela. Esse é o melhor momento para acessar elementos da DOM via document.querySelector em um projeto vanilla.

Fluxo de Atualização

Toda vez que você muda uma propriedade de um componente (ex: button.loading = true), o seguinte ciclo acontece:

1. componentWillUpdate(): Componente descobre que uma propriedade mudou.
2. Renderização (render): Ocorre a reavaliação apenas da parte do Shadow DOM que foi modificada.
3. componentDidUpdate(): O componente terminou de aplicar as mudanças na tela.

Qual a importância disso no dia a dia?

1. Interação Baseada em Propriedades vs Atributos

Tratar componentes web puramente via HTML baseia-se em Atributos:

<br-input label="Meu Input" disabled="true"></br-input>

Porém, ao interagir com o componente via JavaScript (ou Frameworks), você deve tratar as Propriedades:

const inputEl = document.querySelector('br-input');
// Evite usar setAttribute, pois pode não disparar certas tipagens.
inputEl.disabled = true; // ✅ Forma Correta (Propriedade)

2. Atrasos de Renderização em Vanilla JS

Se você precisar acessar uma dimensão física de um componente (ou de um sub-elemento interno do seu Shadow DOM) logo após alterar o seu estado, você deve esperar o fluxo assíncrono. O Stencil expõe uma Promise em cada componente, o método componentOnReady().

const modal = document.querySelector('br-modal');
modal.show = true;

// ❌ Se você checar a DOM agora, a animação não começou e os elementos podem não estar visíveis.
console.log(modal.offsetHeight);

// ✅ Forma segura: aguarde o componente finalizar seu ciclo
await modal.componentOnReady();
console.log(modal.offsetHeight); // Altura correta.

(Note: Usuários de React, Vue, e Angular não costumam precisar chamar componentOnReady, porque os wrappers gerados para essas tecnologias gerenciam as Promises por baixo dos panos na maior parte das atualizações).