# Web Bileşenleri

`@astroway/ui`, sıradan custom element'lerden oluşan bir settir: etiketi sayfaya koyarsınız ve kendini çizer. Kartları [`@astroway/render`](https://www.npmjs.com/package/@astroway/render) çizer; `/v1/render/*` arkasındaki kodun aynısıdır, bu yüzden sayfanızdaki çember, API'nin döndürdüğü çemberle birebir aynıdır.

Paket **alfa** aşamasındadır (`0.1.0-alpha.1`): 1.0'a kadar attribute adları değişebilir. Paket sayfası: [npm](https://www.npmjs.com/package/@astroway/ui), kod: [GitHub](https://github.com/astroway/astroway-ui).

## Kurulum

CDN'den, derleme olmadan:

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

Ya da npm ile, tüm elementleri ya da yalnızca gerekenleri import ederek. Paket henüz alfa aşamasında olduğundan şu etiketi isteyin:

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

```js
```

## Elemente veri vermenin üç yolu

**A. Kendi veriniz.** Kendi sunucunuzda kendi anahtarınızla istek yapar ve elemente JSON'u iletirsiniz. Ziyaretçinin tarayıcısından istek gitmez, bu yüzden herhangi bir sınıftan anahtar uygundur.

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

Sunucu tarafı bir şablon aynı JSON'u bir attribute'a yazabilir:

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

**B. Anahtarsız.** `/v1/public/*` üzerindeki elementlerin anahtara ihtiyacı yoktur. Ziyaretçinin genel bütçesini paylaşırlar; tek bir IP'den saatte 30 birim. Bütçe tükendiğinde element ne kadar beklemek gerektiğini yazar.

```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. Tarayıcı için anahtar.** Anahtar gerektiren endpoint'lerdeki elementler, siteniz için oluşturulmuş bir `pk_` anahtarı alır: oluştururken domain listesi, kredi limiti ve endpoint kapsamı zorunludur. [Kimlik doğrulama](/authentication/) sayfasındaki "Tarayıcı için anahtarlar" bölümüne bakın. Gizli `aw_` anahtarı, istek yapılmadan önce reddedilir.

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

Bu elementler için anahtar kapsamında `chart` gerekir; `aw-chinese-sign` kullanıyorsanız ayrıca `chinese/zodiac/animal` da gerekir. Domain'ler host'a göre eşleştirilir: `example.com` için bir anahtar `http://example.com:8080` üzerinde de çalışır.

## React ve Next.js

React 19, custom element'leri doğrudan render eder. Normal HTML'den iki fark vardır:

- React `key`'i kendine alır, bu yüzden anahtarı `api-key` olarak iletin.
- Sunucu tarafı render edilen bir sayfada, A yöntemi için verileri string olarak iletin. React, sunucu render'ı sırasında nesneleri atar ve hidrasyon sırasında bunları ayarlamaz.

```tsx
'use client';

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

Modüller sunucuda import edilebilir: etiket normal HTML olarak gider ve tarayıcı elementi yükler yüklenmez çizilir.

## Elementler

| Element | Yöntemler | Kaynak |
|---|---|---|
| `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` |

Sayfada tek bir kartı olan elementler (aynı doğum verileriyle çember, tablo ve ızgara) hepsi için tek bir istek yapar.

`aw-aspect-grid`, kendi boyutunda yaklaşık 560 px genişliğindedir. Daha dar bir sütunda küçülür ve orb etiketleri ufalır; `scroll` attribute'u, yatay kaydırmayla tam boyutu korur.

## Dil, tema, hatalar

- `lang`, [21 dilin](/languages/) herhangi birini kabul eder; varsayılan olarak sayfanın `<html lang>` değeri alınır. Adlar, API'deki `localized` tablolarından gelir.
- `theme="dark"` çizimi değiştirir; renkleri `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border` CSS değişkenleri belirler.
- Her element, `{ kind, message }` içeren bir `aw-error` olayı gönderir; burada `kind`, `error`, `rate-limited` ya da `key` olabilir.