# 機能設計書 49-コンテナプラグイン互換

## 概要

本ドキュメントは、v3の `container` プラグイン設定をv4に変換する `registerContainerCompat` 関数および `buildCustomContainerUtilityRules` 関数の設計を記述する。

### 本機能の処理概要

registerContainerCompatは、v3設定ファイルのcontainerオプション（center、padding、screens）に基づいて、カスタムcontainerユーティリティのCSSルールを構築し、v4のDesignSystemに静的ユーティリティとして登録する処理である。

**業務上の目的・背景**：v3ではcontainerプラグインで `center: true`、`padding`、`screens` オプションを設定してcontainerユーティリティの動作をカスタマイズできた。v4ではcontainerは通常のユーティリティとして提供されるが、v3のカスタム設定との互換性のため、これらのオプションに基づくカスタムルールを生成する必要がある。

**機能の利用シーン**：`upgradeToFullPluginSupport` の後処理として呼び出される。JS設定ファイルでcontainerオプションが定義されている場合にのみ有効。

**主要な処理内容**：
1. resolvedUserConfigのtheme.containerから設定を取得
2. `center: true` の場合、`margin-inline: auto` を追加
3. `padding` の処理（文字列/オブジェクト）
4. `screens` のカスタムブレークポイント処理
5. ブレークポイントごとのmax-width/padding-inlineのメディアクエリ生成
6. 生成されたルールでcontainerユーティリティをstatic登録

**関連システム・外部連携**：DesignSystemのThemeからブレークポイント値を解決。compareBreakpointsでブレークポイントの順序をソート。

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

## 関連画面

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

## 機能種別

計算処理（カスタムcontainerユーティリティ生成）

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- resolvedUserConfig.theme.container（v3形式のコンテナ設定）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | void | 副作用としてcontainerユーティリティを登録 |

### 出力先

- DesignSystemのUtilitiesオブジェクト

## 処理フロー

### 処理シーケンス

```
1. container設定の取得・検証
   └─ userConfig.theme.container || {} で取得。オブジェクトでない場合はリターン

2. buildCustomContainerUtilityRulesでルール構築
   ├─ center: true → margin-inline: auto
   ├─ padding (文字列/DEFAULT) → padding-inline
   ├─ screens設定がある場合
   │   ├─ デフォルトブレークポイントのunset用ルール追加
   │   └─ カスタムスクリーンの@media + max-width生成
   └─ padding (オブジェクト/ブレークポイント別)
       ├─ screensオーバーライトがある場合はそちらにマージ
       └─ ない場合はtheme(--breakpoint-*)で@mediaルール生成

3. ルールが空でない場合のみ登録
   └─ designSystem.utilities.static('container', () => rules.map(cloneAstNode))
```

### フローチャート

