各レシピは、短縮形・展開後の HTML・任意のマクロ・サーバレスポンス契約を
ドキュメント化しています。必要なもの列に記載のあるレシピは
@hypermedia-components/coreの
installX() を必要とします。それ以外(「—」)は純粋な htmx 属性だけです。
任意のレシピのスキャフォールドは
npx @hypermedia-components/cli add <name> で取得できます。コピーは
npx @hypermedia-components/cli validate で契約に対して機械検証できます。
各レシピページにはライブデモもあります。ほぼすべてのデモは、
このサイトの Worker が api/recipes/<name>/ 配下で実装する
各レシピのサーバ応答契約に対して、実際の htmx リクエストを送ります
(例外: コピー、
条件付きフィールド、
未保存ガードは
クライアントのみ、ストリーミング応答は
chat-messages のエンドポイントを共有)。
フォームの構築と送信 — バリデーション、ウィザード、サーバ往復を
必要とする入力たち。
| レシピ |
やりたいこと |
必要なもの |
| ミューテーションフォーム |
インライン 4xx エラー・成功時リダイレクト・二重送信ガードつきでフォームを送信する |
installFieldErrors() |
| フィールドエラー |
サーバが送るバリデーションエラーフラグメントを、名前の一致するフィールドへ振り分ける |
installFieldErrors() |
| 条件付きフィールド |
選択中のモードが読まないフィールドを、往復なしで宣言的に隠す |
installShowWhen() |
| マルチステップフォーム |
ウィザードを作る — ステップとドラフトはサーバが所有し、ステップ全体をスワップ |
— |
| インライン編集 |
値を表示モードと編集モードの間でその場でスワップする(クリックして編集) |
— |
| ファイルアップロード |
ライブ進捗バーと out-of-band フォームリセットつきでマルチパートアップロードする |
installUploadProgress() |
| 郵便番号住所補完 |
郵便番号から住所を補完したい — マスク付き入力、1 回のルックアップ GET、アウトオブバンドの自動入力 |
installMask() |
| マスタ参照 |
マスタを参照する — change で検証されるコード直接入力+検索ダイアログのピッカー。未解決コードは hidden の id を必ずクリア |
installRemoteDialog() + installCloseDialog() |
| カスケードセレクト |
階層選択を連鎖する(依存)select で行う — change のたびに次のレベルを読み込み |
— |
| トランスファー |
デュアルリストボックスの割り当て / 解除をサーバ往復で行う — フォーム全体のスワップ、カスタム JS ゼロ |
— |
作業中の内容を守る — ドラフト、ダーティ状態、セッション切れ、
落ちた接続、そして競合・重複する保存。
| レシピ |
やりたいこと |
必要なもの |
| 未保存ガード |
編集が失われる前に警告したい — data-dirty 状態、タブを閉じる際のプロンプト、boosted ナビの確認、保存でクリーン |
installDirtyGuard() |
| 自動保存 |
入力と同時にフォームをドラフトしたい — デバウンス送信、復元バナー、新規 JS ゼロ |
— |
| 編集競合 |
楽観ロックにしたい — 隠し version が毎回の保存に同乗し、古い保存は 409 の競合ダイアログに |
— |
| 冪等キー |
二重送信をサーバ側で無害化する — 描画フォームごとにキー 1 つ。リプレイには元のレスポンスを返し、エラーにしない |
— |
| セッション切れ再認証 |
401 をログインダイアログにして、中断されたリクエストを再実行したい |
installSessionExpiry() |
| ネットワーク再試行 |
応答がまったく来なかったリクエスト(オフライン / タイムアウト)を、動く Retry 付きで表面化する |
installNetworkRetry() |
要素ひとつ、リクエストひとつ — ボタン、ガード、小さな
クライアントサイドユーティリティ。
| レシピ |
やりたいこと |
必要なもの |
| リクエストアクション |
ビジー状態つきのボタンから htmx リクエストを発行する |
— |
| 確認アクション |
破壊的リクエストを確認ダイアログでガードする |
installConfirm() |
| 削除の取り消し |
即座に削除する(楽観的削除)— 猶予期間内ならトーストの Undo で行を復元 |
installToast() |
| クリップボードにコピー |
読み取り専用の値(URL、トークン、スニペット)をクリップボードへコピーする |
installCopy() |
| 並べ替えリスト |
サーバが順序を所有するリストをポインタ/キーボードで並べ替え、リクエスト 1 本で永続化する |
installSortable() |
業務レコードが通る契約 — 明細行、ライフサイクル、一括投入、
長時間処理。
| レシピ |
やりたいこと |
必要なもの |
| 明細行 |
受注・見積の明細行を編集する — 追加・削除・再計算はフォーム全体の往復。計算はすべてサーバが所有 |
— |
| ワークフローアクション |
レコードのライフサイクルを駆動する — サーバは合法な遷移だけを描画。コメント必須の遷移は 422、陳腐化した操作は現在の真実で 409 |
— |
| CSV インポート |
驚きなしの一括投入 — アップロード、検証レポート、トークン付き確定 |
— |
| 非同期ジョブ |
リクエストより長生きする処理を回す — 202 + 終端状態を列挙した自己ポーリングのジョブカード |
— |
hc-datagrid
コンポーネントを運用するためのすべて — ページング、ソート / フィルタ /
列のツーリング、インライン編集のエラーワイヤ、そして大きなグリッドを
正直に保つパターン。データグリッドページ
テンプレートが、これらすべてが載るレイアウトを組み立てます。
初めてなら、全体を構築順で地図化した
データグリッドガイドから
始めてください。
| レシピ |
やりたいこと |
必要なもの |
| データグリッドのページネーション |
データグリッドをサーバ駆動でページングする — out-of-band の行スワップつき |
installDatagrid() |
| データグリッドの並び替え |
適用中のソート集合を述べ、その場で編集させたい — 並べ替え可能な順序付きリスト。表示していない列のキーも扱える |
installSortList() |
| データグリッドの列フィルタ |
列ごとのフィルタポップオーバー — 名前空間付き f-col パラメータでグリッドを GET し、トリガーが data-filtered で戻る |
— |
| データグリッドの列選択 |
ユーザーごとにグリッドの列を選ばせたい — チューザーフォームが cols= の繰り返しパラメータ付きでグリッドを GET |
— |
| データグリッドの列プリファレンス |
ユーザーごとの列幅・列順を記憶 — ミラー入力がリサイズをオートセーブ。ソータブルなチューザーの cols= 順が列順 |
— |
| 行から詳細へ |
行が指すレコードを開いて同じ一覧に戻る — 同一性の列のリンク、戻りの #row-<id>、結果セットや選択を辿る |
installRowLink() |
| データグリッドのツリー |
グリッド内の階層 — aria-level の行が子を親の直後に遅延ロード |
— |
| データグリッド無限スクロール |
ページ番号なしの無限リスト — revealed の番兵行が次のカーソルバッチをスワップ |
— |
| データグリッドのスナップショットページャー |
ワークキューの母集合を検索時点で凍結する — フォームが行キーを運び、処理済み行は見え続け、消えた行はトゥームストーンに |
installDatagrid() |
| データグリッドの編集エラー |
グリッドの楽観的コミットのループを閉じる — 422 がマーク付きセル＋エラー行つきでレコードを再描画 |
— |
| データグリッドの編集競合 |
行単位の楽観的ロック — 古いバージョンは 409 で上書き/破棄つきの競合行へ |
— |
| データグリッド一括操作 |
チェックボックスで行を選択し、1 つのアクションを全行に POST する |
installDatagridActions() |
| データグリッドの一括操作エラー |
大量エラーの一括操作 — best-effort と atomic、理由別集約、レポートから行へのリンク |
— |
| レシピ |
やりたいこと |
必要なもの |
| ライブ検索 |
入力に応じて検索する(タイプアヘッド)— デバウンスされた入力で結果をスワップ |
— |
| 検索結果の上限 |
1 回の検索が返せる件数を制限する — cap+1 検出、「cap+」件数、残り続ける切り詰めバナーまたはハードリジェクト |
— |
| フィルタポップオーバー |
フィルタフォームをポップオーバーに載せ、成功時に閉じる |
installClosePopover() |
| 保存ビュー |
現在のフィルタに名前を付けて、ただのリンクとして呼び戻したい — サーバー保存のクエリ文字列 |
— |
| レシピ |
やりたいこと |
必要なもの |
| レイジーパネル |
パネルの読み込みを、初めて表示されるまで遅延する |
— |
| レイジーツリー |
ツリーの枝の子を初回展開時に読み込む |
installTree() |
| データ領域 |
HX-Trigger の無効化を起点に領域を自己更新する |
— |
| レシピ |
やりたいこと |
必要なもの |
| SSE 更新 |
Server-Sent Events でサーバからフラグメント更新をプッシュする — 名前付きイベントと out-of-band プッシュ |
— |
| SSE トースト |
JSON ペイロードつき SSE イベントを許可リスト方式の DOM イベントへ変換する — トーストはそのまま動作 |
installSseDispatch() |
| チャットメッセージ |
コンポーザーの 1 POST でチャットのやり取り(ユーザーメッセージ + aria-busy のアシスタントプレースホルダー)を追記。422 経路はトランスクリプトを汚しません |
installChatScroll() |
| ストリーミングレスポンス |
アシスタントのプレースホルダーを SSE で埋める — aria-busy が読み上げを保留する間チャンクを追記し、done が最終メッセージに置換してストリームを閉じます |
— |
| レシピ |
やりたいこと |
必要なもの |
| リモートダイアログ |
ダイアログ(モーダル)の中身を、開くときにサーバから読み込む |
installRemoteDialog() + installCloseDialog() |
| トースト |
クライアントまたは HX-Trigger ヘッダーからトースト通知(スナックバー)を発火する |
installToast() |
| 未読バッジ |
アプリクロームの通知カウントを新鮮に保ち、ゼロでは正直に消し、自分の操作で即時補正する |
— |
| レシピ |
やりたいこと |
必要なもの |
| チャート |
サーバが送るデータテーブルを Observable Plot の SVG チャートへ昇格する |
installChart() + Plot |