# 画面設計書 10-CommandPalette（コマンドパレット）

## 概要

本ドキュメントは、Windows Terminal のコマンド検索・フィルタリング・実行を行う CommandPalette の画面設計書である。Ctrl+Shift+P で起動し、アクション検索モード・タブ検索モード・コマンドラインモードの3つのモードを提供するオーバーレイパレットである。

### 本画面の処理概要

**業務上の目的・背景**：CommandPalette は VS Code 等のモダンエディタと同様のコマンドパレット機能を提供し、ユーザーがキーバインドを記憶していないコマンドでも素早く検索・実行できるようにする。タブ検索やコマンドライン実行も統合することで、ターミナル操作の効率を大幅に向上させる。

**画面へのアクセス方法**：Ctrl+Shift+P でアクション検索モードとして起動。タブ検索アクションでタブ検索モードとして起動。">" プレフィックスでコマンドラインモードに切り替え可能。

**主要な操作・処理内容**：
1. テキスト入力によるコマンド/タブの検索（fzfファジーマッチング）
2. アクションモード：登録されたアクションの検索・実行
3. タブ検索モード：開いているタブの名前検索・切り替え
4. コマンドラインモード：WTコマンドラインの直接実行
5. ネストされたコマンドの展開・ドリルダウン
6. キーチョード（ショートカットキー）の表示
7. コマンドのプレビュー（カラースキーム変更等のリアルタイムプレビュー）
8. コマンド履歴の保持（最大20件）

**画面遷移**：
- 親：TerminalPage（Grid.Row=2 にオーバーレイ表示）
- Ctrl+Shift+P で起動、Escape で閉じる

**権限による表示制御**：特になし

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 73 | コマンドパレット切替 | 主機能 | コマンドパレットの表示/非表示切替 |
| 10 | タブ検索 | 主機能 | タブ検索モードでタブを名前検索 |
| 111 | コマンドライン実行 | 補助機能 | コマンドラインモードでWTコマンドを実行 |
| 112 | 複数アクションの一括実行 | 補助機能 | 選択されたコマンドに含まれる複数アクションを実行 |

## 画面種別

ツール / オーバーレイ

## URL/ルーティング

該当なし

## 入出力項目

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|------|------|
| ActionMap | 入力 | IActionMapView | 利用可能なアクションの一覧 |
| Tabs | 入力 | IObservableVector<Tab> | タブ一覧 |
| MruTabs | 入力 | IObservableVector<Tab> | MRU順のタブ一覧 |
| FilteredActions | 出力 | IObservableVector<FilteredCommand> | フィルタリング済みアクションリスト |
| NoMatchesText | 出力 | hstring | 一致なし時のメッセージ |
| SearchBoxPlaceholderText | 出力 | hstring | 検索ボックスのプレースホルダー |
| PrefixCharacter | 出力 | hstring | モードプレフィックス文字 |
| ControlName | 出力 | hstring | アクセシビリティ名 |
| ParentCommandName | 出力 | hstring | 親コマンド名（ネスト時） |
| ParsedCommandLineText | 出力 | hstring | パース済みコマンドライン表示 |
| DispatchCommandRequested | 出力 | イベント | コマンド実行要求イベント |
| CommandLineExecutionRequested | 出力 | イベント | コマンドライン実行要求イベント |
| SwitchToTabRequested | 出力 | イベント | タブ切り替え要求イベント |
| PreviewAction | 出力 | イベント | コマンドプレビューイベント |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| _backdrop | Grid (6:2:2 レイアウト Column=1) | パレット背景パネル（FlyoutPresenterBackground、影付き） |
| _searchBox | _backdrop Grid.Row=0 | 検索テキストボックス |
| _prefixCharacter | _backdrop Grid.Row=0 | モードプレフィックス文字表示 |
| _parentCommandBackButton | _backdrop Grid.Row=1 | 親コマンドに戻るボタン（ネスト時表示） |
| _parentCommandText | _backdrop Grid.Row=1 | 親コマンド名テキスト（ネスト時表示） |
| ParsedCommandLineBox | _backdrop Grid.Row=1 | パース済みコマンドライン表示（コマンドラインモード時） |
| _noMatchesText | _backdrop Grid.Row=3 | 一致なし時のメッセージ表示 |
| _filteredActionsView | _backdrop Grid.Row=3 | フィルタリング済みアクション一覧（ListView） |

