# Webové komponenty

`@astroway/ui` je sada obyčejných custom elements: vložíš tag na stránku a on si sám vykreslí. Karty vykresluje [`@astroway/render`](https://www.npmjs.com/package/@astroway/render), ten samý kód, který stojí za `/v1/render/*`, takže kolo na tvé stránce odpovídá kolu, které vrací API.

Balíček je v **alfa** (`0.1.0-alpha.1`): názvy atributů se ještě mohou změnit až do 1.0. Stránka balíčku: [npm](https://www.npmjs.com/package/@astroway/ui), kód: [GitHub](https://github.com/astroway/astroway-ui).

## Instalace

Z CDN, bez sestavení:

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

Nebo z npm, importuješ všechny elementy nebo jen potřebné. Balíček je zatím v alfa, takže požádej o tento tag:

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

```js
```

## Tři způsoby, jak dát elementu data

**A. Tvá data.** Uděláš požadavek na svém serveru svým klíčem a předáš elementu JSON. Z prohlížeče návštěvníka požadavek neodchází, takže funguje klíč jakékoli třídy.

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

Serverový šablon může zapsat ten samý JSON do atributu:

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

**B. Bez klíče.** Elementům na `/v1/public/*` klíč není potřeba. Sdílejí veřejný rozpočet návštěvníka, 30 jednotek za hodinu z jedné IP; když se vyčerpá, element napíše, jak dlouho čekat.

```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. Klíč pro prohlížeč.** Elementy na endpointách s klíčem berou klíč `pk_`, vytvořený pro tvůj web: seznam domén, limit kreditů a oblast endpointů jsou při vytvoření povinné. Viz sekce "Klíče pro prohlížeč" na stránce [autentizace](/authentication/). Tajný klíč `aw_` je odmítnut ještě před požadavkem.

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

Pro tyto elementy v oblasti klíče je potřeba `chart` a také `chinese/zodiac/animal`, pokud používáš `aw-chinese-sign`. Domény se ověřují podle hostu: klíč pro `example.com` funguje i na `http://example.com:8080`.

## React a Next.js

React 19 renderuje custom elements přímo. O běžném HTML se liší dvě věci:

- React si bere `key` pro sebe, takže klíč předávej jako `api-key`.
- Na stránce se server-side renderingem předávej data pro způsob A jako řetězec. React odmítá objekty během server-side renderu a neaplikuje je během hydratace.

```tsx
'use client';

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

Moduly lze importovat na serveru: tag funguje jako běžný HTML a vykreslí se, jakmile prohlížeč načte element.

## Elementy

| Element | Způsoby | Zdroj |
|---|---|---|
| `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 s jednou kartou na stránce (kolo, tabulka a mřížka se stejnými údaji narození) provádějí jeden požadavek na všechny.

`aw-aspect-grid` v přirozené velikosti má asi 560 px na šířku. V užší sloupci se zmenšuje a popisky orb se stávají drobnými; atribut `scroll` zachovává plnou velikost s horizontálním posouváním.

## Jazyk, téma, chyby

- `lang` přijímá libovolný z [21 jazyků](/languages/), ve výchozím nastavení se bere `<html lang>` stránky. Názvy přicházejí z tabulek `localized` v API.
- `theme="dark"` přepíná obrázek; barvy nastavují CSS‑proměnné `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border`.
- Každý element odesílá událost `aw-error` s `{ kind, message }`, kde `kind` je `error`, `rate-limited` nebo `key`.