# 機能設計書 31-ColorPicker

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるColorPicker（色選択コントロール）の機能設計を定義するものである。ColorPickerはユーザーがRGB、HSV、HLS形式で色を選択・編集できる高機能なUIコンポーネントを提供する。

### 本機能の処理概要

ColorPickerは、スペクトラム、パレット、コンポーネントスライダーを使用して、ユーザーが直感的に色を選択・編集できる機能を提供する。ドロップダウンフライアウト内で編集が可能で、閉じた状態ではプレビューコンテンツエリアのみが表示される。

**業務上の目的・背景**：アプリケーション開発において、ユーザーが色を選択する必要があるシーンは多岐にわたる（テーマカスタマイズ、描画ツール、データ可視化の色分けなど）。ColorPickerは、これらの要件を満たす統一的なUI部品を提供し、開発効率の向上とユーザー体験の一貫性を実現する。また、複数の色空間（RGB/HSV/HLS）をサポートすることで、専門的な色選択ニーズにも対応する。

**機能の利用シーン**：
- グラフィックエディタでの描画色選択
- テーマカスタマイズ機能での色設定
- チャートやダッシュボードの色分け設定
- 背景色・前景色の設定ダイアログ

**主要な処理内容**：
1. スペクトラム表示による2次元色空間でのインタラクティブな色選択
2. パレット表示による定義済み色セットからの選択
3. RGB/HSV/HLSコンポーネントスライダーによる精密な色調整
4. Hex形式での直接入力と表示
5. アルファ（透明度）チャンネルのサポート
6. リアルタイムプレビュー表示

**関連システム・外部連携**：スタンドアロンの色選択コンポーネントとして動作するが、データバインディングを通じて他のコントロールやViewModelと連携可能。

**権限による制御**：特になし。UIコンポーネントとしての制限はなく、アプリケーション側で必要に応じて実装する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | ColorPicker | 主画面 | カラーピッカーコントロールのデモ。HLS/RGB/HSV形式での色指定 |

## 機能種別

データ入力 / UI操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Color | Color | No | 選択されている色（RGB形式） | 0-255の範囲内 |
| HsvColor | HsvColor | No | 選択されている色（HSV形式） | H:0-360, S:0-100, V:0-100 |
| IsAlphaEnabled | bool | No | アルファチャンネルを有効にするかどうか（デフォルト: true） | - |
| IsAlphaVisible | bool | No | アルファスライダーを表示するかどうか（デフォルト: true） | - |
| IsColorSpectrumVisible | bool | No | 色スペクトラムタブを表示するかどうか（デフォルト: true） | - |
| IsColorPaletteVisible | bool | No | 色パレットタブを表示するかどうか（デフォルト: true） | - |
| IsColorComponentsVisible | bool | No | コンポーネントスライダータブを表示するかどうか（デフォルト: true） | - |
| Palette | IColorPalette | No | 使用する色パレット | - |
| HexInputAlphaPosition | AlphaComponentPosition | No | Hex入力時のアルファ位置 | Beginning/End |

### 入力データソース

- ユーザー操作による直接入力（スペクトラムクリック、スライダー操作、パレット選択、Hex入力）
- データバインディングによるViewModel経由の設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Color | Color | 選択された色（ARGB形式） |
| HsvColor | HsvColor | 選択された色（HSV形式） |
| ColorChanged | event | 色が変更された際に発火するイベント |

### 出力先

- データバインディングを通じたViewModel更新
- ColorChangedイベントによる通知

## 処理フロー

### 処理シーケンス

```
1. コントロール初期化
   └─ テンプレート適用とコンポーネント取得
2. ユーザー操作検知
   └─ スペクトラム/パレット/スライダー/Hex入力
3. 色値計算・変換
   └─ RGB ⇔ HSV相互変換
4. プロパティ更新
   └─ Color/HsvColor同期更新
5. イベント発火
   └─ ColorChangedイベント通知
6. UI更新
   └─ 全関連コンポーネントの表示更新
```

### フローチャート

