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（開いている positioner を OPEN_POSITIONER_SELECTOR で走査）・PositionController （scroll/resize リスナー）。
• 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()）はこの 非対称性を利用し、マーカーの有無で「SSR 静的フォールバック（position: absolute + ローカル座標系）」と「wasm 確定座標（position: fixed + viewport 座標系、--fandhe-x/--fandhe-y を transform: translate3d で消費）」を切り替える。マーカー不在（wasm 未稼働）では常に静的表示へ fail-closed に留まる。arrow（Menu のみ、has_arrow() が Select を対象外 とする、§4a.2）は --fandhe-arrow-x/--fandhe-arrow-y を変数フォール バックのみで消費し、マーカー切り替えを必要としない。

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 が回帰を固定する。
9. format モジュールはテキスト値を返す純関数であり、出力は呼び出し側が 必ず fandhe_frontend_core::text() ノード → 上記 2 の既定エスケープを 経由してから描画する（本モジュール自体は HTML を組み立てない）。 std::time::SystemTime::now() 等の現在時刻 API・環境変数・グローバル 状態を一切参照しない決定的純関数であり、base/target 等の時刻は 必ず呼び出し側が明示的に渡す（§4e.1 参照）。

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 サイト非掲載のためリンク化しない）