# 웹 컴포넌트

`@astroway/ui`는 일반 custom elements 모음이야: 페이지에 태그를 넣으면 스스로 그려. 지도는 [`@astroway/render`](https://www.npmjs.com/package/@astroway/render)가 그려, `/v1/render/*` 뒤에 있는 같은 코드라서, 네 페이지의 휠이 API가 반환하는 휠과 일치해.

패키지는 **알파**(`0.1.0-alpha.1`) 단계야: 속성 이름은 1.0까지 바뀔 수 있어. 패키지 페이지: [npm](https://www.npmjs.com/package/@astroway/ui), 코드: [GitHub](https://github.com/astroway/astroway-ui).

## 설치

CDN으로, 빌드 없이:

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

또는 npm으로, 모든 요소를 가져오거나 필요한 것만 가져와. 패키지는 아직 알파 단계라, 이 태그를 요청해:

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

```js
```

## 세 가지 방법으로 요소에 데이터 제공

**A. 너의 데이터.** 서버에서 네 키로 요청을 보내고 요소에 JSON을 전달해. 방문자의 브라우저에서는 요청이 안 가니까, 어떤 클래스의 키든 괜찮아.

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

서버 템플릿이 같은 JSON을 속성에 기록할 수 있어:

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

**B. 키 없이.** `/v1/public/*` 엔드포인트의 요소들은 키가 필요 없어. 방문자의 퍼블릭 예산을 공유하는데, IP당 시간당 30 유닛; 소진되면 요소가 얼마나 기다려야 하는지 알려줘.

```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. 브라우저용 키.** 키가 필요한 엔드포인트의 요소들은 `pk_` 키를 사용해, 네 사이트를 위해 생성된 거야: 도메인 목록, 크레딧 한도, 엔드포인트 영역이 생성 시 필수야. [인증](/authentication/) 페이지의 "브라우저용 키" 섹션을 참고해. 비밀 키 `aw_`는 요청 전에 거부돼.

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

이 요소들에선 키 영역에 `chart`가 필요하고, `aw-chinese-sign`을 사용할 경우 `chinese/zodiac/animal`도 필요해. 도메인은 호스트와 일치해야 해: `example.com`용 키는 `http://example.com:8080`에서도 동작해.

## React와 Next.js

React 19는 custom elements를 직접 렌더링해. 일반 HTML과 다른 점은 두 가지야:

- React는 `key`를 자신이 잡아먹으니, 키는 `api-key`로 전달해.
- 서버 렌더링 페이지에서 방식 A의 데이터를 문자열로 전달해. React는 서버 렌더링 시 객체를 버리고, 하이드레이션 시에도 설정하지 않아.

```tsx
'use client';

  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`는 자체 크기가 약 560px 너비야. 좁은 컬럼에서는 줄어들고, 궤도 라벨이 작아져; `scroll` 속성은 가로 스크롤이 있는 전체 크기를 유지해.

## 언어, 테마, 오류

- `lang`은 [21 언어](/languages/) 중 하나를 받아, 기본값은 페이지의 `<html lang>`을 사용해. 이름은 API의 `localized` 테이블에서 와.
- `theme="dark"`는 그림을 전환해; 색은 CSS 변수 `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border`로 지정돼.
- 각 요소는 `{ kind, message }`를 포함한 `aw-error` 이벤트를 보내, 여기서 `kind`는 `error`, `rate-limited` 또는 `key`야.