# 画面設計書 4-Vertico

## 概要

本ドキュメントは、Doom Emacsの垂直補完インターフェース（Vertico）の設計仕様を定義する。

### 本画面の処理概要

Verticoは、ミニバッファ内で垂直リスト形式の補完候補を表示し、様々なコマンド（ファイル選択、コマンド実行、バッファ切り替え等）のインタラクティブな選択を提供する。

**業務上の目的・背景**：
Verticoは、Emacs標準のミニバッファ補完を強化し、ユーザーが候補を視覚的に確認しながら素早く選択できるようにする。consult、marginalia、orderless、embarkなどの周辺パッケージとの連携により、高度な検索・絞り込み・アクション実行が可能になる。Ivy/Helmの代替として、より軽量でEmacs標準APIに準拠したモダンな補完フレームワークを提供する。

**画面へのアクセス方法**：
- 任意の補完を要するコマンド実行時（M-x, find-file, switch-buffer等）
- `SPC f f`（find-file）、`SPC b b`（switch-buffer）等のキーバインド
- `SPC s p`（プロジェクト検索）等

**主要な操作・処理内容**：
1. 補完候補の垂直リスト表示
2. 絞り込み検索（orderlessによるスペース区切りマルチパターン検索）
3. 候補のプレビュー（consultによるライブプレビュー）
4. 候補へのアクション実行（embarkによるコンテキストアクション）
5. 検索結果の書き出し（embark-exportによるwgrepバッファ等への変換）

**画面遷移**：
- 遷移元：コマンド実行、キーバインド
- 遷移先：選択した候補に対応するバッファ/ファイル/動作

**権限による表示制御**：
- 権限による表示制御は存在しない

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | 入力補完インターフェース（Vertico） | 主機能 | 補完候補の垂直表示、ナビゲーション、選択 |
| 47 | ミニバッファ補完 | 補助機能 | ミニバッファでの補完表示基盤 |
| 3 | コマンドパレット | 補助機能 | M-xでのコマンド選択 |
| 7 | プロジェクト管理 | 補助機能 | プロジェクト内ファイル検索・選択 |
| 50 | ファイル検索 | 補助機能 | consult-fd、consult-ripgrepによる検索 |

## 画面種別

ミニバッファ補完インターフェース

## URL/ルーティング

Emacsアプリケーションのため、URLルーティングは存在しない。ミニバッファ領域で動作する。

## 入出力項目

| 項目名 | 種別 | 必須 | 説明 |
|--------|------|------|------|
| 検索パターン | 入力 | いいえ | 候補を絞り込むためのテキスト入力（スペース区切りで複数パターン指定可能） |

## 表示項目

| 項目名 | 種別 | 説明 |
|--------|------|------|
| プロンプト | テキスト | コマンドの説明（例："Find file:"） |
| 候補リスト | 垂直リスト | 絞り込まれた候補の一覧表示 |
| マージナリア | テキスト | 各候補の付加情報（ファイルサイズ、日時、関数説明等） |
| カーソル位置 | ハイライト | 現在選択中の候補 |
| 候補数 | テキスト | 現在の候補数/全候補数 |

## イベント仕様

### 1-ナビゲーション

| キー | 動作 |
|------|------|
| C-n, 下矢印 | 次の候補へ移動 |
| C-p, 上矢印 | 前の候補へ移動 |
| M-< | 最初の候補へ移動 |
| M-> | 最後の候補へ移動 |
| C-M-n | 次のグループへ移動 |
| C-M-p | 前のグループへ移動 |

### 2-選択・確定

| キー | 動作 |
|------|------|
| RET | 選択中の候補を確定 |
| TAB | ディレクトリを展開/補完挿入 |
| C-RET | 入力テキストをそのまま確定 |
| C-q | 補完をキャンセル |

### 3-Embarkアクション

| キー | 動作 |
|------|------|
| C-; | embark-act（候補へのアクションメニュー表示） |
| C-c C-o | embark-export（検索結果を別バッファに書き出し） |

### 4-Consultプレビュー

| キー | 動作 |
|------|------|
| C-SPC | embark-preview / enter-or-preview |

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

本画面はEmacs UI機能であり、データベースとの連携は存在しない。

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| なし | - | - | データベース操作なし |

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容 |
|---------------|---------|---------------|
| エラー | ripgrepが見つからない | "Couldn't find ripgrep in your PATH" |
| 情報 | 候補なし | ミニバッファに候補が表示されない状態 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ripgrepがインストールされていない | エラーメッセージを表示 |
| fd >= 8.6.0でない場合 | consult-findにフォールバック |
| 検索候補が0件 | 空のリストを表示 |

