# 機能設計書 69-Transition

## 概要

本ドキュメントは、Avaloniaフレームワークにおける**Transition**機能の設計仕様を記述する。Transitionは、プロパティ値の変更時に自動的に遷移アニメーションを適用する機能を提供する。

### 本機能の処理概要

Transitionは、AvaloniaPropertyの値が変更された際に、旧値から新値への補間アニメーションを自動的に実行する抽象クラスである。Duration、Delay、Easing、Propertyの各プロパティで動作を制御し、具体的な型に対する補間ロジックは派生クラス（DoubleTransition、BrushTransition等）で実装される。

**業務上の目的・背景**：UIにおいて、プロパティ値の急激な変更は視覚的に不自然に感じられることがある。Transitionは、プロパティ変更時に滑らかな遷移効果を自動的に適用することで、より洗練されたユーザー体験を提供する。Animationとは異なり、宣言的に「このプロパティが変更されたら遷移させる」と指定するだけで機能する。

**機能の利用シーン**：
- コントロールのサイズ変更時の滑らかな遷移
- 色やブラシの変更時のフェード効果
- 位置変更時のスライド効果
- 不透明度変更時のフェードイン・アウト

**主要な処理内容**：
1. プロパティ変更の検知
2. 遷移パラメータ（Duration, Delay, Easing）の適用
3. 旧値から新値への補間計算
4. 補間値のプロパティへの適用（Animation優先度）

**関連システム・外部連携**：TransitionはAvalonia.Base.Animationモジュール内で実装され、Animatable、IClock、およびプロパティシステムと連携する。

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

## 関連画面

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

## 機能種別

アニメーション / プロパティ遷移 / 値補間

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Duration | TimeSpan | No | 遷移の長さ | - |
| Delay | TimeSpan | No | 開始前の遅延（デフォルト0） | - |
| Easing | Easing | No | イージング関数（デフォルトLinear） | - |
| Property | AvaloniaProperty | Yes | 遷移対象のプロパティ | Apply時にnullは不可 |

### 入力データソース

- スタイルのTransitionsコレクション
- コントロールのTransitionsプロパティ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| IDisposable | subscription | 遷移アニメーションの購読 |
| IObservable<T> | values | 補間値のストリーム |

### 出力先

- ターゲットコントロールのAvaloniaProperty（Animation優先度）

## 処理フロー

### 処理シーケンス

```
1. Transitionの定義
   └─ Duration, Delay, Easing, Propertyの設定
2. プロパティ変更の検知
   └─ Animatable.PropertyChanged経由
3. Applyメソッド呼び出し
   └─ 旧値と新値を受け取りトランジション開始
4. DoTransition実行
   └─ 派生クラスで補間ロジックを実行
5. TransitionInstance生成
   └─ 時間進行に応じたprogressを生成
6. 値の補間とバインド
   └─ BindingPriority.Animationでプロパティにバインド
```

### フローチャート

