Componenti Web

@astroway/ui è un set di normali custom elements: metti il tag nella pagina e si disegna da solo. Le carte sono disegnate da @astroway/render, lo stesso codice che sta dietro a /v1/render/*, quindi la ruota sulla tua pagina corrisponde alla ruota restituita dall’API.

Il pacchetto è in alfa (0.1.0-alpha.1): i nomi degli attributi potrebbero ancora cambiare prima della 1.0. Pagina del pacchetto: npm, codice: GitHub.

Installazione

Da CDN, senza build:

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

Oppure da npm, importando tutti gli elementi o solo quelli che ti servono. Il pacchetto è ancora in alfa, quindi richiedi questo tag:

npm install @astroway/ui@alpha

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

Tre modi per fornire i dati a un elemento

A. I tuoi dati. Fai la richiesta sul tuo server con la tua chiave e passi il JSON all’elemento. Dal browser del visitatore non parte alcuna richiesta, quindi va bene una chiave di qualsiasi classe.

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

Un template lato server può scrivere lo stesso JSON in un attributo:

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

B. Senza chiave. Gli elementi su /v1/public/* non hanno bisogno di una chiave. Condividono il budget pubblico del visitatore, 30 unità all’ora per IP; quando si esaurisce, l’elemento indica quanto attendere.

<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. Chiave per il browser. Gli elementi su endpoint con chiave accettano una chiave pk_ creata per il tuo sito: alla creazione sono obbligatori l’elenco dei domini, il limite di crediti e l’ambito degli endpoint. Vedi la sezione “Chiavi per il browser” nella pagina di autenticazione. La chiave segreta aw_ viene rifiutata ancora prima della richiesta.

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

Per questi elementi l’ambito della chiave deve includere chart, e anche chinese/zodiac/animal se usi aw-chinese-sign. I domini vengono confrontati per host: una chiave per example.com funziona anche su http://example.com:8080.

React e Next.js

React 19 renderizza i custom elements direttamente. Rispetto al normale HTML cambiano due cose:

• React si prende key per sé, quindi passa la chiave come api-key.
• In una pagina con rendering lato server, i dati per il metodo A vanno passati come stringa. React scarta gli oggetti durante il rendering lato server e non li espone durante l’idratazione.

'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)} />;
}

I moduli possono essere importati sul server: il tag arriva come normale HTML e si disegna non appena il browser carica l’elemento.

Elementi

Elemento	Metodi	Sorgente
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

Gli elementi con una sola carta nella pagina (ruota, tabella e griglia con gli stessi dati di nascita) fanno una sola richiesta per tutti.

aw-aspect-grid nella sua dimensione nativa è largo circa 560 px. In una colonna più stretta si riduce e le etichette degli orbi diventano piccole; l’attributo scroll mantiene la dimensione piena con scorrimento orizzontale.

Lingua, tema, errori

• lang accetta una qualsiasi delle 21 lingue; per default viene preso il <html lang> della pagina. I nomi arrivano dalle tabelle localized dell’API.
• theme="dark" cambia il disegno; i colori sono definiti dalle variabili CSS --aw-accent, --aw-fg, --aw-bg, --aw-bg-soft, --aw-border.
• Ogni elemento emette un evento aw-error con { kind, message }, dove kind è error, rate-limited oppure key.