# 機能設計書 48-スクリーン設定互換

## 概要

本ドキュメントは、v3の `screens` 設定をv4のレスポンシブバリアントに変換する `registerScreensConfig` 関数および `buildMediaQuery` 関数の設計を記述する。

### 本機能の処理概要

registerScreensConfigは、v3設定ファイルのscreens設定（ブレークポイント定義）をv4のVariantsシステムに静的バリアントとして登録する処理である。

**業務上の目的・背景**：v3ではscreens設定で `sm: '640px'` や `md: '768px'` のようにブレークポイントを定義し、`sm:`, `md:` 等のバリアントとして使用していた。v4ではテーマの `--breakpoint-*` 名前空間でブレークポイントを管理し、`min-*`/`max-*` バリアントが提供される。JS設定ファイルからのscreens設定をv4のバリアントシステムに橋渡しする必要がある。

**機能の利用シーン**：`upgradeToFullPluginSupport` の後処理として呼び出される。JS設定ファイルまたはプラグインでscreens設定が定義されている場合に、対応する静的バリアントを登録する。

**主要な処理内容**：
1. resolvedUserConfigのtheme.screensから設定を取得
2. コアの `min` バリアントの順序を基準として使用
3. 各スクリーン設定についてメディアクエリを構築（buildMediaQuery）
4. CSSテーマに既に値がある場合はスキップ
5. 文字列値は即座に登録、オブジェクト値（min/max/raw）は遅延登録
6. 遅延登録のバリアントはコアバリアントの順序の後に挿入

**関連システム・外部連携**：DesignSystemのVariantsオブジェクトに直接登録する。テーマシステムからブレークポイント値を確認する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面には直接関連しない |

## 機能種別

データ連携（v3 screens → v4 バリアント変換）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| userConfig | ResolvedConfig | Yes | 解決済みユーザー設定 | theme.screensプロパティ |
| designSystem | DesignSystem | Yes | バリアント登録先 | 有効なDesignSystem |

### 入力データソース

- resolvedUserConfig.theme.screens（v3形式のスクリーン設定）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | void | 副作用としてバリアントを登録 |

### 出力先

- DesignSystemのVariantsオブジェクト

## 処理フロー

### 処理シーケンス

```
1. screens設定の取得
   └─ userConfig.theme.screens || {} で取得

2. コア順序の取得
   └─ designSystem.variants.get('min')?.order で基準順序を取得

3. 各スクリーン設定の処理
   ├─ CSSテーマに既に値がありDEFAULTでない場合はスキップ
   ├─ 文字列値の場合は即座に登録（coreOrder）
   └─ オブジェクト値の場合は遅延登録リストに追加

4. メディアクエリの構築（buildMediaQuery）
   ├─ 文字列値: { min: value } に変換
   ├─ raw: rawクエリをそのまま使用
   └─ min/max: "(max >= width >= min)" 形式のクエリを構築

5. 遅延登録の実行
   ├─ 既存バリアントの順序を後方にシフト
   ├─ compareFnsのキーも後方にシフト
   └─ 各遅延バリアントをcoreOrder + index + 1で登録
```

### フローチャート

