@snack-uikit/popover-private

Popover Private

Installation

npm i @snack-uikit/popover-private

Changelog

Description

• Пакет @snack-uikit/popover-private предоставляет низкоуровневый компонент PopoverPrivate для отображения всплывающих окон (поповеров) относительно триггер-элемента.
• Компонент использует библиотеку Floating UI для позиционирования и автоматической адаптации поповера при выходе за границы видимой области.
• Поддерживает различные типы триггеров отображения: клик, ховер, фокус и их комбинации (click, hover, focus, focusVisible, hoverAndFocus, hoverAndFocusVisible, clickAndFocusVisible).
• Позволяет задать 12 вариантов размещения поповера относительно триггера (top, bottom, left, right и их вариации с -start и -end), а также цепочку резервных позиций (fallbackPlacements) для автоматического переключения при нехватке места.
• Поддерживает управляемый и неуправляемый режимы работы через пропы open и onOpenChange.
• Предоставляет гибкие стратегии управления размерами контейнера поповера: автоматические размеры по контенту, привязка к ширине/высоте триггера (widthStrategy, heightStrategy).
• Может отображать стрелку (hasArrow), указывающую на триггер, с настраиваемыми CSS-классами для стилизации.
• Поддерживает различные варианты работы с триггером: оборачивание элемента в span, передача функции-рендера, использование внешнего ref без оборачивания (triggerRef, disableSpanWrapper).
• Автоматически закрывается при клике вне поповера, по нажатию Esc, при навигации по истории браузера (опционально).
• Поддерживает задержки открытия и закрытия для триггера hover (hoverDelayOpen, hoverDelayClose).
• Работает с вложенными поповерами через FloatingTree из Floating UI.

Example

import { useRef } from "react";
import { PopoverPrivate } from "@snack-uikit/popover-private";

function App() {
  return (
    <PopoverPrivate
        placement='top'
        popoverContent='Не нажимать, опасно!'
        trigger='click'
      >
        <button>Button with popover</button>
    </PopoverPrivate>
  );
}

// Без оборачивания таргета
function App() {
  const triggerRef = useRef(null)

  return (
    <>
      <PopoverPrivate
        placement='top'
        popoverContent='Не нажимать, опасно!'
        trigger='click'
        triggerRef={triggerRef}
      />
      <button ref={triggerRef}>Button with popover</button>
    </>
  );
}

PopoverPrivate

Props

children: ReactNode | ChildrenFunction

Референс, относительно которого рисуется поповер. Возможно несколько вариантов:

• в children передан компонент, который принимает в себя ref. В таком случае пропсы этого компонента будут дополнены необходимыми для работы триггеров отображения: useHoverTrigger, useClickTrigger, useFocusTrigger.

  Осторожно, ref будет перезаписан. Если вы хотите получить ref на children поповера, можете передать ref в параметр triggerRef. Тогда поповер установит туда значение:

    <PopoverPrivate
      popoverContent={<div className={style.content}>some tip here</div>}
      useHoverTrigger
      triggerRef={(button) => { /* button HTMLElement из children */ }}
    >
      <button>some button</button>
    </PopoverPrivate>

• в children передан компонент, который НЕ принимает в себя ref. В таком случае компонент будет обернут в span, который и послужит рефом для поповера.

• в children передана функция. Эта функция будет вызвана на каждый рендер, она должна возвращать ReactNode. В параметры принимает ref, который нужно установить в целевой компонент и функцию getReferenceProps, возвращающую необходимые для ref параметры. Пример:

    <PopoverPrivate
      popoverContent={<div className={style.content}>some tip here</div>}
      useHoverTrigger
    >
      {({ getReferenceProps, ref }) => (
        <label>
          Set the value
          <input ref={ref} {...getReferenceProps({ onClick: onClickInputHandler })} />
        </label>
      )}
    </PopoverPrivate>

• в children передан примитив string, number или React.Fragment. Children будет обернут в span.

• children не передан в компонент, в таком случае необходимо передать ref элемента в triggerRef, который будет служить триггером для поповера. Пример:

const triggerRef = useRef(null)

return (
  <>
    <PopoverPrivate 
      popoverContent={<div className={style.content}>some tip here</div>}
      useHoverTrigger
      triggerRef={triggerRef}
    />
    <button ref={triggerRef}>Click me</button>
  </>
)