# Webコンポーネント

`@astroway/ui` は普通のカスタムエレメントのセットです。ページにタグを置くだけで自分で描画します。カードは [`@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
```

## エレメントにデータを渡す3つの方法

**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/*` のエレメントはキーを必要としません。訪問者のパブリック予算を共有し、1 IP あたり 1 時間に 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 はカスタムエレメントを直接レンダリングします。普通の HTML と違う点が2つあります:

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

ページ上で同じカードを持つエレメント（ホイール、テーブル、グリッドは同じ出生データ）では、すべてが1回のリクエストで済みます。

`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` のいずれかです。