# 画面設計書 1-Doom Dashboard

## 概要

本ドキュメントは、Doom Emacsの起動時に表示されるダッシュボード画面（Doom Dashboard）の設計仕様を定義する。

### 本画面の処理概要

Doom Dashboardは、Doom Emacs起動時に最初に表示されるスタートアップ画面であり、ユーザーが効率的に作業を開始するためのクイックアクセス機能を提供する。

**業務上の目的・背景**：
Doom Dashboardは、Emacsの起動直後にユーザーが最も頻繁に行う操作（最近使用したファイルを開く、プロジェクトを切り替える、セッションを復元する等）への素早いアクセスを実現することを目的としている。従来のEmacs起動時の空バッファ（scratch）画面と異なり、視覚的に魅力的なバナー表示と共に、一般的なワークフローへのショートカットを提供することで、ユーザー体験を向上させる。

**画面へのアクセス方法**：
- Doom Emacs起動時に自動的に表示される
- `+doom-dashboard/open` コマンドを実行する
- 他のバッファがすべて閉じられた際にフォールバックバッファとして表示される

**主要な操作・処理内容**：
1. ASCIIバナーまたは画像バナーの表示
2. 最近開いたファイル一覧へのアクセス（recentf-open-files）
3. 前回セッションの復元（doom/quickload-session）
4. org-agendaの表示
5. プロジェクトの切り替え（projectile-switch-project）
6. ブックマークへのジャンプ（bookmark-jump）
7. プライベート設定ファイルを開く（doom/open-private-config）
8. ドキュメントを開く（doom/help）

**画面遷移**：
- 遷移元：Emacs起動、他バッファのクローズ時
- 遷移先：編集バッファ、最近のファイル一覧、プロジェクト選択画面、org-agenda、ブックマーク一覧、設定ファイル編集画面、ドキュメント表示

**権限による表示制御**：
- 権限による表示制御は存在しない
- ただし、各メニュー項目は`:when`条件により動的に表示/非表示が切り替わる（例：workspacesモジュール有効時のみセッション復元を表示）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 25 | 起動時ダッシュボード表示 | 主機能 | ダッシュボード画面の描画、ウィジェット表示、バナー表示処理 |
| 7 | プロジェクト管理 | 補助機能 | プロジェクト切り替えメニュー、最後のプロジェクトディレクトリ記憶 |
| 41 | ワークスペース管理（タブ風） | 補助機能 | セッション復元機能、ワークスペース連携 |
| 24 | Doomテーマ・視覚スタイル | 補助機能 | ダッシュボードのテーマ適用、フェイス定義 |
| 74 | Org-mode文書作成 | 遷移先機能 | org-agenda表示へのショートカット |

## 画面種別

ダッシュボード（スタートアップ画面）

## URL/ルーティング

Emacsはブラウザベースのアプリケーションではないため、URLルーティングは存在しない。バッファ名 `*doom*` で識別される。

## 入出力項目

本画面は表示専用のダッシュボード画面であり、ユーザー入力フォームは存在しない。

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

## 表示項目

| 項目名 | 種別 | 説明 |
|--------|------|------|
| バナー | 画像/ASCII | Doom Emacsロゴ（GUIでは画像、CUIではASCIIアート） |
| メニュー項目 | ボタン | 各機能へのショートカットリンク |
| ロード時間 | テキスト | Doom Emacsの起動にかかった時間とロードされたパッケージ数 |
| フッター | リンク | GitHubページへのリンク |

## イベント仕様

### 1-メニューボタン押下

各メニューボタンを押下（RETキーまたはクリック）すると、対応するコマンドが実行される。

| メニュー項目 | 実行されるコマンド | 遷移先 |
|-------------|-------------------|--------|
| Recently opened files | recentf-open-files | Vertico/Ivy/Helm補完画面 |
| Reload last session | doom/quickload-session | 前回のワークスペース状態 |
| Open org-agenda | org-agenda | org-agenda画面 |
| Open project | projectile-switch-project | プロジェクト選択画面 |
| Jump to bookmark | bookmark-jump | ブックマーク選択画面 |
| Open private configuration | doom/open-private-config | 設定ファイル |
| Open documentation | doom/help | ドキュメント表示 |

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