```mermaid
flowchart TD
    A[registerContainerCompat開始] --> B[container設定取得]
    B --> C{オブジェクト?}
    C -->|No| D[リターン]
    C -->|Yes| E[buildCustomContainerUtilityRules]
    E --> F{center: true?}
    F -->|Yes| G[margin-inline: auto]
    F -->|No| H{padding設定?}
    G --> H
    H -->|string/DEFAULT| I[padding-inline追加]
    H -->|No| J{screens設定?}
    I --> J
    J -->|Yes| K[カスタムスクリーン処理]
    J -->|No| L{padding object?}
    K --> L
    L -->|Yes| M[ブレークポイント別padding追加]
    L -->|No| N{ルールが空?}
    M --> N
    N -->|Yes| D
    N -->|No| O[utilities.static container 登録]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-49-01 | center | `center: true` の場合 `margin-inline: auto` を出力 | center設定 |
| BR-49-02 | デフォルトpadding | paddingが文字列またはDEFAULTキーの場合、ベースのpadding-inlineとして出力 | padding設定 |
| BR-49-03 | スクリーンオーバーライド | screens設定がある場合、デフォルトブレークポイントをunsetし、カスタムスクリーンで上書き | screens設定 |
| BR-49-04 | paddingマージ | screensオーバーライト内のブレークポイントにpadding設定がある場合はマージ | screens && padding |
| BR-49-05 | ブレークポイントソート | ブレークポイントはcompareBreakpointsで昇順ソートされる | screens/padding |
| BR-49-06 | cloneAstNode | ルールは毎回cloneAstNodeで複製して返される（キャッシュ汚染防止） | 常時 |

### 計算ロジック

生成されるCSSルールの構造例:
```css
.container {
  margin-inline: auto;
  padding-inline: 1rem;
  @media (width >= --theme(--breakpoint-sm)) {
    max-width: none;
  }
  @media (width >= 640px) {
    max-width: 640px;
  }
  @media (width >= 768px) {
    max-width: 768px;
    padding-inline: 2rem;
  }
}
```

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

該当なし

## エラー処理

### エラーケース一覧

特定のエラーケースはない。container設定がオブジェクトでない場合は無視される。

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- ルールは一度構築された後、cloneAstNodeで毎回複製されるため、元のルールが変更されない

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

該当なし

## 備考

- `screens` 設定がある場合、最初のデフォルトブレークポイント以降のmax-widthを `none` にリセットするルールが挿入される
- screensオーバーライトの値は `{min: value}` オブジェクトの場合 `min` プロパティが使用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ast.ts | `packages/tailwindcss/src/ast.ts` | atRule/decl/cloneAstNode関数。ルール構築の基本関数 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | container.ts | `packages/tailwindcss/src/compat/container.ts` | registerContainerCompat関数（6-20行目） |

**主要処理フロー**:
1. **7行目**: container設定の取得
2. **9-11行目**: オブジェクト型チェック
3. **13行目**: buildCustomContainerUtilityRulesの呼び出し
4. **15-16行目**: ルールが空でない場合の検証
5. **19行目**: utilities.staticでcontainerを登録

#### Step 3: ルール構築を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | container.ts | `packages/tailwindcss/src/compat/container.ts` | buildCustomContainerUtilityRules関数（22-120行目） |

**主要処理フロー**:
- **37-39行目**: center処理
- **41-48行目**: デフォルトpadding処理
- **50-84行目**: screensオーバーライト処理
- **86-111行目**: ブレークポイント別padding処理
- **113-117行目**: screensオーバーライトのルール追加

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

```
registerContainerCompat(userConfig, designSystem)
    │
    ├─ buildCustomContainerUtilityRules(container, designSystem)
    │      ├─ decl('margin-inline', 'auto')  [center]
    │      ├─ decl('padding-inline', value)  [padding]
    │      ├─ designSystem.theme.namespace('--breakpoint')  [ブレークポイント取得]
    │      ├─ compareBreakpoints()  [ソート]
    │      ├─ atRule('@media', query, [...])  [メディアクエリ生成]
    │      └─ designSystem.theme.resolveValue(key, ['--breakpoint'])  [値解決]
    │
    └─ designSystem.utilities.static('container', () => rules.map(cloneAstNode))
```

### データフロー図

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

container設定 ─────▶ buildCustomContainerUtilityRules() ──▶ AstNode[]
{ center: true,              │
  padding: '1rem',           ├─ center → margin-inline: auto
  screens: {...} }           ├─ padding → padding-inline
                             └─ screens → @media + max-width
                                    │
                                    ▼
                             utilities.static('container', ...)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| container.ts | `packages/tailwindcss/src/compat/container.ts` | ソース | コンテナプラグイン互換の本体 |
| apply-compat-hooks.ts | `packages/tailwindcss/src/compat/apply-compat-hooks.ts` | ソース | 呼び出し元（360行目） |
| ast.ts | `packages/tailwindcss/src/ast.ts` | ソース | atRule/decl/cloneAstNode関数 |
| theme.ts | `packages/tailwindcss/src/theme.ts` | ソース | Themeクラス（namespace/resolveValue） |
| compare-breakpoints.ts | `packages/tailwindcss/src/utils/compare-breakpoints.ts` | ソース | ブレークポイントソート関数 |