## イベント仕様

### 1-テキスト入力（_filterTextChanged）

_searchBox のテキスト変更で _filterTextChanged が呼び出される。_evaluatePrefix() でプレフィックス文字を判定し、モードに応じた検索処理 _updateFilteredActions() を実行する。fzf マッチャーでファジーマッチングを行い、Weight でソートされた結果が _filteredActions に設定される。

### 2-アクション実行（_listItemClicked）

ListView のアイテムクリックで _listItemClicked が呼び出される。モードに応じて以下のいずれかが実行される：
- ActionMode: _dispatchCommand() -> DispatchCommandRequested イベント
- TabSearchMode: _switchToTab() -> SwitchToTabRequested イベント
- CommandlineMode: _dispatchCommandline() -> CommandLineExecutionRequested イベント

### 3-ネストコマンドドリルダウン

ネストされたコマンドを選択すると _updateCurrentNestedCommands() が呼び出され、子コマンドの一覧が表示される。_parentCommandBackButton で親に戻ることができる。

### 4-コマンドプレビュー

マウスホバーでPreviewActionイベントが発火し、カラースキーム変更等のプレビューがリアルタイムで表示される。マウスが離れるとプレビューが元に戻る（_pointerExitTimer でデバウンス）。

### 5-タブ切り替えモード

EnableTabSwitcherMode() で起動。Ctrl+Tab のキーアップでアンカーキーハンドラが動作し、選択中のタブに切り替える。MRU 順またはインデックス順で表示可能。

### 6-閉じる

Escape キーまたは背景クリックで _dismissPalette() が呼び出され、パレットが非表示になる。フォーカスが外れた場合も自動的に閉じる（_lostFocusHandler）。

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

該当なし（コマンド履歴はローカルファイルに保存）

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

該当なし

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| NoMatchesText | 情報 | 一致するコマンドなし | 検索結果が0件の時 |
| SearchBoxPlaceholderText | プレースホルダー | 検索ボックスのヒント | テキスト未入力時 |
| ParentCommandBackButton | ToolTip | 親に戻る | ネスト時の戻るボタン |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 無効なコマンドライン | ParsedCommandLineText にエラー情報を表示 |
| コマンド実行失敗 | アクションの args.Handled が false のまま返される |

## 備考

- UserControl ベース
- 画面レイアウトは 2:6:2 のGrid比率でセンタリング配置
- x:Load="False" で遅延読み込み（TerminalPage.xaml 163-168行目）
- Visibility="Collapsed" で非表示状態から切り替え
- CommandPaletteMode enum で4モードを管理（ActionMode, TabSearchMode, TabSwitchMode, CommandlineMode）
- CommandLineHistoryLength=20 でコマンドライン履歴を最大20件保持
- ChoosingItemContainer/ContainerContentChanging で ListView のコンテナを最適化（リサイクル）
- PaletteItemTemplateSelector で GeneralItemTemplate / NestedItemTemplate / TabItemTemplate を切り替え
- GeneralItemTemplate にはアイコン、コマンド名、サブタイトル、キーチョードが表示される
- TabItemTemplate にはプログレスリング、アイコン、タブ名、ステータスアイコン群、色インジケータが表示される
- FlyoutPresenterBackground で背景、SharedShadow で影付き（Translation=0,0,32）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CommandPalette.h | `src/cascadia/TerminalApp/CommandPalette.h` | CommandPaletteMode enum（20-26行目）。FilteredActions/各種Observable Property（56-61行目）。_allCommands/_currentNestedCommands/_filteredActions（74-76行目） |
| 1-2 | FilteredCommand.h | `src/cascadia/TerminalApp/FilteredCommand.h` | フィルタリング結果のラッパー。Weight プロパティでマッチ度を管理 |

