# 画面設計書 27-ColorSchemes（配色一覧）

## 概要

本ドキュメントは、Windows Terminal の配色スキーム一覧画面（ColorSchemes）の設計を記述する。登録済みの配色スキームを一覧表示し、新規作成・選択・編集画面への遷移を行う画面である。

### 本画面の処理概要

**業務上の目的・背景**：ターミナルの配色テーマを管理するための画面である。Windows Terminal にはビルトイン配色スキームとユーザー定義の配色スキームがあり、本画面でそれらを一覧表示して管理する。各配色スキームのプレビュー（16色のカラーチップ + 背景色 + 前景色テキスト）を表示することで、視覚的に配色を確認できる。

**画面へのアクセス方法**：MainPage（設定ナビゲーション）の左側ナビゲーションから「配色」項目をクリックすることでアクセスする。

**主要な操作・処理内容**：
1. 配色スキームの一覧表示（ListView）。各項目は16色のカラーチップとスキーム名をプレビュー表示
2. 新規配色スキームの作成（Add New ボタン）
3. 配色スキームの選択と編集画面（EditColorScheme）への遷移
4. デフォルトスキームのタグ表示

**画面遷移**：
- 遷移元：MainPage（設定ナビゲーション）
- 遷移先：EditColorScheme（配色編集）- スキームクリック時またはEnterキー押下時

**権限による表示制御**：デフォルトスキームには "Default" タグが表示される（IsDefaultScheme プロパティ）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 108 | カラースキーム管理 | 主機能 | 配色スキームの一覧表示・新規作成・削除 |
| 82 | 設定の読み込み・保存 | 主機能 | 配色スキーム設定の読み込みと保存 |
| 84 | 設定UI | 主機能 | 配色一覧のUI表示 |

## 画面種別

一覧

## URL/ルーティング

UWP/WinUI アプリケーションのためURL/ルーティングは適用されない。MainPage の contentFrame 内に Frame.Navigate で表示される。ナビゲーションパラメータとして ColorSchemesPageViewModel が渡される。

## 入出力項目

| 項目名 | 入出力 | データ型 | 説明 |
|--------|--------|----------|------|
| AllColorSchemes | 入力（表示） | IObservableVector<ColorSchemeViewModel> | 全配色スキームのリスト |
| CurrentScheme | 入出力 | ColorSchemeViewModel | 現在選択中のスキーム |

## 表示項目

| 表示領域 | 項目名 | コントロール種別 | 説明 |
|----------|--------|-----------------|------|
| ヘッダー | ColorSchemesDisclaimer | TextBlock（DisclaimerStyle） | 配色に関する注意書き |
| ヘッダー | AddNewButton | Button（BrowseButtonStyle） | 新規配色スキーム作成ボタン（アイコン E710 + テキスト） |
| 一覧 | ColorSchemeListView | ListView（SingleSelection、ItemClick有効） | 配色スキーム一覧 |
| 一覧アイテム | カラーチップグリッド | Grid（8列 x 2行 = 16色） | 各スキームの16色プレビュー（12x12px、CornerRadius=2） |
| 一覧アイテム | スキーム名テキスト | TextBlock（Cascadia Code フォント） | スキーム名（背景色上に前景色で表示） |
| 一覧アイテム | デフォルトタグ | Border + TextBlock | "Default" タグ（IsDefaultScheme=true の場合のみ表示） |

## イベント仕様

### 1-OnNavigatedTo

MainPage からナビゲートされた時に発火する。ナビゲーションパラメータから ColorSchemesPageViewModel を取得し、CurrentPage を Base に設定する。レイアウト更新後に ColorSchemeListView にプログラム的フォーカスを設定する（LayoutUpdated 使用、1回のみ）。テレメトリログとして "NavigatedToPage" イベント（PageId="colorSchemes"）を記録する。

### 2-AddNew_Click

新規配色スキーム作成ボタンのクリック時に発火する。ViewModel の RequestAddNew メソッドを呼び出し、新しいスキームが作成される。作成されたスキームが ListView で選択状態になり、編集画面への遷移が要求される（RequestEditSelectedScheme）。

### 3-ListView_PreviewKeyDown

ListView 上で Enter キーが押下された時に発火する。選択中のスキームの編集画面への遷移を要求する（RequestEditSelectedScheme）。

### 4-SchemeListItemClicked

一覧アイテムがクリックされた時に発火する。ViewModel の SchemeListItemClicked メソッドにより、選択されたスキームの編集画面への遷移が開始される。

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| AddNew_Click | settings.json（ファイル） | INSERT | 新しい配色スキームをメモリ上のモデルに追加（保存は MainPage 経由） |

### テーブル別更新項目詳細

本画面自体は直接ファイルに書き込まない。新規作成はメモリ上のモデルに追加され、MainPage の SaveButton 経由で永続化される。

## メッセージ仕様

