# 画面設計書 21-カラープレゼンテーション

## 概要

本ドキュメントは、Lua Language Serverにおける「カラープレゼンテーション」機能の画面設計書です。LSPプロトコルの `textDocument/colorPresentation` リクエストに対応し、色の代替表現を提供します。

### 本画面の処理概要

カラープレゼンテーション機能は、エディタで検出された色に対して、異なる形式での色表現を提供する機能です。例えば、ARGB形式の色コードに対して、代替の表記方法を提案します。

**業務上の目的・背景**：Luaコード内で色を扱う場合、様々な形式で色を表現することがあります。開発者がある色形式から別の形式に変換したい場合に、この機能を使用することで、手動での変換作業を省略できます。特にゲーム開発やUI開発において、色の形式変換は頻繁に行われる作業であり、この機能により開発効率が向上します。

**画面へのアクセス方法**：エディタ（VS Code等）で、色として認識された文字列（8桁のARGB形式または7桁の#RRGGBB形式）にカーソルを合わせ、カラーピッカーを開いた際に自動的にこの機能が呼び出されます。エディタのカラーピッカーUIから色を選択・変更する際に、変換後の色コードが提供されます。

**主要な操作・処理内容**：
1. エディタからカラープレゼンテーションリクエストを受信
2. リクエストに含まれる色情報（RGBA値）を解析
3. 色情報を8桁のARGB形式（例：`FF00FF00`）の文字列に変換
4. 変換結果をエディタに返却し、ユーザーが選択可能な形式で表示

**画面遷移**：この機能は、`textDocument/documentColor`（カラー表示）機能で検出された色に対して呼び出されます。カラー表示機能が色を検出し、ユーザーがその色を編集しようとした際にカラープレゼンテーション機能が連携して動作します。

**権限による表示制御**：特別な権限制御はありません。Luaファイルが開かれている全てのユーザーが利用可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 48 | カラープレゼンテーション (textDocument/colorPresentation) | 主機能 | 色の代替表現を提供する主処理 |
| 47 | ドキュメントカラー (textDocument/documentColor) | 補助機能 | 色の検出処理（前提機能） |

## 画面種別

LSP機能（カラーピッカー連携）

## URL/ルーティング

LSPメソッド: `textDocument/colorPresentation`

## 入出力項目

### 入力パラメータ

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| textDocument | TextDocumentIdentifier | はい | 対象ドキュメントの識別子 |
| color | Color | はい | 変換対象の色情報（red, green, blue, alpha: 0.0-1.0） |
| range | Range | はい | 色が表示されている範囲 |

### 出力パラメータ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| colorPresentations | ColorPresentation[] | 色の代替表現リスト |
| colorPresentations[].label | string | 表示用ラベル（8桁のARGB形式） |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| label | string | 色の代替表現（例：`FF00FF00`） |

## イベント仕様

### 1-カラープレゼンテーション要求

1. エディタが `textDocument/colorPresentation` リクエストを送信
2. サーバーが `colorToText` 関数で色をテキスト形式に変換
3. 8桁のARGB形式（AARRGGBB）の文字列を生成
4. レスポンスとしてラベル付きの色表現を返却

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| カラープレゼンテーション要求 | - | - | データベース操作なし（読み取り専用） |

## メッセージ仕様

| メッセージID | 種別 | 表示内容 | 発生条件 |
|-------------|------|----------|----------|
| - | - | - | 通常メッセージは表示されない |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 無効な色情報 | 空の配列を返却 |
| ファイルが存在しない | 空の配列を返却 |

## 備考

- 色の検出は `textDocument/documentColor` で行われ、本機能は検出された色の変換のみを担当
- 出力形式は常にARGB形式（8桁16進数）
- Alpha値は最初の2桁、RGB値が続く6桁で表現される

---

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

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

### 推奨読解順序

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

LSPプロトコルで定義されるColor型とColorPresentation型の構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | color.lua | `script/core/color.lua` | Color構造体の定義（59-65行目）とcolorToText関数（47-54行目）を確認 |

**読解のコツ**: Color型はred, green, blue, alphaの4つのフィールドを持ち、各値は0.0〜1.0の範囲で正規化されています。

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

LSPリクエストハンドラがどのように呼び出されるかを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | provider.lua | `script/provider/provider.lua` | `textDocument/colorPresentation` ハンドラ（1211-1216行目）を確認 |

**主要処理フロー**:
1. **1211行目**: `m.register 'textDocument/colorPresentation'` でハンドラを登録
2. **1212行目**: パラメータからcolor情報を取得
3. **1213行目**: `core.color.colorToText(params.color)` で色をテキストに変換
4. **1214行目**: 変換結果を配列に包んで返却

#### Step 3: 色変換処理を理解する

色情報をテキスト形式に変換する処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | color.lua | `script/core/color.lua` | colorToText関数（47-54行目）の変換ロジックを確認 |

**主要処理フロー**:
- **47-54行目**: ARGB形式の文字列を生成（Alpha, Red, Green, Blueの順）
- **48-52行目**: 各色成分を0-255の整数に変換し、2桁の16進数文字列にフォーマット

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

```
textDocument/colorPresentation (provider.lua:1211-1216)
    │
    └─ colorToText (color.lua:47-54)
           │
           └─ string.format('%02X%02X%02X%02X', alpha, red, green, blue)
```

### データフロー図

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

Color {                   colorToText()                    ColorPresentation[] {
  alpha: 1.0,      ───▶   - alpha * 255 → 'FF'    ───▶      label: 'FF00FF00'
  red: 0.0,               - red * 255 → '00'               }
  green: 1.0,             - green * 255 → 'FF'
  blue: 0.0               - blue * 255 → '00'
}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| provider.lua | `script/provider/provider.lua` | ソース | LSPリクエストハンドラの登録・処理 |
| color.lua | `script/core/color.lua` | ソース | 色の検出・変換処理のコアロジック |
| proto.lua | `script/proto/proto.lua` | ソース | LSPプロトコル通信の基盤 |
