fandhe-frontend-headless-ui API

1. 目的とトレーサビリティ

本ドキュメントは fandhe-frontend-headless-ui（ark-ui / chakra-ui 参考の 2 層 UI コンポーネント構成）が提供する headless（unstyled）UI コンポーネント層の公開 API 表面をまとめる。上層の fandhe-frontend-pre-styled-ui（chakra-ui 相当）は本層の anatomy・data-*・WAI-ARIA 出力を前提にスタイルを重ねる。

docs/api/component-api.md との整合: 本クレートのコンポーネントはすべて「fandhe_frontend_core::Node を返す通常の Rust 関数」（REQ-5 の凍結 API 前提）として実装され、fandhe_frontend_core::render の既定エスケープ（REQ-1）を必ず経由する。raw_html() は使用しない。

2. 位置づけ

• headless-ui は anatomy・data-*・WAI-ARIA を出力する下層、pre-styled-ui は本層の出力を前提にスタイルを重ねる上層という 2 層構成である。
• 外部依存は fandhe-frontend-core / fandhe-frontend-interactive（いずれも crates.io バージョン依存）のみ

3. 共通基盤 API

これらは Dialog / Accordion / Tabs / Collapsible / Popover / Tooltip が共通で使う「open/closed・selected」の dispatch 契約・data-state 整合・SSR/hydration 契約を一度だけ実装したものであり、各コンポーネントはフィールドとして埋め込んで再利用する。

4. コンポーネント一覧

4z. combobox / listbox の ARIA 関連付けは呼び出し側責務

combobox::input/combobox::trigger の controls/activedescendant（aria-controls/aria-activedescendant）、listbox::content の labelledby（aria-labelledby）はいずれも Option の opt-in 引数であり、本クレートは値を強制しない（構造・アクセシビリティの anatomy は提供するが、呼び出し側が渡す値の正しさまでは型で保証しない）。

• combobox: popup（content）を描画するインスタンスは controls に content の id を渡すこと。ハイライト中の候補（item の highlighted 引数）が存在する構成では activedescendant にその候補の id を渡すこと（ARIA 1.2 combobox パターン、フォーカスを保持する input 側に配線する。content 側ではない）。
• listbox: content のアクセシブルネームは labelledby（対応する label の id）または呼び出し側 attrs 経由の aria-label のいずれかで必ず与えること。

リポジトリ内呼び出し（docs-site の Primitives/Themes 全ページ）はこの規約に準拠しており、crates/headless-ui/tests/combobox.rs・crates/headless-ui/tests/listbox.rs・crates/docs-site/tests/combobox_aria_association.rs が契約テストとして固定・回帰防止している。監査結果・型必須化を採らなかった判断根拠・再評価トリガーは ../internal/headless-ui-implementation-notes.md §S を参照。

4a0. 色変換コア（color）

color モジュールは anatomy を持たない純粋関数モジュールであり、上表の UI コンポーネント群とは性質が異なる（ブラウザ API 依存なし・wasm 境界隔離の対象外）。RGB / HSL / HSV / HEX の相互変換を、外部依存ゼロ・整数演算のみで提供する。fandhe-frontend-pre-styled-ui::color_swatch（ColorSwatch）と color_picker（ColorPicker）が本モジュールの型・変換関数を土台にする。

• 型: Rgb { r, g, b }（全フィールド公開、u8 全域が有効値）/ Hsl・Hsv（h: u16（0..=359）・s/l/v: u8（0..=100）、フィールド非公開・new() の fallible コンストラクタのみ公開）/ Color（RGBA canonical 表現、from_rgb/from_rgba/parse_hex/to_hex_string）/ ColorError（OutOfRange/InvalidHex、Display は静的文言のみ）。
• 変換関数: Rgb::to_hsl/Rgb::to_hsv（順方向）・Hsl::to_rgb/ Hsv::to_rgb（逆方向）。すべて f32/f64 を使わず i64 スケール整数演算で完結する。
• 丸め規則: 正の有理数の丸めは round half up（(2*num + den) / (2*den)）で固定する。無彩色（max == min）は s = 0, h = 0 と定義する。詳細は crates/headless-ui/src/color.rs モジュール doc 冒頭「丸め規則」参照。
• fail-closed 契約: Color::parse_hex は #rgb/#rgba/#rrggbb/ #rrggbbaa の 4 形式以外をすべて Err(ColorError::InvalidHex) にする（黙って補正しない）。Hsl::new/Hsv::new は範囲外を構築不能にする。Color::to_hex_string() の出力字母は常に # + 小文字 16 進数字に閉じる（ColorSwatch が CSS カスタムプロパティ値としてそのまま使う契約の根拠）。

