# 機能設計書 35-クラスリスト取得（getClassList）

## 概要

本ドキュメントは、Tailwind CSSにおける利用可能な全ユーティリティクラスリストの生成機能（getClassList）の機能設計を記述する。

### 本機能の処理概要

登録されたすべてのユーティリティクラスとその修飾子情報（modifiers）のリストを生成する機能である。IDE補完機能（IntelliSense）で利用可能なクラス候補の一覧を提供する。

**業務上の目的・背景**：Tailwind CSSのIDE統合（VS Code拡張等）において、開発者がクラス名を入力する際のオートコンプリートを実現するために、利用可能なすべてのユーティリティクラスの一覧が必要である。本機能は、DesignSystemに登録されたstatic/functionalユーティリティからクラス名リストを生成し、各クラスに使用可能な修飾子（modifier）の情報を付加して返す。また、負の値（例: -mx-4）をサポートするユーティリティについても対応する。

**機能の利用シーン**：
- VS Code拡張機能でのクラス名オートコンプリート
- IntelliSense APIを通じたユーティリティクラスの一覧取得
- DesignSystem.getClassList()メソッドの呼び出し時

**主要な処理内容**：
1. staticユーティリティの列挙と補完候補の取得
2. functionalユーティリティの列挙と各値に対する補完候補の生成
3. 負の値サポート（supportsNegative）の処理
4. 修飾子（modifiers）の重複排除
5. クラス名のアルファベット順ソート
6. 分数値（fraction: 1/2, 2/3等）の末尾移動

**関連システム・外部連携**：DesignSystem APIの一部として公開される。IDE拡張機能（Tailwind CSS IntelliSense）から利用される。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面に直接関連しないAPI機能。IDEの補完UIに間接的に関連 |

## 機能種別

データ取得処理（ユーティリティクラスリストの生成）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| design | DesignSystem | Yes | デザインシステムオブジェクト | 有効なDesignSystemインスタンスであること |

### 入力データソース

DesignSystemオブジェクトの`utilities`プロパティからstaticおよびfunctionalユーティリティのキーと補完候補を取得する。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | ClassEntry[] | `[string, { modifiers: string[] }]`のタプル配列。クラス名と修飾子リストのペア |

### 出力先

呼び出し元への戻り値として返される。

## 処理フロー

### 処理シーケンス

