# 画面設計書 14-Calendar

## 概要

本ドキュメントは、Doom EmacsにおけるCalendar（カレンダー）画面の設計仕様を定義するものである。calfwパッケージを利用したカレンダー表示について、その表示形式、ナビゲーション、およびorg-mode連携機能を記載する。

### 本画面の処理概要

Calendar画面は、カレンダー形式で日付と予定を表示し、時間管理をサポートする機能である。

**業務上の目的・背景**：テキストエディタ内で予定管理を行いたいユーザー向けに、視覚的なカレンダーインターフェースを提供する。org-modeのスケジュールやiCalendar形式のイベントを統合表示することで、別途カレンダーアプリを開くことなくEmacs内で予定を確認できる。特にorg-agenda連携により、タスク管理とスケジュール管理を一元化できる。

**画面へのアクセス方法**：`=calendar`コマンドを実行してカレンダー画面を開く。workspacesモジュールが有効な場合は専用ワークスペースで開かれる。

**主要な操作・処理内容**：
1. 月表示、週表示、2週間表示、日表示の切り替え
2. 日付間のナビゲーション（hjkl/矢印キー）
3. 予定詳細のポップアップ表示
4. org-mode予定との統合表示
5. Google Calendar連携（org-gcal使用時）

**画面遷移**：`=calendar`コマンドでカレンダー画面を開き、`q`キーで終了。予定を選択すると詳細がポップアップで表示される。ワークスペースモード有効時は専用ワークスペースが作成される。

**権限による表示制御**：本機能に権限による表示制御はない。全ユーザーが同一の機能を利用可能である。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 81 | カレンダー統合 | 主機能 | calfwによるカレンダー表示、予定表示 |
| 74 | Org-mode文書作成 | 補助機能 | org-mode予定との統合表示 |

## 画面種別

一覧（カレンダー形式の予定一覧）

## URL/ルーティング

Emacsモード: `calfw-calendar-mode`, `calfw-details-mode`
バッファ名: `*calfw-calendar*`, `*calfw-details*`
コマンド: `=calendar`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|---------|------|
| カレンダーソース | 入力 | リスト | org-agenda、iCalendarなどのイベントソース |
| 表示期間 | 入力 | 日付範囲 | 表示する期間（月/週/日） |
| イベント一覧 | 出力 | リスト | カレンダーに表示されるイベント |
| 選択日付 | 出力 | 日付 | 現在選択されている日付 |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|---------|------|
| カレンダーグリッド | 中央 | 日付と曜日を格子状に表示 |
| イベント | 各日付セル | 予定名を日付セル内に表示 |
| 月/年 | 上部 | 現在表示中の月と年 |
| 曜日ヘッダー | 上部 | 曜日名（日〜土） |
| ナビゲーションボタン | 上部 | 月移動、表示切替ボタン |
| 詳細ポップアップ | オーバーレイ | 選択したイベントの詳細 |

## イベント仕様

### 1-カレンダー起動

`=calendar`コマンドを実行すると、以下の処理が行われる：
1. workspacesモジュール有効時: 専用ワークスペース（`*calendar*`）を作成/切り替え
2. 無効時: 現在のウィンドウ構成を保存し、全ウィンドウを削除
3. `+calendar/open-calendar`を呼び出してorg-calendarを開く

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

Vimスタイルのキーバインドで日付間を移動：
- `h`: 前の日へ（`calfw-navi-previous-day-command`）
- `l`: 次の日へ（`calfw-navi-next-day-command`）
- `j`: 次の週へ（`calfw-navi-next-week-command`）
- `k`: 前の週へ（`calfw-navi-previous-week-command`）
- `.`/`t`: 今日へ（`calfw-navi-goto-today-command`）

### 3-月ナビゲーション

- `<`/`C-h`: 前の月へ（`calfw-navi-previous-month-command`）
- `>`/`C-l`: 次の月へ（`calfw-navi-next-month-command`）

### 4-表示切替

- `D`: 日表示（`calfw-change-view-day`）
- `W`: 週表示（`calfw-change-view-week`）
- `T`: 2週間表示（`calfw-change-view-two-weeks`）
- `M`: 月表示（`calfw-change-view-month`）

### 5-詳細表示

`RET`または`SPC`キーで選択した日付のイベント詳細をポップアップ表示（`calfw-show-details-command`）。詳細ポップアップは`q`キーで閉じる。

### 6-カレンダー終了

`q`キーで`+calendar/quit`を実行：
1. workspacesモード有効時: カレンダーワークスペースを削除
2. 無効時: 保存されたウィンドウ構成を復元
3. 関連バッファ（`*cfw[:-]*`）をすべて削除

### 7-リフレッシュ

`gr`キーでカレンダーを再描画（`calfw-refresh-calendar-buffer`）。

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

本機能はデータベースを直接使用しない。イベントデータはorg-modeファイルまたは外部カレンダーサービス（iCalendar、Google Calendar）から取得される。

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|--------------|--------------|---------|
| なし | - | カレンダー操作ではメッセージは表示されない |

