# Web-συστατικά

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

Το πακέτο είναι σε **alpha** (`0.1.0-alpha.1`): τα ονόματα των attributes μπορεί ακόμη να αλλάξουν μέχρι το 1.0. Σελίδα πακέτου: [npm](https://www.npmjs.com/package/@astroway/ui), κώδικας: [GitHub](https://github.com/astroway/astroway-ui).

## Εγκατάσταση

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

```html
<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:

```bash
npm install @astroway/ui@alpha
```

```js
```

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

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

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

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

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

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

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

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

Για αυτά τα 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.

```tsx
'use client';

  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 γλώσσες](/languages/), από προεπιλογή παίρνεται το `<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`.