# 画面設計書 5-コマンドパレット

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータのコマンドパレット画面の設計について記載する。コマンドパレットは、VSCode風のコマンド検索・実行インターフェースを提供するオーバーレイ画面である。

### 本画面の処理概要

コマンドパレットは、ユーザーがキーボードだけで素早くコマンドを検索・実行できるインターフェースを提供する。

**業務上の目的・背景**：メニューバーやキーボードショートカットを覚えていなくても、テキスト入力でコマンドを検索・実行できるようにする。開発者に馴染みのあるVSCode風のUIを採用し、直感的な操作を可能にする。

**画面へのアクセス方法**：
- Cmd+Shift+P（デフォルトキーバインド）
- メニューバーから「View > Command Palette」を選択

**主要な操作・処理内容**：
1. コマンドの検索（インクリメンタルサーチ）
2. 上下キーによるコマンドの選択
3. Enterによるコマンドの実行
4. ESCまたはフォーカス喪失による閉じる
5. 色名による検索（テーマ選択時）
6. キーボードショートカットの表示

**画面遷移**：
- ターミナル画面 → コマンドパレット（オーバーレイ表示）
- コマンド実行/ESC → コマンドパレット閉じる → ターミナル画面

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 87 | コマンドパレット | 主機能 | コマンド検索・実行のためのパレット表示 |
| 19 | キーバインド | 補助機能 | キーボードショートカットの表示 |
| 42 | テーマ | 遷移先機能 | テーマ選択コマンドの実行 |
| 89 | アップデート確認 | 遷移先機能 | アップデート確認コマンドの実行 |

## 画面種別

オーバーレイ検索・実行画面

## URL/ルーティング

N/A（ネイティブデスクトップアプリケーション）

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| 検索クエリ | 入力 | String | - | コマンド検索テキスト |
| isPresented | 入力/出力 | Bool | はい | パレット表示状態 |
| options | 入力 | [CommandOption] | はい | 表示するコマンドオプション一覧 |
| backgroundColor | 設定 | Color | - | 背景色（ターミナルと合わせる） |

## 表示項目

| 項目名 | 表示位置 | データ型 | 説明 |
|--------|----------|----------|------|
| 検索フィールド | 上部 | TextField | "Execute a command..." プレースホルダー |
| コマンドリスト | 下部 | ScrollView | フィルタリングされたコマンド一覧 |
| 選択ハイライト | リスト内 | View | 選択中のコマンドのハイライト |
| ショートカット表示 | 各行右 | Text | キーボードショートカット記号 |
| リーディングアイコン | 各行左 | Image | コマンドのアイコン（オプション） |
| リーディングカラー | 各行左 | Circle | 色インジケーター（テーマ等） |
| バッジ | 各行右 | Text | バッジテキスト（オプション） |

## イベント仕様

### 1-パレット表示

Cmd+Shift+Pが押下されると、以下の処理が実行される：

1. `commandPaletteIsShowing`がtrueに設定される
2. TerminalCommandPaletteViewがオーバーレイ表示される
3. テキストフィールドにフォーカスが設定される
4. コマンドオプション一覧が表示される

### 2-検索入力

検索フィールドにテキストが入力されると、以下の処理が実行される：

1. `query`変数が更新される
2. `filteredOptions`が再計算される（タイトル/サブタイトル/色名でフィルタリング）
3. クエリが空でない場合、最初の項目が自動選択される
4. 色名に一致する場合、色の近さでソートされる

### 3-キーボードナビゲーション

上下キーまたはCtrl+P/Ctrl+Nで選択が移動する：

1. `.move(.up)`または`.move(.down)`イベントが発行される
2. `selectedIndex`が更新される
3. 選択がリストの端に達するとループする
4. ScrollViewReader.scrollToで選択項目を可視化

### 4-コマンド実行

Enterキーまたはクリックでコマンドが実行される：

1. `.submit`イベントが発行される
2. `isPresented`がfalseに設定される
3. `selectedOption?.action()`が呼び出される
4. 対象サーフェスに対してアクションが実行される

### 5-パレット閉じる

ESCキーまたはフォーカス喪失でパレットが閉じる：