4a. 位置決め（anchor positioning）

Popover/Tooltip/Menu/Select の positioner/arrow/arrow_tip は Floating UI 相当の placement 計算を実装済みである（正の規範文書は docs/design/anchor-positioning-design.md。以下 ADR）。

4a.1 対象コンポーネントと anatomy

Combobox の positioner は SSR 静的マークアップ（開閉状態の data-state/ hidden）のみ実装済みであり、crates/wasm-full/src/position.rs の PositionedKind への Combobox バリアント追加（実 DOM 計測・OPEN_POSITIONER_SELECTOR への組み込み）は後続イシューのスコープである（select/menu/popover/tooltip と同型の position 連携完了は未了）。HoverCard も同様に、positioner/arrow/arrow_tip anatomy とパーツ関数の attrs 透過は実装済みだが、PositionedKind::from_scope への "hover-card" 追加（実 DOM 計測対象化）は後続イシューのスコープである。

再計算対象の走査は開いている positioner のみに限定するセレクタ [data-part="positioner"][data-state="open"]（crates/wasm-full/src/position.rs の OPEN_POSITIONER_SELECTOR）を使う。

4a.2 placement API（positioning モジュール、クレートルート再エクスポート）

crates/headless-ui/src/positioning.rs が外部依存ゼロの純粋関数として提供し、クレートルート（lib.rs）から次の型・関数を再エクスポートする: compute_position / css_vars_style / data_align / data_side / placement_attrs / Align / ArrowPosition / Placement / PositioningConfig / Rect / ResolvedPosition / Side / Size。CSS 変数名定数は positioning::css_vars（X/Y/REFERENCE_WIDTH/ ARROW_X/ARROW_Y）としてクレートルートとは別に公開される。

• [Placement] は Side（top/bottom/left/right）× Align（start/center/end）の組み合わせで、12 placement 語彙（top/top-start/top-end/bottom/bottom-start/bottom-end/ left/left-start/left-end/right/right-start/right-end）を型として一元化する。as_str()/from_str() は相互に逆写像であり、from_str() は未知の値に対し None を返す（fail-closed）。
• data-* 契約:
  • data-side（top/bottom/left/right）・data-align（start/center/end）は flip 適用後の確定値の出力専用であり、再計算のたびに上書きされる CSS セレクタ用の属性である。
  • 希望 placement（flip 適用前）は別の永続化領域である data-requested-side/data-requested-align 属性に保持する（wasm 層の reposition_one が初回のみ書き込む。data-side/ data-align を希望値の保持先に流用すると flip 後に希望値が失われるため分離した、詳細は ADR §4.4a）。
  • SSR/SSG では位置計算そのものをスキップし、[placement_attrs] による data-side/data-align の静的出力と pre-styled-ui 側の静的 CSS フォールバックで初期表示を描画する。

4a.3 位置計算 API（純粋関数・外部依存ゼロ・web-sys 非依存）

入力型:

• [Rect]（x/y/width/height）: anchor（参照要素）の矩形。
• [Size]（width/height）: floating 要素・viewport の寸法。
• [PositioningConfig]（placement/offset/flip/shift/same_width）: Default は bottom-center・offset: 0.0・flip/shift 有効・same_width: false。

compute_position(anchor: Rect, floating: Size, viewport: Size, config: &PositioningConfig, has_arrow: bool) -> ResolvedPosition:

1. config.placement で主軸・交差軸座標を計算する。
2. flip（主軸の単純反転 1 候補のみ）が有効かつ主軸方向で viewport をはみ出す場合、反転後の座標で置き換える（反転後も収まらない場合は反転後の座標をそのまま採用する）。
3. shift（交差軸方向の viewport 内クランプ）を適用する。
4. has_arrow が true のときのみ arrow 座標（[ArrowPosition]、floating 要素左上原点の相対座標）を計算する（Select は arrow を持たないため呼び出し側が false を渡す）。

