# Modal

Ein Modal zeigt Inhalte zentriert als Overlay über der Hauptseite an, wodurch der Nutzer sich voll auf den Inhalt des Modals konzentrieren kann.

## Guidelines

# Grundlagen

## Best practices

- Setze Modals nur ein, wenn sie wirklich notwendig sind. Ein geöffnetes Modal
  zieht die gesamte Aufmerksamkeit des Nutzers auf sich und lenkt von der
  restlichen Seite ab.
- Stelle umfangreiche Prozesse in einem OffCanvas dar.
- Überfordere den Nutzer nicht mit mehr als drei Aktionen im Modal-Footer.
- Stelle sicher, dass das Modal leicht zu schließen ist, damit der Nutzer nicht
  in eine Sackgasse gerät.
- Wähle eine verständliche und prägnante Überschrift und halte den restlichen
  Inhalt leicht verständlich.
- Es sollte sich maximal ein weiteres Modal über einem bereits geöffneten Modal
  öffnen.

## Verwendung

Verwende ein Modal, um ...

- Dialoge zur Abfrage anzuzeigen, z. B. um zu bestätigen, ob etwas wirklich
  gelöscht werden soll.
- Erstellungsprozesse zu ermöglichen, ohne die aktuelle Seite zu verlassen.
- Formulare zur Bearbeitung anzuzeigen.

## Modal vs. OffCanvas

Modal und OffCanvas erfüllen beide den Zweck, dem Nutzer Informationen in einem
Overlay zu vermitteln. Auch technisch sind sie identisch.

Dennoch sollte je nach Anwendungsfall zwischen beiden unterschieden werden, da
die unterschiedliche Darstellung verschiedene Vorteile mit sich bringt.

  

**ℹ️ Info**

- einfache Dialoge wie Abfragen oder kurze Anlege-Prozesse anzuzeigen.

    - kurze Bearbeitungsmöglichkeiten darzustellen.

    - Inhalte anzuzeigen, die kein Scrollen erfordern und für die die Breite des Modals ausreicht.

  

**ℹ️ Info**

- Inhalte anzuzeigen, die nicht gekürzt werden können und ein Scrollen
    erfordern.

    - sehr breite Inhalte anzuzeigen.

---

# Inhalt

In den meisten Fällen ist eine
[ActionGroup](/04-components/actions/action-group/overview) im Footer des Modals
erforderlich, um Eingaben zu bestätigen oder das Modal zu verlassen.

Beachte bei der Verwendung jedoch, dass manche Inhalte keine Bestätigung
erfordern, da ...

- manche Modals rein informativen Inhalt enthalten.
- einige Inhalte sich unmittelbar selber speichern und zu direkten Änderungen
  führen (z. B. Einstellungen in einem OffCanvas mittels
  [Switch](/04-components/form-controls/switch/overview)).
- bestimmte Eingaben sich automatisch selber validieren (z. B.
  2-FA-Authentifikation) und das Modal schließen.

In diesen Fällen benötigt die ActionGroup keine Hauptaktion.

**ℹ️ Info**

Manche Eingaben erfordern keine explizite Bestätigung. An diesen Stellen ist
  es ausreichend, nur einen „Schließen“-Button in der ActionGroup des Modal
  Footers anzuzeigen.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  Heading,
  Section,
  Switch,
} from "@mittwald/flow-react-components";

<StaticModal>
  <header className="flow--modal--header">
    <Heading>Einstellungen</Heading>
  </header>
  <div className="flow--modal--content">
    <Section>
      <Switch defaultSelected>
        Container Frontend anzeigen
      </Switch>
      <Switch>Extensions anzeigen</Switch>
    </Section>
  </div>
  <ActionGroup className="flow--modal--action-group">
    <Action closeModal>
      <Button variant="soft" color="secondary">
        Schließen
      </Button>
    </Action>
  </ActionGroup>
</StaticModal>
```

---

# Writing guidelines

## Heading

Beachte bei der [Heading](/04-components/content/heading/overview) folgende
Punkte:

- Halte Überschriften kurz und verständlich.
- Zeichne sie semantisch korrekt aus und halte die Reihenfolge (H2, H3, H4, ...)
  ein. Die erste Überschrift in einem Modal ist semantisch immer eine H2.
- HTML-Semantik und visuelle Darstellung können separat voneinander festgelegt
  werden.
- Beginne Lösch-Prozesse immer mit einer Frage.

  

**✅ Do**

```tsx
import { Heading } from "@mittwald/flow-react-components";

<>
  <Heading level={4}>E-Mail-Adresse bearbeiten</Heading>
  <Heading level={4}>Projekt wirklich löschen?</Heading>
  <Heading level={4}>
    Projekt wirklich löschen? - App auswählen
  </Heading>
</>
```

  

**⛔️ Don't**

```tsx
import { Heading } from "@mittwald/flow-react-components";

<>
  <Heading level={4}>
    Bearbeite hier deine E-Mail-Adresse
  </Heading>
  <Heading level={4}>Projektlöschvorgang starten</Heading>
  <Heading level={4}>Wähle hier eine App aus</Heading>
</>
```

## Text

Unter der Heading befindet sich oft ein beschreibender Text. Dabei sind folgende
Punkte zu beachten:

- Setze wichtige Informationen an den Anfang.
- Hebe wichtige Informationen in Bold hervor.
- Verzichte auf einen passiven Satzbau und formuliere aktiv.

---

# Behavior

## Responsive layout

Wenn die Bildschirmgröße weniger als 551 px beträgt, dann füllt das Modal die
gesamte Breite des Bildschirms aus und wird am unteren Rand des Bildschirms
angezeigt.

**ℹ️ Info**

```tsx
import {
  Action,
  ActionGroup,
  Button,
  Heading,
  Label,
  Section,
  Text,
  TextField,
} from "@mittwald/flow-react-components";

<StaticModal>
  <header className="flow--modal--header">
    <Heading>Organisation anlegen</Heading>
  </header>

  <div className="flow--modal--content">
    <Section>
      <Text>
        Eine Organisation kannst du dir wie ein Unternehmen
        vorstellen. An diesem Ort verwaltest du deine
        Mitarbeiter, Zahlungsmodalitäten und kannst deine
        Rechnungen einsehen.
      </Text>
      <TextField>
        <Label>Organisationsname</Label>
      </TextField>
    </Section>
  </div>
  <ActionGroup className="flow--modal--action-group">
    <Action closeModal>
      <Button color="accent">Organisation anlegen</Button>
      <Button variant="soft" color="secondary">
        Abbrechen
      </Button>
    </Action>
  </ActionGroup>
</StaticModal>
```

## Schließen eines Modals

Das Schließen eines Modals sollte einfach sein, besonders wenn im Modal nichts
Wichtiges vom Nutzer bestätigt werden muss. Es sollte möglich sein, es durch
einen Klick außerhalb des Modals oder durch Drücken der "Schließen"- oder
"Abbrechen"-Taste oder der Esc-Taste zu schließen.