1. `.exit`イベントが発行される
2. `isPresented`がfalseに設定される
3. パレットが非表示になる
4. ターミナルにフォーカスが戻る

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

N/A（本アプリケーションはデータベースを使用しない）

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| MSG001 | プレースホルダー | "Execute a command..." | 検索フィールドが空の時 |
| MSG002 | 情報 | "No matches" | 検索結果が0件の時 |

## 例外処理

| 例外状況 | 処理内容 |
|----------|----------|
| オプションが空 | "No matches"を表示 |
| 検索結果なし | "No matches"を表示 |

## 備考

- 背景色はターミナルの背景色に合わせて調整される
- ultraThinMaterialとブレンドモードで半透明効果
- 角丸（10pt）とシャドウで浮遊感を演出
- 色名検索はNSColorの色名と比較し、近い色を上位にソート
- CommandOptionは各コマンドの情報（タイトル、サブタイトル、アイコン、アクション等）を保持

---

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

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

### 推奨読解順序

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

コマンドオプションの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CommandPalette.swift | `macos/Sources/Features/Command Palette/CommandPalette.swift` | CommandOption構造体（3-58行目） |

**読解のコツ**: CommandOptionは各コマンドの情報を保持。title、subtitle、symbols（ショートカット）、leadingIcon、leadingColor、badge、action（クロージャ）等のプロパティを持つ。

#### Step 2: メインビューを理解する

CommandPaletteViewの構造を理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CommandPalette.swift | `macos/Sources/Features/Command Palette/CommandPalette.swift` | CommandPaletteView構造体（60-229行目） |

**主要処理フロー**:
1. **71-89行目**: filteredOptions - クエリでフィルタリングしたオプション
2. **100-202行目**: body - メインビューの構造
3. **108-134行目**: CommandPaletteQuery - キーイベント処理

#### Step 3: コマンドテーブルを理解する

コマンド一覧の表示とインタラクションを理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CommandPalette.swift | `macos/Sources/Features/Command Palette/CommandPalette.swift` | CommandTable（287-332行目）、CommandRow（335-406行目） |

**主要処理フロー**:
- **299-328行目**: ScrollViewReaderでスクロール制御
- **302-317行目**: ForEachで各オプションを表示

#### Step 4: 呼び出し元を理解する

コマンドパレットがどこから呼び出されるかを理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TerminalView.swift | `macos/Sources/Features/Terminal/TerminalView.swift` | TerminalCommandPaletteView呼び出し（110-117行目） |

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

```
TerminalView
    │
    └─ TerminalCommandPaletteView (オーバーレイ)
           │
           └─ CommandPaletteView
                  │
                  ├─ CommandPaletteQuery (検索入力)
                  │      └─ TextField
                  │
                  ├─ Divider
                  │
                  └─ CommandTable
                         │
                         └─ ScrollView
                                └─ ForEach
                                       └─ CommandRow
                                              ├─ leadingColor (Circle)
                                              ├─ leadingIcon (Image)
                                              ├─ title/subtitle (Text)
                                              ├─ badge (Capsule)
                                              └─ ShortcutSymbolsView
```

### データフロー図

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

検索クエリ ────────────▶ filteredOptions ────────────▶ コマンドリスト更新
                              │
                              ▼
                        localizedCaseInsensitiveContains
                        + colorMatchScore
                              │
                              ▼
                        ソート後のオプション

キーボードイベント ────────▶ onEvent ────────────────────▶ 状態更新
(.up/.down/.submit)           │
                              ▼
                        selectedIndex / isPresented

コマンド選択 ────────────▶ option.action() ───────────▶ 対象サーフェスでアクション実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CommandPalette.swift | `macos/Sources/Features/Command Palette/CommandPalette.swift` | ソース | コマンドパレットのメインビュー |
| TerminalView.swift | `macos/Sources/Features/Terminal/TerminalView.swift` | ソース | コマンドパレットの呼び出し元 |
| BaseTerminalController.swift | `macos/Sources/Features/Terminal/BaseTerminalController.swift` | ソース | commandPaletteIsShowing管理 |
| command_palette.zig | `src/apprt/gtk/class/command_palette.zig` | ソース | GTK版の実装 |
