Веб-компоненти

@astroway/ui це набір звичайних custom elements: ставите тег на сторінку, і він малює себе сам. Карти малює @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 рендерить custom elements напряму. Від звичайного HTML відрізняються дві речі:

• React забирає key собі, тому ключ передавайте як api-key.
• На сторінці з серверним рендером дані для способу A передавайте рядком. React відкидає об’єкти під час серверного рендеру і не виставляє їх під час гідрації.

'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 px завширшки. У вужчій колонці він зменшується, і підписи орбів стають дрібними; атрибут 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.