# 機能設計書 70-PageSlide

## 概要

本ドキュメントは、Avaloniaフレームワークにおける**PageSlide**機能の設計仕様を記述する。PageSlideは、ページ間のスライドトランジション効果を提供し、ページナビゲーション時の視覚的なフィードバックを実現する。

### 本機能の処理概要

PageSlideは、2つのVisual要素間でスライドアニメーションを実行するIPageTransition実装である。水平方向または垂直方向のスライドをサポートし、前進・後退の方向に応じてスライド方向を自動的に調整する。SlideInEasingとSlideOutEasingで入場・退場のイージングを個別に設定可能。

**業務上の目的・背景**：ページベースのナビゲーション（ウィザード、タブ切り替え、カルーセル等）において、ページ遷移を視覚的にわかりやすくすることはユーザー体験向上に重要である。PageSlideは、モバイルアプリケーションでよく見られるスライド遷移効果をAvaloniaで実現し、直感的なナビゲーション体験を提供する。

**機能の利用シーン**：
- Carouselコントロールのページ切り替え
- TransitioningContentControlのコンテンツ遷移
- ウィザード形式のUIでのステップ遷移
- タブコンテンツの切り替え

**主要な処理内容**：
1. 遷移元・遷移先Visualの取得
2. 共通親要素の特定
3. 親要素のサイズに基づくスライド距離の計算
4. TranslateTransformを使用したアニメーション実行
5. 遷移元の非表示・遷移先の表示制御

**関連システム・外部連携**：PageSlideはAvalonia.Base.Animationモジュール内で実装され、Animation、TranslateTransform、およびVisualTreeと連携する。

**権限による制御**：特にアクセス権限による制御は行われない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | Carousel | 主機能 | ページスライドトランジションの適用 |
| 60 | TransitioningContentControl | 補助機能 | コンテンツ遷移アニメーション |

## 機能種別

ページトランジション / スライドアニメーション / ナビゲーション効果

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Duration | TimeSpan | No | アニメーションの長さ | - |
| Orientation | SlideAxis | No | スライド方向（Horizontal/Vertical） | - |
| SlideInEasing | Easing | No | 入場イージング（デフォルトLinear） | - |
| SlideOutEasing | Easing | No | 退場イージング（デフォルトLinear） | - |

### 入力データソース

- コードまたはXAMLでのPageSlideインスタンス化
- IPageTransition要求コントロール

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Task | completion | トランジション完了を待つTask |

### 出力先

- 遷移元・遷移先VisualのTranslateTransformプロパティ
- Visualの可視性プロパティ

## 処理フロー

### 処理シーケンス

```
1. Start呼び出し
   └─ from, to, forward, cancellationTokenを受け取る
2. 共通親要素の取得
   └─ GetVisualParentで親Visualを特定
3. スライド距離の計算
   └─ 親要素の幅または高さを取得
4. 退場アニメーション（from）
   └─ 0 → ±distance のTranslateTransform
5. 入場アニメーション（to）
   └─ ±distance → 0 のTranslateTransform
6. 両アニメーションの並行実行
   └─ Task.WhenAllで完了待ち
7. 遷移元の非表示化
   └─ from.IsVisible = false
```

### フローチャート

