refactor: ModalRoot/ModalPage/ModalCard

[inomdzhon]

• close [Feature] Переписать модальные окна #2449
• fix [Bug] В модалках не работают внутренние скроллы #335 (см. Решения → Вертикальный и горизонтальный скроллы)
• close На ios некорректно работает скролл в модальном окне. #604 (не воспроизводится)
• fix [Bug] Скролл в модалке перестает работать #876 (не воспроизводится)
• fix [Bug] Highlighting text in modalRoot #1071 (см. Решения → Выделение текста)
• fix [Bug] CardScroll не работает в модальном окне #1494 (см. Решения → Вертикальный и горизонтальный скроллы)
• resolve [Feature] Фиксированные кнопки для ModalPage #1570
• resolve [Feature] Разделить settlingHeight и fullscreen #1697
• fix [Bug] Модалки ломаются, если начальная высота контента 0px #2008, [Bug] Открытие пальцем/курсором ломается в ModalPage #2029 (теперь нельзя выставить settlingHeight в 0, минимальное значение ограничено до 25, а максимальное до 100)
• fix [Bug]: Компонент ChipSelect. Проблема со скролом выпадающего списка при использовании в мобильном приложении. #3028 (см. Решения → Плавающие элементы внутри модалки)
• fix [Feature]: Добавить возможность отключать сворачивание ModalCard и ModalPage жестом вниз #3628 (см. Решения)
• fix [Bug]: На мобильных устройствах не работает скролл выпадающего списка компонента CustomSelect (React v18.2.0) #5540 (см. Решения → Плавающие элементы внутри модалки)

Проверить после

• Не работает бегунок скролла в модалке IOS #741
• [Bug] Клавиатура в мобильном клиенте на Android перекрывает ModalPage #961

---

• Unit-тесты
• e2e-тесты
• Дизайн-ревью
• Документация фичи
• Release notes

---

Описание

Переписаны компоненты ModalPage/ModalCard

⚠️ Теперь компоненты могут использоваться без ModalRoot.

ModalPage / ModalCard:

• добавлено свойство open;
• добавлено свойство keepMounted;
• типа onClose изменён с VoidFunction на (reason: ModalPageCloseReason, event?: UIEvent<HTMLElement>) => void;
• добавлено свойство noFocusToDialog, приоритетней чем noFocusToDialog в ModalRoot;
• добавлено свойство modalOverlayTestId, приоритетней чем modalOverlayTestId в ModalRoot.
• создан компонент ModalOutlet;
• создан компонент ModalOverlay;
• основной код работы модалок вынесен в отдельные компоненты ModalPageInternal и ModalCardInternal, у них есть свойство ModalOverlay;
• создан контекст ModalContext, который теперь используется в компонентах ModalPageHeader, Group и PanelHeader вместо ModalRootContext.

ModalPage:

• settlingHeight теперь имеет значение по умолчанию 50% вместо 75%, обратил внимание, что в обычно BottomSheet'ы открываются на половину экрана;
• добавлено свойство footer, а также создан компонент ModalPageFooter;
• созданы компонент ModalPageContent – вынес, чтобы можно было в будущем перейти на сбор ModalPage через композицию компонентов.

lib/sheet:

В папке хранится логика отвечающая за взаимодействие с модалкой на мобильных экранах. Отдаёт хук useBottomSheet().

Переписан компонент ModalRoot

⚠️ Теперь лишь отвечает за состояние open компонентов ModalCard и ModalPage в зависимости от их id/nav и параметра activeModal, а также рендера общей ModalOverlay для всех модалок.

ModalRoot:

• добавлены события onOpen, onOpened, onClosed, которые всплывают от activeModal;
• в PopoutRoot удалён PopoutRootModal в пользу ModalOutlet у ModalPage и ModalCard.

ModalRootContext:

• ⚠️ BREAKING CHANGE в свойство onClose нужно теперь обязательно передавать id модального окна;
• добавлены события onOpen, onOpened, onClosed, чтобы их могли вызывать ModalPage и ModalCard;
• свойство registerModal теперь @deprecated – не нужно отдельно регистрировать модальное окно.
• свойство updateModalHeight теперь @deprecated – задача с обновлением высоты контента при dynamicContentHeight решается через CSS;

ModalRootOverlayContext / VisuallyHiddenModalOverlay:

