# Komponen Web

`@astroway/ui` adalah sekumpulan custom elements biasa: kamu menaruh tag di halaman, dan ia menggambar dirinya sendiri. Kartu digambar oleh [`@astroway/render`](https://www.npmjs.com/package/@astroway/render), kode yang sama yang berada di balik `/v1/render/*`, jadi roda di halamanmu cocok dengan roda yang dikembalikan API.

Paket ini masih dalam **alfa** (`0.1.0-alpha.1`): nama atribut masih bisa berubah sebelum 1.0. Halaman paket: [npm](https://www.npmjs.com/package/@astroway/ui), kode: [GitHub](https://github.com/astroway/astroway-ui).

## Instalasi

Dari CDN, tanpa build:

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

Atau dari npm, mengimpor semua elemen atau hanya yang dibutuhkan. Paket masih dalam alfa, jadi minta tag ini:

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

```js
```

## Tiga cara memberi data ke elemen

**A. Datamu sendiri.** Kamu melakukan request di servermu dengan kuncimu dan meneruskan JSON ke elemen. Tidak ada request dari browser pengunjung, jadi kunci kelas apa pun bisa dipakai.

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

Template server bisa menulis JSON yang sama ke dalam atribut:

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

**B. Tanpa kunci.** Elemen pada `/v1/public/*` tidak memerlukan kunci. Mereka berbagi anggaran publik pengunjung, 30 unit per jam dari satu IP; saat habis, elemen menampilkan berapa lama harus menunggu.

```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. Kunci untuk browser.** Elemen pada endpoint dengan kunci menerima kunci `pk_` yang dibuat untuk situsmu: daftar domain, batas kredit, dan cakupan endpoint wajib diisi saat pembuatan. Lihat bagian "Kunci untuk browser" di halaman [autentikasi](/authentication/). Kunci rahasia `aw_` ditolak bahkan sebelum request.

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

Untuk elemen-elemen ini, cakupan kunci memerlukan `chart`, dan juga `chinese/zodiac/animal` jika kamu memakai `aw-chinese-sign`. Domain dicocokkan berdasarkan host: kunci untuk `example.com` juga berfungsi di `http://example.com:8080`.

## React dan Next.js

React 19 me-render custom elements secara langsung. Dua hal berbeda dari HTML biasa:

- React mengambil `key` untuk dirinya sendiri, jadi teruskan kunci sebagai `api-key`.
- Pada halaman dengan server render, data untuk cara A diteruskan sebagai string. React membuang objek saat server render dan tidak mengeksposnya saat hidrasi.

```tsx
'use client';

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

Modul bisa diimpor di server: tag berjalan sebagai HTML biasa dan digambar begitu browser memuat elemen.

## Elemen

| Elemen | Cara | Sumber |
|---|---|---|
| `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` |

Elemen-elemen dengan satu kartu di halaman (roda, tabel, dan grid dengan data kelahiran yang sama) melakukan satu request untuk semuanya.

`aw-aspect-grid` pada ukuran aslinya memiliki lebar sekitar 560 px. Di kolom yang lebih sempit ia mengecil, dan label orb menjadi kecil; atribut `scroll` mempertahankan ukuran penuh dengan pengguliran horizontal.

## Bahasa, tema, error

- `lang` menerima salah satu dari [21 bahasa](/languages/), secara default diambil dari `<html lang>` halaman. Nama-nama datang dari tabel `localized` di API.
- `theme="dark"` mengganti tampilan gambar; warna diatur oleh variabel CSS `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border`.
- Setiap elemen mengirim event `aw-error` dengan `{ kind, message }`, di mana `kind` adalah `error`, `rate-limited`, atau `key`.