refactor: ModalRoot/ModalPage/ModalCard

[inomdzhon]

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

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

• [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
• feat: mv useKeyboard to useVirtualKeyboardState #7959

Нюансы

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

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

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

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-событий

Release notes

BREAKING CHANGE

• ModalRoot: удалена реализация контекста через React.cloneElement, которая требовала передавать settlingHeight и dynamicContentHeight в обёртки над ModalPage / ModalCard.

  Пример миграции (перенос `settlingHeight` / `dynamicContentHeight`)

  const SomeWrapper = ({ id }) => (
    <ModalPage
      id={id}
  +   settlingHeight={100} // или dynamicContentHeight
    />
  );
  
  <ModalRoot activeModal="m">
    <SomeWrapper
      id="m"
  -   settlingHeight={100} // или dynamicContentHeight
    />
  </ModalRoot>

  Пример миграции (пробрасывание `settlingHeight` / `dynamicContentHeight`)

  - const SomeWrapper = ({ id }) => (
  + const SomeWrapper = (props) => (
    <ModalPage
  -   id={id}
  +   {...props}
    />
  );
  
  <ModalRoot activeModal="m">
    <SomeWrapper
      id="m"
      settlingHeight={100} // или dynamicContentHeight
    />
  </ModalRoot>

Улучшения

• ModalRoot:
  • updateModalHeight() помечен как @depreacted, т.к. в нём больше нет необходимости – ModalPage, при dynamicContentHeight, теперь автоматически подстраиваются под контент;
  • registerModal() помечен как @depreacted, т.к. изменилась логика работы компонента – теперь ModalPage и ModalCard ориентируется на контекст, создаваемый ModalRoot;
  • добавлено свойство usePortal.
• ModalPage:
  • теперь можно использовать без ModalRoot (для рендера в портале можно обернуть в AppRootPortal);
  • изменилось значение по умолчанию у свойств settlingHeight – 75 → 50 ;
  • добавлено свойство keepMounted;
  • добавлено свойство footer;
  • добавлено свойство disableContentPanningGestureProp;
  • расширен тип onClose до (reason: ModalPageCloseReason, event?: UIEvent<HTMLElement>) => void.
• ModalCard:
  • теперь можно использовать без ModalRoot (для рендера в портале можно обернуть в AppRootPortal);
  • добавлено свойство keepMounted;
  • расширен тип onClose до (reason: ModalPageCloseReason, event?: UIEvent<HTMLElement>) => void.

[github-actions]

size-limit report 📦

Path	Size
JS	384.63 KB (-0.25% 🔽)
JS (gzip)	116.33 KB (-0.45% 🔽)
JS (brotli)	95.78 KB (-0.41% 🔽)
JS import Div (tree shaking)	1.56 KB (0%)
CSS	337.07 KB (+0.64% 🔺)
CSS (gzip)	42.75 KB (+0.88% 🔺)
CSS (brotli)	33.77 KB (+1.04% 🔺)

[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 49b82a4:

Sandbox	Source
vkui boilerplate (forked)	Issue #1494

[github-actions]

e2e tests

Playwright Report

[github-actions]

👀 Docs deployed

• ✅ Styleguide
• ✅ Storybook

Commit 49b82a4

[codecov]

Codecov Report

Attention: Patch coverage is 95.86207% with 24 lines in your changes missing coverage. Please review.

Project coverage is 95.49%. Comparing base (95b518c) to head (49b82a4).
Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
...kui/src/components/ModalPage/ModalPageInternal.tsx	87.83%	9 Missing ⚠️
...ckages/vkui/src/components/ModalPage/ModalPage.tsx	85.71%	6 Missing ⚠️
...kui/src/components/ModalCard/ModalCardInternal.tsx	92.15%	4 Missing ⚠️
...src/lib/sheet/controllers/BottomSheetController.ts	98.97%	2 Missing ⚠️
packages/vkui/src/lib/sheet/index.ts	71.42%	2 Missing ⚠️
.../vkui/src/components/ModalOverlay/ModalOverlay.tsx	91.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6759      +/-   ##
==========================================
+ Coverage   95.45%   95.49%   +0.03%     
==========================================
  Files         384      393       +9     
  Lines       11312    11188     -124     
  Branches     3780     3708      -72     
==========================================
- Hits        10798    10684     -114     
+ Misses        514      504      -10     

Flag	Coverage Δ
unittests	95.49% <95.86%> (+0.03%)	⬆️

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.

[andrey-medvedev-vk]

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

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

---

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

---

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

[inomdzhon]

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

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

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

[BlackySoul]

Ещё заметила, что как будто пропала фича, которая позволяла высоту модалки "запоминать". Т.е. если мы вытянули первую модалку на всю высоту, переключились на другую и вернулись на первую - первая должна сохранить высоту

[inomdzhon]

Ещё заметила, что как будто пропала фича, которая позволяла высоту модалки "запоминать". Т.е. если мы вытянули первую модалку на всю высоту, переключились на другую и вернулись на первую - первая должна сохранить высоту

воу, действительно, пропала...

• 8275749 – немного переделал логику в BottomSheetController (изначально не было необходимости сразу так сделать)
• 0346909 – а в этом коммите накидал логику сохранения состояния (🔗 Storybook, 🔗 Styleguide), но ух... получилось как-будто сложно 🥲 мб опустим? 😅 вообще по дизайну модалки должны друг на друга накладываться, а на iOS, при раскрытии на 100% эффект стека должен быть – отложил это на закуску после рефактора