異常入力（NaN/Infinity・負の幅高さ・viewport 寸法 0 等）は fail-closed: panic!/unwrap() を使わず、config.placement のまま座標 (0.0, 0.0)・arrow: None を返す。

出力型 [ResolvedPosition]（x/y/確定 placement/Option<ArrowPosition>）。

4a.4 CSS 変数契約（--fandhe-*）

css_vars_style(position: &ResolvedPosition, reference_width: f64, same_width: bool) -> String:

• same_width == false のときは --fandhe-reference-width 自体を出力しない（PositioningConfig::same_width をそのまま渡す契約。コンポーネント種別ごとの sameWidth 既定値が実行時挙動に反映される）。
• position.arrow が Some のときのみ arrow 2 変数を出力する。
• 出力は内部生成の数値書式（px）のみからなり、非有限値は最終防御線として 0.0 へ丸める。
• 戻り値は ("style", &value) として既存の attrs: Vec<(&'a str, &'a str)> 引数へ渡し、[fandhe_frontend_core::render] の既定エスケープ経由で出力する契約とする（§6 不変条件 7 と同一）。

コンポーネント別の sameWidth 既定（fandhe-frontend-wasm-full の PositionedKind::same_width_default）: Menu/Select/Menubar は true、Popover/Tooltip/NavigationMenu は false（Menubar/NavigationMenu はイシュー #1182 で追加、判断根拠は docs/design/wasm-full-architecture.md §23.1）。

4a.5 計測注入・再計算（fandhe-frontend-wasm-full の position モジュール）

headless-ui は web-sys 非依存のまま維持し、実 DOM 計測（getBoundingClientRect・viewport 寸法）とスクロール/リサイズ契機の再計算は fandhe-frontend-wasm-full（position モジュール）が担う。再計算はスクロール・リサイズイベントを契機とした離散的な呼び出しであり、autoUpdate 相当の連続監視は非採用。

• 純粋ロジック層（native cargo test 可）: PositionedKind（from_scope: 未知の data-scope 値は None の fail-closed / has_arrow: Popover/Tooltip/Menu のみ true（許可リスト形式。Select/ Menubar/NavigationMenu は false） / same_width_default: 上記表）・parse_side_attr/parse_align_attr（属性欠落・未知値は bottom/center へ fail-closed）・resolve_requested_placement・Measurement・resolve_position(kind, measurement, requested) -> RepositionResult（flip/shift 常時有効・offset 0.0 固定）。
• 配線層（#[cfg(target_arch = "wasm32")]）: reposition_all（document 全体の開いている positioner を OPEN_POSITIONER_SELECTOR で走査）・reposition_within（root 自身とその子孫に走査を限定する版、イシュー #2209）・PositionController（scroll/resize リスナー）。fandhe-frontend-wasm-full の headless::wire_headless_component（標準の headless 配線 API）は配線時・dispatch 成功後の 2 箇所で reposition_within を自動的に呼び、配線時に一度だけ ensure_global_controller で thread_local 単一の PositionController を遅延生成する（イシュー #2209、親 #2208。詳細は docs/design/wasm-full-architecture.md §34）。利用者が PositionController を明示的に組み立てなくても popover/tooltip/menu の positioner へ実座標が書き込まれる。
• DOM 属性値（data-side/data-requested-side 等）は改ざんされうるクライアント入力として扱い、fail-closed でパースする。

4a.7 data-positioned マーカー契約（ADR §4.4b）

fandhe-frontend-wasm-full の position::wiring::reposition_one は座標反映のたびに positioner へ data-positioned=""（値なしの存在マーカー）を書き込む。headless-ui 層（本モジュール）は SSR/SSG のいずれの出力経路でもこの属性を一切出力しない（[placement_attrs] は data-side/ data-align の 2 属性のみを返す）。fandhe-frontend-pre-styled-ui（crates/pre-styled-ui/src/menu.rs/select.rs の recipe()。イシュー #2210 で popover.rs/tooltip.rs の positioner にも同型の state 規則を追加した）はこの非対称性を利用し、マーカーの有無で「SSR 静的フォールバック（position: absolute + ローカル座標系）」と「wasm 確定座標（position: fixed + viewport 座標系、--fandhe-x/--fandhe-y を transform: translate3d で消費）」を切り替える。マーカー不在（wasm 未稼働）では常に静的表示へ fail-closed に留まる。arrow（Popover/Tooltip/ Menu のみ、has_arrow() が Select を対象外とする、§4a.2）は --fandhe-arrow-x/--fandhe-arrow-y を変数フォールバックのみで消費し、マーカー切り替えを必要としない（イシュー #2210 で popover.rs/ tooltip.rs も arrow/arrow-tip を消費するようになったため、この一文は 3 部品共通の契約として読み替える）。

