# مكوّنات الويب

`@astroway/ui` هو مجموعة من عناصر مخصصة عادية: تضع الوسم في الصفحة، وهو يرسم نفسه. الرسوم تُرسم بواسطة [`@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 يرسم العناصر المخصصة مباشرة. هناك شيئين يختلفان عن HTML العادي:

- React يأخذ `key` لنفسه، لذا مرّر المفتاح كـ `api-key`.
- في الصفحة التي تُ render على الخادم، مرّر البيانات للطريقة A كسلسلة. React يرفض الكائنات أثناء render على الخادم ولا يضعها أثناء hydration.

```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 بكسل عرضًا. في عمود أضيق يتقلص، وتصبح تسميات المدارات صغيرة؛ السمة `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`.