# 機能設計書 22-Expander

## 概要

本ドキュメントは、AvaloniaフレームワークにおけるExpanderコントロールの機能設計を記載する。Expanderは、ヘッダーをクリックすることでコンテンツ領域を展開・折りたたみできるUIコントロールである。

### 本機能の処理概要

Expanderは、ヘッダーと折りたたみ可能なコンテンツ領域を持つUIコントロールである。ユーザーがヘッダーをクリックすると、コンテンツ領域が展開または折りたたまれる。展開方向は上下左右の4方向を指定でき、アニメーション付きのトランジションをサポートする。

**業務上の目的・背景**：
限られた画面スペースを効率的に活用するために、詳細情報を必要に応じて表示/非表示にする機能が必要である。設定画面やダッシュボードなど、情報量が多いUIで特に有用であり、ユーザーが必要な情報にフォーカスできるようにする。

**機能の利用シーン**：
- 設定画面での詳細オプションの表示/非表示
- FAQページでの質問と回答の表示
- サイドパネルでのカテゴリごとのコンテンツ折りたたみ
- アコーディオン形式のナビゲーション
- プロパティインスペクタでのグループ化された設定項目

**主要な処理内容**：
1. ヘッダークリックによる展開/折りたたみ切り替え
2. 展開方向（上/下/左/右）の制御
3. コンテンツトランジションアニメーションの実行
4. 展開/折りたたみイベントの発行（Expanding/Expanded/Collapsing/Collapsed）
5. イベントのキャンセル機能による展開/折りたたみの抑止
6. 擬似クラスによるスタイル制御（:expanded, :up, :down, :left, :right）

**関連システム・外部連携**：
- IPageTransitionインターフェースによるカスタムトランジション
- オートメーションピア（ExpanderAutomationPeer）によるアクセシビリティ対応

**権限による制御**：
本コントロールには権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 31 | Expander | 主画面 | Expanderコントロールのデモ。折りたたみ可能なコンテンツ |
| 87 | Expanders | 主画面 | Expanderを使用した仮想化デモ。展開・収縮と仮想化 |

## 機能種別

UI操作 / コンテナコントロール / 表示切り替え

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Header | object | No | ヘッダーに表示するコンテンツ | - |
| Content | object | No | 折りたたみ可能なコンテンツ | - |
| IsExpanded | bool | No | 展開状態 | デフォルト: false |
| ExpandDirection | ExpandDirection | No | 展開方向 | Down/Up/Left/Right、デフォルト: Down |
| ContentTransition | IPageTransition | No | 展開/折りたたみ時のトランジション | - |

### 入力データソース

- ユーザーによるヘッダークリック操作
- プログラムによるIsExpanded設定
- データバインディングによるIsExpanded制御

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| IsExpanded | bool | 現在の展開状態 |
| ExpandDirection | ExpandDirection | 現在の展開方向 |

### 出力先

- UI表示（コンテンツの展開/折りたたみ状態）
- Expanding/Expanded/Collapsing/Collapsedイベントの発行

## 処理フロー

### 処理シーケンス

```
1. ヘッダークリック検出
   └─ ToggleButtonのChecked/Uncheckedイベント発生
2. IsExpandedプロパティ変更開始
   └─ CoerceIsExpandedによる値検証
3. Expanding/Collapsingイベント発行
   └─ イベントハンドラでCancel=trueの場合は処理中断
4. プロパティ変更確定
   └─ OnPropertyChangedでStartContentTransition呼び出し
5. トランジション実行
   └─ ContentTransitionがある場合はアニメーション実行
6. 擬似クラス更新
   └─ :expanded/:up/:down/:left/:right の設定
7. Expanded/Collapsedイベント発行
   └─ Dispatcher.UIThread.Postで非同期発行
```

### フローチャート

