# 機能設計書 46-レガシーユーティリティ登録

## 概要

本ドキュメントは、v3互換のレガシーユーティリティ（bg-gradient-to-*、flex-grow、flex-shrink、start/end等）をv4のDesignSystemに登録する `registerLegacyUtilities` 関数の設計を記述する。

### 本機能の処理概要

registerLegacyUtilitiesは、v3で提供されていたがv4のコアユーティリティから削除または名前変更されたユーティリティクラスを、後方互換性のためにDesignSystemに登録する処理である。

**業務上の目的・背景**：Tailwind CSS v4ではユーティリティクラスの命名体系が見直され、一部のクラスが廃止・改名された。しかし、v3プロジェクトからの移行を円滑にするため、旧名称のユーティリティもサポートする必要がある。本機能は、`applyCompatibilityHooks` の一部として常に呼び出され、v3ユーザーが使い慣れたクラス名を引き続き使用できるようにする。

**機能の利用シーン**：`applyCompatibilityHooks` 関数の冒頭で、プラグインや設定ファイルの有無に関わらず常に実行される。

**主要な処理内容**：
1. `bg-gradient-to-{direction}` ユーティリティ（8方向）の登録
2. `bg-left-top`/`bg-right-top`/`bg-left-bottom`/`bg-right-bottom` ユーティリティの登録
3. `object-left-top`/`object-right-top`/`object-left-bottom`/`object-right-bottom` ユーティリティの登録
4. `max-w-screen-{breakpoint}` ユーティリティの登録
5. `overflow-ellipsis`（text-overflow: ellipsis）の登録
6. `decoration-slice`/`decoration-clone`（box-decoration-break）の登録
7. `flex-shrink`/`flex-grow` ユーティリティ（v3名称）の登録
8. `order-none` ユーティリティの登録
9. `break-words` ユーティリティの登録
10. `start-*`/`end-*` insetユーティリティ（v3名称）の登録

**関連システム・外部連携**：DesignSystemのUtilitiesオブジェクトに直接登録する。テーマシステムからbreakpoint/spacing/inset値を解決する。

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

## 関連画面

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

## 機能種別

データ連携（v3ユーティリティの後方互換登録）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| designSystem | DesignSystem | Yes | ユーティリティ登録先 | 有効なDesignSystem |

### 入力データソース

- DesignSystemのThemeオブジェクト（breakpoint/spacing/inset値の解決）

## 出力仕様

### 出力データ

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

### 出力先

- DesignSystemのUtilitiesオブジェクト（static/functional登録）

## 処理フロー

### 処理シーケンス

```
1. グラデーション方向ユーティリティの登録
   └─ bg-gradient-to-{t,tr,r,br,b,bl,l,tl}: 8方向のlinear-gradient

2. レガシー背景位置ユーティリティの登録
   └─ bg-left-top, bg-right-top, bg-left-bottom, bg-right-bottom

3. レガシーオブジェクト位置ユーティリティの登録
   └─ object-left-top, object-right-top, object-left-bottom, object-right-bottom

4. max-w-screen-{breakpoint}ユーティリティの登録
   └─ テーマの--breakpoint名前空間から値を解決

5. テキスト関連ユーティリティの登録
   └─ overflow-ellipsis

6. ボックスデコレーションユーティリティの登録
   └─ decoration-slice, decoration-clone

7. Flexbox関連ユーティリティの登録
   └─ flex-shrink, flex-grow（functionalユーティリティ）

8. その他ユーティリティの登録
   └─ order-none, break-words

9. Inset関連ユーティリティの登録
   └─ start-*/end-*: static/functionalの両方を登録
```

### フローチャート

