Componentes web: elementos personalizados, shadow DOM y dónde termina el encapsulamiento

Qué es

Tres funciones del navegador componen los componentes web. Elementos personalizados: una clase que extiende HTMLElement, registrada con customElements.define("x-name", Class) (el nombre debe contener un guion), con connectedCallback, disconnectedCallback y attributeChangedCallback para los atributos listados en un array estático observedAttributes. Shadow DOM: attachShadow({ mode: "open" }) otorga al elemento un subárbol privado; MDN indica que los estilos dentro de él quedan acotados a ese árbol, de modo que los estilos de la página no afectan a los elementos de la sombra ni los estilos de la sombra afectan a la página, y <slot> proyecta en él los hijos del DOM de luz. Plantillas: <template> contiene marcado inerte, y <template shadowrootmode="open"> declara un shadow root en HTML renderizado en el servidor sin ningún script.

Por qué importa

Los elementos personalizados son el único modelo de componentes que el propio navegador entiende: funcionan en cualquier framework o en ninguno, sobreviven a las migraciones de framework y pueden usarse desde HTML plano renderizado en el servidor. El precio es que el encapsulamiento es real, y cada aspecto que cruza el límite (tematización, formularios, etiquetas, foco, eventos) necesita una apertura explícita.

Cómo aplicarlo

• Exponer las superficies de estilo de forma deliberada: propiedades personalizadas para los valores (heredan hacia el árbol de sombra), y part="label" en los elementos internos para que la página pueda escribir x-name::part(label); MDN describe part como lo que hace visible un elemento de la sombra al DOM padre.
• Hacer que los controles de formulario sean participantes reales con static formAssociated = true y ElementInternals (setFormValue, setValidity); sin esto, una entrada personalizada nunca envía un valor.
• Preferir los elementos autónomos; MDN señala que Safari no tiene previsto admitir los elementos integrados personalizados (is="...").
• Renderizar el estado inicial con shadow DOM declarativo cuando importe el primer renderizado o los rastreadores, y luego actualizarlo con la clase.
• Reflejar el estado importante como atributos para que CSS y las pruebas puedan seleccionarlo; mantener mode: "open" (MDN indica que el modo cerrado no es un mecanismo de seguridad fuerte, solo una señal).
• Aplicar estilo a x-name:not(:defined) para el tiempo previo a que se ejecute el script, de modo que el contenido no salte al actualizarse.

Trampas

Las referencias por ID no cruzan el límite: un <label for> o aria-labelledby en la página no puede apuntar a una entrada dentro de la sombra, así que hay que insertar el control desde el DOM de luz mediante un slot o etiquetarlo dentro. Los resets globales, las clases de utilidad y los sprites de iconos no se aplican dentro. Los eventos personalizados necesitan composed: true para oírse fuera. Registrar el mismo nombre dos veces lanza un error, lo que afecta cuando dos paquetes distribuyen el mismo componente. Las herramientas de desarrollo muestran el árbol de sombra, pero document.querySelector no lo hace.