Popups-engine

Движок для управления попапами в React с поддержкой кастомных компонентов и анимаций через motion.

Версия motion: ^12.24.7

Установка

npm i @barabel324/popups-engine

Основные компоненты

PopupsEngineProvider

Провайдер для регистрации и управления попапами.

<PopupsEngineProvider popups={popups}>
  {children}

  <PopupsEngineRoot
    id="popups-root"
    lockBodyScroll={() => (document.body.style.overflow = 'hidden')}
    enableBodyScroll={() => (document.body.style.overflow = '')}
  />
</PopupsEngineProvider>

PopupsEngineRoot

Компонент, который рендерит все попапы и обёртки. Обычно используется один раз в корне приложения.

<PopupsEngineRoot
  id="popups-root"
  lockBodyScroll={() => (document.body.style.overflow = 'hidden')}
  enableBodyScroll={() => (document.body.style.overflow = '')}
/>

Пропсы

Проп	Тип	Описание
id	string	id атрибут для корневого элемента попапов
lockBodyScroll	() => void	Функция блокировки скролла страницы
enableBodyScroll	() => void	Функция разблокировки скролла страницы
components	TPEComponents	Кастомные компоненты. openPopup имеет приоритет над этим пропсом
classNames	TPEClassNames	Кастомные классы. openPopup имеет приоритет над этим пропсом
motionVariants	TPEMotionVariants	Анимации для motion-обёртки попапа. openPopup имеет приоритет

PopupsEngineProvider должен оборачивать приложение, а PopupsEngineRoot должен быть отрендерен внутри него.

Хук usePopupsEngineProvider

Позволяет управлять попапами внутри компонентов.

const {
  openPopup,
  closePopup,
  closeFirstPopup,
  closeAllPopups,
} = usePopupsEngineProvider();

openPopup({ variant: 'MyPopup', popupProps: { title: 'Hello' } });
closePopup();
closeFirstPopup();
closeAllPopups();

Пропсы openPopup

Проп	Тип	Описание
variant	string	Ключ попапа, зарегистрированного в провайдере
popupProps	Record<string, any>	Пропсы, передаваемые в компонент попапа
isCloseAll	boolean	Закрывать ли все попапы при вызове close внутри попапа
components	TPEComponents	Кастомные компоненты. Приоритет над PopupsEngineRoot
classNames	TPEClassNames	Кастомные классы. Приоритет над PopupsEngineRoot
motionVariants	TPEMotionVariants	Анимации для motion-обёртки попапа. Приоритет над PopupsEngineRoot

Кастомизация

Кастомизация возможна глобально через PopupsEngineRoot или локально через openPopup.

Пропсы, переданные в openPopup, имеют приоритет над пропсами PopupsEngineRoot.

Компоненты

const components = {
  wrapper: CustomWrapper,
  loader: CustomLoader,
};

Классы

const classNames = {
  wrapper: 'my-wrapper-class',
  loader: 'my-loader-class',
};

Анимации (motion / framer-motion)

const motionVariants = {
  initial: { opacity: 0, y: -20 },
  animate: { opacity: 1, y: 0 },
  exit: { opacity: 0, y: 20 },
};

Дженерики

TPEComponentWrapper — дженерик для типизации попапов. Библиотека автоматически передаёт в компонент служебные пропсы (например, closePopup).

Минимальный пример

// '@/popup-templates/message'
export const PopupMessage: TPEComponentWrapper<TPopupMessage> = ({
  title,
  description,
  closePopup,
}) => (
  <div>
    <div>{title}</div>
    <div>{description}</div>
    <button type="button" onClick={closePopup}>
      close
    </button>
  </div>
);

// '@/popup-templates'
const popups = {
  message: lazy(() => import('@views/popup-templates/message')),
};

// '@/show-popup'
export const ShowPopup = () => {
  const { openPopup } = usePopupsEngineProvider();

  return (
    <button
      type="button"
      onClick={() =>
        openPopup({
          variant: 'message',
          popupProps: {
            title: 'I am popup',
            description: 'Destroyer of the worlds',
          },
        })
      }
    >
      Press
    </button>
  );
};

// 'app.tsx'
import { PopupsEngineProvider, PopupsEngineRoot } from '@barabel324/popups-engine';
import '@barabel324/popups-engine/css';

<PopupsEngineProvider popups={popups}>
  <ShowPopup />
  <PopupsEngineRoot />
</PopupsEngineProvider>