```mermaid
flowchart TD
    A[registerLegacyUtilities開始] --> B[bg-gradient-to-* 登録]
    B --> C[bg-{position} 登録]
    C --> D[object-{position} 登録]
    D --> E[max-w-screen-* 登録]
    E --> F[overflow-ellipsis 登録]
    F --> G[decoration-slice/clone 登録]
    G --> H[flex-shrink/grow 登録]
    H --> I[order-none/break-words 登録]
    I --> J[start-*/end-* 登録]
    J --> K[完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-46-01 | グラデーション方向 | bg-gradient-to-{方向}はoklab色空間のlinear-gradientを生成する | bg-gradient-to-*使用時 |
| BR-46-02 | max-w-screen解決 | max-w-screen-{name}はテーマの--breakpoint名前空間から値を解決する | 候補値がnamed |
| BR-46-03 | flex-shrink/growデフォルト | 値なしの場合はデフォルト値'1'を使用する | flex-shrink/flex-grow使用時 |
| BR-46-04 | start/end inset | start-*/end-*はinset-inline-start/endプロパティにマッピングされる | start/end使用時 |
| BR-46-05 | spacing乗数 | start-*/end-*はspacing乗数をサポートする（calc(spacing * N)） | isValidSpacingMultiplier |
| BR-46-06 | 分数サポート | start-*/end-*は分数値（1/2等）をパーセント値に変換する | candidate.value.fraction |

### 計算ロジック

- **グラデーション**: `linear-gradient(var(--tw-gradient-stops))` + `--tw-gradient-position: to {direction} in oklab`
- **spacing乗数**: `calc({multiplier} * {value})` 形式
- **分数→パーセント**: `calc({fraction} * 100%)`
- **負の値**: `calc({value} * -1)`

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

該当なし

## エラー処理

### エラーケース一覧

エラーは投げられない。値の解決に失敗した場合は `undefined` を返して登録をスキップする。

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 全ユーティリティは遅延評価され、実際に使用される候補がコンパイルされるときのみCSS生成処理が実行される

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

該当なし

## 備考

- suggestメソッドは各ユーティリティに対して空の配列を返すよう設定されており、IDE補完リストに表示はされるがサジェスト値は提供しない
- start/endユーティリティは最も複雑で、static（auto/full/px等）とfunctional（値解決・spacing乗数・分数）の両方を登録する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | candidate.ts | `packages/tailwindcss/src/candidate.ts` | Candidate型のfunctionalバリアント（value/modifier/fraction） |
| 1-2 | ast.ts | `packages/tailwindcss/src/ast.ts` | decl関数（CSS宣言ノードの生成） |

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

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

**主要処理フロー**:
1. **7-22行目**: bg-gradient-to-{方向}の8方向登録（ループ）
2. **24-50行目**: bg-{position}とobject-{position}の登録
3. **52-59行目**: max-w-screen-{breakpoint}の登録
4. **61-74行目**: overflow-ellipsis, decoration-slice/cloneの登録
5. **76-108行目**: flex-shrink, flex-grow, order-none, break-wordsの登録
6. **117-178行目**: start-*/end-*の登録（最も複雑）

#### Step 3: start/end insetの値解決を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | legacy-utilities.ts | `packages/tailwindcss/src/compat/legacy-utilities.ts` | handleInset関数（127-174行目）。値解決の優先順位とspacing乗数・分数処理 |

**主要処理フロー**:
- **130-134行目**: デフォルト値（値なし）の処理
- **136-140行目**: arbitrary値の処理
- **142-145行目**: テーマからの値解決（--inset/--spacing）
- **148-151行目**: 分数値のパーセント変換
- **155-168行目**: spacing乗数の処理

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

```
registerLegacyUtilities(designSystem)
    │
    ├─ designSystem.utilities.static('bg-gradient-to-*', ...)
    ├─ designSystem.utilities.suggest('bg-gradient-to-*', ...)
    │
    ├─ designSystem.utilities.static('bg-left-top', ...)
    ├─ designSystem.utilities.static('object-left-top', ...)
    │
    ├─ designSystem.utilities.functional('max-w-screen', ...)
    │      └─ designSystem.theme.resolve(value, ['--breakpoint'])
    │
    ├─ designSystem.utilities.static('overflow-ellipsis', ...)
    ├─ designSystem.utilities.static('decoration-slice', ...)
    │
    ├─ designSystem.utilities.functional('flex-shrink', ...)
    ├─ designSystem.utilities.functional('flex-grow', ...)
    │
    └─ designSystem.utilities.functional('start'/'end', ...)
           ├─ designSystem.theme.resolve(value, ['--inset', '--spacing'])
           └─ designSystem.theme.resolve(null, ['--spacing'])
```

### データフロー図

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

DesignSystem ────▶ registerLegacyUtilities() ──▶ Utilities登録
                         │
                         ├─ static登録: 固定CSS宣言
                         │
                         └─ functional登録:
                               │
                               ├─ テーマ値解決
                               │   (--breakpoint/--inset/--spacing)
                               │
                               ├─ spacing乗数計算
                               │   calc(multiplier * value)
                               │
                               └─ 分数→パーセント変換
                                   calc(fraction * 100%)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| legacy-utilities.ts | `packages/tailwindcss/src/compat/legacy-utilities.ts` | ソース | レガシーユーティリティ登録の本体 |
| apply-compat-hooks.ts | `packages/tailwindcss/src/compat/apply-compat-hooks.ts` | ソース | 呼び出し元（147行目） |
| utilities.ts | `packages/tailwindcss/src/utilities.ts` | ソース | Utilitiesクラス（static/functional） |
| theme.ts | `packages/tailwindcss/src/theme.ts` | ソース | Themeクラス（resolve） |
| ast.ts | `packages/tailwindcss/src/ast.ts` | ソース | decl関数 |
| infer-data-type.ts | `packages/tailwindcss/src/utils/infer-data-type.ts` | ソース | isPositiveInteger/isValidSpacingMultiplier |
| segment.ts | `packages/tailwindcss/src/utils/segment.ts` | ソース | segment関数（分数パース） |
