Web components: custom elements, shadow DOM e onde termina o encapsulamento

O que é

Os web components se baseiam em três recursos do navegador. Custom elements: uma classe que estende HTMLElement, registrada com customElements.define("x-name", Class) (o nome precisa conter um hífen), com connectedCallback, disconnectedCallback e attributeChangedCallback para os atributos listados no array estático observedAttributes. Shadow DOM: attachShadow({ mode: "open" }) dá ao elemento uma subárvore privada; segundo a MDN, os estilos dentro dela ficam restritos a essa árvore, de modo que os estilos da página não afetam os elementos do shadow e os estilos do shadow não afetam a página, e <slot> projeta nela os filhos do light DOM. Templates: <template> guarda marcação inerte, e <template shadowrootmode="open"> declara um shadow root em HTML renderizado no servidor, sem nenhum script.

Por que importa

Custom elements são o único modelo de componentes que o próprio navegador entende: funcionam em qualquer framework ou em nenhum, sobrevivem a migrações de framework e podem ser usados a partir de HTML simples renderizado no servidor. O preço é que o encapsulamento é real, e tudo o que atravessa a fronteira (temas, formulários, labels, foco, eventos) exige uma abertura explícita.

Como aplicar

• Exponha superfícies de estilização de forma deliberada: custom properties para valores (elas são herdadas pela árvore shadow) e part="label" em elementos internos, para que a página possa escrever x-name::part(label); a MDN descreve part como o recurso que torna um elemento do shadow visível ao DOM pai.
• Faça os controles de formulário participarem de verdade com static formAssociated = true e ElementInternals (setFormValue, setValidity); sem isso, um input customizado nunca envia um valor.
• Prefira elementos autônomos; a MDN observa que o Safari não pretende dar suporte a customized built-ins (is="...").
• Renderize o estado inicial com shadow DOM declarativo quando a primeira renderização ou os crawlers importarem e, depois, faça o upgrade com a classe.
• Reflita o estado importante em atributos, para que o CSS e os testes possam selecioná-lo; mantenha mode: "open" (segundo a MDN, o modo closed não é um mecanismo de segurança forte, apenas um sinal).
• Estilize x-name:not(:defined) para o período anterior à execução do script, de modo que o conteúdo não dê um salto no upgrade.

Armadilhas

Referências por ID não atravessam a fronteira: um <label for> ou aria-labelledby na página não consegue apontar para um input dentro do shadow; por isso, ou o controle é inserido via slot a partir do light DOM, ou o label é colocado dentro do shadow. Resets globais, classes utilitárias e sprites de ícones não se aplicam ao interior. Eventos customizados precisam de composed: true para serem ouvidos fora. Registrar o mesmo nome duas vezes lança um erro, o que costuma causar problemas quando dois bundles distribuem o mesmo componente. As ferramentas de desenvolvedor mostram a árvore shadow, mas document.querySelector não a alcança.