# 画面設計書 9-Popup

## 概要

本ドキュメントは、Doom Emacsのポップアップウィンドウ管理システム（Popup）の設計仕様を定義する。

### 本画面の処理概要

Popupは、ヘルプバッファ、コンパイル出力、端末エミュレータなど、一時的または補助的なバッファを専用のポップアップウィンドウとして管理するシステムである。

**業務上の目的・背景**：
Doom Emacsのポップアップシステムは、Emacsの標準的なウィンドウ管理では実現しにくい「一時的なバッファの特別な表示」を提供する。ヘルプ、補完結果、コンパイル出力、REPLなどのバッファを、メインの編集ウィンドウを邪魔しない形で表示し、ESCキーで簡単に閉じられるようにすることで、スムーズな作業フローを実現する。

**画面へのアクセス方法**：
- 各種コマンド実行時に自動的にポップアップ表示（ヘルプ、コンパイル等）
- `+popup/toggle` コマンドでポップアップの表示/非表示切り替え
- `+popup/other` コマンドでポップアップ間の移動

**主要な操作・処理内容**：
1. バッファタイプに応じたポップアップルールの適用
2. ポップアップウィンドウのサイズ・位置制御
3. TTL（Time To Live）によるバッファの自動削除
4. ESCキーによるポップアップの自動クローズ
5. ポップアップ状態の保存と復元

**画面遷移**：
- 遷移元：各種コマンド（ヘルプ、コンパイル、端末等）
- 遷移先：ポップアップ内のコンテンツに依存

**権限による表示制御**：
- 権限による表示制御は存在しない

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 38 | ポップアップウィンドウ管理 | 主機能 | ポップアップルール適用、ウィンドウ表示制御、TTL管理 |
| 52 | ヘルプシステム | 補助機能 | ヘルプバッファのポップアップ表示 |
| 55 | コンパイル・ビルド | 補助機能 | コンパイル出力のポップアップ表示 |
| 81 | 端末エミュレータ統合 | 補助機能 | vterm/eshellのポップアップ表示 |

## 画面種別

ウィンドウ管理システム（複数のポップアップタイプを統括）

## URL/ルーティング

Emacsアプリケーションのため、URLルーティングは存在しない。`display-buffer-alist`を通じてバッファ表示を制御する。

## 入出力項目

本システムは画面表示の管理機能であり、ユーザー入力項目は存在しない。

| 項目名 | 種別 | 必須 | 説明 |
|--------|------|------|------|
| なし | - | - | 入力項目なし |

## 表示項目

| 項目名 | 種別 | 説明 |
|--------|------|------|
| ポップアップウィンドウ | ウィンドウ | 側面または下部に表示される専用ウィンドウ |
| モードライン | テキスト | ポップアップパラメータに応じた表示/非表示 |
| マージン | 空白 | +popup-margin-widthで制御されるマージン |

## イベント仕様

### 1-ポップアップ操作

| コマンド | 動作 |
|---------|------|
| +popup/toggle | ポップアップの表示/非表示をトグル |
| +popup/other | 次のポップアップウィンドウへ移動 |
| +popup/close | 現在のポップアップを閉じる |
| +popup/close-all | すべてのポップアップを閉じる |
| +popup/restore | 最後に閉じたポップアップを復元 |
| +popup/raise | ポップアップを通常ウィンドウに昇格 |

### 2-キーバインド

| キー | 動作 |
|------|------|
| ESC | ポップアップ内で押下時にクローズ |
| q | 特定のポップアップでクローズ（quit='t時） |

### 3-ポップアップパラメータ

| パラメータ | 説明 |
|-----------|------|
| ttl | バッファの生存時間（秒）、tでデフォルト |
| quit | ESCで閉じられるか（t, current, other, nil） |
| select | ポップアップ表示時に選択するか |
| modeline | モードラインの表示形式（t, nil, 関数） |
| popup | ポップアップであることを示すマーカー |

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

本画面はEmacs UI機能であり、データベースとの連携は存在しない。

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

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

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容 |
|---------------|---------|---------------|
| エラー | ポップアップが存在しない | "No popups are open" |
| エラー | 復元するポップアップがない | "No popups to restore" |
| 情報 | +popup/diagnose実行時 | "Rule matches: ..." または "No popup rule for this buffer" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ポップアップが開いていない | エラーメッセージを表示 |
| 復元するポップアップがない | エラーメッセージを表示 |
| 非ポップアップウィンドウでraise | エラーメッセージを表示 |

