# 機能設計書 49-HTML空白処理（htmlWhitespaceSensitivity）

## 概要

本ドキュメントは、PrettierのHTML空白処理機能（htmlWhitespaceSensitivity）の設計仕様を定義する。

### 本機能の処理概要

htmlWhitespaceSensitivityオプションは、HTMLのフォーマット時に空白（ホワイトスペース）をどのように扱うかを制御する。CSSのdisplayプロパティのデフォルト値に基づいて空白の重要性を判断する（css）、全ての空白を重要として扱う（strict）、または全ての空白を無視する（ignore）の3つのモードから選択できる。

**業務上の目的・背景**：
HTMLでは、要素間の空白がレンダリング結果に影響を与えることがある。特にインライン要素では、タグ間の空白が1つのスペースとしてレンダリングされる。一方で、ブロック要素では空白は通常無視される。この機能により、HTMLの視覚的な出力を維持しながらコードを整形できる。strictモードでは全ての空白を保持し、ignoreモードでは空白を無視して自由にフォーマットできる。

**機能の利用シーン**：
1. CSSの表示特性に基づいてインテリジェントに空白を処理したい場合（css）
2. 全ての空白を維持して、HTMLの出力を完全に保持したい場合（strict）
3. 空白を無視してコードを自由に整形したい場合（ignore）
4. インライン要素の空白問題を解決したい場合

**主要な処理内容**：
1. htmlWhitespaceSensitivityオプションの値取得（css/strict/ignore）
2. 要素のCSS displayプロパティのデフォルト値を参照
3. 空白の重要性判定（leading/trailing/dangling）
4. 適切な改行・インデントの適用
5. テキストノードの空白処理

**関連システム・外部連携**：
- HTMLパーサー
- Vue/Angularテンプレートパーサー
- CLI、API、エディタプラグインからの呼び出し

**権限による制御**：
特になし。全てのユーザーが同一の機能を使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Playground | 補助機能 | サイドバーからHTML空白処理を設定 |
| 19 | Configuration - Options | 主機能 | htmlWhitespaceSensitivityオプションの詳細説明 |

## 機能種別

設定オプション / フォーマット制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| htmlWhitespaceSensitivity | string | No | HTML空白の扱い方 | "css" / "strict" / "ignore" のいずれか |

### 入力データソース

- 設定ファイル（.prettierrc、prettier.config.js、package.json等）
- CLI引数（--html-whitespace-sensitivity）
- API呼び出し時のオプションオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| formatted | string | 空白処理が適用されたフォーマット済みHTML |

### 出力先

- 標準出力（CLIの場合）
- ファイル（--write オプション使用時）
- API戻り値

## 処理フロー

### 処理シーケンス

```
1. オプション解析
   └─ htmlWhitespaceSensitivityオプションの値を取得（デフォルト: "css"）
2. 要素の解析
   └─ HTML要素のCSSdisplayプロパティを判定
3. 空白重要性判定
   └─ getNodeCssStyleDisplay関数でdisplay値を取得
4. フォーマット適用
   └─ 空白重要性に基づいてインデント・改行を決定
5. テキスト処理
   └─ テキストノードの先頭・末尾空白を処理
```

### フローチャート

