feat(FocusTrap): refactor using focus guards

[EldarMuhamethanov]

• close [Feature][FocusTrap]: Экспортировать FocusTrap #5093
• relates to feat(Popover): add keepMount props #7058

---

• Unit-тесты
• Release notes

Описание

Рефакторинг хука useFocusTrap и компонента FocusTrap с целью улучшения архитектуры, упрощения логики и повышения гибкости использования.

Основные изменения:

• Разделение монолитного хука useFocusTrap на модульную структуру с выделением отдельных хуков useAutoFocus и useRestoreFocus
• Изменение API хука: теперь возвращает guard-элементы (beforeGuard, afterGuard) вместо их внутреннего рендеринга
• Упрощение логики Tab-навигации: переход на подход с guard-элементами вместо обработки keydown событий
• Разделение ответственности: удаление обработки Escape из FocusTrap - теперь компонент отвечает только за захват фокуса и Tab-навигацию
• Обработка Escape вынесена в компоненты через useGlobalEscKeyDown для большей гибкости
• Улучшение типизации: удаление зависимостей от UseFocusTrapProps в публичных API компонентов, добавление прямых типов для лучшей читаемости
• Обновление всех компонентов, использующих FocusTrap или useFocusTrap для работы с новым API

Изменения

Архитектурные изменения

1. Рефакторинг useFocusTrap:

   • Разделение на три модуля:
     • useFocusTrap.tsx - основной хук, координирующий работу
     • useAutoFocus.ts - логика автофокуса при монтировании
     • useRestoreFocus.ts - логика восстановления фокуса при размонтировании
   • Изменение возвращаемого значения: хук теперь возвращает {beforeGuard, afterGuard} вместо void
   • Упрощение логики Tab-навигации: использование guard-элементов с обработчиками onFocus вместо глобальных обработчиков keydown для Tab

2. Изменение компонента FocusTrap:

   • Разделение на FocusTrapInternal (с полным API) и FocusTrap (публичный API без внутренних опций)
   • Явный рендеринг guard-элементов в JSX вместо их скрытого создания внутри хука
   • Добавление атрибута data-focus-guard для идентификации guard-элементов
   • Удаление обработки Escape: удалены пропсы onClose и captureEscapeKeyboardEvent - теперь FocusTrap отвечает только за захват фокуса и Tab-навигацию

3. Обновление типизации:

   • Удаление зависимостей от UseFocusTrapProps в публичных типах компонентов (ModalCard, ModalPage, Alert, ActionSheet, Popover, OnboardingTooltip, DateInput, DateRangeInput)
   • Добавление прямых типов для restoreFocus, autoFocus, disableFocusTrap в интерфейсы компонентов
   • Улучшение читаемости и явности API

4. Обновление компонентов:

   • DateInput, DateRangeInput: переход на FocusTrapInternal для доступа к внутренним опциям
   • Все компоненты обновлены для работы с новым API guard-элементов
   • Обработка Escape вынесена в компоненты: Alert, ActionSheet, OnboardingTooltip, DateInput, DateRangeInput теперь используют useGlobalEscKeyDown для обработки нажатия Escape
   • Компоненты получили больше контроля над обработкой Escape (например, возможность использовать capture: false для DateInput и DateRangeInput)

5. Другие изменения:

   • Экспорт FocusTrap и FocusTrapProps добавлен в публичный API (src/index.ts)

Технические детали

• Guard-элементы теперь явно рендерятся в DOM, что упрощает отладку и тестирование
• Логика Tab-навигации упрощена: вместо перехвата всех Tab-событий используются guard-элементы, которые перенаправляют фокус при получении
• Улучшена производительность: удалена необходимость в arraysEquals для сравнения массивов фокусируемых элементов
• Улучшена читаемость кода: разделение ответственности между модулями
• Разделение ответственности: FocusTrap теперь отвечает только за управление фокусом (захват, Tab-навигация, автофокус, восстановление фокуса), а обработка Escape вынесена в компоненты
• Компоненты получили больше гибкости в обработке Escape: могут контролировать capture-режим, порядок обработки и другие аспекты

Release notes

[github-actions]

e2e tests

Playwright Report

[github-actions]

📊 Найдены изменения в собранных файлах: Отчет

Commit cb5dd29

[github-actions]

👀 Docs deployed

• ✅ Website
• ✅ Playground

📦 Package ✅

yarn add @vkontakte/vkui@https://development.s3.prodcloud.vk.team/pull/9330/cb5dd295ca993913bbf511e89ae4b009a3226b08/pkg/@vkontakte/vkui/_pkg.tgz

Commit cb5dd29

[codecov]

Codecov Report

❌ Patch coverage is 94.29825% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.92%. Comparing base (50455c2) to head (cb5dd29).
⚠️ Report is 4 commits behind head on master.

Files with missing lines	Patch %	Lines
...kages/vkui/src/hooks/useFocusTrap/useFocusTrap.tsx	89.04%	8 Missing ⚠️
...i/src/hooks/useFocusTrap/useRestoreFocusWrapper.ts	91.30%	2 Missing ⚠️
...kui/src/components/ModalPage/ModalPageInternal.tsx	88.88%	1 Missing ⚠️
...components/OnboardingTooltip/OnboardingTooltip.tsx	85.71%	1 Missing ⚠️
...ckages/vkui/src/hooks/useFocusTrap/useAutoFocus.ts	93.75%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #9330      +/-   ##
==========================================
- Coverage   94.96%   94.92%   -0.04%     
==========================================
  Files         436      440       +4     
  Lines       11752    11807      +55     
  Branches     4324     4339      +15     
==========================================
+ Hits        11160    11208      +48     
- Misses        592      599       +7     

Flag	Coverage Δ
unittests	94.92% <94.29%> (-0.04%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

size-limit report 📦

Path	Size
JS	410.25 KB (+0.53% 🔺)
JS (gzip)	125.76 KB (+0.46% 🔺)
JS (brotli)	104 KB (+0.35% 🔺)
JS import Div (tree shaking)	811 B (0%)
CSS	372.69 KB (0%)
CSS (gzip)	46.22 KB (0%)
CSS (brotli)	36.62 KB (0%)