From feebee9f36a7604a3cb23026f1b20ea5c2a5cd90 Mon Sep 17 00:00:00 2001 From: Andrey Morozov Date: Thu, 16 Jan 2025 15:27:49 +0300 Subject: [PATCH] docs(Popup): fix docs --- src/components/Popup/README-ru.md | 359 ++++++++---------------------- src/components/Popup/README.md | 118 +++++----- 2 files changed, 147 insertions(+), 330 deletions(-) diff --git a/src/components/Popup/README-ru.md b/src/components/Popup/README-ru.md index 666a1090b3..fc55d0169e 100644 --- a/src/components/Popup/README-ru.md +++ b/src/components/Popup/README-ru.md @@ -1,300 +1,127 @@ -# Popover +# Popup ```tsx -import {Popover} from '@gravity-ui/uikit'; +import {Popup} from '@gravity-ui/uikit'; ``` -Компонент `Popover` позволяет добавить раздел с всплывающим содержимым. +You can use a `Popup` to display floating content above the page. Technically, it is a wrapper around [Floating UI](https://floating-ui.com) with some default values. To manage `Popup` visibility, use the `open` property. +The `Popup` child components are rendered inside the [`Portal`](../Portal) component. To disable this behavior, use the `disablePortal` property. -### Стандартное использование +## Anchor - - - - -```tsx -Open a tooltip -``` - - - -### С JSX-контентом +To specify the anchor of a floating element, you can use the `anchorElement` property. - - - -```tsx -}>Open a tooltip -``` - - - -### С HTML-контентом - - - - -```tsx -html content. Learn more here' - } -> - Open a tooltip - -``` - - - -### Со ссылками - ```tsx - alert('The link is clicked'), - }, - ]} -> - Open a tooltip - +const [buttonElement, setButtonElement] = React.useState(null); +const [open, setOpen] = React.useState(false); + + + + Content + ``` -### С кнопкой действия +## Placement - - - - -```tsx - console.log('Action button was clicked'), - }} -> - Open a tooltip - -``` - - - -### С автоматическим закрытием, когда курсор находится вне области в течение `delayClosing` +Use the `placement` property to manage the `Popup` position around the anchor element. +By default, `Popup` uses [flip middleware](https://floating-ui.com/docs/flip) to prevent overflow. +If the property is set to an array, the first element will be used as the default placement value, the rest will be used as [fallback placements](https://floating-ui.com/docs/flip#fallbackplacements). +It is also acceptable to use the values `auto`, `auto-start`, `auto-end` to use [autoPlacement middleware](https://floating-ui.com/docs/autoPlacement) instead of flip. - - -```tsx - console.log('Action button was clicked'), - }} -> - Open a tooltip - -``` - - - -## Использование экземпляра - -```tsx -import {Popover, PopoverInstanceProps} from '@gravity-ui/uikit'; - -const popoverRef = useRef(); - -const open = () => { - popoverRef.current?.openTooltip(); -}; - -const close = () => { - popoverRef.current?.closeTooltip(); -}; - -<> - - - -; -``` - -### Свойства экземпляра - -| Имя | Описание | Тип | Значение по умолчанию | -| ------------ | ------------------------------ | :--------: | :-------------------: | -| openTooltip | Открывает тултип `() => void`. | `Function` | | -| closeTooltip | Закрывает тултип `() => void`. | `Function` | | - -## Свойства - -| Имя | Описание | Тип | Значение по умолчанию | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------: | :-------------------: | -| anchorRef | Элемент-якорь `Popper.js`, который также может быть `popper.VirtualElement`. | [`PopupAnchorRef`](../Popup/README.md#anchor) | | -| autoclosable | Включает или отключает автоматическое закрытие тултипа при выходе курсора за его пределы. | `boolean` | `true` | -| autoFocus | Если установлено значение `true`, фокус будет перемещен на первый элемент при открытии компонента `Popover`. | `boolean` | | -| behavior | Поведение тултипа при его открытии или закрытии с использованием `openOnHover`: `"immediate"` — без каких-либо задержек, `"delayed"` — с задержкой 300 мс при открытии и закрытии, `"delayedClosing"` — с задержкой 300 мс только при закрытии. Это свойство не будет работать, если заданы `delayOpening` или `delayClosing`. | `"immediate"` `"delayed"` `"delayedClosing"` | `"delayed"` | -| children | Контент, который служит триггером для отображаемого над ним тултипа. Может принимать значения функции `(triggerProps: `[`TriggerProps`](#triggerprops))` => React.ReactNode` или `ReactNode`. | `React.ReactNode` `Function` | | -| className | CSS-класс контрола. | `string` | | -| content | Содержимое тултипа. | `React.ReactNode` | | -| contentClassName | CSS-класс для `content`. | `string` | | -| delayClosing | Пользовательская задержка закрытия, если задано свойство `autoclosable`. | `number` | | -| delayOpening | Пользовательская задержка открытия, если задано свойство `openOnHover`. | `number` | | -| disabled | Отключает возможность изменения состояния открытия. | `boolean` | `false` | -| disablePortal | Отключает рендеринг компонента `Popover` в портале. | `boolean` | `false` | -| focusTrap | Не допускает выхода фокуса за пределы `Popover`, пока он открыт. | `boolean` | | -| forceLinksAppearance | Принудительно применяет стили к ссылкам. | `boolean` | `false` | -| hasArrow | Включает или отключает стрелку тултипа. | `boolean` | `true` | -| hasClose | Включает или отключает кнопку закрытия тултипа. | `boolean` | `false` | -| htmlContent | HTML-содержимое тултипа, которое будет отрисовано с помощью `dangerouslySetInnerHTML`. | `string` | | -| initialOpen | Включает или отключает автоматическое открытие тултипа при загрузке. | `boolean` | `false` | -| links | Ссылки под содержимым. | `[`[`LinkProps`](#linksprops)`]` | | -| offset | Смещение контрола. | `{top: number, left: number}` | | -| onClick | Обратный вызов при клике по элементу-якорю — `(event: React.MouseEvent) => boolean \| Promise`. Если функция возвращает `true`, тултип откроется; в противном случае — нет. | `Function` | | -| onCloseClick | Обработчик клика по кнопке закрытия — `(event: React.MouseEvent) => void`. | `Function` | | -| onOpenChange | Обработчик изменения состояния открытия — `(open: boolean) => void`. Может использоваться для задержки рендеринга содержимого тултипа. | `Function` | | -| openOnHover | Включает или отключает открытие тултипа по ховеру. | `boolean` | `true` | -| placement | Размещение `Popper.js`. | [`PopupPlacement`](../Popup/README.md#placement) | `["right", "bottom"]` | -| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | -| restoreFocusRef | Элемент, на который возвращается фокус при закрытии `Popover`. | `React.RefObject` | | -| size | Размер тултипа. | `"s"` `"l"` | `"s"` | -| strategy | [Стратегия](https://popper.js.org/docs/v2/constructors/#strategy) позиционирования `Popper.js`. | `"absolute"` `"fixed"` | `"absolute"` | -| title | Заголовок тултипа. | `string` | | -| theme | Тема тултипа. | `"info"` `"special"` `"announcement"` | `"info"` | -| tooltipActionButton | Свойства кнопки действия. Кнопка не будет отрисована, если не задать это свойство. | [`PopoverButtonProps`](#popoverbuttonprops) | | -| tooltipCancelButton | Свойства кнопки отмены. Кнопка не будет отрисована, если не задать это свойство. | [`PopoverButtonProps`](#popoverbuttonprops) | | -| tooltipClassName | CSS-класс тултипа. | `string` | | -| tooltipContentClassName | CSS-класс содержимого тултипа. | `string` | | -| tooltipOffset | Смещение тултипа относительно контрола. | `[number, number]` | | -| tooltipId | HTML-атрибут `id` для компонента `Popover`. | `string` | | - -### TriggerProps - -| Имя | Описание | Тип | Значение по умолчанию | -| --------- | ------------------------------ | :--------------------------: | :-------------------: | -| onClick | Обработчик события клика. | `React.MouseEventHandler` | | -| onKeyDown | Обработчик события клавиатуры. | `React.KeyboardEventHandler` | | - -### LinkProps - -| Имя | Описание | Тип | Значение по умолчанию | -| ------- | ---------------------------------------------------------------------------------- | :------------------: | :-------------------: | -| text | Текст ссылки. | `string` | | -| href | Атрибут ссылки `href`. | `string` | | -| target | Определяет, где откроется ссылка. | `"_self"` `"_blank"` | | -| onClick | Обработчик события клика — `(event: React.MouseEvent) => void`. | `Function` | | - -### PopoverButtonProps - -| Имя | Описание | Тип | Значение по умолчанию | -| ------- | --------------------------------------------------------------- | :--------: | :-------------------: | -| text | Текст на кнопке. | `string` | | -| onClick | Обработчик события клика — `(event: React.MouseEvent) => void`. | `Function` | | +LANDING_BLOCK--> -| Имя | Описание | -| :---------------------- | :---------------------------- | -| `--g-popover-padding` | Отступы контента. | -| `--g-popover-max-width` | Максимальная ширина контента. | +## Properties + +| Name | Description | Type | Default | +| :---------------------- | :-------------------------------------------------------------------------------------------------------- | :-----------------------------------------------------------: | :--------: | +| anchorElement | Anchor element. Can also be a `VirtualElement` | `PopupAnchorElement` | | +| aria-describedby | `aria-describedby` attribute. Use it if you have both label and description nodes | `string` | | +| aria-label | `aria-label` attribute. Use it only if you do not have any visible caption | `string` | | +| aria-labelledby | `aria-labelledby` attribute. Preferable if you have visible caption | `string` | | +| autoFocus | While open, the focus will be set to the floating element | `boolean` | `false` | +| children | Any React content | `React.ReactNode` | | +| className | `class` HTML attribute for the root node | `string` | | +| disableEscapeKeyDown | Disables triggering close on `Esc` | `boolean` | `false` | +| disableOutsideClick | Disables triggering close on outside clicks | `boolean` | `false` | +| disablePortal | Disables using `Portal` for children | `boolean` | `false` | +| floatingContext | `Floating UI` context to provide interactions | `FloatingRootContext` | | +| floatingInteractions | Override `Floating UI` interactions | `Array` | | +| floatingMiddlewares | `Floating UI` middlewares. If set, they will completely overwrite the default middlewares. | `Array` | | +| hasArrow | Renders arrow pointing to the anchor | `boolean` | `false` | +| id | `id` HTML attribute | `string` | | +| initialFocus | Initial element to be focused when `autoFocus` is true. Positive number is the index of tabbable element. | `number` `React.Ref` | | +| keepMounted | `Popup` will not be removed from the DOM upon hiding | `boolean` | `false` | +| modalFocus | Enables focus trapping behaviour | `boolean` | `false` | +| offset | `Floating UI` offset value | `PopupOffset` | `4` | +| onOpenChange | Handles `Popup` open change event | `Function` | | +| onTransitionIn | On start open popup animation | `Function` | | +| onTransitionInComplete | On finish open popup animation | `Function` | | +| onTransitionOut | On start close popup animation | `Function` | | +| onTransitionOutComplete | On finish close popup animation | `Function` | | +| open | Manages `Popup` visibility | `boolean` | `false` | +| placement | `Floating UI` placement | `Placement` `Array` `auto` `auto-start` `auto-end` | | +| qa | Test attribute (`data-qa`) | `string` | | +| returnFocus | Element to be focused on closing | `boolean` `React.Ref` | `true` | +| role | Accessibility role for popup | `string` | | +| strategy | `Floating UI` positioning strategy | `absolute` `fixed` | `absolute` | +| style | `style` HTML attribute for root node | `string` | | + +## CSS API + +| Name | Description | +| :--------------------------- | :--------------- | +| `--g-popup-background-color` | Background color | +| `--g-popup-border-color` | Border color | +| `--g-popup-border-width` | Border width | diff --git a/src/components/Popup/README.md b/src/components/Popup/README.md index 852900b576..fc55d0169e 100644 --- a/src/components/Popup/README.md +++ b/src/components/Popup/README.md @@ -19,13 +19,13 @@ To specify the anchor of a floating element, you can use the `anchorElement` pro setOpen((prevOpen) => !prevOpen)}> + - + Content `}> @@ -37,13 +37,13 @@ LANDING_BLOCK--> ```tsx -const buttonRef = React.useRef(null); +const [buttonElement, setButtonElement] = React.useState(null); const [open, setOpen] = React.useState(false); - - + Content ``` @@ -61,21 +61,21 @@ It is also acceptable to use the values `auto`, `auto-start`, `auto-end` to use -Top Start -Top -Top End -Right Start -Right -Right End -Bottom End -Bottom -Bottom Start -Left End -Left -Left Start +const [boxElement, setBoxElement] = React.useState(null); + +
+Top Start +Top +Top End +Right Start +Right +Right End +Bottom End +Bottom +Bottom Start +Left End +Left +Left Start `}> @@ -84,49 +84,39 @@ LANDING_BLOCK--> ## Properties -| Name | Description | Type | Default | -| :------------------- | :----------------------------------------------------------------------------------------- | :-----------------------------------------------------------: | :------------------------------: | -| anchorElement | Anchor element. Can also be `VirtualElement` | `PopupAnchorElement` | | -| autoFocus | While open, the focus will be set to the first interactive element in the content | `boolean` | `false` | -| children | Any React content | `React.ReactNode` | | -| className | `class` HTML attribute for the root node | `string` | | -| container | DOM element the children will be mounted to | `HTMLElement` | `document.body` | -| contentClassName | `class` HTML attribute for the content node | `string` | | -| disableEscapeKeyDown | Disables triggering close on `Esc` | `boolean` | `false` | -| disableLayer | Disables using `LayerManager` on stacking popups | `boolean` | `false` | -| disableOutsideClick | Disables triggering close on outside clicks | `boolean` | `false` | -| disablePortal | Disables using `Portal` for children | `boolean` | `false` | -| focusTrap | Enables focus trapping behavior | `boolean` | `false` | -| hasArrow | Renders arrow pointing to the anchor | `boolean` | `false` | -| id | `id` HTML attribute | `string` | | -| keepMounted | `Popup` will not be removed from the DOM upon hiding | `boolean` | `false` | -| middlewares | `Floating UI` middlewares. If set, they will completely overwrite the default middlewares. | `Array` | | -| offset | `Floating UI` offset value | `PopupOffset` | `4` | -| floatingContext | `Floating UI` context to provide interactions | `FloatingRootContext` | | -| floatingProps | Additional floating element props to provide interactions | `Record` | | -| onBlur | `blur` event handler | `Function` | | -| onClose | Handles `Popup` close event | `Function` | | -| onEnterKeyDown | `Enter` press event handler | `Function` | | -| onEscapeKeyDown | `Esc` press event handler | `Function` | | -| onFocus | `focus` event handler | `Function` | | -| onMouseEnter | `mouseenter` event handler | `Function` | | -| onMouseLeave | `mouseleave` event handler | `Function` | | -| onOutsideClick | Outside click event handler | `Function` | | -| onTransitionEnter | On start open popup animation | `Function` | | -| onTransitionEntered | On finish open popup animation | `Function` | | -| onTransitionExit | On start close popup animation | `Function` | | -| onTransitionExited | On finish close popup animation | `Function` | | -| open | Manages `Popup` visibility | `boolean` | `false` | -| placement | `Floating UI` placement | `Placement` `Array` `auto` `auto-start` `auto-end` | | -| qa | Test attribute (`data-qa`) | `string` | | -| restoreFocus | If true, the focus will return to the anchor element | `boolean` | `false` | -| restoreFocusRef | Element the focus will be restored to | `React.RefObject` | | -| aria-labelledby | `aria-labelledby` attribute. Preferable if you have visible caption | `string` | | -| aria-label | `aria-label` attribute. Use it only if you do not have any visible caption | `string` | | -| aria-modal | `aria-modal` attribute. Indicates whether an element is modal when displayed | `Booleanish` | value of `focusTrap` | -| role | Accessibility role for popup | `string` | `dialog` if `aria-modal` is true | -| strategy | `Floating UI` positioning strategy | `absolute` `fixed` | `absolute` | -| style | `style` HTML attribute for root node | `string` | | +| Name | Description | Type | Default | +| :---------------------- | :-------------------------------------------------------------------------------------------------------- | :-----------------------------------------------------------: | :--------: | +| anchorElement | Anchor element. Can also be a `VirtualElement` | `PopupAnchorElement` | | +| aria-describedby | `aria-describedby` attribute. Use it if you have both label and description nodes | `string` | | +| aria-label | `aria-label` attribute. Use it only if you do not have any visible caption | `string` | | +| aria-labelledby | `aria-labelledby` attribute. Preferable if you have visible caption | `string` | | +| autoFocus | While open, the focus will be set to the floating element | `boolean` | `false` | +| children | Any React content | `React.ReactNode` | | +| className | `class` HTML attribute for the root node | `string` | | +| disableEscapeKeyDown | Disables triggering close on `Esc` | `boolean` | `false` | +| disableOutsideClick | Disables triggering close on outside clicks | `boolean` | `false` | +| disablePortal | Disables using `Portal` for children | `boolean` | `false` | +| floatingContext | `Floating UI` context to provide interactions | `FloatingRootContext` | | +| floatingInteractions | Override `Floating UI` interactions | `Array` | | +| floatingMiddlewares | `Floating UI` middlewares. If set, they will completely overwrite the default middlewares. | `Array` | | +| hasArrow | Renders arrow pointing to the anchor | `boolean` | `false` | +| id | `id` HTML attribute | `string` | | +| initialFocus | Initial element to be focused when `autoFocus` is true. Positive number is the index of tabbable element. | `number` `React.Ref` | | +| keepMounted | `Popup` will not be removed from the DOM upon hiding | `boolean` | `false` | +| modalFocus | Enables focus trapping behaviour | `boolean` | `false` | +| offset | `Floating UI` offset value | `PopupOffset` | `4` | +| onOpenChange | Handles `Popup` open change event | `Function` | | +| onTransitionIn | On start open popup animation | `Function` | | +| onTransitionInComplete | On finish open popup animation | `Function` | | +| onTransitionOut | On start close popup animation | `Function` | | +| onTransitionOutComplete | On finish close popup animation | `Function` | | +| open | Manages `Popup` visibility | `boolean` | `false` | +| placement | `Floating UI` placement | `Placement` `Array` `auto` `auto-start` `auto-end` | | +| qa | Test attribute (`data-qa`) | `string` | | +| returnFocus | Element to be focused on closing | `boolean` `React.Ref` | `true` | +| role | Accessibility role for popup | `string` | | +| strategy | `Floating UI` positioning strategy | `absolute` `fixed` | `absolute` | +| style | `style` HTML attribute for root node | `string` | | ## CSS API