Popover

!npm

Popover package offers following components:

* Popover
* Tooltip

Popover and Tooltip require a target element that acts as a pivot for their content. They support multiple placement positions, allowing both elements to be positioned next to the target element in any direction.

Popover

Popover is an interactive floating element that displays information related to an anchor element when the element is clicked. It represents the UI element as floating above the normal flow creating the "pop out" effect. Popover can contain a range of elements from simple strings to complex React designs.

Popover is a controlled component, it does not manage visibility state on it's own.

Tooltip

Tooltip component allows user to see additional context about a UI element without cluttering the interface. Tooltip provides informative text when the user hovers over, focuses on, and on mobile device taps on an element. Tooltips are often used sparingly to avoid overwhelming users. They are meant to support discovery, not replace clear design or documentation.

To use an icon from @asphalt-react/iconpack as the target element for tooltip, wrap the icon inside an HTML element like a div or span.

Usage

``js
import React, { useState } from "react"
import { Popover, Tooltip } from "@asphalt-react/popover"
import { Button } from "@asphalt-react/button"

const App = () => {
const [open, setOpen] = useState(false)

return (
<>
open={open}
target={Click Me}
onOpenChange={setOpen}
>



Hello there


target={Hover over here}
>
Add information here


)
}

export default App
`

Sizes

Popover & Tooltip comes in 3 sizes small(s), medium(m) & large(l).

Building blocks

1. Popover component comes with:
* BasePopover
* FocusManager

2. BasePopover supports 3 sizes: small(s), medium(m) & large(l).

3. FocusManager handles the focus management for Popover content.

Hooks

$3

Use the usePopover() hook to get all the prop getter functions and then spread them in the target & popover components. usePopover() takes props as parameter.

React hook which returns prop getter functions. Use these functions to generate prop objects for different components in Popover.

#### Arguments

usePopover accepts the following props:

1. open
2. placement
3. outOfFlow
4. flip
5. size
6. bezel
7. focusTrap
8. noOffset
9. lowOffset
10. mediumOffset
11. highOffset
12. onOpenChange
13. stretch
14. returnFocus

#### Getter functions

#### getTargetProps()

Use this function to create props for Target element of the Popover.

`jsx
const { getTargetProps } = usePopover({ open: true, onOpenChange: setOpen })


Click me

`

#### getPopoverProps()

Use this function to create props for Popover/floating component.

`jsx
const { getPopoverProps } = usePopover({ open: true, onOpenChange: setOpen })





Hello there!




`

#### getFocusProps()

Use this function to create props for FocusManager component.

`jsx
const { getFocusProps } = usePopover({ open: true, onOpenChange: setOpen })






Hello there!





`

#### Usage

`js
import { BasePopover, usePopover, FocusManager } from "@asphalt-react/popover"

const App = () => {
const [open, setOpen] = useState(false)

const { getTargetProps, getPopoverProps, getFocusProps } = usePopover({
open,
onOpenChange: setOpen,
})

return (


)
}

export default App
`

Accessibility

* For popover, clicking outside the popover closes it. While in tooltip, moving the cursor away from the target element closes the tooltip.

* Pressing Esc key closes both popover and tooltip.

* Popover traps focus within its content, rotating the focus among its interactive elements.

* The first interactive element receives focus by default when Popover opens.

* The element that serves as the tooltip container has role="tooltip".

* The element that triggers the tooltip has aria-describedby.

Example of tooltip accessibility:

`jsx
id="my-tooltip"
target={Hover over here}
>
Add information here