## 例外処理

| 例外状態 | 処理内容 |
|---------|---------|
| org-modeファイルなし | 空のカレンダーを表示 |
| ワークスペース作成失敗 | 通常モードで開く |
| iCalendarソースエラー | 該当ソースをスキップ |

## 備考

- calfwパッケージはカレンダーの描画とナビゲーションを担当
- calfw-orgはorg-modeとの連携を担当
- calfw-icalはiCalendarファイルとの連携を担当
- org-gcalはGoogle Calendar APIとの連携を担当（オプション）
- カレンダー罫線にはUnicode文字（┏┯┓等）を使用
- 詳細ポップアップはDoomのpopupルールに従い40%サイズで表示
- モードラインはカレンダー画面では非表示

---

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

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

### 推奨読解順序

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

calfwカレンダーのデータ構造とソース概念を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/app/calendar/config.el` | 3-4行目: カレンダー開始関数変数 |

**読解のコツ**: calfwはソースベースのアーキテクチャを採用。`calfw-org-create-source`等でソースを作成し、カレンダーに追加する。

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

カレンダー起動処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | autoload.el | `modules/app/calendar/autoload.el` | 14-30行目: `=calendar`関数 |

**主要処理フロー**:
1. **17-26行目**: workspacesモジュール有効時の処理
2. **27-30行目**: 無効時の処理（ウィンドウ構成保存）
3. **11行目**: `+calendar-open-function`（デフォルト: `+calendar/open-calendar`）を呼び出し

#### Step 3: calfwパッケージ設定を理解する

カレンダー描画設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/app/calendar/config.el` | 10-23行目: calfw設定 |

**主要処理フロー**:
- **14-15行目**: セパレータ色とライン改行設定
- **16-23行目**: Unicode罫線文字の設定
- **25行目**: 詳細ポップアップのルール設定

#### Step 4: Evil連携キーバインドを理解する

Vimスタイルのナビゲーションを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/app/calendar/config.el` | 28-67行目: Evilキーマップ設定 |

**主要処理フロー**:
- **31-56行目**: calfw-calendar-mode-mapのキーバインド
- **57-67行目**: calfw-details-mode-mapのキーバインド

#### Step 5: org-mode連携を理解する

org-modeスケジュールとの連携を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | config.el | `modules/app/calendar/config.el` | 75-79行目: calfw-org設定 |
| 5-2 | autoload.el | `modules/app/calendar/autoload.el` | 45-49行目: `+calendar/open-calendar`関数 |

**主要処理フロー**:
- **48行目**: `calfw-org-open-calendar`を呼び出し、org-agendaソースで初期化

#### Step 6: 終了処理を理解する

カレンダー終了とクリーンアップを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | autoload.el | `modules/app/calendar/autoload.el` | 33-42行目: `+calendar/quit`関数 |

**主要処理フロー**:
- **36-38行目**: workspacesモード有効時はワークスペース削除
- **39-41行目**: 無効時はウィンドウ構成復元
- **42行目**: 関連バッファをパターンマッチで削除

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

```
=calendar
    │
    ├─ [workspacesモード有効時]
    │      ├─ +workspace-switch "+calendar*" t
    │      ├─ doom/switch-to-scratch-buffer
    │      ├─ +calendar--init
    │      │      └─ +calendar/open-calendar
    │      │             └─ calfw-org-open-calendar
    │      └─ +workspace/display
    │
    └─ [workspacesモード無効時]
           ├─ current-window-configuration (保存)
           ├─ delete-other-windows
           ├─ switch-to-buffer
           └─ +calendar--init
                  └─ +calendar/open-calendar
                         └─ calfw-org-open-calendar

+calendar/quit
    │
    ├─ [workspacesモード有効時]
    │      └─ +workspace/kill
    │
    ├─ [workspacesモード無効時]
    │      └─ set-window-configuration
    │
    └─ doom-kill-matching-buffers "^\\*cfw[:-]"
```

### データフロー図

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

org-agenda-files   ───▶ calfw-org-create-source ───▶ org-agendaソース
                                                         │
iCalendar URL/file ───▶ calfw-ical-create-source ───▶ iCalendarソース
                                                         │
Google Calendar    ───▶ org-gcal                  ───▶ GCalソース
(org-gcal)                                               │
                                                         ▼
                                              calfw-open-calendar-buffer
                                                         │
                                                         ▼
                                                    カレンダー表示
                                                         │
                                                         ▼
キー入力           ───▶ ナビゲーション処理        ───▶ 表示更新

RET/SPC            ───▶ calfw-show-details        ───▶ 詳細ポップアップ
                        -command
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/app/calendar/config.el` | ソース | メイン設定ファイル、calfw設定とキーバインド |
| autoload.el | `modules/app/calendar/autoload.el` | ソース | 起動/終了コマンド、ワークスペース連携 |
| packages.el | `modules/app/calendar/packages.el` | 設定 | パッケージ依存関係定義 |
