# Kbd

Kbd ist eine Component zur einheitlichen Darstellung von Tastaturkürzeln. Sie stellt Tastaturkürzel visuell dar und passt sich automatisch an das Betriebssystem des Users an.

## Overview

# Playground

Die Component unterstützt ein Array von `keys`. Die einzelnen keys werden als
Strings übergeben. Wenn dabei die Werte "mod", "alt" oder "shift" verwendet
werden, wird automatisch das passende Tastensymbol angezeigt – abhängig davon,
ob der User macOS oder Windows verwendet. Dadurch werden die jeweiligen
Tastenbezeichnungen plattformspezifisch korrekt dargestellt, ohne dass
zusätzliche Logik implementiert werden muss.

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

<Kbd 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>
```

---

# Varianten

Die Component wird in den Varianten `plain` und `soft` angeboten. Für die
Darstellung von Shortcuts direkt an Bedienelementen sollte die Variante `plain`
verwendet werden, da sie sich dezent in die Oberfläche einfügt und nicht zu
aufdringlich wirkt. Innerhalb von erklärenden Texten oder Beschreibungen sollte
hingegen die Variante `soft` eingesetzt werden, um hervorzuheben, 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"]} />
</>
```

---

# Kombiniere mit …

## SearchField

Wenn eine Suche durch einen Keyboard-Shortcut fokussiert werden kann, kann die
Kbd Component mit dem
[SearchField](/04-components/form-controls/search-field/overview) 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](/04-components/actions/context-menu/overview) 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](/04-components/content/text/overview) 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>
```


## Guidelines

# Grundlagen

## Best practices

Achte bei der Verwendung eines Kbds darauf, dass ...

- nur tatsächlich verfügbare und funktionierende Keyboard-Shortcuts angezeigt
  werden.
- der Kbd in direktem Bezug zu dem Inhalt oder der Aktion platziert wird, die
  durch den Shortcut ausgeführt werden kann.

## Verwendung

Verwende einen Kbd, um Keyboard-Shortcuts visuell klar und konsistent
darzustellen.