# Popover: API

## Пропсы корня

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | — | Нет | Элементы триггера и содержимого поповера. Должны включать компоненты `PopoverTrigger` и `PopoverContent`. |
| `placement` | `Placement` | `'bottom'` | Нет | Предпочтительное размещение поповера относительно триггера. Соответствует типу `Placement` из Floating UI (например, 'top', 'bottom-start'). |
| `open` | `boolean` | — | Нет | Управляет состоянием открытия поповера. Если задан, компонент становится контролируемым. |
| `defaultOpen` | `boolean` | `false` | Нет | Начальное состояние открытия для неконтролируемого использования. |
| `onChangeOpen` | `(state: boolean) => void` | — | Нет | Колбэк, вызываемый при изменении состояния открытия. |
| `role` | `'listbox' \| 'dialog'` | — | Нет | Определяет ARIA-роль содержимого поповера для доступности. 'listbox': для выпадающих меню и списков выбора; 'dialog': для модального содержимого с удержанием фокуса |

Также принимает все атрибуты `<div>`.

## Дочерние части

## `PopoverTrigger`

Кнопка, которая переключает поповер через нативный `popovertarget`. Устанавливает `aria-haspopup` по `role` корня; состояние раскрытия браузер сообщает сам на основе нативного `popovertarget`, поэтому `aria-expanded` и `aria-controls` не устанавливаются. Это обязательно должна быть кнопка: с `asChild` дочерний элемент должен рендерить `<button>`.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | — | Нет | Если true, рендерит триггер как его дочерний элемент через `Slot`. Дочерний элемент должен быть кнопкой: браузер открывает поповер через её `popovertarget`. |
| `ref` | `Ref<HTMLButtonElement>` | — | Нет | Ref, передаваемый на нижележащий элемент триггера. Полезен для управления фокусом, измерений или интеграций. |

Также принимает все атрибуты `<button>`.

## `PopoverContent`

Нативная панель `popover="auto"`.

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `shadowed` | `boolean` | `true` | Нет | Добавляет контейнеру компонента тень. Создаёт приподнятость и глубину, визуально отделяя содержимое от фона. |
| `ref` | `Ref<HTMLDivElement>` | — | Нет | Ref, передаваемый на нативный элемент `[popover]`. Полезен для управления фокусом, анимаций или измерения положения. |

Также принимает все атрибуты `<div>`.

- Рендерится всегда и скрыта, пока поповер закрыт; её дочерние элементы рендерятся, только пока он открыт.
- Браузер закрывает её по клику снаружи или `Escape`, складывает вложенные поповеры в стек и возвращает фокус на триггер.
- Открытие не переводит фокус в содержимое; в него можно попасть клавишей `Tab` с триггера. Safari так не делает, поэтому пользователи клавиатуры там не могут перейти с триггера в содержимое через `Tab`.
- `shadowed` (по умолчанию `true`) добавляет тень поверхности.

## Типы

- `PopoverProps`
- `PopoverTriggerProps`
- `PopoverContentProps`

## Модель состояния

- Состояние открытия может быть контролируемым или неконтролируемым.
- Позиционирование содержимого живёт в модели корня; клик снаружи и `Escape` обрабатывает браузер, и они проходят через `onChangeOpen(false)`.
- Для продвинутых обёрток и помощников состояния открытия доступен `usePopoverContext`. Он больше не предоставляет контекст и пропсы floating-ui.
- `PopoverContent` рендерится в верхнем слое через `popover="auto"`; портал не нужен.
- Поповер с затемнённой подложкой — это модальный паттерн: используйте `Dialog` или `Sheet`.