# Componente Web

`@astroway/ui` este un set de custom elements obișnuite: pui tag-ul pe pagină și el se desenează singur. Hărțile le desenează [`@astroway/render`](https://www.npmjs.com/package/@astroway/render), același cod care stă în spatele `/v1/render/*`, deci roata de pe pagina ta coincide cu roata pe care o returnează API-ul.

Pachetul este în **alfa** (`0.1.0-alpha.1`): numele atributelor se mai pot schimba până la 1.0. Pagina pachetului: [npm](https://www.npmjs.com/package/@astroway/ui), codul: [GitHub](https://github.com/astroway/astroway-ui).

## Instalare

De pe CDN, fără build:

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

Sau din npm, importând toate elementele sau doar pe cele necesare. Pachetul este încă în alfa, așa că cere acest tag:

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

```js
```

## Trei moduri de a da elementului date

**A. Datele tale.** Faci cererea pe serverul tău cu cheia ta și transmiți elementului JSON-ul. Din browserul vizitatorului nu pleacă nicio cerere, deci merge o cheie de orice clasă.

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

Un șablon de server poate scrie același JSON într-un atribut:

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

**B. Fără cheie.** Elementelor de pe `/v1/public/*` nu le trebuie cheie. Ele împart bugetul public al vizitatorului, 30 de unități pe oră de pe un IP; când se epuizează, elementul scrie cât trebuie așteptat.

```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. Cheie pentru browser.** Elementele de pe endpoint-uri cu cheie iau o cheie `pk_`, creată pentru site-ul tău: lista de domenii, limita de credite și aria endpoint-urilor sunt obligatorii la creare. Vezi secțiunea "Chei pentru browser" de pe pagina de [autentificare](/authentication/). Cheia secretă `aw_` este respinsă înainte de cerere.

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

Pentru aceste elemente, în aria cheii este necesar `chart`, plus `chinese/zodiac/animal` dacă folosești `aw-chinese-sign`. Domeniile se verifică după host: o cheie pentru `example.com` funcționează și pe `http://example.com:8080`.

## React și Next.js

React 19 randează custom elements direct. Față de HTML-ul obișnuit diferă două lucruri:

- React își rezervă `key`, așa că transmite cheia ca `api-key`.
- Pe o pagină cu randare pe server, datele pentru modul A transmite-le ca string. React respinge obiectele în timpul randării pe server și nu le expune la hidratare.

```tsx
'use client';

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

Modulele pot fi importate pe server: tag-ul pleacă ca HTML obișnuit și se desenează imediat ce browserul încarcă elementul.

## Elemente

| Element | Moduri | Sursă |
|---|---|---|
| `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` |

Elementele cu o singură hartă pe pagină (roata, tabelul și grila cu aceleași date de naștere) fac o singură cerere pentru toate.

`aw-aspect-grid` la dimensiunea proprie are aproximativ 560 px lățime. Într-o coloană mai îngustă se micșorează, iar etichetele orburilor devin mici; atributul `scroll` păstrează dimensiunea completă cu derulare orizontală.

## Limbă, temă, erori

- `lang` acceptă oricare dintre cele [21 de limbi](/languages/); implicit se ia `<html lang>` al paginii. Denumirile vin din tabelele `localized` din API.
- `theme="dark"` comută desenul; culorile le definesc variabilele CSS `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border`.
- Fiecare element emite un eveniment `aw-error` cu `{ kind, message }`, unde `kind` este `error`, `rate-limited` sau `key`.