```mermaid
flowchart TD
    A[HTML要素解析] --> B{htmlWhitespaceSensitivity?}
    B -->|strict| C[全ての空白を重要として扱う]
    B -->|ignore| D[全ての空白を無視]
    B -->|css| E[CSS displayに基づいて判定]
    E --> F{display値}
    F -->|inline| G[空白を保持]
    F -->|block| H[空白を無視可能]
    F -->|inline-block| I[先頭・末尾空白を保持]
    C --> J[出力]
    D --> J
    G --> J
    H --> J
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-49-01 | デフォルト設定 | デフォルトでは"css"（CSS displayに基づく） | htmlWhitespaceSensitivity未指定 |
| BR-49-02 | CSSベース | "css"ではCSS displayプロパティのデフォルト値を参照 | htmlWhitespaceSensitivity: "css" |
| BR-49-03 | 厳密モード | "strict"では全ての空白を重要として扱う | htmlWhitespaceSensitivity: "strict" |
| BR-49-04 | 無視モード | "ignore"では全ての空白を無視 | htmlWhitespaceSensitivity: "ignore" |
| BR-49-05 | ブロック要素 | block要素では空白を無視可能 | css mode && display: block |
| BR-49-06 | インライン要素 | inline要素では空白を保持 | css mode && display: inline |

### 計算ロジック

CSS display判定ロジック:
```javascript
function getNodeCssStyleDisplay(node, options) {
  switch (options.htmlWhitespaceSensitivity) {
    case "strict":
      return "inline"; // 全てinlineとして扱う
    case "ignore":
      return "block";  // 全てblockとして扱う
    default:
      // CSSのdisplayデフォルト値を参照
      return CSS_DISPLAY_TAGS[node.name] || CSS_DISPLAY_DEFAULT;
  }
}
```

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

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

該当なし（本機能はデータベース操作を行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | バリデーションエラー | htmlWhitespaceSensitivityに不正な値が指定された場合 | "css"/"strict"/"ignore"のいずれかを指定する |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 処理時間への影響は軽微
- CSS displayテーブルのルックアップはO(1)

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

特になし

## 備考

- VueおよびAngularテンプレートにも適用される
- Handlebars/Glimmerテンプレートにも適用される
- SVG要素はデフォルトでblockとして扱われる（svg:foreignObject内を除く）

---

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

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

### 推奨読解順序

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

オプション定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | options.js | `src/language-html/options.js` | htmlWhitespaceSensitivityオプションの定義（8-27行目） |

**読解のコツ**: htmlWhitespaceSensitivityはchoice型で、"css"、"strict"、"ignore"の3つの選択肢がある。デフォルトは"css"。

#### Step 2: CSS display判定ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/language-html/utilities/index.js` | getNodeCssStyleDisplay関数（477-516行目） |

**主要処理フロー**:
1. **500-502行目**: strictの場合は"inline"を返す
2. **503-504行目**: ignoreの場合は"block"を返す
3. **505-513行目**: cssモードではCSS_DISPLAY_TAGSを参照

#### Step 3: 空白の重要性判定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.js | `src/language-html/utilities/index.js` | isLeadingSpaceSensitiveNode関数（139-193行目） |
| 3-2 | index.js | `src/language-html/utilities/index.js` | isTrailingSpaceSensitiveNode関数（195-235行目） |
| 3-3 | index.js | `src/language-html/utilities/index.js` | isDanglingSpaceSensitiveNode関数（237-242行目） |

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

```
format() / formatWithCursor()
    │
    ├─ core.formatWithCursor()
    │      └─ printToDoc()
    │             └─ printer.print()
    │                    │
    │                    └─ printHtml() [printer.js]
    │                           │
    │                           ├─ getNodeCssStyleDisplay()
    │                           │      └─ options.htmlWhitespaceSensitivity
    │                           │
    │                           ├─ isLeadingSpaceSensitiveNode()
    │                           │
    │                           ├─ isTrailingSpaceSensitiveNode()
    │                           │
    │                           └─ isDanglingSpaceSensitiveNode()
```

### データフロー図

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

options.htmlWhitespaceSensitivity ──▶ getNodeCssStyleDisplay() ──▶ cssDisplay
                                    │
HTML要素 ───────────────────────────┘
                                    │
                                    ├─ "strict" → "inline"
                                    │
                                    ├─ "ignore" → "block"
                                    │
                                    └─ "css" → CSS_DISPLAY_TAGS[tag]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| options.js | `src/language-html/options.js` | ソース | htmlWhitespaceSensitivityオプション定義 |
| index.js | `src/language-html/utilities/index.js` | ソース | 空白処理ユーティリティ |
| constants.evaluate.js | `src/language-html/constants.evaluate.js` | ソース | CSS_DISPLAY_TAGS定義 |
| printer-glimmer.js | `src/language-handlebars/printer-glimmer.js` | ソース | Handlebarsでの空白処理 |
| html.js | `src/language-js/embed/html.js` | ソース | JS内HTMLでの空白処理 |
