# 機能設計書 35-WrapPanel

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるWrapPanel（折り返しレイアウトパネル）の機能設計を定義するものである。WrapPanelは子要素を順次配置し、コンテナの端に達したら次の行または列に折り返すレイアウトパネルを提供する。

### 本機能の処理概要

WrapPanelは、子要素を左から右（Horizontal）または上から下（Vertical）に順次配置し、コンテナの境界に達した時点で自動的に次の行または列に折り返すレイアウトパネルを提供する。フローレイアウトやタグクラウド、ギャラリービューなどに適している。

**業務上の目的・背景**：ウィンドウサイズの変化に応じて要素を自動的に折り返す「フローレイアウト」は、レスポンシブなUI設計において重要である。WrapPanelは、タグ一覧、ツールバーボタン、サムネイルギャラリーなど、動的な数の要素を柔軟に配置する必要があるシーンで活用される。

**機能の利用シーン**：
- タグクラウドやチップの表示
- フォトギャラリーのサムネイル配置
- ツールバーのボタン配置
- 商品一覧のタイル表示

**主要な処理内容**：
1. Orientationによる配置方向の決定（Horizontal/Vertical）
2. コンテナ幅/高さに基づく自動折り返し
3. ItemWidth/ItemHeightによる統一サイズ指定
4. ItemSpacing/LineSpacingによる間隔設定
5. ItemsAlignmentによる行内アライメント（Start/Center/End）

**関連システム・外部連携**：Panel基底クラスを継承し、INavigableContainerインターフェースを実装。

**権限による制御**：特になし。UIコンポーネントとしてアプリケーション側で必要に応じて実装。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | WrapPanelはフローレイアウトが必要な画面で使用される |

## 機能種別

レイアウト制御 / UIコンテナ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Orientation | Orientation | No | 配置方向（デフォルト: Horizontal） | Horizontal/Vertical |
| ItemWidth | double | No | 全アイテムの統一幅（デフォルト: NaN=個別サイズ） | NaNまたは正数 |
| ItemHeight | double | No | 全アイテムの統一高さ（デフォルト: NaN=個別サイズ） | NaNまたは正数 |
| ItemSpacing | double | No | アイテム間のスペース（デフォルト: 0） | 0以上 |
| LineSpacing | double | No | 行間のスペース（デフォルト: 0） | 0以上 |
| ItemsAlignment | WrapPanelItemsAlignment | No | 行内のアライメント（デフォルト: Start） | Start/Center/End |

### WrapPanelItemsAlignment列挙型

| 値 | 説明 |
|-----|------|
| Start | 各行/列の先頭（上/左）揃え |
| Center | 各行/列の中央揃え |
| End | 各行/列の末尾（下/右）揃え |

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DesiredSize | Size | 計測フェーズで計算された希望サイズ |
| 子要素の最終位置 | Rect | 配置フェーズで決定された各子要素の位置とサイズ |

## 処理フロー

### 処理シーケンス

```
1. MeasureOverrideフェーズ
   ├─ UV空間で計測（方向に依存しない処理）
   ├─ 各子要素を計測
   ├─ 行の累積サイズ計算
   ├─ 境界到達で改行判定
   └─ パネル全体サイズ計算
2. ArrangeOverrideフェーズ
   ├─ 各行の要素範囲特定
   ├─ ItemsAlignmentに応じた開始位置計算
   ├─ 各要素の配置
   └─ 行間スペース適用
```

### フローチャート

