# 機能設計書 73-コマンドパレット切替

## 概要

本ドキュメントは、Windows Terminalにおけるコマンドパレットの開閉切替機能の設計を記述する。コマンドパレットはアクションモードとコマンドラインモードの2つのモードで起動でき、登録済みアクションの検索・実行やWTコマンドラインの直接実行を可能にする。

### 本機能の処理概要

ToggleCommandPaletteアクションは、コマンドパレットUIの表示/非表示を切り替える機能である。コマンドパレットはフィルタリング可能なコマンド一覧を表示し、キーボード操作で素早くアクションを実行できるUIコンポーネントである。

**業務上の目的・背景**：マウス操作やメニュー探索を行わずに、キーボードのみでターミナルの各種操作を素早く実行できるようにする。VS Codeのコマンドパレットに着想を得た機能で、パワーユーザーの生産性向上を目的とする。

**機能の利用シーン**：キーバインドを覚えていないアクションを検索して実行したい場合、WTコマンドラインをインライン実行したい場合、タブ検索モードでタブを名前から検索したい場合に利用される。

**主要な処理内容**：
1. ToggleCommandPaletteアクションの受信と起動モードの判定
2. コマンドパレットUIの遅延読み込み（LoadCommandPalette）
3. Visibilityの切り替え（Visible/Collapsed）
4. 指定されたモード（アクション/コマンドライン）での有効化
5. コマンドのフィルタリングと表示
6. 選択されたコマンドのディスパッチ

**関連システム・外部連携**：ActionMap（キーバインド/アクション定義）、Settings Model（設定モデル）との連携。

**権限による制御**：特になし。すべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleToggleCommandPaletteによりコマンドパレットの開閉 |
| 10 | CommandPalette（コマンドパレット） | 主画面 | コマンドパレットの表示/非表示切替、タブ検索モード |

## 機能種別

UI制御 / コマンド実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| LaunchMode | CommandPaletteLaunchMode | No | 起動モード（Action/CommandLine） | 列挙型の範囲内であること |

### 入力データソース

キーバインド（デフォルト: Ctrl+Shift+P）またはコマンドパレットボタンからのアクション発行。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Visibility | Visibility | コマンドパレットの表示/非表示状態 |
| FilteredActions | IObservableVector | フィルタリング済みコマンド一覧 |

### 出力先

コマンドパレットUI（CommandPalette XAML コントロール）

## 処理フロー

### 処理シーケンス

```
1. ToggleCommandPaletteアクション受信
   └─ _HandleToggleCommandPaletteハンドラが呼び出される
2. ToggleCommandPaletteArgs の取得
   └─ LaunchMode（アクション or コマンドライン）の判定
3. LoadCommandPalette() による遅延読み込み
   └─ コマンドパレットUIが未初期化の場合に初期化
4. 現在のVisibility確認
   └─ Visible → Collapsed、Collapsed → Visible に切り替え
5. EnableCommandPaletteMode() の呼び出し
   └─ 指定されたLaunchModeでパレットを有効化
6. Visibility 設定
   └─ 新しい表示状態を適用
```

### フローチャート

