# mittwald Flow — Full documentation

> Full-text Markdown export of the Flow design system documentation, generated for LLMs. The React components are published as `@mittwald/flow-react-components`. Source: https://github.com/mittwald/flow

Individual pages are also available by prefixing any docs path with `/raw/` and appending `.md`.

---

# Installation

---

# Installation der Flow React Component Library

Die Flow React Component Library kann mit einem Package Manager wie `npm` oder
`yarn` installiert werden.

```shell
yarn add @mittwald/flow-react-components
```

Zur leichteren Verwaltung der Abhängigkeiten werden alle Components innerhalb
diese Packages bereitgestellt.

---

# Styles importieren

Um die Components-Styles zu verwenden, musst du das Stylesheet importieren. Füge
diese Zeile zum Einstiegspunkt deines Projektes hinzu.

```
import "@mittwald/flow-react-components/all.css";
```

---

# Defaults für Components festlegen

Einige Components verhalten sich nach einem Standard, den du für deine gesamte
Anwendung festlegen kannst, anstatt ihn an jeder Verwendung zu wiederholen.
Dafür umschließt du deine Anwendung mit dem `<ComponentDefaultsProvider />`:

```tsx
<ComponentDefaultsProvider
  defaults={{
    List: { disableInitialSuspenseBoundary: true },
    Form: { confirmModalCloseOnUnsavedChanges: false },
  }}
>
  <App />
</ComponentDefaultsProvider>
```

Jede einzelne Verwendung bleibt stärker als der Standard: Setzt eine
[List](https://flow.mittwald.de/components/list/list) das `disableInitialSuspenseBoundary`-Property an
ihrer Datenquelle oder eine [Form](https://flow.mittwald.de/components/react-hook-form/form) das
`confirmModalCloseOnUnsavedChanges`-Property, gilt dort dieser Wert.
Verschachtelte Provider gelten jeweils für ihren Teilbaum und übernehmen die
Werte, die sie nicht selbst nennen.

Diese Defaults stehen zur Verfügung:

| Default                                  | Bedeutung                                                                                                         | Wert ohne Provider |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------ |
| `List.disableInitialSuspenseBoundary`    | Die List rendert beim initialen Laden keine eigene Suspense-Boundary, sondern erscheint erst mit geladenen Daten. | `false`            |
| `Form.confirmModalCloseOnUnsavedChanges` | Das Schließen eines Modals, das eine Form mit ungespeicherten Änderungen enthält, muss bestätigt werden.          | `true`             |

---

# Aktualisieren

Ein Befehl hebt alle Flow-Abhängigkeiten auf die Zielversion, installiert und
führt den Codemod jeder Migration bis zu dieser Version aus:

```shell
npx @mittwald/flow-codemods@latest upgrade
```

Er ersetzt den Migrationsleitfaden nicht: die meisten Änderungen haben keinen
Codemod. Was in deinem Bereich von Hand ansteht, listet der Befehl am Ende auf –
vorab und ohne etwas zu verändern zeigt es `list`.

Welche Änderung ab welcher Version greift und wie Deprecation-Warnungen den
Vorlauf bilden, steht unter [Upgrades](https://flow.mittwald.de/get-started/upgrades). Was Flow dir
innerhalb einer Linie zusichert, steht unter
[Versionierung & Stabilität](https://flow.mittwald.de/get-started/versioning).

---

# Mit KI-Agents arbeiten

Ein Coding-Agent liest von sich aus nur die Anweisungen deines Projekts. Diese
Dokumentation und die Hinweise im Paket findet er nur, wenn sie dort genannt
sind. Füge deshalb diesen Block in die `AGENTS.md` (oder `CLAUDE.md`) deines
Projekts ein:

```markdown
## UI mit Flow

Bevor du UI mit Flow baust oder änderst:

1. Lies die USAGE.md des Flow-Pakets, das in package.json steht:
   - `@mittwald/flow-react-components` (Anwendung):
     node_modules/@mittwald/flow-react-components/USAGE.md
   - `@mittwald/flow-remote-react-components` (mStudio-Extension):
     node_modules/@mittwald/flow-remote-react-components/USAGE.md. Importiere
     dann immer aus diesem Paket, auch wenn die Beispiele der Dokumentation
     `@mittwald/flow-react-components` zeigen.
   - `@mittwald/flow-remote-vue-components` (mStudio-Extension in Vue, Beta):
     node_modules/@mittwald/flow-remote-vue-components/USAGE.md.
2. Lies https://flow.mittwald.de/llms.txt und öffne die dort verlinkte Seite,
   bevor du eine Component, ein Layout oder einen UI-Text festlegst. Antworte
   nicht aus dem Gedächtnis.
3. Baust du eine neue App, Seite oder einen Ablauf, wähle zuerst das passende
   Template aus dem Abschnitt „Templates“ in llms.txt: erst die App-Shell, dann
   das Seiten-Template, dann Overlays und Bausteine. Starte vom Beispielcode des
   Templates. Weiche nur davon ab, wenn ausdrücklich ein anderes Layout
   gewünscht ist – auch bei schnellen Prototypen.
```

Die `USAGE.md` passt zur installierten Version, `llms.txt` beschreibt den
aktuellen Stand der Dokumentation und verlinkt jede Seite als Markdown. Auf
jeder Seite dieser Dokumentation führt außerdem „Markdowndatei öffnen“ zur
Markdown-Fassung.

---

# mStudio-Extensions mit Vue (Beta)

Eine mStudio-Extension kann statt in React auch in Vue geschrieben werden. Das
Package `@mittwald/flow-remote-vue-components` ist das Vue-Gegenstück zu
`@mittwald/flow-remote-react-components`: Die Extension rendert damit dieselben
Flow Components im mStudio.

```shell
FLOW=$(npm view @mittwald/flow-remote-vue-components@next version)
yarn add @mittwald/flow-remote-vue-components@$FLOW @mittwald/flow-react-components@$FLOW @mittwald/ext-bridge@$FLOW vue react react-dom
```

`@mittwald/flow-react-components` ist eine Laufzeit- und Typ-Abhängigkeit: Die
Remote-Verbindung serialisiert Passwort-Policies über seinen Einstiegspunkt
`mittwald-password-tools-js`, der `react` importiert, und die Prop-Typen der
Components stammen aus seinen Deklarationen. Fehlt das Package oder `react`,
schlägt der Build der Extension fehl, ebenso ohne `@mittwald/ext-bridge`, das
`RemoteRoot` importiert. `react-dom` ist eine Peer-Dependency von
`@mittwald/flow-react-components`. `yarn` installiert Peer-Dependencies nicht
selbst, deshalb stehen alle in der Zeile. Alle Flow-Packages brauchen genau die
Version von `@mittwald/flow-remote-vue-components`. Ohne Versionsangabe nehmen
pnpm und yarn das `latest`-Tag der beiden anderen, und das ist eine andere
Release-Linie.

Das Package ist **Beta**. Es ist von der Breaking-Change-Zusage ausgenommen,
seine API kann sich auch außerhalb einer Major-Version ändern (siehe
[Component Lifecycle](https://flow.mittwald.de/get-started/versioning#component-lifecycle)). Welche
Components und Funktionen es schon abdeckt und welche noch fehlen, beschreibt
seine
[USAGE.md](https://github.com/mittwald/flow/blob/main/packages/remote-vue-components/USAGE.md).

---

# Stylesheet

Die Flow-Components-Bibliotheken werden über ein gemeinsames Stylesheet, das
auch für sich alleine verwendet werden kann, gestyled. Das kann nützlich sein,
wenn du dein eigenes Framework verwendest, um Components zu bauen, und dich
dabei an die mittwald Styling Guidelines halten willst.

Auf dieser Seite findest du alle Informationen darüber, wie du das Stylesheet
installieren kannst und wie die Klassennamen strukturiert sind.

---

# Installation des Standalone Stylesheets

Die Flow-Stylesheet-Bibliothek wird über NPM veröffentlicht und kann mit einem
Package Manager wie `npm` oder `yarn` installiert werden.

```shell
yarn add @mittwald/flow-stylesheet
```

---

# Styles importieren

Um die Components-Styles zu verwenden, musst du das Stylesheet importieren. Füge
diese Zeile zum Einstiegspunkt deines Projektes hinzu.

```
import "@mittwald/flow-stylesheet/css";
```

---

# Layered-Variante (optional)

Das Standard-Stylesheet (`@mittwald/flow-stylesheet/css`) ist **ungelayert**:
welche Regel gewinnt, entscheidet sich über Spezifität und Quell-Reihenfolge.

Optional gibt es eine **gelayerte Variante**, deren Styles in
[CSS Cascade Layers](https://developer.mozilla.org/de/docs/Web/CSS/@layer)
organisiert sind:

```
import "@mittwald/flow-stylesheet/css-layered";
```

Aus dem `@mittwald/flow-react-components`-Paket entsprechend:

```
import "@mittwald/flow-react-components/all-layered.css";
```

Sie liegt unter einem `flow`-Layer mit dieser Reihenfolge:

```css
@layer flow.tokens, flow.reset, flow.base, flow.components;
```

- `flow.tokens` – die Design-Token als CSS Custom Properties
- `flow.reset` – der globale Reset
- `flow.base` – Schriftarten (`@font-face`) und globale Basis-Styles
- `flow.components` – die Styles der einzelnen Komponenten

---

## Warum die gelayerte Variante?

Nach den Regeln der Cascade Layers gewinnt **ungelayertes** CSS immer gegen
gelayertes – unabhängig von der Spezifität. Mit der gelayerten Variante
überschreibst du Flows Styles daher ohne `!important` oder Spezifitäts-Tricks:

```css
/* Gewinnt gegen Flows .flow--button, ohne !important */
.flow--button {
  border-radius: 0;
}
```

Wenn du selbst mit Cascade Layers arbeitest (z. B. Tailwind), deklariere deine
Layer **nach** `flow`, damit sie Vorrang behalten.

---

## Welche Variante wann?

- **Standard (`css` / `all.css`):** klassisches, spezifitätsbasiertes Verhalten.
  Passt auch für Apps mit einem aggressiven globalen Reset (z. B.
  `* { all: initial }`), der gelayerte Styles sonst vollständig überschreiben
  würde.
- **Layered (`css-layered` / `all-layered.css`):** einfache, spezifitätsfreie
  Überschreibbarkeit und saubere Interop mit eigenen Cascade Layers.

---

# Anwendung des Stylesheets

Um anfangen zu können, solltest du verstehen, wie die Klassennamen strukturiert
sind. Die im Stylesheet bereitgestellten Klassennamen folgen einem konsistenten,
komponentenbasierten und leicht zu verstehendem Schema.

---

## Generelle Klassennamen-Auszeichnungen

Alle Klassennamen sind in Lowercase geschrieben und benutzen `-` um Wörter zu
trennen und `--` um logische Abschnitte zu unterteilen.

Der erste logische Abschnitt ist immer der `flow` Namespace. Andere Abschnitte
könnten beispielsweise so aussehen:

### Components

```css
.flow--button
.flow--heading
.flow--alert-badge
```

### Sub-Components

```css
.flow--navigation
.flow--navigation--navigation-group
```

### Spezialisierung: Verschiedene Varianten

```css
.flow--button--primary
.flow--alert--danger
.flow--icon--size-s
```

### Spezialisierung: In einer Komposition verwendete Components

```css
.flow--button--icon
.flow--alert--heading
```

---

## Ein Hinweis zur Spezialisierung

Klassennamen die verwendet werden, um die Basiskomponente zu spezialisieren,
müssen immer **zusätzlich zum Basis-Klassennamen** verwendet werden.

Hier ein paar Beispiele um die diese Anforderung zu verdeutlichen:

```tsx
<button className="flow--button flow--button--success">
  Success Button
</button>
```

### Kombinierte Varianten

```tsx
<button className="flow--button flow--button--success flow--button--size-s">
  Small Success Button
</button>
```

### In einer Komposition verwendete Components

Es ist gängige Praxis, größere Components aus bereits bestehenden kleineren
Components zusammenzusetzen. Der [Alert](https://flow.mittwald.de/components/status/alert) besteht
beispielsweise aus einem [Icon](https://flow.mittwald.de/components/content/icon), einer
[Heading](https://flow.mittwald.de/components/content/heading) und optionalem Inhalt. Die verwendeten
Components müssen ihren Basis-Klassennamen für das grundsätzliche Styling
erhalten (`flow--heading`), sowie den spezialisierten Klassennamen
(`flow--alert--heading`), um spezifische Styles des Inline Alerts zu erhalten.

```tsx
import ExampleSvg from "@/content/get-started/stylesheet/examples/components/ExampleSvg";

<aside className="flow--alert">
  <h3 className="flow--heading flow--heading--size-s flow--alert--heading">
    <span className="flow--heading--heading-text">
      <ExampleSvg className="flow--icon flow--alert--icon flow--heading--icon" />
      E-Mail-Adresse wurde archiviert
    </span>
  </h3>
  <div className="flow--alert--content">
    Da deine Domain gelöscht wurde, wurde diese
    E-Mail-Adresse archiviert. Um E-Mails empfangen und
    senden zu können musst du die Adresse wieder umbenennen.
  </div>
</aside>
```

---

# Versionierung & Stabilität

---

# Semantic Versioning

Alle `@mittwald/flow-*`-Packages teilen sich eine gemeinsame Version. Dieselbe
Zusage gilt damit einheitlich für jedes Package. Es gibt keine
Package-spezifischen Sonderregeln – ausgenommen ein Package, das als Ganzes Beta
ist (siehe [Component Lifecycle](#component-lifecycle)).

Seit Version `1.0.0` ist aus einer guten Absicht eine verlässliche Zusage
geworden: Wir halten uns an [Semantic Versioning](https://semver.org) und gehen
Änderungen planbar und nachvollziehbar an.

- **Major** – enthält Breaking Changes. Ein Update kann Anpassungen in deinem
  Code erfordern. Major-Versionen bleiben bewusst selten.
- **Minor** – fügt neue Funktionen hinzu und ist abwärtskompatibel.
- **Patch** – enthält Bugfixes und ist abwärtskompatibel.

Entscheidend ist die Grenze: Welche Änderung erzwingt eine neue Major-Version,
und welche darf in einem Minor oder Patch erscheinen? Die folgenden Abschnitte
beschreiben diese Grenze aus Sicht der Entwickler. Wie du ein Update oder eine
Migration konkret durchführst, beschreibt [Upgrades](https://flow.mittwald.de/get-started/upgrades).

---

# Worauf du dich verlassen kannst

Diese Bereiche sind durch die Versionierung geschützt. Eine inkompatible
Änderung daran erscheint nur in einer neuen Major-Version:

- **Runtime Public API von `public.ts`** – welche Components und Exports
  existieren und welche Props sie zur Laufzeit akzeptieren, sowie das
  dokumentierte Verhalten dokumentierter Funktionen. Die Type-Ebene ist hiervon
  ausdrücklich ausgenommen (siehe unten).
- **Components aus `@mittwald/flow-remote-react-components`** – die in
  mStudio-Extensions verwendete API. Ihre Props sind der Vertrag mit
  Extension-Entwicklern und unterliegen derselben Zusage.
- **Veröffentlichte Icons** – ein Icon zu entfernen oder umzubenennen ist ein
  Breaking Change. Icons werden ohnehin nie entfernt, sondern nur deprecated.
- **Das Remote-Protokoll** – die versionierte Verbindungsschicht zwischen
  Extension und Host bleibt kompatibel, solange dies möglich ist.

Wenn ein Teil der öffentlichen API entfernt werden soll, wird er zunächst als
deprecated gekennzeichnet und nicht sofort entfernt. Der alte Pfad bleibt
erhalten und wird zur Laufzeit über eine Deprecation-Warnung angekündigt, bevor
er in einer Major-Version entfernt wird. Das betrifft die gesamte öffentliche
API, nicht nur die in Extensions verwendeten Components.

---

# Node- und React-Unterstützung

Node und React sind echte Runtime-Voraussetzungen. Auch hier gibt es klare
Regeln, welche Änderung eine neue Major-Version erzwingt.

**Node**

- Der garantierte Node-Floor ist die aktiv unterstützte Node-LTS, aktuell
  `node >=24`, einheitlich über alle Packages. Er wird nur bei konkretem Bedarf
  angehoben, nicht um neuen Releases hinterherzulaufen.
- Eine Node-Version fallen zu lassen, die noch in ihrem LTS-/Maintenance-Fenster
  liegt, ist ein Breaking Change (→ Major). Eine bereits End-of-Life-Version
  fallen zu lassen, darf in einem Minor erscheinen.
- Strenger sind die Node-Runtime-Packages `@mittwald/ext-bridge` und
  `@mittwald/flow-remote-core`: Für sie ist jedes Anheben des Node-Floors ein
  Breaking Change (→ Major), unabhängig von EOL, und ihr Floor kann
  konservativer sein als der der übrigen Packages.

**React**

- Das **Erweitern** der akzeptierten Range (z. B. `^19` → `^19 || ^20`) ist
  abwärtskompatibel (Minor).
- Das **Anheben der Mindestversion** oder das Fallenlassen einer React-Major ist
  ein Breaking Change (→ Major).

---

# Was nicht garantiert ist

Damit sich das Design System weiterentwickeln kann, sind die folgenden Bereiche
bewusst nicht durch die Versionierung abgedeckt. Sie können sich in jedem
Release ändern, auch in einem Minor oder Patch.

## Best-effort

TypeScript-Typen, CSS-Klassennamen und Design Tokens fallen nicht unter Semantic
Versioning. Eine Änderung daran ist unwahrscheinlich – wir nehmen sie nicht
leichtfertig vor –, aber möglich: Sie kann in jedem Release erscheinen, auch in
einem Patch, ohne Major-Version und ohne Deprecation-Phase. Wenn du dich auf
einen davon stützt, lies „So schützt du dich“.

- **TypeScript-Typen.** Das gilt für die gesamte Type-Ebene: Auch das Entfernen
  oder Umbenennen eines exportierten Typs oder das Verengen eines Prop-Typs ist
  für sich genommen kein Breaking Change. Nennenswerte Type-Änderungen werden
  dennoch im Changelog erwähnt.
- **CSS-Klassennamen.** Ein internes Implementierungsdetail – weder ihre
  Existenz noch ihre Schreibweise ist zugesagt.
- **Namen und Werte von Design Tokens.** Ein Token kann umbenannt werden, einen
  anderen Wert bekommen oder verschwinden.

## Ebenfalls nicht abgedeckt

- **Das visuelle Erscheinungsbild.**
- **Die interne DOM-Struktur.**

---

# So schützt du dich

Weil die best-effort-Bereiche bewusst nicht garantiert sind, gibt es drei
Regeln, an die du dich als Entwickler halten solltest.

Drei Regeln für den stabilen Betrieb

Style nicht gegen interne CSS-Klassen, referenziere Design Tokens nicht
ungeprüft über Releases hinweg, und behandle Flows TypeScript-Typen als
best-effort. Alle drei Bereiche ändern sich selten – aber wenn, dann ohne
Vorwarnung in einem beliebigen Release.

## Style nicht gegen interne CSS-Klassen

Die CSS-Klassennamen der Components sind ein internes Implementierungsdetail und
können sich in jedem Release ändern. Verlasse dich für eigenes Styling nicht
darauf, dass eine bestimmte interne Klasse existiert oder gleich heißt.
Andernfalls kann bereits ein Patch dein Styling brechen.

## Behandle Design Tokens als best-effort

Design Tokens sind für die Verwendung innerhalb von Flow gedacht. Greifst du in
eigenem Code auf eine Token-CSS-Variable zu, prüfe sie nach einem Update: Name
und Wert können sich auch in einem Patch ändern, und ein nicht mehr
existierender Token fällt still auf den Browser-Default zurück statt einen
Fehler zu werfen.

## Behandle TypeScript-Typen als best-effort

Flows TypeScript-Typen folgen nicht Semantic Versioning. Ein `tsc`-Fehler kann
daher theoretisch schon in einem Patch auftreten. Wenn ein solcher Bruch für
dein Projekt teuer wäre, pinne exakte Versionen (statt `^`-Ranges), sodass ein
Update bewusst und kontrolliert erfolgt. Zu einem bewusst herbeigeführten
Type-Breaking-Change gehört eine Migrationsnotiz in den Release Notes – so
bekommst du einen konkreten Upgrade-Pfad, auch wenn die Änderung in einem Minor
oder Patch erscheint.

---

# Component Lifecycle

Der Vertrag gilt nicht für jede Component gleich. Jede Component hat einen
Lifecycle-Status, der die obigen Regeln überschreibt:

- **Beta** – von der Breaking-Change-Zusage ausgenommen. Die API kann sich auch
  außerhalb einer Major-Version ändern.
- **Stable** (Standard) – vollständig durch die obigen Regeln gebunden.
- **Deprecated** – bis zur Entfernung in einer Major-Version weiter abgesichert
  und mit einem Migrationspfad versehen.

Auch ein ganzes Package kann Beta sein. Das gilt derzeit für
`@mittwald/flow-remote-vue-components`, die Vue-Anbindung für
mStudio-Extensions: Es teilt die gemeinsame Version, ist aber von der
Breaking-Change-Zusage ausgenommen. Die Beta endet, sobald jede seiner bekannten
Lücken geschlossen oder als dauerhaft vermerkt ist und seine API feststeht. Ab
dann gilt die Zusage auch für dieses Package.

Das vollständige Lifecycle-Modell beschreibt
[ADR 0003](https://github.com/mittwald/flow/blob/main/docs/adr/0003-component-lifecycle-status.md),
Beta für ein ganzes Package
[ADR 0007](https://github.com/mittwald/flow/blob/main/docs/adr/0007-beta-packages.md).

---

# Upgrades

---

# Migration bei einer Breaking Change

Jede Änderung, die eine Anpassung in deinem Code erfordert, steht mit
Vorher-Nachher-Beispiel im Migrationsleitfaden des betroffenen Packages:

- [Migrationsleitfaden @mittwald/flow-react-components](https://github.com/mittwald/flow/blob/main/packages/components/MIGRATION.md)
  – deckt auch `@mittwald/flow-remote-react-components` ab
- [Migrationsleitfaden @mittwald/ext-bridge](https://github.com/mittwald/flow/blob/main/packages/ext-bridge/MIGRATION.md)

Die Einträge sind nach Version absteigend sortiert und nennen jeweils die
Version, ab der die Änderung greift. Suche die Version, von der du kommst, und
arbeite dich nach oben durch. Was dabei überhaupt als Breaking Change zählt und
eine neue Major-Version erzwingt, beschreibt
[Versionierung & Stabilität](https://flow.mittwald.de/get-started/versioning).

## Nutze die Codemod-CLI

Ein Befehl hebt alle Flow-Abhängigkeiten auf die Zielversion, installiert und
führt den Codemod jeder Migration bis zu dieser Version aus:

```shell
npx @mittwald/flow-codemods@latest upgrade
```

Ohne Argument geht es auf die nächste Minor innerhalb deiner Major.
`upgrade patch` bleibt auf deiner Minor, `upgrade major` überquert eine
Major-Grenze, und eine exakte Version oder ein Dist-Tag (`next`) gehen genau
dorthin.

Der Befehl ändert Dateien direkt und bricht auf einem unsauberen Git-Stand ab.

Der Befehl kennt keine untere Grenze: er listet auch Migrationen, die vor deiner
aktuellen Version erschienen sind. Nichts hält fest, welche davon dein Projekt
schon durchgeführt hat – und ein zweiter Durchlauf eines Codemods ändert nichts.

Ein Codemod, der durchgelaufen ist, ist allerdings kein Beweis: jeder Codemod
ist bewusst eng gefasst und lässt liegen, was er aus dem Code nicht sicher
entscheiden kann – ein gespreadetes Prop, eine Component, die über einen eigenen
Wrapper re-exportiert wird, ein dynamischer Zugriff. Einen Fehler meldet er
dafür nicht. Prüfe nach einem Upgrade deshalb auch die Migrationen mit Codemod
am Code nach, nicht nur die ohne.

Er ersetzt den Migrationsleitfaden nicht: die meisten Einträge haben keinen
Codemod. Welche das für deinen Bereich sind, listet der Befehl am Ende auf –
oder vorab, ohne etwas zu verändern, mit `list` und derselben Revision:

```shell
npx @mittwald/flow-codemods@latest list minor
```

`list` ohne Argument zeigt den gesamten Katalog, offline. Mit einer Revision
liest es dieselbe Version aus deinem `package.json` und zeigt genau den Bereich,
den `upgrade` mit dieser Revision anfassen würde – ein echter Trockenlauf.

Einen einzelnen Codemod führst du über seine ID aus:

```shell
npx @mittwald/flow-codemods@latest align-to-combine src
```

## Lass einen Agenten das Upgrade machen

Was die CLI offen lässt, kann ein Coding-Agent übernehmen: die Migrationen ohne
Codemod – das sind die meisten – und die Stellen, die ein Codemod übersprungen
hat. `list --json` liefert ihm dafür pro Migration das Feld `apply`: die
Anweisung, was zu ändern ist, knapp genug für einen Katalog und präzise genug
zum Ausführen.

Kopiere den folgenden Prompt in deinen Agenten. Er sucht zuerst, wo Flow
überhaupt deklariert ist – in einem Monorepo ist das meist mehr als ein Package,
und `list` wie `upgrade` lesen immer nur die `package.json` des Verzeichnisses,
in dem sie laufen. Dann klärt er auf, welche Zielversionen zur Wahl stehen und
was jede davon an Arbeit bedeutet, und fragt dich, welche es sein soll. Danach
geht er jede Migration im Bereich am Code nach – auch die mit Codemod – und
ändert nur, wo er das alte Muster wirklich findet.

Was dabei offen bleibt, gibt er dir nicht als Hausaufgabe zurück. Genau die
Punkte, die eine Entscheidung brauchen, sind die, bei denen er den Diff gelesen
hat und du nicht – deshalb legt er sie dir gesammelt vor, jeweils mit den
Optionen und einer Empfehlung, setzt deine Antwort um und lässt die Checks
erneut laufen. Das wiederholt sich, bis nichts mehr offen ist. Er hört vorher
nur auf, wenn etwas wirklich nicht hier entschieden werden kann – eine
Design-Entscheidung, eine Freigabe, ein Zugang – und sagt dann, worauf es wartet
und wer es tun muss.

Der Prompt ist englisch, weil alles, worauf er zeigt, englisch ist: die
CLI-Ausgabe, die `apply`-Felder und der Migrationsleitfaden.

```text
Upgrade this project's mittwald Flow dependencies.

First find out where Flow is declared. Search every `package.json` in the
project for a `@mittwald/flow-` dependency, but only the ones the project
actually maintains. `git ls-files "*package.json"` gets that right in one step:
`node_modules` and build output — `dist`, `build`, `.next`, `.output`, `.nuxt`,
`.svelte-kit`, `.turbo`, `out`, `coverage`, whatever this project emits — are
git-ignored, and a copied or generated manifest in there would have you
upgrading an artefact. Outside a git checkout, exclude those paths yourself.

In a monorepo Flow is usually declared in several workspace packages, and the
root often declares none. Every command below reads and writes exactly one
`package.json`: the one in the directory you run it from. Neither `list` nor
`upgrade` walks a workspace, so a single run at the root silently leaves every
other package behind. Tell me which packages you found, and which Flow version
each is currently on.

Then plan — change nothing yet. From one of those packages, run all three and
read the JSON:

- `npx @mittwald/flow-codemods@latest list patch --json`
- `npx @mittwald/flow-codemods@latest list minor --json`
- `npx @mittwald/flow-codemods@latest list major --json`

Each run reports the version it would resolve to (`range.target`) and every
migration in that range. A relative revision only resolves if such a release
exists: from a prerelease, or from the newest version on a line, `patch` and
`minor` exit non-zero with no JSON and a message saying so. That is not an
error to work around — it means the choice is narrower than three options.

So show me what actually resolved, side by side: target version, how many
migrations carry a codemod, how many need a hand. If fewer than three resolved,
say which and why, and put a dist-tag (`next`) or an exact version (`1.4.0`) on
the table as an equal option rather than a fallback — those always resolve.

Then ask me which target to take, and wait for my answer.

Then, on the target I chose:

- Commit or stash what is open first. Do not pass `--allow-dirty` — that guard
  is what keeps a bad run `git checkout`-able.
- Run `npx @mittwald/flow-codemods@latest upgrade <target>`. It bumps the
  dependencies, installs, and runs the codemod of every migration up to the
  target. Pass `--path <dir>` unless the sources really are under `./src` —
  find that directory before the first command, not after.
- It bumps every package published from the Flow monorepo, not only the
  `@mittwald/flow-*` ones: `@mittwald/ext-bridge`,
  `@mittwald/mstudio-ext-react-components` and `@mittwald/react-tunnel` are on
  the same release train and move too. Tell me which ones it actually rewrote.
- Only if more than one package declares Flow: run it once per package, from
  that package's own directory, passing the resolved exact version rather than
  `patch`/`minor`/`major` — a relative revision resolves from the version that
  one package is on, so packages that started out apart would land apart. And
  commit after each one: the dirty-tree guard reads `git status` for the whole
  repository, so the second run would otherwise refuse. Do not reach for
  `--allow-dirty` instead; committing keeps each package a revertible step.
- `peerDependencies` are reported and deliberately left untouched. Note what it
  named as an open decision for the closing round below — do not hand it to me
  now and do not narrow a range on your own. That report comes after the
  install, so a failed install means you never see it; read the manifests
  yourself then.
- If the install fails with `ETARGET` or `ERR_PNPM_NO_MATCHING_VERSION` on a
  Flow package, that is the publishing window right after a release. Wait a few
  minutes and install again — do not pin anything and do not mix Flow versions
  to get around it.
- If the install fails for any other reason, do not wait and retry — that only
  helps the case above. The manifest is already rewritten while `node_modules`
  still holds the old version, so read the actual error and finish the install
  yourself with the project's own package manager. The command detects the
  manager from lockfiles in the directory it runs in, which in a workspace
  package is the wrong place to look: check the repository root for a lockfile
  and a `packageManager` field before trusting what it chose. Confirm the
  versions it wrote are published, then install; revert the bump only if they
  are not.

Then check every migration against the code — every entry in the JSON, including
the ones with `action: "codemod"`. A codemod is deliberately scoped
narrowly and skips anything it cannot decide from the source: a spread prop, a
component re-exported through a local wrapper, a dynamic access, a file outside
the path it ran on. It reports no error for those. A codemod that ran clean is
therefore not proof the old pattern is gone — treat its run as a head start, not
as a result. Read the `upgrade` report for what it admits: an entry that changed
no file, declined every file it looked at, or found nothing to process is the
strongest hint that its pattern is still there in a shape it could not handle.

One caveat on that report. "No files were processed. Is the path right?" is also
what a codemod that crashed before touching a file looks like — the counters are
identical, and the summary line guesses at the path. Check stderr for a stack
trace before you believe the path is wrong, and tell me if a codemod died: its
migration then had no run at all, and everything below is the only thing that
covers it.

Include the entries flagged `catchUp: true`. They shipped before the version
this project was on and may never have been done here.

For each entry:

1. Read `apply`. It is the whole instruction — the JSON carries no example, and
   the human-readable `list` output has none either. For a before/after example,
   look up the entry id in `MIGRATION.md`, which ships inside
   `@mittwald/flow-react-components` and is also on GitHub. Do not paste the
   command `list` prints beside an entry: its path argument is hardcoded to
   `src`, which is wrong wherever `--path` was needed above.
2. Search for the old pattern across every package that uses Flow, not just the
   one you last ran in. Resolve Flow imports properly — named, aliased and
   namespace imports all count — and treat an entry marked `remotePackage: true`
   as applying to `@mittwald/flow-remote-react-components` too.
3. No match: say so and move on. No edit.
4. Match: make the change `apply` describes, by hand. On a codemod entry, do not
   just run the codemod again — it already saw that site and declined it, so a
   second run declines it again.
5. Leave an edit undone only when the right migration is genuinely ambiguous
   from the code. Do not hand it to me here: record it as an open decision with
   the entry id, the site, the options you see and which one you would pick and
   why. The closing round below settles it.

Keep the change scoped to the upgrade. No unrelated refactoring, no reformatting
of files you did not otherwise touch.

Then run the project's own checks — type check, lint, build, tests, whatever
`package.json` provides — and fix what the upgrade broke. In a monorepo run them
at the root so a package you did not touch is covered too: a Flow change in one
package can break its consumer in another.

A failure that was already there before the upgrade is not yours to fix, and not
mine to be handed either. Check it against the commit you started from, then
say which of the two it is. Pre-existing ones: name them in one line each and
leave them alone — chasing them turns an upgrade into an open-ended cleanup. If
the project has no checks at all, say that too, so neither of us mistakes
silence for a green run.

Then finish the migration with me. Do not hand me a list of leftovers — a
migration that ends in homework is not done, and the open items are exactly the
ones where you have the context and I do not, having not read the diff.

Go through every open decision you recorded, plus the `peerDependencies` report,
one at a time. For each: name the entry and the site, show the code as it
stands, lay out the options in a sentence each, say which one you would pick and
why, and ask me. Ask them in one pass rather than trickling them out, and put
the ones that block a check first. If a decision turns out to have one obviously
right answer once you look properly, take it and tell me — do not spend my
attention on a question you can answer.

Apply each answer as I give it, then run the checks again: a decision can break
something the previous pass did not touch, and closing one item can make another
moot. Repeat until nothing is open.

Stop only when one of these is true, and say which:

- Nothing is open. Every check that passed before the upgrade passes again — or
  the project has none — and no decision is waiting.
- What is left genuinely cannot be settled here — it needs someone who owns the
  design, an approval, a credential, or a change outside this upgrade's scope.
  Name each one, say exactly what it is waiting on and who has to do it, and put
  it in a state I can pick up: the code compiling, or a single clearly marked
  spot to come back to.
- I told you to stop.

Then summarize: which packages you upgraded and from which version to which,
which codemods changed files, which entries you fixed by hand, which found
nothing, what we decided together — and whether anything is still open, with the
reason from the list above. If nothing is open, say so plainly rather than
padding the summary with caveats.

Finally, do not leave the whole migration sitting uncommitted. Walk me through
the diff at the level of what changed and why — not file by file — then propose
how to commit it: one commit, or one per package in a monorepo, with the
messages written out. Commit once I say so. If I would rather review first,
leave the tree as it is and say so in one line; do not commit without an answer,
and do not push in any case.

```

Zwei Dinge, die der Prompt bewusst nicht tut: Er lässt den Agenten nicht auf
einem unsauberen Git-Stand starten, damit ein missglückter Lauf ein
`git checkout` bleibt. Und er lässt ihn nichts an deinen `peerDependencies`
ändern – was deine eigenen Consumer installieren dürfen, ist deine Entscheidung.

### Optional: erzähl uns, was nicht getragen hat

Ganz unabhängig vom Upgrade: der folgende Prompt ist ein **zweiter, eigener
Baustein**. Du kopierst ihn – wenn du magst – direkt nach dem Upgrade in
dieselbe Session. Der Agent hat den Lauf dann noch im Kontext und schreibt
daraus einen Bericht auf zwei Ebenen. Nicht kopieren ist die Absage; am Upgrade
ändert das nichts.

**Der Prompt selbst.** Ein Schritt in der falschen Reihenfolge. Eine Annahme,
die auf dein Projekt nicht zutrifft. Eine Stelle, an der der Agent raten musste
oder zwei Anweisungen sich widersprachen. Eine Situation, zu der der Prompt
schweigt. Eine Anweisung, die Arbeit gekostet und nichts geändert hat.

**Die einzelne Migration.** Ein `apply`, das ohne Raten nicht ausführbar war.
Eine Stelle, die ein Codemod liegen gelassen hat, obwohl er sie hätte
entscheiden können. Eine Migration ohne Codemod, die mechanisch entscheidbar
wäre. Ein `apply`, das eine Umbenennung beschreibt, obwohl sich auch die
Signatur geändert hat. Ein Codemod, der abgestürzt ist. Und der wertvollste
Fall: ein Bruch, den deine Checks gefunden haben und für den es gar keinen
Katalogeintrag gibt.

Beide Ebenen sehen wir sonst nicht. Ob eine Migration verständlich beschrieben
ist und ob der Upgrade-Prompt trägt, zeigt sich erst an einer echten Codebase –
nicht an unserer. Ein Bericht als
[Issue](https://github.com/mittwald/flow/issues) hilft uns deshalb wirklich
weiter: er fließt in den Katalog und in den Prompt zurück, und das nächste
Upgrade ist für alle etwas weniger Handarbeit. Ein Paste genügt, und eine
Antwort schuldest du niemandem.

Der Agent reicht ihn nicht selbst ein. Er legt ihn dir vor und sagt dir, was du
damit tun kannst – du entscheidest, was rausgeht. Code-Beispiele reduziert er
auf die kleinste anonymisierte Form, aber prüfen musst du das selbst.

```text
Write a report on that upgrade for Flow's maintainers — not for me. Report where
their tooling fell short, not what my project needed. Judge every point from
what actually happened in this session, not from reading any text back: a
plausible-sounding critique nobody hit is worse than no report, because it sends
them after a problem that does not exist and nothing here can be checked against
anything.

It has two parts, and the first is the one nobody ever sends.

Part one, the upgrade prompt you just followed. You ran it end to end against a
codebase its authors have never seen, which is the only way its gaps show up at
all. Report:

- A step that came in the wrong order, or that assumed something this project
  does not have.
- A point where you had to guess what was meant, or where two instructions
  pulled in different directions.
- A situation you ran into that the prompt says nothing about, and what you did
  instead.
- An instruction that turned out to be unnecessary, or that cost work without
  changing the outcome.
- What you would have wanted to know before you started.

Part two, the migration catalogue. Name the entry id for each:

- Entries whose `apply` you could not execute without guessing. Quote the field
  and say what it left open.
- Sites a codemod declined that it looks like it could have handled. Name the
  shape that defeated it.
- Entries with `action: "manual"` whose change looks mechanically decidable — a
  codemod could exist there and does not.
- Breaks the checks surfaced that no entry in the catalogue covers at all. These
  matter most: nothing else reveals them.
- An `apply` that described a rename but was also a type or behaviour change, or
  that contradicted the code you actually saw.
- A codemod that crashed, or a command the tool printed that did not work as
  printed.

Write it as Markdown that can go into an issue unedited, opening with the
version you went from and to, the package manager, and whether this is a
monorepo. Reduce every code sample to the smallest anonymised shape that still
shows the problem:
no project or package names, no file paths, no business logic. If a point has
nothing under it, drop the point rather than padding it; if a whole part would
be empty, say so in one line.

Do not file it anywhere and do not push it. Hand it over, and close by telling
me what I can do with it:

- Send it as a new issue at https://github.com/mittwald/flow/issues. This is
  genuinely valuable to the Flow team — a run against a codebase they cannot see
  is the only way they learn where the catalogue and that prompt fall short, and
  what comes back feeds into both. It takes one paste.
- Or drop it. Nothing depends on it and no answer is owed.

Either way the choice is mine, and so is the review: tell me to read it for
anything about my project I would not put in a public tracker before I send it.
```

## Deprecation-Warnungen sind der Vorlauf

Wird ein Pfad deprecated, bleibt er funktionsfähig und meldet sich zur Laufzeit
per `console.warn`. Diese Warnungen sind die Vorwarnzeit vor der nächsten
Major-Version – behandle sie als Aufgabenliste, nicht als Rauschen. Um sie
zentral einzusammeln, etwa im Error-Tracking, umschließe deine Anwendung mit
einem `DeprecationWarningProvider` und gib ihm einen `onWarning`-Handler:

```tsx
<DeprecationWarningProvider onWarning={(message) => reportToTracking(message)}>
  <App />
</DeprecationWarningProvider>
```

---

# Direkt nach einem Release

Ein Release veröffentlicht die Packages **nacheinander**, nicht gleichzeitig.
Für einige Minuten liegt in der npm-Registry deshalb für die schon
veröffentlichten Packages die neue Version, für die restlichen noch die alte.
Beim Release `1.0.6` lagen zwischen dem ersten und dem letzten Package rund 25
Minuten.

Du triffst dieses Fenster leicht, denn ein Update betrifft immer mehrere
Packages: alle `@mittwald/flow-*`-Packages teilen sich eine gemeinsame Version,
und `@mittwald/flow-react-components` fordert `@mittwald/flow-icons-pro` als
Peer-Dependency in exakt derselben Version. Ziehst du in diesem Fenster alle
Flow-Abhängigkeiten auf die neue Version, schlägt die Installation für das
Package fehl, das noch nicht dran war:

```
npm error code ETARGET
npm error notarget No matching version found for @mittwald/flow-react-components@1.0.6
```

pnpm meldet dasselbe als `ERR_PNPM_NO_MATCHING_VERSION`.

Das ist keine Lücke im Release: sobald der Release-Lauf durch ist, haben alle
Packages dieselbe Version. Direkt nach einem Release ist dieser Fehler fast
immer das Veröffentlichungsfenster und nichts anderes.

Warte ein paar Minuten und installiere erneut

Das Fenster schließt sich von selbst. Du brauchst keinen Workaround – pinne
nichts fest und mische keine Flow-Versionen, um den Fehler zu umgehen.

---

# Releases

Diese Seite bündelt die veröffentlichten Flow-Releases in einer Zeitleiste – mit
Highlights, Migrationshinweisen und den enthaltenen Fixes je Patch-Version. Wie
du ein Update einspielst, beschreibt [Upgrades](https://flow.mittwald.de/get-started/upgrades).

---

# Design Tokens

Design Tokens übersetzen grundlegende Designentscheidungen wie Farben, Abstände
und mehr in eine einheitliche Sprache. Entwickler und Designer nutzen diese
Sprache, um ein konsistentes, skalierbares und wiederverwendbares Design in der
gesamten Benutzeroberfläche sicherzustellen.

---

# Was sind Design Tokens?

Ein Design Token (kurz: Token) besteht aus 2 Teilen: Name und Wert. Der Name
eines Tokens folgt einem klaren und verständlichen Benennungsschema. Der Wert
kann alles beinhalten, was zum Erstellen eines Designs notwendig ist: Eine Farbe
in RGB, eine Schriftart, eine Animations-Geschwindigkeit oder einen anderen
Token.

---

# Vorteile

- **Verringerter Wartungsaufwand:** Tokens können aufeinander basieren und die
  Eigenschaften eines anderen Tokens erben. Dadurch wirken sich Änderungen an
  einem Token-Wert automatisch auf alle Stellen aus, an denen er verwendet oder
  referenziert wird. Das spart Zeit und reduziert Fehler.

- **Verbesserte Zusammenarbeit:** Design und Development nutzen mit Tokens eine
  gemeinsame Sprache. Dadurch lassen sich Designentscheidungen leicht
  verständlich ausdrücken und ebenso einfach im Code implementieren.

- **Einheitliches Design:** Farben, Schriften, Größen und mehr werden überall
  einheitlich verwendet.

- **Wiederverwendbarkeit:** Tokens lassen sich problemlos in mehreren Projekten
  und Frontends gleichzeitig verwenden.

---

# Benennung von Tokens

Unsere Tokens sind leicht verständlich und nachvollziehbar benannt, um komplexe
Informationen konsistent und selbsterklärend zu vermitteln.

## Schema

Jeder Token-Name folgt einem dreistufigen Benennungsschema: Context, Common Unit
und Clarification. Dieses Schema beginnt mit einer allgemeinen Einordnung und
wird von Stufe zu Stufe immer detaillierter.

**ℹ️ Token-Benennungsschema**

```tsx
import {
  Badge,
  ColumnLayout,
  Text,
} from "@mittwald/flow-react-components";

<ColumnLayout m={[1, 1, 1]}>
  <Text>
    <Badge color="teal">Context</Badge>
    Einordnung <br />
    <small>z. B. Farbe, Component</small>
  </Text>
  <Text>
    <Badge color="orange">Common Unit</Badge>
    Kategorie <br />
    <small>z. B. Variante, Sizing, Styling</small>
  </Text>
  <Text>
    <Badge color="lilac">Clarification</Badge>
    Spezifizierung <br />
    <small>z. B. Farbwert, State</small>
  </Text>
</ColumnLayout>
```

### Context

Der Context stellt den allgemeinsten Zusammenhang dar, auf den ein Token sich
beziehen kann.

### Common Unit

Die Common Unit ordnet den Token in eine spezifische Kategorie innerhalb des
Context ein.

### Clarification

Die Clarification ist die präziseste Ebene, die den Token klar definiert und
abgrenzt.

## Beispiele

**color--hosting-blue--800**

Der Token `color--hosting-blue--800` definiert eine spezifische
[Color](https://flow.mittwald.de/foundations/design/colors). `color` gibt den **Context** an. Der Name
der Farbe `hosting-blue` ist die **Common Unit**. Die Zahl `800` ist die
**Clarification**, die die Abstufung der Farbe definiert und auf den genauen
Farbwert `#0054F5` im Designsystem verweist.

**primary-solid-background-color--default**

Dieser Token definiert die primäre Hintergrundfarbe einer „Solid“-Variante.
`primary` gibt als Context an, dass es sich um eine primäre Farbe handelt. Die
Common Unit `solid-background-color` verdeutlicht, dass die Farbe als
Hintergrundfarbe in der „Solid“-Variante verwendet wird. Die **Clarification**
`default` gibt an, dass der Token für den Default-State verwendet wird.

**alert--info-border-color**

Dieser Token definiert eine Designentscheidung für eine spezifische Component,
in diesem Fall einen [Alert](https://flow.mittwald.de/components/status/alert). `alert` liefert den
**Context** und stellt klar, dass der Token nur für diese Component verwendet
wird. `info-border-color` als **Common Unit** kategorisiert den Token weiter
ein: Er wird für die Border-Color eines Alerts in der „Info“-Variante verwendet.
Eine **Clarification** braucht dieser Token nicht, weil die Border-Color eines
Alerts in allen States gleich bleibt.

---

# Token-Arten und Struktur

Im Benennungsschema haben wir bereits Tokens mit unterschiedlicher Komplexität
betrachtet. In diesem Abschnitt erklären wir die Konzepte, die den verschiedenen
Token-Arten und deren Struktur zugrunde liegen.

## Global Token

Diese Tokens bilden die Grundlage des gesamten Designsystems. Sie definieren
grundlegende Eigenschaften wie Farben, Schriftarten und Abstände, die überall im
System verwendet werden können. Global Tokens sollten nur eingesetzt werden,
wenn der Verwendung kein tieferes Konzept zugrunde liegt. Ein gutes Beispiel
dafür sind Farben, die einen rein dekorativen Zweck erfüllen. Diese müssen nicht
weiter definiert oder in eine Kategorie eingeordnet werden, da sie einen rein
optischen Nutzen erfüllen und keiner tieferen Idee folgen.

| Token-Name               | Wert    |
| ------------------------ | ------- |
| color--hosting-blue--800 | #0054F5 |
| size-px--s               | 8px     |

## Alias Token

Alias Tokens referenzieren andere Tokens und weisen ihnen eine spezifischere
Bedeutung zu. Sie helfen dabei, allgemeine Werte in spezifischen Kontexten
einzusetzen. Ein Alias Token konkretisiert z. B. bei einer Color, in welchem
Zusammenhang (Primary, Success, Danger, ...) sie genutzt werden soll. Sie
beziehen sich immer auf einen Global Token und dürfen keine hard coded Werte
besitzen.

Wir nutzen diese Ebene vor allem für die Definition von Tokens, die sich keiner
bestimmten Variante (Solid, Soft, Outlined, Plain) zuordnen lassen, aber in eine
gemeinsame Kategorie zusammengefasst werden können.

| Token-Name          | Wert                     |
| ------------------- | ------------------------ |
| primary--color--800 | color--hosting-blue--800 |
| border-width--400   | size-px--s               |

## Alias Token 2

Tokens dieser Ebene besitzen einen noch höheren Detailgrad. Sie werden oft einer
spezifischen Variante zugeordnet und fügen weitere Details hinzu, die über den
ersten Alias Token hinausgehen. Dabei achten wir auch darauf, die Token so zu
definieren, dass sie innerhalb der Variante gut harmonieren. So legen wir z. B.
bei einer bestimmten Variante die Farben so fest, dass die Content-Farbe optisch
zur Hintergrundfarbe passt und barrierefrei lesbar ist.

Ein Alias Token 2 darf keine hard coded Werte besitzen, sich aber sowohl auf
Alias als auch Global Token beziehen.

| Token-Name                              | Wert                |
| --------------------------------------- | ------------------- |
| primary-solid-background-color--default | primary--color--800 |
| info-outline-border-color               | info--color--800    |

## Component Specific Token

Diese Tokens sind speziell auf einzelne Components zugeschnitten. Sie vermitteln
einzigartige Designentscheidungen, die ausschließlich für eine bestimmte
Component relevant sind. Sie enthalten den höchsten Detailgrad der
Token-Struktur und sind somit das Gegenteil eines Global Tokens.

| Token-Name                                      | Wert                                    |
| ----------------------------------------------- | --------------------------------------- |
| button--primary-solid-background-color--default | primary-solid-background-color--default |
| alert--info-border-color                        | info-outline-border-color               |

---

# Color

Ausgewählte Colors verkörpern die Marke und dienen gleichzeitig als wesentliches
Kommunikationsmittel in der Benutzeroberfläche. Sie lenken die Aufmerksamkeit
des Users und vermitteln gezielt wichtige Informationen wie z. B. den Status.

---

# Base Color

Base Colors bilden das Fundament des Flow Design Systems. Sie prägen die
Oberflächen und schaffen die visuelle Grundlage für alle Components und Layouts.

## Neutral Color

Neutral Colors sind zurückhaltend und vielseitig einsetzbar. Durch ihre
Ausgewogenheit harmonieren sie mit allen weiteren Farben und kommen in nahezu
allen UI-Elementen zum Einsatz.

| Token | Wert |
| --- | --- |
| `--color--gray--100` | `#FFFFFF` |
| `--color--gray--200` | `#F4F8FC` |
| `--color--gray--300` | `#E5EFF8` |
| `--color--gray--400` | `#DCE9F7` |
| `--color--gray--500` | `#B7C9DB` |
| `--color--gray--600` | `#8FA1B4` |
| `--color--gray--700` | `#5E6C7A` |
| `--color--gray--800` | `#3A434E` |
| `--color--gray--900` | `#292F37` |
| `--color--gray--1000` | `#1B1F24` |
| `--color--gray--1100` | `#121518` |
| `--color--gray--1200` | `#000000` |

## Hosting Blue

Hosting Blue ist unsere Primärfarbe. Sie verleiht dem mStudio ein prägnantes
Erscheinungsbild und stärkt die Wiedererkennung der Marke mittwald. Aufgrund
ihrer Leuchtkraft eignet sie sich besonders für gezielte Akzente, interaktive
Elemente und visuelle Hervorhebungen.

| Token | Wert |
| --- | --- |
| `--color--hosting-blue--100` | `#F0F5FF` |
| `--color--hosting-blue--200` | `#E0EBFF` |
| `--color--hosting-blue--300` | `#ABC6FF` |
| `--color--hosting-blue--400` | `#85AFFF` |
| `--color--hosting-blue--500` | `#6197FF` |
| `--color--hosting-blue--600` | `#3D80FF` |
| `--color--hosting-blue--700` | `#1A68FF` |
| `--color--hosting-blue--800` | `#0054F5` |
| `--color--hosting-blue--900` | `#003FB8` |
| `--color--hosting-blue--1000` | `#002A7B` |
| `--color--hosting-blue--1100` | `#00205C` |

---

# Functional Color

Functional Colors kommunizieren Zustände und unterstützen die Nutzerführung. Sie
helfen dabei, Informationen schnell einzuordnen und Handlungsbedarf zu erkennen.
Weitere Details zur Anwendung finden sich im
[Informationskonzept](https://flow.mittwald.de/foundations/content-guidelines/informationskonzept).

## Espelkamp Green

Espelkamp Green steht für positive Rückmeldungen und erfolgreiche Aktionen. Die
Farbe signalisiert Bestätigung, Abschluss oder einen fehlerfreien Zustand.

| Token | Wert |
| --- | --- |
| `--color--espelkamp-green--100` | `#DCFFF4` |
| `--color--espelkamp-green--200` | `#C0FFEB` |
| `--color--espelkamp-green--300` | `#87FFDA` |
| `--color--espelkamp-green--400` | `#4FFFC9` |
| `--color--espelkamp-green--500` | `#17FFB8` |
| `--color--espelkamp-green--600` | `#00DE9A` |
| `--color--espelkamp-green--700` | `#00A673` |
| `--color--espelkamp-green--800` | `#00825B` |
| `--color--espelkamp-green--900` | `#005F42` |
| `--color--espelkamp-green--1000` | `#003B29` |
| `--color--espelkamp-green--1100` | `#00291C` |

## Royal Orange

Royal Orange kennzeichnet Warnungen und weist auf potenzielle Risiken oder
unerwünschte Zustände hin. Die Farbe signalisiert, dass Aufmerksamkeit
erforderlich ist und eine Handlung zeitnah erfolgen sollte, auch wenn noch kein
kritischer Fehler vorliegt.

| Token | Wert |
| --- | --- |
| `--color--royal-orange--100` | `#FFF4EB` |
| `--color--royal-orange--200` | `#FFEBDC` |
| `--color--royal-orange--300` | `#FFD9BD` |
| `--color--royal-orange--400` | `#FFC89F` |
| `--color--royal-orange--500` | `#FFA562` |
| `--color--royal-orange--600` | `#FF9343` |
| `--color--royal-orange--700` | `#FF8225` |
| `--color--royal-orange--800` | `#F56800` |
| `--color--royal-orange--900` | `#C25200` |
| `--color--royal-orange--1000` | `#8F3D00` |
| `--color--royal-orange--1100` | `#763200` |

## Amaranth Red

Amaranth Red kennzeichnet kritische Zustände. Die Farbe signalisiert dringenden
Handlungsbedarf oder Fehler, die unmittelbare Aufmerksamkeit erfordern.

| Token | Wert |
| --- | --- |
| `--color--amaranth-red--100` | `#FDF0F3` |
| `--color--amaranth-red--200` | `#FBE0E6` |
| `--color--amaranth-red--300` | `#F7C1CC` |
| `--color--amaranth-red--400` | `#F2A2B3` |
| `--color--amaranth-red--500` | `#EE8299` |
| `--color--amaranth-red--600` | `#EA637F` |
| `--color--amaranth-red--700` | `#E54366` |
| `--color--amaranth-red--800` | `#E1244C` |
| `--color--amaranth-red--900` | `#AB1737` |
| `--color--amaranth-red--1000` | `#710F24` |
| `--color--amaranth-red--1100` | `#540B1B` |

---

# Decorative Color

Decorative Colors erweitern die Farbpalette um zusätzliche Markenfarben. Sie
werden ausschließlich für dekorative Elemente sowie für Marketing- und
Kommunikationsmaßnahmen eingesetzt und haben keine funktionale Bedeutung
innerhalb des Interfaces.

## Soft Contrast Violet

| Token | Wert |
| --- | --- |
| `--color--soft-contrast-violet--100` | `#F4F3FE` |
| `--color--soft-contrast-violet--200` | `#EAE7FD` |
| `--color--soft-contrast-violet--300` | `#D6D0FA` |
| `--color--soft-contrast-violet--400` | `#C2B9F8` |
| `--color--soft-contrast-violet--500` | `#AEA2F5` |
| `--color--soft-contrast-violet--600` | `#998BF3` |
| `--color--soft-contrast-violet--700` | `#8574F0` |
| `--color--soft-contrast-violet--800` | `#715DEE` |
| `--color--soft-contrast-violet--900` | `#5d4abf` |
| `--color--soft-contrast-violet--1000` | `#483b9f` |
| `--color--soft-contrast-violet--1100` | `#302a6f` |

## Super Teal

| Token | Wert |
| --- | --- |
| `--color--super-teal--100` | `#ebfdff` |
| `--color--super-teal--200` | `#cffaff` |
| `--color--super-teal--300` | `#96f3ff` |
| `--color--super-teal--400` | `#5eedff` |
| `--color--super-teal--500` | `#26e7ff` |
| `--color--super-teal--600` | `#00d3ed` |
| `--color--super-teal--700` | `#00a1b5` |
| `--color--super-teal--800` | `#008696` |
| `--color--super-teal--900` | `#006b78` |
| `--color--super-teal--1000` | `#004f59` |
| `--color--super-teal--1100` | `#00424a` |

## Bright Lilac

| Token | Wert |
| --- | --- |
| `--color--bright-lilac--100` | `#f9e9ff` |
| `--color--bright-lilac--200` | `#f6dfff` |
| `--color--bright-lilac--300` | `#f1caff` |
| `--color--bright-lilac--400` | `#ebb6ff` |
| `--color--bright-lilac--500` | `#e6a1ff` |
| `--color--bright-lilac--600` | `#e08dff` |
| `--color--bright-lilac--700` | `#ce4bff` |
| `--color--bright-lilac--800` | `#bc08ff` |
| `--color--bright-lilac--900` | `#9000c5` |
| `--color--bright-lilac--1000` | `#5f0083` |
| `--color--bright-lilac--1100` | `#470062` |

## mittwald Navy

| Token | Wert |
| --- | --- |
| `--color--mittwald-navy--100` | `#E4E7F6` |
| `--color--mittwald-navy--200` | `#C8CFEE` |
| `--color--mittwald-navy--300` | `#A5B0E2` |
| `--color--mittwald-navy--400` | `#8291D7` |
| `--color--mittwald-navy--500` | `#5F73CC` |
| `--color--mittwald-navy--600` | `#3D55C1` |
| `--color--mittwald-navy--700` | `#32459E` |
| `--color--mittwald-navy--800` | `#27367B` |
| `--color--mittwald-navy--900` | `#1D285C` |
| `--color--mittwald-navy--1000` | `#131B3D` |
| `--color--mittwald-navy--1100` | `#0E142E` |

---

# Light und Dark Color

Light und Dark Colors wurden speziell für den Einsatz auf farbigen Hintergründen
oder Bildern entwickelt. Sie bestehen aus jeweils 8 transparenten Abstufungen.
Da die Farben auf Transparenzen basieren, muss der Kontrast zur jeweiligen
Hintergrundfarbe eigenständig auf Barrierefreiheit geprüft werden. Aus diesem
Grund stehen sie nur in definierten Components zur Verfügung, beispielsweise im
[Button](https://flow.mittwald.de/components/actions/button).

Die Verwendung orientiert sich am HSL-Farbmodell. HSL steht für Hue, Saturation
und Lightness. Für die Auswahl von Light oder Dark ist ausschließlich der
Lightness-Wert relevant. Er beschreibt die wahrgenommene Helligkeit einer Farbe
auf einer Skala von 0 bis 100.

Als Schwellenwert gilt 50. Liegt der Lightness-Wert **unter 50**, sollte
**Light** verwendet. Liegt der Lightness-Wert **über 50**, sollte **Dark**
verwendet.

Grundsätzlich gilt: Je weiter der Lightness-Wert vom Schwellenwert 50 entfernt
ist, desto größer ist in der Regel der erreichbare Kontrast. Werte deutlich
unter 50 verbessern den Kontrast mit Light, Werte deutlich über 50 verbessern
den Kontrast mit Dark.

Themes berücksichtigen

Bei der Verwendung von Light und Dark auf individuellen Hintergründen sollte
das Verhalten beim Theme-Wechsel bewusst gesteuert werden. Nutze dafür die
Colors Light Static und Dark Static.
Mehr zu Themes

## Light

Verwende die Light-Color, bei dunklen Hintergründen mit einem HSL Lightness-Wert
von weniger als 50.

| Token | Wert |
| --- | --- |
| `--color--white-alpha--100` | `rgb(255 255 255 / 12.5%)` |
| `--color--white-alpha--200` | `rgb(255 255 255 / 25%)` |
| `--color--white-alpha--300` | `rgb(255 255 255 / 37.5%)` |
| `--color--white-alpha--400` | `rgb(255 255 255 / 50%)` |
| `--color--white-alpha--500` | `rgb(255 255 255 / 62.5%)` |
| `--color--white-alpha--600` | `rgb(255 255 255 / 75%)` |
| `--color--white-alpha--700` | `rgb(255 255 255 / 87.5%)` |
| `--color--white-alpha--800` | `rgb(255 255 255 / 100%)` |

## Dark

Verwende die Dark-Color, bei hellen, farbigen Hintergründen mit einem HSL
Lightness-Wert von größer als 50.

| Token | Wert |
| --- | --- |
| `--color--black-alpha--100` | `rgb(0 0 0 / 12.5%)` |
| `--color--black-alpha--200` | `rgb(0 0 0 / 25%)` |
| `--color--black-alpha--300` | `rgb(0 0 0 / 37.5%)` |
| `--color--black-alpha--400` | `rgb(0 0 0 / 50%)` |
| `--color--black-alpha--500` | `rgb(0 0 0 / 62.5%)` |
| `--color--black-alpha--600` | `rgb(0 0 0 / 75%)` |
| `--color--black-alpha--700` | `rgb(0 0 0 / 87.5%)` |
| `--color--black-alpha--800` | `rgb(0 0 0 / 100%)` |

---

# Categorical Color

Categorical Colors eignen sich hervorragend, um Daten optisch in Kategorien zu
unterscheiden. Die Farben sind so optimiert, dass sie durch hohe Kontraste auch
für Menschen mit einer Farbsehschwäche gut unterscheidbar sind. Am besten
funktionieren sie in der hier gegebenen Reihenfolge.

**Achtung:** Categorical Colors sind ausschließlich für Datenvisualisierung
gedacht und heben sich bewusst von allen anderen Farben im Design System ab.
Darum sollten sie nicht für dekorative Zwecke oder andere UI-Elemente verwendet
werden.

| Token | Wert |
| --- | --- |
| `--color--categorical--sea-green` | `#0fb5ae` |
| `--color--categorical--palatinate-blue` | `#4046ca` |
| `--color--categorical--tangerine` | `#f68511` |
| `--color--categorical--magenta` | `#de3d82` |
| `--color--categorical--tropical-indigo` | `#7e84fa` |
| `--color--categorical--malachite` | `#72e06a` |
| `--color--categorical--azure` | `#147af3` |
| `--color--categorical--violet` | `#7326d3` |
| `--color--categorical--yellow` | `#e8c600` |
| `--color--categorical--alloy-orange` | `#cb5d00` |
| `--color--categorical--green` | `#008f5d` |
| `--color--categorical--lime` | `#bce931` |

---

# Themes

Themes definieren die visuelle Gestaltung einer Anwendung, ohne die zugrunde
liegende Struktur oder Semantik zu verändern.

Aktuell unterstützt Flow zwei Themes:

- Light
- Dark

Beide basieren auf denselben Design Tokens und Components. Ein Theme ist damit
kein separater Modus mit eigener Logik, sondern eine alternative Darstellung
derselben UI.

---

# Umgang mit Themes

Flow stellt die Grundlage für Themes bereit, übernimmt jedoch nicht automatisch
das Theme-Handling in der Anwendung.

Das Design System stellt bereit:

- Design Tokens für Light und Dark
- Components, die diese Tokens verwenden

Die Anwendung ist verantwortlich für:

- Festlegen des aktiven Themes
- Umschalten zwischen Themes
- Berücksichtigung der Browsereinstellung
- Speicherung der Nutzerpräferenz

---

# Individuelle Inhalte

Bei der Umsetzung sollte besonders auf Stellen geachtet werden, an denen nicht
ausschließlich Tokens verwendet werden, zum Beispiel:

- Custom Farben und Farbverläufe
- Bilder, Illustrationen oder Media Assets

Diese Inhalte reagieren nicht automatisch auf Theme-Wechsel und müssen bewusst
so gestaltet werden, dass sie in beiden Themes funktionieren.

In bestimmten Fällen ist es sinnvoll, dass einzelne UI-Elemente nicht auf einen
Theme-Wechsel reagieren. Zum Beispiel, wenn Components auf festen Hintergründen
wie Bildern oder Farbverläufen eingesetzt werden, die sich beim Wechsel des
Themes nicht verändern. Für solche Szenarien stellt Flow die Farben Light Static
und Dark Static bereit. Diese bleiben unabhängig vom aktiven Theme unverändert
und sorgen für konsistente Lesbarkeit.

Für die Verwendung von Light Static und Dark Static gelten die gleichen
Richtlinien wie für
[Light und Dark Colors](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

**ℹ️ Light Theme**

```tsx
import {
  AccentBox,
  Heading,
  LayoutCard,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<>
  <LayoutCard>
    <AccentBox
      color="dark-static"
      backgroundColor="#f6dfff"
    >
      <Section>
        <Heading>Nicht Static</Heading>
        <Text>Die Farben passen sich an das Theme an.</Text>
      </Section>
    </AccentBox>
  </LayoutCard>
  <LayoutCard>
    <AccentBox
      backgroundImage="https://flow.mittwald.de/assets/developer-tile.png"
      color="light-static"
    >
      <Section>
        <Heading>Static</Heading>
        <Text>
          Die Farben bleiben in Dark und Light Theme gleich.
        </Text>
      </Section>
    </AccentBox>
  </LayoutCard>
</>
```

**ℹ️ Dark Theme**

```tsx
import {
  AccentBox,
  Heading,
  LayoutCard,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<>
  <LayoutCard>
    <AccentBox
      color="light-static"
      backgroundColor="#5f0083"
    >
      <Section>
        <Heading>Nicht Static</Heading>
        <Text>Die Farben passen sich an das Theme an.</Text>
      </Section>
    </AccentBox>
  </LayoutCard>
  <LayoutCard>
    <AccentBox
      backgroundImage="https://flow.mittwald.de/assets/developer-tile.png"
      color="light-static"
    >
      <Section>
        <Heading>Static</Heading>
        <Text>
          Die Farben bleiben in Dark und Light Theme gleich.
        </Text>
      </Section>
    </AccentBox>
  </LayoutCard>
</>
```

---

# Technische Implementierung

Das Theme wird über das Attribut `data-theme` auf dem `:root`-Element gesteuert.
Verfügbare Werte sind:

- `light`
- `dark`
- `system`

Wird kein Theme gesetzt oder explizit `data-theme="system"` verwendet, dient die
bevorzugte Browsereinstellung des Nutzers als Grundlage für die Darstellung.

## @teispace/next-themes

Für die Verwaltung und das Umschalten des Themes kann @teispace/next-themes
verwendet werden. Die Bibliothek übernimmt dabei das Speichern des gewählten
Themes und das Setzen des `data-theme` Attributs.

### ThemeProvider

Der `ThemeProvider` wird in der Root der Anwendung eingebunden und steuert, wie
das Theme im DOM abgebildet wird:

```tsx
import { ThemeProvider } from "@teispace/next-themes";

<ThemeProvider attribute="data-theme">{children}</ThemeProvider>;
```

### Theme wechseln mit `useTheme`

Innerhalb von Client Components kann das Theme über den Hook `useTheme`
gesteuert werden:

```ts
import { useTheme } from "@teispace/next-themes";

const { theme, setTheme } = useTheme();
```

#### Verfügbare Werte:

- `theme` → aktuelles gesetztes Theme (`light`, `dark`, `system`)
- `setTheme("light" | "dark" | "system")` → wechselt das Theme

---

# States

States beschreiben den Zustand einer Komponente und ihre Reaktion auf
Interaktionen. Flow stellt die States für alle Komponenten bereit.

---

# Interaktions-States

Interaktions-States entstehen, wenn Nutzer mit einer Komponente interagieren.
Die Komponenten zeigen sie automatisch an.

## Default

Default ist der Ruhezustand einer Komponente, in dem keine Interaktion
stattfindet. Alle anderen States bauen visuell auf ihm auf.

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

<Button isReadOnly>Button</Button>
```

## Hover

Hover zeigt an, dass sich der Mauszeiger über einem interaktiven Element
befindet. Der State signalisiert, dass das Element bedienbar ist. Auf
Touch-Geräten gibt es keinen Hover, wichtige Informationen dürfen deshalb nie
nur im Hover sichtbar sein.

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

<Button
  isReadOnly
  style={{
    backgroundColor:
      "var(--button--primary-solid-background-color--hover)",
  }}
>
  Button
</Button>
```

## Pressed

Pressed zeigt an, dass ein Element gerade gedrückt wird. Das direkte Feedback
bestätigt dem Nutzer, dass seine Eingabe angekommen ist.

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

<Button
  isReadOnly
  style={{
    backgroundColor:
      "var(--button--primary-solid-background-color--pressed)",
    transform: "scale(0.97)",
  }}
>
  Button
</Button>
```

## Focus

Focus zeigt an, welches Element gerade per Tastatur angesteuert ist. Der
Focus-Ring erscheint nur bei der Bedienung mit der Tastatur und ist für Nutzer,
die ohne Maus navigieren, die wichtigste Orientierung. Der Focus darf deshalb
nie verloren gehen. Mehr dazu findest du unter
[Accessibility](https://flow.mittwald.de/foundations/design/accessibility).

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

<Button
  isReadOnly
  style={{
    outline:
      "var(--focus--outline-width) solid var(--focus--outline-color)",
    outlineOffset: "var(--focus--outline-offset)",
    boxShadow:
      "0 0 0 var(--focus--outline-width) var(--focus--secondary-outline-color)",
  }}
>
  Button
</Button>
```

## Selected

Selected zeigt an, dass eine Option ausgewählt oder aktiv ist. Typische
Komponenten sind [Checkbox](https://flow.mittwald.de/components/form-controls/checkbox),
[RadioGroup](https://flow.mittwald.de/components/form-controls/radio-group) und
[Tabs](https://flow.mittwald.de/components/structure/tabs).

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

<Checkbox defaultSelected isReadOnly>
  Newsletter abonnieren
</Checkbox>
```

---

# Component-States

Diese States werden über Properties gesetzt. Sie beschreiben, ob und wie eine
Komponente bedient werden kann.

## Disabled

Disabled zeigt an, dass ein Element aktuell nicht bedient werden kann. Der Wert
eines deaktivierten Felds wird beim Absenden eines Formulars nicht übermittelt.
Mache aus dem Kontext klar, warum das Element nicht zur Verfügung steht, damit
Nutzer wissen, was sie tun müssen. Neben dem
[Button](https://flow.mittwald.de/components/actions/button) lassen sich auch Eingabefelder wie
[TextField](https://flow.mittwald.de/components/form-controls/text-field) oder
[Checkbox](https://flow.mittwald.de/components/form-controls/checkbox) deaktivieren.

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

<Button isDisabled isReadOnly>
  Button
</Button>
```

## Read-only

Nur mit erkennbarem Kontext verwenden

Ein Read-only-Feld unterscheidet sich optisch nicht von einem bedienbaren
Feld. Aus dem Kontext muss deshalb klar hervorgehen, dass nichts bearbeitet
werden kann, zum Beispiel durch eine als Vorschau gekennzeichnete Ansicht.

Read-only zeigt einen Wert an, der relevant ist, aber nicht geändert werden
kann. Anders als bei Disabled bleibt der Wert gut lesbar, lässt sich markieren
und kopieren und wird mit dem Formular übermittelt. Typische Komponenten sind
[TextField](https://flow.mittwald.de/components/form-controls/text-field),
[Select](https://flow.mittwald.de/components/form-controls/select) und
[Rating](https://flow.mittwald.de/components/form-controls/rating).

```tsx
import {
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<TextField
  isReadOnly
  defaultValue="mein-projekt.example.com"
>
  <Label>Domain</Label>
</TextField>
```

## Invalid

Invalid zeigt an, dass eine Eingabe fehlerhaft ist. Kombiniere den State immer
mit einem `FieldError`, der erklärt, wie Nutzer den Fehler beheben. Wie du gute
Fehlermeldungen formulierst, erfährst du unter
[Fehlermeldungen](https://flow.mittwald.de/foundations/content-guidelines/fehlermeldungen).

```tsx
import {
  FieldError,
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<TextField isInvalid defaultValue="mein-projekt">
  <Label>Domain</Label>
  <FieldError>Gib eine gültige Domain ein.</FieldError>
</TextField>
```

## Required

Required kennzeichnet ein Pflichtfeld, das ausgefüllt werden muss, bevor ein
[Form](https://flow.mittwald.de/components/react-hook-form/form) abgeschickt werden kann. Flow
kennzeichnet dabei nicht die Pflichtfelder, sondern die optionalen: Ihr Label
erhält automatisch den Zusatz „(optional)“.

```tsx
import {
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<TextField isRequired isReadOnly>
  <Label>Projektname</Label>
</TextField>
```

## Indeterminate

Indeterminate zeigt an, dass nur ein Teil der untergeordneten Optionen
ausgewählt ist. Der State kommt vor allem bei einer
[Checkbox](https://flow.mittwald.de/components/form-controls/checkbox) zum Einsatz, die eine
[CheckboxGroup](https://flow.mittwald.de/components/form-controls/checkbox-group) oder die Auswahl in
einer Liste zusammenfasst.

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

<Checkbox isIndeterminate isReadOnly>
  Alle Projekte auswählen
</Checkbox>
```

## Pending, Succeeded und Failed

Diese States geben dem Nutzer Feedback zu einer Aktion, die im Hintergrund
läuft: Pending zeigt an, dass die Aktion läuft, Succeeded, dass sie erfolgreich
abgeschlossen wurde, und Failed, dass sie fehlgeschlagen ist. Steuere die States
über die [Action](https://flow.mittwald.de/components/actions/action)-Komponente. Sie setzt den
passenden State automatisch anhand des Verlaufs der Aktion.

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

<>
  <Button isPending isReadOnly>
    Button
  </Button>
  <Button isSucceeded isReadOnly>
    Button
  </Button>
  <Button isFailed isReadOnly>
    Button
  </Button>
</>
```

---

# Accessibility

Accessibility bedeutet, digitale Produkte so zu gestalten, dass möglichst viele
Menschen sie nutzen können. Dazu gehören Menschen mit dauerhaften
Einschränkungen ebenso wie Personen mit temporären oder situativen
Herausforderungen, etwa bei schlechter Beleuchtung oder mit nur einer freien
Hand. Gute Accessibility verbessert die Nutzung für **alle**.

Unser Design System Flow bildet dafür eine wichtige Grundlage. Die Components
bringen bereits zugängliche Interaktionen, eine sinnvolle Struktur und
unterstützende Attribute mit. Echte Accessibility entsteht jedoch erst im
Zusammenspiel mit der Umsetzung im Produkt. Flow unterstützt dich dabei, ersetzt
aber keine bewussten Entscheidungen in deinem Projekt.

Die Anforderungen der
[Web Content Accessibility Guidelines (WCAG) 2.2 AA](https://www.w3.org/TR/WCAG22/)
dienen Flow als Referenz für eine zugängliche Gestaltung. Sie fließen in
Components, Patterns und Grundlagen – wie beispielsweise Kontraste – ein und
werden kontinuierlich berücksichtigt und weiterentwickelt.

---

# Was Flow für dich übernimmt

Unsere Components sind so gestaltet, dass sie automatisch viele typische
Anforderungen an Accessibility erfüllen.

Dazu gehören zum Beispiel:

- ausreichende Kontraste
- Tastaturbedienbarkeit
- unterstützende ARIA-Attribute an geeigneten Stellen
- einheitliche Interaktionsmuster und Patterns

Wenn du die Components wie vorgesehen verwendest, hast du bereits eine solide
Grundlage für Accessibility.

---

# Was du selbst beachten solltest

Accessibility entsteht erst durch die richtige Verwendung der Components im
Produkt.

Beachte dabei einige Grundlagen:

- **Nutze semantisches HTML:** Verwende strukturelle Elemente wie `header`,
  `main` oder `footer`, um Bereiche einer Seite eindeutig zu kennzeichnen, statt
  generischer Container ohne Bedeutung.
- **Achte auf eine sinnvolle Struktur der Seite:** Überschriften sollten logisch
  aufgebaut sein und Inhalte klar gliedern.
- **Setze ARIA-Attribute bewusst ein:** ARIA ergänzt Semantik, ersetzt sie aber
  nicht.
- **Formuliere hilfreiche Alternativtexte für Bilder:** Alt-Texte sollten immer
  den Zweck eines Bildes beschreiben. Dekorative Bilder benötigen keinen
  Alternativtext.
- **Beschrifte interaktive Elemente verständlich:**
  [Links](https://flow.mittwald.de/components/navigation/link) und [Buttons](https://flow.mittwald.de/components/actions/button)
  sollten klar sagen, was passiert.
- **Prüfe Farbkontraste bei individuellen Anpassungen.**

---

# Mehr erfahren

Accessibility ist kein Zustand, den man einmal erreicht und dann abhaken kann.
Sie sollte während der Entwicklung regelmäßig geprüft und Schritt für Schritt
verbessert werden.

Flow und die zugehörige Dokumentation bieten dafür eine solide Grundlage und
helfen dir, viele Anforderungen frühzeitig zu berücksichtigen. Es lohnt sich
dennoch, sich zusätzlich mit den offiziellen Richtlinien vertraut zu machen.
Besonders hilfreich sind die
[WCAG 2.2 Guidelines](https://www.w3.org/TR/WCAG22/) sowie die
[ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/). Dort
findest du konkrete Best Practices, Beispiele für typische Interaktionsmuster
und weiterführende Empfehlungen für barrierearme Interfaces.

---

# Typography

Typography strukturiert den Inhaltsbereich, indem sie eine visuelle Hierarchie
schafft. Darüber hinaus erhöht eine gute Typography die Lesbarkeit und stärkt
die Marke im Erscheinungsbild.

---

Flow nutzt die Schriftfamilie **Inter**, die für Bildschirmdarstellung optimiert
ist und auch in kleinen Größen gut lesbar bleibt. Die einheitliche Verwendung
sorgt für ein ruhiges, konsistentes Erscheinungsbild.

Für Fließtexte wird **Regular**, für Überschriften und Hervorhebungen **Bold**
eingesetzt. Eine Zeilenhöhe (line height) von 150 Prozent zur Schriftgröße (font
size) verbessert die Lesbarkeit und unterstützt die Barrierefreiheit.
Abweichungen sind nur in Ausnahmefällen vorgesehen.

Alle Schriftgrößen werden in **REM** definiert. So bleiben Texte skalierbar,
reagieren auf Zoom und berücksichtigen individuelle Systemeinstellungen.

---

# Schriftgrößen und Hierarchie

Eine klare typografische Hierarchie hilft dabei, Inhalte strukturiert und
schnell erfassbar zu machen.

## Headings

[Headings](https://flow.mittwald.de/components/content/heading) strukturieren Inhalte und definieren
Abschnitte. Jede Stufe hat eine semantische Bedeutung und sollte entsprechend
eingesetzt werden. H1 ist die oberste inhaltliche Ebene einer Seite.

| Preview                                | REM       | Token                   |
| -------------------------------------- | --------- | ----------------------- |
| Heading 1 | 2.625 rem | `font-size-heading-xxl` |
| Heading 2 | 2 rem     | `font-size-heading-xl`  |
| Heading 3 | 1.5 rem   | `font-size-heading-l`   |
| Heading 4 | 1.25 rem  | `font-size-heading-m`   |
| Heading 5 | 1.125 rem | `font-size-heading-s`   |
| Heading 6 | 1 rem     | `font-size-heading-xs`  |

---

## Body

### Text

[Text](https://flow.mittwald.de/components/content/text) wird für Fließtexte, Beschreibungen und längere
Inhalte verwendet. Small eignet sich für unterstützende oder sekundäre
Informationen. Um Inhalte übersichtlich und schnell erfassbar zu gestalten,
lassen sich zentrale Informationen durch Bold gezielt hervorheben.

| Preview                                       | REM       | Token              |
| --------------------------------------------- | --------- | ------------------ |
| Text (Body)                                   | 1 rem     | `font-size-text-m` |
| <strong>Text (Body)</strong>                  | 1 rem     | `font-size-text-m` |
| <small>Text (Small)</small>                   | 0,875 rem | `font-size-text-s` |
| <small><strong>Text (Small)</strong> </small> | 0,875 rem | `font-size-text-s` |

### Links

[Links](https://flow.mittwald.de/components/navigation/link) werden je nach Kontext unterschiedlich
gekennzeichnet. Freistehende Verlinkungen sind visuell in Bold hervorgehoben,
während sie im Fließtext durch Unterstreichung kenntlich gemacht werden.

| Preview                             | REM   | Token              |
| ----------------------------------- | ----- | ------------------ |
| Link                   | 1 rem | `font-size-text-m` |
| [Link](https://flow.mittwald.de/components/navigation/link) | 1 rem | `font-size-text-m` |

### Code

Für eine technische Darstellung von Code wird die Schrift **Fira Code**
eingesetzt.

| Preview | REM       | Token              |
| ------- | --------- | ------------------ |
| `code`  | 0,875 rem | `font-size-text-s` |

---

# Layout

Das Layout organisiert die Benutzeroberfläche in einer logischen und
hierarchischen Struktur, um die Aufmerksamkeit des Users gezielt zu lenken.
Dabei werden Elemente wie Header, Navigation und Content-Bereich berücksichtigt.

---

# Best Practices

Ein Layout fügt verschiedene Elemente der Benutzeroberfläche zu einer logischen
Struktur zusammen. Die folgenden Punkte sind hilfreich, um ein gutes Layout zu
erstellen:

- Ein Layout sollte den Fokus immer auf die Aufgaben des Users legen.
- Ein konsistentes Layout hilft dem User, die Website schneller zu verstehen, da
  nicht ständig neue Layouts erlernt werden müssen.
- Der Fokus des Layouts sollte auf dem Content-Bereich liegen, da hier die
  Hauptaktionen des Users liegen. Achte hier besonders auf die strukturelle
  Hierarchie und die inhaltlichen Beziehungen des Contents.
- Ein Layout sollte immer responsiv sein, damit die Benutzeroberfläche auch auf
  kleineren Bildschirmen funktioniert. Im Layout ist grade das Zusammenspiel von
  Header, Side-Navigation und Content-Bereich für die Responsivität relevant.

---

# Genereller Aufbau

Grob lassen sich die meisten Layouts, die mit Flow erstellt werden können, in 4
Bereiche einteilen: **Header**, **Side-Navigation**, **Content** und
**Overlay**. Das Layout innerhalb dieser Bereiche wird durch verschiedene
Components und deren Komposition bestimmt. In unseren Components ist das
[Spacing](https://flow.mittwald.de/foundations/structure/spacing) bereits integriert.

Verschiedene Layouts mit Code zum Kopieren finden sich unter
[Code Templates](https://flow.mittwald.de/templates/app-shells/simple-app).

**ℹ️ Layout-Aufbau**

Grobes Layout einer Seite. Eingeteilt in Header-, Side-Navigation- und
Content-Bereich.

```tsx
export default () => {
  const area: React.CSSProperties = {
    display: "flex",
    alignItems: "center",
    justifyContent: "center",
    padding: "var(--size-px--xs)",
    backgroundColor:
      "var(--info-soft-background-color--default)",
    border: "1px dashed var(--info-soft-content-color)",
    borderRadius: "var(--corner-radius--s)",
  };

  const vertical: React.CSSProperties = {
    writingMode: "vertical-rl",
    transform: "rotate(180deg)",
  };

  const layout: React.CSSProperties = {
    alignSelf: "stretch",
    height: "280px",
    display: "grid",
    gridTemplateAreas: `
      'header header'
      'nav    content'
    `,
    gridTemplateColumns: "1fr 5fr",
    gridTemplateRows: "1fr 6fr",
    gap: "var(--size-px--s)",
    color: "var(--info-soft-content-color)",
    fontSize: "var(--font-size-text--s)",
  };

  return (
    <div style={layout}>
      <header style={{ ...area, gridArea: "header" }}>
        Header
      </header>
      <nav
        style={{ ...area, ...vertical, gridArea: "nav" }}
      >
        Side-Navigation
      </nav>
      <main style={{ ...area, gridArea: "content" }}>
        Content
      </main>
    </div>
  );
}
```

**mStudio Aufbau**

Grobes Layout des mStudios. Darstellung mit Primary und Secondary
Navigation.

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

export default () => {
  const area: React.CSSProperties = {
    display: "flex",
    alignItems: "center",
    justifyContent: "center",
    padding: "var(--size-px--xs)",
    backgroundColor:
      "var(--info-soft-background-color--default)",
    border: "1px dashed var(--info-soft-content-color)",
    borderRadius: "var(--corner-radius--s)",
  };

  const vertical: React.CSSProperties = {
    writingMode: "vertical-rl",
    transform: "rotate(180deg)",
  };

  const layout: React.CSSProperties = {
    alignSelf: "stretch",
    height: "280px",
    display: "grid",
    gridTemplateAreas: `
      'logo       header       header     header'
      'primaryNav secondaryNav breadcrumb breadcrumb'
      'primaryNav secondaryNav pageTitle  button'
      'primaryNav secondaryNav content    content'
    `,
    gridTemplateColumns: "1fr 2fr 12fr 3fr",
    gridTemplateRows: "auto auto auto 1fr",
    gap: "var(--size-px--s)",
    color: "var(--info-soft-content-color)",
    fontSize: "var(--font-size-text--s)",
  };

  return (
    <div style={layout}>
      <div style={{ ...area, gridArea: "logo" }}>
        <IconMittwald size="s" />
      </div>
      <header style={{ ...area, gridArea: "header" }}>
        Header
      </header>
      <nav
        style={{
          ...area,
          ...vertical,
          gridArea: "primaryNav",
        }}
      >
        Primary Navigation
      </nav>
      <nav
        style={{
          ...area,
          ...vertical,
          gridArea: "secondaryNav",
        }}
      >
        Secondary Navigation
      </nav>
      <div style={{ ...area, gridArea: "breadcrumb" }}>
        Breadcrumb
      </div>
      <div style={{ ...area, gridArea: "pageTitle" }}>
        Page Title
      </div>
      <div style={{ ...area, gridArea: "button" }}>
        Button
      </div>
      <main style={{ ...area, gridArea: "content" }}>
        Content
      </main>
    </div>
  );
}
```

## Header

Der Header-Bereich befindet sich im oberen Bereich des Layouts und ist auf jeder
Seite identisch. Er kann das Logo sowie eine
[HeaderNavigation](https://flow.mittwald.de/components/navigation/header-navigation) enthalten. Ein
Hauptbestandteil der HeaderNavigation sind primäre Navigationspunkte. Ergänzend
gibt es [Buttons](https://flow.mittwald.de/components/actions/button), die Overlays oder
[ContextMenus](https://flow.mittwald.de/components/actions/context-menu) öffnen, wie beispielsweise für
die Suche, das NotificationCenter oder das ProfilMenu. Im Header-Bereich sollten
ausschließlich wichtige Elemente angezeigt werden, die auf allen Seiten sichtbar
sein müssen.

## Side-Navigation

Die Side-Navigation befindet sich entweder direkt links neben dem
Content-Bereich oder fest am linken Bildschirmrand. Sie muss nicht nur aus einer
Navigation bestehen, sondern kann auch aus einer Primary und einer Secondary
Navigation bestehen.

Zum Aufbau einer Side-Navigation kann eine
[LayoutCard](https://flow.mittwald.de/components/structure/layout-card) mit der Component
[Navigation](https://flow.mittwald.de/components/navigation/navigation) gefüllt werden.

## Content

Der Content-Bereich stellt dem User Informationen zur Verfügung, damit er seine
Aufgabe erfüllen kann. Der Inhalt variiert von Seite zu Seite, es wird jedoch
empfohlen, den Inhalt nach einem wiederkehrenden Muster anzuordnen, das bereits
auf anderen Seiten verwendet wurde.

Die Navigationsstruktur im Content-Bereich folgt ebenfalls einem klaren Muster.
Im Content-Bereich können [Tabs](https://flow.mittwald.de/components/structure/tabs) und
[List](https://flow.mittwald.de/components/list/list) verwendet werden, um die Inhalte zu teilen oder in
die Tiefe zu navigieren. Bei der Navigation in tiefere Ebenen, z. B. über eine
List, bietet eine [Breadcrumb](https://flow.mittwald.de/components/navigation/breadcrumb) eine
Orientierungshilfe.

Der Content wird von einer [LayoutCard](https://flow.mittwald.de/components/structure/layout-card)
umschlossen. Um innerhalb der LayoutCard die richtigen Abstände in vertikaler
und horizontaler Richtung sicherzustellen, sollten die Layout-Components
[Section](https://flow.mittwald.de/components/structure/section) und
[ColumnLayout](https://flow.mittwald.de/components/structure/column-layout) verwendet werden. Ein
seitenweiter [Alert](https://flow.mittwald.de/components/status/alert#position-seitenweit) steht
ebenfalls in der LayoutCard, vor der ersten Section und nicht oberhalb der
LayoutCard.

## Overlay

Ein Overlay öffnet sich über der eigentlichen Seite. Größere Overlays wie
[Modals](https://flow.mittwald.de/components/overlays/modal) und [OffCanvas](https://flow.mittwald.de/components/overlays/modal)
erhalten zusätzlich einen Backdrop, damit sich der User besser auf den
angezeigten Inhalt konzentrieren kann. Andere, kleinere Overlays wie
[ContextMenu](https://flow.mittwald.de/components/actions/context-menu) oder
[Tooltip](https://flow.mittwald.de/components/overlays/tooltip) erhalten keinen Backdrop für die im
Hintergrund angezeigte Seite.

---

# Spacing

Spacing definiert die vertikalen und horizontalen Abstände zwischen Elementen
und sorgt so für ein harmonisches Layout.

---

# Grundlagen

Die Spacings und generell alle Größen in Flow basieren auf 8-Pixel-Schritten. Da
jedoch oft kleinere Spacings als 8px benötigt werden, stehen zusätzlich feinere
Abstufungen von 4px und 2px zur Verfügung. Standardmäßig folgen alle Components
den definierten Spacings. Für ein optimales Spacing – das Einfluss auf das
Layout hat – sollten die Components
[ColumnLayout](https://flow.mittwald.de/components/structure/column-layout) und
[Section](https://flow.mittwald.de/components/structure/section) verwendet werden.

---

# Best Practices

Um mit dem Spacing ein harmonisches Layout zu erschaffen, achte auf folgende
Punkte:

- Verwende die Layout-Components
  [ColumnLayout](https://flow.mittwald.de/components/structure/column-layout) und
  [Section](https://flow.mittwald.de/components/structure/section), um dadurch das richtige vertikale
  und horizontale Spacing zu erhalten.
- Spacing hilft bei der Gruppierung von Elementen auf Benutzeroberflächen. Je
  geringer das Spacing zwischen den Elementen ist, desto größer ist das Gefühl
  der Zusammengehörigkeit.
- Optisch kann es sinnvoll sein, das Spacing zwischen größeren Elementen größer
  und zwischen kleineren Elementen kleiner zu wählen.

**✅ Do**

Zwischen dem [Avatar](https://flow.mittwald.de/components/content/avatar) und dem Namen und
Untertitel ist ein Spacing von 8px definiert, da diese Größe ein gutes
Zusammengehörigkeitsgefühl vermittelt.

```tsx
import {
  Avatar,
  Content,
  Initials,
  Text,
} from "@mittwald/flow-react-components";

<Content
  style={{
    display: "grid",
    gridTemplateAreas: '"avatar title" "avatar subtitle"',
    gridTemplateColumns: "auto 1fr",
    alignItems: "center",
    columnGap: "8px",
    width: "max-content",
    marginLeft: "auto",
    marginRight: "auto",
  }}
>
  <div
    style={{
      gridArea: "avatar",
    }}
  >
    <Avatar>
      <Initials>Sven Fuchs</Initials>
    </Avatar>
  </div>
  <Text
    style={{
      gridArea: "title",
    }}
  >
    <b style={{ margin: 0 }}>Sven Fuchs</b>
  </Text>
  <Text
    style={{
      gridArea: "subtitle",
      fontSize: "14px",
    }}
  >
    Projektentwickler
  </Text>
</Content>
```

**⛔️ Don't**

Wenn das Spacing zu groß ist, fühlt sich der Avatar nicht mehr zum Namen und
Untertitel gehörig an.

```tsx
import {
  Avatar,
  Content,
  Initials,
  Text,
} from "@mittwald/flow-react-components";

<Content
  style={{
    display: "grid",
    gridTemplateAreas: '"avatar title" "avatar subtitle"',
    gridTemplateColumns: "auto 1fr",
    alignItems: "center",
    columnGap: "32px",
    width: "max-content",
    marginLeft: "auto",
    marginRight: "auto",
  }}
>
  <div
    style={{
      gridArea: "avatar",
    }}
  >
    <Avatar>
      <Initials>Sven Fuchs</Initials>
    </Avatar>
  </div>
  <Text
    style={{
      gridArea: "title",
    }}
  >
    <b style={{ margin: 0 }}>Sven Fuchs</b>
  </Text>
  <Text
    style={{
      gridArea: "subtitle",
      fontSize: "14px",
    }}
  >
    Projektentwickler
  </Text>
</Content>
```

---

# Spacing-Tabelle

Alle Spacings in der Tabelle können sowohl vertikal und horizontal verwendet
werden. Spacings werden in REM angegeben, wenn sie zwischen Elementen eingesetzt
werden, die ebenfalls in REM definiert sind. Dies ist zum Beispiel bei Text der
Fall, damit der Abstand beim Skalieren der Schriftgröße konsistent bleibt.
Zwischen zwei Elementen muss jedoch nicht zwingend ein Spacing verwendet werden,
da nicht immer ein Abstand erforderlich ist.

| Size  | Pixel | REM       | (Vertical) Visual                                                                                        |
| ----- | ----- | --------- | -------------------------------------------------------------------------------------------------------- |
| `xxs` | 2px   | 0,125 rem | <div style={{ backgroundColor: "#EBB6FF", width: "0.125rem", height: "1.5rem", borderRadius: "4px" }} /> |
| `xs`  | 4px   | 0,25 rem  | <div style={{ backgroundColor: "#EBB6FF", width: "0.25rem", height: "1.5rem", borderRadius: "4px" }} />  |
| `s`   | 8px   | 0,5 rem   | <div style={{ backgroundColor: "#EBB6FF", width: "0.5rem", height: "1.5rem", borderRadius: "4px" }} />   |
| `m`   | 16px  | 1 rem     | <div style={{ backgroundColor: "#EBB6FF", width: "1rem", height: "1.5rem", borderRadius: "4px" }} />     |
| `l`   | 24px  | 1,5 rem   | <div style={{ backgroundColor: "#EBB6FF", width: "1.5rem", height: "1.5rem", borderRadius: "4px" }} />   |
| `xl`  | 32px  | 2 rem     | <div style={{ backgroundColor: "#EBB6FF", width: "2rem", height: "1.5rem", borderRadius: "4px" }} />     |
| `xxl` | 64px  | 4 rem     | <div style={{ backgroundColor: "#EBB6FF", width: "4rem", height: "1.5rem", borderRadius: "4px" }} />     |

---

# Components

Flow unterstützt das Verschachteln von Components, um deine UI aufzubauen. Dies
ist eine kurze Dokumentation darüber, warum wir uns dafür entschieden haben.

---

Die folgenden Codebeispiele werden in der Erklärung referenziert.

```
// Flow
<Button aria-label="Notifications: 7">
  <IconNotification />
  <CounterBadge count={7} />
</Button>
```

vs.

```
// Not Flow
<IconButton label="Benachrichtigung" icon="Notification" counterBadge={7} />
```

---

# Logik

Components-Libraries basieren in der Regel darauf, Components zu verschachteln,
um größere Components zu bauen. Das ist ein weit verbreitetes und effektives
Pattern, das außerdem leicht verständlich ist. Genau deshalb unterstützen wir
dieses Modell auch in Flow. Wenn man zum Beispiel ein
[CounterBadge](https://flow.mittwald.de/components/status/counter-badge) innerhalb eines
[Buttons](https://flow.mittwald.de/components/actions/button) platziert, wird dieses automatisch oben
rechts positioniert – so, wie man es erwarten würde.

---

# Lesbarkeit

Wir haben unsere Frontend-Entwickler gefragt, was am Ende besser lesbar ist:

1. Unterkomponenten über Props zu übergeben, wie das
   [Icon](https://flow.mittwald.de/components/content/icon) im Beispiel
2. Das Icon als Child in die Component zu legen.

Wir haben uns für Variante 2 entschieden, da sie besonders bei mehreren
Unterkomponenten besser lesbar ist.

---

# Wiederverwendbarkeit

Entwickler bauen häufig eigene Components, um sie wiederzuverwenden oder um die
Implementierung aufzuteilen. Wenn es zum Beispiel bereits eine
`UnreadNotificationsCounter`-Component gibt, die den Zähler aus der API lädt und
in einem CounterBadge darstellt, kann diese einfach als Child im Button
verwendet werden.

```
<Button>
  <IconNotification />
  <UnreadNotificationsCounter />
</Button>
```

---

# Suspense- / ErrorBoundaries

Nur mit dem „Components-Ansatz“ ist es möglich, Child-Components in Loading-
oder ErrorBoundaries zu kapseln.

```
<Button>
  <IconNotification />
  <Suspense>
    <UnreadNotificationsCounter />
  </Suspense>
</Button>
```

---

# Aufgeblähtes Props-Interface

Wenn Components anfangen, Features anderer Components nativ zu unterstützen,
wird ihr Props-Interface schnell aufgebläht. Beim Beispiel `counterBadge={7}`
könnte man denken: „Hey, das ist doch nur ein Prop mehr und leicht
verständlich!“ Aber was ist, wenn CounterBadge mehr Eigenschaften als nur count
unterstützt? Jede unterstützte Eigenschaft müsste dann als
`counter[CounterProp]` im Button (und möglicherweise weiteren Parent-Components)
vorhanden sein.

Aufgeblähte Gesamtbibliothek vs. All-Mighty-Components

Wenn Flow für jeden Anwendungsfall spezielle Components anbieten würde, müsste
es z. B. einen `IconButton`, einen `CounterBadgeButton` und streng genommen
sogar einen `IconCounterBadgeButton` geben. Das würde schnell zu sehr vielen
Components führen.

Und was wäre, wenn man stattdessen alles direkt im Button unterstützt? Das führt
meist zu sehr großen „All-Mighty-Components“ ohne klaren Scope und mit
überladener Implementierung.

---

# Children in Unterkomponenten

Nur mit dem „Components-Ansatz“ ist es möglich, Children auch in
Unterkomponenten zu verwenden.

```
<Button aria-label="Notifications: 7">
  <Icon>
    <IconStar />
  </Icon>
  <CounterBadge count={7} />
</Button>
```

---

# Baue deine eigenen Components

Wenn du bestimmte Kombinationen von Components häufig in deiner UI verwendest,
kannst du dir einfach eigene Components mit genau den Props bauen, die du
benötigst.

---

# Navigation

Eine Navigation ist ein zentraler Baustein jeder Benutzeroberfläche. Sie hilft
Usern, Inhalte schnell und intuitiv zu finden. Sie verbindet verschiedene
Bereiche miteinander, macht Strukturen verständlich und unterstützt ein
konsistentes Nutzungserlebnis. Je nach Struktur und Komplexität einer Anwendung
kommen unterschiedliche Components zum Einsatz, die häufig sinnvoll miteinander
kombiniert werden.

---

# Best Practices

- **Komplexität reduzieren:** Gestalte Inhalte und Navigationen klar und
  verständlich. Eine reduzierte und konsistente Navigation verbessert die
  Orientierung und erleichtert die Nutzung.
- **Orientierung schaffen:** User sollten jederzeit erkennen können, wo sie sich
  befinden. Aktive Zustände, Breadcrumbs und die TabNavigation unterstützen
  dabei.
- **Suche integrieren:** Eine gut sichtbare Suche und Schnellzugriffe
  erleichtern besonders in komplexen Anwendungen den schnellen Zugriff auf
  Inhalte.
- **Konsistente Navigation:** Navigationsmuster und Positionierungen sollten
  innerhalb der gesamten Anwendung konsistent verwendet werden. Wiederkehrende
  Muster erleichtern das Verständnis und stärken die Orientierung.

---

# Navigationsstrukturen

Hauptnavigationen ermöglichen den Zugriff auf zentrale Bereiche einer Anwendung.
Ergänzende Navigationskomponenten innerhalb des Contents schaffen Orientierung,
erleichtern den Wechsel zwischen Ansichten und ermöglichen die Navigation auf
tieferer Ebene.

## Hauptnavigation

Es gibt zwei grundlegende Navigationsvarianten: HeaderNavigation und
SideNavigation. Welche eingesetzt wird, hängt vom Layout und der Komplexität der
Anwendung ab. Beachte hierbei die Best Practices der Navigationen.

```tsx
import {
  Avatar,
  Button,
  Flex,
  HeaderNavigation,
  Heading,
  IconSearch,
  Initials,
  Label,
  LayoutCard,
  Link,
  Navigation,
  NavigationGroup,
  IconDashboard,
  IconMonitoring,
  IconApp,
  IconContainer,
  Text,
  ColumnLayout,
} from "@mittwald/flow-react-components";

<Flex direction="column" rowGap="l">
  <Flex justify="end">
    <HeaderNavigation color="dark">
      <Link>Dashboard</Link>
      <Link aria-current="page">Projekt</Link>
      <Link>Server</Link>
      <Link>Organisation</Link>
      <Button aria-label="Suche">
        <IconSearch />
      </Button>
      <Button aria-label="Suche">
        <Avatar>
          <Initials>Max Mustermann</Initials>
        </Avatar>
      </Button>
    </HeaderNavigation>
  </Flex>
  <ColumnLayout l={[1, 3]} m={[1, 2]}>
    <LayoutCard>
      <Navigation>
        <Heading>Mein Projekt</Heading>
        <NavigationGroup>
          <Label>Allgemeines</Label>
          <Link aria-current="page">
            <IconDashboard />
            Dashboard
          </Link>
          <Link>
            <IconMonitoring />
            Monitoring
          </Link>
        </NavigationGroup>
        <NavigationGroup>
          <Label>Components</Label>
          <Link>
            <IconApp />
            Apps
          </Link>
          <Link>
            <IconContainer />
            Container
          </Link>
        </NavigationGroup>
      </Navigation>
    </LayoutCard>
    <LayoutCard>
      <Text>
        Lorem ipsum dolor sit amet consectetur adipisicing
        elit. Cumque eius quam quas vel voluptas, ullam
        aliquid fugit. Voluptate harum accusantium rerum
        ullam modi blanditiis vitae, laborum ea tempore,
        dolore voluptas. Earum pariatur, similique corrupti
        id officia perferendis. Labore, similique. Earum,
        quas in. At dolorem corrupti blanditiis nulla
        deserunt laborum! Corrupti delectus aspernatur nihil
        nulla obcaecati ipsam porro sequi rem? Quam.
      </Text>
    </LayoutCard>
  </ColumnLayout>
</Flex>
```

### HeaderNaviagtion

Die [HeaderNavigation](https://flow.mittwald.de/components/navigation/header-navigation), befindet sich
im oberen Bereich der Seite und eignet sich besonders für Hauptnavigationen mit
flacher Struktur und übersichtlicher Informationsarchitektur. Zusätzlich zu den
zentralen Navigationspunkten kann sie mit übergeordneten Funktionen ergänzt
werden, wie beispielsweise der Zugang zu einem Profil, eine globale Suche oder
globale Einstellungen.

### Navigation (SideNavigation)

Die [Navigation](https://flow.mittwald.de/components/navigation/navigation) ist vertikal angeordnet und
eignet sich besonders für Seitenlayouts mit viel Platz in der Breite oder für
Anwendungen mit komplexeren Strukturen. Sie bietet ausreichend Platz für viele
Menüpunkte sowie verschachtelte Navigations-Ebenen.

Im mStudio wird die SideNavigation aufgrund der komplexen
Informationsarchitektur sowohl für Hauptnavigationspunkte als auch für
untergeordnete Navigationspunkte genutzt und in einer
[LayoudCard](https://flow.mittwald.de/components/structure/layout-card) dargestellt.

---

## Content-Navigation

Die Components Breadcrumb, TabNavigation und List unterstützen bei der
Orientierung innerhalb des Contents und ermöglichen einen schnellen Wechsel
zwischen zusammengehörenden Bereichen oder das Navigieren in tiefere Ebenen.

```tsx
import {
  Flex,
  Breadcrumb,
  Link,
  Heading,
  LayoutCard,
  TabNavigation,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<Flex direction="column" gap="m">
  <Breadcrumb color="dark">
    <Link>Projekt</Link>
    <Link>E-Mails</Link>
    <Link>E-Mail-Adresse</Link>
  </Breadcrumb>
  <Heading level={1} color="dark">
    mail@meinprojekt.de
  </Heading>
  <LayoutCard>
    <TabNavigation aria-label="E-Mail-Navigation">
      <Link href="#" aria-current="page">
        E-Mail-Adressen
      </Link>
      <Link href="#">Postausgänge</Link>
      <Link href="#">Archivierung</Link>
    </TabNavigation>
    <Section>
      <Text>
        Lorem ipsum dolor sit amet consectetur adipisicing
        elit. Cumque eius quam quas vel voluptas, ullam
        aliquid fugit. Voluptate harum accusantium rerum
        ullam modi blanditiis vitae, laborum ea tempore,
        dolore voluptas. Earum pariatur, similique corrupti
        id officia perferendis. Labore, similique. Earum,
        quas in. At dolorem corrupti blanditiis nulla
        deserunt laborum! Corrupti delectus aspernatur nihil
        nulla obcaecati ipsam porro sequi rem? Quam.
      </Text>
    </Section>
  </LayoutCard>
</Flex>
```

### Breadcrumb

Die [Breadcrumb](https://flow.mittwald.de/components/navigation/breadcrumb) zeigt den aktuellen Pfad
innerhalb einer hierarchischen Struktur an. Sie unterstützt die Orientierung,
indem sie den Usern jederzeit verdeutlicht, wo sie sich befinden. Zusätzlich
erleichtert sie die Rücknavigation zu übergeordneten Ebenen und verbessert damit
die Navigierbarkeit komplexerer Anwendungen.

### TabNavigation

Die [TabNavigation](https://flow.mittwald.de/components/navigation/tab-navigation) ermöglicht das
Navigieren zwischen gleichrangigen Unterseiten. Durch ihre permanente
Sichtbarkeit behalten User den Überblick über die verfügbaren Bereiche und
erkennen am aktiven Zustand, wo sie sich gerade befinden. Reicht die verfügbare
Breite nicht aus, klappen überzählige Punkte automatisch in ein
[ContextMenu](https://flow.mittwald.de/components/actions/context-menu) zusammen.

### Listen, Raster und Tabellen

Die verschiedenen Darstellungen einer [List](https://flow.mittwald.de/components/list/list)
strukturieren Inhalte, schaffen Übersicht über ähnliche Elemente und ermöglichen
die Navigation zu detaillierteren Ansichten.

---

## Ergänzende Navigation

Klassische Navigationen können durch Verlinkungen, eine globale Suche oder
automatische Weiterleitungen ergänzt werden. Gerade in komplexen Anwendungen
möchten User schnell zu bestimmten Inhalten gelangen, ohne sich durch die
gesamte Navigationsstruktur bewegen zu müssen. Ergänzende Navigationskomponenten
ersetzen die Hauptnavigation nicht, sondern erweitern sie gezielt.

### Links

[Links](https://flow.mittwald.de/components/navigation/link) ermöglichen den direkten Wechsel in einen
anderen Bereich der Anwendung oder zu externen Inhalten. User können dabei
selbst entscheiden, ob sie dem Wechsel folgen wollen. Daher sollten Links klar
und aussagekräftig benannt sein, damit erkennbar ist, welches Ziel sie haben.

### Suche

Die [Suche](https://flow.mittwald.de/components/form-controls/search-field) ermöglicht den direkten
Zugriff auf Inhalte, Funktionen oder Bereiche, ohne mehrere Navigationsebenen
durchlaufen zu müssen. Besonders in komplexen Anwendungen mit vielen Inhalten
unterstützt sie User dabei, Informationen effizient und zielgerichtet zu finden.

### Weiterleitungen

Weiterleitungen führen User automatisch oder systemgesteuert zu einer anderen
Ansicht oder einem anderen Bereich der Anwendung. Sie sollten bewusst und
nachvollziehbar eingesetzt werden, da unerwartete Wechsel schnell zu
Orientierungsverlust führen können.

---

# Accessibility

Eine barrierefreie Navigation stellt sicher, dass alle User die Anwendung
zuverlässig bedienen können.

- **Semantische Struktur und ARIA-Rollen:** Verwende semantisch korrekte
  HTML-Elemente und ergänze diese bei Bedarf durch passende ARIA-Rollen und
  -Attribute. Dadurch können Screenreader Navigationsbereiche korrekt
  interpretieren und vermitteln.
- **Fokus-Reihenfolge und Tastaturbedienung:** Navigations-Elemente müssen
  vollständig per Tastatur erreichbar und bedienbar sein. Die Fokus-Reihenfolge
  sollte logisch aufgebaut sein und der visuellen Struktur folgen.
- **Verständliche Bezeichnungen:** Navigationspunkte sollten eindeutig benannt
  sein und verständlich kommunizieren, wohin sie führen. Dadurch wird die
  Orientierung zusätzlich verbessert.

---

# Sprach-Guide

Dieser Guide beschreibt, wie wir bei mittwald schreiben. Er gilt für alle Texte
im mStudio. Für Extensions ist er eine Hilfe, damit die Texte zu unserem Produkt
passen. Du findest hier Leitlinien für deine Texte und einen Glossar mit den
Begriffen, die bei mittwald eine eigene Bedeutung haben.

---

# Wie wir sprechen

## Technisch und verständlich

Wir überzeugen mit Inhalten, nicht mit langen und verschachtelten Erklärungen.
Kurze Sätze und einfacher Satzbau halten unsere Texte übersichtlich. Wir drücken
uns technisch, aber verständlich aus, genau mit der technischen Tiefe, die dem
Nutzer weiterhilft.

## Konsistent

Für Aktionen wie Bestellen und Kündigen oder Anlegen und Löschen legen wir feste
Begriffspaare fest. Verwende dafür die Begriffe aus unseren
[Leitlinien](#leitlinien) und dem [Glossar](#glossar). So erleben unsere Nutzer
überall dieselbe Sprache.

---

# Leitlinien

## Aktive Sprache

Wir agieren aktiv. Das zeigen wir auch in unserer Sprache. Passiv ist in
Ordnung, wenn ein System handelt oder der Handelnde keine Rolle spielt, z. B.
bei automatischen Vorgängen: „Nach 7 Tagen wird dein Server gelöscht.“

**✅ Do**

Du hast den Server gelöscht.

**⛔️ Don't**

Der Server wurde von dir gelöscht.

## Sie, Du oder Ihr

Wir sprechen Nutzer mit „Du“ an und im Singular. In Mailings und Tickets
schreiben wir „Du“, „Dein“ und „Deiner“ groß. Im mStudio schreiben wir „du“,
„dein“ und „deiner“ klein, weil die Texte eher Anleitungscharakter haben.

**✅ Do**

Du hast dein Projekt angelegt.

**⛔️ Don't**

Ihr habt euer Projekt angelegt.

## Kurze Sätze

Fass dich kurz. Um Technisches einfach zu formulieren, helfen kurze Sätze.
Faustregel: Satzlänge maximal 1,5 Zeilen. 1 Subjekt pro Satz.

## Klare Gliederung

Dein Text sollte durch Absätze gegliedert sein. Im besten Fall sind diese nicht
länger als 5 Zeilen. Auch Nummerierungen oder Bulletpoints helfen den Lesern,
deinem Text besser zu folgen und Wichtiges schneller wahrzunehmen.

## Wichtige Aspekte hervorheben

Fette zentrale Begriffe, um Wichtiges in den Vordergrund zu stellen. Beschränke
dich dabei auf einzelne Wörter. Ganze Sätze (oder gar Absätze) werden nicht
gefettet.

## KEIN! GRUND! ZU! SCHREIEN!!!

Wir schreiben ohne Versalien und ohne Ausrufezeichen. Ausnahmen sind etablierte
Abkürzungen wie „DSGVO“ und „PHP“ sowie Eigennamen, die selbst ein
Ausrufezeichen enthalten, z. B. „Joomla!“.

## Bindestrich: Wörter koppeln

Zweisprachige Wortkombinationen werden mit einem Bindestrich gekoppelt.
Englische Begriffe werden nicht gekoppelt, deutsche Kombinationen werden
zusammengeschrieben.

**✅ Do**

Ein Tarif-Upgrade kommt selten allein. Erst recht im Cloud Hosting.

**⛔️ Don't**

Ein Tarif Upgrade allein macht noch keinen Sommer. Auch nicht im
Cloud-Hosting.

Akronyme werden mit einem Bindestrich gekoppelt, z. B. „DSGVO-konform“.

Egal ob mittwald Hosting oder mStudio Login: Die Regel ist immer dieselbe.
mittwald und Produktnamen werden niemals mit einem Bindestrich an ein anderes
Wort gekoppelt.

Generell gilt: Im Zweifel für die Lesbarkeit. Macht die korrekte Schreibweise
Probleme (sieht schlecht aus, Umbruch, usw.), missachten wir die Regeln. Das
sollte aber nur die Ausnahme sein.

## mittwald, mStudio und vServer werden IMMER kleingeschrieben

... auch am Satzanfang.

## Gendern

mittwald lebt Gleichberechtigung. Um kurz und prägnant formulieren zu können,
gendern wir jedoch nur dort, wo es Sinn macht, z. B. in Stellenanzeigen.

An Orten mit wenig Platz, etwa im mStudio oder auf Social Media, verwenden wir
die meist verwendete Schreibweise.

## Zahlen

Um die Lesbarkeit zu steigern, schreiben wir alle Zahlen als Ziffern, auch von 0
bis 12.

Im UX-Writing gibt es davon eine Ausnahme: Ist die Zahl für den Nutzer nicht
besonders relevant und gibt keine konkrete Information wieder, kann sie
ausgeschrieben werden.

**✅ Do**

Nur noch ein Schritt bis zum Abschluss.

**⛔️ Don't**

Nur noch 1 Schritt bis zum Abschluss.

Ist die Zahl dagegen eine wichtige Information, bleibt sie eine Ziffer, z. B.
„Nach 7 Tagen wird dein Server gelöscht.“

## Speicherplatzangaben in binären Einheiten

Wir geben Speichergrößen bewusst in binären Einheiten wie KiB, MiB oder GiB an.
Diese folgen dem binären System, z. B. 1 GiB = 1.073.741.824 Bytes = 1024³
Bytes. Dadurch stellen wir technische Genauigkeit sicher und vermeiden
Verwirrung durch uneinheitliche Umrechnungen, wie sie bei dezimalen Angaben
(z. B. KB, MB, GB) häufig auftreten.

## Preise und Umsatzsteuer

Wir geben Preise immer mit dem Hinweis „zzgl. USt.“ an. Die Abkürzung „USt.“
verwenden wir nur dort. Im Text schreiben wir „Umsatzsteuer“, nicht
„Mehrwertsteuer“.

## Abkürzungen

Wir schreiben „inkl.“ in der deutschen Schreibweise und mit Punkt.

## Englischsprachige Inhalte

Deutsch bildet die Grundlage unserer Kommunikation. Für englische Texte
verwenden wir amerikanisches Englisch (US English).

Das betrifft insbesondere Rechtschreibung, Fachbegriffe und UI-Texte. US English
entspricht in der Tech-Welt dem etablierten Standard.

**✅ Do**

color, behavior, organization

**⛔️ Don't**

colour, behaviour, organisation

## Nutzer, nicht Kunde

Im Produkt sprechen wir von „Nutzern“. Den Begriff „Kunde“ verwenden wir nicht.
Wer mit uns einen Vertrag hat, ist ein „Vertragspartner“ (siehe Glossar).

## Technische Fachbegriffe

Etablierte technische Fachbegriffe übersetzen wir nicht, sondern lassen sie
englisch, z. B. „SSH-User“. „Nutzer“ gilt für Personen, die das Produkt nutzen.
Bezeichnet „User“ dagegen ein technisches Konto, bleibt es „User“.

**✅ Do**

Lege einen Cronjob an.

**⛔️ Don't**

Lege eine zeitgesteuerte Aufgabe an.

## AI und KI

Im Kontext von AI Hosting schreiben wir „AI“. Sonst kann „KI“ im Fließtext
verwendet werden.

## Gegenstücke für Aktionen

Wir nennen die Aktion und ihr Gegenstück konsistent: Wer etwas **installiert**,
kann es **deinstallieren**. Wer ein Verb für den Anfang einer Aktion wählt,
nimmt für ihre Umkehrung das passende Gegenstück.

Für die häufigsten Verben legen wir die Paare fest:

| Aktion       | Gegenstück     | Wann                                                        |
| ------------ | -------------- | ----------------------------------------------------------- |
| Anlegen      | Löschen        | Ein Objekt wird von Grund auf erstellt, die Daten sind weg. |
| Hinzufügen   | Entfernen      | Ein bestehendes Objekt wird zugeordnet oder wieder gelöst.  |
| Bestellen    | Kündigen       | Eine kostenpflichtige Bestellung wird beendet.              |
| Installieren | Deinstallieren | Gilt nur für Software, z. B. Apps und Systemsoftware.       |
| Einladen     | Ausladen       | Gilt für Personen, die Zugriff erhalten.                    |

Alle anderen Verben folgen demselben Prinzip, ohne dass sie hier stehen.

---

# Glossar

Dieser Glossar erklärt Begriffe, die im Produkt eine eigene Bedeutung haben und
ohne Definition missverstanden werden könnten. Regeln zur Wortwahl stehen in den
Leitlinien.

- **Artikel:** Alle kostenpflichtigen Produkte, z. B. Domains, die hinzubestellt
  werden.
- **Organisation:** Der Vertrags- und Abrechnungsrahmen. Hier werden
  Zahlungsinformationen und Vertragspartnerdaten hinterlegt.
- **Projekt:** Bündelt alles, was für den Betrieb einer Website oder
  Webanwendung nötig ist, z. B. Apps, Domains, Datenbanken und
  E-Mail-Postfächer.
- **Ressourcen:** Die Rechenleistung und der Speicherplatz, die ein Server oder
  Projekt zur Verfügung hat: vCPU, RAM und Speicherplatz.
- **Server:** Stellt Ressourcen bereit, die sich mehrere Projekte teilen.
- **Umsatzsteuer:** Die Steuer auf unsere Preise. Wir sagen „Umsatzsteuer“,
  nicht „Mehrwertsteuer“.
- **Vertragspartner:** Eine natürliche oder juristische Person, die mit uns
  einen Vertrag abgeschlossen hat. Das ist nicht zwangsläufig ein Nutzer.

---

# Informationskonzept

Das Informationskonzept beschreibt, wie der User im mStudio über alle relevanten
Informationen informiert wird – sowohl durch selbst initiierte Aktionen als auch
durch systemseitig ausgelöste Ereignisse. Dazu zählen laufende und
abgeschlossene Prozesse sowie wichtige Systemmeldungen (z. B. „Speicherplatz ist
voll“). Es definiert, wie Feedback zu Prozessen gegeben wird und wie
Benachrichtigungen gestaltet sind.

---

# Status

Das Informationskonzept unterscheidet verschiedene Status. Jeder Status folgt
dabei einem definierten Kombination aus [Color](https://flow.mittwald.de/foundations/design/colors)- und
[Icon](https://flow.mittwald.de/components/content/icon#icon-bibliothek), um eine eindeutige und
schnelle Erkennung zu ermöglichen.

Wenn zwei Status inhaltlich miteinander konkurrieren, wird immer der
handlungsentscheidende angezeigt. Zum Beispiel überschreibt ein Danger stets
Warning und Info.

| Status                                                    | Einsatz                                                      | Beispiel                                                                                                                                     |
| --------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Info               | Sachliche Hinweise/Informationen ohne akuten Handlungsbedarf | - Update verfügbar<br />- Download wird vorbereitet<br />- Kündigung vorgemerkt<br />- Neue Nachricht im Ticket<br />- Aktive Anlegeprozesse |
| Warning         | Handlungsempfehlung oder Hinweis möglicher Konflikt          | - Speicherplatz fast voll<br />- E-Mail Versand gesperrt<br />- Domain unverifiziert<br />- Zertifikat konnte nicht ausgestellt werden       |
| Danger           | Kritisches Problem, das sofortiges Handeln erfordert         | - Speicherplatz voll<br />- E-Mail Empfang deaktiviert<br />- Webserver/Cronjobs deaktiviert                                                 |
| Success         | Erfolgreich abgeschlossene Ereignisse                        | - Erfolgreich installiert<br />- Erfolgreich angelegt<br />- Erfolgreich erstellt<br />- Domain verifiziert                                  |
| Unavailable | Nicht verfügbare Elemente                                    | - Fehlende Berechtigungen<br />- Gelöschtes Objekt                                                                                           |

---

# Alert

Ein [Alert](https://flow.mittwald.de/components/status/alert) wird dort eingesetzt, wo unmittelbare
Aufmerksamkeit erforderlich ist – etwa bei Systemfehlern oder wichtigen
Systeminformationen. Er übermittelt die Information in wenigen Sätzen und gibt,
wenn möglich, eine Handlungsempfehlung. Diese kann mithilfe eines
[Links](https://flow.mittwald.de/components/navigation/link) oder eines
[Buttons](https://flow.mittwald.de/components/actions/button) unterstützt werden. Alerts sollten stets
in der Nähe des betroffenen Inhalts platziert werden (s.
[Alert: Position](https://flow.mittwald.de/components/status/alert#position)). Ein seitenweiter Alert
steht in der
[LayoutCard](https://flow.mittwald.de/components/structure/layout-card#kombiniere-mit-alert) vor der
ersten Section und nicht oberhalb der LayoutCard.

```tsx
import {
  Alert,
  Heading,
  Text,
  Content,
  Button,
  Link,
} from "@mittwald/flow-react-components";

<>
  <Alert>
    <Heading>E-Mail-Adresse wurde archiviert</Heading>
    <Content>
      <Text>
        Da deine Domain gelöscht wurde, wurde diese
        E-Mail-Adresse archiviert. Um E-Mails empfangen und
        senden zu können musst du die Adresse wieder
        umbenennen.
      </Text>
    </Content>
  </Alert>

  <Alert status="warning">
    <Heading>Dein Speicher ist fast voll</Heading>
    <Content>
      <Text>
        Dein Speicher ist zu über 80% belegt. Wir empfehlen
        dir deinen Speicherplatz zu erweitern, um Problemen
        vorzubeugen.
      </Text>
      <Button>Speicherplatz anpassen</Button>
    </Content>
  </Alert>

  <Alert status="danger">
    <Heading>
      Es konnte kein SSL-Zertifikat ausgestellt werden
    </Heading>
    <Content>
      <Text>
        Für diese Domain konnte kein SSL-Zertifikat
        ausgestellt werden, da die Domain per IP nicht auf
        deine Server-IP zeigt.
      </Text>
    </Content>
  </Alert>

  <Alert status="success">
    <Heading>App aktualisiert</Heading>
    <Content>
      <Text>
        Deine App wurde erfolgreich auf die neueste Version
        aktualisiert.
      </Text>
      <Link>Mehr Informationen zur aktuellen Version</Link>
    </Content>
  </Alert>

  <Alert status="unavailable">
    <Heading>Inhalte nicht gefunden</Heading>
    <Content>
      <Text>
        Die gewünschten Inhalte sind leider nicht verfügbar.
        Entweder wurden sie inzwischen gelöscht oder dir
        fehlen die notwendigen Berechtigungen.
      </Text>
    </Content>
  </Alert>
</>
```

---

# AlertBadge

Eine [AlertBadge](https://flow.mittwald.de/components/status/alert-badge) dient dazu, den Status eines
Elements schnell sichtbar zu machen, beispielsweise in
[Headings](https://flow.mittwald.de/components/content/heading) oder
[List](https://flow.mittwald.de/components/list/list)-Einträgen. In vielen Fällen wird sie durch einen
[Alert](https://flow.mittwald.de/components/status/alert) ergänzt, etwa auf der
[Detailseite](https://flow.mittwald.de/templates/seiten/detailseite), um zusätzliche Informationen
bereitzustellen. Für Metadaten oder ergänzende Informationen ist hingegen die
[Badge](https://flow.mittwald.de/components/status/badge) besser geeignet (siehe
[AlertBadge vs. Badge](https://flow.mittwald.de/components/status/alert-badge#best-practices-alertbadge-vs-badge)).

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

<>
  <AlertBadge>Update verfügbar</AlertBadge>

  <AlertBadge status="warning">
    Speicherplatz fast voll
  </AlertBadge>

  <AlertBadge status="danger">
    Speicherplatz voll
  </AlertBadge>

  <AlertBadge status="success">Verifiziert</AlertBadge>

  <AlertBadge status="unavailable">
    Nicht gefunden
  </AlertBadge>
</>
```

---

# Notifications

[Notifications](https://flow.mittwald.de/components/status/notification) informieren über wichtige
System- oder Statusmeldungen und erscheinen kurz im Bildschirm des Users. So
stellen sie sicher, dass User über einen Status informiert werden, auch wenn sie
sich gerade nicht auf der betroffenen
[Detailseite](https://flow.mittwald.de/templates/seiten/detailseite) befinden. Notifications sollten
bewusst und sparsam eingesetzt werden. Denn zu viele Notifications überfluten
den User und lenken von wirklich wichtigen Informationen ab.

Notifications werden durch den
[NotificationsProvider](https://flow.mittwald.de/components/status/notification-provider) ausgelöst. Da
Notifications in der Regel nur kurz sichtbar sind, sollten sie an einem
zentralen Ort gesammelt werden, damit ungelesene Notifications auch zu einem
späteren Zeitpunkt eingesehen werden können. Kritische Probleme sollten
zusätzlich zur Notification per E-Mail kommuniziert werden. So wird
sichergestellt, dass der User die Informationen zuverlässig erhält.

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

<>
  <Notification>
    <Heading>E-Mail-Adresse archiviert</Heading>
    <Text>
      Die E-Mail-Adresse <b>example@mittwald.de</b> wurde
      archiviert.
    </Text>
  </Notification>

  <Notification status="warning">
    <Heading>Speicher fast voll</Heading>
    <Text>
      Der Speicherplatz im Projekt <b>My Project</b> ist zu
      80% voll.
    </Text>
  </Notification>

  <Notification status="danger">
    <Heading>Kein SSL-Zertifikat</Heading>
    <Text>
      Für <b>exmaple.de</b> konnte kein SSL-Zertifikat
      ausgestellt werden.
    </Text>
  </Notification>

  <Notification status="success">
    <Heading>App installiert</Heading>
    <Text>
      Deine App <b>My WordPress</b> wurde erfolgreich
      installiert.
    </Text>
  </Notification>

  <Notification status="unavailable">
    <Heading>Nicht gefunden</Heading>
    <Text>
      Die gewünschten Inhalte sind leider nicht verfügbar.
    </Text>
  </Notification>
</>
```

---

# Status-Icon

Einzelne [Status-Icons](https://flow.mittwald.de/components/content/icon#icon-bibliothek) können den
User auf versteckte Status-Informtionen aufmerksam machen. Zum Beispiel zeigt
ein Status-Icon innerhalb von einem [Tab](https://flow.mittwald.de/components/structure/tabs) an, dass
in diesem ein relevanter Status vorliegt. Der Status kann dann im Tab z. B. mit
Hilfe eines [Alerts](https://flow.mittwald.de/components/status/alert) erläutert werden.

```tsx
import {
  Tabs,
  Tab,
  TabTitle,
  AlertIcon,
} from "@mittwald/flow-react-components";

<Tabs>
  <Tab>
    <TabTitle>Tab</TabTitle>
    Tab Content
  </Tab>
  <Tab>
    <TabTitle>
      Tab
      <AlertIcon />
    </TabTitle>
    Tab Content
  </Tab>
  <Tab>
    <TabTitle>Tab</TabTitle>
    Tab Content
  </Tab>
</Tabs>
```

---

# Fehlermeldungen

Der beste Fehler ist der, der gar nicht erst auftritt. Klare Strukturen,
verständliche Beschriftungen und sinnvolle Defaults helfen, Fehlbedienungen zu
vermeiden. Lassen sich Fehler nicht verhindern, entscheiden zwei Dinge darüber,
ob Nutzer weiterkommen: wo und mit welcher Komponente der Fehler erscheint und
wie er formuliert ist.

---

# Best Practices

- Vermeide Fehler schon im Design, zum Beispiel durch klare Beschriftungen und
  sinnvolle Defaults.
- Zeige Fehler dort, wo sie entstehen oder wo der erwartete Inhalt wäre.
- Nenne eine Lösung oder biete einen Ausweg an, zum Beispiel "Erneut laden".
- Wähle die Darstellung passend zum Umfang des Fehlers.
- Bleibe sachlich: keine Schuldzuweisungen und keine Entschuldigungen.
- Formuliere kurz und positiv. Das hilft Nutzern, schnell zu handeln.

---

# Fehlermeldungen anzeigen

## Beim Laden von Inhalten

Beim Laden können Fehler auftreten, zum Beispiel wenn ein Service nicht
erreichbar ist oder ein Timeout entsteht. Beende in diesem Fall den Ladezustand,
damit Nutzer sehen, dass sie nicht weiter warten müssen.

Die Fehlermeldung erscheint dort, wo der erwartete Inhalt wäre. Für größere
Bereiche wie [LayoutCards](https://flow.mittwald.de/components/structure/layout-card) oder
[Sections](https://flow.mittwald.de/components/structure/section) eignet sich eine
[IllustratedMessage](https://flow.mittwald.de/components/content/illustrated-message) mit
`status="danger"`. Sie zeigt deutlich, dass der Inhalt aktuell nicht verfügbar
ist, und bietet idealerweise eine Handlung an, zum Beispiel einen
[Button](https://flow.mittwald.de/components/actions/button) mit der Beschriftung "Erneut laden".

```tsx
import {
  Flex,
  Heading,
  IconDanger,
  IllustratedMessage,
  LayoutCard,
  Text,
} from "@mittwald/flow-react-components";

export default () => {
  return (
    <Flex direction="column" gap="m">
      <Heading level={1} color="dark">
        Mein Projekt
      </Heading>

      <LayoutCard>
        <IllustratedMessage color="danger">
          <IconDanger />
          <Heading>Fehler beim Laden von Daten</Heading>
          <Text>
            Dieser Bereich konnte nicht geladen werden. Wir
            arbeiten daran das Problem zu beheben. Bitte
            habe etwas Geduld und probiere es später noch
            einmal.
          </Text>
        </IllustratedMessage>
      </LayoutCard>
    </Flex>
  );
}
```

Für kleinere, abgegrenzte Elemente wie Tabellen- oder Listenzeilen eignet sich
ein [AlertText](https://flow.mittwald.de/components/status/alert-text). So bleibt der Kontext erhalten
und der Fehler betrifft nicht die ganze [Table](https://flow.mittwald.de/components/structure/table)
oder [List](https://flow.mittwald.de/components/list/list).

```tsx
import {
  AlertText,
  Avatar,
  Content,
  Flex,
  Heading,
  IconDomain,
  LayoutCard,
  ListItemView,
  Text,
  typedList,
} from "@mittwald/flow-react-components";

export default () => {
  const DomainList = typedList<{
    id: string;
    domain: string;

    target?: string;
  }>();

  return (
    <Flex direction="column" gap="m">
      <Heading level={1} color="dark">
        Domains
      </Heading>
      <LayoutCard>
        <DomainList.List
          aria-label="Domains"
          getItemId={(domain) => domain.id}
          loadingItemsCount={3}
        >
          <DomainList.StaticData
            data={[
              {
                id: "1",
                domain: "mjaofd6.project.space",
              },
              {
                id: "2",
                domain: "formel1.de",
                target: "Mein WordPress",
              },
              {
                id: "3",
                domain: "schumi-fanclub.de",
                target: "/home/xyz/ordner/tollerpfad",
              },
            ]}
          />
          <DomainList.Search />
          <DomainList.Item
            textValue={(domain) => domain.domain}
          >
            {(domain) => (
              <ListItemView>
                <Avatar>
                  <IconDomain />
                </Avatar>
                <Heading>{domain.domain}</Heading>
                <Text>
                  {domain.target ? (
                    domain.target
                  ) : (
                    <AlertText status="danger">
                      Fehler beim Laden
                    </AlertText>
                  )}
                </Text>

                <Content>
                  <small></small>
                </Content>
              </ListItemView>
            )}
          </DomainList.Item>
        </DomainList.List>
      </LayoutCard>
    </Flex>
  );
}
```

Um Fehler auf kleine Bereiche zu begrenzen, nutzen wir im mStudio Loading und
Error Boundaries. Sie kapseln technische Fehler ab und sorgen für konsistentes
Feedback.

## Bei ungültigen Eingaben

Zeige das Feedback direkt am Form Control, damit Nutzer sofort erkennen, was sie
anpassen müssen. Details stehen unter
[Formular (Mit Validierung)](https://flow.mittwald.de/templates/bausteine/formular#varianten-und-abwandlung-mit-validierung).

## Bei fehlgeschlagenen Aktionen

Aktionen, die einen Request an das Backend senden, können aus technischen
Gründen, wegen Kommunikationsproblemen oder fehlender Berechtigungen
fehlschlagen. Dafür eignet sich ein [Modal](https://flow.mittwald.de/components/overlays/modal) mit
einer [IllustratedMessage](https://flow.mittwald.de/components/content/illustrated-message) mit
`status="danger"`. Sie erklärt kurz den Grund, sofern er für Nutzer relevant
ist, und bietet einen Ausweg an, zum Beispiel die Aktion erneut auszuführen.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  Content,
  Flex,
  Heading,
  IconDanger,
  IconProject,
  IllustratedMessage,
  LayoutCard,
  Modal,
  Text,
  useModalController,
} from "@mittwald/flow-react-components";

export default () => {
  const controller = useModalController();

  return (
    <Flex direction="column" gap="m">
      <Heading level={1} color="dark">
        Projekte
      </Heading>

      <LayoutCard>
        <IllustratedMessage>
          <IconProject />
          <Heading>Erstes Projekt anlegen</Heading>
          <Text>
            Du hast noch keine Projekte angelegt! Lege ein
            Projekt an und schon kannst du mit dem
            Entwickeln loslegen.
          </Text>
          <Action
            onAction={() => {
              controller.open();
            }}
          >
            <Button>Projekt anlegen</Button>
          </Action>
        </IllustratedMessage>
        <Modal controller={controller}>
          <Content>
            <IllustratedMessage color="danger">
              <IconDanger />
              <Heading>
                Fehler beim Ausführen der Aktion
              </Heading>
              <Text>
                Die Aktion konnte nicht ausgeführt werden.
                Wir arbeiten daran das Problem zu beheben.
                Bitte habe etwas Geduld und probiere es
                später noch einmal.
              </Text>
            </IllustratedMessage>
          </Content>
          <ActionGroup>
            <Action closeModal>
              <Button
                slot="abort"
                variant="soft"
                color="secondary"
              >
                Schließen
              </Button>
            </Action>
          </ActionGroup>
        </Modal>
      </LayoutCard>
    </Flex>
  );
}
```

Schlägt eine Aktion erst später fehl, nachdem sie zunächst erfolgreich an das
Backend übermittelt wurde, eignen sich
[Notifications](https://flow.mittwald.de/components/status/notification) besser. Ein typisches Beispiel
ist das Registrieren einer Domain. Mehr dazu steht im
[Informationskonzept](https://flow.mittwald.de/foundations/content-guidelines/informationskonzept).

---

# Fehlermeldungen formulieren

Die allgemeinen Regeln zu Anrede und Satzlänge stehen im
[Sprach-Guide](https://flow.mittwald.de/foundations/content-guidelines/sprach-guide). Dort steht auch,
dass eine passive Schreibweise in Ordnung ist, wenn ein System handelt. Das
trifft bei Fehlermeldungen oft zu. Für sie gilt zusätzlich:

## Kurz formulieren und Lösung nennen

Schreibe so kurz wie möglich, aber so lang wie nötig. Oft reicht es, nur die
Lösung zu nennen. Gibt es mehrere mögliche Ursachen, beschreibe, wie sich die
wahrscheinlichste beheben lässt.

**✅ Do**

**⛔️ Don't**

Wir unterstützen die Formatierung nicht. Gib eine E-Mail-Adresse im Format
name@domain.de ein.

## Schuldzuweisungen vermeiden

Beschreibe, was passiert ist, und nicht, was der Nutzer falsch gemacht hat. Ein
Fehler ist an sich schon frustrierend.

**✅ Do**

Das Bild konnte nicht hochgeladen werden. Wähle eine Datei bis 10 MB.

**⛔️ Don't**

Du hast ein ungültiges Bild hochgeladen. Wähle eine Datei bis 10 MB.

## Nicht entschuldigen

Formuliere Fehlermeldungen sachlich und fachlich. Entschuldigungen lenken vom
Wesentlichen ab und lassen Fehler größer wirken.

**✅ Do**

Die Eingabe konnte nicht gespeichert werden. Versuche es erneut.

**⛔️ Don't**

Es tut uns leid, wir konnten deine Eingabe nicht speichern. Versuche es erneut.

## Positiv formulieren

Konzentriere dich auf die Lösung und darauf, was als Nächstes möglich ist.
Verzichte nach Möglichkeit auf negativ besetzte Begriffe wie Fehler, Problem,
fehlgeschlagen, falsch oder ungültig. Bei Systemfehlern ohne direkte Lösung
gelingt das nicht immer.

**⛔️ Don't**

Durch ein Problem mit dem Server ist die Verbindung fehlgeschlagen.

## Allgemein formulieren

Formuliere eher allgemein als zu spezifisch. Details wie Dateinamen oder Ordner
finden Nutzer meist an anderer Stelle in der Oberfläche.

**✅ Do**

Die Datei konnte nicht hochgeladen werden. Verwende eine Datei vom Typ XY.

**⛔️ Don't**

Die Datei „example_file-20.4.24.xy“ konnte nicht hochgeladen werden. Verwende
eine Datei vom Typ XY.

---

# Focus Task

**focus-task.tsx**

```tsx
import {
  Button,
  Flex,
  Heading,
  Label,
  LayoutCard,
  Link,
  Section,
  Text,
  TextField,
} from "@mittwald/flow-react-components";
import styles from "./focus-task.module.css";

export default () => (
  <Flex
    justify="center"
    align="center"
    paddingBlock="l"
    paddingInline="xl"
    className={styles.page}
  >
    <Flex
      elementType="main"
      direction="column"
      align="stretch"
      gap="l"
      className={styles.center}
    >
      <span
        className={styles.logo}
        role="img"
        aria-label="mittwald"
      />
      <LayoutCard>
        <Section>
          <Heading>Login</Heading>
          <TextField type="email" isRequired>
            <Label>E-Mail-Adresse</Label>
          </TextField>
          <TextField type="password" isRequired>
            <Label>Passwort</Label>
          </TextField>
          <Flex
            align="center"
            justify="space-between"
            wrap="wrap"
            gap="m"
          >
            <Link href="#">Passwort vergessen</Link>
            <Button>Anmelden</Button>
          </Flex>
          <Text className={styles.registerLine}>
            Du hast noch keinen Nutzer?{" "}
            <Link href="#">Registrieren</Link>
          </Text>
        </Section>
      </LayoutCard>
      <Flex justify="center" wrap="wrap" gap="l">
        <Link href="#" target="_blank" color="dark">
          Datenschutz
        </Link>
        <Link href="#" target="_blank" color="dark">
          Impressum
        </Link>
      </Flex>
    </Flex>
  </Flex>
)
```

**focus-task.module.css**

```css
.page {
  /* Container-relative here; use 100dvh in a real full-page app. */
  height: 100%;
  background: var(--texture--grain), var(--color--background-gradient);
  background-blend-mode: overlay, normal;
}

.center {
  width: 100%;
  max-width: 30rem;
}

/*
 * The wordmark rides on `currentColor` through a CSS mask, so it follows the
 * theme (dark on light, light on dark). Swap the masked SVG for your own logo.
 */
.logo {
  align-self: center;
  width: 18rem;
  max-width: 100%;
  aspect-ratio: 300 / 57;
  background: currentcolor;
  mask: url("./mittwald.svg") no-repeat center / contain;
  -webkit-mask: url("./mittwald.svg") no-repeat center / contain;
}

.registerLine {
  text-align: end;
}

/* The generous page padding is too much for a narrow screen. */
@media (max-width: 768px) {
  .page {
    padding-inline: var(--size-px--m);
  }
}
```

---

# Verwendung

Ein Focus Task ist eine einzelne Seite ohne umgebende Navigation. Verwende ihn
für einen klar abgegrenzten Vorgang wie Registrierung, Anmeldung, Konfiguration
oder Bestellung. Ohne Navigation bleibt der Nutzer auf die eine Aufgabe
konzentriert und schließt sie zielgerichtet ab.

---

# Aufbau

- **Content** – Die Aufgabe liegt in einer
  [LayoutCard](https://flow.mittwald.de/components/structure/layout-card): Eingaben und Aktionen stehen
  direkt darin, ohne umgebende Navigation.
- **Footer** – Hier lassen sich [Links](https://flow.mittwald.de/components/navigation/link) platzieren,
  etwa Verweise auf Datenschutz oder Impressum.

---

# Varianten und Abwandlung

## Konfigurations-Aufgabe

Auch eine mehrteilige Aufgabe bleibt ein Focus Task, solange sie ohne Navigation
auf ein Ziel führt. Über die [ActionGroup](https://flow.mittwald.de/components/actions/action-group)
gelangt der Nutzer zum jeweils nächsten Schritt.

**focus-task-bestellung.tsx**

```tsx
import {
  Badge,
  Button,
  ColumnLayout,
  Content,
  Flex,
  Heading,
  Label,
  LayoutCard,
  Link,
  RadioButton,
  RadioGroup,
  Section,
  Table,
  TableBody,
  TableCell,
  TableColumn,
  TableFooterRow,
  TableHeader,
  TableRow,
  Text,
  TextField,
} from "@mittwald/flow-react-components";
import styles from "./focus-task-bestellung.module.css";

export default () => (
  <Flex
    justify="center"
    padding="xl"
    className={styles.page}
  >
    <Flex
      elementType="main"
      direction="column"
      align="stretch"
      gap="l"
      className={styles.center}
    >
      <span
        className={styles.logo}
        role="img"
        aria-label="mittwald"
      />
      <Heading level={1}>Bestellung</Heading>

      <ColumnLayout l={[2, 1]}>
        <LayoutCard>
          <Section>
            <Heading>Individuell konfigurieren</Heading>
            <Text>
              Passe deinen Tarif ganz einfach an deine
              Bedürfnisse an. Wähle Ressourcen und
              Speicherplatz so, wie du sie wirklich
              brauchst, und stelle dir deinen passenden
              Tarif zusammen.
            </Text>

            <Heading level={3}>Ressourcen</Heading>
            <Text>
              Die Ressourcen aus vCPU und RAM bestimmen die
              Leistung deines Tarifs. Du kannst sie
              jederzeit nach der Buchung anpassen.
            </Text>
            <RadioGroup
              defaultValue="rec"
              aria-label="Ressourcen"
              l={[1, 1, 1]}
            >
              <RadioButton value="small">
                <Text>1 vCPU</Text>
                <Content>1 GiB RAM</Content>
              </RadioButton>
              <RadioButton value="rec">
                <Flex
                  align="center"
                  gap="s"
                  className={styles.resourceTitle}
                >
                  <Text>1 vCPU</Text>
                  <Badge color="blue">Empfehlung</Badge>
                </Flex>
                <Content>2 GiB RAM</Content>
              </RadioButton>
              <RadioButton value="large">
                <Text>2 vCPU</Text>
                <Content>4 GiB RAM</Content>
              </RadioButton>
            </RadioGroup>

            <Heading level={3}>Speicherplatz</Heading>
            <Text>
              Der Speicherplatz umfasst Datenbanken,
              Backups, Webspace und E-Mails aller Projekte
              auf deinem Tarif.
            </Text>
            <RadioGroup
              defaultValue="40"
              aria-label="Speicherplatz"
              l={[1, 1, 1]}
            >
              <RadioButton value="20">20 GiB</RadioButton>
              <RadioButton value="40">40 GiB</RadioButton>
              <RadioButton value="60">60 GiB</RadioButton>
              <RadioButton value="80">80 GiB</RadioButton>
              <RadioButton value="100">100 GiB</RadioButton>
              <RadioButton value="custom">
                Individuell
              </RadioButton>
            </RadioGroup>

            <Flex
              align="center"
              justify="space-between"
              wrap="wrap"
              gap="m"
            >
              <Button variant="soft" color="secondary">
                Abbrechen
              </Button>
              <Flex
                wrap="wrap"
                gap="m"
                className={styles.actionsRight}
              >
                <Button variant="soft" color="secondary">
                  Zurück
                </Button>
                <Button>Weiter</Button>
              </Flex>
            </Flex>
          </Section>
        </LayoutCard>

        <LayoutCard>
          <Section>
            <Heading>Kostenübersicht</Heading>
            <Table aria-label="Kostenübersicht">
              <TableHeader>
                <TableColumn>Artikel</TableColumn>
                <TableColumn horizontalAlign="end">
                  Monatliche Kosten
                </TableColumn>
              </TableHeader>
              <TableBody>
                <TableRow>
                  <TableCell>1 vCPU / 2 GiB RAM</TableCell>
                  <TableCell horizontalAlign="end">
                    17,00 €
                  </TableCell>
                </TableRow>
                <TableRow>
                  <TableCell>40 GiB Speicher</TableCell>
                  <TableCell horizontalAlign="end">
                    2,00 €
                  </TableCell>
                </TableRow>
                <TableRow>
                  <TableCell>Aktionsrabatt</TableCell>
                  <TableCell horizontalAlign="end">
                    -5,00 €
                  </TableCell>
                </TableRow>
                <TableFooterRow>
                  <TableCell>Gesamt</TableCell>
                  <TableCell horizontalAlign="end">
                    14,00 €
                  </TableCell>
                </TableFooterRow>
              </TableBody>
            </Table>

            <Flex align="end" gap="m">
              <TextField>
                <Label>Gutscheincode</Label>
              </TextField>
              <Button variant="soft" color="secondary">
                Einlösen
              </Button>
            </Flex>
          </Section>
        </LayoutCard>
      </ColumnLayout>

      <Flex justify="center" wrap="wrap" gap="l">
        <Link href="#" target="_blank" color="dark">
          Datenschutz
        </Link>
        <Link href="#" target="_blank" color="dark">
          Impressum
        </Link>
      </Flex>
    </Flex>
  </Flex>
)
```

**focus-task-bestellung.module.css**

```css
.page {
  /* Container-relative here; use 100dvh in a real full-page app. */
  min-height: 100%;
  background: var(--texture--grain), var(--color--background-gradient);
  background-blend-mode: overlay, normal;
}

.center {
  width: 100%;
  max-width: 84rem;
}

/*
 * The wordmark rides on `currentColor` through a CSS mask, so it follows the
 * theme. Swap the masked SVG for your own logo.
 */
.logo {
  align-self: flex-start;
  width: 12rem;
  max-width: 100%;
  aspect-ratio: 300 / 57;
  background: currentcolor;
  mask: url("./mittwald.svg") no-repeat center / contain;
  -webkit-mask: url("./mittwald.svg") no-repeat center / contain;
}

/*
 * The RadioButton lays its slots out on a grid ("icon label" / ". content").
 * A raw child lands in the wrong cell, so the title row claims the label area.
 */
.resourceTitle {
  grid-area: label;
}

.actionsRight {
  margin-inline-start: auto;
}

/* The generous page padding is too much for a narrow screen. */
@media (max-width: 768px) {
  .page {
    padding-inline: var(--size-px--m);
  }
}
```

---

# Simple App

**simple-app.tsx**

```tsx
import {
  ActionGroup,
  Avatar,
  Button,
  CartesianChart,
  ChartGrid,
  ChartLegend,
  ChartTooltip,
  ColumnLayout,
  Combine,
  Content,
  ContextMenu,
  ContextMenuTrigger,
  CounterBadge,
  DonutChart,
  Flex,
  Header,
  HeaderNavigation,
  Heading,
  Icon,
  IconLogout,
  IconMenu,
  IconNotification,
  IconSettings,
  Initials,
  LayoutCard,
  Line,
  Link,
  MenuItem,
  Message,
  MessageThread,
  Modal,
  ModalTrigger,
  Navigation,
  Rating,
  Section,
  Text,
  XAxis,
  YAxis,
} from "@mittwald/flow-react-components";
import {
  IconTrendingDown,
  IconTrendingUp,
} from "@tabler/icons-react";
import styles from "./simple-app.module.css";

const contracts = [
  {
    month: "Jan",
    Webhosting: 33,
    vServer: 72,
    "Dedicated Server": 52,
  },
  {
    month: "Feb",
    Webhosting: 52,
    vServer: 84,
    "Dedicated Server": 80,
  },
  {
    month: "Mär",
    Webhosting: 62,
    vServer: 83,
    "Dedicated Server": 98,
  },
  {
    month: "Apr",
    Webhosting: 24,
    vServer: 63,
    "Dedicated Server": 42,
  },
  {
    month: "Mai",
    Webhosting: 70,
    vServer: 78,
    "Dedicated Server": 50,
  },
  {
    month: "Jun",
    Webhosting: 96,
    vServer: 88,
    "Dedicated Server": 54,
  },
  {
    month: "Jul",
    Webhosting: 146,
    vServer: 98,
    "Dedicated Server": 56,
  },
  {
    month: "Aug",
    Webhosting: 132,
    vServer: 85,
    "Dedicated Server": 90,
  },
  {
    month: "Sep",
    Webhosting: 114,
    vServer: 82,
    "Dedicated Server": 148,
  },
  {
    month: "Okt",
    Webhosting: 18,
    vServer: 42,
    "Dedicated Server": 120,
  },
  {
    month: "Nov",
    Webhosting: 48,
    vServer: 70,
    "Dedicated Server": 98,
  },
  {
    month: "Dez",
    Webhosting: 68,
    vServer: 110,
    "Dedicated Server": 126,
  },
];

export default () => (
  <Flex direction="column" className={styles.app}>
    <header className={styles.header}>
      <Flex
        align="center"
        wrap="wrap"
        gap="m"
        className={styles.headerContent}
      >
        <span
          className={styles.logo}
          role="img"
          aria-label="mittwald"
        />
        <HeaderNavigation
          aria-label="Hauptnavigation"
          className={styles.nav}
        >
          <GlobalNavigationLinks />
          <NotificationButton />
          <ContextMenuTrigger>
            <Button aria-label="Konto">
              <Avatar>
                <Initials>Max Mustermann</Initials>
              </Avatar>
            </Button>
            <ContextMenu>
              <MenuItem>
                <IconSettings />
                <Text>Profil</Text>
              </MenuItem>
              <MenuItem>
                <IconLogout />
                <Text>Abmelden</Text>
              </MenuItem>
            </ContextMenu>
          </ContextMenuTrigger>
        </HeaderNavigation>
        <HeaderNavigation className={styles.mobileActions}>
          <NotificationButton />
          <MobileMenu />
        </HeaderNavigation>
      </Flex>
    </header>

    <Flex
      direction="column"
      gap="l"
      grow
      className={styles.content}
    >
      <Flex elementType="main" direction="column" gap="l">
        {/* The active area is already named in the navigation, so the page
            heading is only exposed to assistive technology. */}
        <Heading
          level={1}
          className={styles.visuallyHidden}
        >
          Dashboard
        </Heading>

        <ColumnLayout l={[1, 1]} m={[1]}>
          <ColumnLayout l={[1]} m={[1]}>
            <LayoutCard>
              <Section>
                <Heading>Neuverträge</Heading>
                <CartesianChart
                  data={contracts}
                  height="18rem"
                >
                  <Line
                    dataKey="Webhosting"
                    color="sea-green"
                  />
                  <Line
                    dataKey="vServer"
                    color="palatinate-blue"
                  />
                  <Line
                    dataKey="Dedicated Server"
                    color="tangerine"
                  />
                  <XAxis dataKey="month" />
                  <YAxis domain={[0, 200]} />
                  <ChartGrid />
                  <ChartLegend />
                  <ChartTooltip />
                </CartesianChart>
              </Section>
            </LayoutCard>

            <ColumnLayout l={[1, 1]} m={[1, 1]}>
              <LayoutCard>
                <Flex
                  direction="column"
                  align="center"
                  gap="xs"
                  className={styles.stat}
                >
                  <Icon size="l" color="success">
                    <IconTrendingUp />
                  </Icon>
                  <span className={styles.statValue}>
                    + 2.000 €
                  </span>
                  <Text className={styles.statLabel}>
                    Vertragsbestand (30 Tage)
                  </Text>
                </Flex>
              </LayoutCard>
              <LayoutCard>
                <Flex
                  direction="column"
                  align="center"
                  gap="xs"
                  className={styles.stat}
                >
                  <Icon size="l" color="danger">
                    <IconTrendingDown />
                  </Icon>
                  <span className={styles.statValue}>
                    40
                  </span>
                  <Text className={styles.statLabel}>
                    Neuverträge (30 Tage)
                  </Text>
                </Flex>
              </LayoutCard>
            </ColumnLayout>

            <LayoutCard>
              <Section>
                <Heading>Vertragszusammensetzung</Heading>
                <DonutChart
                  aria-label="Vertragszusammensetzung"
                  size="l"
                  legendPosition="bottom"
                  maxValue={1200}
                  formatOptions={{ style: "decimal" }}
                  segments={[
                    {
                      title: "Webhosting",
                      value: 700,
                      color: "sea-green",
                    },
                    {
                      title: "vServer",
                      value: 300,
                      color: "palatinate-blue",
                    },
                    {
                      title: "Dedicated Server",
                      value: 200,
                      color: "tangerine",
                    },
                  ]}
                >
                  <strong>1,2 K</strong>
                </DonutChart>
              </Section>
            </LayoutCard>
          </ColumnLayout>

          <LayoutCard>
            <Section>
              <Heading>Letzte Kundenfeedbacks</Heading>
              <MessageThread>
                <Feedback
                  name="Lena Brinkmann"
                  date="13.09.24, 10:40"
                  rating={5}
                  text="Der Umzug meiner drei WordPress-Seiten lief völlig reibungslos. Der Support hat sogar proaktiv nachgefragt, ob alles passt – klare Empfehlung."
                />
                <Feedback
                  name="Jonas Weber"
                  date="12.09.24, 16:12"
                  rating={5}
                  text="Performance ist top und das Backup-Handling hat mir bei einem eigenen Fehler den Tag gerettet. So stelle ich mir Hosting vor."
                />
                <Feedback
                  name="Miriam Kessler"
                  date="11.09.24, 09:03"
                  rating={3}
                  text="Technisch stark, aber die Ersteinrichtung war für mich als Umsteiger etwas zäh. Mit dem Support ging es dann zügig."
                />
                <Feedback
                  name="Tobias Reinhardt"
                  date="10.09.24, 14:27"
                  rating={4}
                  text="Faires Preis-Leistungs-Verhältnis und schnelle Reaktionszeiten. Das mStudio könnte an ein, zwei Stellen noch aufgeräumter sein."
                />
              </MessageThread>
            </Section>
          </LayoutCard>
        </ColumnLayout>
      </Flex>

      <Flex
        elementType="footer"
        justify="center"
        wrap="wrap"
        gap="l"
        className={styles.footer}
      >
        <Link href="#" target="_blank" color="dark">
          Datenschutz
        </Link>
        <Link href="#" target="_blank" color="dark">
          Impressum
        </Link>
      </Flex>
    </Flex>
  </Flex>
);

/*
 * The bell keeps its place next to the burger: a pending notification is worth
 * seeing without opening the menu first.
 */
const NotificationButton = () => (
  <Button aria-label="Benachrichtigungen">
    <IconNotification />
    <CounterBadge count={2} />
  </Button>
);

/*
 * The navigation links, shared by the top bar and the off-canvas. Each renders
 * them through its own props context, so the same Links read as a header bar
 * in one and as a navigation list in the other.
 */
const GlobalNavigationLinks = () => (
  <>
    <Link href="#" aria-current="page">
      Dashboard
    </Link>
    <Link href="#">Kündigungen</Link>
    <Link href="#">Vertragsbestand</Link>
  </>
);

/*
 * On a narrow screen the top bar has no room for the navigation, so it moves
 * in here. The burger is then the shell's only navigation control.
 */
const MobileMenu = () => (
  <ModalTrigger>
    <Button aria-label="Menü öffnen">
      <IconMenu />
    </Button>
    <Modal offCanvas showCloseButton>
      <Heading>Menü</Heading>
      <Content>
        <Navigation aria-label="Hauptnavigation">
          <GlobalNavigationLinks />
        </Navigation>
      </Content>
      <ActionGroup>
        <Button variant="soft" color="secondary">
          <IconLogout />
          <Text>Abmelden</Text>
        </Button>
      </ActionGroup>
    </Modal>
  </ModalTrigger>
);

interface FeedbackProps {
  name: string;
  date: string;
  rating: number;
  text: string;
}

const Feedback = ({
  name,
  date,
  rating,
  text,
}: FeedbackProps) => (
  <Message>
    <Header>
      <Combine>
        <Avatar>
          <Initials>{name}</Initials>
        </Avatar>
        <Text>
          <strong>{name}</strong>
        </Text>
      </Combine>
      <Text>{date}</Text>
    </Header>
    <Content>
      <Flex direction="column" gap="xs">
        <Rating
          value={rating}
          isReadOnly
          size="s"
          aria-label={`Bewertung: ${rating} von 5 Sternen`}
        />
        <Text>{text}</Text>
      </Flex>
    </Content>
  </Message>
)
```

**simple-app.module.css**

```css
.app {
  /* Header and content share one maximum width, so their edges line up. */
  --page-width: 1800px;

  /* The header's tint is mixed from the gradient's first stop. */
  --header-ground: var(--neutral--color--200);

  /* Container-relative here; use 100dvh in a real full-page app. */
  min-height: 100%;
  background: var(--texture--grain), var(--color--background-gradient);
  background-blend-mode: overlay, normal;
}

/*
 * The header stays at the top while the page scrolls beneath it. Its tint is
 * translucent and blurred, so the navigation stays legible above the content.
 */
.header {
  position: sticky;
  top: 0;
  z-index: 1;
  padding-block: var(--size-px--m);
  background-color: color-mix(in srgb, var(--header-ground) 40%, transparent);
  backdrop-filter: blur(var(--blur));
}

.headerContent {
  max-width: var(--page-width);
  margin-inline: auto;
  padding-inline: var(--size-px--xl);
}

.content {
  width: 100%;
  max-width: var(--page-width);
  margin-inline: auto;
  padding-block: var(--size-px--s) var(--size-px--l);
  padding-inline: var(--size-px--xl);
}

/*
 * The wordmark rides on `currentColor` through a CSS mask, so it follows the
 * theme. Swap the masked SVG for your own logo.
 */
.logo {
  width: 9rem;
  max-width: 100%;
  aspect-ratio: 300 / 57;
  background: currentcolor;
  mask: url("./mittwald.svg") no-repeat center / contain;
  -webkit-mask: url("./mittwald.svg") no-repeat center / contain;
}

/* The navigation is pushed to the far end of the top bar. */
.nav {
  margin-inline-start: auto;
}

/* The bell and the burger take that place once the navigation gives it up. */
.mobileActions {
  margin-inline-start: auto;
}

/* Keeps the heading in the accessibility tree while hiding it visually. */
.visuallyHidden {
  position: absolute;
  width: 1px;
  height: 1px;
  margin: -1px;
  padding: 0;
  overflow: hidden;
  clip-path: inset(50%);
  white-space: nowrap;
  border: 0;
}

/* A single metric: trend icon, the value, and its caption. */
.stat {
  text-align: center;
}

.statValue {
  font-size: 1.75rem;
  font-weight: var(--font-weight--bold, 700);
}

.statLabel {
  font-weight: var(--font-weight--medium);
}

.footer {
  margin-block-start: auto;
}

/*
 * Below this width the top bar has no room for the navigation, so it hands its
 * links to the off-canvas behind the burger.
 */
@media (max-width: 768px) {
  .nav {
    display: none;
  }

  .headerContent,
  .content {
    padding-inline: var(--size-px--m);
  }
}

@media (min-width: 769px) {
  .mobileActions {
    display: none;
  }
}

@media (prefers-contrast: more), (prefers-reduced-transparency) {
  .header {
    background-color: var(--header-ground);
    backdrop-filter: none;
  }
}

/* The dark gradient starts darker than the neutral token. */
[data-theme="dark"] .app {
  --header-ground: #121518;
}
```

---

# Verwendung

Eine Simple App führt wenige gleichrangige Bereiche unter einer einzigen,
flachen Navigationsebene zusammen. Verwende sie für ein überschaubares Werkzeug,
dessen Bereiche alle auf einer Ebene liegen. Die flache Struktur macht jeden
Bereich mit einem Klick erreichbar. Sobald eine zweite Navigationsebene nötig
wird, ist es eine [Complex App](https://flow.mittwald.de/templates/app-shells/complex-app).

---

# Aufbau

- **Header** – Eine [HeaderNavigation](https://flow.mittwald.de/components/navigation/header-navigation)
  bildet die einzige, flache Navigationsebene über die gleichrangigen Bereiche
  und bietet Raum für bereichsübergreifende Funktionen wie eine Suche oder die
  Profilverwaltung. Er bleibt beim Scrollen oben stehen, der Inhalt läuft
  darunter durch.
- **Content** – Der Inhalt ist auf eine maximale Breite begrenzt und wird in der
  Regel in [LayoutCards](https://flow.mittwald.de/components/structure/layout-card) dargestellt.
  Typische Seitentypen sind beispielsweise
  [Detailseiten](https://flow.mittwald.de/templates/seiten/detailseite),
  [Dashboards](https://flow.mittwald.de/templates/seiten/dashboard) und
  [Übersichtsseiten](https://flow.mittwald.de/templates/seiten/uebersichtsseite).
- **Footer** – Hier lassen sich [Links](https://flow.mittwald.de/components/navigation/link) platzieren,
  etwa Verweise auf Datenschutz oder Impressum.

Auf schmalen Screens ist für die Header-Navigation kein Platz. Sie gibt ihre
Links an ein [OffCanvas](https://flow.mittwald.de/components/overlays/modal) ab, das ein Burger-Menü in
der Kopfleiste öffnet.

---

# Varianten und Abwandlung

## Mit seitlicher Navigation

Wenn der Header nicht genug Platz für alle gleichrangigen Bereiche bietet,
wandert die flache Navigation nach links in eine
[Navigation](https://flow.mittwald.de/components/navigation/navigation). Sie nimmt auch das Logo,
globale Funktionen wie Benachrichtigungen und Einstellungen sowie das
Nutzerprofil auf, sodass der Header ganz entfällt. Die Struktur bleibt einstufig
und damit eine Simple App. Öffnet ein Wechsel je Bereich eine eigene
Seitennavigation, entsteht eine
[Complex App](https://flow.mittwald.de/templates/app-shells/complex-app).

**simple-app-sidebar.tsx**

```tsx
import {
  Avatar,
  Badge,
  Button,
  ColumnLayout,
  Combine,
  CounterBadge,
  Flex,
  Heading,
  IconCustomer,
  IconDashboard,
  IconInvoice,
  IconLogout,
  IconNotification,
  IconPayment,
  IconQuote,
  IconSettings,
  Initials,
  LayoutCard,
  Link,
  Navigation,
  Section,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import styles from "./simple-app-sidebar.module.css";

type Status = "Bezahlt" | "Offen" | "Überfällig";

const statusColor: Record<
  Status,
  "green" | "neutral" | "red"
> = {
  Bezahlt: "green",
  Offen: "neutral",
  Überfällig: "red",
};

interface Invoice {
  number: string;
  customer: string;
  createdAt: string; // ISO date, sorted on
  date: string; // formatted for display
  amount: string;
  status: Status;
}

// A page of invoices, one per day counting back from 30.09.2026, with enough
// rows to sort, filter and search through.
const invoices: Invoice[] = [
  {
    number: "RE-2026-0148",
    customer: "KD-1298",
    createdAt: "2026-09-30",
    date: "30.09.2026",
    amount: "844,00 €",
    status: "Offen",
  },
  {
    number: "RE-2026-0149",
    customer: "KD-0553",
    createdAt: "2026-09-29",
    date: "29.09.2026",
    amount: "965,00 €",
    status: "Bezahlt",
  },
  {
    number: "RE-2026-0150",
    customer: "KD-0987",
    createdAt: "2026-09-28",
    date: "28.09.2026",
    amount: "917,00 €",
    status: "Bezahlt",
  },
  {
    number: "RE-2026-0151",
    customer: "KD-0553",
    createdAt: "2026-09-27",
    date: "27.09.2026",
    amount: "844,00 €",
    status: "Überfällig",
  },
  {
    number: "RE-2026-0152",
    customer: "KD-1298",
    createdAt: "2026-09-26",
    date: "26.09.2026",
    amount: "418,00 €",
    status: "Überfällig",
  },
  {
    number: "RE-2026-0153",
    customer: "KD-0553",
    createdAt: "2026-09-25",
    date: "25.09.2026",
    amount: "1.434,00 €",
    status: "Offen",
  },
  {
    number: "RE-2026-0154",
    customer: "KD-0553",
    createdAt: "2026-09-24",
    date: "24.09.2026",
    amount: "1.559,00 €",
    status: "Offen",
  },
  {
    number: "RE-2026-0155",
    customer: "KD-0765",
    createdAt: "2026-09-23",
    date: "23.09.2026",
    amount: "2.032,00 €",
    status: "Überfällig",
  },
  {
    number: "RE-2026-0156",
    customer: "KD-0987",
    createdAt: "2026-09-22",
    date: "22.09.2026",
    amount: "2.269,00 €",
    status: "Bezahlt",
  },
  {
    number: "RE-2026-0157",
    customer: "KD-1298",
    createdAt: "2026-09-21",
    date: "21.09.2026",
    amount: "1.230,00 €",
    status: "Offen",
  },
  {
    number: "RE-2026-0158",
    customer: "KD-1042",
    createdAt: "2026-09-20",
    date: "20.09.2026",
    amount: "2.771,00 €",
    status: "Offen",
  },
  {
    number: "RE-2026-0159",
    customer: "KD-0987",
    createdAt: "2026-09-19",
    date: "19.09.2026",
    amount: "2.556,00 €",
    status: "Offen",
  },
  {
    number: "RE-2026-0160",
    customer: "KD-1298",
    createdAt: "2026-09-18",
    date: "18.09.2026",
    amount: "669,00 €",
    status: "Bezahlt",
  },
  {
    number: "RE-2026-0161",
    customer: "KD-1042",
    createdAt: "2026-09-17",
    date: "17.09.2026",
    amount: "1.761,00 €",
    status: "Bezahlt",
  },
  {
    number: "RE-2026-0162",
    customer: "KD-0553",
    createdAt: "2026-09-16",
    date: "16.09.2026",
    amount: "871,00 €",
    status: "Überfällig",
  },
];

export default () => {
  const InvoiceList = typedList<Invoice>();

  return (
    <div className={styles.shell}>
      <Flex
        direction="column"
        gap="l"
        paddingBlock="l"
        paddingInline="xl"
        className={styles.app}
      >
        <ColumnLayout
          l={[1, 3]}
          m={[1]}
          gap="l"
          className={styles.body}
        >
          <LayoutCard className={styles.sidebar}>
            <span
              className={styles.logo}
              role="img"
              aria-label="mittwald"
            />
            <AreaNavigation />
            <Flex
              direction="column"
              gap="m"
              className={styles.sidebarBottom}
            >
              <AdminNavigation />
              {/* The current user sits at the very bottom of the sidebar. */}
              <Flex
                align="center"
                justify="space-between"
                gap="s"
              >
                <Combine>
                  <Avatar>
                    <Initials>Max Mustermann</Initials>
                  </Avatar>
                  <Text>Max Mustermann</Text>
                </Combine>
                <Button
                  variant="plain"
                  color="secondary"
                  aria-label="Abmelden"
                >
                  <IconLogout />
                </Button>
              </Flex>
            </Flex>
          </LayoutCard>

          <Flex
            elementType="main"
            direction="column"
            gap="m"
            className={styles.main}
          >
            {/* The active area is already named in the navigation, so the page
            heading is only exposed to assistive technology. */}
            <Heading
              level={1}
              className={styles.visuallyHidden}
            >
              Rechnungen
            </Heading>

            <LayoutCard className={styles.contentCard}>
              <Section>
                <InvoiceList.List
                  aria-label="Rechnungen"
                  defaultViewMode="table"
                  batchSize={20}
                  getItemId={(invoice) => invoice.number}
                >
                  <InvoiceList.StaticData data={invoices} />
                  <InvoiceList.Search />
                  <InvoiceList.Filter
                    property="status"
                    mode="some"
                    name="Status"
                  />
                  <InvoiceList.Sorting
                    property="createdAt"
                    name="Erstelldatum"
                    direction="desc"
                    directionName="absteigend"
                    defaultEnabled
                  />
                  <InvoiceList.Sorting
                    property="createdAt"
                    name="Erstelldatum"
                    direction="asc"
                    directionName="aufsteigend"
                  />
                  <InvoiceList.Table>
                    <InvoiceList.TableHeader>
                      <InvoiceList.TableColumn>
                        Rechnungsnummer
                      </InvoiceList.TableColumn>
                      <InvoiceList.TableColumn>
                        Kundennummer
                      </InvoiceList.TableColumn>
                      <InvoiceList.TableColumn>
                        Ausstellungsdatum
                      </InvoiceList.TableColumn>
                      <InvoiceList.TableColumn>
                        Betrag
                      </InvoiceList.TableColumn>
                      <InvoiceList.TableColumn>
                        Status
                      </InvoiceList.TableColumn>
                    </InvoiceList.TableHeader>

                    <InvoiceList.TableBody>
                      <InvoiceList.TableRow>
                        <InvoiceList.TableCell>
                          {(invoice) => invoice.number}
                        </InvoiceList.TableCell>
                        <InvoiceList.TableCell>
                          {(invoice) => invoice.customer}
                        </InvoiceList.TableCell>
                        <InvoiceList.TableCell>
                          {(invoice) => invoice.date}
                        </InvoiceList.TableCell>
                        <InvoiceList.TableCell>
                          {(invoice) => invoice.amount}
                        </InvoiceList.TableCell>
                        <InvoiceList.TableCell>
                          {(invoice) => (
                            <Badge
                              color={
                                statusColor[invoice.status]
                              }
                            >
                              {invoice.status}
                            </Badge>
                          )}
                        </InvoiceList.TableCell>
                      </InvoiceList.TableRow>
                    </InvoiceList.TableBody>
                  </InvoiceList.Table>
                </InvoiceList.List>
              </Section>
            </LayoutCard>
          </Flex>
        </ColumnLayout>

        <Flex
          elementType="footer"
          justify="center"
          wrap="wrap"
          gap="l"
          className={styles.footer}
        >
          <Link href="#" target="_blank" color="dark">
            Datenschutz
          </Link>
          <Link href="#" target="_blank" color="dark">
            Impressum
          </Link>
        </Flex>
      </Flex>
    </div>
  );
};

/*
 * The flat list of equal-ranking areas — the single navigation level of a
 * Simple App, moved from the header into the sidebar.
 */
const AreaNavigation = () => (
  <Navigation aria-label="Bereiche">
    <Link href="#">
      <IconDashboard />
      <Text>Dashboard</Text>
    </Link>
    <Link href="#" aria-current="page">
      <IconInvoice />
      <Text>Rechnungen</Text>
    </Link>
    <Link href="#">
      <IconQuote />
      <Text>Angebote</Text>
    </Link>
    <Link href="#">
      <IconCustomer />
      <Text>Kunden</Text>
    </Link>
    <Link href="#">
      <IconPayment />
      <Text>Zahlungseingang</Text>
    </Link>
  </Navigation>
);

/*
 * Supplementary points that would be out of place among the areas. They sit
 * apart from the flat list above.
 */
const AdminNavigation = () => (
  <Navigation aria-label="Verwaltung">
    <Link href="#">
      <IconNotification />
      <Text>Benachrichtigungen</Text>
      <CounterBadge count={2} />
    </Link>
    <Link href="#">
      <IconSettings />
      <Text>Einstellungen</Text>
    </Link>
  </Navigation>
)
```

**simple-app-sidebar.module.css**

```css
/* The container the page-scroll switch below is measured against. */
.shell {
  container-type: inline-size;
  height: 100%;
  background: var(--texture--grain), var(--color--background-gradient);
  background-blend-mode: overlay, normal;
}

.app {
  /* Fixed to the viewport height (container-relative here; use 100dvh in a real
     full-page app) so the cards below can fill it and scroll their own content
     instead of growing the page. */
  height: 100%;
  max-width: 1800px;
  margin-inline: auto;
  overflow: hidden;
}

/*
 * The wordmark rides on `currentColor` through a CSS mask, so it follows the
 * theme. Swap the masked SVG for your own logo.
 */
.logo {
  width: 9rem;
  max-width: 100%;
  aspect-ratio: 300 / 57;

  /* Extra breathing room between the wordmark and the navigation below it. */
  margin-block-end: var(--size-px--m);
  background: currentcolor;
  mask: url("./mittwald.svg") no-repeat left center / contain;
  -webkit-mask: url("./mittwald.svg") no-repeat left center / contain;
}

/* Sidebar and content fill the available height side by side; the column
   layout stacks them once its container gets narrow. */
.body {
  flex: 1;
  min-height: 0;
}

/* The column layout's inner grid fills that height, so its row stretches. */
.body > * {
  height: 100%;
}

/* The navigation card scrolls its own content if the viewport is too short for
   it. */
.sidebar {
  align-self: stretch;
  gap: var(--size-px--m);
  min-height: 0;
  overflow: auto;
}

/* Settings and the user profile sit at the bottom, apart from the areas above. */
.sidebarBottom {
  margin-block-start: auto;
}

.main {
  align-self: stretch;
  min-width: 0;
  min-height: 0;
}

/* The content card grows with its content, but only up to the viewport: once it
   would run past the bottom it stops there and scrolls its own overflow (the
   long invoice list) instead of growing the page. */
.contentCard {
  flex: 0 1 auto;
  min-height: 0;
  overflow: auto;
}

/* Keeps the heading in the accessibility tree while hiding it visually. */
.visuallyHidden {
  position: absolute;
  width: 1px;
  height: 1px;
  margin: -1px;
  padding: 0;
  overflow: hidden;
  clip-path: inset(50%);
  white-space: nowrap;
  border: 0;
}

.footer {
  margin-block-start: auto;
}

/*
 * Once the column layout stacks the cards (its content box at or below 850px,
 * i.e. 850px plus the xl side padding), the page scrolls as a whole rather than
 * each card scrolling on its own inside a fixed height.
 */
@container (max-width: 914px) {
  .app {
    height: auto;
    overflow: visible;
  }

  .sidebar {
    overflow: visible;
  }

  .main {
    min-height: auto;
  }

  .contentCard {
    flex: none;
    min-height: auto;
    overflow: visible;
  }
}

@media (max-width: 768px) {
  .app {
    padding-inline: var(--size-px--m);
  }
}
```

---

# Complex App

**complex-app.tsx**

```tsx
import {
  ActionGroup,
  Avatar,
  Breadcrumb,
  Button,
  Content,
  ContextMenu,
  ContextMenuTrigger,
  CounterBadge,
  Flex,
  HeaderNavigation,
  Heading,
  IconApp,
  IconCronjob,
  IconDashboard,
  IconDatabase,
  IconDomain,
  IconEmail,
  IconLogout,
  IconMember,
  IconMenu,
  IconMonitoring,
  IconNotification,
  IconSearch,
  IconSettings,
  IconSshSftp,
  Initials,
  Label,
  LayoutCard,
  Link,
  MenuItem,
  Modal,
  ModalTrigger,
  Navigation,
  NavigationGroup,
  ProgressBar,
  Section,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import styles from "./complex-app.module.css";

interface Mailbox {
  id: string;
  address: string;
  type: string;
  color: "blue" | "teal" | "violet";
  storage?: { used: number; max: number };
}

const mailboxes: Mailbox[] = [
  {
    id: "1",
    address: "max.mustermann@mittwald.de",
    type: "E-Mail-Adresse",
    color: "blue",
    storage: { used: 1, max: 2 },
  },
  {
    id: "2",
    address: "kontakt@mittwald.de",
    type: "E-Mail-Adresse",
    color: "blue",
    storage: { used: 0.5, max: 2 },
  },
  {
    id: "3",
    address: "info@mittwald.de",
    type: "Weiterleitungsadresse",
    color: "teal",
  },
  {
    id: "4",
    address: "hallo@mittwald.de",
    type: "Catch-All-Adresse",
    color: "violet",
    storage: { used: 0, max: 2 },
  },
];

const MailboxList = typedList<Mailbox>();

export default () => (
  <Flex direction="column" className={styles.app}>
    <Topbar />
    <Flex
      direction="column"
      gap="l"
      grow
      className={styles.content}
    >
      <Flex gap="l" align="stretch" className={styles.body}>
        <ProjectSidebar />
        <Flex
          elementType="main"
          direction="column"
          gap="m"
          className={styles.main}
        >
          <Breadcrumb>
            <Link href="#">Projekt</Link>
            <Link href="#">E-Mails</Link>
          </Breadcrumb>
          <Heading level={1}>E-Mails</Heading>
          <LayoutCard>
            <MailboxList.List
              batchSize={4}
              aria-label="E-Mail-Adressen"
              getItemId={(m) => m.id}
            >
              <MailboxList.StaticData data={mailboxes} />
              <ActionGroup>
                <Button>Anlegen</Button>
              </ActionGroup>
              <MailboxList.Search />
              <MailboxList.Filter
                property="type"
                name="Typ"
                mode="some"
              />
              <MailboxList.Sorting
                property="address"
                name="Alphabetisch"
                direction="asc"
                directionName="aufsteigend"
                defaultEnabled
              />
              <MailboxList.Sorting
                property="address"
                name="Alphabetisch"
                direction="desc"
                directionName="absteigend"
              />
              <MailboxList.Item
                textValue={(m) => m.address}
              >
                {(m) => (
                  <MailboxList.ItemView
                    l={[3, 1]}
                    m={[2, 1]}
                    s={[1]}
                  >
                    <Avatar color={m.color}>
                      <IconEmail />
                    </Avatar>
                    <Heading>{m.address}</Heading>
                    <Text>{m.type}</Text>
                    {m.storage && (
                      <Content>
                        <ProgressBar
                          size="s"
                          showMaxValue
                          value={m.storage.used}
                          maxValue={m.storage.max}
                          formatOptions={{
                            style: "unit",
                            unit: "gigabyte",
                          }}
                        >
                          <Label>Speicher</Label>
                        </ProgressBar>
                      </Content>
                    )}
                    <ContextMenu>
                      <MenuItem>Details anzeigen</MenuItem>
                      <MenuItem>Bearbeiten</MenuItem>
                      <MenuItem>Löschen</MenuItem>
                    </ContextMenu>
                  </MailboxList.ItemView>
                )}
              </MailboxList.Item>
            </MailboxList.List>
          </LayoutCard>
        </Flex>
      </Flex>
      <Footer />
    </Flex>
  </Flex>
);

/*
 * The global navigation links, shared by the top bar and the off-canvas. Each
 * renders them through its own props context, so the same Links read as a
 * header bar in one and as a navigation list in the other.
 */
const GlobalNavigationLinks = () => (
  <>
    <Link href="#">Dashboard</Link>
    <Link href="#">Organisation</Link>
    <Link href="#">Server</Link>
    <Link href="#" aria-current="page">
      Projekte
    </Link>
  </>
);

const Topbar = () => (
  <header className={styles.header}>
    <Flex
      align="center"
      wrap="wrap"
      gap="m"
      className={styles.headerContent}
    >
      <span
        className={styles.logo}
        role="img"
        aria-label="mittwald"
      />
      <HeaderNavigation
        aria-label="Hauptnavigation"
        className={styles.topnav}
      >
        <GlobalNavigationLinks />
        <SearchButton />
        <NotificationButton />
        <ContextMenuTrigger>
          <Button aria-label="Konto">
            <Avatar>
              <Initials>Max Mustermann</Initials>
            </Avatar>
          </Button>
          <ContextMenu>
            <MenuItem>
              <IconSettings />
              <Text>Profil</Text>
            </MenuItem>
            <MenuItem>
              <IconLogout />
              <Text>Abmelden</Text>
            </MenuItem>
          </ContextMenu>
        </ContextMenuTrigger>
      </HeaderNavigation>
      <HeaderNavigation className={styles.mobileActions}>
        <SearchButton />
        <NotificationButton />
        <MobileMenu />
      </HeaderNavigation>
    </Flex>
  </header>
);

/*
 * Search and the bell keep their place next to the burger: both are worth
 * reaching without opening the menu first.
 */
const SearchButton = () => (
  <Button
    variant="plain"
    color="secondary"
    aria-label="Suche"
  >
    <IconSearch />
  </Button>
);

const NotificationButton = () => (
  <Button aria-label="Benachrichtigungen">
    <IconNotification />
    <CounterBadge count={2} />
  </Button>
);

/*
 * On a narrow screen the top bar has no room for the navigation and the
 * sidebar has no column of its own, so both move in here. The burger is then
 * the shell's only navigation control.
 */
const MobileMenu = () => (
  <ModalTrigger>
    <Button aria-label="Menü öffnen">
      <IconMenu />
    </Button>
    <Modal offCanvas showCloseButton>
      <Heading>Menü</Heading>
      <Content>
        <Section>
          <Navigation aria-label="Hauptnavigation">
            <GlobalNavigationLinks />
          </Navigation>
        </Section>
        <Section>
          <Heading>Mein Projekt</Heading>
          <ProjectNavigation />
        </Section>
      </Content>
      <ActionGroup>
        <Button variant="soft" color="secondary">
          <IconLogout />
          <Text>Abmelden</Text>
        </Button>
      </ActionGroup>
    </Modal>
  </ModalTrigger>
);

const ProjectSidebar = () => (
  <LayoutCard className={styles.sidebar}>
    <Section>
      <Heading>Mein Projekt</Heading>
      <ProjectNavigation />
    </Section>
  </LayoutCard>
);

const ProjectNavigation = () => (
  <Navigation aria-label="Projektnavigation">
    <NavigationGroup>
      <Label>Allgemein</Label>
      <Link href="#">
        <IconDashboard />
        <Text>Dashboard</Text>
      </Link>
      <Link href="#">
        <IconMonitoring />
        <Text>Monitoring</Text>
      </Link>
    </NavigationGroup>
    <NavigationGroup>
      <Label>Komponenten</Label>
      <Link href="#">
        <IconApp />
        <Text>Apps</Text>
      </Link>
      <Link href="#">
        <IconDomain />
        <Text>Domains</Text>
      </Link>
      <Link href="#" aria-current="page">
        <IconEmail />
        <Text>E-Mails</Text>
      </Link>
      <Link href="#">
        <IconDatabase />
        <Text>Datenbanken</Text>
      </Link>
      <Link href="#">
        <IconCronjob />
        <Text>Cronjobs</Text>
      </Link>
      <Link href="#">
        <IconSshSftp />
        <Text>SSH/SFTP</Text>
      </Link>
    </NavigationGroup>
    <NavigationGroup>
      <Label>Verwaltung</Label>
      <Link href="#">
        <IconMember />
        <Text>Mitglieder</Text>
      </Link>
      <Link href="#">
        <IconSettings />
        <Text>Einstellungen</Text>
      </Link>
    </NavigationGroup>
  </Navigation>
);

const Footer = () => (
  <Flex
    elementType="footer"
    justify="center"
    wrap="wrap"
    gap="l"
    className={styles.footer}
  >
    <Link href="#" target="_blank" color="dark">
      Datenschutz
    </Link>
    <Link href="#" target="_blank" color="dark">
      Impressum
    </Link>
  </Flex>
)
```

**complex-app.module.css**

```css
.app {
  /* Header and content share one maximum width, so their edges line up. */
  --page-width: 1800px;

  /* The header's tint is mixed from the gradient's first stop. */
  --header-ground: var(--neutral--color--200);

  /* The header's rendered height; the sticky sidebar starts just below it. */
  --header-height: 72px;

  /* Container-relative here; use 100dvh in a real full-page app. */
  min-height: 100%;
  background: var(--texture--grain), var(--color--background-gradient);
  background-blend-mode: overlay, normal;
}

/*
 * The header stays at the top while the page scrolls beneath it. Its tint is
 * translucent and blurred, so the navigation stays legible above the content.
 */
.header {
  position: sticky;
  top: 0;
  z-index: 1;
  padding-block: var(--size-px--m);
  background-color: color-mix(in srgb, var(--header-ground) 40%, transparent);
  backdrop-filter: blur(var(--blur));
}

.headerContent {
  max-width: var(--page-width);
  margin-inline: auto;
  padding-inline: var(--size-px--xl);
}

.content {
  width: 100%;
  max-width: var(--page-width);
  margin-inline: auto;
  padding-block: var(--size-px--s) var(--size-px--l);
  padding-inline: var(--size-px--xl);
}

/*
 * The wordmark rides on `currentColor` through a CSS mask, so it follows the
 * theme. Swap the masked SVG for your own logo.
 */
.logo {
  width: 7rem;
  max-width: 100%;
  aspect-ratio: 300 / 57;
  background: currentcolor;
  mask: url("./mittwald.svg") no-repeat center / contain;
  -webkit-mask: url("./mittwald.svg") no-repeat center / contain;
}

/* The global navigation is pushed to the far end of the top bar. */
.topnav {
  margin-inline-start: auto;
}

/* The bell and the burger take that place once the navigation gives it up. */
.mobileActions {
  margin-inline-start: auto;
}

/* Sidebar and content fill the space between top bar and footer. */
.body {
  flex: 1;
  min-height: 0;
}

/*
 * The navigation card keeps a fixed width beside the flexible content. It stays
 * below the header while the page scrolls, and scrolls its own links once they
 * outgrow the viewport.
 */
.sidebar {
  flex: 0 0 17rem;
  position: sticky;
  top: calc(var(--header-height) + var(--size-px--s));
  align-self: flex-start;
  max-height: calc(
    100dvh - var(--header-height) - var(--size-px--s) - var(--size-px--l)
  );
  overflow: auto;
}

.main {
  flex: 1 1 auto;
  min-width: 0;
}

.footer {
  margin-block-start: auto;
}

/*
 * Below this width neither the global navigation nor the sidebar fits, so both
 * hand their links to the off-canvas behind the burger.
 */
@media (max-width: 768px) {
  .topnav,
  .sidebar {
    display: none;
  }

  .headerContent,
  .content {
    padding-inline: var(--size-px--m);
  }
}

@media (min-width: 769px) {
  .mobileActions {
    display: none;
  }
}

@media (prefers-contrast: more), (prefers-reduced-transparency) {
  .header {
    background-color: var(--header-ground);
    backdrop-filter: none;
  }
}

/* The dark gradient starts darker than the neutral token. */
[data-theme="dark"] .app {
  --header-ground: #121518;
}
```

---

# Verwendung

Eine Complex App erschließt viele Bereiche über mehrere Navigationsebenen aus
globalem Header, Sidebar und Breadcrumb. Das ist die im mStudio typische Form.
Verwende sie, wenn eine flache Navigation nicht mehr ausreicht. Die gestaffelten
Ebenen halten auch eine große Anwendung übersichtlich und zeigen dem Nutzer
jederzeit, wo er sich befindet. Für ein kleines Werkzeug mit wenigen,
gleichrangigen Bereichen genügt eine
[Simple App](https://flow.mittwald.de/templates/app-shells/simple-app).

---

# Aufbau

- **Header** – Eine [HeaderNavigation](https://flow.mittwald.de/components/navigation/header-navigation)
  trägt die globale Navigationsebene und bereichsübergreifende Funktionen. Er
  bleibt beim Scrollen oben stehen, der Inhalt läuft darunter durch.
- **Sidebar** – Eine [Navigation](https://flow.mittwald.de/components/navigation/navigation) führt durch
  die Unterseiten des aktuellen Bereichs. Sie bleibt beim Scrollen unter dem
  Header stehen.
- **Content Header** – [Breadcrumb](https://flow.mittwald.de/components/navigation/breadcrumb) und
  PageTitle (ein [Heading](https://flow.mittwald.de/components/content/heading) der Ebene 1) orientieren
  den Nutzer in der Tiefe.
- **Content** – Der Inhalt ist auf eine maximale Breite begrenzt und wird in der
  Regel in [LayoutCards](https://flow.mittwald.de/components/structure/layout-card) dargestellt.
  Typische Seitentypen sind beispielsweise
  [Detailseiten](https://flow.mittwald.de/templates/seiten/detailseite),
  [Dashboards](https://flow.mittwald.de/templates/seiten/dashboard) und
  [Übersichtsseiten](https://flow.mittwald.de/templates/seiten/uebersichtsseite).
- **Footer** – Hier lassen sich [Links](https://flow.mittwald.de/components/navigation/link) platzieren,
  etwa Verweise auf Datenschutz oder Impressum.

Auf schmalen Screens ist für Header-Navigation und Sidebar kein Platz. Beide
geben ihre Links an ein [OffCanvas](https://flow.mittwald.de/components/overlays/modal) ab, das ein
Burger-Menü in der Kopfleiste öffnet.

---

# Varianten und Abwandlung

## Detailansicht

Die Detailansicht kombiniert zwei Seitentypen: Über die
[Übersichtsseite](https://flow.mittwald.de/templates/seiten/uebersichtsseite) – eine
[List](https://flow.mittwald.de/components/list/list) – navigiert man in die Tiefe zu einem einzelnen
Objekt. [Breadcrumb](https://flow.mittwald.de/components/navigation/breadcrumb) und PageTitle helfen bei
der Orientierung; eine [TabNavigation](https://flow.mittwald.de/components/navigation/tab-navigation)
gliedert das Objekt in Unterbereiche.

**complex-app-detail.tsx**

```tsx
import {
  ActionGroup,
  Avatar,
  Breadcrumb,
  Button,
  ColumnLayout,
  Content,
  ContextMenu,
  ContextMenuTrigger,
  CounterBadge,
  Flex,
  Header,
  HeaderNavigation,
  Heading,
  IconApp,
  IconCronjob,
  IconDashboard,
  IconDatabase,
  IconDomain,
  IconEmail,
  IconLogout,
  IconMember,
  IconMenu,
  IconMonitoring,
  IconNotification,
  IconSearch,
  IconSettings,
  IconSshSftp,
  Initials,
  InlineCode,
  Label,
  LabeledValue,
  LayoutCard,
  Link,
  MenuItem,
  Modal,
  ModalTrigger,
  Navigation,
  NavigationGroup,
  ProgressBar,
  Section,
  Switch,
  Tab,
  TabNavigation,
  Tabs,
  TabTitle,
  Text,
} from "@mittwald/flow-react-components";
import styles from "./complex-app-detail.module.css";

const connections = {
  imap: {
    server: "imap.mittwald.de",
    port: "993 (SSL/TLS)",
  },
  pop3: {
    server: "pop3.mittwald.de",
    port: "995 (SSL/TLS)",
  },
  smtp: {
    server: "smtp.mittwald.de",
    port: "465 (SSL/TLS)",
  },
};

export default () => (
  <Flex direction="column" className={styles.app}>
    <Topbar />
    <Flex
      direction="column"
      gap="l"
      grow
      className={styles.content}
    >
      <Flex gap="l" align="stretch" className={styles.body}>
        <ProjectSidebar />
        <Flex
          elementType="main"
          direction="column"
          gap="m"
          className={styles.main}
        >
          <Breadcrumb>
            <Link href="#">Projekt</Link>
            <Link href="#">E-Mails</Link>
            <Link href="#">E-Mail-Details</Link>
          </Breadcrumb>
          <Heading level={1}>
            max.mustermann@mittwald.de
          </Heading>
          <LayoutCard>
            <TabNavigation aria-label="E-Mail-Bereiche">
              <Link href="#" aria-current="page">
                Allgemein
              </Link>
              <Link href="#">Weiterleitungen</Link>
              <Link href="#">Autoresponder</Link>
            </TabNavigation>
            <Section>
              <Header>
                <Heading>E-Mail-Adresse</Heading>
                <Button variant="soft" color="secondary">
                  Passwort ändern
                </Button>
                <Button>E-Mail-Adresse bearbeiten</Button>
              </Header>
              <ColumnLayout>
                <LabeledValue>
                  <Label>E-Mail-Adresse</Label>
                  <Content>
                    max.mustermann@mittwald.de
                  </Content>
                </LabeledValue>
                <LabeledValue>
                  <Label>Webmailer</Label>
                  <Link href="#" target="_blank">
                    mittwald Webmailer
                  </Link>
                </LabeledValue>
              </ColumnLayout>
            </Section>

            <Section>
              <Header>
                <Heading>Speicherplatz</Heading>
                <Button variant="soft" color="secondary">
                  Bearbeiten
                </Button>
              </Header>
              <Text>
                Die E-Mail-Adresse verfügt über
                Speicherplatz zum Empfangen und Speichern
                von E-Mails. Wir empfehlen mindestens 2 GB.
              </Text>
              <ProgressBar
                showMaxValue
                value={1}
                maxValue={2}
                formatOptions={{
                  style: "unit",
                  unit: "gigabyte",
                }}
              >
                <Label>Speicherplatz</Label>
              </ProgressBar>
            </Section>

            <Section>
              <Heading>Verbindungsinformationen</Heading>
              <Tabs aria-label="Verbindungsprotokoll">
                {Object.entries(connections).map(
                  ([key, c]) => (
                    <Tab key={key} id={key}>
                      <TabTitle>
                        {key.toUpperCase()}
                      </TabTitle>
                      <ColumnLayout>
                        <LabeledValue>
                          <Label>Benutzername</Label>
                          <InlineCode>
                            max.mustermann@mittwald.de
                          </InlineCode>
                        </LabeledValue>
                        <LabeledValue>
                          <Label>Server</Label>
                          <InlineCode>
                            {c.server}
                          </InlineCode>
                        </LabeledValue>
                        <LabeledValue>
                          <Label>Port</Label>
                          <InlineCode>{c.port}</InlineCode>
                        </LabeledValue>
                      </ColumnLayout>
                    </Tab>
                  ),
                )}
              </Tabs>
            </Section>

            <Section>
              <Header>
                <Heading>Spamschutz</Heading>
                <Switch defaultSelected>
                  <Label>Aktivieren</Label>
                </Switch>
              </Header>
              <Text>
                Der Spamfilter schützt dich vor ungewollten
                E-Mails. Wir empfehlen, ihn immer aktiviert
                zu lassen.
              </Text>
            </Section>
          </LayoutCard>
        </Flex>
      </Flex>
      <Footer />
    </Flex>
  </Flex>
);

/*
 * The global navigation links, shared by the top bar and the off-canvas. Each
 * renders them through its own props context, so the same Links read as a
 * header bar in one and as a navigation list in the other.
 */
const GlobalNavigationLinks = () => (
  <>
    <Link href="#">Dashboard</Link>
    <Link href="#">Organisation</Link>
    <Link href="#">Server</Link>
    <Link href="#" aria-current="page">
      Projekte
    </Link>
  </>
);

const Topbar = () => (
  <header className={styles.header}>
    <Flex
      align="center"
      wrap="wrap"
      gap="m"
      className={styles.headerContent}
    >
      <span
        className={styles.logo}
        role="img"
        aria-label="mittwald"
      />
      <HeaderNavigation
        aria-label="Hauptnavigation"
        className={styles.topnav}
      >
        <GlobalNavigationLinks />
        <SearchButton />
        <NotificationButton />
        <ContextMenuTrigger>
          <Button aria-label="Konto">
            <Avatar>
              <Initials>Max Mustermann</Initials>
            </Avatar>
          </Button>
          <ContextMenu>
            <MenuItem>
              <IconSettings />
              <Text>Profil</Text>
            </MenuItem>
            <MenuItem>
              <IconLogout />
              <Text>Abmelden</Text>
            </MenuItem>
          </ContextMenu>
        </ContextMenuTrigger>
      </HeaderNavigation>
      <HeaderNavigation className={styles.mobileActions}>
        <SearchButton />
        <NotificationButton />
        <MobileMenu />
      </HeaderNavigation>
    </Flex>
  </header>
);

/*
 * Search and the bell keep their place next to the burger: both are worth
 * reaching without opening the menu first.
 */
const SearchButton = () => (
  <Button
    variant="plain"
    color="secondary"
    aria-label="Suche"
  >
    <IconSearch />
  </Button>
);

const NotificationButton = () => (
  <Button aria-label="Benachrichtigungen">
    <IconNotification />
    <CounterBadge count={2} />
  </Button>
);

/*
 * On a narrow screen the top bar has no room for the navigation and the
 * sidebar has no column of its own, so both move in here. The burger is then
 * the shell's only navigation control.
 */
const MobileMenu = () => (
  <ModalTrigger>
    <Button aria-label="Menü öffnen">
      <IconMenu />
    </Button>
    <Modal offCanvas showCloseButton>
      <Heading>Menü</Heading>
      <Content>
        <Section>
          <Navigation aria-label="Hauptnavigation">
            <GlobalNavigationLinks />
          </Navigation>
        </Section>
        <Section>
          <Heading>Mein Projekt</Heading>
          <ProjectNavigation />
        </Section>
      </Content>
      <ActionGroup>
        <Button variant="soft" color="secondary">
          <IconLogout />
          <Text>Abmelden</Text>
        </Button>
      </ActionGroup>
    </Modal>
  </ModalTrigger>
);

const ProjectSidebar = () => (
  <LayoutCard className={styles.sidebar}>
    <Section>
      <Heading>Mein Projekt</Heading>
      <ProjectNavigation />
    </Section>
  </LayoutCard>
);

const ProjectNavigation = () => (
  <Navigation aria-label="Projektnavigation">
    <NavigationGroup>
      <Label>Allgemein</Label>
      <Link href="#">
        <IconDashboard />
        <Text>Dashboard</Text>
      </Link>
      <Link href="#">
        <IconMonitoring />
        <Text>Monitoring</Text>
      </Link>
    </NavigationGroup>
    <NavigationGroup>
      <Label>Komponenten</Label>
      <Link href="#">
        <IconApp />
        <Text>Apps</Text>
      </Link>
      <Link href="#">
        <IconDomain />
        <Text>Domains</Text>
      </Link>
      <Link href="#" aria-current="page">
        <IconEmail />
        <Text>E-Mails</Text>
      </Link>
      <Link href="#">
        <IconDatabase />
        <Text>Datenbanken</Text>
      </Link>
      <Link href="#">
        <IconCronjob />
        <Text>Cronjobs</Text>
      </Link>
      <Link href="#">
        <IconSshSftp />
        <Text>SSH/SFTP</Text>
      </Link>
    </NavigationGroup>
    <NavigationGroup>
      <Label>Verwaltung</Label>
      <Link href="#">
        <IconMember />
        <Text>Mitglieder</Text>
      </Link>
      <Link href="#">
        <IconSettings />
        <Text>Einstellungen</Text>
      </Link>
    </NavigationGroup>
  </Navigation>
);

const Footer = () => (
  <Flex
    elementType="footer"
    justify="center"
    wrap="wrap"
    gap="l"
    className={styles.footer}
  >
    <Link href="#" target="_blank" color="dark">
      Datenschutz
    </Link>
    <Link href="#" target="_blank" color="dark">
      Impressum
    </Link>
  </Flex>
)
```

**complex-app-detail.module.css**

```css
.app {
  /* Header and content share one maximum width, so their edges line up. */
  --page-width: 1800px;

  /* The header's tint is mixed from the gradient's first stop. */
  --header-ground: var(--neutral--color--200);

  /* The header's rendered height; the sticky sidebar starts just below it. */
  --header-height: 72px;

  /* Container-relative here; use 100dvh in a real full-page app. */
  min-height: 100%;
  background: var(--texture--grain), var(--color--background-gradient);
  background-blend-mode: overlay, normal;
}

/*
 * The header stays at the top while the page scrolls beneath it. Its tint is
 * translucent and blurred, so the navigation stays legible above the content.
 */
.header {
  position: sticky;
  top: 0;
  z-index: 1;
  padding-block: var(--size-px--m);
  background-color: color-mix(in srgb, var(--header-ground) 40%, transparent);
  backdrop-filter: blur(var(--blur));
}

.headerContent {
  max-width: var(--page-width);
  margin-inline: auto;
  padding-inline: var(--size-px--xl);
}

.content {
  width: 100%;
  max-width: var(--page-width);
  margin-inline: auto;
  padding-block: var(--size-px--s) var(--size-px--l);
  padding-inline: var(--size-px--xl);
}

/*
 * The wordmark rides on `currentColor` through a CSS mask, so it follows the
 * theme. Swap the masked SVG for your own logo.
 */
.logo {
  width: 7rem;
  max-width: 100%;
  aspect-ratio: 300 / 57;
  background: currentcolor;
  mask: url("./mittwald.svg") no-repeat center / contain;
  -webkit-mask: url("./mittwald.svg") no-repeat center / contain;
}

/* The global navigation is pushed to the far end of the top bar. */
.topnav {
  margin-inline-start: auto;
}

/* The bell and the burger take that place once the navigation gives it up. */
.mobileActions {
  margin-inline-start: auto;
}

/* Sidebar and content fill the space between top bar and footer. */
.body {
  flex: 1;
  min-height: 0;
}

/*
 * The navigation card keeps a fixed width beside the flexible content. It stays
 * below the header while the page scrolls, and scrolls its own links once they
 * outgrow the viewport.
 */
.sidebar {
  flex: 0 0 17rem;
  position: sticky;
  top: calc(var(--header-height) + var(--size-px--s));
  align-self: flex-start;
  max-height: calc(
    100dvh - var(--header-height) - var(--size-px--s) - var(--size-px--l)
  );
  overflow: auto;
}

.main {
  flex: 1 1 auto;
  min-width: 0;
}

.footer {
  margin-block-start: auto;
}

/*
 * Below this width neither the global navigation nor the sidebar fits, so both
 * hand their links to the off-canvas behind the burger.
 */
@media (max-width: 768px) {
  .topnav,
  .sidebar {
    display: none;
  }

  .headerContent,
  .content {
    padding-inline: var(--size-px--m);
  }
}

@media (min-width: 769px) {
  .mobileActions {
    display: none;
  }
}

@media (prefers-contrast: more), (prefers-reduced-transparency) {
  .header {
    background-color: var(--header-ground);
    backdrop-filter: none;
  }
}

/* The dark gradient starts darker than the neutral token. */
[data-theme="dark"] .app {
  --header-ground: #121518;
}
```

## Doku-Layout

Eine einfachere Abwandlung ohne globale Objekt-Tiefe: Die
[Navigation](https://flow.mittwald.de/components/navigation/navigation) listet die Bereiche flach, der
Content steht mittig, und rechts führt ein eigenes Inhaltsverzeichnis („Auf
dieser Seite") durch die Abschnitte der Seite. Dieser Styleguide selbst folgt
dem Muster.

**complex-app-doku.tsx**

```tsx
import {
  ActionGroup,
  Badge,
  Button,
  Content,
  Flex,
  HeaderNavigation,
  Heading,
  Icon,
  IconMenu,
  IconSearch,
  Label,
  LayoutCard,
  Link,
  Modal,
  ModalTrigger,
  Navigation,
  NavigationGroup,
  Section,
  Text,
} from "@mittwald/flow-react-components";
import { IconContrastFilled } from "@tabler/icons-react";
import styles from "./complex-app-doku.module.css";

const lorem =
  "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum.";

export default () => (
  <Flex direction="column" className={styles.app}>
    <header className={styles.header}>
      <Flex
        align="center"
        wrap="wrap"
        gap="m"
        className={styles.headerContent}
      >
        <span
          className={styles.logo}
          role="img"
          aria-label="mittwald"
        />
        <HeaderNavigation
          aria-label="Hauptnavigation"
          className={styles.topnav}
        >
          <GlobalNavigationLinks />
          <SearchButton />
          <Button aria-label="Theme wechseln">
            <Icon>
              <IconContrastFilled />
            </Icon>
          </Button>
        </HeaderNavigation>
        <HeaderNavigation className={styles.mobileActions}>
          <SearchButton />
          <MobileMenu />
        </HeaderNavigation>
      </Flex>
    </header>

    <Flex
      direction="column"
      gap="l"
      grow
      className={styles.content}
    >
      <Flex
        gap="l"
        wrap="wrap"
        align="stretch"
        className={styles.body}
      >
        <LayoutCard className={styles.sidebar}>
          <ComponentNavigation />
        </LayoutCard>

        <LayoutCard
          elementType="main"
          className={styles.main}
        >
          <Section>
            <Heading level={1}>Button</Heading>
            <Text>{lorem}</Text>
            <Heading level={2}>Colors</Heading>
            <Text>{lorem}</Text>
            <Heading level={3}>Light und Dark</Heading>
            <Text>{lorem}</Text>
            <Heading level={2}>Sizes</Heading>
            <Text>{lorem}</Text>
            <Heading level={2}>Variants</Heading>
            <Text>{lorem}</Text>
          </Section>
        </LayoutCard>

        <LayoutCard className={styles.toc}>
          <Section>
            <Heading level={4}>Auf dieser Seite</Heading>
            <Navigation aria-label="Auf dieser Seite">
              <Link href="#" aria-current="page">
                Button
              </Link>
              <Link href="#">Colors</Link>
              <Link href="#">Light und Dark</Link>
              <Link href="#">Sizes</Link>
              <Link href="#">Variants</Link>
            </Navigation>
          </Section>
        </LayoutCard>
      </Flex>

      <Flex
        elementType="footer"
        justify="center"
        wrap="wrap"
        gap="l"
        className={styles.footer}
      >
        <Link href="#" target="_blank" color="dark">
          Datenschutz
        </Link>
        <Link href="#" target="_blank" color="dark">
          Impressum
        </Link>
      </Flex>
    </Flex>
  </Flex>
);

/*
 * Search keeps its place next to the burger: it is worth reaching without
 * opening the menu first.
 */
const SearchButton = () => (
  <Button
    variant="plain"
    color="secondary"
    aria-label="Suche"
  >
    <IconSearch />
  </Button>
);

/*
 * The section links, shared by the top bar and the off-canvas. Each renders
 * them through its own props context, so the same Links read as a header bar
 * in one and as a navigation list in the other.
 */
const GlobalNavigationLinks = () => (
  <>
    <Link href="#">Get Started</Link>
    <Link href="#">Foundations</Link>
    <Link href="#">Templates</Link>
    <Link href="#" aria-current="page">
      Components
    </Link>
  </>
);

const ComponentNavigation = () => (
  <Navigation aria-label="Komponenten">
    <NavigationGroup>
      <Label>Actions</Label>
      <Link href="#">Action</Link>
      <Link href="#">ActionGroup</Link>
      <Link href="#" aria-current="page">
        Button
      </Link>
      <Link href="#">ContextMenu</Link>
    </NavigationGroup>
    <NavigationGroup>
      <Label>Form Controls</Label>
      <Link href="#">Autocomplete</Link>
      <Link href="#">Checkbox</Link>
      <Link href="#">CheckboxButton</Link>
      <Link href="#">
        <Text>CodeEditor</Text>
        <Badge color="blue">Neu</Badge>
      </Link>
      <Link href="#">Combobox</Link>
      <Link href="#">DatePicker</Link>
      <Link href="#">Select</Link>
      <Link href="#">Switch</Link>
    </NavigationGroup>
  </Navigation>
);

/*
 * On a narrow screen the top bar has no room for the sections and the
 * component navigation has no column of its own, so both move in here.
 */
const MobileMenu = () => (
  <ModalTrigger>
    <Button aria-label="Menü öffnen">
      <IconMenu />
    </Button>
    <Modal offCanvas showCloseButton>
      <Heading>Menü</Heading>
      <Content>
        <Section>
          <ActionGroup>
            <Button variant="soft" color="secondary">
              <Icon>
                <IconContrastFilled />
              </Icon>
              <Text>Theme wechseln</Text>
            </Button>
          </ActionGroup>
        </Section>
        <Section>
          <Navigation aria-label="Hauptnavigation">
            <GlobalNavigationLinks />
          </Navigation>
        </Section>
        <Section>
          <Heading>Components</Heading>
          <ComponentNavigation />
        </Section>
      </Content>
    </Modal>
  </ModalTrigger>
)
```

**complex-app-doku.module.css**

```css
.app {
  /* Header and content share one maximum width, so their edges line up. */
  --page-width: 1800px;

  /* The header's tint is mixed from the gradient's first stop. */
  --header-ground: var(--neutral--color--200);

  /* The header's rendered height; the sticky sidebar starts just below it. */
  --header-height: 72px;

  /* Container-relative here; use 100dvh in a real full-page app. */
  min-height: 100%;
  background: var(--texture--grain), var(--color--background-gradient);
  background-blend-mode: overlay, normal;
}

/*
 * The header stays at the top while the page scrolls beneath it. Its tint is
 * translucent and blurred, so the navigation stays legible above the content.
 */
.header {
  position: sticky;
  top: 0;
  z-index: 1;
  padding-block: var(--size-px--m);
  background-color: color-mix(in srgb, var(--header-ground) 40%, transparent);
  backdrop-filter: blur(var(--blur));
}

.headerContent {
  max-width: var(--page-width);
  margin-inline: auto;
  padding-inline: var(--size-px--xl);
}

.content {
  width: 100%;
  max-width: var(--page-width);
  margin-inline: auto;
  padding-block: var(--size-px--s) var(--size-px--l);
  padding-inline: var(--size-px--xl);
}

/*
 * The wordmark rides on `currentColor` through a CSS mask, so it follows the
 * theme. Swap the masked SVG for your own logo.
 */
.logo {
  width: 8rem;
  max-width: 100%;
  aspect-ratio: 300 / 57;
  background: currentcolor;
  mask: url("./mittwald.svg") no-repeat center / contain;
  -webkit-mask: url("./mittwald.svg") no-repeat center / contain;
}

/* The global navigation is pushed to the far end of the top bar. */
.topnav {
  margin-inline-start: auto;
}

/* Search and the burger take that place once the navigation gives it up. */
.mobileActions {
  margin-inline-start: auto;
}

/* Navigation, content and table of contents sit in three columns. */
.body {
  flex: 1;
  min-height: 0;
}

/*
 * Both cards keep a fixed width; only the content column flexes. They stay below
 * the header while the page scrolls, and scroll their own links once they
 * outgrow the viewport.
 */
.sidebar,
.toc {
  flex: 0 0 17rem;
  position: sticky;
  top: calc(var(--header-height) + var(--size-px--s));
  align-self: flex-start;
  max-height: calc(
    100dvh - var(--header-height) - var(--size-px--s) - var(--size-px--l)
  );
  overflow: auto;
}

.main {
  flex: 1 1 20rem;
}

.footer {
  margin-block-start: auto;
}

/*
 * Below this width neither the section links nor the component navigation
 * fits, so both hand their links to the off-canvas behind the burger.
 */
@media (max-width: 768px) {
  .topnav,
  .sidebar {
    display: none;
  }

  .headerContent,
  .content {
    padding-inline: var(--size-px--m);
  }
}

@media (min-width: 769px) {
  .mobileActions {
    display: none;
  }
}

@media (prefers-contrast: more), (prefers-reduced-transparency) {
  .header {
    background-color: var(--header-ground);
    backdrop-filter: none;
  }
}

/* The dark gradient starts darker than the neutral token. */
[data-theme="dark"] .app {
  --header-ground: #121518;
}
```

---

# Detailseite

```tsx
import {
  Breadcrumb,
  Button,
  ColumnLayout,
  Content,
  ContextMenu,
  ContextMenuTrigger,
  Flex,
  Header,
  Heading,
  IconChevronDown,
  IconDelete,
  IconEdit,
  IconExternalLink,
  IconPassword,
  Label,
  LabeledValue,
  LayoutCard,
  Link,
  MenuItem,
  Modal,
  ModalTrigger,
  ProgressBar,
  Section,
  Switch,
  Tab,
  Table,
  TableBody,
  TableCell,
  TableColumn,
  TableHeader,
  TableRow,
  TabNavigation,
  Tabs,
  TabTitle,
  Text,
} from "@mittwald/flow-react-components";

export default () => {
  return (
    <Flex direction="column" gap="m">
      <Flex direction="column">
        <Breadcrumb color="dark">
          <Link>Projekt</Link>
          <Link>E-Mails</Link>
          <Link>E-Mail-Details</Link>
        </Breadcrumb>
        <Flex justify="space-between" align="end">
          <Heading color="dark" level={1}>
            max@mustermann.de
          </Heading>
          <ContextMenuTrigger>
            <Button variant="outline" color="dark">
              <Text>Aktionen</Text>
              <IconChevronDown />
            </Button>
            <ContextMenu placement="bottom end">
              <MenuItem>
                <IconEdit />
                <Text>E-Mail-Adresse bearbeiten</Text>
              </MenuItem>
              <MenuItem>
                <IconPassword />
                <Text>Passwort ändern</Text>
              </MenuItem>
              <MenuItem>
                <IconExternalLink />
                <Text>mittwald Webmailer</Text>
              </MenuItem>
              <MenuItem>
                <IconDelete />
                <Text>Löschen</Text>
              </MenuItem>
            </ContextMenu>
          </ContextMenuTrigger>
        </Flex>
      </Flex>
      <LayoutCard>
        <TabNavigation aria-label="E-Mail-Navigation">
          <Link href="#" aria-current="page">
            Allgemein
          </Link>
          <Link href="#">Weiterleitungen</Link>
          <Link href="#">Autoresponder</Link>
        </TabNavigation>
        <Section>
          <Header>
            <Heading>E-Mail-Adresse</Heading>
            <ModalTrigger>
              <Button variant="soft" color="secondary">
                Passwort ändern
              </Button>
              <Modal>
                <Heading>Passwort ändern</Heading>
                <Content>
                  <Text>...</Text>
                </Content>
              </Modal>
            </ModalTrigger>
            <ModalTrigger>
              <Button>E-Mail-Adresse bearbeiten</Button>
              <Modal>
                <Heading>E-Mail-Adresse bearbeiten</Heading>
                <Content>
                  <Text>...</Text>
                </Content>
              </Modal>
            </ModalTrigger>
          </Header>
          <ColumnLayout>
            <LabeledValue>
              <Label>E-Mail-Adresse</Label>
              <Text>max@mustermann.de</Text>
            </LabeledValue>
            <LabeledValue>
              <Label>Webmailer</Label>
              <Link target="_blank">
                mittwald Webmailer
              </Link>
            </LabeledValue>
          </ColumnLayout>
        </Section>
        <Section>
          <Header>
            <Heading>Speicherplatz</Heading>
            <ModalTrigger>
              <Button variant="soft" color="secondary">
                Bearbeiten
              </Button>
              <Modal>
                <Heading>Speicherplatz bearbeiten</Heading>
                <Content>
                  <Text>...</Text>
                </Content>
              </Modal>
            </ModalTrigger>
          </Header>
          <Text>
            Die E-Mail-Adresse verfügt über einen
            Speicherplatz zum Empfangen und Speichern von
            E-Mails. Wir empfehlen dir, mindestens 2 GB zu
            reservieren.
          </Text>
          <ProgressBar
            formatOptions={{
              style: "unit",
              unit: "gigabyte",
            }}
            size="l"
            showMaxValue
            maxValue={2}
            value={1}
            status="success"
          >
            <Label>Speicherplatz</Label>
          </ProgressBar>
        </Section>
        <Section>
          <Heading>Verbindungsinformationen</Heading>
          <Tabs>
            {["IMAP", "POP3", "SMTP"].map(
              (connectionType) => (
                <Tab
                  key={connectionType}
                  id={connectionType}
                >
                  <TabTitle>{connectionType}</TabTitle>
                  <Table
                    aria-label={`Verbindungsinformationen ${connectionType}`}
                  >
                    <TableHeader>
                      <TableColumn></TableColumn>
                      <TableColumn></TableColumn>
                    </TableHeader>
                    <TableBody>
                      <TableRow>
                        <TableCell rowHeader>
                          Benutzername
                        </TableCell>
                        <TableCell>
                          max@mustermann.de
                        </TableCell>
                      </TableRow>
                      <TableRow>
                        <TableCell rowHeader>
                          {connectionType} Port
                        </TableCell>
                        <TableCell>...</TableCell>
                      </TableRow>
                      <TableRow>
                        <TableCell rowHeader>
                          {connectionType} Postausgang
                        </TableCell>
                        <TableCell>...</TableCell>
                      </TableRow>
                    </TableBody>
                  </Table>
                </Tab>
              ),
            )}
          </Tabs>
        </Section>
        <Section>
          <Header>
            <Heading>Spamschutz</Heading>
            <Switch defaultSelected>
              <Label>Aktivieren</Label>
            </Switch>
          </Header>
          <Text>
            Der Spamfilter schützt dich vor ungewollten
            E-Mails. Niemand will Müll in seinem Postfach,
            daher empfehlen wir den Spamschutz immer
            aktiviert zu lassen.
          </Text>
        </Section>
      </LayoutCard>
    </Flex>
  );
}
```

---

# Verwendung

Verwende die Detailseite, wenn sich Nutzer in **ein einzelnes Objekt** vertiefen
und es bearbeiten sollen – sobald zu einem Datensatz mehr gehört als eine Zeile
in einer Liste. Geht es um viele gleichartige Objekte nebeneinander, führt die
[Übersichtsseite](https://flow.mittwald.de/templates/seiten/uebersichtsseite) dorthin.

---

# Aufbau

- **Content Header** – Eine [Heading](https://flow.mittwald.de/components/content/heading) als H1
  benennt das Objekt und macht klar, in welchem Bereich sich der Nutzer
  befindet. Eine [Breadcrumb](https://flow.mittwald.de/components/navigation/breadcrumb) ergänzt die
  Orientierung, navigiert im Seitenbaum und führt schnell auf übergeordnete
  Ebenen zurück; ihre Einträge bleiben möglichst generisch.
- **Aktionsmenü** – Ein [Button](https://flow.mittwald.de/components/actions/button) mit einem
  [ContextMenu](https://flow.mittwald.de/components/actions/context-menu) bündelt die wichtigsten
  Aktionen des Objekts und dient den Nutzern als Schnellzugriff.
- **Content** – Eine [LayoutCard](https://flow.mittwald.de/components/structure/layout-card) ist die
  Grundlage jeder Detailseite. Sie bildet den äußeren Container für den Inhalt
  und stellt Hintergrund und Padding bereit.
- **Themenblöcke** – [Sections](https://flow.mittwald.de/components/structure/section) gliedern den
  Content in Themenblöcke mit eigener H2-Überschrift und eigenen Aktionen im
  Header. Sie lassen sich beliebig verschachteln, um auch umfangreiche Inhalte
  strukturiert darzustellen. Ordne sie nach Wichtigkeit und staffle Details nach
  unten.
- **Tab-Unterseiten** (optional) – Bei umfangreichen Objekten verteilt eine
  [TabNavigation](https://flow.mittwald.de/components/navigation/tab-navigation) die Themenblöcke auf
  gleichrangige Unterseiten. Nutzer wechseln zwischen ihnen, ohne den Kontext
  des Objekts zu verlieren.

---

# Dashboard

```tsx
import {
  AlertBadge,
  Avatar,
  Button,
  ColumnLayout,
  Content,
  Header,
  Heading,
  IconCheck,
  IconEmail,
  Image,
  LayoutCard,
  Link,
  Section,
  Text,
  typedList,
} from "@mittwald/flow-react-components";

export default () => {
  const List = typedList<{
    title: string;
    date: string;
    status?: "info" | "warning" | "danger";
    isInvite?: boolean;
  }>();

  return (
    <ColumnLayout l={[1]} m={[1]}>
      <Heading color="dark" level={1}>
        Hey Max!
      </Heading>
      <ColumnLayout m={[1]} l={[3, 2]}>
        <ColumnLayout l={[1]} m={[1]}>
          <LayoutCard>
            <Section>
              <Header>
                <Heading>Benachrichtigungen</Heading>
                <Button
                  onPress={() => alert("not implemented")}
                  variant="soft"
                  color="secondary"
                >
                  Alle anzeigen
                </Button>
              </Header>
              <List.List
                hidePagination
                onAction={() => alert("not implemented")}
              >
                <List.StaticData
                  data={[
                    {
                      title:
                        "Projekteinladung: „Mein Projekt“",
                      date: "10.03.2025, 09:42 Uhr",
                      isInvite: true,
                    },
                    {
                      title:
                        "E-Mail-Empfang wurde deaktiviert",
                      date: "15.05.2025, 10:33 Uhr",
                      status: "danger",
                    },
                    {
                      title:
                        "E-Mail-Versand wurde gesperrt",
                      date: "15.05.2025, 10:33 Uhr",
                      status: "warning",
                    },
                    {
                      title: "Ticket wurde beantwortet",
                      date: "16.05.2025, 16:33 Uhr",
                      status: "info",
                    },
                  ]}
                />
                <List.Item textValue={(i) => i.title}>
                  {(i) => (
                    <List.ItemView>
                      {i.isInvite ? (
                        <Avatar>
                          <IconEmail />
                        </Avatar>
                      ) : (
                        <Avatar status={i.status} />
                      )}
                      <Heading>{i.title}</Heading>
                      <Text>{i.date}</Text>
                      <Content>
                        {i.isInvite ? (
                          <Button
                            onPress={() =>
                              alert("not implemented")
                            }
                            variant="soft"
                            color="secondary"
                          >
                            Öffnen
                          </Button>
                        ) : (
                          <Button
                            onPress={() =>
                              alert("not implemented")
                            }
                            aria-label="Erledigt"
                            variant="plain"
                            color="secondary"
                          >
                            <IconCheck />
                          </Button>
                        )}
                      </Content>
                    </List.ItemView>
                  )}
                </List.Item>
              </List.List>
            </Section>
          </LayoutCard>

          <LayoutCard>
            <Section>
              <Heading>mStudio entdecken</Heading>
              <Text>
                Du willst das Beste aus deinen Projekten
                herausholen? Unsere{" "}
                <Link href="#">Wissensdatenbank</Link> hilft
                dir dabei, das mStudio und seine
                Möglichkeiten besser kennenzulernen.
              </Text>
            </Section>
          </LayoutCard>
        </ColumnLayout>

        <ColumnLayout l={[1]} m={[1]}>
          <LayoutCard>
            <Section>
              <Heading>
                Status
                <AlertBadge status="success">
                  Alle Systeme funktionieren
                </AlertBadge>
              </Heading>
              <Text>
                Das mStudio und alle dazugehörenden Systeme
                laufen einwandfrei.
              </Text>
              <Link target="_blank" href="#">
                Zur Statusseite
              </Link>
            </Section>
          </LayoutCard>

          <LayoutCard>
            <Section>
              <Heading>Neues aus dem Blog</Heading>
              <Image
                src="https://flow.mittwald.de/assets/blog.png"
                alt=""
                aria-hidden
              />

              <Heading level={3}>
                Zukunft pflanzen – mittwald unterstützt 8000
                m² Aufforstung für den Klimaschutz
              </Heading>
              <Text>
                Nachhaltigkeitsmanager Marvin von mittwald
                berichtet über ein regionales
                Aufforstungsprojekt mit 8.000 m² neuem Wald.
              </Text>
              <Link href="#" target="_blank">
                Zum Blogartikel
              </Link>
            </Section>
          </LayoutCard>
        </ColumnLayout>
      </ColumnLayout>
    </ColumnLayout>
  );
}
```

---

# Verwendung

Verwende ein Dashboard, wenn Nutzer **mehrere Themen gleichzeitig** im Blick
behalten und die wichtigsten davon direkt erreichen sollen. Zeige nur, was einen
Mehrwert bietet, und ordne die Kacheln nach Relevanz. Geht es um viele
gleichartige Objekte in einer durchsuchbaren Liste, führt die
[Übersichtsseite](https://flow.mittwald.de/templates/seiten/uebersichtsseite) dorthin.

---

# Aufbau

- **Content Header** – Eine [Heading](https://flow.mittwald.de/components/content/heading) als H1
  benennt den Bereich, dessen Lage das Dashboard zusammenfasst.
- **Kachel-Anordnung** – Ein [ColumnLayout](https://flow.mittwald.de/components/structure/column-layout)
  verteilt die Kacheln über die verfügbaren Spalten und passt sich an
  unterschiedliche Breakpoints an.
- **Kacheln** – Jede Kachel ist eine
  [LayoutCard](https://flow.mittwald.de/components/structure/layout-card), in der
  [Sections](https://flow.mittwald.de/components/structure/section) den Inhalt in Header, Content und
  Footer gliedern. Jede Kachel bildet genau ein Thema ab.
- **Visuelle Aufbereitung** – Kennzahlen und Trends werden mit Komponenten wie
  [ProgressBar](https://flow.mittwald.de/components/status/progress-bar),
  [DonutChart](https://flow.mittwald.de/components/data-visualisation/donut-chart) oder einem
  [Image](https://flow.mittwald.de/components/content/image) sofort ablesbar; eine
  [AccentBox](https://flow.mittwald.de/components/structure/accent-box) hebt einzelne Kacheln gezielt
  hervor.

---

# Varianten und Abwandlung

## Detail-Dashboard

Ein Detail-Dashboard gibt einen schnellen Einblick in **ein einzelnes Objekt**:
Status, relevante Kennzahlen und Zusammenhänge, oft durch Diagramme
visualisiert. Dafür eignen sich [ProgressBar](https://flow.mittwald.de/components/status/progress-bar),
[DonutChart](https://flow.mittwald.de/components/data-visualisation/donut-chart),
[BigNumber](https://flow.mittwald.de/components/data-visualisation/big-number) und
[CartesianChart](https://flow.mittwald.de/components/data-visualisation/cartesian-chart).

```tsx
import {
  Breadcrumb,
  ColumnLayout,
  DonutChart,
  Flex,
  Header,
  Heading,
  Label,
  LabeledValue,
  LayoutCard,
  Link,
  ProgressBar,
  Section,
  Text,
} from "@mittwald/flow-react-components";

export default () => {
  return (
    <ColumnLayout l={[1]} m={[1]}>
      <Flex direction="column" gap="xs">
        <Breadcrumb color="dark">
          <Link href="#">Projekt</Link>
          <Link href="#">Dashboard</Link>
        </Breadcrumb>
        <Heading color="dark" level={1}>
          Dashboard
        </Heading>
      </Flex>
      <LayoutCard>
        <Section>
          <Heading>Projektdetails</Heading>
          <ColumnLayout>
            <LabeledValue>
              <Label>Short-ID</Label>
              <Text>p12345</Text>
            </LabeledValue>
            <LabeledValue>
              <Label>Server</Label>
              <Link href="#">Mein Server</Link>
            </LabeledValue>
          </ColumnLayout>
        </Section>
      </LayoutCard>
      <ColumnLayout l={[1, 1]} m={[1]}>
        <LayoutCard>
          <Section>
            <Header>
              <Heading>vCPU Auslastung</Heading>
              <Link href="#">Details</Link>
            </Header>
            <Flex
              columnGap="l"
              grow
              justify="center"
              rowGap="m"
              wrap="wrap"
            >
              <DonutChart
                aria-label="vCPU Auslastung"
                status="success"
                value={43}
              >
                <strong>43 %</strong>
              </DonutChart>
              <Flex direction="column" grow rowGap="m">
                <LabeledValue>
                  <Label>Messzeitpunkt</Label>
                  <Text>05.09.2025, 07:30 Uhr</Text>
                </LabeledValue>
                <LabeledValue>
                  <Label>Maximum (Letzte 7 Tage)</Label>
                  <Text>67 %</Text>
                </LabeledValue>
              </Flex>
            </Flex>
          </Section>
        </LayoutCard>
        <LayoutCard>
          <Section>
            <Header>
              <Heading>RAM Auslastung</Heading>
              <Link href="#">Details</Link>
            </Header>
            <Flex
              columnGap="l"
              grow
              justify="center"
              rowGap="m"
              wrap="wrap"
            >
              <DonutChart
                aria-label="RAM Auslastung"
                status="success"
                value={12}
              >
                <strong>12 %</strong>
              </DonutChart>
              <Flex direction="column" grow rowGap="m">
                <LabeledValue>
                  <Label>Messzeitpunkt</Label>
                  <Text>05.09.2025, 07:30 Uhr</Text>
                </LabeledValue>
                <LabeledValue>
                  <Label>Maximum (Letzte 7 Tage)</Label>
                  <Text>24 %</Text>
                </LabeledValue>
              </Flex>
            </Flex>
          </Section>
        </LayoutCard>
      </ColumnLayout>
      <LayoutCard>
        <Section>
          <Header>
            <Heading>Speicherplatz</Heading>
            <Link href="#">Details</Link>
          </Header>
          <ProgressBar
            value={2.3}
            maxValue={5}
            formatOptions={{
              style: "unit",
              unit: "gigabyte",
            }}
            showMaxValue
            size="l"
            status="success"
          >
            <Label>Speicherplatz</Label>
          </ProgressBar>
        </Section>
      </LayoutCard>
    </ColumnLayout>
  );
}
```

## Kachel mit AccentBox

Eine [AccentBox](https://flow.mittwald.de/components/structure/accent-box) setzt gezielt einen
farblichen Akzent, etwa für einen Hinweis oder eine Werbemaßnahme. Setze sie
sparsam ein – in der Regel genügt eine farbige Kachel, damit das Gesamtbild
ruhig bleibt.

```tsx
import {
  AccentBox,
  Breadcrumb,
  Button,
  ColumnLayout,
  Flex,
  Header,
  Heading,
  Icon,
  LayoutCard,
  Link,
  Section,
  Text,
} from "@mittwald/flow-react-components";
import { IconHeartHandshake } from "@tabler/icons-react";

export default () => {
  return (
    <ColumnLayout l={[1]} m={[1]}>
      <Flex direction="column" gap="xs">
        <Breadcrumb color="dark">
          <Link href="#">Organisation</Link>
          <Link href="#">Dashboard</Link>
        </Breadcrumb>
        <Heading color="dark" level={1}>
          Dashboard
        </Heading>
      </Flex>
      <ColumnLayout l={[1, 1]} m={[1]}>
        <LayoutCard>
          <Section>
            <Header>
              <Heading>Vertragspartner</Heading>
              <Button
                onPress={() => alert("not implemented")}
                color="secondary"
                variant="soft"
              >
                Bearbeiten
              </Button>
            </Header>
            <Text>
              Mittwald CM Service GmbH & Co.KG
              <br />
              Max Mustermann
              <br />
              Königsberger Straße 4-6, 32339 Espelkamp
              <br />
              mittwald@mittwald.de
              <br />
              +49 1234 5678910
            </Text>
          </Section>
        </LayoutCard>
        <LayoutCard>
          <Section>
            <Header>
              <Heading>Rechnungsempfänger</Heading>
              <Button
                onPress={() => alert("not implemented")}
                color="secondary"
                variant="soft"
              >
                Bearbeiten
              </Button>
            </Header>
            <Text>
              <strong>Rechnung</strong>
            </Text>
            <Text>
              Max Mustermann
              <br />
              Königsberger Straße 4-6, 32339 Espelkamp
              <br />
              mittwald@mittwald.de
              <br />
              +49 1234 5678910
            </Text>
          </Section>
        </LayoutCard>
      </ColumnLayout>
      <LayoutCard>
        <AccentBox color="dark">
          <Icon>
            <IconHeartHandshake />
          </Icon>
          <Section>
            <Heading>
              Entwickle deine eigene Extension
            </Heading>
            <Text>
              Du hast Lust als Organisation deine eigene
              Extension zu bauen und sie der Community
              bereitzustellen? Du hast vorab noch Fragen
              rund um die Contribution? Lass uns drüber
              quatschen.
            </Text>
            <Link href="#" target="_blank">
              Contributor werden
            </Link>
          </Section>
        </AccentBox>
      </LayoutCard>
    </ColumnLayout>
  );
}
```

---

# Übersichtsseite

```tsx
import {
  ActionGroup,
  Avatar,
  Button,
  Content,
  ContextMenu,
  ContextMenuTrigger,
  Flex,
  Heading,
  IconChevronDown,
  IconDomain,
  IconHome,
  IconInfo,
  IconMove,
  IconSubdomain,
  IconVhost,
  LayoutCard,
  ListItemView,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";

export default () => {
  const DomainList = typedList<{
    id: string;
    domain: string;
    type: string;
    target?: string;
  }>();

  return (
    <Flex direction="column" gap="m">
      <Heading level={1} color="dark">
        Domains
      </Heading>
      <LayoutCard>
        <DomainList.List
          aria-label="Domains"
          loadingItemsCount={3}
          getItemId={(domain) => domain.id}
        >
          <DomainList.StaticData
            data={[
              {
                id: "1",
                domain: "my-domain.de",
                type: "Domain",
                target: "Mein Blog",
              },
              {
                id: "2",
                domain: "www.my-domain.de",
                type: "Subdomain",
                target: "Mein Blog",
              },
              {
                id: "3",
                domain: "one-more-domain.com",
                type: "Domain",
                target: "Mein Shop",
              },
            ]}
          />
          <DomainList.Search />
          <DomainList.Filter name="Typ" property="type" />
          <DomainList.Item
            textValue={(domain) => domain.domain}
          >
            {(domain) => (
              <ListItemView>
                <Avatar
                  color={
                    domain.type === "Projekt-Domain"
                      ? "violet"
                      : domain.type === "Subdomain"
                        ? "green"
                        : domain.type === "Domain"
                          ? "blue"
                          : "teal"
                  }
                >
                  {domain.type === "Projekt-Domain" ? (
                    <IconHome />
                  ) : domain.type === "Subdomain" ? (
                    <IconSubdomain />
                  ) : domain.type === "Domain" ? (
                    <IconDomain />
                  ) : (
                    <IconVhost />
                  )}
                </Avatar>
                <Heading>{domain.domain}</Heading>
                <Text>{domain.type}</Text>
                <Content>
                  <small>
                    {domain.target
                      ? domain.target
                      : "Kein Ziel"}
                  </small>
                </Content>
                <ContextMenu>
                  <MenuItem>
                    <IconInfo />
                    <Text>Details anzeigen</Text>
                  </MenuItem>
                </ContextMenu>
              </ListItemView>
            )}
          </DomainList.Item>
          <ActionGroup>
            <ContextMenuTrigger>
              <Button>
                <Text>Hinzufügen</Text>
                <IconChevronDown />
              </Button>
              <ContextMenu>
                <MenuItem>
                  <IconDomain />
                  <Text>Domain bestellen</Text>
                </MenuItem>
                <MenuItem>
                  <IconMove />
                  <Text>Domain umziehen</Text>
                </MenuItem>
                <MenuItem>
                  <IconVhost />
                  <Text>vHost einrichten</Text>
                </MenuItem>
                <MenuItem>
                  <IconSubdomain />
                  <Text>Subdomain anlegen</Text>
                </MenuItem>
              </ContextMenu>
            </ContextMenuTrigger>
          </ActionGroup>
        </DomainList.List>
      </LayoutCard>
    </Flex>
  );
}
```

---

# Verwendung

Verwende die Übersichtsseite, wenn Nutzer aus **vielen gleichartigen Objekten**
das passende auswählen und anschließend im Detail bearbeiten sollen. Die Tiefe
eines einzelnen Objekts gehört auf seine
[Detailseite](https://flow.mittwald.de/templates/seiten/detailseite); ist die Liste nur ein Abschnitt
neben anderen Inhalten, gehört sie in ein
[Dashboard](https://flow.mittwald.de/templates/seiten/dashboard).

---

# Aufbau

- **Content Header** – Eine [Heading](https://flow.mittwald.de/components/content/heading) als H1
  benennt den Objekttyp, den die Seite auflistet.
- **Content** – Eine [LayoutCard](https://flow.mittwald.de/components/structure/layout-card) umschließt
  die [List](https://flow.mittwald.de/components/list/list), die das Hauptelement der Seite ist.
- **List** – Die [List](https://flow.mittwald.de/components/list/list) bringt Suche, Filter und
  Sortierung bereits mit. Je nach Inhalt lässt sich ihre Ansicht als Liste,
  Raster oder Tabelle wählen.
- **Eintrag** – Ein [List-Item](https://flow.mittwald.de/components/list/list-item-view) je Objekt
  verlinkt in seine [Detailseite](https://flow.mittwald.de/templates/seiten/detailseite) und trägt
  häufige Aktionen direkt am Objekt, etwa über ein
  [ContextMenu](https://flow.mittwald.de/components/actions/context-menu).
- **Anlege-Aktion** – Sie liegt in der
  [ActionGroup](https://flow.mittwald.de/components/actions/action-group) der List und bleibt so am
  Objekttyp, auch wenn die Liste später an anderer Stelle auftaucht.
- **Leerzustand** – Die List bringt automatisch eine
  [Empty View](https://flow.mittwald.de/components/list/list#lade-und-leeransichten-empty-view) mit;
  passe sie an das anzulegende Objekt an, denn der erste Kontakt mit einem
  Objekttyp ist fast immer die leere Liste.

---

# Varianten und Abwandlung

## Als Kachelansicht

In der Kachelansicht steht ein großes Vorschaubild im Vordergrund. So erkennen
Nutzer das passende Objekt auf einen Blick. Struktur und Ausstattung der Seite
bleiben gleich. Es ändern sich nur `defaultViewMode` und die Anzeigeform des
Eintrags.

```tsx
import {
  ActionGroup,
  Avatar,
  Button,
  ContextMenu,
  Flex,
  Heading,
  IconApp,
  LayoutCard,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";

export default () => {
  const AppList = typedList<{
    id: string;
    name: string;
    type: string;
    domain: string;
  }>();

  return (
    <Flex direction="column" gap="m">
      <Heading level={1} color="dark">
        Apps
      </Heading>
      <LayoutCard>
        <AppList.List
          aria-label="Apps"
          getItemId={(app) => app.id}
          defaultViewMode="tiles"
        >
          <ActionGroup>
            <Button>App installieren</Button>
          </ActionGroup>

          <AppList.StaticData
            data={[
              {
                id: "1",
                name: "Mein Blog",
                type: "WordPress",
                domain: "mustermann.de",
              },
              {
                id: "2",
                name: "Shop",
                type: "Shopware",
                domain: "shop.mustermann.de",
              },
              {
                id: "3",
                name: "Redaktion",
                type: "TYPO3",
                domain: "redaktion.mustermann.de",
              },
            ]}
          />
          <AppList.Search />

          <AppList.Item
            showTiles
            showList={false}
            href={() => "#"}
            textValue={(app) => app.name}
          >
            {(app) => (
              <AppList.ItemView>
                <Avatar color="violet">
                  <IconApp />
                </Avatar>
                <Heading>{app.name}</Heading>
                <Text>{app.type}</Text>
                <ContextMenu>
                  <MenuItem>Details anzeigen</MenuItem>
                  <MenuItem>Löschen</MenuItem>
                </ContextMenu>
              </AppList.ItemView>
            )}
          </AppList.Item>
        </AppList.List>
      </LayoutCard>
    </Flex>
  );
}
```

## Tabs über mehreren Übersichtsseiten

Manchmal gehören mehrere Objekttypen fachlich zusammen, etwa E-Mail-Adressen,
Weiterleitungen und Delivery-Boxen. Eine
[TabNavigation](https://flow.mittwald.de/components/navigation/tab-navigation) fasst sie zusammen. Jeder
Tab ist für sich eine Übersichtsseite.

---

# Anlegen & Bearbeiten

```tsx
import {
  Action,
  ActionGroup,
  Button,
  CheckboxButton,
  ColumnLayout,
  Content,
  FieldDescription,
  Heading,
  Label,
  Modal,
  NumberField,
  Option,
  PasswordCreationField,
  Section,
  Select,
  TextField,
  useModalController,
} from "@mittwald/flow-react-components";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { useForm } from "react-hook-form";

export default () => {
  const controller = useModalController();

  const form = useForm<{
    localPart: string;
    domain: string;
    password: string;
    storageInGb: number;
    spamProtection: boolean;
  }>({
    defaultValues: {
      localPart: "",
      domain: "mustermann.de",
      password: "",
      storageInGb: 2,
      spamProtection: true,
    },
  });

  const Field = typedField(form);

  const handleSubmit = async () => {
    /** ... anlegen */
    return () => {
      // Erst nach erfolgreichem Anlegen schließen
      controller.close();
    };
  };

  return (
    <>
      <Button onPress={controller.open}>
        E-Mail-Adresse anlegen
      </Button>

      <Modal controller={controller} offCanvas>
        <Form form={form} onSubmit={handleSubmit}>
          <Heading>E-Mail-Adresse anlegen</Heading>

          <Content>
            <Section>
              <ColumnLayout m={[2, 1]}>
                <Field
                  name="localPart"
                  rules={{
                    required:
                      "Bitte gib einen lokalen Teil ein",
                  }}
                >
                  <TextField>
                    <Label>Lokaler Teil</Label>
                    <FieldDescription>
                      Der Teil vor dem @
                    </FieldDescription>
                  </TextField>
                </Field>
                <Field
                  name="domain"
                  rules={{
                    required: "Bitte wähle eine Domain",
                  }}
                >
                  <Select>
                    <Label>Domain</Label>
                    <Option value="mustermann.de">
                      mustermann.de
                    </Option>
                    <Option value="muster-shop.de">
                      muster-shop.de
                    </Option>
                  </Select>
                </Field>
              </ColumnLayout>

              <Field
                name="password"
                rules={{
                  required: "Bitte vergib ein Passwort",
                }}
              >
                <PasswordCreationField>
                  <Label>Passwort</Label>
                </PasswordCreationField>
              </Field>
            </Section>

            <Section>
              <Heading>Speicherplatz</Heading>
              <Field
                name="storageInGb"
                rules={{
                  required:
                    "Bitte gib einen Speicherplatz an",
                }}
              >
                <NumberField
                  minValue={1}
                  formatOptions={{
                    style: "unit",
                    unit: "gigabyte",
                  }}
                >
                  <Label>Speicherplatz</Label>
                </NumberField>
              </Field>
            </Section>

            <Section>
              <Heading>Spamschutz</Heading>
              <Field name="spamProtection">
                <CheckboxButton>
                  Spamschutz aktivieren
                </CheckboxButton>
              </Field>
            </Section>
          </Content>

          <ActionGroup>
            <SubmitButton>Anlegen</SubmitButton>
            <Action closeModal>
              <Button variant="soft" color="secondary">
                Abbrechen
              </Button>
            </Action>
          </ActionGroup>
        </Form>
      </Modal>
    </>
  );
}
```

---

# Verwendung

Verwende dieses Overlay für Eingaben, die zu einem Objekt gehören: anlegen,
bearbeiten oder konfigurieren. Wird nichts eingegeben, sondern nur eine
Entscheidung getroffen, nimm ein Overlay zum
[Bestätigen](https://flow.mittwald.de/templates/overlays/bestaetigen); hängt die Eingabe von einer
vorgelagerten Auswahl ab, eines mit
[mehreren Schritten](https://flow.mittwald.de/templates/overlays/mehrere-schritte).

---

# Aufbau

- **Overlay-Container** – Ein [Modal](https://flow.mittwald.de/components/overlays/modal) legt sich über
  die auslösende Seite; nach dem Speichern kehrt der Nutzer an dieselbe Stelle
  zurück. Je nach Umfang des Formulars wird das mittige Modal gewählt oder – für
  lange, ausführliche Inhalte, die sonst im Modal scrollen müssten – die
  `offCanvas`-Variante.
- **Überschrift** – Eine [Heading](https://flow.mittwald.de/components/content/heading) benennt Aktion
  und Objekt, etwa „E-Mail-Adresse anlegen". Sie ist meist der einzige Hinweis
  auf den Bezug des Formulars, da die auslösende Seite verdeckt ist.
- **Formular** – Ein [Form](https://flow.mittwald.de/components/react-hook-form/form) fasst die Felder
  zusammen. Umfangreiche Formulare lassen sich mit
  [Sections](https://flow.mittwald.de/components/structure/section) in Abschnitte unterteilen.
- **Aktionen** – Das Formular wird über den
  [SubmitButton](https://flow.mittwald.de/components/react-hook-form/submit-button) in der
  [ActionGroup](https://flow.mittwald.de/components/actions/action-group) abgesendet. Sie enthält
  außerdem immer einen „Abbrechen"-Button, der das Overlay wieder schließt.

---

# Varianten und Abwandlung

## Bearbeiten

Anlegen und Bearbeiten teilen sich ein Template. Sie unterscheiden sich in
Überschrift, Button-Beschriftung und der Vorbelegung der Felder.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  CheckboxButton,
  ColumnLayout,
  Content,
  Heading,
  Label,
  Modal,
  NumberField,
  Section,
  TextField,
  useModalController,
} from "@mittwald/flow-react-components";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { useForm } from "react-hook-form";

export default () => {
  const controller = useModalController();

  const form = useForm<{
    description: string;
    storageInGb: number;
    spamProtection: boolean;
  }>({
    defaultValues: {
      description: "Persönliches Postfach",
      storageInGb: 2,
      spamProtection: true,
    },
  });

  const Field = typedField(form);

  const handleSubmit = async () => () => controller.close();

  return (
    <>
      <Button
        variant="soft"
        color="secondary"
        onPress={controller.open}
      >
        Bearbeiten
      </Button>

      <Modal controller={controller} offCanvas>
        <Form form={form} onSubmit={handleSubmit}>
          <Heading>E-Mail-Adresse bearbeiten</Heading>

          <Content>
            <Section>
              <ColumnLayout m={[1, 1]}>
                <Field name="description">
                  <TextField>
                    <Label>Beschreibung</Label>
                  </TextField>
                </Field>
                <Field
                  name="storageInGb"
                  rules={{
                    required:
                      "Bitte gib einen Speicherplatz an",
                  }}
                >
                  <NumberField
                    minValue={1}
                    formatOptions={{
                      style: "unit",
                      unit: "gigabyte",
                    }}
                  >
                    <Label>Speicherplatz</Label>
                  </NumberField>
                </Field>
              </ColumnLayout>
            </Section>

            <Section>
              <Heading>Spamschutz</Heading>
              <Field name="spamProtection">
                <CheckboxButton>
                  Spamschutz aktivieren
                </CheckboxButton>
              </Field>
            </Section>
          </Content>

          <ActionGroup>
            <SubmitButton>Speichern</SubmitButton>
            <Action closeModal>
              <Button variant="soft" color="secondary">
                Abbrechen
              </Button>
            </Action>
          </ActionGroup>
        </Form>
      </Modal>
    </>
  );
}
```

## Kurzes Formular

Bei wenigen Feldern ist das Formular im mittigen
[Modal](https://flow.mittwald.de/components/overlays/modal) gut aufgehoben. Hier kann der Fokus beim
Öffnen direkt in das erste [TextField](https://flow.mittwald.de/components/form-controls/text-field)
springen (`autoFocus`), sodass die Eingabe ohne weiteren Klick beginnt. Setze
`autoFocus` nur, wenn das Overlay ausschließlich diesem Eingabezweck dient –
sonst überspringen Screenreader-Nutzer den einleitenden Kontext aus Überschrift
und Beschreibung.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  Content,
  Heading,
  Label,
  Modal,
  Section,
  TextField,
  useModalController,
} from "@mittwald/flow-react-components";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { useForm } from "react-hook-form";

export default () => {
  const controller = useModalController();

  const form = useForm<{ description: string }>({
    defaultValues: { description: "Persönliches Postfach" },
  });

  const Field = typedField(form);

  const handleSubmit = async () => () => controller.close();

  return (
    <>
      <Button
        variant="soft"
        color="secondary"
        onPress={controller.open}
      >
        Beschreibung ändern
      </Button>

      <Modal controller={controller} size="s">
        <Form form={form} onSubmit={handleSubmit}>
          <Heading>Beschreibung ändern</Heading>
          <Content>
            <Section>
              <Field
                name="description"
                rules={{
                  required:
                    "Bitte gib eine Beschreibung ein",
                }}
              >
                <TextField autoFocus>
                  <Label>Beschreibung</Label>
                </TextField>
              </Field>
            </Section>
          </Content>
          <ActionGroup>
            <SubmitButton>Speichern</SubmitButton>
            <Action closeModal>
              <Button variant="soft" color="secondary">
                Abbrechen
              </Button>
            </Action>
          </ActionGroup>
        </Form>
      </Modal>
    </>
  );
}
```

## Fehlende Voraussetzung

Manchmal hängt das Anlegen an einer Voraussetzung, die noch fehlt – etwa ein
Vertragspartner, ohne den eine Extension nicht installiert werden kann. Ein
[Alert](https://flow.mittwald.de/components/status/alert) im Overlay erklärt die fehlende Voraussetzung
und bietet an, den nötigen Teilprozess direkt hier zu starten. So bleibt der
Nutzer im Kontext und kehrt nach dem Anlegen an dieselbe Stelle zurück. Die
abschließende Aktion bleibt deaktiviert, bis die Voraussetzung erfüllt ist.

```tsx
import {
  Action,
  ActionGroup,
  Alert,
  Button,
  Content,
  Heading,
  Label,
  Modal,
  Option,
  Section,
  Select,
  Text,
  useModalController,
} from "@mittwald/flow-react-components";

export default () => {
  const controller = useModalController();

  return (
    <>
      <Button onPress={controller.open}>
        Extension installieren
      </Button>

      <Modal controller={controller} offCanvas>
        <Heading>Extension installieren</Heading>

        <Content>
          <Section>
            <Text>
              Wähle die Organisation, in der die Extension
              bereitgestellt werden soll.
            </Text>

            <Select isRequired defaultSelectedKey="1">
              <Label>Organisation</Label>
              <Option value="1">Meine Organisation</Option>
              <Option value="2">
                Noch eine Organisation
              </Option>
            </Select>

            <Alert status="warning">
              <Heading>
                Kein Vertragspartner hinterlegt
              </Heading>
              <Content>
                <Text>
                  Für diese Organisation ist noch kein
                  Vertragspartner hinterlegt. Lege einen an,
                  um mit der Installation fortzufahren.
                </Text>
                <Button>Vertragspartner anlegen</Button>
              </Content>
            </Alert>
          </Section>
        </Content>

        <ActionGroup>
          <Button isDisabled>Installieren</Button>
          <Action closeModal>
            <Button variant="soft" color="secondary">
              Abbrechen
            </Button>
          </Action>
        </ActionGroup>
      </Modal>
    </>
  );
}
```

---

# Bestätigen

```tsx
import {
  Action,
  ActionGroup,
  Button,
  Content,
  Heading,
  Modal,
  ModalTrigger,
  Text,
} from "@mittwald/flow-react-components";

export default () => (
  <ModalTrigger>
    <Button color="danger" variant="solid">
      E-Mail-Adresse löschen
    </Button>
    <Modal>
      <Heading>E-Mail-Adresse löschen</Heading>
      <Content>
        <Text>
          Die E-Mail-Adresse <b>max@mustermann.de</b> und
          alle darin gespeicherten E-Mails werden gelöscht.
          Das lässt sich nicht rückgängig machen. Die
          Weiterleitung von <b>kontakt@mustermann.de</b> auf
          diese Adresse geht danach ins Leere.
        </Text>
      </Content>
      <ActionGroup>
        <Action closeModal>
          <Button color="danger">Löschen</Button>
          <Button variant="soft" color="secondary">
            Abbrechen
          </Button>
        </Action>
      </ActionGroup>
    </Modal>
  </ModalTrigger>
)
```

---

# Verwendung

Verwende dieses Overlay, wenn eine Aktion Daten unwiederbringlich entfernt,
etwas Kostenpflichtiges beendet oder weitere Objekte betrifft – etwa löschen,
kündigen oder eine Verknüpfung auflösen. Der Sinn dieses Overlays ist, den
Workflow bewusst zu unterbrechen und den Nutzer auf die Tragweite der Aktion
aufmerksam zu machen. Lässt sich eine Aktion dagegen sofort und mit geringem
Aufwand rückgängig machen, wirkt eine Rückfrage schnell lästig und das Overlay
ist verzichtbar.

---

# Aufbau

- **Overlay-Container** – Ein [Modal](https://flow.mittwald.de/components/overlays/modal) erscheint
  mittig und ist so groß wie sein Inhalt. Meist ist das Modal die richtige Wahl,
  da es um eine kurze Rückfrage geht; werden viele abhängige Objekte
  aufgelistet, die mitgelöscht werden, kann die `offCanvas`-Variante sinnvoll
  sein.
- **Überschrift und Folgen** – Die Überschrift ist kurz und prägnant. Ein
  [Text](https://flow.mittwald.de/components/content/text) darunter klärt den Nutzer verständlich über
  die Folgen der Aktion auf. Wichtige Informationen (z. B. das zu löschende
  Objekt) können mit **Fettschrift** hervorgehoben werden. Betrifft die Aktion
  weitere Objekte, werden sie hier genannt.
- **Aktionen** – Eine [ActionGroup](https://flow.mittwald.de/components/actions/action-group) trägt die
  bestätigende Aktion mit der Aktion als Verb, daneben ein zurückhaltendes
  „Abbrechen". Je nach Konsequenz nutzt die bestätigende Aktion einen
  [Button](https://flow.mittwald.de/components/actions/button) in `color="success"` oder
  `color="danger"`, um die Folge zu verdeutlichen.

---

# Varianten und Abwandlung

## Mit Eingabe der Bestätigung

Bei besonders folgenreichen Aktionen, etwa dem Löschen des eigenen Profils,
tippt der Nutzer den Namen des Objekts ab, bevor der Button aktiv wird.

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

export default () => {
  const profileName = "Max Mustermann";
  const [confirmation, setConfirmation] = useState("");

  return (
    <ModalTrigger>
      <Button color="danger" variant="solid">
        Profil löschen
      </Button>
      <Modal>
        <Heading>Profil löschen</Heading>
        <Content>
          <Section>
            <Text>
              Das Profil <b>{profileName}</b> wird mit allen
              zugehörigen Daten und Zugriffsrechten
              gelöscht. Das lässt sich nicht rückgängig
              machen.
            </Text>
            <TextField
              value={confirmation}
              onChange={setConfirmation}
              isRequired
            >
              <Label>Namen eingeben</Label>
              <FieldDescription>
                Tippe <b>{profileName}</b> ab, um das
                Löschen zu bestätigen.
              </FieldDescription>
            </TextField>
          </Section>
        </Content>
        <ActionGroup>
          <Action closeModal>
            <Button
              color="danger"
              isDisabled={confirmation !== profileName}
            >
              Profil löschen
            </Button>
            <Button variant="soft" color="secondary">
              Abbrechen
            </Button>
          </Action>
        </ActionGroup>
      </Modal>
    </ModalTrigger>
  );
}
```

---

# Anzeigen

```tsx
import {
  Action,
  ActionGroup,
  Button,
  CodeBlock,
  Content,
  Heading,
  Modal,
  ModalTrigger,
} from "@mittwald/flow-react-components";

export default () => {
  const log = `[2026-08-10 03:00:01] INFO  cron: starting job "backup-database"
[2026-08-10 03:00:01] INFO  backup: connecting to database "app_production"
[2026-08-10 03:00:02] INFO  backup: dumping database "app_production"
[2026-08-10 03:00:09] INFO  backup: 42 tables dumped, 1.284.902 rows total
[2026-08-10 03:00:14] INFO  backup: 248.6 MB written to /backups/2026-08-10.sql.gz
[2026-08-10 03:00:14] INFO  backup: verifying checksum sha256:9f2b…c41e
[2026-08-10 03:00:15] INFO  backup: upload to offsite storage "eu-central" started
[2026-08-10 03:00:22] INFO  backup: upload finished in 7.4s
[2026-08-10 03:00:22] WARN  backup: retention exceeded, removing /backups/2026-07-27.sql.gz
[2026-08-10 03:00:23] INFO  backup: 30 snapshots retained, oldest 2026-07-11
[2026-08-10 03:00:23] INFO  cron: job "backup-database" finished with exit code 0`;

  return (
    <ModalTrigger>
      <Button variant="soft" color="secondary">
        Log anzeigen
      </Button>
      <Modal size="m" offCanvas>
        <Heading>
          Cronjob „backup-database" – Durchlauf vom
          10.08.2026
        </Heading>
        <Content>
          <CodeBlock language="log" code={log} copyable />
        </Content>
        <ActionGroup>
          <Action closeModal>
            <Button variant="soft" color="secondary">
              Schließen
            </Button>
          </Action>
        </ActionGroup>
      </Modal>
    </ModalTrigger>
  );
}
```

---

# Verwendung

Verwende dieses Overlay für Inhalte, die zu einem Objekt gehören, die Seite aber
sprengen würden und aus denen keine weitere Aktion folgt: Details, Protokolle,
Vorschauen oder Belege. Wird etwas eingegeben, nimm ein Overlay zum
[Anlegen & Bearbeiten](https://flow.mittwald.de/templates/overlays/anlegen-bearbeiten); ist eine
Entscheidung zu treffen, eines zum
[Bestätigen](https://flow.mittwald.de/templates/overlays/bestaetigen). Was jeder Besucher dauerhaft
sehen soll, gehört fest auf die [Detailseite](https://flow.mittwald.de/templates/seiten/detailseite).

---

# Aufbau

- **Overlay-Container** – Bei wenig Inhalt eignet sich ein
  [Modal](https://flow.mittwald.de/components/overlays/modal), das mittig erscheint; bei viel Inhalt mit
  erwartetem Scrollen – etwa ein Log oder eine lange Liste – bietet sich die
  `offCanvas`-Variante an, die für sich scrollt.
- **Überschrift** – Eine [Heading](https://flow.mittwald.de/components/content/heading) benennt kurz das
  gezeigte Objekt.
- **Content** – Der Inhalt lässt sich mit
  [Sections](https://flow.mittwald.de/components/structure/section) und einem
  [ColumnLayout](https://flow.mittwald.de/components/structure/column-layout) übersichtlich
  strukturieren. Werte, die weiterverwendet werden, erhalten einen
  [CopyButton](https://flow.mittwald.de/components/actions/copy-button); das Overlay ist oft der einzige
  Ort, an dem ein Wert vollständig steht.
- **Aktion** – Eine [ActionGroup](https://flow.mittwald.de/components/actions/action-group) trägt als
  einzige Aktion „Schließen".

---

# Varianten und Abwandlung

## Einmal-Anzeige eines Geheimnisses

Ein Sonderfall, in dem das Overlay nach dem Anlegen erscheint: Das Ergebnis
enthält einen Wert, der später nicht erneut abrufbar ist – ein API-Token,
Recovery-Codes oder ein Auth-Code. Der Warnhinweis steht vor dem Wert, damit vor
dem Schließen klar ist, dass es keine zweite Gelegenheit gibt.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  Content,
  CopyButton,
  Heading,
  InlineCode,
  Label,
  LabeledValue,
  Modal,
  ModalTrigger,
  Section,
  Text,
} from "@mittwald/flow-react-components";

export default () => (
  <ModalTrigger>
    <Button>Geheimnis anzeigen</Button>
    <Modal>
      <Heading>API-Token kopieren</Heading>
      <Content>
        <Section>
          <Text>
            Dein persönlicher Token wird dir{" "}
            <b>nur einmalig</b> angezeigt. Speichere ihn an
            einem sicheren Ort ab.
          </Text>
          <LabeledValue>
            <Label>API-Token</Label>
            <InlineCode>
              0664f2ab-9556-4a96-a95c-ea72800f379c
            </InlineCode>
            <CopyButton text="0664f2ab-9556-4a96-a95c-ea72800f379c" />
          </LabeledValue>
        </Section>
      </Content>
      <ActionGroup>
        <Action closeModal>
          <Button variant="soft" color="secondary">
            Schließen
          </Button>
        </Action>
      </ActionGroup>
    </Modal>
  </ModalTrigger>
)
```

## IllustratedMessage

Eine [IllustratedMessage](https://flow.mittwald.de/components/content/illustrated-message) wird
verwendet, wenn eine Botschaft im Modal besonders hervorgehoben werden soll. Sie
eignet sich vor allem für wichtige Zustände wie
[Fehler](https://flow.mittwald.de/foundations/content-guidelines/fehlermeldungen#fehlermeldungen-anzeigen-bei-fehlgeschlagenen-aktionen),
leere Inhalte oder abgeschlossene Aktionen und macht diese visuell schnell
erfassbar.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  Content,
  Heading,
  IconDanger,
  IllustratedMessage,
  Modal,
  ModalTrigger,
  Text,
} from "@mittwald/flow-react-components";

export default () => (
  <ModalTrigger>
    <Button color="danger" variant="solid">
      E-Mail-Adresse löschen
    </Button>
    <Modal>
      <Content>
        <IllustratedMessage color="danger">
          <IconDanger />
          <Heading>Löschen fehlgeschlagen</Heading>
          <Text>
            Die E-Mail-Adresse konnte nicht gelöscht werden.
            Wir arbeiten daran, das Problem zu beheben.
            Bitte versuche es später noch einmal.
          </Text>
        </IllustratedMessage>
      </Content>
      <ActionGroup>
        <Action closeModal>
          <Button variant="soft" color="secondary">
            Schließen
          </Button>
        </Action>
      </ActionGroup>
    </Modal>
  </ModalTrigger>
)
```

---

# Mehrere Schritte

```tsx
import {
  Action,
  ActionGroup,
  Alert,
  Button,
  Content,
  FieldDescription,
  Heading,
  Label,
  Modal,
  NumberField,
  Option,
  RadioButton,
  RadioGroup,
  Section,
  Select,
  Text,
  TextArea,
  TextField,
  useModalController,
} from "@mittwald/flow-react-components";
import { useState } from "react";

type RecordType =
  "a" | "cname" | "mx" | "txt" | "caa" | "srv";
type Step = "selectType" | "configure";

export default () => {
  const controller = useModalController();
  const [step, setStep] = useState<Step>("selectType");
  const [type, setType] = useState<RecordType>("a");

  const recordTypes: {
    id: RecordType;
    name: string;
    description: string;
  }[] = [
    {
      id: "a",
      name: "A / AAAA",
      description:
        "Verweist den Namen auf eine IPv4- oder IPv6-Adresse.",
    },
    {
      id: "cname",
      name: "CNAME",
      description:
        "Verweist den Namen als Alias auf einen anderen Hostnamen.",
    },
    {
      id: "mx",
      name: "MX",
      description:
        "Legt fest, welcher Mailserver E-Mails für die Domain annimmt.",
    },
    {
      id: "txt",
      name: "TXT",
      description:
        "Hinterlegt einen frei wählbaren Text, etwa zur Verifizierung oder für SPF.",
    },
    {
      id: "caa",
      name: "CAA",
      description:
        "Bestimmt, welche Zertifizierungsstelle Zertifikate ausstellen darf.",
    },
    {
      id: "srv",
      name: "SRV",
      description:
        "Gibt an, unter welchem Host und Port ein Dienst erreichbar ist.",
    },
  ];

  // The heading takes up the selection: "DNS-Eintrag anlegen" becomes
  // e.g. "MX-Eintrag anlegen".
  const headlines: Record<RecordType, string> = {
    a: "A-/AAAA-Eintrag anlegen",
    cname: "CNAME-Eintrag anlegen",
    mx: "MX-Eintrag anlegen",
    txt: "TXT-Eintrag anlegen",
    caa: "CAA-Eintrag anlegen",
    srv: "SRV-Eintrag anlegen",
  };

  // Every record type carries a time-to-live.
  const ttlField = () => (
    <Select isRequired defaultSelectedKey="auto">
      <Label>TTL</Label>
      <Option value="auto">Automatisch</Option>
      <Option value="300">5 Minuten</Option>
      <Option value="3600">1 Stunde</Option>
      <Option value="14400">4 Stunden</Option>
      <Option value="86400">1 Tag</Option>
    </Select>
  );

  // The selected type decides which fields follow — that is why this is a
  // separate step and not a field in one form.
  const configFields = (recordType: RecordType) => {
    switch (recordType) {
      case "a":
        return (
          <>
            <Text>
              Mit einem A-Record (A steht für Address)
              leitest du eine Domain oder Subdomain an eine
              IP-Adresse weiter. Er ist also entscheidend
              für die Zuordnung von Domainnamen zu
              physischen Servern im Internet.
            </Text>
            {ttlField()}
            <TextField isRequired>
              <Label>IP-Adresse</Label>
            </TextField>
          </>
        );
      case "mx":
        return (
          <>
            <Text>
              Ein MX-Record leitet E-Mails an einen
              Mailserver weiter. Es ist üblich, für eine
              Domäne mehrere MX-Records zu definieren mit
              unterschiedlichen Prioritäten, so dass bei
              Ausfall eines Mail-Servers ein anderer die
              E-Mails entgegennehmen kann.
            </Text>
            {ttlField()}
            <TextField isRequired>
              <Label>Hostname</Label>
            </TextField>
            <NumberField isRequired>
              <Label>Priorität</Label>
            </NumberField>
          </>
        );
      case "txt":
        return (
          <>
            <Text>
              Ein TXT-Record ist ein Eintrag im DNS, mit dem
              ein frei definierbarer Text in einer DNS-Zone
              abgelegt werden kann.
            </Text>
            {ttlField()}
            <TextArea isRequired>
              <Label>Eintrag</Label>
            </TextArea>
          </>
        );
      case "caa":
        return (
          <>
            <Text>
              Mit einem CAA-Record (Certificate Authority
              Authorization) können Domain-Inhaber über das
              DNS festlegen, welche Zertifizierungsstellen
              berechtigt sind, Zertifikate für ihre Domain
              oder Subdomain auszustellen.
            </Text>
            {ttlField()}
            <Select isRequired defaultSelectedKey="iodef">
              <Label>Tag</Label>
              <Option value="issue">issue</Option>
              <Option value="issuewild">issuewild</Option>
              <Option value="iodef">iodef</Option>
            </Select>
            <Select isRequired defaultSelectedKey="128">
              <Label>Flag</Label>
              <Option value="128">128 (critical)</Option>
              <Option value="0">0 (undefined)</Option>
            </Select>
            <TextField isRequired>
              <Label>Domain</Label>
            </TextField>
          </>
        );
      case "cname":
        return (
          <>
            <Text>
              Ein Canonical Name- oder CNAME-Record ist ein
              DNS-Eintrag, der einen Aliasnamen dem
              eigentlichen oder kanonischen Domainnamen
              zuordnet.
            </Text>
            {ttlField()}
            <TextField isRequired>
              <Label>Ziel</Label>
            </TextField>
            <Alert status="info">
              <Heading>
                DNS-Records werden überschrieben
              </Heading>
              <Content>
                Wenn ein CNAME-Record für die DNS-Zone
                angelegt wird, werden alle bereits
                angelegten DNS-Records entfernt.
              </Content>
            </Alert>
          </>
        );
      case "srv":
        return (
          <>
            <Text>
              Mit einem SRV-Record kannst du einen Host und
              einen Port für spezifische Dienste angeben.
            </Text>
            {ttlField()}
            <TextField isRequired>
              <Label>Dienst</Label>
              <FieldDescription>
                z. B. _sip
              </FieldDescription>
            </TextField>
            <Select isRequired defaultSelectedKey="_tcp">
              <Label>Protokoll</Label>
              <Option value="_tcp">_tcp</Option>
              <Option value="_udp">_udp</Option>
            </Select>
            <NumberField isRequired>
              <Label>Priorität</Label>
            </NumberField>
            <NumberField isRequired>
              <Label>Gewichtung</Label>
            </NumberField>
            <NumberField isRequired>
              <Label>Port</Label>
            </NumberField>
            <TextField isRequired>
              <Label>Host</Label>
            </TextField>
          </>
        );
    }
  };

  return (
    <>
      <Button
        onPress={() => {
          setStep("selectType");
          setType("a");
          controller.open();
        }}
      >
        DNS-Eintrag anlegen
      </Button>

      <Modal controller={controller} offCanvas>
        <Heading>
          {step === "selectType"
            ? "DNS-Eintrag anlegen"
            : headlines[type]}
        </Heading>

        <Content>
          {step === "selectType" && (
            <Section>
              <Text>
                Wähle aus, welche Art von Eintrag du anlegen
                möchtest.
              </Text>
              <RadioGroup
                aria-label="Eintragstyp"
                value={type}
                onChange={(value) =>
                  setType(value as RecordType)
                }
              >
                {recordTypes.map((record) => (
                  <RadioButton
                    key={record.id}
                    value={record.id}
                  >
                    <Text>{record.name}</Text>
                    <Content>{record.description}</Content>
                  </RadioButton>
                ))}
              </RadioGroup>
            </Section>
          )}

          {step === "configure" && (
            <Section>{configFields(type)}</Section>
          )}
        </Content>

        <ActionGroup>
          {step === "selectType" && (
            <Button onPress={() => setStep("configure")}>
              Weiter
            </Button>
          )}
          {step === "configure" && (
            <>
              <Action closeModal>
                <Button color="success">Anlegen</Button>
              </Action>
              <Button
                slot="secondary"
                variant="soft"
                color="secondary"
                onPress={() => setStep("selectType")}
              >
                Zurück
              </Button>
            </>
          )}
          <Action closeModal>
            <Button variant="soft" color="secondary">
              Abbrechen
            </Button>
          </Action>
        </ActionGroup>
      </Modal>
    </>
  );
}
```

---

# Verwendung

Verwende mehrere Schritte, wenn eine Auswahl bestimmt, welche Eingaben danach
folgen, und diese Auswahl nicht nebenbei in einem Feld getroffen werden kann –
etwa weil Bild, Beschreibung oder Vergleich dazugehören. Stehen die Felder von
Anfang an fest, genügt ein Overlay zum
[Anlegen & Bearbeiten](https://flow.mittwald.de/templates/overlays/anlegen-bearbeiten).

---

# Aufbau

- **Overlay-Container** – Ein [Modal](https://flow.mittwald.de/components/overlays/modal), meist als
  `offCanvas`. Die Schritte sind Zustände darin, keine eigenen Seiten.
- **Auswahl am Anfang** – Der erste Schritt trifft die Auswahl, von der alle
  weiteren abhängen; eine Auswahl mitten im Vorgang würde vorherige Eingaben
  entwerten. Jeder Schritt bildet eine Entscheidung ab, nicht nur eine
  Feldergruppe.
- **Überschrift** – Eine [Heading](https://flow.mittwald.de/components/content/heading) wechselt mit dem
  Schritt und nimmt die Auswahl auf – aus „DNS-Eintrag anlegen" wird „MX-Eintrag
  anlegen".
- **Aktionen** – Eine [ActionGroup](https://flow.mittwald.de/components/actions/action-group) ordnet die
  Buttons nach Farbe: die weiterführende Aktion rechts, „Abbrechen" links. Der
  Zurück-Button führt zum vorherigen Schritt und erhält bei drei Buttons
  `slot="secondary"`, damit er nicht mit „Abbrechen" zusammenfällt. Bereits
  getätigte Eingaben bleiben beim Zurückgehen erhalten, soweit sie zur
  geänderten Auswahl noch passen.

---

# Varianten und Abwandlung

## Weitere Abwandlungen

**Ein Overlay öffnet ein zweites.** Muss während des Vorgangs ein noch nicht
vorhandenes Objekt angelegt werden – eine Subdomain, ein API-Key – geschieht das
in einem eigenen Overlay mit eigenem Controller, nicht als weiterer Schritt. Das
erste Overlay bleibt darunter geöffnet und behält, was bereits eingegeben wurde.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  ColumnLayout,
  Content,
  FieldDescription,
  Header,
  Heading,
  InlineCode,
  Label,
  Modal,
  Option,
  Section,
  Select,
  Text,
  TextField,
  useModalController,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const appController = useModalController();
  const subdomainController = useModalController();

  const [domains, setDomains] = useState([
    "mustermann.de",
    "muster-shop.de",
  ]);
  const [domain, setDomain] = useState<string | null>(null);
  const [subdomain, setSubdomain] = useState("");

  const addSubdomain = () => {
    const name = `${subdomain}.mustermann.de`;
    setDomains((all) => [...all, name]);
    setDomain(name);
    setSubdomain("");
    subdomainController.close();
  };

  return (
    <>
      <Button onPress={appController.open}>
        App anlegen
      </Button>

      <Modal controller={appController} offCanvas>
        <Heading>App anlegen</Heading>

        <Content>
          <Section>
            <ColumnLayout m={[2, 1]}>
              <TextField isRequired>
                <Label>Name</Label>
              </TextField>
              <Select
                isRequired
                defaultSelectedKey="6.7.14.1"
              >
                <Label>Version</Label>
                <Option value="6.7.14.1">6.7.14.1</Option>
                <Option value="6.7.13.0">6.7.13.0</Option>
                <Option value="6.6.10.7">6.6.10.7</Option>
              </Select>
            </ColumnLayout>

            <TextField isRequired>
              <Label>Installationsverzeichnis</Label>
              <FieldDescription>
                Deine App wird unter{" "}
                <InlineCode>
                  {"/html/<installationsverzeichnis>"}
                </InlineCode>{" "}
                installiert
              </FieldDescription>
            </TextField>
          </Section>

          <Section>
            <Header>
              <Heading>Hauptdomain zuweisen</Heading>
              {/*
               * Its own controller, not another step: the app overlay stays
               * open underneath and keeps what was already entered.
               */}
              <Button onPress={subdomainController.open}>
                Subdomain anlegen
              </Button>
            </Header>

            <Select
              isRequired
              placeholder="Domain wählen"
              selectedKey={domain}
              onChange={(key) => setDomain(String(key))}
            >
              <Label>Domain</Label>
              {domains.map((name) => (
                <Option key={name} value={name}>
                  {name}
                </Option>
              ))}
            </Select>
          </Section>
        </Content>

        <ActionGroup>
          <Action closeModal>
            <Button color="success">Anlegen</Button>
          </Action>
          <Action closeModal>
            <Button variant="soft" color="secondary">
              Abbrechen
            </Button>
          </Action>
        </ActionGroup>
      </Modal>

      <Modal controller={subdomainController}>
        <Heading>Subdomain anlegen</Heading>

        <Content>
          <Section>
            <Text>
              Eine Subdomain ist der Teil einer Domain, der
              vor dem eigentlichen Domainnamen steht und
              durch einen Punkt getrennt ist. Subdomains
              sind eine praktische Möglichkeit, verschiedene
              Bereiche einer Website voneinander zu trennen.
            </Text>

            <TextField
              isRequired
              value={subdomain}
              onChange={setSubdomain}
            >
              <Label>Subdomain</Label>
            </TextField>
          </Section>
        </Content>

        <ActionGroup>
          <Button
            color="success"
            isDisabled={subdomain.length === 0}
            onPress={addSubdomain}
          >
            Anlegen
          </Button>
          <Action closeModal>
            <Button variant="soft" color="secondary">
              Abbrechen
            </Button>
          </Action>
        </ActionGroup>
      </Modal>
    </>
  );
}
```

---

# Formular

```tsx
import {
  ActionGroup,
  ColumnLayout,
  Heading,
  Label,
  Section,
  TextField,
} from "@mittwald/flow-react-components";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { useForm } from "react-hook-form";

export default () => {
  const form = useForm<{
    firstName: string;
    lastName: string;
    street: string;
    houseNumber: string;
    zip: string;
    city: string;
    email: string;
    phone?: string;
  }>({
    defaultValues: {
      firstName: "",
      lastName: "",
      street: "",
      houseNumber: "",
      zip: "",
      city: "",
      email: "",
      phone: "",
    },
  });

  const Field = typedField(form);

  return (
    <Form
      form={form}
      onSubmit={() => console.log("submitted")}
    >
      <Section>
        <Heading>Rechnungsadresse</Heading>
        <ColumnLayout l={[1, 1]}>
          <Field
            name="firstName"
            rules={{
              required: "Bitte gib einen Vornamen ein",
            }}
          >
            <TextField>
              <Label>Vorname</Label>
            </TextField>
          </Field>
          <Field
            name="lastName"
            rules={{
              required: "Bitte gib einen Nachnamen ein",
            }}
          >
            <TextField>
              <Label>Nachname</Label>
            </TextField>
          </Field>
        </ColumnLayout>
        <ColumnLayout l={[1, 1]}>
          <ColumnLayout m={[2, 1]} s={[2, 1]}>
            <Field
              name="street"
              rules={{
                required: "Bitte gib eine Straße ein",
              }}
            >
              <TextField>
                <Label>Straße</Label>
              </TextField>
            </Field>
            <Field
              name="houseNumber"
              rules={{
                required: "Bitte gib eine Hausnr. ein",
              }}
            >
              <TextField>
                <Label>Hausnummer</Label>
              </TextField>
            </Field>
          </ColumnLayout>
          <ColumnLayout m={[1, 2]} s={[1, 2]}>
            <Field
              name="zip"
              rules={{
                required: "Bitte gib eine Postleitzahl ein",
              }}
            >
              <TextField>
                <Label>Postleitzahl</Label>
              </TextField>
            </Field>
            <Field
              name="city"
              rules={{
                required: "Bitte gib einen Ort ein",
              }}
            >
              <TextField>
                <Label>Ort</Label>
              </TextField>
            </Field>
          </ColumnLayout>
        </ColumnLayout>
        <ColumnLayout l={[1, 1]}>
          <Field
            name="email"
            rules={{
              required: "Bitte gib eine E-Mail-Adresse ein",
            }}
          >
            <TextField type="email">
              <Label>E-Mail-Adresse</Label>
            </TextField>
          </Field>
          <Field name="phone">
            <TextField>
              <Label>Telefonnummer</Label>
            </TextField>
          </Field>
        </ColumnLayout>
        <ActionGroup>
          <SubmitButton>Speichern</SubmitButton>
        </ActionGroup>
      </Section>
    </Form>
  );
}
```

---

# Verwendung

Verwende diesen Baustein, wenn Nutzer zusammengehörige Daten eingeben,
bearbeiten oder übermitteln. Im mStudio steht ein Formular meist in einem
Overlay zum [Anlegen & Bearbeiten](https://flow.mittwald.de/templates/overlays/anlegen-bearbeiten).

---

# Aufbau

- **Form** – Ein [Form](https://flow.mittwald.de/components/react-hook-form/form) klammert die Felder
  und verbindet sie über [Field](https://flow.mittwald.de/components/react-hook-form/field) mit React
  Hook Form. Es sammelt die Werte und übergibt sie beim Absenden.
- **Struktur** – [Sections](https://flow.mittwald.de/components/structure/section) gruppieren
  zusammengehörige Felder, ein
  [ColumnLayout](https://flow.mittwald.de/components/structure/column-layout) ordnet zusammengehörige
  Felder in eine Zeile – etwa Straße und Hausnummer oder PLZ und Ort. Ordne die
  Felder nach Wichtigkeit und stelle Zusammengehöriges nah beieinander.
- **Absenden** – Eine [ActionGroup](https://flow.mittwald.de/components/actions/action-group) trägt den
  [SubmitButton](https://flow.mittwald.de/components/react-hook-form/submit-button). Die Validierung
  erfolgt standardmäßig erst beim Absenden. Quick Submit sendet das Formular
  zusätzlich per ⌘/Strg + Enter aus jedem Feld ab – besonders hilfreich in einer
  [TextArea](https://flow.mittwald.de/components/form-controls/text-area) oder einem
  [MarkdownEditor](https://flow.mittwald.de/components/form-controls/markdown-editor).

### Field

Diese Punkte kehren über alle Form Controls hinweg wieder:

- **Label** – Ein gutes [Label](https://flow.mittwald.de/components/content/label) vermittelt alle
  notwendigen Informationen klar und prägnant (max. 2 Wörter). Felder sind
  standardmäßig Pflichtfelder; optionale Felder tragen den Zusatz „(optional)"
  am Label. Lässt sich die Anforderung aus dem Kontext erschließen, kann ein
  sichtbares Label entfallen – dann muss das Form Control über `aria-labelledby`
  verknüpft oder mit `aria-label` beschrieben sein.
- **Fields & Controls** – Das Design System bietet viele wiederverwendbare Form
  Controls: Fields wie [TextField](https://flow.mittwald.de/components/form-controls/text-field),
  [NumberField](https://flow.mittwald.de/components/form-controls/number-field) oder
  [PasswordCreationField](https://flow.mittwald.de/components/form-controls/password-creation-field)
  sowie Controls wie [Checkbox](https://flow.mittwald.de/components/form-controls/checkbox),
  [Select](https://flow.mittwald.de/components/form-controls/select) oder
  [RadioGroup](https://flow.mittwald.de/components/form-controls/radio-group). Alle findest du unter
  Components → Form Controls.
- **FieldDescription** – Die `<FieldDescription />` ist ein optionaler Hilfstext
  unterhalb des Form Controls. Verwende sie sparsam: nur, wenn das Label allein
  eine Frage offenlässt – etwa ein Beispiel, ein Format, eine Einheit, eine
  Einschränkung oder eine Konsequenz.
- **FieldError** – Ein ungültiges Field zeigt immer eine Fehlermeldung über die
  `<FieldError />`. Sie erklärt verständlich, warum die Eingabe ungültig ist,
  und hilft bei der Korrektur. Formulierungshinweise stehen in der Guideline zu
  [Fehlermeldungen](https://flow.mittwald.de/foundations/content-guidelines/fehlermeldungen).
- **Placeholder** – Ein Placeholder ersetzt kein Label: Er verschwindet bei der
  Eingabe und wird von Assistenztechnologien oft nicht zuverlässig erkannt.
  Nutze ein `Label` für essenzielle Anforderungen und eine `FieldDescription`
  für Beispiele oder Formatierungshinweise. Eine Ausnahme ist das
  [SearchField](https://flow.mittwald.de/components/form-controls/search-field) mit seinem
  kennzeichnenden Leading-Icon.

---

# Varianten und Abwandlung

## Mit Validierung

Nutze für die Validierung in der Regel
[React Hook Form](https://flow.mittwald.de/components/react-hook-form/form). Alternativ stehen
`isRequired` (für Pflichtfelder) und `validate` (für eigene Validierungen) zur
Verfügung. Bei ungültiger Eingabe wird das Field invalidiert; über die
`FieldError` kann eine Fehlermeldung ausgegeben werden.

```tsx
import {
  ActionGroup,
  Heading,
  Label,
  Section,
  TextArea,
} from "@mittwald/flow-react-components";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { useForm } from "react-hook-form";

export default () => {
  const form = useForm<{
    publicKey: string;
  }>({
    defaultValues: {
      publicKey: "",
    },
  });

  const Field = typedField(form);

  return (
    <Form
      form={form}
      onSubmit={() => console.log("submitted")}
    >
      <Section>
        <Heading>Validierung</Heading>
        <Field
          name="publicKey"
          rules={{
            required: "Bitte gib einen SSH-Key ein",
            validate: {
              isValid: (key) =>
                key.startsWith("rsa")
                  ? true
                  : "Der SSH-Key muss mit 'rsa' anfangen",
            },
            minLength: {
              value: 10,
              message:
                "Der SSH-Key muss mindestens 10 Zeichen lang sein",
            },
          }}
        >
          <TextArea maxLength={8000} showCharacterCount>
            <Label>SSH-Key</Label>
          </TextArea>
        </Field>

        <ActionGroup>
          <SubmitButton>Speichern</SubmitButton>
        </ActionGroup>
      </Section>
    </Form>
  );
}
```

## Progressive Disclosure

Felder erscheinen erst, wenn sie gebraucht werden. Ein übergeordnetes Control
wie eine [RadioGroup](https://flow.mittwald.de/components/form-controls/radio-group) oder eine
[Checkbox](https://flow.mittwald.de/components/form-controls/checkbox) blendet die abhängigen Felder ein
und hält das Formular so schlank.

```tsx
import {
  ActionGroup,
  ColumnLayout,
  Heading,
  Label,
  RadioButton,
  RadioGroup,
  Section,
  Text,
  TextField,
} from "@mittwald/flow-react-components";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { useForm, useWatch } from "react-hook-form";

export default () => {
  const form = useForm<{
    paymentMethod: "invoice" | "debit";
    accountHolder: string;
    iban: string;
  }>({
    defaultValues: {
      paymentMethod: "invoice",
      accountHolder: "",
      iban: "",
    },
  });

  const Field = typedField(form);

  const watchedPaymentMethod = useWatch({
    control: form.control,
    name: "paymentMethod",
  });

  return (
    <Form
      form={form}
      onSubmit={() => console.log("submitted")}
    >
      <Section>
        <Heading>Zahlungsart</Heading>
        <Field name="paymentMethod">
          <RadioGroup l={[1, 1]} aria-label="Zahlungsart">
            <RadioButton value="invoice">
              Rechnung
            </RadioButton>
            <RadioButton value="debit">
              Lastschrift
            </RadioButton>
          </RadioGroup>
        </Field>

        {watchedPaymentMethod === "invoice" && (
          <Text>
            Bitte bezahle deine Rechnungen innerhalb von 14
            Tagen.
          </Text>
        )}

        {watchedPaymentMethod === "debit" && (
          <ColumnLayout m={[1, 1]}>
            <Field
              name="accountHolder"
              rules={{
                required:
                  "Bitte gib einen Kontoinhaber ein",
              }}
            >
              <TextField>
                <Label>Kontoinhaber</Label>
              </TextField>
            </Field>
            <Field
              name="iban"
              rules={{
                required: "Bitte gib eine IBAN ein",
              }}
            >
              <TextField>
                <Label>IBAN</Label>
              </TextField>
            </Field>
          </ColumnLayout>
        )}

        <ActionGroup>
          <SubmitButton>Speichern</SubmitButton>
        </ActionGroup>
      </Section>
    </Form>
  );
}
```

---

# Multi-Upload

```tsx
import {
  Button,
  FileCard,
  FileCardList,
  FileDropZone,
  FileField,
  Heading,
  IconUpload,
  Section,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [files, setFiles] = useState<File[]>([]);

  return (
    <Section>
      <FileDropZone
        multiple
        onChange={(droppedFiles) => {
          if (droppedFiles) {
            setFiles((existingFiles) => [
              ...existingFiles,
              ...droppedFiles,
            ]);
          }
        }}
      >
        <IconUpload />
        <Heading>Dateien ablegen</Heading>
        <FileField>
          <Button>Dateien auswählen</Button>
        </FileField>
      </FileDropZone>

      <FileCardList>
        {files.map((file) => (
          <FileCard
            name={file.name}
            type={file.type}
            key={file.name}
            sizeInBytes={file.size}
            onDelete={() =>
              setFiles(
                files.filter((watched) => watched !== file),
              )
            }
          />
        ))}
      </FileCardList>
    </Section>
  );
}
```

---

# Verwendung

Verwende diesen Baustein, wenn Nutzer mehrere Dateien auf einmal auswählen und
vor dem Absenden noch prüfen oder einzelne wieder entfernen sollen. Für eine
einzelne Datei genügt ein [FileField](https://flow.mittwald.de/components/form-controls/file-field) oder
eine [FileDropZone](https://flow.mittwald.de/components/upload/file-drop-zone).

---

# Aufbau

- **Auswahl** – Eine [FileDropZone](https://flow.mittwald.de/components/upload/file-drop-zone) nimmt
  Dateien per Drag-and-drop entgegen und enthält ein
  [FileField](https://flow.mittwald.de/components/form-controls/file-field) für den Dateidialog.
  `multiple` erlaubt mehrere Dateien auf einmal.
- **Dateiliste** – Eine [FileCardList](https://flow.mittwald.de/components/upload/file-card-list) aus
  [FileCards](https://flow.mittwald.de/components/upload/file-card) zeigt die ausgewählten Dateien mit
  Name, Typ und Größe; über `onDelete` entfernt der Nutzer einzelne vor dem
  Upload.
- **Zwischenspeicher** – Die ausgewählten Dateien liegen in einem Array im State
  (`File[]`) und werden erst beim Absenden übertragen; bis dahin lassen sie sich
  prüfen und einzeln entfernen.

---

# Zeitintervalle

```tsx
import {
  Content,
  FieldError,
  Label,
  LabeledValue,
  Option,
  Section,
  Select,
  type SelectProps,
  Separator,
  Text,
  TextField,
  TimeField,
  type TimeFieldProps,
} from "@mittwald/flow-react-components";
import CronTime from "cron-time-generator";
import { type FC, useMemo, useState } from "react";
import {
  CronExpressionParser,
  CronFieldCollection,
  type HourRange,
  type SixtyRange,
} from "cron-parser";

export default () => {
  type Interval =
    | "ONE_MINUTE"
    | "FIVE_MINUTES"
    | "THIRTY_MINUTES"
    | "ONE_HOUR"
    | "ONE_DAY"
    | "SEVEN_DAYS"
    | "FOURTEEN_DAYS"
    | "THIRTY_DAYS"
    | "CUSTOM";

  const Intervals: Record<
    Interval,
    {
      label: string;
      toCronString: (lastCronString: string) => string;
      allowTimeEdit?: boolean;
      allowCustomEdit?: boolean;
    }
  > = {
    ONE_MINUTE: {
      label: "1 Minute",
      toCronString: () => CronTime.everyMinute(),
    },
    FIVE_MINUTES: {
      label: "5 Minuten",
      toCronString: () => CronTime.every(5).minutes(),
    },
    THIRTY_MINUTES: {
      label: "30 Minuten",
      toCronString: () => CronTime.every(30).minutes(),
    },
    ONE_HOUR: {
      label: "1 Stunde",
      toCronString: () => CronTime.everyHour(),
    },
    ONE_DAY: {
      label: "1 Tag",
      toCronString: () => CronTime.everyDay(),
      allowTimeEdit: true,
    },
    SEVEN_DAYS: {
      label: "7 Tage",
      toCronString: () => CronTime.every(7).days(),
      allowTimeEdit: true,
    },
    FOURTEEN_DAYS: {
      label: "14 Tage",
      toCronString: () => CronTime.every(14).days(),
      allowTimeEdit: true,
    },
    THIRTY_DAYS: {
      label: "30 Tage",
      toCronString: () => CronTime.every(30).days(),
      allowTimeEdit: true,
    },
    CUSTOM: {
      label: "Benutzerdefiniert",
      allowCustomEdit: true,
      toCronString: (lastCronString) => lastCronString,
    },
  };

  const CronTimeSelector: FC<{
    value?: string;
    onChange: (cronValue: string) => void;
  }> = ({ value = "", onChange }) => {
    const [errorMessage, setErrorMessage] = useState<
      string | null
    >(null);
    const [currentInterval, setInterval] =
      useState<Interval>("CUSTOM");

    const parseCronExpression = (cron: string) => {
      try {
        const expression = CronExpressionParser.parse(cron);
        setErrorMessage(null);
        return expression;
      } catch (error) {
        if (error instanceof Error) {
          setErrorMessage(error.message);
        } else {
          setErrorMessage(`invalid cron: ${cron}`);
        }

        return false;
      }
    };

    const currentCronExpression = useMemo(
      () => parseCronExpression(value),
      [value],
    );

    const nextIntervals = useMemo(() => {
      if (!currentCronExpression) {
        return;
      }

      return currentCronExpression.take(5).map((time) => (
        <Text key={time.toISOString()}>
          {time.toString()}
          <br />
        </Text>
      ));
    }, [currentCronExpression]);

    const intervalSettings = Intervals[currentInterval];
    const isValidCronExpression =
      currentCronExpression && !errorMessage;

    const handleIntervalChange: SelectProps["onChange"] = (
      selectValue,
    ) => {
      const newInterval = selectValue as Interval | null;
      if (!newInterval) {
        return;
      }

      setInterval(newInterval);
      const intervalSettings = Intervals[newInterval];

      if (onChange) {
        onChange(intervalSettings.toCronString(value));
      }
    };

    const handleTimeChange: TimeFieldProps["onChange"] = (
      v,
    ) => {
      if (onChange && currentCronExpression) {
        const modified = CronFieldCollection.from(
          currentCronExpression.fields,
          {
            hour: [(v ? v.hour : 0) as HourRange],
            minute: [(v ? v.minute : 0) as SixtyRange],
          },
        );

        onChange(modified.stringify());
      }
    };

    const handleCustomCronChange = (customCron: string) => {
      const newExpression = parseCronExpression(customCron);
      if (newExpression && onChange) {
        onChange(customCron);
      }
    };

    return (
      <Section>
        <Select
          isRequired
          value={currentInterval}
          onChange={handleIntervalChange}
        >
          <Label>Interval</Label>
          {Object.keys(Intervals).map((i) => (
            <Option key={i} value={i}>
              {Intervals[i as Interval].label}
            </Option>
          ))}
        </Select>
        {intervalSettings.allowTimeEdit && (
          <TimeField onChange={handleTimeChange}>
            <Label>Uhrzeit</Label>
          </TimeField>
        )}
        {intervalSettings.allowCustomEdit && (
          <TextField
            isRequired
            isInvalid={!isValidCronExpression}
            value={value}
            onChange={handleCustomCronChange}
          >
            <Label>Cron-Syntax</Label>
            {errorMessage && (
              <FieldError>{errorMessage}</FieldError>
            )}
          </TextField>
        )}
        <Separator />
        <LabeledValue>
          <Label>Nächste Ausführungen</Label>
          <Content>
            {isValidCronExpression && nextIntervals}
          </Content>
        </LabeledValue>
      </Section>
    );
  };

  // only necessary because CronTimeSelector is an inline component
  // which is a requirement in the demo page
  const MemorizedCronTimeSelector = useMemo(
    () => CronTimeSelector,
    [],
  );

  const [currentCronString, setCronString] =
    useState("0 0 * * *");

  return (
    <>
      <MemorizedCronTimeSelector
        value={currentCronString}
        onChange={setCronString}
      />
    </>
  );
}
```

---

# Verwendung

Verwende diesen Baustein, wenn Nutzer festlegen, in welchem Intervall eine
Aktion wiederholt ausgeführt wird – etwa beim Konfigurieren eines Cronjobs.
Reduziere die Auswahl auf die im Kontext sinnvollen Intervalle, damit die
Entscheidung leicht fällt.

---

# Aufbau

- **Intervall-Auswahl** – Ein [Select](https://flow.mittwald.de/components/form-controls/select) schlägt
  passende Zeitintervalle vor und hält die häufigen Fälle einfach. Sehr kleine
  Intervalle sind oft weder nötig noch ressourcenschonend; weise bei Bedarf mit
  einer [AccentBox](https://flow.mittwald.de/components/structure/accent-box) darauf hin.
- **Verfeinerung** – Je nach Auswahl wird dynamisch ein weiteres Feld
  eingeblendet, etwa ein [TimeField](https://flow.mittwald.de/components/form-controls/time-field) für
  die Uhrzeit. So bleibt die Oberfläche schlank und überfordert nicht. Dieses
  Ein- und Ausblenden folgt der
  [Progressive Disclosure](https://flow.mittwald.de/templates/bausteine/formular#varianten-und-abwandlung-progressive-disclosure)
  des Formular-Bausteins.
- **Benutzerdefiniert** – Die Option „Benutzerdefiniert" gibt über ein
  [TextField](https://flow.mittwald.de/components/form-controls/text-field) mit Cron-Syntax volle
  Kontrolle; ungültige Ausdrücke werden direkt am Feld gemeldet.
- **Vorschau** – Ein [LabeledValue](https://flow.mittwald.de/components/content/labeled-value) zeigt die
  nächsten Ausführungen zur Kontrolle. Kommuniziere die Zeitzone klar, in der
  das Intervall gilt, sonst entstehen falsche Erwartungen.

---

# Action

Die Action umschließt einen Button und gibt visuelles Feedback bei asynchronen Aktionen.

> **mStudio-Extensions:** Importiere `Action` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  Action,
  Button,
} from "@mittwald/flow-react-components";
import { sleep } from "@/content/components/actions/action/examples/lib";

<Action onAction={sleep}>
  <Button color="success">Speichern</Button>
</Action>
```

---

# Best Practices

- Nutze den Pending State nur für Vorgänge unter etwa fünf Sekunden. Für längere
  Prozesse eignet sich eher eine
  [Notification](https://flow.mittwald.de/components/status/notification).
- Setze Feedback States nur ein, wenn sie dem Nutzer einen Mehrwert bieten.

---

# Pending

Wenn eine asynchrone Aktion länger als 1000 Millisekunden dauert, wird der
**Pending** State angezeigt.

```tsx
import {
  Action,
  Button,
} from "@mittwald/flow-react-components";
import { sleepLong } from "@/content/components/actions/action/examples/lib";

<Action onAction={sleepLong}>
  <Button color="success">Speichern</Button>
</Action>
```

---

# Feedback

Wenn ein visuelles Feedback nach einer Userinteraktion angezeigt werden soll,
kann das Property `showFeedback` genutzt werden.

Solange die Aktion läuft oder Feedback anzeigt, nimmt der Button bzw. das
MenuItem keine Klicks an und ist als `aria-disabled` markiert.

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

<Action
  onAction={() => {
    // do nothing
  }}
  showFeedback
>
  <Button color="success">Speichern</Button>
</Action>
```

---

# Bestätigungsmodal

Um User vor unbeabsichtigten Aktionen zu schützen, kann ein Bestätigungsmodal
angezeigt werden. Dafür muss innerhalb der Action ein
[Modal](https://flow.mittwald.de/components/overlays/modal) mit dem Attribut `slot="actionConfirm"`
platziert werden.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  Content,
  Heading,
  Modal,
} from "@mittwald/flow-react-components";
import { sleepLong } from "@/content/components/actions/action/examples/lib";

<Action onAction={sleepLong}>
  <Modal slot="actionConfirm">
    <Heading>Projekt löschen</Heading>
    <Content>
      Wenn das Projekt &quot;Test&quot; einmal gelöscht ist,
      kann es nicht wiederhergestellt werden.
    </Content>
    <ActionGroup>
      <Button color="danger">Löschen</Button>
      <Button color="secondary" variant="soft">
        Abbrechen
      </Button>
    </ActionGroup>
  </Modal>
  <Button color="danger">Projekt löschen</Button>
</Action>
```

---

# Verschachtelte Actions

Wenn mehrere Aktionen auf eine Userinteraktion folgen, können Actions auch
ineinander verschachtelt werden.

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

<Action onAction={() => console.log("close modal")}>
  <Action onAction={() => console.log("save")}>
    <Button color="success">Speichern</Button>
  </Action>
</Action>
```

---

# In MenuItems

Actions können auch um `MenuItems` gelegt werden, um deren State zu steuern.

```tsx
import {
  Action,
  Button,
  ContextMenuTrigger,
  ContextMenu,
  MenuItem,
} from "@mittwald/flow-react-components";
import { sleepLong } from "@/content/components/actions/action/examples/lib";

<ContextMenuTrigger>
  <Button>Trigger</Button>
  <ContextMenu>
    <Action onAction={sleepLong}>
      <MenuItem>Herunterladen</MenuItem>
    </Action>
  </ContextMenu>
</ContextMenuTrigger>
```

---

# Actions abbrechen

Wenn eine Action abgebrochen werden soll, ohne einen Fehler auszulösen, kann die
Funktion `abortAction` aus dem Action-Modul verwendet werden. Diese Funktion
wirft einen speziellen Fehler, der von der Action-Component erkannt wird.
Dadurch kann die Action sauber abgebrochen werden, ohne dass unerwünschte
Fehlermeldungen oder Seiteneffekte auftreten.

Alle nachfolgenden Funktionen in der Action-Execution-Logik, die nach dem Aufruf
von `abortAction` definiert sind, werden nicht mehr ausgeführt. Das bedeutet,
dass der gesamte Ablauf der Action sofort gestoppt wird, sobald `abortAction`
aufgerufen wird.

Umschließende Actions bei einer Verschachtelung von Actions werden ebenfalls
abgebrochen, wenn `abortAction` in einer inneren Action aufgerufen wird.

```tsx
import { sleep } from "@/content/components/actions/action/examples/lib";
import {
  abortAction,
  Action,
  Button,
} from "@mittwald/flow-react-components";

<Action
  onAction={() => {
    console.log("Outer action");
  }}
>
  <Action
    onAction={async () => {
      await sleep();
      console.log("Inner action");
      abortAction();
    }}
  >
    <Button>Start action</Button>
  </Action>
</Action>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `actionModel` | `ActionModel` | - | An existing action model to use instead of creating a new one. Lets several components share one action state. |
| `break` | `boolean` | `false` | Stops the execution here: parent actions are not executed. |
| `children` | `ReactNode` | - | - |
| `closeModal` | `boolean \| CloseModalOptions` | - | Whether the surrounding modal is closed when the action is triggered. |
| `closeOverlay` | `boolean \| keyof FlowComponentPropsTypes \| OverlayController \| CloseOverlayOptions` | - | The overlay to close when the action is triggered. `true` closes the nearest enclosing overlay, whichever component it is — a name still wins, so `closeOverlay="Modal"` inside a `Popover` closes the outer modal. There is no `openOverlay={true}` counterpart: the nearest overlay is the one this action renders inside, so it is open by definition. |
| `openModal` | `boolean` | - | Whether the surrounding modal is opened when the action is triggered. |
| `openOverlay` | `keyof FlowComponentPropsTypes \| OverlayController` | - | The overlay to open when the action is triggered. |
| `showFeedback` | `boolean` | - | Whether success feedback is shown after the action succeeded. Asynchronous actions show feedback by default; set `false` to suppress it. |
| `skip` | `number \| boolean` | `false` | The number of parent actions skipped when the action is triggered. `true` skips one. |
| `toggleModal` | `boolean` | - | Whether the surrounding modal is opened or closed when the action is triggered. |
| `toggleOverlay` | `keyof FlowComponentPropsTypes \| OverlayController` | - | The overlay to open or close when the action is triggered. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onAction` | `ActionFn` | - | The function executed when the action is triggered. Returning a promise puts the action into its pending and feedback states automatically. |

---

# ActionGroup

Die ActionGroup gruppiert zusammengehörige Actions.

> **mStudio-Extensions:** Importiere `ActionGroup` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<ActionGroup>
  <Button color="success">Organisation erstellen</Button>
  <Button color="secondary" variant="soft">
    Abbrechen
  </Button>
</ActionGroup>
```

---

# Best Practices

- Für die Buttons in der ActionGroup gelten die
  [Best Practices des Buttons](https://flow.mittwald.de/components/actions/button).
- Hebe pro Seite möglichst nur eine Hauptaktion hervor. So erkennt der User den
  primären nächsten Schritt eindeutig.

---

# Slots

Die [Actions](https://flow.mittwald.de/components/actions/action) werden von der ActionGroup automatisch
in die Slots `primary`, `secondary` und `abort` sortiert. `primary` steht am
Ende der ActionGroup, `secondary` direkt davor und `abort` am Anfang. Die
Reihenfolge im Code spielt dabei keine Rolle.

Hat ein [Button](https://flow.mittwald.de/components/actions/button) keinen `slot`, entscheidet seine
Color: Primary (Standard), Success und Danger landen in `primary`, alle anderen
Colors in `abort`. Ein Button mit der Color Secondary, der nicht abbricht – etwa
„Nur prüfen“ oder „Als Entwurf speichern“ –, braucht deshalb `slot="secondary"`.
Sonst landet er neben „Abbrechen“ am Anfang der ActionGroup.

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

<ActionGroup>
  <Button color="success">E-Mail-Addresse anlegen</Button>
  <Button color="secondary" variant="soft" slot="secondary">
    Speichern und weitere anlegen
  </Button>
  <Button color="secondary" variant="soft">
    Abbrechen
  </Button>
</ActionGroup>
```

## Reihenfolge beibehalten

Mit `preserveOrder` verzichtet die ActionGroup auf die automatische Sortierung
in die Slots `primary`, `secondary` und `abort`. Die Actions bleiben in der
Reihenfolge, in der sie im Code stehen.

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

<ActionGroup preserveOrder>
  <Button color="secondary" variant="soft">
    Abbrechen
  </Button>
  <Button color="success">Organisation erstellen</Button>
</ActionGroup>
```

---

# Sizes

Mit `size` werden die Buttons und Links in der ActionGroup einheitlich
dimensioniert.

```tsx
import {
  ActionGroup,
  Button,
  Link,
} from "@mittwald/flow-react-components";

<ActionGroup size="s">
  <Link>Passwort vergessen?</Link>
  <Button>Anmelden</Button>
</ActionGroup>
```

---

# Kombiniere mit …

## Link

Kombiniere Buttons in der ActionGroup mit einem
[Link](https://flow.mittwald.de/components/navigation/link), um textuelle Nebenaktionen anzubieten.

```tsx
import {
  ActionGroup,
  Button,
  Link,
} from "@mittwald/flow-react-components";

<ActionGroup>
  <Link slot="abort">Passwort vergessen?</Link>
  <Button>Anmelden</Button>
</ActionGroup>
```

---

# Reihenfolge der Buttons

Es kann vorkommen, dass sich durch Rerendering die Reihenfolge der Buttons
ändert, wenn z. B. Inhalte nachgeladen werden. Um das zu verhindern, sollte um
diese `Inhalte` ein Suspense gelegt werden.

```
<ActionGroup>
  <Button>Projekt bearbeiten</Button>
  <ModalTrigger>
    <Button>Mitglieder anzeigen</Button>
    <Suspense>
      <Modal>...</Modal>
    </Suspense>
  </ModalTrigger>
</ActionGroup>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `preserveOrder` | `boolean` | `false` | When set, the buttons are not sorted into the slots `primary`, `secondary` and `abort` but stay in source order. Use it when the actions have no such hierarchy, e.g. a row of equal actions or icon buttons. |
| `size` | `"s" \| "m"` | `"m"` | The size of the buttons and links inside the action group. |
| `spacing` | `"s" \| "m"` | `"s"` | The spacing between the buttons inside the action group. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--action-group--spacing--m` | `16px` |
| `--action-group--spacing--s` | `8px` |

---

# Button

Buttons werden verwendet, um Aktionen auf einer Seite oder in einem Formular auszulösen.

> **mStudio-Extensions:** Importiere `Button` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

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

<Button
  onPress={() => {
    alert("Button gedrückt");
  }}
>
  Button
</Button>
```

---

# Best Practices

- Beschrifte den Button kurz und eindeutig. Ergänze ein `aria-label`, wenn der
  Kontext nicht klar ist, etwa bei einem reinen Icon-Button oder wenn der Text
  allein nicht ausreicht.
- Richte die visuelle Hierarchie nach der Wichtigkeit der Aktion. Nutze dafür
  die verschiedenen Varianten und Colors.
- Gib dem User nach der Aktion ein visuelles Feedback. Über die
  [Action](https://flow.mittwald.de/components/actions/action) lässt sich dieses Feedback steuern.

## Button vs. Link

Verwende für Navigation bevorzugt Links und für Aktionen Buttons. Eine Ausnahme
können hervorgehobene
[Call-to-Actions](https://flow.mittwald.de/components/navigation/link#kombiniere-mit-button) sein, bei
denen ein Button-ähnliches Erscheinungsbild für eine Navigation sinnvoll ist.

**Verwende Buttons, um z. B. ...**

- eine Aktion auszuführen oder ein Event zu starten, ohne die Seite zu verlassen.
- Formulare zu speichern oder zurückzusetzen.
- in einem [Modal](https://flow.mittwald.de/components/overlays/modal) Aktionen auszuwählen.

**Verwende Links, um z. B. ...**

- zu einer anderen Seite zu navigieren.
- zu einem Anker auf der Seite zu scrollen.
- eine externe Seite zu öffnen.
- einen Download zu starten.

---

# Variants

Verwende die unterschiedlichen Varianten, um Buttons in einer Oberfläche eine
visuelle Hierarchie zu geben:

- **Solid**, um Hauptaktionen hevrozuheben, die eine hohe Aufmerksamkeit
  erfordern.
- **Soft**, um Nebenaktionen abzuschwächen, die visuell keine hohe
  Aufmerksamkeit erfordern.
- **Outline**, um eine Aktion darzustellen, die klar als solche erkennbar sein
  soll, aber weniger Aufmerksamkeit als ein gefüllter Button beansprucht.
- **Plain**, um weniger wichtige oder zurückhaltende Aktionen darzustellen.

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

<>
  <Button>Solid</Button>
  <Button variant="soft">Soft</Button>
  <Button variant="outline">Outline</Button>
  <Button variant="plain">Plain</Button>
</>
```

---

# Color

Farben unterstützen die visuelle Hierarchie zusätzlich. Verwende:

- **Primary**, um Hauptaktionen standardmäßig visuell hervorzuheben.
- **Secondary**, um Nebenaktionen abzuschwächen und neutral darzustellen.
- **Success**, um die positive Bedeutung einer Aktion zu stärken. Diese Farbe
  wird daher vor allem im Kontext von Erstellungs-, Speicher- oder
  Bestellvorgängen verwendet.
- **Danger**, um negative Konsequenzen einer Aktion zu verdeutlichen. Sie wird
  beispielsweise für Lösch- oder Kündigungsaktionen verwendet.

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

<>
  <Button color="primary">Fortfahren/Aktion</Button>
  <Button color="secondary">Abbrechen/Zurück</Button>
  <Button color="success">Erstellen/Speichern</Button>
  <Button color="danger">Löschen/Kündigen</Button>
</>
```

## Light und Dark

Um auf farbigen Hintergründen ausreichend Kontrast zu erreichen, können Buttons
auch in Light und Dark eingesetzt werden. Mehr zur richtigen Verwendung von
Light und Dark findest du in den Foundations unter
[Color](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

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

<>
  <Button color="light">Light</Button>
  <Button variant="soft" color="light">
    Light
  </Button>
  <Button variant="outline" color="light">
    Light
  </Button>
  <Button variant="plain" color="light">
    Light
  </Button>
</>
```

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

<>
  <Button color="dark">Dark</Button>
  <Button variant="soft" color="dark">
    Dark
  </Button>
  <Button variant="outline" color="dark">
    Dark
  </Button>
  <Button variant="plain" color="dark">
    Dark
  </Button>
</>
```

---

# Sizes

**Medium** ist die Standardgröße und wird für die meisten Buttons verwendet.
**Small** kann genutzt werden, wenn weniger Platz vorhanden ist. Vermeide es,
unterschiedliche Button-Größen direkt nebeneinander zu verwenden.

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

<>
  <Button size="s">Small</Button>
  <Button>Medium</Button>
</>
```

---

# States

**Disabled** zeigt an, dass eine Aktion nicht ausgeführt werden kann. Achte
darauf, dass aus dem Kontext klar wird, warum die Aktion nicht zur Verfügung
steht.

Die States **Pending**, **Succeeded** und **Failed** geben dem User zusätzliches
visuelles Feedback darüber, dass im Hintergrund eine Aktion läuft, erfolgreich
abgeschlossen wurde oder fehlgeschlagen ist. Um diese States zu steuern, kann
die [Action](https://flow.mittwald.de/components/actions/action)-Komponente genutzt werden.

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

<>
  <Button isDisabled>Fortfahren/Aktion</Button>
  <Button isPending>Fortfahren/Aktion</Button>
  <Button isSucceeded>Fortfahren/Aktion</Button>
  <Button isFailed>Fortfahren/Aktion</Button>
</>
```

---

# Content

Der Content-Bereich eines Buttons kann entweder Text, ein
[Icon](https://flow.mittwald.de/components/content/icon) oder [Text](https://flow.mittwald.de/components/content/text) mit einem
Icon am Ende enthalten. Achte in allen Fällen darauf, dass Text und Icon die
Aktion eindeutig beschreiben.

## Icon

Wenn ausschließlich ein Icon verwendet wird, sollte das `aria-label` den
Verwendungszweck beschreiben. Ein [Tooltip](https://flow.mittwald.de/components/overlays/tooltip) kann
zusätzlich verdeutlichen, wofür die Aktion gedacht ist.

```tsx
import {
  Button,
  IconHome,
} from "@mittwald/flow-react-components";

<Button aria-label="Home">
  <IconHome />
</Button>
```

## Text + Icon

Der Default ist Text ohne Icon, das hält die Oberfläche ruhig. Ein Icon kommt
nur dazu, wenn es etwas beiträgt, das der Text allein nicht abdeckt:

- **Verhalten:** Das Icon zeigt, wie sich der Button verhält. Ein Chevron-Icon
  zeigt zum Beispiel an, dass sich dahinter ein
  [ContextMenu](https://flow.mittwald.de/components/actions/context-menu) verbirgt.
- **Erkennung:** Das Icon steht produktweit und ausschließlich für eine
  Feature-Familie, nach der User scannen, z. B. das AI-Icon neben „AI Agent
  verbinden".

Wiederholt das Icon nur das Wort (etwa eine Diskette neben „Speichern"), bringt
es nur Unruhe. Im Zweifel weglassen.

```tsx
import {
  Button,
  IconChevronDown,
  Text,
} from "@mittwald/flow-react-components";

<Button>
  <Text>E-Mail hinzufügen</Text>
  <IconChevronDown />
</Button>
```

---

# Kombiniere mit …

## Combine

Benutze die [Combine](https://flow.mittwald.de/components/structure/combine)-Component, um deinen Button
neben Input-Feldern zu platzieren.

```tsx
import {
  Combine,
  Button,
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<Combine>
  <TextField>
    <Label>Weiterleitungsziel</Label>
  </TextField>
  <Button>Hinzufügen</Button>
</Combine>
```

## ActionGroup

Benutze die [ActionGroup](https://flow.mittwald.de/components/actions/action-group)-Component, um
zusammengehörige Aktionen zu gruppieren und automatisch in eine konsistente
Hierarchie (Haupt- und Nebenaktion) zu bringen.

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

<ActionGroup>
  <Button color="success">Speichern</Button>
  <Button color="secondary" variant="soft">
    Abbrechen
  </Button>
</ActionGroup>
```

## Action

Benutze die [Action](https://flow.mittwald.de/components/actions/action)-Component, um die States eines
Buttons zu steuern.

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

<Action
  onAction={() =>
    new Promise((resolve) => setTimeout(resolve, 1500))
  }
>
  <Button color="success">Speichern</Button>
</Action>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | The children of the component. A function may be provided to alter the children based on component state. |
| `className` | `ClassNameOrFunction<ButtonRenderProps>` | `'react-aria-Button'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `color` | `"dark" \| "light" \| "dark-static" \| "light-static" \| "success" \| "danger" \| "primary" \| "secondary"` | `"primary"` | The color of the button. |
| `dir` | `string` | - | - |
| `excludeFromTabOrder` | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| `form` | `string` | - | The `<form>` element to associate the button with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#form). |
| `formAction` | `string \| ((formData: FormData) => void \| Promise<void>)` | - | The URL that processes the information submitted by the button. Overrides the action attribute of the button's form owner. |
| `formEncType` | `string` | - | Indicates how to encode the form data that is submitted. |
| `formMethod` | `string` | - | Indicates the HTTP method used to submit the form. |
| `formNoValidate` | `boolean` | - | Indicates that the form is not to be validated when it is submitted. |
| `formTarget` | `string` | - | Overrides the target attribute of the button's form owner. |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the button is disabled. |
| `isFailed` | `boolean` | - | Whether the button is in a failed state. |
| `isPending` | `boolean` | - | Whether the button is in a pending state. |
| `isReadOnly` | `boolean` | - | Whether the button is in a read only state. |
| `isSucceeded` | `boolean` | - | Whether the button is in a succeeded state. |
| `lang` | `string` | - | - |
| `name` | `string` | - | Submitted as a pair with the button's value as part of the form data. |
| `preventFocusOnPress` | `boolean` | - | Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `size` | `"s" \| "m"` | `"m"` | The size of the button. |
| `slot` | `string` | - | Slot for button placement in action groups: `primary` (at the end), `secondary` (before the primary action) or `abort` (at the start). Without a slot, an action group places the colors primary, success and danger in `primary` and every other color in `abort`. A secondary-colored button that does not abort therefore needs `slot="secondary"`. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `type` | `"button" \| "submit" \| "reset"` | `'button'` | The behavior of the button when used in an HTML form. |
| `value` | `string` | - | The value associated with the button's name when it's submitted with the form data. |
| `variant` | `"solid" \| "plain" \| "soft" \| "outline"` | `"solid"` | The visual variant of the button. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onClick` | `((e: MouseEvent<FocusableElement, MouseEvent>) => void)` | - | **Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions. |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onHoverChange` | `((isHovering: boolean) => void)` | - | Handler that is called when the hover state changes. |
| `onHoverEnd` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction ends. |
| `onHoverStart` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction starts. |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPress` | `((e: PressEvent) => void)` | - | Handler that is called when the press is released over the target. |
| `onPressChange` | `((isPressed: boolean) => void)` | - | Handler that is called when the press state changes. |
| `onPressEnd` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. |
| `onPressStart` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction starts. |
| `onPressUp` | `((e: PressEvent) => void)` | - | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-controls` | `string` | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| `aria-current` | `boolean \| "step" \| "false" \| "true" \| "page" \| "location" \| "date" \| "time"` | - | Indicates whether this element represents the current item within a container or set of related elements. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-disabled` | `boolean` | - | Disables button but keeps it focusable. |
| `aria-expanded` | `boolean \| "false" \| "true"` | - | Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed. |
| `aria-haspopup` | `boolean \| "false" \| "true" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` | - | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |
| `aria-pressed` | `boolean \| "false" \| "true" \| "mixed"` | - | Indicates the current "pressed" state of toggle buttons. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--button--corner-radius` | `8px` |
| `--button--padding-x` | `16px` |
| `--button--padding-y` | `8px` |
| `--button--padding-icon-only` | `8px` |
| `--button--spacing` | `0.5rem` |
| `--button--border-width` | `1px` |
| `--button--border-style` | `solid` |
| `--button--padding-s-icon-only` | `4px` |
| `--button--padding-s-x` | `8px` |
| `--button--padding-s-y` | `4px` |
| `--button--spacing-s` | `0.25rem` |
| `--button--font-size-s` | `0.875rem` |
| `--button--line-height-s` | `1rem` |
| `--button--corner-radius-s` | `4px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--button--pending-icon-color` | `#1B1F24` | `#FFFFFF` |
| `--button--success-solid-background-color--default` | `#00825B` | `#4FFFC9` |
| `--button--success-solid-background-color--hover` | `#005F42` | `#87FFDA` |
| `--button--success-solid-background-color--pressed` | `#003B29` | `#C0FFEB` |
| `--button--success-solid-background-color--disabled` | `#E5EFF8` | `#3A434E` |
| `--button--success-solid-content-color--default` | `#FFFFFF` | `#1B1F24` |
| `--button--success-solid-content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--button--success-plain-background-color--default` | `transparent` | `transparent` |
| `--button--success-plain-background-color--hover` | `#DCFFF4` | `#00291C` |
| `--button--success-plain-background-color--pressed` | `#C0FFEB` | `#003B29` |
| `--button--success-plain-background-color--disabled` | `transparent` | `transparent` |
| `--button--success-plain-content-color--default` | `#00825B` | `#4FFFC9` |
| `--button--success-plain-content-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--button--success-soft-background-color--default` | `#DCFFF4` | `#00291C` |
| `--button--success-soft-background-color--hover` | `#C0FFEB` | `#003B29` |
| `--button--success-soft-background-color--pressed` | `#87FFDA` | `#005F42` |
| `--button--success-soft-background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--button--success-soft-content-color--default` | `#005F42` | `#87FFDA` |
| `--button--success-soft-content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--button--success-outline-background-color--default` | `transparent` | `transparent` |
| `--button--success-outline-background-color--hover` | `#DCFFF4` | `#00291C` |
| `--button--success-outline-background-color--pressed` | `#C0FFEB` | `#003B29` |
| `--button--success-outline-background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--button--success-outline-content-color--default` | `#005F42` | `#87FFDA` |
| `--button--success-outline-content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--button--success-outline-border-color--default` | `#00825B` | `#4FFFC9` |
| `--button--success-outline-border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--button--primary-solid-background-color--default` | `#0054F5` | `#85AFFF` |
| `--button--primary-solid-background-color--hover` | `#003FB8` | `#ABC6FF` |
| `--button--primary-solid-background-color--pressed` | `#002A7B` | `#E0EBFF` |
| `--button--primary-solid-background-color--disabled` | `#E5EFF8` | `#3A434E` |
| `--button--primary-solid-content-color--default` | `#FFFFFF` | `#1B1F24` |
| `--button--primary-solid-content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--button--primary-plain-background-color--default` | `transparent` | `transparent` |
| `--button--primary-plain-background-color--hover` | `#F0F5FF` | `#00205C` |
| `--button--primary-plain-background-color--pressed` | `#E0EBFF` | `#002A7B` |
| `--button--primary-plain-background-color--disabled` | `transparent` | `transparent` |
| `--button--primary-plain-content-color--default` | `#0054F5` | `#85AFFF` |
| `--button--primary-plain-content-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--button--primary-soft-background-color--default` | `#F0F5FF` | `#00205C` |
| `--button--primary-soft-background-color--hover` | `#E0EBFF` | `#002A7B` |
| `--button--primary-soft-background-color--pressed` | `#ABC6FF` | `#003FB8` |
| `--button--primary-soft-background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--button--primary-soft-content-color--default` | `#003FB8` | `#ABC6FF` |
| `--button--primary-soft-content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--button--primary-outline-background-color--default` | `transparent` | `transparent` |
| `--button--primary-outline-background-color--hover` | `#F0F5FF` | `#00205C` |
| `--button--primary-outline-background-color--pressed` | `#E0EBFF` | `#002A7B` |
| `--button--primary-outline-background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--button--primary-outline-content-color--default` | `#003FB8` | `#ABC6FF` |
| `--button--primary-outline-content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--button--primary-outline-border-color--default` | `#0054F5` | `#85AFFF` |
| `--button--primary-outline-border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--button--secondary-solid-background-color--default` | `#3A434E` | `#E5EFF8` |
| `--button--secondary-solid-background-color--hover` | `#292F37` | `#F4F8FC` |
| `--button--secondary-solid-background-color--pressed` | `#1B1F24` | `#FFFFFF` |
| `--button--secondary-solid-background-color--disabled` | `#E5EFF8` | `#3A434E` |
| `--button--secondary-solid-content-color--default` | `#FFFFFF` | `#1B1F24` |
| `--button--secondary-solid-content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--button--secondary-plain-background-color--default` | `transparent` | `transparent` |
| `--button--secondary-plain-background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--button--secondary-plain-background-color--pressed` | `#DCE9F7` | `#5E6C7A` |
| `--button--secondary-plain-background-color--disabled` | `transparent` | `transparent` |
| `--button--secondary-plain-content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--button--secondary-plain-content-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--button--secondary-soft-background-color--default` | `#DCE9F7` | `#5E6C7A` |
| `--button--secondary-soft-background-color--hover` | `#B7C9DB` | `#8FA1B4` |
| `--button--secondary-soft-background-color--pressed` | `#8FA1B4` | `#B7C9DB` |
| `--button--secondary-soft-background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--button--secondary-soft-content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--button--secondary-soft-content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--button--secondary-outline-background-color--default` | `transparent` | `transparent` |
| `--button--secondary-outline-background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--button--secondary-outline-background-color--pressed` | `#DCE9F7` | `#5E6C7A` |
| `--button--secondary-outline-background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--button--secondary-outline-content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--button--secondary-outline-content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--button--secondary-outline-border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--button--secondary-outline-border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--button--danger-solid-background-color--default` | `#E1244C` | `#F2A2B3` |
| `--button--danger-solid-background-color--hover` | `#AB1737` | `#F7C1CC` |
| `--button--danger-solid-background-color--pressed` | `#710F24` | `#FBE0E6` |
| `--button--danger-solid-background-color--disabled` | `#E5EFF8` | `#3A434E` |
| `--button--danger-solid-content-color--default` | `#FFFFFF` | `#1B1F24` |
| `--button--danger-solid-content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--button--danger-plain-background-color--default` | `transparent` | `transparent` |
| `--button--danger-plain-background-color--hover` | `#FDF0F3` | `#540B1B` |
| `--button--danger-plain-background-color--pressed` | `#FBE0E6` | `#710F24` |
| `--button--danger-plain-background-color--disabled` | `transparent` | `transparent` |
| `--button--danger-plain-content-color--default` | `#E1244C` | `#F2A2B3` |
| `--button--danger-plain-content-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--button--danger-soft-background-color--default` | `#FDF0F3` | `#540B1B` |
| `--button--danger-soft-background-color--hover` | `#FBE0E6` | `#710F24` |
| `--button--danger-soft-background-color--pressed` | `#F7C1CC` | `#AB1737` |
| `--button--danger-soft-background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--button--danger-soft-content-color--default` | `#AB1737` | `#F7C1CC` |
| `--button--danger-soft-content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--button--danger-outline-background-color--default` | `transparent` | `transparent` |
| `--button--danger-outline-background-color--hover` | `#FDF0F3` | `#540B1B` |
| `--button--danger-outline-background-color--pressed` | `#FBE0E6` | `#710F24` |
| `--button--danger-outline-background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--button--danger-outline-content-color--default` | `#AB1737` | `#F7C1CC` |
| `--button--danger-outline-content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--button--danger-outline-border-color--default` | `#E1244C` | `#F2A2B3` |
| `--button--danger-outline-border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--button--dark-solid-background-color--default` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--button--dark-solid-background-color--hover` | `rgb(0 0 0 / 87.5%)` | `rgb(255 255 255 / 87.5%)` |
| `--button--dark-solid-background-color--pressed` | `rgb(0 0 0 / 75%)` | `rgb(255 255 255 / 75%)` |
| `--button--dark-solid-background-color--disabled` | `rgb(0 0 0 / 37.5%)` | `rgb(255 255 255 / 37.5%)` |
| `--button--dark-solid-content-color--default` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--button--dark-solid-content-color--disabled` | `rgb(255 255 255 / 37.5%)` | `rgb(0 0 0 / 37.5%)` |
| `--button--dark-plain-background-color--default` | `transparent` | `transparent` |
| `--button--dark-plain-background-color--hover` | `rgb(0 0 0 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--button--dark-plain-background-color--pressed` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--dark-plain-background-color--disabled` | `transparent` | `transparent` |
| `--button--dark-plain-content-color--default` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--button--dark-plain-content-color--disabled` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--dark-soft-background-color--default` | `rgb(0 0 0 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--button--dark-soft-background-color--hover` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--dark-soft-background-color--pressed` | `rgb(0 0 0 / 37.5%)` | `rgb(255 255 255 / 37.5%)` |
| `--button--dark-soft-background-color--disabled` | `rgb(0 0 0 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--button--dark-soft-content-color--default` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--button--dark-soft-content-color--disabled` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--dark-outline-background-color--default` | `transparent` | `transparent` |
| `--button--dark-outline-background-color--hover` | `rgb(0 0 0 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--button--dark-outline-background-color--pressed` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--dark-outline-background-color--disabled` | `transparent` | `transparent` |
| `--button--dark-outline-content-color--default` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--button--dark-outline-content-color--disabled` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--dark-outline-border-color--default` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--button--dark-outline-border-color--disabled` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--light-solid-background-color--default` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--button--light-solid-background-color--hover` | `rgb(255 255 255 / 87.5%)` | `rgb(0 0 0 / 87.5%)` |
| `--button--light-solid-background-color--pressed` | `rgb(255 255 255 / 75%)` | `rgb(0 0 0 / 75%)` |
| `--button--light-solid-background-color--disabled` | `rgb(255 255 255 / 37.5%)` | `rgb(0 0 0 / 37.5%)` |
| `--button--light-solid-content-color--default` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--button--light-solid-content-color--disabled` | `rgb(0 0 0 / 37.5%)` | `rgb(255 255 255 / 37.5%)` |
| `--button--light-plain-background-color--default` | `transparent` | `transparent` |
| `--button--light-plain-background-color--hover` | `rgb(255 255 255 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--button--light-plain-background-color--pressed` | `rgb(255 255 255 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--light-plain-background-color--disabled` | `transparent` | `transparent` |
| `--button--light-plain-content-color--default` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--button--light-plain-content-color--disabled` | `rgb(255 255 255 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--light-soft-background-color--default` | `rgb(255 255 255 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--button--light-soft-background-color--hover` | `rgb(255 255 255 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--light-soft-background-color--pressed` | `rgb(255 255 255 / 37.5%)` | `rgb(0 0 0 / 37.5%)` |
| `--button--light-soft-background-color--disabled` | `rgb(255 255 255 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--button--light-soft-content-color--default` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--button--light-soft-content-color--disabled` | `rgb(255 255 255 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--light-outline-background-color--default` | `transparent` | `transparent` |
| `--button--light-outline-background-color--hover` | `rgb(255 255 255 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--button--light-outline-background-color--pressed` | `rgb(255 255 255 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--light-outline-background-color--disabled` | `transparent` | `transparent` |
| `--button--light-outline-content-color--default` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--button--light-outline-content-color--disabled` | `rgb(255 255 255 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--light-outline-border-color--default` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--button--light-outline-border-color--disabled` | `rgb(255 255 255 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--dark-static-solid-background-color--default` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--button--dark-static-solid-background-color--hover` | `rgb(0 0 0 / 87.5%)` | `rgb(0 0 0 / 87.5%)` |
| `--button--dark-static-solid-background-color--pressed` | `rgb(0 0 0 / 75%)` | `rgb(0 0 0 / 75%)` |
| `--button--dark-static-solid-background-color--disabled` | `rgb(0 0 0 / 37.5%)` | `rgb(0 0 0 / 37.5%)` |
| `--button--dark-static-solid-content-color--default` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--button--dark-static-solid-content-color--disabled` | `rgb(255 255 255 / 37.5%)` | `rgb(255 255 255 / 37.5%)` |
| `--button--dark-static-plain-background-color--default` | `transparent` | `transparent` |
| `--button--dark-static-plain-background-color--hover` | `rgb(0 0 0 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--button--dark-static-plain-background-color--pressed` | `rgb(0 0 0 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--dark-static-plain-background-color--disabled` | `transparent` | `transparent` |
| `--button--dark-static-plain-content-color--default` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--button--dark-static-plain-content-color--disabled` | `rgb(0 0 0 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--dark-static-soft-background-color--default` | `rgb(0 0 0 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--button--dark-static-soft-background-color--hover` | `rgb(0 0 0 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--dark-static-soft-background-color--pressed` | `rgb(0 0 0 / 37.5%)` | `rgb(0 0 0 / 37.5%)` |
| `--button--dark-static-soft-background-color--disabled` | `rgb(0 0 0 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--button--dark-static-soft-content-color--default` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--button--dark-static-soft-content-color--disabled` | `rgb(0 0 0 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--dark-static-outline-background-color--default` | `transparent` | `transparent` |
| `--button--dark-static-outline-background-color--hover` | `rgb(0 0 0 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--button--dark-static-outline-background-color--pressed` | `rgb(0 0 0 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--dark-static-outline-background-color--disabled` | `transparent` | `transparent` |
| `--button--dark-static-outline-content-color--default` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--button--dark-static-outline-content-color--disabled` | `rgb(0 0 0 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--dark-static-outline-border-color--default` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--button--dark-static-outline-border-color--disabled` | `rgb(0 0 0 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--button--light-static-solid-background-color--default` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--button--light-static-solid-background-color--hover` | `rgb(255 255 255 / 87.5%)` | `rgb(255 255 255 / 87.5%)` |
| `--button--light-static-solid-background-color--pressed` | `rgb(255 255 255 / 75%)` | `rgb(255 255 255 / 75%)` |
| `--button--light-static-solid-background-color--disabled` | `rgb(255 255 255 / 37.5%)` | `rgb(255 255 255 / 37.5%)` |
| `--button--light-static-solid-content-color--default` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--button--light-static-solid-content-color--disabled` | `rgb(0 0 0 / 37.5%)` | `rgb(0 0 0 / 37.5%)` |
| `--button--light-static-plain-background-color--default` | `transparent` | `transparent` |
| `--button--light-static-plain-background-color--hover` | `rgb(255 255 255 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--button--light-static-plain-background-color--pressed` | `rgb(255 255 255 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--light-static-plain-background-color--disabled` | `transparent` | `transparent` |
| `--button--light-static-plain-content-color--default` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--button--light-static-plain-content-color--disabled` | `rgb(255 255 255 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--light-static-soft-background-color--default` | `rgb(255 255 255 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--button--light-static-soft-background-color--hover` | `rgb(255 255 255 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--light-static-soft-background-color--pressed` | `rgb(255 255 255 / 37.5%)` | `rgb(255 255 255 / 37.5%)` |
| `--button--light-static-soft-background-color--disabled` | `rgb(255 255 255 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--button--light-static-soft-content-color--default` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--button--light-static-soft-content-color--disabled` | `rgb(255 255 255 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--light-static-outline-background-color--default` | `transparent` | `transparent` |
| `--button--light-static-outline-background-color--hover` | `rgb(255 255 255 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--button--light-static-outline-background-color--pressed` | `rgb(255 255 255 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--light-static-outline-background-color--disabled` | `transparent` | `transparent` |
| `--button--light-static-outline-content-color--default` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--button--light-static-outline-content-color--disabled` | `rgb(255 255 255 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--button--light-static-outline-border-color--default` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--button--light-static-outline-border-color--disabled` | `rgb(255 255 255 / 25%)` | `rgb(255 255 255 / 25%)` |

---

# ContextMenu

Das ContextMenu öffnet ein Popover mit Aktionen oder Links, meist über einen Button.

> **mStudio-Extensions:** Importiere `ContextMenu` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `controller`, `render`, `renderEmptyState`, `style`, `wrapWith`.

```tsx
import {
  Button,
  ContextMenu,
  ContextMenuTrigger,
  MenuItem,
} from "@mittwald/flow-react-components";

<ContextMenuTrigger>
  <Button>Trigger</Button>
  <ContextMenu
    onAction={(id) => {
      alert(id);
    }}
  >
    <MenuItem id="1">Item 1</MenuItem>
    <MenuItem id="2">Item 2</MenuItem>
    <MenuItem id="3">Item 3</MenuItem>
  </ContextMenu>
</ContextMenuTrigger>
```

---

# Best Practices

- Sammle Aktionen in einem ContextMenu, um die Oberfläche aufgeräumt zu halten.
- Zeige nur kontextrelevante Inhalte.
- Benenne die Aktionen klar und verständlich.
- Stelle häufig genutzte Aktionen nach oben, damit sie leicht erreichbar sind.
- Gruppiere bei Bedarf mit einer [Section](https://flow.mittwald.de/components/structure/section) oder
  einem [Separator](https://flow.mittwald.de/components/structure/separator). Das erhöht die
  Übersichtlichkeit.

---

# Einfach-Auswahl

Durch `selectionMode="single"` verhalten sich die Menüeinträge des ContextMenu
wie eine [RadioGroup](https://flow.mittwald.de/components/form-controls/radio-group), sodass nur ein
Element ausgewählt werden kann.

```tsx
import {
  Button,
  ContextMenu,
  ContextMenuTrigger,
  MenuItem,
} from "@mittwald/flow-react-components";

<ContextMenuTrigger>
  <Button>Trigger</Button>
  <ContextMenu
    selectionMode="single"
    defaultSelectedKeys={["item2"]}
  >
    <MenuItem id="item1">Item 1</MenuItem>
    <MenuItem id="item2">Item 2</MenuItem>
    <MenuItem id="item3">Item 3</MenuItem>
  </ContextMenu>
</ContextMenuTrigger>
```

---

# Mehrfach-Auswahl

Durch `selectionMode="multiple"` verhalten sich die Menüeinträge des ContextMenu
wie [Checkboxen](https://flow.mittwald.de/components/form-controls/checkbox), sodass mehrere Optionen
ausgewählt werden können.

```tsx
import {
  Button,
  ContextMenu,
  ContextMenuTrigger,
  MenuItem,
} from "@mittwald/flow-react-components";

<ContextMenuTrigger>
  <Button>Trigger</Button>
  <ContextMenu
    selectionMode="multiple"
    defaultSelectedKeys={["item2", "item3"]}
  >
    <MenuItem id="item1">Item 1</MenuItem>
    <MenuItem id="item2">Item 2</MenuItem>
    <MenuItem id="item3">Item 3</MenuItem>
  </ContextMenu>
</ContextMenuTrigger>
```

---

# Mit Switch

Ein [Switch](https://flow.mittwald.de/components/form-controls/switch) im ContextMenu ermöglicht es,
Aktionen direkt zu aktivieren oder deaktivieren.

```tsx
import {
  Button,
  ContextMenu,
  ContextMenuTrigger,
  MenuItem,
} from "@mittwald/flow-react-components";

<ContextMenuTrigger>
  <Button>Trigger</Button>
  <ContextMenu selectionMode="switch">
    <MenuItem id="item1">Item 1</MenuItem>
    <MenuItem id="item2">Item 2</MenuItem>
    <MenuItem id="item3">Item 3</MenuItem>
  </ContextMenu>
</ContextMenuTrigger>
```

---

# Mit Icon

Verwende [Icons](https://flow.mittwald.de/components/content/icon) innerhalb vom `<MenuItem />`, um
Aktionen schneller verständlich zu machen oder bekannte Funktionen klarer zu
vermitteln.

```tsx
import {
  Button,
  ContextMenu,
  ContextMenuTrigger,
  IconDelete,
  IconDomain,
  IconInfo,
  MenuItem,
  Text,
} from "@mittwald/flow-react-components";

<ContextMenuTrigger>
  <Button>Trigger</Button>
  <ContextMenu
    onAction={(id) => {
      alert(id);
    }}
  >
    <MenuItem id="details">
      <IconInfo />
      <Text>Details anzeigen</Text>
    </MenuItem>
    <MenuItem id="open">
      <IconDomain />
      <Text>Im Browser öffnen</Text>
    </MenuItem>
    <MenuItem id="delete">
      <IconDelete />
      <Text>Löschen</Text>
    </MenuItem>
  </ContextMenu>
</ContextMenuTrigger>
```

---

# Mit Separator

Ein [Separator](https://flow.mittwald.de/components/structure/separator) gruppiert logisch
zusammengehörige Aktionen.

```tsx
import {
  Button,
  ContextMenu,
  ContextMenuTrigger,
  MenuItem,
  Separator,
} from "@mittwald/flow-react-components";

<ContextMenuTrigger>
  <Button>Trigger</Button>
  <ContextMenu>
    <MenuItem id="1">Item 1</MenuItem>
    <Separator />
    <MenuItem id="2">Item 2</MenuItem>
    <MenuItem id="3">Item 3</MenuItem>
  </ContextMenu>
</ContextMenuTrigger>
```

---

# Mit ContextMenuSections

Eine `ContextMenuSection` sorgt im ContextMenu für klare Struktur, indem sie
eine [Heading](https://flow.mittwald.de/components/content/heading) und definierte Abstände verwendet.

```tsx
import {
  Button,
  ContextMenu,
  ContextMenuSection,
  ContextMenuTrigger,
  Heading,
  MenuItem,
  Separator,
} from "@mittwald/flow-react-components";

<ContextMenuTrigger>
  <Button>Trigger</Button>
  <ContextMenu>
    <ContextMenuSection>
      <Heading>Section 1</Heading>
      <MenuItem id="1">Item 1</MenuItem>
      <MenuItem id="2">Item 2</MenuItem>
      <MenuItem id="3">Item 3</MenuItem>
    </ContextMenuSection>
    <Separator />
    <ContextMenuSection>
      <Heading>Section 2</Heading>
      <MenuItem id="4">Item 4</MenuItem>
      <MenuItem id="5">Item 5</MenuItem>
    </ContextMenuSection>
  </ContextMenu>
</ContextMenuTrigger>
```

---

# Mit fester Breite

Lege eine Breite für dein ContextMenu fest, um beispielsweise zu verhindern,
dass das ContextMenu zu breit wird oder die Breite des ContextMenus beim
Nachladen von Daten springt.

```tsx
import {
  Button,
  ContextMenu,
  ContextMenuTrigger,
  MenuItem,
} from "@mittwald/flow-react-components";

<ContextMenuTrigger>
  <Button>Trigger</Button>
  <ContextMenu
    width={300}
    onAction={(id) => {
      alert(id);
    }}
  >
    <MenuItem id="1">Mein Projekt</MenuItem>
    <MenuItem id="2">Mein zweites Projekt</MenuItem>
    <MenuItem id="3">
      Mein drittes Projekt mit einem sehr langen Namen
    </MenuItem>
  </ContextMenu>
</ContextMenuTrigger>
```

---

# Mit Selection Mode

Setze `selectionMode` direkt auf einer `ContextMenuSection`, um mehrere
Auswahlgruppen mit jeweils eigenem Auswahlverhalten zu kombinieren.

```tsx
import {
  Button,
  ContextMenu,
  ContextMenuSection,
  ContextMenuTrigger,
  MenuItem,
  Separator,
} from "@mittwald/flow-react-components";

<ContextMenuTrigger>
  <Button>Trigger</Button>
  <ContextMenu>
    <ContextMenuSection selectionMode="multiple">
      <MenuItem id="item1">Item 1</MenuItem>
      <MenuItem id="item2">Item 2</MenuItem>
      <MenuItem id="item3">Item 3</MenuItem>
    </ContextMenuSection>
    <Separator />
    <ContextMenuSection selectionMode="single">
      <MenuItem id="item1">Item 4</MenuItem>
      <MenuItem id="item2">Item 5</MenuItem>
      <MenuItem id="item3">Item 6</MenuItem>
    </ContextMenuSection>
  </ContextMenu>
</ContextMenuTrigger>
```

---

# Mit Avatar

Verwende das ContextMenu als Profilmenü, indem innerhalb ein
[Avatar](https://flow.mittwald.de/components/content/avatar) und eine
[Heading](https://flow.mittwald.de/components/content/heading) platziert werden.

```tsx
import {
  Avatar,
  Button,
  ContextMenu,
  ContextMenuTrigger,
  Heading,
  IconCamera,
  Initials,
  MenuItem,
  Section,
  Separator,
  Text,
} from "@mittwald/flow-react-components";

<ContextMenuTrigger>
  <Button>Trigger</Button>
  <ContextMenu selectionMode="navigation">
    <Section>
      <MenuItem>
        <Avatar>
          <Initials>Max Mustermann</Initials>
        </Avatar>
        <IconCamera />
      </MenuItem>
      <Heading>Max Mustermann</Heading>
    </Section>
    <Separator />
    <Section>
      <MenuItem>
        <Text>Settings</Text>
      </MenuItem>
      <MenuItem>
        <Text>Logout</Text>
      </MenuItem>
    </Section>
  </ContextMenu>
</ContextMenuTrigger>
```

---

# States

Ein MenuItem kann unterschiedliche States annehmen, die anzeigen, dass aktuell
keine Interaktion möglich ist.

- **Disabled** – Verwende den Disabled-State, wenn das MenuItem keine Aktion
  oder kein Ereignis auslösen soll.
- **Pending, Succeeded und Failed** – signalisieren dem Nutzer, dass im
  Hintergrund etwas passiert, nachdem er auf ein MenuItem geklickt hat. Verwende
  das MenuItem zusammen mit der Component [Action](https://flow.mittwald.de/components/actions/action),
  um die States zu steuern.

```tsx
import {
  Button,
  ContextMenu,
  ContextMenuTrigger,
  MenuItem,
} from "@mittwald/flow-react-components";

<ContextMenuTrigger>
  <Button>Trigger</Button>
  <ContextMenu>
    <MenuItem isDisabled>Disabled</MenuItem>
    <MenuItem isPending>Pending</MenuItem>
    <MenuItem isSucceeded>Succeeded</MenuItem>
    <MenuItem isFailed>Failed</MenuItem>
  </ContextMenu>
</ContextMenuTrigger>
```

---

# Kombiniere mit …

## Modal

Aktionen im ContextMenu können [Modals](https://flow.mittwald.de/components/overlays/modal) als Overlay
öffnen, wenn zusätzliche Informationen erfasst, bestätigt oder bearbeitet werden
müssen.

```tsx
import {
  ActionGroup,
  Button,
  Content,
  ContextMenu,
  ContextMenuTrigger,
  Heading,
  IconContextMenu,
  IconEdit,
  Label,
  MenuItem,
  Modal,
  TextField,
  Text,
  Action,
  useModalController,
  Section,
} from "@mittwald/flow-react-components";

export default () => {
  const modalController = useModalController();

  return (
    <>
      <ContextMenuTrigger>
        <Button variant="plain" color="secondary">
          <IconContextMenu />
        </Button>
        <ContextMenu>
          <MenuItem
            onAction={() => {
              modalController.open();
            }}
          >
            <IconEdit />
            <Text>Bearbeiten</Text>
          </MenuItem>
        </ContextMenu>
      </ContextMenuTrigger>
      <Modal controller={modalController}>
        <Heading>Bearbeiten</Heading>
        <Content>
          <Section>
            <TextField>
              <Label>Name</Label>
            </TextField>
          </Section>
        </Content>
        <ActionGroup>
          <Action closeModal>
            <Button color="success">Speichern</Button>
            <Button color="secondary" variant="soft">
              Abbrechen
            </Button>
          </Action>
        </ActionGroup>
      </Modal>
    </>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `UNSTABLE_portalContainer` _(deprecated)_ | `Element` | `document.body` | The container element in which the overlay portal will be placed. This may have unknown behavior depending on where it is portalled to. @deprecated - Use a parent UNSAFE_PortalProvider to set your portal container instead. |
| `arrowBoundaryOffset` | `number` | `0` | The minimum distance the arrow's edge should be from the edge of the overlay element. |
| `arrowRef` | `RefObject<Element \| null>` | - | A ref for the popover arrow element. |
| `boundaryElement` | `Element` | `document.body` | Element that that serves as the positioning boundary. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<PopoverRenderProps>` | `'react-aria-Popover'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `containerPadding` | `number` | `12` | The placement padding that should be applied between the element and its surrounding container. |
| `controller` | `OverlayController` | - | An overlay controller to control the popover state. |
| `crossOffset` | `number` | `0` | The additional offset applied along the cross axis between the element and its anchor element. |
| `defaultOpen` _(deprecated)_ | `boolean` | - | Whether the overlay is open by default (uncontrolled). @deprecated Use `isDefaultOpen` instead. |
| `defaultSelectedKeys` | `"all" \| Iterable<Key>` | - | The initial selected keys in the collection (uncontrolled). |
| `dir` | `string` | - | - |
| `disabledKeys` | `Iterable<Key>` | - | The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. |
| `getTargetRect` | `((target: Element) => DOMRect \| null)` | `target.getBoundingClientRect()` | Overrides the target element's bounding rectangle. Useful for positioning relative to a specific point such as the mouse cursor (e.g. context menus) or text selection. @param target - The target element. |
| `hidden` | `boolean` | - | - |
| `inert` | `boolean` | - | - |
| `isDefaultOpen` | `boolean` | `false` | Whether the popover is open initially. Use it for an uncontrolled popover. |
| `isDialogContent` | `boolean` | - | Whether the popover contains a dialog. |
| `isEntering` | `boolean` | - | Whether the popover is currently performing an entry animation. |
| `isExiting` | `boolean` | - | Whether the popover is currently performing an exit animation. |
| `isKeyboardDismissDisabled` | `boolean` | `false` | Whether pressing the escape key to close the popover should be disabled. Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided. |
| `isNonModal` | `boolean` | - | Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies. Most popovers should not use this option as it may negatively impact the screen reader experience. Only use with components such as combobox, which are designed to handle this situation carefully. |
| `isOpen` | `boolean` | - | Whether the popover is open. Use it to control the popover state – then `onOpenChange` must update the state this value comes from. |
| `lang` | `string` | - | - |
| `maxHeight` | `number` | - | The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height. |
| `offset` | `number` | `8` | The additional offset applied along the main axis between the element and its anchor element. |
| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `'bottom'` | The placement of the element with respect to its anchor element. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `renderEmptyState` | `(() => ReactNode)` | - | Provides content to display when there are no items in the menu. |
| `scrollRef` | `RefObject<Element \| null>` | `overlayRef` | A ref for the scrollable region within the overlay. |
| `selectedKeys` | `"all" \| Iterable<Key>` | - | The currently selected keys in the collection (controlled). |
| `selectionMode` | `"multiple" \| "navigation" \| "switch" \| "single"` | - | The type of selection that is allowed in the context menu. |
| `shouldCloseOnInteractOutside` | `((element: Element) => boolean)` | - | When user interacts with the argument element outside of the popover ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the popover. By default, onClose will always be called on interaction outside the popover ref. |
| `shouldFlip` | `boolean` | `true` | Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely. |
| `shouldSkipAnimation` | `boolean` | - | Whether the popover should appear and disappear without an entry or exit animation. This is used by components such as PreviewTrigger to skip animations when quickly swapping between overlays. |
| `shouldUpdatePosition` | `boolean` | `true` | Whether the overlay should update its position automatically. |
| `showSelectAll` | `boolean` | - | Adds a first entry that selects or deselects all items at once. Only applies to `selectionMode="multiple"`. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `trigger` | `string` | - | The name of the component that triggered the popover. This is reflected on the element as the `data-trigger` attribute, and can be used to provide specific styles for the popover depending on which element triggered it. |
| `triggerRef` | `RefObject<Element \| null>` | - | The ref for the element which the popover positions itself with respect to. When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone. |
| `width` | `string \| number` | - | Sets the context menu to a fixed width. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onAction` | `((key: Key, value: MenuItemProps) => void)` | - | Handler that is called when an item is selected. |
| `onBlurWithin` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the target element and all descendants lose focus. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onFocusWithin` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the target element or a descendant receives focus. |
| `onFocusWithinChange` | `((isFocusWithin: boolean) => void)` | - | Handler that is called when the the focus within state changes. |
| `onOpenChange` | `((isOpen: boolean) => void)` | - | Called with the new open state whenever the popover is opened or closed – on every path, including a close triggered through the controller. It only reports the change; it never performs or suppresses it. |
| `onSelectionChange` | `((keys: Selection) => void)` | - | Handler that is called when the selection changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--menu--item-to-item-spacing` | `4px` |
| `--menu--group-to-group-spacing` | `16px` |
| `--menu--select-all-to-item-spacing` | `8px` |
| `--menu-item--font-weight--current` | `bold` |
| `--menu-item--corner-radius` | `8px` |
| `--menu-item--padding-x` | `8px` |
| `--menu-item--padding-y` | `4px` |
| `--menu-item--spacing` | `0.5rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--menu-item--icon-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--menu-item--icon-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--menu-item--icon-color--current` | `#121518` | `#FFFFFF` |
| `--menu-item--background-color--default` | `transparent` | `transparent` |
| `--menu-item--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--menu-item--background-color--current` | `#DCE9F7` | `#5E6C7A` |
| `--menu-item--disabled-background-color` | `transparent` | `transparent` |
| `--menu-item--disabled-color` | `#DCE9F7` | `#5E6C7A` |

---

# CopyButton

Mit dem CopyButton können Informationen mit einem Klick in die Zwischenablage kopiert werden.

> **mStudio-Extensions:** Importiere `CopyButton` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `style`, `wrapWith`.

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

<CopyButton text="Kopierter Inhalt" />
```

---

# Best Practices

- Platziere den CopyButton unmittelbar neben dem zu kopierenden Text. Die
  [Combine](https://flow.mittwald.de/components/structure/combine)-Component hilft bei der Anordnung.
- Nutze standardmäßig die Secondary Color. So bleibt der CopyButton trotz
  häufiger Nutzung in der Oberfläche optisch zurückhaltend.

---

# Kombiniere mit …

## Combine

Benutze die [Combine](https://flow.mittwald.de/components/structure/combine)-Component, um einen
CopyButton neben dem zu kopierenden Text zu platzieren.

```tsx
import {
  Combine,
  CopyButton,
  Text,
} from "@mittwald/flow-react-components";

<Combine>
  <Text>mail.agenturserver.de</Text>
  <CopyButton text="mail.agenturserver.de" />
</Combine>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | The children of the component. A function may be provided to alter the children based on component state. |
| `className` | `ClassNameOrFunction<ButtonRenderProps>` | `'react-aria-Button'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `color` | `"dark" \| "light" \| "dark-static" \| "light-static" \| "success" \| "danger" \| "primary" \| "secondary"` | `"primary"` | The color of the button. |
| `dir` | `string` | - | - |
| `excludeFromTabOrder` | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| `form` | `string` | - | The `<form>` element to associate the button with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#form). |
| `formAction` | `string \| ((formData: FormData) => void \| Promise<void>)` | - | The URL that processes the information submitted by the button. Overrides the action attribute of the button's form owner. |
| `formEncType` | `string` | - | Indicates how to encode the form data that is submitted. |
| `formMethod` | `string` | - | Indicates the HTTP method used to submit the form. |
| `formNoValidate` | `boolean` | - | Indicates that the form is not to be validated when it is submitted. |
| `formTarget` | `string` | - | Overrides the target attribute of the button's form owner. |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the button is disabled. |
| `isFailed` | `boolean` | - | Whether the button is in a failed state. |
| `isPending` | `boolean` | - | Whether the button is in a pending state. |
| `isReadOnly` | `boolean` | - | Whether the button is in a read only state. |
| `isSucceeded` | `boolean` | - | Whether the button is in a succeeded state. |
| `lang` | `string` | - | - |
| `name` | `string` | - | Submitted as a pair with the button's value as part of the form data. |
| `preventFocusOnPress` | `boolean` | - | Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control. |
| `size` | `"s" \| "m"` | `"m"` | The size of the button. |
| `slot` | `string` | - | Slot for button placement in action groups: `primary` (at the end), `secondary` (before the primary action) or `abort` (at the start). Without a slot, an action group places the colors primary, success and danger in `primary` and every other color in `abort`. A secondary-colored button that does not abort therefore needs `slot="secondary"`. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `text` | `string` | - | The text to copy. |
| `translate` | `"yes" \| "no"` | - | - |
| `type` | `"button" \| "submit" \| "reset"` | `'button'` | The behavior of the button when used in an HTML form. |
| `value` | `string` | - | The value associated with the button's name when it's submitted with the form data. |
| `variant` | `"solid" \| "plain" \| "soft" \| "outline"` | `"solid"` | The visual variant of the button. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onClick` | `((e: MouseEvent<FocusableElement, MouseEvent>) => void)` | - | **Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions. |
| `onCopy` | `((text: string) => void)` | - | Called with the copied text once it has been written to the clipboard. Not called when copying fails. |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onHoverChange` | `((isHovering: boolean) => void)` | - | Handler that is called when the hover state changes. |
| `onHoverEnd` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction ends. |
| `onHoverStart` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction starts. |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPressChange` | `((isPressed: boolean) => void)` | - | Handler that is called when the press state changes. |
| `onPressEnd` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. |
| `onPressStart` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction starts. |
| `onPressUp` | `((e: PressEvent) => void)` | - | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-controls` | `string` | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| `aria-current` | `boolean \| "step" \| "false" \| "true" \| "page" \| "location" \| "date" \| "time"` | - | Indicates whether this element represents the current item within a container or set of related elements. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-disabled` | `boolean` | - | Disables button but keeps it focusable. |
| `aria-expanded` | `boolean \| "false" \| "true"` | - | Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed. |
| `aria-haspopup` | `boolean \| "false" \| "true" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` | - | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |
| `aria-pressed` | `boolean \| "false" \| "true" \| "mixed"` | - | Indicates the current "pressed" state of toggle buttons. |

---

# Chat

Der Chat kombiniert den MessageThread mit einer Texteingabe.

> **mStudio-Extensions:** Importiere `Chat` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import {
  Combine,
  Avatar,
  Button,
  Chat,
  Content,
  Header,
  Initials,
  Message,
  MessageSeparator,
  MessageThread,
  Text,
  TextArea,
} from "@mittwald/flow-react-components";

<Chat height={400}>
  <MessageThread>
    <MessageSeparator>Ticket geöffnet</MessageSeparator>
    <Message>
      <Header>
        <Combine>
          <Avatar>
            <Initials>Max Mustermann</Initials>
          </Avatar>
          <Text>
            <strong>Max Mustermann</strong>
          </Text>
        </Combine>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet consectetur adipisicing
          elit. Cumque eius quam quas vel voluptas, ullam
          aliquid fugit. Voluptate harum accusantium rerum
          ullam modi blanditiis vitae, laborum ea tempore,
          dolore voluptas. Earum pariatur, similique
          corrupti id officia perferendis. Labore,
          similique. Earum, quas in. At dolorem corrupti
          blanditiis nulla deserunt laborum! Corrupti
          delectus aspernatur nihil nulla obcaecati ipsam
          porro sequi rem? Quam.
        </Text>
      </Content>
    </Message>
    <Message type="sender">
      <Header>
        <Combine>
          <Avatar>
            <Initials>John Doe</Initials>
          </Avatar>
          <Text>
            <strong>John Doe</strong>
          </Text>
        </Combine>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet consectetur adipisicing
          elit. Cumque eius quam quas vel voluptas, ullam
          aliquid fugit. Voluptate harum accusantium rerum
          ullam modi blanditiis vitae, laborum ea tempore,
          dolore voluptas. Earum pariatur, similique
          corrupti id officia perferendis. Labore,
          similique. Earum, quas in.
        </Text>
      </Content>
    </Message>
  </MessageThread>
  <TextArea
    aria-label="Nachricht"
    rows={3}
    autoResizeMaxRows={10}
  />
  <Button color="success">Senden</Button>
</Chat>
```

---

# Best Practices

- Setze immer ein `aria-label` an der Texteingabe, da sie in der Regel kein
  sichtbares Label hat.
- Wähle die `height` Property so, dass genug Platz zum Lesen bleibt.

---

# Kombiniere mit ...

## FileField

Erweitere einen Chat um eine Uploadfunktion: Über ein
[FileField](https://flow.mittwald.de/components/form-controls/file-field) wählen User Dateien aus, die
dann in einer [FileCardList](https://flow.mittwald.de/components/upload/file-card-list) dargestellt
werden.

```tsx
import {
  Combine,
  Avatar,
  Button,
  Chat,
  Content,
  FileCard,
  FileCardList,
  FileField,
  Header,
  Initials,
  Message,
  MessageThread,
  Text,
  TextArea,
} from "@mittwald/flow-react-components";

<Chat>
  <MessageThread>
    <Message>
      <Header>
        <Combine>
          <Avatar>
            <Initials>Max Mustermann</Initials>
          </Avatar>
          <Text>
            <strong>Max Mustermann</strong>
          </Text>
        </Combine>
      </Header>
      <Content>
        <Text>
          Labore, similique. Earum, quas in. At dolorem
          corrupti blanditiis nulla deserunt laborum!
          Corrupti delectus aspernatur nihil nulla obcaecati
          ipsam porro sequi rem? Quam.
        </Text>
      </Content>
    </Message>
  </MessageThread>

  <TextArea
    aria-label="Nachricht"
    rows={3}
    autoResizeMaxRows={10}
  />

  <FileField>
    <Button variant="outline" color="secondary">
      Datei anhängen
    </Button>
  </FileField>
  <Button color="success">Senden</Button>
  <FileCardList>
    <FileCard name="Hochgeladene Datei 1" />
    <FileCard name="Hochgeladene Datei 2" />
  </FileCardList>
</Chat>
```

## Markdown Editor

Statt einer [TextArea](https://flow.mittwald.de/components/form-controls/text-area) kann auch der
[MarkdownEditor](https://flow.mittwald.de/components/form-controls/markdown-editor) als Texteingabe
verwendet werden.

```tsx
import {
  Combine,
  Avatar,
  Button,
  Chat,
  Content,
  Header,
  Initials,
  MarkdownEditor,
  Message,
  MessageSeparator,
  MessageThread,
  Text,
} from "@mittwald/flow-react-components";

<Chat height={400}>
  <MessageThread>
    <MessageSeparator>Ticket geöffnet</MessageSeparator>
    <Message>
      <Header>
        <Combine>
          <Avatar>
            <Initials>Max Mustermann</Initials>
          </Avatar>
          <Text>
            <strong>Max Mustermann</strong>
          </Text>
        </Combine>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet consectetur adipisicing
          elit. Cumque eius quam quas vel voluptas, ullam
          aliquid fugit. Voluptate harum accusantium rerum
          ullam modi blanditiis vitae, laborum ea tempore,
          dolore voluptas. Earum pariatur, similique
          corrupti id officia perferendis. Labore,
          similique. Earum, quas in. At dolorem corrupti
          blanditiis nulla deserunt laborum! Corrupti
          delectus aspernatur nihil nulla obcaecati ipsam
          porro sequi rem? Quam.
        </Text>
      </Content>
    </Message>
    <Message type="sender">
      <Header>
        <Combine>
          <Avatar>
            <Initials>John Doe</Initials>
          </Avatar>
          <Text>
            <strong>John Doe</strong>
          </Text>
        </Combine>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet consectetur adipisicing
          elit. Cumque eius quam quas vel voluptas, ullam
          aliquid fugit. Voluptate harum accusantium rerum
          ullam modi blanditiis vitae, laborum ea tempore,
          dolore voluptas. Earum pariatur, similique
          corrupti id officia perferendis. Labore,
          similique. Earum, quas in.
        </Text>
      </Content>
    </Message>
  </MessageThread>
  <MarkdownEditor
    aria-label="Nachricht"
    rows={3}
    autoResizeMaxRows={10}
  />
  <Button color="success">Senden</Button>
</Chat>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Combine,
  Avatar,
  Chat,
  Content,
  Header,
  Initials,
  Message,
  MessageThread,
  Text,
  TextArea,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Field,
  Form,
  SubmitButton,
} from "@mittwald/flow-react-components/react-hook-form";

export default () => {
  const form = useForm<{ message: string }>();

  return (
    <Chat>
      <MessageThread>
        <Message>
          <Header>
            <Combine>
              <Avatar>
                <Initials>Max Mustermann</Initials>
              </Avatar>
              <Text>
                <strong>Max Mustermann</strong>
              </Text>
            </Combine>
          </Header>
          <Content>
            <Text>
              Lorem ipsum dolor sit amet consectetur
              adipisicing elit. Cumque eius quam quas vel
              voluptas, ullam aliquid fugit. Voluptate harum
              accusantium rerum ullam modi blanditiis vitae,
              laborum ea tempore, dolore voluptas. Earum
              pariatur, similique corrupti id officia
              perferendis. Labore, similique. Earum, quas
              in. At dolorem corrupti blanditiis nulla
              deserunt laborum! Corrupti delectus aspernatur
              nihil nulla obcaecati ipsam porro sequi rem?
              Quam.
            </Text>
          </Content>
        </Message>
      </MessageThread>
      <Form
        form={form}
        onSubmit={() => {
          console.log("submitted");
        }}
      >
        <Field name="message">
          <TextArea
            aria-label="message"
            rows={3}
            autoResizeMaxRows={10}
          />
        </Field>
        <SubmitButton>Submit</SubmitButton>
      </Form>
    </Chat>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `height` | `Height<string \| number>` | - | The height of the chat. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--chat--spacing` | `8px` |

---

# Message

Eine Message stellt Nachrichten mit Autor-Informationen, Datum und Aktionen übersichtlich dar.

> **mStudio-Extensions:** Importiere `Message` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  Combine,
  Avatar,
  Button,
  Content,
  ContextMenu,
  ContextMenuTrigger,
  Header,
  Initials,
  MenuItem,
  Message,
  Text,
} from "@mittwald/flow-react-components";

<Message>
  <Header>
    <ContextMenuTrigger>
      <Button />
      <ContextMenu>
        <MenuItem>Bearbeiten</MenuItem>
        <MenuItem>Löschen</MenuItem>
      </ContextMenu>
    </ContextMenuTrigger>
    <Combine>
      <Avatar>
        <Initials>Max Mustermann</Initials>
      </Avatar>
      <Text>
        <strong>Max Mustermann</strong>
        Organisationsinhaber
      </Text>
    </Combine>
    <Text>01.09.2024, 12:45</Text>
  </Header>

  <Content>
    <Text>
      Lorem ipsum dolor sit amet, consetetur sadipscing
      elitr, sed diam nonumy eirmod tempor invidunt ut
      labore et dolore magna aliquyam erat, sed diam
      voluptua. At vero eos et accusam et justo duo dolores
      et ea rebum. Stet clita kasd gubergren, no sea
      takimata sanctus est Lorem ipsum dolor sit amet.
    </Text>
  </Content>
</Message>
```

---

# Best Practices

- Gruppiere mehrere Messages in einem
  [MessageThread](https://flow.mittwald.de/components/chat/message-thread).
- Halte das [ContextMenu](https://flow.mittwald.de/components/actions/context-menu) schlank. Es enthält
  nur direkt relevante Aktionen wie Bearbeiten und Löschen.

---

# Type

Eine Message hat im Default den Type `responder`. Mit dem Type `sender` ändern
sich Hintergrundfarbe und Anordnung der Message.

```tsx
import {
  Combine,
  Avatar,
  Button,
  Content,
  ContextMenu,
  ContextMenuTrigger,
  Header,
  Initials,
  MenuItem,
  Message,
  Text,
} from "@mittwald/flow-react-components";

<Message type="sender">
  <Header>
    <ContextMenuTrigger>
      <Button />
      <ContextMenu>
        <MenuItem>Bearbeiten</MenuItem>
        <MenuItem>Löschen</MenuItem>
      </ContextMenu>
    </ContextMenuTrigger>
    <Combine>
      <Avatar>
        <Initials>Max Mustermann</Initials>
      </Avatar>
      <Text>
        <strong>Max Mustermann</strong>
        Organisationsinhaber
      </Text>
    </Combine>
    <Text>01.09.2024, 12:45</Text>
  </Header>

  <Content>
    <Text>
      Lorem ipsum dolor sit amet, consetetur sadipscing
      elitr, sed diam nonumy eirmod tempor invidunt ut
      labore et dolore magna aliquyam erat, sed diam
      voluptua. At vero eos et accusam et justo duo dolores
      et ea rebum. Stet clita kasd gubergren, no sea
      takimata sanctus est Lorem ipsum dolor sit amet.
    </Text>
  </Content>
</Message>
```

---

# Custom Color

Über die `color` Property lässt sich eine Message gezielt hervorheben, etwa als
System-Nachricht oder interne Notiz. Setze für den Text eine statische Farbe wie
`dark-static` oder `light-static`, damit er unabhängig vom Theme lesbar bleibt.

```tsx
import {
  Content,
  Message,
  Text,
} from "@mittwald/flow-react-components";

<Message color="#ffeedd">
  <Content>
    <Text color="dark-static">
      Lorem ipsum dolor sit amet, consetetur sadipscing
      elitr, sed diam nonumy eirmod tempor invidunt ut
      labore et dolore magna aliquyam erat, sed diam
      voluptua. At vero eos et accusam et justo duo dolores
      et ea rebum. Stet clita kasd gubergren, no sea
      takimata sanctus est Lorem ipsum dolor sit amet.
    </Text>
  </Content>
</Message>
```

---

# Kombiniere mit ...

## ActionGroup

Ergänze eine Message um einen [Button](https://flow.mittwald.de/components/actions/button) oder eine
[ActionGroup](https://flow.mittwald.de/components/actions/action-group). Die Actions sollten immer in
direktem Bezug zum Inhalt der Message stehen.

```tsx
import {
  Combine,
  Avatar,
  Button,
  Content,
  ContextMenu,
  ContextMenuTrigger,
  Header,
  Initials,
  MenuItem,
  Message,
  Text,
  ActionGroup,
} from "@mittwald/flow-react-components";

<Message>
  <Header>
    <ContextMenuTrigger>
      <Button />
      <ContextMenu>
        <MenuItem>Bearbeiten</MenuItem>
        <MenuItem>Löschen</MenuItem>
      </ContextMenu>
    </ContextMenuTrigger>
    <Combine>
      <Avatar>
        <Initials>Max Mustermann</Initials>
      </Avatar>
      <Text>
        <b>Max Mustermann</b>
        Organisationsinhaber
      </Text>
    </Combine>
    <Text>01.09.2024, 12:45</Text>
  </Header>

  <Content>
    <Text>
      Lorem ipsum dolor sit amet, consetetur sadipscing
      elitr, sed diam nonumy eirmod tempor invidunt ut
      labore et dolore magna aliquyam erat, sed diam
      voluptua. At vero eos et accusam et justo duo dolores
      et ea rebum. Stet clita kasd gubergren, no sea
      takimata sanctus est Lorem ipsum dolor sit amet.
    </Text>
  </Content>
  <ActionGroup>
    <Button variant="soft" color="secondary">
      Secondary
    </Button>
    <Button>Primary</Button>
  </ActionGroup>
</Message>
```

## Markdown

Nutze die [Markdown](https://flow.mittwald.de/components/content/markdown)-Component, um den Text einer
Message als Markdown zu rendern.

```tsx
import {
  Combine,
  Avatar,
  Button,
  Content,
  ContextMenu,
  ContextMenuTrigger,
  Header,
  Initials,
  MenuItem,
  Message,
  Text,
  Markdown,
} from "@mittwald/flow-react-components";

<Message>
  <Header>
    <ContextMenuTrigger>
      <Button />
      <ContextMenu>
        <MenuItem>Bearbeiten</MenuItem>
        <MenuItem>Löschen</MenuItem>
      </ContextMenu>
    </ContextMenuTrigger>
    <Combine>
      <Avatar>
        <Initials>Max Mustermann</Initials>
      </Avatar>
      <Text>
        <strong>Max Mustermann</strong>
        Organisationsinhaber
      </Text>
    </Combine>
    <Text>01.09.2024, 12:45</Text>
  </Header>

  <Content>
    <Markdown>
      Lorem ipsum dolor sit amet, consetetur **sadipscing
      elitr**, sed diam nonumy eirmod tempor invidunt ut
      labore et dolore magna aliquyam erat, sed *diam
      voluptua*. At vero eos et accusam et justo duo dolores
      et ea rebum. Stet clita kasd gubergren, no sea
      takimata sanctus est Lorem ipsum ***dolor sit amet***.
    </Markdown>
  </Content>
</Message>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `color` | `string` | - | A custom background color of the message as a CSS color value. |
| `elementType` | `"article" \| ExoticComponent<{}> \| "li"` | - | The HTML element or React component rendered as the elements root. |
| `type` | `"responder" \| "sender"` | `"responder"` | Determines the color and orientation of the message. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--message--corner-radius` | `8px` |
| `--message--padding-y` | `8px` |
| `--message--padding-x` | `16px` |
| `--message--spacing-y` | `0.5rem` |
| `--message--spacing-x` | `1rem` |
| `--message--tip-size-x` | `8px` |
| `--message--tip-size-y` | `12px` |
| `--message--border-style` | `solid` |
| `--message--border-width` | `1px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--message--background-color-responder` | `#F4F8FC` | `#292F37` |
| `--message--background-color-sender` | `#E0EBFF` | `#002A7B` |
| `--message--border-color` | `#E5EFF8` | `#3A434E` |

---

# MessageThread

Der MessageThread gruppiert Messages zu einem Gesprächsverlauf.

> **mStudio-Extensions:** Importiere `MessageThread` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  Combine,
  Avatar,
  Content,
  Header,
  Initials,
  Message,
  MessageSeparator,
  MessageThread,
  Text,
} from "@mittwald/flow-react-components";

<MessageThread>
  <Message type="sender">
    <Header>
      <Combine>
        <Avatar>
          <Initials>Max Mustermann</Initials>
        </Avatar>
        <Text>
          <strong>Max Mustermann</strong>
        </Text>
      </Combine>
    </Header>
    <Content>
      <Text>
        Lorem ipsum dolor sit amet consectetur adipisicing
        elit. Cumque eius quam quas vel voluptas, ullam
        aliquid fugit. Voluptate harum accusantium rerum
        ullam modi blanditiis vitae.
      </Text>
    </Content>
  </Message>

  <Message type="responder">
    <Header>
      <Combine>
        <Avatar>
          <Initials>John Doe</Initials>
        </Avatar>
        <Text>
          <strong>John Doe</strong>
        </Text>
      </Combine>
    </Header>
    <Content>
      <Text>
        Lorem ipsum dolor sit amet consectetur adipisicing
        elit. Cumque eius quam quas vel voluptas, ullam
        aliquid fugit. Voluptate harum accusantium rerum
        ullam modi blanditiis vitae, laborum ea tempore,
        dolore voluptas. Earum pariatur, similique corrupti
        id officia perferendis. Labore, similique. Earum,
        quas in. At dolorem corrupti blanditiis nulla
        deserunt laborum! Corrupti delectus aspernatur nihil
        nulla obcaecati ipsam porro sequi rem? Quam.
      </Text>
    </Content>
  </Message>

  <MessageSeparator>Ticket geschlossen</MessageSeparator>

  <Message type="sender">
    <Header>
      <Combine>
        <Avatar>
          <Initials>Max Mustermann</Initials>
        </Avatar>
        <Text>
          <strong>Max Mustermann</strong>
        </Text>
      </Combine>
    </Header>
    <Content>
      <Text>Lorem ipsum dolor sit amet.</Text>
    </Content>
  </Message>
</MessageThread>
```

---

# Best Practices

- Halte die zeitliche Abfolge der [Messages](https://flow.mittwald.de/components/chat/message)
  konsistent.
- Zeichne Absender und Antwortender über das `type`-Property als `sender` bzw.
  `responder` aus.
- Hebe wichtige Ereignisse mit einem `<MessageSeparator />` hervor. Dazu zählen
  etwa Statusänderungen oder der Eintritt neuer Teilnehmer.

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--message-thread--spacing` | `1.5rem` |
| `--message-thread--indentation` | `16px` |
| `--message-separator--font-size` | `0.875rem` |
| `--message-separator--padding` | `16px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--message-separator--background-color` | `#FFFFFF` | `#1B1F24` |
| `--message-separator--color` | `#3A434E` | `#E5EFF8` |

---

# Avatar

Ein Avatar repräsentiert User visuell, per Image, Initials oder Icon.

> **mStudio-Extensions:** Importiere `Avatar` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  Avatar,
  Image,
} from "@mittwald/flow-react-components";

<Avatar>
  <Image
    alt="Gopher"
    src="https://cdn.shopify.com/s/files/1/2022/6883/products/IMG_2002_250x250@2x.JPG?v=1538235544"
  />
</Avatar>
```

---

# Best Practices

- Wähle die passende Variante je nach Anwendungsfall. Ein
  [Image](https://flow.mittwald.de/components/content/image) eignet sich für personalisierte Elemente
  wie Benutzerprofile, ein [Icon](https://flow.mittwald.de/components/content/icon) für wiederkehrende
  Inhalte.
- Zeige Initialen, wenn kein passendes Image hinterlegt ist.
- Überlass die Farbe meist dem enthaltenen Element. Setze über `color` nur dann
  eine feste Farbe, wenn sie die Unterscheidung verbessert.
- Sorge dafür, dass die Bedeutung des Avatars aus dem Kontext hervorgeht.
- Nutze bei mehreren Avataren nebeneinander einen
  [AvatarStack](https://flow.mittwald.de/components/content/avatar-stack).

---

# Color

Initials erhalten automatisch eine der Colors, abhängig von ihrem Inhalt. Ein
[Icon](https://flow.mittwald.de/components/content/icon) erhält über den Avatar im Default die Color
`blue`. Für eine gezielte Wahl kann das Property `color` verwendet werden.

```tsx
import {
  Avatar,
  IconCustomer,
  IconHome,
  Initials,
} from "@mittwald/flow-react-components";

<>
  <Avatar>
    <Initials>Gillian Gopher</Initials>
  </Avatar>
  <Avatar>
    <Initials>Gina-Lisa Gopher</Initials>
  </Avatar>
  <Avatar color="lilac">
    <Initials>Gilian Gopher</Initials>
  </Avatar>
  <Avatar>
    <IconHome />
  </Avatar>
  <Avatar>
    <IconCustomer />
  </Avatar>
</>
```

---

# Sizes

```tsx
import {
  Avatar,
  Initials,
} from "@mittwald/flow-react-components";

<>
  <Avatar size="xs">
    <Initials>Gillian Gopher</Initials>
  </Avatar>
  <Avatar size="s">
    <Initials>Gillian Gopher</Initials>
  </Avatar>
  <Avatar size="m">
    <Initials>Gillian Gopher</Initials>
  </Avatar>
  <Avatar size="l">
    <Initials>Gillian Gopher</Initials>
  </Avatar>
</>
```

---

# Status

Wird im Avatar das Property `status` gesetzt erhält der Avatar automatisch das
passende Icon und die passende Farbe. Dieses Property darf nur verwendet werden,
wenn der Status zusätzlich durch ein benachbartes Element (z. B.
[Text](https://flow.mittwald.de/components/content/text) oder [Label](https://flow.mittwald.de/components/content/label))
eindeutig kommuniziert wird.

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

<>
  <Avatar status="info" />
  <Avatar status="success" />
  <Avatar status="warning" />
  <Avatar status="danger" />
  <Avatar status="unavailable" />
</>
```

```tsx
import {
  AlertBadge,
  Avatar,
  Heading,
  IconEmail,
  Section,
  Text,
  typedList,
} from "@mittwald/flow-react-components";

export default () => {
  const NotificationList = typedList<{
    status: "info" | "success" | "danger" | "warning";
    content: string;
  }>();

  const EmailList = typedList<{
    address: string;
    blocked?: boolean;
  }>();

  return (
    <>
      <Section>
        <Heading>Benachrichtigungen</Heading>
        <Text>
          Hier wird der Status durch den Inhalt der
          Benachrichtigung erklärt, daher kann der Status
          Avatar verwendet werden.
        </Text>

        <NotificationList.List>
          <NotificationList.StaticData
            data={[
              {
                status: "danger",
                content:
                  'E-Mail-Adresse "mail@example.de" gesperrt',
              },
              {
                status: "success",
                content: "App erfolgreich angelegt",
              },
            ]}
          />
          <NotificationList.Item
            textValue={(notification) =>
              notification.content
            }
          >
            {(notification) => (
              <NotificationList.ItemView>
                <Avatar status={notification.status} />
                <Heading>{notification.content}</Heading>
              </NotificationList.ItemView>
            )}
          </NotificationList.Item>
        </NotificationList.List>
      </Section>
      <Section>
        <Heading>E-Mail-Adressen</Heading>
        <Text>
          Hier muss der Status durch das AlertBadge erklärt
          werden, der Status Avatar kann daher nicht
          verwendet werden.
        </Text>
        <EmailList.List>
          <EmailList.StaticData
            data={[
              {
                address: "mail@example.de",
                blocked: true,
              },
              {
                address: "info@example.de",
              },
            ]}
          />
          <EmailList.Item
            textValue={(email) => email.address}
          >
            {(email) => (
              <EmailList.ItemView>
                <Avatar>
                  <IconEmail />
                </Avatar>
                <Heading>
                  {email.address}
                  {email.blocked && (
                    <AlertBadge status="danger">
                      E-Mail-Adresse gesperrt
                    </AlertBadge>
                  )}
                </Heading>
              </EmailList.ItemView>
            )}
          </EmailList.Item>
        </EmailList.List>
      </Section>
    </>
  );
}
```

---

# Kombiniere mit ...

## Image

Im folgenden Code-Beispiel wird ein Avatar mit einem
[Image](https://flow.mittwald.de/components/content/image) kombiniert. Wenn kein Image vorhanden ist,
sollten Initials angezeigt werden.

```tsx
import {
  Avatar,
  Image,
} from "@mittwald/flow-react-components";

<Avatar>
  <Image
    alt="Gopher"
    src="https://cdn.shopify.com/s/files/1/2022/6883/products/IMG_2002_250x250@2x.JPG?v=1538235544"
  />
</Avatar>
```

Die Initials werden automatisch aus dem Text generiert, der innerhalb von
`<Initials />` übergeben wird. Sie dienen ausschließlich als Platzhalter für ein
[Image](https://flow.mittwald.de/components/content/image).

```tsx
import {
  Avatar,
  Initials,
} from "@mittwald/flow-react-components";

<Avatar>
  <Initials>Gillian Gopher</Initials>
</Avatar>
```

## Icon

Ein Avatar lässt sich mit einem beliebigen [Icon](https://flow.mittwald.de/components/content/icon)
kombinieren.

```tsx
import {
  Avatar,
  IconHome,
} from "@mittwald/flow-react-components";

<Avatar color="blue">
  <IconHome />
</Avatar>
```

## Combine

Benutze die [Combine](https://flow.mittwald.de/components/structure/combine)-Component, um Text neben
dem Avatar zu platzieren.

```tsx
import {
  Combine,
  Avatar,
  Initials,
  Text,
} from "@mittwald/flow-react-components";

<Combine>
  <Avatar>
    <Initials>Max Mustermann</Initials>
  </Avatar>
  <Text>
    <strong>Max Mustermann</strong>
    Organisationsinhaber
  </Text>
</Combine>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `color` | `"violet" \| "green" \| "blue" \| "teal" \| "lilac"` | - | The color of icons and initials inside the avatar. |
| `label` | `string` | - | A descriptive label that assistive technology announces for the avatar (e.g. the name of the represented person or entity). When set, the avatar is exposed as a single image with this label. When omitted, the avatar is treated as purely decorative and hidden from assistive technology. |
| `size` | `"s" \| "xs" \| "m" \| "l"` | `"m"` | The size of the avatar. |
| `status` | `"info" \| "success" \| "warning" \| "danger" \| "unavailable"` | - | Adds status icon and color to the avatar. May only be used if the status is explained by an element (like text or label) nearby. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--avatar--size--xs` | `1.5rem` |
| `--avatar--size--s` | `2rem` |
| `--avatar--size--m` | `2.5rem` |
| `--avatar--size--l` | `4rem` |
| `--initials--font-weight` | `bold` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--avatar--info-status-background-color` | `#E0EBFF` | `#002A7B` |
| `--avatar--warning-status-background-color` | `#FFEBDC` | `#8F3D00` |
| `--avatar--danger-status-background-color` | `#FBE0E6` | `#710F24` |
| `--avatar--success-status-background-color` | `#C0FFEB` | `#003B29` |
| `--avatar--unavailable-status-background-color` | `#DCE9F7` | `#5E6C7A` |

---

# AvatarStack

Ein AvatarStack zeigt mehrere Avatare in einer horizontalen Gruppierung.

> **mStudio-Extensions:** Importiere `AvatarStack` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import {
  Avatar,
  AvatarStack,
  Initials,
} from "@mittwald/flow-react-components";

<AvatarStack>
  <Avatar>
    <Initials>Max Mustermann</Initials>
  </Avatar>
  <Avatar>
    <Initials>John Doe</Initials>
  </Avatar>
  <Avatar>
    <Initials>Gillian Gopher</Initials>
  </Avatar>
</AvatarStack>
```

---

# Best Practices

- Zeige nicht zu viele [Avatare](https://flow.mittwald.de/components/content/avatar) gleichzeitig.
  Empfohlen sind höchstens fünf; für die verbleibende Anzahl nutzt du die
  Property `totalCount`.
- Zeige bei Bedarf per Klick mehr Informationen an. Nutze auf den einzelnen
  Avataren eine [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help) mit dem
  Namen und auf dem `totalCount`-Avatar ein [Modal](https://flow.mittwald.de/components/overlays/modal)
  mit allen Usern in einer Liste.
- Halte die Avatare konsistent zur Darstellung an anderen Stellen. Nutze etwa
  das hochgeladene Profilbild statt eines generischen
  User-[Icons](https://flow.mittwald.de/components/content/icon).

---

# Sizes

```tsx
import {
  Avatar,
  AvatarStack,
  Initials,
} from "@mittwald/flow-react-components";

<>
  <AvatarStack size="xs">
    <Avatar>
      <Initials>Max Mustermann</Initials>
    </Avatar>
    <Avatar>
      <Initials>John Doe</Initials>
    </Avatar>
  </AvatarStack>
  <AvatarStack size="s">
    <Avatar>
      <Initials>Max Mustermann</Initials>
    </Avatar>
    <Avatar>
      <Initials>John Doe</Initials>
    </Avatar>
  </AvatarStack>
  <AvatarStack size="m">
    <Avatar>
      <Initials>Max Mustermann</Initials>
    </Avatar>
    <Avatar>
      <Initials>John Doe</Initials>
    </Avatar>
  </AvatarStack>
  <AvatarStack size="l">
    <Avatar>
      <Initials>Max Mustermann</Initials>
    </Avatar>
    <Avatar>
      <Initials>John Doe</Initials>
    </Avatar>
  </AvatarStack>
</>
```

---

# Total Count

Über die Property `totalCount` lässt sich die Gesamtzahl der
[Avatare](https://flow.mittwald.de/components/content/avatar) angeben. Ist `totalCount` größer als die
Anzahl der angezeigten Avatare, wird ein zusätzlicher Counter mit der
verbleibenden Anzahl angezeigt.

```tsx
import {
  Avatar,
  AvatarStack,
  Initials,
} from "@mittwald/flow-react-components";

<AvatarStack totalCount={20}>
  <Avatar>
    <Initials>Max Mustermann</Initials>
  </Avatar>
  <Avatar>
    <Initials>John Doe</Initials>
  </Avatar>
  <Avatar>
    <Initials>Gillian Gopher</Initials>
  </Avatar>
</AvatarStack>
```

---

# Klickbar

Mache Avatare interaktiv, um mehr Informationen anzuzeigen. Im Beispiel öffnet
jeder einzelne Avatar eine
[ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help) mit dem Namen, während
der `totalCount`-Avatar über `onCountPress` ein
[Modal](https://flow.mittwald.de/components/overlays/modal) mit allen Usern öffnet.

```tsx
import {
  Combine,
  Avatar,
  AvatarStack,
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  Content,
  Heading,
  Initials,
  Modal,
  Section,
  Text,
  useModalController,
} from "@mittwald/flow-react-components";

export default () => {
  const controller = useModalController();

  const users = [
    "Max Mustermann",
    "John Doe",
    "Gillian Gopher",
    "Erika Musterfrau",
    "Jane Doe",
  ];

  return (
    <>
      <AvatarStack
        totalCount={users.length}
        onCountPress={controller.open}
      >
        {users.slice(0, 3).map((name) => (
          <ContextualHelpTrigger key={name}>
            <Button>
              <Avatar>
                <Initials>{name}</Initials>
              </Avatar>
            </Button>
            <ContextualHelp>
              <Text>{name}</Text>
            </ContextualHelp>
          </ContextualHelpTrigger>
        ))}
      </AvatarStack>

      <Modal controller={controller}>
        <Heading>Beteiligte User</Heading>
        <Content>
          <Section>
            {users.map((name) => (
              <Combine key={name}>
                <Avatar>
                  <Initials>{name}</Initials>
                </Avatar>
                <Text>{name}</Text>
              </Combine>
            ))}
          </Section>
        </Content>
      </Modal>
    </>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `size` | `"s" \| "xs" \| "m" \| "l"` | `"m"` | The size of the avatars inside the stack. |
| `totalCount` | `number` | - | The total count of items, as avatars should only be displayed for the first view |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onCountPress` | `(() => void)` | - | The onPress action of the additional items count element |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--avatar-stack--border-width` | `2px` |

---

# CodeBlock

Der CodeBlock dient der übersichtlichen Darstellung von Code als Block mit Syntax-Highlighting.

> **mStudio-Extensions:** Importiere `CodeBlock` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

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

<CodeBlock
  language="json"
  code={`{
  "projectId": "b3a96db5-ba8f-40dd-9100-bab43ac1f698",
  "name": "My Project"
}`}
/>
```

---

# Best Practices

- Nutze den CodeBlock nur für Inhalte, die länger als eine Zeile sind.
- Zeige bei langen Inhalten Zeilennummern an. Das verbessert die Orientierung.
- Mach den Inhalt nur kopierbar, wenn er sich an anderer Stelle weiterverwenden
  lässt.

---

# Mit Zeilennummern

Wird das `showLineNumbers` Property gesetzt, werden Zeilennummern angezeigt.

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

<CodeBlock
  showLineNumbers
  language="json"
  code={`{
  "projectId": "b3a96db5-ba8f-40dd-9100-bab43ac1f698",
  "name": "My Project"
}`}
/>
```

---

# Mit Kopierfunktion

Mit dem Property `copyable` erhält der CodeBlock eine Kopierfunktion. Dadurch
kann der User den gesamten Inhalt des CodeBlocks in die Zwischenablage kopieren.
Eventuelle Zeilennummern werden nicht mit kopiert.

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

<CodeBlock
  copyable
  language="json"
  code={`{
  "projectId": "b3a96db5-ba8f-40dd-9100-bab43ac1f698",
  "name": "My Project"
}`}
/>
```

---

# Mehr anzeigen

Über die Property `truncateLines` lässt sich die Höhe des CodeBlocks begrenzen.
Ist sie `true`, wird der Inhalt nach dem Standardwert gekürzt. Bei einer Zahl
erfolgt die Kürzung nach der angegebenen Zeilenanzahl. Überschreitet der Code
diese Länge, erscheint automatisch ein „Mehr anzeigen“-Button.

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

<CodeBlock
  language="json"
  truncateLines={4}
  code={`{
  "projectId": "b3a96db5-ba8f-40dd-9100-bab43ac1f698",
  "name": "My Project"
  "createdAt": "2025-08-25T06:11:21.000Z",
  "enabled": true,
  "status": "ready",
  "serverId": "830d3c18-2d32-4768-b6a0-7e8b424a1271",
  "serverShortId": "s-123456",
}`}
/>
```

---

# Mit Children

Um den Inhalt des CodeBlocks frei gestalten zu können, gibt es die Möglichkeit
anstatt des `code` Properties Children zu nutzen.

```tsx
import {
  CodeBlock,
  Color,
} from "@mittwald/flow-react-components";

<CodeBlock>
  Lorem ipsum dolor sit amet consectetur adipisicing elit.
  <br />
  <Color color="danger">
    Lorem ipsum dolor sit amet consectetur adipisicing elit.
  </Color>
  <br />
  Lorem ipsum dolor sit amet consectetur adipisicing elit.
</CodeBlock>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `code` | `string` | - | The code displayed in the block. |
| `copyable` | `boolean` | `true` | Whether a button to copy the code to the clipboard is shown. |
| `language` | `"text" \| "go" \| (string & {}) \| "p" \| "b" \| "html" \| "map" \| "q" \| "s" \| "svg" \| "m" \| "markdown" \| "d" \| "in" \| "r" \| "apl" \| "asc" \| "asn" \| "asn1" \| "bash" \| "bf" \| "BUILD" \| "bzl" \| ... 196 more ...` | - | The language the code is highlighted as. A language the editor does not know is shown as plain text. |
| `showLineNumbers` | `boolean` | `true` | Whether line numbers are shown in the gutter. |
| `truncateLines` | `number \| boolean` | `false` | Controls truncation of long code blocks. `false` disables it, `true` truncates after 8 lines, and a number sets the maximum line count. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--code-block--font-size` | `0.875rem` |
| `--code-block--font-family` | `FiraCode, monospace` |
| `--code-block--padding` | `16px` |
| `--code-block--corner-radius` | `8px` |
| `--code-block--border-width` | `1px` |
| `--code-block--border-style` | `solid` |
| `--code-block--show-more-padding` | `4px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--code-block--border-color` | `#B7C9DB` | `#8FA1B4` |
| `--code-block--background-color` | `#F4F8FC` | `#292F37` |
| `--code-block--content-color` | `#1B1F24` | `#FFFFFF` |

---

# Color

Mit der Color-Component lassen sich Texte, Headings oder Icons gezielt einfärben.

> **mStudio-Extensions:** Importiere `Color` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

Nutze die Color-Component mit Bedacht

Die Color-Component hebt den umschlossenen Bereich deutlich vom übrigen
Designsystem ab und sollte daher nur in Ausnahmefällen eingesetzt werden.

```tsx
import {
  Color,
  Text,
} from "@mittwald/flow-react-components";

<Text>
  <strong>
    Veröffentliche{" "}
    <Color color="violet">eigene Features</Color> im mStudio
  </strong>
</Text>
```

---

# Best Practices

- Setze die Color-Component sparsam und nur in Ausnahmefällen ein.
- Sorge für ausreichenden Kontrast der eingefärbten Schrift zum Hintergrund.
- Hebe nur kurze Abschnitte von ein bis drei Wörtern hervor. So betonst du die
  Aussage in [Texten](https://flow.mittwald.de/components/content/text) oder
  [Headings](https://flow.mittwald.de/components/content/heading) gezielt.

---

# Color

Je nach Anwendungsfall stehen Colors aus den Bereichen **Brand**, **Status**
oder **Custom** zur Verfügung. Je nach Hintergrund muss auf ein ausreichendes
Kontrastverhältnis geachtet werden. Außerdem sollten Farben nicht allein eine
Bedeutung übertragen.

## Brand Colors

Brand Colors eignen sich, um einzelne Passagen in
[Texten](https://flow.mittwald.de/components/content/text) oder [Headings](https://flow.mittwald.de/components/content/heading)
hervorzuheben. Das ist vor allem bei werblichen Hinweisen hilfreich.

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

<>
  <Color color="blue">blue</Color>
  <Color color="violet">violet</Color>
  <Color color="lilac">lilac</Color>
  <Color color="teal">teal</Color>
</>
```

## Status Colors

Status Colors unterstützen die visuelle Einordnung eines Zustands. Ein häufiger
Einsatzort ist die Darstellung negativer Beträge.

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

<>
  <Color color="danger">danger</Color>
  <Color color="warning">warning</Color>
  <Color color="info">info</Color>
  <Color color="success">success</Color>
  <Color color="unavialable">unavialable</Color>
</>
```

## Custom Colors

Für beliebige Colors unterstützt die `color`-Property die Angabe eines
HEX-Werts.

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

<Color color="#00c513">custom</Color>
```

---

# Kombiniere mit ...

## Text

Teile eines [Textes](https://flow.mittwald.de/components/content/text) lassen sich mithilfe der
Color-Component einfärben.

```tsx
import {
  Color,
  Text,
} from "@mittwald/flow-react-components";

<Text>
  <strong>
    Veröffentliche{" "}
    <Color color="violet">eigene Features</Color> im mStudio
  </strong>
</Text>
```

## Heading

Mit der Color-Component lassen sich in [Headings](https://flow.mittwald.de/components/content/heading)
gezielt wichtige Wörter farblich hervorheben.

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

<Heading>
  <Color color="violet">mStudio Extension</Color> selber
  entwickeln
</Heading>
```

## AccentBox

Ein häufiges Einsatzgebiet der Color-Component ist die Hervorhebung von
[Headings](https://flow.mittwald.de/components/content/heading) in
[AccentBoxen](https://flow.mittwald.de/components/structure/accent-box) mit Werbeinhalten. Dabei ist
besonders wichtig, dass die eingefärbte Schrift einen ausreichenden Kontrast zum
Hintergrund aufweist.

```tsx
import {
  AccentBox,
  Color,
  Flex,
  Heading,
  Link,
  Text,
} from "@mittwald/flow-react-components";

<AccentBox backgroundColor="gradient">
  <Flex align="center" wrap="wrap" gap="m">
    <Flex direction="column" grow>
      <Heading size="l">
        <Color color="violet">mStudio Extension</Color>{" "}
        selber entwickeln
      </Heading>
      <Text>
        <strong>
          <Color>
            Veröffentliche{" "}
            <Color color="violet">eigene Features</Color> im
            mStudio
          </Color>
        </strong>
      </Text>
    </Flex>
    <Link target="_blank" href="#" color="dark">
      Contributor Landingpage
    </Link>
  </Flex>
</AccentBox>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `color` | `FlowWithCustomColor` | `"blue"` | The color of the element. |

---

# Heading

Headings strukturieren den Inhalt einer Seite in Wichtigkeitsstufen.

> **mStudio-Extensions:** Importiere `Heading` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `wrapWith`.

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

<Heading>Das ist eine Überschrift</Heading>
```

---

# Best Practices

- Beschreibe mit der Heading den folgenden Abschnitt eindeutig.
- Formuliere die Heading kurz und sachlich.
- Halte Hierarchie und Reihenfolge klar. Vermeide Sprünge, etwa von `<h2>` zu
  `<h4>`.
- Verwende pro Seite nur eine `<h1>`.

---

# Level

Über das Property `level` kann die Hierarchie der Heading angepasst werden.
Standardmäßig wird eine Heading mit dem Level `H2` erzeugt. Die Seite sollte
eine sinnvolle Struktur mit verschiedenen Ebenen aufweisen.

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

<>
  <Heading level={1}>
    Das ist eine Level 1 Überschrift
  </Heading>
  <Heading level={2}>
    Das ist eine Level 2 Überschrift
  </Heading>
  <Heading level={3}>
    Das ist eine Level 3 Überschrift
  </Heading>
  <Heading level={4}>
    Das ist eine Level 4 Überschrift
  </Heading>
  <Heading level={5}>
    Das ist eine Level 5 Überschrift
  </Heading>
</>
```

---

# Color

Zusätzlich zur Standard-Color kann die Heading in **Light** und **Dark**
dargestellt werden, wenn die Standard-Color auf farbigen oder dekorativen
Hintergründen nicht gut funktioniert. Wann welche Color passt, beschreibt
[Color](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

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

<Heading color="dark">Das ist eine Überschrift</Heading>
```

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

<Heading color="light">Das ist eine Überschrift</Heading>
```

---

# Size

Über das Property `size` kann in Ausnahmefällen die Schriftgröße einer Heading
manuell angepasst werden. Die Headings sollten dabei eine visuelle Hierarchie
beibehalten.

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

<Heading level={2} size="xs">
  Das ist eine Überschrift für die eine benutzerdefinierte
  Größe gesetzt wurde
</Heading>
```

---

# Kombiniere mit ...

## ContextualHelp

Verwende eine [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help), um Usern
zusätzliche Hilfestellungen zu geben (z. B. bei Fachbegriffen).

```tsx
import { Heading } from "@mittwald/flow-react-components";
import { Button } from "@mittwald/flow-react-components";
import {
  ContextualHelp,
  ContextualHelpTrigger,
} from "@mittwald/flow-react-components";
import { Text } from "@mittwald/flow-react-components";

<Heading>
  Rechte & Rollen
  <ContextualHelpTrigger>
    <Button />
    <ContextualHelp>
      <Text>
        Weitere Informationen zum Thema Rechte & Rollen
      </Text>
    </ContextualHelp>
  </ContextualHelpTrigger>
</Heading>
```

## Badge oder AlertBadge

Verwende ein [Badge](https://flow.mittwald.de/components/status/badge), um wichtige Metainformationen zu
einem Abschnitt hervorzuheben, oder ein
[AlertBadge](https://flow.mittwald.de/components/status/alert-badge), um einen Status anzuzeigen.

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

<Heading>
  E-Mail-Adresse
  <Badge>Primär</Badge>
  <AlertBadge status="danger">
    Speicherplatz voll
  </AlertBadge>
</Heading>
```

## Button oder CopyButton

Verwende einen [Button](https://flow.mittwald.de/components/actions/button) für eine Aktion, die sich
direkt auf den Abschnitt bezieht, etwa ihn umzubenennen, oder einen
[CopyButton](https://flow.mittwald.de/components/actions/copy-button), um den Text der Heading zu
kopieren. Der Button steht neben dem Text und passt seine Größe an die der
Heading an. Gib einem Button ohne Text ein `aria-label`.

```tsx
import {
  Badge,
  Button,
  CopyButton,
  Heading,
  IconEdit,
  Section,
} from "@mittwald/flow-react-components";

<Section>
  <Heading>
    mein-shop.de
    <CopyButton text="mein-shop.de" />
  </Heading>
  <Heading level={3}>
    Onlineshop
    <Badge>Produktiv</Badge>
    <Button
      aria-label="Projekt umbenennen"
      variant="plain"
      color="secondary"
    >
      <IconEdit />
    </Button>
  </Heading>
</Section>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | `'react-aria-Heading'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static" \| "danger" \| "unavailable"` | `"default"` | The color of the heading. |
| `elementType` | `"span" \| "p" \| ExoticComponent<{}>` | - | The HTML element or React component rendered as the elements root. |
| `level` | `number` | `3` | The heading level. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `size` | `"s" \| "xs" \| "m" \| "l" \| "xl" \| "xxl"` | - | The font size of the heading. |
| `wrap` | `"wrap" \| "balance"` | `undefined` | The text-wrap property of the text. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--heading--icon-to-text-spacing` | `0.5rem` |
| `--heading--font-weight` | `bold` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--heading--color` | `#121518` | `#FFFFFF` |
| `--heading--color-dark` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--heading--color-light` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--heading--color-dark-static` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--heading--color-light-static` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--heading--color-danger` | `#AB1737` | `#F7C1CC` |
| `--heading--color-unavailable` | `#3A434E` | `#E5EFF8` |

---

# Icon

Icons sind semantische Symbole, die Inhalte und Funktionen visualisieren.

> **mStudio-Extensions:** Importiere `Icon` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<IconHome />
```

---

# Best Practices

- Wähle ein Icon, das zum Element und Kontext passt. Verändere oder vertausche
  die Bedeutungen der Bibliotheks-Icons nicht.
- Lass Icons eine unterstützende Rolle einnehmen. Ein Decorative Icon braucht
  immer den Kontextbezug, sonst wird es nicht verstanden.
- Setze Icons sparsam ein. Zu viele Icons überfordern kognitiv.
- Verwende nach Möglichkeit ein Icon aus der
  [Icon-Bibliothek](#icon-bibliothek). Nur wenn keins passt, nutze ein
  [Tabler Icon](https://tabler.io/icons) oder ein eigenes SVG.

---

# Colors

Ohne weitere Angabe übernimmt ein Icon die Textfarbe seiner Umgebung. Über die
`color`-Property lässt sich ein Icon gezielt einfärben. Dabei stehen Brand- und
Status-Colors zur Verfügung; `neutral` setzt die Standard-Icon-Farbe.

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

<>
  <IconHome color="neutral" />
  <IconHome color="blue" />
  <IconHome color="violet" />
  <IconHome color="teal" />
  <IconHome color="lilac" />
  <IconHome color="info" />
  <IconHome color="success" />
  <IconHome color="warning" />
  <IconHome color="danger" />
  <IconHome color="unavailable" />
</>
```

Für beliebige Colors unterstützt die `color`-Property außerdem die Angabe eines
HEX-Werts.

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

<IconHome color="#0fdf00" />
```

---

# Sizes

- **s** für kleine Hinweise oder Components mit wenig Platz.
- **m** als Standardgröße.
- **l** vor allem für dekorative Zwecke.

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

<>
  <IconHome size="s" />
  <IconHome size="m" />
  <IconHome size="l" />
</>
```

---

# Tabler Icon

Wenn kein passendes Icon in der Icon-Bibliothek vorhanden ist, kann alternativ
ein Icon von [Tabler](https://tabler.io/icons) ausgewählt werden. Diese muss für
die korrekte Darstellung in der `<Icon>`-Component eingebunden werden.

Flow bringt `@tabler/icons-react` nicht mit – die Icons der Icon-Bibliothek sind
direkt in `@mittwald/flow-icons` enthalten. Für ein Icon außerhalb der
Bibliothek installierst du das Package selbst:

```shell
npm i @tabler/icons-react
```

```tsx
import { Icon } from "@mittwald/flow-react-components";
import { IconStar } from "@tabler/icons-react";

<Icon>
  <IconStar />
</Icon>
```

---

# SVG

Zusätzlich können eigene SVGs als Icons eingesetzt werden. Dabei ist darauf zu
achten, dass sie im Stil der übrigen Icons konsistent bleiben. Das SVG muss
ebenfalls in der `<Icon>`-Component eingebunden werden, damit es korrekt
dargestellt wird.

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

<Icon>
  <svg
    fill="currentColor"
    viewBox="0 0 100 100"
    xmlns="http://www.w3.org/2000/svg"
  >
    <circle cx="50" cy="50" r="50" />
  </svg>
</Icon>
```

---

# Icon-Bibliothek

Im Flow Design System haben ausgewählte Icons eine festgelegte Bedeutung. Sie
lassen sich drei Typen zuordnen: **Functional, Decorative** und **Status**.

## Functional

Functional Icons besitzen eine eindeutige, allgemein verständliche Symbolik, die
der User bereits kennt. Sie unterstützen User bei Navigation und Interaktion und
werden häufig in Actions wie [Icon-Buttons](https://flow.mittwald.de/components/actions/button)
eingesetzt.

## Decorative

Decorative Icons tragen zur Ästhetik und zur emotionalen Wirkung der
Benutzeroberfläche bei. Im Gegensatz zu den Functional Icons ist ihre Bedeutung
jedoch oft nicht intuitiv erfassbar.

## Status

Bestimmte Icons dienen der Anzeige des Status eines Elements.

---

# Kombiniere mit ...

## Combine

Benutze die [Combine](https://flow.mittwald.de/components/structure/combine)-Component, um ein Icon
neben einem Text zu platzieren.

```tsx
import {
  Combine,
  IconDomain,
  Text,
} from "@mittwald/flow-react-components";

<Combine>
  <IconDomain />
  <Text>mail.agenturserver.de</Text>
</Combine>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `IconWithCustomColor` | - | The color of the icon. Besides the Flow colors, any custom CSS color is supported. Inherits the surrounding text color when unset. |
| `size` | `"s" \| "m" \| "l"` | `"m"` | The size of the icon. |
| `status` _(deprecated)_ | `"info" \| "success" \| "warning" \| "danger" \| "unavailable"` | - | The elements status. @deprecated Use `color` instead. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--icon--size--s` | `1rem` |
| `--icon--size--m` | `1.5rem` |
| `--icon--size--l` | `4rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--icon--color` | `#5E6C7A` | `#DCE9F7` |
| `--icon--info-color` | `#003FB8` | `#ABC6FF` |
| `--icon--warning-color` | `#C25200` | `#FFD9BD` |
| `--icon--danger-color` | `#AB1737` | `#F7C1CC` |
| `--icon--success-color` | `#005F42` | `#87FFDA` |
| `--icon--unavailable-color` | `#3A434E` | `#E5EFF8` |
| `--icon--blue-color` | `#002A7B` | `#E0EBFF` |
| `--icon--violet-color` | `#715DEE` | `#C2B9F8` |
| `--icon--teal-color` | `#008696` | `#5eedff` |
| `--icon--lilac-color` | `#bc08ff` | `#ebb6ff` |
| `--icon--dark-color` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--icon--light-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--icon--dark-static-color` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--icon--light-static-color` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |

---

# IllustratedMessage

Die IllustratedMessage gibt großflächigen Bereichen mit wenig Inhalt eine visuelle Struktur.

> **mStudio-Extensions:** Importiere `IllustratedMessage` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  Button,
  Heading,
  IconApp,
  IllustratedMessage,
  Text,
} from "@mittwald/flow-react-components";

<IllustratedMessage>
  <IconApp />
  <Heading>Keine Apps installiert</Heading>
  <Text>
    Lege deine erste App an, um mit der Arbeit an deiner
    Webseite loszulegen.
  </Text>
  <Button>App anlegen</Button>
</IllustratedMessage>
```

---

# Best Practices

- Wähle ein [Icon](https://flow.mittwald.de/components/content/icon), das zum Kontext passt.
- Beschreibe im Text klar, warum der Zustand leer ist und was als Nächstes zu
  tun ist.
- Unterstütze Handlungsaufforderungen mit interaktiven Elementen wie
  [Buttons](https://flow.mittwald.de/components/actions/button) oder
  [Links](https://flow.mittwald.de/components/navigation/link).

---

# Color

## Danger und Unavailable

Bei Fehlern oder unzulässigem Zugriff hilft die IllustratedMessage Usern dabei
zu verstehen, was nicht funktioniert und warum. Zusätzlich kann sie eine
mögliche Lösung anbieten. Im Vergleich zu einem
[Alert](https://flow.mittwald.de/components/status/alert) wirkt sie freundlicher und gleicht fehlende
Inhalte visuell besser aus.

```tsx
import {
  Button,
  Heading,
  IconDanger,
  IllustratedMessage,
  Text,
} from "@mittwald/flow-react-components";

<IllustratedMessage color="danger">
  <IconDanger />
  <Heading>Fehler beim Laden von Daten</Heading>
  <Text>
    Dieser Bereich konnte nicht geladen werden. Wir arbeiten
    daran das Problem zu beheben. Bitte habe etwas Geduld
    und probiere es später noch einmal.
  </Text>
  <Button color="secondary" variant="soft">
    Erneut versuchen
  </Button>
</IllustratedMessage>
```

```tsx
import {
  Link,
  Heading,
  IconUnavailable,
  IllustratedMessage,
  Text,
} from "@mittwald/flow-react-components";

<IllustratedMessage color="unavailable">
  <IconUnavailable />
  <Heading>Kein Zugriff</Heading>
  <Text>
    Du hast keine Berechtigung, um auf diese Seite
    zuzugreifen.
  </Text>
  <Link>Zum Dashboard</Link>
</IllustratedMessage>
```

## Light und Dark

Zusätzlich zu den Standard-Colors kann die IllustratedMessage in **Light** und
**Dark** dargestellt werden, wenn die Standard-Colors auf farbigen oder
dekorativen Hintergründen nicht gut funktionieren. Wann welche Color passt,
beschreibt [Color](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

```tsx
import {
  Button,
  Heading,
  IconApp,
  IllustratedMessage,
  Text,
} from "@mittwald/flow-react-components";

<IllustratedMessage color="light">
  <IconApp />
  <Heading>Keine Apps installiert</Heading>
  <Text>
    Lege deine erste App an, um mit der Arbeit an deiner
    Webseite loszulegen.
  </Text>
  <Button>App anlegen</Button>
</IllustratedMessage>
```

```tsx
import {
  Button,
  Heading,
  IconApp,
  IllustratedMessage,
  Text,
} from "@mittwald/flow-react-components";

<IllustratedMessage color="dark">
  <IconApp />
  <Heading>Keine Apps installiert</Heading>
  <Text>
    Lege deine erste App an, um mit der Arbeit an deiner
    Webseite loszulegen.
  </Text>
  <Button>App anlegen</Button>
</IllustratedMessage>
```

---

# Kombiniere mit ...

## ActionGroup

Wenn mehr als eine [Action](https://flow.mittwald.de/components/actions/action) benötigt wird, kann die
IllustratedMessage auch mit einer
[ActionGroup](https://flow.mittwald.de/components/actions/action-group) kombiniert werden.

```tsx
import {
  ActionGroup,
  Button,
  Heading,
  IconApp,
  IllustratedMessage,
  Text,
} from "@mittwald/flow-react-components";

<IllustratedMessage>
  <IconApp />
  <Heading>Keine Apps installiert</Heading>
  <Text>
    Lege deine erste App an, um mit der Arbeit an deiner
    Webseite loszulegen.
  </Text>
  <ActionGroup>
    <Button variant="soft" color="secondary">
      Zurück
    </Button>
    <Button>App anlegen</Button>
  </ActionGroup>
</IllustratedMessage>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static" \| "danger" \| "unavailable"` | `"default"` | The color of the illustrated message. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--illustrated-message--padding` | `16px` |
| `--illustrated-message--spacing` | `1rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--illustrated-message--content-color` | `#121518` | `#FFFFFF` |
| `--illustrated-message--danger-content-color` | `#AB1737` | `#F7C1CC` |
| `--illustrated-message--unavailable-content-color` | `#3A434E` | `#E5EFF8` |
| `--illustrated-message--dark-content-color` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--illustrated-message--light-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--illustrated-message--dark-static-content-color` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--illustrated-message--light-static-content-color` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |

---

# Image

Mit der Image-Component lassen sich Bilder in der Benutzeroberfläche einbinden.

> **mStudio-Extensions:** Importiere `Image` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<Image
  src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
  alt="mittwald"
  width={200}
/>
```

---

# Best Practices

- Wähle Bilder, die zum Kontext und zur Gestaltung passen.
- Beschreibe Inhalt oder Zweck über einen aussagekräftigen `alt`-Text. Rein
  dekorative Bilder erhalten ein leeres `alt`-Attribut (`alt=""`).
- Optimiere die Größenverhältnisse für kurze Ladezeiten.
- Wähle Auflösung und Seitenverhältnis konsistent.
- Setze bei geringem Kontrast zum Hintergrund eine sichtbare Border.
- Verzichte möglichst auf Text im Bild. Screenreader erfassen ihn nicht.
- Nutze für verschiedene Bildschirmgrößen das `srcSet`-Attribut. Es wählt je
  nach Pixeldichte automatisch die passende Auflösung (siehe
  [Responsive Images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#resolution_switching_same_size_different_resolutions:~:text=Resolution%20switching%3A%20Same%20size%2C%20different%20resolutions)).

---

# Border

Mit der Property `withBorder` erhält die Image-Component eine Border. Das ist
insbesondere bei Bildern mit geringem Kontrast zum Hintergrund von Vorteil, da
es die visuelle Abgrenzung verbessert und die Bildwahrnehmung unterstützt.

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

<Image
  src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
  alt="mittwald"
  width={200}
  withBorder
/>
```

---

# Abgerundete Ecken

Die Image-Component hat standardmäßig abgerundete Ecken, unabhängig von
`withBorder`. Mit `withRoundedCorners={false}` erhält sie eckige Kanten, etwa
wenn das Bild bündig an einen Container anschließt.

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

<Image
  src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
  alt="mittwald"
  width={200}
  withRoundedCorners={false}
/>
```

---

# Fixes Seitenverhältnis

Die Property `aspectRatio` definiert das Seitenverhältnis der Image-Component.
Weicht das Seitenverhältnis des eingebetteten Bildes ab – etwa durch eine
größere Höhe oder Breite –, wird das Bild zentriert, und überstehende Bereiche
außerhalb des festgelegten Verhältnisses werden ausgeblendet.

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

<Image
  src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
  alt="mittwald"
  width={200}
  aspectRatio={16 / 9}
  withBorder
/>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aspectRatio` | `number` | - | The aspect ratio of the images container. Larger images will be centered and their overflow will be hidden. |
| `withBorder` | `boolean` | - | Display the image with a border. |
| `withRoundedCorners` | `boolean` | `true` | Display the image with rounded corners. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--image--corner-radius` | `8px` |
| `--image--border-width` | `1px` |
| `--image--border-style` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--image--border-color` | `#B7C9DB` | `#8FA1B4` |

---

# InlineCode

InlineCode hebt Code-Beispiele innerhalb eines Fließtextes hervor.

> **mStudio-Extensions:** Importiere `InlineCode` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import {
  InlineCode,
  Text,
} from "@mittwald/flow-react-components";

<Text>
  Gib <InlineCode>yarn start</InlineCode> ein um deine App
  zu starten.
</Text>
```

---

# Best Practices

- Setze InlineCode sparsam ein. Zu viele InlineCodes machen einen Text
  unleserlich.
- Nutze InlineCode nur für kurze Beispiele. Für längere Code-Beispiele eignet
  sich der [CodeBlock](https://flow.mittwald.de/components/content/code-block).

---

# Color

Zusätzlich zur Standard-Color kann InlineCode in **Light** und **Dark**
dargestellt werden, wenn die Standard-Color auf farbigen oder dekorativen
Hintergründen keinen ausreichenden Kontrast (mind. 4,5:1) bietet. Wann welche
Color passt, beschreibt
[Color](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

```tsx
import {
  InlineCode,
  Text,
} from "@mittwald/flow-react-components";

<Text color="light">
  Gib <InlineCode color="light">yarn start</InlineCode> ein
  um deine App zu starten.
</Text>
```

```tsx
import {
  InlineCode,
  Text,
} from "@mittwald/flow-react-components";

<Text>
  Gib <InlineCode color="dark">yarn start</InlineCode> ein
  um deine App zu starten.
</Text>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static"` | `"default"` | The color schema of the inline code component. |
| `whiteSpace` | `WhiteSpace` | `undefined` | The white-space property of the inline code component. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--inline-code--font-size` | `0.875rem` |
| `--inline-code--padding-x` | `4px` |
| `--inline-code--padding-y` | `2px` |
| `--inline-code--corner-radius` | `4px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--inline-code--background-color` | `#DCE9F7` | `#5E6C7A` |
| `--inline-code--content-color` | `#1B1F24` | `#FFFFFF` |
| `--inline-code--dark-background-color` | `rgb(0 0 0 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--inline-code--dark-content-color` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--inline-code--light-background-color` | `rgb(255 255 255 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--inline-code--light-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--inline-code--dark-static-background-color` | `rgb(0 0 0 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--inline-code--dark-static-content-color` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--inline-code--light-static-background-color` | `rgb(255 255 255 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--inline-code--light-static-content-color` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |

---

# Kbd

Kbd stellt Tastaturkürzel dar und passt sich dem Betriebssystem an.

> **mStudio-Extensions:** Importiere `Kbd` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<Kbd keys={["mod", "k"]} />
```

---

# Best Practices

- Zeige nur tatsächlich verfügbare und funktionierende Keyboard-Shortcuts an.
- Platziere den Kbd in direktem Bezug zu Inhalt oder Aktion des Shortcuts.

---

# Variants

Die Component wird in zwei Varianten angeboten:

- `plain` – für Shortcuts direkt an Bedienelementen; fügt sich dezent in die
  Oberfläche ein, ohne aufdringlich zu wirken.
- `soft` – für erklärende Texte oder Beschreibungen; hebt hervor, dass es sich
  um einen Keyboard-Shortcut handelt.

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

<>
  <Kbd variant="plain" keys={["mod", "k"]} />
  <Kbd variant="soft" keys={["mod", "k"]} />
</>
```

---

# Children

Um flexiblere Shortcuts darzustellen, unterstützt die Component auch `children`.
Hierbei ist darauf zu achten, dass Kbd-Components für die einzelnen Keys gesetzt
werden müssen, um semantisch korrekte
[kbd-HTML-Elemente](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/kbd)
zu erzeugen.

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

<Kbd>
  <Kbd keys={["mod"]} /> + <Kbd keys={["k"]} />,{" "}
  <Kbd keys={["mod"]} /> + <Kbd keys={["c"]} />
</Kbd>
```

---

# Kombiniere mit …

## SearchField

Wenn eine Suche durch einen Keyboard-Shortcut fokussiert werden kann, kann die
Kbd Component mit dem [SearchField](https://flow.mittwald.de/components/form-controls/search-field)
kombiniert werden, um dem User das verfügbare Tastaturkürzel sichtbar zu machen.

```tsx
import {
  SearchField,
  Kbd,
} from "@mittwald/flow-react-components";

<SearchField aria-label="Suche">
  <Kbd keys={["mod", "k"]} />
</SearchField>
```

## ContextMenu

In [ContextMenus](https://flow.mittwald.de/components/actions/context-menu) werden häufig Aktionen
angezeigt, die zusätzlich per Keyboard-Shortcut ausgelöst werden können. In
diesem Fall kann Kbd mit dem jeweiligen MenuItem kombiniert werden.

```tsx
import {
  Button,
  ContextMenu,
  ContextMenuTrigger,
  MenuItem,
  Kbd,
} from "@mittwald/flow-react-components";

<ContextMenuTrigger>
  <Button>Menü öffnen</Button>
  <ContextMenu>
    <MenuItem>
      Speichern <Kbd keys={["mod", "s"]} />
    </MenuItem>
    <MenuItem>
      Kopieren <Kbd keys={["mod", "c"]} />
    </MenuItem>
    <MenuItem>
      Einfügen <Kbd keys={["mod", "v"]} />
    </MenuItem>
  </ContextMenu>
</ContextMenuTrigger>
```

## Text

Wird die Kbd Component innerhalb eines [Texts](https://flow.mittwald.de/components/content/text)
verwendet, wird sie automatisch in der `soft` Variante dargestellt. Dadurch hebt
sie sich visuell vom Fließtext ab und macht deutlich, dass es sich um einen
Keyboard-Shortcut handelt.

```tsx
import { Text, Kbd } from "@mittwald/flow-react-components";

<Text>
  Verwende <Kbd keys={["mod", "k"]} /> um die Suche zu
  öffnen.
</Text>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `isDisabled` | `boolean` | - | Whether the component is displayed as disabled |
| `keys` | `string[]` | - | Array of keys to be joined |
| `variant` | `"plain" \| "soft"` | `"plain"` | The visual variant |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--kbd--corner-radius` | `4px` |
| `--kbd--padding` | `4px` |
| `--kbd--padding-y-start` | `2px` |
| `--kbd--inner-shadow-size-x` | `2px` |
| `--kbd--inner-shadow-size-y-end` | `4px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--kbd--background-color--default` | `#DCE9F7` | `#5E6C7A` |
| `--kbd--background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--kbd--content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--kbd--content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--kbd--content-color-plain--default` | `#5E6C7A` | `#DCE9F7` |
| `--kbd--content-color-plain--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--kbd--inner-shadow-color--default` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--kbd--inner-shadow-color--disabled` | `rgb(0 0 0 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |

---

# Label

Ein Label erläutert Eingabeanforderungen in Formularen.

> **mStudio-Extensions:** Importiere `Label` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `wrapWith`.

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

<Label>Label</Label>
```

---

# Best Practices

- Formuliere das Label kurz, prägnant und in einfacher Sprache, meist ein bis
  drei Wörter.
- Halte das Label jederzeit vollständig sichtbar und einzeilig.
- Benenne das Feld als Substantiv. Nutze etwa „E-Mail-Adresse“ statt „E-Mail
  eingeben“.
- Gib Formatierungshinweise über die FieldDescription im
  [TextField](https://flow.mittwald.de/components/form-controls/text-field).

---

# States

Ein Label hat zwei States:

- **Default** – das Label wird in seiner Standarddarstellung angezeigt.
- **Disabled** – das Label beschreibt häufig komplexere Components und übernimmt
  automatisch deren State. Ist z. B. ein
  [TextField](https://flow.mittwald.de/components/form-controls/text-field) oder
  [NumberField](https://flow.mittwald.de/components/form-controls/number-field) gerade **disabled**,
  nimmt das Label denselben State an.

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

<>
  <Label>Default</Label>
  <Label isDisabled>Disabled</Label>
</>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `elementType` | `string` | - | - |
| `isDisabled` | `boolean` | - | Whether the label should be displayed as disabled. |
| `optional` | `boolean` | - | Whether the label should show an "optional" indicator. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--label--font-size` | `0.875rem` |
| `--label--font-weight` | `bold` |
| `--label--spacing` | `0.25rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--label--color--default` | `#3A434E` | `#E5EFF8` |
| `--label--color--disabled` | `#DCE9F7` | `#5E6C7A` |

---

# LabeledValue

Das LabeledValue zeigt eine statische Information mit beschreibendem Label.

> **mStudio-Extensions:** Importiere `LabeledValue` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import {
  Content,
  Label,
  LabeledValue,
} from "@mittwald/flow-react-components";

<LabeledValue>
  <Label>Speicherplatz</Label>
  <Content>20 GB</Content>
</LabeledValue>
```

---

# Best Practices

- Formuliere das [Label](https://flow.mittwald.de/components/content/label) kurz, prägnant und in
  einfacher Sprache, sodass es den Wert eindeutig beschreibt.
- Stelle mehrere LabeledValues in einem
  [ColumnLayout](https://flow.mittwald.de/components/structure/column-layout) nebeneinander dar. Setze
  dabei nicht zu viele Informationen in eine Zeile.
- Sortiere sie nach Wichtigkeit und fasse sie in sinnvolle Gruppen. Ein Beispiel
  ist die Gruppe aus Name und Adresse.

---

# Kombiniere mit ...

Der Content-Bereich des LabeledValue kann einen
[Text](https://flow.mittwald.de/components/content/text), einen InlineCode oder einen Link beinhalten
und jeweils durch einen CopyButton ergänzt werden.

## ColumnLayout

Stelle mehrere LabeledValues in einem
[ColumnLayout](https://flow.mittwald.de/components/structure/column-layout) nebeneinander dar, um
zusammengehörige Informationen wie Name und Adresse zu gruppieren.

```tsx
import {
  ColumnLayout,
  Content,
  Label,
  LabeledValue,
} from "@mittwald/flow-react-components";

<ColumnLayout>
  <LabeledValue>
    <Label>Vorname</Label>
    <Content>Max</Content>
  </LabeledValue>
  <LabeledValue>
    <Label>Nachname</Label>
    <Content>Mustermann</Content>
  </LabeledValue>
  <LabeledValue>
    <Label>Straße</Label>
    <Content>Musterstraße 1</Content>
  </LabeledValue>
  <LabeledValue>
    <Label>Ort</Label>
    <Content>32423 Minden</Content>
  </LabeledValue>
</ColumnLayout>
```

## InlineCode

Mit `<InlineCode />` anstelle von `<Content />` kann ein
[InlineCode](https://flow.mittwald.de/components/content/inline-code) angezeigt werden.

```tsx
import {
  InlineCode,
  Label,
  LabeledValue,
} from "@mittwald/flow-react-components";

<LabeledValue>
  <Label>Datenbankserver</Label>
  <InlineCode>
    mysql-kq3v4g.ge-s-hopovh.db.project.host
  </InlineCode>
</LabeledValue>
```

## Link

Nutze einen `<Link />` anstelle von `<Content />`, um einen
[Link](https://flow.mittwald.de/components/navigation/link) anzuzeigen.

```tsx
import {
  Label,
  LabeledValue,
  Link,
} from "@mittwald/flow-react-components";

<LabeledValue>
  <Label>Server</Label>
  <Link>MyServ-01</Link>
</LabeledValue>
```

## CopyButton

Verwende `<CopyButton />` innerhalb des `<LabeledValue />`, um einen
[CopyButton](https://flow.mittwald.de/components/actions/copy-button) am Ende des Contents anzuzeigen.

```tsx
import {
  Content,
  CopyButton,
  Label,
  LabeledValue,
} from "@mittwald/flow-react-components";

<LabeledValue>
  <Label>Short-ID</Label>
  <Content>p-wut3uw</Content>
  <CopyButton text="p-wut3uw" />
</LabeledValue>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--labeled-value--label-to-value-spacing` | `0.25rem` |
| `--labeled-value--value-to-action-spacing` | `0.25rem` |

---

# Markdown

Die Markdown Component rendert Texteingaben im Markdown-Format.

> **mStudio-Extensions:** Importiere `Markdown` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `components`, `ref`.

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

<Markdown>
  Lorem ipsum dolor sit amet **consectetur adipisicing**
  elit. Cumque eius *quam quas vel voluptas* ullam aliquid
  ***fugit***.
</Markdown>
```

---

# Best Practices

- Nutze Markdown vor allem für dynamische oder nutzergenerierte Texteingaben.
- Verwende für mehr Kontrolle über Layout und semantische Elemente stattdessen
  [Text](https://flow.mittwald.de/components/content/text). Markdown wird als HTML ohne explizite
  Kontrolle über Elemente wie `<p>` oder `<h1>` gerendert.

---

# Color

Zusätzlich zur Standard-Color kann Markdown in **Light** und **Dark**
dargestellt werden, wenn die Standard-Color auf farbigen oder dekorativen
Hintergründen nicht gut funktioniert. Wann welche Color passt, beschreibt
[Color](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

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

<Markdown color="light">
  Lorem ipsum dolor sit amet **consectetur adipisicing**
  elit. Cumque eius *quam quas vel voluptas* ullam aliquid
  ***fugit***.
</Markdown>
```

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

<Markdown color="dark">
  Lorem ipsum dolor sit amet **consectetur adipisicing**
  elit. Cumque eius *quam quas vel voluptas* ullam aliquid
  ***fugit***.
</Markdown>
```

---

# Unterstützte Syntax

## Headings

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

<Markdown>
  {
    "# Heading Level 1 \n## Heading Level 2 \n### Heading Level 3 \n#### Heading Level 4 \n##### Heading Level 5 \n###### Heading Level 6"
  }
</Markdown>
```

## Bold und Italic

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

<Markdown>
  Lorem ipsum dolor sit amet **consectetur adipisicing**
  elit. Cumque eius *quam quas vel voluptas* ullam aliquid
  ***fugit***.
</Markdown>
```

## Unordered Lists

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

<Markdown>
  {
    "- Unordered list item 1 \n - Unordered list item 2  \n - Unordered list item 3"
  }
</Markdown>
```

## Ordered Lists

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

<Markdown>
  {
    "1. Ordered list item 1 \n 2. Ordered list item 2  \n 3. Ordered list item 3"
  }
</Markdown>
```

## Quote

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

<Markdown>{"> This is a quote"}</Markdown>
```

## Link

Externe Links (`https://…`, `http://…`, `//…`) öffnen in einem neuen Tab und
zeigen das Extern-Icon. Relative Links, Anker und `mailto:` öffnen im selben
Tab.

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

<Markdown>
  [mittwald.de](https://mittwald.de) öffnet in einem neuen
  Tab, [Text](/components/content/text) im selben.
</Markdown>
```

## InlineCode

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

<Markdown>{"`127.0.0.1`"}</Markdown>
```

## CodeBlock

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

<Markdown>
  {"```json\n" +
    "{\n" +
    '    "projectId": "b3a96db5-ba8f-40dd-9100-bab43ac1f698",\n' +
    '    "name": "My Project"\n' +
    "}\n" +
    "```\n"}
</Markdown>
```

## Table

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

<Markdown>
  {"| Column 1       | Column 2      |\n" +
    "|---------------|---------------|\n" +
    "| Row 1 Cell 1  | Row 1 Cell 2  |\n" +
    "| Row 2 Cell 1  | Row 2 Cell 2  |\n"}
</Markdown>
```

---

# Offset

Das Property `headingOffset` verschiebt alle Überschriften um den angegebenen
Offset.

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

<Markdown headingOffset={1}>
  {
    "# Heading Level 1 -> 2 \n## Heading Level 2 -> 3 \n### Heading Level 3 -> 4 \n#### Heading Level 4 -> 5 \n##### Heading Level 5 -> 6 \n###### Heading Level 6 -> 6"
  }
</Markdown>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `allowElement` | `AllowElement` | - | Filter elements (optional); `allowedElements` / `disallowedElements` is used first. |
| `allowedElements` | `readonly string[]` | - | Tag names to allow (default: all tag names); cannot combine w/ `disallowedElements`. |
| `children` | `ReactNode` | - | Markdown. |
| `className` | `string` | - | The elements class name. |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static"` | `"default"` | The color schema of the markdown component. |
| `components` | `Components` | - | Allows overriding markdown element renderers from outside. |
| `disallowedElements` | `readonly string[]` | - | Tag names to disallow (default: `[]`); cannot combine w/ `allowedElements`. |
| `headingOffset` | `number` | `0` | Shifts all heading levels by the given offset. |
| `ref` | `Ref<HTMLDivElement>` | - | A ref to the elements root. |
| `rehypePlugins` | `PluggableList` | - | List of rehype plugins to use. |
| `remarkPlugins` | `PluggableList` | - | List of remark plugins to use. |
| `remarkRehypeOptions` | `Readonly<Options>` | - | Options to pass through to `remark-rehype`. |
| `skipHtml` | `boolean` | - | Ignore HTML in markdown completely (default: `false`). |
| `unwrapDisallowed` | `boolean` | - | Extract (unwrap) what’s in disallowed elements (default: `false`); normally when say `strong` is not allowed, it and it’s children are dropped, with `unwrapDisallowed` the element itself is replaced by its children. |
| `urlTransform` | `UrlTransform` | - | Change URLs (default: `defaultUrlTransform`) |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--markdown--spacing` | `1rem` |

---

# Skeleton

Das Skeleton zeigt eine vereinfachte Vorschau, bis der Content geladen ist.

> **mStudio-Extensions:** Importiere `Skeleton` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

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

<Skeleton />
```

---

# Best Practices

- Nutze für Ladeansichten bevorzugt den
  [SkeletonMode](https://flow.mittwald.de/components/content/skeleton-mode). Er stellt die finale
  Oberfläche als Skeleton dar, sodass keine eigene Ladeansicht nötig ist.
- Spiegele das finale Layout so gut wie möglich wider. Nutze vereinfachte Formen
  für [Avatare](https://flow.mittwald.de/components/content/avatar) oder
  [Images](https://flow.mittwald.de/components/content/image), damit User die erwarteten Inhalte
  erkennen.
- Halte Detailgrad und Anzahl gering. Skeletons sollten an Wireframes erinnern
  und keine visuelle Unruhe erzeugen.
- Setze Skeletons nur für das initiale, kurzzeitige Laden ein. Für andere Lade-
  oder Feedbackprozesse eignet sich etwa der
  [LoadingSpinner](https://flow.mittwald.de/components/status/loading-spinner).
- Vermeide beim Laden einen Cumulative Layout Shift. Das finale Layout sollte
  den Skeleton-Content nahtlos ersetzen.
- Signalisiere den Ladezustand über `aria-busy` am umgebenden Container. Das
  Skeleton selbst nutzt bereits `aria-hidden`; setze `aria-busy` nach dem Laden
  auf `false` (siehe
  [MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy)).

## Skeleton vs. SkeletonText

Skeleton und [SkeletonText](https://flow.mittwald.de/components/content/skeleton-text) haben dasselbe
Erscheinungsbild, unterscheiden sich aber in ihrer Größe.

**Verwende Skeleton für ...**

- Flächen, deren Größe du selbst festlegst.
- Bilder, [Avatare](https://flow.mittwald.de/components/content/avatar) und andere grafische Elemente.

**Verwende SkeletonText für ...**

- Textzeilen, deren Höhe sich aus der umgebenden Typografie ergibt.
- Überschriften, Fließtext und Labels.

---

# Benutzerdefinierte Größe

Skeletons können mit dem `width`- oder `height`-Attribut angepasst werden, um
die grobe Ladevorschau an die Benutzeroberfläche anzupassen.

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

<>
  <Skeleton height="100px" />
  <Skeleton height="100px" width="100px" />
</>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `height` | `Height<string \| number>` | - | The height of the skeleton. |
| `width` | `Width<string \| number>` | - | The width of the skeleton. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# SkeletonMode

Der SkeletonMode stellt die echte Oberfläche als Skeleton dar, bis der Content geladen ist.

> **mStudio-Extensions:** Importiere `SkeletonMode` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import {
  Content,
  Heading,
  Label,
  LabeledValue,
  Section,
  SkeletonMode,
  Switch,
  Text,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [isLoading, setIsLoading] = useState(true);

  return (
    <Section>
      <Switch
        isSelected={isLoading}
        onChange={setIsLoading}
      >
        Ladezustand anzeigen
      </Switch>
      <SkeletonMode isEnabled={isLoading}>
        <Section>
          <Heading>Webshop Relaunch</Heading>
          <Text>
            Das Projekt liegt auf dem Server p-4711 und wird
            jede Nacht gesichert.
          </Text>
          <LabeledValue>
            <Label>Speicherplatz</Label>
            <Content>20 GB</Content>
          </LabeledValue>
        </Section>
      </SkeletonMode>
    </Section>
  );
}
```

---

# Best Practices

- Umschließe die finale Oberfläche mit dem SkeletonMode, statt eine eigene
  Ladeansicht aus [Skeleton](https://flow.mittwald.de/components/content/skeleton) und
  [SkeletonText](https://flow.mittwald.de/components/content/skeleton-text) nachzubauen. So entspricht
  die Vorschau dem finalen Layout, und es entsteht kein Layout-Sprung.
- Gib Platzhalter-Inhalt mit, wenn ein Balken eine bestimmte Breite haben soll.
  Components mit Inhalt übernehmen dessen Breite, Components ohne Inhalt nutzen
  eine Standardbreite.
- Gib einem Image ohne feste Größe ein `aspectRatio`. Das Skeleton lädt das Bild
  nicht, kennt sein Seitenverhältnis also nicht und nimmt sonst 16:9 an.
- Nimm bereits geladene Bereiche mit `isEnabled={false}` aus dem Skeleton
  heraus.
- Setze den SkeletonMode nur für das initiale, kurzzeitige Laden ein. Für andere
  Lade- oder Feedbackprozesse eignet sich etwa der
  [LoadingSpinner](https://flow.mittwald.de/components/status/loading-spinner).
- Verlass dich auf die eingebaute Ansage. Der SkeletonMode meldet Screenreadern
  einmal „Inhalt wird geladen“ und nimmt die Platzhalter selbst aus dem
  Accessibility Tree.
- Schalte den SkeletonMode nicht ein, während der Fokus in seinem Inhalt liegt.
  Der Fokus geht dabei verloren.

---

# Inhalt und Breite

Components mit Inhalt werden zu einem Balken pro Zeile, in der Breite dieser
Zeile. Components ohne Inhalt zeigen einen Balken in einer Standardbreite.

```tsx
import {
  Heading,
  Section,
  SkeletonMode,
  Switch,
  Text,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [isLoading, setIsLoading] = useState(true);
  const domain = {
    hostname: "webshop.example-domain.de",
    type: "Subdomain",
    project: "Webshop Relaunch",
    createdAt: "Angelegt am 12.03.2025",
  };

  return (
    <Section>
      <Switch
        isSelected={isLoading}
        onChange={setIsLoading}
      >
        Ladezustand anzeigen
      </Switch>
      <SkeletonMode isEnabled={isLoading}>
        <Section>
          {/* Platzhalter-Inhalt bestimmt die Breite */}
          <Heading>
            {isLoading
              ? "example-domain.de"
              : domain.hostname}
          </Heading>
          <Text>
            {isLoading ? "Subdomain" : domain.type}
          </Text>
          {/* Ohne Inhalt: Standardbreite */}
          <Heading>
            {isLoading ? null : domain.project}
          </Heading>
          <Text>{isLoading ? null : domain.createdAt}</Text>
        </Section>
      </SkeletonMode>
    </Section>
  );
}
```

---

# Teilweise geladen

Ein verschachtelter SkeletonMode mit `isEnabled={false}` stellt seinen Inhalt
als echte Oberfläche dar – etwa eine Überschrift, die schon vor den Daten
feststeht.

```tsx
import {
  Heading,
  Section,
  SkeletonMode,
  Switch,
  Text,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [isLoading, setIsLoading] = useState(true);

  return (
    <Section>
      <Switch
        isSelected={isLoading}
        onChange={setIsLoading}
      >
        Ladezustand anzeigen
      </Switch>
      <SkeletonMode isEnabled={isLoading}>
        <Section>
          <SkeletonMode isEnabled={false}>
            <Heading>Speicherplatz</Heading>
          </SkeletonMode>
          <Text>Belegt sind 12,4 GB von 20 GB.</Text>
        </Section>
      </SkeletonMode>
    </Section>
  );
}
```

---

# Bilder, Badges und Buttons

Avatare, Icons, Images, Badges und Buttons behalten Form und Größe und werden zu
einer Fläche. Ihr Inhalt ist ausgeblendet, ein Text in einem Button oder Badge
zeigt keinen eigenen Balken. Ein Image lädt im SkeletonMode nichts. Es nimmt die
Größe aus `width` und `height`. Eine fehlende Angabe ergibt sich aus
`aspectRatio`, sonst aus dem Seitenverhältnis 16:9. Ohne beide Angaben füllt es
die verfügbare Breite. Buttons, als Button gestaltete Links und
ContextMenu-Trigger lassen sich nicht bedienen.

```tsx
import {
  ActionGroup,
  AlertBadge,
  Avatar,
  Badge,
  Button,
  CopyButton,
  Flex,
  Heading,
  IconDomain,
  Image,
  Initials,
  Link,
  Section,
  SkeletonMode,
  Switch,
  Text,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [isLoading, setIsLoading] = useState(true);

  return (
    <Section>
      <Switch
        isSelected={isLoading}
        onChange={setIsLoading}
      >
        Ladezustand anzeigen
      </Switch>
      <SkeletonMode isEnabled={isLoading}>
        <Section>
          <Heading>
            Webshop Relaunch
            <Badge color="green">Neu</Badge>
          </Heading>
          <Flex gap="m" align="center">
            <Avatar>
              <Initials>Max Mustermann</Initials>
            </Avatar>
            <Text>Max Mustermann ist Projektinhaber.</Text>
          </Flex>
          <Flex gap="m" align="center">
            <IconDomain />
            <Text>webshop.example-domain.de</Text>
            <CopyButton text="webshop.example-domain.de" />
            <AlertBadge status="warning">
              Zertifikat läuft ab
            </AlertBadge>
          </Flex>
          <Image
            src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
            alt="mittwald"
            width={100}
            aspectRatio={1}
          />
          <ActionGroup>
            <Link href="#">
              <Button color="secondary" variant="soft">
                Zum Projekt
              </Button>
            </Link>
            <Button color="primary">Speichern</Button>
          </ActionGroup>
        </Section>
      </SkeletonMode>
    </Section>
  );
}
```

---

# Formularfelder

Formularfelder behalten ihre Größe. Label und FieldDescription werden zu Balken,
das Eingabefeld oder Steuerelement – etwa die Box einer
[Checkbox](https://flow.mittwald.de/components/form-controls/checkbox) oder der Track eines
[Switch](https://flow.mittwald.de/components/form-controls/switch) – wird zu einer Fläche. Ein
FieldError wird nicht angezeigt, auch wenn das Feld ungültig ist.

- Die Felder sind nicht fokussierbar und nehmen keine Eingaben an. Auch Popover
  wie das Kalender-Popover des
  [DatePicker](https://flow.mittwald.de/components/form-controls/date-picker) oder die Optionen eines
  [Select](https://flow.mittwald.de/components/form-controls/select) öffnen sich nicht.
- Die Felder behalten ihr echtes `input`. Wird ein Formular während des Ladens
  abgeschickt, sendet es die leeren Werte der Felder. Verhindere das Absenden,
  solange der SkeletonMode aktiv ist.

```tsx
import {
  Checkbox,
  ColumnLayout,
  FieldDescription,
  Label,
  Option,
  Section,
  Select,
  SkeletonMode,
  Slider,
  Switch,
  TextField,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [isLoading, setIsLoading] = useState(true);

  return (
    <Section>
      <Switch
        isSelected={isLoading}
        onChange={setIsLoading}
      >
        Ladezustand anzeigen
      </Switch>
      <SkeletonMode isEnabled={isLoading}>
        <Section>
          <ColumnLayout m={[1, 1]}>
            <TextField defaultValue="wordpress_prod">
              <Label>Datenbankname</Label>
              <FieldDescription>
                Nur Kleinbuchstaben und Unterstriche
              </FieldDescription>
            </TextField>
            <Select defaultValue="8.4">
              <Label>MySQL-Version</Label>
              <Option value="8.0">8.0</Option>
              <Option value="8.4">8.4</Option>
            </Select>
          </ColumnLayout>
          <Slider
            defaultValue={20}
            minValue={5}
            maxValue={100}
          >
            <Label>Speicherplatz in GB</Label>
          </Slider>
          <Checkbox defaultSelected>
            Tägliches Backup
          </Checkbox>
          <Switch defaultSelected>
            Fernzugriff erlauben
          </Switch>
        </Section>
      </SkeletonMode>
    </Section>
  );
}
```

---

# Navigation und Status

Navigationen, Breadcrumbs und Tabs behalten ihre Struktur. Ihre Einträge werden
zu Balken und lassen sich weder fokussieren noch auswählen. Ein aktiver Eintrag
ist nicht hervorgehoben. Status-Components wie Alert oder ProgressBar zeigen
keine Statusfarbe: Die ProgressBar zeigt ihre Leiste ohne Füllung und ohne Wert,
LoadingSpinner und AlertIcon werden zu runden Flächen.

```tsx
import {
  Alert,
  Content,
  Heading,
  Label,
  Link,
  ProgressBar,
  Section,
  SkeletonMode,
  Switch,
  Tab,
  TabNavigation,
  Tabs,
  TabTitle,
  Text,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [isLoading, setIsLoading] = useState(true);

  return (
    <Section>
      <Switch
        isSelected={isLoading}
        onChange={setIsLoading}
      >
        Ladezustand anzeigen
      </Switch>
      <SkeletonMode isEnabled={isLoading}>
        <Section>
          <TabNavigation aria-label="Projekt">
            <Link href="#" aria-current="page">
              Übersicht
            </Link>
            <Link href="#">Domains</Link>
            <Link href="#">Backups</Link>
          </TabNavigation>
          <Alert status="danger">
            <Heading>Zertifikat abgelaufen</Heading>
            <Content>
              Die Domain webshop.example-domain.de ist nicht
              mehr per HTTPS erreichbar.
            </Content>
          </Alert>
          <ProgressBar value={72} status="warning">
            <Label>Speicherplatz</Label>
          </ProgressBar>
          <Tabs aria-label="Einstellungen">
            <Tab id="general">
              <TabTitle>Allgemein</TabTitle>
              <Text>
                Der Projektname erscheint in allen
                Rechnungen.
              </Text>
            </Tab>
            <Tab id="backups">
              <TabTitle>Backups</TabTitle>
              <Text>
                Backups werden jede Nacht erstellt.
              </Text>
            </Tab>
          </Tabs>
        </Section>
      </SkeletonMode>
    </Section>
  );
}
```

---

# Inhalte, Diagramme und Editoren

Kbd, CodeBlock, FileDropZone, Kalender und ImageCropper werden zu einer Fläche
in ihrer Größe. Markdown, Tabellen und Listen folgen den Regeln ihres Inhalts.
Diagramme und Editoren zeigen eine Fläche und laden weder Diagramm noch Editor.
Die Höhe stammt aus `height`, beim CodeEditor aus der Zahl der Code-Zeilen. Ein
Bild in Markdown oder im ImageCropper wird nicht geladen. Overlays lassen sich
über einen Trigger im SkeletonMode nicht öffnen. Ein bereits geöffnetes Modal
zeigt seinen Inhalt als Skeleton und schließt mit Escape.

```tsx
import {
  Bar,
  CartesianChart,
  CodeBlock,
  ColumnLayout,
  DonutChart,
  Heading,
  Section,
  SkeletonMode,
  Switch,
  Table,
  TableBody,
  TableCell,
  TableColumn,
  TableHeader,
  TableRow,
  XAxis,
  YAxis,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [isLoading, setIsLoading] = useState(true);

  return (
    <Section>
      <Switch
        isSelected={isLoading}
        onChange={setIsLoading}
      >
        Ladezustand anzeigen
      </Switch>
      <SkeletonMode isEnabled={isLoading}>
        <Section>
          <Heading>Webshop Relaunch</Heading>
          <ColumnLayout m={[2, 1]}>
            <CartesianChart
              height="160px"
              data={[
                { month: "Juli", requests: 1200 },
                { month: "August", requests: 1800 },
              ]}
            >
              <XAxis dataKey="month" />
              <YAxis />
              <Bar dataKey="requests" />
            </CartesianChart>
            <DonutChart
              value={70}
              aria-label="Speicherplatz"
            />
          </ColumnLayout>
          <CodeBlock
            code={`server {
  listen 443 ssl;
  server_name webshop.example-domain.de;
}`}
          />
          <Table aria-label="Zertifikate">
            <TableHeader>
              <TableColumn>Domain</TableColumn>
              <TableColumn>Gültig bis</TableColumn>
            </TableHeader>
            <TableBody>
              <TableRow>
                <TableCell>
                  webshop.example-domain.de
                </TableCell>
                <TableCell>12.01.2027</TableCell>
              </TableRow>
            </TableBody>
          </Table>
        </Section>
      </SkeletonMode>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `isEnabled` | `boolean` | `true` | Whether the components inside render as skeleton. A nested `SkeletonMode` with `isEnabled={false}` renders its content as real UI. |

---

# SkeletonText

Der SkeletonText zeigt eine vereinfachte Vorschau einer Textzeile, bis der Content geladen ist.

> **mStudio-Extensions:** Importiere `SkeletonText` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import {
  SkeletonText,
  Text,
} from "@mittwald/flow-react-components";

<Text>
  <SkeletonText />
</Text>
```

---

# Best Practices

- Nutze für Ladeansichten bevorzugt den
  [SkeletonMode](https://flow.mittwald.de/components/content/skeleton-mode). Er stellt die finale
  Oberfläche als Skeleton dar, sodass keine eigene Ladeansicht nötig ist.
- Platziere den SkeletonText in der Component, die später den Text enthält (z.
  B. [Text](https://flow.mittwald.de/components/content/text) oder
  [Heading](https://flow.mittwald.de/components/content/heading)). So entspricht seine Höhe der finalen
  Typografie und es entsteht kein Layout-Sprung.
- Wähle die Breite ungefähr passend zur Länge des erwarteten Textes.
- Verwende pro Textblock nur wenige Zeilen. Zwei bis drei genügen, um den Inhalt
  anzudeuten, ohne visuelle Unruhe zu erzeugen.
- Variiere bei mehreren Zeilen die Breite der letzten Zeile, damit der Block wie
  echter Fließtext wirkt.
- Setze den SkeletonText nur für das initiale, kurzzeitige Laden ein. Für andere
  Lade- oder Feedbackprozesse eignet sich etwa der
  [LoadingSpinner](https://flow.mittwald.de/components/status/loading-spinner).

## SkeletonText vs. Skeleton

SkeletonText und [Skeleton](https://flow.mittwald.de/components/content/skeleton) haben dasselbe
Erscheinungsbild, unterscheiden sich aber in ihrer Größe.

**Verwende SkeletonText für ...**

- Textzeilen, deren Höhe sich aus der umgebenden Typografie ergibt.
- Überschriften, Fließtext und Labels.

**Verwende Skeleton für ...**

- Flächen, deren Größe du selbst festlegst.
- Bilder, [Avatare](https://flow.mittwald.de/components/content/avatar) und andere grafische Elemente.

---

# Breite

Ohne weitere Angabe füllt der SkeletonText die volle Breite des umgebenden
Elements. Über das `width`-Property lässt sich die Breite anpassen, damit die
Vorschau der erwarteten Textlänge entspricht.

```tsx
import {
  SkeletonText,
  Text,
} from "@mittwald/flow-react-components";

<>
  <Text>
    <SkeletonText />
  </Text>
  <Text>
    <SkeletonText width="60%" />
  </Text>
  <Text>
    <SkeletonText width="12em" />
  </Text>
</>
```

---

# Kombiniere mit ...

## Heading

Platziere einen SkeletonText innerhalb einer
[Heading](https://flow.mittwald.de/components/content/heading), damit er deren Schriftgröße übernimmt.

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

<Heading level={1}>
  <SkeletonText width="8em" />
</Heading>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | `Width<string \| number>` | - | The width of the skeleton text. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Text

Die Text-Component sorgt für eine konsistente Formatierung und Strukturierung von Text.

> **mStudio-Extensions:** Importiere `Text` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `wrapWith`.

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

<Text>Das ist ein Text</Text>
```

---

# Best Practices

- Formuliere Texte prägnant, verständlich und hilfreich. Orientiere dich am
  [Sprach-Guide](https://flow.mittwald.de/foundations/content-guidelines/sprach-guide).
- Halte die Benutzeroberfläche auch ohne Text verständlich. Text wird häufig nur
  unaufmerksam wahrgenommen.
- Begrenze die Zeilenlänge auf höchstens 75 Zeichen. Längere Zeilen erschweren
  die Lesbarkeit.
- Kennzeichne Absätze über `elementType` korrekt als `<p>`.

---

# Color

Zusätzlich zur Standard-Color kann Text in **Light** und **Dark** dargestellt
werden, wenn die Standard-Color auf farbigen oder dekorativen Hintergründen
nicht gut funktioniert. Wann welche Color passt, beschreibt
[Color](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

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

<Text color="dark">Das ist ein Text</Text>
```

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

<Text color="light">Das ist ein Text</Text>
```

---

# Size

Neben der Default-Schriftgröße unterstützt Text auch die Size **Small**. Nutze
das `<small>`-Tag, um sie zu verwenden.

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

<Text>
  <small>Das ist ein Text in small</small>
</Text>
```

---

# Mit elementType

Verwende die `elementType`-Property, um festzulegen, welches HTML-Element die
Text-Component rendern soll. Standardmäßig wird ein `<span>` erzeugt. Für
Fließtexte, die als eigenständige Absätze erkennbar sein sollen, verwende
stattdessen ein `<p>`-Element.

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

<Text elementType="p">Das ist ein Absatz</Text>
```

---

# HTML-Elemente und Formatierungen

Die Text-Component unterstützt alle gängigen Formatierungen und Elemente wie
`<strong>`, `<i>`, `<ul>` und `<ol>`.

Kompatibilität mit Remote Components

Bei der Verwendung von Text als Remote Component wird nicht jede HTML
Formatierung unterstützt. Aktuell sind dies nur strong, ul, ol, li, small,
br. Wenn dir etwas fehlt, sag uns gerne auf GitHub Bescheid.

Feedback geben

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

<>
  <Text>
    <ul>
      <li>Item 1</li>
      <li>Item 2</li>
    </ul>
  </Text>
  <Text>
    Dies ist ein <strong>Beispiel</strong> für{" "}
    <i>verschiedene</i> HTML-Formatierungen.
  </Text>
</>
```

---

# No Ligatures

Verwende die `noLigatures`-Property, um typografische Ligaturen in der
Text-Component zu deaktivieren. Dadurch werden Zeichen unverändert und einzeln
dargestellt.

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

<>
  <Text>
    <b>4x5</b>=20
  </Text>
  <Text>vs.</Text>
  <Text noLigatures>
    Short-ID: p-ah<b>4x5</b>fs
  </Text>
</>
```

---

# Kombiniere mit ...

## Combine

Benutze die [Combine-Component](https://flow.mittwald.de/components/structure/combine), um neben dem
Text z. B. ein [Icon](https://flow.mittwald.de/components/content/icon), einen
[CopyButton](https://flow.mittwald.de/components/actions/copy-button) oder ein
[ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help) zu platzieren.

```tsx
import {
  Combine,
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  CopyButton,
  IconDomain,
  Text,
} from "@mittwald/flow-react-components";

<>
  <Combine>
    <IconDomain />
    <Text>mail.agenturserver.de</Text>
  </Combine>

  <Combine>
    <Text>mail.agenturserver.de</Text>
    <CopyButton text="mail.agenturserver.de" />
  </Combine>

  <Combine>
    <Text>mail.agenturserver.de</Text>
    <ContextualHelpTrigger>
      <Button />
      <ContextualHelp>
        <Text>
          Hier wird die URL des Servers angezeigt, der für
          den E-Mail-Versand genutzt wird.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Combine>
</>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "end" \| "center"` | `"start"` | The alignment of the text. |
| `children` | `ReactNode` | - | - |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static"` | `"default"` | The color of the text. |
| `elementType` | `"div" \| "span" \| "p" \| ExoticComponent<{}>` | - | The HTML element or React component rendered as the elements root. |
| `emulateBoldWidth` | `boolean` | - | Whether the elements width should match the width it would have with bold text. |
| `noLigatures` | `boolean` | - | Disables standard and contextual ligatures for predictable, literal text rendering. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `whiteSpace` | `WhiteSpace` | - | The white-space property of the text. |
| `wordBreak` | `"-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "normal" \| "auto-phrase" \| "break-all" \| "break-word" \| "keep-all"` | - | The word-break property of the text. |
| `wrap` | `"wrap" \| "balance" \| "pretty"` | - | The text-wrap property of the text. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--text--blockquote-border-width` | `4px` |
| `--text--blockquote-border-style` | `solid` |
| `--text--blockquote-padding` | `0.5rem` |
| `--text--list-padding` | `1.5rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--text--color--default` | `#121518` | `#FFFFFF` |
| `--text--color--light` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--text--color--dark` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--text--color--light-static` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--text--color--dark-static` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--text--color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--text--blockquote-border-color` | `#0054F5` | `#85AFFF` |

---

# Truncate

Truncate kürzt zu lange Texte automatisch mit "…" ab.

> **mStudio-Extensions:** Importiere `Truncate` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

Accessibility-Warnung

Die Component verwendet das
[title-Attribut](https://html.spec.whatwg.org/multipage/dom.html#the-title-attribute),
um den vollständigen Inhalt sichtbar zu machen. Für Tastatur-User ist dieses
jedoch nicht zugänglich, da Browser keine Möglichkeit bieten,
`title`-Tooltips per Tastatur anzuzeigen. Verwende `Truncate` daher nur in
Ausnahmefällen und stelle wichtige Inhalte an anderer Stelle vollständig
dar.

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

<Truncate
  title="Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
  sed diam nonumy eirmod tempor invidunt ut labore et dolore
  magna aliquyam erat, sed diam voluptua."
>
  Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
  sed diam nonumy eirmod tempor invidunt ut labore et dolore
  magna aliquyam erat, sed diam voluptua.
</Truncate>
```

---

# Best Practices

- Kürze keine kritischen Informationen ab, die zum Verständnis oder zur
  Bedienung nötig sind.
- Mach den vollständigen Inhalt an anderer Stelle zugänglich.

---

# Mit Offset

Um zum Beispiel bei Pfaden sowohl den Anfang als auch das Ende sichtbar zu
halten, kann über die Property `offset` festgelegt werden, wie viele Zeichen vom
Ende angezeigt werden sollen. Zusätzlich lässt sich mit `ellipsis` ein
individueller Platzhalter definieren.

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

<Truncate offset={9} ellipsis="[...]">
  https://flow.mittwald.de/components/lorem/ipsum/dolor/sit/amet/consetetur/sadipscing/elitr/sed/diam/nonumy/eirmod/tempor/invidunt/ut/labore/et/dolore/content/truncate/overview
</Truncate>
```

---

# Kombiniere mit ...

## Text

Kombiniere Truncate mit [Text](https://flow.mittwald.de/components/content/text), um langen Fließtext
einzeilig zu kürzen.

```tsx
import {
  Text,
  Truncate,
} from "@mittwald/flow-react-components";

<Text>
  <Truncate>
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
    sed diam nonumy eirmod tempor invidunt ut labore et
    dolore magna aliquyam erat, sed diam voluptua. At vero
    eos et accusam et justo duo dolores et ea rebum. Stet
    clita kasd gubergren, no sea takimata sanctus est Lorem
    ipsum dolor sit amet. Lorem ipsum dolor sit amet,
    consetetur sadipscing elitr, sed diam nonumy eirmod
    tempor invidunt ut labore et dolore magna aliquyam erat,
    sed diam voluptua.
  </Truncate>
</Text>
```

## Heading

Kombiniere Truncate mit [Heading](https://flow.mittwald.de/components/content/heading), um lange
Überschriften zu kürzen.

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

<Heading>
  <Truncate>
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
    sed diam nonumy eirmod tempor invidunt ut labore et
    dolore magna aliquyam erat, sed diam voluptua. At vero
    eos et accusam et justo duo dolores et ea rebum. Stet
    clita kasd gubergren, no sea takimata sanctus est Lorem
    ipsum dolor sit amet. Lorem ipsum dolor sit amet,
    consetetur sadipscing elitr, sed diam nonumy eirmod
    tempor invidunt ut labore et dolore magna aliquyam erat,
    sed diam voluptua.
  </Truncate>
</Heading>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `ellipsis` | `string` | `...` | Ellipsis that is added into the text in case it is truncated |
| `offset` | `number` | `8` | the position(from the end) of the ellipsis that shows in text |
| `title` | `string` | - | The `title` attribute of the elements root, which browsers show as a native tooltip on hover. It is not derived from the children — pass the full text to make it readable while truncated. |

---

# BigNumber

Die BigNumber stellt Kennzahlen und Metriken prominent dar.

> **mStudio-Extensions:** Importiere `BigNumber` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import {
  BigNumber,
  Text,
} from "@mittwald/flow-react-components";

<BigNumber>
  <Text>69%</Text>
  <Text>Performance</Text>
</BigNumber>
```

---

# Best Practices

- Zeige nur Werte mit unmittelbarer Relevanz oder Aussagekraft.
- Gib der Zahl ausreichend Raum. So wirkt sie optisch und konkurriert nicht mit
  anderen Elementen.

---

# Kombiniere mit ...

## Rating

Nutze das [Rating](https://flow.mittwald.de/components/form-controls/rating), um den Kontext der
BigNumber für die User auf einer Bewertungsskala besser einzuordnen.

```tsx
import {
  BigNumber,
  Flex,
  Rating,
  Text,
} from "@mittwald/flow-react-components";

<Flex direction="column" gap="s" align="center">
  <BigNumber>
    <Text>80%</Text>
    <Text>Performance</Text>
  </BigNumber>
  <Rating aria-label="Performance" value={4} isReadOnly />
</Flex>
```

## AccentBox

Zur visuellen Hervorhebung kann die BigNumber innerhalb einer
[AccentBox](https://flow.mittwald.de/components/structure/accent-box) angezeigt werden.

```tsx
import {
  AccentBox,
  BigNumber,
  Button,
  ColumnLayout,
  Flex,
  Text,
} from "@mittwald/flow-react-components";

<ColumnLayout>
  <AccentBox>
    <Flex direction="column" gap="s" align="center">
      <BigNumber>
        <Text>250 ms</Text>
        <Text>Dateioperationen</Text>
      </BigNumber>
      <Text>
        <small>Geringer Optimierungsbedarf</small>
      </Text>
      <Button size="s" variant="outline" color="secondary">
        Details anzeigen
      </Button>
    </Flex>
  </AccentBox>
  <AccentBox>
    <Flex direction="column" gap="xs" align="center">
      <BigNumber>
        <Text>100 ms</Text>
        <Text>Serveroperationen</Text>
      </BigNumber>
      <Text>
        <small>Optimierungsbedarf</small>
      </Text>
      <Button size="s" variant="outline" color="secondary">
        Details anzeigen
      </Button>
    </Flex>
  </AccentBox>
</ColumnLayout>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--big-number--spacing` | `0.25rem` |
| `--big-number--top-font-size` | `2rem` |
| `--big-number--bottom-font-size` | `1rem` |
| `--big-number--font-weight` | `bold` |

---

# CartesianChart

Das CartesianChart stellt Metriken als Linien-, Flächen- oder Balkendiagramm dar.

> **mStudio-Extensions:** Importiere `CartesianChart` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

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

export default () => {
  const CartesianChart = typedCartesianChart<{
    Zeit: string;
    Datenbanken: number;
    Projekte: number;
  }>();

  return (
    <CartesianChart.Chart
      data={[
        {
          Zeit: "0 Uhr",
          Datenbanken: 40,
          Projekte: 24,
        },
        {
          Zeit: "1 Uhr",
          Datenbanken: 30,
          Projekte: 13,
        },
        {
          Zeit: "2 Uhr",
          Datenbanken: 20,
          Projekte: 78,
        },
        {
          Zeit: "3 Uhr",
          Datenbanken: 27,
          Projekte: 39,
        },
      ]}
    >
      <CartesianChart.Area dataKey="Datenbanken" unit="%" />
      <CartesianChart.Area
        dataKey="Projekte"
        color="palatinate-blue"
        unit="%"
      />
      <CartesianChart.XAxis dataKey="Zeit" />
      <CartesianChart.YAxis domain={[0, 100]} unit=" %" />
      <CartesianChart.Grid />
      <CartesianChart.Legend />
      <CartesianChart.Tooltip />
    </CartesianChart.Chart>
  );
}
```

---

# Best Practices

- Halte die x-Achse immer zeitbasiert.
- Stelle Dimensionen mit
  [Categorical Colors](https://flow.mittwald.de/foundations/design/colors#categorical-color) dar.
- Sortiere die Areas bei der Area-Darstellung nach Größe, die größte unten.
- Halte die Zahl der Dimensionen übersichtlich. Das sichert die Lesbarkeit.
- Bei der Bar-Darstellung darf die x-Achse auch kategorisch sein. Balken
  vergleichen Kategorien, nicht nur Zeitpunkte.
- Stapele Balken nur dort, wo die Summe eine Bedeutung hat.

---

# Darstellungstypen

Im CartesianChart können unterschiedliche Darstellungstypen wie `<Area />`,
`<Line />`, `<Bar />` oder eine Kombination daraus verwendet werden.

Unter der Haube arbeitet [Recharts](https://recharts.github.io). Flow hat
einiges daran angepasst: Farben, Linienstärke und Punkte folgen dem Flow-Design,
Tooltip und Legende sind eigene Flow-Komponenten, und die Properties sind auf
das Wesentliche reduziert. Die vorhandenen Properties verhalten sich wie in
Recharts. Details dazu findest du in der Recharts-Dokumentation, die bei jedem
Darstellungstyp verlinkt ist.

## Line

Zeigt die Entwicklung einzelner Objekte über einen Zeitraum und ermöglicht den
Vergleich zwischen ihnen. Properties wie `type` und `unit` entsprechen denen von
Recharts, siehe [Line in Recharts](https://recharts.github.io/en-US/api/Line/).

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

export default () => {
  const data = [
    {
      Datum: "1.9.2025",
      "Projekt A": 1256,
      "Projekt B": 345,
      "Projekt C": 467,
    },
    {
      Datum: "2.9.2025",
      "Projekt A": 1342,
      "Projekt B": 876,
      "Projekt C": 45,
    },
    {
      Datum: "3.9.2025",
      "Projekt A": 342,
      "Projekt B": 576,
      "Projekt C": 123,
    },
  ];

  const CartesianChart = typedCartesianChart<{
    Datum: string;
    "Projekt A": number;
    "Projekt B": number;
    "Projekt C": number;
  }>();

  return (
    <Section>
      <Heading>Besucher</Heading>
      <CartesianChart.Chart data={data} height="300px">
        <CartesianChart.Line dataKey="Projekt A" />
        <CartesianChart.Line
          dataKey="Projekt B"
          color="palatinate-blue"
        />
        <CartesianChart.Line
          dataKey="Projekt C"
          color="tangerine"
        />
        <CartesianChart.XAxis dataKey="Datum" />
        <CartesianChart.YAxis />
        <CartesianChart.Grid />
        <CartesianChart.Legend />
        <CartesianChart.Tooltip
          formatter={(v, k) => `${k} (${v} Besucher)`}
        />
      </CartesianChart.Chart>
    </Section>
  );
}
```

## Area

Zeigt die Entwicklung des Gesamtwerts über einen Zeitraum und den jeweiligen
Anteil einzelner Objekte daran. Properties wie `type`, `stackId` und
`fillOpacity` entsprechen denen von Recharts, siehe
[Area in Recharts](https://recharts.github.io/en-US/api/Area/).

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

export default () => {
  const data = [
    {
      Datum: "1.9.2025",
      Datenbanken: 10,
      Webspace: 15.4,
      Email: 5.1,
    },
    {
      Datum: "2.9.2025",
      Datenbanken: 32.9,
      Webspace: 25.6,
      Email: 10,
    },
    {
      Datum: "3.9.2025",
      Datenbanken: 40,
      Webspace: 20.2,
      Email: 8,
    },
  ];

  const CartesianChart = typedCartesianChart<{
    Datum: string;
    Datenbanken: number;
    Webspace: number;
    Email: number;
  }>();

  return (
    <Section>
      <Heading>Speicherplatz</Heading>
      <CartesianChart.Chart data={data} height="300px">
        <CartesianChart.Area
          dataKey="Datenbanken"
          unit="%"
        />
        <CartesianChart.Area
          dataKey="Webspace"
          color="palatinate-blue"
          unit="%"
        />
        <CartesianChart.Area
          dataKey="Email"
          color="tangerine"
          unit="%"
        />
        <CartesianChart.XAxis dataKey="Datum" />
        <CartesianChart.YAxis domain={[0, 100]} unit=" %" />
        <CartesianChart.Grid />
        <CartesianChart.Legend />
        <CartesianChart.Tooltip
          formatter={(value, name) =>
            `${name}: ${Intl.NumberFormat(undefined, {
              style: "unit",
              unit: "gigabyte",
            }).format(
              typeof value === "number" ? value : 0,
            )}`
          }
          progressBarFormatter={(value) =>
            Intl.NumberFormat(undefined, {
              style: "unit",
              unit: "gigabyte",
            }).format(typeof value === "number" ? value : 0)
          }
        />
      </CartesianChart.Chart>
    </Section>
  );
}
```

## Bar

Vergleicht Werte einzelner Kategorien miteinander. Ohne `stackId` stehen die
Balken einer Kategorie nebeneinander. Properties wie `barSize`, `maxBarSize` und
`minPointSize` entsprechen denen von Recharts, siehe
[Bar in Recharts](https://recharts.github.io/en-US/api/Bar/).

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

export default () => {
  const data = [
    {
      Monat: "Juli",
      Datenbanken: 10,
      Webspace: 15.4,
      Email: 5.1,
    },
    {
      Monat: "August",
      Datenbanken: 32.9,
      Webspace: 25.6,
      Email: 10,
    },
    {
      Monat: "September",
      Datenbanken: 40,
      Webspace: 20.2,
      Email: 8,
    },
  ];

  const CartesianChart = typedCartesianChart<{
    Monat: string;
    Datenbanken: number;
    Webspace: number;
    Email: number;
  }>();

  return (
    <Section>
      <Heading>Speicherplatz</Heading>
      <CartesianChart.Chart data={data} height="300px">
        <CartesianChart.Bar
          dataKey="Datenbanken"
          unit="GB"
        />
        <CartesianChart.Bar
          dataKey="Webspace"
          color="palatinate-blue"
          unit="GB"
        />
        <CartesianChart.Bar
          dataKey="Email"
          color="tangerine"
          unit="GB"
        />
        <CartesianChart.XAxis dataKey="Monat" />
        <CartesianChart.YAxis unit=" GB" />
        <CartesianChart.Grid />
        <CartesianChart.Legend />
        <CartesianChart.Tooltip />
      </CartesianChart.Chart>
    </Section>
  );
}
```

Mehrere `<Bar />` mit derselben `stackId` werden gestapelt. Das zeigt den Anteil
einzelner Objekte am Gesamtwert einer Kategorie.

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

export default () => {
  const data = [
    {
      Monat: "Juli",
      Datenbanken: 10,
      Webspace: 15.4,
      Email: 5.1,
    },
    {
      Monat: "August",
      Datenbanken: 32.9,
      Webspace: 25.6,
      Email: 10,
    },
    {
      Monat: "September",
      Datenbanken: 40,
      Webspace: 20.2,
      Email: 8,
    },
  ];

  const CartesianChart = typedCartesianChart<{
    Monat: string;
    Datenbanken: number;
    Webspace: number;
    Email: number;
  }>();

  return (
    <Section>
      <Heading>Speicherplatz</Heading>
      <CartesianChart.Chart data={data} height="300px">
        <CartesianChart.Bar
          dataKey="Datenbanken"
          stackId="speicher"
          unit="GB"
        />
        <CartesianChart.Bar
          dataKey="Webspace"
          color="palatinate-blue"
          stackId="speicher"
          unit="GB"
        />
        <CartesianChart.Bar
          dataKey="Email"
          color="tangerine"
          stackId="speicher"
          unit="GB"
        />
        <CartesianChart.XAxis dataKey="Monat" />
        <CartesianChart.YAxis unit=" GB" />
        <CartesianChart.Grid />
        <CartesianChart.Legend />
        <CartesianChart.Tooltip />
      </CartesianChart.Chart>
    </Section>
  );
}
```

### Ausrichtung

Die Property `layout` bestimmt, wo die Kategorie-Achse liegt. Mit dem Default
`horizontal` liegt sie auf der x-Achse, die Balken wachsen nach oben. Mit
`vertical` liegt sie auf der y-Achse und die Balken wachsen zur Seite. Der
`dataKey` wandert dabei auf die `<YAxis />`, die Achsentypen ergeben sich von
selbst.

Nutze die vertikale Ausrichtung für lange Kategorie-Namen oder für viele
Kategorien. Nur Balken lassen sich sinnvoll drehen. `<Line />` und `<Area />`
zeigen einen Verlauf und bleiben horizontal.

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

export default () => {
  const data = [
    { Projekt: "Webshop Produktion", Speicherplatz: 68 },
    { Projekt: "Webshop Staging", Speicherplatz: 42 },
    { Projekt: "Firmenblog", Speicherplatz: 21 },
  ];

  const CartesianChart = typedCartesianChart<{
    Projekt: string;
    Speicherplatz: number;
  }>();

  return (
    <Section>
      <Heading>Speicherplatz pro Projekt</Heading>
      <CartesianChart.Chart
        data={data}
        height="300px"
        layout="vertical"
      >
        <CartesianChart.Bar
          dataKey="Speicherplatz"
          unit="GB"
        />
        <CartesianChart.XAxis unit=" GB" />
        <CartesianChart.YAxis dataKey="Projekt" />
        <CartesianChart.Grid vertical horizontal={false} />
        <CartesianChart.Tooltip />
      </CartesianChart.Chart>
    </Section>
  );
}
```

---

# Color

Für die Farbgebung der Daten können
[Categorical Colors](https://flow.mittwald.de/foundations/design/colors#categorical-color) oder eigene
Farben verwendet werden. Es sollte sichergestellt sein, dass Farben, die direkt
nebeneinander liegen, einen ausreichenden Kontrast zueinander haben.

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

export default () => {
  const CartesianChart = typedCartesianChart<{
    Zeit: string;
    Datenbanken: number;
    Projekte: number;
  }>();

  return (
    <CartesianChart.Chart
      data={[
        {
          Zeit: "0 Uhr",
          Datenbanken: 40,
          Projekte: 24,
        },
        {
          Zeit: "1 Uhr",
          Datenbanken: 30,
          Projekte: 13,
        },
        {
          Zeit: "2 Uhr",
          Datenbanken: 20,
          Projekte: 78,
        },
        {
          Zeit: "3 Uhr",
          Datenbanken: 27,
          Projekte: 39,
        },
      ]}
    >
      <CartesianChart.Area
        dataKey="Datenbanken"
        color="lime"
        unit="%"
      />
      <CartesianChart.Area
        dataKey="Projekte"
        color="#555"
        unit="%"
      />
      <CartesianChart.XAxis dataKey="Zeit" />
      <CartesianChart.YAxis domain={[0, 100]} unit=" %" />
      <CartesianChart.Grid />
      <CartesianChart.Legend />
      <CartesianChart.Tooltip />
    </CartesianChart.Chart>
  );
}
```

---

# Synchronisierte Charts

Zwei CartesianCharts können synchronisiert werden, um den gleichen Zeitraum
darzustellen. Dadurch lassen sich verschiedene Metriken zeitlich exakt
vergleichen.

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

export default () => {
  interface ChartData {
    Zeit: string;
    Datenbanken: number;
    Projekte: number;
  }

  const CartesianChart = typedCartesianChart<ChartData>();

  return (
    <Section>
      <Heading>CPU</Heading>
      <CartesianChart.Chart
        data={[
          {
            Zeit: "0 Uhr",
            Datenbanken: 40,
            Projekte: 24,
          },
          {
            Zeit: "1 Uhr",
            Datenbanken: 30,
            Projekte: 13,
          },
          {
            Zeit: "2 Uhr",
            Datenbanken: 20,
            Projekte: 78,
          },
          {
            Zeit: "3 Uhr",
            Datenbanken: 27,
            Projekte: 39,
          },
        ]}
        height="200px"
        syncId="syncedCharts"
      >
        <CartesianChart.Area
          dataKey="Datenbanken"
          unit="%"
        />
        <CartesianChart.Area
          dataKey="Projekte"
          color="palatinate-blue"
          unit="%"
        />
        <CartesianChart.XAxis dataKey="Zeit" />
        <CartesianChart.YAxis domain={[0, 100]} unit=" %" />
        <CartesianChart.Grid />
        <CartesianChart.Tooltip />
      </CartesianChart.Chart>
      <Heading>RAM</Heading>
      <CartesianChart.Chart
        data={[
          {
            Zeit: "0 Uhr",
            Datenbanken: 39,
            Projekte: 27,
          },
          {
            Zeit: "1 Uhr",
            Datenbanken: 30,
            Projekte: 13,
          },
          {
            Zeit: "2 Uhr",
            Datenbanken: 63,
            Projekte: 10,
          },
          {
            Zeit: "3 Uhr",
            Datenbanken: 24,
            Projekte: 40,
          },
        ]}
        syncId="syncedCharts"
      >
        <CartesianChart.Area
          dataKey="Datenbanken"
          unit="%"
        />
        <CartesianChart.Area
          dataKey="Projekte"
          color="palatinate-blue"
          unit="%"
        />
        <CartesianChart.XAxis dataKey="Zeit" />
        <CartesianChart.YAxis domain={[0, 100]} unit=" %" />
        <CartesianChart.Grid />
        <CartesianChart.Legend />
        <CartesianChart.Tooltip />
      </CartesianChart.Chart>
    </Section>
  );
}
```

---

# Mit EmptyView

Der EmptyView wird angezeigt, sobald die Property `data` des Charts entweder ein
leeres Array enthält oder `undefined` ist. Er dient dazu, leere Zustände visuell
zu kennzeichnen und bietet Orientierung bei Ausnahmefällen wie Ladefehlern,
fehlgeschlagenen Datenabfragen oder nicht vorhandenen Ergebnissen.

```tsx
import {
  CartesianChart,
  Flex,
  Heading,
  IconMonitoring,
  IllustratedMessage,
  XAxis,
  YAxis,
} from "@mittwald/flow-react-components";

export default () => {
  const emptyView = (
    <IllustratedMessage>
      <IconMonitoring />
      <Heading>Keine Daten verfügbar</Heading>
    </IllustratedMessage>
  );

  return (
    <Flex direction="row" grow>
      <CartesianChart emptyView={emptyView}>
        <XAxis />
        <YAxis />
      </CartesianChart>
    </Flex>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | - |
| `data` | `ChartDataValue[]` | - | The data points rendered by the chart. |
| `emptyView` | `ReactNode` | - | View that is provided when data is empty/undefined |
| `flexGrow` | `boolean` | - | Allow the height controlling container to set flex-grow: 1. Can only be used in combination with `height` |
| `height` | `string` | - | The height of the chart. |
| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the axes and graphical items. `"horizontal"` puts the category axis on the x-axis — bars grow upwards. `"vertical"` puts it on the y-axis — bars grow to the side. `XAxis` and `YAxis` follow the layout on their own; only the `dataKey` moves to whichever axis is the categorical one. |
| `syncId` | `string \| number` | - | Charts with the same syncId will synchronize Tooltip and Brush events. @see [Synchronized Charts Example](https://recharts.github.io/en-US/examples/SynchronizedAreaChart/) |
| `syncMethod` | `SyncMethod` | - | Customize how the charts will synchronize tooltips and brushes. `index`: synchronize using the data index in the data array. Index expects that all data has the same length. `value`: synchronize using the data value on categorical axis (categorical: XAxis in horizontal layout, YAxis in vertical layout). function: a custom sync method which receives tick and data as argument and returns an index. @defaultValue index |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--cartesian-chart--transition-duration` | `800ms` |
| `--cartesian-grid--stroke-width` | `1px` |
| `--axis--spacing` | `8px` |
| `--axis--font-size` | `0.875rem` |
| `--axis--stroke-width` | `1px` |
| `--axis--tick-size` | `8px` |
| `--area--border-width` | `2px` |
| `--bar--corner-radius` | `4px` |
| `--line--border-width` | `2px` |
| `--legend--spacing-x` | `16px` |
| `--legend--spacing-y` | `8px` |
| `--legend-item--spacing` | `0.5rem` |
| `--legend-item--marker--size` | `1rem` |
| `--legend-item--marker--corner-radius` | `4px` |
| `--chart-tooltip--spacing` | `8px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--cartesian-grid--color` | `#3A434E` | `#E5EFF8` |
| `--axis--color` | `#3A434E` | `#E5EFF8` |
| `--area--border-color` | `#FFFFFF` | `#1B1F24` |

---

# DonutChart

Das DonutChart stellt Verteilungen und Anteile als Ring dar.

> **mStudio-Extensions:** Importiere `DonutChart` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`.

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

<DonutChart value={30} aria-label="Auslastung" />
```

---

# Best Practices

- Gib dem DonutChart über `aria-label` einen zugänglichen Namen. Sonst liest ein
  Screenreader den Wert vor, ohne zu sagen, worauf er sich bezieht.
- Kombiniere die Status-Farben gezielt, um Zustände hervorzuheben. Wechsle etwa
  bei hoher Speicherplatzauslastung auf Warning oder Danger.
- Mach jede Segmentfarbe eindeutig unterscheidbar. Nutze dafür die
  [Categorical Colors](https://flow.mittwald.de/foundations/design/colors#categorical-color).
- Begrenze die Segmente auf höchstens sechs. Mehr Segmente beeinträchtigen die
  Lesbarkeit stark.
- Sortiere die Segmente nach Größe. Das größte beginnt auf der 12-Uhr-Position,
  die weiteren folgen im Uhrzeigersinn absteigend.

---

# Sizes

Die Size des DonutCharts kann Medium oder Large sein. Medium ist dabei die
Standardgröße.

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

<>
  <DonutChart value={30} aria-label="Auslastung" />
  <DonutChart value={30} aria-label="Auslastung" size="l" />
</>
```

---

# Status

Je nach Anwendungsfall stehen vier Status-Farben zur Auswahl: **Info**,
**Success**, **Warning** und **Danger**.

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

<>
  <DonutChart
    value={30}
    status="success"
    aria-label="Auslastung"
  />
  <DonutChart value={30} aria-label="Auslastung" />
  <DonutChart
    value={80}
    status="warning"
    aria-label="Auslastung"
  />
  <DonutChart
    value={95}
    status="danger"
    aria-label="Auslastung"
  />
</>
```

---

# Mit Unit

Im Default wird das DonutChart immer mit Prozentangabe angezeigt. Über das
Property `formatOptions` können aber auch andere Einheiten gewählt werden (s.
[Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)).

## Gigabyte

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

<DonutChart
  aria-label="Speicherplatz"
  formatOptions={{ style: "unit", unit: "gigabyte" }}
  maxValue={50}
  value={12}
/>
```

## Dezimalzahl

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

<DonutChart
  aria-label="Performance"
  formatOptions={{ style: "decimal" }}
  maxValue={200}
  value={135}
/>
```

---

# Mit alternativem Text

Über die `children` kann der Text innerhalb des DonutCharts überschrieben
werden.

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

<DonutChart
  value={300}
  maxValue={600}
  aria-label="Speicherplatz"
>
  <strong>300</strong>
  <small>GB</small>
</DonutChart>
```

---

# Segmente

Die Anzeige des DonutCharts kann über das `segments` Property um einzelne
Abschnitte ergänzt werden. Der `value` ergibt sich in diesem Fall aus der Summe
der Werte der einzelnen Segmente. Um die einzelnen Werte näher zu erläutern wird
automatisch die `Legend` Component angezeigt. Über das `showLegend` Property
kann diese ein- und ausgeblendet werden. Die Position der Legende kann über das
Property `legendPosition` bestimmt werden.

Die Farben der Segmente werden automatisch festgelegt, können aber über das
`color`-Property, mit
[Categorical Colors](https://flow.mittwald.de/foundations/design/colors#categorical-color) oder eigenen
Colors überschrieben werden. Beim Überschreiben muss darauf geachtet werden,
dass nebeneinander liegende Farben weiterhin einen ausreichenden Kontrast
zueinander haben.

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

<DonutChart
  aria-label="Items"
  segments={[
    { title: "Item 1", value: 28 },
    { title: "Item 2", value: 24 },
    { title: "Item 3", value: 20 },
    { title: "Item 4", value: 10 },
    { title: "Item 5", value: 12 },
    { title: "Item 6", value: 6 },
  ]}
/>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<ProgressBarRenderProps>` | `'react-aria-ProgressBar'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `dir` | `string` | - | - |
| `formatOptions` | `NumberFormatOptions` | `{ style: 'percent' }` | The display format of the value label. |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isIndeterminate` | `boolean` | - | Whether presentation is indeterminate when progress isn't known. |
| `lang` | `string` | - | - |
| `legendPosition` | `"bottom" \| "top" \| "left" \| "right"` | `"right"` | The position of the legend. |
| `maxValue` | `number` | `100` | The largest value allowed for the input. |
| `minValue` | `number` | `0` | The smallest value allowed for the input. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `segments` | `DonutChartSegment[]` | - | Divides the fill of the donut chart into segments |
| `showLegend` | `boolean` | `true` | Whether the legend component is shown when segments are used. |
| `size` | `"m" \| "l"` | `"m"` | The size variant of the donut chart. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `status` | `"info" \| "success" \| "warning" \| "danger"` | - | The status the donut chart is colored by. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `value` | `number` | `0` | The current value (controlled). |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--donut-chart--transition-duration` | `800ms` |
| `--donut-chart--spacing-y` | `0.5rem` |
| `--donut-chart--spacing-x` | `1rem` |
| `--donut-chart--padding--m` | `24px` |
| `--donut-chart--padding--l` | `32px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--donut-chart--border-color` | `#5E6C7A` | `#DCE9F7` |
| `--donut-chart--background-color` | `#F4F8FC` | `#292F37` |
| `--donut-chart--info-fill-background-color` | `#0054F5` | `#85AFFF` |
| `--donut-chart--success-fill-background-color` | `#00825B` | `#4FFFC9` |
| `--donut-chart--warning-fill-background-color` | `#F56800` | `#FFC89F` |
| `--donut-chart--danger-fill-background-color` | `#E1244C` | `#F2A2B3` |

---

# Autocomplete

Autocomplete ergänzt eine Texteingabe um kontextbezogene Vorschläge.

> **mStudio-Extensions:** Importiere `Autocomplete` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  Option,
  Label,
  TextField,
  Autocomplete,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [input, setInput] = useState("");

  const generateSuggestItems = () => {
    return [
      "example.com",
      "test.org",
      "email.net",
      "mail.com",
    ]
      .map((d) => {
        const email = `${input.split("@")[0]}@${d}`;
        return (
          <Option
            key={email}
            value={email}
            textValue={email}
          >
            {email}
          </Option>
        );
      })
      .filter(() => input);
  };

  return (
    <Autocomplete>
      <TextField value={input} onChange={setInput}>
        <Label>Email</Label>
      </TextField>
      {generateSuggestItems()}
    </Autocomplete>
  );
}
```

---

# Best Practices

- Zeige kontextbezogene Vorschläge an.
- Filtere die Vorschlagsliste bei Bedarf sinnvoll vor. Das kann zum Beispiel
  nach Kategorien oder Kontext erfolgen.
- Zeige bei leerem Eingabefeld zunächst keine Vorschläge an.

## Autocomplete vs. ComboBox

Autocomplete und [ComboBoxen](https://flow.mittwald.de/components/form-controls/combo-box) sehen oft
ähnlich aus, erfüllen aber unterschiedliche Zwecke.

**Verwende Autocomplete, um z. B. ...**

- Usern zu ermöglichen, freie Eingaben zu machen, während Vorschläge zur Auswahl angezeigt werden.
- bei langen oder dynamischen Datenlisten (z. B. Städte, Usernamen, Tags).

**Verwende ComboBox, um z. B. ...**

- aus einer vordefinierten Liste von Optionen eine Auswahl zu treffen.
- bei bekannten, überschaubaren Optionen (z. B. Sprachen, Kategorien, Geschlecht).

---

# Benutzerdefinierte Filter

Schränke die Optionen, die dem User zur Auswahl stehen, mithilfe von Filtern
ein.

```tsx
import {
  Option,
  Label,
  TextField,
  Autocomplete,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [input, setInput] = useState("");

  const generateSuggestItems = () => {
    return [
      "example.com",
      "test.org",
      "email.net",
      "mail.com",
    ]
      .map((d) => {
        const email = `${input.split("@")[0]}@${d}`;
        return (
          <Option
            key={email}
            value={email}
            textValue={email}
          >
            {email}
          </Option>
        );
      })
      .filter(() => input);
  };

  const domainDotComFilter = (
    textValue: string,
    ignored_inputValue: string,
  ) => {
    return textValue.includes(".com");
  };

  return (
    <Autocomplete filter={domainDotComFilter}>
      <TextField value={input} onChange={setInput}>
        <Label>Email</Label>
      </TextField>
      {generateSuggestItems()}
    </Autocomplete>
  );
}
```

---

# Kombiniere mit ...

## SearchField

Nutze `<Autocomplete />` mit einem
[SearchField](https://flow.mittwald.de/components/form-controls/search-field), um die User beim Suchen
mit Vorschlägen zu unterstützen.

```tsx
import {
  Label,
  Autocomplete,
  SearchField,
  Option,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [input, setInput] = useState("");

  const components = [
    "Button",
    "Checkbox",
    "ContextMenu",
    "Modal",
    "Select",
    "TextField",
  ];

  const suggestItems = components
    .filter((name) =>
      name.toLowerCase().includes(input.toLowerCase()),
    )
    .map((name) => (
      <Option key={name} value={name} textValue={name}>
        {name}
      </Option>
    ))
    .filter(() => input);

  return (
    <Autocomplete>
      <SearchField value={input} onChange={setInput}>
        <Label>Komponente</Label>
      </SearchField>
      {suggestItems}
    </Autocomplete>
  );
}
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Label,
  Autocomplete,
  Section,
  TextField,
  Option,
} from "@mittwald/flow-react-components";
import { useForm, useWatch } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ email: string }>({
    defaultValues: {
      email: "",
    },
  });
  const Field = typedField(form);

  const currentEmailValue = useWatch({
    name: "email",
    control: form.control,
  });

  const generateSuggestItems = () => {
    return [
      "example.com",
      "test.org",
      "email.net",
      "mail.com",
    ]
      .map((d) => {
        const email = `${currentEmailValue.split("@")[0]}@${d}`;
        return (
          <Option
            key={email}
            value={email}
            textValue={email}
          >
            {email}
          </Option>
        );
      })
      .filter(() => currentEmailValue);
  };

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="email"
          rules={{
            required: "Bitte wähle eine App aus",
          }}
        >
          <Autocomplete>
            <TextField>
              <Label>Test</Label>
            </TextField>
            {generateSuggestItems()}
          </Autocomplete>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `disableAutoFocusFirst` | `boolean` | `false` | Whether or not to focus the first item in the collection after a filter is performed. Note this is only applicable if virtual focus behavior is not turned off via `disableVirtualFocus`. |
| `disableVirtualFocus` | `boolean` | `false` | Whether the autocomplete should disable virtual focus, instead making the wrapped collection directly tabbable. |
| `filter` | `((textValue: string, inputValue: string, node: Node<object>) => boolean)` | - | An optional filter function used to determine if a option should be included in the autocomplete list. Include this if the items you are providing to your wrapped collection aren't filtered by default. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

---

# Checkbox

Eine Checkbox stellt eine Option dar, die aus- oder abgewählt werden kann.

> **mStudio-Extensions:** Importiere `Checkbox` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

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

<Checkbox>
  Ich stimme den AGBs zu und bestätige, dass ich die
  Datenschutzhinweise zur Kenntnis genommen habe.
</Checkbox>
```

---

# Best Practices

- Wähle den initialen Zustand nachvollziehbar und sinnvoll. Möglich sind
  ausgewählt, nicht ausgewählt oder uneindeutig.
- Ordne mehrere Checkboxen logisch und nachvollziehbar an. Mehr dazu unter
  [CheckboxGroup](https://flow.mittwald.de/components/form-controls/checkbox-group).
- Nutze für eine visuell stärkere Auswahl alternativ den
  [CheckboxButton](https://flow.mittwald.de/components/form-controls/checkbox-button).

## Checkbox vs. Switch

Mit den Components Checkbox und [Switch](https://flow.mittwald.de/components/form-controls/switch)
können Optionen aktiviert/ausgewählt werden.

**Verwende eine Checkbox, um z. B. ...**

- dem User eine Auswahloption zur Bestätigung zu geben.
- Auswahlmöglichkeiten in einem Formular anzubieten, die gespeichert werden müssen.

**Verwende einen Switch, um z. B. ...**

- eine Funktion direkt zu aktivieren oder zu deaktivieren.
- eine Einstellung sofort zu ändern, ohne sie separat speichern zu müssen.

---

# Indeterminate

Die Property `isIndeterminate` zeigt an, dass sich eine Checkbox in einem
visuell uneindeutigen Zustand befindet – also weder vollständig ausgewählt noch
vollständig abgewählt ist. Sie wird verwendet, um übergeordnete Checkboxen
darzustellen, bei denen nur ein Teil der untergeordneten Optionen ausgewählt
wurde.

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

<Checkbox isIndeterminate>
  Ich stimme den AGBs zu und bestätige, dass ich die
  Datenschutzhinweise zur Kenntnis genommen habe.
</Checkbox>
```

---

# Disabled

Achte bei der Verwendung von **Disabled** darauf, dass aus dem Kontext klar
wird, warum der User die Checkbox gerade nicht auswählen kann.

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

<Checkbox isDisabled>
  Ich stimme den AGBs zu und bestätige, dass ich die
  Datenschutzhinweise zur Kenntnis genommen habe.
</Checkbox>
```

---

# Kombiniere mit …

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Checkbox,
  Section,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ acceptTerms: boolean }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="acceptTerms"
          rules={{ required: true }}
        >
          <Checkbox>
            Ich stimme den AGBs zu und bestätige, dass ich
            die Datenschutzhinweise zur Kenntnis genommen
            habe.
          </Checkbox>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<CheckboxGroupRenderProps>` | `'react-aria-CheckboxGroup'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultSelected` | `boolean` | - | Whether the element should be selected (uncontrolled). |
| `dir` | `string` | - | - |
| `excludeFromTabOrder` | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `inputClassName` | `string` | - | The class name of the underlying input element. |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isIndeterminate` | `boolean` | - | Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `isSelected` | `boolean` | - | Whether the element should be selected (controlled). |
| `lang` | `string` | - | - |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `string` | - | The value of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefvalue). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((isSelected: boolean) => void)` | - | Handler that is called when the element's selection state changes. |
| `onClick` | `((e: MouseEvent<FocusableElement, MouseEvent>) => void)` | - | **Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions. |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onHoverChange` | `((isHovering: boolean) => void)` | - | Handler that is called when the hover state changes. |
| `onHoverEnd` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction ends. |
| `onHoverStart` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction starts. |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPress` | `((e: PressEvent) => void)` | - | Handler that is called when the press is released over the target. |
| `onPressChange` | `((isPressed: boolean) => void)` | - | Handler that is called when the press state changes. |
| `onPressEnd` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. |
| `onPressStart` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction starts. |
| `onPressUp` | `((e: PressEvent) => void)` | - | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-controls` | `string` | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--choice--icon-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--choice--icon-color--selected` | `#003FB8` | `#ABC6FF` |
| `--choice--icon-color--disabled` | `#B7C9DB` | `#8FA1B4` |

---

# CheckboxButton

Der CheckboxButton ist eine auffälligere Variante der Checkbox.

> **mStudio-Extensions:** Importiere `CheckboxButton` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

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

<CheckboxButton>
  Ich stimme den AGBs zu und bestätige, dass ich die
  Datenschutzhinweise zur Kenntnis genommen habe.
</CheckboxButton>
```

---

# Best Practices

- Wähle den initialen Zustand nachvollziehbar und sinnvoll.
- Ordne mehrere CheckboxButtons logisch und nachvollziehbar an. Mehr dazu unter
  [CheckboxGroup](https://flow.mittwald.de/components/form-controls/checkbox-group).
- Nutze für eine kompaktere, unauffälligere Auswahl alternativ die
  [Checkbox](https://flow.mittwald.de/components/form-controls/checkbox).

## CheckboxButton vs. Switch

Mit den Components CheckboxButton und [Switch](https://flow.mittwald.de/components/form-controls/switch)
können Optionen aktiviert/ausgewählt werden.

**Verwende einen CheckboxButton, um z. B. ...**

- dem User eine Auswahloption zur Bestätigung zu geben.
- Auswahlmöglichkeiten in einem Formular anzubieten, die gespeichert werden müssen.

**Verwende einen Switch, um z. B. ...**

- eine Funktion direkt zu aktivieren oder zu deaktivieren.
- eine Einstellung sofort zu ändern, ohne sie separat speichern zu müssen.

---

# Kombiniere mit …

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  CheckboxButton,
  Section,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ acceptTerms: boolean }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="acceptTerms"
          rules={{ required: true }}
        >
          <CheckboxButton>
            Ich stimme den AGBs zu und bestätige, dass ich
            die Datenschutzhinweise zur Kenntnis genommen
            habe.
          </CheckboxButton>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<CheckboxGroupRenderProps>` | `'react-aria-CheckboxGroup'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultSelected` | `boolean` | - | Whether the element should be selected (uncontrolled). |
| `dir` | `string` | - | - |
| `excludeFromTabOrder` | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `inputClassName` | `string` | - | The class name of the underlying input element. |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isIndeterminate` | `boolean` | - | Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `isSelected` | `boolean` | - | Whether the element should be selected (controlled). |
| `lang` | `string` | - | - |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `string` | - | The value of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefvalue). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((isSelected: boolean) => void)` | - | Handler that is called when the element's selection state changes. |
| `onClick` | `((e: MouseEvent<FocusableElement, MouseEvent>) => void)` | - | **Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions. |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onHoverChange` | `((isHovering: boolean) => void)` | - | Handler that is called when the hover state changes. |
| `onHoverEnd` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction ends. |
| `onHoverStart` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction starts. |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPress` | `((e: PressEvent) => void)` | - | Handler that is called when the press is released over the target. |
| `onPressChange` | `((isPressed: boolean) => void)` | - | Handler that is called when the press state changes. |
| `onPressEnd` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. |
| `onPressStart` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction starts. |
| `onPressUp` | `((e: PressEvent) => void)` | - | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-controls` | `string` | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--form-control--label-to-control-spacing` | `0.25rem` |
| `--form-control--control-to-info-spacing` | `0.25rem` |
| `--form-control--spacing-x` | `0.5rem` |
| `--form-control--spacing-y` | `0.25rem` |
| `--form-control--padding-x` | `16px` |
| `--form-control--padding-y` | `8px` |
| `--form-control--corner-radius` | `8px` |
| `--form-control--border-width` | `1px` |
| `--form-control--border-style` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--form-control--placeholder-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--placeholder-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--border-color--invalid` | `#E1244C` | `#F2A2B3` |
| `--form-control--border-color--focused` | `#0054F5` | `#85AFFF` |
| `--form-control--border-color--selected` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--background-color--default` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--form-control--background-color--focused` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--invalid` | `#FDF0F3` | `#540B1B` |
| `--form-control--background-color--selected` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--form-control--content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--content-color--selected` | `#1B1F24` | `#FFFFFF` |

---

# CheckboxGroup

Die CheckboxGroup fasst mehrere Checkboxen oder CheckboxButtons zusammen.

> **mStudio-Extensions:** Importiere `CheckboxGroup` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  Checkbox,
  CheckboxGroup,
  Label,
} from "@mittwald/flow-react-components";

<CheckboxGroup>
  <Label>Berechtigungen</Label>
  <Checkbox value="read">Lesen</Checkbox>
  <Checkbox value="write">Schreiben</Checkbox>
</CheckboxGroup>
```

---

# Best Practices

- Beschreibe die Gruppierung mit einem logischen, prägnanten Label.
- Ordne die [Checkboxen](https://flow.mittwald.de/components/form-controls/checkbox) bzw.
  [CheckboxButtons](https://flow.mittwald.de/components/form-controls/checkbox-button) sinnvoll an.
  Möglich sind Relevanz, alphabetische oder thematische Gruppierung.
- Halte die Zahl der Auswahlmöglichkeiten überschaubar. Zu viele Optionen
  überfordern schnell.

## CheckboxGroup vs. RadioGroup

Mit einer CheckboxGroup oder mit einer
[RadioGroup](https://flow.mittwald.de/components/form-controls/radio-group) erhalten User verschiedene
Auswahlmöglichkeiten.

**Verwende eine CheckboxGroup, um z. B. ...**

- eine Mehrfachauswahl darzustellen.
- [Checkboxen](https://flow.mittwald.de/components/form-controls/checkbox) oder [CheckboxButtons](https://flow.mittwald.de/components/form-controls/checkbox-button) sinnvoll zu strukturieren.

**Verwende eine RadioGroup, um z. B. ...**

- eine Einfachauswahl darzustellen.
- Radios oder RadioButtons sinnvoll zu strukturieren.

---

# CheckboxButtons

Eine CheckboxGroup kann entweder mit
[CheckboxButtons](https://flow.mittwald.de/components/form-controls/checkbox-button) oder
[Checkboxen](https://flow.mittwald.de/components/form-controls/checkbox) gefüllt werden.

```tsx
import {
  CheckboxButton,
  CheckboxGroup,
  Label,
} from "@mittwald/flow-react-components";

<CheckboxGroup>
  <Label>Berechtigungen</Label>
  <CheckboxButton value="read">Lesen</CheckboxButton>
  <CheckboxButton value="write">Schreiben</CheckboxButton>
</CheckboxGroup>
```

---

# Spalten

Die CheckboxGroup verwendet das
[ColumnLayout](https://flow.mittwald.de/components/structure/column-layout), um eine Anpassung der
Spalten zu ermöglichen. Bei der Verwendung von CheckboxButtons entspricht der
Default dem des ColumnLayouts, während Checkboxen im Default untereinander
angezeigt werden.

```tsx
import {
  CheckboxButton,
  CheckboxGroup,
  Label,
} from "@mittwald/flow-react-components";

<CheckboxGroup l={[1, 1]} m={[1]}>
  <Label>Berechtigungen</Label>
  <CheckboxButton value="read">Lesen</CheckboxButton>
  <CheckboxButton value="write">Schreiben</CheckboxButton>
</CheckboxGroup>
```

---

# FieldDescription

Für eine kurze Hilfestellung zu den Auswahloptionen kann unterhalb der Gruppe
eine `<FieldDescription />` eingebaut werden.

```tsx
import {
  Checkbox,
  CheckboxGroup,
  FieldDescription,
  Label,
} from "@mittwald/flow-react-components";

<CheckboxGroup>
  <Label>Berechtigungen</Label>
  <Checkbox value="read">Lesen</Checkbox>
  <Checkbox value="write">Schreiben</Checkbox>
  <FieldDescription>Weitere Informationen</FieldDescription>
</CheckboxGroup>
```

---

# Kombiniere mit …

## ContextualHelp

Benutze die [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help), um weitere
Informationen bereitzustellen.

```tsx
import {
  Button,
  Checkbox,
  CheckboxGroup,
  ContextualHelp,
  ContextualHelpTrigger,
  Label,
  Text,
} from "@mittwald/flow-react-components";

<CheckboxGroup>
  <Label>
    Berechtigungen
    <ContextualHelpTrigger subject="Berechtigungen">
      <Button />
      <ContextualHelp>
        <Text>
          Hier gibt es weitere Informationen, die zu lang
          für die FieldDescription sind.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Label>
  <Checkbox value="read">Lesen</Checkbox>
  <Checkbox value="write">Schreiben</Checkbox>
</CheckboxGroup>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Checkbox,
  CheckboxGroup,
  Label,
  Section,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ permissions: string[] }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="permissions"
          rules={{
            required:
              "Bitte wähle mindestens eine Berechtigung aus",
          }}
        >
          <CheckboxGroup>
            <Label>Berechtigungen</Label>
            <Checkbox value="read">Lesen</Checkbox>
            <Checkbox value="write">Schreiben</Checkbox>
          </CheckboxGroup>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<CheckboxGroupRenderProps>` | `'react-aria-CheckboxGroup'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `l` | `(number \| null)[]` | - | Column layout for container size l. |
| `lang` | `string` | - | - |
| `m` | `(number \| null)[]` | - | Column layout for container size m. |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `s` | `(number \| null)[]` | - | Column layout for container size s. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# CodeEditor

Der CodeEditor dient dem Bearbeiten von Code, mit Syntax-Highlighting.

> **mStudio-Extensions:** Importiere `CodeEditor` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<CodeEditor
  language="tsx"
  value={
    'import React, { FC } from "react";\n' +
    "\n" +
    "const ExampleCodeComponent: FC = () => {\n" +
    "  \n" +
    "  useEffect(() => {\n" +
    "    // some effect \n" +
    "  }, []);\n" +
    "  \n" +
    "  return <>Example JSX</>;\n" +
    "};"
  }
/>
```

---

# Best Practices

- Setze im `language` Property die Sprache passend zum Code-Inhalt. So wird das
  Syntax-Highlighting korrekt dargestellt.

---

# Disabled

Achte bei der Verwendung von **Disabled** darauf, dass aus dem Kontext klar
wird, warum der User gerade nicht mit dem CodeEditor interagieren kann. Muss der
User den Code weiterhin lesen und per Tastatur scrollen können, nutze
stattdessen `isReadOnly`.

```tsx
import {
  CodeEditor,
  Label,
} from "@mittwald/flow-react-components";

<CodeEditor
  isDisabled
  language="json"
  value={'{\n  "name": "flow"\n}'}
>
  <Label>Konfiguration</Label>
</CodeEditor>
```

---

# Kombiniere mit ...

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Label,
  CodeEditor,
  Section,
  ActionGroup,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Field,
  Form,
  SubmitButton,
} from "@mittwald/flow-react-components/react-hook-form";

export default () => {
  const form = useForm({
    defaultValues: {
      code:
        'import React, { FC } from "react";\n' +
        "\n" +
        "const ExampleCodeComponent: FC = () => {\n" +
        "  \n" +
        "  useEffect(() => {\n" +
        "    // some effect\n" +
        "  }, []);\n" +
        "  \n" +
        "  return <>Example JSX</>;\n" +
        "};",
    },
  });
  return (
    <Section>
      <Form
        form={form}
        onSubmit={(v) => console.log(v.code)}
      >
        <Field
          name="code"
          rules={{
            required: "Bitte gib Quelltext ein",
          }}
        >
          <CodeEditor language="tsx">
            <Label>Quelltext</Label>
          </CodeEditor>
        </Field>
        <ActionGroup>
          <SubmitButton>Senden</SubmitButton>
        </ActionGroup>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` | `boolean` | - | focus on the editor. |
| `className` | `string` | - | The elements class name. |
| `copyable` | `boolean` | `true` | Whether a button to copy the code to the clipboard is shown. |
| `defaultValue` | `string` | - | The initial code of an uncontrolled editor. |
| `editable` | `boolean` | `true` | This disables editing of the editor content by the user. |
| `extensions` | `Extension[]` | - | Extension values can be [provided](https://codemirror.net/6/docs/ref/#state.EditorStateConfig.extensions) when creating a state to attach various kinds of configuration and behavior information. They can either be built-in extension-providing objects, such as [state fields](https://codemirror.net/6/docs/ref/#state.StateField) or [facet providers](https://codemirror.net/6/docs/ref/#state.Facet.of), or objects with an extension in its `extension` property. Extensions can be nested in arrays arbitrarily deep—they will be flattened when processed. |
| `height` | `string` | - | - |
| `indentWithTab` | `boolean` | `true` | Controls whether pressing the `Tab` key inserts a tab character and indents the text (`true`) or behaves according to the browser's default behavior (`false`). |
| `initialState` | `{ json: any; fields?: Record<string, StateField<any>>; }` | - | Create a state from its JSON representation serialized with [toJSON](https://codemirror.net/docs/ref/#state.EditorState.toJSON) function |
| `isDisabled` | `boolean` | `false` | Whether the editor is disabled. The code can neither be edited, focused nor copied. |
| `isInvalid` | `boolean` | `false` | Whether the editor is displayed as invalid. |
| `isReadOnly` | `boolean` | `false` | Whether the code can be read but not edited. |
| `isRequired` | `boolean` | `false` | Whether the field must be filled in. Only marks the editor as required for assistive technology — the editor does not validate itself. |
| `language` | `"text" \| "go" \| (string & {}) \| "p" \| "b" \| "html" \| "map" \| "q" \| "s" \| "svg" \| "m" \| "markdown" \| "d" \| "in" \| "r" \| "apl" \| "asc" \| "asn" \| "asn1" \| "bash" \| "bf" \| "BUILD" \| "bzl" \| ... 196 more ...` | - | The language the code is highlighted as. A language the editor does not know is shown as plain text. |
| `maxHeight` | `string` | - | - |
| `maxWidth` | `string` | - | - |
| `minHeight` | `string` | - | - |
| `minWidth` | `string` | - | - |
| `placeholder` | `string \| HTMLElement` | - | Enables a placeholder—a piece of example content to show when the editor is empty. |
| `root` | `ShadowRoot \| Document` | - | If the view is going to be mounted in a shadow root or document other than the one held by the global variable document (the default), you should pass it here. Originally from the [config of EditorView](https://codemirror.net/6/docs/ref/#view.EditorView.constructor%5Econfig.root) |
| `selection` | `EditorSelection \| { anchor: number; head?: number; }` | - | The starting selection. Defaults to a cursor at the very start of the document. |
| `showActiveLineMarker` | `boolean` | `true` | Whether the line the cursor is on is highlighted. |
| `showCodeFolding` | `boolean` | `true` | Whether the gutter offers controls to fold and unfold code blocks. |
| `showCodeIndentationMakers` | `boolean` | `true` | Whether indentation levels are visualized with guide lines. |
| `showLineNumbers` | `boolean` | `true` | Whether line numbers are shown in the gutter. |
| `showLinterMarkers` | `boolean` | `true` | Whether linter results are shown in the gutter. |
| `value` | `string` | - | value of the auto created model in the editor. |
| `width` | `string` | - | - |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onChange` | `((value: string, viewUpdate: ViewUpdate) => void)` | - | Fired whenever a change occurs to the document. |
| `onCreateEditor` | `((view: EditorView, state: EditorState) => void)` | - | The first time the editor executes the event. |
| `onStatistics` | `((data: Statistics) => void)` | - | Some data on the statistics editor. |
| `onUpdate` | `((viewUpdate: ViewUpdate) => void)` | - | Fired whenever any state change occurs within the editor, including non-document changes like lint results. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--code-editor--font-size` | `0.875rem` |
| `--code-editor--font-family` | `FiraCode, monospace` |
| `--code-editor--gutter-element-min-width` | `1.5rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--code-editor--gutter-separator-color` | `#B7C9DB` | `#8FA1B4` |
| `--code-editor--indentation-marker-color` | `#DCE9F7` | `#5E6C7A` |

---

# ComboBox

Die ComboBox kombiniert eine Texteingabe mit einem filterbaren Auswahlmenü.

> **mStudio-Extensions:** Importiere `ComboBox` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `renderEmptyState`, `style`, `wrapWith`.

```tsx
import {
  ComboBox,
  Label,
  Option,
} from "@mittwald/flow-react-components";

<ComboBox>
  <Label>Domain</Label>
  <Option>mydomain.de</Option>
  <Option>shop.mydomain.de</Option>
  <Option>anotherdomain.com</Option>
  <Option>www.anotherdomain.com</Option>
  <Option>anotherdomain.com/shop</Option>
  <Option>anotherdomain.com/blog</Option>
  <Option>onemoredomain.de</Option>
  <Option>www.onemoredomain.de</Option>
</ComboBox>
```

---

# Best Practices

- Benenne die angezeigten Optionen klar und eindeutig.
- Grenze die Liste der Vorschläge sinnvoll ein. Das erleichtert die Auswahl.
- Decke mit den vorgeschlagenen Optionen die erwarteten Eingaben möglichst
  vollständig ab.

## ComboBox vs. Autocomplete

ComboBoxen und [Autocomplete](https://flow.mittwald.de/components/form-controls/autocomplete) sehen oft
ähnlich aus, erfüllen aber unterschiedliche Zwecke.

**Verwende ComboBox, um z. B. ...**

- aus einer vordefinierten Liste von Optionen eine Auswahl zu treffen.
- bei bekannten, überschaubaren Optionen (z. B. Sprachen, Kategorien, Geschlecht).

**Verwende Autocomplete, um z. B. ...**

- Usern zu ermöglichen, freie Eingaben zu machen, während Vorschläge zur Auswahl angezeigt werden.
- bei langen oder dynamischen Datenlisten (z. B. Städte, Usernamen, Tags).

---

# Custom Value

Standardmäßig setzt eine ComboBox beim Verlassen des Inputfelds den Eingabewert
entweder auf den Wert der ausgewählten Option zurück oder leert das Feld, wenn
noch keine Option ausgewählt wurde. Mit dem Property `allowsCustomValue` kann
dieses Verhalten überschrieben werden, um auch freie Eingaben zu erlauben.

```tsx
import {
  ComboBox,
  Label,
  Option,
} from "@mittwald/flow-react-components";

<ComboBox allowsCustomValue>
  <Label>Domain</Label>
  <Option>mydomain.de</Option>
  <Option>shop.mydomain.de</Option>
  <Option>anotherdomain.com</Option>
  <Option>www.anotherdomain.com</Option>
  <Option>anotherdomain.com/shop</Option>
  <Option>anotherdomain.com/blog</Option>
  <Option>onemoredomain.de</Option>
  <Option>www.onemoredomain.de</Option>
</ComboBox>
```

---

# CountryOptions

Verwende die `CountryOptions`, um eine Länderauswahl anzubieten.

```tsx
import {
  ComboBox,
  CountryOptions,
  Label,
} from "@mittwald/flow-react-components";

<ComboBox>
  <Label>Land</Label>
  <CountryOptions />
</ComboBox>
```

---

# Mit FieldDescription

Um wichtige Hinweise zur ComboBox bereitzustellen, kann unterhalb eine
`<FieldDescription />` eingebaut werden.

```tsx
import {
  ComboBox,
  FieldDescription,
  Label,
  Option,
} from "@mittwald/flow-react-components";

<ComboBox>
  <Label>Domain</Label>
  <Option>mydomain.de</Option>
  <Option>shop.mydomain.de</Option>
  <Option>anotherdomain.com</Option>
  <Option>www.anotherdomain.com</Option>
  <Option>anotherdomain.com/shop</Option>
  <Option>anotherdomain.com/blog</Option>
  <Option>onemoredomain.de</Option>
  <Option>www.onemoredomain.de</Option>
  <FieldDescription>Weitere Informationen</FieldDescription>
</ComboBox>
```

---

# Kombiniere mit ...

## Combine

Benutze [Combine](https://flow.mittwald.de/components/structure/combine), um einen
[Button](https://flow.mittwald.de/components/actions/button) neben deiner ComboBox zu platzieren.

```tsx
import {
  Combine,
  Button,
  ComboBox,
  Label,
  Option,
} from "@mittwald/flow-react-components";

<Combine>
  <ComboBox>
    <Label>Domain</Label>
    <Option>mydomain.de</Option>
    <Option>shop.mydomain.de</Option>
    <Option>anotherdomain.com</Option>
    <Option>www.anotherdomain.com</Option>
    <Option>anotherdomain.com/shop</Option>
    <Option>anotherdomain.com/blog</Option>
    <Option>onemoredomain.de</Option>
    <Option>www.onemoredomain.de</Option>
  </ComboBox>
  <Button>Hinzufügen</Button>
</Combine>
```

## ContextualHelp

Verwende ein [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help), wenn du
weitere Informationen bereitstellen möchtest, und diese zu lang für die
FieldDescription sind.

```tsx
import {
  Button,
  ComboBox,
  ContextualHelp,
  ContextualHelpTrigger,
  Label,
  Option,
  Text,
} from "@mittwald/flow-react-components";

<ComboBox>
  <Label>
    Domain
    <ContextualHelpTrigger subject="Domain">
      <Button />
      <ContextualHelp>
        <Text>
          Hier gibt es weitere Informationen, die zu lang
          für die FieldDescription sind.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Label>
  <Option>mydomain.de</Option>
  <Option>shop.mydomain.de</Option>
  <Option>anotherdomain.com</Option>
  <Option>www.anotherdomain.com</Option>
  <Option>anotherdomain.com/shop</Option>
  <Option>anotherdomain.com/blog</Option>
  <Option>onemoredomain.de</Option>
  <Option>www.onemoredomain.de</Option>
</ComboBox>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  ComboBox,
  Label,
  Option,
  Section,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ domain: string }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="domain"
          rules={{
            required: "Bitte wähle eine Domain aus",
          }}
        >
          <ComboBox>
            <Label>Domain</Label>
            <Option>mydomain.de</Option>
            <Option>anotherdomain.com</Option>
          </ComboBox>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `allowsCustomValue` | `boolean` | - | Whether the ComboBox allows a non-item matching input value to be set. |
| `allowsEmptyCollection` | `boolean` | - | Whether the combo box allows the menu to be open when the collection is empty. |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<ComboBoxRenderProps>` | `'react-aria-ComboBox'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultFilter` | `((textValue: string, inputValue: string) => boolean)` | - | The filter function used to determine if an option should be included in the combo box list. By default, a language-sensitive "contains" filter from `useFilter` is used. |
| `defaultInputValue` | `string` | - | The default value of the ComboBox input (uncontrolled). |
| `defaultItems` | `Iterable<never>` | - | The list of ComboBox items (uncontrolled). |
| `defaultSelectedKey` _(deprecated)_ | `Key` | - | The initial selected key in the collection (uncontrolled). @deprecated |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `disabledKeys` | `Iterable<Key>` | - | The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `formValue` | `"text" \| "key"` | `'key'` | Whether the text or key of the selected item is submitted as part of an HTML form. When `allowsCustomValue` is `true`, this option does not apply and the text is always submitted. |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `inputValue` | `string` | - | The value of the ComboBox input (controlled). |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `items` | `Iterable<never>` | - | The list of ComboBox items (controlled). |
| `lang` | `string` | - | - |
| `menuTrigger` | `"input" \| "manual" \| "focus"` | `'input'` | The interaction required to display the ComboBox menu. |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `placeholder` | `string` | - | Temporary text that occupies the text input when it is empty. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/placeholder). |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `renderEmptyState` | `((props: ListBoxRenderProps) => ReactNode)` | - | Provides content to display when there are no items in the list. |
| `selectedKey` _(deprecated)_ | `Key` | - | The currently selected key in the collection (controlled). @deprecated |
| `selectionMode` | `"single"` | `'single'` | Whether single or multiple selection is enabled. |
| `shouldFocusWrap` | `boolean` | - | Whether keyboard navigation is circular. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: string) => void)` | - | Called with the key of the selected option whenever the selection changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onInputChange` | `((value: string) => void)` | - | Handler that is called when the ComboBox input value changes. |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onOpenChange` | `((isOpen: boolean, menuTrigger?: MenuTriggerAction) => void)` | - | Method that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu. |
| `onSelectionChange` _(deprecated)_ | `((key: Key \| null) => void)` | - | Handler that is called when the selection changes. @deprecated |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--form-control--label-to-control-spacing` | `0.25rem` |
| `--form-control--control-to-info-spacing` | `0.25rem` |
| `--form-control--spacing-x` | `0.5rem` |
| `--form-control--spacing-y` | `0.25rem` |
| `--form-control--padding-x` | `16px` |
| `--form-control--padding-y` | `8px` |
| `--form-control--corner-radius` | `8px` |
| `--form-control--border-width` | `1px` |
| `--form-control--border-style` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--form-control--placeholder-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--placeholder-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--border-color--invalid` | `#E1244C` | `#F2A2B3` |
| `--form-control--border-color--focused` | `#0054F5` | `#85AFFF` |
| `--form-control--border-color--selected` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--background-color--default` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--form-control--background-color--focused` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--invalid` | `#FDF0F3` | `#540B1B` |
| `--form-control--background-color--selected` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--form-control--content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--content-color--selected` | `#1B1F24` | `#FFFFFF` |

---

# DatePicker

Der DatePicker erlaubt die Eingabe eines Datums per Tastatur oder Kalender.

> **mStudio-Extensions:** Importiere `DatePicker` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  DatePicker,
  Label,
} from "@mittwald/flow-react-components";

<DatePicker>
  <Label>Datum</Label>
</DatePicker>
```

---

# Best Practices

- Verwende ein verständliches [Label](https://flow.mittwald.de/components/content/label) wie „Datum".
- Wähle ein Datumsformat passend zum gewohnten Format des Users und zum Kontext.
- Wähle sinnvolle Defaultwerte.
- Schränke Eingaben bei Bedarf mit `minValue` und `maxValue` ein. So zeigst du
  zum Beispiel das frühestmögliche Datum eines Termins an.

---

# Min- und Max-Values

Das wählbare Datum lässt sich über `minValue` und `maxValue` begrenzen.

```tsx
import {
  DatePicker,
  Label,
} from "@mittwald/flow-react-components";
import {
  getLocalTimeZone,
  today,
} from "@internationalized/date";

<DatePicker minValue={today(getLocalTimeZone())}>
  <Label>Datum</Label>
</DatePicker>
```

---

# Verfügbare Daten

Über das `isDateUnavailable` Property kann die Datumsauswahl eingeschränkt
werden.

```tsx
import {
  DatePicker,
  FieldDescription,
  Label,
} from "@mittwald/flow-react-components";
import { type DateValue } from "@internationalized/date";

<DatePicker
  isRequired
  isDateUnavailable={(date: DateValue) => date.day !== 1}
>
  <Label>Datum</Label>
  <FieldDescription>
    Es kann nur der 1. jeden Monats ausgewählt werden
  </FieldDescription>
</DatePicker>
```

---

# Mit FieldDescription

Um wichtige Hinweise zum DatePicker bereitzustellen, kann unterhalb eine
`<FieldDescription />` eingebaut werden.

```tsx
import {
  DatePicker,
  FieldDescription,
  Label,
} from "@mittwald/flow-react-components";

<DatePicker>
  <Label>Datum</Label>
  <FieldDescription>Weitere Informationen</FieldDescription>
</DatePicker>
```

---

# Disabled

Achte bei der Verwendung von **Disabled** darauf, dass aus dem Kontext klar
wird, warum der User gerade nicht mit dem DatePicker interagieren kann.

```tsx
import {
  DatePicker,
  Label,
} from "@mittwald/flow-react-components";

<DatePicker isDisabled>
  <Label>Datum</Label>
</DatePicker>
```

---

# Kombiniere mit ...

## ContextualHelp

Benutze das [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help), wenn
zusätzliche Informationen bereitgestellt werden sollen, die zu umfangreich für
die FieldDescription sind.

```tsx
import {
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  DatePicker,
  Text,
  Label,
} from "@mittwald/flow-react-components";

<DatePicker>
  <Label>
    Datum
    <ContextualHelpTrigger subject="Datum">
      <Button />
      <ContextualHelp>
        <Text>
          Hier gibt es weitere Informationen, die zu lang
          für die FieldDescription sind.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Label>
</DatePicker>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  DatePicker,
  Label,
  Section,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";
import type { CalendarDate } from "@internationalized/date";

export default () => {
  const form = useForm<{ date: CalendarDate }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="date"
          rules={{
            required: "Bitte wähle ein Datum aus",
          }}
        >
          <DatePicker>
            <Label>Datum</Label>
          </DatePicker>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoComplete` | `string` | - | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<DateRangePickerRenderProps>` | `'react-aria-DateRangePicker'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultOpen` | `boolean` | - | Whether the overlay is open by default (uncontrolled). |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `firstDayOfWeek` | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | - | The day that starts the week. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `granularity` | `"hour" \| "minute" \| "second"` | `'minute'` | Determines the smallest unit that is displayed in the time picker. |
| `hidden` | `boolean` | - | - |
| `hideTimeZone` | `boolean` | - | Whether to hide the time zone abbreviation. |
| `hourCycle` | `12 \| 24` | - | Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale. |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDateUnavailable` | `((date: DateValue, anchorDate: CalendarDate \| null) => boolean)` | - | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable. |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isOpen` | `boolean` | - | Whether the overlay is open by default (controlled). |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `lang` | `string` | - | - |
| `maxValue` | `TimeValue` | - | The maximum allowed time that a user may select. |
| `minValue` | `TimeValue` | - | The minimum allowed time that a user may select. |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `pageBehavior` | `"single" \| "visible"` | `visible` | Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration. |
| `placeholderValue` | `TimeValue` | - | A placeholder time that influences the format of the placeholder shown when no value is selected. Defaults to 12:00 AM or 00:00 depending on the hour cycle. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `shouldCloseOnSelect` | `boolean \| (() => boolean)` | `true` | Determines whether the date picker popover should close automatically when a date is selected. |
| `shouldForceLeadingZeros` | `boolean` | - | Whether to always show leading zeros in the hour field. By default, this is determined by the user's locale. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onOpenChange` | `((isOpen: boolean) => void)` | - | Handler that is called when the overlay's open state changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--date-picker--date-segment-corner-radius` | `4px` |
| `--calendar--spacing` | `0.25rem` |
| `--calendar--heading-font-size` | `1rem` |
| `--calendar--cell-size` | `2.25rem` |
| `--calendar--cell-corner-radius` | `50%` |
| `--calendar--cell-font-size` | `0.875rem` |
| `--calendar--range-border-width` | `0.5px` |
| `--calendar--range-border-style` | `solid` |
| `--calendar--header-cell-font-weight` | `bold` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--date-picker--date-segment-background-color--focused` | `#E0EBFF` | `#002A7B` |
| `--calendar--cell-background-color--disabled` | `transparent` | `transparent` |
| `--calendar--cell-background-color--hover` | `rgb(0 0 0 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--calendar--cell-background-color--pressed` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--calendar--cell-background-color--selected` | `#0054F5` | `#85AFFF` |
| `--calendar--cell-content-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--calendar--cell-content-color--selected` | `#FFFFFF` | `#1B1F24` |
| `--calendar--range-background-color` | `#F0F5FF` | `#00205C` |
| `--calendar--range-border-color` | `#5E6C7A` | `#DCE9F7` |

---

# DateRangePicker

Der DateRangePicker erlaubt die Eingabe einer Zeitspanne per Tastatur oder Kalender.

> **mStudio-Extensions:** Importiere `DateRangePicker` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  DateRangePicker,
  Label,
} from "@mittwald/flow-react-components";

<DateRangePicker>
  <Label>Zeitraum</Label>
</DateRangePicker>
```

---

# Best Practices

- Verwende ein verständliches [Label](https://flow.mittwald.de/components/content/label) wie „Zeitraum".
- Wähle ein Datumsformat passend zum gewohnten Format des Users und zum Kontext.
- Wähle sinnvolle Defaultwerte.
- Schränke den auswählbaren Zeitraum bei Bedarf mit `minValue` und `maxValue`
  ein.

---

# Min- und Max-Values

Der auswählbare Datumsbereich lässt sich über `minValue` und `maxValue`
begrenzen.

```tsx
import {
  DateRangePicker,
  Label,
} from "@mittwald/flow-react-components";
import {
  getLocalTimeZone,
  today,
} from "@internationalized/date";

<DateRangePicker minValue={today(getLocalTimeZone())}>
  <Label>Zeitraum</Label>
</DateRangePicker>
```

---

# Mit FieldDescription

Um wichtige Hinweise zum DateRangePicker bereitzustellen, kann unterhalb eine
`<FieldDescription />` eingebaut werden.

```tsx
import {
  DateRangePicker,
  FieldDescription,
  Label,
} from "@mittwald/flow-react-components";

<DateRangePicker>
  <Label>Zeitraum</Label>
  <FieldDescription>Weitere Informationen</FieldDescription>
</DateRangePicker>
```

---

# Mit Presets

Mit `withDatePickerPresets` lassen sich Presets anzeigen, die eine beschleunigte
Auswahl von Datumsbereichen ermöglichen.

```tsx
import {
  DateRangePicker,
  Label,
  Section,
} from "@mittwald/flow-react-components";

export default () => {
  return (
    <Section>
      <DateRangePicker withDatePickerPresets>
        <Label>Zeitraum</Label>
      </DateRangePicker>
    </Section>
  );
}
```

## Custom Presets

Wird `withDatePickerPresets` ein Array mit eigenen Presets übergeben, werden
diese anstelle der Default Presets verwendet.

```tsx
import {
  DateRangePicker,
  Label,
  Section,
  type DateRangePresets,
} from "@mittwald/flow-react-components";
import { CalendarDate } from "@internationalized/date";

export default () => {
  const customPresets: DateRangePresets = [
    {
      start: new CalendarDate(2050, 1, 1),
      end: new CalendarDate(2100, 1, 1),
      label: "Custom Preset",
    },
  ];

  return (
    <Section>
      <DateRangePicker
        withDatePickerPresets={customPresets}
      >
        <Label>Zeitraum</Label>
      </DateRangePicker>
    </Section>
  );
}
```

---

# Disabled

Achte bei der Verwendung von **Disabled** darauf, dass aus dem Kontext klar
wird, warum der User gerade nicht mit dem DateRangePicker interagieren kann.

```tsx
import {
  DateRangePicker,
  Label,
} from "@mittwald/flow-react-components";

<DateRangePicker isDisabled>
  <Label>Zeitraum</Label>
</DateRangePicker>
```

---

# Kombiniere mit ...

## ContextualHelp

Benutze das [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help), wenn
zusätzliche Informationen bereitgestellt werden sollen, die zu umfangreich für
die FieldDescription sind.

```tsx
import {
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  DateRangePicker,
  Label,
  Text,
} from "@mittwald/flow-react-components";

<DateRangePicker>
  <Label>
    Zeitraum
    <ContextualHelpTrigger subject="Zeitraum">
      <Button />
      <ContextualHelp>
        <Text>
          Hier gibt es weitere Informationen, die zu lang
          für die FieldDescription sind.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Label>
</DateRangePicker>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  DateRangePicker,
  Label,
  Section,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import type { CalendarDate } from "@internationalized/date";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{
    range: { start: CalendarDate; end: CalendarDate };
  }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="range"
          rules={{
            required: "Bitte wähle einen Zeitraum aus",
          }}
        >
          <DateRangePicker>
            <Label>Zeitraum</Label>
          </DateRangePicker>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `allowsNonContiguousRanges` | `boolean` | - | When combined with `isDateUnavailable`, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected. |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<DateRangePickerRenderProps>` | `'react-aria-DateRangePicker'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultOpen` | `boolean` | - | Whether the overlay is open by default (uncontrolled). |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `endName` | `string` | - | The name of the end date input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `firstDayOfWeek` | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | - | The day that starts the week. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `granularity` | `"hour" \| "minute" \| "second"` | `'minute'` | Determines the smallest unit that is displayed in the time picker. |
| `hidden` | `boolean` | - | - |
| `hideTimeZone` | `boolean` | - | Whether to hide the time zone abbreviation. |
| `hourCycle` | `12 \| 24` | - | Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale. |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDateUnavailable` | `((date: DateValue, anchorDate: CalendarDate \| null) => boolean)` | - | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable. |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isOpen` | `boolean` | - | Whether the overlay is open by default (controlled). |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `lang` | `string` | - | - |
| `maxValue` | `TimeValue` | - | The maximum allowed time that a user may select. |
| `minValue` | `TimeValue` | - | The minimum allowed time that a user may select. |
| `pageBehavior` | `"single" \| "visible"` | `visible` | Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration. |
| `placeholderValue` | `TimeValue` | - | A placeholder time that influences the format of the placeholder shown when no value is selected. Defaults to 12:00 AM or 00:00 depending on the hour cycle. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `shouldCloseOnSelect` | `boolean \| (() => boolean)` | `true` | Determines whether the date picker popover should close automatically when a date is selected. |
| `shouldForceLeadingZeros` | `boolean` | - | Whether to always show leading zeros in the hour field. By default, this is determined by the user's locale. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `startName` | `string` | - | The name of the start date input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `withDatePickerPresets` | `boolean \| DateRangePresets` | `false` | Whether the calendar offers presets to pick a range with one click. Pass an array to replace the built-in presets with your own. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onOpenChange` | `((isOpen: boolean) => void)` | - | Handler that is called when the overlay's open state changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--date-picker--date-segment-corner-radius` | `4px` |
| `--calendar--spacing` | `0.25rem` |
| `--calendar--heading-font-size` | `1rem` |
| `--calendar--cell-size` | `2.25rem` |
| `--calendar--cell-corner-radius` | `50%` |
| `--calendar--cell-font-size` | `0.875rem` |
| `--calendar--range-border-width` | `0.5px` |
| `--calendar--range-border-style` | `solid` |
| `--calendar--header-cell-font-weight` | `bold` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--date-picker--date-segment-background-color--focused` | `#E0EBFF` | `#002A7B` |
| `--calendar--cell-background-color--disabled` | `transparent` | `transparent` |
| `--calendar--cell-background-color--hover` | `rgb(0 0 0 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--calendar--cell-background-color--pressed` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--calendar--cell-background-color--selected` | `#0054F5` | `#85AFFF` |
| `--calendar--cell-content-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--calendar--cell-content-color--selected` | `#FFFFFF` | `#1B1F24` |
| `--calendar--range-background-color` | `#F0F5FF` | `#00205C` |
| `--calendar--range-border-color` | `#5E6C7A` | `#DCE9F7` |

---

# FileField

Das FileField stellt eine kompakte Lösung dar, um Uploads von Dateien zu ermöglichen.

> **mStudio-Extensions:** Importiere `FileField` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  Button,
  FileField,
  Label,
} from "@mittwald/flow-react-components";

<FileField>
  <Label>Zertifikat</Label>
  <Button variant="outline" color="secondary">
    Auswählen
  </Button>
</FileField>
```

---

# Best Practices

- Gib dem FileField ein aussagekräftiges [Label](https://flow.mittwald.de/components/content/label),
  wenn es sonst nicht eindeutig verständlich ist.
- Kommuniziere zulässige Dateitypen und mögliche Größenbeschränkungen deutlich.
- Stelle hochgeladene Dateien übersichtlich dar. Dafür eignen sich
  [FileCard](https://flow.mittwald.de/components/upload/file-card) oder
  [FileCardList](https://flow.mittwald.de/components/upload/file-card-list).
- Formuliere [Fehlermeldungen](https://flow.mittwald.de/foundations/content-guidelines/fehlermeldungen)
  klar und hilfreich.

---

# Mit FieldDescription

Um wichtige Hinweise zum FileField bereitzustellen, kann unterhalb eine
`<FieldDescription />` eingebaut werden. In vielen Fällen empfiehlt es sich, die
erlaubten Dateitypen dort anzugeben.

```tsx
import {
  Button,
  FieldDescription,
  FileField,
  Label,
} from "@mittwald/flow-react-components";

<FileField accept={"image/png, image/jpeg"}>
  <Label>Zertifikat</Label>
  <Button variant="outline" color="secondary">
    Auswählen
  </Button>
  <FieldDescription>
    Erlaubte Dateitypen sind .jpeg und .png
  </FieldDescription>
</FileField>
```

---

# Invalid

Bei ungültiger Eingabe wird das FileField invalidiert. Über `<FieldError />`
kann eine entsprechende
[Fehlermeldung](https://flow.mittwald.de/foundations/content-guidelines/fehlermeldungen) ausgegeben
werden.

```tsx
import {
  Button,
  FieldError,
  FileField,
  Label,
} from "@mittwald/flow-react-components";

<FileField isInvalid>
  <Label>Zertifikat</Label>
  <Button variant="outline" color="secondary">
    Auswählen
  </Button>
  <FieldError>
    Wir konnten das Zertifikat nicht hochladen. Bitte
    verwende eine .txt-Datei.
  </FieldError>
</FileField>
```

---

# Mehrere Dateien

Über die Property `multiple` wird das gleichzeitige Hochladen mehrerer Dateien
ermöglicht. Beim erneuten Hochladen werden bestehende Dateien ersetzt. Ein
Beispiel für das Hochladen und Verwalten mehrerer Dateien findest du im
Codesnippet [Multi Upload](https://flow.mittwald.de/templates/bausteine/multi-upload).

```tsx
import {
  Button,
  FileField,
  Label,
  Section,
  LabeledValue,
  Text,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [files, setFiles] = useState<FileList | null>(null);

  return (
    <Section>
      <FileField multiple onChange={setFiles}>
        <Label>Dateien</Label>
        <Button variant="outline" color="secondary">
          Auswählen
        </Button>
      </FileField>

      <LabeledValue>
        <Label>Ausgewählte Dateien</Label>
        <Text>
          {files
            ? [...files].map((file) => file.name).join(", ")
            : "-"}
        </Text>
      </LabeledValue>
    </Section>
  );
}
```

---

# Disabled

Achte bei der Verwendung von **Disabled** darauf, dass aus dem Kontext klar
wird, warum der User gerade nicht mit dem FileField interagieren kann.

```tsx
import {
  Button,
  FileField,
  Label,
} from "@mittwald/flow-react-components";

<FileField isDisabled>
  <Label>Zertifikat</Label>
  <Button variant="outline" color="secondary">
    Auswählen
  </Button>
</FileField>
```

---

# Kombiniere mit ...

## ContextualHelp

Verwende [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help), um zusätzliche
Informationen bereitzustellen.

```tsx
import {
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  FileField,
  Label,
  Text,
} from "@mittwald/flow-react-components";

<FileField>
  <Label>
    Zertifikat
    <ContextualHelpTrigger subject="Zertifikat">
      <Button />
      <ContextualHelp>
        <Text>
          Hier gibt es weitere Informationen, die zu lang
          für die FieldDescription sind.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Label>
  <Button variant="outline" color="secondary">
    Auswählen
  </Button>
</FileField>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Button,
  FileCard,
  FileCardList,
  FileField,
  Label,
  Section,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{
    files: FileList | File[] | [];
  }>({ defaultValues: { files: [] } });
  const Field = typedField(form);

  const watchedFiles = [...form.watch("files")];

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="files"
          rules={{
            required:
              "Bitte wähle mindestens eine Datei aus",
          }}
        >
          <FileField multiple>
            <Label>Dateien</Label>
            <Button variant="outline" color="secondary">
              Auswählen
            </Button>
          </FileField>
        </Field>
        <FileCardList>
          {watchedFiles.map((file) => (
            <FileCard
              name={file.name}
              type={file.type}
              key={file.name}
              sizeInBytes={file.size}
              onDelete={() =>
                form.setValue(
                  "files",
                  watchedFiles.filter(
                    (watched) => watched !== file,
                  ),
                )
              }
            />
          ))}
        </FileCardList>
        <SubmitButton>Hochladen</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the component is read only. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onChange` | `FileInputOnChangeHandler` | - | Handler that is called when the file input changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |

---

# MarkdownEditor

Der MarkdownEditor formatiert Text per Markdown-Syntax und bietet eine Vorschau.

> **mStudio-Extensions:** Importiere `MarkdownEditor` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

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

<MarkdownEditor
  aria-label="Nachricht"
  placeholder="Schreibe eine Nachricht ..."
/>
```

---

# Best Practices

- Wähle die Höhe über das Property `rows` passend zur erwarteten Textmenge.
- Nutze die FieldDescription für Beispiele, Formatierungshinweise oder Kontext.
- Formuliere [Fehlermeldungen](https://flow.mittwald.de/foundations/content-guidelines/fehlermeldungen)
  klar, hilfreich und lösungsorientiert.
- Setze Custom Buttons sparsam ein. So bleibt die Toolbar übersichtlich und die
  Standard-Aktionen erkennbar.
- Lass Custom Buttons die aktuelle Text- und Cursor-Position berücksichtigen. So
  lässt sich nahtlos weiterarbeiten.
- Wähle für die Custom Buttons ein aussagekräftiges
  [Icon](https://flow.mittwald.de/components/content/icon) und formuliere das
  [Label](https://flow.mittwald.de/components/content/label) prägnant und leicht verständlich.
- Schränke die erlaubten Dateitypen über `accept` ein. Das verhindert Anhänge,
  die die Anwendung ohnehin ablehnt.
- Gib aus `uploadFile` eine `http`- oder `https`-URL zurück. Nur solche Bilder
  stellt die Vorschau dar.

---

# Character Count

Mit der Property `showCharacterCount` wird automatisch eine
`<FieldDescription />` ergänzt, die die aktuelle Zeichenanzahl und – sofern
angegeben – die maximale Zeichenanzahl anzeigt.

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

<MarkdownEditor
  showCharacterCount
  maxLength={100}
  aria-label="Nachricht"
  placeholder="Schreibe eine Nachricht ..."
/>
```

---

# Resize

## Automatisch

Mit der Property `autoResizeMaxRows` lässt sich eine maximale Höhe definieren,
bis zu der sich der MarkdownEditor automatisch an den Inhalt anpasst.

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

<MarkdownEditor
  rows={1}
  autoResizeMaxRows={5}
  aria-label="Nachricht"
  placeholder="Schreibe eine Nachricht ..."
/>
```

## Manuell

Über die Properties `allowResize`, `allowVerticalResize` oder
`allowHorizontalResize` kann die Größe des MarkdownEditors manuell verändert
werden.

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

<MarkdownEditor
  allowResize
  aria-label="Nachricht"
  placeholder="Schreibe eine Nachricht ..."
/>
```

## Kombiniert

Beide Resize-Varianten lassen sich auch miteinander kombinieren. In diesem Fall
passt sich der MarkdownEditor zunächst automatisch an, bis die Größe einmal
manuell geändert wird. Danach bleibt er in der eingestellten Größe bestehen.

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

<MarkdownEditor
  allowResize
  aria-label="Nachricht"
  placeholder="Schreibe eine Nachricht ..."
  rows={1}
  autoResizeMaxRows={5}
/>
```

---

# Custom Buttons

Ergänze die Toolbar des MarkdownEditors, indem du zusätzliche
[Actions](https://flow.mittwald.de/components/actions/action) direkt als Children von
`<MarkdownEditor />` deklarierst. So lassen sich einfache
[Buttons](https://flow.mittwald.de/components/actions/button) ebenso integrieren wie komplexere Trigger
wie `<ContextMenuTrigger />` oder `<ModalTrigger />`.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  Content,
  ContextMenu,
  ContextMenuTrigger,
  Heading,
  IconContextMenu,
  IconEdit,
  IconPlus,
  MarkdownEditor,
  MenuItem,
  Modal,
  ModalTrigger,
  Text,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [value, setValue] = useState(
    "## Support-Antwort\n\nVielen Dank für deine Nachricht.",
  );

  const insertAtEnd = (content: string) => {
    setValue((currentValue) => `${currentValue}${content}`);
  };

  return (
    <MarkdownEditor
      aria-label="Nachricht"
      value={value}
      onChange={setValue}
      rows={5}
    >
      <Button
        aria-label="Signatur einfügen"
        onPress={() => {
          insertAtEnd("\n\nViele Grüße\nDein Support-Team");
        }}
      >
        <IconPlus />
      </Button>

      <ContextMenuTrigger>
        <Button aria-label="Textbausteine anzeigen">
          <IconContextMenu />
        </Button>
        <ContextMenu>
          <MenuItem
            onAction={() => {
              insertAtEnd("Hallo {{name}},");
            }}
          >
            Begrüßung einfügen
          </MenuItem>
          <MenuItem
            onAction={() => {
              insertAtEnd(
                "## Nächste Schritte\n\n1. Vertrag prüfen\n2. Rückmeldung geben",
              );
            }}
          >
            Nächste Schritte einfügen
          </MenuItem>
        </ContextMenu>
      </ContextMenuTrigger>

      <ModalTrigger>
        <Button aria-label="Vorlagen anzeigen">
          <IconEdit />
        </Button>
        <Modal>
          <Heading>Vorlage einfügen</Heading>
          <Content>
            <Text>
              Füge einen vorbereiteten Antwortblock in den
              Editor ein.
            </Text>
          </Content>
          <ActionGroup>
            <Action closeModal>
              <Button
                color="success"
                onPress={() => {
                  insertAtEnd(
                    "## Wartungsfenster\n\nDas Wartungsfenster startet morgen um 22:00 Uhr.",
                  );
                }}
              >
                Wartungsfenster einfügen
              </Button>
              <Button color="secondary" variant="soft">
                Abbrechen
              </Button>
            </Action>
          </ActionGroup>
        </Modal>
      </ModalTrigger>
    </MarkdownEditor>
  );
}
```

---

# Datei-Upload

Ist die Property `uploadFile` gesetzt, nimmt der MarkdownEditor Dateien
entgegen: per Drag & Drop auf das Eingabefeld, aus der Zwischenablage oder über
den Anhang-Button in der Toolbar. `accept` schränkt die erlaubten Dateitypen
ein, genau wie beim [FileField](https://flow.mittwald.de/components/form-controls/file-field).

An der Cursorposition erscheint sofort ein Platzhalter-Kommentar. Sobald das
zurückgegebene Promise erfüllt ist, ersetzt ihn der MarkdownEditor durch die
Markdown-Syntax der Datei: ein Bild wird eingebettet, jede andere Datei
verlinkt. Wird es abgelehnt, verschwindet der Platzhalter wieder.

Der Upload selbst bleibt Aufgabe der Anwendung, die Endpunkt, Authentifizierung
und Fehlerbehandlung kennt.

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

<MarkdownEditor
  aria-label="Nachricht"
  accept="image/*"
  placeholder="Ziehe einen Screenshot in das Eingabefeld ..."
  uploadFile={async () => {
    // Your application uploads the file it is called with and returns its URL.
    await new Promise((resolve) =>
      setTimeout(resolve, 1500),
    );
    return {
      url: "https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg",
    };
  }}
/>
```

---

# Disabled

Achte bei der Verwendung von **Disabled** darauf, dass aus dem Kontext klar
wird, warum der User gerade nicht mit dem MarkdownEditor interagieren kann.

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

<MarkdownEditor
  isDisabled
  aria-label="Nachricht"
  placeholder="Schreibe eine Nachricht ..."
/>
```

---

# Kombiniere mit ...

## Chat

Verwende den MarkdownEditor als Eingabefeld innerhalb eines
[Chat](https://flow.mittwald.de/components/chat/chat), um Nachrichten zu verfassen.

```tsx
import {
  Combine,
  Avatar,
  Button,
  Chat,
  Content,
  Header,
  Initials,
  Message,
  MessageSeparator,
  MessageThread,
  Text,
  MarkdownEditor,
} from "@mittwald/flow-react-components";

<Chat height={400}>
  <MessageThread>
    <MessageSeparator>Ticket geöffnet</MessageSeparator>
    <Message>
      <Header>
        <Combine>
          <Avatar>
            <Initials>Max Mustermann</Initials>
          </Avatar>
          <Text>
            <strong>Max Mustermann</strong>
          </Text>
        </Combine>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet consectetur adipisicing
          elit. Cumque eius quam quas vel voluptas, ullam
          aliquid fugit. Voluptate harum accusantium rerum
          ullam modi blanditiis vitae, laborum ea tempore,
          dolore voluptas. Earum pariatur, similique
          corrupti id officia perferendis. Labore,
          similique. Earum, quas in. At dolorem corrupti
          blanditiis nulla deserunt laborum! Corrupti
          delectus aspernatur nihil nulla obcaecati ipsam
          porro sequi rem? Quam.
        </Text>
      </Content>
    </Message>
    <Message type="sender">
      <Header>
        <Combine>
          <Avatar>
            <Initials>John Doe</Initials>
          </Avatar>
          <Text>
            <strong>John Doe</strong>
          </Text>
        </Combine>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet consectetur adipisicing
          elit. Cumque eius quam quas vel voluptas, ullam
          aliquid fugit. Voluptate harum accusantium rerum
          ullam modi blanditiis vitae, laborum ea tempore,
          dolore voluptas. Earum pariatur, similique
          corrupti id officia perferendis. Labore,
          similique. Earum, quas in.
        </Text>
      </Content>
    </Message>
  </MessageThread>
  <MarkdownEditor aria-label="Nachricht" />
  <Button color="success">Senden</Button>
</Chat>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Label,
  MarkdownEditor,
  Section,
  ActionGroup,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Field,
  Form,
  SubmitButton,
} from "@mittwald/flow-react-components/react-hook-form";

export default () => {
  const form = useForm({
    defaultValues: { message: "" },
  });
  return (
    <Section>
      <Form
        form={form}
        onSubmit={(v) => console.log(v.message)}
      >
        <Field
          name="message"
          rules={{
            required: "Bitte gib eine Nachricht ein",
          }}
        >
          <MarkdownEditor placeholder="Schreibe eine Nachricht ...">
            <Label>Nachricht</Label>
          </MarkdownEditor>
        </Field>
        <ActionGroup>
          <SubmitButton>Senden</SubmitButton>
        </ActionGroup>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `accept` | `string` | - | Which file types the editor takes, as the `accept` attribute of a file input: a comma separated list of MIME types (`image/png`), MIME wildcards (`image/*`) and file extensions (`.png`). Defaults to every type. |
| `allowHorizontalResize` _(deprecated)_ | `boolean` | - | @deprecated Use `allowResize` instead. |
| `allowResize` | `boolean \| "horizontal" \| "vertical"` | - | Allows the user to manually resize the textArea horizontally. |
| `allowVerticalResize` _(deprecated)_ | `boolean` | - | @deprecated Use `allowResize` instead. |
| `autoComplete` | `string` | - | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). |
| `autoCorrect` | `string` | - | An attribute that takes as its value a space-separated string that describes what, if any, type of autocomplete functionality the input should provide. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#autocomplete). |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `autoResizeMaxRows` | `number` | - | Whether the text area should grow if its content gets longer than its initial height. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<TextFieldRenderProps>` | `'react-aria-TextField'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `enterKeyHint` | `"enter" \| "done" \| "go" \| "next" \| "previous" \| "search" \| "send"` | - | An enumerated attribute that defines what action label or icon to preset for the enter key on virtual keyboards. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint). |
| `excludeFromTabOrder` | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `headingOffset` | `number` | `0` | Shifts all heading levels by the given offset. |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `inputMode` | `"text" \| "none" \| "search" \| "url" \| "tel" \| "email" \| "numeric" \| "decimal"` | - | Hints at the type of data that might be entered by the user while editing the element or its contents. See [MDN](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute). |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `lang` | `string` | - | - |
| `markdownComponent` | `ComponentType<MarkdownProps>` | - | Allows replacing the markdown preview renderer implementation. Defaults to the internal `Markdown` component. |
| `maxLength` | `number` | - | The maximum number of characters supported by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength). |
| `minLength` | `number` | - | The minimum number of characters required by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength). |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `pattern` | `string` | - | Regex pattern that the value of the input must match to be valid. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern). |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `showCharacterCount` | `boolean` | - | Whether a character count should be displayed inside the field description. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `spellCheck` | `string` | - | An enumerated attribute that defines whether the element may be checked for spelling errors. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck). |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `type` | `"text" \| "search" \| "url" \| "tel" \| "email" \| "password" \| (string & {})` | `'text'` | The type of input to render. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype). |
| `uploadFile` | `((file: File) => Promise<MarkdownEditorUpload>)` | - | Uploads a file the user dropped onto the editor, pasted into it or picked with its attachment button. A placeholder comment sits at the cursor while the returned promise is pending: resolving replaces it with markdown linking to the file — an image embed for an image — and rejecting takes it back out. Without this prop the editor takes no files at all. Named without an `on` prefix on purpose: the remote generator turns an `on*` prop into a fire-and-forget event, and this one has to hand a result back. |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBeforeInput` | `FormEventHandler<HTMLInputElement>` | - | Handler that is called when the input value is about to be modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event). |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onCompositionEnd` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a text composition system completes or cancels the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionend_event). |
| `onCompositionStart` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a text composition system starts a new text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event). |
| `onCompositionUpdate` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a new character is received in the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event). |
| `onCopy` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user copies text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncopy). |
| `onCut` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user cuts text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncut). |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onInput` | `FormEventHandler<HTMLInputElement>` | - | Handler that is called when the input value is modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPaste` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user pastes text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/onpaste). |
| `onSelect` | `ReactEventHandler<HTMLInputElement>` | - | Handler that is called when text in the input is selected. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event). |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-activedescendant` | `string` | - | Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application. |
| `aria-autocomplete` | `"list" \| "none" \| "inline" \| "both"` | - | Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made. |
| `aria-controls` | `string` | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |
| `aria-haspopup` | `boolean \| "false" \| "true" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` | - | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--form-control--label-to-control-spacing` | `0.25rem` |
| `--form-control--control-to-info-spacing` | `0.25rem` |
| `--form-control--spacing-x` | `0.5rem` |
| `--form-control--spacing-y` | `0.25rem` |
| `--form-control--padding-x` | `16px` |
| `--form-control--padding-y` | `8px` |
| `--form-control--corner-radius` | `8px` |
| `--form-control--border-width` | `1px` |
| `--form-control--border-style` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--form-control--placeholder-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--placeholder-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--border-color--invalid` | `#E1244C` | `#F2A2B3` |
| `--form-control--border-color--focused` | `#0054F5` | `#85AFFF` |
| `--form-control--border-color--selected` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--background-color--default` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--form-control--background-color--focused` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--invalid` | `#FDF0F3` | `#540B1B` |
| `--form-control--background-color--selected` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--form-control--content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--content-color--selected` | `#1B1F24` | `#FFFFFF` |

---

# NumberField

Das NumberField erlaubt die Eingabe und schrittweise Anpassung von Zahlen.

> **mStudio-Extensions:** Importiere `NumberField` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  Label,
  NumberField,
} from "@mittwald/flow-react-components";

<NumberField minValue={0} maxValue={100}>
  <Label>Alter</Label>
</NumberField>
```

---

# Best Practices

- Definiere Mindest- und Höchstwerte (`minValue`/`maxValue`) sinnvoll, wenn du
  Eingaben einschränken willst.
- Formuliere das [Label](https://flow.mittwald.de/components/content/label) prägnant und leicht
  verständlich.
- Formuliere [Fehlermeldungen](https://flow.mittwald.de/foundations/content-guidelines/fehlermeldungen)
  klar, hilfreich und lösungsorientiert.

---

# Einheit

Über das Property `formatOptions` lassen sich Einheiten für das NumberField
definieren (s.
[Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)).

```tsx
import {
  Label,
  NumberField,
} from "@mittwald/flow-react-components";

<NumberField
  formatOptions={{
    style: "unit",
    unit: "gigabyte",
  }}
  defaultValue={12}
>
  <Label>Speicherplatz</Label>
</NumberField>
```

## Eigene Einheit

Kennt `Intl.NumberFormat` die Einheit nicht (etwa `MiB` oder `GiB`), übergib sie
als Text über das Property `unit`. Das NumberField zeigt sie hinter der Zahl an;
der Wert bleibt eine reine Zahl.

- Nutze `unit` nur, wenn `formatOptions` die Einheit nicht abdeckt –
  `formatOptions` lokalisiert Einheit und Schreibweise automatisch.
- Übersetze die Einheit selbst, wenn sie sprachabhängig ist.

```tsx
import {
  Label,
  NumberField,
} from "@mittwald/flow-react-components";

<NumberField unit="MiB" defaultValue={512}>
  <Label>Arbeitsspeicher</Label>
</NumberField>
```

---

# Validierung

Nutze für die Validierung [React Hook Form](https://flow.mittwald.de/components/react-hook-form/form).
Alternativ stehen aber auch folgende Properties zur Verfügung:

- `isRequired` für Pflichtfelder.
- `validate` für eigene Validierungen.

Bei ungültiger Eingabe wird das NumberField invalidiert. Über `<FieldError />`
kann eine entsprechende Fehlermeldung ausgegeben werden.

## Required

```tsx
import {
  Label,
  NumberField,
} from "@mittwald/flow-react-components";

<NumberField isRequired>
  <Label>Alter</Label>
</NumberField>
```

## Invalid

```tsx
import {
  FieldError,
  Label,
  NumberField,
} from "@mittwald/flow-react-components";

<NumberField isInvalid value={-1}>
  <Label>Alter</Label>
  <FieldError>Ungültige Eingabe</FieldError>
</NumberField>
```

---

# Mit FieldDescription

Um wichtige Hinweise zum NumberField bereitzustellen, kann unterhalb eine
`<FieldDescription />` eingebaut werden.

```tsx
import {
  FieldDescription,
  Label,
  NumberField,
} from "@mittwald/flow-react-components";

<NumberField minValue={18} maxValue={100}>
  <Label>Alter</Label>
  <FieldDescription>
    Du musst mindestens 18 Jahre alt sein
  </FieldDescription>
</NumberField>
```

---

# Disabled

Achte bei der Verwendung von **Disabled** darauf, dass aus dem Kontext klar
wird, warum der User gerade nicht mit dem NumberField interagieren kann.

```tsx
import {
  Label,
  NumberField,
} from "@mittwald/flow-react-components";

<NumberField isDisabled>
  <Label>Alter</Label>
</NumberField>
```

---

# Kombiniere mit ...

## Combine

Benutze die [Combine](https://flow.mittwald.de/components/structure/combine)-Component, um andere
Components wie einen [Button](https://flow.mittwald.de/components/actions/button) neben dem NumberField
auszurichten.

```tsx
import {
  Combine,
  Button,
  Label,
  NumberField,
} from "@mittwald/flow-react-components";

<Combine>
  <NumberField>
    <Label>Alter</Label>
  </NumberField>
  <Button>Hinzufügen</Button>
</Combine>
```

## ContextualHelp

Verwende [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help), um zusätzliche
Informationen bereitzustellen, die über den Umfang der FieldDescription
hinausgehen.

```tsx
import {
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  Label,
  NumberField,
  Text,
} from "@mittwald/flow-react-components";

<NumberField minValue={0} maxValue={100}>
  <Label>
    Alter
    <ContextualHelpTrigger subject="Alter">
      <Button />
      <ContextualHelp>
        <Text>
          Hier gibt es weitere Informationen, die zu lang
          für die FieldDescription sind.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Label>
</NumberField>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Label,
  NumberField,
  Section,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ age: number }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="age"
          rules={{
            required: "Bitte gib dein Alter an",
          }}
        >
          <NumberField minValue={0}>
            <Label>Alter</Label>
          </NumberField>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<NumberFieldRenderProps>` | `'react-aria-NumberField'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `commitBehavior` | `"validate" \| "snap"` | `'snap'` | Controls the behavior of the number field when the user blurs the field after editing. 'snap' will clamp the value to the min/max values, and snap to the nearest step value. 'validate' will not clamp the value, and will validate that the value is within the min/max range and on a valid step. |
| `decrementAriaLabel` | `string` | - | A custom aria-label for the decrement button. If not provided, the localized string "Decrement" is used. |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `formatOptions` | `NumberFormatOptions` | - | Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user. |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `incrementAriaLabel` | `string` | - | A custom aria-label for the increment button. If not provided, the localized string "Increment" is used. |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `isWheelDisabled` | `boolean` | - | Enables or disables changing the value with scroll. |
| `lang` | `string` | - | - |
| `maxValue` | `number` | - | The largest value allowed for the input. |
| `minValue` | `number` | - | The smallest value allowed for the input. |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `step` | `number` | - | The amount that the input value changes with each increment or decrement "tick". |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `unit` | `string` | - | A unit displayed after the number, for units `Intl.NumberFormat` does not support (e.g. "MiB"). For supported units, use `formatOptions` instead. |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBeforeInput` | `FormEventHandler<HTMLInputElement>` | - | Handler that is called when the input value is about to be modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event). |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onCompositionEnd` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a text composition system completes or cancels the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionend_event). |
| `onCompositionStart` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a text composition system starts a new text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event). |
| `onCompositionUpdate` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a new character is received in the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event). |
| `onCopy` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user copies text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncopy). |
| `onCut` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user cuts text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncut). |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onInput` | `FormEventHandler<HTMLInputElement>` | - | Handler that is called when the input value is modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPaste` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user pastes text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/onpaste). |
| `onSelect` | `ReactEventHandler<HTMLInputElement>` | - | Handler that is called when text in the input is selected. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event). |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--form-control--label-to-control-spacing` | `0.25rem` |
| `--form-control--control-to-info-spacing` | `0.25rem` |
| `--form-control--spacing-x` | `0.5rem` |
| `--form-control--spacing-y` | `0.25rem` |
| `--form-control--padding-x` | `16px` |
| `--form-control--padding-y` | `8px` |
| `--form-control--corner-radius` | `8px` |
| `--form-control--border-width` | `1px` |
| `--form-control--border-style` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--form-control--placeholder-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--placeholder-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--border-color--invalid` | `#E1244C` | `#F2A2B3` |
| `--form-control--border-color--focused` | `#0054F5` | `#85AFFF` |
| `--form-control--border-color--selected` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--background-color--default` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--form-control--background-color--focused` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--invalid` | `#FDF0F3` | `#540B1B` |
| `--form-control--background-color--selected` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--form-control--content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--content-color--selected` | `#1B1F24` | `#FFFFFF` |

---

# PasswordCreationField

Das PasswordCreationField zeigt beim Erstellen eines Passworts dessen Komplexität.

> **mStudio-Extensions:** Importiere `PasswordCreationField` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  Label,
  PasswordCreationField,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [password, setPassword] = useState("");

  return (
    <PasswordCreationField
      value={password}
      onChange={setPassword}
    >
      <Label>Password</Label>
    </PasswordCreationField>
  );
}
```

---

# Best Practices

- Nutze standardisierte Richtlinien, sofern keine spezifischen Anforderungen
  bestehen.
- Formuliere selbst definierte Richtlinien klar und eindeutig verständlich.
- Nutze für die Eingabe bestehender Passwörter ein reguläres
  [TextField](https://flow.mittwald.de/components/form-controls/text-field) mit dem Type `password`.

---

# Passwort Richtlinien

Standardmäßig wendet das PasswordCreationField folgende Passwortregeln an:

- Mindestlänge von 12 Zeichen
- Mindestens ein Sonderzeichen enthalten
- Mindestens eine Zahl enthalten
- Darf nicht durch [HaveIBeenPwned](https://haveibeenpwned.com/passwords)
  verboten sein

Alternativ lassen sich eigene Passwortanforderungen definieren. Diese sollten
klar formuliert und für User nachvollziehbar sein.

```tsx
import {
  PasswordCreationField,
  Label,
} from "@mittwald/flow-react-components";

import {
  Policy,
  RuleType,
} from "@mittwald/flow-react-components/mittwald-password-tools-js";
import { useState } from "react";

export default () => {
  const [password, setPassword] = useState("");

  return (
    <PasswordCreationField
      validationPolicy={Policy.fromDeclaration({
        minComplexity: 3,
        rules: [
          {
            ruleType: RuleType.length,
            min: 8,
            max: 12,
          },
          {
            ruleType: RuleType.regex,
            pattern: "^[0-9]",
            min: 1,
            max: 2,
          },
          {
            ruleType: RuleType.hibp,
          },
          {
            identifier: "special",
            ruleType: RuleType.charPool,
            charPools: ["special"],
            min: 1,
            max: 2,
          },
          {
            identifier: "numbers",
            ruleType: RuleType.charPool,
            charPools: ["numbers"],
            min: 1,
            max: 2,
          },
          {
            ruleType: RuleType.blocklist,
            blocklist: ["foo", "bar"],
            substringMatch: true,
          },
        ],
      })}
      value={password}
      onChange={setPassword}
    >
      <Label>Password</Label>
    </PasswordCreationField>
  );
}
```

---

# Disabled

Achte bei der Verwendung von **Disabled** darauf, dass aus dem Kontext klar
wird, warum der User gerade nicht mit dem PasswordCreationField interagieren
kann.

```tsx
import {
  Label,
  PasswordCreationField,
} from "@mittwald/flow-react-components";

<PasswordCreationField isDisabled>
  <Label>Password</Label>
</PasswordCreationField>
```

---

# Kombiniere mit ...

## Button

Das PasswordCreationField kann mit zusätzlichen
[Buttons](https://flow.mittwald.de/components/actions/button) ergänzt werden. Diese Erweiterungen sind
flexibel einsetzbar und sollten im direkten Zusammenhang mit der
Passworterstellung stehen.

```tsx
import {
  Button,
  Label,
  IconSshKey,
  PasswordCreationField,
} from "@mittwald/flow-react-components";
import { useState } from "react";
export default () => {
  const [password, setPassword] = useState("");

  return (
    <PasswordCreationField
      value={password}
      onChange={setPassword}
    >
      <Label>Password</Label>
      <Button>
        <IconSshKey />
      </Button>
    </PasswordCreationField>
  );
}
```

## CopyButton

Optional kann ein [CopyButton](https://flow.mittwald.de/components/actions/copy-button) integriert
werden. Dadurch lassen sich erstellte Passwörter direkt in die Zwischenablage
kopieren.

```tsx
import {
  CopyButton,
  Label,
  PasswordCreationField,
} from "@mittwald/flow-react-components";

export default () => {
  return (
    <PasswordCreationField>
      <Label>Password</Label>
      <CopyButton />
    </PasswordCreationField>
  );
}
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";
import {
  Label,
  Section,
  PasswordCreationField,
} from "@mittwald/flow-react-components";
import {
  usePasswordCreationFieldValidation,
  Policy,
  RuleType,
} from "@mittwald/flow-react-components/mittwald-password-tools-js";

export default () => {
  const customPolicy = Policy.fromDeclaration({
    minComplexity: 3,
    rules: [
      {
        ruleType: RuleType.length,
        min: 8,
        max: 12,
      },
    ],
  });

  const form = useForm<{ password: string }>({
    defaultValues: {
      password: "",
    },
  });
  const Field = typedField(form);
  const validatePassword =
    usePasswordCreationFieldValidation(customPolicy);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="password"
          rules={{
            required: true,
            validate: validatePassword,
          }}
        >
          <PasswordCreationField
            validationPolicy={customPolicy}
          >
            <Label>Passwort</Label>
          </PasswordCreationField>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoComplete` | `string` | - | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). |
| `autoCorrect` | `string` | - | An attribute that takes as its value a space-separated string that describes what, if any, type of autocomplete functionality the input should provide. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#autocomplete). |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<TextFieldRenderProps>` | `'react-aria-TextField'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultValue` | `string` | - | The initial password of an uncontrolled field. |
| `dir` | `string` | - | - |
| `enterKeyHint` | `"enter" \| "done" \| "go" \| "next" \| "previous" \| "search" \| "send"` | - | An enumerated attribute that defines what action label or icon to preset for the enter key on virtual keyboards. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint). |
| `excludeFromTabOrder` | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `inputMode` | `"text" \| "none" \| "search" \| "url" \| "tel" \| "email" \| "numeric" \| "decimal"` | - | Hints at the type of data that might be entered by the user while editing the element or its contents. See [MDN](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute). |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `lang` | `string` | - | - |
| `maxLength` | `number` | - | The maximum number of characters supported by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength). |
| `minLength` | `number` | - | The minimum number of characters required by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength). |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `pattern` | `string` | - | Regex pattern that the value of the input must match to be valid. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern). |
| `placeholder` | `string` | - | The placeholder shown while the field is empty. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `spellCheck` | `string` | - | An enumerated attribute that defines whether the element may be checked for spelling errors. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck). |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `type` | `"text" \| "search" \| "url" \| "tel" \| "email" \| "password" \| (string & {})` | `'text'` | The type of input to render. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype). |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `validationErrors` | `string[]` | - | The current error messages for the input if it is invalid, otherwise an empty array. |
| `validationPolicy` | `PolicyGenericDeclaration` | `defaultPasswordCreationPolicy` | The policy the password is validated against. |
| `value` | `string` | - | The password of a controlled field. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBeforeInput` | `FormEventHandler<HTMLInputElement>` | - | Handler that is called when the input value is about to be modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event). |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onCompositionEnd` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a text composition system completes or cancels the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionend_event). |
| `onCompositionStart` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a text composition system starts a new text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event). |
| `onCompositionUpdate` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a new character is received in the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event). |
| `onCopy` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user copies text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncopy). |
| `onCut` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user cuts text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncut). |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onInput` | `FormEventHandler<HTMLInputElement>` | - | Handler that is called when the input value is modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPaste` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user pastes text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/onpaste). |
| `onSelect` | `ReactEventHandler<HTMLInputElement>` | - | Handler that is called when text in the input is selected. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event). |
| `onValidationResult` | `((result: { password: string; isValid: boolean; }) => void)` | - | Called with the password and its validity whenever the password changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-activedescendant` | `string` | - | Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application. |
| `aria-autocomplete` | `"list" \| "none" \| "inline" \| "both"` | - | Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made. |
| `aria-controls` | `string` | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |
| `aria-haspopup` | `boolean \| "false" \| "true" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` | - | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--password-creation-field--rule-to-rule-spacing` | `8px` |

---

# RadioGroup

Eine RadioGroup ermöglicht die Auswahl genau einer Option aus einer Gruppe.

> **mStudio-Extensions:** Importiere `RadioGroup` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  Label,
  Radio,
  RadioGroup,
} from "@mittwald/flow-react-components";

<RadioGroup defaultValue="more">
  <Label>Täglicher Kaffeekonsum</Label>
  <Radio value="more">Mehr als 6 Tassen</Radio>
  <Radio value="5-6">5-6 Tassen</Radio>
  <Radio value="3-4">3-4 Tassen</Radio>
  <Radio value="1-2">1-2 Tassen</Radio>
  <Radio value="none">Trinke keinen Kaffee</Radio>
</RadioGroup>
```

---

# Best Practices

- Beschrifte die RadioGroup mit einem [Label](https://flow.mittwald.de/components/content/label).
  Übernimmt ein nahes Element wie eine [Heading](https://flow.mittwald.de/components/content/heading)
  diese Rolle, setze stattdessen `aria-label` bzw. `aria-labelledby`.
- Nutze bei vielen Optionen ein [Select](https://flow.mittwald.de/components/form-controls/select), um
  die Oberfläche aufgeräumt zu halten. Als Faustregel ab etwa sieben Optionen.
- Wähle zu Beginn eine sinnvolle Option vor. Das vermeidet unnötige
  Fehlermeldungen.
- Ordne die Optionen nach Wichtigkeit. Die wichtigste steht oben; eine Option
  mit weitreichenden Folgen gehört nach unten und ist nie vorausgewählt.
- Formuliere die Optionen klar unterscheidbar. So erkennt der User die passende
  Wahl auf einen Blick.
- Orientiere dich in einem Formular am
  [Formular-Baustein](https://flow.mittwald.de/templates/bausteine/formular). Dort sind Aufbau,
  Validierung und Fehlerbehandlung geregelt.

---

# States

In einer RadioGroup sollte immer eine sinnvolle Option vorausgewählt
(**Selected**) sein.

## Disabled

Um Optionen in der RadioGroup zu deaktivieren, lässt sich der Disabled-State für
die gesamte RadioGroup oder gezielt für einzelne Radios bzw. RadioButtons
setzen.

```tsx
import {
  RadioButton,
  RadioGroup,
} from "@mittwald/flow-react-components";

<RadioGroup
  defaultValue="selected"
  l={[1, 1]}
  aria-label="States"
>
  <RadioButton value="default">Domain buchen</RadioButton>
  <RadioButton value="selected">Domain buchen</RadioButton>
  <RadioButton isDisabled value="default">
    Domain buchen
  </RadioButton>
  <RadioButton isDisabled value="selected">
    Domain buchen
  </RadioButton>
</RadioGroup>
```

## Error

Ein Error-State wird angezeigt, wenn etwas schiefgelaufen ist (siehe
[Fehlermeldungen](https://flow.mittwald.de/foundations/content-guidelines/fehlermeldungen)). Da meist
eine Option vorselektiert ist, wird er nur selten benötigt.

```tsx
import {
  FieldError,
  Label,
  RadioButton,
  RadioGroup,
} from "@mittwald/flow-react-components";

<RadioGroup isInvalid>
  <Label>Datenbank-Typ</Label>
  <RadioButton value="mysql">MySQL</RadioButton>
  <RadioButton value="redis">Redis</RadioButton>
  <FieldError>Bitte wähle eine Option aus</FieldError>
</RadioGroup>
```

---

# RadioButtons

Um Inhalte stärker hervorzuheben und die Klickfläche zu vergrößern, lassen sich
statt `<Radio />` auch `<RadioButton />` nutzen.

```tsx
import {
  Label,
  RadioButton,
  RadioGroup,
} from "@mittwald/flow-react-components";

<RadioGroup defaultValue="mysql">
  <Label>Datenbank-Typ</Label>
  <RadioButton value="mysql">MySQL</RadioButton>
  <RadioButton value="redis">Redis</RadioButton>
</RadioGroup>
```

## Weiterer Inhalt

Anstelle einer einfachen Bezeichnung kann der `<RadioButton />` auch mit
zusätzlichem Inhalt gefüllt werden. Verwende dazu innerhalb des
`<RadioButton />` [Text](https://flow.mittwald.de/components/content/text) für eine Überschrift und
`<Content />` für Fließtext.

```tsx
import {
  Content,
  RadioButton,
  RadioGroup,
  Text,
} from "@mittwald/flow-react-components";

<RadioGroup
  defaultValue="bookDomain"
  aria-label="Domain"
  l={[1, 1]}
>
  <RadioButton value="bookDomain">
    <Text>Domain buchen</Text>
    <Content>
      Du hast eine Wunsch-Domain? Kein Problem, wir helfen
      dir, die passende Domain für dich zu finden.
      <br />
      <strong>
        <small>8,28€ jährlich</small>
      </strong>
    </Content>
  </RadioButton>
  <RadioButton value="moveDomain">
    <Text>Domain umziehen</Text>
    <Content>
      Du hast schon eine Domain und möchtest sie von deinem
      jetzigen Anbieter zu mittwald umziehen.
      <br />
      <strong>
        <small>8,28€ jährlich</small>
      </strong>
    </Content>
  </RadioButton>
  <RadioButton value="virtualHost">
    <Text>Virtual Host einrichten</Text>
    <Content>
      Die Domain bleibt bei deinem bisherigen Anbieter, du
      kannst sie aber für deine Website in unserem mStudio
      verwenden.
      <br />
      <strong>
        <small>kostenlos</small>
      </strong>
    </Content>
  </RadioButton>
  <RadioButton value="subdomain">
    <Text>Subdomain anlegen</Text>
    <Content>
      Eine Subdomain von einer bereits vorhandenen Domain
      erstellen, um sie für dein Projekt zu verwenden.
      <br />
      <strong>
        <small>kostenlos</small>
      </strong>
    </Content>
  </RadioButton>
</RadioGroup>
```

## Benutzerdefinierte Spalten

Die RadioGroup verwendet das
[ColumnLayout](https://flow.mittwald.de/components/structure/column-layout), um eine Anpassung der
Spalten zu ermöglichen. Bei der Verwendung von RadioButtons entspricht der
Default dem des ColumnLayouts, während Radios im Default untereinander angezeigt
werden.

```tsx
import {
  Label,
  RadioButton,
  RadioGroup,
} from "@mittwald/flow-react-components";

<RadioGroup
  defaultValue="one"
  s={[1, 1]}
  m={[1, 1, 1]}
  l={[1, 1, 1, 1]}
>
  <Label>Benutzerdefinierte Spalten</Label>
  <RadioButton value="one">Spalte 1</RadioButton>
  <RadioButton value="two">Spalte 2</RadioButton>
  <RadioButton value="three">Spalte 3</RadioButton>
</RadioGroup>
```

---

# FieldDescription

Für eine kurze Hilfestellung zu den Optionen kann unterhalb der `<Radio />` oder
`<RadioButton />` eine `<FieldDescription />` eingebaut werden.

```tsx
import {
  FieldDescription,
  Label,
  Radio,
  RadioGroup,
} from "@mittwald/flow-react-components";

<RadioGroup defaultValue="more">
  <Label>Wie viele Pflanzen besitzt du?</Label>
  <Radio value="more">Mehr als 9 Pflanzen</Radio>
  <Radio value="6-8">6-8 Pflanzen</Radio>
  <Radio value="3-5">3-5 9 Pflanzen</Radio>
  <Radio value="1-2">1-2 Pflanzen</Radio>
  <Radio value="none">Keine</Radio>
  <FieldDescription>
    Mehrere identische Pflanzen in einem Topf gelten als
    eine Pflanze.
  </FieldDescription>
</RadioGroup>
```

---

# Kombiniere mit …

## ContextualHelp

Benutze die [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help) Component,
wenn du weitere Informationen bereitstellen möchtest, und diese zu lang für die
FieldDescription sind.

```tsx
import {
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  Label,
  Radio,
  RadioGroup,
  Text,
} from "@mittwald/flow-react-components";

<RadioGroup defaultValue="more">
  <Label>
    Täglicher Kaffeekonsum
    <ContextualHelpTrigger subject="Täglicher Kaffeekonsum">
      <Button />
      <ContextualHelp>
        <Text>
          Hier gibt es weitere Informationen, die zu lang
          für die FieldDescription sind.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Label>
  <Radio value="more">Mehr als 6 Tassen</Radio>
  <Radio value="5-6">5-6 Tassen</Radio>
  <Radio value="3-4">3-4 Tassen</Radio>
  <Radio value="1-2">1-2 Tassen</Radio>
  <Radio value="none">Trinke keinen Kaffee</Radio>
</RadioGroup>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Label,
  Radio,
  RadioGroup,
  Section,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ coffee: string }>({
    defaultValues: { coffee: "more" },
  });
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="coffee"
          rules={{
            required: "Bitte gib deinen Kaffeekonsum an",
          }}
        >
          <RadioGroup>
            <Label>Täglicher Kaffeekonsum</Label>
            <Radio value="more">Mehr als 6 Tassen</Radio>
            <Radio value="5-6">5-6 Tassen</Radio>
            <Radio value="3-4">3-4 Tassen</Radio>
            <Radio value="1-2">1-2 Tassen</Radio>
            <Radio value="none">Trinke keinen Kaffee</Radio>
          </RadioGroup>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<RadioGroupRenderProps>` | `'react-aria-RadioGroup'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `l` | `(number \| null)[]` | - | Column layout for container size l. |
| `lang` | `string` | - | - |
| `m` | `(number \| null)[]` | - | Column layout for container size m. |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `orientation` | `"horizontal" \| "vertical"` | `'vertical'` | The axis the Radio Button(s) should align with. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `s` | `(number \| null)[]` | - | Column layout for container size s. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--choice--icon-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--choice--icon-color--selected` | `#003FB8` | `#ABC6FF` |
| `--choice--icon-color--disabled` | `#B7C9DB` | `#8FA1B4` |

---

# Rating

Die Rating Component ermöglicht die Eingabe und Darstellung einer Bewertung — standardmäßig mit fünf Sternen.

> **mStudio-Extensions:** Importiere `Rating` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  Label,
  Rating,
} from "@mittwald/flow-react-components";

<Rating>
  <Label>Bewertung</Label>
</Rating>
```

---

# Best Practices

- Unterstütze die visuelle Darstellung immer mit ergänzendem Kontext. Dazu
  eignet sich zum Beispiel ein [Label](https://flow.mittwald.de/components/content/label).
- Nutze innerhalb eines Interfaces eine konsistente Skalierung. Gleichartige
  Bewertungen erhalten dieselbe Anzahl an Segmenten und dieselben Symbole.

---

# Sizes

Es stehen die Größen **Medium** oder **Small** zur Verfügung.

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

<>
  <Rating defaultValue={2} aria-label="Bewertung" />
  <Rating
    size="s"
    defaultValue={2}
    aria-label="Bewertung"
  />
</>
```

---

# Anzahl der Segmente

Über `maxValue` wird die Anzahl der Segmente gesetzt. Ohne Angabe besteht ein
Rating aus fünf Segmenten.

```tsx
import {
  Label,
  Rating,
} from "@mittwald/flow-react-components";

<Rating maxValue={10} defaultValue={7}>
  <Label>Bewertung</Label>
</Rating>
```

---

# Readonly

Verwende `isReadOnly`, wenn du die Rating-Component nur zur Darstellung
verwenden möchtest.

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

<Rating value={2} isReadOnly aria-label="Bewertung" />
```

---

# Alternative Icons

Über die Properties `iconEmpty` und `iconFilled` können benutzerdefinierte
[Icons](https://flow.mittwald.de/components/content/icon) gesetzt werden.

```tsx
import {
  Icon,
  Rating,
} from "@mittwald/flow-react-components";
import {
  IconLeaf,
  IconLeafFilled,
} from "@tabler/icons-react";

<Rating
  aria-label="Bewertung"
  iconEmpty={
    <Icon>
      <IconLeaf />
    </Icon>
  }
  iconFilled={
    <Icon color="success">
      <IconLeafFilled />
    </Icon>
  }
  defaultValue={2}
/>
```

---

# Icons pro Segment

Soll jede Stufe ihr eigenes Symbol haben, werden die Segmente einzeln über
`<RatingSegment />` in das Rating gelegt. Jedes Segment unterstützt eigene
`iconEmpty`- und `iconFilled`-Icons und überschreibt damit die Icons des
Ratings. Sind Segmente angegeben, bestimmen sie die Anzahl der Segmente.

Über `aria-label` lassen sich die automatischen Labels („3 von 5") pro Segment
überschreiben.

Über `fill` wird zusätzlich gesteuert, welche Segmente als gefüllt dargestellt
werden: **Cumulative** füllt alle Segmente bis zum Wert (Standard, das Verhalten
einer Sternebewertung), **Single** nur das gewählte Segment.

```tsx
import {
  Icon,
  Label,
  Rating,
  RatingSegment,
} from "@mittwald/flow-react-components";
import {
  IconMoodEmpty,
  IconMoodEmptyFilled,
  IconMoodHappy,
  IconMoodHappyFilled,
  IconMoodSad,
  IconMoodSadFilled,
} from "@tabler/icons-react";

<Rating fill="single" defaultValue={3}>
  <Label>Wie zufrieden bist du?</Label>
  <RatingSegment
    aria-label="Unzufrieden"
    iconEmpty={
      <Icon>
        <IconMoodSad />
      </Icon>
    }
    iconFilled={
      <Icon color="danger">
        <IconMoodSadFilled />
      </Icon>
    }
  />
  <RatingSegment
    aria-label="Neutral"
    iconEmpty={
      <Icon>
        <IconMoodEmpty />
      </Icon>
    }
    iconFilled={
      <Icon color="warning">
        <IconMoodEmptyFilled />
      </Icon>
    }
  />
  <RatingSegment
    aria-label="Zufrieden"
    iconEmpty={
      <Icon>
        <IconMoodHappy />
      </Icon>
    }
    iconFilled={
      <Icon color="success">
        <IconMoodHappyFilled />
      </Icon>
    }
  />
</Rating>
```

---

# Kombiniere mit ...

## BigNumber

Das Rating kann mit einer [BigNumber](https://flow.mittwald.de/components/data-visualisation/big-number)
kombiniert werden, um den Wert der BigNumber visuell besser einordnen zu können.

```tsx
import {
  BigNumber,
  Flex,
  Rating,
  Text,
} from "@mittwald/flow-react-components";

<Flex direction="column" gap="s" align="center">
  <BigNumber>
    <Text>80%</Text>
    <Text>Performance</Text>
  </BigNumber>
  <Rating aria-label="Performance" value={4} isReadOnly />
</Flex>
```

## AccentBox

Zur visuellen Hervorhebung kann das Rating innerhalb einer
[AccentBox](https://flow.mittwald.de/components/structure/accent-box) angezeigt werden.

```tsx
import {
  AccentBox,
  BigNumber,
  ColumnLayout,
  Flex,
  Rating,
  Text,
} from "@mittwald/flow-react-components";

<ColumnLayout>
  <AccentBox>
    <Flex direction="column" gap="s" align="center">
      <BigNumber>
        <Text>250 ms</Text>
        <Text>Dateioperationen</Text>
      </BigNumber>
      <Rating aria-label="Bewertung" value={4} isReadOnly />
      <Text>
        <small>Geringer Optimierungsbedarf</small>
      </Text>
    </Flex>
  </AccentBox>
  <AccentBox>
    <Flex direction="column" gap="xs" align="center">
      <BigNumber>
        <Text>100 ms</Text>
        <Text>Serveroperationen</Text>
      </BigNumber>
      <Rating aria-label="Bewertung" value={2} isReadOnly />
      <Text>
        <small>Optimierungsbedarf</small>
      </Text>
    </Flex>
  </AccentBox>
</ColumnLayout>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<RadioGroupRenderProps>` | `'react-aria-RadioGroup'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultValue` | `number` | `0` | The defaultValue sets the amount of default filled stars. Decimals are rounded to the nearest whole star. |
| `dir` | `string` | - | - |
| `fill` | `"single" \| "cumulative"` | `"cumulative"` | How the segments are filled. `cumulative` fills every segment up to the value, `single` fills only the selected segment. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `hidden` | `boolean` | - | - |
| `iconEmpty` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | An alternative icon for the empty state |
| `iconFilled` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | An alternative icon for the filled state |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `lang` | `string` | - | - |
| `maxValue` | `number` | `5` | The number of segments the rating consists of. Ignored when the rating has `RatingSegment` children — those define the number of segments themselves. |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `orientation` | `"horizontal" \| "vertical"` | `'vertical'` | The axis the Radio Button(s) should align with. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `size` | `"s" \| "m"` | `"m"` | The size of the component. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `number` | `0` | The value sets the amount of filled stars. Decimals are rounded to the nearest whole star. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--rating--spacing--s` | `0.125rem` |
| `--rating--spacing--m` | `0.25rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--rating--star-color` | `#5E6C7A` | `#DCE9F7` |
| `--rating--star-filled-color` | `#0054F5` | `#85AFFF` |

---

# SearchField

Mit einem SearchField wird gezielt nach Inhalten in einer Anwendung gesucht.

> **mStudio-Extensions:** Importiere `SearchField` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

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

<SearchField />
```

---

# Best Practices

- Gib visuelles Feedback bei Ladezuständen oder Fehlern. Ein Beispiel ist der
  Hinweis, dass keine Suchergebnisse gefunden wurden.
- Positioniere das SearchField leicht zugänglich und gut sichtbar. Platziere es
  dort, wo User eine Suche erwarten.

---

# Kombiniere mit ...

## Combine

Benutze die [Combine](https://flow.mittwald.de/components/structure/combine)-Component, um andere
Components, wie einen [Button](https://flow.mittwald.de/components/actions/button), neben dem
SearchField auszurichten.

```tsx
import {
  Combine,
  Button,
  SearchField,
} from "@mittwald/flow-react-components";

<Combine>
  <SearchField />
  <Button>Suchen</Button>
</Combine>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  SearchField,
  Section,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ search: string }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="search"
          rules={{
            required: "Bitte gib etwas in die Suche ein",
          }}
        >
          <SearchField />
        </Field>
        <SubmitButton>Suchen</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoComplete` | `string` | - | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). |
| `autoCorrect` | `string` | - | An attribute that takes as its value a space-separated string that describes what, if any, type of autocomplete functionality the input should provide. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#autocomplete). |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<SearchFieldRenderProps>` | `'react-aria-SearchField'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `enterKeyHint` | `"enter" \| "done" \| "go" \| "next" \| "previous" \| "search" \| "send"` | - | An enumerated attribute that defines what action label or icon to preset for the enter key on virtual keyboards. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint). |
| `excludeFromTabOrder` | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `inputMode` | `"text" \| "none" \| "search" \| "url" \| "tel" \| "email" \| "numeric" \| "decimal"` | - | Hints at the type of data that might be entered by the user while editing the element or its contents. See [MDN](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute). |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `lang` | `string` | - | - |
| `maxLength` | `number` | - | The maximum number of characters supported by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength). |
| `minLength` | `number` | - | The minimum number of characters required by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength). |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `pattern` | `string` | - | Regex pattern that the value of the input must match to be valid. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern). |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `spellCheck` | `string` | - | An enumerated attribute that defines whether the element may be checked for spelling errors. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck). |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `type` | `"text" \| "search" \| "url" \| "tel" \| "email" \| "password" \| (string & {})` | `'search'` | The type of input to render. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype). |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBeforeInput` | `FormEventHandler<HTMLInputElement>` | - | Handler that is called when the input value is about to be modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event). |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClear` | `(() => void)` | - | Handler that is called when the clear button is pressed. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onCompositionEnd` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a text composition system completes or cancels the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionend_event). |
| `onCompositionStart` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a text composition system starts a new text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event). |
| `onCompositionUpdate` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a new character is received in the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event). |
| `onCopy` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user copies text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncopy). |
| `onCut` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user cuts text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncut). |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onInput` | `FormEventHandler<HTMLInputElement>` | - | Handler that is called when the input value is modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPaste` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user pastes text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/onpaste). |
| `onSelect` | `ReactEventHandler<HTMLInputElement>` | - | Handler that is called when text in the input is selected. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event). |
| `onSubmit` | `((value: string) => void)` | - | Handler that is called when the SearchField is submitted. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-activedescendant` | `string` | - | Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application. |
| `aria-autocomplete` | `"list" \| "none" \| "inline" \| "both"` | - | Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made. |
| `aria-controls` | `string` | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |
| `aria-haspopup` | `boolean \| "false" \| "true" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` | - | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--form-control--label-to-control-spacing` | `0.25rem` |
| `--form-control--control-to-info-spacing` | `0.25rem` |
| `--form-control--spacing-x` | `0.5rem` |
| `--form-control--spacing-y` | `0.25rem` |
| `--form-control--padding-x` | `16px` |
| `--form-control--padding-y` | `8px` |
| `--form-control--corner-radius` | `8px` |
| `--form-control--border-width` | `1px` |
| `--form-control--border-style` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--form-control--placeholder-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--placeholder-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--border-color--invalid` | `#E1244C` | `#F2A2B3` |
| `--form-control--border-color--focused` | `#0054F5` | `#85AFFF` |
| `--form-control--border-color--selected` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--background-color--default` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--form-control--background-color--focused` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--invalid` | `#FDF0F3` | `#540B1B` |
| `--form-control--background-color--selected` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--form-control--content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--content-color--selected` | `#1B1F24` | `#FFFFFF` |

---

# SegmentedControl

Ein SegmentedControl bietet eine Einfachauswahl aus 2 bis 5 kurzen Optionen.

> **mStudio-Extensions:** Importiere `SegmentedControl` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  Label,
  Segment,
  SegmentedControl,
} from "@mittwald/flow-react-components";

<SegmentedControl defaultValue="lastschrift">
  <Label>Zahlungsart</Label>
  <Segment value="lastschrift">Lastschrift</Segment>
  <Segment value="Rechnung">Rechnung</Segment>
</SegmentedControl>
```

---

# Best Practices

Das SegmentedControl hat zwei verschiedene Aufgaben übernommen. Welche Component
es ersetzt, entscheidet die Aufgabe an der jeweiligen Stelle:

- Schaltet die Auswahl den Inhalt darunter um, ersetzen
  [Tabs](https://flow.mittwald.de/components/structure/tabs) das SegmentedControl.
- Setzt die Auswahl einen Wert – etwa in einem Formular oder in Einstellungen –
  ersetzt eine [RadioGroup](https://flow.mittwald.de/components/form-controls/radio-group) das
  SegmentedControl.
- Migriere von Hand. Es gibt keinen Codemod: welche Component passt, hängt an
  der Aufgabe und ist pro Verwendung zu entscheiden. Die Diffs für beide Wege
  stehen in der
  [MIGRATION.md](https://github.com/mittwald/flow/blob/main/packages/components/MIGRATION.md).
- SegmentedControl gibt zur Laufzeit eine Deprecation-Warnung aus und wird in
  einer zukünftigen Major-Version entfernt. Bis dahin bleibt der alte Pfad
  abgesichert (siehe [Versionierung & Stabilität](https://flow.mittwald.de/get-started/versioning)).

---

# Inhalte umschalten: Tabs

Ein SegmentedControl, dessen Auswahl den Inhalt darunter austauscht, ist ein
Content Switcher – und damit die Aufgabe von [Tabs](https://flow.mittwald.de/components/structure/tabs).
Aus jedem `<Segment />` wird ein `<Tab />`, dessen Titel im `<TabTitle />` steht
und dessen Inhalt direkt im Tab liegt. Das Label und der State für den
angezeigten Inhalt entfallen.

```tsx
import {
  Tab,
  Tabs,
  TabTitle,
} from "@mittwald/flow-react-components";

<Tabs>
  <Tab>
    <TabTitle>Mit App verbinden</TabTitle>
    App Content
  </Tab>
  <Tab>
    <TabTitle>Mit Container verbinden</TabTitle>
    Container Content
  </Tab>
</Tabs>
```

---

# Werte auswählen: RadioGroup

Ein SegmentedControl, dessen Auswahl einen Wert setzt, wird zu einer
[RadioGroup](https://flow.mittwald.de/components/form-controls/radio-group). Aus jedem `<Segment />`
wird ein `<Radio />`; Label, FieldDescription, FieldError und die Anbindung an
[React Hook Form](https://flow.mittwald.de/components/react-hook-form/form) bleiben unverändert.

```tsx
import {
  FieldDescription,
  Label,
  Radio,
  RadioGroup,
} from "@mittwald/flow-react-components";

<RadioGroup defaultValue="lastschrift">
  <Label>Zahlungsart</Label>
  <Radio value="lastschrift">Lastschrift</Radio>
  <Radio value="rechnung">Rechnung</Radio>
  <FieldDescription>
    Die Zahlungsart kann jederzeit geändert werden
  </FieldDescription>
</RadioGroup>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<RadioGroupRenderProps>` | `'react-aria-RadioGroup'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `containerBreakpointSize` | `"s" \| "xs" \| "m" \| "l" \| "xl"` | - | The breakpoint at which the element switches to its compact layout. Evaluated as a container query against the surrounding container, not against the viewport. |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `lang` | `string` | - | - |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `orientation` | `"horizontal" \| "vertical"` | `'vertical'` | The axis the Radio Button(s) should align with. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--form-control--label-to-control-spacing` | `0.25rem` |
| `--form-control--control-to-info-spacing` | `0.25rem` |
| `--form-control--spacing-x` | `0.5rem` |
| `--form-control--spacing-y` | `0.25rem` |
| `--form-control--padding-x` | `16px` |
| `--form-control--padding-y` | `8px` |
| `--form-control--corner-radius` | `8px` |
| `--form-control--border-width` | `1px` |
| `--form-control--border-style` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--form-control--placeholder-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--placeholder-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--border-color--invalid` | `#E1244C` | `#F2A2B3` |
| `--form-control--border-color--focused` | `#0054F5` | `#85AFFF` |
| `--form-control--border-color--selected` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--background-color--default` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--form-control--background-color--focused` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--invalid` | `#FDF0F3` | `#540B1B` |
| `--form-control--background-color--selected` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--form-control--content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--content-color--selected` | `#1B1F24` | `#FFFFFF` |

---

# Select

Ein Select ermöglicht es Usern, eine einzelne Option aus einer vordefinierten Liste auszuwählen.

> **mStudio-Extensions:** Importiere `Select` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

Verwendung mit dynamisch erstellten Options

Wenn die `Select`-Component ohne ein `key` Prop und mit dynamisch erstellten
`Options` betrieben wird, kann dies dazu führen, dass die Component
einfriert oder nicht mehr reagiert. Verwende ein `key` Prop auf der
`Select`-Component, welches sich mit den dynamischen `Options` ändert.

```tsx
import {
  Label,
  Option,
  Select,
} from "@mittwald/flow-react-components";

<Select>
  <Label>App</Label>
  <Option>WordPress</Option>
  <Option>TYPO3</Option>
  <Option>Contao</Option>
  <Option>Drupal</Option>
  <Option>Joomla!</Option>
  <Option>Matomo</Option>
</Select>
```

---

# Best Practices

- Formuliere das [Label](https://flow.mittwald.de/components/content/label) kurz und deutlich.
- Nutze einen Placeholder mit klarer Handlungsaufforderung, wenn kein sinnvoller
  Default existiert. Ein Beispiel ist „Sprache wählen".
- Benenne die Optionen verständlich und konsistent.
- Halte die Zahl der Optionen überschaubar. Bei sehr vielen Einträgen eignet
  sich eher eine [ComboBox](https://flow.mittwald.de/components/form-controls/combo-box).
- Ordne die Optionen nachvollziehbar. Möglich sind alphabetische, thematische
  oder Relevanz-Sortierung.

---

# Default-Wert

Mit `defaultSelectedKey` kann eine Default-Option angegeben werden, die dem User
standardmäßig zuerst angezeigt wird.

```tsx
import {
  Label,
  Option,
  Select,
} from "@mittwald/flow-react-components";

<Select defaultSelectedKey="wordpress" isRequired>
  <Label>App</Label>
  <Option value="wordpress">WordPress</Option>
  <Option value="typo3">TYPO3</Option>
</Select>
```

---

# Multiple

Über `selectionMode` kann zwischen den Modi `single` und `multiple` gewechselt
werden.

```tsx
import {
  Label,
  Option,
  Select,
} from "@mittwald/flow-react-components";

<Select selectionMode="multiple">
  <Label>App</Label>
  <Option>WordPress</Option>
  <Option>TYPO3</Option>
  <Option>Contao</Option>
  <Option>Drupal</Option>
  <Option>Joomla!</Option>
  <Option>Matomo</Option>
</Select>
```

---

# Mit FieldDescription

Um wichtige Hinweise zu den Auswahloptionen des Select bereitzustellen, kann
unterhalb eine `<FieldDescription />` eingebaut werden.

```tsx
import {
  FieldDescription,
  Label,
  Option,
  Select,
} from "@mittwald/flow-react-components";

<Select>
  <Label>App</Label>
  <Option>WordPress</Option>
  <Option>TYPO3</Option>
  <Option>Contao</Option>
  <Option>Drupal</Option>
  <Option>Joomla!</Option>
  <Option>Matomo</Option>
  <FieldDescription>Weitere Informationen</FieldDescription>
</Select>
```

---

# Kombiniere mit ...

## Combine

Benutze die [Combine](https://flow.mittwald.de/components/structure/combine) Component, um
beispielsweise einen [Button](https://flow.mittwald.de/components/actions/button) neben dem Select zu
platzieren.

```tsx
import {
  Combine,
  Button,
  Select,
  Label,
  Option,
} from "@mittwald/flow-react-components";

<Combine>
  <Select>
    <Label>App</Label>
    <Option>WordPress</Option>
    <Option>TYPO3</Option>
    <Option>Contao</Option>
    <Option>Drupal</Option>
    <Option>Joomla!</Option>
    <Option>Matomo</Option>
  </Select>
  <Button>Hinzufügen</Button>
</Combine>
```

## ContextualHelp

Benutze das [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help), um weitere
Informationen bereitstellen zu können.

```tsx
import {
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  Label,
  Option,
  Select,
  Text,
} from "@mittwald/flow-react-components";

<Select>
  <Label>
    App
    <ContextualHelpTrigger subject="App">
      <Button />
      <ContextualHelp>
        <Text>
          Hier gibt es weitere Informationen, die zu lang
          für die FieldDescription sind.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Label>
  <Option>WordPress</Option>
  <Option>TYPO3</Option>
  <Option>Contao</Option>
  <Option>Drupal</Option>
  <Option>Joomla!</Option>
  <Option>Matomo</Option>
</Select>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Label,
  Option,
  Section,
  Select,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ app: string }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="app"
          rules={{
            required: "Bitte wähle eine App aus",
          }}
        >
          <Select>
            <Label>App</Label>
            <Option value="wordpress">WordPress</Option>
            <Option value="typo3">TYPO3</Option>
          </Select>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `allowsEmptyCollection` | `boolean` | - | Whether the select should be allowed to be open when the collection is empty. |
| `autoComplete` | `string` | - | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `defaultOpen` | `boolean` | - | Sets the default open state of the menu. |
| `defaultSelectedKey` _(deprecated)_ | `Key` | - | The initial selected key in the collection (uncontrolled). @deprecated |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `disabledKeys` | `Iterable<Key>` | - | The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. |
| `excludeFromTabOrder` | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isOpen` | `boolean` | - | Sets the open state of the menu. |
| `isReadOnly` | `boolean` | - | Whether the component is read only. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `lang` | `string` | - | - |
| `name` | `string` | - | The name of the input, used when submitting an HTML form. |
| `placeholder` | `string` | `'Select an item' (localized)` | Temporary text that occupies the select when it is empty. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `selectedKey` _(deprecated)_ | `Key` | - | The currently selected key in the collection (controlled). @deprecated |
| `selectionMode` | `"multiple" \| "single"` | `'single'` | Whether single or multiple selection is enabled. |
| `shouldCloseOnSelect` | `boolean` | - | Whether the Select should close when an item is selected. Defaults to true if selectionMode is single, false otherwise. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: Key \| Key[] \| null) => void)` | - | Handler that is called when the selected value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onOpenChange` | `((isOpen: boolean) => void)` | - | Method that is called when the open state of the menu changes. |
| `onSelectionChange` _(deprecated)_ | `((value: Key \| Key[] \| null) => void)` | - | Handler that is called when the selection changes. @deprecated Use `onChange` instead. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--form-control--label-to-control-spacing` | `0.25rem` |
| `--form-control--control-to-info-spacing` | `0.25rem` |
| `--form-control--spacing-x` | `0.5rem` |
| `--form-control--spacing-y` | `0.25rem` |
| `--form-control--padding-x` | `16px` |
| `--form-control--padding-y` | `8px` |
| `--form-control--corner-radius` | `8px` |
| `--form-control--border-width` | `1px` |
| `--form-control--border-style` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--form-control--placeholder-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--placeholder-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--border-color--invalid` | `#E1244C` | `#F2A2B3` |
| `--form-control--border-color--focused` | `#0054F5` | `#85AFFF` |
| `--form-control--border-color--selected` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--background-color--default` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--form-control--background-color--focused` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--invalid` | `#FDF0F3` | `#540B1B` |
| `--form-control--background-color--selected` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--form-control--content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--content-color--selected` | `#1B1F24` | `#FFFFFF` |

---

# Slider

Slider ermöglichen die Auswahl von Zahlenwerten innerhalb eines definierten Wertebereichs.

> **mStudio-Extensions:** Importiere `Slider` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  Label,
  Slider,
} from "@mittwald/flow-react-components";

<Slider
  formatOptions={{
    style: "unit",
    unit: "gigabyte",
  }}
  minValue={50}
  maxValue={750}
  defaultValue={150}
  step={50}
  showInitialMarker
>
  <Label>Speicherplatz</Label>
</Slider>
```

---

# Best Practices

- Wähle Min-, Max- und Default-Werte logisch für die User.
- Wähle die Schrittweite (`step`) sinnvoll, ohne zu viele kleine Schritte.
- Formuliere das beschreibende Label neben der Unit kurz und verständlich.
- Setze bei Bedarf einen InitialMarker über `showInitialMarker`. So erkennen
  User den Startwert.

---

# Kombiniere mit ...

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Label,
  Section,
  Slider,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ storage: number }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="storage"
          rules={{
            required:
              "Bitte wähle deinen Speicherplatz aus",
          }}
        >
          <Slider
            formatOptions={{
              style: "unit",
              unit: "gigabyte",
            }}
            minValue={50}
            maxValue={750}
            defaultValue={150}
            step={50}
            showInitialMarker
          >
            <Label>Speicherplatz</Label>
          </Slider>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | The children of the component. A function may be provided to alter the children based on component state. |
| `className` | `ClassNameOrFunction<SliderRenderProps>` | `'react-aria-Slider'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `formatOptions` | `NumberFormatOptions` | - | The display format of the value label. |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the whole Slider is disabled. |
| `isInvalid` | `boolean` | - | Whether the component is invalid. |
| `isReadOnly` | `boolean` | - | Whether the component is read only. |
| `lang` | `string` | - | - |
| `maxValue` | `number` | `100` | The slider's maximum value. |
| `minValue` | `number` | `0` | The slider's minimum value. |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the Slider. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `showInitialMarker` | `boolean` | - | Whether the marker for the initial value should be visible |
| `sliderOnly` | `boolean` | - | Hide Buttons, Label and Value |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `step` | `number` | `1` | The slider's step value. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onChangeEnd` | `((value: number \| number[]) => void)` | - | Fired when the slider stops moving, due to being let go. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--slider--spacing-x` | `0.5rem` |
| `--slider--spacing-y` | `1rem` |
| `--slider--value-font-weight` | `bold` |
| `--slider--track-height` | `8px` |
| `--slider--track-border-width` | `1px` |
| `--slider--track-border-style` | `solid` |
| `--slider--corner-radius` | `4px` |
| `--slider--handle-corner-radius` | `50%` |
| `--slider--handle-size` | `1.5rem` |
| `--slider--handle-border-width` | `4px` |
| `--slider--initial-marker-height` | `1rem` |
| `--slider--initial-marker-border-width` | `4px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--slider--color--default` | `#1B1F24` | `#FFFFFF` |
| `--slider--color--disabled` | `#8FA1B4` | `#B7C9DB` |
| `--slider--track-color--default` | `#F4F8FC` | `#292F37` |
| `--slider--track-color--disabled` | `#F4F8FC` | `#292F37` |
| `--slider--track-border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--slider--track-border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--slider--handle-fill-color` | `#FFFFFF` | `#1B1F24` |

---

# Switch

Ein Switch schaltet eine Option unmittelbar ein oder aus.

> **mStudio-Extensions:** Importiere `Switch` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  Label,
  Switch,
} from "@mittwald/flow-react-components";

<Switch defaultSelected>
  <Label>Autoresponder</Label>
</Switch>
```

---

# Best Practices

- Übernimm Änderungen sofort, ohne zusätzlichen Speichern-Button.
- Beschreibe die Funktion mit einem klaren, prägnanten Label, meist ein bis drei
  Wörter.
- Halte die Beschriftung unabhängig vom Zustand des Switches gleich.

---

# Label-Position: Links

Die Positionierung des Labels sollte sich am Seitenlayout orientieren. Steht der
Switch rechtsbündig, sollte die Beschriftung links davor platziert werden. So
erfasst der User zuerst den Zweck, bevor die Aktion ausgeführt wird.

```tsx
import {
  Label,
  Switch,
} from "@mittwald/flow-react-components";

<Switch labelPosition="leading">
  <Label>Autoresponder</Label>
</Switch>
```

---

# Disabled

In Ausnahmefällen kann ein deaktivierter Switch verwendet werden, um eine
Funktion temporär als nicht verfügbar darzustellen, ohne diesen vollständig aus
der Oberfläche zu entfernen.

```tsx
import {
  Label,
  Switch,
} from "@mittwald/flow-react-components";

<Switch isDisabled>
  <Label>Autoresponder</Label>
</Switch>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<SwitchRenderProps>` | `'react-aria-Switch'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultSelected` | `boolean` | - | Whether the element should be selected (uncontrolled). |
| `dir` | `string` | - | - |
| `excludeFromTabOrder` | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isSelected` | `boolean` | - | Whether the element should be selected (controlled). |
| `labelPosition` | `"leading" \| "trailing"` | `"trailing"` | Whether the label should appear before or after the switch. |
| `lang` | `string` | - | - |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `value` | `string` | - | The value of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefvalue). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((isSelected: boolean) => void)` | - | Handler that is called when the element's selection state changes. |
| `onClick` | `((e: MouseEvent<FocusableElement, MouseEvent>) => void)` | - | **Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions. |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onHoverChange` | `((isHovering: boolean) => void)` | - | Handler that is called when the hover state changes. |
| `onHoverEnd` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction ends. |
| `onHoverStart` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction starts. |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPress` | `((e: PressEvent) => void)` | - | Handler that is called when the press is released over the target. |
| `onPressChange` | `((isPressed: boolean) => void)` | - | Handler that is called when the press state changes. |
| `onPressEnd` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. |
| `onPressStart` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction starts. |
| `onPressUp` | `((e: PressEvent) => void)` | - | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-controls` | `string` | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--switch--label-to-track-spacing` | `0.5rem` |
| `--switch--track-height` | `1.5rem` |
| `--switch--track-width` | `2.75rem` |
| `--switch--track-corner-radius` | `0.75rem` |
| `--switch--track-padding` | `0.125rem` |
| `--switch--handle-size` | `1.25rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--switch--track-background-color--default` | `#3A434E` | `#E5EFF8` |
| `--switch--track-background-color--disabled` | `#E5EFF8` | `#3A434E` |
| `--switch--track-background-color--selected` | `#0054F5` | `#85AFFF` |
| `--switch--handle-content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--switch--handle-content-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--switch--handle-background-color` | `#FFFFFF` | `#1B1F24` |

---

# TextArea

Die TextArea ermöglicht es dem User, längere Texte über mehrere Zeilen hinweg einzugeben.

> **mStudio-Extensions:** Importiere `TextArea` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  FieldDescription,
  Label,
  TextArea,
} from "@mittwald/flow-react-components";

<TextArea>
  <Label>Public Key</Label>
  <FieldDescription>Beginnt mit ssh-rsa</FieldDescription>
</TextArea>
```

---

# Best Practices

- Wähle die Höhe über das Property `rows` passend zur erwarteten Textmenge.
- Formuliere das [Label](https://flow.mittwald.de/components/content/label) prägnant und leicht
  verständlich.
- Nutze die FieldDescription für Beispiele, Formatierungshinweise oder Kontext.
- Formuliere [Fehlermeldungen](https://flow.mittwald.de/foundations/content-guidelines/fehlermeldungen)
  klar, hilfreich und lösungsorientiert.

---

# Character Count

Mit der Property `showCharacterCount` wird automatisch eine
`<FieldDescription />` ergänzt, die die aktuelle Zeichenanzahl und – sofern
angegeben – die maximale Zeichenanzahl anzeigt.

```tsx
import {
  Label,
  TextArea,
} from "@mittwald/flow-react-components";

<TextArea showCharacterCount maxLength={100}>
  <Label>Nachricht</Label>
</TextArea>
```

---

# Validierung

Nutze für die Validierung [React Hook Form](https://flow.mittwald.de/components/react-hook-form/form).
Alternativ stehen aber auch folgende Properties zur Verfügung:

- `isRequired` für Pflichtfelder.
- `validate` für eigene Validierungen.
- HTML Input Properties wie `minLength`.

Bei ungültiger Eingabe wird die TextArea invalidiert. Über `<FieldError />` kann
eine entsprechende Fehlermeldung ausgegeben werden.

## Required

```tsx
import {
  Label,
  TextArea,
} from "@mittwald/flow-react-components";

<TextArea isRequired>
  <Label>Public Key</Label>
</TextArea>
```

## Invalid

```tsx
import {
  FieldError,
  Label,
  TextArea,
} from "@mittwald/flow-react-components";

<TextArea isInvalid defaultValue="hello">
  <Label>Public Key</Label>
  <FieldError>Ungültiger Key</FieldError>
</TextArea>
```

---

# Resize

## Automatisch

Mit der Property `autoResizeMaxRows` lässt sich eine maximale Höhe definieren,
bis zu der sich die TextArea automatisch an den Inhalt anpasst.

```tsx
import {
  Label,
  TextArea,
} from "@mittwald/flow-react-components";

<TextArea rows={1} autoResizeMaxRows={5}>
  <Label>Nachricht</Label>
</TextArea>
```

## Manuell

Über die Properties `allowResize`, `allowVerticalResize` oder
`allowHorizontalResize` kann die Größe der TextArea manuell verändert werden.

```tsx
import {
  Label,
  TextArea,
} from "@mittwald/flow-react-components";

<TextArea allowResize>
  <Label>Nachricht</Label>
</TextArea>
```

## Kombiniert

Beide Resize-Varianten lassen sich auch miteinander kombinieren. In diesem Fall
passt sich die TextArea zunächst automatisch an, bis die Größe einmal manuell
geändert wird. Danach bleibt sie in der eingestellten Größe bestehen.

```tsx
import {
  Label,
  TextArea,
} from "@mittwald/flow-react-components";

<TextArea allowResize rows={1} autoResizeMaxRows={5}>
  <Label>Nachricht</Label>
</TextArea>
```

---

# Disabled

Achte bei der Verwendung von **Disabled** darauf, dass aus dem Kontext klar
wird, warum der User gerade nicht mit der TextArea interagieren kann.

```tsx
import {
  Label,
  TextArea,
} from "@mittwald/flow-react-components";

<TextArea isDisabled>
  <Label>Public Key</Label>
</TextArea>
```

---

# Kombiniere mit ...

## Combine

Benutze die [Combine](https://flow.mittwald.de/components/structure/combine)-Component, um andere
Components, wie einen [Button](https://flow.mittwald.de/components/actions/button), neben der TextArea
auszurichten.

```tsx
import {
  Combine,
  Button,
  Label,
  TextArea,
} from "@mittwald/flow-react-components";

<Combine>
  <TextArea>
    <Label>Nachricht</Label>
  </TextArea>
  <Button>Senden</Button>
</Combine>
```

## ContextualHelp

Verwende [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help), um zusätzliche
Informationen bereitzustellen, die über den Umfang der FieldDescription
hinausgehen.

```tsx
import {
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  Label,
  TextArea,
  Text,
} from "@mittwald/flow-react-components";

<TextArea>
  <Label>
    Public Key
    <ContextualHelpTrigger subject="Public Key">
      <Button />
      <ContextualHelp>
        <Text>
          Hier gibt es weitere Informationen, die zu lang
          für die FieldDescription sind.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Label>
</TextArea>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Label,
  Section,
  TextArea,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ message: string }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="message"
          rules={{
            required: "Bitte gib eine Nachricht ein",
          }}
        >
          <TextArea>
            <Label>Nachricht</Label>
          </TextArea>
        </Field>
        <SubmitButton>Senden</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `allowHorizontalResize` _(deprecated)_ | `boolean` | - | @deprecated Use `allowResize` instead. |
| `allowResize` | `boolean \| "horizontal" \| "vertical"` | - | Allows the user to manually resize the textArea horizontally. |
| `allowVerticalResize` _(deprecated)_ | `boolean` | - | @deprecated Use `allowResize` instead. |
| `autoComplete` | `string` | - | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). |
| `autoCorrect` | `string` | - | An attribute that takes as its value a space-separated string that describes what, if any, type of autocomplete functionality the input should provide. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#autocomplete). |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `autoResizeMaxRows` | `number` | - | Whether the text area should grow if its content gets longer than its initial height. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<TextFieldRenderProps>` | `'react-aria-TextField'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `enterKeyHint` | `"enter" \| "done" \| "go" \| "next" \| "previous" \| "search" \| "send"` | - | An enumerated attribute that defines what action label or icon to preset for the enter key on virtual keyboards. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint). |
| `excludeFromTabOrder` | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `inputMode` | `"text" \| "none" \| "search" \| "url" \| "tel" \| "email" \| "numeric" \| "decimal"` | - | Hints at the type of data that might be entered by the user while editing the element or its contents. See [MDN](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute). |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `lang` | `string` | - | - |
| `maxLength` | `number` | - | The maximum number of characters supported by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength). |
| `minLength` | `number` | - | The minimum number of characters required by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength). |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `pattern` | `string` | - | Regex pattern that the value of the input must match to be valid. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern). |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `showCharacterCount` | `boolean` | - | Whether a character count should be displayed inside the field description. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `spellCheck` | `string` | - | An enumerated attribute that defines whether the element may be checked for spelling errors. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck). |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `type` | `"text" \| "search" \| "url" \| "tel" \| "email" \| "password" \| (string & {})` | `'text'` | The type of input to render. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype). |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBeforeInput` | `FormEventHandler<HTMLInputElement>` | - | Handler that is called when the input value is about to be modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event). |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onCompositionEnd` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a text composition system completes or cancels the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionend_event). |
| `onCompositionStart` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a text composition system starts a new text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event). |
| `onCompositionUpdate` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a new character is received in the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event). |
| `onCopy` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user copies text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncopy). |
| `onCut` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user cuts text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncut). |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onInput` | `FormEventHandler<HTMLInputElement>` | - | Handler that is called when the input value is modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPaste` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user pastes text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/onpaste). |
| `onSelect` | `ReactEventHandler<HTMLInputElement>` | - | Handler that is called when text in the input is selected. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event). |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-activedescendant` | `string` | - | Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application. |
| `aria-autocomplete` | `"list" \| "none" \| "inline" \| "both"` | - | Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made. |
| `aria-controls` | `string` | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |
| `aria-haspopup` | `boolean \| "false" \| "true" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` | - | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--form-control--label-to-control-spacing` | `0.25rem` |
| `--form-control--control-to-info-spacing` | `0.25rem` |
| `--form-control--spacing-x` | `0.5rem` |
| `--form-control--spacing-y` | `0.25rem` |
| `--form-control--padding-x` | `16px` |
| `--form-control--padding-y` | `8px` |
| `--form-control--corner-radius` | `8px` |
| `--form-control--border-width` | `1px` |
| `--form-control--border-style` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--form-control--placeholder-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--placeholder-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--border-color--invalid` | `#E1244C` | `#F2A2B3` |
| `--form-control--border-color--focused` | `#0054F5` | `#85AFFF` |
| `--form-control--border-color--selected` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--background-color--default` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--form-control--background-color--focused` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--invalid` | `#FDF0F3` | `#540B1B` |
| `--form-control--background-color--selected` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--form-control--content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--content-color--selected` | `#1B1F24` | `#FFFFFF` |

---

# TextField

Ein TextField ermöglicht die Texteingabe über die Tastatur.

> **mStudio-Extensions:** Importiere `TextField` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  FieldDescription,
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<TextField>
  <Label>URL</Label>
  <FieldDescription>Beginnt mit https://</FieldDescription>
</TextField>
```

---

# Best Practices

- Nutze das TextField nur für einzeilige Eingaben. Für mehrzeilige Angaben
  eignet sich die [TextArea](https://flow.mittwald.de/components/form-controls/text-area).
- Verwende für spezielle Eingabetypen das passende `type` Attribut. Für
  E-Mail-Adressen ist das zum Beispiel `email`.
- Orientiere dich in einem Formular am
  [Formular-Baustein](https://flow.mittwald.de/templates/bausteine/formular). Dort sind Labels,
  Hilfetexte, Platzhalter und Fehlermeldungen geregelt.

---

# Value

Standardmäßig ist der Value eines TextFields leer. Es ist möglich dem TextField
eine uncontrolled `defaultValue` mitzugeben. Es kann auch ein controlled `value`
für das TextField gesetzt werden, um dieses über `onChange` zu updaten.

```tsx
import {
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<TextField defaultValue="https://mittwald.de">
  <Label>URL</Label>
</TextField>
```

---

# Input Properties

Das TextField unterstützt die Standard-Properties eines HTML `<input />` Feldes.
(s. [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input))

```tsx
import {
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<TextField name="email" type="email">
  <Label>E-Mail</Label>
</TextField>
```

## Passwort

TextFields mit `type="password"` erhalten automatisch einen Button zum ein- und
ausblenden des Passworts.

```tsx
import {
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<TextField type="password">
  <Label>Passwort</Label>
</TextField>
```

---

# Character Count

Über das `showCharacterCount` Property wird eine FieldDescription hinzugefügt,
die aktuelle Anzahl der Zeichen und, falls angegeben, die maximale Zeichenanzahl
anzeigt.

```tsx
import {
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<TextField showCharacterCount maxLength={10}>
  <Label>Benutzername</Label>
</TextField>
```

---

# Validierung

Nutze für die Validierung [React Hook Form](https://flow.mittwald.de/components/react-hook-form/form).
Alternativ stehen aber auch folgende Properties zur Verfügung:

- `isRequired` für Pflichtfelder.
- `validate` für eigene Validierungen.
- HTML Input Properties wie `type="email"`, `minLength`.

Wenn die Benutzereingabe nicht den Anforderungen entspricht, wird das TextField
invalidiert. Mittels `<FieldError />` kann eine Fehlermeldung angezeigt werden.

```tsx
import {
  FieldError,
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<TextField isInvalid defaultValue="hello">
  <Label>URL</Label>
  <FieldError>Das ist keine URL</FieldError>
</TextField>
```

---

# Disabled

Achte bei der Verwendung von **Disabled** darauf, dass aus dem Kontext klar
wird, warum der User gerade nicht mit dem TextField interagieren kann.

```tsx
import {
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<TextField isDisabled>
  <Label>URL</Label>
</TextField>
```

---

# Kombiniere mit ...

## Combine

Benutze die [Combine](https://flow.mittwald.de/components/structure/combine) Component, um einen
[Button](https://flow.mittwald.de/components/actions/button) neben deinem TextField zu platzieren.

```tsx
import {
  Combine,
  Button,
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<Combine>
  <TextField>
    <Label>Weiterleitungsziel</Label>
  </TextField>
  <Button>Hinzufügen</Button>
</Combine>
```

## Button

Du kannst einen Button zum TextField hinzufügen, um benutzerdefinierte Aktionen
auszuführen.

```tsx
import {
  Label,
  TextField,
  Button,
  IconStar,
} from "@mittwald/flow-react-components";

<TextField>
  <Label>Label</Label>
  <Button aria-label="Custom Button">
    <IconStar />
  </Button>
</TextField>
```

## ContextualHelp

Benutze die [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help) Component,
wenn du weitere Informationen bereitstellen möchtest, und diese zu lang für die
FieldDescription sind.

```tsx
import {
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  Label,
  Text,
  TextField,
} from "@mittwald/flow-react-components";

<TextField>
  <Label>
    URL
    <ContextualHelpTrigger subject="URL">
      <Button />
      <ContextualHelp>
        <Text>
          Hier gibt es weitere Informationen, die zu lang
          für die FieldDescription sind.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Label>
</TextField>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Label,
  Section,
  TextField,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ url: string }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="url"
          rules={{
            required: "Bitte gib eine URL ein",
          }}
        >
          <TextField>
            <Label>URL</Label>
          </TextField>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoComplete` | `string` | - | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). |
| `autoCorrect` | `string` | - | An attribute that takes as its value a space-separated string that describes what, if any, type of autocomplete functionality the input should provide. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#autocomplete). |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<TextFieldRenderProps>` | `'react-aria-TextField'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `enterKeyHint` | `"enter" \| "done" \| "go" \| "next" \| "previous" \| "search" \| "send"` | - | An enumerated attribute that defines what action label or icon to preset for the enter key on virtual keyboards. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint). |
| `excludeFromTabOrder` | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `inputMode` | `"text" \| "none" \| "search" \| "url" \| "tel" \| "email" \| "numeric" \| "decimal"` | - | Hints at the type of data that might be entered by the user while editing the element or its contents. See [MDN](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute). |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `lang` | `string` | - | - |
| `maxLength` | `number` | - | The maximum number of characters supported by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength). |
| `minLength` | `number` | - | The minimum number of characters required by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength). |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `pattern` | `string` | - | Regex pattern that the value of the input must match to be valid. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern). |
| `placeholder` | `string` | - | Temporary text that occupies the text input when it is empty. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/placeholder). |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `showCharacterCount` | `boolean` | - | Whether a character count should be displayed inside the field description. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `spellCheck` | `string` | - | An enumerated attribute that defines whether the element may be checked for spelling errors. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck). |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `type` | `"text" \| "search" \| "url" \| "tel" \| "email" \| "password" \| (string & {})` | `'text'` | The type of input to render. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype). |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBeforeInput` | `FormEventHandler<HTMLInputElement>` | - | Handler that is called when the input value is about to be modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event). |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onCompositionEnd` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a text composition system completes or cancels the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionend_event). |
| `onCompositionStart` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a text composition system starts a new text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event). |
| `onCompositionUpdate` | `CompositionEventHandler<HTMLInputElement>` | - | Handler that is called when a new character is received in the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event). |
| `onCopy` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user copies text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncopy). |
| `onCut` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user cuts text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncut). |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onInput` | `FormEventHandler<HTMLInputElement>` | - | Handler that is called when the input value is modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPaste` | `ClipboardEventHandler<HTMLInputElement>` | - | Handler that is called when the user pastes text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/onpaste). |
| `onSelect` | `ReactEventHandler<HTMLInputElement>` | - | Handler that is called when text in the input is selected. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event). |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-activedescendant` | `string` | - | Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application. |
| `aria-autocomplete` | `"list" \| "none" \| "inline" \| "both"` | - | Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made. |
| `aria-controls` | `string` | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |
| `aria-haspopup` | `boolean \| "false" \| "true" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` | - | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--form-control--label-to-control-spacing` | `0.25rem` |
| `--form-control--control-to-info-spacing` | `0.25rem` |
| `--form-control--spacing-x` | `0.5rem` |
| `--form-control--spacing-y` | `0.25rem` |
| `--form-control--padding-x` | `16px` |
| `--form-control--padding-y` | `8px` |
| `--form-control--corner-radius` | `8px` |
| `--form-control--border-width` | `1px` |
| `--form-control--border-style` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--form-control--placeholder-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--placeholder-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--border-color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--border-color--invalid` | `#E1244C` | `#F2A2B3` |
| `--form-control--border-color--focused` | `#0054F5` | `#85AFFF` |
| `--form-control--border-color--selected` | `#5E6C7A` | `#DCE9F7` |
| `--form-control--background-color--default` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--form-control--background-color--focused` | `#F4F8FC` | `#292F37` |
| `--form-control--background-color--invalid` | `#FDF0F3` | `#540B1B` |
| `--form-control--background-color--selected` | `#DCE9F7` | `#5E6C7A` |
| `--form-control--content-color--default` | `#1B1F24` | `#FFFFFF` |
| `--form-control--content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--form-control--content-color--selected` | `#1B1F24` | `#FFFFFF` |

---

# TimeField

Mit dem TimeField können User eine konkrete Uhrzeit angeben.

> **mStudio-Extensions:** Importiere `TimeField` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  Label,
  TimeField,
} from "@mittwald/flow-react-components";

<TimeField>
  <Label>Uhrzeit</Label>
</TimeField>
```

---

# Best Practices

- Verwende ein verständliches [Label](https://flow.mittwald.de/components/content/label) wie „Uhrzeit".
- Wähle ein Zeitformat passend zum vertrauten Format des Users und zum Kontext.
- Wähle sinnvolle Defaultwerte.
- Schränke Eingaben bei Bedarf mit `minValue` und `maxValue` ein. So lässt du
  zum Beispiel nur Zeiten zwischen 8 und 16 Uhr zu.
- Wähle die Genauigkeit über das `granularity` Property passend zur Nutzung. Für
  Erinnerungen genügen Stunden und Minuten, Sekunden wären unnötig.

---

# Min- und Max-Values

Die wählbare Uhrzeit lässt sich über `minValue` und `maxValue` begrenzen.

```tsx
import {
  FieldDescription,
  Label,
  TimeField,
} from "@mittwald/flow-react-components";
import { Time } from "@internationalized/date";

<TimeField
  minValue={new Time(8, 0)}
  maxValue={new Time(16, 0)}
>
  <Label>Uhrzeit</Label>
  <FieldDescription>Zwischen 8 und 16 Uhr</FieldDescription>
</TimeField>
```

---

# Granularity

Mit der `granularity` Property wird definiert, ob Stunden, Minuten und/oder
Sekunden auswählbar sind.

```tsx
import {
  ColumnLayout,
  Label,
  TimeField,
} from "@mittwald/flow-react-components";

<ColumnLayout>
  <TimeField granularity="hour">
    <Label>Stunde</Label>
  </TimeField>
  <TimeField>
    <Label>Stunde und Minute</Label>
  </TimeField>
  <TimeField granularity="second">
    <Label>Stunde, Minute und Sekunde</Label>
  </TimeField>
</ColumnLayout>
```

---

# Disabled

Achte bei der Verwendung von **Disabled** darauf, dass aus dem Kontext klar
wird, warum der User gerade nicht mit dem TimeField interagieren kann.

```tsx
import {
  Label,
  TimeField,
} from "@mittwald/flow-react-components";

<TimeField isDisabled>
  <Label>Datum</Label>
</TimeField>
```

---

# Kombiniere mit ...

## ContextualHelp

Benutze das [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help), wenn
zusätzliche Informationen bereitgestellt werden sollen, die zu umfangreich für
die FieldDescription sind.

```tsx
import {
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  Label,
  TimeField,
  Text,
} from "@mittwald/flow-react-components";

<TimeField>
  <Label>
    Uhrzeit
    <ContextualHelpTrigger subject="Uhrzeit">
      <Button />
      <ContextualHelp>
        <Text>
          Hier gibt es weitere Informationen, die zu lang
          für die FieldDescription sind.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Label>
</TimeField>
```

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Label,
  Section,
  TimeField,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";
import type { CalendarDateTime } from "@internationalized/date";

export default () => {
  const form = useForm<{ time: CalendarDateTime }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="time"
          rules={{
            required: "Bitte gib eine Uhrzeit ein",
          }}
        >
          <TimeField>
            <Label>Uhrzeit</Label>
          </TimeField>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<DateFieldRenderProps>` | `'react-aria-TimeField'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultValue` | `TimeValue` | - | The default value (uncontrolled). |
| `dir` | `string` | - | - |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `granularity` | `"hour" \| "minute" \| "second"` | `'minute'` | Determines the smallest unit that is displayed in the time picker. |
| `hidden` | `boolean` | - | - |
| `hideTimeZone` | `boolean` | - | Whether to hide the time zone abbreviation. |
| `hourCycle` | `12 \| 24` | - | Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale. |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `lang` | `string` | - | - |
| `maxValue` | `TimeValue` | - | The maximum allowed time that a user may select. |
| `minValue` | `TimeValue` | - | The minimum allowed time that a user may select. |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `placeholderValue` | `TimeValue` | - | A placeholder time that influences the format of the placeholder shown when no value is selected. Defaults to 12:00 AM or 00:00 depending on the hour cycle. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `shouldForceLeadingZeros` | `boolean` | - | Whether to always show leading zeros in the hour field. By default, this is determined by the user's locale. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `validate` | `((value: TimeValue) => true \| ValidationError \| null)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `value` | `TimeValue` | - | The current value (controlled). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onChange` | `((value: TimeValue \| null) => void)` | - | Handler that is called when the value changes. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--time-field--date-segment-corner-radius` | `8px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--time-field--date-segment-background-color--focused` | `#E0EBFF` | `#002A7B` |

---

# List

Die List stellt mehrere List-Items dar und bietet Sortierung, Filter und Suche.

> **mStudio-Extensions:** Importiere `List` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  ActionGroup,
  AlertBadge,
  Avatar,
  Button,
  ContextMenu,
  Heading,
  IconDomain,
  IconSubdomain,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={4}
      aria-label="Domains"
      defaultViewMode="list"
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData data={domains} />
      <ActionGroup>
        <Button>Anlegen</Button>
      </ActionGroup>
      <DomainList.Search />
      <DomainList.Filter
        property="type"
        mode="some"
        name="Typ"
      />
      <DomainList.Sorting
        property="hostname"
        name="Alphabetisch"
        direction="asc"
        directionName="aufsteigend"
        defaultEnabled
      />
      <DomainList.Sorting
        property="hostname"
        name="Alphabetisch"
        direction="desc"
        directionName="absteigend"
      />
      <DomainList.Table>
        <DomainList.TableHeader>
          <DomainList.TableColumn>
            Name
          </DomainList.TableColumn>
          <DomainList.TableColumn>
            Type
          </DomainList.TableColumn>
          <DomainList.TableColumn>
            TLD
          </DomainList.TableColumn>
          <DomainList.TableColumn>
            Hostname
          </DomainList.TableColumn>
        </DomainList.TableHeader>

        <DomainList.TableBody>
          <DomainList.TableRow>
            <DomainList.TableCell>
              {(domain) => domain.domain}
            </DomainList.TableCell>
            <DomainList.TableCell>
              {(domain) => domain.type}
            </DomainList.TableCell>
            <DomainList.TableCell>
              {(domain) => domain.tld}
            </DomainList.TableCell>
            <DomainList.TableCell>
              {(domain) => domain.hostname}
            </DomainList.TableCell>
          </DomainList.TableRow>
        </DomainList.TableBody>
      </DomainList.Table>
      <DomainList.Item
        textValue={(domain) => domain.domain}
        showTiles
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar
              color={
                domain.type === "Domain" ? "blue" : "teal"
              }
            >
              {domain.type === "Domain" ? (
                <IconDomain />
              ) : (
                <IconSubdomain />
              )}
            </Avatar>
            <Heading>
              {domain.hostname}
              {!domain.verified && (
                <AlertBadge status="warning">
                  Unverifiziert
                </AlertBadge>
              )}
            </Heading>
            <Text>{domain.type}</Text>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
              <MenuItem>Löschen</MenuItem>
            </ContextMenu>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

---

# Best Practices

- Biete eine passende Ansicht an. Eine Rasteransicht eignet sich, wenn das Bild
  eines List-Items den Userflow bestimmt; bei mehreren Anwendungsfällen kann der
  User zwischen Ansichten wechseln.
- Wähle eine Standardsortierung nach dem häufigsten Anwendungsfall. Ein Beispiel
  ist „Neueste zuerst“ bei einer Änderungshistorie; biete nur Sortieroptionen
  mit echtem Mehrwert.
- Setze bei umfangreichen Lists Filter ein und gruppiere die Kategorien
  sinnvoll. Sinnvolle Gruppen sind zum Beispiel Typ, Größe oder Status.
- Platziere weiteren Seiteninhalt oberhalb der List. So verursacht das Nachladen
  über den „Mehr anzeigen“-Button keine Layout-Verschiebungen; die List nimmt
  die volle Breite des Contents einer
  [LayoutCard](https://flow.mittwald.de/components/structure/layout-card) ein.
- Beschreibe die List zugänglich. Ist sie der einzige Hauptinhalt einer Seite,
  erhält sie ein `aria-label`; hat sie eine eigene
  [Heading](https://flow.mittwald.de/components/content/heading), wird diese über `aria-labelledby`
  zugeordnet.
- Gib jedem Item über `textValue` seinen Text mit. Erst damit findet der User
  ein Item über die Tastatur, indem er dessen Anfang tippt.

---

# Ansichten

Die List unterstützt drei Ansichten: **Liste**, **Raster** und **Tabelle**. Die
Default-Ansicht legst du über das Property `defaultViewMode` fest; sind mehrere
Ansichten verfügbar, wechselt der User über den Ansichts-Button zwischen ihnen.

Jedes Element renderst du über `List.Item`. Den Inhalt gestaltest du frei mit
einer eigenen View – oder du nutzt die vorgefertigte Layout-Lösung
[List.ItemView](https://flow.mittwald.de/components/list/list-item-view), die Avatar, Titel, Content und
Aktionen einheitlich anordnet.

## Listenansicht

Besonders geeignet, wenn viele Elemente übersichtlich, platzsparend und
ansprechend dargestellt werden sollen. Nutze `<List.Item />`, um die List in der
Listenansicht darzustellen.

```tsx
import {
  AlertBadge,
  Avatar,
  ContextMenu,
  Heading,
  IconDomain,
  IconSubdomain,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={4}
      aria-label="Domains"
      hidePagination
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData data={domains} />

      <DomainList.Item
        textValue={(domain) => domain.domain}
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar
              color={
                domain.type === "Domain" ? "blue" : "teal"
              }
            >
              {domain.type === "Domain" ? (
                <IconDomain />
              ) : (
                <IconSubdomain />
              )}
            </Avatar>
            <Heading>
              {domain.hostname}
              {!domain.verified && (
                <AlertBadge status="warning">
                  Unverifiziert
                </AlertBadge>
              )}
            </Heading>
            <Text>{domain.type}</Text>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
              <MenuItem>Löschen</MenuItem>
            </ContextMenu>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

## Rasteransicht

Sinnvoll, wenn die Anzahl der Elemente überschaubar ist oder die visuelle
Darstellung im Vordergrund steht – das `List.Item` sollte hier nur wenige
Informationen enthalten. Für die Rasteransicht wird ebenfalls das
`<List.Item />` verwendet: Aktiviere sie über `showTiles` und deaktiviere die
Listenansicht bei Bedarf mit `showList={false}`. Über `maxTileWidth` steuerst du
die maximale Breite der Kacheln.

```tsx
import {
  AlertBadge,
  Avatar,
  ContextMenu,
  Heading,
  IconDomain,
  IconSubdomain,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={4}
      aria-label="Domains"
      hidePagination
      defaultViewMode="tiles"
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData data={domains} />
      <DomainList.Item
        textValue={(domain) => domain.domain}
        showTiles
        showList={false}
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar
              color={
                domain.type === "Domain" ? "blue" : "teal"
              }
            >
              {domain.type === "Domain" ? (
                <IconDomain />
              ) : (
                <IconSubdomain />
              )}
            </Avatar>
            <Heading>
              {domain.hostname}
              {!domain.verified && (
                <AlertBadge status="warning">
                  Unverifiziert
                </AlertBadge>
              )}
            </Heading>
            <Text>{domain.type}</Text>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
              <MenuItem>Löschen</MenuItem>
            </ContextMenu>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

## Tabellenansicht

Ideal für Daten, die schnell erfassbar sein müssen, während die optische
Gestaltung zweitrangig ist. Nutze `<List.Table />`, um die List als
[Table](https://flow.mittwald.de/components/structure/table) darzustellen – dabei gelten die Guidelines
der Table.

```tsx
import { typedList } from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={4}
      defaultViewMode="table"
      aria-label="Domains"
      hidePagination
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData data={domains} />
      <DomainList.Table>
        <DomainList.TableHeader>
          <DomainList.TableColumn>
            Name
          </DomainList.TableColumn>
          <DomainList.TableColumn>
            Type
          </DomainList.TableColumn>
          <DomainList.TableColumn>
            TLD
          </DomainList.TableColumn>
          <DomainList.TableColumn>
            Hostname
          </DomainList.TableColumn>
        </DomainList.TableHeader>

        <DomainList.TableBody>
          <DomainList.TableRow>
            <DomainList.TableCell>
              {(domain) => domain.domain}
            </DomainList.TableCell>
            <DomainList.TableCell>
              {(domain) => domain.type}
            </DomainList.TableCell>
            <DomainList.TableCell>
              {(domain) => domain.tld}
            </DomainList.TableCell>
            <DomainList.TableCell>
              {(domain) => domain.hostname}
            </DomainList.TableCell>
          </DomainList.TableRow>
        </DomainList.TableBody>
      </DomainList.Table>
    </DomainList.List>
  );
}
```

---

# Sortierung

Ist die Standardsortierung aktiv, zeigt der Sortierungs-Button nur „Sortierung“
an; wählt der User eine Option, wird der Button-Text entsprechend angepasst.
Lege eine Sortiermethode über `<List.Sorting />` an; mit `customSortingFn` und
einem vorangestellten `$` im `property` definierst du eine eigene Sortierung.

Benenne die Sortierung so, dass Kriterium und Reihenfolge sofort ersichtlich
sind.

**✅ Do**

Benenne die Sortierung so, dass eindeutig ersichtlich ist, wonach und in
welcher Reihenfolge sortiert wird.

```tsx
import {
  type Domain,
  domains,
} from "@/content/components/list/list/examples/domainApi";
import {
  AlertBadge,
  Avatar,
  ContextMenu,
  Heading,
  IconDomain,
  IconSubdomain,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={2}
      aria-label="Domains"
      getItemId={(domain) => domain.id}
      hidePagination
    >
      <DomainList.StaticData data={domains} />
      <DomainList.Sorting
        property="hostname"
        name="Alphabetisch"
        direction="asc"
        directionName="aufsteigend"
        defaultEnabled
      />
      <DomainList.Sorting
        property="hostname"
        name="Alphabetisch"
        direction="desc"
        directionName="absteigend"
      />
      <DomainList.Item
        textValue={(domain) => domain.domain}
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar
              color={
                domain.type === "Domain" ? "blue" : "teal"
              }
            >
              {domain.type === "Domain" ? (
                <IconDomain />
              ) : (
                <IconSubdomain />
              )}
            </Avatar>
            <Heading>
              {domain.hostname}
              {!domain.verified && (
                <AlertBadge status="warning">
                  Unverifiziert
                </AlertBadge>
              )}
            </Heading>
            <Text>{domain.type}</Text>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
              <MenuItem>Löschen</MenuItem>
            </ContextMenu>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

**⛔️ Don't**

Verzichte auf Sortierformulierungen, die nicht eindeutig verständlich sind
oder keine klare Reihenfolge vermitteln.

```tsx
import {
  AlertBadge,
  Avatar,
  ContextMenu,
  Heading,
  IconDomain,
  IconSubdomain,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={2}
      aria-label="Domains"
      getItemId={(domain) => domain.id}
      hidePagination
    >
      <DomainList.StaticData data={domains} />
      <DomainList.Sorting
        property="domain"
        name="Name"
        defaultEnabled
      />
      <DomainList.Item
        textValue={(domain) => domain.domain}
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar
              color={
                domain.type === "Domain" ? "blue" : "teal"
              }
            >
              {domain.type === "Domain" ? (
                <IconDomain />
              ) : (
                <IconSubdomain />
              )}
            </Avatar>
            <Heading>
              {domain.hostname}
              {!domain.verified && (
                <AlertBadge status="warning">
                  Unverifiziert
                </AlertBadge>
              )}
            </Heading>
            <Text>{domain.type}</Text>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
              <MenuItem>Löschen</MenuItem>
            </ContextMenu>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

## Sorting Properties

| Property          | Typ                   | Beschreibung                                                                                                                          |
| ----------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `customSortingFn` | `SortingFn<T>`        | Möglichkeit, eine eigene Sortierfunktion zu definieren                                                                                |
| `defaultEnabled`  | `boolean \| "hidden"` | Bestimmt, ob die Sortierung als Default gesetzt wird; bei "hidden" ist die Option nicht sichtbar, wird aber im Hintergrund angewendet |
| `direction`       | `"asc" \| "desc"`     | Auf- oder absteigende Sortierung                                                                                                      |
| `name`            | `string`              | Der Anzeigename der Sortier-Option                                                                                                    |
| `directionName`   | `string`              | Der Anzeigename der Sortierrichtung                                                                                                   |
| `property`        | `string`              | Das für die Sortierung verwendete Property                                                                                            |

---

# Filter

Ein Klick auf den Filter-Button öffnet ein
[ContextMenu](https://flow.mittwald.de/components/actions/context-menu), in dem Filter aktiviert oder
deaktiviert werden können.

- Standardmäßig erlaubt ein Filter die **Mehrfachauswahl**, damit User nach
  mehreren Kriterien filtern können; die Optionen erscheinen dann als
  [Checkbox](https://flow.mittwald.de/components/form-controls/checkbox). Bei **Einzelauswahl** werden
  sie als [RadioGroup](https://flow.mittwald.de/components/form-controls/radio-group) dargestellt.
- Hat ein Filter mit `mode="some"` **mindestens 6 Optionen**, erscheint oben
  automatisch die Option „Alle auswählen“. Damit wählen User alle Optionen auf
  einmal aus und können danach gezielt einzelne abwählen. Sind alle Optionen
  gewählt, wird daraus „Alle abwählen“; sind nur einige gewählt, zeigt die
  Checkbox einen Zwischenzustand.
- Jeder **aktive Filter** wird durch eine [Badge](https://flow.mittwald.de/components/status/badge)
  visualisiert, die per Klick entfernt werden kann. Sind mindestens zwei Filter
  aktiv, erscheint zusätzlich ein „Filter zurücksetzen“-Button.
- Mehrere Filter **derselben Kategorie** (z. B. Status, Art, Größe) werden in
  einem eigenen, passend benannten Filter-Button zusammengefasst. Filter ohne
  Kategorie gruppierst du unter einem allgemeinen „Filter“-Button.

Lege Filter über `<List.Filter />` an. Über `priority` bestimmst du, ob ein
Filter immer sichtbar ist (`primary`) oder erst im „Alle Filter“-Modal erscheint
(`secondary`); „Alle Filter“ wird automatisch angezeigt, sobald es secondary
Filter gibt. Die Anzeige des Filter-Werts lässt sich über eine Funktion anpassen
(z. B. für Übersetzungen), und mit einem eigenen `matcher` plus vorangestelltem
`$` im `property` filterst du nach Werten, die nicht in der List vorkommen.

```tsx
import {
  ActionGroup,
  AlertBadge,
  Avatar,
  Button,
  ContextMenu,
  Heading,
  IconDomain,
  IconSubdomain,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={4}
      aria-label="Domains"
      defaultViewMode="list"
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData data={domains} />
      <ActionGroup>
        <Button>Anlegen</Button>
      </ActionGroup>
      <DomainList.Search />
      <DomainList.Filter
        property="type"
        mode="some"
        name="Typ"
      />
      <DomainList.Filter
        property="tld"
        mode="some"
        name="TLD"
        priority="secondary"
      />
      <DomainList.Sorting
        property="hostname"
        name="Alphabetisch"
        direction="asc"
        defaultEnabled
        directionName="aufsteigend"
      />
      <DomainList.Sorting
        property="hostname"
        name="Alphabetisch"
        direction="desc"
        directionName="absteigend"
      />
      <DomainList.Table>
        <DomainList.TableHeader>
          <DomainList.TableColumn>
            Name
          </DomainList.TableColumn>
          <DomainList.TableColumn>
            Type
          </DomainList.TableColumn>
          <DomainList.TableColumn>
            TLD
          </DomainList.TableColumn>
          <DomainList.TableColumn>
            Hostname
          </DomainList.TableColumn>
        </DomainList.TableHeader>

        <DomainList.TableBody>
          <DomainList.TableRow>
            <DomainList.TableCell>
              {(domain) => domain.domain}
            </DomainList.TableCell>
            <DomainList.TableCell>
              {(domain) => domain.type}
            </DomainList.TableCell>
            <DomainList.TableCell>
              {(domain) => domain.tld}
            </DomainList.TableCell>
            <DomainList.TableCell>
              {(domain) => domain.hostname}
            </DomainList.TableCell>
          </DomainList.TableRow>
        </DomainList.TableBody>
      </DomainList.Table>
      <DomainList.Item
        textValue={(domain) => domain.domain}
        showTiles
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar
              color={
                domain.type === "Domain" ? "blue" : "teal"
              }
            >
              {domain.type === "Domain" ? (
                <IconDomain />
              ) : (
                <IconSubdomain />
              )}
            </Avatar>
            <Heading>
              {domain.hostname}
              {!domain.verified && (
                <AlertBadge status="warning">
                  Unverifiziert
                </AlertBadge>
              )}
            </Heading>
            <Text>{domain.type}</Text>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
              <MenuItem>Löschen</MenuItem>
            </ContextMenu>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

Aktive Filter-Badges sollten selbsterklärend sein. Bei mehrdeutigen Begriffen
gib zusätzlichen Kontext an.

**✅ Do**

Intuitiv verständliche Filter benötigen keinen zusätzlichen Kontext.
Erklärungsbedürftige Filter sollten mit weiterem Text versehen werden.

```tsx
import {
  AlertBadge,
  Avatar,
  ContextMenu,
  Heading,
  IconDomain,
  IconSubdomain,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={5}
      aria-label="Domains"
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData data={domains} />
      <DomainList.Filter
        property="type"
        mode="some"
        name="Typ"
        values={["Domain", "Subdomain"]}
        defaultSelected={["Domain"]}
      />
      <DomainList.Filter
        property="verified"
        mode="some"
        name="Verifizierung"
        matcher={(filterValue, propertyValue) =>
          filterValue === "Verifiziert"
            ? propertyValue
            : !propertyValue
        }
        defaultSelected={["Unverifiziert"]}
        values={["Verifiziert", "Unverifiziert"]}
      />
      <DomainList.Item
        textValue={(domain) => domain.domain}
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar
              color={
                domain.type === "Domain" ? "blue" : "teal"
              }
            >
              {domain.type === "Domain" ? (
                <IconDomain />
              ) : (
                <IconSubdomain />
              )}
            </Avatar>
            <Heading>
              {domain.hostname}
              {!domain.verified && (
                <AlertBadge status="warning">
                  Unverifiziert
                </AlertBadge>
              )}
            </Heading>
            <Text>{domain.type}</Text>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
              <MenuItem>Löschen</MenuItem>
            </ContextMenu>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

**⛔️ Don't**

Bei intuitiven Filtern sollte auf zusätzlichen Text verzichtet werden. Meist
genügt ein einzelnes beschreibendes Wort.

```tsx
import {
  AlertBadge,
  Avatar,
  ContextMenu,
  Heading,
  IconDomain,
  IconSubdomain,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={5}
      aria-label="Domains"
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData data={domains} />
      <DomainList.Filter
        property="type"
        mode="some"
        name="Typ"
        matcher={(filterValue, propertyValue) =>
          filterValue === "Type Domain"
            ? propertyValue === "Domain"
            : propertyValue === "Subdomain"
        }
        values={["Type Domain", "Type Subdomain"]}
        defaultSelected={["Type Domain"]}
      />
      <DomainList.Filter
        property="verified"
        mode="some"
        name="Verifizierung"
        matcher={(filterValue, propertyValue) =>
          filterValue === "Verifizierung Verifiziert"
            ? propertyValue
            : !propertyValue
        }
        defaultSelected={["Verifizierung Unverifiziert"]}
        values={[
          "Verifizierung Verifiziert",
          "Verifizierung Unverifiziert",
        ]}
      />
      <DomainList.Item
        textValue={(domain) => domain.domain}
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar
              color={
                domain.type === "Domain" ? "blue" : "teal"
              }
            >
              {domain.type === "Domain" ? (
                <IconDomain />
              ) : (
                <IconSubdomain />
              )}
            </Avatar>
            <Heading>
              {domain.hostname}
              {!domain.verified && (
                <AlertBadge status="warning">
                  Unverifiziert
                </AlertBadge>
              )}
            </Heading>
            <Text>{domain.type}</Text>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
              <MenuItem>Löschen</MenuItem>
            </ContextMenu>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

## Date Range Filter

Mit `mode="dateRange"` definierst du einen Filter, der die Auswahl eines
Zeitraums ermöglicht. So lassen sich Einträge gezielt zwischen einem Start- und
Enddatum eingrenzen.

```tsx
import { typedList } from "@mittwald/flow-react-components";
import {
  type CalendarDate,
  getLocalTimeZone,
  today,
} from "@internationalized/date";

export default () => {
  const InvoiceList = typedList<{
    id: string;
    date: CalendarDate;
  }>();

  return (
    <InvoiceList.List
      aria-label="Rechnungen"
      defaultViewMode="table"
      getItemId={(domain) => domain.id}
    >
      <InvoiceList.StaticData
        data={[
          {
            id: "RG100000",
            date: today(getLocalTimeZone()),
          },
          {
            id: "RG100001",
            date: today(getLocalTimeZone()).subtract({
              days: 7,
            }),
          },
          {
            id: "RG100002",
            date: today(getLocalTimeZone()).subtract({
              days: 14,
            }),
          },
        ]}
      />
      <InvoiceList.Filter
        property="date"
        mode="dateRange"
        name="Datum"
        dateRangeOptions={{
          maxValue: today(getLocalTimeZone()),
        }}
      />
      <InvoiceList.Table>
        <InvoiceList.TableHeader>
          <InvoiceList.TableColumn>
            Rechnung
          </InvoiceList.TableColumn>
          <InvoiceList.TableColumn>
            Datum
          </InvoiceList.TableColumn>
        </InvoiceList.TableHeader>

        <InvoiceList.TableBody>
          <InvoiceList.TableRow>
            <InvoiceList.TableCell>
              {(invoice) => invoice.id}
            </InvoiceList.TableCell>
            <InvoiceList.TableCell>
              {(invoice) =>
                `${invoice.date.day}.${invoice.date.month}.${invoice.date.year}`
              }
            </InvoiceList.TableCell>
          </InvoiceList.TableRow>
        </InvoiceList.TableBody>
      </InvoiceList.Table>
    </InvoiceList.List>
  );
}
```

## Filter Properties

| Property          | Typ                               | Beschreibung                                                                |
| ----------------- | --------------------------------- | --------------------------------------------------------------------------- |
| `defaultSelected` | `string[]`                        | Array der als Default gesetzten Filter                                      |
| `matcher`         | `FilterMatcher<T, TProp, string>` | Definiert eine eigene Filterlogik für die Listenelemente                    |
| `mode`            | `"all" \| "some" \| "one"`        | Bestimmt, wie mehrere ausgewählte Filterwerte miteinander kombiniert werden |
| `name`            | `string`                          | Der Anzeigename des Filters                                                 |
| `property`        | `string`                          | Das für die Filterung verwendete Property                                   |
| `values`          | `string[]`                        | Die Optionen für den Filter                                                 |

---

# Suche

Verwende `<List.Search />` innerhalb der List, um ein
[SearchField](https://flow.mittwald.de/components/form-controls/search-field) anzuzeigen. Standardmäßig
startet die Suche automatisch; soll sie erst auf Enter auslösen, setze
`autoSubmit` auf `false`. Öffnet sich die List in einem
[Modal](https://flow.mittwald.de/components/overlays/modal), fokussiere das Suchfeld über `autoFocus`,
damit der User direkt tippen kann.

---

# Pagination

Standardmäßig zeigt die List maximal 10 List-Items; weitere lädt der User über
den „Mehr anzeigen“-Button nach. Über `batchSize` änderst du die Anzahl, über
`hidePagination` schaltest du die Pagination ab. Halte die Zahl niedrig: Über
Suche, Filter und Sortierung findet der User gezielt, und viele gleichzeitig
geladene Einträge kosten Performance.

## Infinite Scroll

Für sehr lange Listen, in denen ohne konkretes Suchziel gestöbert wird, kann
statt des „Mehr anzeigen“-Buttons **Infinite Scroll** aktiviert werden: Die
nächste Seite lädt automatisch, sobald das Ende der Liste in den sichtbaren
Bereich scrollt.

```tsx
<List.List infiniteScroll batchSize={20} aria-label="Domains">
  {/* ... */}
</List.List>
```

- Infinite Scroll ist **opt-in** und sollte nicht der Default sein. Für kurze
  oder gezielt durchsuchte Listen ist der „Mehr anzeigen“-Button meist die
  bessere Wahl.
- Der Mechanismus funktioniert unabhängig davon, ob die Daten statisch,
  asynchron oder über Hooks geladen werden, und respektiert `manualPagination`.
- Er gilt für alle View Modes — Liste, Raster und Tabelle.
- Während des Nachladens wird ein Ladeindikator am Ende der Liste angezeigt.

---

# Lade- und Leeransichten

## Loading View

Während die Daten initial geladen werden, zeigt die List eine Loading View aus
Skeleton-Platzhaltern an. Ohne weitere Angabe wird ein generisches Skeleton
verwendet. Über das `loadingView`-Property eines `<List.Item />` – oder eines
`<TableCell />` in der Tabellenansicht – lässt sich diese Ansicht anpassen. Sie
gilt in allen Ansichten (List, Tiles, Table) und auch für einzelne Items, die
nach dem initialen Laden noch suspenden – etwa weil ihr Inhalt eigene Daten
nachlädt. Gestalte sie mit [Skeleton](https://flow.mittwald.de/components/content/skeleton) und
[SkeletonText](https://flow.mittwald.de/components/content/skeleton-text) so, dass sie dem Inhalt in
Aufbau und Größe nahekommt, damit der Übergang ohne Layout-Sprung wirkt.

```tsx
import {
  Avatar,
  Heading,
  IconDomain,
  Skeleton,
  SkeletonText,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list/examples/domainApi";

export default () => {
  const List = typedList<Domain>();

  return (
    <List.List aria-label="Domains">
      {/* The loader waits a moment before resolving, so the loading view is
          briefly visible before the data appears. */}
      <List.LoaderAsync>
        {() =>
          new Promise<{ data: Domain[] }>((resolve) => {
            setTimeout(
              () => resolve({ data: domains.slice(0, 3) }),
              2000,
            );
          })
        }
      </List.LoaderAsync>
      <List.Item
        textValue={(domain) => domain.hostname}
        loadingView={
          <List.ItemView>
            <Avatar>
              <Skeleton />
            </Avatar>
            <Heading>
              <SkeletonText width="12em" />
            </Heading>
            <SkeletonText width="6em" />
          </List.ItemView>
        }
      >
        {(domain) => (
          <List.ItemView>
            <Avatar>
              <IconDomain />
            </Avatar>
            <Heading>{domain.hostname}</Heading>
            <Text>{domain.type}</Text>
          </List.ItemView>
        )}
      </List.Item>
    </List.List>
  );
}
```

## Empty View

Über `emptyView` zeigst du eine eigene Ansicht an, wenn die List keine Einträge
enthält – in der Regel eine
[IllustratedMessage](https://flow.mittwald.de/components/content/illustrated-message), die den User über
einen [Button](https://flow.mittwald.de/components/actions/button) einlädt, das erste Element zu
erstellen. Liefert eine Suche oder ein Filter kein Ergebnis, zeigt
`emptySearchResultView` einen entsprechenden Hinweis. Ist das jeweilige Property
nicht gesetzt, verwendet die List eine vordefinierte Ansicht.

```tsx
import {
  Heading,
  IconDomain,
  IllustratedMessage,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import { type Domain } from "@/content/components/list/list/examples/domainApi";

export default () => {
  const List = typedList<Domain>();

  const emptyView = (
    <IllustratedMessage>
      <IconDomain />
      <Heading>Keine Domains gefunden</Heading>
      <Text>Füge neue Domains hinzu, um zu starten.</Text>
    </IllustratedMessage>
  );

  return (
    <List.List aria-label="Domains" emptyView={emptyView}>
      <List.StaticData data={[]} />
      <List.Item>{() => null}</List.Item>
    </List.List>
  );
}
```

## Initiale Suspense-Boundary

Beim initialen Laden umschließt die List das Laden der Daten standardmäßig mit
einer eigenen [Suspense](https://react.dev/reference/react/Suspense)-Boundary
und zeigt währenddessen ihre Loading View. Über `disableInitialSuspenseBoundary`
an der Datenquelle (`<List.LoaderAsync />`, `<List.LoaderAsyncResource />`,
`<List.LoaderHooks />`) steuerst du dieses Verhalten:

| Wert              | Verhalten                                                                                                                                                                                    |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `false` (Default) | Die List rendert beim initialen Laden ihre eigene Loading View (Skeleton).                                                                                                                   |
| `true`            | Die List rendert beim initialen Laden keine eigene Suspense-Boundary. Das Suspending wird an die nächste übergeordnete Boundary weitergereicht; die List erscheint erst mit geladenen Daten. |

Belasse den Wert bei `false`, wenn die List den Hauptinhalt darstellt oder keine
übergeordnete Ladeanzeige existiert. Setze ihn auf `true`, wenn die List in eine
Seite eingebettet ist, die bereits einen eigenen Ladezustand anzeigt – so wird
die List atomar dargestellt und der Layout-Shift zwischen Loading und Empty View
vermieden. Zeigt deine Anwendung durchgängig eigene Ladezustände, kannst du
`true` über den `<ComponentDefaultsProvider />` als Standard festlegen.

---

# Item-Inhalte und externer State

Ein Item wird neu gerendert, wenn sich seine Daten ändern oder wenn eine der
Render-Funktionen an seinem `<List.Item />` ihre Identität wechselt. Eine inline
im JSX geschriebene Funktion tut das bei jedem Render ihrer Elternkomponente –
State aus der umgebenden Komponente erreicht das Item damit von allein.

Hat die Render-Funktion eine stabile Identität – aus der Komponente
herausgezogen, in `useCallback` gewrappt, oder sie liest aus einem externen
Store –, fehlt dem Item dieses Signal und es behält die Werte, mit denen es
zuerst gerendert wurde. Liste dann über `dependencies` auf, was die Funktion
liest:

```tsx
<List.Item textValue={itemTextValue} dependencies={[selected]}>
  {renderItem}
</List.Item>
```

---

# Daten laden

Die List kann ihre Daten statisch oder asynchron laden.

## Statische Daten

Für statische Daten wird `<List.StaticData />` verwendet. Diese Variante
benötigt keine zusätzliche Logik für Nachladen oder Filtern.

```tsx
<List.StaticData data={dataArray} />
```

## Asynchrone Daten

Mit `<List.LoaderAsync />` werden Daten dynamisch aus einer API oder anderen
asynchronen Quellen nachgeladen.

```tsx
<List.LoaderAsync>
  {async (options) => {
    const response = await fetchDataFromAPI(options);
    return {
      data: response.items,
      itemTotalCount: response.totalCount,
    };
  }}
</List.LoaderAsync>
```

Die Loader-Funktion erhält ein `options`-Objekt und muss `data` sowie – für die
Pagination – `itemTotalCount` zurückgeben.

| Property       | Typ                                                                    | Beschreibung                                                                                             |
| -------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `filtering`    | `{ [key: string]: { mode: "all" \| "some" \| "one"; values: any[] } }` | Enthält Filter für die Daten. Jedes Key-Value-Paar repräsentiert eine Filterbedingung für ein Datenfeld. |
| `searchString` | `string`                                                               | Der eingegebene Suchbegriff.                                                                             |
| `pagination`   | `{ offset: number; limit: number }`                                    | Enthält Offset (Startpunkt) und Limit (maximale Anzahl an Datensätzen).                                  |
| `sorting`      | `{ [key: string]: "asc" \| "desc" }`                                   | Gibt an, nach welchen Datenfeldern sortiert werden soll.                                                 |

## Laden über Hooks

Mit `<List.LoaderHooks />` werden Daten über React Hooks (z. B. TanStack Query
oder SWR) nachgeladen. Der Einsatz von Suspense ist hierbei erforderlich.

```tsx
import { useSuspenseQuery } from "@tanstack/react-query";

<List.LoaderHooks>
  {(options) => {
    const response = useSuspenseQuery({
      queryKey: ["api", options],
      queryFn: () => fetchDataFromAPI(options),
    });
    return {
      data: response.items,
      itemTotalCount: response.totalCount,
    };
  }}
</List.LoaderHooks>;
```

Beim asynchronen Laden lassen sich Pagination (`manualPagination`), Sortierung
(`manualSorting`), Filterung (`manualFiltering`) und Suche serverseitig
verarbeiten.

---

# Kombiniere mit ...

## ActionGroup

Verwende `<ActionGroup />` innerhalb der List, um eine
[ActionGroup](https://flow.mittwald.de/components/actions/action-group) mit Aktionen anzuzeigen, die
sich direkt auf die Liste beziehen.

```tsx
import {
  ActionGroup,
  Avatar,
  Button,
  Heading,
  IconDomain,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={2}
      hidePagination
      aria-label="Domains"
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData data={domains} />
      <ActionGroup>
        <Button>Anlegen</Button>
      </ActionGroup>
      <DomainList.Item
        textValue={(domain) => domain.domain}
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar>
              <IconDomain />
            </Avatar>
            <Heading>{domain.hostname}</Heading>
            <Text>{domain.type}</Text>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

## Summary

Verwende eine `<ListSummary />`, um eine Zusammenfassung anzuzeigen,
beispielsweise die Gesamtsumme der Beträge. Über das `position`-Property legst
du fest, ob die Summary oberhalb oder unterhalb der List erscheint.

```tsx
import {
  Flex,
  Heading,
  ListItemView,
  ListSummary,
  Text,
  typedList,
} from "@mittwald/flow-react-components";

export default () => {
  const InvoiceList = typedList<{
    id: string;
    amount: string;
  }>();

  return (
    <InvoiceList.List
      batchSize={2}
      hidePagination
      aria-label="Rechnungen"
      getItemId={(invoice) => invoice.id}
    >
      <ListSummary position="bottom">
        <Flex justify="end">
          <Text>
            <strong>Gesamt: 37,00 €</strong>
          </Text>
        </Flex>
      </ListSummary>
      <InvoiceList.StaticData
        data={[
          {
            id: "Rechnung 1",
            amount: "25,00 €",
          },
          {
            id: "Rechnung 2",
            amount: "12,00 €",
          },
        ]}
      />

      <InvoiceList.Item textValue={(invoice) => invoice.id}>
        {(invoice) => (
          <ListItemView>
            <Heading>{invoice.id}</Heading>
            <Text>{invoice.amount}</Text>
          </ListItemView>
        )}
      </InvoiceList.Item>
    </InvoiceList.List>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `accordion` | `boolean` | `false` | Makes list items expandable. The expanded content is placed in `<Content slot="bottom" />`. |
| `batchSize` | `number` | - | The number of items to be displayed on one page. |
| `children` | `ReactNode` | - | - |
| `defaultSelectedKeys` | `"all" \| Iterable<Key>` | - | The initial selected keys in the collection (uncontrolled). |
| `defaultViewMode` | `"list" \| "table" \| "tiles"` | `"list"` | The view mode the list starts in. A persisted view mode takes precedence. |
| `disabledKeys` | `Iterable<Key>` | - | The currently disabled keys in the collection (controlled). |
| `disallowEmptySelection` | `boolean` | - | Whether the collection allows empty selection. |
| `emptySearchResultView` | `ReactNode` | - | The view rendered when a search or filter returns no results. |
| `emptyView` | `ReactNode` | - | The view rendered when the list contains no items. |
| `getItemId` | `GetItemId<never>` | - | Derives a stable ID from an items data. Used to deduplicate items across loaded batches and as the row ID in the table view. |
| `hidePagination` | `boolean` | `false` | Hides the pagination controls below the list. |
| `infiniteScroll` | `boolean` | `false` | Automatically loads the next batch of items when the user scrolls to the end of the list, instead of showing a "Show more" button. |
| `loadingItemsCount` | `number` | - | The number of skeleton placeholder items rendered while data is loading. Defaults to the lists batch size. |
| `selectedKeys` | `"all" \| Iterable<Key>` | - | The currently selected keys in the collection (controlled). |
| `selectionBehavior` | `"toggle" \| "replace"` | - | Whether selecting an item replaces the current selection (`"replace"`) or adds to it (`"toggle"`). |
| `selectionMode` | `"multiple" \| "none" \| "single"` | - | The type of selection that is allowed in the collection. |
| `settingStorageKey` | `string` | - | The key the lists settings (view mode, search, filters, sorting) are persisted under. Requires a `<SettingsProvider />` — without a key nothing is persisted. |
| `settingsStorageDefaults` | `ListSettingsDefaults` | - | Defaults for how the lists settings are persisted. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onAction` | `ItemActionFn<never>` | - | Called with the items data when the user activates a list item. |
| `onChange` | `OnListChanged<never, unknown>` | - | Called with the list model whenever its state changes. |
| `onSelectionChange` | `((keys: Selection) => void)` | - | Handler that is called when the selection changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | - | An accessible label for the list. |
| `aria-labelledby` | `string` | - | The ID of the element labelling the list. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--list--spacing` | `8px` |
| `--list--block-to-block-spacing` | `16px` |
| `--list--filter-to-search-spacing` | `32px` |
| `--list-item--corner-radius` | `8px` |
| `--list-item--padding` | `8px` |
| `--list-item--border-width` | `1px` |
| `--list-item--border-style` | `solid` |
| `--list-item--spacing` | `16px` |
| `--list-item--avatar-to-title-spacing` | `8px` |
| `--list-item--subtitle-font-size` | `0.875rem` |
| `--list-item--checkbox-corner-radius` | `4px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--list-item--background-color--default` | `transparent` | `transparent` |
| `--list-item--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--list-item--background-color--pressed` | `#DCE9F7` | `#5E6C7A` |
| `--list-item--border-color` | `#5E6C7A` | `#DCE9F7` |
| `--list-item--checkbox-color` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--list-item--checkbox-background-color` | `rgb(0 0 0 / 50%)` | `rgb(0 0 0 / 50%)` |

---

# ListItemView

List.ItemView ist die vorgefertigte Layout-Lösung für ein List-Item.

> **mStudio-Extensions:** Importiere `ListItemView` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import {
  Avatar,
  Heading,
  IconDomain,
  IconSubdomain,
  ContextMenu,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list-item-view/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={3}
      hidePagination
      aria-label="Domains"
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData data={domains} />
      <DomainList.Item
        textValue={(domain) => domain.domain}
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar
              color={
                domain.type === "Domain" ? "blue" : "teal"
              }
            >
              {domain.type === "Domain" ? (
                <IconDomain />
              ) : (
                <IconSubdomain />
              )}
            </Avatar>
            <Heading>{domain.hostname}</Heading>
            <Text>{domain.type}</Text>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
              <MenuItem>Löschen</MenuItem>
            </ContextMenu>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

`List.ItemView` ist die vorgefertigte Layout-Lösung für ein List-Item und ordnet
Avatar, Titel, Content und Aktionen einheitlich an.

---

# Best Practices

- Halte den Titel kurz und eindeutig. Lange Headings brechen um und erschweren
  das schnelle Scannen der List.
- Zeige nur die Informationen, die zum Verständnis des Elements nötig sind. Zu
  viele Details machen die List unübersichtlich.
- Ergänze im Untertitel weitere Informationen nach dem Muster „Beschreibung – 1.
  Information – 2. Information“.
- Verlagere selten benötigte Details in Top oder Bottom Content oder blende sie
  über [ColumnLayout](https://flow.mittwald.de/components/structure/column-layout) auf kleinen
  Bildschirmen aus.
- Gib jedem List-Item über `textValue` seinen Text mit. Erst damit findet der
  User es über die Tastatur, indem er dessen Anfang tippt.

---

# Als Raster

In der Rasteransicht wird das List-Item kompakter dargestellt: Der Avatar wird
größer und eckig, Top Content sowie die Accordion-Funktion entfallen. Aktiviere
die Darstellung über `showTiles` an `List.Item`.

```tsx
import {
  Avatar,
  ContextMenu,
  Heading,
  IconDomain,
  IconSubdomain,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list-item-view/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={3}
      aria-label="Domains"
      hidePagination
      defaultViewMode="tiles"
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData data={domains} />
      <DomainList.Item
        textValue={(domain) => domain.domain}
        showTiles
        showList={false}
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar
              color={
                domain.type === "Domain" ? "blue" : "teal"
              }
            >
              {domain.type === "Domain" ? (
                <IconDomain />
              ) : (
                <IconSubdomain />
              )}
            </Avatar>
            <Heading>{domain.hostname}</Heading>
            <Text>{domain.type}</Text>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
              <MenuItem>Löschen</MenuItem>
            </ContextMenu>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

---

# Mit Avatar

Der [Avatar](https://flow.mittwald.de/components/content/avatar) steht am Anfang eines List-Items und
spiegelt das Element wider: Ein [Icon](https://flow.mittwald.de/components/content/icon) steht für die
Kategorie (z. B. ein Domain-Icon), ein hochgeladenes
[Image](https://flow.mittwald.de/components/content/image) wird angezeigt, andernfalls erscheinen
Initialen. Elemente derselben Kategorie erhalten dasselbe Icon.

```tsx
import {
  Avatar,
  Heading,
  IconDomain,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list-item-view/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={3}
      hidePagination
      aria-label="Domains"
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData
        data={domains.filter(
          (domain) => domain.type === "Domain",
        )}
      />
      <DomainList.Item
        textValue={(domain) => domain.domain}
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar color="blue">
              <IconDomain />
            </Avatar>
            <Heading>{domain.hostname}</Heading>
            <Text>{domain.type}</Text>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

---

# Mit Link

Setze `href` an `List.Item`, um das gesamte List-Item zu verlinken.

```tsx
import {
  Avatar,
  ContextMenu,
  Heading,
  IconDomain,
  MenuItem,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list-item-view/examples/domainApi";

export default () => {
  const List = typedList<Domain>();

  return (
    <List.List
      batchSize={2}
      hidePagination
      aria-label="Domains"
      getItemId={(domain) => domain.id}
    >
      <List.StaticData data={domains} />
      <List.Item
        href={() => "#"}
        textValue={(domain) => domain.domain}
      >
        {(domain) => (
          <List.ItemView>
            <Avatar>
              <IconDomain />
            </Avatar>
            <Heading>{domain.hostname}</Heading>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
            </ContextMenu>
          </List.ItemView>
        )}
      </List.Item>
    </List.List>
  );
}
```

---

# Mit Accordion

Aktiviere `accordion` an der `List`, damit sich ein List-Item per Klick ein-
oder ausklappen lässt. Den erweiterten Inhalt platzierst du in der ItemView über
`<Content slot="bottom" />`.

```tsx
import {
  Avatar,
  Content,
  Heading,
  IconDomain,
  ListItemView,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list-item-view/examples/domainApi";

export default () => {
  const List = typedList<Domain>();

  return (
    <List.List
      batchSize={2}
      hidePagination
      accordion
      aria-label="Domains"
      getItemId={(domain) => domain.id}
    >
      <List.StaticData data={domains} />
      <List.Item textValue={(domain) => domain.domain}>
        {(domain) => (
          <ListItemView>
            <Avatar>
              <IconDomain />
            </Avatar>
            <Heading>{domain.hostname}</Heading>
            <Text>{domain.type}</Text>
            <Content slot="bottom">Mehr Inhalt</Content>
          </ListItemView>
        )}
      </List.Item>
    </List.List>
  );
}
```

---

# Mit Checkboxen

[Checkboxen](https://flow.mittwald.de/components/form-controls/checkbox) in einem List-Item werden
automatisch am Anfang der Zeile angeordnet. Ihre Funktionalität wird nicht von
der List gesteuert und muss individuell implementiert werden. Achte darauf, dass
die gesamte Zeile zur Auswahl genutzt werden kann – nutze dafür `onAction` der
List.

```tsx
import {
  Avatar,
  Checkbox,
  Heading,
  IconDomain,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list-item-view/examples/domainApi";
import { useState } from "react";

export default () => {
  const List = typedList<Domain>();

  const [selectedDomains, setSelectedDomains] = useState<
    Domain[]
  >([]);

  const onSelected = (
    domain: Domain,
    selected: boolean,
  ) => {
    if (selected) {
      setSelectedDomains((prev) => [...prev, domain]);
    } else {
      setSelectedDomains((prev) =>
        prev.filter((d) => d.id !== domain.id),
      );
    }
  };

  const isSelected = (domain: Domain) => {
    return (
      selectedDomains.find((d) => d.id === domain.id) !==
      undefined
    );
  };

  return (
    <List.List
      hidePagination
      batchSize={2}
      aria-label="Domains"
      onAction={(domain) => {
        onSelected(domain, !isSelected(domain));
      }}
      getItemId={(domain) => domain.id}
    >
      <List.StaticData data={domains} />
      <List.Item
        showTiles
        textValue={(domain) => domain.hostname}
      >
        {(domain) => (
          <List.ItemView>
            <Checkbox
              isSelected={isSelected(domain)}
              onChange={(value) =>
                onSelected(domain, value)
              }
              aria-label={`${domain.hostname} auswählen`}
            />
            <Avatar>
              <IconDomain />
            </Avatar>
            <Heading>{domain.hostname}</Heading>
            <Text>{domain.type}</Text>
          </List.ItemView>
        )}
      </List.Item>

      <List.Table>
        <List.TableHeader>
          <List.TableColumn>
            <Checkbox
              aria-label="Alle auswählen"
              onChange={(v) =>
                setSelectedDomains(v ? domains : [])
              }
            />
          </List.TableColumn>
          <List.TableColumn>Domain</List.TableColumn>
        </List.TableHeader>
        <List.TableBody>
          <List.TableRow>
            <List.TableCell>
              {(domain) => (
                <Checkbox
                  isSelected={isSelected(domain)}
                  onChange={(value) =>
                    onSelected(domain, value)
                  }
                  aria-label={`${domain.hostname} auswählen`}
                />
              )}
            </List.TableCell>
            <List.TableCell>
              {(domain) => domain.hostname}
            </List.TableCell>
          </List.TableRow>
        </List.TableBody>
      </List.Table>
    </List.List>
  );
}
```

---

# Mit Content Slots

In einem List-Item kann zusätzlicher `<Content />` (Top und Bottom Content)
platziert werden. Die Position wird über das `slot`-Property gesteuert.

```tsx
import {
  Avatar,
  Content,
  ContextMenu,
  Heading,
  IconDomain,
  MenuItem,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list-item-view/examples/domainApi";

export default () => {
  const List = typedList<Domain>();

  return (
    <List.List
      batchSize={2}
      hidePagination
      aria-label="Domains"
      getItemId={(domain) => domain.id}
    >
      <List.StaticData data={domains} />
      <List.Item
        showTiles
        textValue={(domain) => domain.domain}
      >
        {(domain) => (
          <List.ItemView>
            <Avatar>
              <IconDomain />
            </Avatar>
            <Heading>{domain.hostname}</Heading>

            <Content slot="top">Top Content</Content>
            <Content slot="bottom">Bottom Content</Content>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
            </ContextMenu>
          </List.ItemView>
        )}
      </List.Item>
    </List.List>
  );
}
```

---

# Mit ColumnLayout

Der `List.ItemView` können die
[ColumnLayout](https://flow.mittwald.de/components/structure/column-layout)-Properties `s`, `m` und `l`
mitgegeben werden, um Seitenverhältnis und Umbruchverhalten von Header und
Content zu steuern.

```tsx
import {
  Avatar,
  Content,
  ContextMenu,
  Heading,
  IconEmail,
  Label,
  MenuItem,
  ProgressBar,
  typedList,
} from "@mittwald/flow-react-components";

export default () => {
  const List = typedList<{ mail: string }>();

  return (
    <List.List
      batchSize={2}
      aria-label="E-Mail-Adressen"
      hidePagination
    >
      <List.StaticData
        data={[
          { mail: "john@doe.com" },
          { mail: "max@mustermann.de" },
        ]}
      />
      <List.Item textValue={(mail) => mail.mail}>
        {(mail) => (
          <List.ItemView l={[3, 1]} m={[2, 1]} s={[1]}>
            <Avatar>
              <IconEmail />
            </Avatar>
            <Heading>{mail.mail}</Heading>

            <Content>
              <ProgressBar size="s" value={50}>
                <Label>Speicherplatz</Label>
              </ProgressBar>
            </Content>

            <ContextMenu>
              <MenuItem>Details anzeigen</MenuItem>
            </ContextMenu>
          </List.ItemView>
        )}
      </List.Item>
    </List.List>
  );
}
```

Da für die Spalten auch `null` gesetzt werden kann, lässt sich nicht zwingend
benötigter Content in kleineren Ansichten ausblenden. In diesem Fall werden auch
die entsprechenden Content Slots nicht angezeigt.

```tsx
import {
  Avatar,
  Content,
  ContextMenu,
  Heading,
  IconEmail,
  Label,
  MenuItem,
  ProgressBar,
  typedList,
} from "@mittwald/flow-react-components";

export default () => {
  const List = typedList<{ mail: string }>();

  return (
    <div style={{ width: 400 }}>
      <List.List
        batchSize={2}
        aria-label="E-Mail-Adressen"
        hidePagination
      >
        <List.StaticData
          data={[
            { mail: "john@doe.com" },
            { mail: "max@mustermann.de" },
          ]}
        />
        <List.Item textValue={(mail) => mail.mail}>
          {(mail) => (
            <List.ItemView
              l={[3, 1]}
              m={[2, 1]}
              s={[1, null]}
            >
              <Avatar>
                <IconEmail />
              </Avatar>
              <Heading>{mail.mail}</Heading>

              <Content>
                <ProgressBar size="s" value={50}>
                  <Label>Speicherplatz</Label>
                </ProgressBar>
              </Content>

              <ContextMenu>
                <MenuItem>Details anzeigen</MenuItem>
              </ContextMenu>
            </List.ItemView>
          )}
        </List.Item>
      </List.List>
    </div>
  );
}
```

---

# Mit ContextMenu

Aktionen eines List-Items platzierst du in einem
[ContextMenu](https://flow.mittwald.de/components/actions/context-menu). Für dauerhaft sichtbare
Aktionen nutzt du stattdessen [Buttons](https://flow.mittwald.de/components/actions/button) in einer
ActionGroup.

```tsx
import {
  Avatar,
  ContextMenu,
  Heading,
  IconDelete,
  IconDomain,
  IconEdit,
  IconInfo,
  IconSubdomain,
  MenuItem,
  Text,
  typedList,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list-item-view/examples/domainApi";

export default () => {
  const DomainList = typedList<Domain>();

  return (
    <DomainList.List
      batchSize={2}
      hidePagination
      aria-label="Domains"
      getItemId={(domain) => domain.id}
    >
      <DomainList.StaticData data={domains} />
      <DomainList.Item
        textValue={(domain) => domain.domain}
      >
        {(domain) => (
          <DomainList.ItemView>
            <Avatar
              color={
                domain.type === "Domain" ? "blue" : "teal"
              }
            >
              {domain.type === "Domain" ? (
                <IconDomain />
              ) : (
                <IconSubdomain />
              )}
            </Avatar>
            <Heading>{domain.hostname}</Heading>
            <Text>{domain.type}</Text>

            <ContextMenu>
              <MenuItem>
                <IconInfo />
                <Text>Details anzeigen</Text>
              </MenuItem>
              <MenuItem>
                <IconEdit />
                <Text>Bearbeiten</Text>
              </MenuItem>
              <MenuItem>
                <IconDelete />
                <Text>Löschen</Text>
              </MenuItem>
            </ContextMenu>
          </DomainList.ItemView>
        )}
      </DomainList.Item>
    </DomainList.List>
  );
}
```

---

# Mit ActionGroup

Verwende eine ActionGroup innerhalb des `<Content />`, um
[Buttons](https://flow.mittwald.de/components/actions/button) im List-Item zu platzieren.

```tsx
import {
  ActionGroup,
  Avatar,
  Button,
  Content,
  Heading,
  IconDomain,
  typedList,
  IconEdit,
  IconDelete,
} from "@mittwald/flow-react-components";
import {
  type Domain,
  domains,
} from "@/content/components/list/list-item-view/examples/domainApi";

export default () => {
  const List = typedList<Domain>();

  return (
    <List.List
      batchSize={2}
      hidePagination
      aria-label="Domains"
      getItemId={(domain) => domain.id}
    >
      <List.StaticData data={domains} />
      <List.Item textValue={(domain) => domain.domain}>
        {(domain) => (
          <List.ItemView>
            <Avatar>
              <IconDomain />
            </Avatar>
            <Heading>{domain.hostname}</Heading>

            <Content>
              <ActionGroup>
                <Button
                  aria-label="Bearbeiten"
                  variant="plain"
                  color="secondary"
                >
                  <IconEdit />
                </Button>
                <Button
                  aria-label="Löschen"
                  variant="plain"
                  color="secondary"
                >
                  <IconDelete />
                </Button>
              </ActionGroup>
            </Content>
          </List.ItemView>
        )}
      </List.Item>
    </List.List>
  );
}
```

---

# Breadcrumb

Eine Breadcrumb zeigt die aktuelle Position sowie übergeordnete Navigationsebenen an.

> **mStudio-Extensions:** Importiere `Breadcrumb` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`.

```tsx
import {
  Breadcrumb,
  Link,
} from "@mittwald/flow-react-components";

<Breadcrumb>
  <Link href="#">Projekte</Link>
  <Link href="#">Apps</Link>
  <Link href="#">Meine App</Link>
</Breadcrumb>
```

---

# Best Practices

- Wähle einen sinnvollen Startpunkt. Im mStudio bezieht sich die Breadcrumb zum
  Beispiel auf die Navigation innerhalb eines Projekts.
- Bilde die Navigationshierarchie exakt ab. Ein Beispiel ist „Projekt > Apps >
  App“.
- Halte die Zahl der Ebenen überschaubar. Ab etwa fünf Ebenen verlieren User die
  Übersicht.
- Verwende generische Bezeichnungen wie „App“ statt konkreter Namen. Dynamische
  Namen verlängern die Breadcrumb unnötig, generische Begriffe halten die
  Navigation stabil und lesbar.

---

# Color

Zusätzlich zur Standard-Color kann die Breadcrumb in **Light** und **Dark**
dargestellt werden, um auf farbigen oder dekorativen Hintergründen ausreichend
Kontrast zu erreichen. Mehr zur richtigen Verwendung von Light und Dark findest
du in den Foundations unter
[Color](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

```tsx
import {
  Breadcrumb,
  Link,
} from "@mittwald/flow-react-components";

<Breadcrumb color="light">
  <Link href="#">Projekte</Link>
  <Link href="#">Apps</Link>
  <Link href="#">Meine App</Link>
</Breadcrumb>
```

```tsx
import {
  Breadcrumb,
  Link,
} from "@mittwald/flow-react-components";

<Breadcrumb color="dark">
  <Link href="#">Projekte</Link>
  <Link href="#">Apps</Link>
  <Link href="#">Meine App</Link>
</Breadcrumb>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | `'react-aria-Breadcrumbs'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static"` | `"default"` | The color of the breadcrumb. |
| `dependencies` | `readonly any[]` | - | Values that should invalidate the item cache when using dynamic collections. |
| `dir` | `string` | - | - |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the breadcrumbs are disabled. |
| `items` | `Iterable<object>` | - | Item objects in the collection. |
| `lang` | `string` | - | - |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `size` | `"s" \| "m"` | `"m"` | The size of the element. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onAction` | `((key: Key) => void)` | - | Handler that is called when a breadcrumb is clicked. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--breadcrumb--spacing` | `0.5rem` |
| `--breadcrumb--font-weight--default` | `normal` |
| `--breadcrumb--font-weight--current` | `bold` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--breadcrumb--color--default` | `#121518` | `#FFFFFF` |
| `--breadcrumb--color--hover` | `#292F37` | `#F4F8FC` |
| `--breadcrumb--color--pressed` | `#3A434E` | `#E5EFF8` |
| `--breadcrumb--color-dark--default` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--breadcrumb--color-dark--hover` | `rgb(0 0 0 / 87.5%)` | `rgb(255 255 255 / 87.5%)` |
| `--breadcrumb--color-dark--pressed` | `rgb(0 0 0 / 75%)` | `rgb(255 255 255 / 75%)` |
| `--breadcrumb--color-light--default` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--breadcrumb--color-light--hover` | `rgb(255 255 255 / 87.5%)` | `rgb(0 0 0 / 87.5%)` |
| `--breadcrumb--color-light--pressed` | `rgb(255 255 255 / 75%)` | `rgb(0 0 0 / 75%)` |
| `--breadcrumb--color-dark-static--default` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--breadcrumb--color-dark-static--hover` | `rgb(0 0 0 / 87.5%)` | `rgb(0 0 0 / 87.5%)` |
| `--breadcrumb--color-dark-static--pressed` | `rgb(0 0 0 / 75%)` | `rgb(0 0 0 / 75%)` |
| `--breadcrumb--color-light-static--default` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--breadcrumb--color-light-static--hover` | `rgb(255 255 255 / 87.5%)` | `rgb(255 255 255 / 87.5%)` |
| `--breadcrumb--color-light-static--pressed` | `rgb(255 255 255 / 75%)` | `rgb(255 255 255 / 75%)` |

---

# HeaderNavigation

Die HeaderNavigation ist eine horizontale Navigationsleiste am Seitenanfang.

> **mStudio-Extensions:** Importiere `HeaderNavigation` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import {
  Button,
  HeaderNavigation,
  IconSearch,
  Link,
} from "@mittwald/flow-react-components";

<HeaderNavigation aria-label="Header navigation">
  <Link href="#">Getting started</Link>
  <Link href="#" aria-current="page">
    Components
  </Link>
  <Button>
    <IconSearch />
  </Button>
</HeaderNavigation>
```

---

# Best Practices

- Beschrifte die Navigationspunkte klar und ordne sie sinnvoll an.
- Nutze für [Icons](https://flow.mittwald.de/components/content/icon) gängige Symbole mit eindeutiger
  Funktion.
- Halte die Navigation schlank und beschränke sie auf relevante Elemente.

---

# Color

Zusätzlich zur Standard-Color kann die HeaderNavigation in **Light** und
**Dark** dargestellt werden, um auf farbigen oder dekorativen Hintergründen
ausreichend Kontrast zu erreichen. Mehr zur richtigen Verwendung von Light und
Dark findest du in den Foundations unter
[Color](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

```tsx
import {
  Button,
  HeaderNavigation,
  IconSearch,
  Link,
} from "@mittwald/flow-react-components";

<HeaderNavigation
  aria-label="Header navigation"
  color="light"
>
  <Link href="#">Getting started</Link>
  <Link href="#" aria-current="page">
    Components
  </Link>
  <Button>
    <IconSearch />
  </Button>
</HeaderNavigation>
```

```tsx
import {
  Button,
  HeaderNavigation,
  IconSearch,
  Link,
} from "@mittwald/flow-react-components";

<HeaderNavigation
  aria-label="Header navigation"
  color="dark"
>
  <Link href="#">Getting started</Link>
  <Link href="#" aria-current="page">
    Components
  </Link>
  <Button>
    <IconSearch />
  </Button>
</HeaderNavigation>
```

---

# Kombiniere mit …

## ContextMenu

Nutze einen [Button](https://flow.mittwald.de/components/actions/button) als Trigger für ein
[ContextMenu](https://flow.mittwald.de/components/actions/context-menu), um zum Beispiel ein Profil-Menü
zu öffnen. Der Button kann dabei einen [Avatar](https://flow.mittwald.de/components/content/avatar)
enthalten.

```tsx
import {
  Avatar,
  Button,
  ContextMenu,
  ContextMenuTrigger,
  HeaderNavigation,
  Heading,
  IconCamera,
  IconLogout,
  IconNotification,
  IconSearch,
  IconSettings,
  IconSupport,
  Image,
  Initials,
  MenuItem,
  Section,
  Separator,
  Text,
} from "@mittwald/flow-react-components";

<HeaderNavigation aria-label="Header navigation">
  <Button>
    <IconSearch />
  </Button>
  <Button>
    <IconSupport />
  </Button>
  <Button>
    <IconNotification />
  </Button>
  <ContextMenuTrigger>
    <Button>
      <Avatar>
        <Image
          alt="Gopher"
          src="https://cdn.shopify.com/s/files/1/2022/6883/products/IMG_2002_250x250@2x.JPG?v=1538235544"
        />
      </Avatar>
    </Button>
    <ContextMenu>
      <Section>
        <MenuItem>
          <Avatar>
            <Initials>Max Mustermann</Initials>
          </Avatar>
          <IconCamera />
        </MenuItem>
        <Heading>Max Mustermann</Heading>
      </Section>
      <Separator />
      <Section>
        <MenuItem>
          <IconSettings />
          <Text>Profil</Text>
        </MenuItem>
        <MenuItem>
          <IconLogout />
          <Text>Logout</Text>
        </MenuItem>
      </Section>
    </ContextMenu>
  </ContextMenuTrigger>
</HeaderNavigation>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static"` | `"default"` | The color of the header navigation. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--header-navigation--padding` | `8px` |
| `--header-navigation--spacing` | `1rem` |
| `--header-navigation--corner-radius` | `8px` |
| `--header-navigation--corner-radius-round` | `50%` |
| `--header-navigation--font-weight-current` | `bold` |
| `--header-navigation--underline-width-current` | `2px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--header-navigation--color` | `#121518` | `#FFFFFF` |
| `--header-navigation--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--header-navigation--background-color--pressed` | `#DCE9F7` | `#5E6C7A` |
| `--header-navigation--color-dark` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--header-navigation--background-color-dark--hover` | `rgb(0 0 0 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--header-navigation--background-color-dark--pressed` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--header-navigation--color-light` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--header-navigation--background-color-light--hover` | `rgb(255 255 255 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--header-navigation--background-color-light--pressed` | `rgb(255 255 255 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--header-navigation--color-dark-static` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--header-navigation--background-color-dark-static--hover` | `rgb(0 0 0 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--header-navigation--background-color-dark-static--pressed` | `rgb(0 0 0 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--header-navigation--color-light-static` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--header-navigation--background-color-light-static--hover` | `rgb(255 255 255 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--header-navigation--background-color-light-static--pressed` | `rgb(255 255 255 / 25%)` | `rgb(255 255 255 / 25%)` |

---

# Link

Ein Link navigiert zu einer anderen Seite, einem Anker oder startet Downloads.

> **mStudio-Extensions:** Importiere `Link` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

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

<Link href="#">Zum Dashboard</Link>
```

---

# Best Practices

- Nutze Links zum Navigieren und [Buttons](https://flow.mittwald.de/components/actions/button) für
  Aktionen. Eine Ausnahme können hervorgehobene Call-to-Actions sein, bei denen
  ein Button-ähnliches Erscheinungsbild für eine Navigation sinnvoll ist.
- Halte den Linktext kurz, prägnant und in seiner Absicht klar erkennbar.
- Ergänze ein `aria-label`, wenn der Linktext allein nicht eindeutig ist.
- Öffne externe Links in einem neuen Tab, interne im gleichen.

## Link vs. Button

Verwende für Navigation bevorzugt Links und für Aktionen Buttons. Eine Ausnahme
können hervorgehobene
[Call-to-Actions](https://flow.mittwald.de/components/navigation/link#kombiniere-mit-button) sein, bei
denen ein Button-ähnliches Erscheinungsbild für eine Navigation sinnvoll ist.

**Verwende Links, um z. B. ...**

- zu einer anderen Seite zu navigieren.
- zu einem Anker auf der Seite zu scrollen.
- eine externe Seite zu öffnen.
- einen Download zu starten.

**Verwende Buttons, um z. B. ...**

- eine Aktion auszuführen oder ein Event zu starten, ohne die Seite zu verlassen.
- Formulare zu speichern oder zurückzusetzen.
- in einem [Modal](https://flow.mittwald.de/components/overlays/modal) Aktionen auszuwählen.

---

# Color

Auf farbigen oder dekorativen Hintergründen kann der Link in **Light** und
**Dark** dargestellt werden, um ausreichend Kontrast zu erreichen. Mehr zur
richtigen Verwendung von Light und Dark findest du in den Foundations unter
[Color](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

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

<Link href="#" color="light">
  Light
</Link>
```

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

<Link href="#" color="dark">
  Dark
</Link>
```

---

# Disabled

Nutze das Property `isDisabled`, um einen Link als disabled darzustellen. Achte
dabei darauf, dass aus dem Kontext klar wird, warum der Link gerade nicht zur
Verfügung steht.

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

<Link href="#" isDisabled>
  Disabled
</Link>
```

---

# Inline

Links innerhalb des `<Text />`-Tags werden automatisch als Inline Link
gerendert.

```tsx
import {
  Link,
  Text,
} from "@mittwald/flow-react-components";

<Text>
  Sieh dir unser <Link href="#">Onboarding</Link> an, um
  weitere Informationen zu erhalten.
</Text>
```

---

# Externe Links und Downloads

Interne Links öffnen sich immer in dem Tab, in dem der User sich gerade
befindet. Der User kann jedoch selbst entscheiden, ob er den Link lieber in
einem neuen Tab öffnen möchte.

## Externer Link

Externe Links – also Verweise auf eine andere Domain – öffnen sich immer in
einem neuen Tab. Sobald `target="_blank"` gesetzt ist, wird automatisch das
`IconExternalLink` angezeigt, um dieses Verhalten zu verdeutlichen.

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

<Link href="https://mittwald.de" target="_blank">
  Externer Link
</Link>
```

## Download

Das `IconDownload` zeigt an, dass es sich um einen Download-Link handelt. Das
Icon wird automatisch neben dem Link angezeigt, wenn das `download` Property
gesetzt ist.

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

<Link download>Rechnung herunterladen</Link>
```

---

# Kombiniere mit …

## Section

Platziere einen Link im Header einer [Section](https://flow.mittwald.de/components/structure/section)
neben der [Heading](https://flow.mittwald.de/components/content/heading), um ihn inhaltlich mit der
Section zu verknüpfen.

```tsx
import {
  Header,
  Heading,
  Link,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<Section>
  <Header>
    <Heading>Heading 2</Heading>
    <Link href="#">Textlink</Link>
  </Header>
  <Text>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  </Text>
</Section>
```

## Button

Für hervorgehobene Call-to-Actions, bei denen ein Button-ähnliches
Erscheinungsbild für eine Navigation sinnvoll ist, kann ein
[Button](https://flow.mittwald.de/components/actions/button) im Link platziert werden.

```tsx
import {
  Link,
  Button,
} from "@mittwald/flow-react-components";

<Link href="#">
  <Button>Zum mStudio</Button>
</Link>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static"` | `"default"` | The color of the link. |
| `dir` | `string` | - | - |
| `download` | `string \| boolean` | - | Causes the browser to download the linked URL. A string may be provided to suggest a file name. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download). |
| `hidden` | `boolean` | - | - |
| `href` | `string` | - | A URL to link to. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href). |
| `hrefLang` | `string` | - | Hints at the human language of the linked URL. See[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#hreflang). |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `inline` | `boolean` | - | Whether the link should be styled for being displayed inside a text. |
| `isDisabled` | `boolean` | - | Whether the link is disabled. |
| `lang` | `string` | - | - |
| `linkComponent` | `ComponentType<Omit<DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, "ref">>` | - | An alternative link component. |
| `ping` | `string` | - | A space-separated list of URLs to ping when the link is followed. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#ping). |
| `referrerPolicy` | `"" \| "no-referrer" \| "no-referrer-when-downgrade" \| "origin" \| "origin-when-cross-origin" \| "same-origin" \| "strict-origin" \| "strict-origin-when-cross-origin" \| "unsafe-url"` | - | How much of the referrer to send when following the link. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#referrerpolicy). |
| `rel` | `string` | - | The relationship between the linked resource and the current page. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel). |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `routerOptions` | `undefined` | - | Options for the configured client side router. |
| `size` | `"s" \| "m"` | `"m"` | The size of the element. |
| `slot` | `string` | - | The name of the slot the link is placed in. In action groups: `primary` (at the end), `secondary` (before the primary action) or `abort` (at the start). |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `target` | `HTMLAttributeAnchorTarget` | - | The target window for the link. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target). |
| `translate` | `"yes" \| "no"` | - | - |
| `whiteSpace` | `WhiteSpace` | - | The whiteSpace css value of the element. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onClick` | `((e: MouseEvent<FocusableElement, MouseEvent>) => void)` | - | **Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions. |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onHoverChange` | `((isHovering: boolean) => void)` | - | Handler that is called when the hover state changes. |
| `onHoverEnd` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction ends. |
| `onHoverStart` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction starts. |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPress` | `((e: PressEvent) => void)` | - | Handler that is called when the press is released over the target. |
| `onPressChange` | `((isPressed: boolean) => void)` | - | Handler that is called when the press state changes. |
| `onPressEnd` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. |
| `onPressStart` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction starts. |
| `onPressUp` | `((e: PressEvent) => void)` | - | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-current` | `string` | - | Marks the link as the currently active one, e.g. in a navigation. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--link--icon-height` | `calc(1rem * 1.25)` |
| `--link--icon-height-s` | `calc(0.875rem * 1.25)` |
| `--link--font-weight` | `bold` |
| `--link--spacing` | `0.25rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--link--color--default` | `#0054F5` | `#85AFFF` |
| `--link--color--hover` | `#003FB8` | `#ABC6FF` |
| `--link--color--pressed` | `#002A7B` | `#E0EBFF` |
| `--link--color--disabled` | `#DCE9F7` | `#5E6C7A` |
| `--link--color-dark--default` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--link--color-dark--hover` | `rgb(0 0 0 / 87.5%)` | `rgb(255 255 255 / 87.5%)` |
| `--link--color-dark--pressed` | `rgb(0 0 0 / 75%)` | `rgb(255 255 255 / 75%)` |
| `--link--color-dark--disabled` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--link--color-light--default` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--link--color-light--hover` | `rgb(255 255 255 / 87.5%)` | `rgb(0 0 0 / 87.5%)` |
| `--link--color-light--pressed` | `rgb(255 255 255 / 75%)` | `rgb(0 0 0 / 75%)` |
| `--link--color-light--disabled` | `rgb(255 255 255 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--link--color-dark-static--default` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--link--color-dark-static--hover` | `rgb(0 0 0 / 87.5%)` | `rgb(0 0 0 / 87.5%)` |
| `--link--color-dark-static--pressed` | `rgb(0 0 0 / 75%)` | `rgb(0 0 0 / 75%)` |
| `--link--color-dark-static--disabled` | `rgb(0 0 0 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--link--color-light-static--default` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--link--color-light-static--hover` | `rgb(255 255 255 / 87.5%)` | `rgb(255 255 255 / 87.5%)` |
| `--link--color-light-static--pressed` | `rgb(255 255 255 / 75%)` | `rgb(255 255 255 / 75%)` |
| `--link--color-light-static--disabled` | `rgb(255 255 255 / 25%)` | `rgb(255 255 255 / 25%)` |

---

# Navigation

Die Navigation dient der Orientierung und führt zu den Unterseiten einer Anwendung.

> **mStudio-Extensions:** Importiere `Navigation` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  Link,
  Navigation,
} from "@mittwald/flow-react-components";

<Navigation aria-label="Companies">
  <Link href="https://www.apple.com">Apple</Link>
  <Link href="https://www.mittwald.de" aria-current="page">
    mittwald
  </Link>
  <Link href="https://www.adobe.com">Adobe</Link>
  <Link href="https://www.google.com">Google</Link>
</Navigation>
```

---

# Best Practices

- Benenne die Menüeinträge kurz, prägnant und verständlich.
- Setze [Icons](https://flow.mittwald.de/components/content/icon) nur ergänzend ein, nicht als alleinige
  Information.
- Begrenze eine Gruppe auf etwa sieben bis acht Menüeinträge. So bleibt die
  Navigation übersichtlich.
- Setze einklappbare Gruppen bewusst ein. Sie verbessern den Überblick, können
  die Orientierung aber erschweren.

---

# Mit Icons

Menüeinträge lassen sich optional mit einem [Icon](https://flow.mittwald.de/components/content/icon)
versehen. Dies bietet Usern eine zusätzliche visuelle Orientierung über den
Inhalt der verlinkten Seite.

```tsx
import {
  IconCustomer,
  IconProject,
  IconServer,
  Link,
  Navigation,
  Text,
} from "@mittwald/flow-react-components";

<Navigation aria-label="Main menu">
  <Link href="#">
    <IconCustomer />
    <Text>Organisationen</Text>
  </Link>
  <Link href="#" aria-current="page">
    <IconServer />
    <Text>Server</Text>
  </Link>
  <Link href="#">
    <IconProject />
    <Text>Projekte</Text>
  </Link>
</Navigation>
```

---

# Mit Gruppen

Mehrere Menüeinträge können zu Gruppen zusammengefasst werden. Zur Kennzeichnung
dieser Gruppen eignet sich ein [Label](https://flow.mittwald.de/components/content/label).

```tsx
import {
  Label,
  Link,
  Navigation,
  NavigationGroup,
} from "@mittwald/flow-react-components";

<Navigation aria-label="Main navigation">
  <NavigationGroup>
    <Label>Allgemein</Label>
    <Link href="#">Dashboard</Link>
    <Link href="#" aria-current="page">
      Performance
    </Link>
  </NavigationGroup>
  <NavigationGroup>
    <Label>Components</Label>
    <Link href="#">Apps</Link>
    <Link href="#">Datenbanken</Link>
    <Link href="#">Domains</Link>
  </NavigationGroup>
</Navigation>
```

---

# Mit einklappbaren Gruppen

Mit der Property `collapsable` können Menügruppen ein- und ausklappbar gemacht
werden. Gerade bei umfangreichen Navigationen hilft dies, die Übersicht zu
wahren.

```tsx
import {
  Label,
  Link,
  Navigation,
  NavigationGroup,
} from "@mittwald/flow-react-components";

<Navigation aria-label="Main navigation">
  <NavigationGroup collapsable>
    <Label>Allgemein</Label>
    <Link href="#">Dashboard</Link>
    <Link href="#" aria-current="page">
      Performance
    </Link>
  </NavigationGroup>
  <NavigationGroup collapsable>
    <Label>Components</Label>
    <Link href="#">Apps</Link>
    <Link href="#">Datenbanken</Link>
    <Link href="#">Domains</Link>
  </NavigationGroup>
</Navigation>
```

---

# Mit eingeklappten Gruppen

Einklappbare Gruppen starten ausgeklappt. Mit `defaultExpanded={false}` starten
sie eingeklappt und der User klappt nur die Gruppen aus, die er braucht. Bei
vielen Gruppen entsteht so eine Übersicht auf einen Blick.

```tsx
import {
  Label,
  Link,
  Navigation,
  NavigationGroup,
} from "@mittwald/flow-react-components";

<Navigation aria-label="Main navigation">
  <NavigationGroup collapsable defaultExpanded={false}>
    <Label>Allgemein</Label>
    <Link href="#">Dashboard</Link>
    <Link href="#">Performance</Link>
  </NavigationGroup>
  <NavigationGroup collapsable>
    <Label>Components</Label>
    <Link href="#">Apps</Link>
    <Link href="#" aria-current="page">
      Datenbanken
    </Link>
    <Link href="#">Domains</Link>
  </NavigationGroup>
</Navigation>
```

---

# Kombiniere mit …

## Separator

Zur klaren Trennung von Menügruppen kann ein
[Separator](https://flow.mittwald.de/components/structure/separator) verwendet werden.

```tsx
import {
  Label,
  Link,
  Navigation,
  NavigationGroup,
  Separator,
} from "@mittwald/flow-react-components";

<Navigation aria-label="Main navigation">
  <NavigationGroup>
    <Label>Allgemein</Label>
    <Link href="#">Dashboard</Link>
    <Link href="#" aria-current="page">
      Performance
    </Link>
  </NavigationGroup>

  <Separator />

  <NavigationGroup>
    <Label>Komponenten</Label>
    <Link href="#">Apps</Link>
    <Link href="#">Datenbanken</Link>
    <Link href="#">Domains</Link>
  </NavigationGroup>
</Navigation>
```

## Badge

Menüeinträge können um ein [Badge](https://flow.mittwald.de/components/status/badge) erweitert werden um
zusätzliche Metainformationen wie „New“ oder „Beta“ anzuzeigen. Für
Anwendungsfälle wie ein Benachrichtigungscenter kann außerdem ein
[CounterBadge](https://flow.mittwald.de/components/status/counter-badge) verwendet werden.

```tsx
import {
  Badge,
  CounterBadge,
  Link,
  Navigation,
} from "@mittwald/flow-react-components";

<Navigation aria-label="Companies">
  <Link>Apps</Link>
  <Link aria-current="page">
    Container <Badge>Neu</Badge>
  </Link>
  <Link>
    Benachrichtigungen <CounterBadge count={3} />
  </Link>
</Navigation>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# TabNavigation

Die TabNavigation ermöglicht die Navigation zwischen verschiedenen Seiten innerhalb eines zusammengehörigen Bereichs.

> **mStudio-Extensions:** Importiere `TabNavigation` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  TabNavigation,
  Link,
  AlertIcon,
} from "@mittwald/flow-react-components";

<TabNavigation aria-label="Projekt-Navigation">
  <Link href="#">Apps</Link>
  <Link href="#" aria-current="page">
    Container
  </Link>
  <Link href="#">Domains</Link>
  <Link href="#">E-Mails</Link>
  <Link href="#">
    Datenbanken
    <AlertIcon status="warning" />
  </Link>
  <Link href="#">Backups</Link>
</TabNavigation>
```

---

# Best Practices

- Benenne die Seiten kurz, prägnant und verständlich.
- Ordne die Seiten nach ihrer Wichtigkeit. Bei wenig Platz bleiben die vorderen
  Seiten am längsten sichtbar.
- Halte die Navigation schlank und beschränke sie auf relevante Bereiche.

## Tabs vs. TabNavigation

Flow bietet mit der TabNavigation und den [Tabs](https://flow.mittwald.de/components/structure/tabs)
zwei ähnlich aussehende Components, die sich aber in der Verwendung klar
unterscheiden:

**Verwende Tabs, um ...**

Inhalte innerhalb derselben Seite umzuschalten, ohne zu navigieren.

**Verwende eine TabNavigation, um ...**

zwischen gleichrangigen Unterseiten zu navigieren.

---

# Responsives Overflow-Verhalten

Passen nicht alle Links in die verfügbare Breite, bleiben die vorderen Links
sichtbar und die übrigen werden ausgeblendet. Stattdessen erscheint rechts ein
**Weitere**-Button, der die ausgeblendeten Links in einem
[ContextMenu](https://flow.mittwald.de/components/actions/context-menu) öffnet. Befindet sich die
aktuell aktive Seite im ContextMenu, wird der Button wie ein aktiver Link
dargestellt.

```tsx
import {
  TabNavigation,
  Link,
  LayoutCard,
} from "@mittwald/flow-react-components";

<LayoutCard style={{ maxWidth: "450px" }}>
  <TabNavigation aria-label="Projekt-Navigation">
    <Link href="#">Dashboard</Link>
    <Link href="#">Domains</Link>
    <Link href="#">E-Mail</Link>
    <Link href="#">Datenbanken</Link>
    <Link href="#" aria-current="page">
      Einstellungen
    </Link>
  </TabNavigation>
</LayoutCard>
```

---

# Mit Status-Icons

Innerhalb der Links kann ein `AlertIcon` verwendet werden, um auf Zustände
innerhalb eines Navigationsbereichs hinzuweisen.

```tsx
import {
  AlertIcon,
  Badge,
  TabNavigation,
  Link,
} from "@mittwald/flow-react-components";

<TabNavigation aria-label="Projekt-Navigation">
  <Link href="#" aria-current="page">
    Dashboard
  </Link>
  <Link href="#">
    Speicherplatz
    <AlertIcon status="danger" />
  </Link>
  <Link href="#">
    Backups
    <Badge color="violet">Neu</Badge>
  </Link>
</TabNavigation>
```

---

# Kombiniere mit …

## LayoutCard

Platziere die TabNavigation in einer
[LayoutCard](https://flow.mittwald.de/components/structure/layout-card), um zwischen den Unterseiten zu
navigieren. Der Inhalt der aktiven Seite wird darunter in derselben LayoutCard
dargestellt.

```tsx
import {
  LayoutCard,
  TabNavigation,
  Link,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<LayoutCard>
  <TabNavigation aria-label="Projekt-Navigation">
    <Link href="#" aria-current="page">
      Apps
    </Link>
    <Link href="#">Container</Link>
    <Link href="#">Domains</Link>
    <Link href="#">E-Mails</Link>
    <Link href="#">Backups</Link>
  </TabNavigation>
  <Section>
    <Text>
      Der Inhalt der aktiven Seite wird unterhalb der
      TabNavigation in derselben LayoutCard dargestellt.
    </Text>
  </Section>
</LayoutCard>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--tab-navigation--padding` | `16px` |
| `--tab-navigation--font-weight--current` | `bold` |
| `--tab-navigation--spacing` | `0.5rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--tab-navigation--background-color--default` | `#DCE9F7` | `#5E6C7A` |
| `--tab-navigation--background-color--hover` | `#B7C9DB` | `#8FA1B4` |
| `--tab-navigation--background-color--pressed` | `#8FA1B4` | `#B7C9DB` |
| `--tab-navigation--background-color--current` | `#FFFFFF` | `#1B1F24` |
| `--tab-navigation--color` | `#1B1F24` | `#FFFFFF` |

---

# CoachMark

Ein CoachMark macht auf neue Features oder verschobene Bedienelemente aufmerksam.

> **mStudio-Extensions:** Importiere `CoachMark` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `anchorRef`, `controller`, `render`, `style`, `wrapWith`.

```tsx
import {
  Action,
  Button,
  CoachMark,
  Heading,
  Section,
  Text,
  useOverlayController,
} from "@mittwald/flow-react-components";
import { useRef } from "react";

export default () => {
  const anchor = useRef<HTMLButtonElement>(null);
  const controller = useOverlayController("CoachMark", {
    isDefaultOpen: true,
  });

  return (
    <Section style={{ paddingBlockEnd: 200 }}>
      <Button
        ref={anchor}
        onPress={() => controller.open()}
      >
        Domain verbinden
      </Button>

      {/* Pinned downwards so the hint stays inside this example's frame. */}
      <CoachMark
        shouldFlip={false}
        anchorRef={anchor}
        controller={controller}
      >
        <Heading>Neu: Domain verbinden</Heading>
        <Text>
          Du kannst deine Domain jetzt direkt hier verbinden
          – ohne den Umweg über die Domain-Übersicht.
        </Text>
        <Action closeOverlay="CoachMark">
          <Button>Verstanden</Button>
        </Action>
      </CoachMark>
    </Section>
  );
}
```

---

# Best Practices

- Zeige höchstens ein CoachMark pro Seite. Mehrere konkurrieren um dieselbe
  Aufmerksamkeit und heben sich gegenseitig auf.
- Beschränke den Inhalt auf einen Gedanken. Benenne, was neu ist und welchen
  Vorteil es bringt.
- Blende ein bestätigtes CoachMark dauerhaft aus. Ein Hinweis, der bei jedem
  Aufruf erneut erscheint, kann als störend wahrgenommen werden.
- Platziere unerlässliche Informationen direkt in der Oberfläche. Ein CoachMark
  sollte nicht die einzige Quelle für wichtige Informationen sein.
- Platziere das CoachMark direkt hinter seinem Ankerelement. So wird es in der
  Vorlesereihenfolge an der passenden Stelle erreicht. Steht keine Referenz zur
  Verfügung, gib den Anker als `id` an.

## CoachMark vs. ContextualHelp

Verwende ein CoachMark, um den User proaktiv auf ein neues oder verschobenes
Feature aufmerksam zu machen. Für weiterführende Informationen ist ein
[ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help) die bessere Wahl, da der
User selbst entscheiden kann, ob er diese Information braucht.

**Verwende ein CoachMark, um z. B. ...**

- auf eine neue oder verschobene Funktion hinzuweisen.
- eine Funktion zu zeigen, die leicht zu übersehen ist.
- einen Hinweis zu geben, ohne die Arbeit zu unterbrechen.

**Verwende ein ContextualHelp, um z. B. ...**

- einen Fachbegriff zu erklären.
- Hintergrund zu einem Formularfeld anzubieten.
- eine Einstellung mit ihren Folgen zu beschreiben.

---

# Anker

Ein CoachMark zeigt auf ein Element, nicht auf die Seite. Einen Trigger gibt es
nicht, da das CoachMark nicht vom User geöffnet wird. Stattdessen wird sein
Ankerelement auf einem von zwei Wegen angegeben:

- `anchorRef` ist die Referenz auf das Element. Das ist der Normalfall in einer
  React-Anwendung.
- `anchor` ist die `id` des Elements, nachgeschlagen beim Öffnen. Sie hilft
  dort, wo sich keine Referenz teilen lässt.

Das CoachMark wird direkt hinter seinem Ankerelement im DOM gerendert und folgt
diesem in der Vorlesereihenfolge. Über `aria-details` verweist der Anker
zusätzlich auf das CoachMark. Es wird nicht automatisch angekündigt, sondern
beim Lesen erreicht.

Das CoachMark ist absolut positioniert und benötigt keinen eigenen Platz.
`overflow: hidden` oder ein eigener Stacking Context eines Vorfahren kann es
abschneiden.

Damit es über dem Seiteninhalt liegt, beansprucht es `z-index: 1` – die
niedrigste Stufe, die dafür reicht. Anwendungs-Chrome, das darüber bleiben soll
– etwa ein Sticky Header –, braucht deshalb einen höheren Wert.

Beim Scrollen folgt das CoachMark seinem Anker und bleibt geöffnet.

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

export default () => (
  <Section style={{ paddingBlockEnd: 200 }}>
    <Button id="backup-button">Backup erstellen</Button>

    {/* Pinned downwards so the hint stays inside this example's frame. */}
    <CoachMark
      shouldFlip={false}
      anchor="backup-button"
      isDefaultOpen
    >
      <Heading>Neu: Backups planen</Heading>
      <Text>
        Lege fest, wann ein Backup automatisch erstellt
        wird.
      </Text>
      <Action closeOverlay="CoachMark">
        <Button>Verstanden</Button>
      </Action>
    </CoachMark>
  </Section>
)
```

---

# Schließen

Den Button zum Schließen bringt das CoachMark nicht selbst mit, er wird
komponiert: Ein [Action](https://flow.mittwald.de/components/actions/action) mit `closeOverlay` um einen
[Button](https://flow.mittwald.de/components/actions/button) schließt das CoachMark. Größe und
Platzierung gibt das CoachMark dem Button vor. Escape schließt es ebenfalls.

`onOpenChange` meldet jede Änderung, unabhängig davon, welcher Weg sie ausgelöst
hat. Das ist der Platz, um die Bestätigung zu speichern; beim nächsten Aufruf
unterdrückt `isDefaultOpen={false}` den Hinweis dann.

```tsx
import {
  Action,
  Button,
  CoachMark,
  Heading,
  Section,
  Text,
  useOverlayController,
} from "@mittwald/flow-react-components";
import { useRef } from "react";

export default () => {
  const anchor = useRef<HTMLButtonElement>(null);
  const controller = useOverlayController("CoachMark", {
    isDefaultOpen: true,
  });

  return (
    <Section style={{ paddingBlockEnd: 200 }}>
      <Button
        ref={anchor}
        onPress={() => controller.open()}
      >
        Backup erstellen
      </Button>

      {/* Pinned downwards so the hint stays inside this example's frame. */}
      <CoachMark
        shouldFlip={false}
        anchorRef={anchor}
        controller={controller}
      >
        <Heading>Neu: Backups planen</Heading>
        <Text>
          Lege fest, wann ein Backup automatisch erstellt
          wird.
        </Text>
        <Action closeOverlay="CoachMark">
          <Button>Ausprobieren</Button>
        </Action>
      </CoachMark>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `anchor` | `string` | - | The `id` of the element the coach mark points at, looked up once the element exists. Use it where a ref cannot be shared — an mStudio extension renders in a different context than the host, so a ref never arrives, while an id does. |
| `anchorRef` | `RefObject<Element \| null>` | - | The element the coach mark points at. It is an anchor, not a trigger — nothing about it opens the coach mark. Give it either this or `anchor`. |
| `arrowBoundaryOffset` | `number` | `0` | The minimum distance the arrow's edge should be from the edge of the overlay element. |
| `arrowRef` | `RefObject<Element \| null>` | - | A ref for the popover arrow element. |
| `boundaryElement` | `Element` | `document.body` | Element that that serves as the positioning boundary. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<PopoverRenderProps>` | `'react-aria-Popover'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `containerPadding` | `number` | `12` | The placement padding that should be applied between the element and its surrounding container. |
| `controller` | `OverlayController` | - | An overlay controller to control the popover state. |
| `crossOffset` | `number` | `0` | The additional offset applied along the cross axis between the element and its anchor element. |
| `dir` | `string` | - | - |
| `hidden` | `boolean` | - | - |
| `inert` | `boolean` | - | - |
| `isDefaultOpen` | `boolean` | `false` | Whether the popover is open initially. Use it for an uncontrolled popover. |
| `isEntering` | `boolean` | - | Whether the popover is currently performing an entry animation. |
| `isExiting` | `boolean` | - | Whether the popover is currently performing an exit animation. |
| `isOpen` | `boolean` | - | Whether the popover is open. Use it to control the popover state – then `onOpenChange` must update the state this value comes from. |
| `lang` | `string` | - | - |
| `offset` | `number` | `8` | The additional offset applied along the main axis between the element and its anchor element. |
| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `'bottom'` | The placement of the element with respect to its anchor element. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `scrollRef` | `RefObject<Element \| null>` | `overlayRef` | A ref for the scrollable region within the overlay. |
| `shouldFlip` | `boolean` | `true` | Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely. |
| `shouldSkipAnimation` | `boolean` | - | Whether the popover should appear and disappear without an entry or exit animation. This is used by components such as PreviewTrigger to skip animations when quickly swapping between overlays. |
| `shouldUpdatePosition` | `boolean` | `true` | Whether the overlay should update its position automatically. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `trigger` | `string` | - | The name of the component that triggered the popover. This is reflected on the element as the `data-trigger` attribute, and can be used to provide specific styles for the popover depending on which element triggered it. |
| `width` | `string \| number` | - | A fixed width for the popover. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlurWithin` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the target element and all descendants lose focus. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onFocusWithin` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the target element or a descendant receives focus. |
| `onFocusWithinChange` | `((isFocusWithin: boolean) => void)` | - | Handler that is called when the the focus within state changes. |
| `onOpenChange` | `((isOpen: boolean) => void)` | - | Called with the new open state whenever the popover is opened or closed – on every path, including a close triggered through the controller. It only reports the change; it never performs or suppresses it. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--coach-mark--max-width` | `360px` |

---

# ContextualHelp

Ein ContextualHelp bietet dem User weiterführende, hilfreiche Informationen in einem Popover an.

> **mStudio-Extensions:** Importiere `ContextualHelp` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `controller`, `render`, `style`, `wrapWith`.

```tsx
import {
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  Link,
  Text,
} from "@mittwald/flow-react-components";

<ContextualHelpTrigger subject="Rechte & Rollen">
  <Button />

  <ContextualHelp>
    <Text>
      Jedem Benutzer-Profil wird im mStudio je Projekt
      und/oder Organisation eine Rolle zugewiesen. Das
      ermöglicht dir ein ganz neues und modernes Arbeiten.
    </Text>
    <Link>Mehr erfahren</Link>
  </ContextualHelp>
</ContextualHelpTrigger>
```

---

# Best Practices

- Ordne ein ContextualHelp immer einem spezifischen Element zu. Das kann zum
  Beispiel eine [Heading](https://flow.mittwald.de/components/content/heading), ein
  [Text](https://flow.mittwald.de/components/content/text) oder [Label](https://flow.mittwald.de/components/content/label) sein.
- Nutze es für weiterführende Erklärungen oder Verweise, nicht für
  Unerlässliches. Zum Verständnis der Oberfläche notwendige Inhalte gehören
  direkt in die Oberfläche.
- Halte den Inhalt kompakt. Eine Aufteilung in mehrere Absätze oder eine
  Überschrift ist nicht nötig.
- Gib dem Trigger ein aussagekräftiges `aria-label`. Bevorzugt über die
  übersetzte `subject` Property, alternativ als vollständiges `aria-label`.

---

# Kombiniere mit …

## Combine

Benutze die [Combine](https://flow.mittwald.de/components/structure/combine) Component, um das
ContextualHelp z. B. neben einem [Text](https://flow.mittwald.de/components/content/text) zu platzieren.

```tsx
import {
  Combine,
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  Text,
} from "@mittwald/flow-react-components";

<Combine>
  <Text>mail.agenturserver.de</Text>

  <ContextualHelpTrigger subject="mail.agenturserver.de">
    <Button />

    <ContextualHelp>
      <Text>
        Hier wird die URL des Servers angezeigt, der für den
        E-Mail-Versand genutzt wird.
      </Text>
    </ContextualHelp>
  </ContextualHelpTrigger>
</Combine>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `UNSTABLE_portalContainer` _(deprecated)_ | `Element` | `document.body` | The container element in which the overlay portal will be placed. This may have unknown behavior depending on where it is portalled to. @deprecated - Use a parent UNSAFE_PortalProvider to set your portal container instead. |
| `arrowBoundaryOffset` | `number` | `0` | The minimum distance the arrow's edge should be from the edge of the overlay element. |
| `arrowRef` | `RefObject<Element \| null>` | - | A ref for the popover arrow element. |
| `boundaryElement` | `Element` | `document.body` | Element that that serves as the positioning boundary. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<PopoverRenderProps>` | `'react-aria-Popover'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `containerPadding` | `number` | `12` | The placement padding that should be applied between the element and its surrounding container. |
| `controller` | `OverlayController` | - | An overlay controller to control the popover state. |
| `crossOffset` | `number` | `0` | The additional offset applied along the cross axis between the element and its anchor element. |
| `defaultOpen` _(deprecated)_ | `boolean` | - | Whether the overlay is open by default (uncontrolled). @deprecated Use `isDefaultOpen` instead. |
| `dir` | `string` | - | - |
| `getTargetRect` | `((target: Element) => DOMRect \| null)` | `target.getBoundingClientRect()` | Overrides the target element's bounding rectangle. Useful for positioning relative to a specific point such as the mouse cursor (e.g. context menus) or text selection. @param target - The target element. |
| `hidden` | `boolean` | - | - |
| `inert` | `boolean` | - | - |
| `isDefaultOpen` | `boolean` | `false` | Whether the popover is open initially. Use it for an uncontrolled popover. |
| `isDialogContent` | `boolean` | - | Whether the popover contains a dialog. |
| `isEntering` | `boolean` | - | Whether the popover is currently performing an entry animation. |
| `isExiting` | `boolean` | - | Whether the popover is currently performing an exit animation. |
| `isKeyboardDismissDisabled` | `boolean` | `false` | Whether pressing the escape key to close the popover should be disabled. Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided. |
| `isNonModal` | `boolean` | - | Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies. Most popovers should not use this option as it may negatively impact the screen reader experience. Only use with components such as combobox, which are designed to handle this situation carefully. |
| `isOpen` | `boolean` | - | Whether the popover is open. Use it to control the popover state – then `onOpenChange` must update the state this value comes from. |
| `lang` | `string` | - | - |
| `maxHeight` | `number` | - | The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height. |
| `offset` | `number` | `8` | The additional offset applied along the main axis between the element and its anchor element. |
| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `'bottom'` | The placement of the element with respect to its anchor element. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `scrollRef` | `RefObject<Element \| null>` | `overlayRef` | A ref for the scrollable region within the overlay. |
| `shouldCloseOnInteractOutside` | `((element: Element) => boolean)` | - | When user interacts with the argument element outside of the popover ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the popover. By default, onClose will always be called on interaction outside the popover ref. |
| `shouldFlip` | `boolean` | `true` | Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely. |
| `shouldSkipAnimation` | `boolean` | - | Whether the popover should appear and disappear without an entry or exit animation. This is used by components such as PreviewTrigger to skip animations when quickly swapping between overlays. |
| `shouldUpdatePosition` | `boolean` | `true` | Whether the overlay should update its position automatically. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `trigger` | `string` | - | The name of the component that triggered the popover. This is reflected on the element as the `data-trigger` attribute, and can be used to provide specific styles for the popover depending on which element triggered it. |
| `triggerRef` | `RefObject<Element \| null>` | - | The ref for the element which the popover positions itself with respect to. When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone. |
| `width` | `string \| number` | - | A fixed width for the popover. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlurWithin` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the target element and all descendants lose focus. |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onFocusWithin` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the target element or a descendant receives focus. |
| `onFocusWithinChange` | `((isFocusWithin: boolean) => void)` | - | Handler that is called when the the focus within state changes. |
| `onOpenChange` | `((isOpen: boolean) => void)` | - | Called with the new open state whenever the popover is opened or closed – on every path, including a close triggered through the controller. It only reports the change; it never performs or suppresses it. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--contextual-help--max-width` | `500px` |

---

# LightBox

Eine LightBox zeigt Bilder vergrößert als Overlay mit abgedunkeltem Hintergrund.

> **mStudio-Extensions:** Importiere `LightBox` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `controller`, `wrapWith`.

```tsx
import {
  Button,
  Image,
  LightBox,
  LightBoxTrigger,
} from "@mittwald/flow-react-components";

<LightBoxTrigger>
  <Button>Open LightBox</Button>
  <LightBox>
    <Image src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg" />
  </LightBox>
</LightBoxTrigger>
```

---

# Best Practices

- Kennzeichne die Aktions-[Icons](https://flow.mittwald.de/components/content/icon) klar und eindeutig.
  So vermeidest du Missverständnisse, etwa bei Löschen oder Herunterladen.
- Pflege sinnvolle Alt-Texte für die Bilder. Das sichert die
  Screenreader-Unterstützung.

---

# FitScreen

Standardmäßig passt sich der Inhalt der LightBox an die Bildschirmgröße an. Wird
die Property `fitScreen` auf `false` gesetzt, wird der Inhalt in seiner vollen
Höhe dargestellt. Falls der verfügbare Platz nicht ausreicht, erscheint eine
vertikale Scrollbar. Dieses Verhalten ist besonders hilfreich bei der
Darstellung von Inhalten mit großer vertikaler Ausdehnung, wie z. B.
mehrseitigen PDFs.

```tsx
import {
  Button,
  Image,
  LightBox,
  LightBoxTrigger,
} from "@mittwald/flow-react-components";

<LightBoxTrigger>
  <Button>Open LightBox</Button>
  <LightBox fitScreen={false}>
    <Image src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg" />
  </LightBox>
</LightBoxTrigger>
```

---

# Galerie

Innerhalb der LightBox kann eine `LightBoxGallery` verwendet werden. Diese kann
mit `LightBoxGalleryItems` gefüllt werden, welche die Platzierung von
[Images](https://flow.mittwald.de/components/content/image) und
[ActionGroups](https://flow.mittwald.de/components/actions/action-group) unterstützen.

```tsx
import {
  Button,
  Flex,
  Image,
  LightBox,
  LightBoxTrigger,
  ActionGroup,
  LightBoxGallery,
  LightBoxGalleryItem,
  IconDownload,
} from "@mittwald/flow-react-components";

export default () => {
  const images = [
    "https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg",
    "https://cdn.shopify.com/s/files/1/2022/6883/products/IMG_2002_250x250@2x.JPG?v=1538235544",
  ];

  return (
    <Flex gap="m">
      {images.map((src, index) => (
        <LightBoxTrigger key={index}>
          <Button>
            <Image
              alt=""
              src={src}
              height="100px"
              withBorder
            />
          </Button>
          <LightBox>
            <LightBoxGallery defaultIndex={index}>
              {images.map((src) => (
                <LightBoxGalleryItem key={src}>
                  <Image src={src} />
                  <ActionGroup>
                    <Button aria-label="Herunterladen">
                      <IconDownload />
                    </Button>
                  </ActionGroup>
                </LightBoxGalleryItem>
              ))}
            </LightBoxGallery>
          </LightBox>
        </LightBoxTrigger>
      ))}
    </Flex>
  );
}
```

---

# Kombiniere mit …

## ActionGroup

In der LightBox kann eine [ActionGroup](https://flow.mittwald.de/components/actions/action-group)
verwendet werden, diese richtet sich automatisch vertikal am Bild aus.

```tsx
import {
  ActionGroup,
  Button,
  IconDelete,
  IconDownload,
  Image,
  LightBox,
  LightBoxTrigger,
} from "@mittwald/flow-react-components";

<LightBoxTrigger>
  <Button>Open LightBox</Button>
  <LightBox>
    <Image src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg" />
    <ActionGroup>
      <Button>
        <IconDownload />
      </Button>
      <Button>
        <IconDelete />
      </Button>
    </ActionGroup>
  </LightBox>
</LightBoxTrigger>
```

## Image

Als Trigger kann auch das [Image](https://flow.mittwald.de/components/content/image) selbst verwendet
werden. Kombiniere dazu `<Button />` mit `<Image />`.

```tsx
import {
  Button,
  Image,
  LightBox,
  LightBoxTrigger,
} from "@mittwald/flow-react-components";

<LightBoxTrigger>
  <Button>
    <Image
      width={100}
      withBorder
      alt="mittwald"
      src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
    />
  </Button>
  <LightBox>
    <Image
      alt="mittwald"
      src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
    />
  </LightBox>
</LightBoxTrigger>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `controller` | `OverlayController` | - | An overlay controller to control the light box state. |
| `fitScreen` | `boolean` | `true` | Whether content can be displayed larger than the available space in the screen. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--light-box--max-width` | `calc(100dvw - 64px)` |
| `--light-box--max-height` | `calc(100dvh - 64px)` |
| `--light-box--max-width-mobile` | `calc(100dvw - 24px)` |
| `--light-box--max-height-mobile` | `calc(100dvh - 24px)` |
| `--light-box--spacing` | `16px` |
| `--light-box--indicator-spacing` | `4px` |
| `--light-box--indicator-size` | `16px` |
| `--light-box--indicator-border-width` | `2px` |
| `--light-box--indicator-border-style` | `solid` |
| `--light-box--indicator-corner-radius` | `50%` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--light-box--content-color` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |

---

# Modal

Ein Modal zeigt Inhalte zentriert als Overlay über der Hauptseite.

> **mStudio-Extensions:** Importiere `Modal` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `controller`, `wrapWith`.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  Content,
  Heading,
  Label,
  Modal,
  ModalTrigger,
  Section,
  Text,
  TextField,
} from "@mittwald/flow-react-components";
import { sleepLong } from "@/content/components/actions/action/examples/lib";

<ModalTrigger>
  <Button>Modal öffnen</Button>
  <Modal>
    <Heading>Organisation anlegen</Heading>
    <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 isRequired>
          <Label>Organisationsname</Label>
        </TextField>
      </Section>
    </Content>
    <ActionGroup>
      <Action closeModal>
        <Action onAction={sleepLong}>
          <Button color="success">
            Organisation anlegen
          </Button>
        </Action>
        <Button variant="soft" color="secondary">
          Abbrechen
        </Button>
      </Action>
    </ActionGroup>
  </Modal>
</ModalTrigger>
```

---

# Best Practices

- Öffne ein Modal nur als Reaktion auf eine bewusste Aktion des Nutzers. Ein
  unerwartet erscheinendes Modal unterbricht ihn und zieht sofort seine gesamte
  Aufmerksamkeit auf sich.
- Nutze für umfangreiche Prozesse ein OffCanvas. Ein Modal bleibt so kurz und
  fokussiert.
- Formuliere eine prägnante Überschrift und halte den Inhalt leicht
  verständlich.
- Strukturiere den Content mit [Section](https://flow.mittwald.de/components/structure/section). Content
  bringt nur den Innenabstand des Modals mit, die Abstände zwischen den
  Komponenten kommen von der Section.
- Vermeide es, mehrere Modals übereinander zu stapeln. Ein Modal über einem
  anderen ist im Einzelfall vertretbar, doch mit jeder weiteren Ebene verliert
  der Nutzer die Orientierung.

---

# OffCanvas

Nutze die Variante OffCanvas für Modals mit viel Inhalt, bei dem gescrollt
werden müsste.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  ColumnLayout,
  Content,
  DatePicker,
  FieldDescription,
  Heading,
  Label,
  Modal,
  ModalTrigger,
  RadioButton,
  RadioGroup,
  Section,
  Text,
  TextField,
} from "@mittwald/flow-react-components";
import { sleepLong } from "@/content/components/actions/action/examples/lib";

<ModalTrigger>
  <Button>OffCanvas öffnen</Button>
  <Modal size="m" offCanvas>
    <Heading>SFTP-Benutzer anlegen</Heading>
    <Content>
      <Section>
        <Heading>Beschreibung</Heading>
        <Text>
          Mit einem SFTP-Benutzer kannst du dich mit deinem
          Projekt verbinden, um z.B. Dateien hochzuladen.
        </Text>
        <ColumnLayout m={[1, 1]}>
          <TextField isRequired>
            <Label>Bezeichnung</Label>
          </TextField>
          <DatePicker>
            <Label>Ablaufdatum</Label>
            <FieldDescription>
              Nach diesem Datum wird der SFTP-Benutzer
              gelöscht.
            </FieldDescription>
          </DatePicker>
        </ColumnLayout>

        <Heading>Authentifizierung</Heading>
        <Text>
          Wähle zwischen der Authentifikation per Passwort
          oder über einen SSH-Key.
        </Text>
        <RadioGroup
          defaultValue="password"
          aria-label="Authentifizierung"
        >
          <RadioButton value="password">
            Passwort
          </RadioButton>
          <RadioButton value="ssh">SSH-Key</RadioButton>
        </RadioGroup>
        <ColumnLayout s={[1, 1]}>
          <TextField isRequired>
            <Label>Passwort</Label>
          </TextField>
        </ColumnLayout>

        <Heading>Berechtigungen</Heading>
        <Text>
          Wähle hier die Berechtigungen aus, mit denen der
          SFTP-Benutzer zugreifen darf.
        </Text>
        <RadioGroup
          s={[1, 1]}
          defaultValue="read&write"
          aria-label="Berechtigungen"
        >
          <RadioButton value="write">
            <Text>Lesezugriff</Text>
            <Content>
              Der SFTP-Benutzer kann Dateien einsehen und
              herunterladen.
            </Content>
          </RadioButton>
          <RadioButton value="read&write">
            <Text>Lese- und Schreibzugriff</Text>
            <Content>
              Der SFTP-Benutzer kann Dateien einsehen,
              bearbeiten, hoch und herunterladen.
            </Content>
          </RadioButton>
        </RadioGroup>

        <Heading>Verzeichnisauswahl</Heading>
        <Text>
          Hier legst du das Verzeichnis fest, auf das der
          SFTP-Benutzer Zugriff hat.
        </Text>
        <TextField isRequired>
          <Label>Pfad</Label>
        </TextField>
      </Section>
    </Content>
    <ActionGroup>
      <Action closeModal>
        <Action onAction={sleepLong}>
          <Button color="success">
            SFTP-Benutzer anlegen
          </Button>
        </Action>
        <Button variant="soft" color="secondary">
          Abbrechen
        </Button>
      </Action>
    </ActionGroup>
  </Modal>
</ModalTrigger>
```

---

# Sizes

Ein Modal mit der Size **Small** (Breite 660 px) eignet sich gut für einfache
Abfragen oder Bestätigungsmodals. Ein Modal mit der Size **Medium** (Breite 900
px) wird für komplexere Dialoge verwendet.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  ColumnLayout,
  Content,
  DatePicker,
  FieldDescription,
  Heading,
  Label,
  Link,
  Modal,
  ModalTrigger,
  Option,
  RadioButton,
  RadioGroup,
  Section,
  Select,
  Switch,
  Text,
  TextField,
} from "@mittwald/flow-react-components";
import { sleepLong } from "@/content/components/actions/action/examples/lib";

export default () => {
  return (
    <>
      <ModalTrigger>
        <Button>Modal S</Button>
        <Modal size="s">
          <Heading>
            Möchtest du die Bestellung wirklich abbrechen?
          </Heading>
          <Content>
            <Section>
              <Text>
                Deine eingegebenen Daten werden nicht
                gespeichert.
              </Text>
            </Section>
          </Content>
          <ActionGroup>
            <Action closeModal>
              <Action onAction={sleepLong}>
                <Button color="danger">
                  Bestellung abbrechen
                </Button>
              </Action>
              <Button variant="soft" color="secondary">
                Bestellung fortsetzen
              </Button>
            </Action>
          </ActionGroup>
        </Modal>
      </ModalTrigger>

      <ModalTrigger>
        <Button>Modal M</Button>
        <Modal size="m">
          <Heading>Backup anlegen</Heading>
          <Content>
            <Section>
              <Text>
                Das Backup enthält alle Dateien deines
                Dateisystems und den Inhalt deiner
                Datenbanken. Dei Erstellung eines Backups
                dauert in der Regel einige Minuten.
              </Text>
              <ColumnLayout m={[1, 1]}>
                <TextField>
                  <Label>Beschreibung</Label>
                </TextField>
                <Select isRequired>
                  <Label>Speicherdauer</Label>
                  <Option>7 Tage</Option>
                  <Option>14 Tage</Option>
                  <Option>30 Tage</Option>
                  <Option>6 Monate</Option>
                  <Option>12 Monate</Option>
                </Select>
              </ColumnLayout>
            </Section>
          </Content>
          <ActionGroup>
            <Action closeModal>
              <Action onAction={sleepLong}>
                <Button color="success">
                  Backup anlegen
                </Button>
              </Action>
              <Button variant="soft" color="secondary">
                Abbrechen
              </Button>
            </Action>
          </ActionGroup>
        </Modal>
      </ModalTrigger>

      <ModalTrigger>
        <Button>OffCanvas S</Button>
        <Modal size="s" offCanvas>
          <Heading>Dashboard-Einstellungen</Heading>
          <Content>
            <Section>
              <Heading>Widget-Sichtbarkeit</Heading>
              <Text>
                Aktiviere und deaktiviere die Widgets, die
                du wirklich benötigst. So bestimmst du
                selbst, wie dein Dashboard aussehen soll.
              </Text>
              <ColumnLayout s={[1]} gap="xl">
                <ColumnLayout s={[1]} gap="s">
                  <Switch>
                    <Label>Erste Schritte</Label>
                  </Switch>
                  <Text>
                    Im Onboarding erklären wir dir alles
                    Wichtige im mStudio.
                  </Text>
                  <Link>Erste Schritte starten</Link>
                </ColumnLayout>

                <ColumnLayout s={[1]} gap="s">
                  <Switch defaultSelected>
                    <Label>mittwald Status</Label>
                  </Switch>
                  <Text>
                    Wir informieren dich über Wartung und
                    Störungen.
                  </Text>
                </ColumnLayout>

                <ColumnLayout s={[1]} gap="s">
                  <Switch>
                    <Label>mittwald Produkt-Slider</Label>
                  </Switch>
                  <Text>
                    Im Produkt-Slider erhälst du
                    Informationen und einen schnellen
                    Einstieg in weitere mittwald Produkte.
                  </Text>
                </ColumnLayout>

                <ColumnLayout s={[1]} gap="s">
                  <Switch defaultSelected>
                    <Label>Neue Features</Label>
                  </Switch>
                  <Text>
                    Wir entwickeln das mStudio stetig weiter
                    Alle kommenden Features findest du auf
                    der <Link>Roadmap</Link>.
                  </Text>
                  <Link>Changelog öffnen</Link>
                </ColumnLayout>

                <ColumnLayout s={[1]} gap="s">
                  <Switch defaultSelected>
                    <Label>Neue Blogbeiträge</Label>
                  </Switch>
                  <Text>
                    Wir zeigen dir den neuesten mittwald
                    Blogartikel an.
                  </Text>
                  <Link>Blogartikel öffnen</Link>
                </ColumnLayout>

                <ColumnLayout s={[1]} gap="s">
                  <Switch>
                    <Label>Lastschift Hinweis</Label>
                  </Switch>
                  <Text>
                    Wir informieren über die neue
                    Möglichkeit, deine Rechnungen per
                    Lastschrift zu bezahlen.
                  </Text>
                </ColumnLayout>
              </ColumnLayout>
            </Section>
          </Content>
          <ActionGroup>
            <Action closeModal>
              <Button variant="soft" color="secondary">
                Schließen
              </Button>
            </Action>
          </ActionGroup>
        </Modal>
      </ModalTrigger>

      <ModalTrigger>
        <Button>OffCanvas M</Button>
        <Modal size="m" offCanvas>
          <Heading>SFTP-Benutzer anlegen</Heading>
          <Content>
            <Section>
              <Heading>Beschreibung</Heading>
              <Text>
                Mit einem SFTP-Benutzer kannst du dich mit
                deinem Projekt verbinden, um z.B. Dateien
                hochzuladen.
              </Text>
              <ColumnLayout m={[1, 1]}>
                <TextField isRequired>
                  <Label>Bezeichnung</Label>
                </TextField>
                <DatePicker>
                  <Label>Ablaufdatum</Label>
                  <FieldDescription>
                    Nach diesem Datum wird der SFTP-Benutzer
                    gelöscht.
                  </FieldDescription>
                </DatePicker>
              </ColumnLayout>

              <Heading>Authentifizierung</Heading>
              <Text>
                Wähle zwischen der Authentifikation per
                Passwort oder über einen SSH-Key.
              </Text>
              <RadioGroup
                defaultValue="password"
                aria-label="Authentifizierung"
              >
                <RadioButton value="password">
                  Passwort
                </RadioButton>
                <RadioButton value="ssh">
                  SSH-Key
                </RadioButton>
              </RadioGroup>
              <ColumnLayout s={[1, 1]}>
                <TextField isRequired>
                  <Label>Passwort</Label>
                </TextField>
              </ColumnLayout>

              <Heading>Berechtigungen</Heading>
              <Text>
                Wähle hier die Berechtigungen aus, mit denen
                der SFTP-Benutzer zugreifen darf.
              </Text>
              <RadioGroup
                s={[1, 1]}
                defaultValue="read&write"
                aria-label="Berechtigungen"
              >
                <RadioButton value="write">
                  <Text>Lesezugriff</Text>
                  <Content>
                    Der SFTP-Benutzer kann Dateien einsehen
                    und herunterladen.
                  </Content>
                </RadioButton>
                <RadioButton value="read&write">
                  <Text>Lese- und Schreibzugriff</Text>
                  <Content>
                    Der SFTP-Benutzer kann Dateien einsehen,
                    bearbeiten, hoch und herunterladen.
                  </Content>
                </RadioButton>
              </RadioGroup>

              <Heading>Verzeichnisauswahl</Heading>
              <Text>
                Hier legst du das Verzeichnis fest, auf das
                der SFTP-Benutzer Zugriff hat.
              </Text>
              <TextField isRequired>
                <Label>Pfad</Label>
              </TextField>
            </Section>
          </Content>
          <ActionGroup>
            <Action closeModal>
              <Action onAction={sleepLong}>
                <Button color="success">
                  SFTP-Benutzer anlegen
                </Button>
              </Action>
              <Button variant="soft" color="secondary">
                Abbrechen
              </Button>
            </Action>
          </ActionGroup>
        </Modal>
      </ModalTrigger>
    </>
  );
}
```

---

# Ungespeicherte Änderungen

Eingaben in einem Modal gehen beim Schließen verloren. Damit das nicht unbemerkt
passiert, kann bei Escape oder einem Klick außerhalb des Modals zuerst ein
Bestätigungs-Dialog erscheinen. Aktionen im Footer und der Close-Button in der
Überschrift schließen dagegen sofort.

Enthält das Modal eine
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form), passiert das
automatisch, sobald sie ungespeicherte Änderungen enthält. Soll eine einzelne
Form das nicht auslösen, setzt du an ihr
`confirmModalCloseOnUnsavedChanges={false}`. Ohne Form – oder wenn du selbst
entscheiden willst, wann es etwas zu verlieren gibt – setzt du `confirmOnClose`.

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

export default () => {
  const [description, setDescription] = useState("");

  return (
    <ModalTrigger>
      <Button>Modal öffnen</Button>

      <Modal
        confirmOnClose={description !== ""}
        onClose={() => setDescription("")}
      >
        <Heading>Projekt-Beschreibung</Heading>

        <Content>
          <Section>
            <Text>
              Gib eine Beschreibung ein und schließe das
              Modal anschließend mit Escape oder per Klick
              außerhalb – das Verwerfen der Änderungen muss
              bestätigt werden.
            </Text>

            <TextField
              value={description}
              onChange={setDescription}
            >
              <Label>Beschreibung</Label>
            </TextField>
          </Section>
        </Content>

        <ActionGroup>
          <Action closeModal>
            <Button color="success">Speichern</Button>
            <Button color="secondary" variant="soft">
              Abbrechen
            </Button>
          </Action>
        </ActionGroup>
      </Modal>
    </ModalTrigger>
  );
}
```

---

# Controller

Neben dem `<ModalTrigger />` kann das Modal auch über einen Controller gesteuert
werden.

Dieser Controller steht auch in Modals zur Verfügung, die über den ModalTrigger
geöffnet wurden.

```tsx
import {
  Action,
  ActionGroup,
  Button,
  Content,
  Heading,
  Label,
  Modal,
  Section,
  Text,
  TextField,
  useModalController,
} from "@mittwald/flow-react-components";
import { sleepLong } from "@/content/components/actions/action/examples/lib";

export default () => {
  const controller = useModalController();

  return (
    <>
      <Button onPress={controller.open}>
        Modal öffnen
      </Button>

      <Modal controller={controller}>
        <Heading>Organisation anlegen</Heading>
        <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 isRequired>
              <Label>Organisationsname</Label>
            </TextField>
          </Section>
        </Content>
        <ActionGroup>
          <Action closeModal>
            <Action onAction={sleepLong}>
              <Button color="success">
                Organisation anlegen
              </Button>
            </Action>
            <Button variant="soft" color="secondary">
              Abbrechen
            </Button>
          </Action>
        </ActionGroup>
      </Modal>
    </>
  );
}
```

---

# Kombiniere mit …

## React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component
[Form (React Hook Form)](https://flow.mittwald.de/components/react-hook-form/form).

```tsx
import {
  Action,
  ActionGroup,
  Button,
  Content,
  Heading,
  Label,
  Modal,
  Section,
  TextField,
  useModalController,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";

export default () => {
  const controller = useModalController();

  const form = useForm<{ name: string }>();

  const Field = typedField(form);

  const handleSubmit = async () => {
    /** ... submit logic */
    return () => {
      // Close after successful submission
      controller.close();
    };
  };

  return (
    <>
      <Button onPress={controller.open}>
        Modal öffnen
      </Button>

      <Modal controller={controller}>
        <Form form={form} onSubmit={handleSubmit}>
          <Heading>Organisation anlegen</Heading>

          <Content>
            <Section>
              <Field
                name="name"
                rules={{
                  required: "Bitte gib einen Namen ein",
                }}
              >
                <TextField>
                  <Label>Name</Label>
                </TextField>
              </Field>
            </Section>
          </Content>

          <ActionGroup>
            <SubmitButton>Speichern</SubmitButton>
            <Action closeModal>
              <Button color="secondary" variant="soft">
                Abbrechen
              </Button>
            </Action>
          </ActionGroup>
        </Form>
      </Modal>
    </>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `confirmOnClose` | `boolean` | - | Whether closing the modal must be confirmed – use it to protect unsaved changes. `false` does not switch off the confirmation of a dirty `Form` inside the modal; set `confirmModalCloseOnUnsavedChanges={false}` on the `Form` for that. |
| `controller` | `OverlayController` | - | An overlay controller to control the modal state. |
| `isDefaultOpen` | `boolean` | `false` | Whether the overlay is open initially. Use it for an uncontrolled overlay. |
| `isDismissable` | `boolean` | - | Whether the modal can be closed by clicking outside of it. |
| `isOpen` | `boolean` | - | Whether the overlay is open. Use it to control the overlay state. |
| `offCanvas` | `boolean` | - | Whether the modal should be displayed as an off canvas. |
| `offCanvasOrientation` | `"left" \| "right"` | `"right"` | Whether the off canvas should be displayed on the right or left side of the screen. |
| `showCloseButton` | `boolean` | - | Whether the close button should be visible |
| `size` | `"s" \| "m" \| "l"` | `"s"` | The size of the modal. |
| `slot` | `string` | - | Accepts "actionConfirm" to use the modal as a confirmation modal for an action. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onClose` | `OverlayCloseHandler` | - | Called when the overlay is closed. |
| `onOpen` | `OverlayOpenHandler` | - | Called when the overlay is opened. |
| `onOpenChange` | `OverlayOpenStateHandler` | - | Called with the new open state whenever the overlay is opened or closed. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--modal--corner-radius` | `16px` |
| `--modal--padding` | `24px` |
| `--modal--padding-mobile` | `16px` |
| `--modal--tray-top-spacing` | `16px` |
| `--modal--size--s` | `660px` |
| `--modal--size--m` | `900px` |
| `--modal--size--l` | `1300px` |
| `--modal--border-width` | `1px` |
| `--modal--border-style` | `solid` |
| `--modal--header-padding-top` | `16px` |
| `--modal--off-canvas-max-width` | `calc(100dvw - 16px)` |
| `--modal--content-min-height` | `120px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--modal--background-color` | `#FFFFFF` | `#1B1F24` |
| `--modal--footer-background-color` | `#F4F8FC` | `#292F37` |
| `--modal--border-color` | `#E5EFF8` | `#3A434E` |

---

# Tooltip

Tooltips zeigen beim Hovern kurze Zusatzinformationen zu einem Element.

> **mStudio-Extensions:** Importiere `Tooltip` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`.

```tsx
import {
  Button,
  IconEdit,
  Tooltip,
  TooltipTrigger,
} from "@mittwald/flow-react-components";

<TooltipTrigger>
  <Button aria-label="Bearbeiten" variant="plain">
    <IconEdit />
  </Button>
  <Tooltip>Bearbeiten</Tooltip>
</TooltipTrigger>
```

---

# Best Practices

- Halte den Inhalt kurz und präzise, meist ein bis drei Wörter.
- Nutze den Tooltip nur für ergänzende Informationen. Wichtige Inhalte wie
  Fehlermeldungen oder Feedback gehören nicht hinein, da er zum Beispiel auf dem
  Smartphone unbemerkt bleibt.
- Verwende im Tooltip nur Text, keine interaktiven Inhalte wie
  [Buttons](https://flow.mittwald.de/components/actions/button) oder
  [Links](https://flow.mittwald.de/components/navigation/link).
- Lass den Tooltip die sichtbare Beschriftung ergänzen, nicht wiederholen.

---

# Delay

Tooltips erscheinen verzögert, damit sie beim Hovern über die Oberfläche nicht
aufblitzen. Über die `delay` Property des Triggers stehen zwei Verzögerungen zur
Auswahl.

- **Default (400 ms)** – Verwende ihn, wenn das Element ohne den Tooltip nicht
  verständlich ist – z. B. ein Button, der nur aus einem Icon besteht.
- **Long (1500 ms)** – Verwende ihn für ergänzende Informationen an Elementen,
  die bereits beschriftet sind. Die längere Verzögerung verhindert, dass der
  Tooltip ungewollt ablenkt.

```tsx
import {
  Button,
  IconEdit,
  Tooltip,
  TooltipTrigger,
} from "@mittwald/flow-react-components";

<>
  <TooltipTrigger>
    <Button aria-label="Bearbeiten" variant="plain">
      <IconEdit />
    </Button>
    <Tooltip>Bearbeiten</Tooltip>
  </TooltipTrigger>
  <TooltipTrigger delay="long">
    <Button variant="plain">Bearbeiten</Button>
    <Tooltip>Name und Beschreibung ändern</Tooltip>
  </TooltipTrigger>
</>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `UNSTABLE_portalContainer` _(deprecated)_ | `Element` | `document.body` | The container element in which the overlay portal will be placed. This may have unknown behavior depending on where it is portalled to. @deprecated - Use a parent UNSAFE_PortalProvider to set your portal container instead. |
| `arrowBoundaryOffset` | `number` | `0` | The minimum distance the arrow's edge should be from the edge of the overlay element. |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<TooltipRenderProps>` | `'react-aria-Tooltip'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `containerPadding` | `number` | `12` | The placement padding that should be applied between the element and its surrounding container. |
| `crossOffset` | `number` | `0` | The additional offset applied along the cross axis between the element and its anchor element. |
| `defaultOpen` | `boolean` | - | Whether the overlay is open by default (uncontrolled). |
| `dir` | `string` | - | - |
| `hidden` | `boolean` | - | - |
| `inert` | `boolean` | - | - |
| `isEntering` | `boolean` | - | Whether the tooltip is currently performing an entry animation. |
| `isExiting` | `boolean` | - | Whether the tooltip is currently performing an exit animation. |
| `isOpen` | `boolean` | - | Whether the element is rendered. |
| `lang` | `string` | - | - |
| `offset` | `number` | `0` | The additional offset applied along the main axis between the element and its anchor element. |
| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `'top'` | The placement of the tooltip with respect to the trigger. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `shouldFlip` | `boolean` | `true` | Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `triggerRef` | `RefObject<Element \| null>` | - | The ref for the element which the tooltip positions itself with respect to. When used within a TooltipTrigger this is set automatically. It is only required when used standalone. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onOpenChange` | `((isOpen: boolean) => void)` | - | Handler that is called when the overlay's open state changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--tooltip--padding-x` | `8px` |
| `--tooltip--padding-y` | `4px` |
| `--tooltip--font-size` | `0.875rem` |
| `--tooltip--max-width` | `300px` |
| `--tooltip--tooltip-to-trigger-spacing` | `8px` |
| `--tooltip--tip-size` | `8px` |
| `--tooltip--box-shadow` | `rgb(0 0 0 / 12.5%) 0 8px 16px` |
| `--tooltip--corner-radius` | `8px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--tooltip--background-color` | `#292F37` | `#F4F8FC` |
| `--tooltip--color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |

---

# Field

Die Field-Component integriert Flows Form Controls in React Hook Form.

> **mStudio-Extensions:** Importiere `Field` aus `@mittwald/flow-remote-react-components/react-hook-form`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import { useForm } from "react-hook-form";
import {
  Field,
  Form,
} from "@mittwald/flow-react-components/react-hook-form";
import {
  Label,
  TextField,
} from "@mittwald/flow-react-components";

export default () => {
  interface Values {
    name: string;
  }
  const form = useForm<Values>();

  return (
    <Form form={form} onSubmit={console.log}>
      <Field
        name="name"
        rules={{
          required: "Bitte gib einen Namen ein",
        }}
      >
        <TextField>
          <Label>Name</Label>
        </TextField>
      </Field>
    </Form>
  );
}
```

---

# typedField

Die `typedField(form)`-Factory erzeugt eine Field-Component, die an den Typ des
jeweiligen [Forms](https://flow.mittwald.de/components/react-hook-form/form) angepasst ist. Dadurch
führen beispielsweise unbekannte Field-Namen zu einem TypeScript-Fehler.

```tsx
import { useForm } from "react-hook-form";
import {
  Form,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import {
  Label,
  TextField,
} from "@mittwald/flow-react-components";

export default () => {
  interface Values {
    myField: string;
  }
  const form = useForm<Values>();

  // Only `myField` is allowed for name prop
  const Field = typedField(form);

  return (
    <Form form={form} onSubmit={console.log}>
      <Field name="myField">
        <TextField>
          <Label>Name</Label>
        </TextField>
      </Field>
    </Form>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `control` | `Control<T, any, T>` | - | - |
| `defaultValue` | `any` | - | - |
| `disabled` | `boolean` | - | - |
| `exact` | `boolean` | - | - |
| `name` _(required)_ | `string` | - | - |
| `rules` | `Omit<RegisterOptions<T, Path<T>>, "disabled" \| "valueAsNumber" \| "valueAsDate" \| "setValueAs">` | - | - |
| `shouldUnregister` | `boolean` | - | - |

---

# Form

Die Form-Component gruppiert Formularfelder, nutzbar nur mit React Hook Form.

> **mStudio-Extensions:** Importiere `Form` aus `@mittwald/flow-remote-react-components/react-hook-form`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import { useForm } from "react-hook-form";
import {
  Field,
  Form,
  ResetButton,
  SubmitButton,
} from "@mittwald/flow-react-components/react-hook-form";
import {
  ActionGroup,
  Label,
  Section,
  TextField,
} from "@mittwald/flow-react-components";

export default () => {
  interface Values {
    name: string;
  }
  const form = useForm<Values>();

  const handleSubmit = (values: Values) =>
    alert(JSON.stringify(values));

  return (
    <Form form={form} onSubmit={handleSubmit}>
      <Section>
        <Field
          name="name"
          rules={{
            required: "Bitte gib einen Namen ein",
          }}
        >
          <TextField>
            <Label>Name</Label>
          </TextField>
        </Field>
        <ActionGroup>
          <ResetButton>Zurücksetzen</ResetButton>
          <SubmitButton>Speichern</SubmitButton>
        </ActionGroup>
      </Section>
    </Form>
  );
}
```

---

# Aktionen nach Submit

Aktionen, die nach dem Submit ausgeführt werden sollen – zum Beispiel ein
Form-Reset oder ein Redirect – sollten im Return-Callback des Submit Handlers
erfolgen. Dieser Callback kann auch asynchron sein.

```tsx
const submitHandler = () => {
  // submit logic
  return () => {
    form.reset();
  };
};
```

```tsx
import { sleepLong } from "@/content/components/actions/action/examples/lib";
import {
  ActionGroup,
  Label,
  Section,
  TextField,
} from "@mittwald/flow-react-components";
import {
  Field,
  Form,
  ResetButton,
  SubmitButton,
} from "@mittwald/flow-react-components/react-hook-form";
import { useForm } from "react-hook-form";

export default () => {
  interface Values {
    name: string;
  }
  const form = useForm<Values>({
    defaultValues: {
      name: "",
    },
  });

  return (
    <Form
      form={form}
      onSubmit={async () => {
        await sleepLong();
        // recommended way to reset forms after submit
        return () => {
          form.reset();
        };
      }}
    >
      <Section>
        <Field
          name="name"
          rules={{
            required: "The project name is required",
          }}
        >
          <TextField>
            <Label>Name</Label>
          </TextField>
        </Field>
        <ActionGroup>
          <ResetButton>Zurücksetzen</ResetButton>
          <SubmitButton>Speichern</SubmitButton>
        </ActionGroup>
      </Section>
    </Form>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoReset` | `boolean \| FormAutoResetOptions` | `true` | When the form is reset to its default values. `true` resets it after the surrounding modal has closed, `false` never resets it. |
| `confirmModalCloseOnUnsavedChanges` | `boolean` | `true` | Whether closing the surrounding modal must be confirmed while the form has unsaved changes. Overrides `Form.confirmModalCloseOnUnsavedChanges` of the `ComponentDefaultsProvider`. |
| `form` _(required)_ | `UseFormReturn<F>` | - | The react-hook-form instance returned by `useForm()`. |
| `formComponent` | `FC<Omit<FormComponentType, "ref">>` | - | The component rendered as the form element. Use it to render the form with a routers form component. Defaults to a plain `<form />`. |
| `isReadOnly` | `boolean` | `false` | Whether all fields of the form can be read but not edited. |
| `submitController` | `{ submit: { (): Promise<void>; set(newSubmitHandler: () => void \| Promise<void>): void; extend(submitController: ...): ...; }; }` | - | A controller to submit the form from outside of it. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onSubmit` _(required)_ | `FormOnSubmitHandler<F>` | - | Called with the validated form values when the form is submitted. Returning a promise keeps the submit button pending until it settles. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# FormRootError

Die FormRootError-Component zeigt Fehler auf Form-Ebene an.

> **mStudio-Extensions:** `FormRootError` ist in `@mittwald/flow-remote-react-components` nicht verfügbar.

```tsx
import { useForm } from "react-hook-form";
import {
  Field,
  Form,
  FormRootError,
  SubmitButton,
} from "@mittwald/flow-react-components/react-hook-form";
import {
  ActionGroup,
  Label,
  Section,
  TextField,
} from "@mittwald/flow-react-components";

export default () => {
  interface Values {
    email: string;
    password: string;
  }
  const form = useForm<Values>({
    defaultValues: {
      email: "max@mustermann.de",
      password: "password",
    },
  });

  return (
    <Section>
      <Form
        form={form}
        onSubmit={() => {
          form.setError("root", {
            message: "Login fehlgeschlagen",
          });
        }}
      >
        <Field
          name="email"
          rules={{
            required: "Bitte gib eine E-Mail ein",
          }}
        >
          <TextField>
            <Label>E-Mail</Label>
          </TextField>
        </Field>
        <Field
          name="password"
          rules={{
            required: "Bitte gib ein Passwort ein",
          }}
        >
          <TextField type="password">
            <Label>Passwort</Label>
          </TextField>
        </Field>
        <FormRootError />
        <ActionGroup>
          <SubmitButton>Speichern</SubmitButton>
        </ActionGroup>
      </Form>
    </Section>
  );
}
```

---

# Eigener Inhalt

Ohne Children zeigt die FormRootError die `message` des Root-Fehlers als Alert
an. Children ersetzen diesen Alert, zum Beispiel für einen Alert mit Heading und
Text. Sie werden nur gerendert, solange ein Root-Fehler gesetzt ist. Als
Funktion erhalten sie den Root-Fehler und können den Inhalt so nach dessen
`type` wählen.

```tsx
import { useForm } from "react-hook-form";
import {
  Field,
  Form,
  FormRootError,
  SubmitButton,
} from "@mittwald/flow-react-components/react-hook-form";
import {
  ActionGroup,
  Alert,
  Heading,
  Label,
  Section,
  Text,
  TextField,
} from "@mittwald/flow-react-components";

export default () => {
  interface Values {
    image: string;
  }
  const form = useForm<Values>({
    defaultValues: {
      image: "ghcr.io/mittwald/example:latest",
    },
  });

  return (
    <Section>
      <Form
        form={form}
        onSubmit={() => {
          form.setError("root", {
            type: "invalidRegistryCredentials",
          });
        }}
      >
        <Field name="image">
          <TextField>
            <Label>Image</Label>
          </TextField>
        </Field>
        <FormRootError>
          {(error) =>
            error.type === "invalidRegistryCredentials" && (
              <Alert status="danger">
                <Heading>Falsche Zugangsdaten</Heading>
                <Text>
                  Das Image kann nicht heruntergeladen
                  werden, da für die Registry falsche
                  Zugangsdaten hinterlegt sind.
                </Text>
              </Alert>
            )
          }
        </FormRootError>
        <ActionGroup>
          <SubmitButton>Container anlegen</SubmitButton>
        </ActionGroup>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | Custom content shown instead of the default alert. Rendered only while a root error is set. A function receives the root error, e.g. to pick the content by its `type`. |

---

# SubmitButton

Der SubmitButton dient in Verbindung mit React Hook Form zum Absenden von Formularen.

> **mStudio-Extensions:** Importiere `SubmitButton` aus `@mittwald/flow-remote-react-components/react-hook-form`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import { useForm } from "react-hook-form";
import {
  Field,
  Form,
  SubmitButton,
} from "@mittwald/flow-react-components/react-hook-form";
import {
  Combine,
  Label,
  TextField,
} from "@mittwald/flow-react-components";

export default () => {
  interface Values {
    name: string;
  }
  const form = useForm<Values>();

  const handleSubmit = (values: Values) =>
    alert(JSON.stringify(values));

  return (
    <Form form={form} onSubmit={handleSubmit}>
      <Combine>
        <Field
          name="name"
          rules={{
            required: "Bitte gib einen Namen ein",
          }}
        >
          <TextField>
            <Label>Name</Label>
          </TextField>
        </Field>

        <SubmitButton>Speichern</SubmitButton>
      </Combine>
    </Form>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
| `children` | `ReactNode` | - | The children of the component. A function may be provided to alter the children based on component state. |
| `className` | `ClassNameOrFunction<ButtonRenderProps>` | `'react-aria-Button'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `color` | `"dark" \| "light" \| "dark-static" \| "light-static" \| "success" \| "danger" \| "primary" \| "secondary"` | `"primary"` | The color of the button. |
| `dir` | `string` | - | - |
| `excludeFromTabOrder` | `boolean` | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| `form` | `string` | - | The `<form>` element to associate the button with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#form). |
| `formAction` | `string \| ((formData: FormData) => void \| Promise<void>)` | - | The URL that processes the information submitted by the button. Overrides the action attribute of the button's form owner. |
| `formEncType` | `string` | - | Indicates how to encode the form data that is submitted. |
| `formMethod` | `string` | - | Indicates the HTTP method used to submit the form. |
| `formNoValidate` | `boolean` | - | Indicates that the form is not to be validated when it is submitted. |
| `formTarget` | `string` | - | Overrides the target attribute of the button's form owner. |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the button is disabled. |
| `isFailed` | `boolean` | - | Whether the button is in a failed state. |
| `isPending` | `boolean` | - | Whether the button is in a pending state. |
| `isReadOnly` | `boolean` | - | Whether the button is in a read only state. |
| `isSucceeded` | `boolean` | - | Whether the button is in a succeeded state. |
| `lang` | `string` | - | - |
| `name` | `string` | - | Submitted as a pair with the button's value as part of the form data. |
| `preventFocusOnPress` | `boolean` | - | Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `showFeedback` | `boolean` | - | Whether success feedback is shown after the action succeeded. Asynchronous actions show feedback by default; set `false` to suppress it. |
| `size` | `"s" \| "m"` | `"m"` | The size of the button. |
| `slot` | `string` | - | Slot for button placement in action groups: `primary` (at the end), `secondary` (before the primary action) or `abort` (at the start). Without a slot, an action group places the colors primary, success and danger in `primary` and every other color in `abort`. A secondary-colored button that does not abort therefore needs `slot="secondary"`. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `type` | `"button" \| "submit" \| "reset"` | `'button'` | The behavior of the button when used in an HTML form. |
| `value` | `string` | - | The value associated with the button's name when it's submitted with the form data. |
| `variant` | `"solid" \| "plain" \| "soft" \| "outline"` | `"solid"` | The visual variant of the button. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onClick` | `((e: MouseEvent<FocusableElement, MouseEvent>) => void)` | - | **Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions. |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onHoverChange` | `((isHovering: boolean) => void)` | - | Handler that is called when the hover state changes. |
| `onHoverEnd` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction ends. |
| `onHoverStart` | `((e: HoverEvent) => void)` | - | Handler that is called when a hover interaction starts. |
| `onKeyDown` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is pressed. |
| `onKeyUp` | `((e: KeyboardEvent) => void)` | - | Handler that is called when a key is released. |
| `onPress` | `((e: PressEvent) => void)` | - | Handler that is called when the press is released over the target. |
| `onPressChange` | `((isPressed: boolean) => void)` | - | Handler that is called when the press state changes. |
| `onPressEnd` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. |
| `onPressStart` | `((e: PressEvent) => void)` | - | Handler that is called when a press interaction starts. |
| `onPressUp` | `((e: PressEvent) => void)` | - | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-controls` | `string` | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| `aria-current` | `boolean \| "step" \| "false" \| "true" \| "page" \| "location" \| "date" \| "time"` | - | Indicates whether this element represents the current item within a container or set of related elements. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-disabled` | `boolean` | - | Disables button but keeps it focusable. |
| `aria-expanded` | `boolean \| "false" \| "true"` | - | Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed. |
| `aria-haspopup` | `boolean \| "false" \| "true" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` | - | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |
| `aria-pressed` | `boolean \| "false" \| "true" \| "mixed"` | - | Indicates the current "pressed" state of toggle buttons. |

---

# Alert

Ein Alert macht den User visuell hervorgehoben auf wichtige, nicht ignorierbare Informationen aufmerksam.

> **mStudio-Extensions:** Importiere `Alert` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<Alert>
  <Heading>E-Mail-Adresse wurde archiviert</Heading>
</Alert>
```

---

# Best Practices

- Setze einen Alert nur ein, wenn der Inhalt eine hohe Aufmerksamkeit verlangt.
  Für rein informative Hinweise reicht oft ein unauffälligeres Element.
- Wähle den Schweregrad passend zur Bedeutung der Meldung. Welcher Status wofür
  steht, beschreibt das
  [Informationskonzept](https://flow.mittwald.de/foundations/content-guidelines/informationskonzept).
- Formuliere den Text klar, prägnant und lösungsorientiert. Verzichte auf
  Fachbegriffe und Schuldzuweisungen und beachte die
  [Content Guidelines für Fehlermeldungen](https://flow.mittwald.de/foundations/content-guidelines/fehlermeldungen).
- Biete nach Möglichkeit eine Handlungsmöglichkeit an. Zum Beispiel über einen
  [Button](https://flow.mittwald.de/components/actions/button) oder [Link](https://flow.mittwald.de/components/navigation/link).

## Alert vs. AccentBox

Alerts und [AccentBoxen](https://flow.mittwald.de/components/structure/accent-box) dienen beide dazu,
dem User zusätzliche Informationen bereitzustellen. Eine einfache Faustregel
hilft bei der Entscheidung: Kann die Information ignoriert werden, ohne negative
Folgen? Dann ist eine AccentBox die richtige Wahl. Wenn das Ignorieren hingegen
zu Problemen führen könnte – etwa bei sicherheitsrelevanten Hinweisen oder
wichtigen Systemmeldungen – sollte ein Alert mit entsprechendem Status verwendet
werden.

**Verwende Alerts, um z. B. ...**

- den User auf sicherheits- oder funktionsrelevante Informationen hinzuweisen.
- vor möglichen Problemen oder Systemzuständen zu warnen.
- dringende oder aktionsrelevante Statusmeldungen zu kommunizieren.

**Verwende AccentBoxen, um z. B. ...**

- ergänzende, aber nicht kritische Hinweise anzuzeigen.
- kontextuelle Informationen oder Tipps zu geben.
- visuell strukturierende Inhalte einzubetten, ohne zu unterbrechen.

---

# Mit Inhalt

Über den Content beschreibst du zuerst die Ursache – was ist passiert und welche
Folge ergibt sich – und anschließend, was der User tun kann. Wenn möglich, biete
ihm eine Möglichkeit, sein Problem zu lösen, über einen
[Link](https://flow.mittwald.de/components/navigation/link) oder einen
[Button](https://flow.mittwald.de/components/actions/button). Eingefügte Buttons werden automatisch in
der Größe **Small** dargestellt, um ein ausgewogenes Gesamtbild zu
gewährleisten.

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

<Alert>
  <Heading>E-Mail-Empfang wurde deaktiviert</Heading>
  <Content>
    Der Empfang der E-Mails für dieses Postfach ist aufgrund
    fehlerhafter MX-Records deaktiviert. Bitte setze die
    richtigen Mailserver. Bei einer Neuregistrierung einer
    Domain kann es einige Minuten dauern, bis die MX-Records
    global im DNS verfügbar sind. Die E-Mail-Adresse wird in
    diesem Fall automatisch aktiviert.
    <Button>MX-Records anpassen</Button>
  </Content>
</Alert>
```

---

# Status

Je nach Anwendungsfall stehen verschiedene Status-Farben zur Auswahl:

- **Info** – Allgemeine Systemzustände oder laufende Prozesse, die keine Aktion
  erfordern.
- **Warning** – Hinweise auf mögliche Risiken mit einer klaren
  Handlungsempfehlung.
- **Danger** – Akute Fehlerzustände oder kritische Probleme, die sofortige
  Aufmerksamkeit erfordern.
- **Success** – Abgeschlossene, erfolgreiche oder positiv bewertete Zustände.
- **Unavailable** – Zustände aufgrund von nicht verfügbaren oder gelöschten
  Inhalten.

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

<>
  <Alert status="info">
    <Heading>E-Mail-Adresse wurde archiviert</Heading>
    <Content>
      Da deine Domain gelöscht wurde, wurde diese
      E-Mail-Adresse archiviert. Um E-Mails empfangen und
      senden zu können musst du die Adresse wieder
      umbenennen.
    </Content>
  </Alert>

  <Alert status="warning">
    <Heading>Dein Speicher ist fast voll</Heading>
    <Content>
      Dein Speicher ist zu über 80% belegt. Wir empfehlen
      dir deinen Speicherplatz zu erweitern, um Problemen
      vorzubeugen.
    </Content>
  </Alert>

  <Alert status="danger">
    <Heading>
      Es konnte kein SSL-Zertifikat ausgestellt werden
    </Heading>
    <Content>
      Für diese Domain konnte kein SSL-Zertifikat
      ausgestellt werden, da die Domain per IP nicht auf
      deine Server-IP zeigt.
    </Content>
  </Alert>

  <Alert status="success">
    <Heading>Deine App wurde aktualisiert</Heading>
    <Content>
      Deine App wurde erfolgreich auf die neueste Version
      aktualisiert.
    </Content>
  </Alert>

  <Alert status="unavailable">
    <Heading>Inhalte nicht gefunden</Heading>
    <Content>
      Die gewünschten Inhalte sind leider nicht verfügbar.
      Entweder wurden sie inzwischen gelöscht oder dir
      fehlen die notwendigen Berechtigungen.
    </Content>
  </Alert>
</>
```

---

# Position

Ein Alert sollte immer in unmittelbarem Zusammenhang mit dem betroffenen Inhalt
platziert werden.

## In einer Section

Bezieht sich der Alert auf eine bestimmte
[Section](https://flow.mittwald.de/components/structure/section), wird er in deren Content platziert.

```tsx
import {
  Alert,
  Heading,
  LayoutCard,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<LayoutCard>
  <Section>
    <Heading>E-Mail-Adresse</Heading>
    <Text>...</Text>
  </Section>
  <Section>
    <Heading>Speicherplatz</Heading>
    <Alert status="danger">
      <Heading>Speicherplatz ist voll</Heading>
      <Text>
        Der Speicherplatz deines Postfachs ist voll. Um
        wieder E-Mails erhalten zu können, kannst du der
        E-Mail-Adresse mehr Speicher zuweisen.
      </Text>
    </Alert>
    <Text>...</Text>
  </Section>
</LayoutCard>
```

## Seitenweit

Gilt sein Hinweis für die gesamte Seite, wird er prominent oberhalb der ersten
Section innerhalb der [LayoutCard](https://flow.mittwald.de/components/structure/layout-card) platziert.

```tsx
import {
  Alert,
  LayoutCard,
  Heading,
  Text,
  Section,
} from "@mittwald/flow-react-components";

<LayoutCard>
  <Alert status="danger">
    <Heading>E-Mail-Adresse wurde archiviert</Heading>
    <Text>
      Da deine Domain gelöscht wurde, wurde diese
      E-Mail-Adresse archiviert. Um E-Mails empfangen und
      senden zu können musst du die E-Mail-Adresse
      bearbeiten.
    </Text>
  </Alert>
  <Section>
    <Heading>E-Mail-Adresse</Heading>
    <Text>...</Text>
  </Section>
  <Section>
    <Heading>Speicherplatz</Heading>
    <Text>...</Text>
  </Section>
</LayoutCard>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"info" \| "success" \| "warning" \| "danger" \| "unavailable"` | - | The elements status |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--alert--padding` | `16px` |
| `--alert--corner-radius` | `8px` |
| `--alert--border-width` | `1px` |
| `--alert--border-x-start-width` | `8px` |
| `--alert--border-style` | `solid` |
| `--alert--heading-to-content-spacing` | `0.5rem` |
| `--alert--spacing` | `1rem` |
| `--alert--heading-size` | `1rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--alert--info-border-color` | `#0054F5` | `#85AFFF` |
| `--alert--info-heading-color` | `#003FB8` | `#ABC6FF` |
| `--alert--warning-border-color` | `#F56800` | `#FFC89F` |
| `--alert--warning-heading-color` | `#C25200` | `#FFD9BD` |
| `--alert--danger-border-color` | `#E1244C` | `#F2A2B3` |
| `--alert--danger-heading-color` | `#AB1737` | `#F7C1CC` |
| `--alert--success-border-color` | `#00825B` | `#4FFFC9` |
| `--alert--success-heading-color` | `#005F42` | `#87FFDA` |
| `--alert--unavailable-border-color` | `#3A434E` | `#E5EFF8` |
| `--alert--unavailable-heading-color` | `#3A434E` | `#E5EFF8` |

---

# AlertBadge

Ein AlertBadge hebt Statusmeldungen hervor, die besondere Aufmerksamkeit erfordern.

> **mStudio-Extensions:** Importiere `AlertBadge` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<AlertBadge>Archiviert</AlertBadge>
```

---

# Best Practices

- Halte die Beschriftung kurz und prägnant, idealerweise auf ein bis drei
  Wörter.
- Wähle den Status passend zur Wichtigkeit der Meldung.
- Setze ein AlertBadge nur für kritische oder besonders aufmerksamkeitsstarke
  Hinweise ein. Für weniger dringende Fälle genügt ein
  [Badge](https://flow.mittwald.de/components/status/badge).
- Lass auf ein AlertBadge weiterführende Informationen in einem
  [Alert](https://flow.mittwald.de/components/status/alert) folgen.
- Orientiere dich am
  [Informationskonzept](https://flow.mittwald.de/foundations/content-guidelines/informationskonzept). Es
  beschreibt das Zusammenspiel der Status-Komponenten.

## AlertBadge vs. Badge

**Verwende ein AlertBadge, wenn z. B. ...**

- der Hinweis kritisch, sicherheitsrelevant oder besonders wichtig ist.
- weitere Informationen durch einen Alert notwendig sind.

**Verwende ein Badge, wenn z. B. ...**

- Metadaten oder ergänzende Informationen dargestellt werden sollen.
- keine sofortige Aktion oder erhöhte Aufmerksamkeit notwendig ist.

---

# Status

Je nach Anwendungsfall stehen verschiedene Status-Farben zur Auswahl:

- **Info** – Allgemeine Systemzustände oder laufende Prozesse, die keine Aktion
  erfordern.
- **Success** – Abgeschlossene, erfolgreiche oder positiv bewertete Zustände.
- **Warning** – Hinweise auf mögliche Risiken mit einer klaren
  Handlungsempfehlung.
- **Danger** – Akute Fehlerzustände oder kritische Probleme, die sofortige
  Aufmerksamkeit erfordern.
- **Unavailable** – Zustände aufgrund von nicht verfügbaren oder gelöschten
  Inhalten.

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

<>
  <AlertBadge status="info">Archiviert</AlertBadge>
  <AlertBadge status="success">
    Update erfolgreich
  </AlertBadge>
  <AlertBadge status="warning">
    Speicher fast voll
  </AlertBadge>
  <AlertBadge status="danger">Speicher voll</AlertBadge>
  <AlertBadge status="unavailable">
    Nicht gefunden
  </AlertBadge>
</>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `status` | `"info" \| "success" \| "warning" \| "danger" \| "unavailable"` | - | The elements status |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

---

# Design Tokens

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--alert-badge--info-background-color` | `#F0F5FF` | `#00205C` |
| `--alert-badge--info-content-color` | `#003FB8` | `#ABC6FF` |
| `--alert-badge--info-border-color` | `#0054F5` | `#85AFFF` |
| `--alert-badge--success-background-color` | `#DCFFF4` | `#00291C` |
| `--alert-badge--success-content-color` | `#005F42` | `#87FFDA` |
| `--alert-badge--success-border-color` | `#00825B` | `#4FFFC9` |
| `--alert-badge--warning-background-color` | `#FFF4EB` | `#763200` |
| `--alert-badge--warning-content-color` | `#C25200` | `#FFD9BD` |
| `--alert-badge--warning-border-color` | `#F56800` | `#FFC89F` |
| `--alert-badge--danger-background-color` | `#FDF0F3` | `#540B1B` |
| `--alert-badge--danger-content-color` | `#AB1737` | `#F7C1CC` |
| `--alert-badge--danger-border-color` | `#E1244C` | `#F2A2B3` |
| `--alert-badge--unavailable-background-color` | `#E5EFF8` | `#3A434E` |
| `--alert-badge--unavailable-content-color` | `#3A434E` | `#E5EFF8` |
| `--alert-badge--unavailable-border-color` | `#3A434E` | `#E5EFF8` |

---

# AlertText

AlertText informiert über das Ergebnis einer Aktion, nah an der auslösenden Stelle.

> **mStudio-Extensions:** Importiere `AlertText` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<AlertText>Info</AlertText>
```

---

# Best Practices

- Wähle den Schweregrad passend zur Bedeutung der Meldung. Welcher Status wofür
  steht, beschreibt das
  [Informationskonzept](https://flow.mittwald.de/foundations/content-guidelines/informationskonzept).
- Formuliere den Text klar, prägnant und lösungsorientiert. Verzichte auf
  Fachbegriffe und Schuldzuweisungen und beachte die
  [Content Guidelines für Fehlermeldungen](https://flow.mittwald.de/foundations/content-guidelines/fehlermeldungen).

---

# Status

Je nach Anwendungsfall stehen verschiedene Status-Farben zur Auswahl:

- **Info** – Allgemeine Systemzustände oder laufende Prozesse, die keine Aktion
  erfordern.
- **Warning** – Hinweise auf mögliche Risiken mit einer klaren
  Handlungsempfehlung.
- **Danger** – Akute Fehlerzustände oder kritische Probleme, die sofortige
  Aufmerksamkeit erfordern.
- **Success** – Abgeschlossene, erfolgreiche oder positiv bewertete Zustände.
- **Unavailable** – Zustände aufgrund von nicht verfügbaren oder gelöschten
  Inhalten.

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

<>
  <AlertText status="info">Info</AlertText>
  <AlertText status="warning">Warning</AlertText>
  <AlertText status="danger">Danger</AlertText>
  <AlertText status="success">Success</AlertText>
  <AlertText status="unavailable">Unavailable</AlertText>
</>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `status` | `"info" \| "success" \| "warning" \| "danger" \| "unavailable"` | - | The elements status |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--alert-text--spacing` | `0.25rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--alert-text--info-color` | `#003FB8` | `#ABC6FF` |
| `--alert-text--warning-color` | `#C25200` | `#FFD9BD` |
| `--alert-text--danger-color` | `#AB1737` | `#F7C1CC` |
| `--alert-text--success-color` | `#005F42` | `#87FFDA` |
| `--alert-text--unavailable-color` | `#3A434E` | `#E5EFF8` |

---

# Badge

Ein Badge stellt kompakt zusätzliche Informationen wie Metadaten, Status oder Kategorien dar.

> **mStudio-Extensions:** Importiere `Badge` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<Badge>Value</Badge>
```

---

# Best Practices

- Halte die Beschriftung kurz und prägnant, idealerweise auf ein bis drei
  Wörter.
- Verwende die Colors konsistent für gleiche Informationen.
- Setze die Colors Blue, Green, Orange und Red mit Bedacht ein. Sie werden
  leicht mit [AlertBadges](https://flow.mittwald.de/components/status/alert-badge) oder Status-Colors
  verwechselt.

## Badge vs. AlertBadge

**Verwende ein Badge, wenn z. B. ...**

- Metadaten oder ergänzende Informationen dargestellt werden sollen.
- keine sofortige Aktion oder erhöhte Aufmerksamkeit notwendig ist.

**Verwende ein AlertBadge, wenn z. B. ...**

- der Hinweis kritisch, sicherheitsrelevant oder besonders wichtig ist.
- weitere Informationen durch einen [Alert](https://flow.mittwald.de/components/status/alert) notwendig sind.

---

# Color

Die [Color](https://flow.mittwald.de/foundations/design/colors)-Varianten können frei gewählt werden –
achte dabei auf die beabsichtigte Wirkung. **Neutral** eignet sich zum Beispiel
für sekundäre Informationen, da das dezente Grau weniger Aufmerksamkeit erzeugt.

Setze **Blue**, **Green**, **Orange** und **Red** mit Bedacht ein, da sie leicht
mit [AlertBadges](https://flow.mittwald.de/components/status/alert-badge) oder Status-Colors verwechselt
werden.

```tsx
import {
  Badge,
  Label,
  Text,
} from "@mittwald/flow-react-components";

<>
  <Badge color="neutral">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="blue">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="navy">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="violet">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="teal">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="lilac">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="green">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="orange">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="red">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
</>
```

## Light und Dark

Um auf farbigen oder dekorativen Hintergründen ausreichend Kontrast zu
erreichen, kann das Badge auch in Light und Dark dargestellt werden. Mehr zur
richtigen Verwendung von Light und Dark findest du in den Foundations unter
[Color](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

```tsx
import {
  Badge,
  Label,
  Text,
} from "@mittwald/flow-react-components";

<Badge color="light">
  <Label>Scope</Label>
  <Text>Value</Text>
</Badge>
```

```tsx
import {
  Badge,
  Label,
  Text,
} from "@mittwald/flow-react-components";

<Badge color="dark">
  <Label>Scope</Label>
  <Text>Value</Text>
</Badge>
```

---

# Mit Scope

Ein Scope ordnet das Badge einer Kategorie zu, die meist mehrere Werte hat (z.
B. Priorität: hoch, Priorität: niedrig).

```tsx
import {
  Badge,
  Label,
  Text,
} from "@mittwald/flow-react-components";

<Badge color="neutral">
  <Label>Scope</Label>
  <Text>Value</Text>
</Badge>
```

---

# Badge Aktion

Über `onPress` kann ein Badge eine Aktion auslösen, etwa um weiterführende
Informationen zu öffnen. Es sollte dabei nicht als Ersatz für einen
[Button](https://flow.mittwald.de/components/actions/button) missbraucht werden.

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

<Badge
  onPress={() => {
    alert("pressed!");
  }}
>
  Value
</Badge>
```

---

# Mit ContextualHelp

Eine [ContextualHelp](https://flow.mittwald.de/components/overlays/contextual-help) im Badge wird am
Ende als Button dargestellt. Den Button stellt das Badge selbst. Schreibst du
den `ContextualHelpTrigger` mit eigenem Button aus, landet er an derselben
Stelle.

```tsx
import {
  Badge,
  ContextualHelp,
  Label,
  Text,
} from "@mittwald/flow-react-components";

<Badge>
  <Label>Priorität</Label>
  <Text>Hoch</Text>
  <ContextualHelp>
    <Text>
      Tickets mit hoher Priorität werden zuerst bearbeitet.
    </Text>
  </ContextualHelp>
</Badge>
```

---

# Mit onClose

Über `onClose` platzierst du einen X-Button im Badge. Nutze ihn z. B., um das
Badge entfernbar zu machen.

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

<Badge
  onClose={() => {
    alert("closed!");
  }}
>
  Value
</Badge>
```

---

# Disabled

In Ausnahmefällen können deaktivierte Badges verwendet werden, um eine Funktion
temporär als nicht verfügbar darzustellen, ohne diese vollständig aus der
Oberfläche zu entfernen.

```tsx
import {
  Badge,
  Label,
  Text,
} from "@mittwald/flow-react-components";

<Badge color="neutral" isDisabled>
  <Label>Scope</Label>
  <Text>Value</Text>
</Badge>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `color` | `"dark" \| "light" \| "dark-static" \| "light-static" \| "neutral" \| "violet" \| "green" \| "blue" \| "teal" \| "lilac" \| "navy" \| "orange" \| "red"` | `"neutral"` | The color of the badge. |
| `isDisabled` | `boolean` | - | Whether the badge is disabled. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onClose` | `((e: PressEvent) => void)` | - | Handler that is called when the badges close icon is pressed. |
| `onPress` | `((e: PressEvent) => void)` | - | Handler that is called when the badge is pressed. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--badge--font-size` | `0.875rem` |
| `--badge--font-weight` | `bold` |
| `--badge--line-height` | `1rem` |
| `--badge--corner-radius` | `16px` |
| `--badge--border-width` | `1px` |
| `--badge--border-style` | `solid` |
| `--badge--padding-y` | `0.25rem` |
| `--badge--padding-x` | `0.5rem` |
| `--badge--spacing` | `0.25rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--badge--neutral-border-color` | `#3A434E` | `#E5EFF8` |
| `--badge--neutral-background-color--default` | `#E5EFF8` | `#3A434E` |
| `--badge--neutral-background-color--hover` | `#DCE9F7` | `#5E6C7A` |
| `--badge--neutral-background-color--pressed` | `#B7C9DB` | `#8FA1B4` |
| `--badge--neutral-content-color` | `#292F37` | `#F4F8FC` |
| `--badge--neutral-scope-background-color` | `#3A434E` | `#E5EFF8` |
| `--badge--neutral-scope-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--blue-border-color` | `#0054F5` | `#85AFFF` |
| `--badge--blue-background-color--default` | `#F0F5FF` | `#00205C` |
| `--badge--blue-background-color--hover` | `#E0EBFF` | `#002A7B` |
| `--badge--blue-background-color--pressed` | `#ABC6FF` | `#003FB8` |
| `--badge--blue-content-color` | `#003FB8` | `#ABC6FF` |
| `--badge--blue-scope-background-color` | `#0054F5` | `#85AFFF` |
| `--badge--blue-scope-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--navy-border-color` | `#27367B` | `#8291D7` |
| `--badge--navy-background-color--default` | `#E4E7F6` | `#0E142E` |
| `--badge--navy-background-color--hover` | `#C8CFEE` | `#131B3D` |
| `--badge--navy-background-color--pressed` | `#A5B0E2` | `#1D285C` |
| `--badge--navy-content-color` | `#1D285C` | `#A5B0E2` |
| `--badge--navy-scope-background-color` | `#27367B` | `#8291D7` |
| `--badge--navy-scope-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--violet-border-color` | `#715DEE` | `#C2B9F8` |
| `--badge--violet-background-color--default` | `#F4F3FE` | `#302a6f` |
| `--badge--violet-background-color--hover` | `#EAE7FD` | `#483b9f` |
| `--badge--violet-background-color--pressed` | `#D6D0FA` | `#5d4abf` |
| `--badge--violet-content-color` | `#5d4abf` | `#D6D0FA` |
| `--badge--violet-scope-background-color` | `#715DEE` | `#C2B9F8` |
| `--badge--violet-scope-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--teal-border-color` | `#008696` | `#5eedff` |
| `--badge--teal-background-color--default` | `#ebfdff` | `#00424a` |
| `--badge--teal-background-color--hover` | `#cffaff` | `#004f59` |
| `--badge--teal-background-color--pressed` | `#96f3ff` | `#006b78` |
| `--badge--teal-content-color` | `#006b78` | `#96f3ff` |
| `--badge--teal-scope-background-color` | `#008696` | `#5eedff` |
| `--badge--teal-scope-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--lilac-border-color` | `#bc08ff` | `#ebb6ff` |
| `--badge--lilac-background-color--default` | `#f9e9ff` | `#470062` |
| `--badge--lilac-background-color--hover` | `#f6dfff` | `#5f0083` |
| `--badge--lilac-background-color--pressed` | `#f1caff` | `#9000c5` |
| `--badge--lilac-content-color` | `#9000c5` | `#f1caff` |
| `--badge--lilac-scope-background-color` | `#bc08ff` | `#ebb6ff` |
| `--badge--lilac-scope-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--red-border-color` | `#E1244C` | `#F2A2B3` |
| `--badge--red-background-color--default` | `#FDF0F3` | `#540B1B` |
| `--badge--red-background-color--hover` | `#FBE0E6` | `#710F24` |
| `--badge--red-background-color--pressed` | `#F7C1CC` | `#AB1737` |
| `--badge--red-content-color` | `#AB1737` | `#F7C1CC` |
| `--badge--red-scope-background-color` | `#E1244C` | `#F2A2B3` |
| `--badge--red-scope-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--green-border-color` | `#00825B` | `#4FFFC9` |
| `--badge--green-background-color--default` | `#DCFFF4` | `#00291C` |
| `--badge--green-background-color--hover` | `#C0FFEB` | `#003B29` |
| `--badge--green-background-color--pressed` | `#87FFDA` | `#005F42` |
| `--badge--green-content-color` | `#005F42` | `#87FFDA` |
| `--badge--green-scope-background-color` | `#00825B` | `#4FFFC9` |
| `--badge--green-scope-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--orange-border-color` | `#C25200` | `#FFD9BD` |
| `--badge--orange-background-color--default` | `#FFF4EB` | `#763200` |
| `--badge--orange-background-color--hover` | `#FFEBDC` | `#8F3D00` |
| `--badge--orange-background-color--pressed` | `#FFD9BD` | `#C25200` |
| `--badge--orange-content-color` | `#C25200` | `#FFD9BD` |
| `--badge--orange-scope-background-color` | `#C25200` | `#FFD9BD` |
| `--badge--orange-scope-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--dark-border-color` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--badge--dark-background-color--default` | `rgb(0 0 0 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--badge--dark-background-color--hover` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--badge--dark-background-color--pressed` | `rgb(0 0 0 / 37.5%)` | `rgb(255 255 255 / 37.5%)` |
| `--badge--dark-content-color` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--badge--dark-scope-background-color` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--badge--dark-scope-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--light-border-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--light-background-color--default` | `rgb(255 255 255 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--badge--light-background-color--hover` | `rgb(255 255 255 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--badge--light-background-color--pressed` | `rgb(255 255 255 / 37.5%)` | `rgb(0 0 0 / 37.5%)` |
| `--badge--light-content-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--light-scope-background-color` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--light-scope-content-color` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--badge--dark-static-border-color` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--dark-static-background-color--default` | `rgb(0 0 0 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--badge--dark-static-background-color--hover` | `rgb(0 0 0 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--badge--dark-static-background-color--pressed` | `rgb(0 0 0 / 37.5%)` | `rgb(0 0 0 / 37.5%)` |
| `--badge--dark-static-content-color` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--dark-static-scope-background-color` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--dark-static-scope-content-color` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--badge--light-static-border-color` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--badge--light-static-background-color--default` | `rgb(255 255 255 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--badge--light-static-background-color--hover` | `rgb(255 255 255 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--badge--light-static-background-color--pressed` | `rgb(255 255 255 / 37.5%)` | `rgb(255 255 255 / 37.5%)` |
| `--badge--light-static-content-color` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--badge--light-static-scope-background-color` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--badge--light-static-scope-content-color` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--badge--disabled-border-color` | `#DCE9F7` | `#5E6C7A` |
| `--badge--disabled-background-color` | `#F4F8FC` | `#292F37` |
| `--badge--disabled-content-color` | `#B7C9DB` | `#8FA1B4` |
| `--badge--disabled-scope-background-color` | `#E5EFF8` | `#3A434E` |
| `--badge--disabled-scope-content-color` | `#B7C9DB` | `#8FA1B4` |
| `--badge--disabled-dark-border-color` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--badge--disabled-dark-background-color` | `rgb(0 0 0 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--badge--disabled-dark-content-color` | `rgb(0 0 0 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--badge--disabled-dark-scope-background-color` | `rgb(0 0 0 / 37.5%)` | `rgb(255 255 255 / 37.5%)` |
| `--badge--disabled-dark-scope-content-color` | `rgb(255 255 255 / 37.5%)` | `rgb(0 0 0 / 37.5%)` |
| `--badge--disabled-light-border-color` | `rgb(255 255 255 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--badge--disabled-light-background-color` | `rgb(255 255 255 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--badge--disabled-light-content-color` | `rgb(255 255 255 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--badge--disabled-light-scope-background-color` | `rgb(255 255 255 / 37.5%)` | `rgb(0 0 0 / 37.5%)` |
| `--badge--disabled-light-scope-content-color` | `rgb(0 0 0 / 37.5%)` | `rgb(255 255 255 / 37.5%)` |
| `--badge--disabled-dark-static-border-color` | `rgb(0 0 0 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--badge--disabled-dark-static-background-color` | `rgb(0 0 0 / 12.5%)` | `rgb(0 0 0 / 12.5%)` |
| `--badge--disabled-dark-static-content-color` | `rgb(0 0 0 / 25%)` | `rgb(0 0 0 / 25%)` |
| `--badge--disabled-dark-static-scope-background-color` | `rgb(0 0 0 / 37.5%)` | `rgb(0 0 0 / 37.5%)` |
| `--badge--disabled-dark-static-scope-content-color` | `rgb(255 255 255 / 37.5%)` | `rgb(255 255 255 / 37.5%)` |
| `--badge--disabled-light-static-border-color` | `rgb(255 255 255 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--badge--disabled-light-static-background-color` | `rgb(255 255 255 / 12.5%)` | `rgb(255 255 255 / 12.5%)` |
| `--badge--disabled-light-static-content-color` | `rgb(255 255 255 / 25%)` | `rgb(255 255 255 / 25%)` |
| `--badge--disabled-light-static-scope-background-color` | `rgb(255 255 255 / 37.5%)` | `rgb(255 255 255 / 37.5%)` |
| `--badge--disabled-light-static-scope-content-color` | `rgb(0 0 0 / 37.5%)` | `rgb(0 0 0 / 37.5%)` |

---

# CounterBadge

Ein CounterBadge weist kompakt auf neue oder ungelesene Inhalte hin.

> **mStudio-Extensions:** Importiere `CounterBadge` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<CounterBadge count={5} />
```

---

# Best Practices

- Beziehe das CounterBadge eindeutig auf ein Element. Das kann zum Beispiel ein
  [Button](https://flow.mittwald.de/components/actions/button) oder Tab sein.
- Setze CounterBadges sparsam ein. Zu viele auf engem Raum überfordern den User.
- Mach den Wert über das darunterliegende Element zugänglich. Das CounterBadge
  selbst ist nicht accessible; auf einem Button enthält daher ein `aria-label`
  die Zahl.

---

# Ohne Inhalt

Ein CounterBadge kann auch ohne Inhalt verwendet werden, um auf einen Status
hinzuweisen.

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

<CounterBadge />
```

---

# Hohe Zahlen

Ist der tatsächliche Wert 100 oder höher, wird stattdessen „99+“ im CounterBadge
angezeigt.

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

<CounterBadge count={120} />
```

---

# Innerhalb eines Buttons

Um sich auf anderen Elementen besser abzuheben, hat das CounterBadge eine
Border. Deren Farbe sollte an die Hintergrundfarbe angepasst werden.

```tsx
import {
  Button,
  CounterBadge,
  IconNotification,
} from "@mittwald/flow-react-components";

<Button variant="plain" aria-label="Benachrichtigungen: 7">
  <IconNotification />
  <CounterBadge count={7} />
</Button>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` | - | The number displayed inside the badge. |
| `elementType` | `"span" \| ExoticComponent<{}>` | - | The HTML element or React component rendered as the elements root. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--counter-badge--font-size` | `0.625rem` |
| `--counter-badge--font-weight` | `bold` |
| `--counter-badge--height` | `1.25rem` |
| `--counter-badge--height-empty` | `0.75rem` |
| `--counter-badge--padding-inline` | `0.25rem` |
| `--counter-badge--border-width` | `2px` |
| `--counter-badge--border-style` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--counter-badge--background-color` | `#0054F5` | `#85AFFF` |
| `--counter-badge--content-color` | `#FFFFFF` | `#1B1F24` |
| `--counter-badge--border-color` | `#FFFFFF` | `#1B1F24` |

---

# LoadingSpinner

Der LoadingSpinner signalisiert, dass Inhalte im Hintergrund geladen werden.

> **mStudio-Extensions:** Importiere `LoadingSpinner` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<LoadingSpinner />
```

---

# Best Practices

- Setze den LoadingSpinner nur bei unbestimmter Dauer ein. Bei konkret
  darstellbarem Fortschritt eignet sich eine
  [ProgressBar](https://flow.mittwald.de/components/status/progress-bar), bei kurzem initialem Laden mit
  bekannter Layout-Struktur ein [Skeleton](https://flow.mittwald.de/components/content/skeleton).
- Setze ihn nur bei relevanter Ladezeit ein, als Faustregel ab etwa einer
  Sekunde. Bei sehr kurzen Ladezeiten bringt visuelles Feedback meist keinen
  Mehrwert.
- Kombiniere ihn bei längeren Ladezeiten mit einer
  [IllustratedMessage](https://flow.mittwald.de/components/content/illustrated-message). So erhält der
  User zusätzliche Informationen.
- Platziere ihn dort, wohin der User nach dem Laden schauen soll.
- Zeige nicht zu viele Spinner gleichzeitig. Mehrere gleichzeitig wirken schnell
  unruhig.

---

# Color

Im Standardfall wird der LoadingSpinner in der Color **Default** verwendet – ein
neutraler Ton mit guter Sichtbarkeit, der nicht von der übrigen
Benutzeroberfläche ablenkt.

## Light und Dark

Auf farbigen oder dekorativen Hintergründen kann der LoadingSpinner in **Light**
oder **Dark** dargestellt werden. Welche Color wann passt, beschreibt
[Color](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

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

<LoadingSpinner color="light" />
```

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

<LoadingSpinner color="dark" />
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static"` | `"default"` | The color of the loading spinner. |
| `size` | `"s" \| "m" \| "l"` | `"m"` | The size of the icon. |
| `status` _(deprecated)_ | `"info" \| "success" \| "warning" \| "danger" \| "unavailable"` | - | The elements status. @deprecated Use `color` instead. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--loading-spinner--transition-duration` | `2000ms` |
| `--loading-spinner--transition-duration-slow` | `6000ms` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--loading-spinner--color` | `#5E6C7A` | `#DCE9F7` |
| `--loading-spinner--color-light` | `rgb(255 255 255 / 100%)` | `rgb(0 0 0 / 100%)` |
| `--loading-spinner--color-dark` | `rgb(0 0 0 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--loading-spinner--color-light-static` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--loading-spinner--color-dark-static` | `rgb(0 0 0 / 100%)` | `rgb(0 0 0 / 100%)` |

---

# Notification

Die Notification informiert User über wichtige System- oder Statusmeldungen.

> **mStudio-Extensions:** Importiere `Notification` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

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

<Notification>
  <Heading>E-Mail-Adresse archiviert</Heading>
  <Text>
    Die E-Mail-Adresse <strong>example@mittwald.de</strong>{" "}
    wurde archiviert.
  </Text>
</Notification>
```

---

# Best Practices

- Kommuniziere nur relevante und wichtige Informationen. Das vermeidet eine
  Informationsüberlastung.
- Formuliere die Meldung kurz, klar und verständlich, als Faustregel in
  höchstens zwölf Wörtern.
- Halte Notifications gesammelt und später abrufbar.

---

# Status

Je nach Anwendungsfall stehen verschiedene Status-Farben zur Auswahl:

- **Info** – Allgemeine Systemzustände oder laufende Prozesse, die keine Aktion
  erfordern.
- **Warning** – Hinweise auf mögliche Risiken mit einer klaren
  Handlungsempfehlung.
- **Danger** – Akute Fehlerzustände oder kritische Probleme, die sofortige
  Aufmerksamkeit erfordern.
- **Success** – Abgeschlossene, erfolgreiche oder positiv bewertete Zustände.
- **Unavailable** – Zustände aufgrund von nicht verfügbaren oder gelöschten
  Inhalten.

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

<>
  <Notification status="info">
    <Heading>E-Mail-Adresse archiviert</Heading>
    <Text>
      Die E-Mail-Adresse{" "}
      <strong>example@mittwald.de</strong> wurde archiviert.
    </Text>
  </Notification>

  <Notification status="warning">
    <Heading>Speicher fast voll</Heading>
    <Text>
      Der Speicherplatz im Projekt{" "}
      <strong>My Project</strong> ist zu 80% voll.
    </Text>
  </Notification>

  <Notification status="danger">
    <Heading>Kein SSL-Zertifikat</Heading>
    <Text>
      Für <strong>example.de</strong> konnte kein
      SSL-Zertifikat ausgestellt werden.
    </Text>
  </Notification>

  <Notification status="success">
    <Heading>App installiert</Heading>
    <Text>
      Deine App <strong>My WordPress</strong> wurde
      erfolgreich installiert.
    </Text>
  </Notification>

  <Notification status="unavailable">
    <Heading>Nicht gefunden</Heading>
    <Text>
      Die gewünschten Inhalte sind leider nicht verfügbar.
    </Text>
  </Notification>
</>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoClose` | `boolean` | - | Whether the notification should disappear automatically after some time. |
| `href` | `string` | - | A link that is triggered when clicking the notification. |
| `status` | `"info" \| "success" \| "warning" \| "danger" \| "unavailable"` | - | The elements status |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onClick` | `(() => void)` | - | Handler that is called when the notification is clicked. |
| `onClose` | `(() => void)` | - | Handler that is called when the close button of the notification is clicked. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--notification--padding` | `8px` |
| `--notification--corner-radius` | `8px` |
| `--notification--border-x-start-width` | `4px` |
| `--notification--border-style` | `solid` |
| `--notification--border-width` | `1px` |
| `--notification--box-shadow` | `rgb(0 0 0 / 12.5%) 0 8px 16px` |
| `--notification--width` | `355px` |
| `--notification--max-width` | `calc(100dvw - 2 * 32px)` |
| `--notification--heading-to-text-spacing` | `0.25rem` |
| `--notification--spacing` | `0.5rem` |
| `--notification--font-size` | `0.875rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--notification--border-color` | `#E5EFF8` | `#3A434E` |
| `--notification--info-border-color` | `#0054F5` | `#85AFFF` |
| `--notification--info-heading-color` | `#003FB8` | `#ABC6FF` |
| `--notification--info-background-color--default` | `#FFFFFF` | `#1B1F24` |
| `--notification--info-background-color--hover` | `#F0F5FF` | `#00205C` |
| `--notification--info-background-color--pressed` | `#E0EBFF` | `#002A7B` |
| `--notification--warning-border-color` | `#F56800` | `#FFC89F` |
| `--notification--warning-heading-color` | `#C25200` | `#FFD9BD` |
| `--notification--warning-background-color--default` | `#FFFFFF` | `#1B1F24` |
| `--notification--warning-background-color--hover` | `#FFF4EB` | `#763200` |
| `--notification--warning-background-color--pressed` | `#FFEBDC` | `#8F3D00` |
| `--notification--danger-border-color` | `#E1244C` | `#F2A2B3` |
| `--notification--danger-heading-color` | `#AB1737` | `#F7C1CC` |
| `--notification--danger-background-color--default` | `#FFFFFF` | `#1B1F24` |
| `--notification--danger-background-color--hover` | `#FDF0F3` | `#540B1B` |
| `--notification--danger-background-color--pressed` | `#FBE0E6` | `#710F24` |
| `--notification--success-border-color` | `#00825B` | `#4FFFC9` |
| `--notification--success-heading-color` | `#005F42` | `#87FFDA` |
| `--notification--success-background-color--default` | `#FFFFFF` | `#1B1F24` |
| `--notification--success-background-color--hover` | `#DCFFF4` | `#00291C` |
| `--notification--success-background-color--pressed` | `#C0FFEB` | `#003B29` |
| `--notification--unavailable-border-color` | `#3A434E` | `#E5EFF8` |
| `--notification--unavailable-heading-color` | `#3A434E` | `#E5EFF8` |
| `--notification--unavailable-background-color--default` | `#FFFFFF` | `#1B1F24` |
| `--notification--unavailable-background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--notification--unavailable-background-color--pressed` | `#DCE9F7` | `#5E6C7A` |

---

# NotificationProvider

Der NotificationProvider dient zur Anzeige und Steuerung von Notifications.

> **mStudio-Extensions:** Importiere `NotificationProvider` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import {
  Button,
  Heading,
  Notification,
  Text,
  useNotificationController,
} from "@mittwald/flow-react-components";

export default () => {
  const controller = useNotificationController();

  return (
    <Button
      onPress={() =>
        controller.add(
          <Notification
            onClick={() => alert("Notification clicked")}
            status="warning"
          >
            <Heading>No SSL certificate</Heading>
            <Text>
              No SSL certificate could be issued for
              examples.de.
            </Text>
          </Notification>,
        )
      }
    >
      Trigger Notification
    </Button>
  );
}
```

---

# Best Practices

- Überflute die User nicht mit zu vielen Notifications.
- Für die angezeigten Notifications gelten die
  [Best Practices der Notification](https://flow.mittwald.de/components/status/notification).
- Gib den Usern bei `autoClose` genug Zeit zum Lesen. Idealerweise ist die
  Anzeigedauer einstellbar.

---

# Initialisierung

Damit Notifications angezeigt werden können, muss der `<NotificationProvider />`
als übergeordnete Component eingebunden werden.

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

<NotificationProvider>Meine App</NotificationProvider>
```

---

# Automatisches Schließen

Ist das Property `autoClose` gesetzt, verschwinden die Notifications nach 10
Sekunden.

```tsx
import {
  Button,
  Heading,
  Notification,
  Text,
  useNotificationController,
} from "@mittwald/flow-react-components";

export default () => {
  const controller = useNotificationController();

  return (
    <Button
      onPress={() =>
        controller.add(
          <Notification
            onClick={() => alert("Notification clicked")}
            status="warning"
            autoClose
          >
            <Heading>No SSL certificate</Heading>
            <Text>
              No SSL certificate could be issued for
              examples.de.
            </Text>
          </Notification>,
        )
      }
    >
      Trigger Notification
    </Button>
  );
}
```

---

# Manuelles Schließen

Die `add()`-Methode gibt eine Notification-ID zurück. Diese kann in der
`remove()`-Methode verwendet werden, um eine Notification manuell zu schließen.

```tsx
import {
  Button,
  Heading,
  Notification,
  Text,
  useNotificationController,
} from "@mittwald/flow-react-components";

export default () => {
  const controller = useNotificationController();

  return (
    <Button
      onPress={() => {
        const filename = `export_${Math.round(Math.random() * 1000)}.zip`;

        const notificationId = controller.add(
          <Notification status="info" autoClose={false}>
            <Heading>File is downloading</Heading>
            <Text>
              The file "{filename}" is beeing downloaded.
            </Text>
          </Notification>,
        );

        setTimeout(() => {
          controller.remove(notificationId);
          controller.add(
            <Notification status="success" autoClose>
              <Heading>Download completed</Heading>
              <Text>
                The download of "{filename}" is completed.
              </Text>
            </Notification>,
          );
        }, 3000);
      }}
    >
      Trigger Notification
    </Button>
  );
}
```

---

# Properties

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--notification-provider--window-to-provider-spacing` | `32px` |
| `--notification-provider--notification-to-notification-spacing` | `16px` |

---

# ProgressBar

Eine ProgressBar zeigt den Fortschritt eines laufenden Prozesses als horizontalen Balken an.

> **mStudio-Extensions:** Importiere `ProgressBar` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  Label,
  ProgressBar,
} from "@mittwald/flow-react-components";

<ProgressBar value={50}>
  <Label>Speicher</Label>
</ProgressBar>
```

---

# Best Practices

- Kommuniziere den Fortschritt eindeutig. Ein Beispiel ist „8 GB von 10 GB".
- Kombiniere die Status-Farben gezielt, um Zustände hervorzuheben. Wechsle etwa
  bei hoher Auslastung auf Warning oder Danger.
- Nutze bei unbestimmtem Fortschritt eine Alternative wie den
  [LoadingSpinner](https://flow.mittwald.de/components/status/loading-spinner).
- Aktualisiere dauerhaft angezeigte ProgressBars regelmäßig. Das erhält die
  Verlässlichkeit, etwa bei der Speicherplatzauslastung.

---

# Sizes

ProgressBars sind in drei verschiedenen Größen verfügbar: **Small**, **Medium**
und **Large**.

Die mittlere Größe **Medium** ist Standard und wird am häufigsten verwendet. Die
verschiedenen Größen eignen sich gut, um eine visuelle Hierarchie innerhalb der
Seite zu erzeugen. So kann die größte Variante **Large** sehr gut alleinstehend
eingesetzt werden, wenn die ProgressBar besondere Aufmerksamkeit auf sich ziehen
soll.

```tsx
import {
  Label,
  ProgressBar,
} from "@mittwald/flow-react-components";

<>
  <ProgressBar size="s" value={50}>
    <Label>Größe S</Label>
  </ProgressBar>
  <ProgressBar size="m" value={50}>
    <Label>Größe M</Label>
  </ProgressBar>
  <ProgressBar size="l" value={50}>
    <Label>Größe L</Label>
  </ProgressBar>
</>
```

---

# Status

Je nach Anwendungsfall stehen vier Status-Farben zur Auswahl: **Success**,
**Info**, **Warning** und **Danger**. Wechsle bei einer hohen Auslastung zum
Beispiel auf Warning oder Danger, um den Zustand hervorzuheben.

```tsx
import {
  Label,
  ProgressBar,
} from "@mittwald/flow-react-components";

<>
  <ProgressBar value={100} status="success">
    <Label>Success</Label>
  </ProgressBar>
  <ProgressBar value={50} status="info">
    <Label>Info</Label>
  </ProgressBar>
  <ProgressBar value={70} status="warning">
    <Label>Warning</Label>
  </ProgressBar>
  <ProgressBar value={90} status="danger">
    <Label>Danger</Label>
  </ProgressBar>
</>
```

---

# Mit Unit

Im Default wird die ProgressBar immer mit Prozentangabe angezeigt. Über das
Property `formatOptions` können aber auch andere Einheiten gewählt werden (s.
[Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)).

## Gigabyte

```tsx
import {
  Label,
  ProgressBar,
} from "@mittwald/flow-react-components";

<ProgressBar
  value={500}
  maxValue={1000}
  minValue={0}
  formatOptions={{ style: "unit", unit: "gigabyte" }}
>
  <Label>Speicher</Label>
</ProgressBar>
```

## Dezimalzahl

```tsx
import {
  Label,
  ProgressBar,
} from "@mittwald/flow-react-components";

<ProgressBar
  value={500}
  maxValue={1000}
  minValue={0}
  formatOptions={{ style: "decimal" }}
>
  <Label>Stückzahl</Label>
</ProgressBar>
```

---

# Mit Max Value

Der maximale Wert der ProgressBar lässt sich individuell festlegen, je nachdem,
was dargestellt werden soll. Standardmäßig beträgt dieser Wert 100 %.

```tsx
import {
  Label,
  ProgressBar,
} from "@mittwald/flow-react-components";

<ProgressBar
  showMaxValue
  value={500}
  maxValue={1000}
  minValue={0}
  formatOptions={{ style: "unit", unit: "gigabyte" }}
>
  <Label>Speicher</Label>
</ProgressBar>
```

---

# Segmente

Die Anzeige der ProgressBar kann über das `segments` Property um einzelne
Abschnitte ergänzt werden. Der `value` ergibt sich in diesem Fall aus der Summe
der Werte der einzelnen Segmente. Um die einzelnen Werte näher zu erläutern,
wird automatisch eine Legende angezeigt. Über das `showLegend` Property kann
diese ein- und ausgeblendet werden.

Die Farben der Segmente werden automatisch festgelegt, können aber über das
`color` Property überschrieben werden. Beim Überschreiben muss darauf geachtet
werden, dass nebeneinanderliegende Farben weiterhin einen ausreichenden Kontrast
zueinander haben.

```tsx
import {
  Label,
  ProgressBar,
} from "@mittwald/flow-react-components";

<ProgressBar
  maxValue={1000}
  size="l"
  showMaxValue
  formatOptions={{ style: "unit", unit: "gigabyte" }}
  segments={[
    { value: 280, title: "E-Mails" },
    {
      value: 170,
      title: "Datenbanken",
    },
    {
      value: 110,
      title: "Backups",
    },
  ]}
>
  <Label>Speicher</Label>
</ProgressBar>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<ProgressBarRenderProps>` | `'react-aria-ProgressBar'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `dir` | `string` | - | - |
| `formatOptions` | `NumberFormatOptions` | `{ style: 'percent' }` | The display format of the value label. |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isIndeterminate` | `boolean` | - | Whether presentation is indeterminate when progress isn't known. |
| `lang` | `string` | - | - |
| `maxValue` | `number` | `100` | The largest value allowed for the input. |
| `minValue` | `number` | `0` | The smallest value allowed for the input. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `segments` | `{ value: number; title: string; color?: CategoricalWithCustomColor; valueText?: string; }[]` | - | Divides the fill of the progress bar into segments |
| `showLegend` | `boolean` | `true` | Whether the legend component is shown when segments are used. |
| `showMaxValue` | `boolean` | - | Whether the max value should be displayed. |
| `size` | `"s" \| "m" \| "l"` | `"m"` | The size variant of the progress bar. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `status` | `"info" \| "success" \| "warning" \| "danger"` | - | The status the progress bar is colored by. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |
| `value` | `number` | `0` | The current value (controlled). |
| `valueLabel` | `ReactNode` | - | The content to display as the value's label (e.g. 1 of 4). |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--progress-bar--transition-duration` | `800ms` |
| `--progress-bar--font-size` | `1rem` |
| `--progress-bar--font-size-s` | `0.875rem` |
| `--progress-bar--value-font-weight` | `bold` |
| `--progress-bar--spacing-y` | `0.25rem` |
| `--progress-bar--spacing-x` | `1rem` |
| `--progress-bar--spacing-bar-to-legend` | `16px` |
| `--progress-bar--height--m` | `1rem` |
| `--progress-bar--height--s` | `0.5rem` |
| `--progress-bar--height--l` | `1.5rem` |
| `--progress-bar--corner-radius` | `16px` |
| `--progress-bar--border-width` | `1px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--progress-bar--border-color` | `#5E6C7A` | `#DCE9F7` |
| `--progress-bar--background-color` | `#F4F8FC` | `#292F37` |
| `--progress-bar--info-fill-background-color` | `#0054F5` | `#85AFFF` |
| `--progress-bar--success-fill-background-color` | `#00825B` | `#4FFFC9` |
| `--progress-bar--warning-fill-background-color` | `#F56800` | `#FFC89F` |
| `--progress-bar--danger-fill-background-color` | `#E1244C` | `#F2A2B3` |
| `--progress-bar--indeterminate-fill-background-color` | `#3A434E` | `#E5EFF8` |

---

# AccentBox

Die AccentBox dient dazu, besondere Inhalte dekorativ hervorzuheben.

> **mStudio-Extensions:** Importiere `AccentBox` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  AccentBox,
  Heading,
  Link,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<AccentBox backgroundColor="blue">
  <Section>
    <Heading>Hilf uns, Flow noch besser zu machen!</Heading>
    <Text>
      Fehlt dir eine bestimmte Component oder etwas anderes?
      Hast du Feedback? Dann teile es uns gerne auf GitHub
      mit.
    </Text>
    <Link href="#" target="_blank">
      Feedback zu Flow geben
    </Link>
  </Section>
</AccentBox>
```

---

# Best Practices

- Setze die AccentBox sparsam ein, um gezielt Aufmerksamkeit zu lenken.
- Platziere keine kritischen Inhalte in der AccentBox. Müssen Informationen
  zwingend wahrgenommen werden, nutze stattdessen einen
  [Alert](https://flow.mittwald.de/components/status/alert).
- Sorge für ausreichenden Kontrast zum Inhalt. Das gilt besonders bei mit der
  [Color](https://flow.mittwald.de/components/content/color)-Component eingefärbten Texten; reicht der
  Kontrast nicht, nutze die
  [Light oder Dark Color](https://flow.mittwald.de/foundations/design/colors#light-und-dark-color).

## AccentBox vs. Alert

AccentBoxen und [Alerts](https://flow.mittwald.de/components/status/alert) dienen beide dazu, dem User
zusätzliche Informationen bereitzustellen. Eine einfache Faustregel hilft bei
der Entscheidung: Kann die Information ignoriert werden, ohne negative Folgen?
Dann ist eine AccentBox die richtige Wahl. Wenn das Ignorieren hingegen zu
Problemen führen könnte – etwa bei sicherheitsrelevanten Hinweisen oder
wichtigen Systemmeldungen – sollte ein Alert mit entsprechendem Status verwendet
werden.

**Verwende AccentBoxen, um z. B. ...**

- ergänzende, aber nicht kritische Hinweise anzuzeigen.
- kontextuelle Informationen oder Tipps zu geben.
- visuell strukturierende Inhalte einzubetten, ohne zu unterbrechen.

**Verwende Alerts, um z. B. ...**

- den User auf sicherheits- oder funktionsrelevante Informationen hinzuweisen.
- vor möglichen Problemen oder Systemzuständen zu warnen.
- dringende oder aktionsrelevante Statusmeldungen zu kommunizieren.

---

# Background Color

## Base Colors

Die AccentBox unterstützt die Basisfarben **Blue** und **Neutral** (Default).
Diese helfen dabei, Inhalte für den User dezent hervorzuheben.

```tsx
import {
  AccentBox,
  BigNumber,
  ColumnLayout,
  Flex,
  Rating,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<Section>
  <ColumnLayout>
    <AccentBox backgroundColor="neutral">
      <Flex direction="column" gap="s" align="center">
        <BigNumber>
          <Text>250 ms</Text>
          <Text>Dateioperationen</Text>
        </BigNumber>
        <Rating
          value={4}
          isReadOnly
          aria-label="Dateioperationen"
        />
        <Text>
          <small>Geringer Optimierungsbedarf</small>
        </Text>
      </Flex>
    </AccentBox>
    <AccentBox backgroundColor="blue">
      <Flex direction="column" gap="xs" align="center">
        <BigNumber>
          <Text>100 ms</Text>
          <Text>Serveroperationen</Text>
        </BigNumber>
        <Rating
          value={2}
          isReadOnly
          aria-label="Serveroperationen"
        />
        <Text>
          <small>Optimierungsbedarf</small>
        </Text>
      </Flex>
    </AccentBox>
  </ColumnLayout>
</Section>
```

## Brand Colors

Die Brand Colors **Teal**, **Violet**, **Lilac**, **Navy** und **Green** eignen
sich besonders für werbliche Inhalte und Marketing-Storys.

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

<>
  <AccentBox backgroundColor="teal">
    <Heading>Teal</Heading>
  </AccentBox>
  <AccentBox backgroundColor="violet">
    <Heading>Violet</Heading>
  </AccentBox>
  <AccentBox backgroundColor="lilac">
    <Heading>Lilac</Heading>
  </AccentBox>
  <AccentBox backgroundColor="navy">
    <Heading>Navy</Heading>
  </AccentBox>
  <AccentBox backgroundColor="green">
    <Heading>Green</Heading>
  </AccentBox>
</>
```

## Custom Color

Die AccentBox unterstützt zusätzlich eine benutzerdefinierte Farbe. Diese Option
sollte nur in Ausnahmefällen genutzt werden. Für die meisten Use Cases sollten
**Base Colors** oder **Brand Colors** verwendet werden, damit die visuelle
Konsistenz erhalten bleibt.

```tsx
import {
  AccentBox,
  Heading,
  Link,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<AccentBox backgroundColor="#d8f5d6" color="dark-static">
  <Section>
    <Heading>Tipps & Tricks für mehr Klimaschutz</Heading>
    <Text>
      Dein Cronjob läuft in weniger als
      5-Minuten-Intervallen. Das verbraucht mehr Ressourcen.
      Falls das nicht unbedingt nötig ist, kannst du ein
      längeres Intervall wählen - das spart Energie und
      schützt das Klima
    </Text>
    <Link href="#" target="_blank">
      Blogartikel zu mehr Nachhaltigkeit
    </Link>
  </Section>
</AccentBox>
```

## Gradient

Eine AccentBox mit Gradient hebt sich visuell stärker hervor. Dadurch eignet
sich diese Variante besonders für aufmerksamkeitsstarke Inhalte wie
Werbemaßnahmen.

```tsx
import {
  AccentBox,
  Color,
  Flex,
  Heading,
  Link,
  Text,
} from "@mittwald/flow-react-components";

<AccentBox backgroundColor="gradient" color="dark">
  <Flex align="center" wrap="wrap" gap="m">
    <Flex direction="column" grow>
      <Heading size="l">
        <Color color="violet">mStudio Extension</Color>{" "}
        selber entwickeln
      </Heading>
      <Text>
        <strong>
          Veröffentliche{" "}
          <Color color="violet">eigene Features</Color> im
          mStudio
        </strong>
      </Text>
    </Flex>
    <Link target="_blank" href="#">
      Contributor Landingpage
    </Link>
  </Flex>
</AccentBox>
```

---

# Background Image

Die AccentBox unterstützt ein Hintergrundbild. Über `aspectRatio` kann ein
festes Seitenverhältnis definiert werden.

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

<ColumnLayout>
  <AccentBox
    backgroundImage="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
    aspectRatio={1}
    color="light-static"
  >
    <Heading>Mit Background Image</Heading>
  </AccentBox>
</ColumnLayout>
```

---

# Kombiniere mit ...

## Link

Die AccentBox kann in einen [Link](https://flow.mittwald.de/components/navigation/link) gewrappt werden,
um die gesamte Component klickbar zu machen.

```tsx
import {
  AccentBox,
  LayoutCard,
  Link,
} from "@mittwald/flow-react-components";

<>
  <Link href="#" target="_blank">
    <AccentBox backgroundColor="blue">
      Verlinkte AccentBox
    </AccentBox>
  </Link>
  <Link href="#" target="_blank">
    <LayoutCard>
      <AccentBox backgroundColor="blue">
        Verlinkte AccentBox in LayoutCard
      </AccentBox>
    </LayoutCard>
  </Link>
</>
```

## LayoutCard

Befindet sich eine AccentBox als erstes Element innerhalb einer
[LayoutCard](https://flow.mittwald.de/components/structure/layout-card), füllt sie die gesamte Größe der
LayoutCard aus.

```tsx
import {
  AccentBox,
  Color,
  Flex,
  Heading,
  LayoutCard,
  Link,
  Text,
} from "@mittwald/flow-react-components";

<LayoutCard>
  <AccentBox backgroundColor="gradient" color="dark">
    <Flex align="center" wrap="wrap" gap="m">
      <Flex direction="column" grow>
        <Heading size="l">
          <Color color="violet">mStudio Extension</Color>{" "}
          selber entwickeln
        </Heading>
        <Text>
          <strong>
            Veröffentliche{" "}
            <Color color="violet">eigene Features</Color> im
            mStudio
          </strong>
        </Text>
      </Flex>
      <Link target="_blank" href="#" color="dark">
        Contributor Landingpage
      </Link>
    </Flex>
  </AccentBox>
</LayoutCard>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aspectRatio` | `AspectRatio` | - | The aspect ratio of the accent box. |
| `backgroundColor` | `AccentBoxWithCustomBackgroundColor` | `"neutral"` | The background color of the accent box. |
| `backgroundImage` | `string` | - | The background image of the accent box. |
| `children` | `ReactNode` | - | - |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static"` | `"default"` | The content color of the accent box. |
| `elementType` | `"div" \| "article" \| ExoticComponent<{}> \| "section"` | - | The HTML element or React component rendered as the elements root. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--accent-box--padding` | `16px` |
| `--accent-box--corner-radius` | `8px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--accent-box--background-color-neutral` | `#E5EFF8` | `#3A434E` |
| `--accent-box--background-color-blue` | `#E0EBFF` | `#002A7B` |
| `--accent-box--background-color-teal` | `#cffaff` | `#004f59` |
| `--accent-box--background-color-lilac` | `#f6dfff` | `#5f0083` |
| `--accent-box--background-color-violet` | `#EAE7FD` | `#483b9f` |
| `--accent-box--background-color-green` | `#C0FFEB` | `#003B29` |
| `--accent-box--background-color-navy` | `#C8CFEE` | `#131B3D` |
| `--accent-box--background-color-gradient` | `radial-gradient(circle at 27.74% 38.09%,#d8e9f8,transparent 60%),radial-gradient(circle at 63.98% 99.4%,#e4b8ff,transparent 37%),radial-gradient(circle at 79.7% 64.93%,#d8e9f8,transparent 52%),radial-gradient(circle at 10.9% 91.41%,#d8e9f8,transparent 56%),radial-gradient(circle at 3.68% 3.26%,#0056ff,transparent 31%),radial-gradient(circle at 99.62% 17.78%,#48c7d8,transparent 26%),radial-gradient(circle at 58.65% 24.91%,#d8e9f8,transparent 55%),radial-gradient(circle at 53.23% 52.72%,#d8e9f8,transparent 100%),radial-gradient(circle at 50% 50%,#fff,#fff 100%)` | `radial-gradient(circle at 18% 20%, #3D55C159, transparent 22%), radial-gradient(circle at 82% 18%, #00A1B54D, transparent 18%), radial-gradient(circle at 70% 82%, #715DEE47, transparent 24%), linear-gradient(180deg, #06070A 0%, #0A0E18 45%, #0F1424 100%)` |

---

# Accordion

Das Accordion blendet einen Content-Bereich ein und aus und spart so Platz.

> **mStudio-Extensions:** Importiere `Accordion` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

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

<Accordion>
  <Heading>Zugangsdaten</Heading>
  <Content>
    <Text>
      Die Zugangsdaten für SSH und SFTP findest du in den
      Projekteinstellungen.
    </Text>
  </Content>
</Accordion>
```

---

# Best Practices

- Verberge keine essenziellen Inhalte im Accordion. Eingeklappte Inhalte werden
  standardmäßig nicht direkt wahrgenommen.
- Nutze eine Heading als Titel, wenn das Accordion einen Abschnitt der Seite
  bildet. Nur dann erscheint es in der Seitenstruktur, über die
  Screenreader-Nutzer navigieren.
- Wähle das Level der Heading passend zur umgebenden Seite, ohne Ebenen zu
  überspringen. Ohne `level` ist die Heading eine `h3`.
- Fasse mehrere Accordions untereinander in einer
  [AccordionGroup](https://flow.mittwald.de/components/structure/accordion-group) zusammen. Sie wirken
  dann als kompakter Block.
- Platziere keine interaktiven Elemente wie Buttons im Titel. Der Titel ist
  selbst ein Button.
- Formuliere die Titel klar und prägnant.

---

# Mit Text

Mit einem Text als Titel ist das Accordion keine Überschrift und erscheint in
normaler Textschrift. Nutze ihn für ergänzende Inhalte wie weitere Optionen oder
Details.

```tsx
import {
  Accordion,
  Content,
  Text,
} from "@mittwald/flow-react-components";

<Accordion>
  <Text>Erweiterte Einstellungen</Text>
  <Content>
    <Text>
      Einstellungen, die die meisten Projekte nicht
      benötigen.
    </Text>
  </Content>
</Accordion>
```

---

# Mit Label

Mit einem Label als Titel ist das Accordion keine Überschrift und erscheint als
Label. Nutze es für kompakte Bereiche wie Filter oder Einstellungen.

```tsx
import {
  Accordion,
  Content,
  Label,
  Text,
} from "@mittwald/flow-react-components";

<Accordion>
  <Label>Filter</Label>
  <Content>
    <Text>Zeige nur Projekte mit aktivem Backup.</Text>
  </Content>
</Accordion>
```

---

# Default Expanded

Über `defaultExpanded` ist das Accordion beim Laden der Seite geöffnet.

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

<Accordion defaultExpanded>
  <Heading>Zugangsdaten</Heading>
  <Content>
    <Text>
      Die Zugangsdaten für SSH und SFTP findest du in den
      Projekteinstellungen.
    </Text>
  </Content>
</Accordion>
```

---

# Kombiniere mit …

## AccordionGroup

Die [AccordionGroup](https://flow.mittwald.de/components/structure/accordion-group) fasst mehrere
Accordions zu einem Block mit Trennlinien zusammen.

```tsx
import {
  Accordion,
  AccordionGroup,
  Content,
  Heading,
  Text,
} from "@mittwald/flow-react-components";

<AccordionGroup>
  <Accordion>
    <Heading>Rechnungen</Heading>
    <Content>
      <Text>
        Deine Rechnungen der letzten zwölf Monate.
      </Text>
    </Content>
  </Accordion>
  <Accordion>
    <Heading>Verträge</Heading>
    <Content>
      <Text>Alle aktiven und gekündigten Verträge.</Text>
    </Content>
  </Accordion>
  <Accordion>
    <Heading>Zahlungsart</Heading>
    <Content>
      <Text>
        Lastschrift vom Konto mit der Endung 1234.
      </Text>
    </Content>
  </Accordion>
</AccordionGroup>
```

## Badge und AlertBadge

Ein [Badge](https://flow.mittwald.de/components/status/badge) oder
[AlertBadge](https://flow.mittwald.de/components/status/alert-badge) im Titel wird Teil des Buttons und
damit Teil seines Namens für Screenreader.

```tsx
import {
  Accordion,
  AlertBadge,
  Badge,
  Content,
  Heading,
  Text,
} from "@mittwald/flow-react-components";

<Accordion>
  <Heading>
    Rechnungen
    <Badge>3 offen</Badge>
    <AlertBadge status="warning">Überfällig</AlertBadge>
  </Heading>
  <Content>
    <Text>Deine Rechnungen der letzten zwölf Monate.</Text>
  </Content>
</Accordion>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultExpanded` | `boolean` | - | Whether the accordion should be initially expanded. |
| `id` | `string` | - | The key of the accordion inside an `AccordionGroup`, used by its `expandedKeys`. Also set as the DOM id. |
| `variant` _(deprecated)_ | `"default" \| "outline"` | - | The visual variant of the accordion. Has no effect. @deprecated Use `AccordionGroup` or a `LayoutCard` to set accordions apart. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--accordion--spacing` | `0.5rem` |
| `--accordion--corner-radius` | `8px` |
| `--accordion--border-width` | `1px` |
| `--accordion--border-style` | `solid` |
| `--accordion--padding` | `8px` |
| `--accordion--padding-s-y` | `4px` |
| `--accordion--content-padding-bottom` | `24px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--accordion--border-color` | `#5E6C7A` | `#DCE9F7` |
| `--accordion--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--accordion--background-color--pressed` | `#DCE9F7` | `#5E6C7A` |

---

# AccordionGroup

Die AccordionGroup fasst mehrere Accordions zu einem kompakten Block zusammen.

> **mStudio-Extensions:** Importiere `AccordionGroup` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  Accordion,
  AccordionGroup,
  Content,
  Heading,
  Text,
} from "@mittwald/flow-react-components";

<AccordionGroup>
  <Accordion>
    <Heading>Rechnungen</Heading>
    <Content>
      <Text>
        Deine Rechnungen der letzten zwölf Monate.
      </Text>
    </Content>
  </Accordion>
  <Accordion>
    <Heading>Verträge</Heading>
    <Content>
      <Text>Alle aktiven und gekündigten Verträge.</Text>
    </Content>
  </Accordion>
  <Accordion>
    <Heading>Zahlungsart</Heading>
    <Content>
      <Text>
        Lastschrift vom Konto mit der Endung 1234.
      </Text>
    </Content>
  </Accordion>
</AccordionGroup>
```

---

# Best Practices

- Nutze die AccordionGroup, sobald mehrere Accordions direkt untereinander
  stehen. Der Abstand des umgebenden Layouts liegt dann nur um den Block herum.
- Erlaube in der Regel, mehrere Accordions gleichzeitig zu öffnen. So lassen
  sich Inhalte vergleichen, und der angeklickte Titel springt nicht.

---

# Nur ein Accordion geöffnet

Mit `allowsMultipleExpanded={false}` schließt das Öffnen eines Accordions alle
anderen. Das eignet sich für Inhalte, die nacheinander gelesen werden, wie die
Schritte einer Anleitung.

```tsx
import {
  Accordion,
  AccordionGroup,
  Content,
  Heading,
  Text,
} from "@mittwald/flow-react-components";

<AccordionGroup allowsMultipleExpanded={false}>
  <Accordion defaultExpanded>
    <Heading>Schritt 1: Domain registrieren</Heading>
    <Content>
      <Text>
        Wähle eine freie Domain und registriere sie.
      </Text>
    </Content>
  </Accordion>
  <Accordion>
    <Heading>Schritt 2: DNS einrichten</Heading>
    <Content>
      <Text>Verbinde die Domain mit deinem Projekt.</Text>
    </Content>
  </Accordion>
  <Accordion>
    <Heading>Schritt 3: Zertifikat ausstellen</Heading>
    <Content>
      <Text>
        Sichere die Domain mit einem TLS-Zertifikat ab.
      </Text>
    </Content>
  </Accordion>
</AccordionGroup>
```

---

# Ohne Trennlinien

Mit `separators={false}` entfallen die Trennlinien zwischen den Accordions.

```tsx
import {
  Accordion,
  AccordionGroup,
  Content,
  Text,
} from "@mittwald/flow-react-components";

<AccordionGroup separators={false}>
  <Accordion>
    <Text>Erweiterte Einstellungen</Text>
    <Content>
      <Text>
        Einstellungen, die die meisten Projekte nicht
        benötigen.
      </Text>
    </Content>
  </Accordion>
  <Accordion>
    <Text>Experimentelle Funktionen</Text>
    <Content>
      <Text>Funktionen, die sich noch ändern können.</Text>
    </Content>
  </Accordion>
</AccordionGroup>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `allowsMultipleExpanded` | `boolean` | `true` | Whether several accordions can be expanded at the same time. When false, expanding one accordion collapses the others. Unlike React Aria's `DisclosureGroup`, this defaults to `true`. |
| `children` | `ReactNode` | - | - |
| `defaultExpandedKeys` | `Iterable<string>` | - | The `id`s of the accordions that are expanded initially. |
| `expandedKeys` | `Iterable<string>` | - | The `id`s of the expanded accordions, when the group is controlled. Like React Aria's `expandedKeys`, but an accordion's `id` is a string. |
| `separators` | `boolean` | `true` | Whether separators are drawn between the accordions. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onExpandedChange` | `((expandedKeys: Set<string>) => void)` | - | Called with the `id`s of the expanded accordions when they change. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Align

Align ordnet bekannte Kombinationen von Components korrekt zueinander an.

> **mStudio-Extensions:** Importiere `Align` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  Combine,
  Avatar,
  Initials,
  Text,
} from "@mittwald/flow-react-components";

<Combine>
  <Avatar>
    <Initials>Max Mustermann</Initials>
  </Avatar>
  <Text>
    <strong>Max Mustermann</strong>
    Organisationsinhaber
  </Text>
</Combine>
```

---

# Best Practices

- Ersetze `<Align />` durch [Combine](https://flow.mittwald.de/components/structure/combine). Funktional
  ändert sich nichts, der neue Name beschreibt die Component treffender.
- Für die Umbenennung gibt es einen Codemod – er passt benannte, umbenannte und
  Namespace-Imports an:
  `npx @mittwald/flow-codemods@latest align-to-combine src`. Siehe
  [Upgrades](https://flow.mittwald.de/get-started/upgrades).
- Align gibt zur Laufzeit eine Deprecation-Warnung aus und wird in einer
  zukünftigen Major-Version entfernt. Bis dahin bleibt der alte Pfad abgesichert
  (siehe [Versionierung & Stabilität](https://flow.mittwald.de/get-started/versioning)).

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

---

# ColumnLayout

Das ColumnLayout organisiert Inhalte in Spalten, definierbar je Breakpoint.

> **mStudio-Extensions:** Importiere `ColumnLayout` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  ColumnLayout,
  Content,
  Label,
  LabeledValue,
} from "@mittwald/flow-react-components";

<ColumnLayout>
  <LabeledValue>
    <Label>Vorname</Label>
    <Content>Max</Content>
  </LabeledValue>
  <LabeledValue>
    <Label>Nachname</Label>
    <Content>Mustermann</Content>
  </LabeledValue>
  <LabeledValue>
    <Label>Straße</Label>
    <Content>Musterstraße 1</Content>
  </LabeledValue>
  <LabeledValue>
    <Label>Ort</Label>
    <Content>32423 Minden</Content>
  </LabeledValue>
  <LabeledValue>
    <Label>Telefon</Label>
    <Content>+49 571 000000</Content>
  </LabeledValue>
  <LabeledValue>
    <Label>E-Mail</Label>
    <Content>max@example.com</Content>
  </LabeledValue>
</ColumnLayout>
```

---

# Best Practices

- Verwende nicht zu viele Spalten, in der Regel höchstens vier.
- Wähle die Spaltenbreiten bewusst. Einheitliche Breiten wirken harmonisch,
  unterschiedliche lenken den Fokus auf breitere Inhalte.
- Kombiniere das ColumnLayout bei Bedarf mit einer
  [Section](https://flow.mittwald.de/components/structure/section). Das schafft übersichtliche Layouts.
- Verschachtele mehrere ColumnLayouts, um Inhalte optisch zu gruppieren. Jedes
  verschachtelte ColumnLayout bildet einen eigenen Container und bricht bei
  seiner eigenen Breite um, nicht bei der des äußeren.

---

# Breakpoints

Die Breakpoints beziehen sich auf die Breite des Containers, in dem das
ColumnLayout steht, nicht auf die des Bildschirms. Ihre Default-Werte sind:

- Größe `s` bis 550 Pixel Breite: `[1]`
- Größe `m` bis 850 Pixel Breite: `[1, 1]`
- Größe `l` ab 851 Pixel Breite: `[1, 1, 1]`

Ein Breakpoint ohne eigenen Wert übernimmt den des nächstkleineren; die
Default-Werte greifen nur, solange kein kleinerer Breakpoint gesetzt ist.

---

# Spalten

Die Properties `s`, `m` und `l` legen je Breakpoint fest, wie viele Spalten es
gibt und in welchem Verhältnis sie stehen. Das Verhältnis gilt unabhängig vom
Inhalt: Breiter Inhalt macht seine Spalte nicht breiter.

```tsx
import {
  ColumnLayout,
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<ColumnLayout m={[2, 1]} l={[2, 1, 1]}>
  <TextField isRequired>
    <Label>Straße</Label>
  </TextField>
  <TextField isRequired>
    <Label>Hausnummer</Label>
  </TextField>
</ColumnLayout>
```

## Ausgeblendete Spalten

Als Wert kann neben Zahlen auch `null` mitgegeben werden. Die entsprechende
Spalte wird dann ausgeblendet.

```tsx
import {
  ColumnLayout,
  Heading,
  Image,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<ColumnLayout s={[1, null]} m={[2, 1]} l={[5, 1]}>
  <Section>
    <Heading>mStudio entdecken</Heading>
    <Text>
      Du willst das Beste aus deinen Projekten herausholen?
      Unsere Wissensdatenbank hilft dir dabei, das mStudio
      und seine Möglichkeiten besser kennenzulernen.
    </Text>
  </Section>
  <Image
    src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
    alt="mittwald"
    withBorder
  />
</ColumnLayout>
```

---

# Abstände

Die Abstände des ColumnLayout können in vier Stufen angepasst werden: `s`, `m`,
`l` und `xl`.

Das Property `rowGap` steuert die Abstände zwischen den Zeilen (oben und unten),
`columnGap` die Abstände zwischen den Spalten (rechts und links) und `gap` setzt
alle Abstände gleichzeitig.

```tsx
import {
  ColumnLayout,
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<ColumnLayout m={[1, 1]} rowGap="s" columnGap="l">
  <TextField isRequired>
    <Label>Vorname</Label>
  </TextField>
  <TextField isRequired>
    <Label>Nachname</Label>
  </TextField>
  <ColumnLayout s={[2, 1]} columnGap="m">
    <TextField isRequired>
      <Label>Straße</Label>
    </TextField>
    <TextField isRequired>
      <Label>Hausnummer</Label>
    </TextField>
  </ColumnLayout>
  <TextField isRequired>
    <Label>Ort</Label>
  </TextField>
</ColumnLayout>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `columnGap` | `"s" \| "m" \| "l" \| "xl"` | - | Size of the column gap between the content blocks inside the column layout. |
| `elementType` | `"div" \| ExoticComponent<{}> \| "ul"` | - | The HTML element or React component rendered as the elements root. |
| `gap` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | Size of the row and column gap between the content blocks inside the column layout. |
| `l` | `(number \| null)[]` | - | Column layout for container size l. |
| `m` | `(number \| null)[]` | - | Column layout for container size m. |
| `rowGap` | `"s" \| "m" \| "l" \| "xl"` | - | Size of the row gap between the content blocks inside the column layout. |
| `s` | `(number \| null)[]` | - | Column layout for container size s. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--column-layout--gap--s` | `8px` |
| `--column-layout--gap--m` | `16px` |
| `--column-layout--gap--l` | `24px` |
| `--column-layout--gap--xl` | `32px` |

---

# Combine

Combine ordnet bekannte Kombinationen von Components korrekt zueinander an.

> **mStudio-Extensions:** Importiere `Combine` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  Combine,
  Avatar,
  Initials,
  Text,
} from "@mittwald/flow-react-components";

<Combine>
  <Avatar>
    <Initials>Max Mustermann</Initials>
  </Avatar>
  <Text>
    <strong>Max Mustermann</strong>
    Organisationsinhaber
  </Text>
</Combine>
```

---

# Best Practices

- Verwende nur die unterstützten Kombinationen. Andere Kombinationen erzeugen
  keine Anordnung.
- Nutze Combine nicht als generisches Layout-Tool. Für eine freie Anordnung ist
  [Flex](https://flow.mittwald.de/components/structure/flex) vorgesehen, für Spalten das
  [ColumnLayout](https://flow.mittwald.de/components/structure/column-layout).
- Nutze neben der Anordnung auch visuelle Anpassungen wie das Setzen von Colors.

## Combine vs. Flex

Combine ist das fertige Pattern, [Flex](https://flow.mittwald.de/components/structure/flex) das freie
Werkzeug. Prüfe deshalb zuerst, ob die gewünschte Anordnung schon als
Kombination existiert – dann bleibt sie auch bei geändertem Inhalt und über alle
Breakpoints korrekt.

**Verwende Combine, um ...**

- eine der unterstützten Kombinationen darzustellen.
- die Anordnung dem Designsystem zu überlassen.

**Verwende Flex, um ...**

- individuelle Layouts zu gestalten, die keinem festen UI-Pattern folgen.
- bewusst vom Standard des Designsystems abzuweichen.

---

# Kombinationen

Neben [Avatar](https://flow.mittwald.de/components/content/avatar) + [Text](https://flow.mittwald.de/components/content/text)
unterstützt Combine die folgenden Kombinationen.

## Input + Button

Der [Button](https://flow.mittwald.de/components/actions/button) sitzt auf der Höhe des Eingabefelds –
unabhängig davon, ob das Feld ein [Label](https://flow.mittwald.de/components/content/label) oder eine
FieldDescription hat.

```tsx
import {
  Combine,
  Button,
  Label,
  TextField,
} from "@mittwald/flow-react-components";

<Combine>
  <TextField>
    <Label>Weiterleitungsziel</Label>
  </TextField>
  <Button>Hinzufügen</Button>
</Combine>
```

## Text + CopyButton

```tsx
import {
  Combine,
  CopyButton,
  Text,
} from "@mittwald/flow-react-components";

<Combine>
  <Text>mail.agenturserver.de</Text>
  <CopyButton text="mail.agenturserver.de" />
</Combine>
```

## Icon + Text

```tsx
import {
  Combine,
  IconDomain,
  Text,
} from "@mittwald/flow-react-components";

<Combine>
  <IconDomain />
  <Text>mail.agenturserver.de</Text>
</Combine>
```

## Text + ContextualHelp

```tsx
import {
  Combine,
  Button,
  ContextualHelp,
  ContextualHelpTrigger,
  Text,
} from "@mittwald/flow-react-components";

<Combine>
  <Text>mail.agenturserver.de</Text>

  <ContextualHelpTrigger>
    <Button />

    <ContextualHelp>
      <Text>
        Hier wird die URL des Servers angezeigt, der für den
        E-Mail-Versand genutzt wird.
      </Text>
    </ContextualHelp>
  </ContextualHelpTrigger>
</Combine>
```

## Kbd + Text

Beschriftet ein Tastenkürzel, etwa in einer Legende. Gehören mehrere
[Kbd](https://flow.mittwald.de/components/content/kbd) zu einem [Text](https://flow.mittwald.de/components/content/text), stehen
sie alle in derselben Combine.

```tsx
import {
  Combine,
  Kbd,
  Text,
} from "@mittwald/flow-react-components";

<Combine>
  <Kbd variant="soft">↑</Kbd>
  <Kbd variant="soft">↓</Kbd>
  <Text>Auswählen</Text>
</Combine>
```

## Kbd + Kbd

Mehrere Kbd stehen enger beieinander als Kbd und Text.

```tsx
import {
  Combine,
  Kbd,
} from "@mittwald/flow-react-components";

<Combine>
  <Kbd variant="soft">↑</Kbd>
  <Kbd variant="soft">↓</Kbd>
</Combine>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--combine--avatar-text--spacing` | `0.5rem` |
| `--combine--input-button--spacing` | `16px` |
| `--combine--text-button--spacing` | `0.25rem` |
| `--combine--icon-text--spacing` | `0.5rem` |
| `--combine--kbd-kbd--spacing` | `0.25rem` |
| `--combine--kbd-text--spacing` | `0.5rem` |

---

# Flex

Flex ordnet Components CSS-Flexbox-basiert in einem Flex-Container an.

> **mStudio-Extensions:** Importiere `Flex` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

Individuelles Layout mit Flex

Der Einsatz von Flex führt zu individuellen Layouts, die vom Designsystem
abweichen. Das kann den Wartungsaufwand erhöhen und für User zu ungewohnten
Interaktionen führen. Nutze Flex daher nur für gezielte, kleine
Layout-Anpassungen und überlege sorgfältig, ob der Einsatz wirklich
notwendig ist. Für wiederkehrende Kombinationen ist
[Combine](https://flow.mittwald.de/components/structure/combine) zuständig.

```tsx
import {
  LayoutCard,
  Flex,
} from "@mittwald/flow-react-components";

<Flex gap="m" justify="center">
  <LayoutCard />
  <LayoutCard />
  <LayoutCard />
</Flex>
```

---

# Best Practices

- Nutze Flex nicht für Layouts, die sich mit
  [Combine](https://flow.mittwald.de/components/structure/combine) und einem festen UI-Pattern umsetzen
  lassen.
- Setze Flex gezielt für Sonderfälle ein. Für die meisten Fälle bietet das
  Designsystem bereits eine passende Lösung.
- Nutze für ein Layout über mehrere Spalten das
  [ColumnLayout](https://flow.mittwald.de/components/structure/column-layout). Es bricht je Breakpoint
  automatisch um.

## Flex vs. Combine

Flex ist das freie Werkzeug, [Combine](https://flow.mittwald.de/components/structure/combine) das
fertige Pattern. Prüfe deshalb zuerst, ob die gewünschte Anordnung schon als
Kombination existiert – dann bleibt sie auch bei geändertem Inhalt und über alle
Breakpoints korrekt.

**Verwende Flex, um ...**

- individuelle Layouts zu gestalten, die keinem festen UI-Pattern folgen.
- bewusst vom Standard des Designsystems abzuweichen.

**Verwende Combine, um ...**

- vorab definierte Components miteinander zu kombinieren und automatisch anzuordnen.
- wiederkehrende UI-Patterns konsistent umzusetzen.

---

# Kombiniere mit ...

## List

Innerhalb einer [List](https://flow.mittwald.de/components/list/list) platzierst du mit `<Flex />` den
Content eines ListItems gezielt – in diesem Beispiel den zweiten Text in der
rechten unteren Ecke.

```tsx
import {
  Avatar,
  Content,
  Flex,
  Heading,
  IconExtension,
  Text,
  typedList,
} from "@mittwald/flow-react-components";

export default () => {
  const List = typedList<{ text: string }>();

  return (
    <List.List
      defaultViewMode="tiles"
      aria-label="Extensions"
    >
      <List.StaticData
        data={[
          { text: "Meine Extension" },
          {
            text: "Meine andere Extension mit einen deutlich längeren Namen",
          },
        ]}
      />
      <List.Item
        showTiles
        showList={false}
        textValue={(i) => i.text}
      >
        {(i) => (
          <List.ItemView>
            <Avatar>
              <IconExtension />
            </Avatar>
            <Heading>{i.text}</Heading>

            <Content slot="bottom">
              <Flex justify="end" align="end">
                <Text>Kostenlos</Text>
              </Flex>
            </Content>
          </List.ItemView>
        )}
      </List.Item>
    </List.List>
  );
}
```

## LayoutCard

Innerhalb einer [LayoutCard](https://flow.mittwald.de/components/structure/layout-card) ordnest du mit
`<Flex />` einzelne Elemente gezielt an – hier den Button am unteren Rand.

```tsx
import {
  Button,
  Flex,
  LayoutCard,
  Text,
} from "@mittwald/flow-react-components";

<LayoutCard style={{ minHeight: 300 }}>
  <Text>
    Labore, similique. Earum, quas in. At dolorem corrupti
    blanditiis nulla deserunt laborum! Corrupti delectus
    aspernatur nihil nulla obcaecati ipsam porro sequi rem?
    Quam.
  </Text>
  <Flex align="end" grow>
    <Button>Install</Button>
  </Flex>
</LayoutCard>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "end" \| "center" \| "baseline" \| "stretch"` | `"start"` | The alignItems value of the element. |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `columnGap` | `"s" \| "xs" \| "m" \| "l" \| "xl"` | - | The columnGap size of the element. |
| `direction` | `"-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "row" \| "column" \| "column-reverse" \| "row-reverse"` | `"row"` | The flexDirection value of the element. |
| `elementType` | `"div" \| "span" \| "p" \| "main" \| ExoticComponent<{}> \| "aside" \| "footer" \| "header" \| "li" \| "ol" \| "section" \| "ul"` | - | The HTML element or React component rendered as the elements root. |
| `gap` | `"s" \| "xs" \| "m" \| "l" \| "xl"` | - | The gap size of the element. |
| `grow` | `boolean` | - | Whether the element should grow. |
| `justify` | `JustifyContent` | `"start"` | The justifyContent value of the element. |
| `padding` | `"s" \| "xs" \| "m" \| "l" \| "xl"` | - | The padding of the element. |
| `paddingBlock` | `"s" \| "xs" \| "m" \| "l" \| "xl"` | - | The padding top and bottom of the element. Takes precedence over `padding`. |
| `paddingBottom` | `"s" \| "xs" \| "m" \| "l" \| "xl"` | - | The padding bottom of the element. |
| `paddingInline` | `"s" \| "xs" \| "m" \| "l" \| "xl"` | - | The padding left and right of the element. Takes precedence over `padding`. |
| `paddingLeft` | `"s" \| "xs" \| "m" \| "l" \| "xl"` | - | The padding left of the element. |
| `paddingRight` | `"s" \| "xs" \| "m" \| "l" \| "xl"` | - | The padding right of the element. |
| `paddingTop` | `"s" \| "xs" \| "m" \| "l" \| "xl"` | - | The padding top of the element. |
| `rowGap` | `"s" \| "xs" \| "m" \| "l" \| "xl"` | - | The rowGap size of the element. |
| `wrap` | `"wrap" \| "-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "nowrap" \| "wrap-reverse"` | `"nowrap"` | The flexWrap value of the element. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# LayoutCard

Eine LayoutCard ist ein einfacher Container, der mit beliebigem Inhalt gefüllt werden kann.

> **mStudio-Extensions:** Importiere `LayoutCard` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<LayoutCard>Inhalt der Layout Card</LayoutCard>
```

---

# Best Practices

- Strukturiere den Content sinnvoll, zum Beispiel mit
  [Section](https://flow.mittwald.de/components/structure/section) und
  [ColumnLayout](https://flow.mittwald.de/components/structure/column-layout).
- Platziere einen seitenweiten [Alert](https://flow.mittwald.de/components/status/alert) in der
  LayoutCard vor der ersten Section.
- Kombiniere die LayoutCard bei Bedarf mit einer
  [AccentBox](https://flow.mittwald.de/components/structure/accent-box). So hebst du Inhalte besonders
  hervor.

---

# Kombiniere mit ...

## TabNavigation

Platziere die [TabNavigation](https://flow.mittwald.de/components/navigation/tab-navigation) in einer
LayoutCard, um zwischen den Unterseiten zu navigieren. Der Inhalt der aktiven
Seite wird darunter in derselben LayoutCard dargestellt.

```tsx
import {
  LayoutCard,
  TabNavigation,
  Link,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<LayoutCard>
  <TabNavigation aria-label="Projekt-Navigation">
    <Link href="#" aria-current="page">
      Apps
    </Link>
    <Link href="#">Container</Link>
    <Link href="#">Domains</Link>
    <Link href="#">E-Mails</Link>
    <Link href="#">Backups</Link>
  </TabNavigation>
  <Section>
    <Text>
      Der Inhalt der aktiven Seite wird unterhalb der
      TabNavigation in derselben LayoutCard dargestellt.
    </Text>
  </Section>
</LayoutCard>
```

## Alert

Gilt ein [Alert](https://flow.mittwald.de/components/status/alert#position-seitenweit) für die gesamte
Seite, platziere ihn in der LayoutCard vor der ersten Section – nicht oberhalb
der LayoutCard. Enthält die LayoutCard eine TabNavigation, steht der Alert
unterhalb der Tabs. Verteilt sich die Seite auf mehrere LayoutCards, gehört der
Alert in die LayoutCard, deren Inhalt er betrifft.

```tsx
import {
  Alert,
  Heading,
  LayoutCard,
  Link,
  Section,
  TabNavigation,
  Text,
} from "@mittwald/flow-react-components";

<LayoutCard>
  <TabNavigation aria-label="E-Mail-Navigation">
    <Link href="#" aria-current="page">
      Details
    </Link>
    <Link href="#">Weiterleitungen</Link>
    <Link href="#">Spamschutz</Link>
  </TabNavigation>
  <Alert status="danger">
    <Heading>E-Mail-Adresse wurde archiviert</Heading>
    <Text>
      Da deine Domain gelöscht wurde, wurde diese
      E-Mail-Adresse archiviert. Um E-Mails empfangen und
      senden zu können musst du die E-Mail-Adresse
      bearbeiten.
    </Text>
  </Alert>
  <Section>
    <Heading>E-Mail-Adresse</Heading>
    <Text>...</Text>
  </Section>
  <Section>
    <Heading>Speicherplatz</Heading>
    <Text>...</Text>
  </Section>
</LayoutCard>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `elementType` | `"div" \| "main" \| ExoticComponent<{}> \| "footer" \| "header"` | - | The HTML element or React component rendered as the elements root. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--layout-card--corner-radius` | `16px` |
| `--layout-card--padding` | `24px` |
| `--layout-card--padding-mobile` | `16px` |
| `--layout-card--box-shadow` | `rgb(0 0 0 / 12.5%) 0 2px 4px` |
| `--layout-card--border-style` | `solid` |
| `--layout-card--border-width` | `1px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--layout-card--background-color` | `#FFFFFF` | `#1B1F24` |
| `--layout-card--border-color` | `#E5EFF8` | `#3A434E` |

---

# Section

Eine Section gliedert Content in Teilbereiche und trennt sie durch einen Separator.

> **mStudio-Extensions:** Importiere `Section` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<Section>
  <Heading>Newsletter</Heading>
  <Text>
    Kommende Releases, neue Features und Tipps rund um dein
    Hosting – wir bringen dir das Wichtigste in dein
    Postfach. Abonniere unseren Newsletter und bleib auf dem
    Laufenden.
  </Text>
</Section>
```

---

# Best Practices

- Gib jeder Section eine kurze, aussagekräftige
  [Heading](https://flow.mittwald.de/components/content/heading).
- Stelle bei mehreren Sections die wichtigste nach oben. So sieht der User den
  wichtigsten oder am häufigsten genutzten Content zuerst.
- Setze Sections sparsam ein. Verteile umfangreichen Content sonst auf mehrere
  Seiten oder eine [TabNavigation](https://flow.mittwald.de/components/navigation/tab-navigation).
- Beziehe AlertBadge, Badge und Actions immer auf ihre eigene Section.

---

# Mehrere Sections

Werden mehrere Sections untereinander platziert, trennt sie automatisch ein
[Separator](https://flow.mittwald.de/components/structure/separator).

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

<>
  <Section>
    <Header>
      <Heading>Datenbanken</Heading>
      <Button>Datenbank verknüpfen</Button>
    </Header>
    <Text>
      Eine Datenbank, die mit einer App verknüpft ist, kann
      nicht gelöscht werden. Die App nutzt immer die
      verknüpfte Datenbank.
    </Text>
  </Section>
  <Section>
    <Heading>Cronjobs</Heading>
    <Text>
      Ein Cronjob ist immer fest einer App zugeordnet, du
      kannst ihn unter dem Menüpunkt Cronjobs bearbeiten und
      löschen.
    </Text>
  </Section>
</>
```

## Sub-Headings

Sections beginnen in der Regel mit einer
H2-[Heading](https://flow.mittwald.de/components/content/heading). Ist eine feinere Unterteilung nötig,
platzierst du Headings auf niedrigerem Level (H3) direkt in der Section. Sie
erhalten automatisch einen größeren Abstand zum darüberliegenden Content, statt
durch einen Separator getrennt zu werden.

```tsx
import {
  Heading,
  InlineCode,
  Label,
  LabeledValue,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<Section>
  <Heading>DNS Verwaltung</Heading>
  <Text>
    Da du externe Nameserver nutzt, empfehlen wir dir
    folgende Records bei deinem Provider einzutragen.
  </Text>
  <Heading level={3}>A-Record</Heading>
  <LabeledValue>
    <Label>IPv4-Adresse</Label>
    <InlineCode>12.123.123.12</InlineCode>
  </LabeledValue>
</Section>
```

---

# Actions

In der rechten oberen Ecke bietet die Section einen Bereich für
[Actions](https://flow.mittwald.de/components/actions/action). Dort kannst du einen
[Link](https://flow.mittwald.de/components/navigation/link), einen
[Switch](https://flow.mittwald.de/components/form-controls/switch),
[Buttons](https://flow.mittwald.de/components/actions/button) oder eine Kombination dieser Components
platzieren. Mehrere zusammengehörige Actions kannst du über eine
[ActionGroup](https://flow.mittwald.de/components/actions/action-group) gruppieren.

```tsx
import {
  Header,
  Heading,
  Link,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<Section>
  <Header>
    <Heading>Newsletter</Heading>
    <Link href="#">Zur Anmeldung</Link>
  </Header>
  <Text>
    Kommende Releases, neue Features und Tipps rund um dein
    Hosting – wir bringen dir das Wichtigste in dein
    Postfach. Abonniere unseren Newsletter und bleib auf dem
    Laufenden.
  </Text>
</Section>
```

```tsx
import {
  Header,
  Heading,
  Label,
  Section,
  Switch,
  Text,
} from "@mittwald/flow-react-components";

<Section>
  <Header>
    <Heading>Autoresponder</Heading>
    <Switch>
      <Label>Aktivieren</Label>
    </Switch>
  </Header>
  <Text>
    Lasse den Autoresponder für dich arbeiten. Er kann
    automatisch auf eingehende E-Mails antworten.
  </Text>
</Section>
```

Es lassen sich mehrere Buttons nebeneinander anzeigen. Werden jedoch mehr als
zwei bis drei Actions nötig, behält die Hauptaktion ihren eigenen Button und
alle weiteren wandern in ein [ContextMenu](https://flow.mittwald.de/components/actions/context-menu).

```tsx
import {
  Button,
  ColumnLayout,
  Content,
  ContextMenu,
  ContextMenuTrigger,
  CopyButton,
  Header,
  Heading,
  IconContextMenu,
  IconExternalLink,
  Label,
  LabeledValue,
  Link,
  MenuItem,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<Section>
  <Header>
    <Heading>Mein Projekt</Heading>

    <ContextMenuTrigger>
      <Button
        variant="soft"
        color="secondary"
        aria-label="Weitere Aktionen anzeigen"
      >
        <IconContextMenu />
      </Button>
      <ContextMenu aria-label="Weitere Aktionen">
        <MenuItem>Datenbank migrieren</MenuItem>
        <MenuItem>Volume migrieren</MenuItem>
      </ContextMenu>
    </ContextMenuTrigger>

    <Button color="danger">Deaktivieren</Button>
  </Header>

  <ColumnLayout>
    <LabeledValue>
      <Label>Projektname</Label>
      <Content>Dolce Vita</Content>
    </LabeledValue>
    <LabeledValue>
      <Label>Short-ID</Label>
      <Content>p-lol3qe</Content>
      <CopyButton text="p-lol3qe" />
    </LabeledValue>
    <LabeledValue>
      <Label>Projektdomain</Label>
      <Link>
        <Text>p-lol3qe.project.space</Text>
        <IconExternalLink />
      </Link>
      <CopyButton text="p-lol3qe.project.space" />
    </LabeledValue>
  </ColumnLayout>
</Section>
```

---

# Kombiniere mit ...

## AlertBadge und Badge

Ergänze die [Heading](https://flow.mittwald.de/components/content/heading) mit einem
[AlertBadge](https://flow.mittwald.de/components/status/alert-badge) oder einem
[Badge](https://flow.mittwald.de/components/status/badge), um den User schnell über den Status oder
Metadaten des Inhalts einer Section zu informieren.

```tsx
import {
  AlertBadge,
  Badge,
  Button,
  ColumnLayout,
  Content,
  CopyButton,
  Header,
  Heading,
  IconExternalLink,
  Label,
  LabeledValue,
  Link,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<Section>
  <Header>
    <Heading>
      Mein Projekt
      <Badge>Produktion</Badge>
      <AlertBadge status="danger">Deaktiviert</AlertBadge>
    </Heading>

    <Button variant="soft" color="secondary">
      Datenbank migrieren
    </Button>
    <Button>Aktivieren</Button>
  </Header>

  <ColumnLayout>
    <LabeledValue>
      <Label>Projektname</Label>
      <Content>Dolce Vita</Content>
    </LabeledValue>
    <LabeledValue>
      <Label>Short-ID</Label>
      <Content>p-lol3qe</Content>
      <CopyButton text="p-lol3qe" />
    </LabeledValue>
    <LabeledValue>
      <Label>Projektdomain</Label>
      <Link>
        <Text>p-lol3qe.project.space</Text>
        <IconExternalLink />
      </Link>
      <CopyButton text="p-lol3qe.project.space" />
    </LabeledValue>
  </ColumnLayout>
</Section>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--section--section-to-section-spacing` | `2rem` |
| `--section--spacing` | `1rem` |
| `--section--sub-heading-spacing-m` | `1.5rem` |
| `--section--sub-heading-spacing-s` | `0.5rem` |
| `--section-header--action-to-action-spacing` | `0.5rem` |
| `--section-header--heading-to-action-spacing` | `1rem` |

---

# Separator

Ein Separator ist eine Linie, die inhaltliche Abschnitte voneinander abgrenzt.

> **mStudio-Extensions:** Importiere `Separator` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`.

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

<Separator />
```

---

# Best Practices

- Verlasse dich auf die automatische Trennung durch die
  [Section](https://flow.mittwald.de/components/structure/section). Zwischen Sections mit einer
  H2-[Heading](https://flow.mittwald.de/components/content/heading) setzt sie den Separator meist
  selbst.
- Richte die Breite des Separators an der Breite des Content-Bereichs aus.
- Setze den Separator sparsam ein. Bei zu häufiger Verwendung geht die
  strukturierende Wirkung verloren.

---

# Orientierung

Über das Property `orientation` lässt sich der Separator auch vertikal
ausrichten, um nebeneinanderliegende Inhalte voneinander abzugrenzen.

```tsx
import {
  Flex,
  Separator,
  Text,
} from "@mittwald/flow-react-components";

<Flex direction="row" gap="l">
  <Text>Links</Text>
  <Separator orientation="vertical" />
  <Text>Rechts</Text>
</Flex>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | `'react-aria-Separator'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. |
| `dir` | `string` | - | - |
| `elementType` | `string` | - | The HTML element type that will be used to render the separator. |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `lang` | `string` | - | - |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `translate` | `"yes" \| "no"` | - | - |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--separator--height` | `1px` |
| `--separator--border-style` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--separator--color` | `#B7C9DB` | `#8FA1B4` |

---

# Table

Die Table zeigt Daten in Zeilen und Spalten und macht Einträge vergleichbar.

> **mStudio-Extensions:** Importiere `Table` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import {
  InlineCode,
  Table,
  TableBody,
  TableCell,
  TableColumn,
  TableHeader,
  TableRow,
} from "@mittwald/flow-react-components";

<Table aria-label="Button Props">
  <TableHeader>
    <TableColumn>Name</TableColumn>
    <TableColumn>Type</TableColumn>
    <TableColumn>Default</TableColumn>
    <TableColumn>Description</TableColumn>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>
        <InlineCode>color</InlineCode>
      </TableCell>
      <TableCell>
        primary | success | secondary | danger
      </TableCell>
      <TableCell>primary</TableCell>
      <TableCell>The color of the button</TableCell>
    </TableRow>
    <TableRow>
      <TableCell>
        <InlineCode>variant</InlineCode>
      </TableCell>
      <TableCell>plain | solid | soft</TableCell>
      <TableCell>solid</TableCell>
      <TableCell>The variant of the button</TableCell>
    </TableRow>
    <TableRow>
      <TableCell>
        <InlineCode>size</InlineCode>
      </TableCell>
      <TableCell>m | s</TableCell>
      <TableCell>m</TableCell>
      <TableCell>The size of the button</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

---

# Best Practices

- Halte die Zahl der Spalten so gering wie möglich. Das erleichtert das Scannen.
- Formuliere die Spaltenüberschriften kurz, eindeutig und prägnant.
- Stelle pro Zelle nur eine Information dar.
- Zeige Zahlen wie Geldbeträge oder Zeitwerte rechtsbündig an. Das fördert die
  Vergleichbarkeit.

---

# Mit Footer

Um die letzte Zeile der Table hervorzuheben (z. B. für eine Preisübersicht),
kann `TableFooterRow` verwendet werden.

```tsx
import {
  Table,
  TableBody,
  TableCell,
  TableColumn,
  TableFooterRow,
  TableHeader,
  TableRow,
} from "@mittwald/flow-react-components";

<Table aria-label="Bestellübersicht">
  <TableHeader>
    <TableColumn>Artikel</TableColumn>
    <TableColumn horizontalAlign="end">Preis</TableColumn>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Webhosting (2 vCPU / 4 GB RAM)</TableCell>
      <TableCell horizontalAlign="end">32,00 €</TableCell>
    </TableRow>
    <TableRow>
      <TableCell>20 GB Speicherplatz</TableCell>
      <TableCell horizontalAlign="end">Inklusive</TableCell>
    </TableRow>
    <TableRow>
      <TableCell>20 GB Zusatzspeicherplatz</TableCell>
      <TableCell horizontalAlign="end">2,00 €</TableCell>
    </TableRow>
    <TableFooterRow>
      <TableCell>Gesamtpreis</TableCell>
      <TableCell horizontalAlign="end">34,00 €</TableCell>
    </TableFooterRow>
  </TableBody>
</Table>
```

---

# Ausrichtung

## Vertikal zentriert

Der Inhalt wird vertikal zentriert dargestellt, sodass er mittig zwischen oberem
und unterem Zellenrand positioniert ist.

```tsx
import {
  InlineCode,
  Table,
  TableBody,
  TableCell,
  TableColumn,
  TableHeader,
  TableRow,
} from "@mittwald/flow-react-components";

<Table aria-label="Button Props" verticalAlign="middle">
  <TableHeader>
    <TableColumn>Name</TableColumn>
    <TableColumn>Type</TableColumn>
    <TableColumn>Default</TableColumn>
    <TableColumn>Description</TableColumn>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>
        <InlineCode>size</InlineCode>
      </TableCell>
      <TableCell>m | s</TableCell>
      <TableCell>m</TableCell>
      <TableCell>
        Lorem ipsum dolor sit amet consectetur adipisicing
        elit. Cumque eius quam quas vel voluptas, ullam
        aliquid fugit.
      </TableCell>
    </TableRow>
  </TableBody>
</Table>
```

## Horizontal zentriert

Der Inhalt wird horizontal zentriert ausgerichtet. Unabhängig von der
Ausrichtung unterstützt die Table optional die Statusanzeigen `success` und
`danger`.

```tsx
import {
  IconCheck,
  IconClose,
  Table,
  TableBody,
  TableCell,
  TableColumn,
  TableHeader,
  TableRow,
} from "@mittwald/flow-react-components";

<Table aria-label="Scopes">
  <TableHeader>
    <TableColumn>Bereich</TableColumn>
    <TableColumn horizontalAlign="center">
      Lesen
    </TableColumn>
    <TableColumn horizontalAlign="center">
      Schreiben
    </TableColumn>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Projekt</TableCell>
      <TableCell horizontalAlign="center">
        <IconCheck color="success" aria-label="Zugriff" />
      </TableCell>
      <TableCell horizontalAlign="center">
        <IconClose
          color="danger"
          aria-label="Kein Zugriff"
        />
      </TableCell>
    </TableRow>
  </TableBody>
</Table>
```

---

# Feste Spaltenbreiten

Setze `layout="fixed"` an der `Table` und weise einzelnen `TableColumn` über
`width` eine feste Breite zu. Spalten ohne Breite teilen sich den restlichen
Platz. Mit `minWidth` an der `Table` bleibt bei wenig Platz die Breite erhalten
und die Tabelle scrollt horizontal, statt die Spalten zu stauchen.

```tsx
import {
  InlineCode,
  Table,
  TableBody,
  TableCell,
  TableColumn,
  TableHeader,
  TableRow,
} from "@mittwald/flow-react-components";

<Table
  layout="fixed"
  minWidth={640}
  aria-label="Button Props"
>
  <TableHeader>
    <TableColumn width={160}>Name</TableColumn>
    <TableColumn width="25%">Type</TableColumn>
    <TableColumn>Default</TableColumn>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>
        <InlineCode>color</InlineCode>
      </TableCell>
      <TableCell>
        primary | success | secondary | danger
      </TableCell>
      <TableCell>primary</TableCell>
    </TableRow>
    <TableRow>
      <TableCell>
        <InlineCode>variant</InlineCode>
      </TableCell>
      <TableCell>plain | solid | soft</TableCell>
      <TableCell>solid</TableCell>
    </TableRow>
    <TableRow>
      <TableCell>
        <InlineCode>size</InlineCode>
      </TableCell>
      <TableCell>m | s</TableCell>
      <TableCell>m</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | The elements that make up the table. Includes the TableHeader, TableBody, Columns, and Rows. |
| `className` | `string` | - | The elements class name. |
| `defaultExpandedKeys` | `Iterable<Key>` | - | The initial expanded keys in the collection (uncontrolled). |
| `defaultSelectedKeys` | `"all" \| Iterable<Key>` | - | The initial selected keys in the collection (uncontrolled). |
| `dir` | `string` | - | - |
| `disabledBehavior` | `"all" \| "selection"` | `'all'` | Whether `disabledKeys` applies to all interactions, or only selection. |
| `disabledKeys` | `Iterable<Key>` | - | A list of row keys to disable. |
| `disallowEmptySelection` | `boolean` | - | Whether the collection allows empty selection. |
| `dragAndDropHooks` | `DragAndDropHooks` | - | The drag and drop hooks returned by `useDragAndDrop` used to enable drag and drop behavior for the Table. |
| `escapeKeyBehavior` | `"none" \| "clearSelection"` | `'clearSelection'` | Whether pressing the escape key should clear selection in the table or not. Most experiences should not modify this option as it eliminates a keyboard user's ability to easily clear selection. Only use if the escape key is being handled externally or should not trigger selection clearing contextually. |
| `expandedKeys` | `Iterable<Key>` | - | The currently expanded keys in the collection (controlled). |
| `hidden` | `boolean` | - | - |
| `inert` | `boolean` | - | - |
| `keyboardNavigationBehavior` | `"tab" \| "arrow"` | `'arrow'` | Whether keyboard navigation to focusable elements within the cells is via the left/right arrow keys or the tab key. |
| `lang` | `string` | - | - |
| `layout` | `"auto" \| "fixed"` | `"auto"` | The column-sizing algorithm of the table. Use "fixed" together with column widths to enforce exact widths. |
| `minWidth` | `string \| number` | - | The minimum width of the table. Below this width the table scrolls horizontally instead of shrinking its columns. |
| `selectedKeys` | `"all" \| Iterable<Key>` | - | The currently selected keys in the collection (controlled). |
| `selectionBehavior` | `"toggle" \| "replace"` | `'toggle'` | How multiple selection should behave in the collection. |
| `selectionMode` | `"multiple" \| "none" \| "single"` | - | The type of selection that is allowed in the collection. |
| `shouldSelectOnPressUp` | `boolean` | - | Whether selection should occur on press up instead of press down. |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `sortDescriptor` | `SortDescriptor` | - | The current sorted column and direction. |
| `translate` | `"yes" \| "no"` | - | - |
| `treeColumn` | `Key` | - | The id of the column that displays hierarchical data. |
| `verticalAlign` | `"top" \| "middle"` | - | The vertical alignment of the table cells content. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onExpandedChange` | `((keys: Set<Key>) => any)` | - | Handler that is called when items are expanded or collapsed. |
| `onRowAction` | `((key: Key) => void)` | - | Handler that is called when a user performs an action on the row. |
| `onSelectionChange` | `((keys: Selection) => void)` | - | Handler that is called when the selection changes. |
| `onSortChange` | `((descriptor: SortDescriptor) => any)` | - | Handler that is called when the sorted column or direction changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--table--corner-radius` | `8px` |
| `--table--border-width` | `1px` |
| `--table--border-style` | `solid` |
| `--table--padding-x` | `16px` |
| `--table--padding-y` | `8px` |
| `--table--header-font-weight` | `bold` |
| `--table--header-border-width` | `2px` |
| `--table--footer-font-weight` | `bold` |
| `--table--footer-border-width` | `2px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--table--border-color` | `#5E6C7A` | `#DCE9F7` |
| `--table--background-color` | `#FFFFFF` | `#1B1F24` |
| `--table--background-color-accent` | `#F4F8FC` | `#292F37` |

---

# Tabs

Tabs strukturieren verwandte Inhalte in schnell erreichbaren Ansichten.

> **mStudio-Extensions:** Importiere `Tabs` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `render`, `style`, `wrapWith`.

```tsx
import {
  Tab,
  Tabs,
  TabTitle,
} from "@mittwald/flow-react-components";

<Tabs>
  <Tab>
    <TabTitle>Mit App verbinden</TabTitle>
    App Content
  </Tab>
  <Tab>
    <TabTitle>Mit Container verbinden</TabTitle>
    Container Content
  </Tab>
</Tabs>
```

---

# Best Practices

- Gruppiere in einem Tab thematisch verwandten Content.
- Ordne die Tabs nach Wichtigkeit oder Häufigkeit der Nutzung.
- Mach jeden Tab eigenständig verständlich und beschrifte ihn kurz und deutlich.
- Setze Tabs nicht zur Navigation ein. Sie schalten Inhalte innerhalb derselben
  Seite um, ohne zu einer anderen Seite oder URL zu navigieren.

## Tabs vs. TabNavigation

Flow bietet mit Tabs und der
[TabNavigation](https://flow.mittwald.de/components/navigation/tab-navigation) zwei ähnlich aussehende
Components, die sich in der Verwendung klar unterscheiden.

**Verwende Tabs, um ...**

Inhalte innerhalb derselben Seite umzuschalten, ohne zu navigieren.

**Verwende eine TabNavigation, um ...**

zwischen gleichrangigen Unterseiten zu navigieren.

---

# Eingeklappte Ansicht

Wenn die verfügbare Breite nicht ausreicht, wechseln die Tabs automatisch in
eine eingeklappte Ansicht.

```tsx
import {
  Heading,
  LayoutCard,
  Section,
  Tab,
  Tabs,
  TabTitle,
} from "@mittwald/flow-react-components";

<LayoutCard style={{ maxWidth: "320px" }}>
  <Section>
    <Heading>SSH-Benutzer</Heading>
    <Tabs>
      <Tab>
        <TabTitle>Mit App verbinden</TabTitle>
        App Content
      </Tab>
      <Tab>
        <TabTitle>Mit Container verbinden</TabTitle>
        Container Content
      </Tab>
    </Tabs>
  </Section>
</LayoutCard>
```

---

# Mit Status-Icon

Enthält der Inhalt eines Tabs eine wichtige Information oder Warnung (z. B. in
Form eines [Alerts](https://flow.mittwald.de/components/status/alert)), muss der entsprechende Tab ein
Status-Icon erhalten, um die Aufmerksamkeit darauf zu lenken.

```tsx
import {
  AlertIcon,
  Tab,
  Tabs,
  TabTitle,
} from "@mittwald/flow-react-components";

<Tabs>
  <Tab>
    <TabTitle>Mit App verbinden</TabTitle>
    App Content
  </Tab>
  <Tab>
    <TabTitle>
      Mit Container verbinden
      <AlertIcon status="warning" />
    </TabTitle>
    Container Content
  </Tab>
</Tabs>
```

---

# Mit vorausgewähltem Tab

Standardmäßig ist der erste Tab vorausgewählt. Soll ein anderer Tab initial
aktiv sein, legst du das über `defaultSelectedKey` fest.

```tsx
import {
  Tab,
  Tabs,
  TabTitle,
} from "@mittwald/flow-react-components";

<Tabs defaultSelectedKey="container">
  <Tab>
    <TabTitle>Mit App verbinden</TabTitle>
    App Content
  </Tab>
  <Tab id="container">
    <TabTitle>Mit Container verbinden</TabTitle>
    Container Content
  </Tab>
</Tabs>
```

---

# Beschriftung

Tabs haben keinen `Label`-Slot – die Tab-Leiste beschriftet sich über ihre
Tab-Titel. Benennt die Überschrift der umgebenden `Section` die Gruppe bereits,
reicht das. Wenn nicht, gib der Tab-Leiste über `aria-label` einen eigenen Namen
– oder verweise mit `aria-labelledby` auf eine vorhandene Überschrift, damit der
Name nur an einer Stelle gepflegt wird.

```tsx
import {
  Tab,
  Tabs,
  TabTitle,
} from "@mittwald/flow-react-components";

<Tabs aria-label="Verbindungsart">
  <Tab>
    <TabTitle>Mit App verbinden</TabTitle>
    App Content
  </Tab>
  <Tab>
    <TabTitle>Mit Container verbinden</TabTitle>
    Container Content
  </Tab>
</Tabs>
```

---

# Reihenfolge der Tabs

Werden innerhalb eines Tabs Inhalte nachgeladen, kann sich durch das Rerendering
die Reihenfolge der Tabs ändern. Um das zu verhindern, lagere den Tab-Inhalt in
eine eigene Component aus und umschließe sie mit einem `Suspense`.

```tsx
<Tabs>
  <Tab>
    <TabTitle>Tab 1</TabTitle>
    <Suspense>
      <Tab1Content />
    </Suspense>
  </Tab>
  <Tab>
    <TabTitle>Tab 2</TabTitle>
    <Suspense>
      <Tab2Content />
    </Suspense>
  </Tab>
</Tabs>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `ClassNameOrFunction<TabsRenderProps>` | `'react-aria-Tabs'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `defaultSelectedKey` | `Key` | - | The initial selected keys in the collection (uncontrolled). |
| `dir` | `string` | - | - |
| `disabledKeys` | `Iterable<Key>` | - | The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. |
| `hidden` | `boolean` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `inert` | `boolean` | - | - |
| `isDisabled` | `boolean` | - | Whether the TabList is disabled. Shows that a selection exists, but is not available in that circumstance. |
| `keyboardActivation` | `"manual" \| "automatic"` | `'automatic'` | Whether tabs are activated automatically on focus or manually. |
| `lang` | `string` | - | - |
| `orientation` | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the tabs. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `selectedKey` | `Key` | - | The currently selected key in the collection (controlled). |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `tabNotFoundView` | `ReactNode` | - | The view rendered when the selected tab does not exist. Defaults to a built-in IllustratedMessage. |
| `translate` | `"yes" \| "no"` | - | - |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onSelectionChange` | `((key: Key) => void)` | - | Handler that is called when the selection changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-label` | `string` | - | An accessible name for the tab list. `Tabs` has no `Label` slot, so this is how the group is named when the surrounding heading does not already do it. |
| `aria-labelledby` | `string` | - | The id of an element that names the tab list. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--tabs--padding-y` | `8px` |
| `--tabs--padding-x` | `16px` |
| `--tabs--corner-radius` | `calc(8px * 2 + calc(1rem * 1.5))` |
| `--tabs--border-width` | `1px` |
| `--tabs--border-style` | `solid` |
| `--tabs--font-weight--selected` | `bold` |
| `--tabs--spacing` | `0.5rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--tabs--border-color` | `#5E6C7A` | `#DCE9F7` |
| `--tabs--background-color--default` | `#DCE9F7` | `#5E6C7A` |
| `--tabs--background-color--hover` | `#B7C9DB` | `#8FA1B4` |
| `--tabs--background-color--pressed` | `#8FA1B4` | `#B7C9DB` |
| `--tabs--background-color--selected` | `#FFFFFF` | `#1B1F24` |
| `--tabs--color--default` | `#1B1F24` | `#FFFFFF` |
| `--tabs--color--disabled` | `#B7C9DB` | `#8FA1B4` |

---

# Wrap

Wrap legt ein Element nur dann um seinen Content, wenn eine Bedingung erfüllt ist. Andernfalls wird nur der Content gerendert.

> **mStudio-Extensions:** Importiere `Wrap` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

```tsx
import {
  Link,
  Section,
  Switch,
  Text,
  Wrap,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [isLinked, setIsLinked] = useState(true);

  return (
    <Section>
      <Switch isSelected={isLinked} onChange={setIsLinked}>
        Projekt verlinken
      </Switch>
      <Wrap if={isLinked}>
        <Link href="#">
          <Text>Webshop Relaunch</Text>
        </Link>
      </Wrap>
    </Section>
  );
}
```

---

# Best Practices

- Setze das optionale Element direkt in Wrap und deinen Content in dieses
  Element. Ist die Bedingung nicht erfüllt, entfällt nur das Element. Der
  Content bleibt sichtbar und steht trotzdem nur einmal im Code.

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` _(required)_ | `ReactNode` | - | The element that wraps the content, with the content as its children. |
| `if` _(required)_ | `unknown` | - | Whether the child element is rendered. Any truthy value keeps it, a falsy one renders only its children. |

---

# FileCard

Die FileCard visualisiert Dateien samt relevanter Informationen.

> **mStudio-Extensions:** Importiere `FileCard` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

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

<FileCard
  type="image/jpg"
  name="image.jpg"
  sizeInBytes={47500}
/>
```

---

# Best Practices

- Zeige hochgeladene Dateien sofort an. Das gibt dem User eine direkte
  Rückmeldung.
- Mach relevante Informationen wie Dateiname, Dateigröße und Dateityp klar
  erkennbar.
- Biete wichtige Interaktionen als Aktionen an. Ein Beispiel ist das Entfernen
  der Datei.
- Stelle mehrere Dateien mit der
  [FileCardList](https://flow.mittwald.de/components/upload/file-card-list) dar. Häufig ergänzt die
  FileCard eine [FileDropZone](https://flow.mittwald.de/components/upload/file-drop-zone) oder ein
  [FileField](https://flow.mittwald.de/components/form-controls/file-field).

---

# Mit Delete Button

Verwende `delete`, um in der FileCard einen [Button](https://flow.mittwald.de/components/actions/button)
anzuzeigen, mit dem die Datei unmittelbar entfernt werden kann.

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

<FileCard
  type="image/jpg"
  name="image.jpg"
  sizeInBytes={47500}
  onDelete={() => {
    console.log("delete");
  }}
/>
```

---

# Mit Link

Die FileCard ermöglicht es, Dateien über einen `href`-Link zu öffnen, z. B. um
ein Bild in einem neuen Tab anzuzeigen.

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

<FileCard
  type="image/jpg"
  name="image.jpg"
  sizeInBytes={47500}
  href="#"
/>
```

---

# Mit Bild

Statt eines passenden Icons kann durch `imageSrc` zur Vorschau ein Bild
angezeigt werden.

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

<FileCard
  type="image/jpg"
  name="image.jpg"
  sizeInBytes={47500}
  imageSrc="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
/>
```

---

# Mit Failed State

Über das Property `isFailed` kann die FileCard im Failed State angezeigt werden,
um beispielsweise einen fehlgeschlagenen Upload anzuzeigen. Weitere
Informationen können im Subtitle der FileCard angezeigt werden.

```tsx
import {
  FileCard,
  Text,
} from "@mittwald/flow-react-components";

<FileCard name="image.jpg" isFailed>
  <Text>Datei konnte nicht hochgeladen werden</Text>
</FileCard>
```

---

# Kombiniere mit ...

## Button

Platziere einen oder mehrere [Button](https://flow.mittwald.de/components/actions/button) innerhalb der
FileCard, um zusätzliche Optionen anzubieten.

```tsx
import {
  FileCard,
  Button,
  IconChevronDown,
  IconChevronUp,
} from "@mittwald/flow-react-components";

<FileCard
  type="image/jpg"
  name="image.jpg"
  onDelete={() => {
    console.log("delete");
  }}
>
  <Button>
    <IconChevronUp />
  </Button>
  <Button>
    <IconChevronDown />
  </Button>
</FileCard>
```

## ContextMenu

Nutze ein `<ContextMenu />` innerhalb der FileCard, um wichtige Interaktionen in
einem [ContextMenu](https://flow.mittwald.de/components/actions/context-menu) zu platzieren.

```tsx
import {
  ContextMenu,
  FileCard,
  MenuItem,
} from "@mittwald/flow-react-components";

<FileCard
  type="image/jpg"
  name="image.jpg"
  sizeInBytes={47500}
>
  <ContextMenu>
    <MenuItem>Entfernen</MenuItem>
  </ContextMenu>
</FileCard>
```

## ProgressBar

Nutze eine [ProgressBar](https://flow.mittwald.de/components/status/progress-bar) innerhalb der
FileCard, um beispielsweise einen Upload-Fortschritt anzuzeigen.

```tsx
import {
  FileCard,
  Label,
  ProgressBar,
} from "@mittwald/flow-react-components";

<FileCard>
  <ProgressBar
    value={2.1}
    maxValue={3.4}
    minValue={0}
    showMaxValue
    formatOptions={{ style: "unit", unit: "megabyte" }}
  >
    <Label>Image.png</Label>
  </ProgressBar>
</FileCard>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | - | The elements class name. |
| `download` | `string \| boolean` | - | Causes the browser to download the linked URL. A string may be provided to suggest a file name. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download). |
| `elementType` | `"div" \| ExoticComponent<{}> \| "li"` | - | The HTML element or React component rendered as the elements root. |
| `href` | `string` | - | A URL to link to. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href). |
| `imageSrc` | `string` | - | The source of an image file. |
| `isFailed` | `boolean` | - | Whether the file card is in a failed state. |
| `name` | `string` | - | The name of the file. |
| `sizeInBytes` | `number` | - | The size of the file in bytes. |
| `target` | `HTMLAttributeAnchorTarget` | - | The target window for the link. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target). |
| `type` | `string` | - | The type of the file. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onDelete` | `(() => void)` | - | Handler that is called when the file cards delete button is clicked. |
| `onPress` | `((e: PressEvent) => void)` | - | Handler that is called when the press is released over the target. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--file-card--padding-x` | `8px` |
| `--file-card--padding-y` | `4px` |
| `--file-card--spacing` | `0.5rem` |
| `--file-card--corner-radius` | `8px` |
| `--file-card--border-width` | `1px` |
| `--file-card--border-style` | `solid` |
| `--file-card--sub-title-font-size` | `0.875rem` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--file-card--border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--file-card--border-color--error` | `#E1244C` | `#F2A2B3` |
| `--file-card--background-color--default` | `#FFFFFF` | `#1B1F24` |
| `--file-card--background-color--hover` | `#E5EFF8` | `#3A434E` |
| `--file-card--background-color--pressed` | `#DCE9F7` | `#5E6C7A` |
| `--file-card--background-color--error` | `#FDF0F3` | `#540B1B` |

---

# FileCardList

Die FileCardList platziert mehrere FileCards in einem ColumnLayout.

> **mStudio-Extensions:** Importiere `FileCardList` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  FileCard,
  FileCardList,
} from "@mittwald/flow-react-components";

<FileCardList aria-label="Hochgeladene Dateien">
  <FileCard
    name="file1.txt"
    onDelete={() => {
      console.log("delete");
    }}
  />
  <FileCard
    name="file2.txt"
    onDelete={() => {
      console.log("delete");
    }}
  />
  <FileCard
    name="file3.txt"
    onDelete={() => {
      console.log("delete");
    }}
  />
  <FileCard
    name="file4.txt"
    onDelete={() => {
      console.log("delete");
    }}
  />
  <FileCard
    type="image/jpg"
    name="image.jpg"
    onDelete={() => {
      console.log("delete");
    }}
  />
</FileCardList>
```

---

# Best Practices

- Zeige hochgeladene Dateien sofort an. Das gibt dem User eine direkte
  Rückmeldung.
- Gib der Liste ein aussagekräftiges `aria-label`.

---

# Kombiniere mit ...

## FileDropZone

Stelle mit der FileCardList die Dateien dar, die über eine
[FileDropZone](https://flow.mittwald.de/components/upload/file-drop-zone) hochgeladen wurden.

```tsx
import {
  Button,
  FileCard,
  FileCardList,
  FileDropZone,
  FileField,
  Heading,
  IconUpload,
  Section,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [files, setFiles] = useState<File[]>([]);

  return (
    <Section>
      <FileDropZone
        multiple
        onChange={(value) => {
          if (value) {
            setFiles([...files, ...value]);
          }
        }}
      >
        <IconUpload />
        <Heading>Dateien ablegen</Heading>
        <FileField>
          <Button>Dateien auswählen</Button>
        </FileField>
      </FileDropZone>

      <FileCardList>
        {files.map((file) => (
          <FileCard
            name={file.name}
            type={file.type}
            key={file.name}
            sizeInBytes={file.size}
            onDelete={() =>
              setFiles(
                files.filter((watched) => watched !== file),
              )
            }
          />
        ))}
      </FileCardList>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `columnGap` | `"s" \| "m" \| "l" \| "xl"` | - | Size of the column gap between the content blocks inside the column layout. |
| `gap` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | Size of the row and column gap between the content blocks inside the column layout. |
| `l` | `(number \| null)[]` | - | Column layout for container size l. |
| `m` | `(number \| null)[]` | - | Column layout for container size m. |
| `rowGap` | `"s" \| "m" \| "l" \| "xl"` | - | Size of the row gap between the content blocks inside the column layout. |
| `s` | `(number \| null)[]` | - | Column layout for container size s. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |

---

# FileDropZone

Die FileDropZone ermöglicht das Hochladen von Dateien per Drag-and-Drop oder durch manuelle Auswahl.

> **mStudio-Extensions:** Importiere `FileDropZone` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert. Diese Props kommen remote nicht an: `wrapWith`.

```tsx
import {
  Button,
  FileDropZone,
  FileField,
  Heading,
  IconUpload,
  Section,
} from "@mittwald/flow-react-components";

<Section>
  <FileDropZone onChange={(files) => console.log(files)}>
    <IconUpload />
    <Heading>Datei ablegen</Heading>
    <FileField>
      <Button>Datei auswählen</Button>
    </FileField>
  </FileDropZone>
</Section>
```

---

# Best Practices

- Biete immer eine alternative Upload-Möglichkeit über einen
  [Button](https://flow.mittwald.de/components/actions/button).
- Kommuniziere zulässige Dateitypen und mögliche Größenbeschränkungen deutlich.
- Formuliere [Fehlermeldungen](https://flow.mittwald.de/foundations/content-guidelines/fehlermeldungen)
  klar und hilfreich.

---

# Vorgegebene Dateitypen

Verwende `<Text />`, um den User über erlaubte Dateitypen und maximale
Dateigrößen beim Hochladen zu informieren.

```tsx
import {
  Button,
  FileDropZone,
  FileField,
  Heading,
  IconImage,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<Section>
  <FileDropZone
    accept="image/png"
    onChange={(files) => console.log(files)}
  >
    <IconImage />
    <Heading>Bild ablegen</Heading>
    <Text>
      Es sind nur Bilder vom Typ image/png erlaubt.
    </Text>
    <FileField>
      <Button>Bild auswählen</Button>
    </FileField>
  </FileDropZone>
</Section>
```

---

# Mehrere Dateien

Über die Property `multiple` wird das gleichzeitige Hochladen mehrerer Dateien
ermöglicht. Beim erneuten Hochladen werden bestehende Dateien ersetzt. Ein
Beispiel für das Hochladen und Verwalten mehrerer Dateien findest du im
Codesnippet [Multi Upload](https://flow.mittwald.de/templates/bausteine/multi-upload).

```tsx
import {
  Button,
  FileDropZone,
  FileField,
  Heading,
  IconUpload,
  Section,
} from "@mittwald/flow-react-components";

<Section>
  <FileDropZone
    multiple
    onChange={(files) => console.log(files)}
  >
    <IconUpload />
    <Heading>Dateien ablegen</Heading>
    <FileField>
      <Button>Dateien auswählen</Button>
    </FileField>
  </FileDropZone>
</Section>
```

---

# Kombiniere mit ...

## FileCardList

Stelle die hochgeladenen Dateien übersichtlich mit einer
[FileCardList](https://flow.mittwald.de/components/upload/file-card-list) dar – für eine einzelne Datei
genügt eine [FileCard](https://flow.mittwald.de/components/upload/file-card).

```tsx
import {
  Button,
  FileCard,
  FileCardList,
  FileDropZone,
  FileField,
  Heading,
  IconUpload,
  Section,
} from "@mittwald/flow-react-components";
import { useState } from "react";

export default () => {
  const [files, setFiles] = useState<File[]>([]);

  return (
    <Section>
      <FileDropZone
        multiple
        onChange={(value) => {
          if (value) {
            setFiles([...files, ...value]);
          }
        }}
      >
        <IconUpload />
        <Heading>Dateien ablegen</Heading>
        <FileField>
          <Button>Dateien auswählen</Button>
        </FileField>
      </FileDropZone>

      <FileCardList>
        {files.map((file) => (
          <FileCard
            name={file.name}
            type={file.type}
            key={file.name}
            sizeInBytes={file.size}
            onDelete={() =>
              setFiles(
                files.filter((watched) => watched !== file),
              )
            }
          />
        ))}
      </FileCardList>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `isDisabled` | `boolean` | - | Whether the drop target is disabled. If true, the drop target will not accept any drops. |
| `isReadOnly` | `boolean` | - | Whether the component is read only. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. `null` takes a wrapper a surrounding props context set back off, the way `tunnel: null` does for a tunnel. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onChange` | `FileInputOnChangeHandler` | - | Called with the dropped or selected files whenever the selection changes. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--file-drop-zone--corner-radius` | `8px` |
| `--file-drop-zone--padding` | `16px` |
| `--file-drop-zone--border-width` | `1px` |
| `--file-drop-zone--border-style--default` | `dashed` |
| `--file-drop-zone--border-style--target` | `solid` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--file-drop-zone--content-color--disabled` | `#B7C9DB` | `#8FA1B4` |
| `--file-drop-zone--background-color--default` | `#F4F8FC` | `#292F37` |
| `--file-drop-zone--background-color--target` | `#E5EFF8` | `#3A434E` |
| `--file-drop-zone--background-color--disabled` | `#F4F8FC` | `#292F37` |
| `--file-drop-zone--border-color--default` | `#5E6C7A` | `#DCE9F7` |
| `--file-drop-zone--border-color--target` | `#0054F5` | `#85AFFF` |
| `--file-drop-zone--border-color--disabled` | `#DCE9F7` | `#5E6C7A` |

---

# ImageCropper

Der ImageCropper schneidet ein Bild auf ein bestimmtes Format zu.

> **mStudio-Extensions:** Importiere `ImageCropper` aus `@mittwald/flow-remote-react-components`. Die Beispiele auf dieser Seite importieren aus `@mittwald/flow-react-components`, das in einer Extension nicht rendert.

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

<ImageCropper image="/assets/mittwald_logo_rgb.jpg" />
```

---

# Best Practices

- Wähle das Seitenverhältnis über `aspect` passend zum späteren
  Verwendungszweck.
- Biete dem User eine Möglichkeit zum Zurücksetzen. So kehrt er zum
  Ausgangszustand des Bildes zurück.

---

# Seitenverhältnis

Über das Property `aspect` kann das Seitenverhältnis angegeben werden.

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

<ImageCropper
  image="/assets/mittwald_logo_rgb.jpg"
  aspectRatio={16 / 9}
/>
```

---

# Runder Ausschnitt

Über das Property `cropShape` kann zwischen einer rechteckigen und runden
Ansicht des Ausschnitts gewechselt werden.

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

<ImageCropper
  image="/assets/mittwald_logo_rgb.jpg"
  cropShape="round"
  aspectRatio={1}
/>
```

---

# Sizes

Über die `width` und `height` Properties kann die Größe des Croppers angepasst
werden.

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

<ImageCropper
  image="/assets/mittwald_logo_rgb.jpg"
  height={200}
  width={200}
/>
```

---

# Fehlerzustand

Kann das Bild nicht geladen oder nicht gelesen werden — eine abgelaufene URL,
ein 404 oder ein Bild von einer fremden Domain ohne CORS-Header —, zeigt der
ImageCropper eine Fehlermeldung anstelle des Ausschnitts. Über `onError` erfährt
die Anwendung davon, zum Beispiel um den Upload zurückzusetzen.

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

<ImageCropper
  image="/assets/dieses-bild-existiert-nicht.jpg"
  onError={(error) => console.error(error)}
/>
```

Über `errorView` kann die Fehlermeldung ersetzt werden, etwa um dem User eine
Handlung anzubieten.

```tsx
import {
  IconDanger,
  IllustratedMessage,
  ImageCropper,
  Text,
} from "@mittwald/flow-react-components";

<ImageCropper
  image="/assets/dieses-bild-existiert-nicht.jpg"
  errorView={
    <IllustratedMessage color="danger">
      <IconDanger />
      <Text>
        Dieses Bild ist nicht mehr verfügbar. Bitte lade es
        erneut hoch.
      </Text>
    </IllustratedMessage>
  }
/>
```

---

# Kombiniere mit ...

## FileDropZone

Kombiniere den ImageCropper mit einer
[FileDropZone](https://flow.mittwald.de/components/upload/file-drop-zone), um ein hochgeladenes Bild
direkt zuzuschneiden.

```tsx
import {
  Button,
  Heading,
  FileField,
  ImageCropper,
  IconImage,
  Section,
  FileDropZone,
  Text,
  Flex,
  IconClose,
  Action,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/components/actions/action/examples/lib";

export default () => {
  const form = useForm<{
    files: FileList | File[] | [];
  }>({ defaultValues: { files: [] } });
  const Field = typedField(form);

  const watchedFiles = [...form.watch("files")];

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        {watchedFiles.length === 0 && (
          <FileDropZone
            accept="image/png"
            onChange={(f) => {
              if (f) {
                form.setValue("files", f);
              }
            }}
          >
            <IconImage />
            <Heading>Bild ablegen</Heading>
            <Text>
              Bitte wähle ein Bild vom Typ PNG aus.
            </Text>
            <Field
              name="files"
              rules={{
                required: "Bitte wähle ein Bild aus",
              }}
            >
              <FileField>
                <Button variant="outline" color="dark">
                  Bild auswählen
                </Button>
              </FileField>
            </Field>
          </FileDropZone>
        )}

        {watchedFiles.length > 0 && (
          <Flex justify="center" align="start" gap="m">
            <ImageCropper
              width={200}
              height={200}
              image={watchedFiles[0]}
            />
            <Action
              onAction={() => form.setValue("files", [])}
            >
              <Button
                variant="plain"
                color="secondary"
                aria-label="Bild entfernen"
              >
                <IconClose />
              </Button>
            </Action>
          </Flex>
        )}
        <SubmitButton>Hochladen</SubmitButton>
      </Form>
    </Section>
  );
}
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aspectRatio` | `number` | - | The aspect ratio of the crop shape. |
| `className` | `string` | - | The elements class name. |
| `cropShape` | `"rect" \| "round"` | - | - |
| `errorView` | `ReactNode` | - | View that is shown instead of the cropper when the image cannot be cropped. Defaults to a localized error message. |
| `height` | `Height<string \| number>` | `300` | The height of the component. |
| `image` | `string \| File` | - | The image file to crop. |
| `width` | `Width<string \| number>` | `300` | The width of the component. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onCropComplete` | `((croppedImage: File) => void)` | - | Callback on crop complete. |
| `onError` | `((error: ImageCropperError) => void)` | - | Callback when the image cannot be cropped, because it failed to load or could not be read. |

---

# Design Tokens

## Größen & Stile

| Token | Wert |
| --- | --- |
| `--image-cropper--spacing` | `16px` |
| `--image-cropper--border-style` | `solid` |
| `--image-cropper--border-width` | `1px` |
| `--image-cropper--corner-radius` | `8px` |
| `--image-cropper--grid-width` | `0.5px` |

## Farben

| Token | Light | Dark |
| --- | --- | --- |
| `--image-cropper--border-color` | `#5E6C7A` | `#DCE9F7` |
| `--image-cropper--grid-color` | `rgb(255 255 255 / 50%)` | `rgb(255 255 255 / 50%)` |
| `--image-cropper--mask-border-color` | `rgb(255 255 255 / 100%)` | `rgb(255 255 255 / 100%)` |
| `--image-cropper--mask-color` | `rgb(0 0 0 / 75%)` | `rgb(0 0 0 / 75%)` |