# 機能設計書 61-セグメント分割（segment）

## 概要

本ドキュメントは、Tailwind CSSにおける文字列セグメント分割ユーティリティ関数`segment`の機能設計を記述する。この関数はCSS値やクラス名文字列を、括弧・ブラケット・中括弧・引用符のネストを考慮しながらトップレベルの区切り文字で分割する。

### 本機能の処理概要

**業務上の目的・背景**：CSS値やTailwind CSSクラス名の解析において、単純な文字列分割ではカンマやコロンなどの区切り文字が括弧内にネストされている場合に誤分割が発生する。例えば`var(--a, 0 0 1px rgb(0, 0, 0)), 0 0 1px rgb(0, 0, 0)`というCSS値をカンマで分割する場合、関数引数内のカンマは無視し、トップレベルのカンマでのみ分割する必要がある。本関数はこの問題を解決するための基盤ユーティリティである。

**機能の利用シーン**：候補パーサー（parseCandidate）でのクラス名分割、CSS関数の値解析、CSS省略プロパティの展開（expandDeclaration）、バリアント管理、@apply処理、CSS関数置換、v3互換レイヤーなど、Tailwind CSS内部の多数のモジュールから利用される中核ユーティリティ関数である。

**主要な処理内容**：
1. 入力文字列を1文字ずつ走査し、ステートマシンでネストレベルを追跡する
2. トップレベル（ネストレベル0）で区切り文字を検出した場合に分割を実行する
3. 括弧`()`、ブラケット`[]`、中括弧`{}`のネストを追跡し、対応する閉じ括弧とマッチングする
4. ダブルクォート・シングルクォート内の文字は一切分割対象としない
5. バックスラッシュによるエスケープ文字をスキップする

**関連システム・外部連携**：外部システムとの連携はない。Tailwind CSS内部の純粋なユーティリティ関数として機能する。

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

## 関連画面

本機能は内部ユーティリティ関数であり、画面に直接関連しない。間接的に全てのCSS生成処理に関与する。

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

## 機能種別

計算処理（文字列解析・分割）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| input | string | Yes | 分割対象の文字列 | 任意の文字列。空文字列も許容 |
| separator | string | Yes | 区切り文字（1文字） | 1文字の文字列。先頭の1文字のcharCodeが使用される |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| parts | string[] | 区切り文字で分割された文字列の配列 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 共有バッファのスタック位置を0に初期化
   └─ stackPos = 0, parts = [], lastPos = 0
2. separator の charCode を取得
   └─ separatorCode = separator.charCodeAt(0)
3. 入力文字列を1文字ずつ走査（forループ）
   ├─ 3a. stackPos === 0 かつ 区切り文字の場合
   │      └─ lastPosからidxまでのスライスをpartsに追加、lastPosを更新
   ├─ 3b. バックスラッシュの場合
   │      └─ 次の文字をスキップ（idx += 1）
   ├─ 3c. シングルクォートまたはダブルクォートの場合
   │      └─ 対応する閉じ引用符までスキップ（エスケープ考慮）
   ├─ 3d. 開き括弧 (, [, { の場合
   │      └─ closingBracketStackに対応する閉じ括弧を記録、stackPos++
   └─ 3e. 閉じ括弧 ), ], } の場合
          └─ スタックトップの閉じ括弧と一致すればstackPos--
4. 残りの文字列をpartsに追加
   └─ parts.push(input.slice(lastPos))
5. partsを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始: input, separator] --> B[初期化: stackPos=0, parts=empty]
    B --> C{idx < len?}
    C -->|No| H[残りをpartsに追加]
    C -->|Yes| D[char = input.charCodeAt idx]
    D --> E{stackPos===0 かつ char===separatorCode?}
    E -->|Yes| F[partsにスライス追加, lastPos更新]
    F --> C
    E -->|No| G{char の種類判定}
    G -->|backslash| G1[idx += 1 スキップ]
    G -->|quote| G2[閉じ引用符までスキップ]
    G -->|open bracket| G3[stackにpush, stackPos++]
    G -->|close bracket| G4{スタックトップと一致?}
    G4 -->|Yes| G5[stackPos--]
    G4 -->|No| C
    G -->|other| C
    G1 --> C
    G2 --> C
    G3 --> C
    G5 --> C
    H --> I[return parts]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-61-01 | トップレベル分割 | ネストレベル0の位置でのみ区切り文字による分割を行う | 常時 |
