Web-συστατικά

Το @astroway/ui είναι ένα σύνολο απλών custom elements: βάζεις το tag στη σελίδα και αυτό σχεδιάζει τον εαυτό του. Τα charts τα σχεδιάζει το @astroway/render, ο ίδιος κώδικας που βρίσκεται πίσω από το /v1/render/*, οπότε ο τροχός στη σελίδα σου ταιριάζει με τον τροχό που επιστρέφει το API.

Το πακέτο είναι σε alpha (0.1.0-alpha.1): τα ονόματα των attributes μπορεί ακόμη να αλλάξουν μέχρι το 1.0. Σελίδα πακέτου: npm, κώδικας: GitHub.

Εγκατάσταση

Από CDN, χωρίς build:

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

Ή από npm, κάνοντας import όλα τα elements ή μόνο όσα χρειάζεσαι. Το πακέτο είναι ακόμη σε alpha, οπότε ζήτα αυτό το tag:

npm install @astroway/ui@alpha

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

Τρεις τρόποι να δώσεις δεδομένα σε ένα element

A. Τα δικά σου δεδομένα. Κάνεις το request στον δικό σου server με το δικό σου key και περνάς στο element το JSON. Από τον browser του επισκέπτη δεν γίνεται request, οπότε ταιριάζει key οποιασδήποτε κλάσης.

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

Ένα server-side template μπορεί να γράψει το ίδιο JSON σε attribute:

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

B. Χωρίς key. Τα elements στο /v1/public/* δεν χρειάζονται key. Μοιράζονται το δημόσιο budget του επισκέπτη, 30 μονάδες ανά ώρα από ένα IP· όταν εξαντλείται, το element γράφει πόσο να περιμένεις.

<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 για τον browser. Τα elements σε endpoints με key παίρνουν ένα key pk_, δημιουργημένο για το site σου: λίστα domains, όριο credits και εύρος endpoints είναι υποχρεωτικά κατά τη δημιουργία. Δες την ενότητα “Keys για τον browser” στη σελίδα αυθεντικοποίησης. Το μυστικό key aw_ απορρίπτεται πριν καν από το request.

<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 χρειάζεται το chart, και επιπλέον το chinese/zodiac/animal αν βάζεις το aw-chinese-sign. Τα domains ελέγχονται κατά host: ένα key για το example.com δουλεύει και στο http://example.com:8080.

React και Next.js

Το React 19 κάνει render τα custom elements απευθείας. Από το απλό HTML διαφέρουν δύο πράγματα:

• Το React κρατά το key για τον εαυτό του, οπότε πέρνα το key ως api-key.
• Σε σελίδα με server-side render, τα δεδομένα για τον τρόπο A πέρνα τα ως string. Το React απορρίπτει αντικείμενα κατά το server-side 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)} />;
}

Τα modules μπορούν να γίνουν import στον server: το tag περνά ως απλό HTML και σχεδιάζεται μόλις ο browser φορτώσει το element.

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 με ένα chart στη σελίδα (τροχός, πίνακας και πλέγμα με τα ίδια δεδομένα γέννησης) κάνουν ένα request για όλα.

Το aw-aspect-grid στο δικό του μέγεθος έχει περίπου 560 px πλάτος. Σε στενότερη στήλη συρρικνώνεται και οι ετικέτες των orb γίνονται μικρές· το attribute scroll κρατά το πλήρες μέγεθος με οριζόντια κύλιση.

Γλώσσα, θέμα, σφάλματα

• Το lang δέχεται οποιαδήποτε από τις 21 γλώσσες, από προεπιλογή παίρνεται το <html lang> της σελίδας. Τα ονόματα έρχονται από τους πίνακες localized στο API.
• Το theme="dark" αλλάζει το σχέδιο· τα χρώματα ορίζονται από τις CSS μεταβλητές --aw-accent, --aw-fg, --aw-bg, --aw-bg-soft, --aw-border.
• Κάθε element στέλνει ένα event aw-error με { kind, message }, όπου το kind είναι error, rate-limited ή key.