インストール

Hypermedia Components は、CSS ファイル 1 つ・ビヘイビアバンドル 1 つ・任意のマクロバンドル 1 つとして配布されます。CSS は常に読み込み、JS はインタラクティブなビヘイビアを使う場合のみ読み込んでください。

CDN(ビルドステップなし)

HC を試す最速の方法 — そしてそのまま本番運用しても問題ない方法 — は、 jsDelivr から読み込む 2 つのタグです:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@hypermedia-components/core/dist/hc.min.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@hypermedia-components/core/dist/hc.behaviors.min.js"></script>

これで全コンポーネントと全ビヘイビアが使えます(CSS + JS 合計 gzip 約 74 KB。CDN が通常配信する Brotli ではより小さくなります)。本番ではバージョンを固定してください (…/npm/@hypermedia-components/core@<version>/dist/…)— リリースがページの表示を勝手に変えてしまうのを防げます。固定バージョンを上げる前に、何が公開 API かはバージョニングと安定性を確認してください。正確なサイズ、コンポーネント単位の細粒度ロード、import map 方式はバンドルサイズとインポートを参照してください。

バンドラーを使う場合(npm)

npm install @hypermedia-components/core

import '@hypermedia-components/core/css';       // the styles
import '@hypermedia-components/core/behaviors';  // auto-installs every behavior

/behaviors エントリは副作用を持ちます: インポートすると、DOM の準備ができた時点ですべてのビヘイビアがインストールされます。使うビヘイビアだけを取り込みたい場合は、個別のインストーラをインポートしてください — ビヘイビアを参照。

バンドラーを使わない場合(静的ファイル)

ビルドステップがない場合は、 node_modules/@hypermedia-components/core/dist/(またはリリースのダウンロード)からビルド済みファイルを静的フォルダにコピーし、直接参照します:

<link rel="stylesheet" href="/assets/hc/hc.min.css">
<script type="module" src="/assets/hc/hc.behaviors.min.js"></script>

ここでは .min.js バンドルを使ってください — 単体で完結しています。 (未圧縮の hc.behaviors.js はバンドラー用エントリで、兄弟モジュールをインポートするため <script> タグからは単体で動きません。) Plain HTML ガイドには、トースト領域と htmx のラウンドトリップを含む、コピー&ペーストで動く完全なページがあります。

ビヘイビア

CSS コンポーネントは単体で描画されます。インタラクティブなもの — メニュー、ダイアログ、トースト、コンボボックスなど — には小さな JS ビヘイビアが必要です。選択肢は 2 つ:

一括 — import '@hypermedia-components/core/behaviors'; ですべてのビヘイビアが自動インストールされます(docs サイトと各インテグレーションガイドはこの方式です)。

個別 — 必要なインストーラだけをインポートします:

import { installMenu, installToast } from '@hypermedia-components/core';
installMenu();
installToast();

すべての installX() は冪等で(再呼び出しが安全 — 例: htmx スワップ後)、 アンインストーラを返します。各コンポーネント / レシピのページに、必要なビヘイビアが明記されています。

htmx(レシピ用)

コンポーネントとビヘイビアは htmx なしで動きます。レシピ — およびこのドキュメントのすべての data-hx-* 属性 — には、それに加えて htmx が必要で、読み込みは利用者の責任です。HC が htmx をバンドルすることはありません:

<script defer src="https://unpkg.com/htmx.org@2"></script>

本番では正確なバージョンを固定してください (htmx のインストールドキュメント参照)。 HC のドキュメントは htmx 属性を data-hx-* 形式で書きます (htmx は両形式を受け付けます)— htmx インテグレーションガイドが読み込み・CSRF・レスポンスヘッダーの規約をカバーしています。

トラブルシューティング

インタラクティブなコンポーネントが描画されるのに反応しない (メニューが開かない、トーストがスタックしない)— ビヘイビアバンドルが読み込まれていないか、未圧縮の hc.behaviors.js を <script> タグから読み込んでいます(上記の注意参照 — そこでは .min.js を使ってください)。
data-hx-* 属性が何もしない — htmx 自体がページにありません。別のスクリプトです(htmx参照)。
htmx でスワップしたフラグメント内のコンポーネントが動かなくなる — auto-init の /behaviors バンドルはスワップ後に再スキャンするため、これは個別インストーラ方式でのみ起きます。スワップ後に該当の installX() をもう一度呼んでください(冪等です)。

次のステップ

クイックスタート — 最小構成のページを一歩ずつ組み立てます。
コンポーネント — 全コンポーネントをライブ例つきで。