PopoverPrivate
@cloud-ru/ds-popover-private — внутренний строительный блок: бесстилевая обёртка над @floating-ui/react с поддержкой placement, offset, авто-flip, стрелки и нескольких триггеров (click, hover, focus, controlled open). Поверх него собраны публичные @cloud-ru/ds-tooltip, @cloud-ru/ds-popover, @cloud-ru/ds-dropdown. В продуктовом коде используйте их.
Когда использовать
- Реализация нового публичного компонента, которому нужно всплывающее окно (например, контекстное меню новой формы).
- Очень специфический сценарий, который не покрыт
Tooltip/Popover/Dropdown.
В обычной разработке — берите публичный компонент.
Установка
pnpm add @cloud-ru/ds-popover-privateimport { PopoverPrivate, Arrow } from '@cloud-ru/ds-popover-private'Props
PopoverPrivate
Types
Props
PopoverPrivateProps| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
arrowContainerClassName | string | — | no | CSS-класс контейнера стрелки поповера |
arrowElementClassName | string | — | no | CSS-класс стрелки поповера |
children | ReactNode | ChildrenFunction | — | no | Триггер поповера (подробнее читайте ниже) |
className | string | — | no | |
closeOnEscapeKey | boolean | true | no | Закрывать ли по нажатию на кнопку `Esc` |
closeOnPopstate | boolean | — | no | Закрывать ли поповер при переходе по истории браузера |
container | RefObject<HTMLElement | null> | — | no | Контейнер портала (ref). Переопределяет `PortalContext` для этого инстанса — по аналогии с `container` у Modal/Drawer. По умолчанию берётся из `PortalContextProvider`. |
data-test-id | string | — | no | |
disableSpanWrapper | boolean | — | no | Отключает для `isValidElement` внешнюю обертку триггера <br/> Пригодится для элементов с `position: absolute` <br/> Работает для триггеров, которые умеют отдать свою DOM-ноду: нативные элементы, `forwardRef`-компоненты и компоненты, помеченные `withInnerRefSupport` из `@cloud-ru/ds-utils`. Остальные всё равно получают `<span>` — без ноды поповеру не от чего счита ть позицию; в dev-режиме об этом печатается предупреждение. |
escapeKeyBubbles | boolean | false | no | Пропускать ли `Esc` дальше после закрытия поповера. Без этого открытый поповер гасит всплытие `Esc`, и внешний поповер (например, дроплист, чей триггер несёт тултип) не закроется. |
fallbackPlacements | Placement[] | — | no | Цепочка расположений которая будет применяться к поповеру от первого к последнему если при текущем он не влезает. |
hasArrow | boolean | — | no | Параметр наличия стрелки у поповера. В размеры стрелки встроен отступ. Дополнительный отступ может быть задан параметром `offset`. У элемента стрелки нет цвета, необходимо задавать его через параметр `arrowClassName`. |
heightStrategy | "auto" | "eq" | "lte" | auto | no | Стратегия управления высотой контейнера поповера <br/> - `auto` - соответствует высоте контента, <br/> - `lte` - Less Than or Equal, равен высоте таргета или меньше ее, если контент в поповере меньше, <br/> - `eq` - Equal, строго равен высоте таргета. |
hoverDelayClose | number | — | no | Задержка закрытия по ховеру |
hoverDelayOpen | number | — | no | Задержка открытия по ховеру |
offset | number | 0 | no | Отступ поповера от его триггер-элемента (в пикселях). |
onOpenChange | ((isOpen: boolean) => void) | — | no | Колбек отображения компонента. Срабатывает при изменении состояния open. |
open | boolean | — | no | Управляет состоянием показан/не показан. |
outsideClick | boolean | OutsideClickHandler | — | no | Закрывать ли при клике вне поповера |
placement | "bottom" | "bottom-end" | "bottom-start" | "left" | "left-end" | "left-start" | "right" | "right-end" | "right-start" | "top" | "top-end" | "top-start" | top | yes | Положение поповера относительно своего триггера (children). |
popoverContent | ReactNode | ReactNode[] | — | yes | Контент поповера |
stopPropagation | StopPropagationHandlers | { onClick: true, onMouseDown: true, onMouseUp: true, onTouchStart: true, onTouchEnd: true, onTouchMove: true } | no | Гасить всплытие pointer/touch-событий с floating-контейнера (`stopPropagation`). По умолчанию все хендлеры включены. Для drag&drop внутри поповера отключите `onMouseUp` / `onTouchEnd`, чтобы они дошли до `document`. |
trigger | "click" | "clickAndFocusVisible" | "focus" | "focusVisible" | "hover" | "hoverAndFocus" | "hoverAndFocusVisible" | — | yes | Условие отображения поповера: <br/> - `click` - открывать по клику <br/> - `hover` - открывать по ховеру <br/> - `focusVisible` - открывать по focus-visible <br/> - `focus` - открывать по фокусу <br/> - `hoverAndFocusVisible` - открывать по ховеру и focus-visible <br/> - `hoverAndFocus` - открывать по ховеру и фокусу <br/> - `clickAndFocusVisible` - открывать по клику и focus-visible |
triggerClassName | string | — | no | CSS-класс триггера |
triggerClickByKeys | boolean | true | no | Вызывается ли попоповер по нажатию клавиш Enter/Space (при trigger = `click`) |
triggerRef | ForwardedRef<HTMLElement | ReferenceType | null> | — | no | Ref ссылка на триггер |
widthStrategy | "auto" | "eq" | "gte" | auto | no | Стратегия управления шириной контейнера поповера <br/> - `auto` - соответствует ширине контента, <br/> - `gte` - Great Than or Equal, равен ширине таргета или больше ее, если контент в поповере шире, <br/> - `eq` - Equal, строго равен ширине таргета. |
Unions
Types
PopoverPrivateProps
ChildrenFunction
OutsideClickHandler
StopPropagationHandlers
Unions
Placement
PopoverHeightStrategy
PopoverWidthStrategy
Trigger
Arrow
Types
Props
ArrowProps| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
arrowContainerClassName | string | — | no | |
arrowElementClassName | string | — | no | |
arrowRef | RefObject<HTMLDivElement | null> | — | yes | |
placement | "bottom" | "bottom-end" | "bottom-start" | "left" | "left-end" | "left-start" | "right" | "right-end" | "right-start" | "top" | "top-end" | "top-start" | — | yes | |
x | number | — | no | |
y | number | — | no |