Chucao — formularios

Cómo funcionan los formularios

Los seis controles de formulario — ch-checkbox, ch-input, ch-radio, ch-select, ch-switch y ch-textarea — son form-associated custom elements. Dentro de un <form> se comportan como controles nativos, sin JavaScript de por medio:

• Su valor/estado se envía en FormData y en el submit (por su name).
• Aparecen en form.elements y form.checkValidity() los ve.
• Un campo required vacío es inválido (valueMissing) y bloquea el submit.
• El host matchea :invalid/:valid, así puedes estilarlo desde tu CSS.
• form.reset() restaura el valor o estado inicial.
• Un <fieldset disabled> deshabilita los controles que contiene y excluye sus valores.

Es un cambio de comportamiento: en versiones anteriores estos controles no participaban en el formulario. Si compensabas esa ausencia a mano (por ejemplo, con hidden inputs alimentando FormData), hay que quitar ese trabajo manual para no duplicar valores.

Lo mínimo

Un formulario con un solo campo, leído con JavaScript puro:

<form id="contacto">
  <ch-input name="email" label="Correo" type="email" required></ch-input>
  <ch-button id="enviar">Enviar</ch-button>
</form>

const form = document.getElementById('contacto');
const submit = document.getElementById('enviar');

// ch-button no puede disparar el submit por sí solo (vive en su shadow
// root): conecta chClick con requestSubmit(), que valida y dispara submit.
submit.addEventListener('chClick', () => form.requestSubmit());

form.addEventListener('submit', (event) => {
  event.preventDefault(); // sin backend real, acá solo leemos los datos
  const data = Object.fromEntries(new FormData(form));
  console.log(data); // { email: 'tu@email.com' }
});

Ejemplo: formulario de login

Correo y contraseña con required. El navegador valida antes de disparar submit: si un campo obligatorio está vacío, muestra el mensaje y no se llega al handler.

HTML

<form id="login-form">
  <ch-input name="email" label="Correo electrónico" type="email" required error-message="Ingresa un correo válido"></ch-input>
  <ch-input name="password" label="Contraseña" type="password" required error-message="Ingresa tu contraseña"></ch-input>
  <ch-button id="login-submit">Entrar</ch-button>
</form>

JavaScript

const form = document.getElementById('login-form');
const output = document.getElementById('login-result');
const submit = document.getElementById('login-submit');

// ch-button no puede disparar el submit por sí solo: conecta chClick con
// requestSubmit(), que valida y dispara `submit` si el formulario es válido.
submit.addEventListener('chClick', () => form.requestSubmit());

form.addEventListener('submit', (event) => {
  event.preventDefault(); // en este demo no hay backend
  const data = Object.fromEntries(new FormData(form));

  // fetch('/api/login', { method: 'POST', body: JSON.stringify(data) })

  output.textContent = JSON.stringify(data, null, 2);
});

Ejemplo: suscripción a un newsletter

Un correo y un checkbox de consentimiento required. Como con un checkbox nativo, consent solo aparece en FormData cuando está marcado.

HTML

<form id="newsletter-form">
  <ch-input name="email" label="Correo electrónico" type="email" required error-message="Ingresa un correo válido"></ch-input>
  <ch-checkbox name="consent" label="Acepto recibir novedades por correo" required error-message="Necesitamos tu consentimiento"></ch-checkbox>
  <ch-button id="newsletter-submit">Suscribirme</ch-button>
</form>

JavaScript

const form = document.getElementById('newsletter-form');
const output = document.getElementById('newsletter-result');
const submit = document.getElementById('newsletter-submit');

submit.addEventListener('chClick', () => form.requestSubmit());

form.addEventListener('submit', (event) => {
  event.preventDefault();

  // Si el checkbox está sin marcar, `consent` no aparece en FormData.
  const data = Object.fromEntries(new FormData(form));

  if (data.consent !== 'on') {
    // el usuario no dio consentimiento: no suscribir
    return;
  }

  // fetch('/api/newsletter', { method: 'POST', body: JSON.stringify(data) })

  output.textContent = JSON.stringify(data, null, 2);
});

Notas

• Botón de submit. ch-button renderiza un <button type="button"> dentro de su shadow root, así que no dispara el submit por sí solo. Conecta chClick con form.requestSubmit(): ese método corre la validación nativa y dispara submit si el formulario es válido:

  document.getElementById('entrar').addEventListener('chClick', () => {
    document.getElementById('login-form').requestSubmit();
  });

• Resaltado del campo inválido. Los componentes pintan el borde del control en color de advertencia cuando el campo es inválido después de que el usuario terminó la interacción — al salir del campo (focusout) o al confirmar el valor (change) — o ante un intento de submit (evento invalid). Un campo con foco aún no se resalta mientras el usuario lo está editando. Internamente se marca al terminar la interacción, y el estilo se resuelve con la validez nativa:

  /* dentro del componente */
  :host([data-touched]:invalid) .input,
  :host(:user-invalid) .input {
    border-color: var(--color-status-warning);
  }

  Desde tu CSS también puedes apuntar al host con las mismas pseudoclases (p. ej. ch-input[data-touched]:invalid) para estilos propios. :user-invalid hace lo mismo en navegadores que lo reportan sobre custom elements; el atributo data-touched cubre el resto.
• Mensaje de error inline. El texto rojo bajo el campo se renderiza cuando pasas invalid + error-message (por ejemplo, desde la validación del servidor). El required vacío valida solo por la API nativa: el navegador muestra el validationMessage en el control inválido y bloquea el submit.
• Validación de formato. El type (p. ej. email) se aplica al input interno. La validez del host refleja required y invalid/error-message; la validación de formato del type todavía no se propaga a la constraint validation del host.
• La API de constraint validation de estos componentes vive en element.internals (checkValidity(), validationMessage, validity, willValidate). Para consumidores el camino habitual es form.checkValidity(), new FormData(form) y CSS :invalid.
• Controles sin name no se envían en el submit, igual que los controles nativos.