# Web Components

`@astroway/ui` to zestaw zwykłych custom elements: umieszczasz tag na stronie, a on rysuje się sam. Karty rysuje [`@astroway/render`](https://www.npmjs.com/package/@astroway/render), ten sam kod, który stoi za `/v1/render/*`, więc koło na twojej stronie pokrywa się z kołem, które zwraca API.

Pakiet jest w **alfie** (`0.1.0-alpha.1`): nazwy atrybutów mogą się jeszcze zmienić przed 1.0. Strona pakietu: [npm](https://www.npmjs.com/package/@astroway/ui), kod: [GitHub](https://github.com/astroway/astroway-ui).

## Instalacja

Z CDN, bez budowania:

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

Albo z npm, importując wszystkie elementy lub tylko potrzebne. Pakiet jest jeszcze w alfie, więc żądaj tego tagu:

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

```js
```

## Trzy sposoby przekazania elementowi danych

**A. Twoje dane.** Wykonujesz zapytanie na swoim serwerze swoim kluczem i przekazujesz elementowi JSON. Z przeglądarki odwiedzającego zapytanie nie wychodzi, więc nadaje się klucz dowolnej klasy.

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

Szablon serwerowy może zapisać ten sam JSON w atrybucie:

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

**B. Bez klucza.** Elementy na `/v1/public/*` nie potrzebują klucza. Dzielą publiczny budżet odwiedzającego, 30 jednostek na godzinę z jednego IP; gdy się wyczerpie, element pisze, ile czekać.

```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. Klucz dla przeglądarki.** Elementy na endpointach z kluczem przyjmują klucz `pk_`, utworzony dla twojej strony: lista domen, limit kredytów i zakres endpointów są obowiązkowe przy tworzeniu. Zobacz sekcję "Klucze dla przeglądarki" na stronie [uwierzytelniania](/authentication/). Tajny klucz `aw_` jest odrzucany jeszcze przed zapytaniem.

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

Dla tych elementów w zakresie klucza potrzebny jest `chart`, a także `chinese/zodiac/animal`, jeśli umieszczasz `aw-chinese-sign`. Domeny są porównywane po hoście: klucz dla `example.com` działa też na `http://example.com:8080`.

## React i Next.js

React 19 renderuje custom elements bezpośrednio. Od zwykłego HTML różnią się dwie rzeczy:

- React zabiera `key` dla siebie, więc klucz przekazuj jako `api-key`.
- Na stronie z renderowaniem serwerowym dane dla sposobu A przekazuj jako ciąg znaków. React odrzuca obiekty podczas renderowania serwerowego i nie ustawia ich podczas hydratacji.

```tsx
'use client';

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

Moduły można importować na serwerze: tag przechodzi jako zwykły HTML i rysuje się, gdy tylko przeglądarka załaduje element.

## Elementy

| Element | Sposoby | Źródło |
|---|---|---|
| `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` |

Elementy z jedną kartą na stronie (koło, tabela i siatka z tymi samymi danymi urodzeniowymi) wykonują jedno zapytanie na wszystkie.

`aw-aspect-grid` we własnym rozmiarze ma około 560 px szerokości. W węższej kolumnie się zmniejsza, a podpisy orbów stają się drobne; atrybut `scroll` zachowuje pełny rozmiar z poziomym przewijaniem.

## Język, motyw, błędy

- `lang` przyjmuje dowolny z [21 języków](/languages/), domyślnie pobierany jest `<html lang>` strony. Nazwy pochodzą z tabel `localized` w API.
- `theme="dark"` przełącza rysunek; kolory ustawiają zmienne CSS `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border`.
- Każdy element wysyła zdarzenie `aw-error` z `{ kind, message }`, gdzie `kind` to `error`, `rate-limited` lub `key`.