```mermaid
flowchart TD
    A[MeasureOverride開始] --> B[UV空間初期化]
    B --> C[子要素ループ]
    C --> D{行に収まる?}
    D -->|Yes| E[行サイズ累積]
    D -->|No| F[現行サイズをパネルに加算]
    F --> G[新しい行開始]
    E --> H{次の子?}
    G --> H
    H -->|Yes| C
    H -->|No| I[最終行をパネルに加算]
    I --> J[W/H空間に変換]
    J --> K[DesiredSize返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-35-01 | 折り返し判定 | 累積サイズ+次要素サイズ>制約サイズで折り返し | 境界到達時 |
| BR-35-02 | 統一サイズ | ItemWidth/ItemHeightがNaN以外の場合、全要素に適用 | 統一サイズ指定時 |
| BR-35-03 | 行アライメント | ItemsAlignmentに応じて行内の開始位置を調整 | Arrange時 |
| BR-35-04 | 非可視要素 | IsVisible=falseの子要素はスペース計算から除外 | 子要素が非可視時 |

### 計算ロジック

**UV空間の利用**:
- U軸: 配置方向（Horizontal時はWidth、Vertical時はHeight）
- V軸: 折り返し方向（Horizontal時はHeight、Vertical時はWidth）

**アライメント計算**:
```
StartOffset = ItemsAlignment switch {
    Center => (パネル幅 - 行の総幅) / 2,
    End => パネル幅 - 行の総幅,
    Start => 0
}
```

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

該当なし（UIコンポーネントのためDB操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ArgumentOutOfRangeException | パラメータエラー | 無効なItemsAlignment値 | 例外スロー |

## パフォーマンス要件

- 軽量なレイアウト計算（O(n)）
- UV空間変換による方向非依存の効率的な処理

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

特になし

## 備考

- WPFのWrapPanelからの移植実装
- ItemsAlignment/ItemSpacing/LineSpacingはAvalonia拡張機能

---

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

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

### 推奨読解順序

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

UV空間の概念とアライメント列挙型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WrapPanel.cs | `src/Avalonia.Controls/WrapPanel.cs` | WrapPanelItemsAlignment列挙型（15-31行目） |
| 1-2 | WrapPanel.cs | `src/Avalonia.Controls/WrapPanel.cs` | UVSize構造体（343-373行目） |

**読解のコツ**: UVSize構造体は方向に依存しないレイアウト計算を可能にする。U軸が配置方向、V軸が折り返し方向。

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

WrapPanelクラスの基本構造とプロパティを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | WrapPanel.cs | `src/Avalonia.Controls/WrapPanel.cs` | メインクラス |

**主要処理フロー**:
- **39行目**: `WrapPanel`クラス定義。`Panel`, `INavigableContainer`を実装
- **44-75行目**: プロパティ定義（ItemSpacing/LineSpacing/Orientation/ItemsAlignment/ItemWidth/ItemHeight）
- **80-84行目**: 静的コンストラクタ - AffectsMeasure/AffectsArrange登録

#### Step 3: MeasureOverride - 計測処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WrapPanel.cs | `src/Avalonia.Controls/WrapPanel.cs` | MeasureOverrideメソッド（193-249行目） |

**主要処理フロー**:
- **201-203行目**: UV空間での変数初期化
- **213-241行目**: 子要素ループ
- **225行目**: 折り返し判定（MathUtilities.GreaterThan）
- **226-233行目**: 折り返し処理 - パネルサイズ更新、新行開始
- **234-240行目**: 行内累積処理
- **244-245行目**: 最終行のサイズ加算
- **248行目**: W/H空間への変換返却

#### Step 4: ArrangeOverride - 配置処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | WrapPanel.cs | `src/Avalonia.Controls/WrapPanel.cs` | ArrangeOverrideメソッド（252-341行目） |

**主要処理フロー**:
- **271-298行目**: 子要素ループ - 折り返し判定
- **281-289行目**: 折り返し時のArrangeLine呼び出し
- **300-305行目**: 最終行の配置
- **309-340行目**: ArrangeLineローカル関数
- **313-328行目**: ItemsAlignmentによる開始位置計算
- **330-335行目**: 各要素の配置

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

```
WrapPanel (レイアウトパネル)
    │
    ├─ MeasureOverride()
    │      ├─ UVSize変換
    │      ├─ 子要素ループ
    │      │      ├─ child.Measure()
    │      │      ├─ 折り返し判定
    │      │      └─ 行サイズ累積
    │      └─ W/H空間変換
    │
    ├─ ArrangeOverride()
    │      ├─ 子要素ループ
    │      │      ├─ 折り返し判定
    │      │      └─ ArrangeLine()
    │      │             ├─ ItemsAlignment計算
    │      │             └─ child.Arrange()
    │      └─ 最終行ArrangeLine()
    │
    └─ INavigableContainer.GetControl()
           └─ インデックス計算
```

### データフロー図

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

Orientation ─────────────▶ UVSize変換
                              │
ItemWidth/Height ────────▶ childConstraint作成
                              │
子要素コレクション ────────▶ 子要素ループ
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
         行内累積計算       折り返し判定
                    │         (U方向オーバー時)
                    │                   │
                    └─────────┬─────────┘
                              ▼
                     パネルサイズ計算
                              │
                              ▼
                     W/H空間変換
                              │
                              ▼
                     ArrangeOverride()
                              │
ItemsAlignment ──────────▶ ArrangeLine()
                              │
                              ▼
                     子要素配置完了
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| WrapPanel.cs | `src/Avalonia.Controls/WrapPanel.cs` | ソース | メインクラス、UVSize構造体 |
| Panel.cs | `src/Avalonia.Controls/Panel.cs` | ソース | 基底クラス |
| Orientation.cs | `src/Avalonia.Layout/Orientation.cs` | ソース | 方向列挙型 |
| INavigableContainer.cs | `src/Avalonia.Input/INavigableContainer.cs` | ソース | ナビゲーションインターフェース |
