# 画面設計書 8-補完ポップアップ

## 概要

本ドキュメントは、space-vimにおける補完ポップアップの画面設計について記載する。補完ポップアップはコード入力中に表示される補完候補一覧であり、deoplete、coc.nvim、ncm2、asyncomplete、YouCompleteMe等の複数の補完エンジンに対応している。

### 本画面の処理概要

**業務上の目的・背景**：開発者がコードを効率的に入力できるようにすることが目的である。変数名、関数名、メソッド名などを途中まで入力すると、補完エンジンが候補を提示し、選択することで入力の手間を省くことができる。また、補完候補にはドキュメントや型情報が含まれることもあり、コード品質の向上にも寄与する。

**画面へのアクセス方法**：以下の方法で補完ポップアップが表示される。
- テキスト入力中に自動表示（auto-completion）
- `Ctrl-Space`：手動で補完トリガー（coc.nvim使用時）
- `Tab`キー：補完候補のナビゲーションまたは補完トリガー

**主要な操作・処理内容**：
1. 入力中に自動的に補完候補がポップアップ表示される
2. `Tab`キーまたは`Ctrl-n`で次の候補を選択
3. `Shift-Tab`または`Ctrl-p`で前の候補を選択
4. `Enter`または`Ctrl-y`で選択確定
5. `ESC`または`Ctrl-e`でキャンセル
6. 補完候補のプレビュー表示（対応エンジンのみ）

**画面遷移**：
- エディタ画面（入力中） -> 自動 -> 補完ポップアップ
- 補完ポップアップ -> 候補選択 -> エディタ画面（補完確定）
- 補完ポップアップ -> `ESC` -> エディタ画面（キャンセル）

**権限による表示制御**：特になし。補完ソースに依存する。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 25 | deoplete連携 | 主機能 | deopleteによる非同期補完候補の表示（NeoVim向け） |
| 26 | ncm2連携 | 主機能 | ncm2による補完候補の表示 |
| 27 | asyncomplete連携 | 主機能 | asyncomplete.vimによる補完候補の表示 |
| 28 | YouCompleteMe連携 | 主機能 | YCMによる補完候補の表示 |
| 59 | コードスニペット | 補助機能 | UltiSnipsによるスニペット候補の補完連携 |

## 画面種別

ポップアップ / メニュー

## URL/ルーティング

- 自動トリガー：テキスト入力時
- 手動トリガー：`Ctrl-Space`（coc.nvim）
- 補完オプション：`:h completeopt`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|---------|------|
| completeopt | 入力（設定） | String | 補完オプション（'noinsert,menuone,noselect'） |
| g:mucomplete#enable_auto_at_startup | 入力（設定） | Number | 自動補完有効化 |
| g:ncm2#matcher | 入力（設定） | String | マッチングアルゴリズム |
| 入力テキスト | 入力 | String | ユーザーが入力中のテキスト |
| 補完候補 | 出力 | List | マッチした補完候補一覧 |
| 選択候補 | 出力 | String | 選択された補完テキスト |

## 表示項目

| 項目 | 表示内容 | 説明 |
|-----|---------|------|
| 補完候補テキスト | 補完される文字列 | 候補のテキスト |
| 種別マーク | [F]unction/[M]ethod/[V]ariable等 | 補完候補の種別 |
| ソース | 補完ソース名 | LSP/Snippets等 |
| ドキュメント | 補完候補の説明 | プレビューウィンドウ |

## イベント仕様

### 1-自動補完トリガー

文字入力後、一定時間（`updatetime`）経過で自動的に補完候補が取得・表示される。

### 2-Tabキー補完

`Tab`キー押下時、`spacevim#vim#complete#Tab()`関数が呼ばれ、以下の処理が行われる：
- ポップアップ表示中：次の候補を選択
- 空白の後：通常のTab入力
- それ以外：補完をトリガー

### 3-Enterキー確定

`Enter`キー押下時、`spacevim#vim#complete#CR()`関数が呼ばれ、選択中の候補が確定される。

### 4-coc.nvim補完

coc.nvimが有効かつ`g:spacevim_enable_coc_completion`が1の場合、coc.nvimの補完機能が使用される。

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

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