| 種別 | メッセージID | 表示条件 | 内容 |
|------|-------------|----------|------|
| 注意書き | ColorSchemesDisclaimer | 常時 | 配色に関する説明・注意事項 |

## 例外処理

- RequestAddNew が null を返した場合（新規作成失敗時）、選択状態の更新と編集画面遷移はスキップされる。

## 備考

- カラーチップは ColorPreviewChipTemplate で定義され、12x12px サイズ、CornerRadius=2 の Border として表示される。
- 各スキームの背景色は BackgroundColor.Color、前景色は ForegroundColor.Color から取得される。
- スキーム名の表示フォントは "Cascadia Code" 固定。
- ListView のマージンに -16（左マージン）を設定し、ナビゲーションコンテンツとのアライメントを調整している。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ColorSchemesPageViewModel.idl | `src/cascadia/TerminalSettingsEditor/ColorSchemesPageViewModel.idl` | AllColorSchemes, CurrentScheme, RequestAddNew, RequestEditSelectedScheme 等のメソッドとプロパティを確認する |
| 1-2 | ColorSchemeViewModel.idl | `src/cascadia/TerminalSettingsEditor/ColorSchemeViewModel.idl` | Name, IsEditable, IsDefaultScheme, ColorEntryAt, ForegroundColor, BackgroundColor 等を確認する |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ColorSchemes.cpp | `src/cascadia/TerminalSettingsEditor/ColorSchemes.cpp` | OnNavigatedTo（行34-53）のCurrentPage設定、LayoutUpdated ハンドラ、テレメトリ記録。AddNew_Click（行55-62）の新規作成フロー |

**主要処理フロー**:
1. **行34-37**: OnNavigatedTo で ViewModel 取得、CurrentPage を Base に設定
2. **行39-44**: LayoutUpdated で ListView にフォーカス設定（1回限り）
3. **行55-62**: AddNew_Click で RequestAddNew -> 選択 -> RequestEditSelectedScheme

#### Step 3: XAML レイアウトを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ColorSchemes.xaml | `src/cascadia/TerminalSettingsEditor/ColorSchemes.xaml` | ListView.ItemTemplate 内のカラーチップグリッド（16色 x 2行）とスキーム名表示の構造を理解する |

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

```
MainPage._Navigate("ColorSchemes_Nav")
    |
    +-- contentFrame.Navigate(typeof(ColorSchemes), ColorSchemesPageViewModel)
            |
            +-- ColorSchemes::OnNavigatedTo
            |       +-- CurrentPage = Base
            |       +-- LayoutUpdated (フォーカス設定)
            |       +-- TraceLogging
            |
            +-- AddNew_Click
            |       +-- ViewModel.RequestAddNew()
            |       +-- ListView.SelectedItem = newScheme
            |       +-- ViewModel.RequestEditSelectedScheme()
            |               +-- MainPage._Navigate -> EditColorScheme
            |
            +-- SchemeListItemClicked / ListView_PreviewKeyDown(Enter)
                    +-- ViewModel.RequestEditSelectedScheme()
                            +-- MainPage._Navigate -> EditColorScheme
```

### データフロー図

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

ColorSchemesPageViewModel --------> ColorSchemes Page          -----> ListView (配色一覧)
  +-- AllColorSchemes                |                                 |
  +-- CurrentScheme                  +-- ListView DataBinding          +-- カラーチップ 16色
                                     |                                 +-- スキーム名テキスト
                                     +-- ItemClick                     +-- Default タグ
                                     |
                                     +-- AddNew_Click ---------> 新規スキーム作成 -> 編集画面遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ColorSchemes.xaml | `src/cascadia/TerminalSettingsEditor/ColorSchemes.xaml` | テンプレート | UI レイアウト定義 |
| ColorSchemes.cpp | `src/cascadia/TerminalSettingsEditor/ColorSchemes.cpp` | ソース | ページ実装 |
| ColorSchemesPageViewModel.idl | `src/cascadia/TerminalSettingsEditor/ColorSchemesPageViewModel.idl` | IDL | ページ ViewModel インターフェース |
| ColorSchemesPageViewModel.h | `src/cascadia/TerminalSettingsEditor/ColorSchemesPageViewModel.h` | ソース | ページ ViewModel クラス定義 |
| ColorSchemesPageViewModel.cpp | `src/cascadia/TerminalSettingsEditor/ColorSchemesPageViewModel.cpp` | ソース | ページ ViewModel 実装 |
| ColorSchemeViewModel.idl | `src/cascadia/TerminalSettingsEditor/ColorSchemeViewModel.idl` | IDL | 個別スキーム ViewModel |
| ColorSchemeViewModel.cpp | `src/cascadia/TerminalSettingsEditor/ColorSchemeViewModel.cpp` | ソース | 個別スキーム ViewModel 実装 |
| CommonResources.xaml | `src/cascadia/TerminalSettingsEditor/CommonResources.xaml` | リソース | 共通スタイル定義 |
