# 画面設計書 28-CalendarDatePicker

## 概要

本ドキュメントは、Avalonia ControlCatalogサンプルアプリケーションにおけるCalendarDatePickerデモページの画面設計を定義するものです。

### 本画面の処理概要

本画面は、CalendarDatePickerコントロールの各種使用パターンをデモンストレーションするためのページです。カレンダードロップダウン形式での日付選択、フォーマット設定、ブラックアウト日付、プレースホルダー、バリデーションなど、日付選択UIの実装方法を学習・検証できる環境を提供します。

**業務上の目的・背景**：CalendarDatePickerは、カレンダーポップアップを伴う日付選択コントロールです。DatePickerのスピナー形式とは異なり、カレンダー全体を表示して視覚的に日付を選択できます。予約システムでの空き日程確認、特定日除外（祝日、休業日など）、期限設定などの場面で使用されます。

**画面へのアクセス方法**：ControlCatalogアプリケーションのメインウィンドウから、HamburgerMenuのナビゲーションで「CalendarDatePicker」を選択することでアクセスできます。

**主要な操作・処理内容**：
1. 短い日付形式での表示（SelectedDateFormat: Short）
2. 長い日付形式での表示（SelectedDateFormat: Long）
3. カスタム日付形式での表示（SelectedDateFormat: Custom, CustomDateFormatString）
4. ブラックアウト日付の設定（過去日を選択不可に）
5. プレースホルダーテキストの設定
6. フローティングプレースホルダーの設定
7. カスタム色のプレースホルダー
8. 無効化状態の表示
9. バリデーション機能のデモ

**画面遷移**：MainViewからHamburgerMenuナビゲーションを通じて遷移。画面内での追加遷移なし。

**権限による表示制御**：特になし（サンプルアプリケーション）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | Calendar | 主機能 | CalendarDatePickerのデモ。カレンダー付き日付選択 |

## 画面種別

デモ / サンプル表示

## URL/ルーティング

HamburgerMenu内部ナビゲーション（直接URLルーティングなし）

## 入出力項目

| 項目名 | 種別 | データ型 | 必須 | 説明 |
|--------|------|----------|------|------|
| DatePicker1 | 入力 | DateTimeOffset? | - | Short形式表示、初期値：今日 |
| DatePicker2 | 入力 | DateTimeOffset? | - | Long形式表示、初期値：今日+10日 |
| DatePicker3 | 入力 | DateTimeOffset? | - | Custom形式（ddd, MMM d）、初期値：今日+20日 |
| DatePicker4 | 入力 | DateTimeOffset? | - | ブラックアウト日付設定 |
| DatePicker5 | 入力 | DateTimeOffset? | - | フローティングプレースホルダー、初期値：今日 |
| Validation Example | 入力 | DateTimeOffset? | - | バリデーション対象 |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| 説明テキスト | TextBlock | 「A control for selecting dates with a calendar drop-down」 |
| SelectedDateFormat: Short | TextBlock | 短い形式のラベル |
| SelectedDateFormat: Long | TextBlock | 長い形式のラベル |
| SelectedDateFormat: Custom | TextBlock | カスタム形式のラベル |
| Blackout Dates | TextBlock | ブラックアウト日付のラベル |
| Placeholder | CalendarDatePicker | プレースホルダーテキスト |
| Floating Placeholder | CalendarDatePicker | フローティングプレースホルダー |
| PlaceholderText with custom color | TextBlock | カスタム色プレースホルダーのラベル |
| Disabled | TextBlock | 無効化状態のラベル |
| Validation Example | TextBlock | バリデーションのラベル |

## イベント仕様

### 1-CalendarDatePicker展開

CalendarDatePickerをクリックするとカレンダードロップダウンが表示される。月をナビゲートし、日付をクリックして選択。

### 2-DatePicker1（Short形式）日付選択

SelectedDateFormat="Short"により、システム設定に基づいた短い日付形式（例：2024/12/25）で表示される。初期値はDateTime.Today。

### 3-DatePicker2（Long形式）日付選択

SelectedDateFormat="Long"により、完全な日付形式（例：2024年12月25日 水曜日）で表示される。初期値はDateTime.Today.AddDays(10)。

### 4-DatePicker3（Custom形式）日付選択

SelectedDateFormat="Custom"とCustomDateFormatString="ddd, MMM d"により、カスタム形式（例：Wed, Dec 25）で表示される。初期値はDateTime.Today.AddDays(20)。

### 5-DatePicker4（ブラックアウト日付）日付選択

TemplateAppliedイベント後、BlackoutDates.AddDatesInPast()により過去日が全て選択不可に設定される。カレンダー上で過去日はグレーアウト表示。