• чтобы создать общий ModalOverlay для всех модалок в контексте ModalRoot, происходит подмена ModalOverlay в ModalPage и ModalCard на VisuallyHiddenModalOverlay, который отвечает за приём onClick и modalOverlayTestId, а сам ModalOverlay попадает в начало ModalRoot

useModalManager():

• отвечает за unmounted состояние;
• отвечает за регулирования приоритета параметров из ModalRoot и ModalPage/ModalCard;
• отвечает за подмену ModalOverlay на VisuallyHiddenModalOverlay.

withModalRootContext:

• ввиду отказа от updateModalHeight HOC тоже @deprecated.

Изменения, которые нужно вынести в отдельные PR после первичного ревью

• feat: create useCSSTransition() #7876
• refactor(FocusTrap): mv to hook #7879
• feat(AppRoot): set overscrollBehavior to <html> #7881
• переименовал useKeyboard() в useVirtualKeyboardState()

Нюансы

Обратная совместимость

Постарался сделать так, чтобы миграция прошла бесследно.

Сломаются вот такой кейс:

const MyModal = ({ id }) => { // пропустили settinglingHeight / dynamicContentHeight
  return <ModalPage>Lorem Ipsum</ModalPage>
};

const App = () => (
  <ModalRoot>
    <MyModal
      id="example-1"
      settinglingHeight={100} // устанавливалось здесь, т.к. раньше ModalRoot итерировал по потомкам и доставал этот параметр
    />
    
    <MyModal
      id="example-2"
      dynamicContentHeight // устанавливалось здесь, т.к. раньше ModalRoot итерировал по потомкам и доставал этот параметр
    />
  </ModalRoot>
);

который нужно будет править руками.

BottomSheet, анимации и свайп

Полное появление и полное скрытие происходит через transform, но анимация взаимодействия через свайп реализована через height, т.к. это оказалось самым оптимальным способом для решения задач:

• закреплённый ModalPageFooter внизу;
• возможность скроллить при settlingHeight меньше 100;
• обновление высоты, если задан dynamicContentHeight.

Нашёл решение допустимым, т.к. свайп используется либо для закрытия, либо для разворачивания/сворачивания модального окна на всю или на половину страницы. В первом случае сработает закрытие через transform, а во втором разворачивание/сворачивание произойдёт через height.

dynamicContentHeight

см. предыдущий пункт про BottomSheet для контекста

Обновление высоты происходит без анимации, т.к. height: auto не анимируется. Опустил анимирование, т.к. усложняет компонент. В теории можно прибегнуть к useResizeObserver().

Адативность

При platform="vkcom" и при разрешении экрана 767px компонент теперь превращается в BottomSheet, но при этом логику взаимодействия через тач не имеет, т.к. isDesktop при platform="vkcom" всегда true вне зависимости от размера экрана.

Решения

Выделение текста

С помощью функции hasSelectionWithRangeType определяем, что пользователь выделил текст и перестаём реагировать на touchstart и touchmove пока выделение не будет удалено.

Вертикальный и горизонтальный скроллы

• вертикальный скролл::
  • основной скролл (ModalPageContent): проверяем на scrollTop !== 0
  • другие скроллы: при touchstart достаём скроллируемый элемент через event.target и проверяем на положение scrollTop !== 0 и направление пальца вверх
• горизонтальный скролл: не блочится, т.к. реагируем на события только по оси Y.

Плавающие элементы внутри модалки

Нужно рекомендовать использовать forcePortal – в коде проверяем, что идёт взаимодействие с элементом вне модалки.

Или нужно рекомендовать добавлять в корневой элемент плавающего элемента атрибут data-vkui-prevent-swipe .

Поля ввода

Наилучшего варианта не нашёл кроме как:

1. через useVirtualKeyboardState() узнавать, что пользователь работает с клавиатурой, и перебивать safe-area-inset-bottom на тот, что возвращает хук 0 (попытка вычислять разницу высоты через VisualViewport, чтобы реагировать на смену размера клавиатуры, например, из-за панели эмодзи, не удалась);
2. в том же хуке слушать событие скролла на window и сохранять его позицию на window.scrollTo(0, visualViewport.offsetTop).

Так как иные решения приводят к другим проблемам (подробнее можно прочесть в JSDoc хука useVirtualKeyboardState()), следующие баги нужно закрыть:

• В модальных окнах не хочет появлятся скролл при вводе с клавиатуры #338
• Не скролится модалка пока открыта клавиатура #599

Референсы

