# 機能設計書 12-ユーティリティ登録・生成（Utilities）

## 概要

本ドキュメントは、Tailwind CSSのユーティリティクラスの登録と生成を管理するUtilitiesクラスの設計について記述する。static（固定値）とfunctional（動的値）の2種類のユーティリティをサポートし、補完候補の提供も行う。

### 本機能の処理概要

Utilitiesクラスは、Tailwind CSSの全ユーティリティクラスの登録・管理・生成を担う中核モジュールである。ユーティリティクラス名をキーとして、そのCSSを生成するコンパイル関数を保持する。

**業務上の目的・背景**：Tailwind CSSはユーティリティファーストのCSSフレームワークであり、数百種類のユーティリティクラスを提供する。これらのユーティリティクラスの登録情報を一元管理し、候補クラス名からCSSノードを生成するためのレジストリが必要である。UtilitiesクラスはこのレジストリとしてDesignSystemの中核を構成する。

**機能の利用シーン**：コンパイルパイプラインでユーティリティCSSを生成する際、IntelliSenseで補完候補を提供する際、`@utility` ディレクティブでカスタムユーティリティを登録する際に使用される。

**主要な処理内容**：
1. staticユーティリティの登録: 固定値のユーティリティ（例: `underline`, `flex`）をコンパイル関数とともに登録する
2. functionalユーティリティの登録: 動的値を受け取るユーティリティ（例: `bg-*`, `text-*`）を登録する。型情報（UtilityOptions）も保持する
3. ユーティリティの検索: 名前とkindでの存在確認、名前での取得を行う
4. 補完候補の管理: IntelliSense向けにSuggestionGroupを管理する。テーマキーや修飾子の候補を提供する
5. createUtilities関数: 全組み込みユーティリティの登録を行う大規模な初期化関数
6. createCssUtility関数: `@utility` ディレクティブからユーティリティを生成する

**関連システム・外部連携**：DesignSystemを通じてcompileCandidates（compile.ts）から参照される。Theme（theme.ts）からテーマ値を取得し、ユーティリティのCSS値を生成する。

**権限による制御**：権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Appコンポーネント | 主機能 | m-3・p-3・border等のユーティリティクラスのCSS生成を担当する |
| 4 | トップページ | 補助機能 | skew-7ユーティリティクラスのCSS生成を担当する |
| 6 | トップページ | 主機能 | text-3xl・font-bold・underline・border・ring等のユーティリティクラスのCSS生成を担当する |

## 機能種別

データ管理 / CSS生成処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | ユーティリティクラス名（例: `bg`, `text`, `underline`） | 英数字・ハイフンで構成 |
| compileFn | CompileFn | Yes | 候補からASTノードを生成するコンパイル関数 | 関数型 |
| options | UtilityOptions | No | ユーティリティのオプション（types配列） | types は文字列配列 |

### 入力データソース

- createUtilities 関数によるハードコードされた組み込みユーティリティ定義
- `@utility` ディレクティブによるカスタムユーティリティ定義
- v3互換プラグインAPI経由のユーティリティ定義

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AstNode[] | AstNode[] | ユーティリティクラスに対応するCSSのAST表現 |
| SuggestionGroup[] | SuggestionGroup[] | 補完候補のグループ（値・修飾子の候補リスト） |
| keys | string[] | 登録済みユーティリティ名の一覧 |

### 出力先

- compileCandidates（compile.ts）を通じてCSS出力パイプラインに提供
- IntelliSense（intellisense.ts）を通じてIDE補完機能に提供

## 処理フロー

### 処理シーケンス

```
1. ユーティリティの登録
   ├─ static(): 固定値ユーティリティをDefaultMapに登録
   ├─ functional(): 動的値ユーティリティをDefaultMapに登録（オプション付き）
   └─ suggest(): 補完候補関数を登録

2. ユーティリティの検索・取得
   ├─ has(name, kind): 指定名前・種別でユーティリティの存在確認
   ├─ get(name): 指定名前のユーティリティ一覧を取得
   └─ keys(kind): 指定種別の全ユーティリティ名を一覧取得

3. ユーティリティのコンパイル（外部から呼び出し）
   └─ compileFn(candidate): Candidate構造体からASTノード配列を生成
```

### フローチャート

