Combobox

テキスト入力しながら候補一覧を絞り込む部品です。フォーカスを保持する input パーツ（role="combobox"）が aria-activedescendant の配線先を担い、role="listbox" の候補一覧とセットで動作します。候補データの取得・整形は利用者側の責務であり、本部品は anatomy と ARIA 配線のみを提供します。候補件数の変化は live_region パーツ（aria-live="polite" 固定）が支援技術へ通知します（テキスト更新の実配線は wasm-full の後続責務）。

ComboboxProps（disabled/readonly/invalid/required）を root/label/control/input/trigger/clear_trigger へ一律付与します。data-required は label のみに付与され、input は対応するネイティブ disabled/readonly/required 存在属性と、invalid 時のみ aria-invalid="true" を追加で持ちます。data-scope/data-part/data-state/data-disabled/data-invalid/data-highlighted 等の属性セレクタで自前 CSS を当てられます（詳細は Themes 版ページの Examples を参照）。

fandhe-frontend-headless-ui の combobox mod が提供する構造・アクセシビリティ（WAI-ARIA・キーボード操作）・表示状態（data-*）のみを持つ unstyled 部品です。Themes 版が備える見た目は持たず、anatomy・ARIA・data-* のみを提供します。CSS は利用者が当てます。

スタイル済みの表示例は Combobox を参照してください。

関連 API: fandhe-frontend-headless-ui API

Demo

枠線・余白は docs サイト側のデモ枠であり、fandhe-frontend-headless-ui 自体はスタイルを持ちません。

Fruit

1 result available

Fruit (disabled)

Fruit (invalid, required)

Fruit (readonly)

Features

root/label/control/input/trigger/clear_trigger/positioner/content/item_group/item_group_label/item/item_text/item_indicator/live_region の 14 anatomy パーツを持ち、フォーカスを保持する input（role="combobox"）側に aria-activedescendant を配線する（crate::select と異なる配線先、combobox.rs:59-65）。
ComboboxProps（disabled/readonly/invalid/required）を root/label/control/input/trigger/clear_trigger へ一律付与し、data-required は label にのみ、input は対応するネイティブ disabled/readonly/required 存在属性 + invalid 時のみ aria-invalid="true" を追加する（イシュー #1605 参照突合。ark-ui の data-focus/data-placement/data-empty、item/item-indicator の data-state="checked"/"unchecked" 語彙は crate::select/crate::listbox とのクレート横断整合を優先し意図的に追随しない）。
input は role="combobox" + aria-autocomplete="list" を固定付与し、controls/activedescendant が Some のときのみ aria-controls/aria-activedescendant を付与する（combobox.rs:152-205）。
trigger は type="button" + aria-haspopup="listbox" を固定付与する（combobox.rs:205-238）。
候補データの絞り込みは filter_options（純粋関数）が提供するが、候補データ自体の取得・供給は利用者側の責務である（combobox.rs:398、docs/policy/intentional-non-adoption.md §3.25）。
live_region は候補件数の変化を通知する live region（role="status" + aria-live="polite" 固定、root の直接の子で control の兄弟として配置する。テキスト更新の実配線は fandhe-frontend-wasm-full の後続責務、イシュー #1069）。

Anatomy

root
  label
  control
    input
    trigger
    clear-trigger
  positioner
    content
      item-group
        item-group-label
        item
          item-text
          item-indicator
  live-region

API Reference

Arguments

Name	Type	Default	Description
`root(state) / control(state) / input(state) / trigger(state) / content(state)`	`OpenState`	`OpenState::Closed`	開閉状態。data-state・aria-expanded の判定に使われる（同じ型のため代表 1 行に集約）。
`root(props) / label(props) / control(props) / input(props) / trigger(props) / clear_trigger(props)`	`&ComboboxProps`	`&ComboboxProps::default()`	disabled/readonly/invalid/required の状態束（代表 1 行に集約、イシュー #1605）。
`input(value, controls, activedescendant, name)`	`&str, Option<&str>, Option<&str>, Option<&str>`	—	現在の入力文字列・content の id・ハイライト中 item の id・関連フォームフィールド名（combobox.rs、イシュー #1605 で disabled: bool を props へ置換）。
`item(state, disabled, highlighted, value, id)`	`OpenState, bool, bool, &str, Option<&str>`	—	role="option" を持つ選択肢 1 個の選択状態・無効化・ハイライト中かどうか。value は data-value として既定エスケープ経由で出力される（combobox.rs:333-361）。
`live_region(children)`	`Vec<Node>`	—	role="status"/aria-live="polite"/aria-atomic="true" を固定付与する live region。通知文言は children として呼び出し側が渡す（combobox.rs、イシュー #1069）。
`attrs / children`	`Vec<(&str, &str)> / Vec<Node>`	—	各パーツ共通の追加属性・子ノード（代表 1 行に集約）。

