# 機能設計書 77-EasyAlign

## 概要

本ドキュメントは、space-vimの+vim/text-alignレイヤーが提供するvim-easy-alignによる柔軟なテキスト整列機能について、その設計と実装を詳細に記述する。

### 本機能の処理概要

**業務上の目的・背景**：
tabularプラグインがコマンドベースの整列を提供するのに対し、vim-easy-alignはインタラクティブな整列体験を提供する。ユーザーはモーション/テキストオブジェクトを指定した後、対話的に整列パターンを選択できる。これにより、より直感的で柔軟なテキスト整列が可能となる。特に、左揃え・右揃え・中央揃えの切り替えや、区切り文字の何番目で揃えるかなどの高度な制御が容易になる。

**機能の利用シーン**：
- コードブロックを選択してからインタラクティブに整列パターンを選びたい場合
- 左揃え・右揃え・中央揃えを切り替えながら整列したい場合
- 区切り文字の2番目、3番目など特定の位置で揃えたい場合
- SPC x aでクイックに整列を開始したい場合

**主要な処理内容**：
1. vim-easy-alignプラグインの遅延読み込み（EasyAlignコマンドまたはプラグマッピング実行時）
2. ビジュアルモードでの範囲選択 + Leader xaによる整列開始
3. ノーマルモードでのモーション/テキストオブジェクト + Leader xaによる整列開始
4. インタラクティブモードでの整列パターン・オプション選択

**関連システム・外部連携**：
- 外部プラグイン: junegunn/vim-easy-align
- vim-which-keyとの連携（キーバインディングヒント表示）

**権限による制御**：
本機能に権限による制御は存在しない。+vim/text-alignレイヤーを有効化することで全ユーザーが利用可能となる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Which-Key（キーバインド表示画面） | 補助機能 | SPC xキー押下後のキーバインドヒント表示 |

## 機能種別

エディタ補助機能 / テキスト整形

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| 対象範囲 | Range | Yes | 整列対象のテキスト範囲 | ビジュアル選択またはモーション |
| 整列区切り文字 | Char | Yes | 整列に使用する文字 | =, :, ,, |, スペースなど |
| 整列オプション | String | No | 左揃え/右揃え/中央揃え、N番目指定など | 対話入力 |

### 入力データソース

- ユーザーのキーボード入力（Leader xa + インタラクティブ入力）
- ビジュアルモードでの範囲選択
- ノーマルモードでのモーション/テキストオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 整列済みテキスト | String | 指定パターン・オプションで揃えられたテキスト |

### 出力先

- 現在のバッファ（インプレース編集）

## 処理フロー

### 処理シーケンス

```
1. ユーザーがビジュアルモードで範囲選択、またはノーマルモードでLeader xaを押下
   └─ ビジュアル: 選択範囲が対象
   └─ ノーマル: 次のモーション/テキストオブジェクトが対象
2. EasyAlignがインタラクティブモードに入る
   └─ コマンドラインに入力プロンプトが表示
3. 区切り文字を入力（=, :, ,, |, スペースなど）
   └─ オプションで数字（N番目）、*（全て）、</>（左/右揃え）を前置
4. 整列処理が実行される
   └─ バッファ内容が更新
```

### フローチャート