```mermaid
flowchart TD
    A[Candidate入力] --> B{utilities.has で存在確認}
    B -->|存在する| C[utilities.get でユーティリティ取得]
    B -->|存在しない| D[null を返す]
    C --> E{kind が一致?}
    E -->|static| F[compileFn にCandidate を渡す]
    E -->|functional| G[compileFn にCandidate を渡す]
    F --> H[ASTノード配列を返す]
    G --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-12-01 | 複数登録 | 同一名前に対して複数のユーティリティ（static/functional）を登録可能 | DefaultMapのため常に配列で管理 |
| BR-12-02 | 種別フィルタ | has/keys メソッドで kind を指定してフィルタリングできる | 検索・一覧取得時 |
| BR-12-03 | 補完候補の合成 | 既存の補完候補がある場合、新しい候補は追加（マージ）される | suggest呼び出し時に同名の既存候補がある場合 |
| BR-12-04 | staticの補完 | staticユーティリティは値なしの空SuggestionGroupを返す | getCompletions呼び出し時 |

### 計算ロジック

withAlpha 関数: 色にアルファ値を適用する。数値を百分率に変換し、`color-mix(in oklab, color percentage, transparent)` 形式のCSS式を生成する。100%の場合はcolor-mixを省略する。

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

本機能はデータベースを使用しない。ユーティリティ登録情報はインメモリの `DefaultMap<string, Utility[]>` で管理される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | undefined/null | compileFn が undefined/null を返した場合 | ユーティリティが生成されず、候補は無効として扱われる |

### リトライ仕様

リトライ処理は存在しない。

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

トランザクション管理は存在しない。

## パフォーマンス要件

- ユーティリティの検索は `DefaultMap.get()` / `DefaultMap.has()` による O(1) アクセス
- createUtilities は初期化時に1回のみ実行される。約6000行の組み込みユーティリティ定義を一括登録する

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

ユーティリティ生成はユーザ入力をCSS値として処理するため、CSS仕様の範囲内で安全に処理される。

## 備考

- utilities.ts は約6000行の大規模ファイルであり、全組み込みユーティリティの定義を含む
- CompileFn 型は generic であり、`static` と `functional` の Candidate 型に型安全に対応する
- DefaultMap は存在しないキーに対してデフォルト値（空配列）を自動生成するMap拡張である

---

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

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

### 推奨読解順序

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

ユーティリティの型定義と管理データ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | CompileFn 型（69-71行目）: Candidate のkindに基づいてASTノードを返す関数型 |
| 1-2 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | SuggestionGroup / SuggestionDefinition 型（73-89行目）: 補完候補のデータ構造 |
| 1-3 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | UtilityOptions / Utility 型（91-99行目）: ユーティリティのメタ情報 |
| 1-4 | candidate.ts | `packages/tailwindcss/src/candidate.ts` | Candidate 型（164-218行目）: ユーティリティが受け取る入力の型定義 |

**読解のコツ**: TypeScript の `Extract<T, U>` ユーティリティ型が CompileFn の定義で使用されている。これは Candidate の共用体型から特定の kind を持つ型を抽出する。

#### Step 2: Utilities クラスを理解する

レジストリとしてのUtilitiesクラスの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | Utilities クラス（101-155行目）: static/functional/has/get/suggest/keys の各メソッド |

**主要処理フロー**:
1. **101-102行目**: DefaultMap と completions Map の内部ストレージ初期化
2. **106-108行目**: `static()` - 固定値ユーティリティの登録
3. **110-112行目**: `functional()` - 動的値ユーティリティの登録（オプション付き）
4. **114-116行目**: `has()` - 名前と種別での存在確認
5. **118-120行目**: `get()` - 名前でのユーティリティ一覧取得
6. **132-139行目**: `suggest()` - 補完候補の登録（既存候補とのマージ対応）

#### Step 3: ヘルパー関数を理解する

ユーティリティ生成で使用されるヘルパー関数群を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | `property()` 関数（157-169行目）: @property ルールの生成 |
| 3-2 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | `withAlpha()` 関数（174-191行目）: color-mix による透明度適用 |
| 3-3 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | `createCssUtility()` 関数（5944行目以降）: @utility ディレクティブからのユーティリティ生成 |

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

```
DesignSystem (design-system.ts)
    │
    ├─ createUtilities(theme) → Utilities インスタンス生成
    │      └─ Utilities.static() / functional() / suggest() を多数呼び出し
    │
    ├─ Utilities.has(name, kind) ← parseCandidate から参照
    │
    ├─ Utilities.get(name) ← compileCandidates から参照
    │      └─ compileFn(candidate) → AstNode[]
    │
    └─ Utilities.getCompletions(name) ← IntelliSense から参照
           └─ SuggestionGroup[] を返す
```

### データフロー図

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

createUtilities(theme) ───▶ Utilities.static()       ───▶ utilities Map に登録
                            Utilities.functional()

Candidate 構造体       ───▶ Utilities.get(name)      ───▶ Utility[] を取得
                            compileFn(candidate)     ───▶ AstNode[] を生成

IntelliSense要求       ───▶ Utilities.getCompletions ───▶ SuggestionGroup[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| utilities.ts | `packages/tailwindcss/src/utilities.ts` | ソース | Utilitiesクラス本体と全組み込みユーティリティ定義 |
| design-system.ts | `packages/tailwindcss/src/design-system.ts` | ソース | Utilitiesインスタンスの生成と保持 |
| candidate.ts | `packages/tailwindcss/src/candidate.ts` | ソース | Candidate型定義。compileFn の入力型 |
| compile.ts | `packages/tailwindcss/src/compile.ts` | ソース | compileCandidates からUtilitiesを使用してCSS生成 |
| theme.ts | `packages/tailwindcss/src/theme.ts` | ソース | ユーティリティ値のテーマ解決に使用 |
| intellisense.ts | `packages/tailwindcss/src/intellisense.ts` | ソース | 補完候補取得でUtilitiesを参照 |
| index.ts | `packages/tailwindcss/src/index.ts` | ソース | @utility ディレクティブの処理 |
| default-map.ts | `packages/tailwindcss/src/utils/default-map.ts` | ソース | DefaultMap - ユーティリティ登録のストレージ |
| infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | ソース | CSS値の型推論。functional ユーティリティの値検証に使用 |
| value-parser.ts | `packages/tailwindcss/src/value-parser.ts` | ソース | CSS値のパース。ユーティリティ値の処理に使用 |
