# Alert

Komponente des SBB Design Systems Lyne.

- Paket: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Aufbau: ein Element mit optionaler Gruppierung
- Kategorien: Indicator
- Status: Gestaltungsrichtlinien vollständig

## Links

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

## Elemente

- `sbb-alert`, mehrere lassen sich zusammenfassen mit `sbb-alert-group`: It displays messages which require user's attention.

## Verwandte Komponenten

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

## Übersicht

### Was macht die Komponente?
Ein Alert zeigt wichtige Informationen oder Warnungen an die Nutzenden. Standardmässig kann er geschlossen werden. Er kann auch als nicht schliessbar (readonly) dargestellt werden.

### Wann soll die Komponente eingesetzt werden?
* Um über kritische Fehler, Warnungen oder wichtige Informationen zu informieren.
* Um sofort Aufmerksamkeit auf kritische Nachrichten zu lenken.

### Regeln.
* Ein Alert enthält einen Titel und eine klare, prägnante Nachricht.
* Alerts werden in einer Alert-Group platziert. Sie steuert Abstände und Barrierefreiheit (neue Alerts werden von Screenreadern angekündigt).
* Alerts und [Notifications](https://digital.sbb.ch/de/design-system/lyne/components/notification/) werden nicht kombiniert.
* Alerts werden nicht für Fehlermeldungen in Formularen eingesetzt.

## Implementation (Web Components, Englisch)

The `<sbb-alert>` is a component which should be used to display important messages to a client.

Multiple instances of this component can be used within the `<sbb-alert-group>` component.
The group also manages the accessibility of one or multiple alert instances and also the
visual gap between each other.

```html
<sbb-alert-group accessibility-title="Disruptions" accessibility-title-level="2">
  <sbb-alert size="l">
    <sbb-title level="3">Interruption between Genève and Lausanne</sbb-title>
    The rail traffic between Allaman and Morges is interrupted. All trains are cancelled.
    <sbb-link href="https://www.sbb.ch">Find out more</sbb-link>
  </sbb-alert>
  <sbb-alert>
    <sbb-title level="3">Interruption between Berne and Olten</sbb-title>
    Between Berne and Olten from 03.11.2021 to 05.12.2022 each time from 22:30 to 06:00 o'clock
    construction work will take place. You have to expect changed travel times and changed
    connections. <sbb-link href="https://www.sbb.ch">Find out more</sbb-link>
  </sbb-alert>
</sbb-alert-group>
```

### Interactions

If all `<sbb-alert>` instances in a group are dismissed, it's recommended to completely
remove the `<sbb-alert-group>` from DOM.

Listen to the `empty` event dispatched by the group and react accordingly.

### Slots

The unnamed slot is used to project an `<sbb-title>`, text content and one or more `<sbb-link>` elements.

The component can optionally display an `<sbb-icon>` at the component start using the `iconName` property or via custom content using the `icon` slot.

```html
<sbb-alert icon-name="disruption">
  <sbb-title level="3">Interruption between Berne and Olten</sbb-title>
  Between Bern and Olten from 03.11.2021 to 05.12.2022 each time from 22:30 to 06:00 o'clock
  construction work will take place. You have to expect changed travel times and changed
  connections. <sbb-link href="https://www.sbb.ch">Find out more</sbb-link>
</sbb-alert>

<sbb-alert>
  <sbb-title level="3">Interruption between Berne and Olten</sbb-title>
  <sbb-icon slot="icon" name="disruption"></sbb-icon>
  Between Bern and Olten from 03.11.2021 to 05.12.2022 each time from 22:30 to 06:00 o'clock
  construction work will take place. You have to expect changed travel times and changed
  connections. <sbb-link href="https://www.sbb.ch">Find out more</sbb-link>
</sbb-alert>
```

### Readonly

Per default a `<sbb-alert>` can be dismissed by a user. If an alert should not be dismissable,
use the `readonly` attribute/`readOnly` property.

```html
<sbb-alert readonly>
  <sbb-title level="3">Interruption between Berne and Olten</sbb-title>
  Between Bern and Olten from 03.11.2021 to 05.12.2022 each time from 22:30 to 06:00 o'clock
  construction work will take place. You have to expect changed travel times and changed
  connections.
</sbb-alert>
```

### Style

Users can choose between three `size` options: `s`, `m` and `l`.

```html
<sbb-alert size="s"> ... </sbb-alert>

<sbb-alert size="l"> ... </sbb-alert>
```

### Animation

Set the `animation` property to manage which animations are enabled.
As a base rule, opening animations should be active if an alert arrives after the initial page load.

### Accessibility

Accessibility is mainly done by wrapping the alerts into the `<sbb-alert-group>`.

The description text is wrapped into an `<p>` element to guarantee the semantic meaning.

Avoid slotting block elements (e.g. `<div>`) as this violates semantic rules and can have
negative effects on screen readers.

For the `<sbb-alert-group>` it's possible to add a hidden title by specifying the `accessibility-title`.
The heading level can be set via `accessibility-title-level`.

By default, the `<sbb-alert-group>` has the role `status` which means that if a new alert
arrives, it will be read out as soon as the user is idle
(equal to [aria-live="polite"](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions)).

You can change the `role` or `aria-live` attributes to fit your needs.
For example, you can set the `role` to `alert` which implicitly sets `aria-live` to `assertive`
and therefore interrupts screen reader flow, to immediately read out the alert content.

**Note that with role `alert`, in some combinations of screen readers and browsers not every part of the alert is fully read.**

## API (Web Components, Englisch)

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