```mermaid
flowchart TD
    A[ユーザー操作] --> B{操作種別}
    B -->|スペクトラム| C[2D座標から色計算]
    B -->|パレット| D[パレット色取得]
    B -->|スライダー| E[コンポーネント値更新]
    B -->|Hex入力| F[16進数パース]
    C --> G[HSV色設定]
    D --> H[RGB色設定]
    E --> G
    F --> H
    G --> I[RGB ⇔ HSV同期]
    H --> I
    I --> J[ColorChangedイベント]
    J --> K[UI更新]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-31-01 | 色同期ルール | Color（RGB）とHsvColorは常に同期される | 色が変更された時 |
| BR-31-02 | アルファ無効化ルール | IsAlphaEnabled=falseの場合、アルファは常に255 | アルファ無効時 |
| BR-31-03 | 初期色強制ルール | #00000000から選択時、アルファと第3成分を最大値に設定 | 初期色が完全透明時 |

### 計算ロジック

RGB ⇔ HSV相互変換:
- RGB→HSV: 標準的な色空間変換アルゴリズムを使用
- HSV→RGB: 逆変換アルゴリズムを使用
- Hex変換: ARGBまたはRGBA形式（AlphaComponentPosition設定による）

## データベース操作仕様

該当なし（UIコンポーネントのためDB操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 入力エラー | 無効なHex文字列入力 | 直前の有効な色に戻す |
| - | 範囲エラー | HSVコンポーネントが範囲外 | 範囲内にクランプ |

### リトライ仕様

該当なし

## トランザクション仕様

該当なし

## パフォーマンス要件

- スペクトラムビットマップ生成: 非同期処理で実行
- 色変更時のUI更新: 60fps以上のレスポンス性

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

特になし（入力検証のみ必要）

## 備考

- ColorPickerはColorViewを継承しており、ドロップダウン形式の表示を追加
- ColorSpectrumコンポーネントはWinUIからの移植

---

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

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

### 推奨読解順序

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

色の表現とコンポーネント列挙型の定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | HsvComponent.cs | `src/Avalonia.Controls.ColorPicker/HsvComponent.cs` | HSV色空間のコンポーネント定義（Hue/Saturation/Value） |
| 1-2 | RgbComponent.cs | `src/Avalonia.Controls.ColorPicker/RgbComponent.cs` | RGB色空間のコンポーネント定義 |
| 1-3 | ColorComponent.cs | `src/Avalonia.Controls.ColorPicker/ColorComponent.cs` | 汎用色コンポーネント定義 |
| 1-4 | Hsv.cs | `src/Avalonia.Controls.ColorPicker/Helpers/Hsv.cs` | HSV色値の構造体と変換ロジック |
| 1-5 | Rgb.cs | `src/Avalonia.Controls.ColorPicker/Helpers/Rgb.cs` | RGB色値の構造体と変換ロジック |

**読解のコツ**: HsvとRgbの構造体はそれぞれToRgb()/ToHsv()変換メソッドを持つ。色空間変換の基本アルゴリズムを理解する。

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

ColorPickerクラスの継承関係と初期化フローを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ColorPicker.cs | `src/Avalonia.Controls.ColorPicker/ColorPicker/ColorPicker.cs` | メインクラス。ColorViewを継承し、ドロップダウン機能を追加 |

**主要処理フロー**:
1. **14行目**: `ColorPicker`クラス定義。`ColorView`を継承
2. **25-44行目**: Content/ContentTemplate/Alignmentプロパティ定義
3. **52-58行目**: Contentプロパティ - プレビュー領域のカスタマイズ

#### Step 3: ColorView - 色選択のコア機能

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ColorView.cs | `src/Avalonia.Controls.ColorPicker/ColorView/ColorView.cs` | 色選択UIのコア実装 |
| 3-2 | ColorView.Properties.cs | `src/Avalonia.Controls.ColorPicker/ColorView/ColorView.Properties.cs` | プロパティ定義 |

**主要処理フロー**:
- **40-55行目**: Hex TextBoxからの色取得と設定
- **176-197行目**: OnApplyTemplate - テンプレート適用とイベントハンドラ登録
- **200-286行目**: OnPropertyChanged - Color/HsvColor同期処理
- **301-309行目**: OnCoerceColor - アルファ無効時の強制処理
- **315-323行目**: OnCoerceHsvColor - HSVアルファ強制処理

#### Step 4: ColorSpectrum - 2Dスペクトラム

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ColorSpectrum.cs | `src/Avalonia.Controls.ColorPicker/ColorSpectrum/ColorSpectrum.cs` | 2次元色スペクトラムの実装 |
| 4-2 | ColorSpectrum.Properties.cs | `src/Avalonia.Controls.ColorPicker/ColorSpectrum/ColorSpectrum.Properties.cs` | スペクトラムプロパティ |
| 4-3 | ColorSpectrumShape.cs | `src/Avalonia.Controls.ColorPicker/ColorSpectrum/ColorSpectrumShape.cs` | 形状定義（Box/Ring） |
| 4-4 | ColorSpectrumComponents.cs | `src/Avalonia.Controls.ColorPicker/ColorSpectrum/ColorSpectrumComponents.cs` | 軸コンポーネント組み合わせ |

**主要処理フロー**:
- **117-172行目**: OnApplyTemplate - テンプレート部品取得とイベント登録
- **532-546行目**: SetColor - HSV→RGB変換と色設定
- **613-712行目**: UpdateColor - 色更新とUI同期
- **718-792行目**: UpdateColorFromPoint - ポインタ位置から色計算
- **1042-1231行目**: CreateBitmapsAndColorMap - スペクトラムビットマップ非同期生成

#### Step 5: ヘルパーとコンバーター

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | ColorPickerHelpers.cs | `src/Avalonia.Controls.ColorPicker/Helpers/ColorPickerHelpers.cs` | ビットマップ生成、色増減処理 |
| 5-2 | ColorHelper.cs | `src/Avalonia.Controls.ColorPicker/Helpers/ColorHelper.cs` | 輝度計算、色名取得 |
| 5-3 | ColorToHexConverter.cs | `src/Avalonia.Controls.ColorPicker/Converters/ColorToHexConverter.cs` | Hex文字列変換 |

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

```
ColorPicker (ドロップダウン管理)
    │
    └─ ColorView (色選択UI)
           │
           ├─ ColorSpectrum (2D色スペクトラム)
           │      ├─ CreateBitmapsAndColorMap() - ビットマップ生成
           │      ├─ UpdateColorFromPoint() - ポインタ→色変換
           │      └─ UpdateEllipse() - 選択位置更新
           │
           ├─ ColorSlider (コンポーネントスライダー)
           │
           ├─ ColorPreviewer (色プレビュー)
           │
           └─ HexTextBox (Hex入力)
                  └─ ColorToHexConverter.ParseHexString()
