# 画面設計書 20-カラー表示

## 概要

本ドキュメントは、Lua Language Serverの「カラー表示（textDocument/documentColor）」機能の画面設計書である。この機能は、ファイル内の色定義（16進数カラーコード）を検出し、色付きで表示する機能を提供する。

### 本画面の処理概要

この機能では、ドキュメント内の文字列リテラルから色定義（8桁ARGB形式または6桁RGB形式）を検出し、その色情報を返却する。エディタはこの情報を使用して、色定義の横にカラープレビューを表示する。

**業務上の目的・背景**：Luaでゲームやグラフィックスアプリケーションを開発する際、色定義が頻繁に使用される。16進数のカラーコードだけでは、実際の色を把握しにくい。カラー表示機能により、コード内の色定義が視覚的にプレビューされ、色の確認や修正が容易になる。

**画面へのアクセス方法**：ファイルを開くと自動的に色情報が取得される。対応する色形式の文字列があれば、その横にカラースウォッチ（色見本）が表示される。

**主要な操作・処理内容**：
1. ドキュメントのASTを取得する
2. 文字列リテラルを走査し、色定義パターンに一致するものを検出する
3. 8桁ARGB形式（AARRGGBB）または7桁HEX形式（#RRGGBB）を解析する
4. 各色定義の位置と色情報（RGBA）を返却する

**画面遷移**：カラースウォッチをクリックすると、カラープレゼンテーション（textDocument/colorPresentation）機能を通じてカラーピッカーが表示され、色を変更できる。

**権限による表示制御**：特になし。LSPプロトコルレベルでの認証・権限管理は行わない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 47 | ドキュメントカラー (textDocument/documentColor) | 主機能 | ファイル内の色定義を検出・表示する主処理 |

## 画面種別

LSP機能（カラー情報提供）

## URL/ルーティング

LSPメソッド: `textDocument/documentColor`

## 入出力項目

### 入力項目（リクエストパラメータ）

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| textDocument | TextDocumentIdentifier | Yes | 対象ドキュメントのURI |

### 出力項目（レスポンス）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| colorInformation | ColorInformation[] | 色情報配列 |

### ColorInformation構造

| 項目名 | 型 | 説明 |
|--------|-----|------|
| range | Range | 色定義の範囲 |
| color | Color | 色情報（RGBA） |

### 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） |

## 表示項目

| 表示項目 | 説明 |
|---------|------|
| カラースウォッチ | 色定義横に表示される色見本 |
| カラーピッカー | クリック時に表示される色選択UI |

## イベント仕様

### 1-documentColorリクエスト処理

1. クライアントからtextDocument/documentColorリクエストを受信
2. ドキュメントのASTを取得
3. guide.eachSourceで文字列リテラルを走査
4. isColor関数で色定義パターンに一致するか判定
5. 8桁ARGB形式の場合、textToColor関数で色を解析
6. 7桁HEX形式（#RRGGBB）の場合、hexTextToColor関数で色を解析
7. 各色定義の範囲と色情報をcolorValues配列に追加
8. LSP形式に変換してレスポンスを返却

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

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

この機能はデータベース操作を行わない。ソースコードを解析するのみで、変更は行わない。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| documentColorリクエスト | なし | SELECT（読み取り） | ソースコードの解析のみ |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| - | 成功 | （色情報配列返却） | 色定義が見つかった場合 |
| - | 成功 | null | 色定義が見つからない場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ファイルが見つからない | nullを返却 |
| ASTの取得に失敗 | nullを返却 |
| 色定義が存在しない | 空配列を返却 |

## 備考

- 対応色形式:
  - 8桁ARGB形式: `"AARRGGBB"` - アルファ、赤、緑、青の順で各2桁16進数
  - 7桁HEX形式: `"#RRGGBB"` - ハッシュ付き、赤、緑、青の順で各2桁16進数
- 色成分は0〜255の値を0.0〜1.0に正規化して返却
- 文字列リテラル内の色コードのみを検出（コメント内は対象外）
- colorPresentation機能と連携して色の編集が可能