**読解のコツ**: CommandPaletteMode の4つのモード（ActionMode, TabSearchMode, TabSwitchMode, CommandlineMode）によって表示内容とアクションが大きく変わる。_switchToMode() でモード切替が行われる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CommandPalette.xaml | `src/cascadia/TerminalApp/CommandPalette.xaml` | Grid内にDataTemplate群（53-263行目）とメインUI（272-397行目）。_backdrop（284-394行目）内に検索ボックスとListView |

**主要処理フロー**:
1. **53-58行目**: ListItemTemplate - ListViewItemのベーステンプレート
2. **60-117行目**: GeneralItemTemplate - 通常コマンドアイテム（アイコン、名前、キーチョード）
3. **119-183行目**: NestedItemTemplate - ネストコマンドアイテム（展開矢印付き）
4. **185-263行目**: TabItemTemplate - タブ検索アイテム（プログレス、ステータスアイコン、色）
5. **306-317行目**: _searchBox - 検索入力
6. **378-392行目**: _filteredActionsView - 結果ListView

#### Step 3: モード切替と検索ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CommandPalette.cpp | `src/cascadia/TerminalApp/CommandPalette.cpp` | _switchToMode(), _updateFilteredActions(), _dispatchCommand() の実装 |

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

```
TerminalPage
  └─ CommandPalette (x:Load="False" -> 遅延読み込み)
       ├─ EnableCommandPaletteMode(launchMode)
       │    └─ _switchToMode(ActionMode)
       │         └─ _populateCommands() -> _allCommands 構築
       │              └─ _updateFilteredActions()
       ├─ EnableTabSearchMode()
       │    └─ _switchToMode(TabSearchMode)
       │         └─ _tabActions から検索
       ├─ EnableTabSwitcherMode(startIdx, mode)
       │    └─ _switchToMode(TabSwitchMode)
       │         └─ _mruTabActions から選択
       ├─ _filterTextChanged()
       │    ├─ _evaluatePrefix() -> モード判定
       │    └─ _updateFilteredActions()
       │         └─ _collectFilteredActions() -> fzf マッチング
       └─ _listItemClicked()
            ├─ ActionMode -> _dispatchCommand() -> DispatchCommandRequested
            ├─ TabSearchMode -> _switchToTab() -> SwitchToTabRequested
            └─ CommandlineMode -> _dispatchCommandline() -> CommandLineExecutionRequested
```

### データフロー図

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

ActionMap ────────> _populateCommands()            ┌──> FilteredActions
(全アクション)        └─> _allCommands                │    (ListView表示)
                                                    │
検索テキスト ─────> _filterTextChanged()            ├──> PreviewAction
                     ├─> _evaluatePrefix()          │    (リアルタイムプレビュー)
                     └─> _updateFilteredActions()   │
                          └─> fzf マッチング        │
                                                    │
アイテム選択 ─────> _listItemClicked()              └──> DispatchCommandRequested /
                     └─> _dispatchCommand()              SwitchToTabRequested /
                          / _switchToTab()               CommandLineExecutionRequested
                          / _dispatchCommandline()

Tab一覧 ──────────> SetTabs(tabs, mruTabs)
                     └─> _tabActions / _mruTabActions 構築
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CommandPalette.xaml | `src/cascadia/TerminalApp/CommandPalette.xaml` | テンプレート | XAML レイアウト・テンプレート定義 |
| CommandPalette.h | `src/cascadia/TerminalApp/CommandPalette.h` | ソース | クラス宣言・モード定義 |
| CommandPalette.cpp | `src/cascadia/TerminalApp/CommandPalette.cpp` | ソース | 検索・実行ロジック実装 |
| FilteredCommand.h | `src/cascadia/TerminalApp/FilteredCommand.h` | ソース | フィルタリング結果ラッパー |
| HighlightedTextControl.h | `src/cascadia/TerminalApp/HighlightedTextControl.h` | ソース | マッチ部分ハイライト表示 |
| CommandPaletteItems.h | `src/cascadia/TerminalApp/CommandPaletteItems.h` | ソース | PaletteItem基底クラス |
| AppCommandlineArgs.h | `src/cascadia/TerminalApp/AppCommandlineArgs.h` | ソース | コマンドライン解析 |
| TerminalPage.xaml | `src/cascadia/TerminalApp/TerminalPage.xaml` | テンプレート | 親コンテナ（163-168行目） |
