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

## 概要

本ドキュメントは、Lua Language Serverにおけるカラープレゼンテーション機能（textDocument/colorPresentation）の設計仕様を記述する。この機能は、カラーピッカーで選択された色をテキスト形式に変換する。

### 本機能の処理概要

カラープレゼンテーション機能は、エディタのカラーピッカーからRGBA形式で渡された色を、Luaコードに挿入可能なテキスト形式（8桁の16進数ARGB文字列）に変換する。

**業務上の目的・背景**：機能No.47（ドキュメントカラー）でコード内の色を検出・表示した後、ユーザーがカラーピッカーで新しい色を選択した場合、その色をコードに反映する必要がある。この機能は、選択された色をLuaコードで使用される形式（8桁16進数）に変換し、コードへの挿入を可能にする。

**機能の利用シーン**：
- カラーピッカーで新しい色を選択した際のテキスト生成
- 色の変更をコードに反映したい場合

**主要な処理内容**：
1. クライアントからcolorPresentationリクエストを受信
2. 渡されたRGBA色を8桁16進数文字列に変換
3. 変換結果をラベルとして返却

**関連システム・外部連携**：
- LSPクライアントとのJSON-RPC通信
- 機能No.47（ドキュメントカラー）との連携

**権限による制御**：特に権限による制御は行われない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | カラープレゼンテーション | 主機能 | 色の代替表現を提供する主処理 |

## 機能種別

エディタ補助機能 / カラー変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| color | Color | Yes | 変換対象の色 | red/green/blue/alpha成分（0.0〜1.0） |
| textDocument.uri | string | Yes | 対象ドキュメントのURI | 有効なファイルURIであること |
| range | Range | Yes | 置換対象の範囲 | 有効な範囲であること |

Color構造体:
| 項目名 | 型 | 説明 |
|--------|-----|------|
| red | number | 赤成分（0.0〜1.0） |
| green | number | 緑成分（0.0〜1.0） |
| blue | number | 青成分（0.0〜1.0） |
| alpha | number | アルファ成分（0.0〜1.0） |

### 入力データソース

- LSPクライアントからのJSON-RPCリクエスト（カラーピッカー経由）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ColorPresentation[] | array | カラープレゼンテーションの配列 |
| ColorPresentation.label | string | 表示・挿入用テキスト（8桁16進数） |

### 出力先

- LSPクライアントへのJSON-RPCレスポンス

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ textDocument/colorPresentationメッセージを受信

2. 色変換
   └─ colorToText()でRGBAを8桁16進数に変換

3. レスポンス返却
   └─ { label: "AARRGGBB" }を配列で返却
```

### フローチャート

```mermaid
flowchart TD
    A[リクエスト受信] --> B[color.colorToText]
    B --> C[レスポンス返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-48-01 | ARGB形式 | 出力は8桁16進数（AARRGGBB）形式 | 常時 |
| BR-48-02 | 大文字出力 | 16進数は大文字で出力 | 常時 |
| BR-48-03 | 単一結果 | 配列には1要素のみ | 常時 |

### 計算ロジック

colorToText関数:
```lua
function colorToText(color)
    return string.format('%02X%02X%02X%02X'
        , math.floor(color.alpha * 255)
        , math.floor(color.red   * 255)
        , math.floor(color.green * 255)
        , math.floor(color.blue  * 255)
    )
end
```

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

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

本機能は入力をそのまま変換するため、特殊なエラー処理は行わない。

### リトライ仕様

該当なし。

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

該当なし（メモリ内処理のみ）

## パフォーマンス要件

- 即時応答（単純な文字列フォーマット処理）

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

- 特になし

## 備考

- colorProviderの一部として機能（capability共有）
- 機能No.47のcolorToText関数を再利用

---

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

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

### 推奨読解順序

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

入出力のデータ構造を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | color.lua | `script/core/color.lua` | colorToText関数（47-54行目） |

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

LSPリクエストハンドラを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | provider.lua | `script/provider/provider.lua` | colorPresentationの登録（1211-1216行目） |

**主要処理フロー**:
1. **1212行目**: ハンドラ関数定義（params受信）
2. **1213行目**: color.colorToText(params.color)呼び出し
3. **1214行目**: {{label = color}}で配列返却

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

```
provider.lua (m.register 'textDocument/colorPresentation')
    │
    └─ core/color.lua colorToText(params.color)
           │
           └─ string.format('%02X%02X%02X%02X', ...)
                  ├─ alpha * 255
                  ├─ red * 255
                  ├─ green * 255
                  └─ blue * 255
```

### データフロー図

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

LSPリクエスト             provider.lua
  └─ color        ───▶    └─ color.colorToText()
     ├─ red                      │
     ├─ green                    ├─ alpha * 255 → %02X
     ├─ blue                     ├─ red   * 255 → %02X
     └─ alpha                    ├─ green * 255 → %02X
                                 └─ blue  * 255 → %02X
                                         │
                                         ▼
                                 "AARRGGBB" (8桁)
                                         │
                                         ▼           ColorPresentation[]
                          LSPレスポンス ───────▶    └─ { label: "AARRGGBB" }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| provider.lua | `script/provider/provider.lua` | ソース | LSPリクエストハンドラの登録・実行 |
| color.lua | `script/core/color.lua` | ソース | colorToText関数の実装 |