Data Attributes

Part	Attribute	Observed Values
`clear-trigger`	`data-disabled`	（値なし）
`clear-trigger`	`data-readonly`	（値なし）
`content`	`data-state`	`open`
`control`	`data-disabled`	（値なし）
`control`	`data-invalid`	（値なし）
`control`	`data-readonly`	（値なし）
`control`	`data-state`	`closed`, `open`
`input`	`data-disabled`	（値なし）
`input`	`data-invalid`	（値なし）
`input`	`data-readonly`	（値なし）
`input`	`data-state`	`closed`, `open`
`item`	`data-highlighted`	（値なし）
`item`	`data-state`	`open`
`item`	`data-value`	`apple`
`item-indicator`	`data-state`	`open`
`label`	`data-disabled`	（値なし）
`label`	`data-invalid`	（値なし）
`label`	`data-readonly`	（値なし）
`label`	`data-required`	（値なし）
`positioner`	`data-state`	`open`
`root`	`data-disabled`	（値なし）
`root`	`data-invalid`	（値なし）
`root`	`data-readonly`	（値なし）
`root`	`data-state`	`closed`, `open`
`trigger`	`data-disabled`	（値なし）
`trigger`	`data-invalid`	（値なし）
`trigger`	`data-readonly`	（値なし）
`trigger`	`data-state`	`closed`, `open`

Examples

Closed input + trigger

aria-expanded="false"/aria-autocomplete="list" を持つ閉じた状態の例です。

閉じた状態（aria-expanded="false"）で aria-autocomplete="list" を持つ Combobox input/trigger の組み立て例です。

Language

利用者スタイルの当て方

data-scope / data-part / data-state / data-invalid / data-highlighted 属性セレクタで自前 CSS を当てる最小例です。

利用者が data-scope / data-part / data-state / data-invalid / data-highlighted 属性セレクタで自前 CSS を当てる最小例です（本 Demo には適用されません）。

CSS

[data-scope="combobox"][data-part="root"][data-disabled] {
  opacity: 0.5;
}
[data-scope="combobox"][data-part="input"][data-invalid] {
  border-color: red;
}
[data-scope="combobox"][data-part="item"][data-highlighted] {
  background: #eef;
}
[data-scope="combobox"][data-part="item"][data-state="open"] {
  font-weight: bold;
}
[data-scope="combobox"][data-part="positioner"][hidden] {
  display: none;
}

Accessibility

Keyboard Interactions

Key	Description
ArrowDown	closed: 先頭の非 disabled 候補を highlight して開く。open: 次の候補へ highlight を移動する（keynav.rs combobox_key_action）。
ArrowUp	closed: 末尾の非 disabled 候補を highlight して開く。open: 前の候補へ highlight を移動する（keynav.rs combobox_key_action）。
Home / End	closed: no-op（キャレット移動という input のネイティブ既定動作を奪わない）。open: 先頭/末尾の非 disabled 候補へ highlight を移動する。
Enter	closed: no-op（フォーム submit 等のネイティブ既定動作を奪わない）。open: highlight 中候補を確定選択する。
Escape	closed: no-op（fail-closed。claim すると誤って open してしまうため）。open: highlight をクリアして閉じる。
Tab / ArrowLeft / ArrowRight / printable 文字	claim しない（Tab はフォーカス移動、ArrowLeft/ArrowRight はキャレット移動、printable 文字はフィルタ入力というネイティブ input の既定動作をそのまま許容する）。

WAI-ARIA

Attribute	Description
role="combobox" / aria-autocomplete="list"	input パーツへ固定付与する（combobox.rs:177以降）。
aria-expanded	input・trigger の両方が開閉状態を反映する。
aria-activedescendant	input パーツ側へ配線する（crate::select と異なり本モジュールは input 側、combobox.rs:59-65, 156）。
aria-invalid="true"	input パーツが props.invalid のときのみ付与する（valid のときは属性自体を省略、イシュー #1605）。
role="listbox" / role="option"	content パーツは role="listbox"、item パーツは role="option" を固定付与する（combobox.rs:277, 343）。
role="status" / aria-live="polite" / aria-atomic="true" (live_region)	候補件数の変化を通知する live region に固定付与する（combobox.rs、イシュー #1069）。