該当なし（テキスト補完のみ）

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|---------|
| 情報 | 補完候補一覧 | ポップアップ表示時 |
| 情報 | ドキュメントプレビュー | 候補選択時 |

## 例外処理

| 状態 | 処理 |
|------|------|
| 補完候補なし | ポップアップを表示しない |
| 補完エンジン未ロード | 通常入力として処理 |
| LSPサーバー未起動 | 他の補完ソースを使用 |

## 備考

- 補完エンジンは環境に応じて自動選択される
- NeoVim: ncm2 または deoplete
- Vim8: completor.vim
- それ以外: vim-mucomplete
- coc.nvimが有効な場合、coc.nvimの補完機能が優先される
- `completeopt`は`noinsert,menuone,noselect`に設定される
- UltiSnipsとの連携でスニペット候補も補完される

---

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

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

### 推奨読解順序

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

補完設定とキーマッピングを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.vim | `layers/+completion/auto-completion/config.vim` | 補完設定とキーマッピングを確認 |
| 1-2 | complete.vim | `core/autoload/spacevim/vim/complete.vim` | 補完関数の実装を確認 |

**読解のコツ**: `completeopt`設定と`Tab`/`S-Tab`/`CR`のマッピングが補完操作の基本。

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

補完エンジンの選択ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | packages.vim | `layers/+completion/auto-completion/packages.vim` | 補完エンジンの選択ロジックを確認 |

**主要処理フロー**:
1. **4行目**: ncm2の条件判定（NeoVim 0.2.2以上でPython3対応）
2. **18行目**: Vim8の場合はcompletorを使用
3. **38行目**: それ以外はvim-mucompleteを使用

#### Step 3: キーマッピングを理解する

Tab/Enter等のキー操作を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.vim | `layers/+completion/auto-completion/config.vim` | キーマッピング設定 |
| 3-2 | complete.vim | `core/autoload/spacevim/vim/complete.vim` | 補完関数の実装 |

**主要処理フロー**:
- **config.vim 18行目**: `Tab`キーマッピング
- **config.vim 19行目**: `S-Tab`キーマッピング
- **config.vim 20行目**: `CR`（Enter）キーマッピング
- **complete.vim 8-28行目**: `Tab()`関数のcoc.nvim対応分岐

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

```
テキスト入力
    │
    └─ 補完トリガー
           │
           ├─ [coc.nvim有効時]
           │      │
           │      └─ coc#refresh()
           │             │
           │             └─ LSPサーバーへ補完要求
           │
           ├─ [ncm2有効時]
           │      │
           │      └─ ncm2#enable_for_buffer()
           │             │
           │             └─ 各補完ソースから候補取得
           │
           └─ [mucomplete有効時]
                  │
                  └─ mucomplete#enable_auto_at_startup
                         │
                         └─ Vim標準補完機能
```

### データフロー図

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

テキスト入力 ─────────▶ 補完エンジン ────────────▶ 候補取得
                        (coc/ncm2/etc)

補完ソース ───────────▶ マッチング処理 ──────────▶ 候補フィルタ
(LSP/Buffer/etc)        (ファジーマッチ)

Tab/S-Tab ────────────▶ complete#Tab/STab() ──────▶ 候補選択
キー押下                 (選択処理)

Enter/Ctrl-y ─────────▶ complete#CR() ────────────▶ 補完確定
キー押下                 (確定処理)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.vim | `layers/+completion/auto-completion/config.vim` | ソース | 補完設定・キーマッピング |
| packages.vim | `layers/+completion/auto-completion/packages.vim` | ソース | 補完エンジン選択 |
| complete.vim | `core/autoload/spacevim/vim/complete.vim` | ソース | 補完関数実装 |
| coc.vim | `core/autoload/spacevim/plug/coc.vim` | ソース | coc.nvim連携 |
| ncm2 | 外部プラグイン | プラグイン | ncm2補完エンジン |
| deoplete | 外部プラグイン | プラグイン | deoplete補完エンジン |
| coc.nvim | 外部プラグイン | プラグイン | coc.nvim補完エンジン |