---

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

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

### 推奨読解順序

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

まず、ColorとColorInformationの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | color.lua | `script/core/color.lua` (56-65行目) | Color, ColorValueクラス定義 |

**読解のコツ**: 色成分は0〜255の整数値を0.0〜1.0の浮動小数点数に正規化する。計算式は `component / 255`。

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

処理の起点となるプロバイダー登録を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | provider.lua | `script/provider/provider.lua` (1183-1209行目) | textDocument/documentColorの登録 |

**主要処理フロー**:
1. **1183行目**: `m.register 'textDocument/documentColor'`でハンドラー登録
2. **1189-1190行目**: `core/color`モジュールを読み込み
3. **1196行目**: `color.colors(uri)`で色情報を取得
4. **1201-1206行目**: 各色情報をLSP形式に変換

#### Step 3: コア処理を理解する

色検出のコアロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | color.lua | `script/core/color.lua` | 色検出の全体構造 |
| 3-2 | color.lua | `script/core/color.lua` (4-5行目) | 色パターン定義 |
| 3-3 | color.lua | `script/core/color.lua` (7-20行目) | isColor関数 - 色判定 |
| 3-4 | color.lua | `script/core/color.lua` (24-32行目) | textToColor関数 - 8桁ARGB解析 |
| 3-5 | color.lua | `script/core/color.lua` (36-43行目) | hexTextToColor関数 - 7桁HEX解析 |
| 3-6 | color.lua | `script/core/color.lua` (68-92行目) | colors関数 - メイン処理 |

**主要処理フロー**:
- **4-5行目**: `colorPattern`（8桁16進数）と`hex6Pattern`（#付き6桁16進数）を定義
- **7-20行目**: isColor関数 - 文字列長と正規表現でパターンマッチ
- **77-90行目**: guide.eachSourceで文字列を走査し、isColorで判定、textToColorまたはhexTextToColorで色解析

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

```
textDocument/documentColor (provider.lua:1183-1209)
    |
    +-- workspace.awaitReady (ワークスペース準備待機)
    |
    +-- files.getState (AST取得)
    |
    +-- core/color.colors (color.lua:68-92)
           |
           +-- guide.eachSource (文字列リテラル走査)
           |      |
           |      +-- source.type == 'string'判定
           |      |
           |      +-- isColor (7-20行目)
           |             |
           |             +-- colorPattern判定 (8桁)
           |             +-- hex6Pattern判定 (#付き6桁)
           |
           +-- textToColor (24-32行目) [8桁ARGB]
           |      +-- AARRGGBB解析
           |
           +-- hexTextToColor (36-43行目) [7桁HEX]
                  +-- #RRGGBB解析
```

### データフロー図

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

DocumentColorParams            provider.lua                        ColorInformation[]
+------------------+           +------------------+                 +------------------+
| textDocument.uri |  ------>  | files.getState   |                 | range            |
+------------------+           +------------------+                 |   start          |
                                      |                             |   end            |
                                      v                             | color            |
                               color.lua                            |   red            |
                               +----------------------+              |   green          |
                               | guide.eachSource     |  -------->  |   blue           |
                               |   source.type=='string'            |   alpha          |
                               |   isColor            |              +------------------+
                               |   textToColor        |
                               |   hexTextToColor     |
                               +----------------------+

[色形式変換]
"AARRGGBB" (8桁) --> { alpha: AA/255, red: RR/255, green: GG/255, blue: BB/255 }
"#RRGGBB"  (7桁) --> { alpha: 1.0,    red: RR/255, green: GG/255, blue: BB/255 }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| provider.lua | `script/provider/provider.lua` | ソース | LSPメソッドハンドラー登録 |
| color.lua | `script/core/color.lua` | ソース | 色検出・解析コアロジック |
| converter.lua | `script/proto/converter.lua` | ソース | 範囲変換処理 |
| files.lua | `script/files.lua` | ソース | ファイル管理・AST取得 |
| guide.lua | `script/parser/guide.lua` | ソース | AST操作ユーティリティ |