```mermaid
flowchart TD
    A[プロパティ変更] --> B[Transition.Apply呼び出し]
    B --> C{Property設定?}
    C -->|No| D[InvalidOperationException]
    C -->|Yes| E[DoTransition呼び出し]
    E --> F[TransitionInstance生成]
    F --> G[時間進行ストリーム]
    G --> H[progress計算]
    H --> I[Easing適用]
    I --> J[値の補間]
    J --> K[プロパティへバインド]
    K --> L{遷移完了?}
    L -->|No| H
    L -->|Yes| M[購読解除]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-69-01 | Property必須 | Apply時にPropertyがnullの場合は例外 | Apply呼び出し時 |
| BR-69-02 | 型一致検証 | TransitionのジェネリックパラメータとPropertyの型は一致が必要 | Property設定時 |
| BR-69-03 | Animation優先度 | 遷移値はBindingPriority.Animationでバインドされる | バインド時 |

### 計算ロジック

- progress計算: TransitionInstanceで時間経過を0.0〜1.0にマップ
- 補間計算: 派生クラスのDoTransitionで`oldValue + (newValue - oldValue) * progress`等

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidOperationException | Propertyがnullの場合 | Propertyを設定する |
| - | InvalidCastException | Property型とTransition型が不一致の場合 | 正しい型のTransitionを使用する |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 遷移アニメーションは滑らかに実行される
- 複数プロパティの同時遷移をサポート

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

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

## 備考

**主要なTransition派生クラス**：
- DoubleTransition: double値の遷移
- IntegerTransition: int値の遷移
- PointTransition: Point値の遷移
- SizeTransition: Size値の遷移
- ThicknessTransition: Thickness値の遷移
- CornerRadiusTransition: CornerRadius値の遷移
- BrushTransition: Brush値の遷移
- ColorTransition: Color値の遷移
- BoxShadowsTransition: BoxShadows値の遷移
- TransformOperationsTransition: TransformOperations値の遷移

---

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

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

### 推奨読解順序

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

TransitionBaseとTransition<T>の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TransitionBase.cs | `src/Avalonia.Base/Animation/TransitionBase.cs` | 基底クラス。Duration, Delay, Easing, Propertyプロパティを確認 |
| 1-2 | Transition.cs | `src/Avalonia.Base/Animation/Transition.cs` | ジェネリック派生クラス。DoTransitionとApplyを確認 |

**読解のコツ**: TransitionBaseがプロパティを定義し、Transition<T>がApplyメソッドの実装を提供する。DoTransitionは抽象メソッドで具体的な補間ロジックは派生クラスで実装。

**主要処理フロー (TransitionBase.cs)**:
1. **16-20行目**: DurationProperty 定義
2. **25-29行目**: DelayProperty 定義
3. **34-38行目**: EasingProperty 定義
4. **43-47行目**: PropertyProperty 定義
5. **49行目**: _duration フィールド
6. **50行目**: _delay フィールド（デフォルトTimeSpan.Zero）
7. **51行目**: _easing フィールド（デフォルトLinearEasing）
8. **96-99行目**: ITransition.Apply の実装

**主要処理フロー (Transition.cs)**:
1. **10-13行目**: 静的コンストラクタ - Property変更ハンドラ
2. **15-19行目**: 型チェック - PropertyTypeとTの一致確認
3. **25行目**: DoTransition 抽象メソッド定義
4. **27-34行目**: Apply メソッド - 遷移の適用

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

時間進行のストリーム生成を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TransitionInstance.cs | `src/Avalonia.Base/Animation/TransitionInstance.cs` | progressストリームの生成 |

#### Step 3: 具体的なTransition実装を理解する

代表的な派生クラスのDoTransition実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Transitions.cs | `src/Avalonia.Base/Animation/Transitions.cs` | 各種Transition派生クラス |
| 3-2 | DoubleTransition等 | 同ファイル内 | 補間ロジック |

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

```
Animatable.PropertyChanged
    │
    └─ Transition検出
           │
           └─ ITransition.Apply(control, clock, oldValue, newValue)
                  │
                  └─ Transition<T>.Apply()
                         │
                         ├─ DoTransition(progress, oldValue, newValue)
                         │      │
                         │      └─ 派生クラスで補間計算
                         │
                         └─ control.Bind<T>(Property, transition, BindingPriority.Animation)
```

### データフロー図

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

プロパティ変更 ───────────▶ Transition.Apply() ──────────────▶ 補間値ストリーム
    │                              │                                  │
    │ oldValue                     │ DoTransition()                   │ IObservable<T>
    │ newValue                     │ TransitionInstance               │
    │ Duration, Easing             │ progress計算                     │
    └──────────────────────────────┘                                  │
                                                                      ▼
                                                              control.Bind()
                                                                      │
                                                              BindingPriority.Animation
                                                                      │
                                                                      ▼
                                                              プロパティ更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TransitionBase.cs | `src/Avalonia.Base/Animation/TransitionBase.cs` | ソース | トランジション基底クラス |
| Transition.cs | `src/Avalonia.Base/Animation/Transition.cs` | ソース | ジェネリックトランジション |
| Transitions.cs | `src/Avalonia.Base/Animation/Transitions.cs` | ソース | 各種トランジション派生クラス |
| TransitionInstance.cs | `src/Avalonia.Base/Animation/TransitionInstance.cs` | ソース | 時間進行ストリーム |
| TransitionObservableBase.cs | `src/Avalonia.Base/Animation/TransitionObservableBase.cs` | ソース | Observable基底 |
| ITransition.cs | `src/Avalonia.Base/Animation/ITransition.cs` | ソース | インターフェース |
| Easing.cs | `src/Avalonia.Base/Animation/Easings/Easing.cs` | ソース | イージング基底クラス |
| Animatable.cs | `src/Avalonia.Base/Animation/Animatable.cs` | ソース | アニメーション対応コントロール基底 |