```
1. DefaultMapの初期化
   └─ クラス名→ClassItemのマッピングを作成
2. staticユーティリティの処理
   └─ design.utilities.keys('static')で全staticユーティリティを列挙
   └─ 各ユーティリティのgetCompletionsを取得
   └─ 補完候補がある場合のみ、items MapにClassItemを追加
3. functionalユーティリティの処理
   └─ design.utilities.keys('functional')で全functionalユーティリティを列挙
   └─ 各ユーティリティのgetCompletionsを取得
   └─ 各補完グループの各値に対して:
       ├─ クラス名を構築（utility-value形式）
       ├─ 分数値かどうかを判定（/^\d+\/\d+$/）
       ├─ 修飾子リストを蓄積
       ├─ supportsNegativeの場合、負のクラス名も追加
       └─ 修飾子の重複排除
4. ソートと分数値の末尾移動
   └─ compare関数でアルファベット順ソート
   └─ sortFractionsLastで分数値をユーティリティグループの末尾に移動
5. ClassEntry配列の構築
   └─ [name, { modifiers }]のペアに変換して返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[DefaultMap初期化]
    B --> C[staticユーティリティ列挙]
    C --> D[各staticの補完候補をitemsに追加]
    D --> E[functionalユーティリティ列挙]
    E --> F[各functionalの補完グループを処理]
    F --> G{値がnull?}
    G -->|Yes| H[クラス名=ユーティリティ名]
    G -->|No| I[クラス名=ユーティリティ名-値]
    H --> J[分数判定・修飾子追加]
    I --> J
    J --> K{supportsNegative?}
    K -->|Yes| L[負のクラス名も追加]
    K -->|No| M[修飾子の重複排除]
    L --> M
    M --> F
    F --> N{items空?}
    N -->|Yes| O[空配列を返却]
    N -->|No| P[compare関数でソート]
    P --> Q[sortFractionsLastで分数値を末尾に]
    Q --> R[ClassEntry配列を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-35-01 | staticユーティリティ | 補完候補がある場合のみリストに含める | completions.length > 0 |
| BR-35-02 | functionalユーティリティ | ユーティリティ名と値を`-`で結合してクラス名を構築 | 値がnullでない場合 |
| BR-35-03 | 値がnull | ユーティリティ名そのものをクラス名とする | 値がnullの場合 |
| BR-35-04 | 分数値の判定 | `/^\d+\/\d+$/`に一致する値を分数として識別 | 値が存在する場合 |
| BR-35-05 | 負の値サポート | supportsNegativeの場合、`-`を前置した負のクラス名も追加 | supportsNegativeが true の場合 |
| BR-35-06 | 修飾子の重複排除 | Setを使用して重複する修飾子を除去する | 常に |
| BR-35-07 | アルファベット順ソート | compare関数による自然順ソート | 常に |
| BR-35-08 | 分数値の末尾移動 | 分数値をそのユーティリティグループの末尾に配置する | 分数値が含まれる場合 |

### 計算ロジック

sortFractionsLastのアルゴリズム:
1. ユーティリティ名でバケットに分割
2. 各バケット内の分数値を別途収集
3. 各ユーティリティの最後のバケットに分数値を追加
4. バケットをフラット化してClassEntry配列を構築

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

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

データベース操作なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 空リスト | ユーティリティが1つも登録されていない | 空配列を返す |

### リトライ仕様

リトライは不要。

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

トランザクション管理なし。

## パフォーマンス要件

- 全ユーティリティを走査するため、登録されたユーティリティ数に応じたO(n)の計算コスト
- DefaultMapによるキャッシュ/メモ化でClassItemの重複生成を回避
- ソート処理のコストはO(n log n)

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

特になし。

## 備考

- ClassEntry型は`[string, { modifiers: string[] }]`のタプルである
- 分数値（例: w-1/2, w-2/3）はソート時にユーティリティグループの末尾に配置される。これにより、w-1, w-2, ..., w-1/2, w-1/3, ...のような直感的な順序が実現される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | intellisense.ts | `packages/tailwindcss/src/intellisense.ts` | ClassItem型（13-18行目）とClassEntry型（20行目）の定義 |
| 1-2 | intellisense.ts | `packages/tailwindcss/src/intellisense.ts` | ClassMetadata型（9-11行目） |

**読解のコツ**:
- `ClassItem`: 内部処理用の中間データ構造。name, utility, fraction, modifiersの4フィールドを持つ
- `ClassEntry`: 外部に公開されるタプル型。`[string, ClassMetadata]`
- `IS_FRACTION`: 分数値判定の正規表現（22行目）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | intellisense.ts | `packages/tailwindcss/src/intellisense.ts` | `getClassList`関数（24-79行目） |

**主要処理フロー**:
1. **25-30行目**: DefaultMapの初期化。クラス名→ClassItemのデフォルト値を定義
2. **33-40行目**: staticユーティリティの処理。`design.utilities.keys('static')`で列挙
3. **43-68行目**: functionalユーティリティの処理。補完グループ→値のネストループ
4. **48行目**: 分数値判定: `IS_FRACTION.test(value)`
5. **50行目**: クラス名の構築: `utility-value`形式
6. **57-61行目**: supportsNegativeの処理。`-`を前置した負のクラス名を追加
7. **65行目**: 修飾子の重複排除: `Array.from(new Set(...))`
8. **73行目**: compare関数でアルファベット順ソート
9. **76行目**: sortFractionsLastで分数値を末尾に移動

#### Step 3: 分数値ソートを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | intellisense.ts | `packages/tailwindcss/src/intellisense.ts` | `sortFractionsLast`関数（81-141行目） |

**主要処理フロー**:
- **88-89行目**: Bucket型の定義とbuckets配列の初期化
- **97-117行目**: ClassItemをユーティリティ名ごとのバケットに分割、分数値を別途収集
- **124-129行目**: 分数値を最後のバケットに追加
- **134-138行目**: バケットをフラット化してClassEntry配列に変換

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

```
DesignSystem.getClassList (design-system.ts:170-172)
    │
    └─ getClassList (intellisense.ts:24)
           │
           ├─ design.utilities.keys('static')
           │      └─ staticユーティリティ名の列挙
           │
           ├─ design.utilities.keys('functional')
           │      └─ functionalユーティリティ名の列挙
           │
           ├─ design.utilities.getCompletions()
           │      └─ 各ユーティリティの補完候補取得
           │
           ├─ compare() (utils/compare.ts)
           │      └─ アルファベット順ソート
           │
           └─ sortFractionsLast() (intellisense.ts:81)
                  └─ 分数値をグループ末尾に移動
```

### データフロー図

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

DesignSystem          ───▶ staticユーティリティ処理      ───▶ ClassItem Map
  .utilities                │
                            ├─ functionalユーティリティ処理
                            │   ├─ 値の結合
                            │   ├─ 分数判定
                            │   ├─ 負の値生成
                            │   └─ 修飾子収集
                            │
                            ├─ compare()でソート
                            │
                            └─ sortFractionsLast()      ───▶ ClassEntry[]
                                                              [["bg-red-500", {modifiers: []}],
                                                               ["w-1/2", {modifiers: []}],
                                                               ...]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| intellisense.ts | `packages/tailwindcss/src/intellisense.ts` | ソース | メイン処理: getClassList関数とsortFractionsLast関数 |
| design-system.ts | `packages/tailwindcss/src/design-system.ts` | ソース | DesignSystem API: getClassListメソッド公開 |
| utilities.ts | `packages/tailwindcss/src/utilities.ts` | ソース | Utilitiesクラス: keys(), getCompletions()メソッド |
| compare.ts | `packages/tailwindcss/src/utils/compare.ts` | ソース | 自然順ソート比較関数 |
| default-map.ts | `packages/tailwindcss/src/utils/default-map.ts` | ソース | DefaultMap: キャッシュ付きMap拡張 |
