# 機能設計書 34-カラープレゼンテーション (textDocument/colorPresentation)

## 概要

本ドキュメントは、LSPプロトコルの `textDocument/colorPresentation` リクエストに対応するカラープレゼンテーション機能の設計を記述する。カラーピッカーで選択された色をHEXカラーコード文字列に変換して返却する。

### 本機能の処理概要

**業務上の目的・背景**：エディタのカラーピッカーUIでユーザーが色を選択した際、その色をD言語のDMLファイルで使用可能なHEXカラーコード文字列に変換する必要がある。本機能はLSP仕様の `textDocument/colorPresentation` に準拠し、RGBA値からHEXカラーコード文字列への変換を提供する。

**機能の利用シーン**：開発者がDMLファイル内のカラーコードをクリックしてカラーピッカーを開き、新しい色を選択した際に、エディタがこのリクエストを送信する。返却されたHEXカラーコードでソースコード内の既存のカラーコードが置換される。

**主要な処理内容**：
1. リクエストパラメータからテキストドキュメントと選択された色情報を取得する
2. ドキュメントの言語がDMLであることを確認する
3. アルファ値が1.0でない場合は `#AARRGGBB` 形式、1.0の場合は `#RRGGBB` 形式のHEXカラーコードを生成する
4. ColorPresentation配列として返却する

**関連システム・外部連携**：外部コンポーネントへの依存はない。単純な色値変換処理である。

**権限による制御**：特になし。DMLファイルに対してのみ処理が実行される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | カラー表示（textDocument/documentColor） | 補助機能 | カラーピッカーで選択された色をHEXカラーコード文字列に変換して返却する |

## 機能種別

データ変換処理（RGBA色値からHEXカラーコード文字列への変換）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| params.textDocument | TextDocumentIdentifier | Yes | 対象ドキュメントの識別子（URI） | ドキュメントが管理下に存在すること |
| params.color.red | double | Yes | 赤成分（0.0-1.0） | - |
| params.color.green | double | Yes | 緑成分（0.0-1.0） | - |
| params.color.blue | double | Yes | 青成分（0.0-1.0） | - |
| params.color.alpha | double | Yes | アルファ成分（0.0-1.0） | - |
| params.range | TextRange | Yes | 置換対象のテキスト範囲 | - |

### 入力データソース

LSPクライアントからの `textDocument/colorPresentation` リクエスト。カラーピッカーで選択された色のRGBA値が含まれる。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | ColorPresentation[] | カラープレゼンテーションの配列（要素数1）。DML以外はnull |
| ColorPresentation.label | string | HEXカラーコード文字列（#RRGGBB or #AARRGGBB） |

### 出力先

LSPクライアントへのレスポンスとして返却する。

## 処理フロー

### 処理シーケンス

```
1. ドキュメント取得
   └─ documents[params.textDocument.uri]でドキュメント取得
2. 言語チェック
   └─ getLanguageId != "dml" の場合はnullを返却
3. HEXカラーコード生成
   └─ alpha != 1.0 の場合: #AARRGGBB 形式（8文字HEX）
   └─ alpha == 1.0 の場合: #RRGGBB 形式（6文字HEX）
   └─ 各成分は 0.0-1.0 を 255 倍して整数化し、2桁HEXにフォーマット
4. 結果返却
   └─ ColorPresentation(hex) を単一要素の配列として返却
```

### フローチャート

```mermaid
flowchart TD
    A[textDocument/colorPresentation リクエスト受信] --> B[ドキュメント取得]
    B --> C{言語がDML?}
    C -->|No| D[null を返却]
    C -->|Yes| E{alpha != 1.0?}
    E -->|Yes| F["#AARRGGBB形式で生成"]
    E -->|No| G["#RRGGBB形式で生成"]
    F --> H["[ColorPresentation(hex)]を返却"]
    G --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-34-01 | DML限定 | DMLファイル以外ではnullを返却する | 常時 |
| BR-34-02 | HEX形式選択 | alpha != 1.0 の場合はAAを含む8文字形式、そうでなければ6文字形式 | 常時 |
| BR-34-03 | 小文字HEX | 出力するHEXカラーコードは小文字のa-fを使用する | 常時 |

### 計算ロジック

- `AA = format!"%02x"(cast(int)(alpha * 255))`
- `RR = format!"%02x"(cast(int)(red * 255))`
- `GG = format!"%02x"(cast(int)(green * 255))`
- `BB = format!"%02x"(cast(int)(blue * 255))`

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

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

本機能にデータベース操作は存在しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 非DMLファイル | ドキュメントの言語IDが "dml" でない | nullを返却 |

### リトライ仕様

リトライは行わない。

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

トランザクション管理は不要（読み取り専用処理）。

## パフォーマンス要件

単純な文字列フォーマット処理のみであり、即座に応答可能。

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

特になし。

## 備考

- 本機能はHEXカラー形式のみをサポートしている（RGB、HSL等の他の形式には非対応）。
- 常に単一のColorPresentationを返却する（配列の要素数は常に1）。
- 機能No.33「ドキュメントカラー」と対をなす機能であり、No.33がカラー検出、No.34がカラー表現の生成を担当する。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | protocol.d | `protocol/source/served/lsp/protocol.d` | ColorPresentationParams（3569行目）、Color構造体（3559行目）を確認 |

**読解のコツ**: ColorPresentationParamsはtextDocument, color, rangeの3フィールドを持つ。colorフィールドに選択された色のRGBA値が含まれる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | color.d | `source/served/commands/color.d` | `provideColorPresentations` 関数（58-81行目）がLSPリクエストハンドラ |

**主要処理フロー**:
1. **60行目**: `documents[params.textDocument.uri]` でドキュメント取得
2. **61-62行目**: DML言語チェック
3. **66行目**: `params.color.alpha != 1` でアルファ値判定
4. **67-72行目**: alpha != 1 の場合: `format!"#%02x%02x%02x%02x"` で #AARRGGBB 生成
5. **74-78行目**: alpha == 1 の場合: `format!"#%02x%02x%02x"` で #RRGGBB 生成
6. **80行目**: `[ColorPresentation(hex)]` で単一要素配列を返却

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

```
provideColorPresentations (color.d:58)
    |
    +-- documents[uri] (テキストドキュメント取得)
    |
    +-- document.getLanguageId (言語チェック: "dml")
    |
    +-- format!"#%02x..." (HEXカラーコード生成)
    |
    +-- ColorPresentation(hex) (結果構築)
```

### データフロー図

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

ColorPresentationParams  ──▶  provideColorPresentations    ──▶  [ColorPresentation]
  .color.red                    |                                  .label = "#rrggbb"
  .color.green                  +-- alpha判定
  .color.blue                   +-- RGBA→HEX変換
  .color.alpha                  |     (cast(int)(val*255))
                                +-- format!"%02x"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| color.d | `source/served/commands/color.d` | ソース | LSPリクエストハンドラ（メイン処理、No.33と同一ファイル） |
| protocol.d | `protocol/source/served/lsp/protocol.d` | ソース | ColorPresentationParams/Color等のLSP型定義 |
| extension.d | `source/served/extension.d` | ソース | サーバーケイパビリティにcolorProviderを登録（306行目） |
| types.d | `source/served/types.d` | ソース | 共通型定義・documentsへのアクセス |