```

### データフロー図

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

スペクトラムクリック ───▶ UpdateColorFromPoint() ───▶ HsvColor更新
                              │
パレット選択 ─────────────▶ SetCurrentValue(Color) ───▶ Color更新
                              │
スライダー操作 ──────────▶ コンポーネント値更新 ────────▶ ↓
                              │
Hex入力 ───────────────────▶ ParseHexString() ─────────▶ ↓
                              │
                              ▼
                     OnPropertyChanged()
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
              Color ⇔ HsvColor 同期処理
                              │
                              ▼
                     ColorChangedイベント
                              │
                              ▼
                         UI全体更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ColorPicker.cs | `src/Avalonia.Controls.ColorPicker/ColorPicker/ColorPicker.cs` | ソース | メインコントロールクラス |
| ColorView.cs | `src/Avalonia.Controls.ColorPicker/ColorView/ColorView.cs` | ソース | 色選択UIコア実装 |
| ColorView.Properties.cs | `src/Avalonia.Controls.ColorPicker/ColorView/ColorView.Properties.cs` | ソース | ColorViewプロパティ定義 |
| ColorSpectrum.cs | `src/Avalonia.Controls.ColorPicker/ColorSpectrum/ColorSpectrum.cs` | ソース | 2Dスペクトラム実装 |
| ColorSpectrum.Properties.cs | `src/Avalonia.Controls.ColorPicker/ColorSpectrum/ColorSpectrum.Properties.cs` | ソース | スペクトラムプロパティ |
| ColorSlider.cs | `src/Avalonia.Controls.ColorPicker/ColorSlider/ColorSlider.cs` | ソース | 色コンポーネントスライダー |
| ColorPreviewer.cs | `src/Avalonia.Controls.ColorPicker/ColorPreviewer/ColorPreviewer.cs` | ソース | 色プレビュー表示 |
| IColorPalette.cs | `src/Avalonia.Controls.ColorPicker/ColorPalettes/IColorPalette.cs` | ソース | パレットインターフェース |
| FluentColorPalette.cs | `src/Avalonia.Controls.ColorPicker/ColorPalettes/FluentColorPalette.cs` | ソース | Fluentパレット実装 |
| Hsv.cs | `src/Avalonia.Controls.ColorPicker/Helpers/Hsv.cs` | ソース | HSV構造体と変換 |
| Rgb.cs | `src/Avalonia.Controls.ColorPicker/Helpers/Rgb.cs` | ソース | RGB構造体と変換 |
| ColorPickerHelpers.cs | `src/Avalonia.Controls.ColorPicker/Helpers/ColorPickerHelpers.cs` | ソース | ヘルパー関数 |
| ColorToHexConverter.cs | `src/Avalonia.Controls.ColorPicker/Converters/ColorToHexConverter.cs` | ソース | Hex変換コンバーター |
| ColorChangedEventArgs.cs | `src/Avalonia.Controls.ColorPicker/ColorChangedEventArgs.cs` | ソース | 色変更イベント引数 |
