# वेब-कॉम्पोनेन्ट्स

`@astroway/ui` साधारण custom elements का एक सेट है: पेज पर टैग लगाओ, और वह खुद को render कर लेता है। चार्ट [`@astroway/render`](https://www.npmjs.com/package/@astroway/render) बनाता है, वही कोड जो `/v1/render/*` के पीछे चलता है, इसलिए तुम्हारे पेज का wheel वही होता है जो API लौटाता है।

पैकेज **अल्फा** में है (`0.1.0-alpha.1`): 1.0 से पहले attribute के नाम बदल सकते हैं। पैकेज पेज: [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 से, सभी elements या सिर्फ ज़रूरी elements इम्पोर्ट करके। पैकेज अभी अल्फा में है, इसलिए यही टैग माँगो:

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

```js
```

## Element को डेटा देने के तीन तरीके

**A. तुम्हारा डेटा।** अपने सर्वर से अपनी key से request करो और element को JSON दो। विज़िटर के ब्राउज़र से कोई request नहीं जाती, इसलिए किसी भी class की key चलेगी।

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

सर्वर टेम्पलेट वही JSON attribute में भी लिख सकता है:

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

**B. बिना key।** `/v1/public/*` वाले elements को key की ज़रूरत नहीं। वे विज़िटर के सार्वजनिक बजट को साझा करते हैं, एक IP से प्रति घंटा 30 यूनिट; बजट खत्म होने पर element बता देता है कि कितना इंतज़ार करना है।

```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. ब्राउज़र के लिए key।** key वाले endpoints पर चलने वाले elements `pk_` key लेते हैं, जो तुम्हारी साइट के लिए बनाई जाती है: बनाते समय domains की सूची, credits की limit और endpoints का scope अनिवार्य हैं। [प्रमाणीकरण](/authentication/) पेज पर "ब्राउज़र के लिए keys" सेक्शन देखो। गुप्त key `aw_` request से पहले ही reject कर दी जाती है।

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

इन elements के लिए key के scope में `chart` चाहिए, और अगर `aw-chinese-sign` लगाते हो तो `chinese/zodiac/animal` भी। Domains host से मिलाए जाते हैं: `example.com` के लिए बनी key `http://example.com:8080` पर भी काम करती है।

## React और Next.js

React 19 custom elements को सीधे render करता है। साधारण HTML से सिर्फ दो बातें अलग हैं:

- React `key` अपने लिए रख लेता है, इसलिए key को `api-key` के रूप में दो।
- सर्वर-रेंडर वाले पेज पर तरीके A का डेटा string के रूप में दो। React सर्वर रेंडर के दौरान objects को छोड़ देता है और hydration के समय उन्हें सेट नहीं करता।

```tsx
'use client';

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

मॉड्यूल सर्वर पर भी इम्पोर्ट किए जा सकते हैं: टैग साधारण HTML की तरह जाता है और ब्राउज़र के element लोड करते ही render हो जाता है।

## Elements

| Element | तरीके | स्रोत |
|---|---|---|
| `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` |

एक ही चार्ट वाले elements (एक ही जन्म-डेटा वाला wheel, table और grid) सबके लिए मिलकर एक ही request करते हैं।

`aw-aspect-grid` अपने असली आकार में लगभग 560 px चौड़ा होता है। संकरी कॉलम में वह सिकुड़ जाता है और orb के लेबल छोटे हो जाते हैं; `scroll` attribute पूरा आकार बनाए रखता है और horizontal scrolling देता है।

## भाषा, थीम, errors

- `lang` [21 भाषाओं](/languages/) में से कोई भी स्वीकार करता है, डिफ़ॉल्ट रूप से पेज का `<html lang>` लिया जाता है। नाम API की `localized` tables से आते हैं।
- `theme="dark"` drawing बदल देता है; रंग CSS variables `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border` से सेट होते हैं।
- हर element `{ kind, message }` के साथ `aw-error` event भेजता है, जहाँ `kind` `error`, `rate-limited` या `key` होता है।