```mermaid
flowchart TD
    A[ToggleCommandPaletteアクション受信] --> B[ToggleCommandPaletteArgs取得]
    B --> C{Args取得成功?}
    C -->|No| D[処理終了]
    C -->|Yes| E[LoadCommandPalette]
    E --> F{現在Visible?}
    F -->|Yes| G[Collapsed に設定]
    F -->|No| H[Visible に設定]
    G --> I[EnableCommandPaletteMode]
    H --> I
    I --> J[Visibility適用]
    J --> K[処理完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-73-01 | トグル動作 | 表示中は非表示に、非表示中は表示にする | ToggleCommandPalette実行時 |
| BR-73-02 | モード指定 | LaunchModeに応じてアクションモードまたはコマンドラインモードで起動 | パレット表示時 |
| BR-73-03 | 遅延読み込み | コマンドパレットUIは初回アクセス時に初期化 | LoadCommandPalette呼び出し時 |
| BR-73-04 | フォーカス復帰 | パレットが非表示になるとアクティブコントロールにフォーカスが戻る | Visibility変更時 |

### 計算ロジック

特になし。

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

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

本機能にデータベース操作はない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Args取得失敗 | ToggleCommandPaletteArgsへのキャスト失敗 | ハンドラ内で何もせずリターン |

### リトライ仕様

リトライは不要。

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

本機能にトランザクション処理はない。

## パフォーマンス要件

コマンドパレットの表示は即座に行われること。フィルタリングはキー入力ごとにリアルタイムで実行される。

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

特になし。

## 備考

- コマンドパレットは4つのモードを持つ: ActionMode, TabSearchMode, TabSwitchMode, CommandlineMode
- TabSearchModeはタブ検索機能（No.10）、TabSwitchModeはタブ切り替え機能と連携
- コマンドラインモードでは最大20件のコマンド履歴が保持される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CommandPalette.h | `src/cascadia/TerminalApp/CommandPalette.h` | CommandPaletteMode列挙型（20-26行目）：4つのモード定義。FilteredActions、SetActionMap等のメソッド |
| 1-2 | ActionArgs.h | `src/cascadia/TerminalSettingsModel/ActionArgs.h` | ToggleCommandPaletteArgs のLaunchModeプロパティ |

**読解のコツ**: CommandPaletteはXAMLコントロールで、WinRT/C++のIDLパターン（.g.h生成ファイル）を使用している。WINRT_OBSERVABLE_PROPERTYマクロはデータバインディング用のプロパティを生成する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | _HandleToggleCommandPalette（651-661行目） |

**主要処理フロー**:
1. **654行目**: ToggleCommandPaletteArgsへのtry_asキャスト
2. **656行目**: LoadCommandPaletteで遅延読み込み
3. **657行目**: 現在のVisibilityを取得し反転
4. **658行目**: EnableCommandPaletteModeで起動モード設定
5. **659行目**: Visibility設定
6. **660行目**: args.Handled(true)

#### Step 3: コマンドパレットUIを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CommandPalette.cpp | `src/cascadia/TerminalApp/CommandPalette.cpp` | EnableCommandPaletteMode、_filterTextChanged、_dispatchCommand |
| 3-2 | CommandPalette.xaml | `src/cascadia/TerminalApp/CommandPalette.xaml` | XAMLレイアウト定義 |

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

```
TerminalPage::_HandleToggleCommandPalette (AppActionHandlers.cpp:651)
    │
    ├─ LoadCommandPalette() [遅延初期化]
    │
    ├─ CommandPalette::EnableCommandPaletteMode(launchMode)
    │      │
    │      └─ _switchToMode(ActionMode or CommandlineMode)
    │             │
    │             ├─ _populateCommands() [アクション一覧取得]
    │             └─ _updateFilteredActions() [フィルタリング]
    │
    └─ CommandPalette::Visibility(v) [表示/非表示設定]
           │
           └─ (Collapsed時) _FocusActiveControl [フォーカス復帰]
```

### データフロー図

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

LaunchMode ──────────▶ _HandleToggleCommandPalette
                              │
                              ▼
ActionMap ────────────▶ CommandPalette
(アクション定義)         │  EnableCommandPaletteMode
                        │  _populateCommands
                        │  _updateFilteredActions
                              │
                              ▼
                        FilteredActions ──────▶ CommandPalette UI
                        (フィルタ済み一覧)        (XAML ListView)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | トグルアクションハンドラ |
| CommandPalette.h | `src/cascadia/TerminalApp/CommandPalette.h` | ヘッダー | コマンドパレットクラス定義 |
| CommandPalette.cpp | `src/cascadia/TerminalApp/CommandPalette.cpp` | ソース | コマンドパレット実装 |
| CommandPalette.xaml | `src/cascadia/TerminalApp/CommandPalette.xaml` | XAML | コマンドパレットUIレイアウト |
| CommandPalette.idl | `src/cascadia/TerminalApp/CommandPalette.idl` | IDL | WinRTインターフェース定義 |
| FilteredCommand.cpp | `src/cascadia/TerminalApp/FilteredCommand.cpp` | ソース | フィルタリング済みコマンド |
| CommandPaletteItems.cpp | `src/cascadia/TerminalApp/CommandPaletteItems.cpp` | ソース | パレットアイテム生成 |
| PaletteItemTemplateSelector.cpp | `src/cascadia/TerminalApp/PaletteItemTemplateSelector.cpp` | ソース | テンプレート選択 |
| ActionArgs.h | `src/cascadia/TerminalSettingsModel/ActionArgs.h` | ヘッダー | ToggleCommandPaletteArgs定義 |
