# Webcomponenten

`@astroway/ui` is een set gewone custom elements: je zet een tag op de pagina en hij tekent zichzelf. De kaarten worden getekend door [`@astroway/render`](https://www.npmjs.com/package/@astroway/render), dezelfde code die achter `/v1/render/*` zit, dus het wiel op jouw pagina komt overeen met het wiel dat de API teruggeeft.

Het pakket is in **alfa** (`0.1.0-alpha.1`): attribuutnamen kunnen nog veranderen vóór 1.0. Pakketpagina: [npm](https://www.npmjs.com/package/@astroway/ui), code: [GitHub](https://github.com/astroway/astroway-ui).

## Installatie

Vanaf CDN, zonder build:

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

Of via npm, waarbij je alle elementen importeert of alleen de nodige. Het pakket zit nog in alfa, dus vraag deze tag aan:

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

```js
```

## Drie manieren om een element data te geven

**A. Je eigen data.** Je doet het request op je eigen server met je eigen sleutel en geeft de JSON aan het element. Er gaat geen request vanuit de browser van de bezoeker, dus een sleutel van elke klasse werkt.

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

Een server-side template kan dezelfde JSON in een attribuut schrijven:

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

**B. Zonder sleutel.** Elementen op `/v1/public/*` hebben geen sleutel nodig. Ze delen het publieke budget van de bezoeker, 30 eenheden per uur vanaf één IP; als dat op is, laat het element zien hoe lang je moet wachten.

```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. Sleutel voor de browser.** Elementen op endpoints met sleutel gebruiken een `pk_`-sleutel die voor je site is aangemaakt: een lijst met domeinen, een kredietlimiet en een endpoint-scope zijn verplicht bij het aanmaken. Zie de sectie "Sleutels voor de browser" op de pagina [authenticatie](/authentication/). De geheime sleutel `aw_` wordt al vóór het request geweigerd.

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

Voor deze elementen moet de sleutelscope `chart` bevatten, en ook `chinese/zodiac/animal` als je `aw-chinese-sign` gebruikt. Domeinen worden op host vergeleken: een sleutel voor `example.com` werkt ook op `http://example.com:8080`.

## React en Next.js

React 19 rendert custom elements direct. Twee dingen verschillen van gewone HTML:

- React houdt `key` voor zichzelf, dus geef de sleutel door als `api-key`.
- Op een pagina met server-side rendering geef je de data voor manier A door als string. React gooit objecten weg tijdens server-side rendering en zet ze niet terug tijdens hydratatie.

```tsx
'use client';

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

De modules kun je op de server importeren: de tag gaat mee als gewone HTML en tekent zodra de browser het element laadt.

## Elementen

| Element | Manieren | Bron |
|---|---|---|
| `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` |

Elementen met één kaart op de pagina (wiel, tabel en grid met dezelfde geboortedata) doen samen één request.

`aw-aspect-grid` is op eigen formaat ongeveer 560 px breed. In een smallere kolom krimpt hij en worden de orb-labels klein; het attribuut `scroll` behoudt het volledige formaat met horizontale scrollbalk.

## Taal, thema, fouten

- `lang` accepteert elke [21 talen](/languages/); standaard wordt de `<html lang>` van de pagina gebruikt. Namen komen uit de `localized`-tabellen in de API.
- `theme="dark"` schakelt de tekening om; kleuren stel je in met CSS-variabelen `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border`.
- Elk element stuurt een event `aw-error` met `{ kind, message }`, waarbij `kind` gelijk is aan `error`, `rate-limited` of `key`.