# Elemente

Text, Button, Schalter, Eingabefeld, Diagramm und Tabelle in Nachrichten: Felder, Werte und Größen.

Diese sechs Elemente hängst du an eine [Nachricht](https://packlets.app/docs/nachrichten-elemente.md), im Feld `elements` von [`POST /v1/push`](https://packlets.app/docs/api-push.md). Bis zu 12 pro Nachricht.

## Übersicht

| `type` | Element | Wofür | Wert | Bedienbar |
|---|---|---|---|---|
| `text` | [Text](#text) | Überschrift, Absatz oder Hinweis | der Text | nein |
| `button` | [Button](#button) | eine Aktion auslösen | – | ja, bei jedem Tipp |
| `toggle` | [Schalter](#schalter) | etwas an- oder ausschalten | `true` oder `false` | ja, bei jedem Umschalten |
| `input` | [Eingabefeld](#eingabefeld) | Text an dein Tool schicken | der Text | ja, beim Abschicken |
| `chart` | [Diagramm](#diagramm) | Zahlen als Balken oder Linie | die Punkte | nein |
| `table` | [Tabelle](#tabelle) | Daten in Zeilen und Spalten | die Zeilen | nein |

**Wert** ist das, was dein Tool beim Senden mitgibt. Bei Schalter und Eingabefeld ändert er sich, wenn du sie in der App bedienst; Samy speichert ihn. Dein Tool kann Werte in einer gesendeten Nachricht nicht mehr ändern. **Bedienbar** heißt: Jede Bedienung geht als [Ereignis `ui`](https://packlets.app/docs/ereignisse.md#element-bedient-ui) mit der `message_id` an deinen Webhook.

## Gemeinsame Felder

| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
| `type` | einer der sechs Typen | ja | Art des Elements. |
| `id` | 1 bis 40 Zeichen: Buchstaben, Ziffern, `_`, `-` | ja | Deine Kennung, pro Nachricht eindeutig. Kommt im Webhook als `element_id` zurück. |
| `width` | ganze Zahl 1 bis 6 | nein | Breite in Spalten. Standard 6, die ganze Breite. |
| `height` | Zahl in Punkten | nein | Mindesthöhe. Nicht bei `text`. |

Wie Breite und Höhe zusammenspielen, steht unter [Layout](https://packlets.app/docs/layout.md).

## Text

| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
| `text` | Text, 1 bis 2.000 Zeichen | ja | Der Inhalt. |
| `style` | `title`, `body` oder `caption` | nein | Überschrift, Absatz (Standard) oder kleiner grauer Hinweis. |

- **Wert:** der Text.
- **Größe:** mindestens 2 Spalten breit. Die Höhe richtet sich nach dem Inhalt, `height` gibt es nicht.
- Bei `body` gilt dieselbe [Formatierung](https://packlets.app/docs/senden.md#formatierung) wie im Text der Nachricht.

```json
{ "type": "text", "id": "stand", "text": "Zuletzt geprüft um 9:41", "style": "caption" }
```

## Button

| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
| `label` | Text, 1 bis 40 Zeichen | ja | Beschriftung. |
| `style` | `primary` oder `secondary` | nein | Dunkel (Standard) oder hell. |

- **Wert:** keiner. Ein Tipp schickt das Ereignis `ui` mit `value: null`.
- **Größe:** mindestens 2 Spalten breit, Höhe 44 bis 240.
- Ein Button lässt sich beliebig oft tippen. Das unterscheidet ihn vom [Knopf](https://packlets.app/docs/knoepfe.md) im Feld `buttons`.

```json
{ "type": "button", "id": "restart", "label": "Neu starten", "width": 3 }
```

## Schalter

| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
| `label` | Text, 1 bis 60 Zeichen | ja | Beschriftung. |
| `description` | Text, bis 160 Zeichen | nein | Erklärung unter der Beschriftung. |
| `value` | `true` oder `false` | nein | Startwert. Standard `false`. |

- **Wert:** `true` oder `false`. Jedes Umschalten schickt das Ereignis `ui` mit dem neuen Wert.
- **Größe:** mindestens 3 Spalten breit, Höhe 64 bis 240.

```json
{ "type": "toggle", "id": "wartung", "label": "Wartungsseite zeigen", "value": true }
```

## Eingabefeld

| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
| `label` | Text, 1 bis 60 Zeichen | ja | Beschriftung. |
| `placeholder` | Text, bis 80 Zeichen | nein | Grauer Beispieltext im leeren Feld. |
| `button` | Text, 1 bis 30 Zeichen | nein | Beschriftung des Absende-Knopfs. Standard „Senden“. |
| `value` | Text, bis 500 Zeichen | nein | Startwert. Standard leer. |

- **Wert:** der Text, bis 500 Zeichen. Das Ereignis `ui` kommt erst beim Abschicken, nicht bei jedem Buchstaben.
- **Größe:** mindestens 3 Spalten breit, Höhe 160 bis 400.

```json
{ "type": "input", "id": "antwort", "label": "Antwort an Lena", "placeholder": "z. B. Geht heute raus", "button": "Antworten" }
```

## Diagramm

| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
| `label` | Text, 1 bis 60 Zeichen | ja | Titel der Karte. |
| `chart` | `bar` oder `line` | nein | Balken (Standard) oder Linie. |
| `unit` | Text, bis 8 Zeichen | nein | Einheit hinter dem Wert oben rechts. |
| `points` | Liste, bis 31 Punkte | nein | Je Punkt `{"label": "Mo", "value": 3.5}`. `label` bis 12 Zeichen, `value` eine Zahl. Standard leer. |
| `highlight` | ganze Zahl ab 0 | nein | Welcher Punkt hervorgehoben ist, gezählt ab 0. Standard: der letzte. |

- **Wert:** die Punkte.
- **Größe:** mindestens 3 Spalten breit, Höhe 120 bis 480.
- Bei vielen Punkten zeigt die App nur jede zweite oder dritte Beschriftung.

```json
{
  "type": "chart", "id": "umsatz", "label": "Umsatz", "unit": "€",
  "points": [{ "label": "Mo", "value": 860 }, { "label": "Di", "value": 1204 }]
}
```

## Tabelle

| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
| `columns` | Liste, 1 bis 6 Texte | ja | Spaltenköpfe, je bis 30 Zeichen. |
| `rows` | Liste, bis 50 Zeilen | nein | Jede Zeile ist eine Liste von Zellen: Text (bis 80 Zeichen) oder Zahl. Höchstens so viele Zellen wie Spalten. Standard leer. |
| `label` | Text, bis 60 Zeichen | nein | Titel der Karte. |

- **Wert:** die Zeilen.
- **Größe:** mindestens 3 Spalten breit, Höhe 80 bis 800.
- Eine leere Tabelle zeigt „Noch keine Einträge“. Breite Tabellen lassen sich seitlich schieben.

```json
{
  "type": "table", "id": "bestellungen", "label": "Bestellungen",
  "columns": ["Nr.", "Kunde", "€"],
  "rows": [["1047", "Jonas M.", 89.9], ["1048", "Aylin S.", 34.5]]
}
```

## Unbekannte Typen

Einen `type`, den es nicht gibt, lehnt Samy mit `400 invalid_body` ab. Typen für TypeScript zum Kopieren stehen unter [Fertiger Code](https://packlets.app/docs/beispiele.md#typen-fuer-typescript).