# 機能設計書 11-Leaderキーマッピング

## 概要

本ドキュメントは、space-vimにおけるLeaderキーマッピング機能の設計仕様を記述する。SPCキー（スペースキー）をリーダーキーとして使用し、ニーモニックなキーバインディング体系を提供する機能である。

### 本機能の処理概要

Leaderキーマッピング機能は、Spacemacsのキーバインディング哲学を踏襲し、SPCキーを起点とした階層的なキーバインディング体系を実現する。vim-which-keyプラグインと連携して、SPCキー押下後に利用可能なキーバインディングをポップアップ表示する。

**業務上の目的・背景**：Vimの標準的なキーバインディングは覚えにくく、特に初心者にとっては学習コストが高い。Leaderキーマッピングは、ニーモニック（記憶術的）なキー配置を提供することで、ユーザーがコマンドを直感的に発見・実行できる環境を提供する。例えば「SPC f s」で「file save」、「SPC w d」で「window delete」のように、キーと機能が論理的に対応している。

**機能の利用シーン**：
- Vim操作時に頻繁に使用する機能へ素早くアクセスしたい場合
- 利用可能なキーバインディングを確認しながら操作したい場合
- Spacemacs風のワークフローでVimを使用したい場合
- 複数のプラグイン機能を統一的なキー体系で操作したい場合

**主要な処理内容**：
1. SPCキー（スペースキー）をリーダーキーとして設定
2. `g:spacevim#map#leader#desc`辞書でキーマッピング定義を管理
3. vim-which-keyにキーマッピング辞書を登録してポップアップ表示を実現
4. 各プレフィックスグループ（b:バッファ、w:ウィンドウ、f:ファイル等）ごとにサブコマンドを定義
5. ノーマルモードおよびビジュアルモード用の別々のマッピングを提供

**関連システム・外部連携**：
- vim-which-key：キーバインディングのポップアップ表示
- fzf/vim-clap：ファジーファインダー連携
- vim-fugitive：Git操作連携
- NERDTree：ファイルツリー連携
- EasyMotion：ジャンプ操作連携

**権限による制御**：本機能に権限制御は存在しない。すべてのユーザーが同一のキーバインディングを使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Which-Key（キーバインド表示画面） | 補助機能 | SPCキーをリーダーキーとしたニーモニックキーバインディング |

## 機能種別

キーバインディング管理 / イベントディスパッチ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:spacevim_leader | String | No | リーダーキーのカスタマイズ | デフォルト: `<Space>` |
| g:spacevim#map#leader#desc | Dictionary | Yes | キーマッピング定義辞書 | 必須キーが定義されていること |

### 入力データソース

- `~/.spacevim`ファイル：ユーザーカスタマイズ設定
- `core/autoload/spacevim/map/leader.vim`：デフォルトマッピング定義

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| キーバインディング | Vim mapping | SPCキーを起点とした各種コマンドマッピング |
| which-key辞書 | Dictionary | ポップアップ表示用のキー説明辞書 |

### 出力先

- Vimのキーマッピング空間（ノーマルモード、ビジュアルモード）
- vim-which-keyプラグインのレジストリ

## 処理フロー

### 処理シーケンス

```
1. space-vim初期化（spacevim#begin()）
   └─ ~/.spacevimファイルを読み込み、g:spacevim_leaderを取得
2. リーダーキー設定
   └─ g:mapleader = g:spacevim_leader（デフォルト: "<Space>"）
3. キーマッピング辞書初期化
   └─ core/autoload/spacevim/map/leader.vimで s:leader_map を定義
4. プレフィックスグループ定義
   └─ a:align, b:buffer, c:cscope, e:errors, f:files, g:git, h:help,
      j:jump, l:lsp, p:projects, s:search, t:toggle, w:windows, x:text
5. vim-which-key連携
   └─ spacevim#autocmd#which_key#Init()でwhich_key#register()を呼び出し
6. keybindings.vimでの実キーマッピング設定
   └─ nnoremap <silent> <leader> :<c-u>WhichKey '<Space>'<CR>
```

### フローチャート