## 備考

- `+popup-mode`がdoom-init-ui-hookで有効化される
- ポップアップルールは`set-popup-rule!`マクロで定義
- `+defaults`フラグで多数の標準ポップアップルールが適用される
- `+all`フラグで全`*`で始まるバッファをポップアップ化

---

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

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

### 推奨読解順序

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

ポップアップシステムの変数とパラメータを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/popup/config.el` | 行3-32: 変数定義（+popup-window-parameters, +popup-default-alist等） |

**読解のコツ**: `+popup-window-parameters`（ウィンドウパラメータリスト）、`+popup-default-alist`（デフォルト表示設定）、`+popup-default-parameters`（デフォルトパラメータ）が基盤。

#### Step 2: マイナーモードを理解する

+popup-modeと+popup-buffer-modeの定義を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/popup/config.el` | 行51-70: +popup-mode定義 |
| 2-2 | config.el | `modules/ui/popup/config.el` | 行72-86: +popup-buffer-mode定義 |

**主要処理フロー**:
1. **行51-70**: グローバルマイナーモード、display-buffer-alist管理
2. **行72-86**: バッファローカルマイナーモード、モードライン・タイマー管理

#### Step 3: デフォルトルールを理解する

標準のポップアップルール定義を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/ui/popup/config.el` | 行129-167: set-popup-rules!呼び出し |

**主要処理フロー**:
- **行130-132**: +allフラグ時の全バッファルール
- **行133-161**: +defaultsフラグ時の詳細ルール（Completions, Compilation, Help等）

#### Step 4: ポップアップ操作関数を理解する

ポップアップの表示・管理関数を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | autoload/popup.el | `modules/ui/popup/autoload/popup.el` | 行149-166: +popup--init関数 |
| 4-2 | autoload/popup.el | `modules/ui/popup/autoload/popup.el` | 行193-212: +popup-buffer関数 |
| 4-3 | autoload/popup.el | `modules/ui/popup/autoload/popup.el` | 行373-389: +popup/close関数 |

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

ユーザーが利用するコマンドを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | autoload/popup.el | `modules/ui/popup/autoload/popup.el` | 行341-350: +popup/buffer関数 |
| 5-2 | autoload/popup.el | `modules/ui/popup/autoload/popup.el` | 行353-370: +popup/other関数 |
| 5-3 | autoload/popup.el | `modules/ui/popup/autoload/popup.el` | 行410-417: +popup/toggle関数 |

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

```
doom-init-ui-hook
    │
    └─ +popup-mode有効化
           │
           ├─ display-buffer-alist設定
           │
           └─ window-persistent-parametersにパラメータ追加

バッファ表示要求（display-buffer）
    │
    ├─ +popup--display-buffer-alist照合
    │      └─ ルールマッチ時
    │             └─ +popup-display-buffer-stacked-side-window-fn
    │                    └─ +popup--init
    │                           └─ +popup-buffer-mode有効化
    │
    └─ ルール非マッチ時
           └─ 通常の表示

+popup/close
    │
    └─ +popup--delete-window
           ├─ 変更保存確認
           ├─ window削除
           └─ TTLによるバッファ削除スケジュール
```

### データフロー図

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

ヘルプ要求 ──────────▶ display-buffer ────────▶ ポップアップウィンドウ
                            │
                            └─ +popup-buffer

ESC押下 ────────────▶ +popup-close-on-escape-h ▶ ウィンドウクローズ

+popup/toggle ──────▶ +popup/close-all or ────▶ 表示/非表示切替
                      +popup/restore
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/popup/config.el` | ソース | メイン設定、マイナーモード、デフォルトルール |
| autoload/popup.el | `modules/ui/popup/autoload/popup.el` | ソース | ポップアップ操作関数 |
| autoload/settings.el | `modules/ui/popup/autoload/settings.el` | ソース | set-popup-rule!マクロ |
| +hacks.el | `modules/ui/popup/+hacks.el` | ソース | 各種パッケージとの互換性ハック |
| test/test-popup.el | `modules/ui/popup/test/test-popup.el` | テスト | ユニットテスト |
