kaze風

Popover

クリックで開く非モーダルの浮遊パネル。Dialog と違い背景は操作でき、Escape・外側クリックで閉じてトリガーにフォーカスを戻します。ホバーで出る補足は Tooltip、メニュー項目は Dropdown を使います。

GitHub でソースを見る

プレビュー

使いどころ

使う場面

ボタンやリンク、入力欄など、操作できる中身を、クリックで開く小さなパネルに入れる（フィルター、簡単な設定、日付の選択）
PopoverTrigger と PopoverContent を Popover で包み、中の閉じるボタンには PopoverClose を使う
side（既定 "bottom"）と align で出る位置を決める。画面の端では反対側に切り替わる。anchorRef で別の要素に寄せられる

使わない場面

補足を読むだけのとき。操作できる中身がなければ Tooltip か HelpButton を使う
背景の操作を止めたい確認や必須の入力。Dialog を使う
大きなフォームや長いコンテンツ。Drawer か Dialog を使う
操作を並べたメニュー。Dropdown を使う

使い方

import { Button, Popover, PopoverClose, PopoverContent, PopoverTrigger } from "kaze-design-system";

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">表示設定</Button>
  </PopoverTrigger>
  <PopoverContent aria-label="表示設定" side="bottom" align="start">
    <p>一覧の密度と並び順を変更できます。</p>
    <PopoverClose asChild>
      <Button size="sm">閉じる</Button>
    </PopoverClose>
  </PopoverContent>
</Popover>

プロパティ

名前	型	デフォルト	説明
`children`	`ReactNode`	なし	PopoverTrigger と PopoverContent
`open`	`boolean`	なし	開閉状態（制御）
`defaultOpen`	`boolean`	`false`	初期の開閉状態（非制御）
`onOpenChange`	`(open: boolean) => void`	なし	開閉が変わる時のコールバック
`PopoverTrigger.asChild`	`boolean`	`false`	子要素をそのままトリガーにする。aria-expanded / aria-controls / aria-haspopup="dialog" が注入される
`PopoverContent.side`	`"top" \| "bottom" \| "left" \| "right"`	`"bottom"`	トリガーのどの側に出すか。画面からはみ出すときは反対側へ反転する
`PopoverContent.align`	`"start" \| "center" \| "end"`	`"center"`	トリガーとの揃え位置
`PopoverContent.sideOffset`	`number`	`8`	トリガーとの間隔（px）
`PopoverContent.anchorRef`	`RefObject<HTMLElement \| null>`	なし	トリガーの代わりに位置の基準にする要素
`PopoverContent.onOpenAutoFocus`	`(event: Event) => void`	なし	開いた直後に呼ばれる。preventDefault() で初期フォーカスを自前で制御できる
`PopoverClose.asChild`	`boolean`	`false`	子要素をそのまま閉じるボタンにする

型と必須かどうかはソースの型定義から自動で生成しています。表にない HTML 標準の属性（className や aria-* など）も、ルート要素にそのまま渡せます。

キーボード操作

キー	動作
`Enter / Space`	トリガーを押して開閉する
`Tab / Shift + Tab`	開いたパネル内の操作にフォーカスを移す（フォーカスは閉じ込めない）
`Escape`	パネルを閉じる。フォーカスがトリガーかパネルの中にあればトリガーに戻る

アクセシビリティ

トリガーには aria-haspopup="dialog"、aria-expanded、aria-controls が付き、パネルは role="dialog"（モーダルではない）
開くと最初のフォーカスできる要素にフォーカスが移る。なければパネル自体。onOpenAutoFocus で preventDefault すると初期フォーカスを自分で決められる
背景は inert にならず、スクロールも止まらない。パネルの外をクリックすると閉じる
パネルに名前が必要なら aria-label か aria-labelledby を渡す