# 機能設計書 84-設定UI

## 概要

本ドキュメントは、Windows Terminal の XAML ベース設定エディタ（Settings UI）の全体構造を記述する。TerminalSettingsEditor プロジェクトが提供する MainPage を中核とし、各設定カテゴリのページ遷移とデータバインディングを解説する。

### 本機能の処理概要

**業務上の目的・背景**：settings.json の直接編集は初心者にはハードルが高く、設定ミスの原因になりやすい。GUI ベースの設定エディタを提供することで、ユーザーが視覚的に設定を変更・確認できるようにし、JSON の文法ミスによる設定破損を防止する。

**機能の利用シーン**：ユーザーが Ctrl+, やメニューから「設定」を開いた際に表示される。プロファイルの追加・編集、カラースキームの変更、キーバインドの設定、起動動作やレンダリングオプションの変更など、あらゆる設定変更に使用される。

**主要な処理内容**：
1. MainPage によるナビゲーション管理（NavigationView ベース）
2. 設定のコピー作成（_settingsClone）によるトランザクション的な編集
3. 各設定ページへの遷移とビューモデルの管理
4. パンくずリスト（BreadcrumbBar）によるナビゲーション表示
5. SaveButton による設定の保存と ResetButton によるリセット
6. OpenJson ボタンによる settings.json の直接編集への切り替え

**関連システム・外部連携**：CascadiaSettings モデル（読み込み・保存）、TerminalApp（SettingsPaneContent 経由での統合）。

**権限による制御**：特別な権限による制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | MainPage（設定ナビゲーション） | 主画面 | NavigationView による各設定ページへの遷移管理 |
| 22 | Launch（起動設定） | サブページ | 起動時設定のUI表示と編集 |
| 23 | Interaction（操作設定） | サブページ | 操作設定のUI表示と編集 |
| 24 | GlobalAppearance（外観設定） | サブページ | 外観設定のUI表示と編集 |
| 25 | Rendering（レンダリング設定） | サブページ | レンダリング設定のUI表示と編集 |
| 26 | Compatibility（互換性設定） | サブページ | 互換性設定のUI表示と編集 |
| 27 | ColorSchemes（配色一覧） | サブページ | 配色スキーム管理のUI |
| 28 | EditColorScheme（配色編集） | サブページ | 個別配色の編集UI |
| 29 | Actions（アクション一覧） | サブページ | アクション・キーバインド管理のUI |
| 30 | EditAction（アクション編集） | サブページ | 個別アクション編集のUI |
| 31 | NewTabMenu（新規タブメニュー設定） | サブページ | 新規タブメニューのUI |
| 32 | Extensions（拡張機能管理） | サブページ | 拡張機能管理のUI |
| 33 | AddProfile（プロファイル追加） | サブページ | プロファイル追加のUI |
| 34-38 | Profiles_Base / Appearance / Terminal / Advanced / Orphaned | サブページ | プロファイル詳細設定のUI |

## 機能種別

CRUD操作 / 画面遷移 / データバインディング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| settings | CascadiaSettings | Yes | 現在のアプリケーション設定 | 非null |

### 入力データソース

CascadiaSettings オブジェクト（メモリ内の設定データ）。MainPage コンストラクタで settings.Copy() による編集用クローンが作成される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 編集された設定 | CascadiaSettings | ユーザーが編集した設定オブジェクト |
| OpenJson イベント | SettingsTarget | JSON ファイルを直接開くリクエスト |
| ShowLoadWarningsDialog イベント | IVectorView<SettingsLoadWarnings> | 設定読み込み警告の表示リクエスト |

### 出力先

- 画面表示：XAML による設定UIのレンダリング
- CascadiaSettings：保存時に WriteSettingsToDisk() で settings.json に反映

## 処理フロー

### 処理シーケンス

```
1. MainPage コンストラクタが呼び出される
   └─ settings.Copy() で設定のクローンを作成
   └─ 各ビューモデルを初期化（NewTabMenuViewModel, ColorSchemesPageViewModel, ActionsViewModel）
2. NavigationView の項目選択でページ遷移
   └─ contentFrame().Navigate() で各設定ページに遷移
   └─ パンくずリストを更新
3. ユーザーが設定を編集
   └─ ビューモデルを通じて _settingsClone が更新される
4. SaveButton クリック時
   └─ _settingsClone の変更を反映
   └─ WriteSettingsToDisk() で settings.json に保存
5. ResetButton クリック時
   └─ 設定をデフォルトにリセット
```

### フローチャート

