Gerenciamento de Foco com Animações CSS
Este documento captura aprendizados sobre como corrigir problemas de navegação por teclado quando componentes flutuantes (Select, DropdownMenu, Popover) possuem animações CSS de abertura/fechamento.
O Problema
Quando elementos de conteúdo flutuante têm animações CSS que começam com opacity: 0 (como animate-in fade-in-0 do Tailwind), o navegador pode rejeitar chamadas element.focus() porque o elemento está invisível.
Sintomas
- O componente abre corretamente com cliques do mouse
- A navegação por teclado (setas, Escape) não funciona após abrir com o teclado
- Funciona perfeitamente em demonstrações sem classes de animação
- Quebra em demonstrações com classes de animação
Causa Raiz
- Animações CSS como
fade-in-0começam o elemento comopacity: 0 - Quando
focus()é chamado imediatamente após a renderização, o elemento ainda está invisível - O navegador rejeita foco em elementos invisíveis
- O foco permanece no botão gatilho em vez de ir para o conteúdo
- Eventos de teclado vão para o gatilho (que não faz nada quando aberto) em vez do conteúdo
Evidência do Console de Depuração
// Após abrir o select, eventos de teclado vão para o gatilho, não para o conteúdo:
Document keydown: ArrowDown Target: <button role="combobox" ...>
// O elemento ativo é o gatilho, não o conteúdo:
Active: BUTTON summit-select-...-trigger
A Solução
Implementar um mecanismo de repetição para foco que permite que a animação progrida além de opacity: 0 antes de desistir.
Implementação em JavaScript
// src/SummitUI/Scripts/floating.js
/**
* Foca um elemento com mecanismo de repetição para elementos animados.
* Elementos com animações CSS começando com opacity:0 podem rejeitar o foco inicialmente.
* Isso repete a tentativa de foco até 5 vezes com atrasos de 20ms para permitir que a animação
* progrida além do estado invisível.
* @param {HTMLElement} element - Elemento a focar
*/
export function focusElement(element) {
if (!element) return;
function tryFocus(attempts) {
element.focus();
// Se o foco não foi bem-sucedido e ainda há tentativas restantes, repita
if (document.activeElement !== element && attempts > 0) {
setTimeout(() => tryFocus(attempts - 1), 20);
}
}
// Primeira tentativa após um frame para deixar o CSS ser aplicado
requestAnimationFrame(() => tryFocus(5));
}
Pontos-Chave
- Use
requestAnimationFrameprimeiro - Garante que o CSS foi aplicado antes de tentar o foco - Verifique
document.activeElement- Confirme se o foco realmente funcionou - Repita com atrasos - Intervalos de 20ms permitem que a animação progrida
- Tentativas limitadas - 5 repetições = 100ms de espera máxima, suficiente para animações típicas
- Aplique a todas as funções de foco - Tanto
focusElement(element)quantofocusElementById(id)precisam deste padrão
Funções Atualizadas
floating.js:focusElement(element)- Usado por SelectContentfloating.js:focusElementById(elementId)- Usado por DropdownMenuContent
Testes
Adicionadas seções "Com Animações" às páginas de demonstração de teste e testes Playwright correspondentes.
Classes CSS de Animação para Teste
/* 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 Teste
Para cada componente (Select, DropdownMenu, Popover):
| Teste | O Que Verifica |
|---|---|
Animated*_ShouldOpen_OnEnterKey | Abre com teclado quando animações estão presentes |
Animated*_ShouldNavigate_WithArrowKeys | Teclas de seta funcionam após abertura animada |
Animated*_ShouldSelect/Activate_OnEnterKey | Pode selecionar/ativar item após abertura animada |
Animated*_ShouldClose_OnEscape | Escape aciona a animação de fechamento |
Executando Testes de Animação
dotnet run --project tests/SummitUI.Tests.Playwright -- --treenode-filter '/*/*/*/Animated*'
Arquivos Envolvidos
| Arquivo | Propósito |
|---|---|
src/SummitUI/Scripts/floating.js | Contém as funções focusElement e focusElementById |
src/SummitUI/Components/Select/SelectContent.cs | Chama FocusElementAsync ao abrir |
src/SummitUI/Components/DropdownMenu/DropdownMenuContent.cs | Chama FocusElementByIdAsync para itens de menu |
src/SummitUI/Components/Popover/PopoverContent.cs | Gerencia o foco para conteúdo de popover |
Abordagens Alternativas Consideradas
- Atraso inicial maior - Poderia usar um atraso de 50-100ms antes da primeira tentativa de foco, mas adiciona latência perceptível
- Foco antes da animação começar - Exigiria mudanças na ordem de renderização, complexo
- Desabilitar animação durante o foco - Causaria um glitch visual
- Usar
visibilityem vez deopacityno CSS - Exigiria mudanças na forma como as animações são escritas
O mecanismo de repetição foi escolhido porque:
- Funciona com qualquer duração de animação
- Não requer alterações na forma como o CSS é escrito
- Tem impacto mínimo no desempenho
- Falha graciosamente se o foco nunca for bem-sucedido
Padrões Relacionados
Este padrão é semelhante a como o bits-ui lida com presença animada em componentes Svelte. A principal percepção é que operações DOM (como foco) podem precisar esperar que animações CSS atinjam um estado focalizável.