```mermaid
flowchart TD
    A[ヘッダークリック] --> B{IsExpanded変更}
    B -->|true→false| C[OnCollapsing発行]
    B -->|false→true| D[OnExpanding発行]
    C --> E{Cancel?}
    D --> E
    E -->|Yes| F[変更をリバート]
    E -->|No| G[StartContentTransition]
    G --> H{ContentTransitionあり?}
    H -->|Yes| I[トランジション実行]
    H -->|No| J[即座に状態更新]
    I --> K[UpdatePseudoClasses]
    J --> K
    K --> L{IsExpanded?}
    L -->|true| M[OnExpandedイベント]
    L -->|false| N[OnCollapsedイベント]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 展開キャンセル | Expandingイベントでcancel=trueを設定すると展開を中止 | IsExpanded変更時 |
| BR-002 | 折りたたみキャンセル | Collapsingイベントでcancel=trueを設定すると折りたたみを中止 | IsExpanded変更時 |
| BR-003 | 双方向バインディング | IsExpandedはデフォルトでTwoWayバインディング | 常時適用 |
| BR-004 | トランジション方向 | ExpandDirection=Left/Upの場合、トランジションは逆方向 | トランジション実行時 |

### 計算ロジック

トランジション方向の決定：
```
forward = (ExpandDirection == Left) || (ExpandDirection == Up)
展開時: ContentTransition.Start(null, visualContent, forward)
折りたたみ時: ContentTransition.Start(visualContent, null, !forward)
```

## データベース操作仕様

本コントロールはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | トランジションキャンセル | 連続した展開/折りたたみ操作 | CancellationTokenSourceで前のトランジションをキャンセル |

### リトライ仕様

該当なし

## トランザクション仕様

該当なし

## パフォーマンス要件

- トランジションアニメーションは滑らかに実行される必要がある
- 連続した操作でも適切にキャンセル処理を行う

## セキュリティ考慮事項

本コントロールにはセキュリティ上の特別な考慮事項はない。

## 備考

- 複数のExpanderを組み合わせてアコーディオン形式のUIを実現可能
- ExpanderAutomationPeerによりスクリーンリーダー等でアクセス可能

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

展開方向の列挙型と基底クラスを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Expander.cs | `src/Avalonia.Controls/Expander.cs` | ExpandDirection列挙型（17-38行目） |
| 1-2 | HeaderedContentControl.cs | `src/Avalonia.Controls/Primitives/HeaderedContentControl.cs` | 基底クラスの構造 |

**読解のコツ**: Expanderは HeaderedContentControl を継承しており、Header と Content の両方を持つ構造になっている。

#### Step 2: エントリーポイントを理解する

Expanderクラスの主要プロパティとイベントを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Expander.cs | `src/Avalonia.Controls/Expander.cs` | プロパティ定義（46-100行目）、イベント定義 |

**主要処理フロー**:
1. **46-51行目**: ContentTransitionProperty定義
2. **54-59行目**: ExpandDirectionProperty定義（デフォルト: Down）
3. **62-68行目**: IsExpandedProperty定義（TwoWayバインディング、coerce関数付き）
4. **71-100行目**: Collapsed/Collapsing/Expanded/Expandingイベント定義

#### Step 3: 展開/折りたたみロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Expander.cs | `src/Avalonia.Controls/Expander.cs` | OnPropertyChanged、StartContentTransition |

**主要処理フロー**:
- **256-277行目**: OnPropertyChangedでIsExpanded/ExpandDirectionの変更を検出
- **221-254行目**: StartContentTransitionでトランジション実行とイベント発行
- **299-339行目**: OnCoerceIsExpandedでExpanding/Collapsingイベントを発行、キャンセル処理

#### Step 4: 擬似クラス更新を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Expander.cs | `src/Avalonia.Controls/Expander.cs` | UpdatePseudoClasses |

**主要処理フロー**:
- **287-297行目**: UpdatePseudoClassesで:up/:down/:left/:right/:expandedを設定

### プログラム呼び出し階層図

```
Expander
    │
    ├─ コンストラクタ
    │      └─ UpdatePseudoClasses（初期状態設定）
    │
    ├─ OnPropertyChanged
    │      ├─ ExpandDirectionProperty変更時
    │      │      └─ UpdatePseudoClasses
    │      │
    │      └─ IsExpandedProperty変更時
    │             ├─ StartContentTransition
    │             │      ├─ ContentTransition.Start（アニメーション）
    │             │      └─ Dispatcher.UIThread.Post
    │             │             ├─ OnExpanded
    │             │             └─ OnCollapsed
    │             └─ UpdatePseudoClasses
    │
    └─ CoerceIsExpanded（静的）
           └─ OnCoerceIsExpanded
                  ├─ OnExpanding（展開開始イベント）
                  └─ OnCollapsing（折りたたみ開始イベント）
```

### データフロー図

```
[入力]                    [処理]                         [出力]

ヘッダークリック ───────▶ IsExpanded変更
                              │
プログラム設定 ─────────▶ CoerceIsExpanded
                              │
データバインディング ───▶    ├─▶ Expanding/Collapsingイベント
                              │         │
                              │    Cancel判定
                              │         │
                              ▼         ▼
                      OnPropertyChanged ───▶ StartContentTransition
                              │                      │
                              │              トランジション実行
                              │                      │
                              ▼                      ▼
                      UpdatePseudoClasses     Expanded/Collapsedイベント
                              │
                              ▼
                         UI更新（:expanded等）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Expander.cs | `src/Avalonia.Controls/Expander.cs` | ソース | メインコントロールクラス |
| HeaderedContentControl.cs | `src/Avalonia.Controls/Primitives/HeaderedContentControl.cs` | ソース | 基底クラス |
| ExpanderAutomationPeer.cs | `src/Avalonia.Controls/Automation/Peers/ExpanderAutomationPeer.cs` | ソース | オートメーションピア |
| IPageTransition.cs | `src/Avalonia.Base/Animation/IPageTransition.cs` | ソース | トランジションインターフェース |
| CancelRoutedEventArgs.cs | `src/Avalonia.Base/Interactivity/CancelRoutedEventArgs.cs` | ソース | キャンセル可能イベント引数 |
| Expander.xaml | `src/Avalonia.Themes.Fluent/Controls/Expander.xaml` | テンプレート | Fluentテーマのテンプレート |
