# Composants Web

`@astroway/ui` est un ensemble d'éléments personnalisés classiques : tu places la balise sur la page et il se dessine tout seul. Les cartes sont dessinées par [`@astroway/render`](https://www.npmjs.com/package/@astroway/render), le même code qui se trouve derrière `/v1/render/*`, donc la roue sur ta page correspond à la roue renvoyée par l'API.

Le paquet est en **alpha** (`0.1.0-alpha.1`) : les noms des attributs peuvent encore changer avant la version 1.0. Page du paquet : [npm](https://www.npmjs.com/package/@astroway/ui), code : [GitHub](https://github.com/astroway/astroway-ui).

## Installation

Depuis le CDN, sans compilation :

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

Ou via npm, en important tous les éléments ou seulement ceux dont tu as besoin. Le paquet est encore en alpha, donc demande cette balise :

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

```js
```

## Trois façons de fournir des données à l'élément

**A. Tes données.** Tu fais une requête depuis ton serveur avec ta clé et tu passes du JSON à l'élément. Depuis le navigateur du visiteur aucune requête n'est faite, donc n'importe quelle clé de classe convient.

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

Un template serveur peut écrire le même JSON dans un attribut :

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

**B. Sans clé.** Les éléments sur `/v1/public/*` n'ont pas besoin de clé. Ils partagent le budget public du visiteur, 30 unités par heure depuis une même IP ; quand il est épuisé, l'élément indique combien attendre.

```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. Clé pour le navigateur.** Les éléments sur les endpoints nécessitant une clé utilisent la clé `pk_`, créée pour ton site : la liste des domaines, la limite de crédits et la zone d'endpoints sont obligatoires lors de la création. Voir la section " Clés pour le navigateur " sur la page [authentification](/authentication/). La clé secrète `aw_` est rejetée avant même la requête.

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

Pour ces éléments, dans la zone de clé il faut `chart`, et aussi `chinese/zodiac/animal` si tu utilises `aw-chinese-sign`. Les domaines sont vérifiés par l'hôte : la clé pour `example.com` fonctionne aussi sur `http://example.com:8080`.

## React et Next.js

React 19 rend les custom elements directement. Deux choses diffèrent du HTML ordinaire :

- React prend le `key` pour lui, donc passe la clé comme `api-key`.
- Sur une page avec rendu côté serveur, passe les données pour la méthode A sous forme de chaîne. React rejette les objets pendant le rendu serveur et ne les applique pas lors de l'hydratation.

```tsx
'use client';

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

Les modules peuvent être importés côté serveur : la balise se comporte comme du HTML classique et se dessine dès que le navigateur charge l'élément.

## Éléments

| Élément | Méthodes | Source |
|---|---|---|
| `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` |

Les éléments avec une seule carte sur la page (roue, tableau et grille avec les mêmes données de naissance) effectuent une seule requête pour tous.

`aw-aspect-grid` a une largeur d'environ 560 px en taille native. Dans une colonne plus étroite il se réduit, et les libellés des orbites deviennent petits ; l'attribut `scroll` conserve la taille complète avec un défilement horizontal.

## Langue, thème, erreurs

- `lang` accepte n'importe laquelle des [21 langues](/languages/), par défaut il prend le `<html lang>` de la page. Les noms proviennent des tables `localized` de l'API.
- `theme="dark"` bascule le dessin ; les couleurs sont définies par les variables CSS `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border`.
- Chaque élément envoie l'événement `aw-error` avec `{ kind, message }`, où `kind` vaut `error`, `rate-limited` ou `key`.