# Expansion-Panel

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/expansion-panel/
- Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-expansion-panel--docs
- Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/expansion-panel/overview (API: https://lyne-angular.app.sbb.ch/angular/components/expansion-panel/api)
- Figma: https://www.figma.com/design/mWknI2rC5DJmOgRO61WKai/Lyne-Components?node-id=31075-188808
- GitHub: https://github.com/sbb-design-systems/lyne-components/tree/v5.12.0/src/elements/expansion-panel

## Elemente

- `sbb-expansion-panel`: It displays an expandable summary-details widget.
  - `sbb-expansion-panel-content`, nur innerhalb von `sbb-expansion-panel`: It can be used as a container for the content of the `sbb-expansion-panel` component.
  - `sbb-expansion-panel-header`, nur innerhalb von `sbb-expansion-panel`: It acts as a native `summary` tag for the `sbb-expansion-panel` component.

## Übersicht

### Was macht die Komponente?
Ein Expansion-Panel blendet Inhalt hinter einem Titel aus. Mit einem Klick auf den Titel wird der Inhalt auf- oder zugeklappt.

### Wann soll die Komponente eingesetzt werden?
* Um ergänzende Informationen anzubieten, die nicht alle Nutzenden brauchen, z.B. Details, Erklärungen oder häufige Fragen.
* Um lange Seiten übersichtlicher zu machen, indem Inhalte erst bei Bedarf erscheinen.

### Regeln.
* Der Titel beschreibt den verborgenen Inhalt kurz und eindeutig.
* Informationen, die alle Nutzenden sehen müssen, gehören nicht in ein zugeklapptes Panel.
* Expansion-Panels werden nicht ineinander verschachtelt.
* Mehrere zusammengehörige Panels werden im [Accordion](https://digital.sbb.ch/de/design-system/lyne/components/accordion/) gruppiert.
* Der Titel wird mit der passenden Überschriftenebene ausgezeichnet.

## Implementation (Web Components, Englisch)

The `<sbb-expansion-panel>` is a component which acts as an expandable summary-details widget.

It can be used standalone or inside an [sbb-accordion](https://lyne-elements.app.sbb.ch/?path=/docs/elements-accordion--docs).

In order to correctly display the component, it must be used together with
the `<sbb-expansion-panel-header>` and `<sbb-expansion-panel-content>` components.
The header will work as a state controller, the content will act as the expandable content.

```html
<sbb-expansion-panel>
  <sbb-expansion-panel-header>This is the header.</sbb-expansion-panel-header>
  <sbb-expansion-panel-content>This is the content.</sbb-expansion-panel-content>
</sbb-expansion-panel>
```

The `<sbb-expansion-panel-header>` component is internally rendered as a button, and it is possible to
provide text via an unnamed slot.
On the left side, a toggle icon is displayed; it flips based on the host's `aria-expanded` property.

The component can optionally display a `<sbb-icon>` at the component start using the `iconName`
property or via custom content using the `icon` slot.
If using the SBB icons, the icon should be a medium size icon.

```html
<sbb-expansion-panel-header icon-name="swisspass-medium">Header</sbb-expansion-panel-header>
```

### States

The visibility of the content is controlled by the value of the `expanded` property.

```html
<sbb-expansion-panel expanded> ... </sbb-expansion-panel>
```

The `disabled` state can be set using the self-named variable. In this state, the component can not be collapsed or expanded.

```html
<sbb-expansion-panel disabled> ... </sbb-expansion-panel>
```

### Events

The `<sbb-expansion-panel-header>` element dispatches the `toggleexpanded` event when clicked.

### Style

The component has two background options (`milk` and `white`, which is the default) that can be set using the `color` variable.

```html
<sbb-expansion-panel color="milk"> ... </sbb-expansion-panel>
```

The component has two different sizes, `s` and `l`, which can be changed using the `size` property.
The property is overridden when the component is used within a `<sbb-accordion>`.

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

It's also possible to display the `<sbb-expansion-panel>` without border by setting the `borderless` variable.

```html
<sbb-expansion-panel borderless> ... </sbb-expansion-panel>
```

Using the `titleLevel` variable, it's possible to wrap the `<sbb-expansion-panel-header>` in a heading tag;
if it's unset, a `<div>` is used as a wrapper.

```html
<sbb-expansion-panel level="4">
  <sbb-expansion-panel-header
    >This is the header, and it will be wrapped in a h4 tag.</sbb-expansion-panel-header
  >
  <sbb-expansion-panel-content>This is the content.</sbb-expansion-panel-content>
</sbb-expansion-panel>
```

### Accessibility

The `<sbb-expansion-panel-header>` and `<sbb-expansion-panel-content>` are automatically connected
via `aria-controls` and `aria-labelledby` when placed inside an `<sbb-expansion-panel>`.

The `expanded` attribute is used to correctly set the `aria-expanded` attribute on the header
and the `aria-hidden` attribute on the content.

## API (Web Components, Englisch)

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