## 備考

- orderlessにより、スペース区切りの複数パターンでAND検索が可能
- marginaliaにより、候補に追加情報（ファイルサイズ、説明文等）が表示される
- embark連携により、候補に対してコンテキストメニュー的なアクションが実行可能
- consultにより、様々なソース（ファイル、バッファ、行、grep結果等）に対する統一的な検索インターフェースを提供

---

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

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

### 推奨読解順序

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

Verticoと関連パッケージの設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/completion/vertico/config.el` | 行7-8: vertico-mode有効化 |
| 1-2 | config.el | `modules/completion/vertico/config.el` | 行10-17: vertico設定変数 |

**読解のコツ**: `vertico-count`（表示候補数）、`vertico-scroll-margin`（スクロールマージン）が重要な設定。

#### Step 2: 補完スタイルを理解する

orderlessによる絞り込みパターンの設定を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/completion/vertico/config.el` | 行67-79: orderless設定 |
| 2-2 | autoload/vertico.el | `modules/completion/vertico/autoload/vertico.el` | 行246-269: orderless-dispatch関数 |

**主要処理フロー**:
1. **行67-79**: completion-styles-alistに'+vertico-basic-remote'を追加
2. **行246-269**: プレフィックス/サフィックスでの絞り込みスタイル指定（`!`, `=`, `@`, `%`等）

#### Step 3: Consultsによる検索を理解する

consultの各種検索コマンドと設定を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/completion/vertico/config.el` | 行82-130: consult設定 |
| 3-2 | autoload/vertico.el | `modules/completion/vertico/autoload/vertico.el` | 行8-59: +vertico-file-search関数 |

**主要処理フロー**:
- **行82-130**: consult-ripgrep-args、consult-fd-args等のカスタマイズ
- **行8-59**: ripgrepを使用したファイル検索の実装

#### Step 4: Embark連携を理解する

embarkによるアクション実行機能を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/completion/vertico/config.el` | 行132-180: embark設定 |
| 4-2 | autoload/vertico.el | `modules/completion/vertico/autoload/vertico.el` | 行93-122: embark関連コマンド |

**主要処理フロー**:
- **行132-180**: embark-indicatorsの設定、キーバインド
- **行93-122**: embark-export-write、embark-preview等のラッパーコマンド

#### Step 5: Marginalia連携を理解する

marginaliaによる候補への注釈表示を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | config.el | `modules/completion/vertico/config.el` | 行55-65: marginalia設定 |

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

```
ユーザー入力（M-x, SPC f f等）
    │
    ├─ vertico-mode
    │      └─ 候補の垂直リスト表示
    │
    ├─ orderless
    │      └─ 複数パターンによる絞り込み
    │
    ├─ marginalia
    │      └─ 候補への注釈追加
    │
    ├─ consult（検索系コマンド時）
    │      ├─ consult-line（バッファ内検索）
    │      ├─ consult-ripgrep（プロジェクト検索）
    │      └─ consult-fd（ファイル検索）
    │
    └─ embark（C-;押下時）
           ├─ embark-act（アクションメニュー）
           └─ embark-export（結果エクスポート）
```

### データフロー図

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

検索パターン ────────▶ orderless ───────────▶ 絞り込まれた候補

候補リスト ─────────▶ marginalia ────────────▶ 注釈付き候補表示

候補選択 + C-; ─────▶ embark-act ────────────▶ アクションメニュー

grep結果 + C-c C-o ─▶ embark-export ─────────▶ wgrepバッファ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/completion/vertico/config.el` | ソース | メイン設定 |
| autoload/vertico.el | `modules/completion/vertico/autoload/vertico.el` | ソース | 検索・embark関連コマンド |
| autoload/evil.el | `modules/completion/vertico/autoload/evil.el` | ソース | Evil連携 |
| autoload/workspaces.el | `modules/completion/vertico/autoload/workspaces.el` | ソース | ワークスペース連携 |
| vertico | 外部パッケージ | 依存 | 垂直補完本体 |
| consult | 外部パッケージ | 依存 | 検索コマンド群 |
| marginalia | 外部パッケージ | 依存 | 候補注釈 |
| orderless | 外部パッケージ | 依存 | 絞り込みスタイル |
| embark | 外部パッケージ | 依存 | アクション実行 |
| embark-consult | 外部パッケージ | 依存 | consult-embark連携 |
