# Componenti Web

`@astroway/ui` è un set di normali custom elements: metti il tag nella pagina e si disegna da solo. Le carte sono disegnate da [`@astroway/render`](https://www.npmjs.com/package/@astroway/render), lo stesso codice che sta dietro a `/v1/render/*`, quindi la ruota sulla tua pagina corrisponde alla ruota restituita dall'API.

Il pacchetto è in **alfa** (`0.1.0-alpha.1`): i nomi degli attributi potrebbero ancora cambiare prima della 1.0. Pagina del pacchetto: [npm](https://www.npmjs.com/package/@astroway/ui), codice: [GitHub](https://github.com/astroway/astroway-ui).

## Installazione

Da CDN, senza build:

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

Oppure da npm, importando tutti gli elementi o solo quelli che ti servono. Il pacchetto è ancora in alfa, quindi richiedi questo tag:

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

```js
```

## Tre modi per fornire i dati a un elemento

**A. I tuoi dati.** Fai la richiesta sul tuo server con la tua chiave e passi il JSON all'elemento. Dal browser del visitatore non parte alcuna richiesta, quindi va bene una chiave di qualsiasi classe.

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

Un template lato server può scrivere lo stesso JSON in un attributo:

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

**B. Senza chiave.** Gli elementi su `/v1/public/*` non hanno bisogno di una chiave. Condividono il budget pubblico del visitatore, 30 unità all'ora per IP; quando si esaurisce, l'elemento indica quanto attendere.

```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. Chiave per il browser.** Gli elementi su endpoint con chiave accettano una chiave `pk_` creata per il tuo sito: alla creazione sono obbligatori l'elenco dei domini, il limite di crediti e l'ambito degli endpoint. Vedi la sezione "Chiavi per il browser" nella pagina di [autenticazione](/authentication/). La chiave segreta `aw_` viene rifiutata ancora prima della richiesta.

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

Per questi elementi l'ambito della chiave deve includere `chart`, e anche `chinese/zodiac/animal` se usi `aw-chinese-sign`. I domini vengono confrontati per host: una chiave per `example.com` funziona anche su `http://example.com:8080`.

## React e Next.js

React 19 renderizza i custom elements direttamente. Rispetto al normale HTML cambiano due cose:

- React si prende `key` per sé, quindi passa la chiave come `api-key`.
- In una pagina con rendering lato server, i dati per il metodo A vanno passati come stringa. React scarta gli oggetti durante il rendering lato server e non li espone durante l'idratazione.

```tsx
'use client';

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

I moduli possono essere importati sul server: il tag arriva come normale HTML e si disegna non appena il browser carica l'elemento.

## Elementi

| Elemento | Metodi | Sorgente |
|---|---|---|
| `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` |

Gli elementi con una sola carta nella pagina (ruota, tabella e griglia con gli stessi dati di nascita) fanno una sola richiesta per tutti.

`aw-aspect-grid` nella sua dimensione nativa è largo circa 560 px. In una colonna più stretta si riduce e le etichette degli orbi diventano piccole; l'attributo `scroll` mantiene la dimensione piena con scorrimento orizzontale.

## Lingua, tema, errori

- `lang` accetta una qualsiasi delle [21 lingue](/languages/); per default viene preso il `<html lang>` della pagina. I nomi arrivano dalle tabelle `localized` dell'API.
- `theme="dark"` cambia il disegno; i colori sono definiti dalle variabili CSS `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border`.
- Ogni elemento emette un evento `aw-error` con `{ kind, message }`, dove `kind` è `error`, `rate-limited` oppure `key`.