# 機能設計書 81-emoji

## 概要

本ドキュメントは、space-vimの絵文字サポート機能（emoji）の設計について記述する。この機能は、Markdownファイル編集時に絵文字の自動補完を提供する。

### 本機能の処理概要

**業務上の目的・背景**：Markdownドキュメント作成時に絵文字を活用することで、ドキュメントの視覚的な表現力を高め、コミュニケーションを円滑にする。GitHubのIssueやPull Request、READMEファイルなどで絵文字が広く使われている現状に対応し、Vim上でも効率的に絵文字を入力できる環境を提供する。

**機能の利用シーン**：GitHubのREADME.mdやCHANGELOG.md作成時、Issue/PRコメント執筆時、技術ブログ記事執筆時など、Markdownファイルを編集する際に絵文字を素早く入力したい場面で利用される。

**主要な処理内容**：
1. `+fun/emoji`レイヤーの有効化によりvim-emojiプラグインをロード
2. Markdownファイルタイプ検出時にemoji補完関数を`completefunc`に設定
3. ユーザーがコロン(`:`)を入力後、`Ctrl-x Ctrl-u`で補完候補を表示
4. 選択した絵文字名が実際の絵文字文字に変換される

**関連システム・外部連携**：junegunn/vim-emojiプラグインとの連携。補完システム（deoplete、ncm2等）との統合も可能。

**権限による制御**：特になし。レイヤーが有効化されていればすべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | 補完ポップアップ | 主画面 | 絵文字補完候補の表示 |

## 機能種別

入力支援 / 自動補完

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| findstart | Number | Yes | 補完開始位置取得モード(1)または補完候補取得モード(0) | 0または1 |
| base | String | No | 補完の基準文字列（コロン以降の文字列） | 任意の文字列 |

### 入力データソース

- ユーザーのキーボード入力（Markdownファイル内でのコロン+文字入力）
- vim-emojiプラグインが提供する絵文字データベース

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 補完候補リスト | List | 絵文字名と絵文字文字のペアのリスト |
| 選択絵文字 | String | ユーザーが選択した絵文字文字（UTF-8） |

### 出力先

- Vimの補完ポップアップウィンドウ
- 編集中のバッファ（選択確定後）

## 処理フロー

### 処理シーケンス

```
1. レイヤー有効化
   └─ ~/.spacevimでLayer 'emoji'を設定
2. プラグインロード
   └─ vim-plugがjunegunn/vim-emojiをMarkdownファイルタイプ用にロード
3. ftplugin適用
   └─ core/ftplugin/markdown.vimが実行され、emoji#complete関数が存在すれば
      completefuncに設定
4. 補完トリガー
   └─ ユーザーがCtrl-x Ctrl-uを押下
5. 補完候補表示
   └─ emoji#complete関数が呼び出され、候補リストをポップアップ表示
6. 選択確定
   └─ ユーザーが候補を選択し、絵文字がバッファに挿入
```

### フローチャート

```mermaid
flowchart TD
    A[Markdownファイルを開く] --> B{emojiレイヤー有効?}
    B -->|Yes| C[vim-emojiプラグインロード]
    B -->|No| Z[通常編集]
    C --> D[completefunc設定]
    D --> E[編集開始]
    E --> F{Ctrl-x Ctrl-u押下?}
    F -->|Yes| G[emoji#complete呼び出し]
    F -->|No| E
    G --> H[補完候補表示]
    H --> I{候補選択?}
    I -->|Yes| J[絵文字挿入]
    I -->|No| E
    J --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-81-1 | ファイルタイプ制限 | 絵文字補完はMarkdownファイルでのみ有効 | ファイルタイプがmarkdownの場合 |
| BR-81-2 | 遅延ロード | vim-emojiはMarkdownファイルを開いた時のみロード | for: 'markdown'オプション |
| BR-81-3 | 関数存在確認 | emoji#complete関数が存在する場合のみcompletfuncを設定 | exists('*emoji#complete')がtrue |

### 計算ロジック

絵文字補完関数は以下のロジックで動作：
- `findstart=1`の場合：カーソル位置から逆方向にコロン(`:`)を検索し、補完開始位置を返す
- `findstart=0`の場合：`base`文字列に前方一致する絵文字名のリストを返す

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

本機能はデータベース操作を行わない。

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | プラグイン未インストール | vim-emojiがインストールされていない | :PlugInstallを実行 |
| - | レイヤー無効 | emojiレイヤーが有効化されていない | ~/.spacevimでLayer 'emoji'を追加 |
| - | フォント非対応 | 使用フォントが絵文字を表示できない | Nerdフォントまたは絵文字対応フォントをインストール |

### リトライ仕様

リトライは不要。エラー発生時はユーザーが設定を修正して再度操作する。

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

該当なし（ファイルシステムやDBへの永続化を伴わない）

## パフォーマンス要件

- 補完候補の表示は100ms以内
- 絵文字データベースはプラグイン内に静的に保持されるため、外部通信なし

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

- 外部通信を行わないため、セキュリティリスクは最小限
- ユーザー入力は補完候補のフィルタリングにのみ使用

## 備考

- vim-emojiプラグインは`:emoji-name:`形式のGitHub/Slack互換の絵文字ショートコードに対応
- 補完された絵文字はUTF-8文字として挿入されるため、表示にはUTF-8対応ターミナル/フォントが必要

---

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

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

### 推奨読解順序

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

本機能は外部プラグイン（vim-emoji）が提供する絵文字データベースを利用する。space-vim側では特別なデータ構造定義はない。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+fun/emoji/packages.vim` | ロードされるプラグインの確認 |

**読解のコツ**: `MP`マクロはvim-plugの`Plug`コマンドのラッパー。`{ 'for': 'markdown' }`は遅延ロードの指定。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | packages.vim | `layers/+fun/emoji/packages.vim` | プラグイン登録がエントリーポイント |
| 2-2 | markdown.vim | `core/ftplugin/markdown.vim` | Markdownファイルオープン時のcompletefunc設定 |

**主要処理フロー**:
1. **1行目**: `MP 'junegunn/vim-emoji', { 'for': 'markdown' }` - プラグイン登録
2. **44-46行目（markdown.vim）**: `emoji#complete`関数の存在確認とcompletfunc設定

#### Step 3: ftplugin処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | markdown.vim | `core/ftplugin/markdown.vim` | Markdownファイル固有の設定 |

**主要処理フロー**:
- **44行目**: `if exists('*emoji#complete')` - プラグインがロード済みか確認
- **45行目**: `setlocal completefunc=emoji#complete` - 補完関数を設定

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

```
vim起動
    │
    ├─ spacevim#bootstrap()
    │      └─ レイヤー読み込み
    │             └─ layers/+fun/emoji/packages.vim
    │                    └─ vim-plugへプラグイン登録
    │
    └─ Markdownファイルオープン
           └─ vim-plugが遅延ロード実行
                  └─ vim-emojiプラグインロード
           └─ core/ftplugin/markdown.vim
                  └─ completefunc設定
```

### データフロー図

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

ユーザー入力       emoji#complete()                 補完候補
(:smile など)  ──▶  絵文字データベース検索  ──▶  ポップアップ表示
                                                           │
候補選択       ──────────────────────────────────▶  バッファに挿入
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+fun/emoji/packages.vim` | ソース | プラグイン登録 |
| config.vim | `layers/+fun/emoji/config.vim` | ソース | 設定（現在空） |
| README.md | `layers/+fun/emoji/README.md` | ドキュメント | レイヤー説明 |
| markdown.vim | `core/ftplugin/markdown.vim` | ソース | completefunc設定 |
