# 画面設計書 3-Neotree

## 概要

本ドキュメントは、Doom Emacsのシンプルなファイルツリー表示画面（Neotree）の設計仕様を定義する。

### 本画面の処理概要

Neotreeは、Treemacsの軽量代替として機能するシンプルなファイルツリー表示を提供するサイドパネルである。

**業務上の目的・背景**：
Neotreeは、Treemacsよりも軽量でシンプルなファイルツリーブラウザを求めるユーザーのために提供されている。最小限の機能でファイルナビゲーションを行いたい場合や、リソース制約のある環境での使用に適している。

**画面へのアクセス方法**：
- `SPC o n` キーバインド（+neotree/open）
- `neotree-toggle` コマンドを直接実行
- `+neotree/find-this-file` で現在のファイルを表示

**主要な操作・処理内容**：
1. プロジェクトのファイルツリー表示
2. ディレクトリの展開・折りたたみ
3. ファイルの選択・オープン
4. ファイルの水平/垂直分割オープン
5. Vim風キーバインドでのナビゲーション

**画面遷移**：
- 遷移元：編集バッファからトグルコマンドで表示
- 遷移先：選択したファイルの編集バッファ

**権限による表示制御**：
- 権限による表示制御は存在しない
- ファイルシステムのパーミッションに従った操作制限のみ

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 34 | ファイルツリーブラウザ（Neotree） | 主機能 | シンプルなファイルツリー表示、ナビゲーション |
| 7 | プロジェクト管理 | 補助機能 | プロジェクトルート検出 |

## 画面種別

サイドパネル型ファイルエクスプローラ

## URL/ルーティング

Emacsアプリケーションのため、URLルーティングは存在しない。バッファ名は` *NeoTree*`。

## 入出力項目

| 項目名 | 種別 | 必須 | 説明 |
|--------|------|------|------|
| プロジェクトルート | 入力 | いいえ | 表示するプロジェクトのルートディレクトリ（省略時はdoom-project-root） |

## 表示項目

| 項目名 | 種別 | 説明 |
|--------|------|------|
| ディレクトリ | アイコン+テキスト | 展開可能なフォルダ表示 |
| ファイル | アイコン+テキスト | ファイル名表示 |

## イベント仕様

### 1-ファイル/ディレクトリ選択

| キー | 動作 |
|------|------|
| RET | ファイルを開く/ディレクトリを展開 |
| TAB | ディレクトリを展開・折りたたみ/クイックルック |
| v | ファイルを垂直分割で開く |
| s | ファイルを水平分割で開く |

### 2-ナビゲーション

| キー | 動作 |
|------|------|
| n | 次のノードへ移動 |
| p | 前のノードへ移動 |
| h | ディレクトリを折りたたむ/親ノードへ移動 |
| l | ディレクトリを展開/ファイルを開く |
| J | 次の兄弟ノードへ移動 |
| K | 前の兄弟ノードへ移動 |
| H | 親ノードへ移動 |
| L | 子ノードへ移動 |
| G | 最終行へ移動 |
| gg | 最初の行へ移動 |

### 3-その他の操作

| キー | 動作 |
|------|------|
| DEL | 前のウィンドウに戻る |

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

本画面はファイルシステム操作のためのUIであり、データベースとの連携は存在しない。

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| なし | - | - | データベース操作なし |

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容 |
|---------------|---------|---------------|
| なし | - | 特別なメッセージ表示なし |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| プロジェクトルートが検出できない | default-directoryを使用 |

## 備考

- neo-themeは'nerd'に設定されている
- neo-mode-line-typeは'none'（モードライン非表示）
- neo-window-widthは30カラム
- 隠しファイル表示はneo-show-hidden-filesで制御

---

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

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

### 推奨読解順序

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

Neotreeの設定変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/neotree/config.el` | 行11-36: 各種設定変数の定義 |

**読解のコツ**: `setq`で設定される各変数がNeotreeの動作を決定する。neo-theme, neo-window-width, neo-hidden-regexp-list等が重要。

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

use-package!マクロによるneotreeの設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/neotree/config.el` | 行3-10: コマンド定義 |
| 2-2 | config.el | `modules/ui/neotree/config.el` | 行38-42: 追加設定 |

**主要処理フロー**:
1. **行3-10**: neotree-show, neotree-hide, neotree-toggle等のコマンドをautoload
2. **行39**: ポップアップルールで無視設定
3. **行41-42**: winner-modeからneotreeバッファを除外

#### Step 3: カーソル制御を理解する

Neotree固有のカーソル位置制御を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/ui/neotree/config.el` | 行47-55: カーソルインデント処理 |

**主要処理フロー**:
- **行47-50**: neo-enter-hookでカーソル位置を修正
- **行52-55**: neotree-next-line/previous-line後にカーソルをインデント

#### Step 4: キーマップを理解する

Doom固有のキーマップ設定を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/ui/neotree/config.el` | 行57-73: キーマップ定義 |

**主要処理フロー**:
- **行57-73**: Vim風ナビゲーション（h/l/J/K/H/L/G/gg等）と分割オープン（v/s）を定義

#### Step 5: インタラクティブコマンドを理解する

Doomが提供するラッパーコマンドを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | autoload.el | `modules/ui/neotree/autoload.el` | 行8-15: +neotree/open関数 |
| 5-2 | autoload.el | `modules/ui/neotree/autoload.el` | 行18-35: +neotree/find-this-file関数 |
| 5-3 | autoload.el | `modules/ui/neotree/autoload.el` | 行38-70: 折りたたみ・展開コマンド |

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

```
+neotree/open
    │
    ├─ neo-global--window-exists-p
    │      └─ exists → neotree-hide
    │
    └─ not exists
           └─ neotree-dir (doom-project-root or default-directory)

+neotree/find-this-file
    │
    ├─ neo-global--window-exists-p
    │      └─ exists → neotree-find + neotree-refresh
    │
    └─ not exists
           └─ neotree-dir → neotree-find
```

### データフロー図

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

SPC o n ────────────▶ +neotree/open ──────────▶ サイドパネル表示/非表示

ファイル選択 ────────▶ neotree-enter ─────────▶ ファイルバッファ

h キー押下 ──────────▶ +neotree/collapse-or-up ▶ ディレクトリ折りたたみ/親移動
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/neotree/config.el` | ソース | メイン設定・キーマップ |
| autoload.el | `modules/ui/neotree/autoload.el` | ソース | インタラクティブコマンド |
| neotree | 外部パッケージ | 依存 | ファイルツリー機能本体 |
