# 画面設計書 2-Which-Key（キーバインド表示画面）

## 概要

本ドキュメントは、space-vimにおけるWhich-Key（キーバインド表示画面）の画面設計について記載する。Which-Keyはvim-which-keyプラグインにより提供されるキーバインドガイド表示機能であり、リーダーキー（SPCまたは`,`）押下後に利用可能なキーバインドをポップアップ形式で表示する。

### 本画面の処理概要

**業務上の目的・背景**：space-vimはEmacs Spacemacsに影響を受けたニーモニックキーバインディングシステムを採用しており、多数のキーバインドが階層的に定義されている。開発者がすべてのキーバインドを記憶することは困難であるため、リーダーキー押下後に利用可能なキーバインドをリアルタイムで表示することで、発見性（discoverability）を高め、学習コストを低減する。これにより、新規ユーザーでもspace-vimの豊富な機能に素早くアクセスできるようになる。

**画面へのアクセス方法**：以下の方法でWhich-Key画面にアクセスできる。
- `SPC`キー（スペースキー）押下：Leaderキーバインド一覧表示
- `,`キー押下：LocalLeaderキーバインド一覧表示（言語固有機能）

**主要な操作・処理内容**：
1. リーダーキー押下後、一定時間（timeoutlen）経過でWhich-Keyポップアップが表示される
2. 表示されたキーに続けてキーを押下することで、サブメニューに遷移または機能を実行
3. `ESC`キーでキャンセルして元の状態に戻る
4. 階層的なキーバインド（例：`SPC f`でファイル操作メニュー）をナビゲーション

**画面遷移**：
- エディタ画面 -> `SPC`押下 -> Which-Key画面
- Which-Key画面 -> キー押下 -> サブメニュー（Which-Key）または機能実行
- Which-Key画面 -> `ESC` -> エディタ画面

**権限による表示制御**：特になし。すべてのユーザーが同一の機能を利用可能。ただし、ロードされているレイヤーに応じて表示されるキーバインドは異なる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 78 | which-key | 主機能 | SPCキー押下後に利用可能なキーバインドをポップアップ表示 |
| 11 | Leaderキーマッピング | 補助機能 | SPCキーをリーダーキーとしたニーモニックキーバインディング |
| 12 | LocalLeaderキーマッピング | 補助機能 | カンマキーをローカルリーダーとした言語固有キーバインディング |

## 画面種別

ポップアップ / モーダル

## URL/ルーティング

- Leaderキー: `<Space>`（SPCキー）
- LocalLeaderキー: `,`（カンマキー）
- 起動コマンド: `:WhichKey '<Space>'`、`:WhichKey ','`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|---------|------|
| g:spacevim#map#leader#desc | 入力（設定） | Dictionary | Leaderキーバインドの定義辞書 |
| g:spacevim#map#localleader#desc | 入力（設定） | Dictionary | LocalLeaderキーバインドの定義辞書 |
| g:spacevim#map#leader#desc_visual | 入力（設定） | Dictionary | ビジュアルモード用Leaderキーバインド定義 |
| g:spacevim#map#localleader#desc_visual | 入力（設定） | Dictionary | ビジュアルモード用LocalLeaderキーバインド定義 |
| キー入力 | 入力 | Key | ユーザーが押下したキー |
| キーバインド一覧 | 出力 | String | 利用可能なキーバインドと説明の一覧 |

## 表示項目

| 項目 | 表示内容 | 説明 |
|-----|---------|------|
| キー | 次に押下可能なキー | 英字、数字、記号など |
| 説明 | キーバインドの機能説明 | 例：「+buffers」「+files」 |
| カテゴリ | キーバインドのグループ名 | +プレフィックスで表示 |

## イベント仕様

### 1-Leaderキー押下（ノーマルモード）

`<Space>`キー押下時、`WhichKey '<Space>'`コマンドが実行され、Leaderキーバインド一覧がポップアップ表示される。

### 2-Leaderキー押下（ビジュアルモード）

ビジュアルモードで`<Space>`キー押下時、`WhichKeyVisual '<Space>'`コマンドが実行され、ビジュアルモード用Leaderキーバインド一覧が表示される。

### 3-LocalLeaderキー押下（ノーマルモード）

`,`キー押下時、`WhichKey ','`コマンドが実行され、LocalLeaderキーバインド一覧がポップアップ表示される。

### 4-サブメニュー遷移

表示されたキーに続けてキーを押下すると、そのキーに対応するサブメニューまたは機能が実行される。例：`SPC f`押下で「+files」サブメニューが表示される。

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

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

