# 機能設計書 63-データ型推論（inferDataType）

## 概要

本ドキュメントは、Tailwind CSSにおけるCSS値のデータ型推論ユーティリティ関数群の機能設計を記述する。`inferDataType`関数を中心に、CSS値が色・長さ・パーセンテージ・角度・数値・URL・画像などのデータ型のいずれに該当するかを判定する。functional utilityの任意値解決に使用される中核機能である。

### 本機能の処理概要

**業務上の目的・背景**：Tailwind CSSのfunctional utilityは、ユーザーが指定した任意の値（arbitrary values）を受け取る。例えば`text-[#ff0000]`の`#ff0000`は色として、`w-[100px]`の`100px`は長さとして解釈される必要がある。本機能はCSS仕様に基づいたルールでCSS値の型を自動推論し、適切なCSSプロパティへのマッピングを可能にする。

**機能の利用シーン**：ユーティリティクラスの値型判定（utilities.ts）、バリアントのパラメータ検証（variants.ts）、候補の正規化処理（canonicalize-candidates.ts）、定数畳み込み処理（constant-fold-declaration.ts）、v3互換プラグインAPI（plugin-api.ts）、v3互換レガシーユーティリティ（legacy-utilities.ts）、v3互換デフォルトテーマ（default-theme.ts）で使用される。

**主要な処理内容**：
1. メイン関数`inferDataType`は指定された型リストの順序で値を判定し、最初にマッチした型を返す
2. 17種類のデータ型に対応する判定関数群（isColor, isLength, isPercentage, isNumber等）を提供する
3. CSS数学関数（calc, min, max等）を含む値にも対応する（hasMathFn経由）
4. 補助的な検証関数（isPositiveInteger, isStrictPositiveInteger, isValidSpacingMultiplier, isValidOpacityValue）を公開エクスポートする

**関連システム・外部連携**：外部システムとの連携はない。CSS仕様（MDN Web Docs）に基づいた型判定ルールを実装している。

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

## 関連画面

本機能は内部ユーティリティ関数であり、画面に直接関連しない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | 補助機能 | ユーティリティクラスの値型判定として間接的に全画面のCSS生成に寄与 |

## 機能種別

計算処理（データ型判定・バリデーション）

## 入力仕様

### 入力パラメータ

#### inferDataType関数

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| value | string | Yes | 型推論対象のCSS値文字列 | var()で始まる場合はnullを返す |
| types | DataType[] | Yes | チェックする型の優先順序リスト | DataType型の配列 |

#### DataType型定義

| 値 | 説明 | 判定関数 |
|-----|------|---------|
| 'color' | CSS色値 | isColor |
| 'length' | CSS長さ値 | isLength |
| 'percentage' | CSSパーセンテージ値 | isPercentage |
| 'ratio' | 比率（分数） | isFraction |
| 'number' | 数値 | isNumber |
| 'integer' | 正の整数 | isPositiveInteger |
| 'url' | URL値 | isUrl |
| 'position' | 背景位置 | isBackgroundPosition |
| 'bg-size' | 背景サイズ | isBackgroundSize |
| 'line-width' | 線幅 | isLineWidth |
| 'image' | 画像値 | isImage |
| 'family-name' | フォントファミリー名 | isFamilyName |
| 'generic-name' | 汎用フォントファミリー | isGenericName |
| 'absolute-size' | 絶対サイズキーワード | isAbsoluteSize |
| 'relative-size' | 相対サイズキーワード | isRelativeSize |
| 'angle' | CSS角度値 | isAngle |
| 'vector' | 3Dベクトル | isVector |

### 入力データソース

