# Popover

Komponente des SBB Design Systems Lyne.

- Paket: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Aufbau: Hauptelement mit Bestandteilen; Bestandteile nur innerhalb des jeweiligen Elements verwenden
- Kategorien: Container
- Status: Gestaltungsrichtlinien vollständig

## Links

- Seite auf digital.sbb.ch: https://digital.sbb.ch/de/design-system/lyne/components/popover/
- Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-popover--docs
- Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/popover/overview (API: https://lyne-angular.app.sbb.ch/angular/components/popover/api)
- Figma: https://www.figma.com/design/mWknI2rC5DJmOgRO61WKai/Lyne-Components?node-id=7491-47
- GitHub: https://github.com/sbb-design-systems/lyne-components/tree/v5.12.0/src/elements/popover

## Elemente

- `sbb-popover`: It displays contextual information within a popover.
  - `sbb-popover-close-button`, nur innerhalb von `sbb-popover`: Popover close button, intended to be placed inside sbb-popover.

## Verwandte Komponenten

- Ähnlich: [Tooltip](https://digital.sbb.ch/de/design-system/lyne/components/tooltip/index.md)

## Übersicht

### Was macht die Komponente?
Ein Popover ist ein kleines [Overlay](https://digital.sbb.ch/de/design-system/lyne/components/overlay/), das zusätzliche Informationen oder interaktive Inhalte zu einem Element zeigt. Es öffnet sich per Klick oder optional beim Hovern über das Element.

### Wann soll die Komponente eingesetzt werden?
* Um Icons oder Buttons zu erklären.
* Um Begriffe zu erläutern oder Entscheidungshilfen zu geben, ohne die Seite zu verlassen.
* Für reinen, kurzen Text ohne Interaktion ist stattdessen der [Tooltip](https://digital.sbb.ch/de/design-system/lyne/components/tooltip/) zu verwenden.

### Regeln.
* Der Inhalt ist kurz und funktioniert auf allen Bildschirmgrössen.
* Es ist immer nur ein Popover gleichzeitig offen.
* Ein Popover enthält einen Titel (Überschrift Ebene 2), der bei Bedarf visuell versteckt wird.
* Bei Klick wird ein Schliessen-Button am Anfang des Inhalts platziert. Bei Hover wird kein Schliessen-Button verwendet.

## Implementation (Web Components, Englisch)

The `<sbb-popover>` component can be useful for displaying contextual and additional information on mouse hover or click of a trigger element.

The component could be used:

- to describe icons and buttons;
- when more information is useful to help a user make decisions;
- when an element needs more context or explanation;
- when defining a term or inline item.

The component must be connected with the trigger element using the `trigger` property,
which accepts the id of the element, or directly its reference;

```html
<sbb-mini-button icon-name="circle-information-small" id="popover-trigger"></sbb-mini-button>

<sbb-popover trigger="popover-trigger">
  <sbb-popover-close-button></sbb-popover-close-button>
  <sbb-title level="2" visual-level="6" style="margin-block-start: 0">Popover Title.</sbb-title>
  <p>Popover content.</p>
</sbb-popover>
```

### Configuration

The open and close delays can be configured via global configuration. This values will be used as default, unless explicitly set on the element.

```ts
import { mergeConfig } from '@sbb-esta/lyne-elements/core.js';

mergeConfig({
  popover: {
    openDelay: 0, // ms before the popover opens
    closeDelay: 0, // ms before the popover closes
  },
});
```

### Interactions

The `<sbb-popover>` can be dismissed by clicking on an interactive element within its content,
by clicking on the close button or by performing another action on the page.

You can also indicate that an element within the popover content should close the `<sbb-popover>` when clicked
by marking it with the `sbb-popover-close` attribute.
To display a close button, place the `<sbb-popover-close-button>` inside the popover.
For accessibility reasons, the close button should be the first focusable element in the popover,
so it is recommended to place it at the beginning of the content.

```html
<sbb-popover>
  <sbb-popover-close-button></sbb-popover-close-button>
  <sbb-title level="2" visual-level="6" style="margin-block-start: 0">Popover Title.</sbb-title>
  <p>Popover content. <sbb-link sbb-popover-close>Link</sbb-link></p>
</sbb-popover>
```

You can also indicate that the `<sbb-popover>` should be shown on hover with the property `hoverTrigger`
and set a custom delay for the open and close animations (defaults to 0).
When using `hoverTrigger`, it is the consumer's responsibility to omit the `<sbb-popover-close-button>`,
as a close button is not appropriate in hover-triggered popovers.

If hover is not supported by the current device, the component will be triggered on click/tap as default.
The `<sbb-popover>` will automatically disappear after the hiding delay
if neither the trigger element nor the popover are on hover or if another action is performed on the page.

```html
<sbb-popover hover-trigger open-delay="500" close-delay="750">
  <sbb-title level="2" visual-level="6" style="margin-block-start: 0">Popover Title.</sbb-title>
  <p id="popover-content">Popover content. <sbb-link id="popover-link">Link</sbb-link></p>
</sbb-popover>
```

### Style

The `<sbb-popover>` automatically calculates where it should place itself, based on available space. Default is below and center.

The component has a negative variant which can be set using the `negative` property.
The `<sbb-popover-close-button>` component, if present, is automatically rendered in the `negative` variant,
while consumers need to set it manually on other components, or adjust styling accordingly.

### Accessibility

As the popover opens, the focus will automatically be set to the first focusable item within the component.
If the close button is not hidden, it's the first element and therefore gets focused (unless manually specified, see below).

Overlays should always contain a heading level 2 title. It can be visually hidden if necessary.

#### Controlling initial focus

The first element with the attribute `sbb-focus-initial` will receive focus on opening.
If the attribute is not used, the first focusable element receives focus (recommended).

```html
<sbb-popover>
  <sbb-link href="#">Link</sbb-link>
  <sbb-link sbb-focus-initial href="#">Link 2</sbb-link>
</sbb-popover>
```

## API (Web Components, Englisch)

Vollständige API-Tabellen (Attribute, Events, Slots, CSS-Eigenschaften): https://digital.sbb.ch/de/design-system/lyne/components/popover/api.md