```mermaid
flowchart TD
    A[space-vim起動] --> B[spacevim#begin]
    B --> C{~/.spacevim存在?}
    C -->|Yes| D[g:spacevim_leader読み込み]
    C -->|No| E[デフォルト設定使用]
    D --> F[g:mapleader設定]
    E --> F
    F --> G[leader.vim読み込み]
    G --> H[s:leader_map辞書定義]
    H --> I[各プレフィックスグループ定義]
    I --> J[which-keyレイヤー読み込み]
    J --> K[which_key#register呼び出し]
    K --> L[keybindings.vim読み込み]
    L --> M[SPCキーマッピング完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトリーダーキー | SPCキー（スペースキー）をリーダーキーとする | g:spacevim_leaderが未定義の場合 |
| BR-002 | ニーモニック原則 | キーバインディングは機能を想起させる文字で構成 | 全キーマッピング定義時 |
| BR-003 | 階層構造 | SPC + プレフィックス + アクションの階層構造を維持 | 全キーマッピング定義時 |
| BR-004 | which-key連携必須 | which-keyレイヤーが有効な場合、ポップアップ表示を行う | which-keyレイヤーが読み込まれている場合 |

### 計算ロジック

該当なし（キーマッピングは静的定義）

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

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 警告 | ~/.spacevimファイルが存在しない | エラーメッセージ表示後、spacevim#cache#init()を呼び出し |
| - | 警告 | which-keyレイヤーが未読込 | ポップアップなしでキーマッピングのみ動作 |

### リトライ仕様

該当なし

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

該当なし（データベース操作なし）

## パフォーマンス要件

- キーマッピング定義の読み込みは起動時に1回のみ実行
- which-keyポップアップ表示は即時表示（遅延なし）

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

該当なし（ローカルVim操作のみ）

## 備考

- Spacemacsのキーバインディング哲学を踏襲
- キーマッピングは`g:spacevim#map#leader#desc`を通じてカスタマイズ可能
- ビジュアルモード用のマッピングは`g:spacevim#map#leader#desc_visual`で別途定義

---

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

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

### 推奨読解順序

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

キーマッピング定義のデータ構造を理解することが最初のステップ。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | leader.vim | `core/autoload/spacevim/map/leader.vim` | s:leader_map辞書の構造を理解する |

**読解のコツ**: Vim Scriptの辞書（Dictionary）構造に慣れておく。各キーは単一文字（例: 'b', 'f', 'w'）で、値は文字列またはネストした辞書。

**主要データ構造**:
- **2行目**: `let s:leader_map = {}` - ルート辞書の初期化
- **5-8行目**: ウィンドウ番号（1-9）の動的生成
- **30-50行目**: バッファ操作プレフィックス 'b' の定義
- **72-91行目**: ファイル操作プレフィックス 'f' の定義
- **181-201行目**: ウィンドウ操作プレフィックス 'w' の定義

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

リーダーキー設定の起点を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | spacevim.vim | `core/autoload/spacevim.vim` | g:mapleader設定箇所を確認 |
| 2-2 | keybindings.vim | `layers/+distributions/better-defaults/keybindings.vim` | 実際のキーマッピング定義 |

**主要処理フロー**:
- **60行目（spacevim.vim）**: `let g:mapleader = get(g:, 'spacevim_leader', "\<Space>")` - リーダーキー設定
- **1-2行目（keybindings.vim）**: `nnoremap <silent> <leader> :<c-u>WhichKey '<Space>'<CR>` - which-key連携

#### Step 3: which-key連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | which_key.vim | `core/autoload/spacevim/autocmd/which_key.vim` | which-keyへの辞書登録処理 |
| 3-2 | config.vim | `layers/+vim/which-key/config.vim` | which-keyレイヤーの設定 |

**主要処理フロー**:
- **2行目（which_key.vim）**: `call which_key#register('<Space>', 'g:spacevim#map#leader#desc', 'n')` - ノーマルモード登録
- **3行目（which_key.vim）**: `call which_key#register(',', 'g:spacevim#map#localleader#desc', 'n')` - LocalLeader登録

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

```
spacevim#bootstrap()
    │
    ├─ spacevim#begin()
    │      ├─ s:check_dot_spacevim()
    │      │      └─ g:mapleader 設定（60行目）
    │      └─ s:cache()
    │
    └─ spacevim#end()
           ├─ s:register_plugin()
           ├─ s:config()
           │      └─ layers/+vim/which-key/config.vim 読み込み
           │             └─ spacevim#autocmd#which_key#Init()
           │                    └─ which_key#register()
           └─ layers/+distributions/better-defaults/keybindings.vim 読み込み
                  └─ nnoremap <leader> WhichKey
```

### データフロー図

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

~/.spacevim ─────────────────▶ spacevim#begin() ─────────────────▶ g:mapleader設定
(g:spacevim_leader)                    │
                                       ▼
leader.vim ──────────────────▶ s:leader_map辞書定義 ─────────────▶ g:spacevim#map#leader#desc
(キーマッピング定義)                   │
                                       ▼
which_key.vim ───────────────▶ which_key#register() ─────────────▶ Which-Keyポップアップ
(辞書登録処理)                         │
                                       ▼
keybindings.vim ─────────────▶ nnoremap <leader> ────────────────▶ SPCキー応答
(キーマッピング)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| leader.vim | `core/autoload/spacevim/map/leader.vim` | ソース | Leaderキーマッピング辞書定義 |
| spacevim.vim | `core/autoload/spacevim.vim` | ソース | g:mapleader設定・初期化 |
| which_key.vim | `core/autoload/spacevim/autocmd/which_key.vim` | ソース | which-key辞書登録 |
| keybindings.vim | `layers/+distributions/better-defaults/keybindings.vim` | ソース | 実キーマッピング定義 |
| config.vim | `layers/+vim/which-key/config.vim` | 設定 | which-keyレイヤー設定 |
| packages.vim | `layers/+vim/which-key/packages.vim` | 設定 | which-keyプラグイン登録 |