4c. 暦計算コア（date モジュール）

date-time 系コンポーネント（Calendar / DatePicker / DateInput / Timer）の先行前提として、fandhe_frontend_headless_ui::date モジュールを実装した。他コンポーネントと異なり anatomy パーツ・状態機械を持たない、非描画の純計算モジュールである。

4c.1 公開 API 一覧

4c.2 決定性・現在時刻非取得の契約

• 現在時刻を一切取得しない: SystemTime・Instant・js_sys 等の時刻取得 API を呼ばない。「今日」は常に呼び出し側（Calendar 等の上位コンポーネント）が PlainDate として明示的に渡す設計であり、同一入力から常に同一出力を返す。この不変条件は crates/headless-ui/tests/date.rs::date_module_never_reads_the_current_time（include_str! によるソース走査、コメント行を除く実コード行のみ検査）が恒久的に機械強制する。
• 外部依存ゼロ（REQ-3）: core/標準ライブラリのみで完結し、crates/headless-ui/Cargo.toml に依存を追加しない。
• fail-closed: 不正な年月日・不正な文字列・範囲逸脱・オーバーフローはすべて Err(DateError) を返し、panic!/unwrap()/expect() を使わない（ライブラリコードでの unwrap/panic 回避方針、.claude/rules/coding-rust.md）。
• HTML を一切組み立てない: 本モジュールは非描画の純計算モジュールであり raw_html()・HTML 文字列組み立てを持たない。to_iso_string() の出力（ASCII 数字とハイフンのみ）を後続コンポーネントが描画する際は、fandhe-frontend-core の既定エスケープ（REQ-1）を必ず経由する契約とする。
• 内部アルゴリズム: 年月日 ⇔ エポック日数（1970-01-01 を 0 とする）の変換に Howard Hinnant の days_from_civil/civil_from_days として知られる純整数アルゴリズムを使う。曜日・加減算・日付差・月グリッドの全 API をこの単一の変換対に載せることで、往復変換の性質テストだけで土台の正しさを固定できる。

4d. Calendar / DatePicker

date-time 系コンポーネントのうち、暦計算コア（§4c）を利用する Calendar / DatePicker を実装した。

4d.1 Calendar（calendar モジュール）

4d.2 DatePicker（date_picker モジュール）

4e. Format ユーティリティ（format モジュール）

ark-ui format-byte/format-number/format-time/format-relative-time・chakra-ui i18n/format-byte/format-number 相当の機能を、JS の Intl API・LocaleProvider 等の JS ランタイム機構に依存せず実装した。他コンポーネントと異なりノードを返さず anatomy/状態機械を持たない String 純関数群である。

4e.1a Locale

Locale は #[non_exhaustive] enum で En（既定）・Ja の 2 種を持つ。format_byte/format_number/format_relative_time の各オプションに locale: Locale フィールドとして含み、呼び出し側が明示的に渡す値型のみで完結する。ark-ui utilities/locale.md・chakra-ui i18n/locale-provider.md の React LocaleProvider（Context/Provider）に相当する機構は意図的に非採用であり、グローバル既定ロケール・スレッドローカル・環境変数参照を一切持たない（ambient authority を作らない設計、docs/policy/intentional-non-adoption.md §3.23 参照）。

• Locale::tag(&self) -> &'static str: BCP 47 言語タグ（"en"/"ja"）を返す
• Locale::from_tag(tag: &str) -> Option<Locale>: タグ文字列から Locale を決定的に逆引きする。ASCII 小文字化 + -/_ 前の primary subtag 完全一致のみに対応し（"en-US" → Locale::En 等）、未知タグは None（Accept-Language ヘッダ解析等のロケールネゴシエーションは呼び出し側の責務）

