# 通知設計書 22-popup-buffer表示

## 概要

本ドキュメントは、Doom Emacsのポップアップウィンドウシステム（popup-buffer）による通知表示機能の設計を定義する。

### 本通知の処理概要

popup-buffer表示機能は、Doom Emacsの統合ポップアップ管理システムを通じて、様々なバッファを一貫した方法でポップアップウィンドウとして表示する機能である。`display-buffer-alist`をカスタマイズし、特定のバッファパターンに対して統一されたウィンドウ表示ルールを適用する。

**業務上の目的・背景**：Emacsの標準的なウィンドウ管理は、ヘルプバッファやコンパイルバッファなど様々なバッファが予測不能な方法でウィンドウを占有し、ユーザーの作業フローを中断させることがある。ポップアップシステムは、これらの補助的なバッファを画面端のサイドウィンドウに整理して表示し、メインの作業領域を保護しながら必要な情報へのアクセスを提供する。これにより開発効率が向上し、画面の有効活用が実現される。

**通知の送信タイミング**：`pop-to-buffer`または`display-buffer`関数が呼び出され、対象バッファ名がポップアップルールにマッチした時点で、ポップアップウィンドウとして表示される。

**通知の受信者**：Emacsを操作しているユーザー本人。ポップアップは現在のフレーム内で表示される。

**通知内容の概要**：対象バッファの内容がサイドウィンドウまたは指定された位置にポップアップ表示される。ウィンドウサイズ、位置、TTL（自動クローズまでの時間）等がルールに従って制御される。

**期待されるアクション**：ユーザーはポップアップの内容を確認し、必要に応じてポップアップ内で操作を行うか、ESC/C-gでポップアップを閉じる。`C-\`` でポップアップをトグル、`C-~` でポップアップを通常ウィンドウに昇格させることができる。

## 通知種別

アプリ内通知（Emacsポップアップウィンドウ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 可変（バッファ種別による） |
| リトライ | なし |

### 送信先決定ロジック

`+popup--display-buffer-alist`に定義されたルールに基づき、バッファ名の正規表現マッチングで表示方法を決定。マッチしない場合は`+popup-defaults`のデフォルト値を適用。

## 通知テンプレート

### ポップアップウィンドウの場合

| 項目 | 内容 |
|-----|------|
| 表示位置 | :side (bottom/top/left/right) |
| サイズ | :height / :width |
| スロット | :slot / :vslot |
| 選択状態 | :select (t/nil/関数) |

### ウィンドウパラメータ

| パラメータ | 説明 | デフォルト値 |
|----------|------|-------------|
| ttl | 自動クローズまでの秒数 | 5 |
| quit | ESC/C-gでの閉じ方 | t |
| select | フォーカス移動 | ignore |
| modeline | モードライン表示 | nil |
| transient | 一時的バッファフラグ | t |

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| buffer-name | 対象バッファ名 | buffer-name関数 | Yes |
| side | 表示位置 | ルール定義/:side | Yes |
| size | ウィンドウサイズ | ルール定義/:height,width | No |
| slot | 水平位置 | ルール定義/:slot | No |
| vslot | 垂直スタック位置 | ルール定義/:vslot | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | display-buffer | ルールマッチ | バッファ表示要求時 |
| 関数呼び出し | pop-to-buffer | ルールマッチ | バッファポップアップ要求時 |
| ユーザー操作 | +popup/buffer | 常時 | 現在のバッファをポップアップ化 |
| ユーザー操作 | +popup/toggle | ポップアップ存在時 | ポップアップ表示/非表示切替 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| +popup-mode無効 | ポップアップシステム無効時 |
| :ignore t | ルールでignore指定されたバッファ |
| switch-to-buffer使用 | display-buffer-alistの対象外 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[display-buffer呼び出し] --> B{+popup-mode有効?}
    B -->|No| C[標準display-buffer]
    B -->|Yes| D[display-buffer-alist検索]
    D --> E{ルールマッチ?}
    E -->|No| C
    E -->|マッチ| F{:ignore設定?}
    F -->|Yes| C
    F -->|No| G[+popup-buffer関数]
    G --> H[alist正規化]
    H --> I[サイドウィンドウ作成]
    I --> J[+popup--init]
    J --> K[ウィンドウパラメータ設定]
    K --> L[+popup-buffer-mode有効化]
    L --> M{:select設定?}
    M -->|Yes| N[ウィンドウ選択]
    M -->|No| O[元ウィンドウ維持]
    N --> P[表示完了]
    O --> P
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（メモリ内変数ベースの処理）