| BR-61-02 | 括弧ネスト追跡 | `()`, `[]`, `{}`の開き括弧で深さを増やし、対応する閉じ括弧で減らす | 括弧文字検出時 |
| BR-61-03 | 引用符内スキップ | シングルクォート・ダブルクォート内の全文字を分割対象外とする | 引用符検出時 |
| BR-61-04 | エスケープスキップ | バックスラッシュ直後の1文字を分割対象外とする | バックスラッシュ検出時 |
| BR-61-05 | 共有バッファ最適化 | closingBracketStackは256バイトの共有Uint8Arrayで、毎回のメモリ割り当てを回避する | 常時 |

### 計算ロジック

ネストレベルの追跡はスタック構造で実現される。開き括弧を検出するとスタックに対応する閉じ括弧のcharCodeを積み、閉じ括弧がスタックトップと一致すればポップする。スタック位置が0のときのみ区切り文字で分割を行う。

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 非平衡括弧 | 閉じ括弧が不足している場合 | エラーは発生しない。残りの文字列がそのまま最後のセグメントに含まれる |
| - | 非平衡引用符 | 閉じ引用符が不足している場合 | エラーは発生しない。文字列末尾までが引用符内として処理される |

### リトライ仕様

リトライ処理はない。純粋関数として1回の呼び出しで結果を返す。

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

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

## パフォーマンス要件

- 共有バッファ`closingBracketStack`（Uint8Array(256)）を使用し、関数呼び出しごとのメモリ割り当てを回避する
- 同期・非再帰・シングルスレッド環境を前提とした安全な共有バッファの使用
- 1パスのO(n)走査で処理を完了する

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

セキュリティ上の考慮事項はない。入力文字列を解析するだけの純粋関数であり、副作用はない。

## 備考

- 共有バッファ`closingBracketStack`はモジュールスコープに定義されており、関数が同期的・非再帰的に呼び出される前提で安全に共有される
- ネスト深度は最大256レベルまで対応（Uint8Array(256)のサイズ制限）
- JavaScriptの正規表現は再帰をサポートしないため、ステートマシンによる実装が採用されている

---

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

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

### 推奨読解順序

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

本関数は独自のデータ型定義を持たず、プリミティブ型のみで動作する。まず関数のシグネチャと共有バッファの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | segment.ts | `packages/tailwindcss/src/utils/segment.ts` | **1-15行目**: 文字コード定数定義（BACKSLASH, OPEN_CURLY等）と共有バッファ`closingBracketStack`の定義を確認する |