ja の出力例（unit_display: UnitDisplay::Long）:

format_byte(1000.0, ja, Long)            -> "1 キロバイト"
format_byte(1024.0*1024.0, ja, Binary, Long) -> "1 メビバイト"
format_relative_time(base - 3*86400, base, ja, Long)  -> "3 日前"
format_relative_time(base + 3*86400, base, ja, Long)  -> "3 日後"
format_relative_time(base, base, ja, _)               -> "たった今"

short/narrow の単位記号（kB/k 等）は SI 表記が国際共通のため en と同一値。相対時刻の narrow 形式は数字と単位語彙の間にスペースを挟まない（例: "3時間前"）が、long/short 形式は半角スペースを挟む（例: "3 日前"。CLDR ja の実挙動に整合、Rust 実装の定数表 + テスト網羅表を正とする）。

4e.1 決定性・丸め規則の契約

• 現在時刻 API に依存しない: format_relative_time の基準時刻 base は必ず呼び出し側が明示的に渡す。std::time::SystemTime::now() 等を本モジュールが呼ぶことはない（crate::timer/crate::date と同型の「時刻を渡される」設計）。
• 丸め規則: format_byte/format_number の固定小数点丸めは format!("{:.prec$}")（Rust 標準の 2 進表現に基づく最近接丸め）を正とする（rustdoc に明記）。
• 非有限値・境界値: NaN/±∞ は panic せず "NaN"/"∞"/"-∞" を返す。i64::MIN/i64::MAX を含む全入力域で unwrap()/panic! を使わず unsigned_abs()/checked_sub() で決定的な出力を返す（A04 対策）。

5. 呼び出し規約（SSR / CSR 共通の前提）

• 各コンポーネントの anatomy パーツ（root/trigger/content 等）は状態を引数で受け取る純粋関数として実装されており、SSR は自由関数を直接呼ぶだけで静的マークアップを組み立てられる（状態機械（Accordion/ Dialog/Switch 等の型）を経由する必要はない）。
• CSR/hydration は各コンポーネントの状態機械型（Accordion/Dialog 等）を経由し、fandhe_frontend_interactive::Component/Hydrate の dispatch で状態遷移する。クリック/キーボード操作の実挙動は wasm 層（fandhe-frontend-wasm-client/-wasm-full）の責務であり、本クレートのスコープ外。
• examples/headless-pre-styled-ui は自由関数のみを使う SSR 静的ショーケースの実例。

6. セキュリティ不変条件

