# Componentes web

`@astroway/ui` es un conjunto de custom elements: pones una etiqueta en la página y se dibuja a sí mismo. Los gráficos los dibuja [`@astroway/render`](https://www.npmjs.com/package/@astroway/render), el mismo código que está detrás de `/v1/render/*`, por lo que la rueda en tu página coincide con la que devuelve la API.

El paquete está en **alfa** (`0.1.0-alpha.1`): los nombres de los atributos aún pueden cambiar antes de la versión 1.0. Página del paquete: [npm](https://www.npmjs.com/package/@astroway/ui), código: [GitHub](https://github.com/astroway/astroway-ui).

## Instalación

Desde CDN, sin compilación:

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

O desde npm, importando todos los elementos o solo los necesarios. El paquete está aún en alfa, así que solicita esta etiqueta:

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

```js
```

## Tres formas de dar datos al elemento

**A. Tus datos.** Haces una solicitud en tu servidor con tu clave y pasas el JSON al elemento. No se hace ninguna solicitud desde el navegador del visitante, por lo que sirve cualquier clave de cualquier clase.

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

La plantilla del servidor puede escribir el mismo JSON en el atributo:

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

**B. Sin clave.** Los elementos en `/v1/public/*` no necesitan clave. Comparten un presupuesto público del visitante, 30 unidades por hora desde una IP; cuando se agota, el elemento escribe cuánto esperar.

```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. Clave para navegador.** Los elementos en los endpoints con clave toman la clave `pk_`, creada para tu sitio: lista de dominios, límite de créditos y ámbito de endpoints son obligatorios al crear. Ver la sección "Claves para navegador" en la página de [autenticación](/authentication/). La clave secreta `aw_` se rechaza antes de la solicitud.

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

Para estos elementos en el ámbito de la clave se necesita `chart`, y también `chinese/zodiac/animal` si pones `aw-chinese-sign`. Los dominios se verifican por host: la clave para `example.com` funciona también en `http://example.com:8080`.

## React y Next.js

React 19 renderiza custom elements directamente. Se diferencian del HTML normal en dos cosas:

- React toma `key` para sí mismo, así que pasa la clave como `api-key`.
- En una página con renderizado del servidor, para el método A pasa los datos como cadena. React descarta objetos durante el renderizado del servidor y no los establece durante la hidratación.

```tsx
'use client';

  return <aw-natal-wheel data={JSON.stringify(chart)} />;
}
```

Se pueden importar módulos en el servidor: la etiqueta viene como HTML normal y se dibuja, tan pronto como el navegador carga el elemento.

## Elementos

| Elemento | Métodos | Fuente |
|---|---|---|
| `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` |

Los elementos con un solo gráfico en la página (rueda, tabla y cuadrícula con los mismos datos de nacimiento) hacen una solicitud para todos.

`aw-aspect-grid` en su tamaño completo tiene unos 560 px de ancho. En una columna más estrecha se reduce, y las etiquetas de los órbitas se vuelven pequeñas; el atributo `scroll` mantiene el tamaño completo con desplazamiento horizontal.

## Idioma, tema, errores

- `lang` acepta cualquiera de los [21 idiomas](/languages/), por defecto toma `<html lang>` de la página. Los nombres vienen de las tablas `localized` en la API.
- `theme="dark"` cambia el dibujo; los colores se definen con las variables CSS `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border`.
- Cada elemento envía el evento `aw-error` con `{ kind, message }`, donde `kind` es `error`, `rate-limited` o `key`.