ポップオーバー

hc-popover はネイティブの popover 属性をスタイルします。開閉、トップレイヤー描画、ライトディスミス、Escape で閉じるはブラウザが処理します — JavaScript は不要です。

別名: フローティングパネル。

ブラウザのベースライン

プリミティブ	必要バージョン
HTML `popover`	Chrome 114、Edge 114、Firefox 125、Safari 17
CSS Anchor Positioning	Chrome 125、Edge 125、Firefox 147、Safari 26

Anchor Positioning のないエンジンでは installPopover() の JS フォールバックが data-side のポップオーバーを配置します。JavaScript なしではブラウザ中央のままです。data-arrow ポインタは素の CSS で、どこでも描画されます。

基本の HTML

<button class="hc-button" type="button" popovertarget="filter-popover">
  Filter
</button>

<div id="filter-popover" class="hc-popover" popover>
  <p>Choose filters here.</p>
</div>

popover 属性のデフォルトは popover="auto" で、つまり:

外側クリックでのライトディスミス。
Escape で閉じる。
auto のポップオーバーは同時に 1 つだけ開く。

ライトディスミスを無視するポップオーバーには popover="manual" を使い、element.hidePopover() で自分で閉じてください。

JavaScript

上の基本的なライトディスミスのポップオーバーは、ネイティブの Popover API だけで機能します。下の方向つき配置と htmx 自動クローズにはビヘイビアが必要です — 使うものを起動時に一度インストールしてください:

import { installPopover, installClosePopover } from '@hypermedia-components/core';
installPopover();       // data-side / data-align anchoring + aria sync
installClosePopover();  // close on a successful htmx request (optional)

ゼロ設定の @hypermedia-components/core/behaviors エントリは両方を自動でインストールします。

方向つき配置

素のポップオーバーはブラウザが配置します(トップレイヤーの中央)。 side と align つきでトリガーにアンカーするには、data-side (top / right / bottom / left)と、任意で data-align (start / center / end、デフォルト center)を足します。 installPopover() がアンカリングを配線し、トリガーの aria-expanded / aria-controls を同期し続けます。小さなポインタには data-arrow を足します。

<button class="hc-button" type="button" popovertarget="filters">Filter</button>

<div id="filters" class="hc-popover" popover
     data-side="right" data-align="start" data-arrow>
  <p style="margin:0;">Opens to the inline-end, top-aligned.</p>
</div>

配置は、サポートされる環境では CSS Anchor Positioning (position-area)を使い、ビューポート端では position-try-fallbacks で反転します。同じ属性が、それのないエンジン向けの JS フォールバック(getBoundingClientRect)も駆動するため、両パスはポップオーバーを同一に配置します。共有される機構 — 両パス、矢印、--hc-anchored-* ノブ — は基礎 → アンカー配置にドキュメントがあります。

エンジンの要件とフォールバックの振る舞いは、下のブラウザのベースラインを参照してください。

htmx での利用

ポップオーバーは htmx 駆動のフォームをホストできます。リクエスト成功後にポップオーバーを閉じるには、data-hc-close-popover-on-success 属性を足して installClosePopover() ビヘイビア (@hypermedia-components/core/behaviors に同梱)をインストールします。

<form
  data-hx-get="/items"
  data-hx-target="#results"
  data-hc-close-popover-on-success>
  …
</form>

ビヘイビアは htmx:afterRequest を待ち受けて成功を確認し、 closest('[popover]').hidePopover() を呼びます。

パネル構造 — body と footer

フォームを載せるポップオーバー(データグリッドのフィルタ / ソート / 列選択パネル)は 2 つの任意パーツを使います。hc-popover__body はコントロールを縦に積みます(--hc-popover-body-gap の display: grid — チェックボックス群の自然な body 要素である <fieldset> のリセットも兼ねます)。 hc-popover__footer は末尾のアクション行(終端寄せ・ギャップ付き) です。素のポップオーバーにはどちらも不要です。

<div id="cols-popover" class="hc-popover" popover>
  <form data-hx-get="/items" data-hx-target="#items-grid"
        data-hc-close-popover-on-success>
    <fieldset class="hc-popover__body">
      <label class="hc-checkbox-label">
        <input class="hc-checkbox" type="checkbox" name="cols" value="name" checked />
        Name
      </label>
      <!-- …列ごとにチェックボックスを 1 つ… -->
    </fieldset>
    <footer class="hc-popover__footer">
      <button class="hc-button" type="submit" data-variant="primary">Apply</button>
    </footer>
  </form>
</div>

アクセシビリティ

ポップオーバーは自動的にメニューになるわけではありません。 role="menu" の設定と矢印キーナビゲーションの提供は、別の場所でドキュメントされている別の関心事です。
ポップオーバーが閉じるとトリガー(popovertarget を持つ要素)にフォーカスが戻ります — これはブラウザの挙動です。
ホバーやフォーカスで発動するツールチップ風のポップオーバーには、 [popovertargetaction="show"] 属性ファミリーかカスタムのホバーハンドラを使ってください。ホバーのみのツールチップは、それ自体ではキーボードユーザーにアクセシブルではありません。
ポップオーバーのアクセシブルな名前はコンテンツから来ます。見えるタイトルがなければ aria-label を足してください。

テーマ用トークン

トークンパス	用途
`popover.bg` / `-fg` / `-border`	面の色。
`popover.radius`	角丸。
`popover.padding`	内側のパディング。
`popover.min-width` / `-max-width`	サイズの範囲。
`popover.body-gap` / `-footer-gap`	`__body` / `__footer` 内のギャップ(body のギャップは footer と body の間隔にも使われます)。

CSS 変数

生成される CSS 変数を表示

--hc-popover-bg | -fg | -border
--hc-popover-radius | -padding
--hc-popover-min-width | -max-width
--hc-popover-body-gap | -footer-gap