# Lead-Container

Component of the SBB design system Lyne.

- Package: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Structure: one element
- Categories: Container
- Status: Design guidelines complete

## Links

- Page on digital.sbb.ch: https://digital.sbb.ch/en/design-system/lyne/components/lead-container/
- Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-lead-container--docs
- Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/lead-container/overview (API: https://lyne-angular.app.sbb.ch/angular/components/lead-container/api)
- GitHub: https://github.com/sbb-design-systems/lyne-components

## Elements

- `sbb-lead-container`: The `sbb-lead-container` can be used for product pages to display a lead image and following content.

## Overview

### What does the component do?
A lead container forms the entry of a product page. It shows a large lead image and below it the introductory content such as breadcrumb, title and lead text. It is intended for content pages only, not for business apps.

### When should the component be used?
* As the entry of product or topic pages that are introduced with an image.
* To combine the title and introduction of a page with an image in a consistent way.

### Rules.
* Use at most one lead container per page, placed after the header.
* The content follows this order: alerts, breadcrumb, back link, title, lead text, notifications.
* Use the predefined Lyne classes for the spacing between the content elements.
* The lead image needs an alternative text. If it is purely decorative, it is hidden from screen readers.

## Implementation (web components)

The `<sbb-lead-container>` can be used for product pages to display a lead image and following content.

Please note that the gaps between elements inside the unnamed slot (main content) need to be controlled by the consumer.
However, consumers can use the predefined classes
(`sbb-lead-container-lead-spacing` and `sbb-lead-container-lead-text`) to achieve a correct spacing.

As per design rules, the spacings are defined as following:

```html
<sbb-alert-group></sbb-alert-group>

<sbb-breadcrumb-group></sbb-breadcrumb-group>

<sbb-block-link></sbb-block-link>

<sbb-title></sbb-title>

<p></p>

<sbb-notification></sbb-notification>

...

```

Full example with applied spacings (CSS classes) in content:

```html
<sbb-lead-container>
  <style>
    p.other-content {
      margin-block: 0;
    }
  </style>
  <sbb-image
    slot="image"
    image-src="https://cdn.img.sbb.ch/content/dam/internet/externe-assets/lyne/Bahnhof-Luzern.jpg"
    alt="Station of Lucerne from outside"
  ></sbb-image>
  <sbb-alert-group class="sbb-lead-container-spacing">
    <sbb-alert size="m">
      <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-group>
  <sbb-breadcrumb-group class="sbb-lead-container-spacing">
    <sbb-breadcrumb href="#" icon-name="house-small"></sbb-breadcrumb>
    <sbb-breadcrumb href="#">Level 1</sbb-breadcrumb>
  </sbb-breadcrumb-group>
  <sbb-block-link
    icon-placement="start"
    icon-name="chevron-small-left-small"
    size="xs"
    href="https://www.sbb.ch"
    class="sbb-lead-container-spacing"
  >
    Link
  </sbb-block-link>
  <sbb-title class="sbb-lead-container-spacing">Title</sbb-title>
  <p class="sbb-text-xl sbb-lead-container-lead-text">Lead text.</p>
  <sbb-notification type="info" class="sbb-lead-container-spacing">
    Vestibulum rutrum elit et lacus sollicitudin, quis malesuada lorem vehicula. Suspendisse at
    augue quis tellus vulputate tempor. Vivamus urna velit, varius nec est ac, mollis efficitur
    lorem. Quisque non nisl eget massa interdum tempus. Praesent vel feugiat metus.
  </sbb-notification>
  <p class="sbb-text-m other-content">Other content.</p>
</sbb-lead-container>
```

Optionally, you can add an overlapping `<sbb-chip-label>` by wrapping the `<sbb-image>` in a `figure` tag (see [sbb-image doc](https://lyne-elements.app.sbb.ch/?path=/docs/elements-image--docs#utility-classes)).

```html
<sbb-lead-container>
  <figure class="sbb-figure" slot="image">
    <sbb-image
      image-src="https://cdn.img.sbb.ch/content/dam/internet/externe-assets/lyne/Bahnhof-Luzern.jpg"
      alt="Station of Lucerne from outside"
    ></sbb-image>
    <sbb-chip-label class="sbb-figure-overlap-start-start">...</sbb-chip-label>
  </figure>
  ...
</sbb-lead-container>
```

### Accessibility

Please either define the `alt` attribute of your image or set `aria-hidden="true"` to the image
to hide it from the accessibility tree.

## API (web components)

#### class: `SbbLeadContainerElement`, `sbb-lead-container`

##### Slots

| Name    | Description                                                                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|         | Use the unnamed slot to add any content to the container.                                                                                                          |
| `image` | Use the image slot to provide the lead image. `sbb-image`, `img` and `picture` elements are supported. For other elements the aspect ratio has to be set manually. |