### 6-フローティングプレースホルダー

UseFloatingPlaceholder="True"により、日付選択後もプレースホルダーテキストがフローティングラベルとして表示される。

### 7-Validation Example

ViewModelのValidatedDateExampleプロパティにバインドされ、バリデーションエラー時にエラー表示が行われる。

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

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

本画面はUIコントロールのデモであり、データベース操作は行いません。

## メッセージ仕様

| 種別 | メッセージID | メッセージ内容 | 表示条件 |
|------|-------------|---------------|----------|
| プレースホルダー | - | Placeholder | 日付未選択時 |
| プレースホルダー | - | Floating Placeholder | フローティング表示 |
| プレースホルダー | - | Select a date | カスタム色プレースホルダー |

## 例外処理

- 特になし（デモ画面のため）

## 備考

- BlackoutDates.AddDatesInPast()はTemplateApplied後に呼び出す必要がある
- UseFloatingPlaceholderはMaterial Design風のラベル表示
- PlaceholderForegroundでプレースホルダーの色をカスタマイズ可能
- CompiledBindingでValidatedDateExampleにバインド

---

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

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

### 推奨読解順序

#### Step 1: 画面レイアウトを理解する

XAMLで各コントロールの設定パターンを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CalendarDatePickerPage.xaml | `samples/ControlCatalog/Pages/CalendarDatePickerPage.xaml` | CalendarDatePickerの各種属性設定 |

**主要処理フロー**:
1. **行7**: 説明テキスト
2. **行14-17**: DatePicker1 - SelectedDateFormat="Short"
3. **行19-22**: DatePicker2 - SelectedDateFormat="Long"
4. **行24-28**: DatePicker3 - Custom形式、CustomDateFormatString
5. **行30-32**: DatePicker4 - ブラックアウト日付
6. **行34-39**: プレースホルダー設定
7. **行41-44**: カスタム色プレースホルダー
8. **行46-47**: 無効化状態
9. **行49-50**: バリデーション例

#### Step 2: コードビハインドを理解する

初期値設定とブラックアウト日付の設定を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CalendarDatePickerPage.xaml.cs | `samples/ControlCatalog/Pages/CalendarDatePickerPage.xaml.cs` | 初期値設定、TemplateAppliedイベントでのブラックアウト設定 |

**主要処理フロー**:
- **行10-12**: DatePicker1/2/3への初期日付設定
- **行15**: DatePicker5への初期日付設定
- **行17-20**: DatePicker4のTemplateAppliedイベントでBlackoutDates設定

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

```
CalendarDatePickerPage (UserControl)
    │
    ├─ コンストラクタ
    │      ├─ DatePicker1.SelectedDate = DateTime.Today
    │      ├─ DatePicker2.SelectedDate = DateTime.Today.AddDays(10)
    │      ├─ DatePicker3.SelectedDate = DateTime.Today.AddDays(20)
    │      ├─ DatePicker5.SelectedDate = DateTime.Today
    │      └─ DatePicker4.TemplateApplied += イベント登録
    │
    ├─ DatePicker4.TemplateApplied
    │      └─ BlackoutDates.AddDatesInPast()
    │
    └─ CalendarDatePicker群
           ├─ Short形式
           ├─ Long形式
           ├─ Custom形式
           ├─ ブラックアウト日付
           ├─ プレースホルダー
           ├─ フローティングプレースホルダー
           ├─ カスタム色プレースホルダー
           ├─ 無効化
           └─ バリデーション
```

### データフロー図

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

コンストラクタ ─────────▶ 初期日付設定 ──────────────────▶ SelectedDate
                              │
                              └─ TemplateApplied登録

TemplateApplied ────────▶ BlackoutDates.AddDatesInPast() ──▶ 過去日グレーアウト

カレンダークリック ─────▶ 日付選択判定 ──────────────────▶
                              │
                              ├─ ブラックアウト日 ───────▶ 選択不可
                              │
                              └─ 有効日 ─────────────────▶ SelectedDate更新

ValidatedDateExample ───▶ バリデーション ─────────────────▶ エラー表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CalendarDatePickerPage.xaml | `samples/ControlCatalog/Pages/CalendarDatePickerPage.xaml` | XAML | 画面レイアウト定義 |
| CalendarDatePickerPage.xaml.cs | `samples/ControlCatalog/Pages/CalendarDatePickerPage.xaml.cs` | ソース | コードビハインド |
| MainWindowViewModel.cs | `samples/ControlCatalog/ViewModels/MainWindowViewModel.cs` | ソース | ValidatedDateExampleプロパティ定義 |
