# 画面設計書 4-FZF（ファジーファインダー）

## 概要

本ドキュメントは、space-vimにおけるFZF（ファジーファインダー）の画面設計について記載する。FZFはjunegunn/fzfおよびjunegunn/fzf.vimプラグインにより提供されるファジー検索機能であり、ファイル、バッファ、コマンド履歴などを高速にファジー検索するオーバーレイ画面を提供する。

### 本画面の処理概要

**業務上の目的・背景**：大規模なプロジェクトにおいて、ファイル名やバッファ名の一部を入力するだけで目的のリソースに素早くアクセスできるようにすることが目的である。完全一致ではなくファジー（曖昧）マッチングにより、タイプミスや部分的な記憶でも目的のファイルを見つけることができる。また、Neovimのフローティングウィンドウに対応しており、モダンなUI体験を提供する。

**画面へのアクセス方法**：以下の方法でFZF画面にアクセスできる。
- `SPC f f`キーバインド：ファイル検索
- `SPC b b`キーバインド：バッファ一覧
- `SPC f l`キーバインド：現在バッファの行検索（BLines）
- `SPC f L`キーバインド：全バッファの行検索
- `Leader ag`：Ag検索
- `Leader rg`：Rg検索（ripgrep）
- `:Files`、`:Buffers`、`:Rg`等のコマンド

**主要な操作・処理内容**：
1. 検索クエリをインクリメンタルに入力
2. ファジーマッチングにより候補がリアルタイムに絞り込まれる
3. `Ctrl-j`/`Ctrl-k`または矢印キーで候補間を移動
4. `Enter`で選択したアイテムを開く
5. `ESC`または`Ctrl-c`でキャンセル
6. プレビューウィンドウでファイル内容を確認（対応コマンドのみ）

**画面遷移**：
- エディタ画面 -> `SPC f f` -> FZFファイル検索画面
- FZFファイル検索画面 -> ファイル選択 -> エディタ画面（選択ファイル）
- FZFファイル検索画面 -> `ESC` -> エディタ画面

**権限による表示制御**：特になし。ファイルシステムのパーミッションに依存する。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 32 | fzf連携 | 主機能 | ファジー検索によるファイル・バッファ・コマンド履歴の検索 |
| 16 | プロジェクト検索(SPC p) | 補助機能 | プロジェクト内のファイル検索、テキスト検索（rg連携） |
| 13 | バッファ操作(SPC b) | API連携 | SPC b bでバッファ一覧のファジー検索 |

## 画面種別

オーバーレイ / ポップアップ

## URL/ルーティング

- ファイル検索: `:Files`、`SPC f f`
- バッファ一覧: `:Buffers`、`SPC b b`
- Ag検索: `:Ag`、`Leader ag`
- Rg検索: `:Rg`、`Leader rg`
- 行検索: `:BLines`、`SPC f l`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|---------|------|
| $FZF_DEFAULT_OPTS | 入力（環境変数） | String | FZFのデフォルトオプション |
| g:fzf_layout | 入力（設定） | Dictionary | FZFウィンドウのレイアウト設定 |
| g:fzf_colors | 入力（設定） | Dictionary | FZFのカラースキーム設定 |
| 検索クエリ | 入力 | String | ユーザーが入力する検索文字列 |
| 選択アイテム | 出力 | String | 選択されたファイルパス/バッファ名等 |

## 表示項目

| 項目 | 表示内容 | 説明 |
|-----|---------|------|
| プロンプト | 検索種別表示 | 「Files>」「Buffers>」等 |
| 検索クエリ | 入力中の検索文字列 | リアルタイム更新 |
| 候補一覧 | マッチした候補 | ハイライト表示 |
| プレビュー | 選択ファイルの内容 | 対応コマンドのみ |
| マッチ数 | マッチした候補数 | ステータス表示 |

## イベント仕様

### 1-ファイル検索（Files）

`SPC f f`押下時、`spacevim#map#manager#Files()`が呼ばれ、FZFファイル検索画面が表示される。プロジェクトルートディレクトリを起点に検索する。

### 2-バッファ一覧（Buffers）

`SPC b b`押下時、`spacevim#map#manager#Buffers()`が呼ばれ、現在開いているバッファ一覧がFZF形式で表示される。

### 3-テキスト検索（Rg/Ag）

`Leader rg`または`Leader ag`押下時、ripgrepまたはagを使用してプロジェクト内のテキスト検索を行う。プレビューウィンドウで検索結果のコンテキストを確認できる。

### 4-行検索（BLines）

`SPC f l`押下時、現在のバッファ内で行をファジー検索する。

### 5-フローティングウィンドウ表示