```mermaid
flowchart TD
    A[registerScreensConfig開始] --> B[screens設定取得]
    B --> C[コア順序取得: min variant order]
    C --> D{各スクリーンエントリ}
    D --> E{CSSテーマに値あり?}
    E -->|Yes & 非DEFAULT| F[スキップ]
    E -->|No| G{文字列値?}
    G -->|Yes| H[即座に登録: coreOrder]
    G -->|No| I[遅延登録リストに追加]
    H --> D
    I --> D
    D -->|完了| J{遅延登録あり?}
    J -->|No| K[終了]
    J -->|Yes| L[既存バリアント順序シフト]
    L --> M[各遅延バリアントを登録]
    M --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-48-01 | CSS優先 | CSSテーマに値がありDEFAULTフラグでない場合、JS設定は無視される | coreVariant && cssValue && !hasDefault |
| BR-48-02 | 即時登録 | 文字列値のスクリーンはコアバリアントと同じ順序で即座に登録 | typeof value === 'string' |
| BR-48-03 | 遅延登録 | オブジェクト値のスクリーンはコア順序の後に順番に登録 | typeof value !== 'string' |
| BR-48-04 | 順序シフト | 遅延登録時に既存の高順序バリアントを後方にシフトする | additionalVariants.length > 0 |
| BR-48-05 | メディアクエリ形式 | `(max >= width >= min)` 形式のモダンCSS範囲構文を使用 | buildMediaQuery |

### 計算ロジック

**buildMediaQueryの変換例**:
- `'640px'` → `(width >= 640px)`
- `{ min: '640px' }` → `(width >= 640px)`
- `{ max: '1024px' }` → `(1024px >= width)`
- `{ min: '640px', max: '1024px' }` → `(1024px >= width >= 640px)`
- `{ raw: 'print' }` → `print`

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

該当なし

## エラー処理

### エラーケース一覧

特定のエラーケースはない。無効な値は `null` としてフィルタリングされる。

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- バリアント順序のシフト処理は全バリアントを走査する必要があるが、通常バリアント数は限られている

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

該当なし

## 備考

- `min-*` と `max-*` バリアントは本関数では再設定されない。テーマの最新値から動的に読み取るため、別途設定不要
- compareFnsマップのキーシフトにより、遅延登録バリアントのソート順序が正しく維持される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/tailwindcss/src/compat/config/types.ts` | ResolvedConfig.theme.screensの型 |
| 1-2 | variants.ts | `packages/tailwindcss/src/variants.ts` | Variantsクラスのorder/compareFnsプロパティ |

#### Step 2: メイン関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | screens-config.ts | `packages/tailwindcss/src/compat/screens-config.ts` | registerScreensConfig関数（5-78行目） |

**主要処理フロー**:
1. **6行目**: screens設定の取得
2. **13行目**: コア順序の取得（min variant order）
3. **19-58行目**: 各スクリーンエントリのループ処理
4. **62-77行目**: 遅延登録の実行と順序シフト

#### Step 3: buildMediaQueryを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | screens-config.ts | `packages/tailwindcss/src/compat/screens-config.ts` | buildMediaQuery関数（80-123行目）。スクリーン値からメディアクエリ文字列への変換 |

**主要処理フロー**:
- **90行目**: 文字列は{min: value}に変換
- **103行目**: rawはそのまま使用
- **109-119行目**: min/maxからクエリ文字列を構築

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

```
registerScreensConfig(userConfig, designSystem)
    │
    ├─ designSystem.variants.get('min')  [コア順序取得]
    │
    ├─ designSystem.theme.resolveValue(name, ['--breakpoint'])  [CSS値確認]
    │
    ├─ buildMediaQuery(value)  [メディアクエリ構築]
    │
    ├─ designSystem.variants.static(name, ...)  [バリアント登録]
    │
    └─ 順序シフト処理
           ├─ designSystem.variants.variants [全バリアント順序更新]
           └─ designSystem.variants.compareFns [比較関数キー更新]
```

### データフロー図

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

screens設定 ────────▶ registerScreensConfig() ──▶ Variants登録
{ sm: '640px',              │
  md: '768px' }             ├─ buildMediaQuery()
                            │   '640px' → '(width >= 640px)'
                            │
                            └─ variants.static('sm', ...)
                                variants.static('md', ...)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| screens-config.ts | `packages/tailwindcss/src/compat/screens-config.ts` | ソース | スクリーン設定互換の本体 |
| variants.ts | `packages/tailwindcss/src/variants.ts` | ソース | Variantsクラス（static登録・順序管理） |
| theme.ts | `packages/tailwindcss/src/theme.ts` | ソース | Themeクラス（resolveValue/hasDefault） |
| apply-compat-hooks.ts | `packages/tailwindcss/src/compat/apply-compat-hooks.ts` | ソース | 呼び出し元（359行目） |
| ast.ts | `packages/tailwindcss/src/ast.ts` | ソース | atRule関数（メディアクエリASTノード生成） |
