Modal

Diálogo que se superpone a todo, con el fondo desenfocado y un brillo del color del tono. Hecho sobre el <dialog> nativo: de él vienen la capa por encima de cualquier z-index, el foco atrapado, el Esc y el foco devuelto a quien lo abrió — el componente solo dibuja la caja y la anima.

Ejemplos

Todos los de abajo son el mismo Tucano.modal() con opciones distintas.

Cómo usar

Hay dos caminos. Desde JavaScript, el modal se monta en el momento, entra en el <body> al abrirse y sale al cerrarse. Desde la plantilla, el <dialog> ya está en la página y el componente solo lo abre, lo cierra y lo anima.

En JavaScript

Tucano.modal({
  title: 'Eliminar contrato',
  text: 'Esta acción no se puede deshacer.',
  tone: 'danger',     // default | danger | success | warning
  size: 'md',         // sm | md | lg | full
  sheet: true,        // en el móvil sube desde abajo
  actions: [
    { text: 'Cancelar', variant: 'outline' },
    { text: 'Eliminar', variant: 'danger', onClick: () => deleteContract() },
  ],
  onClose: (reason, modal) => console.log(reason),
});

// Solo con texto, el atajo acepta una cadena
Tucano.modal('Archivo enviado.');

El atajo Tucano.modal() crea y abre en un paso, y devuelve la instancia. Para montarlo antes y abrirlo después, usa la clase:

const m = new Tucano.Modal({ title: 'Nuevo contacto', size: 'lg' });
m.content(form);         // cualquier nodo, o un array de nodos
m.open();
m.close();               // anima la salida y llama a onClose(reason)

Confirmación

El caso más común de modal en un CRUD es preguntar antes de borrar. Tucano.confirm() devuelve una promesa, y el código sigue leyéndose de arriba abajo:

if (await Tucano.confirm({ title: '¿Eliminar contrato?', text: 'Esta acción no se puede deshacer.', confirm: 'Eliminar' })) {
  deleteContract();
}

Las demás opciones del modal también valen aquí, excepto actions, que confirm() monta por su cuenta. Un onClose que pases se sigue llamando.

Acciones

Cada elemento de actions se convierte en un .tuc-btn en el pie, en el orden en que se escribió.

Escrito en la plantilla

Cuando el contenido viene renderizado por el servidor — un formulario de Django, con errores y csrf_token —, el <dialog> vive en la plantilla. Todo dialog.tuc-modal se adopta al cargar y en cada htmx:afterSwap; abrir no lo inserta y cerrar no lo quita, porque el nodo es de quien escribió el HTML.

<dialog class="tuc-modal is-md" id="delete" aria-labelledby="delete-title">
  <form class="tuc-modal__panel" method="post" action="{% url 'contract-delete' contract.pk %}">
    {% csrf_token %}
    <div class="tuc-modal__top">
      <div class="tuc-modal__header">
        <h2 class="tuc-modal__title" id="delete-title">¿Eliminar contrato?</h2>
        <p class="tuc-modal__text">Esta acción no se puede deshacer.</p>
      </div>
      <button type="button" class="tuc-btn is-ghost is-icon is-sm tuc-modal__close" aria-label="Cerrar" data-tuc-modal-close>…</button>
    </div>
    <div class="tuc-modal__footer">
      <button type="button" class="tuc-btn is-outline" data-tuc-modal-close>Cancelar</button>
      <button class="tuc-btn is-danger">Eliminar</button>
    </div>
  </form>
</dialog>

<button class="tuc-btn is-outline" data-tuc-modal="#delete">Eliminar</button>

Las clases son las mismas que monta el JavaScript: __panel es la caja, __top contiene el __header (con __title y __text) y el __close, __body es el cuerpo que se desplaza y __footer alinea las acciones a la derecha. El tamaño y el tono van como clase en el propio <dialog>: is-lg, is-danger, is-sheet.

Confirmar antes de enviar un formulario

Para un formulario de eliminación que ya existe en la página, confirm() intercepta el envío y lo deja pasar solo con un sí:

document.querySelector('#delete-contract').addEventListener('submit', async (e) => {
  e.preventDefault();
  const ok = await Tucano.confirm({ title: '¿Eliminar contrato?', confirm: 'Eliminar' });
  if (ok) e.target.submit();
});

Tonos y brillo

El fondo no es solo oscuro: un brillo radial detrás de la caja separa el diálogo de lo que quedó debajo, y el desenfoque saca la página del foco. El tono cambia el color de ese brillo y del aura alrededor de la caja — no el color de los botones, que sigue siendo elección de cada acción.

Tamaños

La caja ocupa el ancho disponible hasta el límite del tamaño, y el cuerpo se desplaza cuando el contenido supera la altura de la pantalla.

Por debajo de 40rem los botones del pie ocupan la fila, para que el área táctil crezca. Con sheet, la caja pierde las esquinas de abajo, se apoya en el borde inferior y respeta el área segura del iPhone. Es opcional porque no todo modal quiere convertirse en panel lateral en el móvil.

Teclado y accesibilidad

showModal() pone el diálogo en la top layer y deja inerte el resto de la página: el foco no escapa detrás de él, y al cerrar vuelve a quien lo abrió. Nada de eso es JavaScript nuestro — es el elemento nativo.

Con title, el diálogo recibe un aria-labelledby que apunta a él, y el lector de pantalla anuncia el título al abrirse. La X es un .tuc-btn con aria-label="Fechar". Con prefers-reduced-motion, la entrada dura 100 ms y no crece.

El modal y el panel lateral comparten esta mecánica: una corrección hecha en uno vale para el otro.

API

Generada a partir del código en cada build — si algo no está aquí, no existe.

Opciones

Las notas de esta tabla salen de los comentarios del código fuente, que están escritos en portugués.