import { Meta, Primary, Controls, Story } from '@storybook/blocks';
import * as stories from './uui-popover-container.story.ts';

<Meta of={stories} />

# Popover Container

This component is a container for popovers. It is used to position the popover relative to the target element.
It is also a native popover. So everything descriped in the **[Popover API documentation](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)** applies.

**Note**: The `popover` attribute that is required by the Popover API is automatically added to the uui-popover-container if it is not already present. So this attribute can be omitted, unless you want to change the default behavior. More information about this can be found in the **[Manual popover](#manual-popover)** section.

<div
  style={{
    borderLeft: '6px solid #f3d41b',
    background: '#f3d41b24',
    padding: '0px 16px',
    display: 'flex',
    flexDirection: 'column',
  }}>
  When used with UUIButton or any element that is not a native button or input,
  the popovertargetaction property will not work, and defaults too toggle.
</div>
<br />
<div
  style={{
    borderLeft: '6px solid #f3d41b',
    background: '#f3d41b24',
    padding: '0px 16px',
    display: 'flex',
    flexDirection: 'column',
  }}>
  This uses the Popover API which is experimental and will not work in all
  browsers. See **[Popover API
  documentation](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)**
  for more information. A polyfill is provided for browsers that do not support
  the Popover API.
</div>
<Controls />
## Basic usage

```html
<uui-button popovertarget="my-popover">Open Popover</uui-button>
<uui-popover-container id="my-popover">
  My popover content
</uui-popover-container>
```

## Change placement

```html
<uui-button popovertarget="my-popover">Open Popover</uui-button>
<uui-popover-container id="my-popover" placement="top-start">
  My popover content
</uui-popover-container>
```

## Add margin

```html
<uui-button popovertarget="my-popover">Open Popover</uui-button>
<uui-popover-container id="my-popover" margin="10">
  My popover content
</uui-popover-container>
```

## Nested popover

```html
<uui-button popovertarget="my-popover">Open Popover</uui-button>
<uui-popover-container id="my-popover">
  My popover content
  <uui-button popovertarget="my-popover-2">Open another popover</uui-button>
  <uui-popover-container id="my-popover-2">
    My other popover content
  </uui-popover-container>
</uui-popover-container>
```

## Manual popover

By default, popovers have a feature known as "light dismiss," which causes them to close if you click outside the popover.
However, you have the option to alter this behavior using the `popover` attribute. The `popover` attribute offers two possible values: `auto` and `manual`.
If you omit a value, it will automatically default to `auto`. Essentially, using `popover` is the same as using `popover="auto"`.

When you set the value to `manual`, the "light dismiss" functionality is disabled.
As a result, you will need to manually close the popover either by clicking the button again or by explicitly toggling the popover.

```html
<uui-button popovertarget="my-popover">Open Popover</uui-button>
<uui-popover-container id="my-popover" popover="manual">
  My popover content
</uui-popover-container>
```

## Example: Tooltip

A tooltip is a small pop-up box that appears when the user hovers over an item, providing additional information or context about that item.
Note: The popover-container always needs a an element with the `popovertarget` attribute, even when it's not a button. This element is used as the anchor to position the popover.

```js
const tooltipToggle = document.getElementById('tooltip-toggle');
const tooltipPopover = document.getElementById('tooltip-popover');

tooltipToggle.addEventListener('mouseenter', () => tooltipPopover.show());
tooltipToggle.addEventListener('mouseleave', () => tooltipPopover.hide());
```

```html
Sometimes words such as
<b id="tooltip-toggle" popovertarget="tooltip-popover">petrichor</b>
needs some more explanation
<uui-popover-container id="tooltip-popover">
  A pleasant smell that frequently accompanies the first rain after a long
  period of warm, dry weather.
</uui-popover-container>
```
