Gestión de Enfoque con Animaciones CSS
Este documento captura lecciones aprendidas al solucionar problemas de navegación por teclado cuando componentes flotantes (Select, DropdownMenu, Popover) tienen animaciones CSS de apertura/cierre.
El Problema
Cuando los elementos de contenido flotante tienen animaciones CSS que comienzan con opacity: 0 (como animate-in fade-in-0 de Tailwind), el navegador puede rechazar las llamadas element.focus() porque el elemento es invisible.
Síntomas
- El componente se abre correctamente con clics del ratón
- La navegación por teclado (flechas, Escape) no funciona después de abrir con teclado
- Funciona correctamente en demos sin clases de animación
- No funciona en demos con clases de animación
Causa Raíz
- Las animaciones CSS como
fade-in-0inician el elemento conopacity: 0 - Cuando se llama a
focus()inmediatamente después del renderizado, el elemento aún es invisible - El navegador rechaza el enfoque en elementos invisibles
- El enfoque permanece en el botón desencadenante en lugar de moverse al contenido
- Los eventos de teclado van al desencadenante (que no hace nada cuando está abierto) en lugar del contenido
Evidencia de la Depuración en Consola
// Después de abrir el select, los eventos de teclado van al desencadenante, no al contenido:
Document keydown: ArrowDown Target: <button role="combobox" ...>
// El elemento activo es el desencadenante, no el contenido:
Active: BUTTON summit-select-...-trigger
La Solución
Implementar un mecanismo de reintento para el enfoque que permita que la animación progrese más allá de opacity: 0 antes de rendirse.
Implementación en JavaScript
// src/SummitUI/Scripts/floating.js
/**
* Enfoca un elemento con mecanismo de reintento para elementos animados.
* Los elementos con animaciones CSS que comienzan con opacity:0 pueden rechazar el enfoque inicialmente.
* Esto reintenta el enfoque hasta 5 veces con retrasos de 20ms para permitir que la animación
* progrese más allá del estado invisible.
* @param {HTMLElement} element - Elemento a enfocar
*/
export function focusElement(element) {
if (!element) return;
function tryFocus(attempts) {
element.focus();
// Si el enfoque no tuvo éxito y quedan intentos, reintentar
if (document.activeElement !== element && attempts > 0) {
setTimeout(() => tryFocus(attempts - 1), 20);
}
}
// Primer intento después de un frame para dejar que CSS se aplique
requestAnimationFrame(() => tryFocus(5));
}
Puntos Clave
- Usar
requestAnimationFrameprimero - Asegura que CSS se haya aplicado antes de intentar el enfoque - Verificar
document.activeElement- Comprueba si el enfoque realmente tuvo éxito - Reintentar con retrasos - Intervalos de 20ms permiten que la animación progrese
- Intentos limitados - 5 reintentos = 100ms de espera máxima, suficiente para animaciones típicas
- Aplicar a todas las funciones de enfoque - Tanto
focusElement(element)comofocusElementById(id)necesitan este patrón
Funciones Actualizadas
floating.js:focusElement(element)- Usado por SelectContentfloating.js:focusElementById(elementId)- Usado por DropdownMenuContent
Pruebas
Se agregaron secciones "Con Animaciones" a las páginas demo de prueba y las correspondientes pruebas de Playwright.
Clases CSS de Animación para Pruebas
/* tests/SummitUI.Tests.Manual/SummitUI.Tests.Manual/wwwroot/app.css */
@keyframes fadeInZoomIn {
from {
opacity: 0;
transform: scale(0.95);
}
to {
opacity: 1;
transform: scale(1);
}
}
@keyframes fadeOutZoomOut {
from {
opacity: 1;
transform: scale(1);
}
to {
opacity: 0;
transform: scale(0.95);
}
}
.animated-content[data-state="open"] {
animation: fadeInZoomIn 150ms ease-out forwards;
}
.animated-content[data-state="closed"] {
animation: fadeOutZoomOut 150ms ease-in forwards;
}
Casos de Prueba
Para cada componente (Select, DropdownMenu, Popover):
| Prueba | Qué Verifica |
|---|---|
Animated*_ShouldOpen_OnEnterKey | Se abre con teclado cuando hay animaciones presentes |
Animated*_ShouldNavigate_WithArrowKeys | Las flechas funcionan después de apertura animada |
Animated*_ShouldSelect/Activate_OnEnterKey | Puede seleccionar/activar un elemento después de apertura animada |
Animated*_ShouldClose_OnEscape | Escape activa la animación de cierre |
Ejecutar Pruebas de Animación
dotnet run --project tests/SummitUI.Tests.Playwright -- --treenode-filter '/*/*/*/Animated*'
Archivos Involucrados
| Archivo | Propósito |
|---|---|
src/SummitUI/Scripts/floating.js | Contiene las funciones focusElement y focusElementById |
src/SummitUI/Components/Select/SelectContent.cs | Llama a FocusElementAsync al abrir |
src/SummitUI/Components/DropdownMenu/DropdownMenuContent.cs | Llama a FocusElementByIdAsync para elementos del menú |
src/SummitUI/Components/Popover/PopoverContent.cs | Gestiona el enfoque para el contenido del popover |
Enfoques Alternativos Considerados
- Retraso inicial más largo - Podría usar 50-100ms de retraso antes del primer intento de enfoque, pero añade una latencia notable
- Enfocar antes de que comience la animación - Requeriría cambios en el orden de renderizado, complejo
- Desactivar animación durante el enfoque - Causaría un destello visual
- Usar
visibilityen lugar deopacityen CSS - Requeriría cambios en cómo se crean las animaciones
Se eligió el mecanismo de reintento porque:
- Funciona con cualquier duración de animación
- No requiere cambios en la creación de CSS
- Tiene un impacto mínimo en el rendimiento
- Fallas de manera elegante si el enfoque nunca tiene éxito
Patrones Relacionados
Este patrón es similar a cómo bits-ui maneja la presencia animada en componentes Svelte. La idea clave es que las operaciones del DOM (como el enfoque) pueden necesitar esperar a que las animaciones CSS alcancen un estado enfocable.