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

@astroway/ui هو مجموعة من عناصر مخصصة عادية: تضع الوسم في الصفحة، وهو يرسم نفسه. الرسوم تُرسم بواسطة @astroway/render، نفس الكود الذي يدعم /v1/render/*، لذا العجلة في صفحتك تتطابق مع العجلة التي تُرجعها API.

الحزمة في ألفا (0.1.0-alpha.1): قد تتغير أسماء السمات حتى الإصدار 1.0. صفحة الحزمة: npm، الكود: GitHub.

التثبيت

من CDN، بدون تجميع:

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

أو من npm، استيراد جميع العناصر أو فقط المطلوبة. الحزمة لا تزال في ألفا، لذا اطلب هذا الوسم:

npm install @astroway/ui@alpha

import '@astroway/ui';               // усі елементи
import '@astroway/ui/natal-wheel';   // або один

ثلاث طرق لإعطاء العنصر بيانات

A. بياناتك. تقوم بإجراء طلب على خادمك باستخدام مفتاحك وتُرسل JSON إلى العنصر. لا يُرسل طلب من متصفح الزائر، لذا أي مفتاح من أي فئة يناسب.

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

قالب الخادم يمكنه كتابة نفس JSON في السمة:

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

B. بدون مفتاح. العناصر على /v1/public/* لا تحتاج إلى مفتاح. يشاركون ميزانية الزائر العامة، 30 وحدة في الساعة من عنوان IP واحد؛ عندما تُستنفد، يكتب العنصر كم يجب الانتظار.

<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_ المُنشأ لموقعك: قائمة النطاقات، حد الائتمانات، ونطاق النقاط النهاية مطلوبان عند الإنشاء. راجع قسم “مفاتيح المتصفح” في صفحة المصادقة. المفتاح السري aw_ يُرفض قبل الطلب.

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

'use client';
import '@astroway/ui/natal-wheel';
import '@astroway/ui/jsx'; // типи для тегів <aw-*> у TypeScript

export default function Chart({ chart }: { chart: unknown }) {
  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 لغة، بشكل افتراضي يُأخذ من <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.