呼び出し元モジュールからの関数引数として入力される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| inferDataType戻り値 | DataType \| null | 推論されたデータ型。一致する型がない場合はnull |
| isPositiveInteger戻り値 | boolean | 正の整数（0以上）かどうか |
| isStrictPositiveInteger戻り値 | boolean | 厳密な正の整数（1以上）かどうか |
| isValidSpacingMultiplier戻り値 | boolean | 有効なspacing倍数（0.25の倍数）かどうか |
| isValidOpacityValue戻り値 | boolean | 有効な不透明度値（0.25の倍数）かどうか |
| isLength戻り値 | boolean | CSS長さ値かどうか |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. var()チェック
   └─ 値がvar(で始まる場合はnullを返却（CSS変数は型推論不可）
2. 型リスト順にチェック
   ├─ types配列の各要素に対応するチェック関数を呼び出し
   ├─ 最初にtrueを返した型を返却
   └─ 全てfalseの場合はnullを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始: value, types] --> B{value が var( で始まる?}
    B -->|Yes| C[return null]
    B -->|No| D[types配列のループ開始]
    D --> E{現在の型のチェック関数 value}
    E -->|true| F[return 現在の型]
    E -->|false| G{次の型がある?}
    G -->|Yes| D
    G -->|No| H[return null]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-63-01 | var()除外 | CSS変数参照(var())は型推論をスキップしnullを返す | 値がvar(で始まる場合 |
| BR-63-02 | 優先順序マッチング | types配列の先頭から順にチェックし、最初にマッチした型を返す | 常時 |
| BR-63-03 | 色判定 | #ハッシュ、CSS色関数(rgb,hsl等)、名前付き色で判定 | type='color' |
| BR-63-04 | 長さ判定 | 数値+長さ単位(px,rem,em等 32種)またはCSS数学関数で判定 | type='length' |
| BR-63-05 | 角度判定 | 数値+角度単位(deg,rad,grad,turn)で判定 | type='angle' |
| BR-63-06 | 数学関数対応 | calc,min,max,clamp等のCSS数学関数を含む値は長さ・パーセンテージ・数値・分数として判定可能 | 数学関数を含む値 |
| BR-63-07 | spacing倍数検証 | spacing値は0以上かつ0.25の倍数であること | isValidSpacingMultiplier |
| BR-63-08 | 背景サイズ判定 | cover/contain、または1-2個の長さ/パーセンテージ/auto値 | type='bg-size' |

### 計算ロジック

**長さ単位一覧（32種）**：cm, mm, Q, in, pc, pt, px, em, ex, ch, rem, lh, rlh, vw, vh, vmin, vmax, vb, vi, svw, svh, lvw, lvh, dvw, dvh, cqw, cqh, cqi, cqb, cqmin, cqmax

**角度単位一覧（4種）**：deg, rad, grad, turn

**isMultipleOf(value, divisor)**: `num >= 0 && num % divisor === 0 && String(num) === String(value)` - 数値の倍数チェックに加え、文字列表現の一致で先頭ゼロ等の不正形式を排除

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

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

データベース操作はない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | エラーはスローされない。マッチしない場合はnull/falseを返す |

### リトライ仕様

リトライ処理はない。

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

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

## パフォーマンス要件

- 正規表現は事前コンパイル（モジュールレベルconst）されており、毎回の再コンパイルを回避
- types配列のサイズは通常小さく（2-5要素程度）、O(types.length)の走査
- 各チェック関数は正規表現テストまたはキーワード比較で高速に動作

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

セキュリティ上の考慮事項はない。純粋な値判定関数であり、副作用はない。

## 備考

- isColor関数は別モジュール`./is-color.ts`に定義されている
- hasMathFn関数は別モジュール`./math-operators.ts`に定義されている
- segment関数は別モジュール`./segment.ts`に定義されている（本機能のisImage, isFamilyName, isBackgroundPosition, isBackgroundSize, isLineWidthで使用）
- MDNドキュメントへの参照コメントが複数箇所に記載されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | **5-22行目**: `DataType`型定義。17種類のデータ型のユニオン型 |
| 1-2 | infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | **24-42行目**: `checks`オブジェクト。DataType→判定関数のマッピング |

**読解のコツ**: `checks`オブジェクトはRecord<DataType, (value: string) => boolean>型で、各DataTypeに対応する判定関数をマッピングしている。inferDataType関数はこのマッピングを使って型判定を行う。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | **47-57行目**: `inferDataType`関数のメインロジック |

**主要処理フロー**:
1. **48行目**: var()で始まる値はnullを返す
2. **50-53行目**: types配列を順にチェックし、最初にマッチした型を返す
3. **56行目**: マッチなしの場合null

#### Step 3: 各判定関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | is-color.ts | `packages/tailwindcss/src/utils/is-color.ts` | **200-204行目**: isColor関数。#ハッシュ、色関数、名前付き色で判定 |
| 3-2 | infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | **200-238行目**: isLength関数。32種の長さ単位またはCSS数学関数で判定 |
| 3-3 | infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | **173-175行目**: isNumber関数。数値パターンまたはCSS数学関数で判定 |
| 3-4 | infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | **63-65行目**: isUrl関数。url()パターンで判定 |
| 3-5 | infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | **85-110行目**: isImage関数。url、グラデーション、画像関数で判定 |
| 3-6 | infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | **242-268行目**: isBackgroundPosition関数。位置キーワード+長さ/パーセンテージ |
| 3-7 | infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | **285-308行目**: isBackgroundSize関数。cover/contain/長さ値 |
| 3-8 | infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | **324-326行目**: isAngle関数。角度単位(deg,rad,grad,turn)で判定 |
| 3-9 | infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | **339-341行目**: isVector関数。3つの数値のスペース区切り |

#### Step 4: 補助関数と依存モジュールを確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | **346-371行目**: isPositiveInteger, isStrictPositiveInteger, isValidSpacingMultiplier, isValidOpacityValue, isMultipleOf |
| 4-2 | math-operators.ts | `packages/tailwindcss/src/utils/math-operators.ts` | **41-43行目**: hasMathFn関数。calc/min/max等のCSS数学関数の検出 |
| 4-3 | segment.ts | `packages/tailwindcss/src/utils/segment.ts` | segment関数。isImage, isFamilyName等で値の分割に使用 |

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

```
inferDataType(value, types)
    │
    ├─ checks[type](value)
    │      │
    │      ├─ isColor(value)          ← is-color.ts
    │      │      └─ NAMED_COLORS / IS_COLOR_FN / #ハッシュ判定
    │      │
    │      ├─ isLength(value)
    │      │      ├─ IS_LENGTH 正規表現テスト
    │      │      └─ hasMathFn(value)  ← math-operators.ts
    │      │
    │      ├─ isPercentage(value)
    │      │      ├─ IS_PERCENTAGE 正規表現テスト
    │      │      └─ hasMathFn(value)
    │      │
    │      ├─ isNumber(value)
    │      │      ├─ IS_NUMBER 正規表現テスト
    │      │      └─ hasMathFn(value)
    │      │
    │      ├─ isImage(value)
    │      │      └─ segment(value, ',')  ── カンマ区切りで各画像を検証
    │      │
    │      ├─ isBackgroundPosition(value)
    │      │      └─ segment(value, ' ')  ── スペース区切りで各値を検証
    │      │
    │      ├─ isBackgroundSize(value)
    │      │      └─ segment(value, ',')  ── カンマ区切りで各サイズを検証
    │      │
    │      └─ [その他14種の判定関数]
    │
    └─ return DataType | null

[個別エクスポート関数]
    ├─ isPositiveInteger(value)
    ├─ isStrictPositiveInteger(value)
    ├─ isValidSpacingMultiplier(value)
    ├─ isValidOpacityValue(value)
    └─ isLength(value)
```

### データフロー図

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

CSS値文字列 ──────▶ inferDataType(value, types)
                          │
                          ├─ var()チェック
                          ├─ types配列の順次チェック
                          │    ├─ 正規表現テスト
                          │    ├─ キーワード比較
                          │    └─ segment分割 + 再帰的チェック   ───▶ DataType | null
                          │
types配列 ────────▶ チェック順序の決定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | ソース | データ型推論関数群の実装 |
| is-color.ts | `packages/tailwindcss/src/utils/is-color.ts` | ソース | 色判定関数（isColor）の実装 |
| math-operators.ts | `packages/tailwindcss/src/utils/math-operators.ts` | ソース | CSS数学関数検出（hasMathFn）の実装 |
| segment.ts | `packages/tailwindcss/src/utils/segment.ts` | ソース | 文字列セグメント分割（isImage等の内部で使用） |
| utilities.ts | `packages/tailwindcss/src/utilities.ts` | ソース | ユーティリティクラスの値型判定で利用 |
| variants.ts | `packages/tailwindcss/src/variants.ts` | ソース | バリアントのパラメータ検証で利用 |
| canonicalize-candidates.ts | `packages/tailwindcss/src/canonicalize-candidates.ts` | ソース | 候補正規化で利用 |
| constant-fold-declaration.ts | `packages/tailwindcss/src/constant-fold-declaration.ts` | ソース | 定数畳み込みでisLengthを利用 |
| plugin-api.ts | `packages/tailwindcss/src/compat/plugin-api.ts` | ソース | v3互換APIでinferDataTypeを利用 |
| legacy-utilities.ts | `packages/tailwindcss/src/compat/legacy-utilities.ts` | ソース | v3互換ユーティリティで利用 |
| default-theme.ts | `packages/tailwindcss/src/compat/default-theme.ts` | ソース | v3互換デフォルトテーマで利用 |
