# 機能設計書 5-CSS値パーサー（ValueParser）

## 概要

本ドキュメントは、CSSプロパティ値をword・function・separatorノードに分解するValueParserの機能設計書である。theme()関数等のCSS関数処理に使用される。

### 本機能の処理概要

**業務上の目的・背景**：Tailwind CSSでは`theme()`、`--spacing()`、`--alpha()`等のカスタムCSS関数を処理する必要がある。CSS値文字列を構造化されたASTに変換することで、関数呼び出しの検出・引数の解析・値の置換が可能になる。

**機能の利用シーン**：css-functions.tsのsubstituteFunctions関数からCSS宣言値の解析に使用される。また、ast.tsのoptimizeAst関数内でcolor-mix()ポリフィル生成時の値解析にも使用される。

**主要な処理内容**：
1. CSS値文字列を1文字ずつスキャンし、トークンを識別する
2. 関数呼び出し（`name(...)`）をfunctionノードとしてネスト構造で表現する
3. スペース・コンマ・コロン等の区切り文字をseparatorノードとしてグループ化する
4. その他の値トークンをwordノードとして生成する
5. スラッシュ（`/`）を独立したwordノードとして分離する（modifier記法対応）
6. 解析結果のASTをCSS文字列に逆変換するtoCss関数を提供する

**関連システム・外部連携**：特になし。純粋な文字列処理。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CSS関数処理の内部で間接的に使用される |

## 機能種別

データ変換処理（CSS値文字列 -> ValueAstNode配列）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| input | string | Yes | CSS値文字列 | CRLF改行はLFに正規化される |

### 入力データソース

- CSS宣言のvalueフィールド

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ast | ValueAstNode[] | パース済みの値ASTノード配列 |

### 出力先

- css-functions.tsのsubstituteFunctions関数に返却される
- ast.tsのoptimizeAst関数に返却される

## 処理フロー

### 処理シーケンス

```
1. 前処理
   └─ CRLF改行をLFに正規化
2. 文字スキャンループ
   ├─ バックスラッシュ: エスケープ処理（次文字をバッファに含む）
   ├─ スラッシュ(/): バッファをwordとして確定、/を独立wordとして出力
   ├─ 区切り文字(スペース,コンマ,コロン,=,>,<,改行,タブ):
   │   ├─ バッファをwordとして確定
   │   └─ 連続する区切り文字をまとめてseparatorノードに
   ├─ 引用符('/"): 文字列リテラルをバッファに含む
   ├─ 開き丸括弧((: functionノード生成、スタックプッシュ
   ├─ 閉じ丸括弧(): バッファをword確定、スタックポップ
   └─ その他: バッファに蓄積
3. 後処理
   └─ 残りバッファをwordとして確定
```

### フローチャート

```mermaid
flowchart TD
    A[CSS値文字列入力] --> B[CRLF正規化]
    B --> C{文字スキャンループ}
    C --> D{文字種判定}
    D -->|バックスラッシュ| E[エスケープ処理]
    D -->|スラッシュ| F[バッファ確定+/をword化]
    D -->|区切り文字| G[separatorノード生成]
    D -->|引用符| H[文字列リテラル処理]
    D -->|開き括弧| I[functionノード生成]
    D -->|閉じ括弧| J[スタックポップ]
    D -->|その他| K[バッファ蓄積]
    E --> C
    F --> C
    G --> C
    H --> C
    I --> C
    J --> C
    K --> C
    C -->|完了| L[残りバッファ確定]
    L --> M[ValueAstNode配列返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | スラッシュの分離 | `/`は独立したwordノードとして分離される（modifier記法対応） | スラッシュ文字出現時 |
| BR-02 | 区切り文字のグループ化 | 連続する区切り文字は1つのseparatorノードにまとめられる | 区切り文字が連続する場合 |
| BR-03 | 関数のネスト | 関数呼び出しはfunctionノードとしてネスト構造で表現される | `name(`パターンの出現時 |
| BR-04 | 引用符内の保護 | 引用符内の文字はエスケープ以外全てバッファに含まれる | 文字列リテラル内 |

### 計算ロジック

特になし。

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

該当なし

## エラー処理

### エラーケース一覧

本パーサーは明示的なエラーをスローしない。不正な入力に対してもベストエフォートでパースを行う。

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- charCodeAtによる数値比較で高速な文字種判定を実現
- switch文による分岐最適化

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

特になし。

## 備考

- ValueAstNodeは3種類: `word`（値トークン）、`function`（関数呼び出し、子ノード持ち）、`separator`（区切り文字列）
- `toCss`関数により解析結果を元のCSS文字列に戻すことが可能（ラウンドトリップ）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | value-parser.ts | `packages/tailwindcss/src/value-parser.ts` | ValueAstNode型（1-17行目）: ValueWordNode、ValueFunctionNode、ValueSeparatorNodeの3種類 |

**読解のコツ**: `ValueFunctionNode`のみが`nodes`プロパティを持ち、再帰的なネスト構造を形成する。`value`フィールドは関数名（括弧前の文字列）を保持する。

#### Step 2: parse関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | value-parser.ts | `packages/tailwindcss/src/value-parser.ts` | `parse`関数（73-279行目）のswitch文による文字種ごとの処理 |

**主要処理フロー**:
1. **74行目**: CRLF正規化
2. **86-271行目**: メインのforループとswitch文
3. **92-96行目**: バックスラッシュによるエスケープ
4. **101-123行目**: スラッシュの独立word化
5. **133-181行目**: 区切り文字のseparatorノード化
6. **224-237行目**: 開き括弧によるfunctionノード生成
7. **247-264行目**: 閉じ括弧によるスタックポップ

#### Step 3: toCss関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | value-parser.ts | `packages/tailwindcss/src/value-parser.ts` | `toCss`関数（41-56行目）。ASTからCSS文字列への逆変換 |

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

```
ValueParser.parse(input)
    |
    +-- word(value)             ... wordノード生成
    +-- fun(value, nodes)       ... functionノード生成
    +-- separator(value)        ... separatorノード生成

ValueParser.toCss(ast)          ... AST→CSS文字列変換
```

### データフロー図

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

"theme(--color-red-500)"
                   ──▶  parse()                ──▶  [
                                                      {kind:'function', value:'theme',
                                                       nodes:[{kind:'word', value:'--color-red-500'}]}
                                                    ]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| value-parser.ts | `packages/tailwindcss/src/value-parser.ts` | ソース | ValueParser本体（parse, toCss, 型定義） |
| css-functions.ts | `packages/tailwindcss/src/css-functions.ts` | ソース | 主要な利用元（substituteFunctions） |
| ast.ts | `packages/tailwindcss/src/ast.ts` | ソース | optimizeAst内のcolor-mixポリフィル処理で使用 |