```mermaid
flowchart TD
    A[Leader xa 押下] --> B{モード判定}
    B -->|ビジュアル| C[選択範囲を対象に設定]
    B -->|ノーマル| D[モーション/テキストオブジェクト待ち]
    D --> E[対象範囲を設定]
    C --> F[インタラクティブモード]
    E --> F
    F --> G[区切り文字入力]
    G --> H{オプション?}
    H -->|数字| I[N番目の区切りで整列]
    H -->|*| J[全ての区切りで整列]
    H -->|なし| K[最初の区切りで整列]
    I --> L[整列実行・バッファ更新]
    J --> L
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-77-1 | 遅延読み込み | EasyAlignコマンドまたはプラグマッピング実行時にロード | 初回実行時 |
| BR-77-2 | デフォルト整列 | オプション未指定時は最初の区切り文字で左揃え | インタラクティブモード |
| BR-77-3 | 繰り返し整列 | *を指定すると全ての区切り文字で整列 | インタラクティブモード |

### 計算ロジック

- 各行の区切り文字位置を検出
- 指定されたオプション（左/右/中央揃え、N番目指定）に基づいて整列位置を計算
- 必要なスペースを挿入してテキストを更新

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

本機能にデータベース操作は存在しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 区切り文字未検出 | 指定区切り文字が対象範囲に存在しない | 別の文字を指定 |
| - | キャンセル | ユーザーがEscでキャンセル | 正常終了として扱う |

### リトライ仕様

本機能にリトライ処理は存在しない。

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

本機能はUndoで元に戻すことが可能。整列操作は1つのUndo単位として扱われる。

## パフォーマンス要件

- 遅延読み込みにより起動時間への影響を最小化
- インタラクティブモードは即座に応答

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

本機能はテキスト編集のみであり、セキュリティ上の考慮事項は特になし。

## 備考

- vim-easy-alignはjunegunn氏が開発・メンテナンスしている外部プラグイン
- tabularとの違い：easy-alignはインタラクティブ、tabularはコマンドベース
- SPC x aで起動可能（space-vimのキーバインディング）

---

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

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

### 推奨読解順序

#### Step 1: パッケージ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+vim/text-align/packages.vim` | プラグイン登録と遅延読み込み条件 |

**読解のコツ**: `{ 'on': [ '<Plug>(EasyAlign)', 'EasyAlign' ] }`はプラグマッピングまたはコマンド実行時にロードする設定。

**主要処理フロー**:
- **2行目**: `MP 'junegunn/vim-easy-align', { 'on': [ '<Plug>(EasyAlign)', 'EasyAlign' ] }` - 遅延読み込み設定

#### Step 2: キーバインディング設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.vim | `layers/+vim/text-align/config.vim` | EasyAlignのキーマッピング |

**読解のコツ**: `xmap`はビジュアルモード用、`nmap`はノーマルモード用のマッピング。`<Plug>(EasyAlign)`はプラグインが提供するプラグマッピング。

**主要処理フロー**:
- **22行目**: `xmap <Leader>xa <Plug>(EasyAlign)` - ビジュアルモード用マッピング
- **25行目**: `nmap <Leader>xa <Plug>(EasyAlign)` - ノーマルモード用マッピング

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | leader.vim | `core/autoload/spacevim/map/leader.vim` | SPC x aの説明定義 |

**読解のコツ**: `s:leader_map['x']`でテキスト操作関連のキーバインディングを定義。

**主要処理フロー**:
- **203-207行目**: `s:leader_map['x']`定義 - テキスト操作メニュー
- **205行目**: `'a' : ['<Plug>(EasyAlign)', 'easy-align']` - SPC x aの説明

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

```
~/.spacevim（ユーザー設定）
    │
    └─ Layer('+vim/text-align')
           │
           ├─ packages.vim
           │      └─ MP 'junegunn/vim-easy-align'（プラグマッピング/コマンドで遅延ロード）
           │
           └─ config.vim
                  ├─ xmap <Leader>xa <Plug>(EasyAlign)（ビジュアル）
                  └─ nmap <Leader>xa <Plug>(EasyAlign)（ノーマル）

core/autoload/spacevim/map/leader.vim
    │
    └─ s:leader_map['x']['a'] = 'easy-align'
```

### データフロー図

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

ビジュアル選択 +   ───▶  インタラクティブモード   ───▶  整列済みテキスト
Leader xa                       ↓
                          区切り文字入力
                               ↓
ノーマル + モーション  ───▶  整列オプション解析      ───▶  バッファ更新
+ Leader xa                    ↓
                          整列実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+vim/text-align/packages.vim` | ソース | プラグイン登録と遅延読み込み設定 |
| config.vim | `layers/+vim/text-align/config.vim` | ソース | キーマッピング定義 |
| leader.vim | `core/autoload/spacevim/map/leader.vim` | ソース | Leaderキーマッピングの説明定義 |
