# Web-Komponenten

`@astroway/ui` ist eine Sammlung gewöhnlicher Custom Elements: Du setzt ein Tag auf die Seite, und es zeichnet sich selbst. Die Karten zeichnet [`@astroway/render`](https://www.npmjs.com/package/@astroway/render), derselbe Code, der hinter `/v1/render/*` steckt, also stimmt das Rad auf deiner Seite mit dem überein, das die API zurückgibt.

Das Paket ist in der **Alpha**-Version (`0.1.0-alpha.1`): Attributnamen können sich bis Version 1.0 noch ändern. Paketseite: [npm](https://www.npmjs.com/package/@astroway/ui), Code: [GitHub](https://github.com/astroway/astroway-ui).

## Installation

Mit CDN, ohne Build:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@astroway/ui/dist/cdn/index.js"></script>
<aw-moon-phase></aw-moon-phase>
```

Oder mit npm, indem du alle Elemente oder nur die benötigsten importierst. Das Paket ist noch in Alpha, also verwende dieses Tag:

```bash
npm install @astroway/ui@alpha
```

```js
```

## Drei Wege, um Daten an ein Element zu übergeben

**A. Deine Daten.** Du machst eine Anfrage auf deinem Server mit deinem Schlüssel und übergibst dem Element JSON. Vom Browser des Besuchers geht keine Anfrage aus, also eignet sich jeder beliebige Schlüssel.

```js
document.querySelector('aw-natal-wheel').data = chart; // data з відповіді /v1/chart
```

Ein Server-Template kann denselben JSON in das Attribut schreiben:

```php
<aw-natal-wheel data='<?= htmlspecialchars(json_encode($chart), ENT_QUOTES) ?>'></aw-natal-wheel>
```

**B. Ohne Schlüssel.** Elemente auf `/v1/public/*` benötigen keinen Schlüssel. Sie teilen sich das öffentliche Budget des Besuchers, 30 Einheiten pro Stunde von einer IP; wenn es erschöpft ist, schreibt das Element, wie lange warten.

```html
<aw-moon-phase lang="uk"></aw-moon-phase>
<aw-horoscope sign="leo" period="daily"></aw-horoscope>
<aw-tarot-spread spread="three-card"></aw-tarot-spread>
```

**C. Schlüssel für den Browser.** Elemente auf Endpunkten mit Schlüssel verwenden den Schlüssel `pk_`, der für deine Website erstellt wurde: Liste der Domains, Kreditlimit und Endpunkt-Bereich sind beim Erstellen obligatorisch. Siehe Abschnitt "Browser-Schlüssel" auf der Seite [Authentifizierung](/authentication/). Der geheime Schlüssel `aw_` wird vor der Anfrage abgelehnt.

```html
<aw-natal-wheel api-key="pk_live_..." date="1990-05-15" time="14:30"
  latitude="50.45" longitude="30.52" timezone-offset="3"></aw-natal-wheel>
```

Für diese Elemente im Schlüsselbereich wird ein `chart` benötigt, und zusätzlich `chinese/zodiac/animal`, wenn du `aw-chinese-sign` verwendest. Domains werden mit dem Host abgeglichen: Der Schlüssel für `example.com` funktioniert auch auf `http://example.com:8080`.

## React und Next.js

React 19 rendert Custom Elements direkt. Zwei Dinge unterscheiden sie von normalem HTML:

- React nimmt `key` für sich selbst, also gibst du den Schlüssel als `api-key` weiter.
- Auf einer Seite mit Server-Rendering übergibst du die Daten für Methode A als String. React verwirft Objekte während des Server-Renderings und setzt sie nicht während der Hydration.

```tsx
'use client';

  return <aw-natal-wheel data={JSON.stringify(chart)} />;
}
```

Module können auf dem Server importiert werden: Das Tag kommt als normales HTML und wird gezeichnet, sobald der Browser das Element lädt.

## Elemente

| Element | Methoden | Quelle |
|---|---|---|
| `aw-natal-wheel` | A/C | `/v1/chart` |
| `aw-aspect-grid` | A/C | `/v1/chart` |
| `aw-planet-table` | A/C | `/v1/chart` |
| `aw-moon-phase` | A/B | `/v1/public/moon-phase` |
| `aw-planet-of-day` | A/B | `/v1/public/planet-of-day` |
| `aw-horoscope` | A/B | `/v1/public/horoscope/{daily,weekly,monthly}` |
| `aw-tarot-card`, `aw-tarot-spread` | A/B | `/v1/public/tarot/*` |
| `aw-sign-matrix` | A/B | `/v1/public/compatibility/matrix` |
| `aw-synastry-score` | A/B | `/v1/public/synastry` |
| `aw-chinese-sign` | A/C | `/v1/chinese/zodiac/animal` + `/v1/public/chinese/zodiac/texts` |

Elemente mit einer Karte pro Seite (Rad, Tabelle und Raster mit denselben Geburtsdaten) machen eine Anfrage für alle.

`aw-aspect-grid` in seiner eigenen Größe ist etwa 560 px breit. In einer schmaleren Spalte verkleinert es sich, und die Orbitbeschriftungen werden klein; das Attribut `scroll` lässt die volle Größe mit horizontaler Scrollbar.

## Sprache, Thema, Fehler

- `lang` akzeptiert eine der [21 Sprachen](/languages/), standardmäßig wird `<html lang>` der Seite verwendet. Die Namen kommen aus den `localized`-Tabellen in der API.
- `theme="dark"` schaltet das Rendering um; Farben werden durch CSS-Variablen `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border` festgelegt.
- Jedes Element sendet ein `aw-error`-Ereignis mit `{ kind, message }`, wobei `kind` `error`, `rate-limited` oder `key` ist.