# Text

Die Text-Component sorgt für eine konsistente Formatierung und Strukturierung von Text.

```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/02-foundations/03-content-guidelines/01-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/02-foundations/01-design/02-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/04-components/structure/combine), um neben dem
Text z. B. ein Icon, einen CopyButton oder ein ContextualHelp 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` | `WordBreak` | - | 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. |

### 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. |