```mermaid
flowchart TD
    A[Start呼び出し] --> B{cancellationToken確認}
    B -->|Cancelled| C[即座にreturn]
    B -->|OK| D[GetVisualParent]
    D --> E[スライド距離計算]
    E --> F{from存在?}
    F -->|Yes| G[退場Animation作成]
    F -->|No| H{to存在?}
    G --> H
    H -->|Yes| I[to.IsVisible = true]
    I --> J[入場Animation作成]
    H -->|No| K[Task.WhenAll]
    J --> K
    K --> L{Cancelled?}
    L -->|No| M[from.IsVisible = false]
    L -->|Yes| N[終了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-70-01 | 共通親必須 | fromとtoは同じVisualParentを持つ必要がある | Start時 |
| BR-70-02 | null許容 | fromまたはtoの一方がnullでも動作可能 | Start時 |
| BR-70-03 | forward方向 | forward=trueで正方向、falseで逆方向スライド | アニメーション時 |
| BR-70-04 | キャンセル対応 | CancellationToken.Requestedならすぐにreturn | Start時・終了時 |

### 計算ロジック

- 距離計算: `parent.Bounds.Width`（Horizontal）または `parent.Bounds.Height`（Vertical）
- 退場終点: `forward ? -distance : distance`
- 入場始点: `forward ? distance : -distance`

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ArgumentException | fromとtoのVisualParentが異なる場合 | 同じ親を持つVisualを使用 |
| - | InvalidOperationException | 両方のVisualの親がnullの場合 | 有効な親を持つVisualを使用 |

### リトライ仕様

リトライ処理は行わない。

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

本機能はトランザクションを使用しない。

## パフォーマンス要件

- アニメーションは滑らかに実行される
- 60fps以上のフレームレートを目標

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

特段のセキュリティ要件はない。

## 備考

- SlideAxis: Horizontal（デフォルト）、Vertical
- IPageTransitionインターフェースを実装

---

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

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

### 推奨読解順序

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

PageSlideクラスの構造とプロパティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | PageSlide.cs | `src/Avalonia.Base/Animation/PageSlide.cs` | IPageTransition実装、Duration、Orientation、Easing設定を確認 |

**読解のコツ**: PageSlideはIPageTransitionを実装し、Startメソッドで非同期にトランジションを実行する。内部でAnimationを動的に生成している。

**主要処理フロー (PageSlide.cs)**:
1. **20-24行目**: SlideAxis列挙型 - Horizontal, Vertical
2. **29-31行目**: デフォルトコンストラクタ
3. **38-42行目**: パラメータ付きコンストラクタ
4. **47行目**: Duration プロパティ
5. **52行目**: Orientation プロパティ
6. **57行目**: SlideInEasing プロパティ（デフォルトLinearEasing）
7. **62行目**: SlideOutEasing プロパティ（デフォルトLinearEasing）
8. **65-144行目**: Start メソッド - メイン処理
9. **72-75行目**: 親要素とスライド距離の取得
10. **77-104行目**: 退場アニメーション生成
11. **107-136行目**: 入場アニメーション生成
12. **138行目**: Task.WhenAll - 並行実行
13. **140-143行目**: 終了処理（from非表示化）
14. **158-169行目**: GetVisualParent - 共通親要素の取得

#### Step 2: IPageTransitionを理解する

ページトランジションインターフェースを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | IPageTransition.cs | `src/Avalonia.Base/Animation/IPageTransition.cs` | Startメソッドシグネチャ |

#### Step 3: 関連トランジションを理解する

他のページトランジション実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CrossFade.cs | `src/Avalonia.Base/Animation/CrossFade.cs` | フェードトランジション |

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

```
Carousel / TransitioningContentControl
    │
    └─ IPageTransition.Start(from, to, forward, cancellationToken)
           │
           └─ PageSlide.Start()
                  │
                  ├─ GetVisualParent(from, to)
                  │
                  ├─ 退場Animation生成
                  │      │
                  │      ├─ new Animation { ... }
                  │      │
                  │      └─ KeyFrame (TranslateTransform)
                  │
                  ├─ 入場Animation生成
                  │      │
                  │      ├─ to.IsVisible = true
                  │      │
                  │      └─ new Animation { ... }
                  │
                  ├─ Task.WhenAll(animations)
                  │
                  └─ from.IsVisible = false
```

### データフロー図

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

from Visual ────────────────▶ PageSlide.Start() ─────────────▶ Taskの完了
to Visual                          │
forward flag                       │
cancellationToken                  │
                                   ├─ 退場Animation
                                   │      TranslateTransform 0 → ±distance
                                   │
                                   ├─ 入場Animation
                                   │      TranslateTransform ±distance → 0
                                   │
                                   └─ 可視性制御
                                          from.IsVisible = false
                                          to.IsVisible = true
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| PageSlide.cs | `src/Avalonia.Base/Animation/PageSlide.cs` | ソース | ページスライドトランジション |
| CrossFade.cs | `src/Avalonia.Base/Animation/CrossFade.cs` | ソース | クロスフェードトランジション |
| IPageTransition.cs | `src/Avalonia.Base/Animation/IPageTransition.cs` | ソース | ページトランジションインターフェース |
| Animation.cs | `src/Avalonia.Base/Animation/Animation.cs` | ソース | アニメーションクラス |
| KeyFrame.cs | `src/Avalonia.Base/Animation/KeyFrame.cs` | ソース | キーフレーム |
| Setter.cs | `src/Avalonia.Base/Styling/Setter.cs` | ソース | セッター |
| TranslateTransform.cs | `src/Avalonia.Base/Media/TranslateTransform.cs` | ソース | 移動変換 |
| Visual.cs | `src/Avalonia.Base/Visual.cs` | ソース | ビジュアル基底クラス |
