CSS 애니메이션을 사용한 포커스 관리
이 문서는 플로팅 콘텐츠 요소(Select, DropdownMenu, Popover)에 CSS 오픈/클로즈 애니메이션이 있을 때 키보드 탐색 문제를 수정한 학습 내용을 기록합니다.
문제
플로팅 콘텐츠 요소에 opacity: 0으로 시작하는 CSS 애니메이션(Tailwind의 animate-in fade-in-0 등)이 있으면, 브라우저가 요소가 보이지 않는다고 판단하여 element.focus() 호출을 거부할 수 있습니다.
증상
- 마우스 클릭으로는 컴포넌트가 올바르게 열림
- 키보드로 연 후 키보드 탐색(화살표 키, Escape)이 작동하지 않음
- 애니메이션 클래스가 없는 데모에서는 정상 작동
- 애니메이션 클래스가 있는 데모에서는 작동하지 않음
근본 원인
fade-in-0과 같은 CSS 애니메이션은 요소를opacity: 0으로 시작함- 렌더링 직후
focus()가 호출되면 요소가 여전히 보이지 않음 - 브라우저가 보이지 않는 요소에 포커스를 거부함
- 포커스가 콘텐츠 대신 트리거 버튼에 남아 있음
- 키보드 이벤트가 콘텐츠 대신 트리거로 전달됨(트리거는 열려 있을 때 아무 동작도 하지 않음)
콘솔 디버깅 증거
// Select를 연 후, 키보드 이벤트가 콘텐츠가 아닌 트리거로 전달됨:
Document keydown: ArrowDown Target: <button role="combobox" ...>
// 활성 요소는 트리거이며, 콘텐츠가 아님:
Active: BUTTON summit-select-...-trigger
해결책
애니메이션이 opacity: 0 상태를 지나 진행될 수 있도록 포커스 재시도 메커니즘을 구현합니다.
JavaScript 구현
// src/SummitUI/Scripts/floating.js
/**
* 애니메이션 요소를 위한 재시도 메커니즘으로 요소에 포커스를 설정합니다.
* opacity:0으로 시작하는 CSS 애니메이션이 있는 요소는 초기에 focus()를 거부할 수 있습니다.
* 애니메이션이 보이지 않는 상태를 지나 진행될 수 있도록 20ms 지연으로 최대 5회 재시도합니다.
* @param {HTMLElement} element - 포커스를 설정할 요소
*/
export function focusElement(element) {
if (!element) return;
function tryFocus(attempts) {
element.focus();
// 포커스가 성공하지 않았고 시도 횟수가 남아 있으면 재시도
if (document.activeElement !== element && attempts > 0) {
setTimeout(() => tryFocus(attempts - 1), 20);
}
}
// CSS가 적용될 수 있도록 한 프레임 후 첫 번째 시도
requestAnimationFrame(() => tryFocus(5));
}
핵심 사항
- 먼저
requestAnimationFrame사용 - 포커스를 시도하기 전에 CSS가 적용되었는지 확인 document.activeElement확인 - 포커스가 실제로 성공했는지 검증- 지연과 함께 재시도 - 20ms 간격으로 애니메이션이 진행될 수 있도록 함
- 제한된 시도 횟수 - 5회 재시도 = 최대 100ms 대기, 일반적인 애니메이션에 충분
- 모든 포커스 함수에 적용 -
focusElement(element)와focusElementById(id)모두 이 패턴 필요
업데이트된 함수
floating.js:focusElement(element)- SelectContent에서 사용floating.js:focusElementById(elementId)- DropdownMenuContent에서 사용
테스트
테스트 데모 페이지에 "애니메이션 포함" 섹션과 해당 Playwright 테스트를 추가했습니다.
테스트용 CSS 애니메이션 클래스
/* 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;
}
테스트 케이스
각 컴포넌트(Select, DropdownMenu, Popover)에 대해:
| 테스트 | 검증 내용 |
|---|---|
Animated*_ShouldOpen_OnEnterKey | 애니메이션이 있을 때 키보드로 열림 |
Animated*_ShouldNavigate_WithArrowKeys | 애니메이션으로 열린 후 화살표 키 작동 |
Animated*_ShouldSelect/Activate_OnEnterKey | 애니메이션으로 열린 후 항목 선택/활성화 가능 |
Animated*_ShouldClose_OnEscape | Escape가 닫기 애니메이션 트리거 |
애니메이션 테스트 실행
dotnet run --project tests/SummitUI.Tests.Playwright -- --treenode-filter '/*/*/*/Animated*'
관련 파일
| 파일 | 목적 |
|---|---|
src/SummitUI/Scripts/floating.js | focusElement 및 focusElementById 함수 포함 |
src/SummitUI/Components/Select/SelectContent.cs | 열릴 때 FocusElementAsync 호출 |
src/SummitUI/Components/DropdownMenu/DropdownMenuContent.cs | 메뉴 항목에 대해 FocusElementByIdAsync 호출 |
src/SummitUI/Components/Popover/PopoverContent.cs | 팝오버 콘텐츠에 대한 포커스 관리 |
고려된 대체 접근 방식
- 더 긴 초기 지연 - 첫 포커스 시도 전에 50-100ms 지연을 사용할 수 있지만 눈에 띄는 지연이 발생함
- 애니메이션 시작 전 포커스 - 렌더링 순서 변경이 필요해 복잡함
- 포커스 중 애니메이션 비활성화 - 시각적 결함이 발생함
opacity대신 CSSvisibility사용 - 애니메이션 작성 방식을 변경해야 함
재시도 메커니즘을 선택한 이유:
- 모든 애니메이션 지속 시간과 호환됨
- CSS 작성 방식을 변경할 필요 없음
- 성능 영향이 최소화됨
- 포커스가 결코 성공하지 않아도 정상적으로 실패 처리됨
관련 패턴
이 패턴은 Svelte 컴포넌트에서 bits-ui가 애니메이션 존재를 처리하는 방식과 유사합니다. 핵심 통찰은 DOM 작업(예: 포커스)이 CSS 애니메이션이 포커스 가능한 상태에 도달할 때까지 기다려야 할 수 있다는 것입니다.