**読解のコツ**: 文字コードは16進数リテラルで定義されている（例: `0x5c` = `\`）。Uint8Arrayの256バイトはネストの最大深度を表す。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | segment.ts | `packages/tailwindcss/src/utils/segment.ts` | **29-102行目**: `segment`関数のメインロジック。ステートマシンによる文字列走査を理解する |

**主要処理フロー**:
1. **29-37行目**: 関数シグネチャと初期化。stackPos, parts, lastPos, separatorCodeの設定
2. **39-46行目**: メインループ開始。トップレベルでの区切り文字検出と分割
3. **48-52行目**: バックスラッシュエスケープ処理。次の1文字をスキップ
4. **55-71行目**: 引用符処理。対応する閉じ引用符までスキップ（エスケープ考慮）
5. **72-83行目**: 開き括弧処理。closingBracketStackに対応する閉じ括弧を記録しstackPosをインクリメント
6. **84-95行目**: 閉じ括弧処理。スタックトップとマッチすればstackPosをデクリメント
7. **99-101行目**: ループ終了後、残りの文字列をpartsに追加して返却

#### Step 3: テストコードで挙動を確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | segment.test.ts | `packages/tailwindcss/src/utils/segment.test.ts` | 各種ケース（括弧内、引用符内、エスケープ）での分割挙動をテストケースから理解する |

#### Step 4: 利用箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | candidate.ts | `packages/tailwindcss/src/candidate.ts` | クラス名をコロン区切りで分割する際にsegmentを使用 |
| 4-2 | css-functions.ts | `packages/tailwindcss/src/css-functions.ts` | CSS関数の引数解析でカンマ区切り分割に使用 |
| 4-3 | expand-declaration.ts | `packages/tailwindcss/src/expand-declaration.ts` | CSS省略プロパティの値分割に使用 |

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

```
[多数の呼び出し元]
    │
    ├─ candidate.ts (parseCandidate)
    │      └─ segment(input, ':')  ── クラス名のバリアント分割
    │
    ├─ css-functions.ts (substituteFunctions)
    │      └─ segment(value, ',')  ── CSS関数引数の分割
    │
    ├─ expand-declaration.ts (expandDeclaration)
    │      └─ segment(value, ' ')  ── CSS省略プロパティ値の分割
    │
    ├─ variants.ts
    │      └─ segment(selector, ',') ── セレクタリストの分割
    │
    ├─ apply.ts (substituteAtApply)
    │      └─ segment(value, ' ')  ── @apply値の分割
    │
    ├─ utilities.ts
    │      └─ segment(value, ',')  ── ユーティリティ値の分割
    │
    ├─ index.ts (compile)
    │      └─ segment(params, ',') ── ディレクティブパラメータの分割
    │
    └─ compat/ (plugin-api.ts, legacy-utilities.ts, etc.)
           └─ segment(value, ',')  ── v3互換レイヤーでの値分割
```

### データフロー図

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

文字列 input ───────▶ segment(input, separator)
                          │
                          ├─ 文字走査ループ
                          │    ├─ ネストレベル追跡
                          │    ├─ 引用符スキップ
                          │    └─ エスケープスキップ           ───▶ string[] parts
                          │
separator ─────────▶ 区切り文字判定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| segment.ts | `packages/tailwindcss/src/utils/segment.ts` | ソース | セグメント分割関数の実装 |
| segment.test.ts | `packages/tailwindcss/src/utils/segment.test.ts` | テスト | セグメント分割関数のユニットテスト |
| candidate.ts | `packages/tailwindcss/src/candidate.ts` | ソース | 候補パーサーからの利用元 |
| css-functions.ts | `packages/tailwindcss/src/css-functions.ts` | ソース | CSS関数処理からの利用元 |
| expand-declaration.ts | `packages/tailwindcss/src/expand-declaration.ts` | ソース | 宣言展開からの利用元 |
| variants.ts | `packages/tailwindcss/src/variants.ts` | ソース | バリアント管理からの利用元 |
| apply.ts | `packages/tailwindcss/src/apply.ts` | ソース | @apply処理からの利用元 |
| utilities.ts | `packages/tailwindcss/src/utilities.ts` | ソース | ユーティリティ登録からの利用元 |
| index.ts | `packages/tailwindcss/src/index.ts` | ソース | コンパイルエントリからの利用元 |
| canonicalize-candidates.ts | `packages/tailwindcss/src/canonicalize-candidates.ts` | ソース | 候補正規化からの利用元 |
| plugin-api.ts | `packages/tailwindcss/src/compat/plugin-api.ts` | ソース | v3互換プラグインAPIからの利用元 |
| legacy-utilities.ts | `packages/tailwindcss/src/compat/legacy-utilities.ts` | ソース | v3互換レガシーユーティリティからの利用元 |
| apply-compat-hooks.ts | `packages/tailwindcss/src/compat/apply-compat-hooks.ts` | ソース | v3互換フックからの利用元 |
| default-theme.ts | `packages/tailwindcss/src/compat/default-theme.ts` | ソース | v3互換デフォルトテーマからの利用元 |