| キー | 動作 |
|------|------|
| n, C-n, Tab, 下矢印 | 次のボタンへ移動 |
| p, C-p, Backtab, 上矢印 | 前のボタンへ移動 |
| RET | 選択中のボタンを押下 |

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

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

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

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

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容 |
|---------------|---------|---------------|
| 情報 | 常時表示 | "Loaded X packages in Y.Zs" （起動時間表示） |
| 情報 | ボタンホバー時 | 各ボタンのhelp-echoメッセージ（コマンド名表示） |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| バナー画像ファイルが見つからない | ASCIIバナーにフォールバック |
| セッションファイルが存在しない | "Reload last session"メニューを非表示 |
| org-modeがロードされていない | "Open org-agenda"メニューを非表示 |

## 備考

- ダッシュボードはテーマ変更時に自動的にリロードされる（`doom-load-theme-hook`）
- ウィンドウサイズ変更時にマージンが再計算され、コンテンツが中央寄せされる
- `persp-mode`（ワークスペース）との連携により、ワークスペースごとにプロジェクトルートを記憶する

---

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

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

### 推奨読解順序

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

まず、ダッシュボードの設定を保持する変数群を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/doom-dashboard/config.el` | 行3-98: 変数定義（+doom-dashboard-name, +doom-dashboard-functions, +doom-dashboard-menu-sections等） |

**読解のコツ**: `defvar`で定義される変数はカスタマイズポイントであり、`+doom-dashboard-menu-sections`がメニュー項目のデータ構造を定義している。

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

処理の起点となる初期化フックとメジャーモード定義を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/doom-dashboard/config.el` | 行104-131: `+doom-dashboard-init-h`関数（初期化処理） |
| 2-2 | config.el | `modules/ui/doom-dashboard/config.el` | 行170-224: `+doom-dashboard-mode`の定義とキーマップ |

**主要処理フロー**:
1. **行104-131**: `+doom-dashboard-init-h`がDoomのUI初期化時に呼ばれ、フォールバックバッファを設定
2. **行109-110**: `doom-fallback-buffer-name`を`*doom*`に設定
3. **行118-131**: 各種フックを登録（テーマ変更、ウィンドウリサイズ、バッファ切替等）

#### Step 3: リロード・描画処理を理解する

ダッシュボードの描画ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/ui/doom-dashboard/config.el` | 行339-359: `+doom-dashboard-reload`関数（描画更新処理） |
| 3-2 | config.el | `modules/ui/doom-dashboard/config.el` | 行389-506: ウィジェット描画関数群 |

**主要処理フロー**:
- **行339-359**: `+doom-dashboard-reload`がバッファを消去し、`+doom-dashboard-functions`に登録されたウィジェット関数を順次実行
- **行389-420**: `doom-dashboard-draw-ascii-banner-fn`でASCIIバナーを描画
- **行422-441**: `doom-dashboard-widget-banner`で画像バナーを描画（GUI時）
- **行454-506**: `doom-dashboard-widget-shortmenu`でメニューボタンを描画

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

ユーザーが操作可能なコマンドを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | autoload.el | `modules/ui/doom-dashboard/autoload.el` | 行9-14: `+doom-dashboard/open`コマンド |
| 4-2 | autoload.el | `modules/ui/doom-dashboard/autoload.el` | 行17-28: ナビゲーションコマンド |

**主要処理フロー**:
- **行9-14**: `+doom-dashboard/open`はフォールバックバッファに切り替えてダッシュボードをリロード

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

```
Emacs起動
    │
    ├─ doom-init-ui-hook
    │      └─ +doom-dashboard-init-h
    │              ├─ doom-fallback-buffer設定
    │              └─ 各種フック登録
    │
    └─ +doom-dashboard-reload
           ├─ doom-dashboard-widget-banner
           │      └─ doom-dashboard-draw-ascii-banner-fn (CUI時)
           │      └─ create-image (GUI時)
           │
           ├─ doom-dashboard-widget-shortmenu
           │      └─ insert-text-button (各メニュー項目)
           │
           ├─ doom-dashboard-widget-loaded
           │      └─ doom-display-benchmark-h
           │
           └─ doom-dashboard-widget-footer
                  └─ insert-text-button (GitHubリンク)
```

### データフロー図

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

Emacs起動 ────────▶ +doom-dashboard-init-h ───▶ *doom*バッファ作成

ウィンドウリサイズ ──▶ +doom-dashboard-resize-h ─▶ マージン再計算

メニュークリック ────▶ button-action ───────────▶ 対応コマンド実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/doom-dashboard/config.el` | ソース | メイン設定・ウィジェット定義 |
| autoload.el | `modules/ui/doom-dashboard/autoload.el` | ソース | インタラクティブコマンド |
| default.png | `modules/ui/doom-dashboard/banners/default.png` | リソース | デフォルトバナー画像 |
