トースト

hc-toast は一時的な通知です。トーストのマークアップは書きません — イベントを発火する(または HX-Trigger ヘッダーを返す)と、 installToast() が .hc-toast を .hc-toast-region へ描画し、遅延の後に自動で解散させます。

別名: スナックバー、通知ポップアップ。

セットアップ

トーストは installToast() ビヘイビアが描画します — ないと hc:toast イベントを発火しても何も起きません。 起動時に一度インストールしてください:

import { installToast } from '@hypermedia-components/core';
installToast(); // idempotent; returns an uninstaller

ゼロ設定の @hypermedia-components/core/behaviors エントリは自動でインストールします。マークアップは不要です — 事前描画しなければビヘイビアがデフォルトの .hc-toast-region を作成します。

見た目

このマークアップはビヘイビアが描画します — 手で書くことはありません。

Saved

Your changes were saved.

Profile updated.

Upload failed

The server returned a 500.

<!-- installToast() が .hc-toast-region に描画します。
     data-variant のデフォルトは "info"。error は代わりに
     role="alert" / aria-live="assertive" を使います。 -->
<div class="hc-toast" data-variant="success" role="status"
     aria-live="polite" aria-atomic="true">
  <div class="hc-toast__title">Saved</div>
  <div class="hc-toast__body">Your changes were saved.</div>
  <button class="hc-toast__close" type="button" aria-label="Dismiss">
    <span aria-hidden="true">×</span>
  </button>
</div>

トーストの発火

document.body に hc:toast の CustomEvent を発火します:

document.body.dispatchEvent(new CustomEvent('hc:toast', {
  bubbles: true,
  detail: { message: 'Saved.', title: 'Done', variant: 'success', duration: 4500 },
}));

試してみてください — 各ボタンがイベントを発火します。トーストはページの隅に現れて自動で消えます:

// installToast() must be installed (it is in the behaviors bundle).
successButton.addEventListener('click', () => {
  document.body.dispatchEvent(new CustomEvent('hc:toast', {
    bubbles: true,
    detail: { title: 'Done', message: 'Saved.', variant: 'success' },
  }));
});

…あるいはサーバにレスポンスから発火させます — htmx が HX-Trigger ヘッダーを同じイベントに変えます:

HX-Trigger: {"hc:toast": {"message": "Saved.", "variant": "success"}}

detail のフィールド: message(必須)、title?、variant? (info · success · warning · error)、duration? ms(0 は解散されるまで保持)、id?(下記)、action?(下記)。error は assertive に読み上げられ(role="alert")、それ以外は role="status" を使います。

アクションと更新

アクションボタン。 action: { label, event } を足すとトーストがボタンを描画します。クリックすると event という名前のバブリングする CustomEvent を発火します(その後トーストを解散)。素のリスナーか、任意の祖先の htmx data-hx-trigger="<event>" で捕まえます — Undo に便利です:

document.body.dispatchEvent(new CustomEvent('hc:toast', {
  bubbles: true,
  detail: { message: 'Item deleted', duration: 0, action: { label: 'Undo', event: 'hc:undo' } },
}));
document.body.addEventListener('hc:undo', () => restoreItem());

id による更新。 トーストに id を与えると、同じ id の後続 hc:toast は、新しいトーストを積む代わりにそれをその場で更新します (メッセージ / バリアントを再描画し、自動解散タイマーをリセット)。これがクライアント状態なしの loading → success / error の promise をモデル化します — ネットワークは htmx に残ります:

# request fires a sticky loading toast
HX-Trigger: {"hc:toast": {"id": "save-42", "message": "Saving…", "duration": 0}}

# the response updates the same toast
HX-Trigger: {"hc:toast": {"id": "save-42", "message": "Saved!", "variant": "success", "duration": 4500}}

トーストがモデル化するのは UI の状態だけです。実際のリクエストは htmx が実行します。

領域

トーストは最初の [data-hc-toast-region] へ描画されます。なければビヘイビアが(右下に)作成します。位置とスタッキングを設定するには 事前描画してください:

<div class="hc-toast-region" data-hc-toast-region
     data-position="top-center" data-limit="3"
     role="region" aria-label="Notifications"></div>

位置

data-position が領域をアンカーします — {top,bottom}-{left,center,right}(デフォルト bottom-right)。 top 系は下向きに積まれ(最新が端に最も近い)、bottom 系は上向きに積まれます。

<div class="hc-toast-region" data-hc-toast-region data-position="top-right" …></div>

スタッキング上限

data-limit="N" が見えるトースト数の上限です。新しいものが届くと 最も古いものが追い出されます。なければスタックは無制限です。

解散(dismiss)

すべてのトーストは上端コーナーに閉じるボタン (.hc-toast__close、ラベルはカタログメッセージ toast.dismiss)を描画します — マウスでも見つけられる可視の解散手段で、特にスティッキートースト(duration: 0)で重要です。その上に 2 つの操作が重なります:

スワイプ — トーストを横にドラッグし、幅の約 40% を超えると飛び出し、そうでなければスナップバックします。縦のドラッグは引き続きページをスクロールします。動きは prefers-reduced-motion の下で取り除かれます。
Escape — フォーカスを含むトーストを解散します(閉じるボタンまたはアクションボタンがあるため、どのトーストにもキーボードで到達できます)。

アクセシビリティ

領域はラベルつきの role="region" です。ラベルは i18n カタログ (toast.label)で翻訳できます。
各トーストはライブ領域です — error は role="alert" / aria-live="assertive"、それ以外は role="status" / aria-live="polite" — フォーカスを動かさずに読み上げられます。
色だけに頼らないでください: title か明確な message を含めてください。
duration は読み切れる長さに保ってください(重要なメッセージは 0)。
閉じるボタンのアクセシブルネームはカタログメッセージ toast.dismiss(既定 “Dismiss”)です — setMessages() で翻訳してください。

テーマ用トークン

トークンパス	用途
`toast.region-inset` / `region-gap`	端からの領域オフセット / トースト間のギャップ。
`toast.gap`	タイトルと本文の間のギャップ。
`toast.min-width` / `max-width`	トーストの幅の範囲。
`toast.padding-y` / `padding-x` / `radius`	ボックスの寸法。
`toast.{variant}.{bg,fg,border}`	バリアントごとの色。

CSS 変数

生成される CSS 変数を表示

--hc-toast-region-inset | -region-gap
--hc-toast-gap | -min-width | -max-width | -padding-y | -padding-x | -radius | -duration
--hc-toast-info-bg    | -fg | -border
--hc-toast-success-bg | -fg | -border
--hc-toast-warning-bg | -fg | -border
--hc-toast-error-bg  | -fg | -border