該当なし（キーバインド定義辞書のみ使用）

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|---------|
| 情報 | キーバインド一覧 | ポップアップ表示時 |
| 情報 | カテゴリ名（+buffers等） | グループキー表示時 |

## 例外処理

| 状態 | 処理 |
|------|------|
| 未定義キー押下 | 何も起こらない、またはエラービープ |
| タイムアウト | Which-Keyポップアップが閉じる |
| vim-which-keyプラグイン未ロード | 通常のキー入力として処理される |

## 備考

- vim-which-keyプラグインは`liuchengxu/vim-which-key`により提供される
- 遅延読み込み（on-demand loading）が有効であり、`WhichKey`コマンド実行時にプラグインがロードされる
- キーバインド定義は各レイヤーのconfig.vimで行われ、`spacevim#autocmd#which_key#Init()`で登録される
- `timeoutlen`オプションの値によりポップアップ表示までの待機時間が決まる

---

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

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

### 推奨読解順序

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

Which-Keyのキーバインド定義辞書の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | which_key.vim | `core/autoload/spacevim/autocmd/which_key.vim` | キーバインド辞書の登録処理を確認 |

**読解のコツ**: `which_key#register()`関数に渡される引数（キー、辞書名、モード）の関係を理解する。`g:spacevim#map#leader#desc`などの辞書がキーバインド定義の中心である。

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

プラグインのロードとキーマッピングの設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | packages.vim | `layers/+vim/which-key/packages.vim` | プラグイン登録と自動初期化を確認 |
| 2-2 | config.vim | `layers/+vim/which-key/config.vim` | キーマッピング設定を確認 |

**主要処理フロー**:
1. **packages.vim 1行目**: vim-which-keyプラグインの登録（遅延読み込み）
2. **packages.vim 2行目**: `User vim-which-key`イベントで初期化関数を登録
3. **config.vim 1-2行目**: `<leader>`キーのノーマル/ビジュアルモードマッピング
4. **config.vim 4-5行目**: `<localleader>`キーのノーマル/ビジュアルモードマッピング

#### Step 3: 初期化処理を理解する

Which-Keyの初期化処理でキーバインド辞書がどのように登録されるかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | which_key.vim | `core/autoload/spacevim/autocmd/which_key.vim` | `spacevim#autocmd#which_key#Init()`関数の処理内容 |

**主要処理フロー**:
- **2行目**: `<Space>`キーのノーマルモード用辞書登録
- **3行目**: `,`キーのノーマルモード用辞書登録
- **4行目**: `<Space>`キーのビジュアルモード用辞書登録
- **5行目**: `,`キーのビジュアルモード用辞書登録

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

```
<Space>キー押下 (nnoremap)
    │
    └─ :WhichKey '<Space>' コマンド
           │
           ├─ vim-which-key プラグインロード（初回のみ）
           │       │
           │       └─ User vim-which-key (autocmd)
           │              │
           │              └─ spacevim#autocmd#which_key#Init()
           │                     │
           │                     ├─ which_key#register('<Space>', 'g:spacevim#map#leader#desc', 'n')
           │                     ├─ which_key#register(',', 'g:spacevim#map#localleader#desc', 'n')
           │                     ├─ which_key#register('<Space>', 'g:spacevim#map#leader#desc_visual', 'v')
           │                     └─ which_key#register(',', 'g:spacevim#map#localleader#desc_visual', 'v')
           │
           └─ Which-Key ポップアップ表示
                  │
                  └─ キー入力待機 -> サブメニュー/機能実行
```

### データフロー図

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

<Space>キー押下 ──────▶ config.vim ───────────────▶ WhichKeyコマンド
                        (キーマッピング)

vim-which-key ────────▶ which_key#Init() ─────────▶ 辞書登録
プラグインロード          (初期化処理)

g:spacevim#map#... ───▶ vim-which-key ────────────▶ ポップアップ表示
(キーバインド辞書)        (表示処理)

後続キー入力 ─────────▶ vim-which-key ────────────▶ 機能実行/サブメニュー
                        (キー処理)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+vim/which-key/packages.vim` | ソース | プラグイン登録・自動初期化設定 |
| config.vim | `layers/+vim/which-key/config.vim` | ソース | キーマッピング設定 |
| which_key.vim | `core/autoload/spacevim/autocmd/which_key.vim` | ソース | 初期化処理・辞書登録 |
| vim-which-key | 外部プラグイン（liuchengxu/vim-which-key） | プラグイン | Which-Key本体機能 |
