# Веб-компоненти

`@astroway/ui` це набір звичайних custom elements: ставите тег на сторінку, і він малює себе сам. Карти малює [`@astroway/render`](https://www.npmjs.com/package/@astroway/render), той самий код, що стоїть за `/v1/render/*`, тож колесо на вашій сторінці збігається з колесом, яке повертає API.

Пакет в **альфі** (`0.1.0-alpha.1`): назви атрибутів ще можуть змінитися до 1.0. Сторінка пакета: [npm](https://www.npmjs.com/package/@astroway/ui), код: [GitHub](https://github.com/astroway/astroway-ui).

## Встановлення

З CDN, без збирання:

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

Або з npm, імпортуючи всі елементи чи лише потрібні. Пакет поки в альфі, тож просіть цей тег:

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

```js
```

## Три способи дати елементу дані

**A. Ваші дані.** Робите запит на своєму сервері своїм ключем і передаєте елементу JSON. З браузера відвідувача запит не йде, тож підходить ключ будь-якого класу.

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

Серверний шаблон може записати той самий JSON в атрибут:

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

**B. Без ключа.** Елементам на `/v1/public/*` ключ не потрібен. Вони ділять публічний бюджет відвідувача, 30 одиниць на годину з одного IP; коли він вичерпується, елемент пише, скільки чекати.

```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. Ключ для браузера.** Елементи на ендпоінтах з ключем беруть ключ `pk_`, створений для вашого сайту: список доменів, ліміт кредитів і область ендпоінтів при створенні обов'язкові. Див. розділ "Ключі для браузера" на сторінці [автентифікації](/authentication/). Секретний ключ `aw_` відхиляється ще до запиту.

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

Для цих елементів в області ключа потрібен `chart`, і ще `chinese/zodiac/animal`, якщо ставите `aw-chinese-sign`. Домени звіряються за хостом: ключ для `example.com` працює і на `http://example.com:8080`.

## React і Next.js

React 19 рендерить custom elements напряму. Від звичайного HTML відрізняються дві речі:

- React забирає `key` собі, тому ключ передавайте як `api-key`.
- На сторінці з серверним рендером дані для способу A передавайте рядком. React відкидає об'єкти під час серверного рендеру і не виставляє їх під час гідрації.

```tsx
'use client';

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

Модулі можна імпортувати на сервері: тег іде як звичайний HTML і малюється, щойно браузер завантажить елемент.

## Елементи

| Елемент | Способи | Джерело |
|---|---|---|
| `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` |

Елементи з однією картою на сторінці (колесо, таблиця і сітка з тими самими даними народження) роблять один запит на всіх.

`aw-aspect-grid` у власному розмірі має близько 560 px завширшки. У вужчій колонці він зменшується, і підписи орбів стають дрібними; атрибут `scroll` залишає повний розмір із горизонтальною прокруткою.

## Мова, тема, помилки

- `lang` приймає будь-яку з [21 мови](/languages/), за замовчуванням береться `<html lang>` сторінки. Назви приходять з таблиць `localized` в API.
- `theme="dark"` перемикає малюнок; кольори задають CSS-змінні `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border`.
- Кожен елемент надсилає подію `aw-error` з `{ kind, message }`, де `kind` це `error`, `rate-limited` або `key`.