### 内部変数参照

| 変数名 | 用途 | 備考 |
|--------|------|------|
| +popup--display-buffer-alist | ポップアップルール一覧 | display-buffer-alistに設定 |
| +popup-defaults | デフォルトパラメータ | :side, :height等 |
| +popup--last | 最後に閉じたポップアップ情報 | 復元用 |

### 更新変数一覧

| 変数名 | 操作 | 概要 |
|--------|------|------|
| +popup--last | UPDATE | ポップアップクローズ時に状態保存 |
| window-persistent-parameters | UPDATE | popup関連パラメータ追加 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| サイドウィンドウ作成失敗 | スロット競合 | 既存ウィンドウ再利用 |
| ウィンドウサイズ超過 | サイズがフレームより大 | フレームサイズでクリップ |
| 無効なside値 | 不正なパラメータ | エラーシグナル |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | なし |
| リトライ対象エラー | なし |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし

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

- ポップアップには任意のバッファ内容が表示されるため、機密情報を含む可能性がある
- 画面共有時はポップアップ内容に注意が必要

## 備考

- デフォルトのポップアップ位置は画面下部（:side bottom）
- :vslotパラメータでポップアップのスタック順序を制御可能
- +popup/restoreで最後に閉じたポップアップを復元可能
- magitなど独自のウィンドウ管理を行うパッケージは:ignoreで除外される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | settings.el | `modules/ui/popup/autoload/settings.el` | +popup-defaultsとルール構造の定義 |
| 1-2 | config.el | `modules/ui/popup/config.el` | デフォルトルールの定義 |

**読解のコツ**: `+popup-defaults`のplistキーと、`set-popup-rule!`マクロの引数を対応させて理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/popup/config.el` | +popup-modeの定義とフック設定 |

**主要処理フロー**:
1. **51-70行目**: `+popup-mode`の定義、display-buffer-alistの切り替え
2. **56-62行目**: モード有効化時にdisplay-buffer-alistを+popup--display-buffer-alistに設定
3. **129-167行目**: デフォルトのポップアップルール定義

#### Step 3: ポップアップ表示処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | popup.el | `modules/ui/popup/autoload/popup.el` | +popup-buffer関数の実装 |

**主要処理フロー**:
- **193-212行目**: +popup-buffer関数でバッファをポップアップ表示
- **149-166行目**: +popup--init関数でウィンドウパラメータ初期化
- **511-659行目**: +popup-display-buffer-stacked-side-window-fn関数

#### Step 4: コマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | popup.el | `modules/ui/popup/autoload/popup.el` | ユーザー向けコマンド群 |

**主要処理フロー**:
- **341-350行目**: +popup/buffer - 現在のバッファをポップアップ化
- **373-389行目**: +popup/close - ポップアップを閉じる
- **410-417行目**: +popup/toggle - ポップアップ表示切替
- **419-429行目**: +popup/restore - 最後のポップアップを復元

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

```
display-buffer (Emacs組み込み)
    │
    └─ display-buffer-alist (カスタマイズ)
           │
           └─ +popup--display-buffer-alist
                  │
                  └─ +popup-buffer
                         │
                         ├─ +popup--normalize-alist
                         │
                         ├─ +popup-display-buffer-stacked-side-window-fn
                         │      └─ window--make-major-side-window
                         │
                         └─ +popup--init
                                ├─ set-window-parameter (popup=t)
                                ├─ +popup-buffer-mode
                                └─ +popup-create-window-hook
```

### データフロー図

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

バッファ名 ───────▶ display-buffer-alist ───▶ ポップアップウィンドウ
                          │
                          ▼
              +popup--display-buffer-alist
                          │
              ┌───────────┼───────────┐
              ▼           ▼           ▼
        ルールマッチ  :ignore   マッチなし
              │           │           │
              ▼           ▼           ▼
        +popup-buffer  標準処理   標準処理
              │
              ▼
      サイドウィンドウ作成
              │
              ▼
      +popup-buffer-mode有効化
              │
              ▼
        ポップアップ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/popup/config.el` | ソース | ポップアップモード定義とデフォルトルール |
| popup.el | `modules/ui/popup/autoload/popup.el` | ソース | ポップアップ関数とコマンド |
| settings.el | `modules/ui/popup/autoload/settings.el` | ソース | ルール設定マクロ |
| +hacks.el | `modules/ui/popup/+hacks.el` | ソース | 他パッケージとの連携ハック |
| README.org | `modules/ui/popup/README.org` | ドキュメント | モジュール説明 |