Neovim（`nvim_open_win`対応）の場合、フローティングウィンドウでFZFが表示される。それ以外の場合は分割ウィンドウで表示される。

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

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

該当なし（ファイルシステム検索のみ）

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|---------|
| 情報 | プロンプト（Files>等） | 検索画面表示時 |
| エラー | rg is not found | ripgrepが未インストール時 |

## 例外処理

| 状態 | 処理 |
|------|------|
| 検索結果なし | 空の候補一覧を表示 |
| ripgrep未インストール | 警告メッセージ表示 |
| fzfプラグイン未ロード | 手動でプラグインをロード |

## 備考

- FZFプラグインは`junegunn/fzf`および`junegunn/fzf.vim`により提供される
- vim-clapが有効な場合（`g:spacevim_enable_clap`）、FZFの代わりにvim-clapが使用される
- GUI環境でターミナル機能がない場合、LeaderFが代替として使用される
- 遅延読み込み（on-demand loading）が有効
- Neovimではフローティングウィンドウでの表示に対応
- `$LANG = 'en_US.UTF-8'`が設定される（Issue #364対応）

---

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

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

### 推奨読解順序

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

FZFの設定データ構造とレイアウト設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.vim | `layers/+tools/fzf/config.vim` | FZFの設定変数（g:fzf_layout, g:fzf_colors）を確認 |
| 1-2 | fzf.vim | `core/autoload/spacevim/plug/fzf.vim` | カスタムFZF関数の実装を確認 |

**読解のコツ**: `g:fzf_layout`がウィンドウレイアウト、`g:fzf_colors`がカラースキームを定義している。`nvim_open_win`の存在確認でフローティングウィンドウ対応を判定している。

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

キーマッピングとマネージャー関数の関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.vim | `layers/+tools/fzf/config.vim` | キーマッピング設定（SPC f f, SPC b b等） |
| 2-2 | manager.vim | `core/autoload/spacevim/map/manager.vim` | マネージャー関数（Files, Buffers等）の実装 |

**主要処理フロー**:
1. **config.vim 1-4行目**: `spacevim#map#manager#Files()`等へのキーマッピング
2. **config.vim 24-26行目**: フローティングウィンドウの設定
3. **config.vim 50-58行目**: `:Ag`、`:Files`、`:Rg`コマンドの定義
4. **manager.vim 19-25行目**: Files関数のvim-clap/FZF分岐

#### Step 3: カスタムFZF関数を理解する

プロジェクト検索やセッション検索などのカスタム機能を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | fzf.vim | `core/autoload/spacevim/plug/fzf.vim` | `spacevim#plug#fzf#Rg()`等のカスタム関数 |

**主要処理フロー**:
- **8-15行目**: セッション検索（`spacevim#plug#fzf#Session()`）
- **195-223行目**: Rg検索（プロジェクトルート対応）
- **158-160行目**: プロジェクト内ファイル検索

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

```
<Leader>ff (nnoremap)
    │
    └─ spacevim#map#manager#Files()
           │
           ├─ [vim-clap有効時]
           │      │
           │      └─ :Clap buffers
           │
           └─ [FZF使用時]
                  │
                  └─ spacevim#wrap#fzf#Files()
                         │
                         └─ fzf#vim#files() (fzf.vim)
                                │
                                ├─ フローティングウィンドウ（Neovim）
                                │      │
                                │      └─ spacevim#util#FloatingWin()
                                │
                                └─ 分割ウィンドウ（Vim8/旧Neovim）
```

### データフロー図

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

SPC f f / SPC b b ─────▶ config.vim ───────────────▶ マネージャー関数
キー押下                  (キーマッピング)

vim-clap確認 ─────────▶ manager.vim ──────────────▶ FZF/Clap分岐
                        (条件分岐)

検索クエリ ───────────▶ fzf/fzf.vim ──────────────▶ ファジーマッチング
                        (検索処理)

ファイルシステム ─────▶ rg/ag/fd ─────────────────▶ 候補生成
                        (検索バックエンド)

選択アイテム ─────────▶ fzf#vim#* ────────────────▶ バッファオープン
                        (sink処理)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+tools/fzf/packages.vim` | ソース | プラグイン登録・条件分岐 |
| config.vim | `layers/+tools/fzf/config.vim` | ソース | キーマッピング・設定 |
| manager.vim | `core/autoload/spacevim/map/manager.vim` | ソース | マネージャー関数 |
| fzf.vim | `core/autoload/spacevim/plug/fzf.vim` | ソース | カスタムFZF関数 |
| fzf | 外部プラグイン（junegunn/fzf） | プラグイン | FZFコア機能 |
| fzf.vim | 外部プラグイン（junegunn/fzf.vim） | プラグイン | Vim向けFZFラッパー |