1. 属性名（data-*/aria-*/type/role/hidden/disabled/id 等）はすべて &'static str リテラルで固定されており、動的値が属性名スロットへ混入する経路はない。
2. 動的値（value/id/controls/labelled_by/呼び出し側 attrs/ children テキスト）は fandhe_frontend_core::render の既定エスケープ（REQ-1）を必ず経由する。本クレート内で raw_html() は使用しない。
3. data-state 値語彙（"open"/"closed"/"checked"/"unchecked" 等）は各状態モジュール（state/switch/avatar 等）に一元化し、パーツ関数側で独自の値を作らない。
4. hydration 属性（data-hydrate-*）はクライアント側で改ざんされうる入力として扱う。各状態機械の Hydrate 実装は既存の状態機械（Disclosure/SingleSelect）へ委譲することで、panic せず HydrateError を返す保証を継承する。
5. #![forbid(unsafe_code)]（REQ-2）。unsafe はクレート全体で使用しない。
6. 外部依存は fandhe-frontend-core / fandhe-frontend-interactive（いずれも path）のみ（.claude/rules/coding-rust.md）。加えて本クレートは fandhe_frontend_core・fandhe_frontend_interactive の両方をクレートそのものとして再エクスポートし、本クレート単独依存の利用者が Component/Hydrate/dispatch/HydrateError/render_for_hydration を含む hydration API まで到達できるようにしている（docs/api/ pre-styled-ui-api.md §3b・crates/headless-ui/tests/ interactive_reexport.rs 参照）。
7. positioning::css_vars_style(position, reference_width, same_width) が返す style 属性値は内部生成の数値書式（px）のみからなり、呼び出し側は必ず既存の attrs 引数 → 上記 2 の既定エスケープを経由して出力する（same_width == false のとき --fandhe-reference-width は出力しない、docs/design/anchor-positioning-design.md §7）。
8. password_input はパスワード値そのものを一切扱わない。input/PasswordInput は value を出力・保持する API を持たず、状態機械は表示切替の bool（visible）のみをフィールドに持つ。パスワード値が Debug/Hydrate の出力・エラーメッセージ・ログのいずれにも現れる余地がない設計であり、crates/headless-ui/src/password_input.rs の inline test input_never_outputs_value_attribute が回帰を固定する。イシュー #1614（ark-ui/zag/Radix 参照突合）で PasswordInputProps.readonly（input にネイティブ readonly + 6 パーツ全てに data-readonly。visibility_trigger へはネイティブ disabled を合成しない）を追加し、input に data-state・autocapitalize="off"・spellcheck="false" を固定付与した。aria-pressed（zag の aria-expanded に非追随）・tabindex 非付与（tab 順序に残す）は意図的な差分として維持する。
9. イシュー #1615（ark-ui 公式 Data Attributes / Keyboard Support 表・Radix one-time-password-field 参照突合）で pin_input へ PinInputProps（disabled/readonly/invalid/required）を新設し、root/label/input の data-invalid/data-readonly（label にのみ追加で data-required）・input の aria-invalid/ネイティブ readonly・data-index（0-origin 桁インデックス）/data-filled（値が非空のときのみ）を追加した。PinInputAction::Backspace は「現在桁を消去し前の桁へ移動」へ是正し（旧実装は「消去して留まる」で ark-ui の Delete と区別が付かなかった）、PinInputAction::Delete（現在桁のみ消去、フォーカス移動なし）・PinInputAction::Prev/PinInputAction::Next（ArrowLeft/ ArrowRight）を新設した（dispatch 語彙: "delete"/"prev"/"next"）。
10. format モジュールはテキスト値を返す純関数であり、出力は呼び出し側が必ず fandhe_frontend_core::text() ノード → 上記 2 の既定エスケープを経由してから描画する（本モジュール自体は HTML を組み立てない）。std::time::SystemTime::now() 等の現在時刻 API・環境変数・グローバル状態を一切参照しない決定的純関数であり、base/target 等の時刻は必ず呼び出し側が明示的に渡す（§4e.1 参照）。
11. イシュー #1617（ark-ui Rating Group 参照突合）で rating_group へ RatingGroupProps（disabled/readonly/required）を新設し、root/ label/control/hidden_input のシグネチャを &RatingGroupProps 受けへ統一した。label の data-disabled/data-required、control の data-disabled/data-readonly/aria-required + 真のときのみの aria-disabled="true"/aria-readonly="true"/aria-required="true" を追加した。当初案は RatingItemFlags::focusable により item へ roving tabindex を追加していたが、対応する DOM 配線（fandhe-frontend-wasm-full）が無いまま「フォーカスは受けるが Arrow/Space/Enter のいずれも操作不能」な状態で公開してしまう codex-review 指摘を受け、本イシュー内で撤回した（item は tabindex を一切出力しない）。data-half（allow_half）・aria-setsize/aria-posinset・aria-roledescription・aria-orientation は意図的に非採用のまま維持する（crates/headless-ui/src/rating_group.rs モジュール doc「参考サイト突合」節参照）。

7. 関連ドキュメント

• docs/api/component-api.md: Node/el/text/ raw_html/render の凍結 API 表面（本クレートが薄く委譲する下層）
• docs/api/pre-styled-ui-api.md: 本クレートの上層（chakra-ui 相当）
• examples/headless-pre-styled-ui/README.md: 本クレートのショーケース正本サンプル
• docs/design/anchor-positioning-design.md: anchor positioning の設計確定書（正の規範文書。docs サイト nav.toml 未登録の内部設計文書のためリンク化しない）
• docs/policy/intentional-non-adoption.md §3.20/§3.21: anchor positioning 関連（Floating UI 高度 middleware・CSS Anchor Positioning）の非採用判断の正（同様に nav.toml 未登録のためリンク化しない）
• .claude/skills/ark-ui/: 設計時の参考にした ark-ui リファレンススキル
• docs/internal/headless-ui-implementation-notes.md: 実装経緯・ロードマップ・トレーサビリティの記録（docs サイト非掲載のためリンク化しない）