```mermaid
flowchart TD
    A[設定UI起動] --> B[MainPage コンストラクタ]
    B --> C[settings.Copy でクローン作成]
    C --> D[ビューモデル初期化]
    D --> E[NavigationView 表示]
    E --> F{ナビゲーション選択}
    F --> G[対応ページに遷移]
    G --> H[ユーザーが設定編集]
    H --> I{保存ボタンクリック?}
    I -->|Yes| J[WriteSettingsToDisk]
    I -->|No| K{リセットボタンクリック?}
    K -->|Yes| L[デフォルトにリセット]
    K -->|No| F
    J --> M[設定反映完了]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-84-01 | クローン編集 | 設定UIは settings.Copy() で作成したクローンを編集し、保存時にのみ反映する | 設定UI起動時 |
| BR-84-02 | ナビゲーション管理 | NavigationView とパンくずリストで階層的なページ遷移を管理 | 常時 |
| BR-84-03 | サブページ遷移 | カラースキーム編集やアクション編集はサブページとして遷移する | 該当項目選択時 |

### 計算ロジック

該当なし。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 保存失敗 | settings.json への書き込みに失敗 | 警告ダイアログを表示 |
| SettingsLoadWarnings | 設定警告 | 読み込み時に警告が発生 | ShowLoadWarningsDialog で表示 |

### リトライ仕様

特になし。

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

settings.Copy() によるクローンを編集し、保存ボタン押下時にのみ永続化する擬似トランザクション方式。キャンセルした場合はクローンが破棄される。

## パフォーマンス要件

- PrepareForSettingsUI() により設定UIコンポーネントは遅延ロードされ、アプリ起動時間に影響しない。

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

- 設定UIで編集可能な項目は settings.json に記述可能な範囲に限定される。

## 備考

- ナビゲーションタグ一覧：openJsonTag, launchTag, interactionTag, renderingTag, compatibilityTag, actionsTag, newTabMenuTag, extensionsTag, globalProfileTag, addProfileTag, colorSchemesTag, globalAppearanceTag

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CascadiaSettings.h | `src/cascadia/TerminalSettingsModel/CascadiaSettings.h` | Copy() メソッド（164行目）による設定クローンの生成方式を理解 |

**読解のコツ**: 設定UIは CascadiaSettings の Copy（ディープコピー）を編集するため、保存するまで元の設定に影響しない。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | MainPage.cpp | `src/cascadia/TerminalSettingsEditor/MainPage.cpp` | MainPage コンストラクタ（61-120行目）で設定クローン作成とビューモデル初期化 |

**主要処理フロー**:
1. **61-63行目**: _settingsSource と _settingsClone の初期化
2. **68-88行目**: NewTabMenuViewModel の初期化と PropertyChanged ハンドラ
3. **90-114行目**: ColorSchemesPageViewModel の初期化とサブページ遷移管理
4. **116-120行目**: ActionsViewModel の初期化

#### Step 3: ページ遷移を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | MainPage.cpp | `src/cascadia/TerminalSettingsEditor/MainPage.cpp` | ナビゲーションタグ定義（41-52行目）と _Navigate メソッドを確認 |

**主要処理フロー**:
- **41-52行目**: 各設定ページのナビゲーションタグ定数
- サブページ遷移時にパンくずリストが更新される

#### Step 4: 設定ペイン統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | SettingsPaneContent.cpp | `src/cascadia/TerminalApp/SettingsPaneContent.cpp` | SettingsPaneContent が MainPage をラップする構造 |
| 4-2 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | OpenSettingsUI（4360行目付近）で設定タブを作成 |

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

```
TerminalPage::OpenSettingsUI (TerminalPage.cpp:4360)
    │
    └─ SettingsPaneContent::SettingsPaneContent
           │
           └─ MainPage::MainPage (MainPage.cpp:61)
                  │
                  ├─ settings.Copy() → _settingsClone
                  │
                  ├─ NewTabMenuViewModel 初期化
                  ├─ ColorSchemesPageViewModel 初期化
                  ├─ ActionsViewModel 初期化
                  │
                  └─ [ナビゲーション選択時]
                         ├─ Launch ページ
                         ├─ Interaction ページ
                         ├─ GlobalAppearance ページ
                         ├─ Rendering ページ
                         ├─ Compatibility ページ
                         ├─ ColorSchemes ページ → EditColorScheme
                         ├─ Actions ページ → EditAction
                         ├─ NewTabMenu ページ
                         ├─ Extensions ページ
                         ├─ AddProfile ページ
                         └─ Profiles_Base / Appearance / Terminal / Advanced
```

### データフロー図

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

CascadiaSettings ────▶ MainPage (Copy)              settings.json
  (現在の設定)           │                            (保存時)
                        ▼
                   _settingsClone ──▶ [各ビューモデル]
                   (編集用クローン)      │
                                        ▼
                                   XAML Data Binding
                                        │
                                        ▼
                                   ユーザー操作
                                        │
                                   [保存ボタン]
                                        │
                                        ▼
                                   WriteSettingsToDisk()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MainPage.cpp | `src/cascadia/TerminalSettingsEditor/MainPage.cpp` | ソース | 設定UI メインページ実装 |
| Launch.cpp | `src/cascadia/TerminalSettingsEditor/Launch.cpp` | ソース | 起動設定ページ |
| Interaction.cpp | `src/cascadia/TerminalSettingsEditor/Interaction.cpp` | ソース | 操作設定ページ |
| GlobalAppearance.cpp | `src/cascadia/TerminalSettingsEditor/GlobalAppearance.cpp` | ソース | 外観設定ページ |
| Rendering.h | `src/cascadia/TerminalSettingsEditor/Rendering.h` | ヘッダ | レンダリング設定ページ |
| Compatibility.cpp | `src/cascadia/TerminalSettingsEditor/Compatibility.cpp` | ソース | 互換性設定ページ |
| ColorSchemes.xaml | `src/cascadia/TerminalSettingsEditor/ColorSchemes.xaml` | XAML | カラースキーム一覧UI |
| EditColorScheme.xaml | `src/cascadia/TerminalSettingsEditor/EditColorScheme.xaml` | XAML | カラースキーム編集UI |
| Actions.h | `src/cascadia/TerminalSettingsEditor/Actions.h` | ヘッダ | アクション一覧ページ |
| EditAction.cpp | `src/cascadia/TerminalSettingsEditor/EditAction.cpp` | ソース | アクション編集ページ |
| SettingsPaneContent.cpp | `src/cascadia/TerminalApp/SettingsPaneContent.cpp` | ソース | 設定ペイン統合 |
| ProfileViewModel.idl | `src/cascadia/TerminalSettingsEditor/ProfileViewModel.idl` | IDL | プロファイルビューモデル定義 |