• Youtube • Универсальные попапы или UIKit против / Антон Спивак
• Habr • Bottom sheet: Scrolling and interactions
• How to present a Bottom Sheet in iOS 15 with UISheetPresentationController
• GitHub • ionic-framework/core/src/components/modal
• GitHub • stipsan/react-spring-bottom-sheet
• GitHub • gorhom/react-native-bottom-sheet
• GitHub • stanleyugwu/react-native-bottom-sheet
• GitHub • Temzasse/react-modal-sheet
• GitHub • tech-systems/panes
• feat: add ModalSheet #5092 – Пример рефактора модалок с помощью touch-событий

[github-actions]

size-limit report 📦

Path	Size
JS	384.1 KB (-0.36% 🔽)
JS (gzip)	116.18 KB (-0.57% 🔽)
JS (brotli)	95.69 KB (-0.45% 🔽)
JS import Div (tree shaking)	1.56 KB (0%)
CSS	337.19 KB (+0.66% 🔺)
CSS (gzip)	42.8 KB (+0.92% 🔺)
CSS (brotli)	33.7 KB (+0.84% 🔺)

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit d567e6e:

Sandbox	Source
vkui boilerplate (forked)	Issue #1494

[github-actions]

e2e tests

Playwright Report

[github-actions]

👀 Docs deployed

• ✅ Styleguide
• ✅ Storybook

Commit d567e6e

[codecov]

Codecov Report

Attention: Patch coverage is 64.53901% with 200 lines in your changes missing coverage. Please review.

Project coverage is 93.92%. Comparing base (d19c0bf) to head (d567e6e).

Files with missing lines	Patch %	Lines
...src/lib/sheet/controllers/BottomSheetController.ts	25.00%	147 Missing ⚠️
...c/lib/sheet/controllers/CSSTransitionController.ts	32.25%	21 Missing ⚠️
...kui/src/components/ModalPage/ModalPageInternal.tsx	88.00%	9 Missing ⚠️
packages/vkui/src/lib/sheet/useBottomSheet.ts	88.09%	5 Missing ⚠️
...kages/vkui/src/lib/touch/UIPanGestureRecognizer.ts	28.57%	5 Missing ⚠️
...kui/src/components/ModalCard/ModalCardInternal.tsx	92.15%	4 Missing ⚠️
packages/vkui/src/lib/dom.tsx	69.23%	4 Missing ⚠️
packages/vkui/src/lib/adaptivity/functions.ts	60.00%	2 Missing ⚠️
packages/vkui/src/lib/sheet/index.ts	60.00%	2 Missing ⚠️
.../vkui/src/components/ModalOverlay/ModalOverlay.tsx	91.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6759      +/-   ##
==========================================
- Coverage   95.47%   93.92%   -1.55%     
==========================================
  Files         380      389       +9     
  Lines       11325    11182     -143     
  Branches     3777     3699      -78     
==========================================
- Hits        10812    10503     -309     
- Misses        513      679     +166     

Flag	Coverage Δ
unittests	93.92% <64.53%> (-1.55%)	⬇️

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.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests
• JS Bundle Analysis - Avoid shipping oversized bundles

[andrey-medvedev-vk]

Грандиозная работа! 👏 👏 👏 💪

Здорово раскидал по компонентам!
Понравилось, что компоненты теперь функции как практически везде!
Офигенно как переведена анимация/перетаскивание на CSS Transition и контроллеры. (Там я, конечно, поплыл, но приятно видеть знакомое API с коллбэками и то, что всё сводится к установке css переменных)

---

Надо пристально пройтись по местам где коллбёки передаются в компоненты, а не напрямую в html элементы и обернуть их useCallback, и по местам, где объекты возвращаются из хуков или передаются в контекст, чтобы обернуть в useMemo и избежать лишних ререндеров.

---

По стайлгайду и сторибуку прошелся и так и на устройстве, ничего такого не заметил.

[inomdzhon]

Надо пристально пройтись по местам где коллбёки передаются в компоненты, а не напрямую в html элементы и обернуть их useCallback, и по местам, где объекты возвращаются из хуков или передаются в контекст, чтобы обернуть в useMemo и избежать лишних ререндеров.

добавил мемоизацию там где можно, но во всех местах сильная завязка на пользователя, т.к. используются колбеки (onOpen, onOpened, onClose, onClosed), которые пользователь сам должен мемоизировать

ждём React 19, где не нужно будет руками мемоизировать)