`

[comment]: # "Popover Props"

Props

$3

React node to render inside Popover.

| type | required | default |
| ---- | -------- | ------- |
| node | true | N/A |

$3

Target node that triggers the Popover.

| type | required | default |
| ---- | -------- | ------- |
| node | true | N/A |

$3

Decides the open state for Popover.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | false |

$3

Size of the Popover.

| type | required | default |
| ---- | -------- | ------- |
| enum | false | "m" |

$3

Adds padding on all sides.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | true |

$3

Placement of the Popover with respect to target node.

Popover supports multiple placements:

* auto • auto-start • auto-end
* top • top-start • top-end
* bottom • bottom-start • bottom-end
* left • left-start • left-end
* right • right-start • right-end

| type | required | default |
| ---- | -------- | -------- |
| enum | false | "bottom" |

$3

The order in which focus cycles.

* reference - Target element which acts as pivot for Popover.
* floating - Popover wrapper element.
* content - Content inside Popover wrapper.

By default it's value is \['content'] - Subsequent tabs will cycle through the tabbable contents of the Popover content.

If the value is set to \['floating', 'content'] - Includes floating element in focus cycle.

If the value is set to \['reference', 'content'] - Includes reference element in focus cycle.

* If the value is set to \['reference', 'floating', 'content'] - tabs will cycle through the reference, floating & tabbable contents of the Popover content.

| type | required | default |
| ------- | -------- | ----------- |
| arrayOf | false | ["content"] |

$3

Element to initially focus when Popover is opened. Can be either a number or a ref.
Number is decided by the tabbable index as specified by the focusOrder.

| type | required | default |
| ----- | -------- | ------- |
| union | false | 0 |

$3

When Popover is added to a container with position: fixed and/or overflow: hidden,
it creates a containing block with a stacking context which the Popover can't skip.
In such scenarios, enabling outOfFlow will remove Popover from its parent's flow.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | false |

$3

Flips the position of the floating element if there is space constraint
in order to make it visible in viewport.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | true |

$3

Enables the Popover to stretch and fill the width of its container. By default, the Popover matches the width of its content.

Strech works only in a relatively positioned container. Refer to the example below.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | false |

$3

Shifts the Popover horizontally to avoid the content from overflowing the viewport.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | true |

$3

Add focus trap in the content, outside content cannot be accessed if enabled.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | true |

$3

adds a low spacing between target and Popover.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | false |

$3

adds a medium spacing between target and Popover.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | false |

$3

adds a high spacing between target and Popover.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | false |

$3

removes spacing between target and Popover.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | false |

$3

callback when open state is changed.

| type | required | default |
| ---- | -------- | ------- |
| func | false | null |

$3

determines if focus should be returned to the reference element.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | true |

BasePopover

[comment]: # "BasePopover Props"

Props

$3

React node to render inside Base Popover.

| type | required | default |
| ---- | -------- | ------- |
| node | true | N/A |

$3

Indicates the open state for Popover.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | false |

$3

Size of the Popover.

| type | required | default |
| ---- | -------- | ------- |
| enum | false | "m" |

$3

Adds padding on all sides.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | true |

$3

Enables the Popover to stretch and fill the width of its container. By default, the Popover matches the width of its content.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | false |

$3

Adds styles to position the Popover relative to the target element.

| type | required | default |
| ------ | -------- | ------- |
| object | false | N/A |

$3

Set to true to render BasePopover with inverse background.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | false |

FocusManager

[comment]: # "FocusManager Props"

Props

$3

React node to render inside Base Popover.

| type | required | default |
| ---- | -------- | ------- |
| node | true | N/A |

$3

context object used to focus on the floating element, pass the popoverContext returned by the usePopover hook.

| type | required | default |
| ------ | -------- | ------- |
| object | true | N/A |

$3

The order in which focus cycles.

* reference - Target element which acts as pivot for Popover.
* floating - Popover wrapper element.
* content - Content inside Popover wrapper.

By default it's value is \['content'] - Subsequent tabs will cycle through the tabbable contents of the Popover content.

If the value is set to \['floating', 'content'] - Includes floating element in focus cycle.

If the value is set to \['reference', 'content'] - Includes reference element in focus cycle.

* If the value is set to \['reference', 'floating', 'content'] - tabs will cycle through the reference, floating & tabbable contents of the Popover content.

| type | required | default |
| ------- | -------- | ----------- |
| arrayOf | false | ["content"] |

$3

Add focus trap in the content, outside content cannot be accessed if enabled.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | true |

$3

Element to initially focus when Popover is opened. Can be either a number or a ref.
Number is decided by the tabbable index as specified by the focusOrder.

| type | required | default |
| ----- | -------- | ------- |
| union | false | 0 |

$3

determines if focus should be returned to the reference element.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | true |

Tooltip

[comment]: # "Tooltip Props"

Props

$3

Tooltip content receives node.

| type | required | default |
| ---- | -------- | ------- |
| node | true | N/A |

$3

Target node that triggers the Popover.

| type | required | default |
| ---- | -------- | ------- |
| node | true | N/A |

$3

Tooltip title, only receives string.

| type | required | default |
| ------ | -------- | ------- |
| string | false | N/A |

$3

Tooltip size, can be "small", "medium" or "large".

| type | required | default |
| ---- | -------- | ------- |
| enum | false | "m" |

$3

Set arrow=false to disable arrow.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | true |

$3

Placement of the Popover with respect to target node.

Popover supports multiple placements:

* top • top-start • top-end
* bottom • bottom-start • bottom-end
* left • left-start • left-end
* right • right-start • right-end`

| type | required | default |
| ---- | -------- | -------- |
| enum | false | "bottom" |

$3

Adds padding on all sides.

| type | required | default |
| ---- | -------- | ------- |
| bool | false | true |