Ciclo de Vida

Assim como frameworks modernos (React, Angular, Vue) possuem 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 o DOM interno gerado (Shadow DOM). A biblioteca do GovBR-DS utiliza o compilador Stencil, que abstrai e adiciona ciclos assíncronos inteligentes com agrupamento (batching) de renderização.

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

Quando você insere um componente como <br-button> no HTML, o navegador aciona os seguintes métodos nativos na classe registrada:

1. connectedCallback(): Invocado sempre que o componente é inserido na árvore do DOM.
2. disconnectedCallback(): Invocado sempre que o componente é removido do DOM (ponto crítico para limpeza de timers, listeners e observers).
3. attributeChangedCallback(): Acionado quando um atributo observado é adicionado, modificado, removido ou substituído.

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

Como nossos componentes são construídos com StencilJS, as atualizações na tela ocorrem de forma assíncrona para garantir máxima performance e evitar repaints excessivos.

Isso significa que modificar uma propriedade não causa uma atualização visual imediata e síncrona; ela agenda uma renderização para o próximo frame de animação do navegador.

Fluxo de Inicialização e Primeira Carga

1. constructor(): Invocado na instanciação. Define valores padrão primitivos.
2. componentWillLoad(): Executado uma única vez antes do primeiro desenho. Pode retornar Promises (ex: buscar dados remotos iniciais antes de renderizar).
3. componentWillRender(): Executado antes de cada renderização para atualizar dados derivados.
4. render(): Retorna a árvore JSX pura para compor o Virtual DOM.
5. componentDidRender(): Acionado imediatamente após o término de qualquer renderização.
6. componentDidLoad(): Disparado uma única vez assim que a árvore HTML interna está totalmente desenhada e conectada ao DOM. Momento indicado para inicializações que exigem medições físicas ou APIs externas.

Fluxo de Atualização Reativa

Toda vez que uma @Prop() ou @State() muda, o seguinte loop acontece:

1. componentShouldUpdate(newValue, oldValue, propName): Permite ao componente decidir se deve ou não prosseguir com a renderização.
2. componentWillUpdate(): Executado antes da atualização visual.
3. componentWillRender() ➔ render() ➔ componentDidRender(): O Stencil reconcilia o Virtual DOM e atualiza apenas os nós modificados no Shadow DOM.

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 priorizar Propriedades:

const inputEl = document.querySelector('br-input');
// Evite usar setAttribute, pois trata tudo como string e não dispara certas tipagens.
inputEl.disabled = true; // ✅ Forma Correta (Propriedade)

2. Atrasos de Renderização e componentOnReady() 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 o DOM imediatamente, o render assíncrono ainda não ocorreu:
console.log(modal.offsetHeight);

// ✅ Forma segura: aguarde o componente finalizar seu ciclo de inicialização/render
await modal.componentOnReady();
console.log(modal.offsetHeight); // Dimensão real e confiável.

Integração com Frameworks

Usuários dos wrappers oficiais para React (@govbr-ds/webcomponents-react), Angular (@govbr-ds/webcomponents-angular) e Vue (@govbr-ds/webcomponents-vue) não precisam chamar componentOnReady() manualmente, pois os wrappers sincronizam as alterações de estado automaticamente com o ciclo de vida nativo de cada framework.